Skip to content

Commit

Permalink
chore(styles): improve the utility API (#3705)
Browse files Browse the repository at this point in the history
  • Loading branch information
@alizedebray
alizedebray authored Oct 9, 2024
1 parent c9ad537 commit b59a69f
Show file tree
Hide file tree
Showing 7 changed files with 372 additions and 129 deletions.
6 changes: 5 additions & 1 deletion packages/styles/src/mixins/_media.scss
View file
Original file line number Diff line number Diff line change
@@ -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;
}
}
Expand Down
35 changes: 35 additions & 0 deletions packages/styles/src/utilities/_functions.scss
View file
Original file line number Diff line number Diff line change
@@ -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;
}
102 changes: 91 additions & 11 deletions packages/styles/src/utilities/_mixins.scss
View file
Original file line number Diff line number Diff line change
@@ -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 */
193 changes: 119 additions & 74 deletions packages/styles/src/utilities/_variables.scss
View file
Original file line number Diff line number Diff line change
@@ -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`.
);
Loading

0 comments on commit b59a69f

Please sign in to comment.