Updates responsive embeds with new class names and CSS variables

scss/_helpers.scss

@@ -1,6 +1,6 @@
 @import "helpers/clearfix";
 @import "helpers/colored-links";
-@import "helpers/embed";
+@import "helpers/ratio";
 @import "helpers/position";
 @import "helpers/visually-hidden";
 @import "helpers/stretched-link";

scss/_variables.scss

@@ -376,26 +376,16 @@ $transition-base:             all .2s ease-in-out !default;
 $transition-fade:             opacity .15s linear !default;
 $transition-collapse:         height .35s ease !default;
 
-// scss-docs-start embed-responsive-aspect-ratios
-$embed-responsive-aspect-ratios: (
-  "21by9": (
-    x: 21,
-    y: 9
-  ),
-  "16by9": (
-    x: 16,
-    y: 9
-  ),
-  "4by3": (
-    x: 4,
-    y: 3
-  ),
-  "1by1": (
-    x: 1,
-    y: 1
-  )
+// stylelint-disable function-blacklist
+// scss-docs-start aspect-ratios
+$aspect-ratios: (
+  "1x1": 100%,
+  "4x3": calc(3 / 4 * 100%),
+  "16x9": calc(9 / 16 * 100%),
+  "21x9": calc(9 / 21 * 100%)
 ) !default;
-// scss-docs-end embed-responsive-aspect-ratios
+// scss-docs-end aspect-ratios
+// stylelint-enable function-blacklist
 
 // Typography
 //

scss/helpers/_ratio.scss

@@ -0,0 +1,26 @@
+// Credit: Nicolas Gallagher and SUIT CSS.
+
+.ratio {
+  position: relative;
+  width: 100%;
+
+  &::before {
+    display: block;
+    padding-top: var(--aspect-ratio);
+    content: "";
+  }
+
+  > * {
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+  }
+}
+
+@each $key, $ratio in $aspect-ratios {
+  .ratio-#{$key} {
+    --aspect-ratio: #{$ratio};
+  }
+}

site/assets/scss/_component-examples.scss

@@ -167,6 +167,32 @@
   }
 }
 
+// Ratio helpers
+.bd-example-ratios {
+  .ratio {
+    display: inline-block;
+    width: 10rem;
+    color: $gray-600;
+    background-color: $gray-100;
+    border: $border-width solid $border-color;
+
+    > div {
+      display: flex;
+      align-items: center;
+      justify-content: center;
+    }
+  }
+}
+.bd-example-ratios-breakpoint {
+  .ratio-4x3 {
+    width: 16rem;
+
+    @include media-breakpoint-up(md) {
+      --aspect-ratio: 50%; // 2x1
+    }
+  }
+}
+
 .bd-example-modal {
   background-color: #fafafa;
 

site/content/docs/5.0/helpers/ratio.md

@@ -0,0 +1,81 @@
+---
+layout: docs
+title: Ratios
+description: Use generated psuedo 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.
+group: helpers
+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).
+
+{{< callout info >}}
+**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 > *`.
+
+{{< example >}}
+<div class="ratio ratio-16x9">
+  <iframe src="https://www.youtube.com/embed/zpOULjyy-n8?rel=0" title="YouTube video" allowfullscreen></iframe>
+</div>
+{{< /example >}}
+
+## Aspect ratios
+
+Aspect ratios can be customized with modifier classes. By default the following ratio classes are provided:
+
+{{< example class="bd-example-ratios" >}}
+<div class="ratio ratio-1x1">
+  <div>1x1</div>
+</div>
+<div class="ratio ratio-4x3">
+  <div>4x3</div>
+</div>
+<div class="ratio ratio-16x9">
+  <div>16x9</div>
+</div>
+<div class="ratio ratio-21x9">
+  <div>21x9</div>
+</div>
+{{< /example >}}
+
+## Custom ratios
+
+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 `--aspect-ratio: 50%` on the `.ratio`.
+
+{{< example class="bd-example-ratios" >}}
+<div class="ratio" style="--aspect-ratio: 50%;">
+  <div>2x1</div>
+</div>
+{{< /example >}}
+
+This CSS variable makes it easy to modify the aspect ratio across breakpoints. The following is 4x3 to start, but changes to a custom 2x1 at the medium breakpoint.
+
+{{< highlight scss >}}
+.ratio-4x3 {
+  @include media-breakpoint-up(md) {
+    --aspect-ratio: 50%; // 2x1
+  }
+}
+{{< /highlight >}}
+
+{{< example class="bd-example-ratios bd-example-ratios-breakpoint" >}}
+<div class="ratio ratio-4x3">
+  <div>4x3, then 2x1</div>
+</div>
+{{< /example >}}
+
+
+## Sass map
+
+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.
+
+{{< scss-docs name="aspect-ratios" file="scss/_variables.scss" >}}

site/content/docs/5.0/migration.md

@@ -65,6 +65,14 @@ toc: true
 
 - Renamed `whiteList` option to `allowList`.
 
+### Helpers
+
+- Responsive embed helpers have been renamed to [ratio helpers]({{< docsref "/helpers/ratio" >}}) with new class names and improved behaviors, as well as a helpful CSS variable.
+  - Classes have been renamed to change `by` to `x` in the aspect ratrio. For example, `.ratio-16by9` is now `.ratio-16x9`.
+  - We've dropped the `.embed-responsive-item` and element group selector in favor of a simpler `.ratio > *` selector. No more class needed, and the ratio helper now works with any HTML element.
+  - The `$embed-responsive-aspect-ratios` Sass map has been renamed to `$aspect-ratios` and its values have been simplified to include the class name and the percentage as the `key: value` pair.
+  - CSS variables are now generated and included for each value in the Sass map. Modify the `--aspect-ratio` variable on the `.ratio` to create any [custom aspect ratio]({{< docsref "/helpers/ratio#custom-ratios" >}}).
+
 ---
 
 ## v5.0.0-alpha1

site/data/sidebar.yml

@@ -79,7 +79,7 @@
   pages:
     - title: Clearfix
     - title: Colored links
-    - title: Embed
+    - title: Ratio
     - title: Position
     - title: Visually hidden
     - title: Stretched link