Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
127 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
 * @file TokenizerBottomSheet.test.tsx
 * @input Uses vitest, Testing Library, Tokenizer with `presentation`
 * @output Tests for the sheet presentation: the presentation resolution and
 *   its default (`component:Tokenizer` FR16) and the single-sheet touch flow
 *   (FR17–FR24, AR6)
 * @position Core tests; validates Tokenizer.tsx and TokenizerBottomSheet.tsx
 */
import {
  afterEach,
  beforeAll,
  beforeEach,
  describe,
  expect,
  it,
  vi,
} from 'vitest';
import {
  act,
  cleanup,
  fireEvent,
  render,
  screen,
  waitFor,
  within,
} from '@testing-library/react';
import {StrictMode, createRef, useState, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import {
  Tokenizer,
  type TokenizerChange,
  type TokenizerProps,
} from './Tokenizer';
import {Token} from '../Token/Token';
import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
import {__resetDevWarnings} from '../utils/devWarning';
import {colorVars, sizeVars, spacingVars} from '../theme/tokens.stylex';
import {inputWrapperStyles} from '../Field/inputStyles.stylex';
import type {SearchSource, SearchableItem} from '../Typeahead/types';

import {COMPACT_TOUCH_PRESENTATION_QUERY as COMPACT_TOUCH_QUERY} from '../hooks/useAdaptivePresentation';
import {BottomSheet} from '../BottomSheet/BottomSheet';
import {
  getBottomSheetStackForTests,
  resetBottomSheetStackForTests,
} from '../BottomSheet/bottomSheetStack';
import {getActiveModalOutlet} from '../Layer/modalOutlet';

// Tokenizer loads its sheet on demand, and a first load under the test
// transform can take seconds on a busy machine. The file loads the sheet
// module before any test runs, so that load counts against no wait or time
// limit.
await import('./TokenizerBottomSheet');

const ITEMS: SearchableItem[] = [
  {id: 'design', label: 'Design'},
  {id: 'eng', label: 'Eng'},
  {id: 'engineer', label: 'Engineer'},
  {id: 'energizer', label: 'Energizer'},
];
const source: SearchSource<SearchableItem> = {
  search: q =>
    ITEMS.filter(item => item.label.toLowerCase().includes(q.toLowerCase())),
  bootstrap: () => ITEMS,
};

type Presentation = 'popover' | 'bottom-sheet' | 'adaptive';

const DEFAULT_INITIAL = [ITEMS[0], ITEMS[1]];

function Harness({
  spy,
  presentation = 'bottom-sheet',
  initial = DEFAULT_INITIAL,
  ...props
}: {
  spy?: (
    items: SearchableItem[],
    change: TokenizerChange<SearchableItem>,
  ) => void;
  presentation?: Presentation;
  initial?: SearchableItem[];
  hasCreate?: boolean;
  hasClear?: boolean;
  maxEntries?: number;
  isDisabled?: boolean;
  disabledMessage?: string;
  'aria-labelledby'?: string;
  debounceMs?: number;
  onFocus?: (event: React.FocusEvent) => void;
  onBlur?: (event: React.FocusEvent) => void;
  endContent?: ReactNode;
  renderToken?: (item: SearchableItem, onRemove: () => void) => ReactNode;
}) {
  const [value, setValue] = useState<SearchableItem[]>(initial);
  return (
    <Tokenizer
      label="Tags"
      searchSource={source}
      value={value}
      debounceMs={0}
      placeholder="Add tags"
      onChange={(items, change) => {
        setValue(items);
        spy?.(items, change);
      }}
      presentation={presentation}
      {...props}
    />
  );
}

function stubMatchMedia(matcher: (query: string) => boolean) {
  vi.stubGlobal(
    'matchMedia',
    vi.fn().mockImplementation((query: string) => ({
      matches: matcher(query),
      media: query,
      onchange: null,
      addEventListener: vi.fn(),
      removeEventListener: vi.fn(),
      addListener: vi.fn(),
      removeListener: vi.fn(),
      dispatchEvent: vi.fn(),
    })),
  );
}

function stubEnvironment() {
  HTMLDialogElement.prototype.showModal = vi.fn(function (
    this: HTMLDialogElement,
  ) {
    this.setAttribute('open', '');
  });
  HTMLDialogElement.prototype.show = vi.fn(function (this: HTMLDialogElement) {
    this.setAttribute('open', '');
  });
  HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {
    this.removeAttribute('open');
  });
  if (!Element.prototype.setPointerCapture) {
    Element.prototype.setPointerCapture = vi.fn();
    Element.prototype.releasePointerCapture = vi.fn();
  }
  stubMatchMedia(() => false);
  window.scrollTo = vi.fn();
}

const openTrigger = () => screen.getByRole('button', {name: 'Tags'});
// The sheet field's control box: it holds the trigger button, the tokens and
// the end lane.
const sheetField = () =>
  openTrigger().closest<HTMLElement>('.astryx-tokenizer')!;
// The row list carries the progressive-rendering counters (FR21).
const list = () => document.querySelector<HTMLElement>('[data-total-count]')!;

// The sheet surface is loaded with React.lazy, so the first sheet renders a
// tick after it opens. Open one up front so every later sheet renders
// synchronously. `act` renders the sheet once its loaded module resolves,
// with no wait.
beforeAll(async () => {
  stubEnvironment();
  try {
    render(<Harness />);
    await act(async () => {
      fireEvent.click(openTrigger());
    });
    expect(screen.getByLabelText('Search Tags')).toBeInTheDocument();
  } finally {
    cleanup();
    vi.unstubAllGlobals();
  }
});

beforeEach(() => {
  __resetLiveRegionsForTest();
  resetBottomSheetStackForTests();
  stubEnvironment();
});
afterEach(() => vi.unstubAllGlobals());

describe('Tokenizer presentation (FR16)', () => {
  const plain = (props: Partial<TokenizerProps<SearchableItem>> = {}) => (
    <Tokenizer
      label="Tags"
      searchSource={source}
      value={[ITEMS[0]]}
      onChange={() => {}}
      {...props}
    />
  );

  it('keeps the inline combobox by default on a screen that is not compact coarse-pointer', () => {
    render(plain());
    expect(screen.getByRole('combobox')).toBeInTheDocument();
    expect(
      screen.queryByRole('button', {name: 'Tags'}),
    ).not.toBeInTheDocument();
  });

  it('defaults to adaptive: the sheet trigger on a compact coarse-pointer screen', () => {
    stubMatchMedia(() => true);
    render(plain());
    expect(screen.queryByRole('combobox')).not.toBeInTheDocument();
    expect(openTrigger()).toHaveAttribute('aria-haspopup', 'dialog');
  });

  it('keeps the inline combobox with presentation="popover" on a compact coarse-pointer screen', () => {
    stubMatchMedia(() => true);
    render(<Harness presentation="popover" />);
    expect(screen.getByRole('combobox')).toBeInTheDocument();
    expect(
      screen.queryByRole('button', {name: 'Tags'}),
    ).not.toBeInTheDocument();
  });

  it('forces the sheet trigger for bottom-sheet on every device', async () => {
    render(<Harness presentation="bottom-sheet" />);
    expect(screen.queryByRole('combobox')).not.toBeInTheDocument();
    const trigger = openTrigger();
    expect(trigger).toHaveAttribute('aria-haspopup', 'dialog');
    expect(trigger).toHaveAttribute('aria-expanded', 'false');
    expect(sheetField()).toHaveTextContent('Design');
    expect(sheetField()).toHaveTextContent('Eng');
    // The field's tokens are display-only (FR17): the trigger is its only
    // button.
    expect(within(sheetField()).getAllByRole('button')).toEqual([trigger]);

    fireEvent.click(trigger);
    expect(trigger).toHaveAttribute('aria-expanded', 'true');
    const sheet = await screen.findByRole('dialog', {name: 'Tags'});
    expect(sheet).toBeInTheDocument();
    expect(HTMLDialogElement.prototype.showModal).toHaveBeenCalled();
  });

  it('uses the sheet for adaptive presentation on compact touch', async () => {
    stubMatchMedia(query => query === COMPACT_TOUCH_QUERY);
    render(<Harness presentation="adaptive" />);
    expect(screen.queryByRole('combobox')).not.toBeInTheDocument();
    fireEvent.click(openTrigger());
    expect(
      await screen.findByRole('dialog', {name: 'Tags'}),
    ).toBeInTheDocument();
  });

  it('keeps adaptive presentation inline without compact touch', () => {
    render(<Harness presentation="adaptive" />);
    expect(screen.getByRole('combobox')).toBeInTheDocument();
    expect(
      screen.queryByRole('button', {name: 'Tags'}),
    ).not.toBeInTheDocument();
    expect(HTMLDialogElement.prototype.showModal).not.toHaveBeenCalled();
  });

  it('shows the trigger placeholder when nothing is selected', () => {
    render(<Harness initial={[]} />);
    expect(openTrigger()).toHaveTextContent('Add tags');
  });
});

describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {
  it('names the sheet trigger by its label, then a caller aria-labelledby', () => {
    render(
      <>
        <span id="billing-heading">Billing</span>
        <Harness aria-labelledby="billing-heading" />
      </>,
    );
    expect(screen.getByRole('button', {name: 'Tags Billing'})).toBeTruthy();
  });

  it('keeps rows stable while open and applies selected-first order on reopen (FR19)', async () => {
    const spy = vi.fn();
    render(<Harness spy={spy} />);
    const trigger = openTrigger();
    fireEvent.click(trigger);

    await screen.findByRole('checkbox', {name: 'Energizer'});
    const checkboxLabels = () =>
      within(list())
        .getAllByRole('checkbox')
        .map(row => row.getAttribute('aria-label'));
    expect(checkboxLabels()).toEqual([
      'Design',
      'Eng',
      'Engineer',
      'Energizer',
    ]);
    expect(screen.getByLabelText('Search Tags')).toBeInTheDocument();
    expect(
      screen.queryByRole('button', {name: 'Add item'}),
    ).not.toBeInTheDocument();
    const design = screen.getByRole('checkbox', {name: 'Design'});
    expect(design).toBeChecked();
    expect(design.lastElementChild).toHaveAttribute('aria-hidden', 'true');
    expect(design.lastElementChild).toHaveAttribute('data-size', 'md');

    fireEvent.click(screen.getByRole('checkbox', {name: 'Energizer'}));
    // The draft changed; `value` and `onChange` wait for Save (FR26).
    expect(spy).not.toHaveBeenCalled();
    await waitFor(() =>
      expect(screen.getByRole('checkbox', {name: 'Energizer'})).toBeChecked(),
    );
    expect(checkboxLabels()).toEqual([
      'Design',
      'Eng',
      'Engineer',
      'Energizer',
    ]);

    fireEvent.click(screen.getByRole('checkbox', {name: 'Eng'}));
    expect(spy).not.toHaveBeenCalled();
    expect(screen.getByRole('checkbox', {name: 'Eng'})).not.toBeChecked();
    expect(checkboxLabels()).toEqual([
      'Design',
      'Eng',
      'Engineer',
      'Energizer',
    ]);

    // Save reports the whole draft once, with the last edit that holds.
    fireEvent.click(screen.getByRole('button', {name: 'Save'}));
    expect(spy).toHaveBeenCalledTimes(1);
    expect(spy).toHaveBeenCalledWith([ITEMS[0], ITEMS[3]], {
      item: ITEMS[1],
      type: 'remove',
    });
    expect(trigger).toHaveAttribute('aria-expanded', 'false');

    await act(async () => {
      fireEvent.click(trigger);
    });
    expect(checkboxLabels()).toEqual([
      'Design',
      'Energizer',
      'Eng',
      'Engineer',
    ]);
  });

  it('announces additions, removals, and the busy start inside the open modal sheet, not on the page body (AR6; AST-086 FR14)', async () => {
    // jsdom has no showModal(), so an open dialog never matches `:modal`;
    // stand in for the sheet the browser presents modally.
    const matches = Element.prototype.matches;
    const spy = vi
      .spyOn(Element.prototype, 'matches')
      .mockImplementation(function (this: Element, selector: string) {
        return selector === ':modal'
          ? this instanceof HTMLDialogElement && this.open
          : matches.call(this, selector);
      });
    try {
      // A real debounce, so a typed query has a busy window to announce.
      render(<Harness debounceMs={50} />);
      fireEvent.click(openTrigger());
      const dialog = await screen.findByRole('dialog', {name: 'Tags'});
      const region = () =>
        dialog.querySelector(
          ':scope > [data-astryx-modal-live-region="polite"]',
        );
      const shared = () =>
        document.querySelector('[data-astryx-live-region="polite"]');
      // An instant bootstrap announces no busy start; a debounced typed
      // query does, in the sheet, before its results land.
      await screen.findByRole('checkbox', {name: 'Energizer'});
      expect(region()).toBeNull();
      fireEvent.change(screen.getByLabelText('Search Tags'), {
        target: {value: 'E'},
      });
      await waitFor(() => expect(region()).toHaveTextContent('Loading'));
      fireEvent.change(screen.getByLabelText('Search Tags'), {
        target: {value: ''},
      });
      fireEvent.click(await screen.findByRole('checkbox', {name: 'Energizer'}));
      await waitFor(() =>
        expect(region()).toHaveTextContent('Added Energizer'),
      );
      expect(region()).toHaveAttribute('role', 'status');
      expect(dialog.contains(region())).toBe(true);
      expect(shared()?.textContent ?? '').toBe('');
      fireEvent.click(screen.getByRole('checkbox', {name: 'Design'}));
      await waitFor(() => expect(region()).toHaveTextContent('Removed Design'));
      expect(shared()?.textContent ?? '').toBe('');
      // How a search ended: the result count for a typed query …
      fireEvent.change(screen.getByLabelText('Search Tags'), {
        target: {value: 'En'},
      });
      await waitFor(() => expect(region()).toHaveTextContent('3 results'));
      // … and the empty state's words when it shows.
      fireEvent.change(screen.getByLabelText('Search Tags'), {
        target: {value: 'zzz'},
      });
      await waitFor(() =>
        expect(region()).toHaveTextContent('No results found'),
      );
      expect(shared()?.textContent ?? '').toBe('');
    } finally {
      spy.mockRestore();
    }
  });

  it('keeps the inline popover presentation on the shared live region', async () => {
    render(
      <Tokenizer
        label="Tags"
        searchSource={source}
        value={[ITEMS[0], ITEMS[1]]}
        onChange={() => {}}
        debounceMs={0}
      />,
    );
    // Backspace on the empty input removes the last token through the
    // same path the sheet's rows use.
    const input = screen.getByRole('combobox');
    input.focus();
    fireEvent.keyDown(input, {key: 'Backspace'});
    await waitFor(() =>
      expect(
        document.querySelector('[data-astryx-live-region="polite"]'),
      ).toHaveTextContent('Removed Eng'),
    );
    expect(
      document.querySelector('[data-astryx-modal-live-region]'),
    ).toBeNull();
  });

  it('creates a custom entry with a trailing Add action and announces the created value (FR22)', async () => {
    // jsdom has no showModal(); stand in for the sheet presented modally so
    // the announcement takes the in-dialog route.
    const matches = Element.prototype.matches;
    const modalSpy = vi
      .spyOn(Element.prototype, 'matches')
      .mockImplementation(function (this: Element, selector: string) {
        return selector === ':modal'
          ? this instanceof HTMLDialogElement && this.open
          : matches.call(this, selector);
      });
    try {
      const spy = vi.fn();
      render(<Harness spy={spy} hasCreate initial={[]} />);
      const trigger = openTrigger();
      fireEvent.click(trigger);
      const search = await screen.findByLabelText('Search Tags');
      fireEvent.change(search, {target: {value: 'Custom'}});

      expect(
        screen.queryByRole('checkbox', {name: 'Create "Custom"'}),
      ).not.toBeInTheDocument();
      const create = await screen.findByRole('button', {name: 'Add Custom'});
      // The footer stays pinned while searching (FR18).
      expect(
        screen.getByRole('button', {name: 'Clear all'}),
      ).toBeInTheDocument();
      expect(screen.getByRole('button', {name: 'Save'})).toBeInTheDocument();
      expect(create).toHaveAttribute('data-size', 'lg');
      expect(screen.getByText('Create "Custom"')).toBeInTheDocument();
      await act(async () => {
        fireEvent.click(create);
      });
      // The created item joins the draft; the trigger and `onChange` wait
      // for Save (FR22, FR26), which then reports the create.
      expect(spy).not.toHaveBeenCalled();
      expect(sheetField()).not.toHaveTextContent('Custom');
      expect(search).toHaveValue('');
      const custom = await screen.findByRole('checkbox', {name: 'Custom'});
      expect(custom).toBeChecked();
      // Announced inside the sheet as the created value, not the row's
      // caption ("Create …"), as the inline field announces it.
      const dialog = screen.getByRole('dialog', {name: 'Tags'});
      await waitFor(() =>
        expect(
          dialog.querySelector(
            ':scope > [data-astryx-modal-live-region="polite"]',
          ),
        ).toHaveTextContent('Added Custom'),
      );
      expect(
        dialog.querySelector(
          ':scope > [data-astryx-modal-live-region="polite"]',
        ),
      ).not.toHaveTextContent('Create');
      fireEvent.click(screen.getByRole('button', {name: 'Save'}));
      expect(spy).toHaveBeenCalledTimes(1);
      expect(spy).toHaveBeenCalledWith([{id: 'Custom', label: 'Custom'}], {
        item: {id: 'Custom', label: 'Custom'},
        type: 'create',
      });
      await waitFor(() => expect(sheetField()).toHaveTextContent('Custom'));
    } finally {
      modalSpy.mockRestore();
    }
  });
  it('offers no create row for text that matches a selected label or a result', async () => {
    render(<Harness hasCreate />);
    fireEvent.click(openTrigger());
    const search = await screen.findByLabelText('Search Tags');
    fireEvent.change(search, {target: {value: 'design'}});
    await screen.findByRole('checkbox', {name: 'Design'});
    expect(
      screen.queryByRole('button', {name: /^Add /}),
    ).not.toBeInTheDocument();
    fireEvent.change(search, {target: {value: 'ENGINEER'}});
    await screen.findByRole('checkbox', {name: 'Engineer'});
    expect(
      screen.queryByRole('button', {name: /^Add /}),
    ).not.toBeInTheDocument();
  });

  it('renders long lists in 50-item batches and resets the window for search (FR21)', async () => {
    const longItems: SearchableItem[] = Array.from(
      {length: 120},
      (_, index) => ({
        id: `item-${index + 1}`,
        label: `Item ${String(index + 1).padStart(3, '0')}`,
      }),
    );
    const longSource: SearchSource<SearchableItem> = {
      bootstrap: () => longItems,
      search: query =>
        longItems.filter(item =>
          item.label.toLowerCase().includes(query.toLowerCase()),
        ),
    };
    render(
      <Tokenizer
        label="Items"
        searchSource={longSource}
        value={[]}
        onChange={() => {}}
        maxMenuItems={120}
        debounceMs={0}
        presentation="bottom-sheet"
      />,
    );
    fireEvent.click(screen.getByRole('button', {name: 'Items'}));
    await screen.findByRole('checkbox', {name: 'Item 001'});
    const items = list();
    await waitFor(() => {
      expect(items).toHaveAttribute('data-rendered-count', '50');
      expect(items).toHaveAttribute('data-total-count', '120');
    });
    expect(screen.getAllByRole('checkbox')).toHaveLength(50);
    expect(
      screen.queryByRole('checkbox', {name: 'Item 051'}),
    ).not.toBeInTheDocument();
    // Every row's listitem names its place in the whole set, not the
    // rendered window; `checkbox` does not admit the position attributes,
    // so they sit on the listitem that wraps each row.
    const rowList = within(items).getByRole('list');
    const listItems = within(rowList).getAllByRole('listitem');
    expect(listItems).toHaveLength(50);
    expect(listItems[0]).toHaveAttribute('aria-setsize', '120');
    expect(listItems[0]).toHaveAttribute('aria-posinset', '1');
    expect(
      within(listItems[0]).getByRole('checkbox', {name: 'Item 001'}),
    ).toBeInTheDocument();
    expect(listItems[49]).toHaveAttribute('aria-setsize', '120');
    expect(listItems[49]).toHaveAttribute('aria-posinset', '50');
    const first = screen.getByRole('checkbox', {name: 'Item 001'});
    expect(first).not.toHaveAttribute('aria-setsize');
    expect(first).not.toHaveAttribute('aria-posinset');
    const fiftieth = screen.getByRole('checkbox', {name: 'Item 050'});
    // Focus reaching the last rendered row renders the next batch, so a
    // keyboard user reaches every row without scrolling.
    fiftieth.focus();
    await waitFor(() =>
      expect(items).toHaveAttribute('data-rendered-count', '100'),
    );
    expect(
      screen
        .getByRole('checkbox', {name: 'Item 051'})
        .closest('[role="listitem"]'),
    ).toHaveAttribute('aria-posinset', '51');
    screen.getByRole('checkbox', {name: 'Item 100'}).focus();
    await waitFor(() =>
      expect(items).toHaveAttribute('data-rendered-count', '120'),
    );
    // The window is back to one batch for the scroll part of the test.
    fireEvent.change(screen.getByLabelText('Search Items'), {
      target: {value: 'Item'},
    });
    await waitFor(() =>
      expect(items).toHaveAttribute('data-rendered-count', '50'),
    );
    fireEvent.change(screen.getByLabelText('Search Items'), {
      target: {value: ''},
    });
    await waitFor(() =>
      expect(items).toHaveAttribute('data-rendered-count', '50'),
    );

    Object.defineProperties(items, {
      clientHeight: {configurable: true, value: 600},
      scrollHeight: {configurable: true, value: 2400},
      scrollTop: {configurable: true, value: 1700, writable: true},
    });
    fireEvent.scroll(items);
    expect(items).toHaveAttribute('data-rendered-count', '100');
    expect(screen.getAllByRole('checkbox')).toHaveLength(100);
    expect(
      screen.getByRole('checkbox', {name: 'Item 100'}),
    ).toBeInTheDocument();

    Object.defineProperties(items, {
      scrollHeight: {configurable: true, value: 4400},
      scrollTop: {configurable: true, value: 3600, writable: true},
    });
    fireEvent.scroll(items);
    expect(items).toHaveAttribute('data-rendered-count', '120');
    expect(screen.getAllByRole('checkbox')).toHaveLength(120);

    fireEvent.change(screen.getByLabelText('Search Items'), {
      target: {value: 'Item'},
    });
    await waitFor(() =>
      expect(items).toHaveAttribute('data-rendered-count', '50'),
    );
    expect(screen.getAllByRole('checkbox')).toHaveLength(50);

    fireEvent.scroll(items);
    expect(items).toHaveAttribute('data-rendered-count', '100');
    expect(screen.getAllByRole('checkbox')).toHaveLength(100);
  });

  it('searches within the same sheet and shows the no-results state (FR18, FR20)', async () => {
    const onChangeQuery = vi.fn();
    const {rerender} = render(
      <Tokenizer
        label="Tags"
        searchSource={source}
        value={[ITEMS[0]]}
        onChange={() => {}}
        debounceMs={0}
        onChangeQuery={onChangeQuery}
        presentation="bottom-sheet"
      />,
    );
    fireEvent.click(openTrigger());
    const search = await screen.findByLabelText('Search Tags');
    fireEvent.change(search, {target: {value: 'zzz'}});
    expect(onChangeQuery).toHaveBeenCalledWith('zzz');

    const title = await screen.findByRole('heading', {
      name: 'No results found',
    });
    // EmptyState is not a live region (it announces itself once when it
    // appears); locate it by its own root.
    const emptyState = title.closest('.astryx-empty-state');
    expect(emptyState).toHaveTextContent('Try a different search.');
    expect(emptyState?.querySelector('.astryx-icon')).toHaveAttribute(
      'data-size',
      'lg',
    );
    // Only one dialog: the sheet searches in place (FR18).
    expect(screen.getAllByRole('dialog')).toHaveLength(1);

    // A string emptySearchText becomes the empty state's title.
    rerender(
      <Tokenizer
        label="Tags"
        searchSource={source}
        value={[ITEMS[0]]}
        onChange={() => {}}
        debounceMs={0}
        emptySearchText="Nothing here"
        presentation="bottom-sheet"
      />,
    );
    expect(
      await screen.findByRole('heading', {name: 'Nothing here'}),
    ).toBeInTheDocument();
  });

  it('shows only the search field for an empty query with nothing to list, as the inline field does — no list, no message, no announcement (FR20)', async () => {
    // A search-only source: typing finds items, the bootstrap set is empty.
    const searchOnly: SearchSource<SearchableItem> = {
      search: (q: string) =>
        ITEMS.filter(item =>
          item.label.toLowerCase().includes(q.toLowerCase()),
        ),
      bootstrap: () => [],
    };
    const matches = Element.prototype.matches;
    const modalSpy = vi
      .spyOn(Element.prototype, 'matches')
      .mockImplementation(function (this: Element, selector: string) {
        return selector === ':modal'
          ? this instanceof HTMLDialogElement && this.open
          : matches.call(this, selector);
      });
    try {
      render(
        <Tokenizer
          label="Tags"
          searchSource={searchOnly}
          value={[]}
          onChange={() => {}}
          debounceMs={0}
          presentation="bottom-sheet"
        />,
      );
      fireEvent.click(openTrigger());
      const dialog = await screen.findByRole('dialog', {name: 'Tags'});
      const search = screen.getByLabelText('Search Tags');
      await act(async () => {
        await Promise.resolve();
      });
      expect(within(dialog).queryByRole('list')).not.toBeInTheDocument();
      expect(within(dialog).queryByRole('heading')).not.toBeInTheDocument();
      expect(screen.queryByText('No items available')).not.toBeInTheDocument();
      expect(dialog.querySelector('.astryx-empty-state')).toBeNull();
      expect(
        within(dialog).queryByRole('img', {name: 'Loading'}),
      ).not.toBeInTheDocument();
      // Nothing is announced for a bootstrap that returned nothing: not in
      // the sheet's region, not on the page body.
      expect(
        dialog.querySelector(
          ':scope > [data-astryx-modal-live-region="polite"]',
        )?.textContent ?? '',
      ).toBe('');
      expect(
        document.querySelector('[data-astryx-live-region="polite"]')
          ?.textContent ?? '',
      ).toBe('');
      // The footer still closes the sheet (FR18); Clear all is spent.
      expect(within(dialog).getByRole('button', {name: 'Save'})).toBeVisible();
      expect(
        within(dialog).getByRole('button', {name: 'Clear all'}),
      ).toHaveAttribute('aria-disabled', 'true');
      // Typing is what finds items.
      fireEvent.change(search, {target: {value: 'En'}});
      await screen.findByRole('checkbox', {name: 'Eng'});
      expect(within(dialog).getByRole('list')).toBeInTheDocument();
      // Clearing returns to the search-only state, silently.
      fireEvent.change(search, {target: {value: ''}});
      await waitFor(() =>
        expect(within(dialog).queryByRole('list')).not.toBeInTheDocument(),
      );
      expect(dialog.querySelector('.astryx-empty-state')).toBeNull();
    } finally {
      modalSpy.mockRestore();
    }
  });

  it('renders nothing of the sheet at rest: the DOM holds the trigger alone until a press, and again once the exit has completed (INV7)', async () => {
    render(<Harness />);
    const trigger = openTrigger();
    // The lazy chunk may load; give it a tick, then check nothing rendered.
    await act(async () => {
      await new Promise(resolve => setTimeout(resolve, 20));
    });
    const sheetDom = () => ({
      dialog: document.querySelector('dialog'),
      sheet: document.querySelector('.astryx-bottom-sheet'),
      checkboxes: screen.queryAllByRole('checkbox').length,
      search: screen.queryByLabelText('Search Tags'),
      confirmation: screen.queryByRole('alertdialog'),
    });
    expect(sheetDom()).toEqual({
      dialog: null,
      sheet: null,
      checkboxes: 0,
      search: null,
      confirmation: null,
    });
    // Each selected label is in the DOM once: the trigger's token.
    expect(screen.getAllByText('Design')).toHaveLength(1);

    fireEvent.click(trigger);
    await screen.findByRole('dialog', {name: 'Tags'});
    expect(sheetDom().dialog).not.toBeNull();

    fireEvent.click(screen.getByRole('button', {name: 'Save'}));
    fireEvent.transitionEnd(document.querySelector('.astryx-bottom-sheet')!, {
      propertyName: 'transform',
    });
    await waitFor(() => expect(trigger).toHaveFocus());
    await waitFor(() => expect(sheetDom().dialog).toBeNull());
    expect(sheetDom()).toEqual({
      dialog: null,
      sheet: null,
      checkboxes: 0,
      search: null,
      confirmation: null,
    });
    expect(screen.getAllByText('Design')).toHaveLength(1);
  });

  it('mounts the Clear all confirmation only from the press until it closes: no alertdialog while none is pending, focus back on Clear all on cancel and on confirm (FR24; INV7)', async () => {
    const matches = Element.prototype.matches;
    const modalSpy = vi
      .spyOn(Element.prototype, 'matches')
      .mockImplementation(function (this: Element, selector: string) {
        return selector === ':modal'
          ? this instanceof HTMLDialogElement && this.open
          : matches.call(this, selector);
      });
    try {
      render(<Harness />);
      fireEvent.click(openTrigger());
      const sheet = await screen.findByRole('dialog', {name: 'Tags'});
      await screen.findByRole('checkbox', {name: 'Eng'});
      const noConfirmation = () => {
        expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument();
        expect(sheet.querySelectorAll('dialog')).toHaveLength(0);
      };
      noConfirmation();
      const clearAll = screen.getByRole('button', {name: 'Clear all'});

      // Cancel: the confirmation goes, focus is back on Clear all, nothing
      // changed, nothing announced.
      clearAll.focus();
      fireEvent.click(clearAll);
      const first = await screen.findByRole('alertdialog');
      expect(sheet.contains(first)).toBe(true);
      fireEvent.click(within(first).getByRole('button', {name: 'Cancel'}));
      await waitFor(noConfirmation);
      expect(clearAll).toHaveFocus();
      expect(screen.getByRole('checkbox', {name: 'Design'})).toBeChecked();

      // Confirm: the confirmation goes, Clear all keeps focus (now
      // aria-disabled), the clear is announced inside the sheet.
      fireEvent.click(clearAll);
      const second = await screen.findByRole('alertdialog');
      fireEvent.click(
        within(second).getByRole('button', {name: 'Clear selection'}),
      );
      await waitFor(noConfirmation);
      expect(screen.getByRole('button', {name: 'Clear all'})).toHaveFocus();
      await waitFor(() =>
        expect(
          sheet.querySelector(
            ':scope > [data-astryx-modal-live-region="polite"]',
          ),
        ).toHaveTextContent('All items removed'),
      );
      // Exactly one live region says it: the field's own region stays silent
      // for a Clear all the sheet already announced.
      const saying = Array.from(
        document.querySelectorAll(
          '[aria-live], [role="status"], [role="alert"]',
        ),
      ).filter(region => region.textContent?.includes('All items removed'));
      expect(saying).toHaveLength(1);
    } finally {
      modalSpy.mockRestore();
    }
  });

  it('keeps large equal-width Clear all and Save footer actions while guarding the bulk clear (FR24)', async () => {
    const spy = vi.fn();
    render(<Harness spy={spy} />);
    fireEvent.click(openTrigger());
    await screen.findByRole('checkbox', {name: 'Energizer'});

    const clearAll = screen.getByRole('button', {name: 'Clear all'});
    const done = screen.getByRole('button', {name: 'Save'});
    expect(clearAll).toHaveAttribute('data-size', 'lg');
    expect(clearAll).toHaveAttribute('data-variant', 'secondary');
    expect(done).toHaveAttribute('data-size', 'lg');
    expect(list().compareDocumentPosition(clearAll)).toBe(
      Node.DOCUMENT_POSITION_FOLLOWING,
    );
    expect(list().compareDocumentPosition(done)).toBe(
      Node.DOCUMENT_POSITION_FOLLOWING,
    );
    fireEvent.click(clearAll);
    const confirmation = screen.getByRole('alertdialog');
    expect(confirmation).toHaveTextContent('Clear all selected items?');
    expect(confirmation).toHaveTextContent(
      'This removes all selected items from Tags.',
    );
    expect(spy).not.toHaveBeenCalled();
    fireEvent.click(
      within(confirmation).getByRole('button', {name: 'Clear selection'}),
    );
    // The clear empties the draft; `value` waits for Save (FR24, FR26).
    expect(spy).not.toHaveBeenCalled();
    await waitFor(() =>
      expect(screen.getByRole('button', {name: 'Clear all'})).toHaveAttribute(
        'aria-disabled',
        'true',
      ),
    );
    fireEvent.click(screen.getByRole('button', {name: 'Save'}));
    expect(spy).toHaveBeenLastCalledWith([], {item: ITEMS[1], type: 'remove'});
  });

  it('keeps a disabled trigger focusable without opening the sheet (FR17; AST-085 FR1, FR2)', () => {
    render(<Harness isDisabled initial={[ITEMS[0]]} />);
    const trigger = openTrigger();
    expect(trigger).not.toHaveAttribute('disabled');
    expect(trigger).toHaveAttribute('aria-disabled', 'true');
    trigger.focus();
    expect(trigger).toHaveFocus();
    fireEvent.click(trigger);
    expect(trigger).toHaveAttribute('aria-expanded', 'false');
    expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
    // A field disabled from the start mounts no sheet at all.
    expect(document.querySelector('dialog')).toBeNull();
    expect(document.querySelector('[data-total-count]')).toBeNull();
  });

  it('keeps focus on Clear all after a confirmed Clear all — aria-disabled, in the focus order — and never moves it to the search field, which would raise the keyboard (FR24; AST-085 FR4)', async () => {
    render(<Harness />);
    fireEvent.click(openTrigger());
    await screen.findByRole('dialog', {name: 'Tags'});
    const clearAll = screen.getByRole('button', {name: 'Clear all'});
    clearAll.focus();
    fireEvent.click(clearAll);
    const confirmation = await screen.findByRole('alertdialog');
    fireEvent.click(
      within(confirmation).getByRole('button', {name: 'Clear selection'}),
    );
    await waitFor(() =>
      expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument(),
    );
    const clearAllAfter = screen.getByRole('button', {name: 'Clear all'});
    expect(clearAllAfter).toHaveAttribute('aria-disabled', 'true');
    expect(clearAllAfter).not.toBeDisabled();
    expect(clearAllAfter).toHaveFocus();
    expect(screen.getByLabelText('Search Tags')).not.toHaveFocus();
    expect(document.activeElement).not.toBe(document.body);
  });

  it('caps the empty-query bootstrap set at maxMenuItems, as the inline field caps its focus bootstrap (FR20)', async () => {
    // Twenty bootstrap items, two selected (one of them outside the capped
    // window): the sheet lists the selected rows plus the first maxMenuItems
    // bootstrap rows, not the whole set.
    const many = Array.from({length: 20}, (_, i) => ({
      id: `t${String(i).padStart(2, '0')}`,
      label: `Tag ${String(i).padStart(2, '0')}`,
    }));
    const manySource = {
      search: (q: string) =>
        many.filter(item => item.label.toLowerCase().includes(q.toLowerCase())),
      bootstrap: () => many,
    };
    render(
      <Tokenizer
        label="Tags"
        searchSource={manySource}
        value={[many[1], many[15]]}
        onChange={() => {}}
        debounceMs={0}
        maxMenuItems={5}
        presentation="bottom-sheet"
      />,
    );
    fireEvent.click(openTrigger());
    const dialog = await screen.findByRole('dialog', {name: 'Tags'});
    await screen.findByRole('checkbox', {name: 'Tag 00'});
    const rows = within(dialog)
      .getAllByRole('checkbox')
      .map(row => row.getAttribute('aria-label'));
    // Selected first (Tag 01, Tag 15), then the capped bootstrap window's
    // remaining rows (Tag 00, 02, 03, 04): five bootstrap rows in all.
    expect(rows).toEqual([
      'Tag 01',
      'Tag 15',
      'Tag 00',
      'Tag 02',
      'Tag 03',
      'Tag 04',
    ]);
    expect(dialog.querySelector('[data-total-count]')).toHaveAttribute(
      'data-total-count',
      '6',
    );
  });

  it('announces the rows it lists, not the source count: a created value and a maxMenuItems cap (FR20; AR6)', async () => {
    const matches = Element.prototype.matches;
    const modalSpy = vi
      .spyOn(Element.prototype, 'matches')
      .mockImplementation(function (this: Element, selector: string) {
        return selector === ':modal'
          ? this instanceof HTMLDialogElement && this.open
          : matches.call(this, selector);
      });
    try {
      // "Enzo" is a created value the source never returns; the source has
      // three "en" matches (Eng, Engineer, Energizer), capped to two rows.
      render(
        <Tokenizer
          label="Tags"
          searchSource={source}
          value={[{id: 'Enzo', label: 'Enzo'}]}
          onChange={() => {}}
          debounceMs={0}
          maxMenuItems={2}
          hasCreate
          presentation="bottom-sheet"
        />,
      );
      fireEvent.click(openTrigger());
      const dialog = await screen.findByRole('dialog', {name: 'Tags'});
      const region = () =>
        dialog.querySelector(
          ':scope > [data-astryx-modal-live-region="polite"]',
        );
      // Part of the created value: the source returns nothing, but the
      // checked row for Enzo is listed, and the sheet offers a create row
      // for "enz" — two entries, not "0 results".
      fireEvent.change(screen.getByLabelText('Search Tags'), {
        target: {value: 'enz'},
      });
      await screen.findByRole('checkbox', {name: 'Enzo'});
      await screen.findByRole('button', {name: 'Add enz'});
      await waitFor(() => expect(region()).toHaveTextContent('2 results'));
      expect(region()).not.toHaveTextContent('0 results');
      // A query the cap applies to: the source has three matches, capped to
      // two rows, plus the created value's checked row, plus the create row
      // the sheet offers for "en" — four entries listed, four announced (the
      // source count would say two, or three uncapped).
      fireEvent.change(screen.getByLabelText('Search Tags'), {
        target: {value: 'en'},
      });
      await screen.findByRole('button', {name: 'Add en'});
      await waitFor(() => expect(region()).toHaveTextContent('4 results'));
      expect(screen.getAllByRole('checkbox')).toHaveLength(3);
      expect(
        screen.queryByRole('checkbox', {name: 'Energizer'}),
      ).not.toBeInTheDocument();
    } finally {
      modalSpy.mockRestore();
    }
  });

  it('counts the create row it offers, as the inline field counts its create entry (FR20, FR22; AR6)', async () => {
    const matches = Element.prototype.matches;
    const modalSpy = vi
      .spyOn(Element.prototype, 'matches')
      .mockImplementation(function (this: Element, selector: string) {
        return selector === ':modal'
          ? this instanceof HTMLDialogElement && this.open
          : matches.call(this, selector);
      });
    try {
      render(<Harness hasCreate initial={[]} />);
      fireEvent.click(openTrigger());
      const dialog = await screen.findByRole('dialog', {name: 'Tags'});
      const region = () =>
        dialog.querySelector(
          ':scope > [data-astryx-modal-live-region="polite"]',
        );
      // Nothing from the source, one create row offered: "1 result", not
      // "0 results" over a row the person can act on.
      fireEvent.change(screen.getByLabelText('Search Tags'), {
        target: {value: 'Custom'},
      });
      await screen.findByRole('button', {name: 'Add Custom'});
      await waitFor(() => expect(region()).toHaveTextContent('1 result'));
      expect(region()).not.toHaveTextContent('0 results');
      // An exact source match offers no create row: the one row counts.
      fireEvent.change(screen.getByLabelText('Search Tags'), {
        target: {value: 'Design'},
      });
      await screen.findByRole('checkbox', {name: 'Design'});
      expect(
        screen.queryByRole('button', {name: 'Add Design'}),
      ).not.toBeInTheDocument();
      await waitFor(() => expect(region()).toHaveTextContent('1 result'));
    } finally {
      modalSpy.mockRestore();
    }
  });

  it('keeps a spent Clear all focusable with aria-disabled and no action, instead of native disabled (FR24; AST-085 FR1)', async () => {
    render(<Harness initial={[]} />);
    fireEvent.click(openTrigger());
    await screen.findByRole('dialog', {name: 'Tags'});
    const clearAll = screen.getByRole('button', {name: 'Clear all'});
    expect(clearAll).toHaveAttribute('aria-disabled', 'true');
    expect(clearAll).not.toHaveAttribute('disabled');
    // In the tab order, and it says why it does nothing.
    clearAll.focus();
    expect(clearAll).toHaveFocus();
    expect(clearAll).toHaveAccessibleDescription('Nothing selected');
    // A click opens no confirmation.
    fireEvent.click(clearAll);
    expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument();
  });

  it('asks a source rebuilt in render only on open, on a query change, and on clearing — not on a row toggle (FR20)', async () => {
    const search = vi.fn((q: string) =>
      ITEMS.filter(item => item.label.toLowerCase().includes(q.toLowerCase())),
    );
    const bootstrap = vi.fn(() => ITEMS);
    function InlineSourceHarness() {
      const [value, setValue] = useState<SearchableItem[]>([ITEMS[0]]);
      return (
        <Tokenizer
          label="Tags"
          // A new object every render, as a caller writing the source inline
          // produces; the selection change on each toggle re-renders.
          searchSource={{search, bootstrap}}
          value={value}
          onChange={items => setValue(items)}
          debounceMs={0}
          presentation="bottom-sheet"
        />
      );
    }
    render(<InlineSourceHarness />);
    fireEvent.click(openTrigger());
    await screen.findByRole('dialog', {name: 'Tags'});
    await screen.findByRole('checkbox', {name: 'Eng'});
    expect(bootstrap).toHaveBeenCalledTimes(1);
    expect(search).not.toHaveBeenCalled();
    // Row toggles re-render with a fresh source object: no new request.
    fireEvent.click(screen.getByRole('checkbox', {name: 'Eng'}));
    await waitFor(() =>
      expect(screen.getByRole('checkbox', {name: 'Eng'})).toBeChecked(),
    );
    fireEvent.click(screen.getByRole('checkbox', {name: 'Engineer'}));
    await waitFor(() =>
      expect(screen.getByRole('checkbox', {name: 'Engineer'})).toBeChecked(),
    );
    fireEvent.click(screen.getByRole('checkbox', {name: 'Eng'}));
    await waitFor(() =>
      expect(screen.getByRole('checkbox', {name: 'Eng'})).not.toBeChecked(),
    );
    expect(bootstrap).toHaveBeenCalledTimes(1);
    expect(search).not.toHaveBeenCalled();
    // A query change asks the source once; clearing asks for the bootstrap
    // set once more.
    fireEvent.change(screen.getByLabelText('Search Tags'), {
      target: {value: 'en'},
    });
    await waitFor(() => expect(search).toHaveBeenCalledTimes(1));
    expect(search).toHaveBeenLastCalledWith('en');
    fireEvent.change(screen.getByLabelText('Search Tags'), {
      target: {value: ''},
    });
    await waitFor(() => expect(bootstrap).toHaveBeenCalledTimes(2));
    expect(search).toHaveBeenCalledTimes(1);
  });

  it('announces a confirmed Clear all inside the sheet (AR6; AST-086 FR14)', async () => {
    // jsdom has no showModal(); stand in for the sheet presented modally so
    // the announcement takes the in-dialog route.
    const matches = Element.prototype.matches;
    const modalSpy = vi
      .spyOn(Element.prototype, 'matches')
      .mockImplementation(function (this: Element, selector: string) {
        return selector === ':modal'
          ? this instanceof HTMLDialogElement && this.open
          : matches.call(this, selector);
      });
    try {
      render(<Harness />);
      fireEvent.click(openTrigger());
      const dialog = await screen.findByRole('dialog', {name: 'Tags'});
      fireEvent.click(screen.getByRole('button', {name: 'Clear all'}));
      const confirmation = await screen.findByRole('alertdialog');
      fireEvent.click(
        within(confirmation).getByRole('button', {name: 'Clear selection'}),
      );
      await waitFor(() =>
        expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument(),
      );
      await waitFor(() =>
        expect(
          dialog.querySelector(
            ':scope > [data-astryx-modal-live-region="polite"]',
          ),
        ).toHaveTextContent('All items removed'),
      );
    } finally {
      modalSpy.mockRestore();
    }
  });

  it('keeps and does not report the query when the field is disabled while the sheet is open (FR18)', async () => {
    const onChangeQuery = vi.fn();
    const props = {
      label: 'Tags',
      searchSource: source,
      value: [ITEMS[0]],
      onChange: () => {},
      onChangeQuery,
      debounceMs: 0,
      presentation: 'bottom-sheet' as const,
    };
    const {rerender} = render(<Tokenizer {...props} />);
    fireEvent.click(openTrigger());
    await screen.findByRole('dialog', {name: 'Tags'});
    fireEvent.change(screen.getByLabelText('Search Tags'), {
      target: {value: 'En'},
    });
    onChangeQuery.mockClear();
    rerender(<Tokenizer {...props} isDisabled />);
    fireEvent.transitionEnd(document.querySelector('.astryx-bottom-sheet')!, {
      propertyName: 'transform',
    });
    // Nothing the person did changed the query, so nothing is reported, and
    // the caller's mirror and the sheet agree on the next open.
    expect(onChangeQuery).not.toHaveBeenCalled();
    rerender(<Tokenizer {...props} />);
    fireEvent.click(openTrigger());
    await screen.findByRole('dialog', {name: 'Tags'});
    expect(screen.getByLabelText('Search Tags')).toHaveValue('En');
    expect(onChangeQuery).not.toHaveBeenCalled();
  });

  it('reopens settled, not pending, after a forced close kept a query shorter than minQueryLength (FR18, FR20)', async () => {
    const props = {
      label: 'Tags',
      searchSource: source,
      value: [ITEMS[0]],
      onChange: () => {},
      debounceMs: 0,
      minQueryLength: 3,
      presentation: 'bottom-sheet' as const,
    };
    const {rerender} = render(<Tokenizer {...props} />);
    fireEvent.click(openTrigger());
    await screen.findByRole('dialog', {name: 'Tags'});
    // Two characters: below the threshold, so nothing is searched.
    fireEvent.change(screen.getByLabelText('Search Tags'), {
      target: {value: 'En'},
    });
    // The field becomes disabled: the sheet closes, keeping the query.
    rerender(<Tokenizer {...props} isDisabled />);
    fireEvent.transitionEnd(document.querySelector('.astryx-bottom-sheet')!, {
      propertyName: 'transform',
    });
    await waitFor(() => expect(openTrigger()).toHaveFocus());
    await waitFor(() =>
      expect(screen.queryByRole('dialog')).not.toBeInTheDocument(),
    );
    rerender(<Tokenizer {...props} />);
    fireEvent.click(openTrigger());
    const dialog = await screen.findByRole('dialog', {name: 'Tags'});
    expect(screen.getByLabelText('Search Tags')).toHaveValue('En');
    // Mounted open with a query no search runs for: settled at once — no
    // busy feedback, no aria-busy, only the selected rows the query matches
    // (none: "Design" does not contain "En"), no empty state, and nothing
    // announced.
    await act(async () => {
      await new Promise(resolve => setTimeout(resolve, 20));
    });
    expect(
      within(dialog).queryByRole('img', {name: 'Loading'}),
    ).not.toBeInTheDocument();
    expect(dialog.querySelector('[data-total-count]')).not.toHaveAttribute(
      'aria-busy',
    );
    expect(within(dialog).queryAllByRole('checkbox')).toHaveLength(0);
    expect(dialog.querySelector('.astryx-empty-state')).toBeNull();
    expect(
      dialog.querySelector(':scope > [data-astryx-modal-live-region="polite"]')
        ?.textContent ?? '',
    ).toBe('');
    // Typing on past the threshold searches as usual.
    fireEvent.change(screen.getByLabelText('Search Tags'), {
      target: {value: 'Eng'},
    });
    await screen.findByRole('checkbox', {name: 'Eng'});
  });

  it('closes the sheet and returns focus to the trigger when the field becomes disabled (FR17; AST-085 FR2)', async () => {
    const {rerender} = render(
      <Tokenizer
        label="Tags"
        searchSource={source}
        value={[ITEMS[0]]}
        onChange={() => {}}
        debounceMs={0}
        presentation="bottom-sheet"
      />,
    );
    const trigger = openTrigger();
    fireEvent.click(trigger);
    const dialog = await screen.findByRole('dialog', {name: 'Tags'});
    const search = screen.getByLabelText('Search Tags');
    search.focus();
    expect(search).toHaveFocus();

    rerender(
      <Tokenizer
        label="Tags"
        searchSource={source}
        value={[ITEMS[0]]}
        onChange={() => {}}
        debounceMs={0}
        isDisabled
        presentation="bottom-sheet"
      />,
    );
    expect(trigger).toHaveAttribute('aria-expanded', 'false');
    // Focus is in the search field, so the closing sheet stays out of inert
    // and aria-hidden until its exit ends (component:BottomSheet FR9).
    expect(dialog).not.toHaveAttribute('aria-modal');
    // BottomSheet hands focus back after its exit motion.
    fireEvent.transitionEnd(document.querySelector('.astryx-bottom-sheet')!, {
      propertyName: 'transform',
    });
    expect(trigger).toHaveFocus();
    expect(trigger).toHaveAttribute('aria-disabled', 'true');
    // Re-enabling does not reopen it.
    rerender(
      <Tokenizer
        label="Tags"
        searchSource={source}
        value={[ITEMS[0]]}
        onChange={() => {}}
        debounceMs={0}
        presentation="bottom-sheet"
      />,
    );
    expect(trigger).toHaveAttribute('aria-expanded', 'false');
    expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
  });

  it("exposes the caller's ids, the field description, the status and the disabled reason on a disabled trigger, in the inline field's order, before the count and tokens (AR6; AST-085 FR5)", () => {
    render(
      <>
        <span id="hint">Up to five</span>
        <Tokenizer
          label="Tags"
          searchSource={source}
          value={[ITEMS[0], ITEMS[1]]}
          onChange={() => {}}
          aria-describedby="hint"
          description="Pick some"
          status={{type: 'error', message: 'Pick at least three'}}
          isDisabled
          disabledMessage="Locked while syncing"
          presentation="bottom-sheet"
        />
      </>,
    );
    const trigger = openTrigger();
    expect(trigger).toHaveAttribute('aria-disabled', 'true');
    const ids = trigger.getAttribute('aria-describedby')!.split(' ');
    const texts = ids.map(id => document.getElementById(id)?.textContent);
    expect(texts).toEqual([
      'Up to five',
      'Pick some',
      'Pick at least three',
      'Locked while syncing',
      '2 selected',
      'Design',
      'Eng',
    ]);
    expect(trigger).toHaveAccessibleDescription(
      'Up to five Pick some Pick at least three Locked while syncing 2 selected Design Eng',
    );
  });

  it('describes the trigger with the selected token labels for assistive technology (AR6; AST-020 FR1)', () => {
    const {unmount} = render(<Harness />);
    const trigger = openTrigger();
    expect(trigger).toHaveAccessibleName('Tags');
    // A catalog count, then each label; the separator is the accessible-name
    // algorithm's, not a literal (i18n INV1a).
    expect(trigger).toHaveAccessibleDescription('2 selected Design Eng');
    // The labels come from the rendered tokens themselves, referenced by id:
    // in the field and the trigger's description, each label is in the DOM
    // once (component-style-authoring INV7); the only hidden text is the
    // count.
    const ids = trigger.getAttribute('aria-describedby')!.split(' ');
    expect(ids).toHaveLength(3);
    const described = ids.map(id => document.getElementById(id)!);
    expect(described[0]).toHaveTextContent('2 selected');
    expect(described[1]).toBe(
      within(sheetField()).getByText('Design').closest('.astryx-token'),
    );
    expect(described[2]).toBe(
      within(sheetField()).getByText('Eng').closest('.astryx-token'),
    );
    const leaves = (root: Element) =>
      Array.from(root.querySelectorAll('*')).filter(
        el => el.children.length === 0 && el.textContent?.trim() !== '',
      );
    const texts = [...leaves(sheetField()), ...leaves(described[0])].map(
      el => el.textContent,
    );
    expect(texts.filter(text => text === 'Design')).toHaveLength(1);
    expect(texts.filter(text => text === 'Eng')).toHaveLength(1);
    unmount();
    render(<Harness initial={[]} />);
    expect(openTrigger()).not.toHaveAttribute('aria-describedby');
  });

  it('sends base props and ref to the trigger in the sheet presentation (FR10, INV8)', () => {
    const ref = createRef<HTMLInputElement>();
    const onFocus = vi.fn();
    const onKeyDown = vi.fn();
    render(
      <Tokenizer
        label="Tags"
        searchSource={source}
        value={[ITEMS[0]]}
        onChange={() => {}}
        id="tags-field"
        data-testid="tags"
        aria-describedby="hint"
        description="Pick some"
        ref={ref}
        onFocus={onFocus}
        onKeyDown={onKeyDown}
        presentation="bottom-sheet"
      />,
    );
    const trigger = openTrigger();
    expect(trigger).toHaveAttribute('id', 'tags-field');
    expect(trigger).toHaveAttribute('data-testid', 'tags');
    expect(trigger.getAttribute('aria-describedby')).toContain('hint');
    expect(trigger).toHaveAccessibleDescription(/Pick some/);
    expect(ref.current).toBe(trigger);
    // The label points at the trigger.
    expect(screen.getByText('Tags', {selector: 'label'})).toHaveAttribute(
      'for',
      'tags-field',
    );
    fireEvent.focus(trigger);
    expect(onFocus).toHaveBeenCalledTimes(1);
    fireEvent.keyDown(trigger, {key: 'ArrowDown'});
    expect(onKeyDown).toHaveBeenCalledTimes(1);
  });

  it('treats the sheet as part of the field: no onBlur on open, no onFocus on return, both on a real exit (FR10)', async () => {
    const onFocus = vi.fn();
    const onBlur = vi.fn();
    render(
      <>
        <Tokenizer
          label="Tags"
          searchSource={source}
          value={[ITEMS[0]]}
          onChange={() => {}}
          debounceMs={0}
          onFocus={onFocus}
          onBlur={onBlur}
          presentation="bottom-sheet"
        />
        <button type="button">Elsewhere</button>
      </>,
    );
    const trigger = openTrigger();
    // Entering the field from outside reports once.
    trigger.focus();
    expect(onFocus).toHaveBeenCalledTimes(1);
    // Open: focus moves into the field's own sheet, not out of the field.
    fireEvent.click(trigger);
    await screen.findByRole('dialog', {name: 'Tags'});
    screen.getByLabelText('Search Tags').focus();
    expect(onBlur).not.toHaveBeenCalled();
    // Done: focus returns from the sheet, not from outside.
    fireEvent.click(screen.getByRole('button', {name: 'Save'}));
    fireEvent.transitionEnd(document.querySelector('.astryx-bottom-sheet')!, {
      propertyName: 'transform',
    });
    expect(trigger).toHaveFocus();
    expect(onFocus).toHaveBeenCalledTimes(1);
    expect(onBlur).not.toHaveBeenCalled();
    // A real exit, from the trigger to elsewhere, reports.
    screen.getByRole('button', {name: 'Elsewhere'}).focus();
    expect(onBlur).toHaveBeenCalledTimes(1);
    // And a second open-and-close cycle from outside reports the entry once.
    trigger.focus();
    expect(onFocus).toHaveBeenCalledTimes(2);
    fireEvent.click(trigger);
    await screen.findByRole('dialog', {name: 'Tags'});
    fireEvent.click(screen.getByRole('button', {name: 'Save'}));
    fireEvent.transitionEnd(document.querySelector('.astryx-bottom-sheet')!, {
      propertyName: 'transform',
    });
    expect(onFocus).toHaveBeenCalledTimes(2);
    expect(onBlur).toHaveBeenCalledTimes(1);
  });

  it('reports the entry on the return focus when the open came from a click that did not focus the trigger (Safari), so onBlur never comes alone (FR10)', async () => {
    const onFocus = vi.fn();
    const onBlur = vi.fn();
    render(
      <>
        <Tokenizer
          label="Tags"
          searchSource={source}
          value={[ITEMS[0]]}
          onChange={() => {}}
          debounceMs={0}
          onFocus={onFocus}
          onBlur={onBlur}
          presentation="bottom-sheet"
        />
        <button type="button">Elsewhere</button>
      </>,
    );
    const trigger = openTrigger();
    // A click with no focus first, as Safari delivers a pointer press on a
    // button: no entry has been reported when the sheet opens.
    fireEvent.click(trigger);
    await screen.findByRole('dialog', {name: 'Tags'});
    expect(onFocus).not.toHaveBeenCalled();
    expect(onBlur).not.toHaveBeenCalled();
    // Done: BottomSheet's return focus is the one focus the trigger gets in
    // this visit, so it is the entry, and is reported.
    fireEvent.click(screen.getByRole('button', {name: 'Save'}));
    fireEvent.transitionEnd(document.querySelector('.astryx-bottom-sheet')!, {
      propertyName: 'transform',
    });
    expect(trigger).toHaveFocus();
    expect(onFocus).toHaveBeenCalledTimes(1);
    expect(onBlur).not.toHaveBeenCalled();
    // Leaving reports the exit: one onFocus, one onBlur.
    screen.getByRole('button', {name: 'Elsewhere'}).focus();
    expect(onBlur).toHaveBeenCalledTimes(1);
    expect(onFocus).toHaveBeenCalledTimes(1);
  });

  it('runs the open first and then the caller onClick, which cannot cancel it (FR10)', async () => {
    const order: string[] = [];
    const onClick = vi.fn((event: React.MouseEvent) => {
      order.push(
        (event.currentTarget as HTMLElement).getAttribute('aria-expanded') ??
          '',
      );
      event.preventDefault();
    });
    render(
      <Tokenizer
        label="Tags"
        searchSource={source}
        value={[ITEMS[0]]}
        onChange={() => {}}
        debounceMs={0}
        onClick={onClick}
        presentation="bottom-sheet"
      />,
    );
    const trigger = openTrigger();
    fireEvent.click(trigger);
    expect(onClick).toHaveBeenCalledTimes(1);
    // The caller's preventDefault() does not keep the sheet closed, as the
    // inline field's own click handling runs first and is not cancelable.
    expect(
      await screen.findByRole('dialog', {name: 'Tags'}),
    ).toBeInTheDocument();
    expect(trigger).toHaveAttribute('aria-expanded', 'true');
    // The caller saw the click on the trigger (its pre-open state in the same
    // event, since the open commits after the handler).
    expect(order).toEqual(['false']);
  });

  it("renders endContent at the sheet field's inline end; its controls work without opening the sheet (FR17)", async () => {
    const onApply = vi.fn();
    render(
      <Harness
        endContent={
          <button type="button" onClick={onApply}>
            Apply
          </button>
        }
      />,
    );
    const trigger = openTrigger();
    const apply = screen.getByRole('button', {name: 'Apply'});
    expect(sheetField()).toContainElement(apply);
    expect(trigger).not.toContainElement(apply);
    // A control of its own, after the trigger in the focus order.
    expect(
      trigger.compareDocumentPosition(apply) & Node.DOCUMENT_POSITION_FOLLOWING,
    ).toBeTruthy();
    apply.focus();
    expect(apply).toHaveFocus();
    fireEvent.click(apply);
    expect(onApply).toHaveBeenCalledTimes(1);
    expect(trigger).toHaveAttribute('aria-expanded', 'false');
    expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
    // A tap on the field around it still opens the sheet.
    fireEvent.click(sheetField());
    expect(trigger).toHaveAttribute('aria-expanded', 'true');
    expect(
      await screen.findByRole('dialog', {name: 'Tags'}),
    ).toBeInTheDocument();
  });

  it('keeps endContent operable and exposed as enabled in a disabled sheet field (FR17)', () => {
    const onApply = vi.fn();
    render(
      <Harness
        isDisabled
        endContent={
          <button type="button" onClick={onApply}>
            Apply
          </button>
        }
      />,
    );
    const trigger = openTrigger();
    expect(trigger).toHaveAttribute('aria-disabled', 'true');
    const apply = screen.getByRole('button', {name: 'Apply'});
    // aria-disabled on an ancestor would expose the caller's button as
    // disabled while a press still runs it.
    expect(apply.closest('[aria-disabled="true"]')).toBeNull();
    fireEvent.click(apply);
    expect(onApply).toHaveBeenCalledTimes(1);
    // The disabled field itself still does not open.
    fireEvent.click(sheetField());
    expect(trigger).toHaveAttribute('aria-expanded', 'false');
    expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
  });

  it('renders endContent beside the placeholder of an empty sheet field (FR17)', () => {
    render(
      <Harness initial={[]} endContent={<button type="button">Cc</button>} />,
    );
    expect(sheetField()).toHaveTextContent('Add tags');
    expect(
      within(sheetField()).getByRole('button', {name: 'Cc'}),
    ).toBeInTheDocument();
    expect(openTrigger()).toHaveTextContent('Add tags');
  });

  it("renders the sheet field's tokens through renderToken; a token's own remove control removes at once (FR17)", async () => {
    const spy = vi.fn();
    render(
      <Harness
        spy={spy}
        renderToken={(item, onRemove) => (
          <Token label={item.label} onRemove={onRemove} />
        )}
      />,
    );
    const trigger = openTrigger();
    const removeDesign = within(sheetField()).getByRole('button', {
      name: 'Remove Design',
    });
    expect(trigger).not.toContainElement(removeDesign);
    // A custom token's controls follow the trigger in the focus order.
    expect(
      trigger.compareDocumentPosition(removeDesign) &
        Node.DOCUMENT_POSITION_FOLLOWING,
    ).toBeTruthy();
    // The description names the count and the item labels only: no
    // referenced element holds a custom token's control.
    const described = trigger
      .getAttribute('aria-describedby')!
      .split(' ')
      .map(id => document.getElementById(id)!);
    expect(described.map(el => el.textContent)).toEqual([
      '2 selected',
      'Design',
      'Eng',
    ]);
    expect(described.filter(el => el.querySelector('button'))).toEqual([]);
    // The label copies stay out of the accessibility tree.
    expect(described.slice(1).every(el => el.hidden)).toBe(true);
    fireEvent.click(removeDesign);
    expect(spy).toHaveBeenCalledTimes(1);
    expect(spy).toHaveBeenCalledWith([ITEMS[1]], {
      item: ITEMS[0],
      type: 'remove',
    });
    expect(trigger).toHaveAttribute('aria-expanded', 'false');
    expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
    // The removed token's control is gone, so focus moves to the trigger.
    expect(trigger).toHaveFocus();
    // A tap on a custom token's label opens the sheet, as on the default
    // token.
    fireEvent.click(within(sheetField()).getByText('Eng'));
    expect(trigger).toHaveAttribute('aria-expanded', 'true');
    expect(
      await screen.findByRole('dialog', {name: 'Tags'}),
    ).toBeInTheDocument();
  });

  it('reports onFocus and onBlur for the whole sheet field, not for moves between its controls (FR17; input-fields FR10)', () => {
    const onFocus = vi.fn();
    const onBlur = vi.fn();
    render(
      <>
        <Harness
          onFocus={onFocus}
          onBlur={onBlur}
          endContent={<button type="button">Cc</button>}
          renderToken={(item, onRemove) => (
            <Token label={item.label} onRemove={onRemove} />
          )}
        />
        <button type="button">Outside</button>
      </>,
    );
    const trigger = openTrigger();
    act(() => trigger.focus());
    expect(onFocus).toHaveBeenCalledTimes(1);
    // Moving among the trigger, the end content and a token's own control
    // stays inside the field.
    act(() => screen.getByRole('button', {name: 'Cc'}).focus());
    act(() => screen.getByRole('button', {name: 'Remove Eng'}).focus());
    act(() => trigger.focus());
    expect(onFocus).toHaveBeenCalledTimes(1);
    expect(onBlur).not.toHaveBeenCalled();
    act(() => screen.getByRole('button', {name: 'Outside'}).focus());
    expect(onBlur).toHaveBeenCalledTimes(1);
    // Entering at the end content is focus entering the field.
    act(() => screen.getByRole('button', {name: 'Cc'}).focus());
    expect(onFocus).toHaveBeenCalledTimes(2);
  });

  it('hands focus to the inline input when a swap removes a focused end-content or custom-token control (FR16)', () => {
    let compact = true;
    const listeners = new Set<() => void>();
    vi.stubGlobal(
      'matchMedia',
      vi.fn().mockImplementation((query: string) => ({
        get matches() {
          return query === COMPACT_TOUCH_QUERY ? compact : false;
        },
        media: query,
        onchange: null,
        addEventListener: (_: string, cb: () => void) => listeners.add(cb),
        removeEventListener: (_: string, cb: () => void) =>
          listeners.delete(cb),
        addListener: vi.fn(),
        removeListener: vi.fn(),
        dispatchEvent: vi.fn(),
      })),
    );
    const turn = (next: boolean) => {
      compact = next;
      act(() => {
        for (const cb of listeners) {
          cb();
        }
      });
    };
    const view = (
      <Harness
        presentation="adaptive"
        endContent={<button type="button">Cc</button>}
        renderToken={(item, onRemove) => (
          <Token label={item.label} onRemove={onRemove} />
        )}
      />
    );
    render(view);
    // The sheet field: the end content holds focus, then the screen stops
    // being compact-touch.
    act(() => openTrigger().focus());
    const cc = screen.getByRole('button', {name: 'Cc'});
    act(() => cc.focus());
    expect(cc).toHaveFocus();
    turn(false);
    expect(screen.getByRole('combobox')).toHaveFocus();
    // Back to the sheet field, then a custom token's remove holds focus.
    turn(true);
    const remove = within(sheetField()).getByRole('button', {
      name: 'Remove Design',
    });
    act(() => remove.focus());
    expect(remove).toHaveFocus();
    turn(false);
    expect(screen.getByRole('combobox')).toHaveFocus();
  });

  it('does not warn about endContent or renderToken in the sheet presentation', () => {
    __resetDevWarnings();
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
    render(
      <Tokenizer
        label="Tags"
        searchSource={source}
        value={[ITEMS[0]]}
        onChange={() => {}}
        endContent={<button type="button">Apply</button>}
        renderToken={item => <span>{item.label}</span>}
        hasClear
        presentation="bottom-sheet"
      />,
    );
    expect(warn).toHaveBeenCalledTimes(1);
    expect(warn.mock.calls[0][0]).toMatch(/`hasClear` has no surface/);
    expect(warn.mock.calls[0][0]).not.toMatch(/endContent|renderToken/);
    warn.mockRestore();
  });

  it('warns once in development about props with no sheet surface (INV3)', () => {
    __resetDevWarnings();
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
    const {rerender} = render(
      <Tokenizer
        label="Tags"
        searchSource={source}
        value={[ITEMS[0]]}
        onChange={() => {}}
        hasClear
        menuWidth={320}
        presentation="bottom-sheet"
      />,
    );
    expect(warn).toHaveBeenCalledTimes(1);
    expect(warn.mock.calls[0][0]).toMatch(/Tokenizer/);
    expect(warn.mock.calls[0][0]).toMatch(/`hasClear`, `menuWidth`/);
    expect(warn.mock.calls[0][0]).toMatch(/bottom-sheet presentation/);
    rerender(
      <Tokenizer
        label="Tags"
        searchSource={source}
        value={[ITEMS[0], ITEMS[1]]}
        onChange={() => {}}
        hasClear
        menuWidth={320}
        presentation="bottom-sheet"
      />,
    );
    expect(warn).toHaveBeenCalledTimes(1);
    warn.mockClear();
    render(
      <Tokenizer
        label="Other"
        searchSource={source}
        value={[]}
        onChange={() => {}}
        hasClear
        menuWidth={320}
      />,
    );
    // The inline presentation renders them, so nothing to say.
    expect(warn).not.toHaveBeenCalled();
    warn.mockRestore();
  });

  it('is busy, not empty, from open and from each query change until the search settles (FR20)', async () => {
    vi.useFakeTimers();
    try {
      const slow: SearchSource<SearchableItem> = {
        bootstrap: async () =>
          new Promise(resolve => setTimeout(() => resolve(ITEMS), 50)),
        search: async q =>
          new Promise(resolve =>
            setTimeout(
              () =>
                resolve(
                  ITEMS.filter(item =>
                    item.label.toLowerCase().includes(q.toLowerCase()),
                  ),
                ),
              50,
            ),
          ),
      };
      // Default debounceMs (150), so the debounce window is under test too.
      // hasCreate, so the create row's timing is under test as well.
      render(
        <Tokenizer
          label="Tags"
          searchSource={slow}
          value={[]}
          onChange={() => {}}
          hasCreate
          presentation="bottom-sheet"
        />,
      );
      fireEvent.click(openTrigger());
      const list = () => document.querySelector('[data-total-count]')!;
      await act(async () => {
        await vi.advanceTimersByTimeAsync(0);
      });
      expect(list()).toHaveAttribute('aria-busy', 'true');
      expect(screen.getByRole('img', {name: 'Loading'})).toBeInTheDocument();
      expect(
        screen.queryByRole('heading', {name: 'No items available'}),
      ).not.toBeInTheDocument();
      await act(async () => {
        await vi.advanceTimersByTimeAsync(250);
      });
      expect(list()).not.toHaveAttribute('aria-busy');
      expect(
        screen.getByRole('checkbox', {name: 'Design'}),
      ).toBeInTheDocument();

      fireEvent.change(screen.getByLabelText('Search Tags'), {
        target: {value: 'zzz'},
      });
      // Inside the debounce window: busy, no "No results found", no create
      // row (the previous query's results cannot judge a duplicate), and the
      // named Loading row sits above the rows still listed from before, so
      // the person sees that those rows are not the answer yet.
      expect(
        screen.queryByRole('button', {name: /^Add /}),
      ).not.toBeInTheDocument();
      await act(async () => {
        await vi.advanceTimersByTimeAsync(100);
      });
      expect(list()).toHaveAttribute('aria-busy', 'true');
      const loading = screen.getByRole('img', {name: 'Loading'});
      const staleRow = screen.getByRole('checkbox', {name: 'Design'});
      expect(staleRow).toBeInTheDocument();
      expect(loading.compareDocumentPosition(staleRow)).toBe(
        Node.DOCUMENT_POSITION_FOLLOWING,
      );
      expect(
        screen.queryByRole('heading', {name: 'No results found'}),
      ).not.toBeInTheDocument();
      await act(async () => {
        await vi.advanceTimersByTimeAsync(200);
      });
      expect(list()).not.toHaveAttribute('aria-busy');
      // Settled with no match: the create row is offered now, against this
      // query's own results, and no empty state shows beside it.
      expect(screen.getByRole('button', {name: 'Add zzz'})).toBeInTheDocument();
      expect(
        screen.queryByRole('heading', {name: 'No results found'}),
      ).not.toBeInTheDocument();
    } finally {
      vi.useRealTimers();
    }
  });

  it('describes a disabled trigger with disabledMessage', async () => {
    render(
      <Harness isDisabled disabledMessage="Pick a team first" initial={[]} />,
    );
    const trigger = openTrigger();
    fireEvent.focus(trigger);
    expect(await screen.findByText('Pick a team first')).toBeInTheDocument();
  });

  it('keeps an unselectable row at the limit focusable but inert (FR23; AST-085 FR1, FR2)', async () => {
    const spy = vi.fn();
    render(<Harness spy={spy} initial={[ITEMS[0]]} maxEntries={1} />);
    fireEvent.click(openTrigger());
    const row = await screen.findByRole('checkbox', {name: 'Energizer'});
    expect(row).not.toHaveAttribute('disabled');
    expect(row).toHaveAttribute('aria-disabled', 'true');
    fireEvent.click(row);
    expect(spy).not.toHaveBeenCalled();
    expect(row).toHaveAttribute('aria-checked', 'false');
    // In forced colors its indicator border takes GrayText (AST-085 FR6).
    const indicatorClasses = stylex
      .props(
        stylex.create({
          indicatorBorder: {
            borderColor: {
              default: colorVars['--color-border'],
              '@media (forced-colors: active)': 'GrayText',
            },
          },
        }).indicatorBorder,
      )
      .className!.split(' ')
      .filter(name => !name.includes('__'));
    const indicator = row.querySelector('.astryx-checkbox-indicator')!;
    for (const name of indicatorClasses) {
      expect(indicator).toHaveClass(name);
    }
    // The checked row still toggles, making room (FR23).
    // Unchecking the selected row makes room in the draft: the limit is read
    // against the draft, so the inert row becomes selectable before Save.
    fireEvent.click(screen.getByRole('checkbox', {name: 'Design'}));
    expect(spy).not.toHaveBeenCalled();
    expect(row).not.toHaveAttribute('aria-disabled');
    fireEvent.click(screen.getByRole('button', {name: 'Save'}));
    expect(spy).toHaveBeenLastCalledWith([], {item: ITEMS[0], type: 'remove'});
  });

  it('paints a disabled trigger, its placeholder, and its tokens GrayText in forced colors (AST-085 FR6)', () => {
    const atoms = (style: stylex.StyleXStyles) =>
      stylex
        .props(style)
        .className!.split(' ')
        .filter(name => !name.includes('__'));
    const forced = stylex.create({
      trigger: {
        borderColor: {
          default: colorVars['--color-border-emphasized'],
          '@media (forced-colors: active)': 'GrayText',
        },
        color: {default: null, '@media (forced-colors: active)': 'GrayText'},
      },
      token: {
        color: {
          default: colorVars['--color-text-primary'],
          '@media (forced-colors: active)': 'GrayText',
        },
      },
      placeholder: {
        color: {
          default: colorVars['--color-text-secondary'],
          '@media (forced-colors: active)': 'GrayText',
        },
      },
    });
    const {unmount} = render(<Harness isDisabled />);
    const field = sheetField();
    for (const name of atoms(forced.trigger)) {
      expect(field).toHaveClass(name);
    }
    const tokens = field.querySelectorAll('.astryx-token');
    expect(tokens).toHaveLength(2);
    for (const token of tokens) {
      for (const name of atoms(forced.token)) {
        expect(token).toHaveClass(name);
      }
    }
    unmount();
    render(<Harness isDisabled initial={[]} />);
    const placeholder = screen.getByText('Add tags');
    for (const name of atoms(forced.placeholder)) {
      expect(placeholder).toHaveClass(name);
    }
  });

  it('renders a row without its action and warns once in development (FR19; AST-058 FR9)', async () => {
    __resetDevWarnings();
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
    const withAction: SearchSource<SearchableItem> = {
      search: () => [],
      bootstrap: () => [
        {
          id: 'design',
          label: 'Design',
          action: <button type="button">Go</button>,
        },
        {id: 'eng', label: 'Eng'},
      ],
    };
    render(
      <Tokenizer
        label="Tags"
        searchSource={withAction}
        value={[]}
        onChange={() => {}}
        debounceMs={0}
        presentation="bottom-sheet"
      />,
    );
    fireEvent.click(openTrigger());
    const row = await screen.findByRole('checkbox', {name: 'Design'});
    expect(within(row).queryByRole('button')).not.toBeInTheDocument();
    await waitFor(() => expect(warn).toHaveBeenCalledTimes(1));
    expect(warn.mock.calls[0][0]).toMatch(/`action`/);
    expect(warn.mock.calls[0][0]).toMatch(/bottom-sheet rows/);
    warn.mockRestore();
  });

  it('warns about a row action once under StrictMode double renders', async () => {
    __resetDevWarnings();
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
    const withAction: SearchSource<SearchableItem> = {
      search: () => [],
      bootstrap: () => [
        {
          id: 'design',
          label: 'Design',
          action: <button type="button">Go</button>,
        },
      ],
    };
    render(
      <StrictMode>
        <Tokenizer
          label="Tags"
          searchSource={withAction}
          value={[]}
          onChange={() => {}}
          debounceMs={0}
          presentation="bottom-sheet"
        />
      </StrictMode>,
    );
    fireEvent.click(openTrigger());
    await screen.findByRole('checkbox', {name: 'Design'});
    expect(warn).toHaveBeenCalledTimes(1);
    expect(warn.mock.calls[0][0]).toMatch(/bottom-sheet rows/);
    warn.mockRestore();
  });

  it('keeps focus when adaptive stops resolving to the sheet while it is open (FR16)', async () => {
    // A matchMedia stub whose match can flip, with a change listener the
    // test fires, as a phone turned to landscape would.
    let compact = true;
    const listeners = new Set<() => void>();
    vi.stubGlobal(
      'matchMedia',
      vi.fn().mockImplementation((query: string) => ({
        get matches() {
          return query === COMPACT_TOUCH_QUERY ? compact : false;
        },
        media: query,
        onchange: null,
        addEventListener: (_: string, cb: () => void) => listeners.add(cb),
        removeEventListener: (_: string, cb: () => void) =>
          listeners.delete(cb),
        addListener: vi.fn(),
        removeListener: vi.fn(),
        dispatchEvent: vi.fn(),
      })),
    );
    render(<Harness presentation="adaptive" />);
    const trigger = openTrigger();
    fireEvent.click(trigger);
    const dialog = await screen.findByRole('dialog', {name: 'Tags'});
    screen.getByLabelText('Search Tags').focus();

    // The viewport stops being compact while the sheet is open: nothing
    // changes until the sheet closes.
    compact = false;
    act(() => {
      for (const cb of listeners) {
        cb();
      }
    });
    expect(screen.getByRole('dialog', {name: 'Tags'})).toBe(dialog);
    expect(trigger).toBeInTheDocument();
    expect(screen.queryByRole('combobox')).not.toBeInTheDocument();

    fireEvent.click(screen.getByRole('button', {name: 'Save'}));
    // The sheet is closing; the trigger stays mounted to take focus back,
    // and the inline input does not appear yet.
    expect(trigger).toBeInTheDocument();
    expect(screen.queryByRole('combobox')).not.toBeInTheDocument();
    fireEvent.transitionEnd(document.querySelector('.astryx-bottom-sheet')!, {
      propertyName: 'transform',
    });
    // Focus came back to the trigger, the latch released into the popover
    // presentation, and the inline input took the focus over.
    await waitFor(() =>
      expect(screen.getByRole('combobox')).toBeInTheDocument(),
    );
    expect(screen.getByRole('combobox')).toHaveFocus();
    expect(
      screen.queryByRole('button', {name: 'Tags'}),
    ).not.toBeInTheDocument();
  });

  it('gives ref the control it reaches: the input in the popover presentation, the trigger in the sheet', () => {
    const inputRef = createRef<HTMLInputElement>();
    const {unmount} = render(
      <Tokenizer
        label="Tags"
        searchSource={source}
        value={[]}
        onChange={() => {}}
        ref={inputRef}
      />,
    );
    expect(inputRef.current).toBe(screen.getByRole('combobox'));
    unmount();
    const wideRef = createRef<HTMLInputElement | HTMLButtonElement>();
    const {rerender} = render(
      <Tokenizer
        label="Tags"
        searchSource={source}
        value={[]}
        onChange={() => {}}
        ref={wideRef}
        presentation="popover"
      />,
    );
    expect(wideRef.current).toBe(screen.getByRole('combobox'));
    rerender(
      <Tokenizer
        label="Tags"
        searchSource={source}
        value={[]}
        onChange={() => {}}
        ref={wideRef}
        presentation="bottom-sheet"
      />,
    );
    expect(wideRef.current).toBe(openTrigger());
  });

  it('does not search, wait, empty out, or announce for a query below minQueryLength (FR20)', async () => {
    const search = vi.fn(source.search);
    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
    render(
      <Tokenizer
        label="Tags"
        searchSource={{...source, search}}
        value={[ITEMS[0]]}
        onChange={() => {}}
        debounceMs={0}
        minQueryLength={3}
        hasCreate
        presentation="bottom-sheet"
      />,
    );
    fireEvent.click(openTrigger());
    await screen.findByRole('checkbox', {name: 'Eng'});
    search.mockClear();
    fireEvent.change(screen.getByLabelText('Search Tags'), {
      target: {value: 'De'},
    });
    // Only the selected row it matches, and the create row; nothing searched,
    // nothing pending, no empty state.
    expect(screen.getByRole('checkbox', {name: 'Design'})).toBeInTheDocument();
    expect(
      screen.queryByRole('checkbox', {name: 'Eng'}),
    ).not.toBeInTheDocument();
    expect(screen.getByRole('button', {name: 'Add De'})).toBeInTheDocument();
    expect(list()).not.toHaveAttribute('aria-busy');
    expect(
      screen.queryByRole('img', {name: 'Loading'}),
    ).not.toBeInTheDocument();
    expect(
      screen.queryByRole('heading', {name: 'No results found'}),
    ).not.toBeInTheDocument();
    expect(search).not.toHaveBeenCalled();
    // One more character crosses the threshold and searches.
    fireEvent.change(screen.getByLabelText('Search Tags'), {
      target: {value: 'Des'},
    });
    await waitFor(() => expect(search).toHaveBeenCalledWith('Des'));
    spy.mockRestore();
  });

  it('announces the rendered empty state when emptySearchText is an element (FR20; AST-056 FR3)', async () => {
    const matches = Element.prototype.matches;
    const spy = vi
      .spyOn(Element.prototype, 'matches')
      .mockImplementation(function (this: Element, selector: string) {
        return selector === ':modal'
          ? this instanceof HTMLDialogElement && this.open
          : matches.call(this, selector);
      });
    try {
      render(
        <Tokenizer
          label="Tags"
          searchSource={source}
          value={[]}
          onChange={() => {}}
          debounceMs={0}
          emptySearchText={
            <p>
              Nothing called <strong>that</strong>
              <span aria-hidden="true"> (decorative)</span>
            </p>
          }
          presentation="bottom-sheet"
        />,
      );
      fireEvent.click(openTrigger());
      const dialog = await screen.findByRole('dialog', {name: 'Tags'});
      fireEvent.change(screen.getByLabelText('Search Tags'), {
        target: {value: 'zzz'},
      });
      await waitFor(() =>
        expect(
          dialog.querySelector(
            ':scope > [data-astryx-modal-live-region="polite"]',
          ),
        ).toHaveTextContent('Nothing called that'),
      );
      expect(
        dialog.querySelector(
          ':scope > [data-astryx-modal-live-region="polite"]',
        ),
      ).not.toHaveTextContent('decorative');
      expect(screen.getByText('that')).toBeInTheDocument();
    } finally {
      spy.mockRestore();
    }
  });

  it('announces the default empty state exactly once inside the sheet (FR20; AST-086 FR6)', async () => {
    const matches = Element.prototype.matches;
    const modalSpy = vi
      .spyOn(Element.prototype, 'matches')
      .mockImplementation(function (this: Element, selector: string) {
        return selector === ':modal'
          ? this instanceof HTMLDialogElement && this.open
          : matches.call(this, selector);
      });
    try {
      render(<Harness />);
      fireEvent.click(openTrigger());
      const dialog = await screen.findByRole('dialog', {name: 'Tags'});
      const region = () =>
        dialog.querySelector(
          ':scope > [data-astryx-modal-live-region="polite"]',
        );
      fireEvent.change(screen.getByLabelText('Search Tags'), {
        target: {value: 'zzz'},
      });
      await screen.findByRole('heading', {name: 'No results found'});
      await waitFor(() =>
        expect(region()).toHaveTextContent('No results found'),
      );
      // Spoken by EmptyState itself, once: the sheet adds no second copy of
      // the title or description, joined or otherwise.
      const text = region()?.textContent ?? '';
      expect(text.match(/No results found/g)).toHaveLength(1);
      expect(text.match(/Try a different search\./g)).toHaveLength(1);
      expect(
        document.querySelector('[data-astryx-live-region="polite"]')
          ?.textContent ?? '',
      ).toBe('');
    } finally {
      modalSpy.mockRestore();
    }
  });

  it('settles a rejecting source to no results without an unhandled rejection (FR20)', async () => {
    const matches = Element.prototype.matches;
    const spy = vi
      .spyOn(Element.prototype, 'matches')
      .mockImplementation(function (this: Element, selector: string) {
        return selector === ':modal'
          ? this instanceof HTMLDialogElement && this.open
          : matches.call(this, selector);
      });
    const rejected = vi.fn();
    const onRejection = (event: PromiseRejectionEvent) => {
      rejected(event.reason);
      event.preventDefault();
    };
    window.addEventListener('unhandledrejection', onRejection);
    try {
      const flaky: SearchSource<SearchableItem> = {
        bootstrap: () => ITEMS,
        search: async q => {
          if (q === 'boom') {
            throw new Error('source down');
          }
          return source.search(q);
        },
      };
      render(
        <Tokenizer
          label="Tags"
          searchSource={flaky}
          value={[]}
          onChange={() => {}}
          debounceMs={0}
          presentation="bottom-sheet"
        />,
      );
      fireEvent.click(openTrigger());
      const dialog = await screen.findByRole('dialog', {name: 'Tags'});
      const region = () =>
        dialog.querySelector(
          ':scope > [data-astryx-modal-live-region="polite"]',
        );
      fireEvent.change(screen.getByLabelText('Search Tags'), {
        target: {value: 'En'},
      });
      await screen.findByRole('checkbox', {name: 'Energizer'});
      await waitFor(() => expect(region()).toHaveTextContent('3 results'));
      fireEvent.change(screen.getByLabelText('Search Tags'), {
        target: {value: 'boom'},
      });
      // Settled: no stale rows, busy cleared, the empty state announced
      // rather than the old count.
      await waitFor(() =>
        expect(
          screen.getByRole('heading', {name: 'No results found'}),
        ).toBeInTheDocument(),
      );
      expect(
        screen.queryByRole('checkbox', {name: 'Energizer'}),
      ).not.toBeInTheDocument();
      expect(list()).not.toHaveAttribute('aria-busy');
      await waitFor(() =>
        expect(region()).toHaveTextContent('No results found'),
      );
      expect(region()).not.toHaveTextContent('3 results');
      await act(async () => {
        await new Promise(resolve => setTimeout(resolve, 0));
      });
      expect(rejected).not.toHaveBeenCalled();
    } finally {
      window.removeEventListener('unhandledrejection', onRejection);
      spy.mockRestore();
    }
  });

  it('retires an unsettled search when a query below minQueryLength follows it, announcing nothing (FR20)', async () => {
    vi.useFakeTimers();
    const matches = Element.prototype.matches;
    const spy = vi
      .spyOn(Element.prototype, 'matches')
      .mockImplementation(function (this: Element, selector: string) {
        return selector === ':modal'
          ? this instanceof HTMLDialogElement && this.open
          : matches.call(this, selector);
      });
    try {
      const slow: SearchSource<SearchableItem> = {
        bootstrap: () => ITEMS,
        search: async q =>
          new Promise(resolve =>
            setTimeout(() => resolve(source.search(q)), 300),
          ),
      };
      render(
        <Tokenizer
          label="Tags"
          searchSource={slow}
          value={[]}
          onChange={() => {}}
          debounceMs={0}
          minQueryLength={3}
          presentation="bottom-sheet"
        />,
      );
      fireEvent.click(openTrigger());
      await act(async () => {
        await vi.advanceTimersByTimeAsync(10);
      });
      const dialog = screen.getByRole('dialog', {name: 'Tags'});
      const region = () =>
        dialog.querySelector(
          ':scope > [data-astryx-modal-live-region="polite"]',
        );
      const search = screen.getByLabelText('Search Tags');
      // "Eng" searches; before it settles, backspace to "En", below the
      // threshold: nothing pending, and when the old search returns its rows
      // do not land and no count is announced.
      fireEvent.change(search, {target: {value: 'Eng'}});
      expect(list()).toHaveAttribute('aria-busy', 'true');
      fireEvent.change(search, {target: {value: 'En'}});
      expect(list()).not.toHaveAttribute('aria-busy');
      await act(async () => {
        await vi.advanceTimersByTimeAsync(400);
      });
      expect(
        screen.queryByRole('checkbox', {name: 'Eng'}),
      ).not.toBeInTheDocument();
      expect(region()?.textContent ?? '').not.toMatch(/results?/);
      // A searched query afterwards announces as usual.
      fireEvent.change(search, {target: {value: 'Ener'}});
      await act(async () => {
        await vi.advanceTimersByTimeAsync(400);
      });
      expect(
        screen.getByRole('checkbox', {name: 'Energizer'}),
      ).toBeInTheDocument();
      await act(async () => {
        await vi.advanceTimersByTimeAsync(50);
      });
      expect(region()).toHaveTextContent('1 result');
    } finally {
      spy.mockRestore();
      vi.useRealTimers();
    }
  });

  it('marks the list pending while the bootstrap set reloads after the create row (FR20, FR22)', async () => {
    vi.useFakeTimers();
    try {
      const onChangeQuery = vi.fn();
      const slow: SearchSource<SearchableItem> = {
        bootstrap: async () =>
          new Promise(resolve => setTimeout(() => resolve(ITEMS), 300)),
        search: async q =>
          new Promise(resolve =>
            setTimeout(() => resolve(source.search(q)), 300),
          ),
      };
      render(
        <Tokenizer
          label="Tags"
          searchSource={slow}
          value={[]}
          onChange={() => {}}
          onChangeQuery={onChangeQuery}
          debounceMs={0}
          hasCreate
          presentation="bottom-sheet"
        />,
      );
      fireEvent.click(openTrigger());
      await act(async () => {
        await vi.advanceTimersByTimeAsync(400);
      });
      fireEvent.change(screen.getByLabelText('Search Tags'), {
        target: {value: 'Ops'},
      });
      await act(async () => {
        await vi.advanceTimersByTimeAsync(400);
      });
      onChangeQuery.mockClear();
      fireEvent.click(screen.getByRole('button', {name: 'Add Ops'}));
      // The query is cleared through the same path a typed change takes:
      // the bootstrap reload is pending and the change is reported.
      expect(list()).toHaveAttribute('aria-busy', 'true');
      expect(screen.getByRole('img', {name: 'Loading'})).toBeInTheDocument();
      expect(onChangeQuery).toHaveBeenCalledWith('');
      await act(async () => {
        await vi.advanceTimersByTimeAsync(400);
      });
      expect(list()).not.toHaveAttribute('aria-busy');
      expect(
        screen.getByRole('checkbox', {name: 'Design'}),
      ).toBeInTheDocument();
    } finally {
      vi.useRealTimers();
    }
  });

  it('joins two announcements from one change inside the sheet (AST-086 FR14)', async () => {
    const matches = Element.prototype.matches;
    const spy = vi
      .spyOn(Element.prototype, 'matches')
      .mockImplementation(function (this: Element, selector: string) {
        return selector === ':modal'
          ? this instanceof HTMLDialogElement && this.open
          : matches.call(this, selector);
      });
    try {
      render(<Harness hasCreate maxEntries={2} initial={[ITEMS[0]]} />);
      fireEvent.click(openTrigger());
      const dialog = await screen.findByRole('dialog', {name: 'Tags'});
      const region = () =>
        dialog.querySelector(
          ':scope > [data-astryx-modal-live-region="polite"]',
        );
      // Typing a query that both searches (its count is announced on settle)
      // and, here with an instant source, settles in the same frame as the
      // create row appears: the count includes the create row the sheet
      // offers, as the inline field counts its create entry.
      fireEvent.change(screen.getByLabelText('Search Tags'), {
        target: {value: 'Ops'},
      });
      await waitFor(() => expect(region()).toHaveTextContent('1 result'));
      // Two selection changes in one frame: neither is dropped.
      fireEvent.change(screen.getByLabelText('Search Tags'), {
        target: {value: ''},
      });
      await screen.findByRole('checkbox', {name: 'Eng'});
      await act(async () => {
        await new Promise(resolve =>
          requestAnimationFrame(() => resolve(null)),
        );
        await new Promise(resolve =>
          requestAnimationFrame(() => resolve(null)),
        );
      });
      fireEvent.click(screen.getByRole('checkbox', {name: 'Eng'}));
      fireEvent.click(screen.getByRole('checkbox', {name: 'Design'}));
      await waitFor(() =>
        expect(region()).toHaveTextContent('Added Eng Removed Design'),
      );
    } finally {
      spy.mockRestore();
    }
  });

  it('clears the query on Escape dismissal, so the next open lists the bootstrap set and settles (FR18, FR20)', async () => {
    const onChangeQuery = vi.fn();
    const search = vi.fn(source.search);
    render(
      <Tokenizer
        label="Tags"
        searchSource={{...source, search}}
        value={[]}
        onChange={() => {}}
        onChangeQuery={onChangeQuery}
        debounceMs={0}
        minQueryLength={3}
        hasCreate
        presentation="bottom-sheet"
      />,
    );
    fireEvent.click(openTrigger());
    const dialog = await screen.findByRole('dialog', {name: 'Tags'});
    await screen.findByRole('checkbox', {name: 'Design'});
    // A query below the threshold, then an Escape dismissal: the query does
    // not survive the close.
    fireEvent.change(screen.getByLabelText('Search Tags'), {
      target: {value: 'De'},
    });
    expect(screen.getByRole('button', {name: 'Add De'})).toBeInTheDocument();
    onChangeQuery.mockClear();
    search.mockClear();
    fireEvent.keyDown(dialog, {key: 'Escape'});
    await waitFor(() =>
      expect(openTrigger()).toHaveAttribute('aria-expanded', 'false'),
    );
    expect(onChangeQuery).toHaveBeenCalledWith('');
    fireEvent.transitionEnd(document.querySelector('.astryx-bottom-sheet')!, {
      propertyName: 'transform',
    });
    // Reopened: the search field is empty, the bootstrap set loads and
    // settles — no list left pending for a search that never runs.
    fireEvent.click(openTrigger());
    await screen.findByRole('dialog', {name: 'Tags'});
    expect(screen.getByLabelText('Search Tags')).toHaveValue('');
    await screen.findByRole('checkbox', {name: 'Eng'});
    expect(list()).not.toHaveAttribute('aria-busy');
    expect(
      screen.queryByRole('img', {name: 'Loading'}),
    ).not.toBeInTheDocument();
    expect(
      screen.queryByRole('button', {name: /^Add /}),
    ).not.toBeInTheDocument();
    expect(search).not.toHaveBeenCalled();
  });

  it('reports the cleared query from the close handler, not during render (FR18; runtime INV2)', async () => {
    const errors = vi.spyOn(console, 'error').mockImplementation(() => {});
    try {
      // A caller that mirrors the query into its own state: a render-phase
      // report would be a cross-component update React warns about.
      function Mirror() {
        const [query, setQuery] = useState('');
        return (
          <>
            <Tokenizer
              label="Tags"
              searchSource={source}
              value={[]}
              onChange={() => {}}
              onChangeQuery={setQuery}
              debounceMs={0}
              presentation="bottom-sheet"
            />
            <output data-testid="mirror">{query}</output>
          </>
        );
      }
      render(<Mirror />);
      fireEvent.click(openTrigger());
      const dialog = await screen.findByRole('dialog', {name: 'Tags'});
      fireEvent.change(screen.getByLabelText('Search Tags'), {
        target: {value: 'En'},
      });
      expect(screen.getByTestId('mirror')).toHaveTextContent('En');
      fireEvent.keyDown(dialog, {key: 'Escape'});
      await waitFor(() =>
        expect(openTrigger()).toHaveAttribute('aria-expanded', 'false'),
      );
      expect(screen.getByTestId('mirror')).toHaveTextContent('');
      const renderPhase = errors.mock.calls.filter(call =>
        String(call[0]).includes('Cannot update a component'),
      );
      expect(renderPhase).toEqual([]);
    } finally {
      errors.mockRestore();
    }
  });

  it('loads the bootstrap set at once on open: an instant source shows no Loading row and announces nothing (FR20)', async () => {
    const matches = Element.prototype.matches;
    const spy = vi
      .spyOn(Element.prototype, 'matches')
      .mockImplementation(function (this: Element, selector: string) {
        return selector === ':modal'
          ? this instanceof HTMLDialogElement && this.open
          : matches.call(this, selector);
      });
    try {
      // Default debounceMs (150): the open must not wait for it.
      render(
        <Tokenizer
          label="Tags"
          searchSource={source}
          value={[ITEMS[0]]}
          onChange={() => {}}
          presentation="bottom-sheet"
        />,
      );
      fireEvent.click(openTrigger());
      const dialog = await screen.findByRole('dialog', {name: 'Tags'});
      await screen.findByRole('checkbox', {name: 'Eng'});
      expect(list()).not.toHaveAttribute('aria-busy');
      expect(
        screen.queryByRole('img', {name: 'Loading'}),
      ).not.toBeInTheDocument();
      // Nothing was announced for the open: no region was ever needed.
      await act(async () => {
        await new Promise(resolve => setTimeout(resolve, 50));
      });
      expect(
        dialog.querySelector('[data-astryx-modal-live-region]'),
      ).toBeNull();
      // A typed query still waits for the debounce (busy meanwhile), and
      // clearing it reloads the bootstrap set at once.
      fireEvent.change(screen.getByLabelText('Search Tags'), {
        target: {value: 'En'},
      });
      expect(list()).toHaveAttribute('aria-busy', 'true');
      await waitFor(() => expect(list()).not.toHaveAttribute('aria-busy'));
      fireEvent.change(screen.getByLabelText('Search Tags'), {
        target: {value: ''},
      });
      await screen.findByRole('checkbox', {name: 'Design'});
      expect(list()).not.toHaveAttribute('aria-busy');
    } finally {
      spy.mockRestore();
    }
  });

  it('moves focus to the search field when a settled search removes the focused row (FR20; AST-085 FR4)', async () => {
    render(<Harness initial={[]} />);
    fireEvent.click(openTrigger());
    await screen.findByRole('dialog', {name: 'Tags'});
    const design = await screen.findByRole('checkbox', {name: 'Design'});
    design.focus();
    expect(design).toHaveFocus();
    // A query Design does not match: the settled search removes the focused
    // row, and focus lands on the search field, not the page body.
    fireEvent.change(screen.getByLabelText('Search Tags'), {
      target: {value: 'En'},
    });
    await waitFor(() =>
      expect(
        screen.queryByRole('checkbox', {name: 'Design'}),
      ).not.toBeInTheDocument(),
    );
    expect(screen.getByLabelText('Search Tags')).toHaveFocus();
    expect(document.activeElement).not.toBe(document.body);
  });

  it('awaits a non-native thenable from the source, as the inline field does (FR20)', async () => {
    // A thenable that is not a native Promise: a library promise, or one
    // from another realm. Typed as what the source contract names so the
    // source is a plain object of synchronous functions returning it.
    const asThenable = (items: SearchableItem[]) =>
      ({
        then: (resolve: (items: SearchableItem[]) => void) => {
          resolve(items);
        },
      }) as unknown as SearchableItem[];
    const thenable: SearchSource<SearchableItem> = {
      bootstrap: () => asThenable(ITEMS),
      search: q => asThenable(source.search(q) as SearchableItem[]),
    };
    const errors = vi.spyOn(console, 'error').mockImplementation(() => {});
    try {
      render(
        <Tokenizer
          label="Tags"
          searchSource={thenable}
          value={[]}
          onChange={() => {}}
          debounceMs={0}
          presentation="bottom-sheet"
        />,
      );
      fireEvent.click(openTrigger());
      await screen.findByRole('dialog', {name: 'Tags'});
      expect(
        await screen.findByRole('checkbox', {name: 'Design'}),
      ).toBeInTheDocument();
      fireEvent.change(screen.getByLabelText('Search Tags'), {
        target: {value: 'Ener'},
      });
      expect(
        await screen.findByRole('checkbox', {name: 'Energizer'}),
      ).toBeInTheDocument();
      expect(list()).not.toHaveAttribute('aria-busy');
      expect(errors).not.toHaveBeenCalled();
    } finally {
      errors.mockRestore();
    }
  });

  it('subscribes to matchMedia only for the adaptive presentation (runtime INV5)', () => {
    const added: string[] = [];
    const matchMedia = vi.fn().mockImplementation((query: string) => ({
      matches: false,
      media: query,
      onchange: null,
      addEventListener: () => {
        added.push(query);
      },
      removeEventListener: vi.fn(),
      addListener: vi.fn(),
      removeListener: vi.fn(),
      dispatchEvent: vi.fn(),
    }));
    vi.stubGlobal('matchMedia', matchMedia);
    // A fixed presentation evaluates no query and registers no listener.
    render(<Harness presentation="popover" />);
    render(<Harness presentation="bottom-sheet" />);
    expect(
      matchMedia.mock.calls.filter(([q]) => q === COMPACT_TOUCH_QUERY),
    ).toHaveLength(0);
    expect(added.filter(q => q === COMPACT_TOUCH_QUERY)).toHaveLength(0);
    // Only adaptive reads the policy, and subscribes once: by default and
    // when it is passed.
    const {unmount} = render(
      <Tokenizer
        label="Tags"
        searchSource={source}
        value={[]}
        onChange={() => {}}
      />,
    );
    expect(added.filter(q => q === COMPACT_TOUCH_QUERY)).toHaveLength(1);
    unmount();
    render(<Harness presentation="adaptive" />);
    expect(added.filter(q => q === COMPACT_TOUCH_QUERY)).toHaveLength(2);
  });

  it('moves focus to the sheet panel on open, not the search field (FR18)', async () => {
    render(<Harness />);
    fireEvent.click(openTrigger());
    const dialog = await screen.findByRole('dialog', {name: 'Tags'});
    await screen.findByRole('checkbox', {name: 'Design'});
    expect(dialog.contains(document.activeElement)).toBe(true);
    expect(screen.getByLabelText('Search Tags')).not.toHaveFocus();
  });

  it('moves focus to the search field after the create row is activated (FR22)', async () => {
    render(<Harness hasCreate initial={[]} />);
    fireEvent.click(openTrigger());
    await screen.findByRole('dialog', {name: 'Tags'});
    fireEvent.change(screen.getByLabelText('Search Tags'), {
      target: {value: 'Ops'},
    });
    const add = await screen.findByRole('button', {name: 'Add Ops'});
    add.focus();
    fireEvent.click(add);
    expect(
      screen.queryByRole('button', {name: 'Add Ops'}),
    ).not.toBeInTheDocument();
    expect(screen.getByLabelText('Search Tags')).toHaveFocus();
  });

  it("moves focus to the new presentation's control when adaptive changes while the sheet is closed (FR16)", async () => {
    let compact = true;
    const listeners = new Set<() => void>();
    vi.stubGlobal(
      'matchMedia',
      vi.fn().mockImplementation((query: string) => ({
        get matches() {
          return query === COMPACT_TOUCH_QUERY ? compact : false;
        },
        media: query,
        onchange: null,
        addEventListener: (_: string, cb: () => void) => listeners.add(cb),
        removeEventListener: (_: string, cb: () => void) =>
          listeners.delete(cb),
        addListener: vi.fn(),
        removeListener: vi.fn(),
        dispatchEvent: vi.fn(),
      })),
    );
    const onFocus = vi.fn();
    const onBlur = vi.fn();
    render(
      <Harness presentation="adaptive" onFocus={onFocus} onBlur={onBlur} />,
    );
    const trigger = openTrigger();
    trigger.focus();
    expect(trigger).toHaveFocus();
    expect(onFocus).toHaveBeenCalledTimes(1);
    // Trigger focused, phone turns to landscape: the input takes over, and
    // the hand-off inside the field reports neither a blur nor a focus.
    compact = false;
    act(() => {
      for (const cb of listeners) {
        cb();
      }
    });
    expect(screen.getByRole('combobox')).toHaveFocus();
    expect(onFocus).toHaveBeenCalledTimes(1);
    expect(onBlur).not.toHaveBeenCalled();
    // And back: the input focused, the screen becomes compact again.
    compact = true;
    act(() => {
      for (const cb of listeners) {
        cb();
      }
    });
    expect(openTrigger()).toHaveFocus();
    // Unfocused, a change moves nothing.
    openTrigger().blur();
    compact = false;
    act(() => {
      for (const cb of listeners) {
        cb();
      }
    });
    expect(document.body).toHaveFocus();
  });

  it('hands focus to the trigger when a swap removes a focused Remove button or Clear all (FR16)', () => {
    let compact = false;
    const listeners = new Set<() => void>();
    vi.stubGlobal(
      'matchMedia',
      vi.fn().mockImplementation((query: string) => ({
        get matches() {
          return query === COMPACT_TOUCH_QUERY ? compact : false;
        },
        media: query,
        onchange: null,
        addEventListener: (_: string, cb: () => void) => listeners.add(cb),
        removeEventListener: (_: string, cb: () => void) =>
          listeners.delete(cb),
        addListener: vi.fn(),
        removeListener: vi.fn(),
        dispatchEvent: vi.fn(),
      })),
    );
    const turn = (next: boolean) => {
      compact = next;
      act(() => {
        for (const cb of listeners) {
          cb();
        }
      });
    };
    render(<Harness presentation="adaptive" hasClear />);
    // Inline: a token's Remove button holds focus, then the screen turns
    // compact-touch.
    // Enter the field first: focus arriving from the page is redirected to
    // the input, so a Remove button only holds focus once inside.
    screen.getByRole('combobox').focus();
    const remove = screen.getByRole('button', {name: 'Remove Design'});
    remove.focus();
    expect(remove).toHaveFocus();
    turn(true);
    expect(openTrigger()).toHaveFocus();
    // Back to inline, then the inline Clear all holds focus.
    turn(false);
    const clearAll = screen.getByRole('button', {name: 'Clear all'});
    clearAll.focus();
    expect(clearAll).toHaveFocus();
    turn(true);
    expect(openTrigger()).toHaveFocus();
  });

  it('owes no hand-off once focus has left the field, even after the wrapper re-attached while focused (FR16)', () => {
    const onFocus = vi.fn();
    const stableRef = () => {};
    const field = (isDisabled: boolean, ref: () => void = stableRef) => (
      <Tokenizer
        label="Tags"
        searchSource={source}
        value={[]}
        onChange={() => {}}
        onFocus={onFocus}
        isDisabled={isDisabled}
        disabledMessage="You need the Editor role"
        ref={ref}
        presentation="popover"
      />
    );
    const {rerender} = render(field(false));
    const input = screen.getByRole('combobox');
    input.focus();
    expect(onFocus).toHaveBeenCalledTimes(1);
    // Toggling isDisabled re-attaches the field's wrapper, not the input,
    // while the input holds focus, which notes a hand-off.
    rerender(field(true));
    rerender(field(false));
    expect(input).toHaveFocus();
    // The user leaves the field.
    act(() => {
      input.blur();
    });
    expect(document.body).toHaveFocus();
    // A later re-attach of the input (a new inline ref) must not pull focus
    // back.
    rerender(field(false, () => {}));
    expect(document.body).toHaveFocus();
    expect(onFocus).toHaveBeenCalledTimes(1);
  });

  it('moves no focus when a control re-attaches without a swap, such as a new ref callback (FR16; react-component-runtime INV6)', () => {
    const onFocus = vi.fn();
    const {rerender} = render(
      <Tokenizer
        label="Tags"
        searchSource={source}
        value={[]}
        onChange={() => {}}
        onFocus={onFocus}
        ref={() => {}}
        presentation="popover"
      />,
    );
    const input = screen.getByRole('combobox');
    input.focus();
    expect(onFocus).toHaveBeenCalledTimes(1);
    // A new inline ref detaches and re-attaches the same input while it
    // holds focus: nothing is handed off, and no focus is reported again.
    rerender(
      <Tokenizer
        label="Tags"
        searchSource={source}
        value={[]}
        onChange={() => {}}
        onFocus={onFocus}
        ref={() => {}}
        presentation="popover"
      />,
    );
    expect(input).toHaveFocus();
    expect(onFocus).toHaveBeenCalledTimes(1);
    // Focus elsewhere: a later re-attach takes nothing back.
    input.blur();
    rerender(
      <Tokenizer
        label="Tags"
        searchSource={source}
        value={[]}
        onChange={() => {}}
        onFocus={onFocus}
        ref={() => {}}
        presentation="popover"
      />,
    );
    expect(document.body).toHaveFocus();
  });

  it('carries hidden form inputs and the field chrome in the sheet presentation', () => {
    const {container} = render(
      <Tokenizer
        label="Tags"
        searchSource={source}
        value={[ITEMS[0], ITEMS[1]]}
        onChange={() => {}}
        htmlName="tags"
        status={{type: 'error', message: 'Pick at least three'}}
        presentation="bottom-sheet"
      />,
    );
    const hidden = container.querySelectorAll('input[type="hidden"]');
    expect(hidden).toHaveLength(2);
    expect(hidden[0]).toHaveAttribute('name', 'tags');
    expect(hidden[0]).toHaveValue('design');
    expect(sheetField()).toHaveAttribute('data-status', 'error');
    expect(screen.getByText('Pick at least three')).toBeInTheDocument();
  });

  it('submits nothing while disabled, in the sheet presentation as in the inline field (FR10, FR17)', () => {
    const field = (
      presentation: 'popover' | 'bottom-sheet',
      isDisabled: boolean,
    ) => (
      <form>
        <Tokenizer
          label="Tags"
          searchSource={source}
          value={[ITEMS[0], ITEMS[1]]}
          onChange={() => {}}
          htmlName="tags"
          isDisabled={isDisabled}
          presentation={presentation}
        />
      </form>
    );
    for (const presentation of ['popover', 'bottom-sheet'] as const) {
      const enabled = render(field(presentation, false));
      expect(
        new FormData(enabled.container.querySelector('form')!).getAll('tags'),
      ).toEqual(['design', 'eng']);
      enabled.unmount();
      const disabled = render(field(presentation, true));
      const form = disabled.container.querySelector('form')!;
      expect([...new FormData(form).keys()]).toEqual([]);
      expect(form.querySelector('input[type="hidden"]')).toBeNull();
      disabled.unmount();
    }
  });
});

describe('Tokenizer sheet draft, Save and dismissal (FR18, FR23, FR24, FR26, FR27)', () => {
  it('draws the search field as the shared input box at the lg input height above the 44px rows — the input border with its forced-colors branch, accent on focus, element radius, surface — unlike the borderless panel field the dropdowns share (FR18)', () => {
    const atoms = (className: string | undefined) =>
      (className ?? '').split(' ').filter(name => !name.includes('__'));
    // The same shared box the inline field composes, then the sheet's own
    // height and padding on top (later wins per property, as in the sheet).
    const own = stylex.create({
      field: {
        minHeight: sizeVars['--size-element-lg'],
        paddingBlock: spacingVars['--spacing-1'],
      },
      touch: {minHeight: 44},
    });
    render(<Harness />);
    fireEvent.click(openTrigger());
    const input = screen.getByLabelText('Search Tags');
    const field = input.parentElement!;
    for (const name of atoms(
      stylex.props(
        inputWrapperStyles.base,
        inputWrapperStyles.textField,
        own.field,
      ).className,
    )) {
      expect(field).toHaveClass(name);
    }
    for (const name of atoms(stylex.props(own.touch).className)) {
      expect(field).not.toHaveClass(name);
    }
  });

  it('keeps Clear all and Save pinned while searching, while pending and with an empty query (FR18)', async () => {
    render(<Harness />);
    fireEvent.click(openTrigger());
    await screen.findByRole('checkbox', {name: 'Energizer'});
    expect(screen.getByRole('button', {name: 'Save'})).toBeInTheDocument();
    fireEvent.change(screen.getByLabelText('Search Tags'), {
      target: {value: 'zzz'},
    });
    await screen.findByText('No results found');
    expect(screen.getByRole('button', {name: 'Clear all'})).toBeInTheDocument();
    expect(screen.getByRole('button', {name: 'Save'})).toBeInTheDocument();
  });

  it('Save with an unchanged draft reports nothing and closes (FR26)', async () => {
    const spy = vi.fn();
    render(<Harness spy={spy} />);
    const trigger = openTrigger();
    fireEvent.click(trigger);
    await screen.findByRole('checkbox', {name: 'Energizer'});
    fireEvent.click(screen.getByRole('button', {name: 'Save'}));
    expect(spy).not.toHaveBeenCalled();
    expect(trigger).toHaveAttribute('aria-expanded', 'false');
  });

  it("Save's change is the last edit that still holds: a create then an add reports the add; an add then its own undo falls back to the other net edit (FR26)", async () => {
    const spy = vi.fn();
    render(<Harness spy={spy} hasCreate initial={[]} />);
    fireEvent.click(openTrigger());
    const search = await screen.findByLabelText('Search Tags');
    fireEvent.change(search, {target: {value: 'Custom'}});
    await act(async () => {
      fireEvent.click(await screen.findByRole('button', {name: 'Add Custom'}));
    });
    await screen.findByRole('checkbox', {name: 'Design'});
    fireEvent.click(screen.getByRole('checkbox', {name: 'Design'}));
    fireEvent.click(screen.getByRole('button', {name: 'Save'}));
    expect(spy).toHaveBeenCalledTimes(1);
    expect(spy).toHaveBeenCalledWith(
      [{id: 'Custom', label: 'Custom'}, ITEMS[0]],
      {item: ITEMS[0], type: 'add'},
    );
  });

  it('an add that is undone before Save does not hold: Save names the edit that does (FR26)', async () => {
    const spy = vi.fn();
    render(<Harness spy={spy} initial={[ITEMS[0]]} />);
    fireEvent.click(openTrigger());
    await screen.findByRole('checkbox', {name: 'Energizer'});
    // Remove Design (holds), add Eng, then undo the add: the last edit is a
    // removal of Eng, which was never selected at open, so it does not hold;
    // the removal of Design does.
    fireEvent.click(screen.getByRole('checkbox', {name: 'Design'}));
    fireEvent.click(screen.getByRole('checkbox', {name: 'Eng'}));
    fireEvent.click(screen.getByRole('checkbox', {name: 'Eng'}));
    fireEvent.click(screen.getByRole('button', {name: 'Save'}));
    expect(spy).toHaveBeenCalledWith([], {item: ITEMS[0], type: 'remove'});
  });

  it('a clean swipe, scrim or Escape dismissal closes directly; a changed draft asks first, Keep editing returns focus to the search field, Discard changes closes without a report (FR27)', async () => {
    const spy = vi.fn();
    render(<Harness spy={spy} />);
    const trigger = openTrigger();
    fireEvent.click(trigger);
    const sheet = await screen.findByRole('dialog', {name: 'Tags'});
    await screen.findByRole('checkbox', {name: 'Energizer'});
    // Clean: Escape closes at once, nothing asked — also after a row is
    // unchecked and checked again, which leaves the selection as it was.
    fireEvent.click(screen.getByRole('checkbox', {name: 'Design'}));
    fireEvent.click(screen.getByRole('checkbox', {name: 'Design'}));
    fireEvent.keyDown(sheet, {key: 'Escape'});
    expect(screen.queryByRole('alertdialog')).toBeNull();
    expect(trigger).toHaveAttribute('aria-expanded', 'false');
    expect(spy).not.toHaveBeenCalled();
    // Reopen, change the draft, Escape: the confirmation, safe action first.
    await act(async () => {
      fireEvent.click(trigger);
    });
    await screen.findByRole('checkbox', {name: 'Energizer'});
    fireEvent.click(screen.getByRole('checkbox', {name: 'Energizer'}));
    fireEvent.keyDown(screen.getByRole('dialog', {name: 'Tags'}), {
      key: 'Escape',
    });
    const confirmation = await screen.findByRole('alertdialog');
    expect(confirmation).toHaveTextContent('Discard changes?');
    expect(confirmation).toHaveTextContent(
      "Your changes to Tags haven't been saved.",
    );
    const [destructive, safe] = within(confirmation).getAllByRole('button');
    expect(destructive).toHaveAccessibleName('Discard changes');
    expect(safe).toHaveAccessibleName('Keep editing');
    expect(safe).toHaveAttribute('data-autofocus');
    // Keep editing: still open, the draft intact, focus on the search field.
    fireEvent.click(safe);
    await waitFor(() => expect(screen.queryByRole('alertdialog')).toBeNull());
    expect(screen.getByLabelText('Search Tags')).toHaveFocus();
    expect(screen.getByRole('checkbox', {name: 'Energizer'})).toBeChecked();
    expect(spy).not.toHaveBeenCalled();
    // Discard changes: closes without a report; `value` unchanged.
    fireEvent.keyDown(screen.getByRole('dialog', {name: 'Tags'}), {
      key: 'Escape',
    });
    fireEvent.click(
      within(await screen.findByRole('alertdialog')).getByRole('button', {
        name: 'Discard changes',
      }),
    );
    expect(spy).not.toHaveBeenCalled();
    expect(trigger).toHaveAttribute('aria-expanded', 'false');
    expect(trigger).toHaveAccessibleDescription(/2 selected Design Eng/);
  });

  it('Save over the limit is aria-disabled with the limit as its reason, and works again once the draft is within it (FR23)', async () => {
    const spy = vi.fn();
    render(<Harness spy={spy} initial={[ITEMS[0], ITEMS[1]]} maxEntries={1} />);
    fireEvent.click(openTrigger());
    await screen.findByRole('checkbox', {name: 'Energizer'});
    const save = screen.getByRole('button', {name: 'Save'});
    expect(save).toHaveAttribute('aria-disabled', 'true');
    expect(save).not.toHaveAttribute('disabled');
    expect(save).toHaveAccessibleDescription('Select up to 1 item');
    fireEvent.click(save);
    expect(spy).not.toHaveBeenCalled();
    fireEvent.click(screen.getByRole('checkbox', {name: 'Eng'}));
    expect(screen.getByRole('button', {name: 'Save'})).not.toHaveAttribute(
      'aria-disabled',
    );
    fireEvent.click(screen.getByRole('button', {name: 'Save'}));
    expect(spy).toHaveBeenCalledWith([ITEMS[0]], {
      item: ITEMS[1],
      type: 'remove',
    });
  });

  it('a direct vertical drag on the results moves focus from the search field to the sheet panel, keeping the query; a tap or a short move does not (FR18; AST-085 FR4)', async () => {
    render(<Harness />);
    fireEvent.click(openTrigger());
    const sheet = await screen.findByRole('dialog', {name: 'Tags'});
    await screen.findByRole('checkbox', {name: 'Energizer'});
    const search = screen.getByLabelText('Search Tags');
    fireEvent.change(search, {target: {value: 'En'}});
    search.focus();
    const results = list();
    const touches = (clientY: number) => [{clientY}];
    fireEvent.touchStart(results, {touches: touches(100)});
    fireEvent.touchMove(results, {touches: touches(104)});
    expect(search).toHaveFocus();
    fireEvent.touchMove(results, {touches: touches(110)});
    expect(search).not.toHaveFocus();
    expect(document.activeElement).not.toBe(document.body);
    expect(sheet.contains(document.activeElement)).toBe(true);
    expect(document.activeElement).toHaveAttribute('tabindex', '-1');
    expect(search).toHaveValue('En');
  });
});

describe('Tokenizer sheet under the BottomSheet stack (component:BottomSheet FR8, FR9; AST-003 FR18)', () => {
  const stackSummary = () =>
    getBottomSheetStackForTests().map(({element, isOpen, view}) => {
      const label = element?.getAttribute('aria-label') ?? '?';
      const state = !isOpen ? 'exiting' : view.isTop ? 'top' : 'covered';
      return `${label}:${state}:${view.depth}`;
    });
  const finishExit = (dialog: HTMLElement) => {
    for (const panel of Array.from(
      dialog.querySelectorAll<HTMLElement>('.astryx-bottom-sheet'),
    )) {
      if (panel.closest('dialog') === dialog) {
        fireEvent.transitionEnd(panel, {propertyName: 'transform'});
      }
    }
  };
  /** A field inside a host sheet, as PowerSearch's value step hosts one. */
  function Hosted() {
    const [isHostOpen, setIsHostOpen] = useState(false);
    const [value, setValue] = useState<SearchableItem[]>([ITEMS[0]]);
    return (
      <>
        <button type="button" onClick={() => setIsHostOpen(true)}>
          Open step
        </button>
        <BottomSheet
          isOpen={isHostOpen}
          onOpenChange={setIsHostOpen}
          label="Value">
          <Tokenizer
            label="Tags"
            searchSource={source}
            value={value}
            onChange={items => setValue(items)}
            debounceMs={0}
            presentation="bottom-sheet"
          />
        </BottomSheet>
      </>
    );
  }

  it('opened from inside a host sheet, is one stacked standalone sheet on top: the host recedes, Escape closes only the field sheet, focus returns to the trigger inside the host', async () => {
    render(<Hosted />);
    fireEvent.click(screen.getByRole('button', {name: 'Open step'}));
    const host = screen.getByRole('dialog', {name: 'Value'});
    expect(stackSummary()).toEqual(['Value:top:0']);
    const trigger = openTrigger();
    trigger.focus();
    fireEvent.click(trigger);
    const sheet = await screen.findByRole('dialog', {name: 'Tags'});
    await screen.findByRole('checkbox', {name: 'Eng'});
    // The field's sheet is the top of the stack; the host is covered and
    // recedes, and its dialog, which contains the field sheet, is left to the
    // browser's modal blocking rather than marked inert.
    expect(stackSummary()).toEqual(['Value:covered:1', 'Tags:top:0']);
    expect(host).toHaveAttribute('data-sheet-stack', 'covered');
    expect(host).not.toHaveAttribute('inert');
    expect(sheet).toHaveAttribute('aria-modal', 'true');
    expect(sheet).not.toHaveAttribute('inert');
    // A row toggle works on top of the host.
    fireEvent.click(within(sheet).getByRole('checkbox', {name: 'Eng'}));
    await waitFor(() =>
      expect(within(sheet).getByRole('checkbox', {name: 'Eng'})).toBeChecked(),
    );
    // Escape reaches only the top sheet. The draft is changed, so the field
    // sheet asks first (FR27); Discard changes closes it, the host stays open
    // and is the top again; focus returns to the trigger inside the host
    // (FR9: the opener, inside the revealed sheet).
    fireEvent.keyDown(sheet, {key: 'Escape'});
    const confirmation = await screen.findByRole('alertdialog');
    expect(stackSummary()).toEqual(['Value:covered:1', 'Tags:top:0']);
    fireEvent.click(
      within(confirmation).getByRole('button', {name: 'Discard changes'}),
    );
    finishExit(sheet);
    await waitFor(() =>
      expect(
        screen.queryByRole('dialog', {name: 'Tags'}),
      ).not.toBeInTheDocument(),
    );
    expect(stackSummary()).toEqual(['Value:top:0']);
    expect(host).not.toHaveAttribute('data-sheet-stack');
    expect(host).toHaveAttribute('open');
    await waitFor(() => expect(openTrigger()).toHaveFocus());
    // The discarded toggle never reached the field's value.
    expect(openTrigger()).toHaveAccessibleDescription(/1 selected Design/);
  });

  it("the Clear all confirmation opens over the field's sheet and returns into it; a toast raised meanwhile lands in the field's dialog (AST-003 FR18)", async () => {
    render(<Hosted />);
    fireEvent.click(screen.getByRole('button', {name: 'Open step'}));
    fireEvent.click(openTrigger());
    const sheet = await screen.findByRole('dialog', {name: 'Tags'});
    await screen.findByRole('checkbox', {name: 'Eng'});
    // While the field's sheet is the top modal, it is the active outlet for
    // app-global surfaces: a toast raised from inside lands in its dialog.
    expect(getActiveModalOutlet()).toBe(sheet);
    fireEvent.click(within(sheet).getByRole('button', {name: 'Clear all'}));
    const confirmation = await screen.findByRole('alertdialog');
    // A Dialog over the sheet does not join the sheet stack (only sheets
    // count); the field sheet stays the top sheet while covered by it, and
    // the confirmation is now the latest outlet.
    expect(stackSummary()).toEqual(['Value:covered:1', 'Tags:top:0']);
    expect(getActiveModalOutlet()).toBe(confirmation);
    fireEvent.click(
      within(confirmation).getByRole('button', {name: 'Clear selection'}),
    );
    await waitFor(() =>
      expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument(),
    );
    // Back in the field's sheet: focus on its Clear all, the sheet the
    // outlet again, the host still covered beneath.
    expect(
      within(sheet).getByRole('button', {name: 'Clear all'}),
    ).toHaveFocus();
    expect(getActiveModalOutlet()).toBe(sheet);
    expect(stackSummary()).toEqual(['Value:covered:1', 'Tags:top:0']);
  });
});

// The sheet calls the source's cancel where the inline field does: when a
// newer query replaces pending work, and when the sheet closes or unmounts
// while work is pending (spec:BaseTypeahead PR1, component:Tokenizer).
describe('Tokenizer sheet presentation: search cancellation', () => {
  function pendingSource() {
    const cancel = vi.fn();
    const pending: SearchSource<SearchableItem> = {
      search: async () => new Promise<SearchableItem[]>(() => {}),
      bootstrap: async () => new Promise<SearchableItem[]>(() => {}),
      cancel,
    };
    return {source: pending, cancel};
  }

  function renderSheet(searchSource: SearchSource<SearchableItem>) {
    return render(
      <Tokenizer
        label="Tags"
        searchSource={searchSource}
        value={[]}
        onChange={() => {}}
        debounceMs={0}
        presentation="bottom-sheet"
      />,
    );
  }

  it('cancels a pending search once when a newer query replaces it', async () => {
    const {source: pending, cancel} = pendingSource();
    renderSheet(pending);
    fireEvent.click(openTrigger());
    const search = await screen.findByLabelText('Search Tags');
    expect(cancel).not.toHaveBeenCalled();
    fireEvent.change(search, {target: {value: 'en'}});
    expect(cancel).toHaveBeenCalledTimes(1);
  });

  it('cancels pending work once when the sheet closes', async () => {
    const {source: pending, cancel} = pendingSource();
    renderSheet(pending);
    fireEvent.click(openTrigger());
    await screen.findByLabelText('Search Tags');
    fireEvent.click(screen.getByRole('button', {name: 'Save'}));
    await waitFor(() => expect(cancel).toHaveBeenCalledTimes(1));
  });

  it('cancels pending work once when the field unmounts', async () => {
    const {source: pending, cancel} = pendingSource();
    const {unmount} = renderSheet(pending);
    fireEvent.click(openTrigger());
    await screen.findByLabelText('Search Tags');
    unmount();
    expect(cancel).toHaveBeenCalledTimes(1);
  });

  it('cancels the source that started a request, not a replacement source', async () => {
    const first = pendingSource();
    const second = pendingSource();
    const {rerender} = renderSheet(first.source);
    fireEvent.click(openTrigger());
    const search = await screen.findByLabelText('Search Tags');
    rerender(
      <Tokenizer
        label="Tags"
        searchSource={second.source}
        value={[]}
        onChange={() => {}}
        debounceMs={0}
        presentation="bottom-sheet"
      />,
    );
    fireEvent.change(search, {target: {value: 'en'}});
    expect(first.cancel).toHaveBeenCalledTimes(1);
    expect(second.cancel).not.toHaveBeenCalled();
  });

  it('does not cancel when no work is pending', async () => {
    const cancel = vi.fn();
    const {unmount} = renderSheet({...source, cancel});
    fireEvent.click(openTrigger());
    const search = await screen.findByLabelText('Search Tags');
    fireEvent.change(search, {target: {value: 'en'}});
    fireEvent.click(screen.getByRole('button', {name: 'Save'}));
    unmount();
    expect(cancel).not.toHaveBeenCalled();
  });
});