feat(foundations/ratio): add utility and helper for ratios

Resolves #664

packages/styles/settings-tools/_all-settings.scss

@@ -1,36 +1,37 @@
-@import '_tokens.scss';
-@import './_t.map-tools.scss';
-@import './_t.demo-state-class';
-@import './_s.hide.scss';
-@import './_s.unstyle.scss';
-@import './_s.focus.scss';
-@import './_t.size-units-converters.scss';
-@import './_s.inline-icons.scss';
-@import './_s.fonts-faces.scss';
-@import './_s.fonts-scale.scss';
-@import './_s.fonts-colors.scss';
-@import './_s.magic-unit.scss';
-@import './_s.spaces.scss';
-@import './_s.screens.scss';
-@import './_s.radius.scss';
-@import './_s.border.scss';
-@import './_s.shadows.scss';
-@import './_t.reset-forms.scss';
-@import './_t.container.scss';
-@import './_t.flexy.scss';
-@import './_s.buttons.scss';
-@import './_s.checkbox.scss';
-@import './_s.toggle.scss';
-@import './_s.notification.scss';
-@import './_s.radio.scss';
-@import './_s.links.scss';
-@import './_s.select.scss';
-@import './_s.flags.scss';
-@import './_s.stars.scss';
-@import './_s.tag.scss';
-@import './_s.text-input.scss';
-@import './_s.headings.scss';
-@import './_s.divider.scss';
-@import './_s.fields.scss';
-@import './_s.hero.scss';
-@import './_s.progressbar.scss';
+@import "_tokens.scss";
+@import "./_t.map-tools.scss";
+@import "./_t.demo-state-class";
+@import "./_s.hide.scss";
+@import "./_s.unstyle.scss";
+@import "./_s.focus.scss";
+@import "./_t.size-units-converters.scss";
+@import "./_s.inline-icons.scss";
+@import "./_s.fonts-faces.scss";
+@import "./_s.fonts-scale.scss";
+@import "./_s.fonts-colors.scss";
+@import "./_s.magic-unit.scss";
+@import "./_s.spaces.scss";
+@import "./_s.screens.scss";
+@import "./_s.radius.scss";
+@import "./_s.border.scss";
+@import "./_s.shadows.scss";
+@import "./_t.reset-forms.scss";
+@import "./_t.container.scss";
+@import "./_t.flexy.scss";
+@import "./_s.buttons.scss";
+@import "./_s.checkbox.scss";
+@import "./_s.toggle.scss";
+@import "./_s.notification.scss";
+@import "./_s.radio.scss";
+@import "./_s.links.scss";
+@import "./_s.select.scss";
+@import "./_s.flags.scss";
+@import "./_s.stars.scss";
+@import "./_s.tag.scss";
+@import "./_s.text-input.scss";
+@import "./_s.headings.scss";
+@import "./_s.divider.scss";
+@import "./_s.fields.scss";
+@import "./_s.hero.scss";
+@import "./_s.progressbar.scss";
+@import "./_s.ratio.scss";

packages/styles/settings-tools/_s.ratio.scss

@@ -0,0 +1,33 @@
+$aspect-ratios: (
+  "1x1": percentage(1/1),
+  "2x3": percentage(3/2),
+  "3x2": percentage(2/3),
+  "3x4": percentage(4/3),
+  "4x3": percentage(3/4),
+  "16x9": percentage(9/16),
+);
+
+@mixin set-ratio($ratio) {
+  @if map-has-key($aspect-ratios, $ratio) {
+    position: relative;
+
+    &::before {
+      content: "";
+      display: block;
+      padding-top: map-get($aspect-ratios, $ratio);
+      width: 100%;
+    }
+
+    > * {
+      height: 100%;
+      left: 0;
+      position: absolute;
+      top: 0;
+      width: 100%;
+    }
+  }
+
+  @else {
+    @warn 'You are trying to use a ratio size that is not supported : "#{$weight}"';
+  }
+}

packages/styles/utilities/_u.ratio.scss

@@ -0,0 +1,23 @@
+.mu-ratio {
+  position: relative;
+
+  &::before {
+    content: "";
+    display: block;
+    width: 100%;
+  }
+
+  &__item {
+    height: 100%;
+    left: 0;
+    position: absolute;
+    top: 0;
+    width: 100%;
+  }
+
+  @each $ratio, $size in $aspect-ratios {
+    &--#{$ratio}::before {
+      padding-top: $size;
+    }
+  }
+}

src/docs/Foundations/Utilities/Images/code.mdx

@@ -0,0 +1,87 @@
+---
+title: 'Code'
+order: 2
+---
+
+> The implementation of Mozaic ratios in your code can be done in two ways:
+>
+> 1. By using the `set-ratio` mixin
+> 2. By using ratio helpers
+>
+> The above documentation documents both of these approaches.
+
+## Using the `set-ratio` mixin
+
+### Import
+
+In order to use Mozaic ratios via the `set-ratio` mixin, you must first import the `_all-settings.scss` file:
+
+```scss
+@import 'settings-tools/_all-settings';
+```
+
+### Usage
+
+Once you have imported the `_all-settings.scss` file all you need to do is use the `set-ratio` mixin in your code as follows:
+
+```scss
+.your-element {
+  @include set-ratio('1x1');
+}
+```
+
+<Preview path="ratio-with-mixin" />
+
+#### Mixin allowed value
+
+The mixin `set-ratio` accepts the following values:
+
+| ratio    | mixin allowed value |
+| -------- | ------------------- |
+| **1:1**  | `1x1`               |
+| **2:3**  | `2x3`               |
+| **3:2**  | `3x2`               |
+| **3:4**  | `3x4`               |
+| **4:3**  | `4x3`               |
+| **16:9** | `16x9`              |
+
+## Using ratio helpers
+
+### Import
+
+Another way to use Mozaic ratios in your code is to use the ratio helpers.
+
+To do this, you need to import the `_all-settings.scss` file, as well as the `_u.ratio.scss` file.
+
+```scss
+@import 'settings-tools/_all-settings';
+@import 'utilities/_u.ratio.scss';
+```
+
+### Usage
+
+Once you have made all your imports, you just need to add the following elements to your code:
+
+1. Add the class `mu-ratio` followed by a modifier corresponding to the ratio you want to use such as `mu-ratio--16x9`.
+2. Add class `mu-ratio__item` on the child element
+
+```html
+<div class="parent-element mu-ratio mu-ratio--16x9">
+  <iframe class="mu-ratio__item"></iframe>
+</div>
+```
+
+<Preview path="ratio-with-helpers" />
+
+#### List of modifiers to be used
+
+Here is the list of modifiers you can use according to the expected ratio:
+
+| ratio    | associated modifier |
+| -------- | ------------------- |
+| **1:1**  | `mu-ratio--1x1`     |
+| **2:3**  | `mu-ratio--2x3`     |
+| **3:2**  | `mu-ratio--3x2`     |
+| **3:4**  | `mu-ratio--3x4`     |
+| **4:3**  | `mu-ratio--4x3`     |
+| **16:9** | `mu-ratio--16x9`    |

src/docs/Foundations/Utilities/Images/design.mdx

@@ -1,6 +1,6 @@
 ---
 title: 'Design'
-order: 2
+order: 3
 ---
 
 Mozaic provides an optional library with the recommended ratios for designers.

src/docs/Foundations/Utilities/Images/previews/ratio-with-helpers.preview.html

@@ -0,0 +1,13 @@
+<div class="example">
+  <div class="example-element mu-ratio mu-ratio--16x9">
+    <iframe
+      class="mu-ratio__item"
+      width="560"
+      height="315"
+      src="https://www.youtube.com/embed/GS01rL9vU9w"
+      frameborder="0"
+      allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+      allowfullscreen
+    ></iframe>
+  </div>
+</div>

src/docs/Foundations/Utilities/Images/previews/ratio-with-helpers.preview.scss

@@ -0,0 +1,12 @@
+@import "settings-tools/_all-settings";
+@import "utilities/_u.ratio.scss";
+
+.example {
+  display: block;
+  padding: $mu150;
+}
+
+.example-element {
+  margin: 0 auto;
+  max-width: 800px;
+}

src/docs/Foundations/Utilities/Images/previews/ratio-with-mixin.preview.html

@@ -0,0 +1,12 @@
+<div class="example">
+  <div class="example-element">
+    <iframe
+      width="560"
+      height="315"
+      src="https://www.youtube.com/embed/GS01rL9vU9w"
+      frameborder="0"
+      allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+      allowfullscreen
+    ></iframe>
+  </div>
+</div>

src/docs/Foundations/Utilities/Images/previews/ratio-with-mixin.preview.scss

@@ -0,0 +1,13 @@
+@import "settings-tools/_all-settings";
+
+.example {
+  display: block;
+  padding: $mu150;
+}
+
+.example-element {
+  @include set-ratio("16x9");
+
+  margin: 0 auto;
+  max-width: 800px;
+}