feat: add functions/mixins for XY Grid cell base/size/gutters

Move all the `xy-cell()` mixin logics to dedicated functions and mixins.

Changes:
- Add function `xy-cell-gutters()`: Calculate the size of a cell gutters.
- Add function `xy-cell-size-css()`: Returns the appropriate CSS value for a cell size.
- Add mixin `xy-cell-size()`: ets sizing properties for cells.
- Add mixin `xy-cell-gutters()`: Sets gutters properties for cells.
- Refactor mixin `xy-cell()` to move all the logics to these new mixins.

All these functions/mixins now have the same interface. They do not always expect all the XY cell arguments, but they name and process the argument they expect the same way.

**BREAKING CHANGE**: When no gutter can be found to generate a cell, an error is now thrown

diff --git a/scss/xy-grid/_cell.scss b/scss/xy-grid/_cell.scss
index 07dd94f34df348b2a772a20437ed0b27bb56082e..e3360ce790a1df7b630340016a36ffc2989bf60f 100644 (file)
--- a/scss/xy-grid/_cell.scss
+++ b/scss/xy-grid/_cell.scss
@@ -6,7 +6,28 @@
 /// @group xy-grid
 ////
 
-/// Calculate the percentage size of a cell.
+/// Calculate the size of a cell gutters.
+///
+/// @param {Number|Map} $gutters [$grid-margin-gutters] - Map or single value for gutters.
+/// @param {String} $breakpoint [null] - The name of the breakpoint size in your gutters map to get the size from. If using with the `breakpoint()` mixin this will be set automatically unless manually entered.
+///
+/// @returns {Number} The cell gutter size.
+@function xy-cell-gutters(
+  $gutters: $grid-margin-gutters,
+  $breakpoint: null
+) {
+  // Use the contextual breakpoint by default.
+  $breakpoint: -zf-current-breakpoint($breakpoint);
+
+  @if ($breakpoint) {
+    @return -zf-get-bp-val($gutters, $breakpoint);
+  }
+  @else {
+    @return -zf-get-bp-val($gutters, $-zf-zero-breakpoint) or 0;
+  }
+}
+
+/// Returns the percentage size of a cell.
 ///
 /// @param {Number|List} $size [$grid-columns] - Size to make the cell. You can pass a value in multiple formats, such as `6`, `50%`, `1 of 2` or `1/3`.
 @function xy-cell-size(
@@ -15,6 +36,43 @@
   @return fraction-to-percentage($size, $denominator: $grid-columns);
 }
 
+/// 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.
+///
+/// @param {Keyword|Number} $size [full] - The size of your cell. Can be `full`, `auto`, `shrink` or any fraction like `6`, `50%`, `1 of 2` or `1/2`.
+/// @param {Number|Map} $gutters [$grid-margin-gutters] - Map or single value for gutters.
+/// @param {Keyword} $gutter-type [margin] - Type of gutter to output. Accepts `margin`, `padding` or `none`.
+/// @param {String} $breakpoint [null] - The name of the breakpoint size in your gutters map to get the size from. If using with the `breakpoint()` mixin this will be set automatically unless manually entered.
+///
+/// @returns {Number|String} The cell sizing property value.
+@function xy-cell-size-css(
+  $size: full,
+  $gutters: $grid-margin-gutters,
+  $gutter-type: margin,
+  $breakpoint: null
+) {
+  $margin-gutter: 0;
+
+  @if ($size == 'auto' or $size == 'shrink') {
+    @return auto;
+  }
+
+  // For cells with margin gutters, the gutter is included in the width.
+  @if ($gutter-type == 'margin') {
+    $margin-gutter: xy-cell-gutters($gutters, $breakpoint);
+    @if ($margin-gutter == null) {
+      @error 'xy-cell-size: no gutters were found in `$gutters` for "$breakpoint: #{$breakpoint}"`';
+    }
+  }
+
+  // Calculate the cell size (number)
+  $size-raw: if($size == 'full', 100%, xy-cell-size($size));
+  // Calculate the cell CSS size including gutters (string)
+  $size-css: if($margin-gutter == 0, $size-raw, calc(#{$size-raw} - #{rem-calc($margin-gutter)}));
+  @return $size-css;
+}
+
 /// Sets base flex properties for cells.
 ///
 /// @param {Keyword} $size [full] - The size of your cell. Accepts `full`, `auto`, `shrink` or `grow`.
@@ -45,23 +103,55 @@
   max-#{$direction}: none;
 }
 
-// Sets our cell widths or heights depending on gutter type.
-@mixin -xy-cell-properties($size, $margin-gutter, $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.
+///
+/// @param {Keyword|Number} $size [full] - The size of your cell. Can be `full` (default) for 100% width, `auto` to use up available space and `shrink` to use up only required space.
+/// @param {Number|Map} $gutters [$grid-margin-gutters] - Map or single value for gutters.
+/// @param {Keyword} $gutter-type [margin] - Type of gutter to output. Accepts `margin`, `padding` or `none`.
+/// @param {String} $breakpoint [null] - The name of the breakpoint size in your gutters map to get the size from. If using with the `breakpoint()` mixin this will be set automatically unless manually entered.
+/// @param {Boolean} $vertical [false] - Set to true to output vertical (height) styles rather than widths.
+@mixin xy-cell-size(
+  $size: full,
+  $gutters: $grid-margin-gutters,
+  $gutter-type: margin,
+  $breakpoint: null,
+  $vertical: false
+) {
+  $size: xy-cell-size-css($size, $gutters, $gutter-type, $breakpoint);
   $direction: if($vertical == true, height, width);
-  @if($size == 'full') {
-    $val: if($margin-gutter == 0, 100%, calc(100% - #{rem-calc($margin-gutter)}));
-    #{$direction}: $val;
-  }
-  @else if ($size == 'auto') {
-    #{$direction}: auto;
-    $val: if($margin-gutter == 0, 100%, calc(100% - #{rem-calc($margin-gutter)}));
+
+  #{$direction}: $size;
+}
+
+/// Sets gutters properties for cells.
+///
+/// @param {Number|Map} $gutters [$grid-margin-gutters] - Map or single value for gutters.
+/// @param {Keyword} $gutter-type [margin] - Type of gutter to output. Accepts `margin`, `padding` or `none`.
+/// @param {List} $gutter-position [null] - The position to apply gutters to. Accepts `top`, `bottom`, `left`, `right` in any combination. By default `right left` for horizontal cells and `top bottom` for vertical cells.
+/// @param {String} $breakpoint [null] - The name of the breakpoint size in your gutters map to get the size from. If using with the `breakpoint()` mixin this will be set automatically unless manually entered.
+/// @param {Boolean} $vertical [false] - Direction of the gutters to output. See `$gutter-position`.
+@mixin xy-cell-gutters(
+  $gutters: $grid-margin-gutters,
+  $gutter-type: margin,
+  $gutter-position: null,
+  $breakpoint: null,
+  $vertical: false
+) {
+  // Get the default gutter position according to cell direction
+  @if($gutter-position == null) {
+    $gutter-position: if($vertical == true, top bottom, left right);
   }
-  @else if ($size == 'shrink') {
-    #{$direction}: auto;
+
+  // Get the gutter width for this breakpoint
+  $gutter-width: xy-cell-gutters($gutters, $breakpoint);
+  @if ($gutter-width == null) {
+    @error 'xy-cell-gutters: no gutters were found in `$gutters` for "$breakpoint: #{$breakpoint}"`';
   }
-  @else {
-    $val: if($margin-gutter == 0, #{xy-cell-size($size)}, calc(#{xy-cell-size($size)} - #{rem-calc($margin-gutter)}));
-    #{$direction}: $val;
+
+  @if ($gutter-type and $gutter-type != none) {
+    @include xy-gutters($gutter-width, $gutter-type, $gutter-position);
   }
 }
 
@@ -85,8 +175,6 @@
   $vertical: false,
   $output: (base size gutters)
 ) {
-  $bp-is-fallback: false;
-
   // Default for $gutter-output
   @if ($gutter-output != null) {
     @warn 'xy-cell: $gutter-output is deprecated and will be removed. See migration notes at https://git.io/foundation-6-6-0';
@@ -95,41 +183,14 @@
     }
   }
 
-  // Use the contextual breakpoint by default. Otherwise revert to the smallest breakpoint
-  $breakpoint: -zf-current-breakpoint($breakpoint);
-  @if($breakpoint == null) {
-    $breakpoint: $-zf-zero-breakpoint;
-    $bp-is-fallback: true;
+  @if (index($output, base)) {
+    @include xy-cell-base($size);
   }
-
-  // Get the default gutter position according to cell direction
-  @if($gutter-position == null) {
-    $gutter-position: if($vertical == true, top bottom, left right);
+  @if (index($output, size)) {
+    @include xy-cell-size($size, $gutters, $gutter-type, $breakpoint, $vertical);
   }
-
-  // Get the gutter for the given breakpoint/value.
-  $gutter: -zf-get-bp-val($gutters, $breakpoint);
-  // If the breakpoint is a fallback, use a fallback gutter as well
-  @if ($bp-is-fallback == true and $gutter == null) {
-    $gutter: 0;
-  }
-
-  @if($gutter != null) {
-    $-gutter-margin: if($gutter-type == 'margin', $gutter, 0);
-
-    // Base flex properties
-    @if (index($output, base)) {
-      @include xy-cell-base($size);
-    }
-    @if (index($output, size)) {
-      @include -xy-cell-properties($size, $-gutter-margin, $vertical);
-    }
-    @if (index($output, gutters) and $gutter-type and $gutter-type != none) {
-      @include xy-gutters($gutter, $gutter-type, $gutter-position);
-    }
-  }
-  @else {
-    @warn 'xy-cell: no gutters were found in `$gutters` for "$breakpoint: #{$breakpoint}", cell was not generated`';
+  @if (index($output, gutters)) {
+    @include xy-cell-gutters($gutters, $gutter-type, $gutter-position, $breakpoint, $vertical);
   }
 }