@boostdev/design-system-components 2.1.0 → 2.2.0

package/src/components/layout/Grid/Grid.mdx

@@ -0,0 +1,244 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Grid.stories';
+
+<Meta of={Stories} />
+
+# Grid
+
+A responsive layout primitive built on the design-system-foundation grid tokens. Compose layouts from `Grid` (container) and `GridItem` (cells).
+
+The foundation provides the breakpoint ladder (4 columns on mobile, 8 on tablet, 12 on desktop) and the responsive span tokens — `Grid` is a thin wrapper, not a reimplementation.
+
+## When to use
+
+- Page-level or content-block layouts that need to match the Figma grid
+- Responsive multi-column layouts where column count should adapt per viewport
+
+## Variants
+
+| Variant  | Use case                                                                                                    |
+| -------- | ----------------------------------------------------------------------------------------------------------- |
+| `main`   | Default. Content-block grid matching the Figma main grid. Often placed on `<main>` or large content blocks. |
+| `page`   | Single-column full-width grid. Use at the page root; stretches across any parent grid via `1 / -1`.         |
+| `funnel` | Narrow variant of `main` for funnels/forms. Capped at `--bds-container_max-width--narrow` (48rem).          |
+| `custom` | Explicit column count via the `columns` prop. Use sparingly — it is **not** responsive.                     |
+
+## Responsive behavior
+
+`main` and `funnel` inherit the foundation's column ladder automatically. Named `columnSpan` values adapt across breakpoints so you don't need media queries:
+
+| Viewport               | Total columns | `one-quarter` | `one-third` | `half` | `two-thirds` | `three-quarters` | `full` |
+| ---------------------- | ------------- | ------------- | ----------- | ------ | ------------ | ---------------- | ------ |
+| mobile (< 48rem)       | 4             | 4             | 4           | 4      | 4            | 4                | 4      |
+| tablet (≥ 48rem)       | 8             | 4             | 4           | 4      | 4            | 8                | 8      |
+| desktop (≥ 60rem)      | 12            | 3             | 4           | 6      | 8            | 9                | 12     |
+| wide (≥ 64rem / 86rem) | 12            | 3             | 4           | 6      | 8            | 9                | 12     |
+
+Numeric `columnSpan={n}` is literal — it does not adapt. Use named values when you want responsive behavior.
+
+## Grid props
+
+<ArgTypes of={Stories} />
+
+## GridItem props
+
+| Prop          | Type                                                                                                     | Default  | Description                                                                       |
+| ------------- | -------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------- |
+| `columnSpan`  | `'full'` <br /> \| `'three-quarters'` <br /> \| `'two-thirds'` <br /> \| `'half'` <br /> \| `'one-third'` <br /> \| `'one-quarter'` <br /> \| `'auto'` <br /> \| `number` | `'full'` | How many grid columns to span. Named values are responsive via the foundation. `'auto'` derives the span from the intrinsic aspect ratio of the first `<img>`/`<video>` descendant — see [Aspect-ratio auto-span](#aspect-ratio-auto-span). |
+| `rowSpan`     | `number`                                                                                                 | —        | How many rows to span. Ignored in masonry layouts.                                |
+| `startColumn` | `number`                                                                                                 | —        | **Escape hatch.** Explicit start column. Overrides `columnSpan` responsive logic. |
+| `endColumn`   | `number`                                                                                                 | —        | **Escape hatch.** Explicit end column. Overrides `columnSpan` responsive logic.   |
+| `as`          | `ElementType`                                                                                            | `'div'`  | Render as a custom element/component.                                             |
+
+A `GridItemSpan` constant is exported for dot-access:
+
+```ts
+import { GridItemSpan } from '@boostdev/design-system-components';
+<GridItem columnSpan={GridItemSpan.threeQuarters}>…</GridItem>
+```
+
+### Warning: startColumn / endColumn
+
+These override the responsive span tokens and force fixed positioning. Only reach for them when you fully understand the layout implications. Prefer named `columnSpan` values.
+
+## HTML attribute forwarding
+
+All standard HTML attributes (e.g. `id`, `data-*`, `aria-*`, `role`) spread onto the root element.
+
+## CSS variables
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Default</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--grid_gap`</td><td>`var(--bds-grid_gap)`</td><td>Gap between grid items.</td></tr>
+<tr><td>`--grid_columns`</td><td>`4`</td><td>Column count for `variant="custom"` (set automatically when the `columns` prop is supplied).</td></tr>
+</tbody>
+</table>
+
+## Foundation tokens referenced
+
+- `--bds-grid_template-columns`, `--bds-grid_gap`, `--bds-grid_columns`
+- `--bds-grid_span-100`, `--bds-grid_columns-75/66/50/33/25`
+- `--bds-container_max-width`, `--bds-container_max-width--narrow`, `--bds-container_spacing-inline`
+
+## Nesting
+
+Grids can nest. A `variant="page"` inside another grid uses `grid-column: 1 / -1` to span the full parent, so nested page grids always occupy the full width of their container.
+
+```tsx
+<Grid variant="main">
+  <GridItem columnSpan="full">
+    <Grid variant="page">…</Grid>
+  </GridItem>
+</Grid>
+```
+
+## Accessibility
+
+Grid is purely presentational — it renders a `<div>` by default with no ARIA role. Use the `as` prop to render the appropriate landmark when the grid maps to one (`as="main"`, `as="section"`, etc.). The grid itself does not manage focus order; source order drives reading order and should match the visual flow.
+
+## Framework equivalents
+
+| Package                                | React          | Web component             |
+| -------------------------------------- | -------------- | ------------------------- |
+| `@boostdev/design-system-components`   | `<Grid>` / `<GridItem>` | `<bds-grid>` / `<bds-grid-item>` |
+
+## Masonry layout
+
+Set `isMasonry` on any `Grid` to switch to a masonry (a.k.a. Pinterest-style) layout. Items flow into whichever track currently has the most room, so a column with a short item backfills under the tall item next to it — removing the ragged gaps that standard CSS Grid leaves when items have uneven heights.
+
+```tsx
+<Grid isMasonry>
+  {items.map((i) => <GridItem columnSpan="one-quarter" key={i.id}>{i.content}</GridItem>)}
+</Grid>
+```
+
+### When to use
+
+- Image/card galleries with heterogenous heights (photos in mixed portrait/landscape, cards with variable text length).
+- Pinterest / Unsplash / moodboard-style feeds.
+
+### When NOT to use
+
+- Layouts that require a stable **tab/reading order** that matches the visual order — masonry's `grid-auto-flow: dense` backfills items into earlier slots, which means DOM order can differ from visual top-to-bottom order. Keep source order meaningful regardless; don't rely on visual order for accessibility.
+- Fixed-height cards in a uniform grid — standard grid is simpler, cheaper, and has no JS dependency.
+- Lists where row alignment across columns matters (e.g. comparison tables).
+
+### How it works
+
+Masonry targets [CSS Grid Layout Module Level 3](https://www.w3.org/TR/css-grid-3/) ("grid lanes"):
+
+- **Native path** — when the browser supports `display: grid-lanes` or `grid-template-rows: masonry`, CSS handles everything and the JS polyfill short-circuits. Currently Safari Technology Preview only; the polyfill runs in all other browsers.
+- **Polyfill path** — row-span packing. The container's row tracks are collapsed to a 1 px auto-track with `grid-auto-flow: dense`, and each item is given a `grid-row-end: span ceil(height + gap)`. Items stay in **normal document flow** (no absolute positioning), so surrounding content — footers, scroll anchors, page margins — lays out correctly around the grid.
+
+The polyfill re-runs on child size changes (`ResizeObserver` on each child) and child addition/removal (`MutationObserver` on the container). The container itself is not observed — setting row-spans changes the container block-size, which would loop back through the observer.
+
+### Span behavior in masonry
+
+- `columnSpan` works normally — items can span multiple columns. This is how you widen a hero or panorama item within a masonry feed.
+- `rowSpan` is **ignored**. The stacking axis has no rows to span — each column flows freely.
+- `startColumn` / `endColumn` still work for definite placement.
+
+### Performance
+
+- **Initial layout** — three passes (clear, batch-read all heights, batch-write all spans). Height reads and writes are each grouped to avoid O(N) forced reflows; the measured cost is one layout pass regardless of item count.
+- **Re-layout** — on child resize or mutation the polyfill is scheduled via `requestAnimationFrame`, so bursts of observer callbacks coalesce into a single re-run per frame.
+- **Ceil overshoot** — the 1 px row track means each item's span can overshoot by up to 1 px. Not visible in practice (row-gap is 0; the gap is baked into each item's span).
+- **Long lists** — for galleries with hundreds of items, virtualisation is still the correct answer; masonry is orthogonal.
+
+### SSR / hydration
+
+Grid is client-only in masonry mode (uses `useRef` + `useLayoutEffect`). Before hydration there is no row-span overlay, so items fall back to one-row tracks. If you need a server-rendered placeholder, render a static `variant="custom"` grid of the same width on the server and swap to `isMasonry` after hydration.
+
+### Accessibility
+
+Masonry does not change semantics — the DOM stays in source order. Because `grid-auto-flow: dense` can pick any column for each item, **do not rely on visual order for screen-reader reading order**. Structure your content so it makes sense top-to-bottom in the DOM.
+
+## Aspect-ratio auto-span
+
+For galleries that mix portrait, landscape, and panoramic images, set `autoSpanMedia` on the `Grid` and each `GridItem` will derive its column span from the intrinsic aspect ratio of its first `<img>` or `<video>` descendant. The wide pano automatically gets more columns; the portrait stays a quarter.
+
+```tsx
+<Grid isMasonry autoSpanMedia>
+  {photos.map((p) => (
+    <GridItem key={p.id}>
+      <img src={p.src} alt={p.alt} />
+    </GridItem>
+  ))}
+</Grid>
+```
+
+Individual items can opt in or out explicitly with `columnSpan="auto"` or a fixed span — `autoSpanMedia` is only the default for items that don't set `columnSpan` themselves.
+
+### Thresholds
+
+| Aspect ratio (w ÷ h) | Resolved span       | Typical source                    |
+| -------------------- | ------------------- | --------------------------------- |
+| ≤ 1.5                | `'one-quarter'`     | Portrait, square, 3:2 portrait    |
+| > 1.5 and ≤ 2.2      | `'half'`            | 16:9, 3:2 landscape, 2:1          |
+| > 2.2 and ≤ 3.5      | `'three-quarters'`  | 21:9, 2.35:1, 2.5:1 (cinematic)   |
+| > 3.5                | `'full'`            | 32:9, hard panoramic              |
+| invalid / unresolved | `'one-quarter'`     | No media / metadata not yet ready |
+
+Named-span responsive behavior still applies, so on mobile every item collapses to full-width (4-col grid) regardless of its resolved span.
+
+### Loading behavior
+
+Intrinsic dimensions are read from `img.naturalWidth/naturalHeight` and `video.videoWidth/videoHeight` — no layout is triggered. If metadata is not yet available when the component mounts, the item starts at `'one-quarter'` and re-resolves when the `load` (image) or `loadedmetadata` (video) event fires. Subsequent child mutations re-run the resolver.
+
+### When NOT to use auto-span
+
+- Items where span should reflect **content importance** (a featured card is wider because it's featured, not because its photo is wide) — set `columnSpan` explicitly.
+- Non-media grids — a text-only card has no aspect ratio to read, so every item falls back to `'one-quarter'`. Use explicit spans instead.
+- Galleries where all images share the same aspect — the thresholds won't differentiate them; a uniform explicit span is simpler.
+
+### Performance
+
+- One `querySelector('img, video')` + one property read per item per resolve pass.
+- No layout thrashing: `naturalWidth` / `videoWidth` are cached properties that resolve once metadata is available.
+- Event subscriptions are `{ once: true }` so there's no cleanup ceremony per item.
+- Re-resolution cost is bounded by the number of items whose media changes, not the total item count.
+
+## Migration from `@greenchoice/design-system`
+
+| Greenchoice                     | BoostDev equivalent                    |
+| ------------------------------- | -------------------------------------- |
+| `<GdsGrid variant="main">`      | `<Grid variant="main">`                |
+| `<GdsGridItem columnSpan="twoThird">` | `<GridItem columnSpan="two-thirds">` |
+| `--gds-grid-span-*`             | `--bds-grid_span-*`                    |
+| `--gds-main-container--max-width` | `--bds-container_max-width`          |
+| `--gds-main-container--max-width--narrow` | `--bds-container_max-width--narrow` |
+
+## Examples
+
+### Main grid
+<Canvas of={Stories.Main} />
+
+### Page grid
+<Canvas of={Stories.Page} />
+
+### Funnel grid
+<Canvas of={Stories.Funnel} />
+
+### Custom grid
+<Canvas of={Stories.Custom} />
+
+### Centered
+<Canvas of={Stories.Centered} />
+
+### Spans
+<Canvas of={Stories.Spans} />
+
+### Start / end (escape hatch)
+<Canvas of={Stories.StartEnd} />
+
+### Complex layout
+<Canvas of={Stories.ComplexLayout} />
+
+### Masonry
+<Canvas of={Stories.Masonry} />
+
+### Masonry with spans
+<Canvas of={Stories.MasonryWithSpans} />

package/src/components/layout/Grid/Grid.module.css

@@ -0,0 +1,59 @@
+@layer boostdev.component {
+  .grid {
+    display: grid;
+    gap: var(--grid_gap, var(--bds-grid_gap));
+  }
+
+  .grid.--main {
+    grid-template-columns: var(--bds-grid_template-columns);
+  }
+
+  .grid.--page {
+    grid-template-columns: 1fr;
+    grid-column: 1 / -1;
+  }
+
+  .grid.--funnel {
+    grid-template-columns: var(--bds-grid_template-columns);
+    max-inline-size: var(--bds-container_max-width--narrow);
+    margin-inline: auto;
+  }
+
+  .grid.--custom {
+    grid-template-columns: repeat(var(--grid_columns, 4), minmax(0, 1fr));
+  }
+
+  .grid.--centered {
+    margin-inline: auto;
+    max-inline-size: var(--bds-container_max-width);
+    padding-inline: var(--bds-container_spacing-inline);
+  }
+
+  .item {
+    min-inline-size: 0;
+  }
+
+  /*
+   * Masonry (CSS Grid Level 3 — https://www.w3.org/TR/css-grid-3/).
+   * Progressive enhancement: when a browser supports the native grid-lanes
+   * display value or the `masonry` keyword for grid-template-rows, it handles
+   * layout natively. Otherwise the JS polyfill in ./masonry.ts assigns each
+   * item a `grid-row: span N` based on its measured height — items stay in
+   * normal grid flow, so column tracks and spans resolve through CSS as usual.
+   */
+  @supports (grid-template-rows: masonry) {
+    .grid.--masonry {
+      /* stylelint-disable-next-line declaration-property-value-no-unknown --
+         `masonry` is an experimental CSS Grid Level 3 value; stylelint's
+         built-in value list hasn't caught up. This rule is inside @supports
+         so non-supporting browsers never parse it. */
+      grid-template-rows: masonry;
+    }
+  }
+
+  @supports (display: grid-lanes) {
+    .grid.--masonry {
+      display: grid-lanes;
+    }
+  }
+}