Add grid and column to web components - proposal

packages/web-components/package.json

@@ -70,6 +70,7 @@
     "@carbon/styles": "^1.70.0",
     "@floating-ui/dom": "^1.6.3",
     "@ibm/telemetry-js": "^1.5.0",
+    "@lit/context": "1.1.3",
     "flatpickr": "4.6.13",
     "lit": "^3.1.0",
     "lodash-es": "^4.17.21",

packages/web-components/src/components/grid/column-hang.scss

@@ -0,0 +1,15 @@
+//
+// Copyright IBM Corp. 2024, 2024
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+@use '@carbon/styles/scss/config' as *;
+@use '@carbon/styles/scss/grid';
+
+:host(#{$prefix}-column-hang) {
+  @extend .#{$prefix}--grid-column-hang;
+
+  display: block;
+}

packages/web-components/src/components/grid/column-hang.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2024, 2024
+ *
+ * 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 { LitElement, html } from 'lit';
+import { carbonElement as customElement } from '../../globals/decorators/carbon-element';
+import { prefix } from '../../globals/settings';
+import styles from './column-hang.scss?lit';
+
+@customElement(`${prefix}-column-hang`)
+class CDSColumnHang extends LitElement {
+  render() {
+    // Grid styling added to contained components, allowing CSS Grid
+    // to affect the it's own slot content.
+    return html`<div part="column-hang">
+      <slot></slot>
+    </div>`;
+  }
+
+  static styles = styles;
+}
+
+export default CDSColumnHang;

packages/web-components/src/components/grid/column.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2024, 2024
+ *
+ * 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 { LitElement } from 'lit';
+import { property } from 'lit/decorators.js';
+import { carbonElement as customElement } from '../../globals/decorators/carbon-element';
+import { prefix } from '../../globals/settings';
+
+export type ColumnSpec =
+  | Number
+  | `${number}%`
+  | `span:${number} start:${number}`
+  | `span:${number}% start:${number}`;
+
+@customElement(`${prefix}-column`)
+class CDSColumn extends LitElement {
+  /**
+   * Specify column size
+   * Keys sm, md or lg
+   *
+   * Values
+   * - N, P, { span:N start:S}
+   * N = number
+   * P = percentage
+   * S = Start column
+   */
+  @property({ reflect: true, attribute: 'sm' })
+  sm?: ColumnSpec;
+
+  @property({ reflect: true, attribute: 'md' })
+  md?: ColumnSpec;
+
+  @property({ reflect: true, attribute: 'lg' })
+  lg?: ColumnSpec;
+
+  @property({ reflect: true, attribute: 'span' })
+  span?: ColumnSpec;
+
+  createRenderRoot() {
+    return this;
+  }
+}
+
+export default CDSColumn;

packages/web-components/src/components/grid/defs.ts

@@ -0,0 +1,39 @@
+/**
+ * Button size.
+ */
+export enum GRID_ALIGNMENT {
+  /**
+   * Align to start.
+   */
+  START = 'start',
+
+  /**
+   * Align in center
+   */
+  CENTER = 'center',
+
+  /**
+   * Align to end
+   */
+  END = 'end',
+}
+
+/**
+ * Button type.
+ */
+export enum SUB_GRID_MODE {
+  /**
+   * Default sug-grid mode.
+   */
+  WIDE = 'wide',
+
+  /**
+   * Condensed sub-grid (should match hosting grid).
+   */
+  CONDENSED = 'condensed',
+
+  /**
+   * Narrow sub-grid (should match hosting grid).
+   */
+  NARROW = 'narrow',
+}

packages/web-components/src/components/grid/grid-context.ts

@@ -0,0 +1,10 @@
+import { createContext } from '@lit/context';
+
+export type GridContext = {
+  /**
+   * Specifies whether subgrid should be enabled
+   */
+  subgrid?: boolean;
+};
+
+export const gridContext = createContext<GridContext>(Symbol('GridContext'));

packages/web-components/src/components/grid/grid-story.scss

@@ -0,0 +1,105 @@
+@use '@carbon/styles/scss/grid';
+@use '@carbon/styles/scss/colors' as *;
+@use '@carbon/styles/scss/type' as *;
+@use '@carbon/styles/scss/spacing' as *;
+
+:root {
+  @include grid.css-grid();
+}
+
+.sb-css-grid-container {
+  // Gutter modes
+  .sb-grid::part(grid) {
+    background-color: $blue-20;
+    outline: 1px dashed $blue-40;
+    // row-gap: $spacing-05;
+  }
+
+  // .cds--css-grid p {
+  //   @include type-style('code-02');
+  // }
+
+  // .cds--css-grid p:first-of-type {
+  //   margin-block-start: 0;
+  // }
+
+  // Narrow
+  .sb-grid[narrow]::part(grid) {
+    background-color: #d6f9f9;
+    outline: 1px dashed $green-40;
+  }
+
+  // Condensed
+  .sb-grid[condensed]::part(grid) {
+    background-color: $purple-10;
+    outline: 1px dashed $purple-40;
+  }
+
+  .sb-sub-grid::part(grid) {
+    position: relative;
+    background: #eef4ff;
+    /* stylelint-disable-next-line color-named */
+    outline: 1px solid black;
+    padding-block: 2rem;
+  }
+
+  .sb-sub-grid::part(grid),
+  .sb-sub-grid:not(:is([condensed], [narrow]))::part(grid) {
+    --grid-mode-color: #97c1ff;
+  }
+
+  .sb-sub-grid[narrow]::part(grid) {
+    --grid-mode-color: #20d5d2;
+
+    background: #d6f9f9;
+  }
+
+  .sb-grid[condensed]::part(grid),
+  .sb-sub-grid[condensed]::part(grid) {
+    --grid-mode-color: #bb8eff;
+
+    background: $purple-10;
+  }
+
+  .sb-sub-grid[condensed]::part(grid) {
+    background: #f7f2ff;
+  }
+
+  .sb-sub-grid::part(grid)::before {
+    @include type-style('code-01');
+
+    position: absolute;
+    display: block;
+    padding: 0.125rem 0.25rem;
+    background: var(--grid-mode-color, #97c1ff);
+    color: $black;
+    content: 'subgrid';
+    inset-block-start: 0;
+    inset-inline-start: 0;
+  }
+
+  // // Column
+  .sb-column {
+    --border-color: #97c1ff;
+
+    background: $white;
+    box-shadow: 0 0 0 1px var(--border-color);
+
+    min-block-size: 80px;
+  }
+
+  .sb-sub-grid[narrow]::part(grid) .sb-column,
+  .sb-grid[narrow]::part(grid) .sb-column {
+    --border-color: #20d5d2;
+  }
+
+  .sb-sub-grid[condensed]::part(grid) .sb-column,
+  .sb-grid[condensed]::part(grid) .sb-column {
+    --border-color: #bb8eff;
+  }
+}
+
+.cds--grid-part .sb-column .sb-grid::part(grid) {
+  /* stylelint-disable-next-line color-named */
+  box-shadow: 0 0 5px black;
+}

packages/web-components/src/components/grid/grid.mdx

@@ -0,0 +1,38 @@
+import { ArgTypes, Meta, Markdown } from '@storybook/blocks';
+import { cdnJs, cdnCss } from '../../globals/internal/storybook-cdn';
+import * as GridStories from './grid.stories';
+
+<Meta of={GridStories} />
+
+# Grid
+
+> 💡 Check our
+> [Stackblitz](https://stackblitz.com/github/carbon-design-system/carbon/tree/main/packages/web-components/examples/components/grid)
+> example implementation.
+
+[![Edit carbon-web-components](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/carbon-design-system/carbon/tree/main/packages/web-components/examples/components/grid)
+
+## Getting started
+
+Here's a quick example to get you started.
+
+### JS (via import)
+
+```javascript
+import '@carbon/web-components/es/components/grid/index.js';
+```
+
+<Markdown>{`${cdnJs({ components: ['grid'] })}`}</Markdown>
+<Markdown>{`${cdnCss()}`}</Markdown>
+
+### HTML
+
+```html
+<cds-grid class="sb-grid"
+  ><cds-col>1</cds-col><cds-col>1</cds-col><cds-col>1</cds-col>
+</cds-grid>
+```
+
+## `<cds-grid>` attributes, properties and events
+
+<ArgTypes of="cds-grid" />

packages/web-components/src/components/grid/grid.scss

@@ -0,0 +1,60 @@
+//
+// Copyright IBM Corp. 2024, 2024
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+@use '@carbon/styles/scss/config' as *;
+// @use '@carbon/styles/scss/grid/css-grid' as *;
+@use '@carbon/styles/scss/grid';
+@use './mixin' as *;
+
+$css-grid: #{$prefix}--css-grid;
+:host(#{$prefix}-grid) [grid] {
+  @extend .#{$css-grid};
+
+  box-sizing: border-box; /* prevent padding leaking out */
+}
+
+// :host(#{$prefix}-grid[align='start']) [grid] {
+//   @extend .#{$css-grid}--start;
+// }
+
+// :host(#{$prefix}-grid[align='end']) [grid] {
+//   @extend .#{$css-grid}--end;
+// }
+
+:host(#{$prefix}-grid[condensed]) [grid] {
+  @extend .#{$css-grid}--condensed;
+}
+
+:host(#{$prefix}-grid[narrow]) [grid] {
+  @extend .#{$css-grid}--narrow;
+}
+
+:host(#{$prefix}-grid[full-width]) [grid] {
+  @extend .#{$css-grid}--full-width;
+}
+
+/* sub grid styles */
+$sub-grid: #{$prefix}--subgrid;
+:host(#{$prefix}-grid) [subgrid] {
+  @extend .#{$sub-grid};
+
+  box-sizing: border-box; /* prevent padding leaking out */
+}
+
+:host(#{$prefix}-grid) [subgrid][mode='wide'] {
+  @extend .#{$sub-grid}--wide;
+}
+
+:host(#{$prefix}-grid) [subgrid][mode='condensed'] {
+  @extend .#{$sub-grid}--condensed;
+}
+
+:host(#{$prefix}-grid) [subgrid][mode='narrow'] {
+  @extend .#{$sub-grid}--narrow;
+}
+
+// Column styles
+@include grid-columns(#{$prefix}-grid);