@boostdev/design-system-components 2.7.1 → 2.11.0

package/src/web-components/interaction/form/bds-checkbox-group.ts

@@ -1,15 +1,28 @@
-import { LitElement, css, html } from 'lit';
+import { LitElement, css, html, nothing } from 'lit';
 
 /**
  * `<bds-checkbox-group>` — groups related checkboxes with a shared label.
  *
  * Renders a `<fieldset>` with a `<legend>` for accessible grouping.
+ * Propagates `disabled` to slotted `<bds-checkbox>` elements — a shadow-DOM
+ * `<fieldset disabled>` has no effect on slotted light-DOM content on its
+ * own, so the group attribute is explicitly applied to (and removed from)
+ * each child. A checkbox individually marked `disabled` in markup stays
+ * disabled even after the group re-enables.
+ *
+ * `required` is surfaced to assistive tech via a visually-hidden "(required)"
+ * text alternative in the legend rather than `aria-required` on the fieldset —
+ * `aria-required` is only a supported property on the `checkbox`, `combobox`,
+ * `gridcell`, `listbox`, `radiogroup`, `spinbutton`, `textbox` and `tree`
+ * roles; a bare `<fieldset>` maps to the generic `group` role, which does not
+ * support it (there is no ARIA `checkboxgroup` role), so the attribute would
+ * be silently ignored by assistive tech.
  *
  * Attributes:
  *   label    — visible group label (rendered as `<legend>`)
  *   error    — error message shown below items
  *   hint     — hint text shown below items
- *   disabled — disables the entire fieldset
+ *   disabled — disables the entire fieldset and all slotted `<bds-checkbox>` elements
  *   required — marks the group as required
  *
  * Slots:
@@ -23,10 +36,25 @@ import { LitElement, css, html } from 'lit';
  */
 export class BdsCheckboxGroup 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([disabled]) .legend,
+    :host([disabled]) .message {
+      opacity: 0.5;
+    }
+
     fieldset {
       border: none;
       margin: 0;
@@ -36,7 +64,7 @@ export class BdsCheckboxGroup extends LitElement {
     .legend {
       font-size: var(--bds-font_size--body--s);
       font-family: var(--bds-font_family--body);
-      font-weight: var(--bds-font_weight--semibold);
+      font-weight: var(--bds-font_weight--medium);
       color: var(--bds-color_on-bg);
       margin-block-end: var(--bds-space_xs);
     }
@@ -46,6 +74,22 @@ export class BdsCheckboxGroup extends LitElement {
       margin-inline-start: var(--bds-space_xxxs);
     }
 
+    /* Visually hidden but still exposed to assistive tech — carries the
+       "required" state into the fieldset's accessible name, since the
+       visible asterisk above is aria-hidden and aria-required is not
+       supported ARIA on a fieldset (role=group). */
+    .requiredLabel {
+      position: absolute;
+      inline-size: 1px;
+      block-size: 1px;
+      padding: 0;
+      margin: -1px;
+      overflow: hidden;
+      clip: rect(0, 0, 0, 0);
+      white-space: nowrap;
+      border-width: 0;
+    }
+
     .items {
       display: flex;
       flex-direction: column;
@@ -59,7 +103,7 @@ export class BdsCheckboxGroup extends LitElement {
     }
 
     .message--error {
-      color: var(--bds-color_error);
+      color: var(--bds-color_error_on-bg);
     }
 
     .message--hint {
@@ -82,6 +126,8 @@ export class BdsCheckboxGroup extends LitElement {
   declare disabled: boolean;
   declare required: boolean;
 
+  private readonly _uid = Math.random().toString(36).slice(2, 8);
+
   constructor() {
     super();
     this.label = '';
@@ -89,20 +135,60 @@ export class BdsCheckboxGroup extends LitElement {
     this.required = false;
   }
 
+  /**
+   * Propagates `disabled` to slotted `<bds-checkbox>` elements. Only checkboxes
+   * that were enabled before the group disabled them are re-enabled when the
+   * group re-enables — a checkbox individually marked `disabled` in markup
+   * stays disabled.
+   */
+  private _propagateDisabled = () => {
+    this.querySelectorAll('bds-checkbox').forEach(checkbox => {
+      const el = checkbox as HTMLElement;
+      if (this.disabled) {
+        if (!el.hasAttribute('disabled')) {
+          el.setAttribute('data-bds-group-disabled', '');
+        }
+        el.setAttribute('disabled', '');
+      } else if (el.hasAttribute('data-bds-group-disabled')) {
+        el.removeAttribute('disabled');
+        el.removeAttribute('data-bds-group-disabled');
+      }
+    });
+  };
+
+  connectedCallback() {
+    super.connectedCallback();
+    // Propagate after slot content has been parsed
+    Promise.resolve().then(this._propagateDisabled);
+  }
+
+  updated(changed: Map<string, unknown>) {
+    super.updated(changed);
+    if (changed.has('disabled')) {
+      this._propagateDisabled();
+    }
+  }
+
   render() {
+    const errorId = `bds-checkbox-group-${this._uid}-error`;
+    const hintId = `bds-checkbox-group-${this._uid}-hint`;
+    const describedBy = [this.error && errorId, this.hint && hintId].filter(Boolean).join(' ') || undefined;
+
     return html`
-      <fieldset ?disabled=${this.disabled}>
+      <fieldset ?disabled=${this.disabled} aria-describedby=${describedBy ?? nothing}>
         <legend class="legend">
           ${this.label}
-          ${this.required ? html`<span class="required" aria-hidden="true"> *</span>` : ''}
+          ${this.required
+            ? html`<span class="required" aria-hidden="true"> *</span> <span class="requiredLabel">(required)</span>`
+            : ''}
         </legend>
         <div class="items">
-          <slot></slot>
+          <slot @slotchange=${this._propagateDisabled}></slot>
         </div>
         ${this.error
-          ? html`<p class="message message--error" role="alert">${this.error}</p>`
+          ? html`<p id=${errorId} class="message message--error" role="alert">${this.error}</p>`
           : this.hint
-            ? html`<p class="message message--hint">${this.hint}</p>`
+            ? html`<p id=${hintId} class="message message--hint">${this.hint}</p>`
             : ''}
       </fieldset>
     `;

package/src/web-components/interaction/form/bds-checkbox.spec.ts

@@ -60,4 +60,59 @@ describe('bds-checkbox', () => {
   it('is form-associated', () => {
     expect(BdsCheckbox.formAssociated).toBe(true);
   });
+
+  it('recomputes required validity when checked changes (not just when required changes)', async () => {
+    const setValidity = vi.fn();
+    const spy = vi
+      .spyOn(HTMLElement.prototype, 'attachInternals')
+      .mockReturnValue({ setValidity, setFormValue: vi.fn() } as unknown as ElementInternals);
+
+    const el = await fixture('<bds-checkbox name="agree" required>Accept</bds-checkbox>') as BdsCheckbox;
+    // Initial connect already reports invalid (required + unchecked) — clear that call.
+    setValidity.mockClear();
+
+    const input = el.shadowRoot!.querySelector<HTMLInputElement>('input')!;
+    input.checked = true;
+    input.dispatchEvent(new Event('change', { bubbles: true }));
+    await el.updateComplete;
+
+    expect(setValidity).toHaveBeenLastCalledWith({});
+
+    spy.mockRestore();
+    cleanup(el);
+  });
+
+  it('reports invalid when a required checkbox becomes unchecked again', async () => {
+    const setValidity = vi.fn();
+    const spy = vi
+      .spyOn(HTMLElement.prototype, 'attachInternals')
+      .mockReturnValue({ setValidity, setFormValue: vi.fn() } as unknown as ElementInternals);
+
+    const el = await fixture('<bds-checkbox name="agree" required checked>Accept</bds-checkbox>') as BdsCheckbox;
+    setValidity.mockClear();
+
+    const input = el.shadowRoot!.querySelector<HTMLInputElement>('input')!;
+    input.checked = false;
+    input.dispatchEvent(new Event('change', { bubbles: true }));
+    await el.updateComplete;
+
+    expect(setValidity).toHaveBeenLastCalledWith({ valueMissing: true }, 'Required');
+
+    spy.mockRestore();
+    cleanup(el);
+  });
+
+  it('sets aria-invalid on the input when error attribute is set', async () => {
+    const el = await fixture('<bds-checkbox name="agree" error>Accept</bds-checkbox>');
+    const input = el.shadowRoot!.querySelector<HTMLInputElement>('input')!;
+    expect(input.getAttribute('aria-invalid')).toBe('true');
+    cleanup(el);
+  });
+
+  it('aria-invalid is false by default', async () => {
+    const el = await fixture('<bds-checkbox name="agree">Accept</bds-checkbox>');
+    const input = el.shadowRoot!.querySelector<HTMLInputElement>('input')!;
+    expect(input.getAttribute('aria-invalid')).toBe('false');
+    cleanup(el);
+  });
 });

package/src/web-components/interaction/form/bds-checkbox.ts

@@ -13,6 +13,7 @@ import { LitElement, css, html } from 'lit';
  *   checked  — boolean; whether the checkbox is checked
  *   required — boolean
  *   disabled — boolean
+ *   error    — boolean; puts the checkbox in an error state (border colour + aria-invalid)
  *
  * Slots:
  *   (default) — label text
@@ -27,10 +28,20 @@ export class BdsCheckbox extends LitElement {
   static formAssociated = true;
 
   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: flex-start;
-      gap: var(--bds-space_xs);
+      gap: var(--checkbox_gap, var(--bds-space_m));
       cursor: pointer;
       font-size: var(--bds-font_size--body);
       font-family: var(--bds-font_family--body);
@@ -45,16 +56,18 @@ export class BdsCheckbox extends LitElement {
 
     .input {
       --inputSize: calc(var(--bds-space_s) * 2);
-      margin-block-start: 0.25em;
+      margin-block-start: var(--checkbox_offset, 0.25em);
       inline-size: var(--inputSize);
       block-size: var(--inputSize);
       flex-shrink: 0;
-      --bdc_color: var(--checkbox_border-color, currentcolor);
+      /* --checkbox_border-color is a deprecated alias — prefer --checkbox_color (matches React) */
+      color: var(--checkbox_color, var(--checkbox_border-color, var(--bds-color_on-bg)));
+      --bdc_color: currentcolor;
       --bdc-outline_radius: var(--bds-border_radius--xs);
 
       border-radius: var(--checkbox_radius, var(--bdc-outline_radius));
       box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color), var(--checkbox_shadow, var(--bdc-outline_shadow));
-      border: none;
+      border: var(--checkbox_border, none);
       appearance: none;
       background-color: var(--checkbox_color_bg, var(--bds-color_bg));
       cursor: pointer;
@@ -79,11 +92,19 @@ export class BdsCheckbox extends LitElement {
       transform: rotate(45deg);
     }
 
+    .input:focus {
+      --bdc_color: var(--bdc_color--focus);
+    }
+
     .input:focus-visible {
       outline: var(--bds-outline_default);
       outline-offset: var(--bds-outline_offset);
     }
 
+    :host([error]) .input {
+      --bdc_color: var(--bdc_color--error);
+    }
+
     label {
       cursor: pointer;
       flex: 1;
@@ -96,6 +117,7 @@ export class BdsCheckbox extends LitElement {
     checked:  { type: Boolean, reflect: true },
     required: { type: Boolean, reflect: true },
     disabled: { type: Boolean, reflect: true },
+    error:    { type: Boolean, reflect: true },
   };
 
   declare name: string;
@@ -103,6 +125,7 @@ export class BdsCheckbox extends LitElement {
   declare checked: boolean;
   declare required: boolean;
   declare disabled: boolean;
+  declare error: boolean;
 
   private _internals!: ElementInternals;
   private readonly _uid = Math.random().toString(36).slice(2, 8);
@@ -115,6 +138,7 @@ export class BdsCheckbox extends LitElement {
     this.checked = false;
     this.required = false;
     this.disabled = false;
+    this.error = false;
   }
 
   updated(changed: Map<string, unknown>) {
@@ -122,7 +146,7 @@ export class BdsCheckbox extends LitElement {
     if (changed.has('checked') || changed.has('value')) {
       this._internals.setFormValue?.(this.checked ? this.value : null);
     }
-    if (changed.has('required')) {
+    if (changed.has('required') || changed.has('checked')) {
       if (this.required && !this.checked) {
         this._internals.setValidity?.({ valueMissing: true }, 'Required');
       } else {
@@ -150,6 +174,7 @@ export class BdsCheckbox extends LitElement {
         .checked=${this.checked}
         ?required=${this.required}
         ?disabled=${this.disabled}
+        aria-invalid=${this.error ? 'true' : 'false'}
         @change=${this._handleChange}
       />
       <label for=${id}><slot></slot></label>

package/src/web-components/interaction/form/bds-combobox.spec.ts

@@ -114,4 +114,83 @@ describe('bds-combobox', () => {
   it('is form-associated', () => {
     expect(BdsCombobox.formAssociated).toBe(true);
   });
+
+  it('associates a visible label with the input via for/id', async () => {
+    const el = await fixture(`<bds-combobox name="country" label="Country" options='${OPTIONS}'></bds-combobox>`);
+    const label = el.shadowRoot!.querySelector<HTMLLabelElement>('label')!;
+    const input = el.shadowRoot!.querySelector<HTMLInputElement>('input')!;
+    expect(label).not.toBeNull();
+    expect(label.textContent).toBe('Country');
+    expect(label.getAttribute('for')).toBe(input.id);
+    cleanup(el);
+  });
+
+  it('renders no label when the label attribute is unset', async () => {
+    const el = await fixture(`<bds-combobox name="country" options='${OPTIONS}'></bds-combobox>`);
+    expect(el.shadowRoot!.querySelector('label')).toBeNull();
+    cleanup(el);
+  });
+
+  it('sets aria-controls on the input pointing at the listbox id', async () => {
+    const el = await fixture(`<bds-combobox name="country" options='${OPTIONS}'></bds-combobox>`);
+    const input = el.shadowRoot!.querySelector<HTMLInputElement>('input')!;
+    input.dispatchEvent(new Event('focus'));
+    await el.updateComplete;
+    const listbox = el.shadowRoot!.querySelector('[role="listbox"]')!;
+    expect(input.getAttribute('aria-controls')).toBe(listbox.id);
+    cleanup(el);
+  });
+
+  it('sets autocomplete="off" on the input', async () => {
+    const el = await fixture(`<bds-combobox name="country" options='${OPTIONS}'></bds-combobox>`);
+    const input = el.shadowRoot!.querySelector<HTMLInputElement>('input')!;
+    expect(input.getAttribute('autocomplete')).toBe('off');
+    cleanup(el);
+  });
+
+  it('updates aria-activedescendant to the focused option id while navigating', async () => {
+    const el = await fixture(`<bds-combobox name="country" options='${OPTIONS}'></bds-combobox>`);
+    const input = el.shadowRoot!.querySelector<HTMLInputElement>('input')!;
+    input.dispatchEvent(new Event('focus'));
+    await el.updateComplete;
+    expect(input.hasAttribute('aria-activedescendant')).toBe(false);
+
+    input.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }));
+    await el.updateComplete;
+    const options = Array.from(el.shadowRoot!.querySelectorAll('[role="option"]'));
+    const focusedOption = options.find(o => o.className.includes('--focused'))!;
+    expect(focusedOption).not.toBeUndefined();
+    expect(input.getAttribute('aria-activedescendant')).toBe(focusedOption.id);
+    cleanup(el);
+  });
+
+  it('gives the no-results item role="presentation" so it is not exposed as an option', async () => {
+    const el = await fixture(`<bds-combobox name="country" options='${OPTIONS}'></bds-combobox>`);
+    const input = el.shadowRoot!.querySelector<HTMLInputElement>('input')!;
+    input.value = 'zzz';
+    input.dispatchEvent(new Event('input', { bubbles: true }));
+    await el.updateComplete;
+    const noResults = el.shadowRoot!.querySelector('.no-results')!;
+    expect(noResults.getAttribute('role')).toBe('presentation');
+    cleanup(el);
+  });
+
+  it('sets aria-invalid and wires the error message via aria-describedby', async () => {
+    const el = await fixture(`<bds-combobox name="country" error="Required field" options='${OPTIONS}'></bds-combobox>`);
+    const input = el.shadowRoot!.querySelector<HTMLInputElement>('input')!;
+    const error = el.shadowRoot!.querySelector('.message--error')!;
+    expect(input.getAttribute('aria-invalid')).toBe('true');
+    expect(error.getAttribute('role')).toBe('alert');
+    expect(input.getAttribute('aria-describedby')).toBe(error.id);
+    cleanup(el);
+  });
+
+  it('wires the hint message via aria-describedby when there is no error', async () => {
+    const el = await fixture(`<bds-combobox name="country" hint="Pick a country" options='${OPTIONS}'></bds-combobox>`);
+    const input = el.shadowRoot!.querySelector<HTMLInputElement>('input')!;
+    const hint = el.shadowRoot!.querySelector('.message--hint')!;
+    expect(input.getAttribute('aria-invalid')).toBe('false');
+    expect(input.getAttribute('aria-describedby')).toBe(hint.id);
+    cleanup(el);
+  });
 });

package/src/web-components/interaction/form/bds-combobox.ts

@@ -1,4 +1,4 @@
-import { LitElement, css, html } from 'lit';
+import { LitElement, css, html, nothing } from 'lit';
 
 export interface ComboboxOption {
   value: string;
@@ -17,6 +17,9 @@ export interface ComboboxOption {
  *   value       — currently selected value
  *   options     — JSON array of `{ value, label, disabled? }` option objects
  *   placeholder — input placeholder text
+ *   label       — visible label text (associated to the input via `<label for>`)
+ *   hint        — helper text shown below the input
+ *   error       — error message; when set the input enters error state
  *   disabled    — boolean
  *
  * Events:
@@ -25,6 +28,7 @@ export interface ComboboxOption {
  * @example
  * <bds-combobox
  *   name="country"
+ *   label="Country"
  *   placeholder="Search…"
  *   options='[{"value":"nl","label":"Netherlands"},{"value":"be","label":"Belgium"}]'
  * ></bds-combobox>
@@ -33,6 +37,16 @@ export class BdsCombobox extends LitElement {
   static formAssociated = true;
 
   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;
       position: relative;
@@ -43,6 +57,15 @@ export class BdsCombobox extends LitElement {
       pointer-events: none;
     }
 
+    .label {
+      display: block;
+      font-size: var(--bds-font_size--body--s);
+      font-family: var(--bds-font_family--body);
+      font-weight: var(--bds-font_weight--semibold);
+      color: var(--bds-color_on-bg);
+      margin-block-end: var(--bds-space_xxs);
+    }
+
     .wrapper {
       position: relative;
     }
@@ -52,10 +75,10 @@ export class BdsCombobox extends LitElement {
       font-family: var(--bds-font_family--body);
       font-size: var(--bds-font_size--body);
       padding: var(--bds-space_s);
-      padding-inline-end: var(--bds-space_xl);
-      border: none;
+      padding-inline-end: var(--bds-space_xxl);
+      border: var(--combobox_border, none);
       --bdc_color: var(--combobox_border-color, currentcolor);
-      --bdc-outline_radius: var(--bds-border_radius--xs);
+      --bdc-outline_radius: var(--bds-border_radius--full);
 
       border-radius: var(--combobox_radius, var(--bdc-outline_radius));
       box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color), var(--combobox_shadow, var(--bdc-outline_shadow));
@@ -74,6 +97,14 @@ export class BdsCombobox extends LitElement {
       outline-offset: var(--bds-outline_offset);
     }
 
+    :host([error]) .input {
+      --bdc_color: var(--bdc_color--error);
+    }
+
+    :host([error]) .input:focus {
+      --bdc_color: var(--bdc_color--error);
+    }
+
     .chevron {
       position: absolute;
       inset-inline-end: var(--bds-space_s);
@@ -92,31 +123,39 @@ export class BdsCombobox extends LitElement {
 
     .listbox {
       position: absolute;
-      inset-block-start: calc(100% + var(--bds-space_xs));
+      inset-block-start: calc(100% + var(--bds-space_xxs));
       inset-inline-start: 0;
       inline-size: 100%;
       max-block-size: 15rem;
-      overflow-y: auto;
-      background-color: var(--combobox_list-bg, var(--bds-color_bg));
-      border-radius: var(--bds-border_radius--s);
-      box-shadow: var(--bds-shadow_m);
-      z-index: var(--combobox_z-index, 100);
-      padding-block: var(--bds-space_xs);
+      overflow-block: auto;
+      list-style: none;
+      margin: 0;
+      border: var(--combobox_listbox-border, none);
+      --bdc_color: currentcolor;
+      --bdc-outline_radius: var(--bds-border_radius--s);
+
+      border-radius: var(--combobox_listbox-radius, var(--bdc-outline_radius));
+      background-color: var(--combobox_color_bg, var(--bds-color_bg));
+      color: var(--combobox_on-color, var(--bds-color_on-bg));
+      box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color), var(--combobox_listbox-shadow, var(--bds-shadow_m));
+      z-index: var(--combobox_z-index, var(--bds-z-index_dropdown));
+      padding: var(--bds-space_xxs) 0;
     }
 
     .option {
       display: block;
-      padding: var(--bds-space_s) var(--bds-space_m);
+      padding: var(--bds-space_xs) var(--bds-space_m);
       cursor: pointer;
       font-family: var(--bds-font_family--body);
       font-size: var(--bds-font_size--body);
-      color: var(--bds-color_on-bg);
+      color: var(--combobox_on-color, var(--bds-color_on-bg));
       transition: background-color var(--bds-animation_transition-duration) var(--bds-animation_easing);
     }
 
     .option:hover,
     .option[aria-selected='true'] {
-      background-color: var(--bds-color_bg--subtle);
+      background-color: var(--combobox_option-bg--highlighted, var(--bds-color_bg--subtle));
+      color: var(--combobox_option-color--highlighted, var(--bds-color_interactive_on-bg));
     }
 
     .option[aria-disabled='true'] {
@@ -125,7 +164,8 @@ export class BdsCombobox extends LitElement {
     }
 
     .option.--focused {
-      background-color: var(--bds-color_bg--subtle);
+      background-color: var(--combobox_option-bg--highlighted, var(--bds-color_bg--subtle));
+      color: var(--combobox_option-color--highlighted, var(--bds-color_interactive_on-bg));
       outline: none;
     }
 
@@ -135,6 +175,21 @@ export class BdsCombobox extends LitElement {
       font-size: var(--bds-font_size--body--s);
       color: var(--bds-color_on-bg--subtle);
     }
+
+    .message {
+      margin-block-start: var(--bds-space_xxs);
+      font-size: var(--bds-font_size--body--s);
+      font-family: var(--bds-font_family--body);
+    }
+
+    .message--error {
+      color: var(--bds-color_error);
+    }
+
+    .message--hint {
+      color: var(--bds-color_on-bg--subtle);
+      font-style: italic;
+    }
   `;
 
   static properties = {
@@ -142,6 +197,9 @@ export class BdsCombobox extends LitElement {
     value:       { type: String },
     options:     { type: String },
     placeholder: { type: String },
+    label:       { type: String },
+    hint:        { type: String },
+    error:       { type: String, reflect: true },
     disabled:    { type: Boolean, reflect: true },
   };
 
@@ -149,9 +207,13 @@ export class BdsCombobox extends LitElement {
   declare value: string;
   declare options: string;
   declare placeholder: string;
+  declare label: string;
+  declare hint: string | undefined;
+  declare error: string | undefined;
   declare disabled: boolean;
 
   private _internals!: ElementInternals;
+  private readonly _uid = Math.random().toString(36).slice(2, 8);
   private _open = false;
   private _query = '';
   private _focusedIndex = -1;
@@ -163,6 +225,7 @@ export class BdsCombobox extends LitElement {
     this.value = '';
     this.options = '[]';
     this.placeholder = '';
+    this.label = '';
     this.disabled = false;
   }
 
@@ -280,16 +343,32 @@ export class BdsCombobox extends LitElement {
   render() {
     const filtered = this._filtered;
     const inputValue = this._open ? this._query : this._displayLabel;
+    const id = `bds-combobox-${this._uid}`;
+    const listboxId = `${id}-listbox`;
+    const hintId = `${id}-hint`;
+    const errorId = `${id}-error`;
+    const describedBy = [this.error && errorId, this.hint && hintId].filter(Boolean).join(' ') || undefined;
+    const activeDescendant =
+      this._focusedIndex >= 0 && this._focusedIndex < filtered.length
+        ? `${id}-option-${this._focusedIndex}`
+        : undefined;
 
     return html`
+      ${this.label ? html`<label class="label" for=${id}>${this.label}</label>` : ''}
       <div class="wrapper">
         <input
+          id=${id}
           type="text"
           class="input"
           role="combobox"
           aria-expanded=${this._open}
           aria-autocomplete="list"
           aria-haspopup="listbox"
+          aria-controls=${listboxId}
+          aria-activedescendant=${activeDescendant ?? nothing}
+          aria-invalid=${this.error ? 'true' : 'false'}
+          aria-describedby=${describedBy ?? nothing}
+          autocomplete="off"
           name=${this.name}
           placeholder=${this.placeholder}
           .value=${inputValue}
@@ -305,11 +384,12 @@ export class BdsCombobox extends LitElement {
           </svg>
         </span>
         ${this._open ? html`
-          <ul class="listbox" role="listbox" aria-label="Options">
+          <ul id=${listboxId} class="listbox" role="listbox" aria-label="Options">
             ${filtered.length === 0
-              ? html`<li class="no-results">No results</li>`
+              ? html`<li class="no-results" role="presentation">No results</li>`
               : filtered.map((opt, i) => html`
                   <li
+                    id="${id}-option-${i}"
                     class="option ${i === this._focusedIndex ? '--focused' : ''}"
                     role="option"
                     aria-selected=${opt.value === this.value}
@@ -321,6 +401,11 @@ export class BdsCombobox extends LitElement {
           </ul>
         ` : ''}
       </div>
+      ${this.error
+        ? html`<p id=${errorId} class="message message--error" role="alert">${this.error}</p>`
+        : this.hint
+          ? html`<p id=${hintId} class="message message--hint">${this.hint}</p>`
+          : ''}
     `;
   }
 }