Layout::Grid - documentation (HDS-4650)

packages/components/src/styles/components/layout/grid.scss

@@ -27,7 +27,7 @@
   // Note: The gap style is defined here to avoid setting it repeatedly for the gap size variants defined below.
   // For the gap size variants, we override the value of the gap custom properties to set the desired sizes.
   // These variables can be used by the consumers as an escape hatch if they need to set non-standard gap values (but adds a bit of friction to it)
-  gap: 
+  gap:
     var(--hds-layout-grid-row-gap, 0)
     var(--hds-layout-grid-column-gap, 0);
 }
@@ -64,7 +64,7 @@
 .hds-layout-grid-item {
   --hds-layout-grid-row-span: 1;
   --hds-layout-grid-column-span: 1;
-  
+
   grid-row-start: span var(--hds-layout-grid-row-span);
   grid-column-start: span var(--hds-layout-grid-column-span);
 }

website/app/styles/app.scss

@@ -51,6 +51,7 @@
 @use "pages/components/table" as components-table;
 @use "pages/components/tabs" as components-tabs;
 @use "pages/layouts/app-frame" as layouts-app-frame;
+@use "pages/layouts/grid" as layouts-grid;
 @use "pages/whats-new/changelog" as whats-new-changelog;
 @use "pages/patterns/table-multi-select" as patterns-table-multi-select;
 @use "pages/patterns/filter-patterns" as patterns-filter-patterns;

website/app/styles/pages/layouts/grid.scss

@@ -0,0 +1,36 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+// COMPONENTS > GRID
+
+#show-content-layouts-grid {
+  .doc-grid-mobile-view {
+    position: relative;
+    max-width: 280px;
+    padding: 16px 16px 65px;
+    background: #fff;
+    border: 1px solid;
+    border-radius: 16px;
+    aspect-ratio: 9 / 16;
+
+    // home button
+    &::before {
+      position: absolute;
+      inset: auto 0 15px 0;
+      width: 40px;
+      height: 40px;
+      margin: 0 auto;
+      background: var(--token-color-palette-neutral-200);
+      border-radius: 50%;
+      content: "";
+    }
+  }
+
+  .doc-grid-plain-list {
+    margin: 0;
+    padding: 0;
+    list-style-type: none;
+  }
+}

website/docs/layouts/grid/index.md

@@ -0,0 +1,16 @@
+---
+title: Layout::Grid
+description: A component used to implement layouts based on CSS grid
+caption: A layout-only component for the organization of content based on the CSS grid model
+links:
+  github: https://github.com/hashicorp/design-system/tree/main/packages/components/src/components/hds/layout/grid
+previewImage: assets/illustrations/layouts/grid.jpg
+navigation:
+  keywords: ['layout', 'grid', 'columns', 'rows', 'spacing']
+  label: "Grid"
+---
+
+<section data-tab="Code">
+  @include "partials/code/how-to-use.md"
+  @include "partials/code/component-api.md"
+</section>

website/docs/layouts/grid/partials/code/component-api.md

@@ -0,0 +1,49 @@
+## Component API
+
+### Layout::Grid
+
+<Doc::ComponentApi as |C|>
+  <C.Property @name="tag" @type="HTMLElementTagName" @default="div">
+    A valid HTML tag name to be used to render the grid element.
+  </C.Property>
+  <C.Property @name="columnMinWidth" @type="string" @default="0px">
+    Set any valid CSS dimension as a minimum width for the grid columns. If the total width of columns in a row exceeds 100% of the parent, columns will begin to wrap to the next row as necessary to fit. The column gap size is subtracted from this minimum width.
+    <br><br>
+    <em>Note: With the default min-width of 0px, the columns will never wrap.</em>
+  </C.Property>
+  <C.Property @name="align" @type="enum" @values={{array "start" "center" "end" "stretch"}}>
+    The value of the CSS `align-items` property, which controls the alignment of the grid items on the block axis within their grid areas (for a technical explanation: [see MDN reference](https://developer.mozilla.org/en-US/docs/Web/CSS/align-items)).
+    <br/><br/>
+    <em>Note: we only expose a subset of the values allowed for this property, which cover the most common use cases.</em>
+  </C.Property>
+  <C.Property @name="gap" @type="enum" @values={{array "4" "8" "12" "16" "32" "48"}}>
+    The gap spacing between rows and columns of the grid. Specify as either a single value or array of two values for setting the row and column spacing separately.
+  </C.Property>
+  <C.Property @name="...attributes">
+    This component supports use of [`...attributes`](https://guides.emberjs.com/release/in-depth-topics/patterns-for-components/#toc_attribute-ordering).
+  </C.Property>
+</Doc::ComponentApi>
+
+### Contextual components
+
+#### [LG].Item
+
+The `Layout::Grid::Item` component, yielded as contextual component, to be used as child of the `grid` element to control its `colspan/rowspan` values (and other properties).
+
+<Doc::ComponentApi as |C|>
+  <C.Property @name="tag" @type="string" @default="div">
+    HTML tag to be used to render the grid item element.
+  </C.Property>
+  <C.Property @name="colspan" @type="number">
+    The number of columns an item should span.
+  </C.Property>
+  <C.Property @name="rowspan" @type="number">
+    The number of rows an item should span.
+  </C.Property>
+  <C.Property @name="yield">
+    Elements passed as children are yielded as inner content of the element.
+  </C.Property>
+  <C.Property @name="...attributes">
+    This component supports use of [`...attributes`](https://guides.emberjs.com/release/in-depth-topics/patterns-for-components/#toc_attribute-ordering).
+  </C.Property>
+</Doc::ComponentApi>