@carbon/grid 10.1.1 → 10.3.0

package/CHANGELOG.md

@@ -3,6 +3,29 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 10.3.0 (2019-06-05)
+
+
+
+# 10.3.0-rc.2 (2019-06-03)
+
+
+
+# 10.3.0-rc.1 (2019-05-29)
+
+
+### Features
+
+* **grid:** add 1:2 aspect ratio class ([#2858](https://github.com/IBM/carbon-elements/tree/master/packages/grid/issues/2858)) ([43c9446](https://github.com/IBM/carbon-elements/tree/master/packages/grid/commit/43c9446))
+
+
+
+# 10.2.0-bridge (2019-05-13)
+
+
+
+
+
 ## [10.1.1](https://github.com/IBM/carbon-elements/tree/master/packages/grid/compare/v10.1.0...v10.1.1) (2019-04-13)
 
 **Note:** Version bump only for package @carbon/grid

package/LICENSE

@@ -178,7 +178,7 @@
    APPENDIX: How to apply the Apache License to your work.
 
       To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
+      boilerplate notice, with the fields enclosed by brackets "{}"
       replaced with your own identifying information. (Don't include
       the brackets!)  The text should be enclosed in the appropriate
       comment syntax for the file format. We also recommend that a
@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2018 IBM Corp.
+   Copyright 2015 IBM Corp.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -4,15 +4,15 @@
 
 ## Getting started
 
-To install `@carbon/grid` in your project, you will need to run the
-following command using [npm](https://www.npmjs.com/):
+To install `@carbon/grid` in your project, you will need to run the following
+command using [npm](https://www.npmjs.com/):
 
 ```bash
 npm install -S @carbon/grid
 ```
 
-If you prefer [Yarn](https://yarnpkg.com/en/), use the following
-command instead:
+If you prefer [Yarn](https://yarnpkg.com/en/), use the following command
+instead:
 
 ```bash
 yarn add @carbon/grid
@@ -20,17 +20,17 @@ yarn add @carbon/grid
 
 ## Usage
 
-`@carbon/grid` has three primitive class types to use in order to
-structure your application. They include:
+`@carbon/grid` has three primitive class types to use in order to structure your
+application. They include:
 
-- `bx--grid`, defines the overall grid context and sets some useful
-  attributes like width and margin
+- `bx--grid`, defines the overall grid context and sets some useful attributes
+  like width and margin
 - `bx--row`, defines a row of items in a grid
 - `bx--col`, used to define individual columns
 
-You can use a combination of these classes to build a layout. For
-example, if we wanted a 4 column layout for a small breakpoint we
-could use the following markup:
+You can use a combination of these classes to build a layout. For example, if we
+wanted a 4 column layout for a small breakpoint we could use the following
+markup:
 
 ```html
 <div class="bx--grid">
@@ -43,14 +43,14 @@ could use the following markup:
 </div>
 ```
 
-While this layout can work for some grid usage scenarios, we probably
-will want more control over how many columns our layout will span at
-each given breakpoint.
+While this layout can work for some grid usage scenarios, we probably will want
+more control over how many columns our layout will span at each given
+breakpoint.
 
-By default, `@carbon/grid` uses the breakpoints defined in `@carbon/layout`. There are five breakpoints: `sm`, `md`, `lg`, `xlg`,
-and `max`. You can use each one in combination with a column to
-specify the number of columns to span at a given breakpoint. For
-example, we could rewrite the above example to be:
+By default, `@carbon/grid` uses the breakpoints defined in `@carbon/layout`.
+There are five breakpoints: `sm`, `md`, `lg`, `xlg`, and `max`. You can use each
+one in combination with a column to specify the number of columns to span at a
+given breakpoint. For example, we could rewrite the above example to be:
 
 ```html
 <div class="bx--grid">
@@ -63,10 +63,9 @@ example, we could rewrite the above example to be:
 </div>
 ```
 
-The `.bx--col-sm-1` class names tells us that this `<div>` should only
-span one column at our `sm` breakpoint. By default, as we scale beyond
-the breakpoint the layout will still take up a percentage of the
-overall width.
+The `.bx--col-sm-1` class names tells us that this `<div>` should only span one
+column at our `sm` breakpoint. By default, as we scale beyond the breakpoint the
+layout will still take up a percentage of the overall width.
 
 ## 📖 API Documentation
 
@@ -76,10 +75,9 @@ If you're looking for `@carbon/grid` API documentation, check out:
 
 ## 🙌 Contributing
 
-We're always looking for contributors to help us fix bugs, build new
-features, or help us improve the project documentation. If you're
-interested, definitely check out our [Contributing Guide](/.github/CONTRIBUTING.md)
-! 👀
+We're always looking for contributors to help us fix bugs, build new features,
+or help us improve the project documentation. If you're interested, definitely
+check out our [Contributing Guide](/.github/CONTRIBUTING.md) ! 👀
 
 ## 📝 License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@carbon/grid",
   "description": "Grid for digital and software products using the Carbon Design System",
-  "version": "10.1.1",
+  "version": "10.3.0",
   "license": "Apache-2.0",
   "repository": "https://github.com/IBM/carbon-elements/tree/master/packages/grid",
   "bugs": "https://github.com/IBM/carbon-elements/issues",
@@ -21,11 +21,16 @@
     "access": "public"
   },
   "scripts": {
-    "build": "bundler sassdoc 'scss'"
+    "build": "yarn clean && bundler sassdoc 'scss/*.scss' && bundler inline && bundler check 'scss/*.scss'",
+    "clean": "rimraf scss/_inlined scss/vendor"
   },
   "dependencies": {
-    "@carbon/import-once": "10.1.0",
-    "@carbon/layout": "10.1.1"
+    "@carbon/import-once": "10.2.0",
+    "@carbon/layout": "10.2.0"
+  },
+  "devDependencies": {
+    "@carbon/bundler": "10.2.0",
+    "rimraf": "^2.6.3"
   },
   "eyeglass": {
     "exports": false,
@@ -33,5 +38,5 @@
     "sassDir": "scss",
     "needs": "^1.3.0"
   },
-  "gitHead": "0931cfcf4a7636d6e3f5aff3ab8d7d7f2d4ecb99"
+  "gitHead": "e1ff2abd982e22a1d53eeb4c95b1caa00d802595"
 }

package/scss/_inlined/12.scss

@@ -0,0 +1,41 @@
+//
+// 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';
+
+/// Overrides `$carbon--grid-breakpoints` to use a 12 column grid instead of the default 16
+/// @type Map
+/// @access public
+/// @group @carbon/grid
+$carbon--12-column-grid: map-merge(
+  $carbon--grid-breakpoints,
+  (
+    lg:
+      map-merge(
+        map-get($carbon--grid-breakpoints, lg),
+        (
+          columns: 12,
+        )
+      ),
+    xlg:
+      map-merge(
+        map-get($carbon--grid-breakpoints, xlg),
+        (
+          columns: 12,
+        )
+      ),
+    max:
+      map-merge(
+        map-get($carbon--grid-breakpoints, max),
+        (
+          columns: 12,
+        )
+      ),
+  )
+);
+
+@include carbon--grid($breakpoints: $carbon--12-column-grid);

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), (1, 2));
+
+/// 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

@@ -202,7 +202,7 @@
 /// @type List
 /// @access public
 /// @group @carbon/grid
-$carbon--aspect-ratios: ((16, 9), (2, 1), (4, 3), (1, 1));
+$carbon--aspect-ratios: ((16, 9), (2, 1), (4, 3), (1, 1), (1, 2));
 
 /// Output the CSS classes for generating aspect ratio classes
 /// @param {List} $aspect-ratios [$carbon--aspect-ratios] - A list of aspect ratios to generate

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';