From b59a69f2c32451cd06f6d67798fd1cc2c1ff6b5f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aliz=C3=A9=20Debray?=
 <33580481+alizedebray@users.noreply.github.com>
Date: Wed, 9 Oct 2024 16:48:37 +0200
Subject: [PATCH] chore(styles): improve the utility API (#3705)

---
 packages/styles/src/mixins/_media.scss        |   6 +-
 packages/styles/src/utilities/_functions.scss |  35 ++++
 packages/styles/src/utilities/_mixins.scss    | 102 ++++++++-
 packages/styles/src/utilities/_variables.scss | 193 +++++++++++-------
 packages/styles/src/utilities/index.scss      |  32 +--
 .../tests/utilities/functions.test.scss       |  34 +++
 .../styles/tests/utilities/mixins.test.scss   |  99 +++++++--
 7 files changed, 372 insertions(+), 129 deletions(-)
 create mode 100644 packages/styles/src/utilities/_functions.scss
 create mode 100644 packages/styles/tests/utilities/functions.test.scss

diff --git a/packages/styles/src/mixins/_media.scss b/packages/styles/src/mixins/_media.scss
index 2744a83c39..e7dd496aaa 100644
--- a/packages/styles/src/mixins/_media.scss
+++ b/packages/styles/src/mixins/_media.scss
@@ -1,5 +1,9 @@
 @mixin min($device-size) {
-  @media screen and (min-width: $device-size) {
+  @if $device-size != 0 {
+    @media screen and (min-width: $device-size) {
+      @content;
+    }
+  } @else {
     @content;
   }
 }
diff --git a/packages/styles/src/utilities/_functions.scss b/packages/styles/src/utilities/_functions.scss
new file mode 100644
index 0000000000..b60e4e735d
--- /dev/null
+++ b/packages/styles/src/utilities/_functions.scss
@@ -0,0 +1,35 @@
+@use 'sass:list';
+@use 'sass:map';
+@use 'sass:meta';
+
+@use '../functions/string';
+@use '../functions/tokens' as tokens-fn;
+@use '../tokens/utilities' as tokens;
+
+$token-maps: meta.module-variables(tokens);
+
+@function from-tokens($set, $group: $set) {
+  $map-name: 'post-#{$set}';
+  $token-prefix: 'post-utility-#{$group}-';
+
+  @if (not map.has-key($token-maps, $map-name)) {
+    @error 'The utility token map named "$#{$map-name}" is missing.';
+  }
+
+  $values: ();
+  @each $key, $value in map.get($token-maps, $map-name) {
+    @if (string.contains($key, $token-prefix)) {
+      $new-value: (
+        string.replace($key, $token-prefix, ''): $value,
+      );
+
+      $values: map.merge($values, $new-value);
+    }
+  }
+
+  @if (list.length($values) == 0) {
+    @error 'No token matching "#{$token-prefix}*" was found in the "$#{$map-name}" map.';
+  }
+
+  @return $values;
+}
diff --git a/packages/styles/src/utilities/_mixins.scss b/packages/styles/src/utilities/_mixins.scss
index 6c98727479..f062e7d4a2 100644
--- a/packages/styles/src/utilities/_mixins.scss
+++ b/packages/styles/src/utilities/_mixins.scss
@@ -1,16 +1,96 @@
-@use '../functions/string';
-@use '../mixins/media';
-@use '../variables/breakpoints';
-
-@mixin generate-utilities($group, $tokens, $properties, $prefix, $infix: '') {
-  @each $key, $value in $tokens {
-    @if (string.contains($key, 'post-utility-#{$group}')) {
-      $suffix: string.replace($key, 'post-utility-#{$group}', '');
-      .#{$prefix}#{$infix}#{$suffix} {
-        @each $property in $properties {
-          #{$property}: #{$value} !important;
+@use 'sass:map';
+@use 'sass:meta';
+@use 'sass:list';
+@use 'sass:string';
+
+/* stylelint-disable max-nesting-depth */
+@mixin generate-utility($utility, $infix: '') {
+  $values: map.get($utility, values);
+
+  // If the values are a list or string, convert it into a map
+  @if meta.type-of($values) == 'string' or meta.type-of(list.nth($values, 1)) != 'list' {
+    $values: list.zip($values, $values);
+  }
+
+  @each $key, $value in $values {
+    $properties: map.get($utility, property);
+
+    // Multiple properties are possible, for example with vertical or horizontal margins or paddings
+    @if meta.type-of($properties) == 'string' {
+      $properties: list.append((), $properties);
+    }
+
+    // Use custom class if present
+    $property-class: if(
+      map.has-key($utility, class),
+      map.get($utility, class),
+      list.nth($properties, 1)
+    );
+    $property-class: if($property-class == null, '', $property-class);
+
+    // Use custom CSS variable name if present, otherwise default to `class`
+    $css-variable-name: if(
+      map.has-key($utility, css-variable-name),
+      map.get($utility, css-variable-name),
+      map.get($utility, class)
+    );
+
+    // State params to generate pseudo-classes
+    $state: if(map.has-key($utility, state), map.get($utility, state), ());
+
+    $infix: if(
+      $property-class == '' and string.slice($infix, 1, 1) == '-',
+      string.slice($infix, 2),
+      $infix
+    );
+
+    // Don't prefix if value key is null (e.g. with shadow class)
+    $property-class-modifier: if(
+      $key,
+      if($property-class == '' and $infix == '', '', '-') + $key,
+      ''
+    );
+
+    $is-css-var: map.get($utility, css-var);
+    $is-local-vars: map.get($utility, local-vars);
+
+    @if $value != null {
+      @if $is-css-var {
+        .#{$property-class + $infix + $property-class-modifier} {
+          --post-#{$css-variable-name}: #{$value};
+        }
+
+        @each $pseudo in $state {
+          .#{$property-class + $infix + $property-class-modifier}-#{$pseudo}:#{$pseudo} {
+            --post-#{$css-variable-name}: #{$value};
+          }
+        }
+      } @else {
+        .#{$property-class + $infix + $property-class-modifier} {
+          @each $property in $properties {
+            @if $is-local-vars {
+              @each $local-var, $variable in $is-local-vars {
+                --post-#{$local-var}: #{$variable};
+              }
+            }
+            #{$property}: $value !important;
+          }
+        }
+
+        @each $pseudo in $state {
+          .#{$property-class + $infix + $property-class-modifier}-#{$pseudo}:#{$pseudo} {
+            @each $property in $properties {
+              @if $is-local-vars {
+                @each $local-var, $variable in $is-local-vars {
+                  --post-#{$local-var}: #{$variable};
+                }
+              }
+              #{$property}: $value !important;
+            }
+          }
         }
       }
     }
   }
 }
+/* stylelint-enable max-nesting-depth */
diff --git a/packages/styles/src/utilities/_variables.scss b/packages/styles/src/utilities/_variables.scss
index d7c1bca0e7..721d5efe42 100644
--- a/packages/styles/src/utilities/_variables.scss
+++ b/packages/styles/src/utilities/_variables.scss
@@ -1,86 +1,131 @@
 @use '../tokens/utilities' as tokens;
 
-/*
-  Add new utilities using the following structure:
-    [set]: (
-      tokens: map (required),
-      classes: (
-        [group]: (
-          responsive: boolean (optional),
-          prefixes: map (required),
-        )
-      )
-    )
-
-    - `set`:
-      The name of the token set (e.g., if the tokens are contained in the "$post-spacing" map, the set is "spacing").
-
-    - `tokens`:
-      The map of tokens that should be used to generate the utility classes.
+@use './functions' as *;
 
-    - `group`:
-      The group name used in the token keys (e.g., if the tokens are named "post-utility-margin-*", the group is "margin").
+/*
+  Utilities are generated with our utility API using bellow $utilities map.
 
-    - `responsive`:
-      If set to `true`, the utility classes will be generated for all breakpoints (e.g., `-sm`, `-md`, `-lg`, etc.).
-      If set to `false` or omitted, utilities will be generated without a breakpoint infix.
+  The utility map contains a keyed list of utility groups which accept the following options:
 
-    - `prefixes`:
-      A map where each key is the class name prefix and the value is the CSS property (or properties) that the class will set.
+  | Option            | Type     | Default value | Description                                                                                                                                                                                                                              |
+  |-------------------|----------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+  | property          | Required | –             | Name of the property, this can be a string or an array of strings (e.g., horizontal paddings or margins).                                                                                                                                |
+  | values            | Required | –             | List of values, or a map if you don’t want the class name to be the same as the value. If null is used as map key, class is not prepended to the class name.                                                                             |
+  | class             | Optional | null          | Name of the generated class. If not provided and property is an array of strings, class will default to the first element of the property array. If not provided and property is a string, the values keys are used for the class names. |
+  | css-var           | Optional | false         | Boolean to generate CSS variables instead of CSS rules.                                                                                                                                                                                  |
+  | css-variable-name | Optional | null          | Custom un-prefixed name for the CSS variable inside the ruleset.                                                                                                                                                                         |
+  | local-vars        | Optional | null          | Map of local CSS variables to generate in addition to the CSS rules.                                                                                                                                                                     |
+  | state             | Optional | null          | List of pseudo-class variants (e.g., :hover or :focus) to generate.                                                                                                                                                                      |
+  | responsive        | Optional | false         | Boolean indicating if responsive classes should be generated.                                                                                                                                                                            |
 
-  Example:
-  spacing: (
-    tokens: tokens.$post-spacing,       // Refers to the token map containing all spacing values
-    classes: (
-      margin: (                         // Refers to the token "post-utility-margin-*" token in above map
-        classes: (
-          m: margin,                    // Generates `.m-*` classes to set the `margin` property
-          mx: margin-left margin-right, // Generates `.mx-*` classes to set `margin-left` and `margin-right` properties
-          ...
-        ),
-        responsive: true,               // Generates responsive classes
-      )
-    )
-  )
+  Our API is based on bootstrap utility API, more information is available here: https://getbootstrap.com/docs/5.3/utilities/api/
 */
 
 $utilities: (
-  spacing: (
-    tokens: tokens.$post-spacing,
-    classes: (
-      margin: (
-        responsive: true,
-        prefixes: (
-          m: margin,
-          mx: margin-inline,
-          ms: margin-inline-start,
-          me: margin-inline-end,
-          my: margin-block,
-          mt: margin-block-start,
-          mb: margin-block-end,
-        ),
-      ),
-      padding: (
-        responsive: true,
-        prefixes: (
-          p: padding,
-          px: padding-inline,
-          ps: padding-inline-start,
-          pe: padding-inline-end,
-          py: padding-block,
-          pt: padding-block-start,
-          pb: padding-block-end,
-        ),
-      ),
-      gap: (
-        responsive: true,
-        prefixes: (
-          gap: gap,
-          row-gap: row-gap,
-          column-gap: column-gap,
-        ),
-      ),
-    ),
+  'margin': (
+    responsive: true,
+    property: margin,
+    class: m,
+    values: from-tokens('spacing', 'margin'),
+  ),
+  'margin-x': (
+    responsive: true,
+    property: margin-right margin-left,
+    class: mx,
+    values: from-tokens('spacing', 'margin'),
+  ),
+  'margin-y': (
+    responsive: true,
+    property: margin-top margin-bottom,
+    class: my,
+    values: from-tokens('spacing', 'margin'),
+  ),
+  'margin-top': (
+    responsive: true,
+    property: margin-top,
+    class: mt,
+    values: from-tokens('spacing', 'margin'),
+  ),
+  'margin-end': (
+    responsive: true,
+    property: margin-right,
+    class: me,
+    values: from-tokens('spacing', 'margin'),
+  ),
+  'margin-bottom': (
+    responsive: true,
+    property: margin-bottom,
+    class: mb,
+    values: from-tokens('spacing', 'margin'),
+  ),
+  'margin-start': (
+    responsive: true,
+    property: margin-left,
+    class: ms,
+    values: from-tokens('spacing', 'margin'),
+  ),
+
+  'padding': (
+    responsive: true,
+    property: padding,
+    class: p,
+    values: from-tokens('spacing', 'padding'),
   ),
+  'padding-x': (
+    responsive: true,
+    property: padding-right padding-left,
+    class: px,
+    values: from-tokens('spacing', 'padding'),
+  ),
+  'padding-y': (
+    responsive: true,
+    property: padding-top padding-bottom,
+    class: py,
+    values: from-tokens('spacing', 'padding'),
+  ),
+  'padding-top': (
+    responsive: true,
+    property: padding-top,
+    class: pt,
+    values: from-tokens('spacing', 'padding'),
+  ),
+  'padding-end': (
+    responsive: true,
+    property: padding-right,
+    class: pe,
+    values: from-tokens('spacing', 'padding'),
+  ),
+  'padding-bottom': (
+    responsive: true,
+    property: padding-bottom,
+    class: pb,
+    values: from-tokens('spacing', 'padding'),
+  ),
+  'padding-start': (
+    responsive: true,
+    property: padding-left,
+    class: ps,
+    values: from-tokens('spacing', 'padding'),
+  ),
+
+  'gap': (
+    responsive: true,
+    property: gap,
+    class: gap,
+    values: from-tokens('spacing', 'gap'),
+  ),
+  'row-gap': (
+    responsive: true,
+    property: row-gap,
+    class: row-gap,
+    values: from-tokens('spacing', 'gap'),
+  ),
+  'column-gap': (
+    responsive: true,
+    property: column-gap,
+    class: column-gap,
+    values: from-tokens('spacing', 'gap'),
+  ),
+
   // IMPORTANT: When adding new utilities here, please ensure to remove the corresponding bootstrap utilities in `src/themes/bootstrap/_utilities.scss`.
 );
diff --git a/packages/styles/src/utilities/index.scss b/packages/styles/src/utilities/index.scss
index 84aeed5e0d..54e154f001 100644
--- a/packages/styles/src/utilities/index.scss
+++ b/packages/styles/src/utilities/index.scss
@@ -1,6 +1,6 @@
 @use 'sass:map';
+@use 'sass:meta';
 
-@use '../functions/string';
 @use '../mixins/media';
 @use '../variables/breakpoints';
 
@@ -9,31 +9,13 @@
 
 @use './temp/legacy';
 
-@each $set, $config in $utilities {
-  $tokens: map.get($config, tokens);
-  $classes: map.get($config, classes);
+@each $breakpoint, $device-size in breakpoints.$grid-breakpoints {
+  @include media.min($device-size) {
+    $infix: if($device-size == 0, '', '-#{$breakpoint}');
 
-  @each $group, $classesConfig in $classes {
-    $responsive: map.get($classesConfig, responsive);
-    $prefixes: map.get($classesConfig, prefixes);
-
-    @each $prefix, $properties in $prefixes {
-      @if $responsive {
-        @each $breakpoint, $min-width in breakpoints.$grid-breakpoints {
-          @if ($min-width == 0) {
-            // responsive utilities on smaller breakpoint (no breakpoint infix)
-            @include generate-utilities($group, $tokens, $properties, $prefix);
-          } @else {
-            // responsive utilities on all breakpoints that are not the smallest (with breakpoint infix)
-            @include media.min($min-width) {
-              $infix: '-#{$breakpoint}';
-              @include generate-utilities($group, $tokens, $properties, $prefix, $infix);
-            }
-          }
-        }
-      } @else {
-        // non-responsive utilities
-        @include generate-utilities($group, $tokens, $properties, $prefix);
+    @each $key, $utility in $utilities {
+      @if meta.type-of($utility) == 'map' and (map.get($utility, responsive) or $infix == '') {
+        @include generate-utility($utility, $infix);
       }
     }
   }
diff --git a/packages/styles/tests/utilities/functions.test.scss b/packages/styles/tests/utilities/functions.test.scss
new file mode 100644
index 0000000000..4376787cd5
--- /dev/null
+++ b/packages/styles/tests/utilities/functions.test.scss
@@ -0,0 +1,34 @@
+@use 'tests/jest';
+@use 'src/utilities/functions';
+
+$post-spacing: (
+  'post-utility-spacing-1': 12px,
+  'post-utility-spacing-2': 16px,
+);
+
+$post-sizing: (
+  'post-utility-height-1': 24px,
+  'post-utility-height-2': 48px,
+  'post-utility-width-1': 28px,
+  'post-utility-width-2': 44px,
+);
+
+functions.$token-maps: (post-spacing: $post-spacing, post-sizing: $post-sizing);
+
+// it should return all values from the token set
+@include jest.equal(
+  (
+    '1': 12px,
+    '2': 16px,
+  ),
+  functions.from-tokens('spacing')
+);
+
+// it should return values from the group in the token set
+@include jest.equal(
+  (
+    '1': 24px,
+    '2': 48px,
+  ),
+  functions.from-tokens('sizing', 'height')
+);
diff --git a/packages/styles/tests/utilities/mixins.test.scss b/packages/styles/tests/utilities/mixins.test.scss
index 230947b399..34d01304e9 100644
--- a/packages/styles/tests/utilities/mixins.test.scss
+++ b/packages/styles/tests/utilities/mixins.test.scss
@@ -4,25 +4,88 @@
 @use 'src/utilities/mixins';
 
 .test {
-  @include mixins.generate-utilities(
-    $group: 'font-weight',
-    $tokens: (
-      post-utility-font-weight-normal: 400,
-    ),
-    $properties: font-weight,
-    $prefix: 'fw'
+  // it should work with only "property" and "values"
+  @include mixins.generate-utility(
+    (
+      property: text-decoration,
+      values: none underline line-through,
+    )
   );
 
-  @include mixins.generate-utilities(
-    $group: 'gutter',
-    $tokens: (
-      post-utility-gutter-12: 12px,
-    ),
-    $properties: (
-      --gutter-x,
-      --gutter-y,
-    ),
-    $prefix: 'g',
-    $infix: '-lg'
+  // it should work with "class"
+  @include mixins.generate-utility(
+    (
+      property: opacity,
+      class: o,
+      values: (
+        0: 0,
+        25: 0.25,
+        50: 0.5,
+        75: 0.75,
+        100: 1,
+      ),
+    )
+  );
+
+  // it should work with "css-var" and "css-variable-name"
+  @include mixins.generate-utility(
+    (
+      css-var: true,
+      css-variable-name: text-alpha,
+      class: text-opacity,
+      values: (
+        25: 0.25,
+        50: 0.5,
+        75: 0.75,
+        100: 1,
+      ),
+    )
+  );
+
+  // it should work with "local-vars"
+  @include mixins.generate-utility(
+    (
+      property: background-color,
+      class: bg,
+      local-vars: (
+        'bg-opacity': 1,
+      ),
+      values: (
+        'transparent': transparent,
+        'error': red,
+        'success': green,
+      ),
+    )
+  );
+
+  // it should work with "state"
+  @include mixins.generate-utility(
+    (
+      property: opacity,
+      class: opacity,
+      state: hover,
+      values: (
+        0: 0,
+        25: 0.25,
+        50: 0.5,
+        75: 0.75,
+        100: 1,
+      ),
+    )
+  );
+
+  // it should work with "responsive"
+  @include mixins.generate-utility(
+    (
+      property: opacity,
+      responsive: true,
+      values: (
+        0: 0,
+        25: 0.25,
+        50: 0.5,
+        75: 0.75,
+        100: 1,
+      ),
+    )
   );
 }