docs(grid): update elements example, grid pkg readme (#9339)

* docs(grid): update elements example, grid pkg readme

* chore: remove wip work no longer needed

* fix(grid): update css-grid elements example lockfile

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

packages/grid/README.md

@@ -70,6 +70,71 @@ 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.
 
+## Experimental CSS Grid Usage
+
+_More examples and documentation can be found on this
+[live demo website](https://carbon-elements.netlify.com/grid/examples/css-grid/)._
+
+There is an experimental implementation of the Grid built using CSS Grid instead
+of flexbox. This implementation ships with a 16 column grid.
+
+`@carbon/grid` has two primitive class types to use in order to structure your
+application. They include:
+
+- `.#{$prefix}--css-grid` - defines the overall grid context and sets some
+  useful attributes like width and margin
+- `.#{$prefix}--col-span-*` - 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 we could use the following markup:
+
+```html
+<div class="cds--css-grid">
+  <div class="cds--col-span-4"></div>
+  <div class="cds--col-span-4"></div>
+  <div class="cds--col-span-4"></div>
+  <div class="cds--col-span-4"></div>
+</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.
+
+By default, this uses the breakpoints defined in `@carbon/grid`. 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, if we wanted four columns to change widths or be hidden
+at various breakpoints we could use the following markup:
+
+```html
+<div class="cds--css-grid">
+  <div class="cds--sm:col-span-2 cds--md:col-span-4 cds--lg:col-span-6">
+    <p>Small: Span 2 of 4</p>
+    <p>Medium: Span 4 of 8</p>
+    <p>Large: Span 6 of 16</p>
+  </div>
+  <div class="cds--sm:col-span-2 cds--md:col-span-2 cds--lg:col-span-3">
+    <p>Small: Span 2 of 4</p>
+    <p>Medium: Span 2 of 8</p>
+    <p>Large: Span 3 of 16</p>
+  </div>
+  <div class="cds--sm:col-span-0 cds--md:col-span-2 cds--lg:col-span-3">
+    <p>Small: Span 0 of 4</p>
+    <p>Medium: Span 2 of 8</p>
+    <p>Large: Span 3 of 16</p>
+  </div>
+  <div class="cds--sm:col-span-0 cds--md:col-span-0 cds--lg:col-span-4">
+    <p>Small: Span 0 of 4</p>
+    <p>Medium: Span 0 of 8</p>
+    <p>Large: Span 4 of 16</p>
+  </div>
+</div>
+```
+
+The `.cds--sm:col-span-2` class names tells us that this `<div>` should only
+span two columns at our `sm` breakpoint.
+
 ## 📚 Examples
 
 If you're looking for more examples on how to use `@carbon/grid`, we have some

packages/grid/examples/css-grid/package.json

@@ -9,7 +9,6 @@
     "@carbon/colors": "link:../../../colors",
     "@carbon/grid": "link:../../",
     "carbon-components": "link:../../../components",
-    "carbon-components-react": "link:../../../react",
     "next": "^10.0.7",
     "react": "^17.0.1",
     "react-dom": "^17.0.1",

packages/grid/examples/css-grid/src/pages/index.js

@@ -1,172 +1,177 @@
 export default function IndexPage() {
   return (
     <>
-    <h1>CSS Grid Demo</h1>
+      <h1>Experimental CSS Grid</h1>
       <section>
-        <h2>CSS Grid</h2>
-        <article className="example">
-          <div className="bx--css-grid">
-            <div className="content">
-              Span 1
-            </div>
-            <div className="content bx--col-span-2">
-              Span 2
-            </div>
-            <div className="content">
-              Span 1
-            </div>
-            <div className="content">
-              Span 1
-            </div>
-          </div>
-        </article>
+        <h2>Wide</h2>
+        <div class="bx--css-grid">
+          <div class="bx--sm:col-span-4"></div>
+          <div class="bx--sm:col-span-4"></div>
+          <div class="bx--sm:col-span-4"></div>
+          <div class="bx--sm:col-span-4"></div>
+        </div>
       </section>
+
       <section>
-        <h2>Responsive</h2>
+        <h2>Narrow</h2>
+        <div class="bx--css-grid bx--css-grid--narrow">
+          <div class="bx--sm:col-span-4"></div>
+          <div class="bx--sm:col-span-4"></div>
+          <div class="bx--sm:col-span-4"></div>
+          <div class="bx--sm:col-span-4"></div>
+        </div>
       </section>
-      <article className="example">
-        <div className="bx--css-grid">
-          <div className="content bx--col-span-1 bx--md:col-span-2 bx--lg:col-span-4">25%</div>
-          <div className="content bx--col-span-1 bx--md:col-span-2 bx--lg:col-span-4">25%</div>
-          <div className="content bx--col-span-1 bx--md:col-span-2 bx--lg:col-span-4">25%</div>
-          <div className="content bx--col-span-1 bx--md:col-span-2 bx--lg:col-span-4">25%</div>
-          <div className="content bx--col-span-4 bx--md:col-span-6 bx--lg:col-span-12 bx--xlg:col-span-10 bx--max:col-span-8">
-            Responsive
-          </div>
+
+      <section>
+        <h2>Condensed</h2>
+        <div class="bx--css-grid bx--css-grid--condensed">
+          <div class="bx--sm:col-span-4"></div>
+          <div class="bx--sm:col-span-4"></div>
+          <div class="bx--sm:col-span-4"></div>
+          <div class="bx--sm:col-span-4"></div>
         </div>
-      </article>
+      </section>
+
       <section>
-        <h2>Offset</h2>
-        <article className="example">
-          <div className="bx--css-grid">
-            <div className="content bx--col-start-8">Start 8</div>
-            <div className="content bx--col-start-7 bx--col-span-2">Start 7</div>
-            <div className="content bx--col-start-6 bx--col-span-3">Start 6</div>
-            <div className="content bx--col-start-5 bx--col-span-4">Start 5</div>
-            <div className="content bx--col-start-4 bx--col-span-5">Start 4</div>
-            <div className="content bx--col-start-3 bx--col-span-6">Start 3</div>
-            <div className="content bx--col-start-2 bx--col-span-7">Start 2</div>
-            <div className="content bx--col-start-1 bx--col-span-8">Start 1</div>
-            <div className="content bx--col-start-4 bx--col-end-7">
-              Start 4, End 7
-            </div>
-          </div>
-        </article>
+        <h2>Full Width</h2>
+        <div class="bx--css-grid bx--css-grid--full-width">
+          <div class="bx--sm:col-span-4"></div>
+          <div class="bx--sm:col-span-4"></div>
+          <div class="bx--sm:col-span-4"></div>
+          <div class="bx--sm:col-span-4"></div>
+        </div>
       </section>
+
       <section>
-        <h2>Gap (condensed, narrow, no gutters)</h2>
-        <article className="example">
-          <div className="bx--css-grid bx--css-grid--condensed">
-            <div className="content">
-              Span 1
-            </div>
-            <div className="content bx--col-span-2">
-              Span 2
-            </div>
-            <div className="content">
-              Span 1
-            </div>
-            <div className="content">
-              Span 1
-            </div>
+        <h2>Responsive</h2>
+        <div class="bx--css-grid">
+          <div class="bx--sm:col-span-2 bx--md:col-span-4 bx--lg:col-span-6">
+            <p>Small: Span 2 of 4</p>
+            <p>Medium: Span 4 of 8</p>
+            <p>Large: Span 6 of 16</p>
           </div>
-        </article>
-        <article className="example">
-          <div className="bx--css-grid bx--css-grid--narrow">
-            <div className="content bx--col-span-1">
-              Span 1
-            </div>
-            <div className="content bx--col-span-2">
-              Span 2
-            </div>
-            <div className="content bx--col-span-1">
-              Span 1
-            </div>
-            <div className="content bx--col-span-1">
-              Span 1
-            </div>
+          <div class="bx--sm:col-span-2 bx--md:col-span-2 bx--lg:col-span-3">
+            <p>Small: Span 2 of 4</p>
+            <p>Medium: Span 2 of 8</p>
+            <p>Large: Span 3 of 16</p>
           </div>
-        </article>
-        <article className="example">
-          <div className="bx--css-grid bx--css-grid--no-gutter">
-            <div className="content">
-              Span 1
-            </div>
-            <div className="content bx--col-span-2">
-              Span 2
-            </div>
-            <div className="content">
-              Span 1
-            </div>
-            <div className="content">
-              Span 1
-            </div>
+          <div class="bx--sm:col-span-0 bx--md:col-span-2 bx--lg:col-span-3">
+            <p>Small: Span 0 of 4</p>
+            <p>Medium: Span 2 of 8</p>
+            <p>Large: Span 3 of 16</p>
           </div>
-        </article>
-      </section>
-      <section>
-        <h2>Gutter helpers</h2>
-        <article className="example">
-          <div className="bx--css-grid bx--css-grid--no-gutter">
-            <div className="content bx--gutter-start">
-              Span 1
-            </div>
-            <div className="content bx--col-span-2 bx--gutter-end">
-              Span 2
-            </div>
-            <div className="content bx--gutter-start">
-              Span 1
-            </div>
-            <div className="content bx--gutter-end">
-              Span 1
-            </div>
+          <div class="bx--sm:col-span-0 bx--md:col-span-0 bx--lg:col-span-4">
+            <p>Small: Span 0 of 4</p>
+            <p>Medium: Span 0 of 8</p>
+            <p>Large: Span 4 of 16</p>
           </div>
-        </article>
+        </div>
       </section>
+
       <section>
         <h2>Subgrid</h2>
-        <div className="example">
-          <div className="bx--css-grid">
-            <div className="bx--col-span-75 bx--subgrid">
-            </div>
-            <div className="content bx--col-span-25">
-              25%
+        <div class="bx--css-grid">
+          <div class="bx--sm:col-span-2 bx--md:col-span-4 bx--lg:col-span-3">
+            <p>Small: Span 2 of 4</p>
+            <p>Medium: Span 4 of 8</p>
+            <p>Large: Span 3 of 16</p>
+          </div>
+          <div class="bx--sm:col-span-2 bx--md:col-span-4 bx--lg:col-span-10">
+            <p>Small: Span 2 of 4</p>
+            <p>Medium: Span 4 of 8</p>
+            <p>Large: Span 10 of 16</p>
+            <div class="example bx--subgrid">
+              <div class="bx--sm:col-span-1 bx--md:col-span-1 bx--lg:col-span-2">
+                <p>sm=1</p> <p>md=1</p> <p>lg=2</p>
+              </div>
+              <div class="bx--sm:col-span-1 bx--md:col-span-1 bx--lg:col-span-2">
+                <p>sm=1</p> <p>md=1</p> <p>lg=2</p>
+              </div>
+              <div class="bx--sm:col-span-0 bx--md:col-span-1 bx--lg:col-span-1">
+                <p>sm=0</p> <p>md=1</p> <p>lg=1</p>
+              </div>
+              <div class="bx--sm:col-span-0 bx--md:col-span-1 bx--lg:col-span-1">
+                <p>sm=0</p> <p>md=1</p> <p>lg=1</p>
+              </div>
+              <div class="bx--sm:col-span-0 bx--md:col-span-0 bx--lg:col-span-1">
+                <p>sm=0</p> <p>md=0</p> <p>lg=1</p>
+              </div>
+              <div class="bx--sm:col-span-0 bx--md:col-span-0 bx--lg:col-span-1">
+                <p>sm=0</p> <p>md=0</p> <p>lg=1</p>
+              </div>
+              <div class="bx--sm:col-span-0 bx--md:col-span-0 bx--lg:col-span-1">
+                <p>sm=0</p> <p>md=0</p> <p>lg=1</p>
+              </div>
+              <div class="bx--sm:col-span-0 bx--md:col-span-0 bx--lg:col-span-1">
+                <p>sm=0</p> <p>md=0</p> <p>lg=1</p>
+              </div>
             </div>
           </div>
+          <div class="bx--sm:col-span-0 bx--md:col-span-0 bx--lg:col-span-3">
+            <p>Small: Span 0 of 4</p>
+            <p>Medium: Span 0 of 8</p>
+            <p>Large: Span 3 of 16</p>
+          </div>
         </div>
       </section>
+
       <section>
-        <h2>Relative</h2>
-        <div className="example">
-          <div className="bx--css-grid">
-            <div className="bx--col-span-100">
-              <div className="content">100%</div>
-            </div>
-            <div className="bx--col-span-75">
-              <div className="content">75%</div>
-            </div>
-            <div className="bx--col-span-25">
-              <div className="content">25%</div>
+        <h2>Mixed Grid Modes</h2>
+        <div class="bx--css-grid">
+          <div class="bx--sm:col-span-1 bx--md:col-span-2 bx--lg:col-span-4">
+            <div class="bx--css-grid--narrow bx--subgrid">
+              <div class="bx--sm:col-span-1 bx--md:col-span-2 bx--lg:col-span-4">
+                <p>narrow</p>
+              </div>
             </div>
           </div>
-          <div className="bx--css-grid">
-            <div className="bx--col-span-50">
-              <div className="content">50%</div>
-            </div>
-            <div className="bx--col-span-50">
-              <div className="content">50%</div>
+          <div class="bx--sm:col-span-3 bx--md:col-span-6 bx--lg:col-span-12">
+            <div class="bx--css-grid--condensed bx--subgrid">
+              <div class="bx--sm:col-span-3 bx--md:col-span-6 bx--lg:col-span-12">
+                <p>condensed</p>
+              </div>
             </div>
           </div>
-          <div className="bx--css-grid">
-            <div className="bx--col-span-25">
-              <div className="content">25%</div>
+          <div class="bx--sm:col-span-1 bx--md:col-span-2 bx--lg:col-span-4">
+            <div class="bx--css-grid--condensed bx--subgrid">
+              <div class="bx--sm:col-span-1 bx--md:col-span-2 bx--lg:col-span-4">
+                <p>condensed</p>
+              </div>
             </div>
-            <div className="bx--col-span-75">
-              <div className="content">75%</div>
+          </div>
+          <div class="bx--sm:col-span-3 bx--md:col-span-6 bx--lg:col-span-12">
+            <div class="bx--css-grid--narrow bx--subgrid">
+              <div class="bx--sm:col-span-3 bx--md:col-span-6 bx--lg:col-span-12">
+                <p>narrow</p>
+              </div>
             </div>
           </div>
         </div>
       </section>
+
+      <section>
+        <h2>Offset</h2>
+        <div class="bx--css-grid">
+          <div class="bx--sm:col-start-4 bx--sm:col-end-5 bx--md:col-start-7 bx--md:col-end-9 bx--lg:col-start-13 bx--lg:col-end-17"></div>
+          <div class="bx--sm:col-start-3 bx--sm:col-end-5 bx--md:col-start-5 bx--md:col-end-9 bx--lg:col-start-9 bx--lg:col-end-17"></div>
+          <div class="bx--sm:col-start-2 bx--sm:col-end-5 bx--md:col-start-3 bx--md:col-end-9 bx--lg:col-start-5 bx--lg:col-end-17"></div>
+          <div class="bx--sm:col-span-4 bx--md:col-span-8 bx--lg:col-span-16"></div>
+        </div>
+      </section>
+
+      <section>
+        <h2>Auto Columns</h2>
+        <div class="bx--css-grid">
+          <div class="bx--col"></div>
+          <div class="bx--col"></div>
+          <div class="bx--col"></div>
+          <div class="bx--col"></div>
+          <div class="bx--col"></div>
+          <div class="bx--col"></div>
+          <div class="bx--col"></div>
+          <div class="bx--col"></div>
+        </div>
+      </section>
     </>
   );
 }