@arbor-education/design-system.components 0.6.0 → 0.7.0

package/src/components/combobox/Combobox.test.tsx

@@ -0,0 +1,1160 @@
+import '@testing-library/jest-dom/vitest';
+import { fireEvent, render, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, test, vi } from 'vitest';
+import { Combobox } from './Combobox';
+import type { ComboboxOption } from './types';
+
+const people: ComboboxOption[] = [
+  { value: 'alice', label: 'Alice Johnson', iconName: 'user' },
+  { value: 'bob', label: 'Bob Smith', iconName: 'user' },
+  { value: 'charlie', label: 'Charlie Brown', iconName: 'user' },
+];
+
+describe('Combobox', () => {
+  const openWithChevron = async () => {
+    if (screen.queryByRole('listbox')) return;
+    await userEvent.click(screen.getByRole('button', { name: 'Open suggestions' }));
+  };
+
+  test('renders with placeholder when nothing is selected', () => {
+    render(<Combobox options={people} placeholder="Search people..." />);
+    expect(screen.getByPlaceholderText('Search people...')).toBeInTheDocument();
+  });
+
+  test('has correct ARIA attributes on the input', () => {
+    render(<Combobox options={people} aria-label="People" />);
+    const input = screen.getByRole('combobox');
+    expect(input).toHaveAttribute('aria-autocomplete', 'list');
+    expect(input).toHaveAttribute('aria-expanded', 'false');
+    expect(input).toHaveAttribute('aria-label', 'People');
+  });
+
+  test('aria-controls always references the listbox id', () => {
+    render(<Combobox options={people} id="test-cb" />);
+    const input = screen.getByRole('combobox');
+    expect(input).toHaveAttribute('aria-controls', 'test-cb-listbox');
+  });
+
+  test('opens listbox on focus by default when options are available', async () => {
+    render(<Combobox options={people} />);
+    const input = screen.getByRole('combobox');
+    fireEvent.focus(input);
+
+    expect(screen.getByRole('listbox')).toBeInTheDocument();
+  });
+
+  test('does not open listbox on focus when dropdownOnFocus is false', () => {
+    render(<Combobox options={people} dropdownOnFocus={false} />);
+    const input = screen.getByRole('combobox');
+    fireEvent.focus(input);
+
+    expect(screen.queryByRole('listbox')).not.toBeInTheDocument();
+  });
+
+  test('does not force an empty panel on focus when dropdownOnFocus is true but no items are available', () => {
+    render(<Combobox options={[]} dropdownOnFocus />);
+    const input = screen.getByRole('combobox');
+    fireEvent.focus(input);
+
+    expect(screen.queryByRole('listbox')).not.toBeInTheDocument();
+  });
+
+  test('showDropdownTrigger=false hides the chevron button', () => {
+    render(<Combobox options={people} showDropdownTrigger={false} />);
+
+    expect(screen.queryByRole('button', { name: /suggestions/i })).not.toBeInTheDocument();
+  });
+
+  test('showDropdownTrigger=false still allows focus opening', () => {
+    render(<Combobox options={people} showDropdownTrigger={false} />);
+    const input = screen.getByRole('combobox');
+    fireEvent.focus(input);
+
+    expect(screen.getByRole('listbox')).toBeInTheDocument();
+  });
+
+  test('clicking the input opens reliably when dropdownOnFocus is enabled', async () => {
+    render(<Combobox options={people} />);
+    const input = screen.getByRole('combobox');
+
+    await userEvent.click(input);
+
+    expect(screen.getByRole('listbox')).toBeInTheDocument();
+  });
+
+  test('clicking the trigger reopens even when the input is already focused', async () => {
+    render(<Combobox options={people} />);
+    const input = screen.getByRole('combobox');
+    const trigger = input.closest('.ds-combobox__trigger');
+
+    fireEvent.focus(input);
+    expect(screen.getByRole('listbox')).toBeInTheDocument();
+
+    fireEvent.keyDown(input, { key: 'Escape' });
+    expect(screen.queryByRole('listbox')).not.toBeInTheDocument();
+
+    expect(trigger).toBeTruthy();
+    await userEvent.click(trigger as HTMLElement);
+
+    expect(screen.getByRole('listbox')).toBeInTheDocument();
+  });
+
+  test('clicking the input while open does not collapse the dropdown', async () => {
+    render(<Combobox options={people} />);
+    const input = screen.getByRole('combobox');
+
+    fireEvent.focus(input);
+    expect(screen.getByRole('listbox')).toBeInTheDocument();
+
+    await userEvent.click(input);
+
+    expect(screen.getByRole('listbox')).toBeInTheDocument();
+  });
+
+  test('opens listbox on chevron click and shows options', async () => {
+    render(<Combobox options={people} />);
+    await openWithChevron();
+
+    const listbox = screen.getByRole('listbox');
+    expect(listbox).toBeInTheDocument();
+    const options = within(listbox).getAllByRole('option');
+    expect(options).toHaveLength(3);
+    expect(screen.getByRole('combobox')).toHaveAttribute('aria-expanded', 'true');
+  });
+
+  test('button trigger variant has no inline input before open', () => {
+    render(<Combobox options={people} triggerVariant="button" placeholder="Students" />);
+    expect(screen.queryByRole('combobox')).not.toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Open suggestions' })).toBeInTheDocument();
+  });
+
+  test('button trigger variant opens on Enter and renders search input in dropdown', async () => {
+    render(<Combobox options={people} triggerVariant="button" placeholder="Students" />);
+    const trigger = screen.getByRole('button', { name: /students/i });
+    fireEvent.keyDown(trigger, { key: 'Enter' });
+
+    expect(screen.getByRole('listbox')).toBeInTheDocument();
+    expect(screen.getByRole('combobox')).toBeInTheDocument();
+  });
+
+  test('button trigger variant dropdown search input receives focus when clicked', async () => {
+    render(<Combobox options={people} triggerVariant="button" placeholder="Students" />);
+    await userEvent.click(screen.getByRole('button', { name: 'Open suggestions' }));
+
+    const search = screen.getByRole('combobox');
+    await userEvent.click(search);
+    expect(search).toHaveFocus();
+  });
+
+  test('button trigger single-select does not show selection count badge', () => {
+    render(
+      <Combobox
+        options={people}
+        triggerVariant="button"
+        defaultValue={['alice']}
+      />,
+    );
+    expect(screen.queryByLabelText(/selected item/i)).not.toBeInTheDocument();
+  });
+
+  test('button trigger multi-select shows salmon count badge when multiple chips', () => {
+    render(
+      <Combobox
+        options={people}
+        triggerVariant="button"
+        multiple
+        defaultValue={['alice', 'bob']}
+      />,
+    );
+    const badge = screen.getByLabelText(/2 selected items/i);
+    expect(badge).toHaveClass('ds-badge--salmon');
+    expect(badge).toHaveTextContent('2');
+  });
+
+  test('button trigger does not show ellipsis when all selected chips fit', () => {
+    const rectSpy = vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function mockRect(this: HTMLElement) {
+      let width = 0;
+
+      if (this.classList.contains('ds-combobox__button-content')) width = 420;
+      else if (this.classList.contains('ds-combobox__measure-chip')) width = 80;
+      else if (this.classList.contains('ds-combobox__button-ellipsis')) width = 11.6;
+      else if (this.classList.contains('ds-badge')) width = 24.2;
+
+      return {
+        width,
+        height: 0,
+        top: 0,
+        left: 0,
+        right: width,
+        bottom: 0,
+        x: 0,
+        y: 0,
+        toJSON() {
+          return {};
+        },
+      } as DOMRect;
+    });
+
+    try {
+      render(
+        <Combobox
+          options={people}
+          triggerVariant="button"
+          multiple
+          defaultValue={['alice', 'bob', 'charlie']}
+        />,
+      );
+
+      expect(document.querySelector('.ds-combobox__button-tags-viewport .ds-combobox__button-ellipsis')).not.toBeInTheDocument();
+    }
+    finally {
+      rectSpy.mockRestore();
+    }
+  });
+
+  test('button trigger truncates tags and shows ellipsis when space is constrained', () => {
+    const rectSpy = vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function mockRect(this: HTMLElement) {
+      let width = 0;
+
+      if (this.classList.contains('ds-combobox__button-content')) width = 220;
+      else if (this.classList.contains('ds-combobox__measure-chip')) width = 120.4;
+      else if (this.classList.contains('ds-combobox__button-ellipsis')) width = 11.6;
+      else if (this.classList.contains('ds-badge')) width = 24.2;
+
+      return {
+        width,
+        height: 0,
+        top: 0,
+        left: 0,
+        right: width,
+        bottom: 0,
+        x: 0,
+        y: 0,
+        toJSON() {
+          return {};
+        },
+      } as DOMRect;
+    });
+
+    const longOptions: ComboboxOption[] = [
+      { value: 'a', label: 'Alexandria Montgomery' },
+      { value: 'b', label: 'Benjamin Rutherford' },
+      { value: 'c', label: 'Charlotte Kensington' },
+    ];
+
+    const { container } = render(
+      <div style={{ width: 280 }}>
+        <Combobox
+          options={longOptions}
+          triggerVariant="button"
+          multiple
+          defaultValue={['a', 'b', 'c']}
+        />
+      </div>,
+    );
+
+    try {
+      expect(container.querySelector('.ds-combobox__button-tags-viewport .ds-combobox__button-ellipsis')).toBeInTheDocument();
+      expect(screen.getByLabelText(/3 selected items/i)).toBeInTheDocument();
+      const visibleTags = container.querySelectorAll('.ds-combobox__button-tags-viewport .ds-tag');
+      expect(visibleTags.length).toBeLessThan(3);
+    }
+    finally {
+      rectSpy.mockRestore();
+    }
+  });
+
+  test('selected options remain in the listbox without duplication', async () => {
+    render(
+      <Combobox
+        options={people}
+        triggerVariant="button"
+        multiple
+        defaultValue={['alice', 'bob']}
+      />,
+    );
+
+    await userEvent.click(screen.getByRole('button', { name: 'Open suggestions' }));
+    const listbox = screen.getByRole('listbox');
+    expect(within(listbox).getAllByRole('option')).toHaveLength(people.length);
+  });
+
+  test('when dropdownOnFocus is false, clearing the search hides the listbox again', async () => {
+    render(<Combobox options={people} dropdownOnFocus={false} />);
+    const input = screen.getByRole('combobox');
+
+    await userEvent.type(input, 'ali');
+    expect(screen.getByRole('listbox')).toBeInTheDocument();
+
+    await userEvent.clear(input);
+
+    expect(screen.queryByRole('listbox')).not.toBeInTheDocument();
+  });
+
+  test('selecting an option in single-select mode adds a chip', async () => {
+    const onValueChange = vi.fn();
+    render(<Combobox options={people} onValueChange={onValueChange} />);
+
+    await openWithChevron();
+    await userEvent.click(screen.getByText('Alice Johnson'));
+
+    expect(onValueChange).toHaveBeenCalledWith(['alice']);
+  });
+
+  test('single-select replaces the current chip on new selection', async () => {
+    const onValueChange = vi.fn();
+    render(<Combobox options={people} defaultValue={['alice']} onValueChange={onValueChange} />);
+
+    await openWithChevron();
+    await userEvent.click(screen.getByText('Bob Smith'));
+
+    expect(onValueChange).toHaveBeenCalledWith(['bob']);
+  });
+
+  test('multi-select allows multiple chips', async () => {
+    const onValueChange = vi.fn();
+    render(<Combobox options={people} multiple onValueChange={onValueChange} />);
+
+    await openWithChevron();
+    await userEvent.click(screen.getByText('Alice Johnson'));
+
+    await openWithChevron();
+    await userEvent.click(screen.getByText('Bob Smith'));
+
+    expect(onValueChange).toHaveBeenLastCalledWith(['alice', 'bob']);
+  });
+
+  test('Ctrl+A selects all chips when input is focused', async () => {
+    render(<Combobox options={people} multiple defaultValue={['alice', 'bob']} />);
+    const input = screen.getByRole('combobox');
+    input.focus();
+
+    await userEvent.keyboard('{Control>}a{/Control}');
+
+    const selectedTags = document.querySelectorAll('.ds-tag--selected');
+    expect(selectedTags).toHaveLength(2);
+  });
+
+  test('Cmd+A selects all chips in single-select mode', async () => {
+    render(<Combobox options={people} defaultValue={['alice']} />);
+    const input = screen.getByRole('combobox');
+    input.focus();
+
+    fireEvent.keyDown(input, { key: 'a', metaKey: true });
+
+    const selectedTags = document.querySelectorAll('.ds-tag--selected');
+    expect(selectedTags).toHaveLength(1);
+  });
+
+  test('Backspace clears all selected chips after select-all', async () => {
+    const onValueChange = vi.fn();
+    render(
+      <Combobox options={people} multiple defaultValue={['alice', 'bob']} onValueChange={onValueChange} />,
+    );
+    const input = screen.getByRole('combobox');
+    input.focus();
+
+    await userEvent.keyboard('{Control>}a{/Control}');
+    await userEvent.keyboard('{Backspace}');
+
+    expect(onValueChange).toHaveBeenLastCalledWith([]);
+    expect(document.querySelectorAll('.ds-tag--selected')).toHaveLength(0);
+  });
+
+  test('Delete clears all selected chips after select-all', async () => {
+    const onValueChange = vi.fn();
+    render(
+      <Combobox options={people} multiple defaultValue={['alice', 'bob']} onValueChange={onValueChange} />,
+    );
+    const input = screen.getByRole('combobox');
+    input.focus();
+
+    await userEvent.keyboard('{Control>}a{/Control}');
+    await userEvent.keyboard('{Delete}');
+
+    expect(onValueChange).toHaveBeenLastCalledWith([]);
+    expect(document.querySelectorAll('.ds-tag--selected')).toHaveLength(0);
+  });
+
+  test('typing after chip select-all clears selected chip styling', async () => {
+    render(<Combobox options={people} multiple defaultValue={['alice', 'bob']} />);
+    const input = screen.getByRole('combobox');
+    input.focus();
+
+    await userEvent.keyboard('{Control>}a{/Control}');
+    expect(document.querySelectorAll('.ds-tag--selected')).toHaveLength(2);
+
+    await userEvent.type(input, 'c');
+
+    expect(document.querySelectorAll('.ds-tag--selected')).toHaveLength(0);
+  });
+
+  test('Ctrl+A with no chips keeps native input behavior and does not crash', async () => {
+    render(<Combobox options={people} />);
+    const input = screen.getByRole('combobox');
+    input.focus();
+
+    await userEvent.keyboard('{Control>}a{/Control}');
+
+    expect(document.querySelectorAll('.ds-tag--selected')).toHaveLength(0);
+  });
+
+  test('removing a chip calls onValueChange without that value', async () => {
+    const onValueChange = vi.fn();
+    render(
+      <Combobox options={people} multiple defaultValue={['alice', 'bob']} onValueChange={onValueChange} />,
+    );
+
+    const aliceTag = screen.getByText('Alice Johnson').closest('.ds-tag') as HTMLElement;
+    const removeBtn = within(aliceTag).getByRole('button', { name: 'Remove Alice Johnson' });
+    await userEvent.click(removeBtn);
+
+    expect(onValueChange).toHaveBeenCalledWith(['bob']);
+  });
+
+  test('uses resolved tag labels in button trigger remove button labels', () => {
+    render(
+      <Combobox
+        options={[
+          { value: 'alice', label: 'Alice Johnson', tagLabel: 'Alice J.', iconName: 'user' },
+        ]}
+        triggerVariant="button"
+        multiple
+        defaultValue={['alice']}
+      />,
+    );
+
+    expect(screen.getByRole('button', { name: 'Remove Alice J.' })).toBeInTheDocument();
+  });
+
+  test('typing filters options client-side', async () => {
+    render(<Combobox options={people} />);
+    const input = screen.getByRole('combobox');
+
+    await userEvent.type(input, 'Ali');
+
+    const options = screen.getAllByRole('option');
+    expect(options).toHaveLength(1);
+    expect(options[0]).toHaveTextContent('Alice Johnson');
+  });
+
+  test('default searchType uses prefix matching rather than substring matching', async () => {
+    render(<Combobox options={people} />);
+    const input = screen.getByRole('combobox');
+
+    await userEvent.type(input, 'son');
+
+    expect(screen.queryByRole('listbox')).not.toBeInTheDocument();
+  });
+
+  test('substring searchType matches text anywhere in the label', async () => {
+    render(<Combobox options={people} searchType="substring" />);
+    const input = screen.getByRole('combobox');
+
+    await userEvent.type(input, 'son');
+
+    const options = screen.getAllByRole('option');
+    expect(options).toHaveLength(1);
+    expect(options[0]).toHaveTextContent('Alice Johnson');
+  });
+
+  test('function-valued searchType can provide custom matching', async () => {
+    const initialsSearch = (option: ComboboxOption, query: string) =>
+      option.label
+        .toLowerCase()
+        .split(' ')
+        .map(part => part[0])
+        .join('')
+        .includes(query.toLowerCase());
+
+    render(<Combobox options={people} searchType={initialsSearch} />);
+    const input = screen.getByRole('combobox');
+
+    await userEvent.type(input, 'aj');
+
+    const options = screen.getAllByRole('option');
+    expect(options).toHaveLength(1);
+    expect(options[0]).toHaveTextContent('Alice Johnson');
+  });
+
+  test('renderOption allows custom option row content', async () => {
+    render(
+      <Combobox
+        options={people}
+        renderOption={(option, selected) => (
+          <span>{selected ? `Selected: ${option.label}` : `Row: ${option.label}`}</span>
+        )}
+      />,
+    );
+    const input = screen.getByRole('combobox');
+
+    await userEvent.click(input);
+
+    expect(screen.getByText('Row: Alice Johnson')).toBeInTheDocument();
+  });
+
+  test('highlightStringMatches marks prefix matches when enabled', async () => {
+    render(<Combobox options={people} highlightStringMatches />);
+    const input = screen.getByRole('combobox');
+
+    await userEvent.type(input, 'Ali');
+
+    const option = screen.getByRole('option');
+    expect(within(option).getByText('Ali', { selector: 'mark' })).toBeInTheDocument();
+  });
+
+  test('highlightStringMatches marks substring matches when enabled', async () => {
+    render(
+      <Combobox
+        options={people}
+        searchType="substring"
+        highlightStringMatches
+      />,
+    );
+    const input = screen.getByRole('combobox');
+
+    await userEvent.type(input, 'son');
+
+    const option = screen.getByRole('option');
+    expect(within(option).getByText('son', { selector: 'mark' })).toBeInTheDocument();
+  });
+
+  test('function-valued searchType does not apply built-in mark highlighting', async () => {
+    const initialsSearch = (option: ComboboxOption, query: string) =>
+      option.label
+        .toLowerCase()
+        .split(' ')
+        .map(part => part[0])
+        .join('')
+        .includes(query.toLowerCase());
+
+    render(
+      <Combobox
+        options={people}
+        searchType={initialsSearch}
+        highlightStringMatches
+      />,
+    );
+    const input = screen.getByRole('combobox');
+
+    await userEvent.type(input, 'aj');
+
+    const option = screen.getByRole('option');
+    expect(option).toHaveTextContent('Alice Johnson');
+    expect(within(option).queryByText(/aj/i, { selector: 'mark' })).not.toBeInTheDocument();
+  });
+
+  test('clears filter text and hides popup when no matches and allowCreate is false', async () => {
+    render(<Combobox options={people} />);
+    const input = screen.getByRole('combobox');
+
+    await userEvent.type(input, 'zzzzz');
+
+    expect(screen.queryByRole('listbox')).not.toBeInTheDocument();
+  });
+
+  test('keyboard: ArrowDown opens the listbox', async () => {
+    render(<Combobox options={people} />);
+    const input = screen.getByRole('combobox');
+    input.focus();
+
+    await userEvent.keyboard('{ArrowDown}');
+
+    expect(screen.getByRole('listbox')).toBeInTheDocument();
+  });
+
+  test('keyboard: Alt+ArrowDown opens the listbox', async () => {
+    render(<Combobox options={people} />);
+    const input = screen.getByRole('combobox');
+    input.focus();
+
+    await userEvent.keyboard('{Alt>}{ArrowDown}{/Alt}');
+
+    expect(screen.getByRole('listbox')).toBeInTheDocument();
+  });
+
+  test('keyboard: ArrowDown/ArrowUp moves highlight', async () => {
+    render(<Combobox options={people} />);
+    const input = screen.getByRole('combobox');
+    await openWithChevron();
+
+    await userEvent.keyboard('{ArrowDown}');
+    const firstOption = screen.getAllByRole('option')[0]!;
+    expect(firstOption).toHaveClass('ds-combobox__option-row--highlighted');
+    expect(input).toHaveAttribute('aria-activedescendant', firstOption.id);
+
+    await userEvent.keyboard('{ArrowDown}');
+    const secondOption = screen.getAllByRole('option')[1]!;
+    expect(secondOption).toHaveClass('ds-combobox__option-row--highlighted');
+  });
+
+  test('keyboard: Enter selects the highlighted option', async () => {
+    const onValueChange = vi.fn();
+    render(<Combobox options={people} onValueChange={onValueChange} />);
+    await openWithChevron();
+
+    await userEvent.keyboard('{ArrowDown}');
+    await userEvent.keyboard('{Enter}');
+
+    expect(onValueChange).toHaveBeenCalledWith(['alice']);
+  });
+
+  test('keyboard: Escape closes the listbox', async () => {
+    render(<Combobox options={people} />);
+    await openWithChevron();
+
+    expect(screen.getByRole('listbox')).toBeInTheDocument();
+
+    await userEvent.keyboard('{Escape}');
+
+    expect(screen.queryByRole('listbox')).not.toBeInTheDocument();
+  });
+
+  test('keyboard: Backspace on empty input removes last chip', async () => {
+    const onValueChange = vi.fn();
+    render(
+      <Combobox options={people} multiple defaultValue={['alice', 'bob']} onValueChange={onValueChange} />,
+    );
+    const input = screen.getByRole('combobox');
+    input.focus();
+
+    await userEvent.keyboard('{Backspace}');
+
+    expect(onValueChange).toHaveBeenCalledWith(['alice']);
+  });
+
+  test('allowCreate shows a create row when no exact match', async () => {
+    const onCreateNew = vi.fn();
+    render(<Combobox options={people} allowCreate onCreateNew={onCreateNew} />);
+    const input = screen.getByRole('combobox');
+
+    await userEvent.type(input, 'Zara');
+
+    const createRow = screen.getByText(/Create/);
+    expect(createRow).toBeInTheDocument();
+
+    await userEvent.click(createRow.closest('[role="option"]')!);
+    expect(onCreateNew).toHaveBeenCalledWith('Zara');
+  });
+
+  test('create row has descriptive aria-label', async () => {
+    render(<Combobox options={people} allowCreate />);
+    const input = screen.getByRole('combobox');
+
+    await userEvent.type(input, 'Zara');
+
+    const createOption = screen.getByRole('option', { name: /Create new option: Zara/i });
+    expect(createOption).toBeInTheDocument();
+  });
+
+  test('allowCreate: Enter creates and selects in multi mode', async () => {
+    const onCreateNew = vi.fn((name: string) => ({
+      value: name.toLowerCase(),
+      label: name,
+    }));
+    const onValueChange = vi.fn();
+    render(
+      <Combobox
+        options={people}
+        allowCreate
+        multiple
+        onCreateNew={onCreateNew}
+        onValueChange={onValueChange}
+      />,
+    );
+    const input = screen.getByRole('combobox');
+
+    await userEvent.type(input, 'NewPerson');
+    await userEvent.keyboard('{Enter}');
+
+    expect(onCreateNew).toHaveBeenCalledWith('NewPerson');
+    expect(onValueChange).toHaveBeenCalledWith(['newperson']);
+    expect(screen.getByRole('listbox')).toBeInTheDocument();
+  });
+
+  test('allowCreate creates and replaces current selection in single mode', async () => {
+    const onCreateNew = vi.fn((name: string) => ({
+      value: `new-${name.toLowerCase()}`,
+      label: name,
+    }));
+    const onValueChange = vi.fn();
+    render(
+      <Combobox
+        options={people}
+        allowCreate
+        defaultValue={['alice']}
+        onCreateNew={onCreateNew}
+        onValueChange={onValueChange}
+      />,
+    );
+
+    const input = screen.getByRole('combobox');
+    await userEvent.type(input, 'Taylor');
+    await userEvent.keyboard('{Enter}');
+
+    expect(onCreateNew).toHaveBeenCalledWith('Taylor');
+    expect(onValueChange).toHaveBeenCalledWith(['new-taylor']);
+    expect(screen.getByRole('listbox')).toBeInTheDocument();
+  });
+
+  test('allowCreate duplicate prevention selects existing option', async () => {
+    const onCreateNew = vi.fn();
+    const onValueChange = vi.fn();
+    render(
+      <Combobox
+        options={people}
+        allowCreate
+        multiple
+        onCreateNew={onCreateNew}
+        onValueChange={onValueChange}
+      />,
+    );
+
+    const input = screen.getByRole('combobox');
+    await userEvent.type(input, 'alice johnson');
+    await userEvent.keyboard('{Enter}');
+
+    expect(onCreateNew).not.toHaveBeenCalled();
+    expect(onValueChange).toHaveBeenCalledWith(['alice']);
+  });
+
+  test('allowCreate does not show a create row when the query only differs by surrounding spaces', async () => {
+    const onCreateNew = vi.fn();
+    render(<Combobox options={people} allowCreate onCreateNew={onCreateNew} />);
+
+    const input = screen.getByRole('combobox');
+    await userEvent.type(input, ' Alice Johnson ');
+
+    expect(screen.queryByText(/Create/)).not.toBeInTheDocument();
+    await userEvent.keyboard('{Enter}');
+
+    expect(onCreateNew).not.toHaveBeenCalled();
+  });
+
+  test('allowCreate auto-highlights create row so Enter creates immediately', async () => {
+    const onCreateNew = vi.fn((name: string) => ({
+      value: name.toLowerCase(),
+      label: name,
+    }));
+    const onValueChange = vi.fn();
+    render(
+      <Combobox
+        options={people}
+        allowCreate
+        onCreateNew={onCreateNew}
+        onValueChange={onValueChange}
+      />,
+    );
+
+    const input = screen.getByRole('combobox');
+    await userEvent.type(input, 'Zed');
+
+    const createOption = screen.getByRole('option', { name: /Create/i });
+    expect(createOption).toHaveClass('ds-combobox__option--highlighted');
+
+    await userEvent.keyboard('{Enter}');
+    expect(onCreateNew).toHaveBeenCalledWith('Zed');
+    expect(onValueChange).toHaveBeenCalledWith(['zed']);
+  });
+
+  test('clear-all button removes all selections', async () => {
+    const onValueChange = vi.fn();
+    render(
+      <Combobox options={people} multiple defaultValue={['alice', 'bob']} showClearAll onValueChange={onValueChange} />,
+    );
+
+    const clearAll = screen.getByText('Clear all');
+    await userEvent.click(clearAll);
+
+    expect(onValueChange).toHaveBeenCalledWith([]);
+  });
+
+  test('clear-all is hidden when nothing is selected', () => {
+    render(<Combobox options={people} multiple showClearAll />);
+    expect(screen.queryByText('Clear all')).not.toBeInTheDocument();
+  });
+
+  test('disabled combobox cannot be interacted with', async () => {
+    render(<Combobox options={people} disabled placeholder="Disabled" />);
+    const input = screen.getByRole('combobox');
+    expect(input).toBeDisabled();
+
+    await userEvent.click(input);
+    expect(screen.queryByRole('listbox')).not.toBeInTheDocument();
+  });
+
+  test('disabled options cannot be selected via click', async () => {
+    const onValueChange = vi.fn();
+    const opts: ComboboxOption[] = [
+      { value: 'a', label: 'Enabled' },
+      { value: 'b', label: 'Disabled', disabled: true },
+    ];
+    render(<Combobox options={opts} onValueChange={onValueChange} />);
+
+    await openWithChevron();
+    await userEvent.click(screen.getByText('Disabled'));
+
+    expect(onValueChange).not.toHaveBeenCalled();
+  });
+
+  test('renders option groups with headers', async () => {
+    const grouped: ComboboxOption[] = [
+      { value: 'a', label: 'Alice', group: 'Team A' },
+      { value: 'b', label: 'Bob', group: 'Team B' },
+    ];
+    render(<Combobox options={grouped} />);
+
+    await openWithChevron();
+
+    expect(screen.getByText('Team A')).toBeInTheDocument();
+    expect(screen.getByText('Team B')).toBeInTheDocument();
+  });
+
+  test('multi-select shows aria-selected on selected options', async () => {
+    render(<Combobox options={people} multiple defaultValue={['alice']} />);
+    await openWithChevron();
+
+    const options = screen.getAllByRole('option');
+    const aliceOption = options.find(o => o.textContent?.includes('Alice'));
+    expect(aliceOption).toHaveAttribute('aria-selected', 'true');
+  });
+
+  test('listbox has aria-multiselectable in multi mode', async () => {
+    render(<Combobox options={people} multiple />);
+    await openWithChevron();
+
+    const listbox = screen.getByRole('listbox');
+    expect(listbox).toHaveAttribute('aria-multiselectable', 'true');
+  });
+
+  test('loading state sets aria-busy, role=status (spinner only, accessible name), and hides options', async () => {
+    render(
+      <Combobox options={people} loading onSearch={() => {}} aria-label="People" />,
+    );
+    await openWithChevron();
+
+    const input = screen.getByRole('combobox');
+    const listbox = screen.getByRole('listbox');
+    expect(listbox).toHaveAttribute('aria-busy', 'true');
+    expect(input).toHaveAttribute('aria-busy', 'true');
+
+    const status = screen.getByRole('status', { name: 'Loading suggestions' });
+    expect(status.querySelector('.ds-combobox__loading-spinner')).toBeInTheDocument();
+    expect(within(listbox).queryAllByRole('option')).toHaveLength(0);
+  });
+
+  test('loading is false does not set aria-busy on listbox', async () => {
+    render(<Combobox options={people} onSearch={() => {}} />);
+    await openWithChevron();
+
+    expect(screen.getByRole('listbox')).not.toHaveAttribute('aria-busy');
+    expect(screen.getByRole('combobox')).not.toHaveAttribute('aria-busy');
+  });
+
+  describe('delete created items', () => {
+    const setupCreate = () => {
+      const onCreateNew = vi.fn((name: string) => ({
+        value: name.toLowerCase().replace(/\s/g, '-'),
+        label: name,
+      }));
+      const onDeleteCreated = vi.fn();
+      const onValueChange = vi.fn();
+
+      render(
+        <Combobox
+          options={people}
+          multiple
+          allowCreate
+          onCreateNew={onCreateNew}
+          onDeleteCreated={onDeleteCreated}
+          onValueChange={onValueChange}
+        />,
+      );
+
+      return { onCreateNew, onDeleteCreated, onValueChange };
+    };
+
+    const highlightCreatedOption = async () => {
+      const input = screen.getByRole('combobox');
+      const listbox = screen.getByRole('listbox');
+      const createdRow = within(listbox).getByText('NewPerson').closest('.ds-combobox__option-row');
+      expect(createdRow).toBeInTheDocument();
+      fireEvent.mouseEnter(createdRow!);
+      input.focus();
+      return input;
+    };
+
+    test('created items show a trash button with title `Delete ${option.label}`', async () => {
+      setupCreate();
+      const input = screen.getByRole('combobox');
+
+      await userEvent.type(input, 'NewPerson');
+      await userEvent.keyboard('{Enter}');
+
+      await openWithChevron();
+
+      const deleteBtn = screen.getByRole('button', { name: 'Delete NewPerson' });
+      expect(deleteBtn).toBeInTheDocument();
+      expect(deleteBtn).toHaveAttribute('title', 'Delete NewPerson');
+      expect(deleteBtn).toHaveAttribute('tabindex', '-1');
+    });
+
+    test('original options do not show trash button', async () => {
+      setupCreate();
+      await openWithChevron();
+
+      expect(screen.queryByTitle('Delete NewPerson')).not.toBeInTheDocument();
+    });
+
+    test('ArrowRight from a highlighted created item focuses its delete button', async () => {
+      setupCreate();
+      const input = screen.getByRole('combobox');
+
+      await userEvent.type(input, 'NewPerson');
+      await userEvent.keyboard('{Enter}');
+      await openWithChevron();
+      await highlightCreatedOption();
+
+      const deleteBtn = screen.getByRole('button', { name: 'Delete NewPerson' });
+      expect(deleteBtn).toHaveAttribute('tabindex', '0');
+
+      await userEvent.keyboard('{ArrowRight}');
+      expect(deleteBtn).toHaveFocus();
+      expect(screen.getByRole('listbox')).toBeInTheDocument();
+    });
+
+    test('ArrowLeft from a created delete button returns focus to the input', async () => {
+      setupCreate();
+      const input = screen.getByRole('combobox');
+
+      await userEvent.type(input, 'NewPerson');
+      await userEvent.keyboard('{Enter}');
+      await openWithChevron();
+      await highlightCreatedOption();
+      await userEvent.keyboard('{ArrowRight}');
+
+      const deleteBtn = screen.getByRole('button', { name: 'Delete NewPerson' });
+      expect(deleteBtn).toHaveFocus();
+
+      await userEvent.keyboard('{ArrowLeft}');
+      expect(input).toHaveFocus();
+      expect(deleteBtn).toHaveAttribute('tabindex', '0');
+    });
+
+    test('Tab and Shift+Tab move between the input and the highlighted created delete button', async () => {
+      setupCreate();
+      const input = screen.getByRole('combobox');
+
+      await userEvent.type(input, 'NewPerson');
+      await userEvent.keyboard('{Enter}');
+      await openWithChevron();
+      await highlightCreatedOption();
+
+      const deleteBtn = screen.getByRole('button', { name: 'Delete NewPerson' });
+      await userEvent.tab();
+      expect(deleteBtn).toHaveFocus();
+      expect(screen.getByRole('listbox')).toBeInTheDocument();
+
+      await userEvent.tab({ shift: true });
+      expect(input).toHaveFocus();
+    });
+
+    test('clicking trash removes the option from the list and fires onDeleteCreated', async () => {
+      const { onDeleteCreated } = setupCreate();
+      const input = screen.getByRole('combobox');
+
+      await userEvent.type(input, 'NewPerson');
+      await userEvent.keyboard('{Enter}');
+
+      await openWithChevron();
+
+      const deleteBtn = screen.getByRole('button', { name: 'Delete NewPerson' });
+      await userEvent.click(deleteBtn);
+
+      expect(onDeleteCreated).toHaveBeenCalledWith('newperson');
+
+      const listbox = screen.queryByRole('listbox');
+      if (listbox) {
+        const remainingOptions = within(listbox).getAllByRole('option');
+        const labels = remainingOptions.map(o => o.textContent);
+        expect(labels.some(l => l?.includes('NewPerson'))).toBe(false);
+      }
+    });
+
+    test('deleting a selected item also removes the chip', async () => {
+      const { onValueChange } = setupCreate();
+      const input = screen.getByRole('combobox');
+
+      await userEvent.type(input, 'NewPerson');
+      await userEvent.keyboard('{Enter}');
+
+      await openWithChevron();
+
+      const deleteBtn = screen.getByRole('button', { name: 'Delete NewPerson' });
+      await userEvent.click(deleteBtn);
+
+      expect(onValueChange).toHaveBeenLastCalledWith([]);
+    });
+
+    test('trash click does not select/deselect the option (stopPropagation)', async () => {
+      const { onValueChange } = setupCreate();
+      const input = screen.getByRole('combobox');
+
+      await userEvent.type(input, 'NewPerson');
+      await userEvent.keyboard('{Enter}');
+
+      onValueChange.mockClear();
+
+      await openWithChevron();
+      const deleteBtn = screen.getByRole('button', { name: 'Delete NewPerson' });
+      await userEvent.click(deleteBtn);
+
+      const calls = onValueChange.mock.calls;
+      expect(calls.length).toBe(1);
+      expect(calls[0]![0]).toEqual([]);
+    });
+  });
+
+  describe('chip keyboard navigation', () => {
+    test('ArrowLeft at caret 0 focuses the last chip', () => {
+      render(<Combobox options={people} multiple defaultValue={['alice', 'bob']} />);
+      const input = screen.getByRole('combobox');
+      input.focus();
+
+      fireEvent.keyDown(input, { key: 'ArrowLeft' });
+
+      const tags = document.querySelectorAll('.ds-tag');
+      expect(tags[1]).toHaveClass('ds-tag--selected');
+      expect(tags[0]).not.toHaveClass('ds-tag--selected');
+    });
+
+    test('ArrowLeft navigates through chips from right to left', () => {
+      render(<Combobox options={people} multiple defaultValue={['alice', 'bob', 'charlie']} />);
+      const input = screen.getByRole('combobox');
+      input.focus();
+
+      fireEvent.keyDown(input, { key: 'ArrowLeft' });
+      fireEvent.keyDown(input, { key: 'ArrowLeft' });
+
+      const tags = document.querySelectorAll('.ds-tag');
+      expect(tags[1]).toHaveClass('ds-tag--selected');
+      expect(tags[2]).not.toHaveClass('ds-tag--selected');
+    });
+
+    test('ArrowLeft does not go past the first chip', () => {
+      render(<Combobox options={people} multiple defaultValue={['alice', 'bob']} />);
+      const input = screen.getByRole('combobox');
+      input.focus();
+
+      fireEvent.keyDown(input, { key: 'ArrowLeft' });
+      fireEvent.keyDown(input, { key: 'ArrowLeft' });
+      fireEvent.keyDown(input, { key: 'ArrowLeft' });
+
+      const tags = document.querySelectorAll('.ds-tag');
+      expect(tags[0]).toHaveClass('ds-tag--selected');
+    });
+
+    test('ArrowRight past the last chip returns focus to input (exits chip nav)', () => {
+      render(<Combobox options={people} multiple defaultValue={['alice', 'bob']} />);
+      const input = screen.getByRole('combobox');
+      input.focus();
+
+      fireEvent.keyDown(input, { key: 'ArrowLeft' });
+      expect(document.querySelectorAll('.ds-tag--selected')).toHaveLength(1);
+
+      fireEvent.keyDown(input, { key: 'ArrowRight' });
+      expect(document.querySelectorAll('.ds-tag--selected')).toHaveLength(0);
+    });
+
+    test('Backspace on focused chip removes it', () => {
+      const onValueChange = vi.fn();
+      render(
+        <Combobox options={people} multiple defaultValue={['alice', 'bob', 'charlie']} onValueChange={onValueChange} />,
+      );
+      const input = screen.getByRole('combobox');
+      input.focus();
+
+      fireEvent.keyDown(input, { key: 'ArrowLeft' });
+      fireEvent.keyDown(input, { key: 'ArrowLeft' });
+      fireEvent.keyDown(input, { key: 'Backspace' });
+
+      expect(onValueChange).toHaveBeenCalledWith(['alice', 'charlie']);
+    });
+
+    test('Delete on focused chip removes it', () => {
+      const onValueChange = vi.fn();
+      render(
+        <Combobox options={people} multiple defaultValue={['alice', 'bob']} onValueChange={onValueChange} />,
+      );
+      const input = screen.getByRole('combobox');
+      input.focus();
+
+      fireEvent.keyDown(input, { key: 'ArrowLeft' });
+      fireEvent.keyDown(input, { key: 'ArrowLeft' });
+      fireEvent.keyDown(input, { key: 'Delete' });
+
+      expect(onValueChange).toHaveBeenCalledWith(['bob']);
+    });
+
+    test('Backspace on first chip focuses next or exits', () => {
+      const onValueChange = vi.fn();
+      render(
+        <Combobox options={people} multiple defaultValue={['alice']} onValueChange={onValueChange} />,
+      );
+      const input = screen.getByRole('combobox');
+      input.focus();
+
+      fireEvent.keyDown(input, { key: 'ArrowLeft' });
+      fireEvent.keyDown(input, { key: 'Backspace' });
+
+      expect(onValueChange).toHaveBeenCalledWith([]);
+      expect(document.querySelectorAll('.ds-tag--selected')).toHaveLength(0);
+    });
+
+    test('typing exits chip nav mode', async () => {
+      render(<Combobox options={people} multiple defaultValue={['alice', 'bob']} />);
+      const input = screen.getByRole('combobox');
+      input.focus();
+
+      fireEvent.keyDown(input, { key: 'ArrowLeft' });
+      expect(document.querySelectorAll('.ds-tag--selected')).toHaveLength(1);
+
+      await userEvent.type(input, 'c');
+      expect(document.querySelectorAll('.ds-tag--selected')).toHaveLength(0);
+    });
+
+    test('Escape exits chip nav mode', () => {
+      render(<Combobox options={people} multiple defaultValue={['alice', 'bob']} />);
+      const input = screen.getByRole('combobox');
+      input.focus();
+
+      fireEvent.keyDown(input, { key: 'ArrowLeft' });
+      expect(document.querySelectorAll('.ds-tag--selected')).toHaveLength(1);
+
+      fireEvent.keyDown(input, { key: 'Escape' });
+      expect(document.querySelectorAll('.ds-tag--selected')).toHaveLength(0);
+    });
+
+    test('Cmd+A during chip nav enters bulk-select-all mode', () => {
+      render(<Combobox options={people} multiple defaultValue={['alice', 'bob']} />);
+      const input = screen.getByRole('combobox');
+      input.focus();
+
+      fireEvent.keyDown(input, { key: 'ArrowLeft' });
+      expect(document.querySelectorAll('.ds-tag--selected')).toHaveLength(1);
+
+      fireEvent.keyDown(input, { key: 'a', metaKey: true });
+      expect(document.querySelectorAll('.ds-tag--selected')).toHaveLength(2);
+    });
+
+    test('ArrowLeft does nothing when input has text and caret is not at 0', async () => {
+      render(<Combobox options={people} multiple defaultValue={['alice']} />);
+      const input = screen.getByRole('combobox');
+      await userEvent.type(input, 'test');
+
+      fireEvent.keyDown(input, { key: 'ArrowLeft' });
+      expect(document.querySelectorAll('.ds-tag--selected')).toHaveLength(0);
+    });
+  });
+});