Utilities functions mixin

[mdo]

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:

1. 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
2. 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
3. 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)

[mdo]

@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]

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 :)

[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.

[romaricpascal]

@louismaximepiton I've tidied up the code in the functions and mixins so the variable names are more consistent and removed code duplication.

I've also brought in the tests that I had used when writing the code to make sure things stay shipshape. To make the test files not too large, I've split the code for manipulating the utilities map in its own file. I think it's fine for it to have a mix of Sass functions and mixins despite being in the mixin folder. It's something that already happens for the breakpoints and border radius and makes it more convenient to import.

[louismaximepiton]

I think it's way better to read and understand now in the right order (in the scss), thanks for that !
For the API page, I think we should at least keep one example of the previous method to show how that it's still feasible.

Some few questions remains for me, but the work done since last time I reviewed it is insane, well done !

[louismaximepiton]

I find it a bit weird to use a callout success as it is only used there, wondering if we should only do something like https://deploy-preview-37398--twbs-bootstrap.netlify.app/docs/5.3/customize/sass/#add-to-map.

[romaricpascal]

@louismaximepiton I don't see any special treatment on the "add-to-map" page, so I'm not sure what you mean. I did find a few examples of new features highlighted in 5.2.0:

• with bold text in https://getbootstrap.com/docs/5.2/components/navbar/
• and with a little block in https://getbootstrap.com/docs/5.2/components/badge/#background-colors

Maybe the callout is just the progression for that for when we want not just to say there's a new feature but also add a bit of text to describe what changes? @mdo what was your reason for using a callout?

[romaricpascal]

Updated again, hopefully I didn't miss anything. Thanks for the comments 😊

For the API page, I think we should at least keep one example of the previous method to show how that it's still feasible.

🤔 Ultimately we'd want to encourage people to use those mixins, not tamper with the $utilities map directly like before, so I'd lean towards not advertising that they can still map-merge(). We could link the "These replace our previous guidance of using Sass's built-in map-merge() function" from the callout (if we keep it) to the 5.2 documentation, as a little reminder (which wouldn't hurt in any case I think)

Some few questions remains for me, but the work done since last time I reviewed it is insane, well done !

Thanks, though that was mostly bringing the tests that were already waiting in a separate branch for the sass-true PR to be merged, so not as big an edit as the diff makes it look like 😆

[louismaximepiton]

Looks fine to me, let's wait for another thought on the way to add some text in a new feature ! Great work 😄