@boostdev/design-system-components 2.0.0 → 2.2.0

package/src/components/layout/Grid/GridItem.tsx

@@ -0,0 +1,150 @@
+import {
+  ElementType,
+  ComponentPropsWithoutRef,
+  CSSProperties,
+  useContext,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from 'react';
+import css from './Grid.module.css';
+import { cn } from '@boostdev/design-system-foundation';
+import type { WithClassName } from '../../../types';
+import { GridContext } from './Grid';
+import {
+  aspectToColumnSpan,
+  findMediaChild,
+  mediaReadyEvent,
+  readMediaAspect,
+  type AutoSpanResult,
+} from './autoSpan';
+
+export type GridItemSpanValue =
+  | 'full'
+  | 'three-quarters'
+  | 'two-thirds'
+  | 'half'
+  | 'one-third'
+  | 'one-quarter'
+  | 'auto'
+  | number;
+
+export const GridItemSpan = {
+  full: 'full',
+  threeQuarters: 'three-quarters',
+  twoThirds: 'two-thirds',
+  half: 'half',
+  oneThird: 'one-third',
+  oneQuarter: 'one-quarter',
+  auto: 'auto',
+} as const satisfies Record<string, GridItemSpanValue>;
+
+const SPAN_VAR: Record<Exclude<GridItemSpanValue, number | 'auto'>, string> = {
+  full: 'var(--bds-grid_span-100)',
+  'three-quarters': 'span var(--bds-grid_columns-75)',
+  'two-thirds': 'span var(--bds-grid_columns-66)',
+  half: 'span var(--bds-grid_columns-50)',
+  'one-third': 'span var(--bds-grid_columns-33)',
+  'one-quarter': 'span var(--bds-grid_columns-25)',
+};
+
+function resolveSpan(value: Exclude<GridItemSpanValue, 'auto'>): string {
+  if (typeof value === 'number') return `span ${value}`;
+  return SPAN_VAR[value];
+}
+
+type GridItemOwnProps = WithClassName & {
+  columnSpan?: GridItemSpanValue;
+  rowSpan?: number;
+  startColumn?: number;
+  endColumn?: number;
+  as?: ElementType;
+};
+
+type GridItemProps<C extends ElementType = 'div'> = GridItemOwnProps &
+  Omit<ComponentPropsWithoutRef<C>, keyof GridItemOwnProps>;
+
+export function GridItem<C extends ElementType = 'div'>({
+  children,
+  className,
+  columnSpan,
+  rowSpan,
+  startColumn,
+  endColumn,
+  as,
+  style,
+  ...rest
+}: GridItemProps<C>) {
+  const { autoSpanMedia } = useContext(GridContext);
+  const effectiveSpan: GridItemSpanValue =
+    columnSpan ?? (autoSpanMedia ? 'auto' : 'full');
+
+  const ref = useRef<HTMLElement | null>(null);
+  const [autoSpan, setAutoSpan] = useState<AutoSpanResult>('one-quarter');
+
+  useLayoutEffect(() => {
+    if (effectiveSpan !== 'auto') return;
+    const el = ref.current;
+    if (!el) return;
+
+    let cancelled = false;
+    let cleanup: (() => void) | undefined;
+
+    const resolve = () => {
+      if (cancelled) return;
+      const media = findMediaChild(el);
+      if (!media) {
+        setAutoSpan('one-quarter');
+        return;
+      }
+      const aspect = readMediaAspect(media);
+      if (aspect !== null) {
+        setAutoSpan(aspectToColumnSpan(aspect));
+        return;
+      }
+      const event = mediaReadyEvent(media);
+      if (!event) {
+        setAutoSpan('one-quarter');
+        return;
+      }
+      const handler = () => {
+        const a = readMediaAspect(media);
+        if (a !== null) setAutoSpan(aspectToColumnSpan(a));
+      };
+      media.addEventListener(event, handler, { once: true });
+      cleanup = () => media.removeEventListener(event, handler);
+    };
+
+    resolve();
+
+    return () => {
+      cancelled = true;
+      cleanup?.();
+    };
+  }, [effectiveSpan, children]);
+
+  const hasExplicitRange = startColumn !== undefined || endColumn !== undefined;
+
+  const gridColumn = hasExplicitRange
+    ? `${startColumn ?? 'auto'} / ${endColumn ?? 'auto'}`
+    : resolveSpan(effectiveSpan === 'auto' ? autoSpan : effectiveSpan);
+
+  const composedStyle: CSSProperties = {
+    ...(style as CSSProperties),
+    gridColumn,
+    ...(rowSpan !== undefined ? { gridRow: `span ${rowSpan}` } : {}),
+  };
+
+  const Component = as ?? 'div';
+
+  return (
+    <Component
+      ref={ref as never}
+      {...rest}
+      className={cn(css.item, className)}
+      style={composedStyle}
+    >
+      {children}
+    </Component>
+  );
+}

package/src/components/layout/Grid/autoSpan.ts

@@ -0,0 +1,77 @@
+/**
+ * `columnSpan="auto"` support — derives a column span from the intrinsic aspect
+ * ratio of the first `<img>` or `<video>` child of a GridItem.
+ *
+ * Framework-agnostic: pure functions, used by both the React `GridItem` and the
+ * `bds-grid-item` web component. No layout reflow — reads `naturalWidth/Height`
+ * on images and `videoWidth/videoHeight` on videos, both of which are cached
+ * DOM properties that resolve once the media's metadata is available.
+ */
+
+export type AutoSpanResult =
+  | 'full'
+  | 'three-quarters'
+  | 'half'
+  | 'one-quarter';
+
+/**
+ * Map a width-to-height ratio to a named column span.
+ *
+ * Ratios were chosen for photography conventions:
+ *   • 3:2 / 16:9 landscape → `half`           (1.5 < r ≤ 2.2)
+ *   • 21:9 / 2.35:1 / 2.4:1 / 2.5:1 → `three-quarters` (2.2 < r ≤ 3.5)
+ *   • 32:9 / hard pano → `full`               (r > 3.5)
+ *   • Portrait, square, or unknown → `one-quarter` (r ≤ 1.5)
+ *
+ * Returns `one-quarter` for invalid/non-positive ratios so layout stays stable
+ * when metadata isn't yet resolved.
+ */
+export function aspectToColumnSpan(ratio: number): AutoSpanResult {
+  if (!Number.isFinite(ratio) || ratio <= 0) return 'one-quarter';
+  if (ratio > 3.5) return 'full';
+  if (ratio > 2.2) return 'three-quarters';
+  if (ratio > 1.5) return 'half';
+  return 'one-quarter';
+}
+
+/**
+ * Find the first `<img>` or `<video>` descendant of `root`. Returns `null`
+ * if none. Only descends the light DOM; shadow content is opaque by design.
+ */
+export function findMediaChild(
+  root: HTMLElement,
+): HTMLImageElement | HTMLVideoElement | null {
+  return root.querySelector('img, video');
+}
+
+/**
+ * Read the intrinsic aspect ratio (width / height) of an image or video.
+ * Returns `null` if the intrinsic dimensions haven't resolved yet — consumers
+ * should subscribe to `load` (images) or `loadedmetadata` (video) and retry.
+ */
+export function readMediaAspect(
+  media: HTMLImageElement | HTMLVideoElement,
+): number | null {
+  if (media instanceof HTMLImageElement) {
+    if (media.naturalWidth > 0 && media.naturalHeight > 0) {
+      return media.naturalWidth / media.naturalHeight;
+    }
+    return null;
+  }
+  if (media.videoWidth > 0 && media.videoHeight > 0) {
+    return media.videoWidth / media.videoHeight;
+  }
+  return null;
+}
+
+/**
+ * Returns the name of the event the given media element fires when its
+ * intrinsic dimensions become available.
+ */
+export function mediaReadyEvent(
+  media: HTMLImageElement | HTMLVideoElement,
+): 'load' | 'loadedmetadata' | null {
+  if (media instanceof HTMLImageElement) return media.complete ? null : 'load';
+  if (media.readyState < 1 /* HAVE_METADATA */) return 'loadedmetadata';
+  return null;
+}

package/src/components/layout/Grid/index.ts

@@ -0,0 +1,4 @@
+export { Grid } from './Grid';
+export type { GridVariant } from './Grid';
+export { GridItem, GridItemSpan } from './GridItem';
+export type { GridItemSpanValue } from './GridItem';

package/src/components/layout/Grid/masonry.ts

@@ -0,0 +1,134 @@
+import { RefObject, useLayoutEffect } from 'react';
+
+/**
+ * Masonry layout polyfill based on CSS Grid Layout Module Level 3 (a.k.a. "grid-lanes").
+ * https://www.w3.org/TR/css-grid-3/ · https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Grid_layout/Masonry_layout
+ *
+ * Implementation strategy — row-span packing:
+ *   1. Override the container to `grid-auto-rows: 1px` + `row-gap: 0`. The
+ *      author-intended row gap is baked into each item's span instead of
+ *      being applied between rows — that way the ceil() rounding can only
+ *      overshoot by <1px per item, so visual gaps stay uniform.
+ *   2. Set `grid-auto-flow: dense` so items backfill into the earliest empty
+ *      slot — this is what produces the masonry effect when items have
+ *      variable heights.
+ *   3. For each child: measure its natural height H, then set
+ *      `grid-row-end: span ceil(H + targetGap)`. The last `targetGap` pixels
+ *      of each item's cell are empty, which renders as the visual gap below
+ *      the item.
+ *
+ * Items stay in normal document flow — no `position: absolute`. CSS Grid handles
+ * column-track sizing (including the foundation's responsive `--bds-grid_*` tokens),
+ * column spans, and definite placements; the polyfill only supplies the row-span.
+ * Column gap is left untouched; only row gap is subsumed into spans.
+ *
+ * When the browser supports the native `display: grid-lanes` or
+ * `grid-template-rows: masonry` value, the polyfill yields to CSS.
+ */
+
+const ROW_UNIT_PX = 1;
+
+export function supportsNativeMasonry(): boolean {
+  if (typeof CSS === 'undefined' || typeof CSS.supports !== 'function') return false;
+  return (
+    CSS.supports('display', 'grid-lanes') ||
+    CSS.supports('grid-template-rows', 'masonry')
+  );
+}
+
+export function applyMasonryLayout(container: HTMLElement, rawChildren: HTMLElement[]): void {
+  // We override row-gap to 0, so reading it back would always give 0 on re-runs.
+  // Read column-gap instead — `.grid` sets both via the `gap` shorthand and the
+  // polyfill never touches column-gap. (If a consumer sets asymmetric gaps, the
+  // row spacing falls back to the column value — a reasonable compromise.)
+  const cs = window.getComputedStyle(container);
+  const targetGap = parseFloat(cs.columnGap) || 0;
+
+  container.style.gridAutoRows = `${ROW_UNIT_PX}px`;
+  container.style.rowGap = '0px';
+  container.style.gridAutoFlow = 'dense';
+
+  const children = rawChildren.filter(
+    (el) => el.nodeType === 1 && window.getComputedStyle(el).display !== 'none',
+  );
+
+  // Pass 1 — clear prior row-span overrides so items measure at their natural height.
+  for (const child of children) {
+    child.style.gridRow = '';
+    child.style.gridRowStart = '';
+    child.style.gridRowEnd = '';
+  }
+
+  // Pass 2 — read all heights in a tight loop. The first offsetHeight read forces one
+  // reflow; subsequent reads are cached until the next style write. This avoids the
+  // O(N) forced-reflow cost of a read-then-write loop.
+  const heights = children.map((child) => child.offsetHeight);
+
+  // Pass 3 — batch all row-span writes. No reads in between, so the browser can
+  // coalesce style invalidation and do layout once for the whole batch.
+  for (let i = 0; i < children.length; i++) {
+    const span = Math.max(1, Math.ceil(heights[i] + targetGap));
+    children[i].style.gridRowEnd = `span ${span}`;
+  }
+}
+
+export function clearMasonryLayout(container: HTMLElement, rawChildren: HTMLElement[]): void {
+  container.style.gridAutoRows = '';
+  container.style.gridAutoFlow = '';
+  container.style.rowGap = '';
+  for (const child of rawChildren) {
+    if (child.nodeType !== 1) continue;
+    child.style.gridRow = '';
+    child.style.gridRowStart = '';
+    child.style.gridRowEnd = '';
+  }
+}
+
+/**
+ * React hook that runs the polyfill against `ref.current` and re-runs on
+ * size / mutation changes. No-op when `enabled` is false or when the browser
+ * natively supports masonry.
+ */
+export function useMasonry(ref: RefObject<HTMLElement | null>, enabled: boolean): void {
+  useLayoutEffect(() => {
+    const container = ref.current;
+    if (!container || !enabled) return;
+    if (supportsNativeMasonry()) return;
+
+    let frame = 0;
+    const schedule = () => {
+      cancelAnimationFrame(frame);
+      frame = requestAnimationFrame(() => {
+        applyMasonryLayout(container, Array.from(container.children) as HTMLElement[]);
+      });
+    };
+
+    schedule();
+
+    const ro =
+      typeof ResizeObserver !== 'undefined' ? new ResizeObserver(schedule) : null;
+    if (ro) {
+      // Observe each child's size, not the container — re-running when the container
+      // resizes causes a feedback loop (we set grid-auto-rows, which changes container
+      // block-size, which fires the observer). Child-size changes are what we actually
+      // need to respond to.
+      for (const child of Array.from(container.children)) ro.observe(child);
+    }
+
+    const mo =
+      typeof MutationObserver !== 'undefined'
+        ? new MutationObserver(() => {
+            if (ro) for (const child of Array.from(container.children)) ro.observe(child);
+            schedule();
+          })
+        : null;
+    mo?.observe(container, { childList: true });
+
+    return () => {
+      cancelAnimationFrame(frame);
+      ro?.disconnect();
+      mo?.disconnect();
+      clearMasonryLayout(container, Array.from(container.children) as HTMLElement[]);
+    };
+  }, [ref, enabled]);
+}

package/src/components/layout/IconWrapper/IconWrapper.stories.tsx

@@ -1,21 +1,53 @@
 import type { Meta, StoryObj } from '@storybook/react';
-import { IconWrapper } from './IconWrapper';
+import { IconWrapper, type IconWrapperProps } from './IconWrapper';
 
-const meta = {
+const CheckIcon = (
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="1em" height="1em" fill="currentColor" 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 StarIcon = (
+  <svg viewBox="0 0 24 24" fill="currentColor" width="1em" height="1em" aria-hidden>
+    <path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z" />
+  </svg>
+);
+
+const HeartIcon = (
+  <svg viewBox="0 0 24 24" fill="currentColor" width="1em" height="1em" aria-hidden>
+    <path d="M12 21s-7-4.35-7-10a4.5 4.5 0 0 1 8-2.8A4.5 4.5 0 0 1 19 11c0 5.65-7 10-7 10z" />
+  </svg>
+);
+
+const iconMap = {
+  check: CheckIcon,
+  star: StarIcon,
+  heart: HeartIcon,
+};
+
+type IconKey = keyof typeof iconMap;
+
+type IconWrapperStoryArgs = Omit<IconWrapperProps, 'children'> & {
+  children?: IconKey;
+};
+
+const meta: Meta<IconWrapperStoryArgs> = {
   title: 'React/Layout/IconWrapper',
   component: IconWrapper,
-} satisfies Meta<typeof IconWrapper>;
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const Default: Story = {
-  args: {
-    children: (
-      <svg viewBox="0 0 24 24" fill="currentColor" width="1em" height="1em">
-        <path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z" />
-      </svg>
-    ),
+  argTypes: {
+    children: {
+      control: 'select',
+      options: Object.keys(iconMap) as IconKey[],
+      mapping: iconMap,
+      description: 'The icon to render inside the circular wrapper.',
+    },
   },
+  args: { children: 'star' },
 };
 
+export default meta;
+type Story = StoryObj<IconWrapperStoryArgs>;
+
+export const Default: Story = {};
+export const Check: Story = { args: { children: 'check' } };
+export const Heart: Story = { args: { children: 'heart' } };

package/src/index.ts

@@ -67,6 +67,8 @@ export { Textarea } from './components/interaction/form/Textarea';
 export { ButtonContainer, ButtonGroup } from './components/layout/ButtonGroup';
 export type { ButtonContainerProps, ButtonGroupProps } from './components/layout/ButtonGroup';
 export { Card } from './components/layout/Card';
+export { Grid, GridItem, GridItemSpan } from './components/layout/Grid';
+export type { GridVariant, GridItemSpanValue } from './components/layout/Grid';
 export { SectionHeader } from './components/layout/SectionHeader';
 export { IconWrapper } from './components/layout/IconWrapper';
 export type { IconWrapperProps } from './components/layout/IconWrapper';

package/src/web-components/index.ts

@@ -58,6 +58,10 @@ export { BdsDescriptionList } from './ui/bds-description-list';
 export { BdsBreadcrumb } from './ui/bds-breadcrumb';
 export { BdsLink } from './ui/bds-link';
 
+// Phase 8 — layout primitives
+export { BdsGrid } from './layout/bds-grid';
+export { BdsGridItem } from './layout/bds-grid-item';
+
 // Phase 8 — complete parity with React library
 export { BdsButtonGroup } from './ui/bds-button-group';
 export { BdsTable } from './ui/bds-table';

package/src/web-components/interaction/BdsButton.mdx

@@ -1,4 +1,4 @@
-import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import { Meta, Canvas, ArgTypes, Controls } from '@storybook/blocks';
 import * as Stories from './BdsButton.stories';
 
 <Meta of={Stories} />
@@ -24,26 +24,54 @@ Or in HTML without a bundler:
 </script>
 ```
 
-## Examples
+## Playground
 
-### All variants & sizes
-<Canvas of={Stories.AllVariants} />
+<Canvas of={Stories.Playground} />
+<Controls of={Stories.Playground} />
+
+## Variants
 
-### Default
 <Canvas of={Stories.Default} />
+<Canvas of={Stories.Outline} />
 
-### Ghost
-<Canvas of={Stories.Ghost} />
+## Sizes
 
-### Sizes
 <Canvas of={Stories.Small} />
 <Canvas of={Stories.Medium} />
 <Canvas of={Stories.Large} />
 
-### Pulse (CTA emphasis)
+## Icons
+
+Slot an SVG (or any element) into `icon-start` or `icon-end`:
+
+```html
+<bds-button>
+  <svg slot="icon-start">…</svg>
+  Save
+</bds-button>
+```
+
+<Canvas of={Stories.WithIconStart} />
+<Canvas of={Stories.WithIconEnd} />
+
+### Icon-only (1:1 aspect ratio)
+
+Set the `is-icon-only` attribute to render a square button with equal `var(--bds-space_xs)` padding on both axes. Composable with any `variant`. Always pair with `aria-label` — there's no visible label text for assistive tech to read.
+
+<Canvas of={Stories.IconOnly} />
+<Canvas of={Stories.IconOnlyOutline} />
+<Canvas of={Stories.AllIconOnly} />
+
+## All variants & sizes
+
+<Canvas of={Stories.AllVariants} />
+
+## Pulse (CTA emphasis)
+
 <Canvas of={Stories.WithPulse} />
 
-### Disabled
+## Disabled
+
 <Canvas of={Stories.Disabled} />
 
 ## Props
@@ -54,14 +82,15 @@ Or in HTML without a bundler:
 
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `variant` | `"default" \| "ghost"` | `"default"` | Visual style — filled or transparent outlined |
-| `size` | `"small" \| "medium" \| "large"` | `"medium"` | Height and padding scale |
+| `variant` | `"default" \| "outline"` | `"default"` | Visual style — filled or transparent outlined (`"ghost"` is a deprecated alias for `"outline"`) |
+| `size` | `"small" \| "medium" \| "large"` | `"medium"` | Height and horizontal padding |
 | `disabled` | boolean | `false` | Prevents interaction, sets `aria-disabled` |
 | `href` | string | — | Renders as `<a>` when set |
 | `target` | string | — | Forwarded to `<a>` when `href` is set |
 | `rel` | string | — | Forwarded to `<a>` when `href` is set |
 | `type` | `"button" \| "submit" \| "reset"` | `"button"` | Native button type |
 | `has-pulse` | boolean | `false` | Adds animated ring for CTA emphasis |
+| `is-icon-only` | boolean | `false` | 1:1 aspect ratio with equal `xs` padding on both axes. Requires `aria-label`. |
 | `aria-label` | string | — | Accessible label (required for icon-only buttons) |
 
 ## Slots
@@ -76,7 +105,7 @@ Or in HTML without a bundler:
 
 | Property | Description |
 |----------|-------------|
-| `--button_color` | Identity colour — fills the default variant, outlines the ghost variant |
+| `--button_color` | Identity colour — fills the default variant, outlines the outline variant |
 | `--button_on-color` | Text/icon colour on the button surface. Pair with `--button_color` |
 
 ## Invoker Commands API
@@ -94,8 +123,11 @@ Or in HTML without a bundler:
 
 ```html
 <bds-button variant="default" size="medium">Save</bds-button>
-<bds-button variant="ghost">Cancel</bds-button>
+<bds-button variant="outline">Cancel</bds-button>
 <bds-button href="/dashboard">Go to dashboard</bds-button>
+<bds-button is-icon-only aria-label="Confirm">
+  <svg viewBox="0 0 24 24">…</svg>
+</bds-button>
 ```
 
 ## Accessibility