@boostdev/design-system-components 2.8.0 → 2.11.0

package/src/web-components/layout/bds-grid.spec.ts

@@ -1,7 +1,17 @@
 import { fixture, cleanup } from '../test/helpers';
 import { BdsGrid } from './bds-grid';
+import type { BdsGridItem } from './bds-grid-item';
+// Side-effect import: registers the `bds-grid-item` custom element. BdsGridItem
+// above is used only as a type, which esbuild's isolatedModules-style transform
+// would otherwise elide — silently leaving <bds-grid-item> un-upgraded (a plain
+// HTMLElement) in every fixture in this file that nests one inside <bds-grid>.
 import './bds-grid-item';
 
+/** Flush one requestAnimationFrame tick — the masonry polyfill's schedule/apply cycle. */
+function nextFrame(): Promise<void> {
+  return new Promise((resolve) => requestAnimationFrame(() => resolve()));
+}
+
 describe('bds-grid', () => {
   it('is registered as a custom element', () => {
     expect(customElements.get('bds-grid')).toBe(BdsGrid);
@@ -67,4 +77,92 @@ describe('bds-grid', () => {
     expect(el.masonryPreferredColumnSpan).toBe('half');
     cleanup(el);
   });
+
+  it('reflects masonry-row-unit-px as a number property', async () => {
+    const el = await fixture(
+      '<bds-grid is-masonry masonry-row-unit-px="8"></bds-grid>',
+    ) as BdsGrid;
+    expect(el.masonryRowUnitPx).toBe(8);
+    cleanup(el);
+  });
+
+  it('applies grid-column: 1 / -1 to the host (not the inner .grid) for variant="page", so nested page grids span the parent', () => {
+    const cssText = BdsGrid.styles.cssText;
+    expect(cssText).toMatch(/:host\(\[variant='page'\]\)\s*{[^}]*grid-column:\s*1\s*\/\s*-1/);
+    // The inner .grid.--page rule must not also carry grid-column — the host
+    // (which participates in a parent grid's tracks) owns spanning; the inner
+    // div only owns its own track sizing.
+    expect(cssText).not.toMatch(/\.grid\.--page\s*{[^}]*grid-column:/);
+  });
+
+  it('falls back to the --grid_columns default when the columns attribute is removed', async () => {
+    const el = await fixture(
+      '<bds-grid variant="custom" columns="6"></bds-grid>',
+    ) as BdsGrid;
+    const grid = el.shadowRoot!.querySelector('.grid') as HTMLElement;
+    expect(grid.getAttribute('style')).toContain('--grid_columns: 6');
+
+    el.removeAttribute('columns');
+    await el.updateComplete;
+
+    // Lit's Number converter yields `null` (not `undefined`) when a reflected
+    // attribute is removed. A strict `!== undefined` check would still match
+    // and emit the literal string "null", making `var(--grid_columns, 4)`
+    // resolve to an invalid custom property and collapse the grid to one
+    // column instead of falling back to the default.
+    expect(grid.getAttribute('style') ?? '').not.toContain('null');
+    cleanup(el);
+  });
+
+  it('does not clear a slotted grid-item row-span style when re-rendering a non-masonry grid', async () => {
+    const el = await fixture(
+      '<bds-grid><bds-grid-item row-span="3">A</bds-grid-item></bds-grid>',
+    ) as BdsGrid;
+    const item = el.querySelector('bds-grid-item') as BdsGridItem;
+    await item.updateComplete;
+    expect(item.style.gridRow).toBe('span 3');
+
+    // An unrelated property change re-renders bds-grid. Before the fix,
+    // updated() called clearMasonryLayout() unconditionally on every
+    // non-masonry update, wiping the row-span this GridItem's own render set.
+    el.isCentered = true;
+    await el.updateComplete;
+
+    expect(item.style.gridRow).toBe('span 3');
+    cleanup(el);
+  });
+
+  it('applies a masonry row-span to slotted items after mount', async () => {
+    const el = await fixture(
+      '<bds-grid is-masonry><bds-grid-item>A</bds-grid-item></bds-grid>',
+    ) as BdsGrid;
+    await nextFrame();
+    const item = el.querySelector('bds-grid-item') as HTMLElement;
+    // jsdom reports offsetHeight 0 for unlaid-out elements, so the polyfill
+    // assigns the 1-row floor.
+    expect(item.style.gridRowEnd).toBe('span 1');
+    cleanup(el);
+  });
+
+  it('re-engages masonry after being disconnected and reconnected', async () => {
+    const el = await fixture(
+      '<bds-grid is-masonry><bds-grid-item>A</bds-grid-item></bds-grid>',
+    ) as BdsGrid;
+    await nextFrame();
+    const item = el.querySelector('bds-grid-item') as HTMLElement;
+    expect(item.style.gridRowEnd).toBe('span 1');
+
+    const parent = el.parentElement!;
+    el.remove();
+    // disconnectedCallback tears down masonry synchronously.
+    expect(item.style.gridRowEnd).toBe('');
+
+    parent.appendChild(el);
+    // No property changed, so updated() won't fire — connectedCallback must
+    // re-arm masonry on its own for this to re-apply.
+    await nextFrame();
+    expect(item.style.gridRowEnd).toBe('span 1');
+
+    cleanup(el);
+  });
 });

package/src/web-components/layout/bds-grid.ts

@@ -4,6 +4,12 @@ import type { GridItemSpanValue } from '../../components/layout/Grid/GridItem';
 
 export type GridVariant = 'main' | 'page' | 'funnel' | 'custom';
 
+// Mirrors masonry.ts's useMasonry hook: RO-triggered resizes of already-laid-out
+// items are deferred while the user is actively scrolling, and applied once
+// scroll idles for this long — avoids a compositor race where a re-pack mid-
+// scroll paints over already-visible content for a frame or two.
+const MASONRY_SCROLL_IDLE_MS = 150;
+
 /**
  * `<bds-grid>` — framework-agnostic Grid layout custom element.
  *
@@ -23,16 +29,36 @@ export type GridVariant = 'main' | 'page' | 'funnel' | 'custom';
  *                     across breakpoints via the foundation's responsive column
  *                     tokens. An item at row-end is demoted to the remaining
  *                     column count. Numeric values are literal and don't adapt.
+ *   masonry-row-unit-px — number; masonry only. Manual override for the
+ *                     row-track unit (px) the polyfill uses for
+ *                     `grid-auto-rows` and as the ceil() granularity of each
+ *                     item's row span. Omit to let the polyfill auto-pick the
+ *                     smallest unit that keeps the implicit row count under
+ *                     any browser cap.
  *
  * Slots:
  *   (default) — grid content; typically `<bds-grid-item>` children
  */
 export class BdsGrid extends LitElement {
   static styles = css`
+    /* Shadow DOM does not inherit the global box-sizing reset, so set it
+       here; otherwise elements with an explicit size + padding size as
+       content-box and layouts drift from the React (light-DOM) versions. */
+    :host,
+    *,
+    *::before,
+    *::after {
+      box-sizing: border-box;
+    }
+
     :host {
       display: block;
     }
 
+    :host([variant='page']) {
+      grid-column: 1 / -1;
+    }
+
     .grid {
       display: grid;
       gap: var(--grid_gap, var(--bds-grid_gap));
@@ -45,7 +71,6 @@ export class BdsGrid extends LitElement {
 
     .grid.--page {
       grid-template-columns: 1fr;
-      grid-column: 1 / -1;
     }
 
     .grid.--funnel {
@@ -88,6 +113,7 @@ export class BdsGrid extends LitElement {
       attribute: 'masonry-preferred-column-span',
       reflect: true,
     },
+    masonryRowUnitPx: { type: Number, attribute: 'masonry-row-unit-px', reflect: true },
   };
 
   declare variant: GridVariant;
@@ -96,10 +122,53 @@ export class BdsGrid extends LitElement {
   declare isMasonry: boolean;
   declare autoSpanMedia: boolean;
   declare masonryPreferredColumnSpan: string | undefined;
+  declare masonryRowUnitPx: number | undefined;
 
   private _ro?: ResizeObserver;
   private _mo?: MutationObserver;
   private _frame = 0;
+  // Tracks whether the masonry observers/listeners are currently wired up.
+  // Guards _teardownMasonry so a grid that never engaged masonry (or already
+  // tore it down) never clears spans it didn't apply.
+  private _engaged = false;
+  private _scrolling = false;
+  private _pendingResize = false;
+  private _scrollTimer?: ReturnType<typeof setTimeout>;
+
+  // RO-triggered re-runs (an already-laid-out item resizing — image decode, font
+  // swap) apply immediately unless the user is actively scrolling, in which case
+  // they're deferred until scroll idles (see _onScroll) to avoid a compositor
+  // race where `grid-auto-flow: dense` re-packs items mid-scroll. Stable
+  // arrow-function references so connectedCallback/disconnectedCallback can
+  // add/remove the same listener.
+  private _onResize = () => {
+    if (this._scrolling) {
+      this._pendingResize = true;
+      return;
+    }
+    this._apply();
+  };
+
+  // MutationObserver fires when children are added/removed. Newly-added children
+  // (and their media descendants) need to be observed for size, and the run is
+  // deferred to rAF so the browser lays out the new children before measuring.
+  private _onMutate = () => {
+    for (const child of this._items()) this._observeDescendants(child);
+    this._scheduleMasonry();
+  };
+
+  private _onScroll = () => {
+    this._scrolling = true;
+    if (this._scrollTimer !== undefined) clearTimeout(this._scrollTimer);
+    this._scrollTimer = setTimeout(() => {
+      this._scrolling = false;
+      this._scrollTimer = undefined;
+      if (this._pendingResize) {
+        this._pendingResize = false;
+        this._apply();
+      }
+    }, MASONRY_SCROLL_IDLE_MS);
+  };
 
   constructor() {
     super();
@@ -109,6 +178,21 @@ export class BdsGrid extends LitElement {
     this.isMasonry = false;
     this.autoSpanMedia = false;
     this.masonryPreferredColumnSpan = undefined;
+    this.masonryRowUnitPx = undefined;
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    // Re-arm masonry on reconnect (e.g. the element was moved in the DOM).
+    // disconnectedCallback tore down observers/listeners; updated() only fires
+    // again on a property change, so a reconnect with no property change would
+    // otherwise leave masonry permanently disengaged. No-op on first connect —
+    // the shadow root hasn't rendered yet, so _setupMasonry finds no container
+    // and updated() performs the initial setup once it has.
+    if (this.isMasonry && !supportsNativeMasonry() && !this._engaged) {
+      this._setupMasonry();
+      this._scheduleMasonry();
+    }
   }
 
   disconnectedCallback() {
@@ -121,6 +205,7 @@ export class BdsGrid extends LitElement {
       this._setupMasonry();
       this._scheduleMasonry();
     } else {
+      // No-op when masonry was never engaged — see the guard in _teardownMasonry.
       this._teardownMasonry();
     }
   }
@@ -133,37 +218,54 @@ export class BdsGrid extends LitElement {
     return (Array.from(this.children) as HTMLElement[]).filter((el) => el.nodeType === 1);
   }
 
+  private _observeDescendants(child: Element) {
+    if (!this._ro) return;
+    this._ro.observe(child);
+    // Also observe media descendants directly. `loading="lazy"` images decode
+    // asynchronously; observing the image itself means the polyfill re-runs in
+    // the same frame as the decode instead of one frame late.
+    for (const media of Array.from(child.querySelectorAll('img, video'))) {
+      this._ro.observe(media);
+    }
+  }
+
   private _setupMasonry() {
-    if (this._ro || this._mo) return;
+    if (this._engaged) return;
     const container = this._gridEl();
     if (!container) return;
+    this._engaged = true;
 
     if (typeof ResizeObserver !== 'undefined') {
-      this._ro = new ResizeObserver(() => this._scheduleMasonry());
-      // Only observe children, not the container — container block-size changes when
-      // we apply row-spans, which would loop back through the observer.
-      for (const child of this._items()) this._ro.observe(child);
+      this._ro = new ResizeObserver(this._onResize);
+      // Only observe children (and their media), not the container — container
+      // block-size changes when we apply row-spans, which would loop back
+      // through the observer.
+      for (const child of this._items()) this._observeDescendants(child);
     }
 
     if (typeof MutationObserver !== 'undefined') {
-      this._mo = new MutationObserver(() => {
-        if (this._ro) for (const child of this._items()) this._ro.observe(child);
-        this._scheduleMasonry();
-      });
+      this._mo = new MutationObserver(this._onMutate);
       this._mo.observe(this, { childList: true });
     }
+
+    // `capture: true` catches scroll events from any nested scroll container,
+    // since scroll doesn't bubble. `passive: true` tells the browser we won't
+    // preventDefault — critical for not blocking scroll performance.
+    window.addEventListener('scroll', this._onScroll, { passive: true, capture: true });
+  }
+
+  private _apply() {
+    const container = this._gridEl();
+    if (!container) return;
+    applyMasonryLayout(container, this._items(), {
+      preferredColumnSpan: this._resolvePreferredColumnSpan(),
+      rowUnitPx: this.masonryRowUnitPx,
+    });
   }
 
   private _scheduleMasonry() {
     cancelAnimationFrame(this._frame);
-    this._frame = requestAnimationFrame(() => {
-      const container = this._gridEl();
-      if (container) {
-        applyMasonryLayout(container, this._items(), {
-          preferredColumnSpan: this._resolvePreferredColumnSpan(),
-        });
-      }
-    });
+    this._frame = requestAnimationFrame(() => this._apply());
   }
 
   private _resolvePreferredColumnSpan(): Exclude<GridItemSpanValue, 'auto'> | undefined {
@@ -176,11 +278,24 @@ export class BdsGrid extends LitElement {
   }
 
   private _teardownMasonry() {
+    // Nothing was ever wired up — skip clearMasonryLayout too, so a non-masonry
+    // (or not-yet-engaged) grid never has its slotted items' inline styles
+    // (e.g. a `row-span` a consumer set) reset on disconnect/reconnect.
+    if (!this._engaged) return;
+
     cancelAnimationFrame(this._frame);
+    if (this._scrollTimer !== undefined) {
+      clearTimeout(this._scrollTimer);
+      this._scrollTimer = undefined;
+    }
+    this._scrolling = false;
+    this._pendingResize = false;
+    window.removeEventListener('scroll', this._onScroll, { capture: true } as EventListenerOptions);
     this._ro?.disconnect();
     this._mo?.disconnect();
     this._ro = undefined;
     this._mo = undefined;
+    this._engaged = false;
     const container = this._gridEl();
     if (container) clearMasonryLayout(container, this._items());
   }
@@ -193,8 +308,13 @@ export class BdsGrid extends LitElement {
       this.isMasonry ? '--masonry' : '',
     ].filter(Boolean).join(' ');
 
+    // Lit's Number converter yields `null` (not `undefined`) when a reflected
+    // attribute is removed — a strict `!== undefined` check would still match
+    // and emit the literal string "null", making `var(--grid_columns, 4)`
+    // resolve to an invalid custom property and collapse the grid to one
+    // column. Loose `!= null` catches both null and undefined.
     const styleAttr =
-      this.variant === 'custom' && this.columns !== undefined
+      this.variant === 'custom' && this.columns != null
         ? `--grid_columns: ${this.columns}`
         : '';
 

package/src/web-components/ui/BdsAlert.mdx

@@ -5,7 +5,7 @@ import * as Stories from './BdsAlert.stories';
 
 # <bds-alert>
 
-Framework-agnostic alert custom element for inline status messages. Supports four semantic variants, an optional title, and a dismissible mode.
+Framework-agnostic alert custom element for inline status messages. Supports four semantic variants, an optional heading, and a dismissible mode.
 
 > **Status: experimental** — API may change before stable release.
 
@@ -32,8 +32,8 @@ import '@boostdev/design-system-components/web-components';
 ### Error
 <Canvas of={Stories.Error} />
 
-### With title
-<Canvas of={Stories.WithTitle} />
+### With heading
+<Canvas of={Stories.WithHeading} />
 
 ### Dismissible
 <Canvas of={Stories.Dismissible} />
@@ -47,7 +47,8 @@ import '@boostdev/design-system-components/web-components';
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `variant` | `"info" \| "success" \| "warning" \| "error"` | `"info"` | Semantic colour and icon |
-| `title` | string | — | Optional heading displayed above body content |
+| `heading` | string | — | Optional heading displayed above body content |
+| `title` | string | — | **Deprecated.** Alias for `heading`, used as a fallback when `heading` is unset. Avoid: it shares its name with the global HTML `title` attribute, which makes the browser show a native tooltip on hover. Will be removed in a later major — use `heading` instead. |
 | `dismissible` | boolean | `false` | Shows a dismiss (×) button |
 
 ## Slots
@@ -66,7 +67,7 @@ import '@boostdev/design-system-components/web-components';
 ## Usage in plain HTML
 
 ```html
-<bds-alert variant="success" title="Saved">
+<bds-alert variant="success" heading="Saved">
   Your changes have been saved successfully.
 </bds-alert>
 

package/src/web-components/ui/BdsAlert.stories.tsx

@@ -6,20 +6,20 @@ import '../index'; // auto-registers all custom elements
 // Thin React wrapper so Storybook controls work with the custom element's props
 function BdsAlert({
   variant = 'info',
-  title,
+  heading,
   dismissible,
   children,
   onDismiss,
 }: {
   variant?: AlertVariant;
-  title?: string;
+  heading?: string;
   dismissible?: boolean;
   children?: React.ReactNode;
   onDismiss?: () => void;
 }) {
   return React.createElement(
     'bds-alert',
-    { variant, title, dismissible: dismissible || undefined, onbdsdismiss: onDismiss },
+    { variant, heading, dismissible: dismissible || undefined, onbdsdismiss: onDismiss },
     children,
   );
 }
@@ -41,8 +41,8 @@ export const Info: Story = { args: { children: 'This is an informational message
 export const Success: Story = { args: { children: 'Your changes have been saved.', variant: 'success' } };
 export const Warning: Story = { args: { children: 'Please review before continuing.', variant: 'warning' } };
 export const Error: Story = { args: { children: 'Something went wrong.', variant: 'error' } };
-export const WithTitle: Story = {
-  args: { children: 'More details about the alert.', variant: 'info', title: 'Heads up' },
+export const WithHeading: Story = {
+  args: { children: 'More details about the alert.', variant: 'info', heading: 'Heads up' },
 };
 export const Dismissible: Story = {
   args: { children: 'You can dismiss this alert.', variant: 'success', dismissible: true },
@@ -51,7 +51,7 @@ export const AllVariants: Story = {
   render: () => (
     <div style={{ display: 'flex', flexDirection: 'column', gap: '12px', maxWidth: 500 }}>
       {(['info', 'success', 'warning', 'error'] as const).map(v => (
-        <BdsAlert key={v} variant={v} title={v.charAt(0).toUpperCase() + v.slice(1)}>
+        <BdsAlert key={v} variant={v} heading={v.charAt(0).toUpperCase() + v.slice(1)}>
           This is a {v} alert.
         </BdsAlert>
       ))}

package/src/web-components/ui/BdsAvatar.mdx

@@ -46,7 +46,7 @@ import '@boostdev/design-system-components/web-components';
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `src` | string | — | Photo URL; when set the image is shown |
-| `alt` | string | `name` or `"User avatar"` | Alt text for the `<img>` element |
+| `alt` | string | `name` or `"User avatar"` | Alt text for the `<img>` element. Pass `alt=""` explicitly to mark a decorative image — an empty attribute is preserved as-is and is not replaced by `name`/`"User avatar"`. |
 | `name` | string | — | Full name; used to compute up to two initials and as `aria-label` |
 | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Diameter scale |
 
@@ -54,6 +54,8 @@ import '@boostdev/design-system-components/web-components';
 
 | Property | Description |
 |----------|-------------|
+| `--avatar_size` | Diameter override (wins over the `size` attribute's preset); defaults to `3em` |
+| `--avatar_radius` | Corner radius; defaults to `var(--bds-border_radius--circle)` |
 | `--avatar_bg` | Background colour of the fallback initials circle |
 | `--avatar_text` | Text colour of the initials |
 
@@ -73,4 +75,4 @@ import '@boostdev/design-system-components/web-components';
 ## Accessibility
 
 - Without `src`: renders `role="img"` with `aria-label` set to `name` (or "User avatar")
-- With `src`: renders `<img>` with `alt` set to `alt`, `name`, or "User avatar"
+- With `src`: renders `<img>` with `alt` set to the explicit `alt` attribute when provided (including `alt=""` for a decorative image), otherwise falling back to `name`, or "User avatar"

package/src/web-components/ui/BdsBreadcrumb.mdx

@@ -5,7 +5,7 @@ import * as Stories from './BdsBreadcrumb.stories';
 
 # <bds-breadcrumb>
 
-Framework-agnostic Breadcrumb custom element. Renders a horizontal navigation trail from a JSON array of `{ label, href? }` items. The last item is treated as the current page and rendered without a link.
+Framework-agnostic Breadcrumb custom element. Renders a horizontal navigation trail from a JSON array of `{ label, href? }` items. The last item is treated as the current page and rendered without a link. Non-last items without an `href` render as plain (non-interactive) text instead of an unusable link.
 
 > **Status: experimental** — API may change before stable release.
 
@@ -39,7 +39,7 @@ import '@boostdev/design-system-components/web-components';
 
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `items` | `Array<{ label: string; href?: string }>` | `[]` | Breadcrumb items as a JSON-serialisable array. The last item is always the current page. |
+| `items` | `Array<{ label: string; href?: string }>` | `[]` | Breadcrumb items as a JSON-serialisable array. The last item is always the current page. Malformed JSON (or a removed attribute) falls back to an empty list rather than crashing the render. |
 
 ## Usage in plain HTML
 
@@ -64,3 +64,4 @@ document.querySelector('bds-breadcrumb').items = [
 - Wrapped in `<nav aria-label="Breadcrumb">` with an `<ol>` list structure
 - The current page item carries `aria-current="page"`
 - Separator characters are `aria-hidden="true"` to avoid screen reader noise
+- Non-last items without an `href` render as plain text rather than a link with `href="#"` — this avoids an interactive-looking element that scrolls to top and pushes a history entry when activated

package/src/web-components/ui/BdsButtonContainer.mdx

@@ -0,0 +1,64 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsButtonContainer.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-button-container&gt;
+
+Framework-agnostic layout wrapper for a row of action buttons (Cancel / Confirm, Back / Next). Web-component port of the React `ButtonContainer`.
+
+> **Status: experimental** — API may change before stable release.
+
+Buttons stack vertically (primary on top, via `column-reverse`) on narrow containers and lay out in a row once the container is at least `30rem` wide. The `variant` controls alignment: `flow` (multi-step navigation), `card` (single-form submit), `modal` (dialog actions, aligned end), `content` (inline actions, aligned start).
+
+## Installation
+
+```js
+import '@boostdev/design-system-components/web-components';
+```
+
+## Examples
+
+### Two buttons
+<Canvas of={Stories.TwoButtons} />
+
+### Three buttons
+<Canvas of={Stories.ThreeButtons} />
+
+### Variants
+<Canvas of={Stories.Variants} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `variant` | `"flow" \| "card" \| "modal" \| "content"` | — | Alignment of the button row |
+| `aria-label` | string | — | Accessible label for the group container |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | `<bds-button>` elements |
+
+## Usage in plain HTML
+
+```html
+<bds-button-container variant="modal" aria-label="Dialog actions">
+  <bds-button variant="outline">Cancel</bds-button>
+  <bds-button>Confirm</bds-button>
+</bds-button-container>
+```
+
+## Deprecated: `<bds-button-group>`
+
+`<bds-button-group>` is a **deprecated alias** of `<bds-button-container>` and behaves identically. Migrate to `<bds-button-container>`; the alias (and its `./web-components/ui/bds-button-group` deep import) will be removed in a future major version.
+
+## Accessibility
+
+- Renders a `<div role="group">` with the provided `aria-label`; the attribute is omitted entirely (not an empty string) when unset
+- Always set `aria-label` to describe the purpose of the group

package/src/web-components/ui/BdsButtonContainer.stories.tsx

@@ -0,0 +1,84 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import type { ButtonContainerVariant } from './bds-button-container';
+import '../index'; // auto-registers all custom elements
+
+function BdsButtonContainer({
+  variant,
+  ariaLabel,
+  children,
+}: {
+  variant?: ButtonContainerVariant;
+  ariaLabel?: string;
+  children?: React.ReactNode;
+}) {
+  return React.createElement('bds-button-container', { variant, 'aria-label': ariaLabel }, children);
+}
+
+const meta = {
+  title: 'Web Components/Layout/ButtonContainer',
+  component: BdsButtonContainer,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'padded' },
+  argTypes: {
+    variant: { control: 'radio', options: ['flow', 'card', 'modal', 'content'] },
+    ariaLabel: { control: 'text' },
+  },
+} satisfies Meta<typeof BdsButtonContainer>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const btn = (label: string, variant?: string) =>
+  React.createElement('bds-button', variant ? { variant } : null, label);
+
+/** Two actions — the common Cancel / Confirm dialog row. */
+export const TwoButtons: Story = {
+  render: () =>
+    React.createElement(
+      'bds-button-container',
+      { variant: 'modal', 'aria-label': 'Dialog actions' },
+      btn('Cancel', 'outline'),
+      btn('Confirm'),
+    ),
+};
+
+/** Three actions. */
+export const ThreeButtons: Story = {
+  render: () =>
+    React.createElement(
+      'bds-button-container',
+      { variant: 'content', 'aria-label': 'Actions' },
+      btn('Back', 'outline'),
+      btn('Save draft', 'outline'),
+      btn('Publish'),
+    ),
+};
+
+/** All four alignment variants (resize the viewport to see the row/stack switch at 30rem). */
+export const Variants: Story = {
+  render: () =>
+    React.createElement(
+      'div',
+      { style: { display: 'flex', flexDirection: 'column', gap: '2rem' } },
+      ...(['flow', 'card', 'modal', 'content'] as const).map((v) =>
+        React.createElement(
+          'bds-button-container',
+          { key: v, variant: v, 'aria-label': v },
+          btn('Cancel', 'outline'),
+          btn('Confirm'),
+        ),
+      ),
+    ),
+};
+
+/** `<bds-button-group>` is a deprecated alias and behaves identically — prefer `<bds-button-container>`. */
+export const DeprecatedButtonGroupAlias: Story = {
+  render: () =>
+    React.createElement(
+      'bds-button-group',
+      { variant: 'modal', 'aria-label': 'Legacy alias' },
+      btn('Cancel', 'outline'),
+      btn('Confirm'),
+    ),
+};