@carbon/grid 10.0.0-rc.0 → 10.2.0

package/scss/_inlined/_mixins.scss

@@ -0,0 +1,335 @@
+//
+// Copyright IBM Corp. 2018, 2018
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+// Helpers for defining columns, rows, and containers are heavily inspired by,
+// and often derived from, bootstrap:
+// https://github.com/twbs/bootstrap/blob/v4-dev/scss/mixins/_grid.scss
+
+@import '../vendor/@carbon/layout/breakpoint';
+@import 'prefix';
+
+// -----------------------------------------------------------------------------
+// Columns
+// -----------------------------------------------------------------------------
+
+/// Used to initialize the default properties for a column class, most notably
+/// for setting width and default gutters when a column's breakpoint has not been
+/// hit yet.
+/// @param {Number} $gutter [$carbon--grid-gutter] - The gutter for the grid system
+/// @param {Number} $collapsed-gutter [$carbon--grid-gutter--condensed] - The condensed mode gutter
+/// @access private
+/// @group @carbon/grid
+@mixin carbon--make-col-ready(
+  $gutter: $carbon--grid-gutter,
+  $condensed-gutter: $carbon--grid-gutter--condensed
+) {
+  // Prevent columns from becoming too narrow when at smaller grid tiers by
+  // always setting `width: 100%;`. This works because we use `flex` values
+  // later on to override this initial width.
+  width: 100%;
+  padding-right: ($gutter / 2);
+  padding-left: ($gutter / 2);
+
+  // For our condensed use-case, our gutters collapse to 2px solid, 1px on each
+  // side.
+  .#{$prefix}--row--condensed &,
+  .#{$prefix}--grid--condensed & {
+    padding-right: ($condensed-gutter / 2);
+    padding-left: ($condensed-gutter / 2);
+  }
+}
+
+/// Define the width of the column for a given span and column count.
+/// @param {Number} $span - The number of columns covered
+/// @param {Number} $columns - The total number of columns available
+/// @access private
+/// @group @carbon/grid
+@mixin carbon--make-col($span, $columns) {
+  flex: 0 0 percentage($span / $columns);
+  // Add a `max-width` to ensure content within each column does not blow out
+  // the width of the column. Applies to IE10+ and Firefox. Chrome and Safari
+  // do not appear to require this.
+  max-width: percentage($span / $columns);
+}
+
+/// Create a column offset for a given span and column count.
+/// @param {Number} $span - The number of columns the offset should cover
+/// @param {Number} $columns - The total number of columns available
+/// @access private
+/// @group @carbon/grid
+@mixin carbon--make-col-offset($span, $columns) {
+  $offset: $span / $columns;
+  @if $offset == 0 {
+    margin-left: 0;
+  } @else {
+    margin-left: percentage($offset);
+  }
+}
+
+/// Output the CSS required for all the columns in a given grid system.
+/// @param {Map} $breakpoints [$carbon--grid-breakpoints] - The breakpoints in the grid system
+/// @param {Number} $gutter [$carbon--grid-gutter] - The gutter for the grid system
+/// @access private
+/// @group @carbon/grid
+@mixin carbon--make-grid-columns(
+  $breakpoints: $carbon--grid-breakpoints,
+  $gutter: $carbon--grid-gutter
+) {
+  .#{$prefix}--col {
+    @include carbon--make-col-ready();
+  }
+
+  @each $breakpoint in map-keys($breakpoints) {
+    $infix: carbon--breakpoint-infix($breakpoint);
+    $columns: map-get(map-get($breakpoints, $breakpoint), columns);
+
+    // Allow columns to stretch full width below their breakpoints
+    @for $i from 1 through $columns {
+      .#{$prefix}--col#{$infix}-#{$i} {
+        @include carbon--make-col-ready();
+      }
+    }
+
+    .#{$prefix}--col#{$infix},
+    .#{$prefix}--col#{$infix}--auto {
+      @include carbon--make-col-ready();
+    }
+
+    @include carbon--breakpoint($breakpoint, $breakpoints) {
+      // Provide basic `.col-{bp}` classes for equal-width flexbox columns
+      .#{$prefix}--col,
+      .#{$prefix}--col#{$infix} {
+        flex-basis: 0;
+        flex-grow: 1;
+        max-width: 100%;
+      }
+
+      .#{$prefix}--col--auto,
+      .#{$prefix}--col#{$infix}--auto {
+        flex: 1 0 0%;
+        width: auto;
+        // Reset earlier grid tiers
+        max-width: 100%;
+      }
+
+      @for $i from 1 through $columns {
+        .#{$prefix}--col#{$infix}-#{$i} {
+          @include carbon--make-col($i, $columns);
+        }
+      }
+
+      @for $i from 0 through ($columns - 1) {
+        @if not($infix == '') {
+          .#{$prefix}--offset#{$infix}-#{$i} {
+            @include carbon--make-col-offset($i, $columns);
+          }
+        }
+      }
+    }
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Rows
+// -----------------------------------------------------------------------------
+
+/// Define the properties for a selector assigned to a row in the grid system.
+/// @param {Number} $gutter [$carbon--grid-gutter] - The gutter in the grid system
+/// @access private
+/// @group @carbon/grid
+@mixin carbon--make-row($gutter: $carbon--grid-gutter) {
+  display: flex;
+  flex-wrap: wrap;
+  margin-right: -1 * $gutter / 2;
+  margin-left: -1 * $gutter / 2;
+}
+
+// -----------------------------------------------------------------------------
+// No gutter
+// -----------------------------------------------------------------------------
+
+/// Add `no-gutter` and `no-gutter--{left,right}` classes to the output CSS. These
+/// classes are useful for dropping the gutter in fluid situations.
+/// @access private
+/// @group @carbon/grid
+@mixin carbon--no-gutter {
+  .#{$prefix}--no-gutter,
+  .#{$prefix}--row.#{$prefix}--no-gutter [class*='#{$prefix}--col'] {
+    padding-left: 0;
+    padding-right: 0;
+  }
+
+  .#{$prefix}--no-gutter--left,
+  .#{$prefix}--row.#{$prefix}--no-gutter--left [class*='#{$prefix}--col'] {
+    padding-left: 0;
+  }
+
+  .#{$prefix}--no-gutter--right,
+  .#{$prefix}--row.#{$prefix}--no-gutter--right [class*='#{$prefix}--col'] {
+    padding-right: 0;
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Hang
+// -----------------------------------------------------------------------------
+
+/// Add `hang--left` and `hang--right` classes for a given gutter. These classes are
+/// used alongside `no-gutter--left` and `no-gutter--right` to "hang" type.
+/// @param {Number} $gutter [$carbon--grid-gutter] - The gutter in the grid system
+/// @access private
+/// @group @carbon/grid
+@mixin carbon--hang($gutter: $carbon--grid-gutter) {
+  .#{$prefix}--hang--left {
+    padding-left: ($gutter / 2);
+  }
+
+  .#{$prefix}--hang--right {
+    padding-right: ($gutter / 2);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Aspect ratio
+// -----------------------------------------------------------------------------
+
+/// The aspect ratios that are used to generate corresponding aspect ratio
+/// classes in code
+/// @type List
+/// @access public
+/// @group @carbon/grid
+$carbon--aspect-ratios: ((16, 9), (2, 1), (4, 3), (1, 1));
+
+/// Output the CSS classes for generating aspect ratio classes
+/// @param {List} $aspect-ratios [$carbon--aspect-ratios] - A list of aspect ratios to generate
+/// @access private
+/// @group @carbon/grid
+@mixin carbon--aspect-ratio($aspect-ratios: $carbon--aspect-ratios) {
+  .#{$prefix}--aspect-ratio {
+    height: 0;
+    position: relative;
+  }
+
+  .#{$prefix}--aspect-ratio--object {
+    position: absolute;
+    top: 0;
+    right: 0;
+    bottom: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    z-index: 100;
+  }
+
+  @each $ratio in $aspect-ratios {
+    $width: nth($ratio, 1);
+    $height: nth($ratio, 2);
+
+    .#{$prefix}--aspect-ratio--#{$width}x#{$height} {
+      padding-bottom: percentage($height / $width);
+    }
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Grid
+// -----------------------------------------------------------------------------
+
+/// Create the container for a grid. Will cause full-bleed for the grid unless
+/// max-width properties are added with `make-container-max-widths`
+/// @param {Map} $breakpoints [$carbon--grid-breakpoints] - A map of breakpoints where the key is the name
+/// @access private
+/// @group @carbon/grid
+@mixin carbon--make-container($breakpoints: $carbon--grid-breakpoints) {
+  margin-right: auto;
+  margin-left: auto;
+
+  @include carbon--set-largest-breakpoint();
+
+  @each $name, $value in $breakpoints {
+    $prev-breakpoint: map-get($breakpoints, carbon--breakpoint-prev($name));
+    $margin: map-get($value, margin);
+
+    @if $prev-breakpoint {
+      $prev-margin: map-get($prev-breakpoint, margin);
+      @if $prev-margin != $margin {
+        @include carbon--breakpoint($name) {
+          padding-left: #{($carbon--grid-gutter / 2) + $margin};
+          padding-right: #{($carbon--grid-gutter / 2) + $margin};
+        }
+      }
+    } @else {
+      @include carbon--breakpoint($name) {
+        padding-left: #{($carbon--grid-gutter / 2) + $margin};
+        padding-right: #{($carbon--grid-gutter / 2) + $margin};
+      }
+    }
+  }
+}
+
+/// Get the last breakpoint width and set max-width to its value
+/// @param {Map} $breakpoints [$carbon--grid-breakpoints] - A map of breakpoints where the key is the name
+/// @access private
+/// @group @carbon/grid
+@mixin carbon--set-largest-breakpoint($breakpoints: $carbon--grid-breakpoints) {
+  $largest-breakpoint: last-map-item($breakpoints);
+
+  max-width: map-get($largest-breakpoint, 'width');
+}
+
+/// Add in the max-widths for each breakpoint to the container
+/// @param {Map} $breakpoints [$carbon--grid-breakpoints] - A map of breakpoints where the key is the name
+/// @access private
+/// @group @carbon/grid
+@mixin carbon--make-container-max-widths(
+  $breakpoints: $carbon--grid-breakpoints
+) {
+  @each $name, $value in $breakpoints {
+    @include carbon--breakpoint($name) {
+      max-width: map-get($value, width);
+    }
+  }
+}
+
+/// Generate the CSS for a grid for the given breakpoints and gutters
+/// @param {Map} $breakpoints [$carbon--grid-breakpoints] - The default breakpoints
+/// @param {Number} $grid-gutter [$carbon--grid-gutter] - The default gutters
+/// @param {Number} $condensed-gutter [$carbon--grid-gutter--condensed] - The condensed mode gutter
+/// @access public
+/// @group @carbon/grid
+@mixin carbon--grid(
+  $breakpoints: $carbon--grid-breakpoints,
+  $grid-gutter: $carbon--grid-gutter,
+  $condensed-gutter: $carbon--grid-gutter--condensed
+) {
+  .#{$prefix}--grid {
+    @include carbon--make-container($breakpoints);
+  }
+
+  @include carbon--largest-breakpoint($breakpoints) {
+    .#{$prefix}--grid--full-width {
+      max-width: 100%;
+    }
+  }
+
+  .#{$prefix}--row {
+    @include carbon--make-row();
+  }
+
+  .#{$prefix}--grid--condensed .#{$prefix}--row:not(:last-of-type) {
+    margin-bottom: $condensed-gutter;
+  }
+
+  .#{$prefix}--row--condensed + .#{$prefix}--row--condensed {
+    margin-top: $condensed-gutter;
+  }
+
+  @include carbon--make-grid-columns($breakpoints, $grid-gutter);
+  @include carbon--no-gutter();
+  @include carbon--hang($grid-gutter);
+  @include carbon--aspect-ratio();
+}

package/scss/_inlined/_prefix.scss

@@ -0,0 +1,12 @@
+//
+// Copyright IBM Corp. 2018, 2018
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+/// Namespace prefix
+/// @type String
+/// @access public
+/// @group @carbon/grid
+$prefix: 'bx' !default;

package/scss/_mixins.scss

@@ -5,23 +5,24 @@
 // LICENSE file in the root directory of this source tree.
 //
 
-/// Helpers for defining columns, rows, and containers are heavily inspired by,
-/// and often derived from, bootstrap:
-/// https://github.com/twbs/bootstrap/blob/v4-dev/scss/mixins/_grid.scss
+// Helpers for defining columns, rows, and containers are heavily inspired by,
+// and often derived from, bootstrap:
+// https://github.com/twbs/bootstrap/blob/v4-dev/scss/mixins/_grid.scss
 
 @import '@carbon/layout/scss/breakpoint';
 @import 'prefix';
 
-/// -----------------------------------------------------------------------------
-/// Columns
-/// -----------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
+// Columns
+// -----------------------------------------------------------------------------
 
-/// Used to intialize the default properties for a column class, most notably
+/// Used to initialize the default properties for a column class, most notably
 /// for setting width and default gutters when a column's breakpoint has not been
 /// hit yet.
-/// @param {Number} $gutter - the default gutter used in the grid system
-/// @param {Number} $collapsed-gutter - the condensed mode gutter
+/// @param {Number} $gutter [$carbon--grid-gutter] - The gutter for the grid system
+/// @param {Number} $collapsed-gutter [$carbon--grid-gutter--condensed] - The condensed mode gutter
 /// @access private
+/// @group @carbon/grid
 @mixin carbon--make-col-ready(
   $gutter: $carbon--grid-gutter,
   $condensed-gutter: $carbon--grid-gutter--condensed
@@ -43,9 +44,10 @@
 }
 
 /// Define the width of the column for a given span and column count.
-/// @param {Number} $span - the number of columns covered
-/// @param {Number} $columns - the total number of columns available
+/// @param {Number} $span - The number of columns covered
+/// @param {Number} $columns - The total number of columns available
 /// @access private
+/// @group @carbon/grid
 @mixin carbon--make-col($span, $columns) {
   flex: 0 0 percentage($span / $columns);
   // Add a `max-width` to ensure content within each column does not blow out
@@ -55,9 +57,10 @@
 }
 
 /// Create a column offset for a given span and column count.
-/// @param {Number} $span - the number of columns the offset should cover
-/// @param {Number} $columns - the total number of columns available
+/// @param {Number} $span - The number of columns the offset should cover
+/// @param {Number} $columns - The total number of columns available
 /// @access private
+/// @group @carbon/grid
 @mixin carbon--make-col-offset($span, $columns) {
   $offset: $span / $columns;
   @if $offset == 0 {
@@ -68,9 +71,10 @@
 }
 
 /// Output the CSS required for all the columns in a given grid system.
-/// @param {Map} $breakpoints - the breakpoints in the grid system
-/// @param {Number} $gutter - the gutter for the grid system
+/// @param {Map} $breakpoints [$carbon--grid-breakpoints] - The breakpoints in the grid system
+/// @param {Number} $gutter [$carbon--grid-gutter] - The gutter for the grid system
 /// @access private
+/// @group @carbon/grid
 @mixin carbon--make-grid-columns(
   $breakpoints: $carbon--grid-breakpoints,
   $gutter: $carbon--grid-gutter
@@ -129,13 +133,14 @@
   }
 }
 
-/// -----------------------------------------------------------------------------
-/// Rows
-/// -----------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
+// Rows
+// -----------------------------------------------------------------------------
 
 /// Define the properties for a selector assigned to a row in the grid system.
-/// @param {Number} $gutter - the gutter in the grid system
+/// @param {Number} $gutter [$carbon--grid-gutter] - The gutter in the grid system
 /// @access private
+/// @group @carbon/grid
 @mixin carbon--make-row($gutter: $carbon--grid-gutter) {
   display: flex;
   flex-wrap: wrap;
@@ -143,13 +148,14 @@
   margin-left: -1 * $gutter / 2;
 }
 
-/// -----------------------------------------------------------------------------
-/// No gutter
-/// -----------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
+// No gutter
+// -----------------------------------------------------------------------------
 
-/// Add no-gutter and no-gutter--{left,right} classes to the output CSS. These
+/// Add `no-gutter` and `no-gutter--{left,right}` classes to the output CSS. These
 /// classes are useful for dropping the gutter in fluid situations.
 /// @access private
+/// @group @carbon/grid
 @mixin carbon--no-gutter {
   .#{$prefix}--no-gutter,
   .#{$prefix}--row.#{$prefix}--no-gutter [class*='#{$prefix}--col'] {
@@ -168,14 +174,15 @@
   }
 }
 
-/// -----------------------------------------------------------------------------
-/// Hang
-/// -----------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
+// Hang
+// -----------------------------------------------------------------------------
 
-/// Add hang--left and hang--right classes for a given gutter. These classes are
+/// Add `hang--left` and `hang--right` classes for a given gutter. These classes are
 /// used alongside `no-gutter--left` and `no-gutter--right` to "hang" type.
-/// @param {Number} $gutter
+/// @param {Number} $gutter [$carbon--grid-gutter] - The gutter in the grid system
 /// @access private
+/// @group @carbon/grid
 @mixin carbon--hang($gutter: $carbon--grid-gutter) {
   .#{$prefix}--hang--left {
     padding-left: ($gutter / 2);
@@ -186,18 +193,21 @@
   }
 }
 
-/// -----------------------------------------------------------------------------
-/// Aspect ratio
-/// -----------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
+// Aspect ratio
+// -----------------------------------------------------------------------------
 
 /// The aspect ratios that are used to generate corresponding aspect ratio
 /// classes in code
+/// @type List
 /// @access public
+/// @group @carbon/grid
 $carbon--aspect-ratios: ((16, 9), (2, 1), (4, 3), (1, 1));
 
 /// Output the CSS classes for generating aspect ratio classes
-/// @param {List} $aspect-ratios - a list of aspect ratios to generate
+/// @param {List} $aspect-ratios [$carbon--aspect-ratios] - A list of aspect ratios to generate
 /// @access private
+/// @group @carbon/grid
 @mixin carbon--aspect-ratio($aspect-ratios: $carbon--aspect-ratios) {
   .#{$prefix}--aspect-ratio {
     height: 0;
@@ -225,14 +235,15 @@ $carbon--aspect-ratios: ((16, 9), (2, 1), (4, 3), (1, 1));
   }
 }
 
-/// -----------------------------------------------------------------------------
-/// Grid
-/// -----------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
+// Grid
+// -----------------------------------------------------------------------------
 
 /// Create the container for a grid. Will cause full-bleed for the grid unless
 /// max-width properties are added with `make-container-max-widths`
-/// @param {Map} $breakpoints
+/// @param {Map} $breakpoints [$carbon--grid-breakpoints] - A map of breakpoints where the key is the name
 /// @access private
+/// @group @carbon/grid
 @mixin carbon--make-container($breakpoints: $carbon--grid-breakpoints) {
   margin-right: auto;
   margin-left: auto;
@@ -261,8 +272,9 @@ $carbon--aspect-ratios: ((16, 9), (2, 1), (4, 3), (1, 1));
 }
 
 /// Get the last breakpoint width and set max-width to its value
-/// @param {Map} $breakpoints
+/// @param {Map} $breakpoints [$carbon--grid-breakpoints] - A map of breakpoints where the key is the name
 /// @access private
+/// @group @carbon/grid
 @mixin carbon--set-largest-breakpoint($breakpoints: $carbon--grid-breakpoints) {
   $largest-breakpoint: last-map-item($breakpoints);
 
@@ -270,8 +282,9 @@ $carbon--aspect-ratios: ((16, 9), (2, 1), (4, 3), (1, 1));
 }
 
 /// Add in the max-widths for each breakpoint to the container
-/// @param {Map} $breakpoints
+/// @param {Map} $breakpoints [$carbon--grid-breakpoints] - A map of breakpoints where the key is the name
 /// @access private
+/// @group @carbon/grid
 @mixin carbon--make-container-max-widths(
   $breakpoints: $carbon--grid-breakpoints
 ) {
@@ -282,10 +295,12 @@ $carbon--aspect-ratios: ((16, 9), (2, 1), (4, 3), (1, 1));
   }
 }
 
-/// Generate the CSS for a grid for the given breakpoints and gutter
-/// @param {Map} $breakpoints
-/// @param {Number} $grid-gutter
+/// Generate the CSS for a grid for the given breakpoints and gutters
+/// @param {Map} $breakpoints [$carbon--grid-breakpoints] - The default breakpoints
+/// @param {Number} $grid-gutter [$carbon--grid-gutter] - The default gutters
+/// @param {Number} $condensed-gutter [$carbon--grid-gutter--condensed] - The condensed mode gutter
 /// @access public
+/// @group @carbon/grid
 @mixin carbon--grid(
   $breakpoints: $carbon--grid-breakpoints,
   $grid-gutter: $carbon--grid-gutter,

package/scss/_prefix.scss

@@ -5,4 +5,8 @@
 // LICENSE file in the root directory of this source tree.
 //
 
+/// Namespace prefix
+/// @type String
+/// @access public
+/// @group @carbon/grid
 $prefix: 'bx' !default;

package/scss/grid.scss

@@ -5,6 +5,6 @@
 // LICENSE file in the root directory of this source tree.
 //
 
-@import 'mixins';
+@import './_inlined/mixins';
 
 @include carbon--grid();

package/scss/index.scss

@@ -0,0 +1,10 @@
+//
+// Copyright IBM Corp. 2018, 2018
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+@import 'mixins';
+
+@include carbon--grid();

package/scss/vendor/@carbon/import-once/import-once.scss

@@ -0,0 +1,27 @@
+//
+// Copyright IBM Corp. 2018, 2018
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+/// Used by `exports` mixin to track which modules have been imported
+/// @type Map
+/// @access public
+/// @group @carbon/import-once
+$imported-modules: () !default;
+
+/// Module export mixin that helps making sure a module is imported once and only once
+/// @access public
+/// @param {String} $name - Name of exported module
+/// @param {Bool} $warn [false] - Warn when a module has been already imported
+/// @content Declaration blocks to be imported
+/// @group @carbon/import-once
+@mixin exports($name, $warn: false) {
+  @if (index($imported-modules, $name) == null) {
+    $imported-modules: append($imported-modules, $name) !global;
+    @content;
+  } @else if $warn == true {
+    @warn 'Module `#{$name}` has already been imported.';
+  }
+}

package/scss/vendor/@carbon/import-once/index.scss

@@ -0,0 +1,8 @@
+//
+// Copyright IBM Corp. 2018, 2018
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+@import 'import-once';