@boostdev/design-system-components 2.7.1 → 2.11.0

package/src/web-components/interaction/bds-toast-provider.spec.ts

@@ -119,4 +119,47 @@ describe('bds-toast-provider', () => {
     expect(el.shadowRoot!.querySelectorAll('.toast').length).toBe(2);
     cleanup(el);
   });
+
+  it('updated() does not throw when showPopover() reports an already-open popover (regression)', async () => {
+    // jsdom does not implement the Popover API, so showPopover/hidePopover are
+    // undefined on real elements in tests — mock them to reproduce the real-browser
+    // InvalidStateError that fires when showPopover() is called on an already-open
+    // popover (e.g. a 2nd/3rd toast joining the queue while the popover is showing).
+    const el = await fixture('<bds-toast-provider></bds-toast-provider>') as BdsToastProvider;
+    el.showToast('First', 'info');
+    await el.updateComplete;
+    const container = el.shadowRoot!.querySelector('[popover="manual"]') as HTMLElement & {
+      showPopover?: () => void;
+    };
+    container.showPopover = vi.fn(() => {
+      throw new DOMException('Invalid state', 'InvalidStateError');
+    });
+    expect(() => (el as unknown as { updated: () => void }).updated()).not.toThrow();
+    expect(container.showPopover).toHaveBeenCalledTimes(1);
+    cleanup(el);
+  });
+
+  it('variant rules write --toast_color--variant, not the public --toast_color hook (cascade parity)', () => {
+    const cssText = BdsToastProvider.styles.cssText;
+    // Variants must only set the inner slot so a consumer-set --toast_color still
+    // wins the cascade (element-level declarations otherwise beat inherited values).
+    expect(cssText).toMatch(/\.toast\.--variant_error\s*{[^}]*--toast_color--variant:\s*var\(--toast_color--error, var\(--bds-color_error\)\)/);
+    expect(cssText).not.toMatch(/\.toast\.--variant_error\s*{[^}]*--toast_color:\s*var\(--bds-color_error\)/);
+    expect(cssText).toMatch(/background-color:\s*var\(--toast_color,\s*var\(--toast_color--variant,\s*var\(--bds-color_bg\)\)\);/);
+  });
+
+  it('close button expands its hit area to >=44px via the ::after pseudo-element (touch target)', () => {
+    const cssText = BdsToastProvider.styles.cssText;
+    expect(cssText).toMatch(/\.close::after\s*{[^}]*inset:\s*-0\.75rem;/);
+  });
+
+  it('container/toast/close use logical properties, not physical ones', () => {
+    const cssText = BdsToastProvider.styles.cssText;
+    expect(cssText).toMatch(/inset-block-end:\s*var\(--bds-space_xl,\s*2rem\);/);
+    expect(cssText).toMatch(/inset-inline-end:\s*var\(--bds-space_xl,\s*2rem\);/);
+    expect(cssText).not.toMatch(/\n\s*bottom:/);
+    expect(cssText).not.toMatch(/\n\s*right:/);
+    expect(cssText).not.toMatch(/\bwidth:\s*1\.25rem/);
+    expect(cssText).not.toMatch(/\bheight:\s*1\.25rem/);
+  });
 });

package/src/web-components/interaction/bds-toast-provider.ts

@@ -38,6 +38,16 @@ interface ToastEntry {
  */
 export class BdsToastProvider 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: contents;
     }
@@ -46,8 +56,8 @@ export class BdsToastProvider extends LitElement {
       /* Reset UA popover defaults */
       position: fixed;
       inset: unset;
-      bottom: var(--bds-space_xl, 2rem);
-      right: var(--bds-space_xl, 2rem);
+      inset-block-end: var(--bds-space_xl, 2rem);
+      inset-inline-end: var(--bds-space_xl, 2rem);
       display: flex;
       flex-direction: column;
       gap: var(--bds-space_m, 1rem);
@@ -58,34 +68,36 @@ export class BdsToastProvider extends LitElement {
 
     .toast {
       padding: var(--bds-space_m) var(--bds-space_l);
-      background-color: var(--toast_color, var(--bds-color_bg));
-      color: var(--toast_on-color, var(--bds-color_on-bg));
-      border-radius: var(--bds-border_radius--s);
-      box-shadow: var(--bds-shadow_s);
+      /* Layered cascade: public overrides (--toast_color, --toast_on-color) win
+         over per-variant defaults. Variants write to the inner --toast_*--variant slot. */
+      background-color: var(--toast_color, var(--toast_color--variant, var(--bds-color_bg)));
+      color: var(--toast_on-color, var(--toast_on-color--variant, var(--bds-color_on-bg)));
+      border-radius: var(--toast_radius, var(--bds-border_radius--s));
+      box-shadow: var(--toast_shadow, var(--bds-shadow_s));
       display: flex;
       align-items: center;
       gap: var(--bds-space_m);
-      min-width: 300px;
+      min-inline-size: min(300px, calc(100svw - 2 * var(--bds-space_xl)));
     }
 
     .toast.--variant_success {
-      --toast_color:    var(--bds-color_success);
-      --toast_on-color: var(--bds-color_on-success);
+      --toast_color--variant:    var(--toast_color--success, var(--bds-color_success));
+      --toast_on-color--variant: var(--toast_on-color--success, var(--bds-color_on-success));
     }
 
     .toast.--variant_warning {
-      --toast_color:    var(--bds-color_warning);
-      --toast_on-color: var(--bds-color_on-warning);
+      --toast_color--variant:    var(--toast_color--warning, var(--bds-color_warning));
+      --toast_on-color--variant: var(--toast_on-color--warning, var(--bds-color_on-warning));
     }
 
     .toast.--variant_info {
-      --toast_color:    var(--bds-color_bg--subtle);
-      --toast_on-color: var(--bds-color_on-bg--subtle);
+      --toast_color--variant:    var(--toast_color--info, var(--bds-color_bg--subtle));
+      --toast_on-color--variant: var(--toast_on-color--info, var(--bds-color_on-bg--subtle));
     }
 
     .toast.--variant_error {
-      --toast_color:    var(--bds-color_error);
-      --toast_on-color: var(--bds-color_on-error);
+      --toast_color--variant:    var(--toast_color--error, var(--bds-color_error));
+      --toast_on-color--variant: var(--toast_on-color--error, var(--bds-color_on-error));
     }
 
     .message {
@@ -93,22 +105,35 @@ export class BdsToastProvider extends LitElement {
     }
 
     .close {
+      position: relative;
       display: flex;
       align-items: center;
       justify-content: center;
       flex-shrink: 0;
-      width: 1.25rem;
-      height: 1.25rem;
+      inline-size: 1.25rem;
+      block-size: 1.25rem;
       padding: 0;
       background: none;
       border: none;
       cursor: pointer;
-      color: var(--toast_on-color);
+      color: currentcolor;
+    }
+
+    /* Expands the hit area to >=44px (WCAG 2.5.5) without growing the visible icon. */
+    .close::after {
+      content: '';
+      position: absolute;
+      inset: -0.75rem;
+    }
+
+    .close:focus-visible {
+      outline: var(--bds-outline_default);
+      outline-offset: var(--bds-outline_offset);
     }
 
     .close svg {
-      width: 1rem;
-      height: 1rem;
+      inline-size: 1rem;
+      block-size: 1rem;
     }
   `;
 
@@ -135,6 +160,10 @@ export class BdsToastProvider extends LitElement {
 
   // Sync the popover's top-layer visibility with the toast queue —
   // mirrors Toast.tsx's useEffect([toasts.length]).
+  // Both showPopover() and hidePopover() throw an InvalidStateError when called
+  // in a redundant state (e.g. showPopover() while a 2nd/3rd toast is queued and
+  // the popover is already open, or hidePopover() before any toast has shown) —
+  // catch silently in both directions.
   updated() {
     const container = this.shadowRoot?.querySelector<HTMLElement & {
       showPopover?: () => void;
@@ -142,7 +171,7 @@ export class BdsToastProvider extends LitElement {
     }>('[popover]');
     if (!container) return;
     if (this._toasts.length > 0) {
-      container.showPopover?.();
+      try { container.showPopover?.(); } catch { /* already open */ }
     } else {
       try { container.hidePopover?.(); } catch { /* already hidden on initial mount */ }
     }

package/src/web-components/interaction/bds-tooltip.spec.ts

@@ -46,4 +46,75 @@ describe('bds-tooltip', () => {
     expect(el.querySelector('button')!.textContent).toBe('Help');
     cleanup(el);
   });
+
+  it('associates the trigger with the tooltip content via aria-describedby', async () => {
+    const el = await fixture('<bds-tooltip content="Helpful text"><button type="button">?</button></bds-tooltip>');
+    // Wait for the deferred connectedCallback wiring (Promise.resolve().then(...)).
+    await Promise.resolve();
+    await Promise.resolve();
+
+    const trigger = el.querySelector('button')!;
+    const describedById = trigger.getAttribute('aria-describedby');
+    expect(describedById).toBeTruthy();
+
+    const descEl = el.querySelector(`#${describedById}`);
+    expect(descEl).not.toBeNull();
+    expect(descEl!.textContent).toBe('Helpful text');
+    // The description node must live in the light DOM (same tree scope as the
+    // trigger) — aria-describedby cannot reference an id inside the shadow root.
+    expect(descEl!.getRootNode()).toBe(document);
+    cleanup(el);
+  });
+
+  it('keeps a consumer-provided aria-describedby alongside the generated one', async () => {
+    const el = await fixture(
+      '<bds-tooltip content="Tip"><button type="button" aria-describedby="external-hint">?</button></bds-tooltip>',
+    );
+    await Promise.resolve();
+    await Promise.resolve();
+
+    const trigger = el.querySelector('button')!;
+    const ids = trigger.getAttribute('aria-describedby')!.split(/\s+/);
+    expect(ids).toContain('external-hint');
+    expect(ids.length).toBe(2);
+    cleanup(el);
+  });
+
+  it('updates the hidden description text when content changes', async () => {
+    const el = await fixture('<bds-tooltip content="First"><button type="button">?</button></bds-tooltip>') as BdsTooltip;
+    await Promise.resolve();
+    await Promise.resolve();
+
+    el.content = 'Second';
+    await el.updateComplete;
+
+    const trigger = el.querySelector('button')!;
+    const describedById = trigger.getAttribute('aria-describedby')!;
+    const descEl = el.querySelector(`#${describedById}`);
+    expect(descEl!.textContent).toBe('Second');
+    cleanup(el);
+  });
+
+  it('does not add aria-describedby when content is empty', async () => {
+    const el = await fixture('<bds-tooltip><button type="button">?</button></bds-tooltip>');
+    await Promise.resolve();
+    await Promise.resolve();
+
+    const trigger = el.querySelector('button')!;
+    expect(trigger.hasAttribute('aria-describedby')).toBe(false);
+    cleanup(el);
+  });
+
+  it('hides the shadow-DOM tooltip bubble from assistive technology', async () => {
+    const el = await fixture('<bds-tooltip content="Helpful text"><button type="button">?</button></bds-tooltip>');
+    const tooltip = el.shadowRoot!.querySelector('[role="tooltip"]')!;
+    expect(tooltip.getAttribute('aria-hidden')).toBe('true');
+    cleanup(el);
+  });
+
+  it('does not hardcode a z-index fallback (token parity with React Tooltip)', () => {
+    const cssText = BdsTooltip.styles.cssText;
+    expect(cssText).toMatch(/z-index:\s*var\(--bds-z-index_popover\);/);
+    expect(cssText).not.toContain('200');
+  });
 });

package/src/web-components/interaction/bds-tooltip.ts

@@ -16,9 +16,14 @@ export type TooltipPlacement = 'top' | 'bottom' | 'left' | 'right';
  *   (default) — the trigger element (button, icon, etc.)
  *
  * Accessibility:
- *   The `aria-describedby` relationship between trigger and tooltip panel
- *   cannot cross shadow DOM boundaries; screen readers will announce the tooltip
- *   via role="tooltip" proximity when it becomes visible.
+ *   `aria-describedby` id references only resolve within the same tree scope, so a
+ *   slotted (light-DOM) trigger can never reference an id that lives inside this
+ *   element's shadow root. To keep the description reachable, a visually-hidden
+ *   `<span>` holding `content` is appended as a light-DOM child of the host and its
+ *   id is written into `aria-describedby` on the slotted trigger — both elements then
+ *   share the light DOM's tree scope, so the reference resolves in every browser. The
+ *   shadow-DOM tooltip bubble stays `aria-hidden="true"`; it is purely the visual
+ *   presentation, shown on `:hover`/`:focus-within`.
  *
  * @example
  * <bds-tooltip content="More information" placement="bottom">
@@ -27,6 +32,16 @@ export type TooltipPlacement = 'top' | 'bottom' | 'left' | 'right';
  */
 export class BdsTooltip 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;
@@ -35,7 +50,7 @@ export class BdsTooltip extends LitElement {
 
     .tooltip {
       position: absolute;
-      z-index: var(--bds-z-index_popover, 200);
+      z-index: var(--bds-z-index_popover);
       padding: var(--bds-space_xxs) var(--bds-space_xs);
       border-radius: var(--tooltip_radius, var(--bds-border_radius--full));
       background-color: var(--tooltip_bg, var(--bds-color_on-bg));
@@ -101,18 +116,98 @@ export class BdsTooltip extends LitElement {
   declare content: string;
   declare placement: TooltipPlacement;
 
+  private readonly _uid = Math.random().toString(36).slice(2, 8);
+  /** Visually-hidden light-DOM node holding `content`, referenced by the trigger's aria-describedby. */
+  private _descEl: HTMLSpanElement | null = null;
+
   constructor() {
     super();
     this.content = '';
     this.placement = 'top';
   }
 
+  connectedCallback() {
+    super.connectedCallback();
+    // Deferred: on declarative parsing the trigger may not exist as a child yet
+    // when connectedCallback fires (upgrade happens before children are parsed).
+    Promise.resolve().then(this._syncDescription);
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this._teardownDescription();
+  }
+
+  updated(changed: Map<string, unknown>) {
+    super.updated(changed);
+    if (changed.has('content')) {
+      this._syncDescription();
+    }
+  }
+
+  private get _descId(): string {
+    return `bds-tooltip-desc-${this._uid}`;
+  }
+
+  /** Ensures the hidden description node exists (or is torn down) and re-wires the trigger. */
+  private _syncDescription = () => {
+    if (!this.isConnected) return;
+
+    if (!this.content) {
+      this._teardownDescription();
+      return;
+    }
+
+    let desc = this._descEl;
+    if (!desc) {
+      desc = document.createElement('span');
+      desc.id = this._descId;
+      desc.style.cssText =
+        'position:absolute;inline-size:1px;block-size:1px;overflow:hidden;clip-path:inset(50%);white-space:nowrap;';
+      this.append(desc);
+      this._descEl = desc;
+    }
+
+    desc.textContent = this.content;
+    this._describeTrigger();
+  };
+
+  private _describeTrigger() {
+    const id = this._descId;
+    for (const el of Array.from(this.children)) {
+      if (el === this._descEl) continue;
+      const existing = el.getAttribute('aria-describedby');
+      const ids = existing ? existing.split(/\s+/).filter(Boolean) : [];
+      if (!ids.includes(id)) {
+        el.setAttribute('aria-describedby', [...ids, id].join(' '));
+      }
+    }
+  }
+
+  private _teardownDescription() {
+    const id = this._descId;
+    for (const el of Array.from(this.children)) {
+      if (el === this._descEl) continue;
+      const existing = el.getAttribute('aria-describedby');
+      if (!existing) continue;
+      const ids = existing.split(/\s+/).filter(part => part && part !== id);
+      if (ids.length) {
+        el.setAttribute('aria-describedby', ids.join(' '));
+      } else {
+        el.removeAttribute('aria-describedby');
+      }
+    }
+    this._descEl?.remove();
+    this._descEl = null;
+  }
+
   render() {
     return html`
-      <slot></slot>
+      <slot @slotchange=${this._syncDescription}></slot>
       <span
         class="tooltip --placement_${this.placement}"
         role="tooltip"
+        aria-hidden="true"
       >${this.content}</span>
     `;
   }

package/src/web-components/interaction/form/BdsCheckbox.mdx

@@ -30,6 +30,9 @@ Use `<bds-checkbox>` whenever you need a single boolean toggle that participates
 ### Required
 <Canvas of={Stories.Required} />
 
+### Error
+<Canvas of={Stories.WithError} />
+
 ### Disabled
 <Canvas of={Stories.Disabled} />
 
@@ -49,6 +52,21 @@ Use `<bds-checkbox>` whenever you need a single boolean toggle that participates
 | `checked`  | boolean | `false` | Whether the checkbox is checked                  |
 | `required` | boolean | `false` | Marks the field as required                      |
 | `disabled` | boolean | `false` | Disables the checkbox                            |
+| `error`    | boolean | `false` | Puts the checkbox in an error state (border colour + `aria-invalid`) |
+
+## CSS Custom Properties
+
+| Property                    | Default                       | Description                                   |
+|------------------------------|--------------------------------|------------------------------------------------|
+| `--checkbox_color`           | `--bds-color_on-bg`            | Border/frame colour (feeds `currentcolor`)     |
+| `--checkbox_border`          | `none`                          | Real CSS `border` (in addition to the bdc inset outline) |
+| `--checkbox_radius`          | `--bdc-outline_radius` (`--bds-border_radius--xs`) | Corner radius            |
+| `--checkbox_shadow`          | `--bdc-outline_shadow`         | Extra box-shadow layered behind the inset border |
+| `--checkbox_color_bg`        | `--bds-color_bg`                | Unchecked background colour                    |
+| `--checkbox_color-active`    | `--bdc-color_active`           | Checked background colour                      |
+| `--checkbox_color-on-active` | `--bdc-color_on-active`        | Checkmark colour                               |
+
+> **Deprecated:** `--checkbox_border-color` is a legacy alias for `--checkbox_color` kept for backwards compatibility — prefer `--checkbox_color`, which matches the React `Checkbox` component's token name.
 
 ## Slots
 
@@ -71,6 +89,7 @@ Use `<bds-checkbox>` whenever you need a single boolean toggle that participates
 ## Accessibility
 
 - The inner `<input type="checkbox">` is associated with a `<label>` via matching `id`/`for` attributes
-- `required` triggers native browser validation
+- `required` triggers native browser validation; validity is recomputed both when `required` and when `checked` changes, so a required checkbox correctly unblocks form submission once checked
+- `error` sets `aria-invalid="true"` on the inner input and switches the border colour to the error token
 - `disabled` sets `pointer-events: none` and reduces opacity
 - Use `<bds-checkbox-group>` for accessible grouping with `<fieldset>`/`<legend>`

package/src/web-components/interaction/form/BdsCheckbox.stories.tsx

@@ -8,6 +8,7 @@ function BdsCheckbox({
   checked,
   required,
   disabled,
+  error,
   children,
 }: {
   name?: string;
@@ -15,6 +16,7 @@ function BdsCheckbox({
   checked?: boolean;
   required?: boolean;
   disabled?: boolean;
+  error?: boolean;
   children?: React.ReactNode;
 }) {
   return React.createElement(
@@ -25,6 +27,7 @@ function BdsCheckbox({
       checked: checked || undefined,
       required: required || undefined,
       disabled: disabled || undefined,
+      error: error || undefined,
     },
     children,
   );
@@ -39,6 +42,7 @@ const meta = {
     checked: { control: 'boolean' },
     required: { control: 'boolean' },
     disabled: { control: 'boolean' },
+    error: { control: 'boolean' },
   },
 } satisfies Meta<typeof BdsCheckbox>;
 
@@ -61,6 +65,10 @@ export const Required: Story = {
   args: { name: 'option', value: 'yes', required: true, children: 'Required field' },
 };
 
+export const WithError: Story = {
+  args: { name: 'option', value: 'yes', error: true, children: 'Something went wrong' },
+};
+
 export const WithGroup: Story = {
   render: () => (
     <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>

package/src/web-components/interaction/form/BdsCheckboxGroup.mdx

@@ -45,7 +45,7 @@ Use `<bds-checkbox-group>` when you have multiple related checkboxes that belong
 | `error`    | string  | —       | Error message shown below items; takes priority over `hint` |
 | `hint`     | string  | —       | Helper text shown below items                      |
 | `required` | boolean | `false` | Shows a required indicator on the legend           |
-| `disabled` | boolean | `false` | Disables the entire fieldset                       |
+| `disabled` | boolean | `false` | Disables the fieldset and propagates `disabled` to every slotted `<bds-checkbox>` (a checkbox individually marked `disabled` in markup stays disabled after the group re-enables) |
 
 ## Slots
 
@@ -65,6 +65,7 @@ Use `<bds-checkbox-group>` when you have multiple related checkboxes that belong
 ## Accessibility
 
 - Renders a `<fieldset>` with a `<legend>`, which is announced as a group by screen readers
-- `required` attribute adds a visual asterisk indicator to the legend
-- `disabled` on the group disables all contained checkboxes via the native `<fieldset disabled>` behaviour
+- `required` adds a visible asterisk (`aria-hidden`) plus a visually-hidden "(required)" text alternative in the legend, so requiredness is announced in the group's accessible name. `aria-required` is deliberately **not** set on the fieldset — that attribute is only supported ARIA on the `checkbox`, `combobox`, `gridcell`, `listbox`, `radiogroup`, `spinbutton`, `textbox` and `tree` roles; a bare `<fieldset>` maps to the generic `group` role (there is no ARIA `checkboxgroup` role), so assistive tech would silently ignore it
+- `disabled` on the group sets the shadow `<fieldset disabled>` **and** explicitly propagates the `disabled` attribute to every slotted `<bds-checkbox>` — a shadow-DOM `<fieldset disabled>` has no effect on slotted light-DOM custom elements on its own, so propagation happens in JS (on `disabled` change and on `slotchange`)
+- The fieldset's `aria-describedby` points at the rendered error/hint message id, so screen readers announce it as part of the group's description
 - Error messages use `role="alert"` so they are announced immediately

package/src/web-components/interaction/form/BdsCombobox.mdx

@@ -27,6 +27,12 @@ Use `<bds-combobox>` when users need to search and filter a list of options. For
 ### With disabled option
 <Canvas of={Stories.WithDisabledOption} />
 
+### With hint
+<Canvas of={Stories.WithHint} />
+
+### With error
+<Canvas of={Stories.WithError} />
+
 ### Required
 <Canvas of={Stories.Required} />
 
@@ -45,8 +51,34 @@ Use `<bds-combobox>` when users need to search and filter a list of options. For
 | `value`       | string  | `""`    | Currently selected value                                         |
 | `options`     | string  | `"[]"`  | JSON array of `{ value, label, disabled? }` option objects       |
 | `placeholder` | string  | `""`    | Input placeholder text                                           |
+| `label`       | string  | `""`    | Visible label text, associated to the input via `<label for>`    |
+| `hint`        | string  | —       | Helper text shown below the input                                |
+| `error`       | string  | —       | Error message; when set the input enters error state             |
 | `disabled`    | boolean | `false` | Disables the entire combobox                                     |
 
+## CSS Custom Properties
+
+| Property                               | Default                                              | Description                                                             |
+|------------------------------------------|--------------------------------------------------------|---------------------------------------------------------------------------|
+| `--combobox_border`                    | `none`                                                | Real CSS `border` on the input (in addition to the bdc inset outline)   |
+| `--combobox_radius`                    | `--bdc-outline_radius` (`--bds-border_radius--full`)  | Input corner radius                                                     |
+| `--combobox_shadow`                    | `--bdc-outline_shadow`                                | Extra box-shadow layered behind the input's inset border                |
+| `--combobox_color_bg`                  | `--bds-color_bg`                                      | Input and listbox background colour                                     |
+| `--combobox_color`                     | `--bds-color_on-bg`                                   | Input text colour                                                       |
+| `--combobox_on-color`                  | `--bds-color_on-bg`                                   | Listbox/option text colour                                              |
+| `--combobox_listbox-border`            | `none`                                                | Real CSS `border` on the listbox (in addition to the bdc inset outline) |
+| `--combobox_listbox-radius`            | `--bdc-outline_radius` (`--bds-border_radius--s`)     | Listbox corner radius                                                   |
+| `--combobox_listbox-shadow`            | `--bds-shadow_m`                                      | Listbox elevation shadow                                                |
+| `--combobox_z-index`                   | `--bds-z-index_dropdown`                              | Listbox stacking order                                                  |
+| `--combobox_option-bg--highlighted`    | `--bds-color_bg--subtle`                              | Background of the hovered/keyboard-highlighted/selected option          |
+| `--combobox_option-color--highlighted` | `--bds-color_interactive_on-bg`                       | Text colour of the hovered/keyboard-highlighted/selected option         |
+
+> `--combobox_border-color` is a web-component-only override for the input's inset-border colour (`--bdc_color`, default `currentcolor`); it has no React `Combobox` equivalent. Most consumers should use `--combobox_color` (text colour), which the border also inherits via `currentcolor` unless `--combobox_border-color` is set explicitly.
+
+## Slots
+
+_None._
+
 ## Events
 
 | Event        | Detail                          | Description                          |
@@ -58,6 +90,7 @@ Use `<bds-combobox>` when users need to search and filter a list of options. For
 ```html
 <bds-combobox
   name="country"
+  label="Country"
   placeholder="Search country…"
   options='[{"value":"nl","label":"Netherlands"},{"value":"be","label":"Belgium"}]'
 ></bds-combobox>
@@ -65,7 +98,11 @@ Use `<bds-combobox>` when users need to search and filter a list of options. For
 
 ## Accessibility
 
-- Uses `role="combobox"` on the input with `aria-expanded`, `aria-autocomplete="list"`, and `aria-haspopup="listbox"`
-- Listbox uses `role="listbox"` and each option uses `role="option"` with `aria-selected` and `aria-disabled`
+- `<label>` is associated with the inner input via matching `id`/`for` attributes when `label` is set
+- Uses `role="combobox"` on the input with `aria-expanded`, `aria-autocomplete="list"`, `aria-haspopup="listbox"`, and `autocomplete="off"`
+- `aria-controls` points the input at the listbox; `aria-activedescendant` tracks the keyboard-highlighted option so the current selection is exposed to assistive tech
+- Listbox uses `role="listbox"` and each option uses `role="option"` with `aria-selected` and `aria-disabled`; the "No results" placeholder uses `role="presentation"` so it isn't announced as a selectable option
+- `error` sets `aria-invalid="true"` and links the error message via `aria-describedby`; the error message uses `role="alert"`
+- `hint` is linked via `aria-describedby` for screen reader announcement when there is no error
 - Full keyboard navigation: `ArrowDown`/`ArrowUp` to navigate, `Enter` to select, `Escape` to close
 - Participates in HTML forms via the Form-Associated Custom Elements API

package/src/web-components/interaction/form/BdsCombobox.stories.tsx

@@ -22,12 +22,18 @@ function BdsCombobox({
   value,
   options,
   placeholder,
+  label,
+  hint,
+  error,
   disabled,
 }: {
   name?: string;
   value?: string;
   options?: string;
   placeholder?: string;
+  label?: string;
+  hint?: string;
+  error?: string;
   disabled?: boolean;
 }) {
   return React.createElement('bds-combobox', {
@@ -35,6 +41,9 @@ function BdsCombobox({
     value,
     options,
     placeholder,
+    label,
+    hint,
+    error,
     disabled: disabled || undefined,
   });
 }
@@ -62,6 +71,7 @@ type Story = StoryObj<typeof meta>;
 export const Default: Story = {
   args: {
     name: 'country',
+    label: 'Country',
     options: COUNTRIES,
     placeholder: 'Search country…',
   },
@@ -70,11 +80,32 @@ export const Default: Story = {
 export const WithDisabledOption: Story = {
   args: {
     name: 'country',
+    label: 'Country',
     options: COUNTRIES_WITH_DISABLED,
     placeholder: 'Search country…',
   },
 };
 
+export const WithHint: Story = {
+  args: {
+    name: 'country',
+    label: 'Country',
+    hint: 'Start typing to filter the list',
+    options: COUNTRIES,
+    placeholder: 'Search country…',
+  },
+};
+
+export const WithError: Story = {
+  args: {
+    name: 'country',
+    label: 'Country',
+    error: 'Please select a country',
+    options: COUNTRIES,
+    placeholder: 'Search country…',
+  },
+};
+
 export const Required: Story = {
   args: {
     name: 'country',