Refactor XY Grid cell mixins

[ncoden]

Description

This pull request add new options, functions and mixins to the XY Grid and deprecate some others with the following objective:

• Reduce the number of entry points to use the XY Grid and harmonize the interface between the XY Grid mixins.
• Give a finer control on the CSS output
• Add clarity about different usages of gutters generations

Changes

Update XY Grid static classes generation

• Use new XY cell base/gutters/size mixins to generate classes instead of the xy-cell-static() mixin
• Deprecate xy-cell-static() mixin (See migration notes below)

Update XY Grid mixins:

• Add support for fractions in xy-cell-size() mixin
  Support values representing a fraction (6, 50%, 1 of 2 or 1/2...), treating them like shrink.

• Use the contextual breakpoint in xy-cell-offset() and xy-cell-layout()
  Support for the current breakpoint context set by the breakpoint() mixin.

• Add support for none value for $gutter-type in all XY Grid mixins
  Generate a gutters-less cell, instead of a gutter "without gutters generated" or "with 0-width gutters".

• Add $output option to xy-cell() and xy-grid-layout() mixins
  Cell parts to output. You will need to generate others parts of the cell seperately, it may not work properly otherwise.

• Deprecate $gutter-output option in favor of $output (See migration notes below)
  Note: Breaking change introduced in fix: respect $gutter-output in the -xy-cell-properties mixin #11081 has been replaced with a warning notice.

Add XY Grid functions:

• xy-cell-base($size)
  Returns the appropriate CSS flex value for a cell base.

• xy-cell-gutters($gutters, $breakpoint)
  Calculate the size of a cell gutters.

• xy-cell-size-css($size, $gutters, $gutter-type, $breakpoint)
  Returns the appropriate CSS value for a cell size. Gutters-related arguments are required for cells with margin gutters (by default) as the gutter is included in the width.

• xy-cell-offset($n, $gutters, $gutter-type, $breakpoint)
  Returns the appropriate CSS value to offset a cell.

Add XY Grid mixins:

• xy-cell-size($size, $gutters, $gutter-type, $breakpoint, $vertical)
  Sets sizing properties for cells. Gutters-related arguments are required for cells with margin gutters (by default) as the gutter is included in the width.

• xy-cell-gutters($size, $gutter-type, $gutter-position, $breakpoint, $vertical)
  Sets gutters properties for cells.

Add utility functions:

• -zf-bool($val)
  Convert the given $val to a Boolean. Empty values are considered as false.

• zf-is-fraction($value, $allow-no-denominator)
  Returns whether the given $value represents a fraction. Supports formats like 50%, 1 of 2, 1 per 2 or 1/2.

• zf-parse-fraction($fraction)
  Parse the given $fraction to numerators and denumerators.

• fraction-to-percentage($fraction, $denominator)
  Calculate a percentage from a given fraction.

Add utility mixins:

• -zf-each-breakpoint-in($breakpoints, $zero-breakpoint, $media-queries)
  Iterates with @content through the given list of breakpoints $breakpoints.

Others changes:

• Fix reversed $vertical option in xy-cell-reset() mixin.
• Fix description for $gutter-type in xy-cell() mixin
• Add missing semicolon in xy-grid() mixin
• Add info about the cell parts and related mixins in the XY Grid documentation

Impact

🚚 CSS

With the disctinction it provide about different gutters generation usages, this PR remove useless gutters added in #11081 and let us saving some KB.

You can see the diff between this PR and develop at https://www.diffchecker.com/lMRwqPWa

⚠️ Deprecations

• All XY cell mixins/functions: deprecate the $gutter-output option
  We now recommand the usage of the following options according to the needs:
  • Use $gutter-type: none for cells without gutters.
  • Use $gutters: 0 for cells with a 0-width gutters.
  • Use $output: (...) without the gutters keyword for cells with gutters that must be generated seperately.

    // Before
    @include xy-cell($gutter-output: false);

    // After
    @include xy-cell($output: (base size));

• Deprecate the xy-cell-static() mixin
  Use the xy-cell() mixin instead. As xy-cell-static() do not generate the cell base, you may need to use the $output option, like the following.

    // Before
    @include xy-cell-static();
  
    // After
    @include xy-cell($output: (size gutters));

💥 Breaking changes:

• All XY cell mixins/functions: a valid gutter config and breakpoint is now required.
  When no gutter can be found to generate a cell, an error is now thrown.

• The xy-cell-offset() mixin does not support raw values for $breakpoint anymore
  To add an offset to a XY cell with custom gutters, use the $gutters option instead.

    // Before
    @include xy-cell-offset(6, $breakpoint: 16px);
  
    // After
    @include xy-cell-offset(6, $gutters: 16px);

• The xy-cell() and xy-cell-base() mixins now generate the XY cell base CSS when $size represents a fraction.
  If you call xy-cell() with a fraction but do not want to generate the full cell, use the $output option.

    // Before
    @include xy-cell-base(shrink);
    (...)
    @include xy-cell(12);
  
    // After
    @include xy-cell-base(shrink);
    // or @include xy-cell(shrink, $output: (base));
    (...)
    @include xy-cell(12, $output: (size gutters));

  If you call xy-cell-base() dynamically and do not want to generate the base for each keyword/fraction you pass it, check $size before calling the mixin or generate the base seperately.

    // Before
    @each $size in $my-array-of-sizes {
      .my-cell.my-cell-#{$size} {
        @include xy-cell($size);
      }
    }

    // After.
    .my-cell {
      @include xy-cell-base();
    }
    @each $size in $my-array-of-sizes {
      .my-cell-#{$size} {
        @include xy-cell($size, $output: (size gutters));
      }
    }

TODO ⚠️

• Provide a cell-oriented mixin for each part generated by xy-cell()
• Make some tests to make sure that everything works as before
• Update documentation

Types of changes

• Documentation
• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing
  functionality to change)

Checklist (all required):

• I have read and follow the CONTRIBUTING document.
• There are no other pull request similar to this one.
• The pull request title is descriptive.
• The template is fully and correctly filled.
• The pull request targets the right branch (develop or develop-v...).
• My commits are correctly titled and contain all relevant information.
• My code follows the code style of this project.
• I have updated the documentation accordingly to my changes (if relevant).
• I have added tests to cover my changes (if relevant).
• All new and existing tests passed.

[DanielRuf]

Not sure how I can test the changes or what has changed in comparison to before.
Can you explain further @ncoden?

[ncoden]

@DanielRuf hmm, the description of this pull request should describe everything. All changes in the API. New features, deprecations, breaking changes and new recommended usages are listed.

But to make you a quick resume:

• Split the xy-cell mixin into multiple mixins: xy-cell-base, xy-cell-size-css, xy-cell-gutters. They take gutter-oriented arguments.
• Replace the $gutter-output option by much safer options. See Deprecations for more infos.
• Change some arguments defaults and behaiors in various XY mixins and functions so their all behave the same way across mixins/functions.
• Some refactor and optimizations
• Various bug fixes (already merged in v6.5)

There is a lot of changes so the git diff may be a bit confusing, but you can look at individual commits, I tried to keep a clear Git history.

[ncoden]

@SassNinja @DanielRuf Will you have some time to review this?

[SassNinja]

I like your fraction utils!

Lets you create readable, nice code if someone requests 'special' stuff

@include xy-cell(2 of 10);

and even supports multi lang 😄

@include xy-cell(2 von 10);

[ncoden]

@SassNinja Let me know when you finished your review 😉

[SassNinja]

Let me know when you finished your review

I'm no grid power user (quite happy with the basic features 😉) but so far it looks good to me and makes sense.

So good to merge imo.

[DanielRuf]

I'm no grid power user (quite happy with the basic features 😉) but so far it looks good to me and makes sense.

So good to merge imo.

Same here. We do not use these mixins in most projects so I can not test this thoroughly.

[ncoden]

Thank you folks for the review! 👍
I am not a big user of the Sass XY Grid too, but I know the Grid, Flex Grid and XY Grid APIs very well, and how modular mixins and functions may be useful in big Sass projects.

[joeworkman]

This pull request has been mentioned on Foundation Open Source Community. There might be relevant details there:

https://foundation.discourse.group/t/foundation-for-sites-v6-6-0-is-here-farout/30/1

[k33n8nc]

Love the update :) Maybe this is a bit unrelated, but is there any documentation on the reworked XY Grid? The docs are not updated yet, the migration files showing most of the changes, not all of them. Haven't tried the local docs.

Anyone who could point me in the right the direction? Would love to dive into the mixins and see what i can do there :)

[DanielRuf]

In general I can see them in the docs: https://get.foundation/sites/docs/xy-grid.html#xy-cell-base

[k33n8nc]

Must have missed, cause now i see.
Thanks! (y)

[nitrokevin]

can someone please give me an example of xy-cell-layout with the new changes to gutters, I don't really understand what needs to be done, for example a current block grid I'm using is:

 @include xy-grid-layout(2, '.flexible-item', true, $grid-margin-gutters, margin, left right, small, false);

[minchen085]

谢