Utilities functions mixin #37398

mdo · 2022-10-30T23:26:15Z

Replaces #37114 because I couldn't push to that PR.

Re-opening of #35977 after accidentally closing it on my repo (sorry again for that). @mdo, I hope I didn't lose any of your edits in the process as I've also rebased main to fix conflicts in the docs.

As a reminder of what it was about:

Code for #35945. Just threw some code in to get the shapes of the functions. Still need testing, handling all the cases (values not being maps for example), and docs updates (but I'll do that last once the code is set).
The PR adds the following:

functions to get options, a specific option or a specific value for a given utility:
a. utilities-get-options
b. utilities-get-option
c. utilities-get-value

mixins to set options (in bulk or a specific one), new values or remove values for a given utility:
a. utilities-set-options (defaults to merging with existing, but can be used to completely override by passing $merge: false, allowing to completely redefine a utility if necessary)
b. utilities-set-option (just a thin wrapper on utilities-set-options)
c. utilities-add-values
d. utilities-remove-values

mixins to add or remove utilities (they don't do as much as the rest, but provide consistency)
a. utilities-add
b. utilities-remove

Please let me know if there'd be one I missed, or if some are too much (2.b, 3.a. and 3.b for example only bring a consistent API by thinly wrapping other existing functions/mixins)

- get options, a specific option or a specific value for a given utility - set options, new values or remove values for a given utility - add or remove utilities

mdo · 2022-10-31T00:45:02Z

@julien-deramond @louismaximepiton @ffoodd Would love your thoughts on this! Kind of a few PRs worth of history to look through for the full context, but would love to add this for v5.3.

romaricpascal · 2022-11-01T08:55:02Z

Happy to answer any question about the code 😄 One of the things buried in the previous PRs (sorry for the mess with my branches) is that the code is checked by a test suite (kept on a separate branch as it'd rely on sass-true to have been brought into the project, which is getting sorted in #36029).

louismaximepiton

Just few questions, small things to change IMO and as global comments:

Should we introduce default values on each function/mixin ?
Should we check each time for existence of the map ?
What's the future for the maps.scss file ? I thought it was for this kind of purpose (redefine some maps before using them inside utilities API).

However, this sounds really great to have inside Bootstrap. This doesn't add compiled CSS, might not bring any breaking change, might be really useful when well used ! Great work :)

scss/mixins/_utilities.scss

louismaximepiton · 2022-11-08T09:42:28Z

scss/mixins/_utilities.scss

+  @return $values;
+}
+
+@function map-from($list-or-string) {


Just to be sure if I understand well: if we use a string here, there should be only 1 item in the map right ? or is there a way to do multiple item map from a string ?

Yup, @each won't split the string in any way and treat it as a list with 1 item in it.

scss/mixins/_utilities.scss

louismaximepiton · 2022-11-08T09:42:28Z

scss/mixins/_utilities.scss

+
+// Gets the value of a specific option for a given utility
+@function utilities-get-option($utility-name, $option-name) {
+  $options: utilities-get-options($utility-name);


Since we're experiencing some troubles with some overriding Sass variables, should we use a nomenclature such as $utility-options: ...

louismaximepiton · 2022-11-08T09:42:28Z

scss/mixins/_utilities.scss

+  }
+
+  $utilities: map-merge(
+    $utilities,


I suppose $utilities cannot and should not be null here ?

$utilities is the global $utilities variable so is defined by Bootstrap. There's always a risk someone made it null. However, things will blow up in utilities/_api during generation if that's the case, so I'm no sure it's worth being more defensive here.

louismaximepiton · 2022-11-08T09:42:28Z

scss/mixins/_utilities.scss

+@mixin utilities-remove-values($utility-name, $value-names...) {
+  $values: utilities-get-values($utility-name);
+
+  $updated-values: map-remove($values, $value-names...);


Should we check for values not to be null ?

Same as in the previous function, values won't be null thanks to map-from inside utilities-get-values.

louismaximepiton · 2022-11-08T09:42:28Z

scss/mixins/_utilities.scss

+
+// Remove specific values from a given utility
+@mixin utilities-remove-values($utility-name, $value-names...) {
+  $values: utilities-get-values($utility-name);


Should use the same name as the previous function ?

louismaximepiton · 2022-11-08T09:42:28Z

scss/mixins/_utilities.scss

+
+// Add a new utility to the utilities map
+@mixin utilities-add($utility-name, $utility) {
+  $utilities: map-merge(


Should we use @include utilities-set-options($utility-name, $utility, false); ?

site/content/docs/5.2/customize/color.md

romaricpascal

@louismaximepiton Thanks for the review 😄 I've finally found some time to provide some answers, at least for those related to the internals of the functions/mixins. I can only let you and the Bootstrap team decide on whether functions should be extracted in other files and such 😄 .

I'm not quite sure how to deal with the few amends as it's now @mdo's branch on the Bootstrap repo. A PR towards this branch feels a bit overkill, and it'll likely be much faster if someone with write access moves things around (especially as I don't have as much capacity to contribute nowadays, sorry).

As a side note, now #36029 has been merged, it's likely worth pulling in the tests I had set up on a separate branch for writing these functions and mixins.

scss/mixins/_utilities.scss

romaricpascal · 2022-12-26T16:08:23Z

scss/mixins/_utilities.scss

+  @return $values;
+}
+
+@function map-from($list-or-string) {


Yup, @each won't split the string in any way and treat it as a list with 1 item in it.

romaricpascal · 2022-12-26T16:08:23Z

scss/mixins/_utilities.scss

+
+// Set options for a given utility, merged with the existing ones by default.
+// To completely replace the existing options, set the 3rd `$merge` parameter to false
+@mixin utilities-set-options($utility-name, $options, $merge: true) {


Good point on utilities-add being utilities-set-options with $merge: false. I agree it's likely worth refactoring so utilities-add just delegates to utilities-set-options to avoid duplication.

romaricpascal · 2022-12-26T16:08:23Z

scss/mixins/_utilities.scss

+  }
+
+  $utilities: map-merge(
+    $utilities,


$utilities is the global $utilities variable so is defined by Bootstrap. There's always a risk someone made it null. However, things will blow up in utilities/_api during generation if that's the case, so I'm no sure it's worth being more defensive here.

romaricpascal · 2022-12-26T16:08:23Z

scss/mixins/_utilities.scss

+@mixin utilities-remove-values($utility-name, $value-names...) {
+  $values: utilities-get-values($utility-name);
+
+  $updated-values: map-remove($values, $value-names...);


Same as in the previous function, values won't be null thanks to map-from inside utilities-get-values.

romaricpascal · 2022-12-26T16:08:23Z

scss/mixins/_utilities.scss

+    $utility-name,
+    values,
+    map-merge(
+      $existing-values,


utilities-get-values will return an empty map through map-from, so we can always run map-merge without worry here 😄 That'll create a values field if it didn't exist already, but it feels fair as it fulfils what the function name says.

romaricpascal and others added 9 commits Oct 30, 2022

Add functions and mixins to manipulate the utlities map

5ef76ca

- get options, a specific option or a specific value for a given utility - set options, new values or remove values for a given utility - add or remove utilities

Add thorough implementation of utilities functions and mixins

84a447e

Update utilities documentation

500495f

Update example in color API documentation

be0402c

Reorganise headings in utilities page and minor edits

f07f5e4

Minor formatting

3b98827

Some edits

b8c18ab

Update utility example to avoid cspell error

8f2b9e7

Update copy on new utility API docs

e79e7f6

mdo added feature css v5 labels Oct 30, 2022

mdo requested a review from a team as a code owner Oct 30, 2022

This was referenced Oct 30, 2022

Add functions and mixins to manipulate the utlities map #37114

Closed

Adding to "customize/sass/#add-to-map" info about utilities #37319

Closed

louismaximepiton reviewed Nov 8, 2022

View changes

romaricpascal reviewed Dec 26, 2022

View changes

mdo added the utility API label Dec 28, 2022

Nov	DEC	Jan
	31
2021	2022	2023

Utilities functions mixin #37398

Utilities functions mixin #37398

mdo commented Oct 30, 2022

mdo commented Oct 31, 2022

romaricpascal commented Nov 1, 2022

louismaximepiton left a comment

louismaximepiton Nov 8, 2022

romaricpascal Dec 26, 2022

louismaximepiton Nov 8, 2022

louismaximepiton Nov 8, 2022

romaricpascal Dec 26, 2022

louismaximepiton Nov 8, 2022

romaricpascal Dec 26, 2022

louismaximepiton Nov 8, 2022

louismaximepiton Nov 8, 2022

romaricpascal left a comment

romaricpascal Dec 26, 2022

romaricpascal Dec 26, 2022

romaricpascal Dec 26, 2022

romaricpascal Dec 26, 2022

romaricpascal Dec 26, 2022

Utilities functions mixin #37398

Are you sure you want to change the base?

Utilities functions mixin #37398

Conversation

mdo commented Oct 30, 2022

mdo commented Oct 31, 2022

romaricpascal commented Nov 1, 2022

louismaximepiton left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

romaricpascal left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment