chore(styles): improve the utility API

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;
   }
 }

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;
+}

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 */

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`.
 );