Add check require fields for Utilities API

[Psixodelik]

closes #34523

Hi

I added required fields validation when generating utilities using the Utilities API. For this, I added a new mixin to _functions.scss (avoiding code duplication).

The fields for checking are taken from the $required-fields variable (maybe it should be taken out in _variables.scss)

[ffoodd]

We don't need this new argument (which would lead to a breaking change) since we can get the field using $properties: map-get($utility, property) and nth($properties, 1) as it's done L20, isn't it?

[Psixodelik]

The problem is that we are already passing the values, but not the name of the utility. nth($properties, 1) can return multiple values or nothing at all if the property field does not exist.

I can move the name of the utility to the end of the argument chain and make it an optional field. Then I'll add an extra check for the existence of this argument. This will not break the ready-made code for developers.

And you can apply by name. For example, like this: @include generate-utility ($utility, $infix, $utility-name: $key);

[ffoodd]

This change should really be avoided if possible, code relying on generate-utility() outside of our core will break.

[Psixodelik]

Yes, it has something to do with this comment: #34529 (comment)

This part needs to be redone. Look at the solution in the comments, please

[Psixodelik]

@ffoodd Hi

I rewrote the code. I had to leave the name of the utility as an argument, but I made this argument optional, and you can pass it as a named argument. That is, the call can be like this:

@include generate-utility($utility, $infix, $utility-name: $ key);

or

@include generate-utility ($utility, $infix, true);

or

@include generate-utility ($utility, $infix, true, $utility-name: $ key);

etc. This will prevent other developers from breaking code. I haven't come up with any other beautiful solution :( Changing the $ utility array will do more harm than good.

Please see PR. Maybe we can tweak something else. I suggest leaving the checks themselves at the beginning of the mixin so as not to scatter conditions throughout the code. Thus, we will leave the check inside one block of code.

[Psixodelik]

@ffoodd Hi, Are there edits on this PR?

[mdo]

I'll be swinging around to this for our v5.3.0 release—sorry for the delay!

[mdo]

Since this PR was opened, we've expanded the utility API to include CSS variable based utilities, which don't have a property parameter. So the only required field would be values. We could perhaps revisit this and split it based on what's a normal utility vs CSS var utility.

But, after a main merge here, it does work as expected! Super awesome to see.

Warning: Missing 'property' for 'border-width' utility
    scss/_functions.scss 306:5          -validate-utilities-field()
    scss/mixins/_utilities.scss 12:7    generate-utility()
    scss/utilities/_api.scss 13:9       @content
    scss/mixins/_breakpoints.scss 68:5  media-breakpoint-up()
    scss/utilities/_api.scss 5:3        @import
    scss/bootstrap.scss 51:9            root stylesheet

Warning: Missing 'property' for 'border-opacity' utility
    scss/_functions.scss 306:5          -validate-utilities-field()
    scss/mixins/_utilities.scss 12:7    generate-utility()
    scss/utilities/_api.scss 13:9       @content
    scss/mixins/_breakpoints.scss 68:5  media-breakpoint-up()
    scss/utilities/_api.scss 5:3        @import
    scss/bootstrap.scss 51:9            root stylesheet

Warning: Missing 'property' for 'text-opacity' utility
    scss/_functions.scss 306:5          -validate-utilities-field()
    scss/mixins/_utilities.scss 12:7    generate-utility()
    scss/utilities/_api.scss 13:9       @content
    scss/mixins/_breakpoints.scss 68:5  media-breakpoint-up()
    scss/utilities/_api.scss 5:3        @import
    scss/bootstrap.scss 51:9            root stylesheet

Warning: Missing 'property' for 'bg-opacity' utility
    scss/_functions.scss 306:5          -validate-utilities-field()
    scss/mixins/_utilities.scss 12:7    generate-utility()
    scss/utilities/_api.scss 13:9       @content
    scss/mixins/_breakpoints.scss 68:5  media-breakpoint-up()
    scss/utilities/_api.scss 5:3        @import
    scss/bootstrap.scss 51:9            root stylesheet