@boostdev/design-system-components 2.7.1 → 2.11.0

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'),
+    ),
+};

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

@@ -50,6 +50,11 @@ import '@boostdev/design-system-components/web-components';
 | `min` | string | — | Minimum selectable date (ISO 8601) |
 | `max` | string | — | Maximum selectable date (ISO 8601) |
 | `disabled` | boolean | `false` | Disables all interaction |
+| `months` | number | `1` | Number of months shown side by side |
+| `page-by` | `"months"` \| `"single"` | `"months"` | Pagination step |
+| `first-day-of-week` | number (0–6) | `1` | First weekday column (Monday) |
+| `locale` | string | runtime default | `Intl` locale for date text |
+| `previous-label` / `next-label` | string | English | Nav button aria-labels |
 
 ## Events
 
@@ -57,6 +62,23 @@ import '@boostdev/design-system-components/web-components';
 |-------|--------|-------------|
 | `bds-date-select` | `{ date: string }` | Fired when the user selects a date; `date` is in `YYYY-MM-DD` format |
 
+## CSS Custom Properties
+
+| Property | Description |
+|----------|--------------|
+| `--calendar_border` | Border on the calendar frame (default: `none`) |
+| `--calendar_radius` | Corner radius of the calendar frame (default: `var(--bds-border_radius--m)`) |
+| `--calendar_shadow` | Elevation shadow on the calendar frame (default: `var(--bds-shadow_s)`) |
+| `--calendar_button-radius` | Corner radius shared by the nav buttons and day buttons (default: `var(--bds-border_radius--circle)`) |
+| `--calendar_navBtn-bg--hover` | Nav button background on hover (default: `var(--bds-color_bg--subtle)`) |
+| `--calendar_day-bg--hover` | Day background on hover (default: `var(--bds-color_bg--subtle)`) |
+| `--calendar_today-color` | Colour of today's ring (default: `var(--bds-color_interactive)`) |
+| `--calendar_today-border` | Border used for today's ring (default: `none`) |
+| `--calendar_today-shadow` | Shadow tail appended after today's inset ring (default: `var(--bdc-outline_shadow)`) |
+| `--calendar_day-bg--selected` | Selected day background (default: `var(--bds-color_interactive)`) |
+| `--calendar_day-color--selected` | Selected day text colour (default: `var(--bds-color_on-interactive)`) |
+| `--calendar_day-bg--in-range` | Background of days between the range endpoints (default: `var(--bds-color_blue--subtle)`) |
+
 ## Usage in plain HTML
 
 ```html
@@ -82,12 +104,15 @@ import '@boostdev/design-system-components/web-components';
 | End | Move to end of week |
 | Page Up | Navigate to previous month |
 | Page Down | Navigate to next month |
+| Shift + Page Up / Down | Previous / next year |
 | Enter / Space | Select focused date |
 
 ## Accessibility
 
-- Uses the ARIA grid pattern with `role="grid"` and `role="gridcell"` on day buttons
+- Uses the full ARIA grid pattern: `role="grid"` on the grid container, `role="row"` wrapping the column-header row and each week, `role="columnheader"` on weekday labels, and `role="gridcell"` on a wrapper element around each day `<button>`
+- Uses roving tabindex — exactly one day button is ever part of the Tab order at a time (`tabindex="0"`; every other day is `tabindex="-1"`). It prefers, in order: the day currently focused via arrow-key navigation, the selected date (if visible in the current month), today (if visible), then the 1st of the visible month — so the grid never loses its only tab stop after navigating to a month with neither the selected date nor today in view
 - The month/year label uses `aria-live="polite"` for screen reader announcements on navigation
-- Each day carries `aria-selected` and `aria-current="date"` (today)
-- Disabled days carry `aria-disabled="true"` and are not focusable
-- Respects the `disabled` attribute at the host level
+- The `role="gridcell"` wrapper carries `aria-selected`; the day `<button>` carries `aria-current="date"` on today (non-today days omit `aria-current` entirely rather than emitting `aria-current="false"`) and `aria-disabled`. Days outside the current month are inert — greyed, non-selectable, and never marked selected/current
+- Disabled days carry `aria-disabled="true"` and are not focusable (native `disabled` button)
+- Respects the `disabled` attribute at the host level — disables day selection, keyboard navigation, and the month nav buttons; also responds to `formDisabledCallback` (e.g. an ancestor `<fieldset disabled>`)
+- Respects `prefers-reduced-motion` — day and nav-button transitions are disabled for users who request reduced motion

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

@@ -3,24 +3,17 @@ import type { Meta, StoryObj } from '@storybook/react';
 import '../index'; // auto-registers all custom elements
 
 function BdsCalendar({
-  name,
-  value,
-  min,
-  max,
-  disabled,
+  name, value, min, max, disabled, months, firstDayOfWeek, locale,
 }: {
-  name?: string;
-  value?: string;
-  min?: string;
-  max?: string;
-  disabled?: boolean;
+  name?: string; value?: string; min?: string; max?: string; disabled?: boolean;
+  months?: number; firstDayOfWeek?: number; locale?: string;
 }) {
   return React.createElement('bds-calendar', {
-    name,
-    value,
-    min,
-    max,
+    name, value, min, max,
     disabled: disabled || undefined,
+    months,
+    'first-day-of-week': firstDayOfWeek,
+    locale,
   });
 }
 
@@ -30,10 +23,13 @@ const meta = {
   tags: ['!stable', 'experimental'],
   parameters: { layout: 'centered' },
   argTypes: {
-    value:    { control: 'text' },
-    min:      { control: 'text' },
-    max:      { control: 'text' },
-    disabled: { control: 'boolean' },
+    value:          { control: 'text' },
+    min:            { control: 'text' },
+    max:            { control: 'text' },
+    disabled:       { control: 'boolean' },
+    months:         { control: 'number' },
+    firstDayOfWeek: { control: 'number' },
+    locale:         { control: 'text' },
   },
 } satisfies Meta<typeof BdsCalendar>;
 
@@ -46,6 +42,8 @@ export const WithMinMax: Story = {
   args: { value: '2026-04-10', min: '2026-04-05', max: '2026-04-25' },
 };
 export const Disabled: Story = { args: { value: '2026-04-10', disabled: true } };
+export const TwoMonths: Story = { args: { value: '2026-04-15', months: 2 } };
+export const DutchLocale: Story = { args: { value: '2026-04-15', locale: 'nl-NL', firstDayOfWeek: 1 } };
 export const FormField: Story = {
   render: () => (
     <form