An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file CommandPalette.test.tsx
* @input Uses vitest, @testing-library/react, CommandPalette
* @output Unit tests for CommandPalette dialog shell
* @position Testing; validates CommandPalette.tsx implementation
*/
import {describe, it, expect, vi, beforeEach} from 'vitest';
import {render, screen, waitFor, fireEvent, act} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {Component, useState, type ReactNode} from 'react';
import {CommandPalette} from './CommandPalette';
import {CommandPaletteInput} from './CommandPaletteInput';
import {getFocusableElements} from '../hooks/useFocusTrap';
import {useLayerDismissal} from '../Layer/useLayerDismissal';
import {createStaticSource} from '@astryxdesign/core/Typeahead';
import type {SearchSource, SearchableItem} from '@astryxdesign/core/Typeahead';
import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
const simpleSource = createStaticSource([
{id: 'home', label: 'Home'},
{id: 'settings', label: 'Settings'},
]);
const groupedSource = createStaticSource([
{id: 'home', label: 'Home', auxiliaryData: {group: 'Navigation'}},
{id: 'save', label: 'Save', auxiliaryData: {group: 'Actions'}},
]);
const emptySource = createStaticSource([]);
function NestedDismissible({onDismiss}: {onDismiss: () => void}) {
useLayerDismissal({isActive: true, onDismiss});
return null;
}
class TestErrorBoundary extends Component<
{children: ReactNode},
{hasError: boolean}
> {
state = {hasError: false};
static getDerivedStateFromError() {
return {hasError: true};
}
render(): ReactNode {
return this.state.hasError ? <p>Boundary fallback</p> : this.props.children;
}
}
// Mock showModal and close since jsdom doesn't implement them
beforeEach(() => {
HTMLDialogElement.prototype.showModal = vi.fn(function (
this: HTMLDialogElement,
) {
this.setAttribute('open', '');
});
HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {
this.removeAttribute('open');
});
// The live regions are module-level singletons; reset them so
// announcements from one test don't leak into the next.
__resetLiveRegionsForTest();
});
describe('CommandPalette', () => {
it('a closed palette adds no document pointermove listener', () => {
const addListener = vi.spyOn(document, 'addEventListener');
try {
render(
<CommandPalette
isOpen={false}
onOpenChange={() => {}}
searchSource={simpleSource}
/>,
);
const moveListeners = addListener.mock.calls.filter(
([type]) => type === 'pointermove',
);
expect(moveListeners).toEqual([]);
} finally {
addListener.mockRestore();
}
});
it('renders when isOpen is true', () => {
render(
<CommandPalette
isOpen={true}
onOpenChange={() => {}}
searchSource={simpleSource}
/>,
);
expect(screen.getByRole('dialog')).toBeInTheDocument();
});
it('does not show content when isOpen is false', () => {
render(
<CommandPalette
isOpen={false}
onOpenChange={() => {}}
searchSource={simpleSource}
/>,
);
const dialog = screen.getByRole('dialog', {hidden: true});
expect(dialog).not.toHaveAttribute('open');
});
it('has correct aria-label', () => {
render(
<CommandPalette
isOpen={true}
onOpenChange={() => {}}
searchSource={simpleSource}
/>,
);
expect(screen.getByRole('dialog')).toHaveAttribute(
'aria-label',
'Command palette',
);
});
it('supports custom label', () => {
render(
<CommandPalette
isOpen={true}
onOpenChange={() => {}}
searchSource={simpleSource}
label="Quick search"
/>,
);
expect(screen.getByRole('dialog')).toHaveAttribute(
'aria-label',
'Quick search',
);
});
it('renders default input and footer when not provided', () => {
render(
<CommandPalette
isOpen={true}
onOpenChange={() => {}}
searchSource={simpleSource}
/>,
);
expect(screen.getByRole('combobox')).toBeInTheDocument();
expect(screen.getByText(/Navigate/)).toBeInTheDocument();
});
it('renders custom input and footer slots', () => {
render(
<CommandPalette
isOpen={true}
onOpenChange={() => {}}
searchSource={simpleSource}
input={<div data-testid="input-slot">Custom Input</div>}
footer={<div data-testid="footer-slot">Custom Footer</div>}
/>,
);
expect(screen.getByTestId('input-slot')).toBeInTheDocument();
expect(screen.getByTestId('footer-slot')).toBeInTheDocument();
});
it('default renders items from searchSource bootstrap', async () => {
render(
<CommandPalette
isOpen={true}
onOpenChange={() => {}}
searchSource={simpleSource}
/>,
);
await waitFor(() => {
expect(screen.getByText('Home')).toBeInTheDocument();
expect(screen.getByText('Settings')).toBeInTheDocument();
});
});
it('auto-groups items by auxiliaryData.group', async () => {
render(
<CommandPalette
isOpen={true}
onOpenChange={() => {}}
searchSource={groupedSource}
/>,
);
await waitFor(() => {
expect(screen.getByText('Navigation')).toBeInTheDocument();
expect(screen.getByText('Actions')).toBeInTheDocument();
expect(screen.getByText('Home')).toBeInTheDocument();
expect(screen.getByText('Save')).toBeInTheDocument();
});
});
it('uses renderItem for custom item content', async () => {
render(
<CommandPalette
isOpen={true}
onOpenChange={() => {}}
searchSource={simpleSource}
renderItem={item => <span>{item.label.toUpperCase()}</span>}
/>,
);
await waitFor(() => {
expect(screen.getByText('HOME')).toBeInTheDocument();
expect(screen.getByText('SETTINGS')).toBeInTheDocument();
});
});
it('passes isSelected=true to renderItem for the selected value', async () => {
render(
<CommandPalette
isOpen={true}
onOpenChange={() => {}}
searchSource={simpleSource}
value="home"
renderItem={(item, isSelected) => (
<span>{isSelected ? `checked-${item.label}` : item.label}</span>
)}
/>,
);
await waitFor(() => {
expect(screen.getByText('checked-Home')).toBeInTheDocument();
expect(screen.getByText('Settings')).toBeInTheDocument();
});
});
it('shows emptyBootstrapText when bootstrap returns nothing', async () => {
render(
<CommandPalette
isOpen={true}
onOpenChange={() => {}}
searchSource={emptySource}
emptyBootstrapText="Nothing to show"
/>,
);
await waitFor(() => {
expect(screen.getByText('Nothing to show')).toBeInTheDocument();
});
});
it('keeps actionable empty content outside listbox semantics', async () => {
const {container} = render(
<CommandPalette
isOpen={true}
onOpenChange={() => {}}
searchSource={emptySource}
emptyBootstrapText={<a href="/commands/new">Create a command</a>}
/>,
);
expect(
await screen.findByRole('link', {name: 'Create a command'}),
).toHaveAttribute('href', '/commands/new');
expect(screen.queryByRole('listbox')).not.toBeInTheDocument();
expect(screen.queryByRole('option')).not.toBeInTheDocument();
expect(
container.querySelectorAll('.astryx-command-palette-empty'),
).toHaveLength(1);
expect(screen.getByRole('combobox')).toHaveAttribute(
'aria-expanded',
'false',
);
expect(screen.getByRole('combobox')).not.toHaveAttribute('aria-controls');
});
it('shows default emptyBootstrapText when not provided', async () => {
render(
<CommandPalette
isOpen={true}
onOpenChange={() => {}}
searchSource={emptySource}
/>,
);
await waitFor(() => {
expect(screen.getByText('Type to search')).toBeInTheDocument();
});
});
it('clears a stale highlight across empty and repopulated results', async () => {
render(
<CommandPalette
isOpen={true}
onOpenChange={() => {}}
searchSource={simpleSource}
/>,
);
await waitFor(() =>
expect(screen.getByText('Settings')).toBeInTheDocument(),
);
const input = screen.getByRole('combobox');
fireEvent.keyDown(input, {key: 'ArrowDown'});
fireEvent.keyDown(input, {key: 'ArrowDown'});
expect(input.getAttribute('aria-activedescendant')).toMatch(/-item-1$/);
fireEvent.change(input, {target: {value: 'zzz'}});
await waitFor(() => expect(screen.queryByRole('listbox')).toBeNull());
expect(input).not.toHaveAttribute('aria-activedescendant');
fireEvent.change(input, {target: {value: 'hom'}});
await waitFor(() =>
expect(screen.getByRole('option', {name: 'Home'})).toBeInTheDocument(),
);
expect(input).not.toHaveAttribute('aria-activedescendant');
fireEvent.keyDown(input, {key: 'ArrowDown'});
expect(input).toHaveAttribute(
'aria-activedescendant',
screen.getByRole('option', {name: 'Home'}).id,
);
});
it('calls onOpenChange(false) when Escape is pressed', () => {
const handleOpenChange = vi.fn();
render(
<CommandPalette
isOpen={true}
onOpenChange={handleOpenChange}
searchSource={simpleSource}
/>,
);
const dialog = screen.getByRole('dialog');
const escapeEvent = new KeyboardEvent('keydown', {
key: 'Escape',
bubbles: true,
cancelable: true,
});
dialog.dispatchEvent(escapeEvent);
expect(handleOpenChange).toHaveBeenCalledWith(false);
});
it('lets the topmost nested layer handle Escape before the palette', () => {
const handleOpenChange = vi.fn();
const handleNestedDismiss = vi.fn();
render(
<CommandPalette
isOpen={true}
onOpenChange={handleOpenChange}
searchSource={simpleSource}
input={
<>
<CommandPaletteInput />
<NestedDismissible onDismiss={handleNestedDismiss} />
</>
}
/>,
);
fireEvent.keyDown(screen.getByRole('combobox'), {key: 'Escape'});
expect(handleNestedDismiss).toHaveBeenCalledOnce();
expect(handleOpenChange).not.toHaveBeenCalled();
});
it('an inline preview highlights its value again after a key and a cleared query', async () => {
const user = userEvent.setup();
render(
<CommandPalette
isOpen={true}
isInline
onOpenChange={() => {}}
searchSource={simpleSource}
value="settings"
/>,
);
const input = screen.getByRole('combobox');
const settingsId = async () =>
(await screen.findByRole('option', {name: 'Settings', hidden: true})).id;
await waitFor(async () => {
expect(input.getAttribute('aria-activedescendant')).toBe(
await settingsId(),
);
});
await user.click(input);
// Keys only from here: a press would end the keyboard's hold.
await user.keyboard('{ArrowDown}');
await user.keyboard('h');
await waitFor(() => {
expect(
screen.queryByRole('option', {name: 'Settings', hidden: true}),
).toBeNull();
});
await user.keyboard('{Backspace}');
await waitFor(async () => {
expect(input.getAttribute('aria-activedescendant')).toBe(
await settingsId(),
);
});
});
it('preserves local Escape closing for inline previews', () => {
const handleOpenChange = vi.fn();
render(
<CommandPalette
isOpen={true}
isInline
onOpenChange={handleOpenChange}
searchSource={simpleSource}
/>,
);
fireEvent.keyDown(screen.getByRole('combobox'), {key: 'Escape'});
expect(handleOpenChange).toHaveBeenCalledOnce();
expect(handleOpenChange).toHaveBeenCalledWith(false);
});
it('keeps the empty state mounted while a no-result search is pending', async () => {
// A source whose searches resolve only when we release them, so we can
// observe the render output while a search transition is in flight.
const resolvers: ((items: SearchableItem[]) => void)[] = [];
const source: SearchSource = {
bootstrap: () => [],
async search(): Promise<SearchableItem[]> {
return new Promise<SearchableItem[]>(resolve => {
resolvers.push(resolve);
});
},
};
render(
<CommandPalette
isOpen={true}
onOpenChange={() => {}}
searchSource={source}
emptyBootstrapText="Type to search"
emptySearchText="No results"
/>,
);
const input = screen.getByRole('combobox');
// First search: commits an empty result for query "z".
fireEvent.change(input, {target: {value: 'z'}});
await waitFor(() => expect(resolvers).toHaveLength(1));
resolvers[0]([]);
await waitFor(() =>
expect(screen.getByText('No results')).toBeInTheDocument(),
);
// Second keystroke while already empty: the empty state must remain in the
// DOM for the whole pending window — no unmount/remount flash.
fireEvent.change(input, {target: {value: 'zz'}});
expect(screen.getByText('No results')).toBeInTheDocument();
await waitFor(() => expect(resolvers).toHaveLength(2));
expect(screen.getByText('No results')).toBeInTheDocument();
resolvers[1]([]);
await waitFor(() =>
expect(screen.getByText('No results')).toBeInTheDocument(),
);
});
// component:CommandPaletteEmpty FR2: "no query" is the field's current value.
it('shows no empty text while the first query is pending, then its outcome', async () => {
const resolvers: ((items: SearchableItem[]) => void)[] = [];
const source: SearchSource = {
bootstrap: () => [],
async search(): Promise<SearchableItem[]> {
return new Promise<SearchableItem[]>(resolve => {
resolvers.push(resolve);
});
},
};
render(
<CommandPalette
isOpen={true}
onOpenChange={() => {}}
searchSource={source}
emptyBootstrapText="Type to search"
emptySearchText="No results"
/>,
);
await waitFor(() =>
expect(screen.getByText('Type to search')).toBeInTheDocument(),
);
const input = screen.getByRole('combobox');
fireEvent.change(input, {target: {value: 'ap'}});
await waitFor(() => expect(resolvers).toHaveLength(1));
// Pending: no bootstrap text, no search-empty text; the spinner shows.
expect(screen.queryByText('Type to search')).toBeNull();
expect(screen.queryByText('No results')).toBeNull();
// The Input's spinner is decorative (spec:AST-086 FR8): find it by class.
expect(document.querySelector('.astryx-spinner')).not.toBeNull();
// The result surface keeps the Empty container (so the dialog keeps its
// height), hidden from assistive technology and with no message.
const placeholder = document.querySelector('.astryx-command-palette-empty');
expect(placeholder).not.toBeNull();
expect(placeholder).toHaveAttribute('aria-hidden', 'true');
expect(placeholder?.textContent?.trim()).toBe('');
resolvers[0]([]);
await waitFor(() =>
expect(screen.getByText('No results')).toBeInTheDocument(),
);
expect(screen.queryByText('Type to search')).toBeNull();
});
it('shows the first query results once they arrive, with no empty text before', async () => {
const resolvers: ((items: SearchableItem[]) => void)[] = [];
const source: SearchSource = {
bootstrap: () => [],
async search(): Promise<SearchableItem[]> {
return new Promise<SearchableItem[]>(resolve => {
resolvers.push(resolve);
});
},
};
render(
<CommandPalette
isOpen={true}
onOpenChange={() => {}}
searchSource={source}
emptyBootstrapText="Type to search"
emptySearchText="No results"
/>,
);
const input = screen.getByRole('combobox');
fireEvent.change(input, {target: {value: 'ap'}});
await waitFor(() => expect(resolvers).toHaveLength(1));
expect(screen.queryByText('Type to search')).toBeNull();
resolvers[0]([{id: 'apple', label: 'Apple'}]);
await waitFor(() =>
expect(screen.getByRole('option', {name: /Apple/})).toBeInTheDocument(),
);
expect(screen.queryByText('No results')).toBeNull();
});
it('brings the bootstrap text back when the field is cleared', async () => {
const resolvers: ((items: SearchableItem[]) => void)[] = [];
const source: SearchSource = {
bootstrap: () => [],
async search(): Promise<SearchableItem[]> {
return new Promise<SearchableItem[]>(resolve => {
resolvers.push(resolve);
});
},
};
render(
<CommandPalette
isOpen={true}
onOpenChange={() => {}}
searchSource={source}
emptyBootstrapText="Type to search"
emptySearchText="No results"
/>,
);
const input = screen.getByRole('combobox');
fireEvent.change(input, {target: {value: 'zq'}});
await waitFor(() => expect(resolvers).toHaveLength(1));
resolvers[0]([]);
await waitFor(() =>
expect(screen.getByText('No results')).toBeInTheDocument(),
);
fireEvent.change(input, {target: {value: ''}});
await waitFor(() =>
expect(screen.getByText('Type to search')).toBeInTheDocument(),
);
expect(screen.queryByText('No results')).toBeNull();
});
it('discards a search response that resolves after the palette closed', async () => {
// A source whose search resolves only when released, and no cancel()
// implementation — closing the palette must invalidate the request itself.
const resolvers: ((items: SearchableItem[]) => void)[] = [];
const source: SearchSource = {
bootstrap: () => [],
async search(): Promise<SearchableItem[]> {
return new Promise<SearchableItem[]>(resolve => {
resolvers.push(resolve);
});
},
};
function Harness() {
const [isOpen, setIsOpen] = useState(true);
return (
<CommandPalette
isOpen={isOpen}
onOpenChange={setIsOpen}
searchSource={source}
/>
);
}
render(<Harness />);
const input = screen.getByRole('combobox');
fireEvent.change(input, {target: {value: 'a'}});
await waitFor(() => expect(resolvers).toHaveLength(1));
// Close while the search is still in flight.
const dialog = screen.getByRole('dialog');
const escapeEvent = new KeyboardEvent('keydown', {
key: 'Escape',
bubbles: true,
cancelable: true,
});
dialog.dispatchEvent(escapeEvent);
await waitFor(() =>
expect(screen.getByRole('dialog', {hidden: true})).not.toHaveAttribute(
'open',
),
);
// The stale response arrives after close — it must not re-commit the
// abandoned query/results into the closed palette.
await act(async () => {
resolvers[0]([{id: 'stale', label: 'Stale item'}]);
});
expect(screen.getByRole('combobox', {hidden: true})).toHaveValue('');
expect(screen.queryByText('Stale item')).not.toBeInTheDocument();
});
it('does not move the highlight while typing in the search input', async () => {
// The palette's input already filters; letting the shared combobox
// typeahead also chase prefixes would drag the highlight — and Enter —
// onto a command the user never picked.
const gitSource = createStaticSource([
{id: 'git-add', label: 'git add'},
{id: 'git-commit', label: 'git commit'},
{id: 'git-push', label: 'git push'},
]);
render(
<CommandPalette
isOpen={true}
onOpenChange={() => {}}
searchSource={gitSource}
/>,
);
const input = screen.getByRole('combobox');
await waitFor(() =>
expect(screen.getByText('git add')).toBeInTheDocument(),
);
fireEvent.keyDown(input, {key: 'g'});
fireEvent.keyDown(input, {key: 'i'});
fireEvent.keyDown(input, {key: 't'});
expect(input).not.toHaveAttribute('aria-activedescendant');
});
it('keeps Home and End on the query field and uses Page keys for results', async () => {
const user = userEvent.setup();
const handleOpenChange = vi.fn();
const handleValueChange = vi.fn();
render(
<CommandPalette
isOpen={true}
onOpenChange={handleOpenChange}
onValueChange={handleValueChange}
searchSource={simpleSource}
/>,
);
const input = screen.getByRole<HTMLInputElement>('combobox');
await waitFor(() =>
expect(screen.getByText('Settings')).toBeInTheDocument(),
);
await user.click(input);
await user.type(input, 'e');
await waitFor(() =>
expect(screen.getByText('Settings')).toBeInTheDocument(),
);
const homeOption = screen.getByText('Home').closest('[role="option"]');
const settingsOption = screen
.getByText('Settings')
.closest('[role="option"]');
expect(input).toHaveValue('e');
expect(input.selectionStart).toBe(1);
await user.keyboard('{Home}');
expect(input.selectionStart).toBe(0);
await user.keyboard('{End}');
expect(input.selectionStart).toBe(1);
expect(input).not.toHaveAttribute('aria-activedescendant');
await user.keyboard('{PageDown}');
expect(input.getAttribute('aria-activedescendant')).toBe(
settingsOption?.id,
);
await user.keyboard('{PageUp}');
expect(input.getAttribute('aria-activedescendant')).toBe(homeOption?.id);
await user.keyboard('{Enter}');
expect(handleValueChange).toHaveBeenCalledWith('home');
expect(handleOpenChange).toHaveBeenCalledWith(false);
});
it('highlights on hover without scrolling and scrolls once per key (#6077)', async () => {
// Hover must be handled by the root's delegated list handler (routed to
// useCombobox's hover-aware path), and the shared useHighlightedOptionScroll effect
// must be the single keyboard scroll owner. Calling the raw setter on
// hover kept the stationary-pointer runaway path alive, and the item's
// own scrollIntoView effect doubled every scroll call.
const scrollIntoView = vi.fn();
Object.defineProperty(HTMLElement.prototype, 'scrollIntoView', {
configurable: true,
value: scrollIntoView,
});
try {
render(
<CommandPalette
isOpen={true}
onOpenChange={() => {}}
searchSource={simpleSource}
/>,
);
const input = screen.getByRole('combobox');
await waitFor(() => expect(screen.getByText('Home')).toBeInTheDocument());
const home = screen.getByText('Home');
const settings = screen.getByText('Settings');
fireEvent.mouseOver(home);
expect(scrollIntoView).not.toHaveBeenCalled();
expect(input.getAttribute('aria-activedescendant')).toBe(
home.closest('[role="option"]')?.id,
);
// Moving between siblings does not re-enter the list container. Include
// relatedTarget so the test exercises actual within-list transitions.
fireEvent.mouseOut(home, {relatedTarget: settings});
fireEvent.mouseOver(settings, {relatedTarget: home});
expect(input.getAttribute('aria-activedescendant')).toBe(
settings.closest('[role="option"]')?.id,
);
expect(scrollIntoView).not.toHaveBeenCalled();
fireEvent.mouseOut(settings, {relatedTarget: home});
fireEvent.mouseOver(home, {relatedTarget: settings});
expect(input.getAttribute('aria-activedescendant')).toBe(
home.closest('[role="option"]')?.id,
);
expect(scrollIntoView).not.toHaveBeenCalled();
fireEvent.keyDown(input, {key: 'ArrowDown'});
await waitFor(() => expect(scrollIntoView).toHaveBeenCalledTimes(1));
expect(input.getAttribute('aria-activedescendant')).toBe(
settings.closest('[role="option"]')?.id,
);
fireEvent.keyDown(input, {key: 'ArrowUp'});
await waitFor(() => expect(scrollIntoView).toHaveBeenCalledTimes(2));
} finally {
delete (HTMLElement.prototype as unknown as {scrollIntoView?: unknown})
.scrollIntoView;
}
});
describe('a rejected search source', () => {
const spinner = () => document.querySelector('.astryx-spinner');
const renderInsideBoundary = (source: SearchSource) =>
render(
<TestErrorBoundary>
<CommandPalette
isOpen={true}
onOpenChange={() => {}}
searchSource={source}
emptyBootstrapText="Type to search"
emptySearchText="No results"
/>
</TestErrorBoundary>,
);
it('keeps the palette open with no results when bootstrap rejects', async () => {
let rejectBootstrap: (error: Error) => void = () => {};
renderInsideBoundary({
bootstrap: async () =>
new Promise<SearchableItem[]>((_, reject) => {
rejectBootstrap = reject;
}),
search: () => [],
});
await act(async () => {
rejectBootstrap(new Error('offline'));
});
expect(screen.queryByText('Boundary fallback')).not.toBeInTheDocument();
expect(screen.getByRole('combobox')).toBeInTheDocument();
expect(screen.getByText('Type to search')).toBeInTheDocument();
expect(spinner()).not.toBeInTheDocument();
});
it('clears the results and ends the busy state when a search rejects', async () => {
const rejecters: ((error: Error) => void)[] = [];
renderInsideBoundary({
bootstrap: () => [{id: 'home', label: 'Home'}],
search: async () =>
new Promise<SearchableItem[]>((_, reject) => {
rejecters.push(reject);
}),
});
await screen.findByText('Home');
const input = screen.getByRole('combobox');
fireEvent.change(input, {target: {value: 'h'}});
await waitFor(() => expect(rejecters).toHaveLength(1));
await act(async () => {
rejecters[0](new Error('offline'));
});
expect(screen.queryByText('Boundary fallback')).not.toBeInTheDocument();
expect(screen.getByRole('combobox')).toHaveValue('h');
expect(screen.queryByText('Home')).not.toBeInTheDocument();
expect(screen.getByText('No results')).toBeInTheDocument();
expect(spinner()).not.toBeInTheDocument();
});
it('clears the results and ends the busy state when a search throws synchronously', async () => {
renderInsideBoundary({
bootstrap: () => [{id: 'home', label: 'Home'}],
search: () => {
throw new Error('offline');
},
});
await screen.findByText('Home');
await act(async () => {
fireEvent.change(screen.getByRole('combobox'), {
target: {value: 'h'},
});
});
expect(screen.queryByText('Boundary fallback')).not.toBeInTheDocument();
expect(screen.getByRole('combobox')).toHaveValue('h');
expect(screen.queryByText('Home')).not.toBeInTheDocument();
expect(screen.getByText('No results')).toBeInTheDocument();
expect(spinner()).not.toBeInTheDocument();
});
it('ignores a rejection from a superseded query', async () => {
const pending = new Map<
string,
{
resolve: (items: SearchableItem[]) => void;
reject: (error: Error) => void;
}
>();
renderInsideBoundary({
bootstrap: () => [],
search: async query =>
new Promise<SearchableItem[]>((resolve, reject) => {
pending.set(query, {resolve, reject});
}),
});
const input = screen.getByRole('combobox');
fireEvent.change(input, {target: {value: 'a'}});
await waitFor(() => expect(pending.has('a')).toBe(true));
fireEvent.change(input, {target: {value: 'ab'}});
await waitFor(() => expect(pending.has('ab')).toBe(true));
await act(async () => {
pending.get('ab')?.resolve([{id: 'about', label: 'About'}]);
});
await act(async () => {
pending.get('a')?.reject(new Error('aborted'));
});
expect(screen.queryByText('Boundary fallback')).not.toBeInTheDocument();
expect(await screen.findByText('About')).toBeInTheDocument();
expect(screen.getByRole('combobox')).toHaveValue('ab');
expect(screen.queryByText('No results')).not.toBeInTheDocument();
expect(spinner()).not.toBeInTheDocument();
});
});
describe('screen reader announcements', () => {
const politeRegion = () =>
document.querySelector('[data-astryx-live-region="polite"]');
it('announces the result count politely after typing a query', async () => {
render(
<CommandPalette
isOpen={true}
onOpenChange={() => {}}
searchSource={simpleSource}
/>,
);
await waitFor(() => expect(screen.getByText('Home')).toBeInTheDocument());
// "e" matches both Home and Settings.
fireEvent.change(screen.getByRole('combobox'), {target: {value: 'e'}});
await waitFor(() => {
expect(politeRegion()).toHaveTextContent('2 results');
});
});
it('announces the singular form when one item matches', async () => {
render(
<CommandPalette
isOpen={true}
onOpenChange={() => {}}
searchSource={simpleSource}
/>,
);
await waitFor(() => expect(screen.getByText('Home')).toBeInTheDocument());
// "set" matches only Settings. Anchored so it cannot pass on "1 results".
fireEvent.change(screen.getByRole('combobox'), {target: {value: 'set'}});
await waitFor(() => {
expect(politeRegion()).toHaveTextContent(/^1 result$/);
});
});
it('announces the rendered default empty state when nothing matches', async () => {
render(
<CommandPalette
isOpen={true}
onOpenChange={() => {}}
searchSource={simpleSource}
/>,
);
await waitFor(() => expect(screen.getByText('Home')).toBeInTheDocument());
fireEvent.change(screen.getByRole('combobox'), {target: {value: 'zzz'}});
await waitFor(() => {
expect(politeRegion()).toHaveTextContent(/^No results$/);
});
});
it('announces rich emptySearchText exactly as rendered', async () => {
render(
<CommandPalette
isOpen={true}
onOpenChange={() => {}}
searchSource={simpleSource}
emptySearchText={
<span>
Nothing like that here. <a href="/commands/new">Add a command</a>
</span>
}
/>,
);
await waitFor(() => expect(screen.getByText('Home')).toBeInTheDocument());
fireEvent.change(screen.getByRole('combobox'), {target: {value: 'zzz'}});
expect(
await screen.findByRole('link', {name: 'Add a command'}),
).toHaveAttribute('href', '/commands/new');
await waitFor(() => {
expect(politeRegion()).toHaveTextContent(
/^Nothing like that here\. Add a command$/,
);
});
});
it('waits for a narrowed search to settle before announcing no results', async () => {
const resolvers: ((items: SearchableItem[]) => void)[] = [];
const source: SearchSource = {
bootstrap: () => [
{id: 'home', label: 'Home'},
{id: 'settings', label: 'Settings'},
],
async search(): Promise<SearchableItem[]> {
return new Promise<SearchableItem[]>(resolve => {
resolvers.push(resolve);
});
},
};
const spoken: string[] = [];
const observer = new MutationObserver(() => {
const text = politeRegion()?.textContent ?? '';
if (text !== '' && spoken.at(-1) !== text) {
spoken.push(text);
}
});
observer.observe(document.body, {
childList: true,
subtree: true,
characterData: true,
});
try {
render(
<CommandPalette
isOpen={true}
onOpenChange={() => {}}
searchSource={source}
/>,
);
await waitFor(() =>
expect(screen.getByText('Home')).toBeInTheDocument(),
);
const input = screen.getByRole('combobox');
fireEvent.change(input, {target: {value: 'e'}});
await act(async () =>
resolvers.shift()?.(source.bootstrap() as SearchableItem[]),
);
await waitFor(() => expect(spoken.at(-1)).toBe('2 results'));
// Optimistic narrowing empties the list while the source is still
// answering; the source then finds one match.
fireEvent.change(input, {target: {value: 'ez'}});
await act(async () => {
await new Promise(resolve => setTimeout(resolve, 50));
});
await act(async () =>
resolvers.shift()?.([{id: 'settings', label: 'Settings'}]),
);
await waitFor(() => expect(spoken.at(-1)).toBe('1 result'));
expect(spoken).not.toContain('No results');
} finally {
observer.disconnect();
}
});
it('announces loading politely while a search is in flight', async () => {
// A source whose searches never resolve, so the palette stays busy and
// only the loading announcement can reach the live region.
const source: SearchSource = {
bootstrap: () => [],
async search(): Promise<SearchableItem[]> {
return new Promise<SearchableItem[]>(() => {});
},
};
render(
<CommandPalette
isOpen={true}
onOpenChange={() => {}}
searchSource={source}
/>,
);
fireEvent.change(screen.getByRole('combobox'), {target: {value: 'z'}});
await waitFor(() => {
expect(politeRegion()).toHaveTextContent('Loading');
});
});
it('announces no result count on initial open (bootstrap)', async () => {
render(
<CommandPalette
isOpen={true}
onOpenChange={() => {}}
searchSource={simpleSource}
/>,
);
await waitFor(() => expect(screen.getByText('Home')).toBeInTheDocument());
// Flush effects and any pending live-region rAF writes.
await act(async () => {
await new Promise(resolve => setTimeout(resolve, 50));
});
// The bootstrap's busy start may say "Loading" (spec:AST-086 FR3, FR8);
// its results are never counted aloud.
expect(['', 'Loading']).toContain(politeRegion()?.textContent ?? '');
});
});
});
// Tab from the last tabbable control wraps to the first and Shift+Tab from the
// first wraps to the last, so focus never leaves the modal for the browser's
// own UI.
function expectTabWrapsInside(modal: HTMLElement) {
const tabbables = getFocusableElements(modal);
expect(tabbables.length).toBeGreaterThan(0);
const first = tabbables[0];
const last = tabbables[tabbables.length - 1];
last.focus();
expect(last).toHaveFocus();
expect(fireEvent.keyDown(last, {key: 'Tab'})).toBe(false);
expect(first).toHaveFocus();
expect(fireEvent.keyDown(first, {key: 'Tab', shiftKey: true})).toBe(false);
expect(last).toHaveFocus();
}
describe('CommandPalette focus region (Dialog DEC-2)', () => {
it('keeps Tab inside the open palette', () => {
render(
<CommandPalette
isOpen
onOpenChange={() => {}}
searchSource={simpleSource}
/>,
);
expectTabWrapsInside(document.querySelector('dialog') as HTMLElement);
});
});