@boostdev/design-system-components 2.0.0 → 2.2.0

package/src/components/interaction/Button/Button.stories.tsx

@@ -1,42 +1,160 @@
 import type { Meta, StoryObj } from '@storybook/react';
-import { Button } from './Button';
+import { Button, type ButtonProps } from './Button';
 
-const meta = {
+const CheckIcon = (
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="1em" height="1em" aria-hidden>
+    <path d="M12 0a12 12 0 1 0 12 12A12 12 0 0 0 12 0Zm6.93 8.2-6.85 9.29a1 1 0 0 1-1.43.19l-4.89-3.91a1 1 0 0 1-.15-1.41A1 1 0 0 1 7 12.21l4.08 3.26L17.32 7a1 1 0 0 1 1.39-.21 1 1 0 0 1 .22 1.41Z"/>
+  </svg>
+);
+
+const ArrowRight = <span aria-hidden>→</span>;
+const ArrowLeft = <span aria-hidden>←</span>;
+
+const iconMap = {
+  none: undefined,
+  check: CheckIcon,
+  arrowRight: ArrowRight,
+  arrowLeft: ArrowLeft,
+};
+
+type IconKey = keyof typeof iconMap;
+
+/**
+ * Story-local args: `iconStart`/`iconEnd` are narrowed to the icon keys
+ * (`'check' | 'arrowRight' | …`) so the Controls panel stays in sync with
+ * the rendered icon. Storybook's `mapping` resolves the key → ReactNode at
+ * render time, so the prop still receives a real ReactNode downstream.
+ */
+type ButtonStoryArgs = Omit<ButtonProps, 'iconStart' | 'iconEnd'> & {
+  iconStart?: IconKey;
+  iconEnd?: IconKey;
+};
+
+const meta: Meta<ButtonStoryArgs> = {
   title: 'React/Interaction/Button',
   component: Button,
   argTypes: {
-    variant: { control: 'select', options: ['default', 'ghost'] },
-    size: { control: 'select', options: ['small', 'medium', 'large'] },
+    variant: {
+      control: 'select',
+      options: ['default', 'outline'],
+      description: 'Visual style. `default` is filled; `outline` is transparent with a border.',
+      table: { defaultValue: { summary: 'default' } },
+    },
+    size: {
+      control: 'select',
+      options: ['small', 'medium', 'large'],
+      description: 'Height + padding. `small` is 2.25em, `medium` is 3em, `large` bumps font-size to the h3 scale.',
+      table: { defaultValue: { summary: 'medium' } },
+    },
+    iconStart: {
+      control: 'select',
+      options: Object.keys(iconMap) as IconKey[],
+      mapping: iconMap,
+      description: 'Icon rendered before the label.',
+    },
+    iconEnd: {
+      control: 'select',
+      options: Object.keys(iconMap) as IconKey[],
+      mapping: iconMap,
+      description: 'Icon rendered after the label.',
+    },
+    isIconOnly: {
+      control: 'boolean',
+      description: 'Forces a 1:1 aspect ratio with minimal padding. Composable with any `variant`. Requires `aria-label`.',
+      table: { defaultValue: { summary: 'false' } },
+    },
+    hasPulse: {
+      control: 'boolean',
+      description: 'Adds a pulsing animation for CTA emphasis. Respects `prefers-reduced-motion`.',
+      table: { defaultValue: { summary: 'false' } },
+    },
+    disabled: {
+      control: 'boolean',
+      description: 'Blocks interaction, sets `aria-disabled`, and removes the element from the tab order.',
+      table: { defaultValue: { summary: 'false' } },
+    },
+    href: {
+      control: 'text',
+      description: 'When set, renders as `<a>` pointing to this URL instead of `<button>`.',
+    },
+    'aria-label': {
+      control: 'text',
+      description: 'Accessible label. Required for icon-only buttons.',
+    },
     onClick: { action: 'clicked' },
   },
-} satisfies Meta<typeof Button>;
+  args: { variant: 'default', size: 'medium' },
+};
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<ButtonStoryArgs>;
+
+export const Playground: Story = {
+  args: {
+    children: 'Button',
+    iconStart: 'none',
+    iconEnd: 'none',
+  },
+};
 
-export const Default: Story = { args: { children: 'Default', variant: 'default' } };
-export const Ghost: Story = { args: { children: 'Ghost', variant: 'ghost' } };
+export const Default: Story = { args: { children: 'Default' } };
+export const Outline: Story = { args: { children: 'Outline', variant: 'outline' } };
 export const Small: Story = { args: { children: 'Small', size: 'small' } };
 export const Medium: Story = { args: { children: 'Medium', size: 'medium' } };
 export const Large: Story = { args: { children: 'Large', size: 'large' } };
 export const AsLink: Story = { args: { children: 'Link Button', href: 'https://example.com' } };
 export const WithPulse: Story = { args: { children: 'Pulsing', hasPulse: true } };
 export const Disabled: Story = { args: { children: 'Disabled', disabled: true } };
-export const WithIcons: Story = {
+
+export const WithIconStart: Story = { args: { children: 'Confirm', iconStart: 'check' } };
+export const WithIconEnd: Story = { args: { children: 'Continue', iconEnd: 'arrowRight' } };
+export const WithBothIcons: Story = { args: { children: 'Both', iconStart: 'arrowLeft', iconEnd: 'arrowRight' } };
+
+export const IconOnly: Story = {
   args: {
-    children: 'With Icons',
-    iconStart: <span>→</span>,
-    iconEnd: <span>←</span>,
+    isIconOnly: true,
+    'aria-label': 'Confirm',
+    children: CheckIcon,
   },
 };
+
+export const IconOnlyOutline: Story = {
+  args: {
+    variant: 'outline',
+    isIconOnly: true,
+    'aria-label': 'Confirm',
+    children: CheckIcon,
+  },
+};
+
 export const AllVariants: Story = {
   render: () => (
     <div style={{ display: 'flex', gap: '12px', flexWrap: 'wrap', alignItems: 'center' }}>
-      {(['default', 'ghost'] as const).map(v => (
-        ['small', 'medium', 'large'].map(s => (
-          <Button key={`${v}-${s}`} variant={v} size={s as 'small' | 'medium' | 'large'}>{v} {s}</Button>
+      {(['default', 'outline'] as const).map(v =>
+        (['small', 'medium', 'large'] as const).map(s => (
+          <Button key={`${v}-${s}`} variant={v} size={s}>{v} {s}</Button>
+        ))
+      )}
+    </div>
+  ),
+};
+
+export const AllIconOnly: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: '12px', flexWrap: 'wrap', alignItems: 'center' }}>
+      {(['default', 'outline'] as const).map(v =>
+        (['small', 'medium', 'large'] as const).map(s => (
+          <Button
+            key={`${v}-${s}`}
+            variant={v}
+            size={s}
+            isIconOnly
+            aria-label={`${v} ${s}`}
+          >
+            {CheckIcon}
+          </Button>
         ))
-      ))}
+      )}
     </div>
   ),
 };

package/src/components/interaction/Button/Button.tsx

@@ -36,6 +36,8 @@ export interface ButtonProps extends WithClassName, ButtonHTMLAttributes<HTMLBut
   disabled?: boolean;
   /** Adds a pulsing animation for call-to-action emphasis. Respects `prefers-reduced-motion`. */
   hasPulse?: boolean;
+  /** When true, forces a 1:1 aspect ratio with equal `xs` padding on both axes. Pass the icon as `children`; composable with any `variant`. Requires `aria-label`. */
+  isIconOnly?: boolean;
   /** Click handler. Typed as `HTMLElement` because the root may be `<button>` or `<a>`. */
   onClick?: MouseEventHandler<HTMLElement>;
   /** Anchor target (only applied when rendered as `<a>`). */
@@ -57,6 +59,7 @@ export function Button({
   iconEnd,
   size = 'medium',
   hasPulse = false,
+  isIconOnly = false,
   href,
   target,
   rel,
@@ -69,6 +72,7 @@ export function Button({
     css[`--${variant}`],
     css[`--size_${size}`],
     hasPulse && css['--hasPulse'],
+    isIconOnly && css['--iconOnly'],
     className,
   );
 

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;
+    }
+  }
+}