@boostdev/design-system-components 2.8.0 → 2.11.0

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

@@ -3,19 +3,19 @@ import type { Meta, StoryObj } from '@storybook/react';
 import '../index'; // auto-registers all custom elements
 
 function BdsSectionHeader({
-  title = '',
+  heading = '',
   subtitle,
   alignment = 'start',
   size = 'medium',
   titleAs,
 }: {
-  title?: string;
+  heading?: string;
   subtitle?: string;
   alignment?: 'start' | 'center' | 'end';
-  size?: 'small' | 'medium' | 'large';
+  size?: 'xs' | 'small' | 'medium' | 'large';
   titleAs?: string;
 }) {
-  return React.createElement('bds-section-header', { title, subtitle, alignment, size, 'title-as': titleAs });
+  return React.createElement('bds-section-header', { heading, subtitle, alignment, size, 'title-as': titleAs });
 }
 
 const meta = {
@@ -25,7 +25,7 @@ const meta = {
   parameters: { layout: 'padded' },
   argTypes: {
     alignment: { control: 'select', options: ['start', 'center', 'end'] },
-    size:      { control: 'select', options: ['small', 'medium', 'large'] },
+    size:      { control: 'select', options: ['xs', 'small', 'medium', 'large'] },
     titleAs:   { control: 'text' },
   },
 } satisfies Meta<typeof BdsSectionHeader>;
@@ -34,21 +34,23 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {
-  args: { title: 'Our Products', subtitle: 'Browse the full range', size: 'medium', alignment: 'start' },
+  args: { heading: 'Our Products', subtitle: 'Browse the full range', size: 'medium', alignment: 'start' },
 };
-export const Small: Story = { args: { title: 'Recent Activity', subtitle: 'Last 30 days', size: 'small' } };
-export const Large: Story = { args: { title: 'Welcome Back', subtitle: 'Here is what happened today', size: 'large' } };
+export const ExtraSmall: Story = { args: { heading: 'Filters', subtitle: 'Refine the results', size: 'xs' } };
+export const Small: Story = { args: { heading: 'Recent Activity', subtitle: 'Last 30 days', size: 'small' } };
+export const Large: Story = { args: { heading: 'Welcome Back', subtitle: 'Here is what happened today', size: 'large' } };
 export const Centered: Story = {
-  args: { title: 'Our Mission', subtitle: 'We are building something great', alignment: 'center' },
+  args: { heading: 'Our Mission', subtitle: 'We are building something great', alignment: 'center' },
 };
-export const TitleOnly: Story = { args: { title: 'Settings', size: 'small' } };
+export const TitleOnly: Story = { args: { heading: 'Settings', size: 'small' } };
 
 export const AllSizes: Story = {
   render: () => (
     <div style={{ display: 'flex', flexDirection: 'column', gap: 32 }}>
-      {React.createElement('bds-section-header', { title: 'Small Heading', subtitle: 'Subtitle text', size: 'small' })}
-      {React.createElement('bds-section-header', { title: 'Medium Heading', subtitle: 'Subtitle text', size: 'medium' })}
-      {React.createElement('bds-section-header', { title: 'Large Heading', subtitle: 'Subtitle text', size: 'large' })}
+      {React.createElement('bds-section-header', { heading: 'Extra Small Heading', subtitle: 'Subtitle text', size: 'xs' })}
+      {React.createElement('bds-section-header', { heading: 'Small Heading', subtitle: 'Subtitle text', size: 'small' })}
+      {React.createElement('bds-section-header', { heading: 'Medium Heading', subtitle: 'Subtitle text', size: 'medium' })}
+      {React.createElement('bds-section-header', { heading: 'Large Heading', subtitle: 'Subtitle text', size: 'large' })}
     </div>
   ),
 };

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

@@ -9,6 +9,13 @@ Framework-agnostic scrollable Table wrapper custom element. Apply design-system
 
 > **Status: experimental** — API may change before stable release.
 
+> **Light-DOM styling contract:** `::slotted()` can only match the node placed directly into
+> the slot (the `<table>` itself), never its descendants. `<thead>`/`<th>`/`<td>` styling is
+> therefore shipped as a document-level stylesheet scoped to the `bds-table > table …` selector
+> (adopted once, the first time any `<bds-table>` module is imported). This means the slotted
+> `<table>` must be a **direct child** of `<bds-table>` for cell styling and `sticky-header` to
+> apply — don't wrap it in an intermediate element.
+
 ## Installation
 
 ```js
@@ -37,12 +44,21 @@ import '@boostdev/design-system-components/web-components';
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `sticky-header` | boolean | `false` | Freezes `<thead>` at the top when the table overflows vertically |
+| `aria-label` | string | — | Accessible name for the scrollable region; also enables `role="region"` on the wrapper |
 
 ## Slots
 
 | Slot | Description |
 |------|-------------|
-| `(default)` | A standard `<table>` element with `<thead>` and `<tbody>` |
+| `(default)` | A standard `<table>` element (must be a direct child — see the light-DOM styling contract above) |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--table_border` | Wrapper border (default: `none`) |
+| `--table_radius` | Wrapper corner radius (default: `var(--bdc-outline_radius)`, itself set to `var(--bds-border_radius--s)` on the wrapper) |
+| `--table_row-bg--hover` | Row background on hover, pointer devices only (default: `var(--bds-color_bg--subtle)`) |
 
 ## Usage in plain HTML
 
@@ -78,4 +94,9 @@ import '@boostdev/design-system-components/web-components';
 
 - Use a standard `<table>` with proper `<thead>` / `<tbody>` structure
 - Column headers (`<th>`) are automatically styled; add `scope="col"` for complex tables
-- The wrapper is horizontally scrollable (`overflow-inline: auto`) on small viewports
+- The wrapper is horizontally scrollable (`overflow-inline: auto`) on small viewports and is
+  keyboard-focusable (`tabindex="0"`) with a `:focus-visible` outline, so it can be scrolled
+  without a mouse in browsers that don't auto-focus scroll containers
+- Set `aria-label` on `<bds-table>` to give the scrollable region an accessible name — this also
+  adds `role="region"` on the wrapper; without it, the wrapper stays unlabelled and roleless to
+  avoid a nameless landmark

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

@@ -4,14 +4,16 @@ import '../index'; // auto-registers all custom elements
 
 function BdsTable({
   stickyHeader,
+  ariaLabel,
   children,
 }: {
   stickyHeader?: boolean;
+  ariaLabel?: string;
   children?: React.ReactNode;
 }) {
   return React.createElement(
     'bds-table',
-    { 'sticky-header': stickyHeader || undefined },
+    { 'sticky-header': stickyHeader || undefined, 'aria-label': ariaLabel },
     children,
   );
 }
@@ -77,7 +79,11 @@ export const Default: Story = {
 export const StickyHeader: Story = {
   render: () => (
     <div style={{ padding: 24, maxHeight: 200, overflow: 'auto' }}>
-      {React.createElement('bds-table', { 'sticky-header': true }, sampleTable())}
+      {React.createElement(
+        'bds-table',
+        { 'sticky-header': true, 'aria-label': 'Team members' },
+        sampleTable(),
+      )}
     </div>
   ),
 };

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

@@ -52,7 +52,7 @@ import '@boostdev/design-system-components/web-components';
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `variant` | `"h1" \| "h2" \| "h3" \| "body" \| "body_s"` | `"body"` | Visual style and default semantic tag |
-| `component` | string | — | Override the rendered HTML tag (e.g. `"span"`, `"label"`) |
+| `component` | string | — | Override the rendered HTML tag (e.g. `"span"`, `"label"`). Reflects to the host attribute, so it also works when set as a JS property (e.g. from React). |
 
 ## Slots
 
@@ -60,6 +60,17 @@ import '@boostdev/design-system-components/web-components';
 |------|-------------|
 | `(default)` | Text content |
 
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--typography_color` | Text colour (default: `--bds-color_on-bg`) |
+| `--typography_font-size--h1` | Font size for the `h1` variant (default: `--bds-font_size--heading-1`) |
+| `--typography_font-size--h2` | Font size for the `h2` variant (default: `--bds-font_size--heading-2`) |
+| `--typography_font-size--h3` | Font size for the `h3` variant (default: `--bds-font_size--heading-3`) |
+| `--typography_font-size--body` | Font size for the `body` variant (default: `--bds-font_size--body`) |
+| `--typography_font-size--body_s` | Font size for the `body_s` variant (default: `--bds-font_size--body--s`) |
+
 ## Usage in plain HTML
 
 ```html
@@ -68,6 +79,11 @@ import '@boostdev/design-system-components/web-components';
 <bds-typography variant="body_s" component="span">Small helper text</bds-typography>
 ```
 
+## Layout
+
+- The host is `display: block` by default (headings and paragraphs are block-level elements).
+- `component="span"` switches the host to `display: inline` so the element flows inline like a native `<span>`. Other inline tag overrides (e.g. `"label"`) still need host restyling if inline flow is required.
+
 ## Accessibility
 
 - Uses semantic heading elements (`h1`–`h3`) or `<p>` by default

package/src/web-components/ui/bds-alert.spec.ts

@@ -51,7 +51,15 @@ describe('bds-alert', () => {
     cleanup(el);
   });
 
-  it('renders title when title attribute is set', async () => {
+  it('renders heading when heading attribute is set', async () => {
+    const el = await fixture('<bds-alert heading="Heads up">Message</bds-alert>');
+    const strong = el.shadowRoot!.querySelector('strong.title');
+    expect(strong).not.toBeNull();
+    expect(strong!.textContent).toBe('Heads up');
+    cleanup(el);
+  });
+
+  it('renders heading text from the deprecated title attribute as a fallback', async () => {
     const el = await fixture('<bds-alert title="Heads up">Message</bds-alert>');
     const strong = el.shadowRoot!.querySelector('strong.title');
     expect(strong).not.toBeNull();
@@ -59,7 +67,14 @@ describe('bds-alert', () => {
     cleanup(el);
   });
 
-  it('does not render title element when title is not set', async () => {
+  it('prefers heading over the deprecated title attribute when both are set', async () => {
+    const el = await fixture('<bds-alert heading="New" title="Old">Message</bds-alert>');
+    const strong = el.shadowRoot!.querySelector('strong.title');
+    expect(strong!.textContent).toBe('New');
+    cleanup(el);
+  });
+
+  it('does not render title element when neither heading nor title is set', async () => {
     const el = await fixture('<bds-alert>Message</bds-alert>');
     const strong = el.shadowRoot!.querySelector('strong.title');
     expect(strong).toBeNull();

package/src/web-components/ui/bds-alert.ts

@@ -7,7 +7,11 @@ export type AlertVariant = 'info' | 'success' | 'warning' | 'error';
  *
  * Attributes:
  *   variant     — "info" (default) | "success" | "warning" | "error"
- *   title       — optional heading above the body text
+ *   heading     — optional heading above the body text
+ *   title       — deprecated alias for `heading`. Collides with the global HTML
+ *                 `title` attribute, which triggers a native browser tooltip on
+ *                 hover — use `heading` instead. Kept working for backwards
+ *                 compatibility; will be removed in a later major.
  *   dismissible — boolean; shows a dismiss button when present
  *
  * Slots:
@@ -22,7 +26,7 @@ export type AlertVariant = 'info' | 'success' | 'warning' | 'error';
  *   role="status" + aria-live="polite" for info/success variants.
  *
  * @example
- * <bds-alert variant="success" title="Saved!">Your changes have been saved.</bds-alert>
+ * <bds-alert variant="success" heading="Saved!">Your changes have been saved.</bds-alert>
  *
  * <bds-alert variant="error" dismissible>
  *   <svg slot="icon">…</svg>
@@ -31,6 +35,16 @@ export type AlertVariant = 'info' | 'success' | 'warning' | 'error';
  */
 export class BdsAlert 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;
     }
@@ -119,8 +133,8 @@ export class BdsAlert extends LitElement {
     }
 
     .dismiss svg {
-      width: 1rem;
-      height: 1rem;
+      inline-size: 1rem;
+      block-size: 1rem;
     }
 
     .dismiss:focus-visible {
@@ -137,6 +151,7 @@ export class BdsAlert extends LitElement {
 
   static properties = {
     variant:     { type: String, reflect: true },
+    heading:     { type: String },
     title:       { type: String },
     dismissible: { type: Boolean, reflect: true },
     _iconFilled: { state: true },
@@ -145,6 +160,12 @@ export class BdsAlert extends LitElement {
   // `declare` annotates the type without emitting a class field initializer
   // that would shadow Lit's reactive accessors on the prototype.
   declare variant: AlertVariant;
+  declare heading: string;
+  /**
+   * @deprecated Use `heading` instead. Sharing the name with the global HTML
+   * `title` attribute makes the browser show a native tooltip on hover.
+   * Still read as a fallback for the heading text when `heading` is unset.
+   */
   declare title: string;
   declare dismissible: boolean;
   declare private _iconFilled: boolean;
@@ -152,11 +173,16 @@ export class BdsAlert extends LitElement {
   constructor() {
     super();
     this.variant = 'info';
+    this.heading = '';
     this.title = '';
     this.dismissible = false;
     this._iconFilled = false;
   }
 
+  private get _headingText() {
+    return this.heading || this.title;
+  }
+
   private _onIconSlotChange(e: Event) {
     const slot = e.target as HTMLSlotElement;
     this._iconFilled = slot.assignedNodes({ flatten: true }).length > 0;
@@ -182,7 +208,7 @@ export class BdsAlert extends LitElement {
           <slot name="icon" @slotchange=${this._onIconSlotChange}></slot>
         </span>
         <div class="content">
-          ${this.title ? html`<strong class="title">${this.title}</strong>` : nothing}
+          ${this._headingText ? html`<strong class="title">${this._headingText}</strong>` : nothing}
           <div><slot></slot></div>
         </div>
         ${this.dismissible

package/src/web-components/ui/bds-avatar.spec.ts

@@ -72,4 +72,33 @@ describe('bds-avatar', () => {
     expect(el.getAttribute('size')).toBe('large');
     cleanup(el);
   });
+
+  it('preserves an explicit empty alt="" as decorative (does not fall back to name)', async () => {
+    const el = await fixture('<bds-avatar src="/photo.jpg" alt="" name="Jane Doe"></bds-avatar>');
+    const img = el.shadowRoot!.querySelector('img');
+    expect(img!.getAttribute('alt')).toBe('');
+    cleanup(el);
+  });
+
+  it('falls back to name when alt attribute is entirely absent', async () => {
+    const el = await fixture('<bds-avatar src="/photo.jpg" name="Jane Doe"></bds-avatar>');
+    const img = el.shadowRoot!.querySelector('img');
+    expect(img!.hasAttribute('alt')).toBe(true);
+    expect(img!.getAttribute('alt')).toBe('Jane Doe');
+    cleanup(el);
+  });
+
+  it('size selectors write to the --avatar_size--variant slot, not the public --avatar_size token (ancestor overrides stay effective)', () => {
+    const cssText = BdsAvatar.styles.cssText;
+    expect(cssText).toMatch(
+      /inline-size:\s*var\(--avatar_size,\s*var\(--avatar_size--variant,\s*3em\)\)/,
+    );
+    expect(cssText).toMatch(
+      /block-size:\s*var\(--avatar_size,\s*var\(--avatar_size--variant,\s*3em\)\)/,
+    );
+    expect(cssText).toMatch(/:host\(\[size='small'\]\)\s*\{\s*--avatar_size--variant:\s*2em;/);
+    expect(cssText).toMatch(/:host\(\[size='large'\]\)\s*\{\s*--avatar_size--variant:\s*4\.5em;/);
+    // The public --avatar_size token itself must never be set directly by a size selector.
+    expect(cssText).not.toMatch(/:host\(\[size=[^)]*\]\)\s*\{\s*--avatar_size:/);
+  });
 });

package/src/web-components/ui/bds-avatar.ts

@@ -7,7 +7,8 @@ import { LitElement, css, html, nothing } from 'lit';
  *
  * Attributes:
  *   src  — image URL
- *   alt  — image alt text (defaults to `name` or "User avatar")
+ *   alt  — image alt text (defaults to `name` or "User avatar"). Set alt=""
+ *          explicitly to mark the image as decorative (silences the accessible name).
  *   name — full name; used to compute initials and as fallback aria-label
  *   size — "small" | "medium" (default) | "large"
  *
@@ -17,20 +18,34 @@ import { LitElement, css, html, nothing } from 'lit';
  */
 export class BdsAvatar 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: inline-flex;
       align-items: center;
       justify-content: center;
-      inline-size: var(--avatar_size, 3em);
-      block-size: var(--avatar_size, 3em);
+      /* Layered cascade (mirrors the React Avatar): a public --avatar_size
+         override wins over the per-size-variant default. Size selectors
+         below write --avatar_size--variant only, so an ancestor setting
+         --avatar_size still cascades correctly. */
+      inline-size: var(--avatar_size, var(--avatar_size--variant, 3em));
+      block-size: var(--avatar_size, var(--avatar_size--variant, 3em));
       border-radius: var(--avatar_radius, var(--bds-border_radius--circle));
       overflow: hidden;
       flex-shrink: 0;
     }
 
-    :host([size='small'])  { --avatar_size: 2em; }
-    :host([size='medium']) { --avatar_size: 3em; }
-    :host([size='large'])  { --avatar_size: 4.5em; }
+    :host([size='small'])  { --avatar_size--variant: 2em; }
+    :host([size='medium']) { --avatar_size--variant: 3em; }
+    :host([size='large'])  { --avatar_size--variant: 4.5em; }
 
     .fallback {
       display: inline-flex;
@@ -92,11 +107,14 @@ export class BdsAvatar extends LitElement {
 
   render() {
     if (this.src) {
-      return html`<img
-        class="image"
-        src=${this.src}
-        alt=${this.alt || this.name || 'User avatar'}
-      />`;
+      // An explicit alt="" attribute marks the image as decorative and must
+      // be preserved as-is — only substitute name/"User avatar" when the
+      // attribute was never provided (this.alt otherwise defaults to '').
+      const altText = this.hasAttribute('alt')
+        ? this.alt
+        : this.name || 'User avatar';
+
+      return html`<img class="image" src=${this.src} alt=${altText} />`;
     }
 
     return html`

package/src/web-components/ui/bds-badge.spec.ts

@@ -48,4 +48,9 @@ describe('bds-badge', () => {
       cleanup(el);
     }
   });
+
+  it('falls back --badge_radius to the pill token, matching the React counterpart', () => {
+    const cssText = BdsBadge.styles.cssText;
+    expect(cssText).toMatch(/border-radius:\s*var\(--badge_radius,\s*var\(--bds-border_radius--full\)\)/);
+  });
 });

package/src/web-components/ui/bds-badge.ts

@@ -16,6 +16,16 @@ export type BadgeVariant = 'primary' | 'secondary' | 'success' | 'error' | 'warn
  */
 export class BdsBadge 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: inline-flex;
     }
@@ -25,7 +35,7 @@ export class BdsBadge extends LitElement {
       align-items: center;
       justify-content: center;
       padding: var(--bds-space_xxs) var(--bds-space_xs);
-      border-radius: var(--badge_radius, 2em);
+      border-radius: var(--badge_radius, var(--bds-border_radius--full));
       font-size: var(--badge_font-size, var(--bds-font_size--body--s));
       font-weight: var(--bds-font_weight--semibold);
       line-height: 1;

package/src/web-components/ui/bds-breadcrumb.spec.ts

@@ -52,4 +52,34 @@ describe('bds-breadcrumb', () => {
     expect(separators.length).toBe(2); // between each pair
     cleanup(el);
   });
+
+  it('falls back to an empty list instead of crashing when items is null', async () => {
+    const el = await fixture('<bds-breadcrumb></bds-breadcrumb>') as BdsBreadcrumb;
+    // Simulates what Lit's default Array attribute converter produces for
+    // malformed JSON or a removed attribute: it returns null, not [].
+    (el as unknown as { items: unknown }).items = null;
+    await el.updateComplete;
+    const items = el.shadowRoot!.querySelectorAll('.item');
+    expect(items.length).toBe(0);
+    cleanup(el);
+  });
+
+  it('recovers from malformed items JSON set via the attribute', async () => {
+    const el = await fixture('<bds-breadcrumb items="not valid json"></bds-breadcrumb>') as BdsBreadcrumb;
+    const items = el.shadowRoot!.querySelectorAll('.item');
+    expect(items.length).toBe(0);
+    cleanup(el);
+  });
+
+  it('renders non-last items without href as non-interactive text, not a href="#" link', async () => {
+    const el = await fixture('<bds-breadcrumb></bds-breadcrumb>') as BdsBreadcrumb;
+    el.items = [{ label: 'Home' }, { label: 'Current' }];
+    await el.updateComplete;
+    const link = el.shadowRoot!.querySelector('a.link');
+    expect(link).toBeNull();
+    const text = el.shadowRoot!.querySelector('.text');
+    expect(text).not.toBeNull();
+    expect(text!.textContent).toBe('Home');
+    cleanup(el);
+  });
 });

package/src/web-components/ui/bds-breadcrumb.ts

@@ -10,13 +10,25 @@ export interface BreadcrumbItem {
  *
  * Attributes:
  *   items — JSON string array of `{ label: string, href?: string }` objects.
- *           The last item is treated as the current page (no link).
+ *           The last item is treated as the current page (no link). Any other
+ *           item without an `href` renders as plain text instead of a link.
+ *           Malformed JSON (or a removed attribute) falls back to `[]`.
  *
  * @example
  * <bds-breadcrumb items='[{"label":"Home","href":"/"},{"label":"Products","href":"/products"},{"label":"Item"}]'></bds-breadcrumb>
  */
 export class BdsBreadcrumb 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;
     }
@@ -65,6 +77,10 @@ export class BdsBreadcrumb extends LitElement {
       user-select: none;
     }
 
+    .text {
+      color: var(--bds-color_on-bg--subtle);
+    }
+
     .current {
       color: var(--bds-color_on-bg--subtle);
       font-weight: var(--bds-font_weight--semibold);
@@ -83,17 +99,23 @@ export class BdsBreadcrumb extends LitElement {
   }
 
   render() {
+    // this.items may be null: the Lit default Array/Object attribute
+    // converter returns null (rather than throwing) both for malformed
+    // JSON and for a removed attribute — fall back to an empty list.
+    const items = this.items ?? [];
     return html`
       <nav class="breadcrumb" aria-label="Breadcrumb">
         <ol class="list">
-          ${this.items.map((item, index) => {
-            const isLast = index === this.items.length - 1;
+          ${items.map((item, index) => {
+            const isLast = index === items.length - 1;
             return html`
               <li class="item">
                 ${isLast
                   ? html`<span class="current" aria-current="page">${item.label}</span>`
                   : html`
-                      <a class="link" href=${item.href ?? '#'}>${item.label}</a>
+                      ${item.href
+                        ? html`<a class="link" href=${item.href}>${item.label}</a>`
+                        : html`<span class="text">${item.label}</span>`}
                       <span class="separator" aria-hidden="true">›</span>
                     `}
               </li>

package/src/web-components/ui/bds-button-container.spec.ts

@@ -0,0 +1,39 @@
+import { fixture, cleanup } from '../test/helpers';
+import { BdsButtonContainer } from './bds-button-container';
+
+describe('bds-button-container', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-button-container')).toBe(BdsButtonContainer);
+  });
+
+  it('renders a group role element wrapping a slot', async () => {
+    const el = await fixture('<bds-button-container>content</bds-button-container>');
+    const group = el.shadowRoot!.querySelector('[role="group"]')!;
+    expect(group).not.toBeNull();
+    expect(group.querySelector('slot')).not.toBeNull();
+    cleanup(el);
+  });
+
+  it('reflects the variant attribute', async () => {
+    const el = await fixture(
+      '<bds-button-container variant="modal">content</bds-button-container>',
+    ) as BdsButtonContainer;
+    expect(el.variant).toBe('modal');
+    expect(el.getAttribute('variant')).toBe('modal');
+    cleanup(el);
+  });
+
+  it('forwards aria-label to the group', async () => {
+    const el = await fixture('<bds-button-container aria-label="Dialog actions">x</bds-button-container>');
+    const group = el.shadowRoot!.querySelector('[role="group"]')!;
+    expect(group.getAttribute('aria-label')).toBe('Dialog actions');
+    cleanup(el);
+  });
+
+  it('omits aria-label when unset', async () => {
+    const el = await fixture('<bds-button-container>x</bds-button-container>');
+    const group = el.shadowRoot!.querySelector('[role="group"]')!;
+    expect(group.hasAttribute('aria-label')).toBe(false);
+    cleanup(el);
+  });
+});