Give helpers folder an index.scss, migrate ratio helper to aspect-ratio utility

diff --git a/scss/_helpers.scss b/scss/_helpers.scss
deleted file mode 100644 (file)
index 13f2752..0000000
--- a/scss/_helpers.scss
+++ /dev/null
@@ -1,12 +0,0 @@
-@import "helpers/clearfix";
-@import "helpers/color-bg";
-@import "helpers/colored-links";
-@import "helpers/focus-ring";
-@import "helpers/icon-link";
-@import "helpers/ratio";
-@import "helpers/position";
-@import "helpers/stacks";
-@import "helpers/visually-hidden";
-@import "helpers/stretched-link";
-@import "helpers/text-truncation";
-@import "helpers/vr";

diff --git a/scss/_utilities.scss b/scss/_utilities.scss
index 6c1c51450bd9ad28ba46e930184873236f74922e..46020e40a0aae8ae778ba2862a929a0a4c9b3e0d 100644 (file)
--- a/scss/_utilities.scss
+++ b/scss/_utilities.scss
@@ -18,6 +18,13 @@ $utilities: map.merge(
       values: baseline top middle bottom text-bottom text-top
     ),
     // scss-docs-end utils-vertical-align
+    // scss-docs-start utils-aspect-ratio
+    "aspect-ratio": (
+      property: aspect-ratio,
+      class: ratio,
+      values: $aspect-ratios
+    ),
+    // scss-docs-end utils-aspect-ratio
     // scss-docs-start utils-float
     "float": (
       responsive: true,

diff --git a/scss/_variables.scss b/scss/_variables.scss
index 20019cb334ecdb3cf92331a22d2b38e407e2b798..972e79c31abdd6ac93586d7d23240f26529dde1d 100644 (file)
--- a/scss/_variables.scss
+++ b/scss/_variables.scss
@@ -302,7 +302,6 @@ $transition-collapse:         height .35s ease !default;
 $transition-collapse-width:   width .35s ease !default;
 // scss-docs-end collapse-transition
 
-// stylelint-disable function-disallowed-list
 // scss-docs-start aspect-ratios
 $aspect-ratios: (
   "auto": auto,
@@ -312,7 +311,6 @@ $aspect-ratios: (
   "21x9": #{"21 / 9"}
 ) !default;
 // scss-docs-end aspect-ratios
-// stylelint-enable function-disallowed-list
 
 // Typography
 //

diff --git a/scss/helpers/_ratio.scss b/scss/helpers/_ratio.scss
deleted file mode 100644 (file)
index ba13752..0000000
--- a/scss/helpers/_ratio.scss
+++ /dev/null
@@ -1,30 +0,0 @@
-@use "../config" as *;
-@use "../variables" as *;
-// mdo-do: remve for utilities
-
-// Credit: Nicolas Gallagher and SUIT CSS.
-
-.ratio {
-  position: relative;
-  width: 100%;
-
-  &::before {
-    display: block;
-    padding-top: var(--#{$prefix}aspect-ratio);
-    content: "";
-  }
-
-  > * {
-    position: absolute;
-    top: 0;
-    left: 0;
-    width: 100%;
-    height: 100%;
-  }
-}
-
-@each $key, $ratio in $aspect-ratios {
-  .ratio-#{$key} {
-    --#{$prefix}aspect-ratio: #{$ratio};
-  }
-}

diff --git a/scss/helpers/index.scss b/scss/helpers/index.scss
index d9b033aa99f25d402d724f4cf0f58a157388eb37..3df08ebe8d7d2fd901c8aa63cf67a1268167659a 100644 (file)
--- a/scss/helpers/index.scss
+++ b/scss/helpers/index.scss
@@ -1,11 +1,11 @@
-@forward "clearfix";
-@forward "color-bg";
-@forward "colored-links";
-@forward "focus-ring";
-@forward "icon-link";
-@forward "position";
-@forward "stacks";
-@forward "visually-hidden";
-@forward "stretched-link";
-@forward "text-truncation";
-@forward "vr";
+@import "clearfix";
+@import "color-bg";
+@import "colored-links";
+@import "focus-ring";
+@import "icon-link";
+@import "position";
+@import "stacks";
+@import "visually-hidden";
+@import "stretched-link";
+@import "text-truncation";
+@import "vr";

diff --git a/site/data/sidebar.yml b/site/data/sidebar.yml
index dea26b401a9e59f12573764e163b482c83e69122..fb8d3246b6022c4a6349cbeb6b881e09c97fea39 100644 (file)
--- a/site/data/sidebar.yml
+++ b/site/data/sidebar.yml
@@ -107,7 +107,6 @@
     - title: Focus ring
     - title: Icon link
     - title: Position
-    - title: Ratio
     - title: Stacks
     - title: Stretched link
     - title: Text truncation
@@ -119,6 +118,7 @@
   icon_color: red
   pages:
     - title: API
+    - title: Aspect ratio
     - title: Background
     - title: Borders
     - title: Colors

diff --git a/site/src/content/docs/helpers/ratio.mdx b/site/src/content/docs/utilities/aspect-ratio.mdx
similarity index 53%
rename from site/src/content/docs/helpers/ratio.mdx
rename to site/src/content/docs/utilities/aspect-ratio.mdx
index 950d31c7315c548fc9c39b295eb07b4f56e7f876..c201174400d26ff688b428290a2c5d66e78c6c5b 100644 (file)
--- a/site/src/content/docs/helpers/ratio.mdx
+++ b/site/src/content/docs/utilities/aspect-ratio.mdx
@@ -1,46 +1,45 @@
 ---
-title: Ratios
+title: Aspect Ratio
 description: Use generated pseudo elements to make an element maintain the aspect ratio of your choosing. Perfect for responsively handling video or slideshow embeds based on the width of the parent.
 toc: true
 ---
 
-## About
-
-Use the ratio helper to manage the aspect ratios of external content like `<iframe>`s, `<embed>`s, `<video>`s, and `<object>`s. These helpers also can be used on any standard HTML child element (e.g., a `<div>` or `<img>`). Styles are applied from the parent `.ratio` class directly to the child.
-
-Aspect ratios are declared in a Sass map and included in each class via CSS variable, which also allows [custom aspect ratios](#custom-ratios).
+Use the ratio utility to manage the aspect ratios of content like `<iframe>`s, `<embed>`s, `<video>`s, and `<object>`s. These helpers also can be used on any standard HTML child element (e.g., a `<div>` or `<img>`). Customize the available aspect ratios with the Sass variable or the utility API.
 
 <Callout>
-**Pro-Tip!** You don’t need `frameborder="0"` on your `<iframe>`s as we override that for you in [Reboot]([[docsref:/content/reboot]]).
+**Pro-Tip!** You don't need `frameborder="0"` on your `<iframe>`s as we override that for you in [Reboot]([[docsref:/content/reboot]]).
 </Callout>
 
 ## Example
 
-Wrap any embed, like an `<iframe>`, in a parent element with `.ratio` and an aspect ratio class. The immediate child element is automatically sized thanks to our universal selector `.ratio > *`.
+Add your ratio utility to the element you want to modify, like an `<iframe>`. Ratio utilities also pair well with any width utilities, as shown below.
 
-<Example code={`<div class="ratio ratio-16x9">
-    <iframe src="https://www.youtube.com/embed/zpOULjyy-n8?rel=0" title="YouTube video" allowfullscreen></iframe>
-  </div>`} />
+<Example code={`<iframe class="w-100 ratio-16x9" src="https://www.youtube.com/embed/zpOULjyy-n8?rel=0" title="YouTube video" allowfullscreen></iframe>`} />
 
 ## Aspect ratios
 
 Aspect ratios can be customized with modifier classes. By default the following ratio classes are provided:
 
-<Example class="bd-example-ratios" code={`<div class="ratio ratio-1x1">
+<Example class="bd-example-ratios" code={`<div class="ratio-auto">
+    <div>Auto</div>
+  </div>
+  <div class="w-25 ratio-1x1">
     <div>1x1</div>
   </div>
-  <div class="ratio ratio-4x3">
+  <div class="w-50 ratio-4x3">
     <div>4x3</div>
   </div>
-  <div class="ratio ratio-16x9">
+  <div class="w-75 ratio-16x9">
     <div>16x9</div>
   </div>
-  <div class="ratio ratio-21x9">
+  <div class="w-100 ratio-21x9">
     <div>21x9</div>
   </div>`} />
 
 ## Custom ratios
 
+{/* mdo-do: do we bring these back?
+
 Each `.ratio-*` class includes a CSS custom property (or CSS variable) in the selector. You can override this CSS variable to create custom aspect ratios on the fly with some quick math on your part.
 
 For example, to create a 2x1 aspect ratio, set `--bs-aspect-ratio: 50%` on the `.ratio`.
@@ -62,10 +61,10 @@ This CSS variable makes it easy to modify the aspect ratio across breakpoints. T
 <Example class="bd-example-ratios bd-example-ratios-breakpoint" code={`<div class="ratio ratio-4x3">
     <div>4x3, then 2x1</div>
   </div>`} />
+*/}
 
+## Sass map
 
-## Sass maps
-
-Within `_variables.scss`, you can change the aspect ratios you want to use. Here’s our default `$ratio-aspect-ratios` map. Modify the map as you like and recompile your Sass to put them to use.
+Within `_variables.scss`, you can change the aspect ratios you want to use. Here's our default `$aspect-ratios` map. Modify the map as you like and recompile your Sass to put them to use.
 
 <ScssDocs name="aspect-ratios" file="scss/_variables.scss" />

diff --git a/site/src/scss/_component-examples.scss b/site/src/scss/_component-examples.scss
index 2cbe64e8cc7a75ead255c584341cce6be36d6296..1f2401a7104de8b5024a018e63605d91757e29eb 100644 (file)
--- a/site/src/scss/_component-examples.scss
+++ b/site/src/scss/_component-examples.scss
@@ -181,29 +181,17 @@
 
 // Ratio helpers
 .bd-example-ratios {
-  .ratio {
-    display: inline-block;
-    width: 10rem;
+  [class*="ratio"] {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    margin-bottom: 1rem;
     color: var(--bs-secondary-color);
     background-color: var(--bs-tertiary-bg);
     border: var(--bs-border-width) solid var(--bs-border-color);
-
-    > div {
-      display: flex;
-      align-items: center;
-      justify-content: center;
-    }
   }
 }
-.bd-example-ratios-breakpoint {
-  .ratio-4x3 {
-    width: 16rem;
 
-    @include media-breakpoint-up(md) {
-      --bs-aspect-ratio: 50%; // 2x1
-    }
-  }
-}
 
 .bd-example-offcanvas {
   .offcanvas {