feat(grid): add narrow grid support to CSS Grid (#10934)

* chore: check-in work

* refactor(grid): update grid config and add narrow mode

* refactor(grid): update grid, add docs and architecture

* feat(styles): update implementation to support flexbox and CSS Grid

* feat(carbon-react): add support for grid entrypoint

* fix(grid): update flex grid mixin

* feat(react): add unstable_ColumnHang

* test(styles): update config snapshot

* refactor(react): update CSSGrid implementation and stories

* test(react): update vrt for grid

* docs(grid): update grid docs and comments

Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>

.prettierignore

@@ -46,6 +46,7 @@ packages/icons-react/next/**
 # Examples
 packages/**/examples/**
 !packages/themes/examples/**
+!packages/grid/examples/css-grid/**
 
 # Yarn
 **/.yarn/**

packages/carbon-react/.storybook/styles.scss

@@ -6,6 +6,7 @@
 //
 
 @use '../index.scss' as styles;
+@use '../scss/grid/flexbox';
 
 :root {
   @include styles.theme(styles.$white);

packages/carbon-react/__tests__/index-test.js

@@ -32,6 +32,7 @@ describe('Carbon Components React', () => {
         "CodeSnippet",
         "CodeSnippetSkeleton",
         "Column",
+        "ColumnHang",
         "ComboBox",
         "ComposedModal",
         "Content",

packages/carbon-react/scss/components/aspect-ratio/_index.scss

@@ -0,0 +1,9 @@
+// Code generated by @carbon/react. DO NOT EDIT.
+//
+// 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.
+//
+
+@forward '@carbon/styles/scss/components/aspect-ratio';

packages/carbon-react/scss/grid/_config.scss

@@ -0,0 +1,9 @@
+// Code generated by @carbon/react. DO NOT EDIT.
+//
+// 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.
+//
+
+@forward '@carbon/styles/scss/grid/config';

packages/carbon-react/scss/grid/_flexbox.scss

@@ -0,0 +1,9 @@
+// Code generated by @carbon/react. DO NOT EDIT.
+//
+// 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.
+//
+
+@forward '@carbon/styles/scss/grid/flexbox';

packages/carbon-react/scss/utilities/_convert.scss

@@ -0,0 +1,9 @@
+// Code generated by @carbon/react. DO NOT EDIT.
+//
+// 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.
+//
+
+@forward '@carbon/styles/scss/utilities/convert';

packages/carbon-react/scss/utilities/_z-index.scss

@@ -0,0 +1,9 @@
+// Code generated by @carbon/react. DO NOT EDIT.
+//
+// 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.
+//
+
+@forward '@carbon/styles/scss/utilities/z-index';

packages/carbon-react/src/index.js

@@ -187,6 +187,7 @@ export {
   SideNavSwitcher,
   Grid,
   Column,
+  unstable_ColumnHang as ColumnHang,
   unstable_FlexGrid as FlexGrid,
   unstable_useContextMenu,
   unstable_FeatureFlags as FeatureFlags,

packages/carbon-react/tasks/build-styles.js

@@ -32,8 +32,22 @@ async function build() {
         filepath: '_feature-flags.scss',
       },
       {
-        type: 'file',
-        filepath: '_grid.scss',
+        type: 'directory',
+        filepath: 'grid',
+        files: [
+          {
+            type: 'file',
+            filepath: '_config.scss',
+          },
+          {
+            type: 'file',
+            filepath: '_flexbox.scss',
+          },
+          {
+            type: 'file',
+            filepath: '_index.scss',
+          },
+        ],
       },
       {
         type: 'file',

packages/grid/ARCHITECTURE.md

@@ -0,0 +1,53 @@
+# Architecture
+
+> Reference document for the approach of buildling and testing this package.
+
+## CSS Grid
+
+The CSS Grid implementation of the IDL Grid is implemented using `display: grid`
+but unfortunately is unable to use `grid-gap`, `column-gap`, etc for gutters
+because of several requirements we have from the various grid modes we need to
+implement.
+
+In general, our "wide" grid is a grid where each column as 16px of margin on
+either side. Our narrow grid, however, will completely drop the leading 16px of
+margin. The condensed grid will only have 0.5px of margin on either side of the
+column.
+
+Due to this asymmetry, we need to be able to control the leading and trailing
+gutter of each cell (both sides are included for right-to-left layouts). We also
+need to offer utilities for hanging content "on the grid" or "on a column" so
+that elements like text can appropriately align even if the gutter for the cell
+is missing.
+
+### Testing
+
+Our CSS Grid implementation has a wide variety of cases to test for, many of
+which are in our css-grid preview but should be tested more explicitly in the
+future. These ad-hoc tests include verifying:
+
+- The grid definition itself in `$grid-breakpoints` matches the IDL spec
+- The grid has the correct number of columns per brekapoint
+- The margin of the grid correctly changes between breakpoints
+- The various grid modes work as intended, including
+  - Wide
+  - Narrow
+  - Condensed
+- Column span classes have:
+  - Classes that apply span unconditionally, regardless of breakpoint
+  - Classes that apply conditionally depending on breakpoint
+  - Classes that have a span of 0 correctly hide content
+- Column offset classes have:
+  - Classes that apply span unconditionally, regardless of breakpoint
+  - Classes that apply conditionally depending on breakpoint
+- Percent-span column classes have:
+  - Classes that apply unconditionally
+  - Classes that apply conditionally depending on breakpoint
+- The different grid modes interact cleanly in subgrid and support arbitrary
+  levels of nesting
+- The column hang helper class correctly determines the right amount of margin
+  to add in such that text aligns to the grid
+- The layouts align correctly in a right-to-left orientation
+- The "full width" grid allows the grid to span beyond the max-width of the
+  "max" breakpoint
+- The grid classes can be used with custom components to align them to the grid

packages/grid/__tests__/__snapshots__/scss-test.js.snap

@@ -5,7 +5,7 @@ Array [
   "prefix",
   "flex-grid-columns",
   "grid-gutter",
-  "grid-gutter--condensed",
+  "grid-gutter-condensed",
   "grid-breakpoints",
 ]
 `;

packages/grid/__tests__/scss-test.js

@@ -15,20 +15,21 @@ const { render } = SassRenderer.create(__dirname);
 
 describe('@carbon/grid', () => {
   test('Public API', async () => {
-    const { get } = await render(`
+    const { unwrap } = await render(`
       @use 'sass:meta';
       @use '../index.scss' as grid;
 
       $_: get('variables', meta.module-variables('grid'));
       $_: get('mixins', (
-        grid: meta.mixin-exists('css-grid', 'grid'),
+        css-grid: meta.mixin-exists('css-grid', 'grid'),
+        flex-grid: meta.mixin-exists('flex-grid', 'grid'),
       ));
     `);
 
-    const variables = get('variables');
-    expect(Object.keys(variables.value)).toMatchSnapshot();
-
-    const mixins = get('mixins');
-    expect(mixins.value.grid).toBe(true);
+    expect(Object.keys(unwrap('variables'))).toMatchSnapshot();
+    expect(unwrap('mixins')).toEqual({
+      'css-grid': true,
+      'flex-grid': true,
+    });
   });
 });

packages/grid/docs/sass.md

@@ -0,0 +1,74 @@
+# Sass
+
+> Sass documentation for `@carbon/grid`
+
+## Usage
+
+The `@carbon/grid` package ships CSS Grid and Flexbox-based grids, along with
+grid utilities, for the IBM Design Language in Sass. You can import and use the
+grid by writing the following:
+
+```scss
+@use '@carbon/grid';
+
+// Emit all the CSS for the CSS Grid
+@include grid.css-grid();
+```
+
+With the CSS for CSS Grid, you can create a grid in your HTML by writing the
+following:
+
+```html
+<div class="cds--css-grid">
+  <div class="cds--css-grid-column cds--col-span-4">Span 4 columns</div>
+  <div class="cds--css-grid-column cds--col-span-2">Span 2 columns</div>
+</div>
+```
+
+There is also support for responsive classes that are included with the
+`css-grid` mixin. These responsive classes allow you to do the following for
+each breakpoint:
+
+- Change how many columns your content spans based on content
+- Hide or show content depending on the breakpoint
+- Change where your columns start or end
+
+For a full list of classes available, checkout the [classes](#classes) section
+below.
+
+### Classes
+
+| Name                                       | Description                            |
+| :----------------------------------------- | :------------------------------------- |
+| `cds--css-grid`                            | Grid class name                        |
+| `cds--css-grid-column`                     | Column class name                      |
+| `cds--col-span-{0,16}`                     | Unconditional column span              |
+| `cds--{sm,md,lg,xlg,max}:col-span-{0,16}`  | Responsive column span                 |
+| `cds--col-span-{25,50,75,100}`             | Percent column span across breakpoints |
+| `cds--col-start-{1,16}`                    | Unconditional column start             |
+| `cds--{sm,md,lg,xlg,max}:col-start-{1,16}` | Responsive column start                |
+| `cds--col-end-{2,17}`                      | Unconditional column end               |
+| `cds--{sm,md,lg,xlg,max}:col-end-{2,17}`   | Responsive column end                  |
+| `cds--grid-column-hang`                    | Hang content on a grid column          |
+| `cds--subgrid`                             | Specify an element as a subgrid        |
+| `cds--subgrid--{wide,narrow,condensed}`    | Specify the grid mode of subgrid       |
+
+## API
+
+| Name                     | Description                                                                         | Type        | Default       |
+| :----------------------- | :---------------------------------------------------------------------------------- | :---------- | :------------ |
+| `css-grid`               | Generate the CSS for using the CSS Grid                                             | `@mixin`    |               |
+| `$prefix`                | Specify the prefix used for CSS selectors                                           | `String`    | `'cds'`       |
+| `$flex-grid-columns`     | Specify the number of columns for the flex grid                                     | `Number`    | `16`          |
+| `$grid-gutter`           | Specify the gutter of the grid                                                      | `Number`    | `32px (2rem)` |
+| `$grid-gutter-condensed` | Specify the gutter of the condensed grid                                            | `Number`    | `1px`         |
+| `$grid-breakpoints`      | Specify the breakpoints for the grid                                                | `Map`       |               |
+| `breakpoint-next`        | Get the value of the next breakpoint                                                | `@function` |               |
+| `breakpoint-prev`        | Get the value of the previous breakpoint                                            | `@function` |               |
+| `is-smallest-breakpoint` | Check to see if the given breakpoint is the smallest breakpoint                     | `@function` |               |
+| `is-largest-breakpoint`  | Check to see if the given breakpoint is the largest breakpoint                      | `@function` |               |
+| `breakpoint-up`          | Generate a media query from the width of the given breakpoint to infinity           | `@mixin`    |               |
+| `breakpoint-down`        | Generate a media query that applies below the maximum width of the given breakpoint | `@mixin`    |               |
+| `breakpoint-between`     | Generate a media query for the range between the lower and upper breakpoints        | `@mixin`    |               |
+| `largest-breakpoint`     | Generate a media query for the largest breakpoint                                   | `@mixin`    |               |
+| `breakpoint`             | Generate a media query for a given breakpoint, alias of `breakpoint-up`             | `@mixin`    |               |