Skip to content

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

TypeScript

fix(Tokenizer): an open list reloads when the tokens change (#9416)

Cindy Zhang346a3c330f44
diff --git a/.changeset/typeahead-open-list-replaced-source.md b/.changeset/typeahead-open-list-replaced-source.md
new file mode 100644
index 0000000000..c1a9bb918a
--- /dev/null
+++ b/.changeset/typeahead-open-list-replaced-source.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] `Tokenizer`: an open list reloads when the tokens change, so it shows current choices instead of the old ones — a token removed with its button is offered again, and a value set from outside is no longer listed.
+
+@cixzhang
diff --git a/packages/core/src/Tokenizer/Tokenizer.test.tsx b/packages/core/src/Tokenizer/Tokenizer.test.tsx
index 14b6704d5c..3fe4e08a90 100644
--- a/packages/core/src/Tokenizer/Tokenizer.test.tsx
+++ b/packages/core/src/Tokenizer/Tokenizer.test.tsx
@@ -1212,6 +1212,311 @@ describe('Tokenizer', () => {
});
});
+ // After the tokens change, the list the field shows is the current one
+ // (spec:AST-092 FR4; component:Tokenizer FR13, FR15). Each row is one
+ // situation from the state table in the pull request: the list open or
+ // closed, a focus list or typed text, a typed search waiting for its
+ // debounce, a reload that is slow or fails, a token added or removed from
+ // inside or outside, and the limit.
+ describe('list after the tokens change', () => {
+ const slowSource: SearchSource = {
+ search: async query =>
+ users.filter(u => u.label.toLowerCase().includes(query.toLowerCase())),
+ bootstrap: async () => {
+ await new Promise(resolve => setTimeout(resolve, 200));
+ return users.slice(0, 3);
+ },
+ };
+ function failsOnReload(): SearchSource {
+ let calls = 0;
+ return {
+ search: userSource.search,
+ bootstrap: async () => {
+ calls += 1;
+ if (calls > 1) {
+ throw new Error('offline');
+ }
+ return users.slice(0, 3);
+ },
+ };
+ }
+
+ function Controlled({
+ initial,
+ maxEntries,
+ source = userSource,
+ }: {
+ initial: SearchableItem[];
+ maxEntries?: number;
+ source?: SearchSource;
+ }) {
+ const [value, setValue] = useState(initial);
+ return (
+ <>
+ <Tokenizer
+ label="Members"
+ searchSource={source}
+ value={value}
+ onChange={setValue}
+ hasEntriesOnFocus
+ maxEntries={maxEntries}
+ />
+ <button type="button" onClick={() => setValue([users[2]])}>
+ Set Charlie
+ </button>
+ <button type="button" onClick={() => setValue([users[0]])}>
+ Set Alice
+ </button>
+ <button
+ type="button"
+ onClick={() => setValue([users[0], users[1], users[2]])}>
+ Set all three
+ </button>
+ </>
+ );
+ }
+
+ // Steps: `open` (click the field and wait for its list), `type:<text>`
+ // (type without waiting for the debounce), `listed:<name>` (wait until
+ // listed), `noResults` (wait for the empty-search message), `escape`,
+ // `set:<button>` (a value set from outside, focus stays in the field),
+ // `remove:<name>` (the token's remove button), `pick:<name>` (choose an
+ // option), `absent:<name>` (not listed right now).
+ type Row = {
+ situation: string;
+ initial: SearchableItem[];
+ maxEntries?: number;
+ source?: () => SearchSource;
+ steps: string[];
+ expanded: boolean;
+ listed?: string[];
+ notListed?: string[];
+ };
+ const rows: Row[] = [
+ {
+ situation:
+ 'focus list open, outside adds a token, choices remain: reload',
+ initial: [users[0]],
+ steps: ['open', 'listed:Charlie', 'set:Set Charlie', 'listed:Alice'],
+ expanded: true,
+ listed: ['Alice', 'Bob'],
+ notListed: ['Charlie'],
+ },
+ {
+ situation: 'focus list open, outside commits its last row: close',
+ initial: [users[0], users[1]],
+ steps: ['open', 'listed:Charlie', 'set:Set all three'],
+ expanded: false,
+ },
+ {
+ situation: 'focus list open, token removed with its button: reload',
+ initial: [users[0], users[1]],
+ steps: ['open', 'escape', 'remove:Alice', 'listed:Alice'],
+ expanded: true,
+ listed: ['Alice', 'Charlie'],
+ },
+ {
+ situation: 'focus list closed, outside change: stays closed',
+ initial: [users[0]],
+ steps: ['open', 'escape', 'set:Set Charlie'],
+ expanded: false,
+ },
+ {
+ situation: 'token picked from the list (inside add): closes, no reopen',
+ initial: [users[0]],
+ steps: ['open', 'listed:Charlie', 'pick:Charlie'],
+ expanded: false,
+ },
+ {
+ situation: 'focus list open, slow reload: new token never listed',
+ initial: [users[0]],
+ source: () => slowSource,
+ steps: [
+ 'open',
+ 'listed:Charlie',
+ 'set:Set Charlie',
+ 'absent:Charlie',
+ 'listed:Alice',
+ ],
+ expanded: true,
+ notListed: ['Charlie'],
+ },
+ {
+ situation: 'focus list open, reload fails: close',
+ initial: [users[0]],
+ source: failsOnReload,
+ steps: ['open', 'listed:Charlie', 'set:Set Charlie'],
+ expanded: false,
+ },
+ {
+ situation: 'typed text, limit reached from outside: close',
+ initial: [users[0]],
+ maxEntries: 3,
+ steps: ['type:i', 'listed:Diana', 'set:Set all three'],
+ expanded: false,
+ },
+ {
+ situation: 'typed text matched only a token, token removed: re-search',
+ initial: [users[0], users[1]],
+ steps: ['type:ali', 'noResults', 'set:Set Charlie', 'listed:Alice'],
+ expanded: true,
+ listed: ['Alice'],
+ },
+ {
+ situation:
+ 'typed text, tokens return to a set that once emptied the list: re-search',
+ initial: [users[0], users[1]],
+ steps: [
+ 'open',
+ 'listed:Charlie',
+ 'set:Set all three',
+ 'set:Set Alice',
+ 'type:i',
+ 'listed:Diana',
+ 'set:Set all three',
+ 'listed:Diana',
+ ],
+ expanded: true,
+ listed: ['Diana'],
+ notListed: ['Charlie'],
+ },
+ {
+ situation:
+ 'typed search waiting for its debounce, outside commit: re-search',
+ initial: [users[0]],
+ steps: ['type:char', 'set:Set Charlie', 'absent:Charlie'],
+ expanded: true,
+ notListed: ['Charlie'],
+ },
+ {
+ situation:
+ 'typed search waiting for its debounce, commit empties the shown rows: re-search',
+ initial: [users[0], users[1]],
+ steps: [
+ 'open',
+ 'listed:Charlie',
+ 'type:d',
+ 'set:Set all three',
+ 'listed:Diana',
+ ],
+ expanded: true,
+ listed: ['Diana'],
+ },
+ ];
+
+ it.each(rows)('$situation', async row => {
+ const user = userEvent.setup();
+ render(
+ <Controlled
+ initial={row.initial}
+ maxEntries={row.maxEntries}
+ source={row.source?.()}
+ />,
+ );
+ const input = screen.getByRole('combobox');
+ const option = (name: string) =>
+ screen.queryByRole('option', {name, hidden: true});
+ for (const step of row.steps) {
+ const [action, arg = ''] = step.split(/:(.*)/s);
+ if (action === 'open') {
+ await user.click(input);
+ await waitFor(() => {
+ expect(input).toHaveAttribute('aria-expanded', 'true');
+ });
+ } else if (action === 'type') {
+ await user.type(input, arg);
+ } else if (action === 'listed') {
+ await waitFor(() => {
+ expect(option(arg)).toBeInTheDocument();
+ });
+ } else if (action === 'noResults') {
+ await waitFor(() => {
+ expect(screen.getByText('No results found')).toBeInTheDocument();
+ });
+ } else if (action === 'escape') {
+ await user.keyboard('{Escape}');
+ } else if (action === 'set') {
+ act(() => {
+ screen.getByRole('button', {name: arg}).click();
+ });
+ } else if (action === 'remove') {
+ await user.click(screen.getByRole('button', {name: `Remove ${arg}`}));
+ } else if (action === 'pick') {
+ await user.click(
+ screen.getByRole('option', {name: arg, hidden: true}),
+ );
+ } else if (action === 'absent') {
+ expect(option(arg)).not.toBeInTheDocument();
+ } else {
+ throw new Error(`Unknown step: ${step}`);
+ }
+ }
+ // Let any reload or debounced search settle.
+ await act(async () => {
+ await new Promise(resolve => setTimeout(resolve, 300));
+ });
+
+ expect(input).toHaveAttribute(
+ 'aria-expanded',
+ row.expanded ? 'true' : 'false',
+ );
+ for (const name of row.listed ?? []) {
+ expect(option(name)).toBeInTheDocument();
+ }
+ for (const name of row.notListed ?? []) {
+ expect(option(name)).not.toBeInTheDocument();
+ }
+ });
+
+ it('never shows a value set from outside while an async reload is pending', async () => {
+ const user = userEvent.setup();
+ // Whether each commit after the change painted Charlie as a choice.
+ const commitsListingCharlie: boolean[] = [];
+ let isWatching = false;
+ render(
+ <Profiler
+ id="tokenizer"
+ onRender={() => {
+ if (isWatching) {
+ commitsListingCharlie.push(
+ Array.from(document.querySelectorAll('[role="option"]')).some(
+ option => option.textContent?.includes('Charlie'),
+ ),
+ );
+ }
+ }}>
+ <Controlled initial={[users[0]]} source={slowSource} />
+ </Profiler>,
+ );
+ const input = screen.getByRole('combobox');
+
+ await user.click(input);
+ await waitFor(() => {
+ expect(
+ screen.getByRole('option', {name: 'Charlie', hidden: true}),
+ ).toBeInTheDocument();
+ });
+ isWatching = true;
+ act(() => {
+ screen.getByRole('button', {name: 'Set Charlie'}).click();
+ });
+ isWatching = false;
+
+ // No commit, not even the one that adds the token, lists Charlie.
+ expect(commitsListingCharlie.length).toBeGreaterThan(0);
+ expect(commitsListingCharlie).not.toContain(true);
+ expect(
+ screen.queryByRole('option', {name: 'Charlie', hidden: true}),
+ ).not.toBeInTheDocument();
+ expect(input).toHaveAttribute('aria-expanded', 'true');
+ await waitFor(() => {
+ expect(
+ screen.getByRole('option', {name: 'Alice', hidden: true}),
+ ).toBeInTheDocument();
+ });
+ });
+ });
+
describe('paste behavior', () => {
it('pasting text triggers search results like typing', async () => {
const user = userEvent.setup();
diff --git a/packages/core/src/Tokenizer/Tokenizer.tsx b/packages/core/src/Tokenizer/Tokenizer.tsx
index 010ae52e18..9116c3bbcf 100644
--- a/packages/core/src/Tokenizer/Tokenizer.tsx
+++ b/packages/core/src/Tokenizer/Tokenizer.tsx
@@ -47,6 +47,7 @@ import {
type BusyIndicatorLane,
} from '../Typeahead/busyIndicatorLane';
import {TrailingKeyDownContext} from '../Typeahead/trailingKeyDown';
+import {CommittedChoicesKeyContext} from '../Typeahead/committedChoicesKey';
import {
type FieldInputBaseProps,
useFieldInputStyling,
@@ -1095,11 +1096,24 @@ export function Tokenizer<T extends SearchableItem>({
const isAtMax = maxEntries != null && value.length >= maxEntries;
- // Filter out already-selected items from search results
- const selectedIds = useMemo(
- () => new Set(value.map(item => item.id)),
+ // Filter out already-selected items from search results. Keyed by the ids,
+ // not the array: an equal new `value` array on every render keeps the
+ // filtered source, and the key tells an open list to reload only when the
+ // committed values really change (FR13).
+ const selectedIdKey = useMemo(
+ () => JSON.stringify(value.map(item => item.id)),
[value],
);
+ const selectedIds = useMemo(
+ () => new Set<string>(JSON.parse(selectedIdKey) as string[]),
+ [selectedIdKey],
+ );
+ // Tells an open list to reload when the committed values change, or to
+ // close once they reach the limit (FR13, FR15).
+ const committedChoices = useMemo(
+ () => ({key: selectedIdKey, ids: selectedIds, isAtLimit: isAtMax}),
+ [selectedIdKey, selectedIds, isAtMax],
+ );
// Selected labels, lowercased, for the Create entry's duplicate check. The
// typed text is a label, not an id: real selections usually carry an opaque
@@ -1424,68 +1438,70 @@ export function Tokenizer<T extends SearchableItem>({
button rather than as a second one inside the base. */}
<BusyIndicatorLaneProvider value={busyLane}>
<TrailingKeyDownContext value={onKeyDown}>
- <BaseTypeahead
- {...rest}
- ref={useMergedRefs(
- inputRef,
- // With `experimental`, the ref type admits the trigger too; in
- // this presentation it receives the input.
- ref as React.Ref<HTMLInputElement> | undefined,
- handOffFocusRef,
- )}
- searchSource={isAtMax ? emptySource : filteredSource}
- value={null}
- onChange={handleAdd}
- renderItem={renderItem}
- // A space keeps :placeholder-shown available as the CSS-only empty
- // query signal without painting placeholder text beside tokens.
- placeholder={value.length === 0 ? placeholder : ' '}
- hasEntriesOnFocus={isAtMax ? false : hasEntriesOnFocus}
- maxMenuItems={maxMenuItems}
- menuWidth={menuWidth}
- minQueryLength={minQueryLength}
- emptySearchText={emptySearchText}
- isDisabled={isDisabled}
- // A disabled field keeps its tab stop (spec:AST-085 FR1), except in
- // unfocusedLayer mode, where the input lives in a layer a disabled
- // field never opens; how that field takes focus is undecided.
- isFocusableDisabled={
- showsDisabledMessage || (isDisabled && !isLayerMode)
- }
- hasAutoFocus={hasAutoFocus}
- inputId={inputId}
- ariaLabelledBy={fieldLabelledBy}
- ariaDescribedBy={
- [ariaDescribedByProp, ariaDescribedBy]
- .filter(Boolean)
- .join(' ') || undefined
- }
- onChangeQuery={onChangeQuery}
- // The resolved required state reaches the combobox, also when a
- // FormLayout default hides the visible marker (component:FormLayout
- // FR5, AR2).
- aria-required={isEffectivelyRequired || rest['aria-required']}
- // An error status is exposed on the combobox as on every other field
- // (WCAG 4.1.2; spec:AST-020 FR9). Without one, a caller's own
- // aria-required / aria-invalid still applies.
- aria-invalid={status?.type === 'error' || rest['aria-invalid']}
- __queryEntries={createEntries}
- debounceMs={debounceMs}
- onKeyDown={handleKeyDown}
- anchorRef={wrapperRef}
- size={size}
- inputXStyle={[
- isAtMax || isTruncated
- ? styles.inputAtMax
- : value.length > 0
- ? styles.inputCompact
- : undefined,
- // With tokens, wrapperWithTokens reserves the lane for every row.
- // This rule is only for an empty Tokenizer; it still resolves to
- // zero until the lane publishes a width.
- !(isAtMax || isTruncated || value.length > 0) && laneReserve,
- ]}
- />
+ <CommittedChoicesKeyContext value={committedChoices}>
+ <BaseTypeahead
+ {...rest}
+ ref={useMergedRefs(
+ inputRef,
+ // With `experimental`, the ref type admits the trigger too; in
+ // this presentation it receives the input.
+ ref as React.Ref<HTMLInputElement> | undefined,
+ handOffFocusRef,
+ )}
+ searchSource={isAtMax ? emptySource : filteredSource}
+ value={null}
+ onChange={handleAdd}
+ renderItem={renderItem}
+ // A space keeps :placeholder-shown available as the CSS-only empty
+ // query signal without painting placeholder text beside tokens.
+ placeholder={value.length === 0 ? placeholder : ' '}
+ hasEntriesOnFocus={isAtMax ? false : hasEntriesOnFocus}
+ maxMenuItems={maxMenuItems}
+ menuWidth={menuWidth}
+ minQueryLength={minQueryLength}
+ emptySearchText={emptySearchText}
+ isDisabled={isDisabled}
+ // A disabled field keeps its tab stop (spec:AST-085 FR1), except in
+ // unfocusedLayer mode, where the input lives in a layer a disabled
+ // field never opens; how that field takes focus is undecided.
+ isFocusableDisabled={
+ showsDisabledMessage || (isDisabled && !isLayerMode)
+ }
+ hasAutoFocus={hasAutoFocus}
+ inputId={inputId}
+ ariaLabelledBy={fieldLabelledBy}
+ ariaDescribedBy={
+ [ariaDescribedByProp, ariaDescribedBy]
+ .filter(Boolean)
+ .join(' ') || undefined
+ }
+ onChangeQuery={onChangeQuery}
+ // The resolved required state reaches the combobox, also when a
+ // FormLayout default hides the visible marker (component:FormLayout
+ // FR5, AR2).
+ aria-required={isEffectivelyRequired || rest['aria-required']}
+ // An error status is exposed on the combobox as on every other field
+ // (WCAG 4.1.2; spec:AST-020 FR9). Without one, a caller's own
+ // aria-required / aria-invalid still applies.
+ aria-invalid={status?.type === 'error' || rest['aria-invalid']}
+ __queryEntries={createEntries}
+ debounceMs={debounceMs}
+ onKeyDown={handleKeyDown}
+ anchorRef={wrapperRef}
+ size={size}
+ inputXStyle={[
+ isAtMax || isTruncated
+ ? styles.inputAtMax
+ : value.length > 0
+ ? styles.inputCompact
+ : undefined,
+ // With tokens, wrapperWithTokens reserves the lane for every row.
+ // This rule is only for an empty Tokenizer; it still resolves to
+ // zero until the lane publishes a width.
+ !(isAtMax || isTruncated || value.length > 0) && laneReserve,
+ ]}
+ />
+ </CommittedChoicesKeyContext>
</TrailingKeyDownContext>
</BusyIndicatorLaneProvider>
{htmlName != null &&
diff --git a/packages/core/src/Typeahead/BaseTypeahead.test.tsx b/packages/core/src/Typeahead/BaseTypeahead.test.tsx
index a1179af5e7..e51aa558b4 100644
--- a/packages/core/src/Typeahead/BaseTypeahead.test.tsx
+++ b/packages/core/src/Typeahead/BaseTypeahead.test.tsx
@@ -28,6 +28,7 @@ import {
import userEvent from '@testing-library/user-event';
import * as stylex from '@stylexjs/stylex';
import {BaseTypeahead} from './BaseTypeahead';
+import {CommittedChoicesKeyContext} from './committedChoicesKey';
import {Typeahead} from './Typeahead';
import {Tokenizer} from '../Tokenizer';
import {InternationalizationProvider} from '../i18n';
@@ -382,6 +383,217 @@ describe('BaseTypeahead', () => {
).not.toBeInTheDocument();
});
+ // component:Tokenizer FR13, spec:AST-092 FR4: when the caller's committed
+ // values change, an open list reloads from the source they now filter.
+ describe('committed values change', () => {
+ const COMMITTED: Record<
+ string,
+ {key: string; ids: ReadonlySet<string>; isAtLimit: boolean}
+ > = {
+ a: {key: 'a', ids: new Set(), isAtLimit: false},
+ b: {key: 'b', ids: new Set(), isAtLimit: false},
+ };
+ const renderField = (
+ searchSource: SearchSource<SearchableItem>,
+ key: 'a' | 'b',
+ props: {hasEntriesOnFocus?: boolean} = {hasEntriesOnFocus: true},
+ ) => (
+ <CommittedChoicesKeyContext value={COMMITTED[key]}>
+ <BaseTypeahead
+ searchSource={searchSource}
+ value={null}
+ onChange={() => {}}
+ {...props}
+ />
+ </CommittedChoicesKeyContext>
+ );
+
+ it('reloads an open focus list', async () => {
+ const user = userEvent.setup();
+ const updatedBootstrap = vi.fn(() => [
+ {id: '2', label: 'Updated result'},
+ ]);
+ const {rerender} = render(
+ renderField({search: () => [], bootstrap: () => [resultItem]}, 'a'),
+ );
+ const input = screen.getByRole('combobox');
+
+ await user.click(input);
+ await waitFor(() => {
+ expect(
+ screen.getByRole('option', {name: 'Result', hidden: true}),
+ ).toBeInTheDocument();
+ });
+ rerender(
+ renderField({search: () => [], bootstrap: updatedBootstrap}, 'b'),
+ );
+
+ await waitFor(() => {
+ expect(
+ screen.getByRole('option', {name: 'Updated result', hidden: true}),
+ ).toBeInTheDocument();
+ });
+ expect(input).toHaveAttribute('aria-expanded', 'true');
+ expect(
+ screen.queryByRole('option', {name: 'Result', hidden: true}),
+ ).not.toBeInTheDocument();
+ expect(updatedBootstrap).toHaveBeenCalledTimes(1);
+ });
+
+ it('searches again for the typed query while the list is open', async () => {
+ const user = userEvent.setup();
+ const updatedSearch = vi.fn(() => [{id: '2', label: 'Updated result'}]);
+ const {rerender} = render(
+ renderField({search: () => [resultItem], bootstrap: () => []}, 'a', {}),
+ );
+ const input = screen.getByRole('combobox');
+
+ await user.type(input, 're');
+ await waitFor(() => {
+ expect(
+ screen.getByRole('option', {name: 'Result', hidden: true}),
+ ).toBeInTheDocument();
+ });
+ rerender(
+ renderField({search: updatedSearch, bootstrap: () => []}, 'b', {}),
+ );
+
+ await waitFor(() => {
+ expect(
+ screen.getByRole('option', {name: 'Updated result', hidden: true}),
+ ).toBeInTheDocument();
+ });
+ expect(updatedSearch).toHaveBeenCalledWith('re', expect.anything());
+ });
+
+ it('leaves a closed list closed', async () => {
+ const user = userEvent.setup();
+ const updatedBootstrap = vi.fn(() => [
+ {id: '2', label: 'Updated result'},
+ ]);
+ const {rerender} = render(
+ renderField({search: () => [], bootstrap: () => [resultItem]}, 'a'),
+ );
+ const input = screen.getByRole('combobox');
+
+ await user.click(input);
+ await waitFor(() => {
+ expect(input).toHaveAttribute('aria-expanded', 'true');
+ });
+ await user.keyboard('{Escape}');
+ rerender(
+ renderField({search: () => [], bootstrap: updatedBootstrap}, 'b'),
+ );
+
+ await act(async () => {
+ await new Promise(resolve => setTimeout(resolve, 20));
+ });
+ expect(input).toHaveAttribute('aria-expanded', 'false');
+ expect(updatedBootstrap).not.toHaveBeenCalled();
+ });
+
+ it('closes an open focus list when the reload finds nothing', async () => {
+ const user = userEvent.setup();
+ const {rerender} = render(
+ renderField({search: () => [], bootstrap: () => [resultItem]}, 'a'),
+ );
+ const input = screen.getByRole('combobox');
+
+ await user.click(input);
+ await waitFor(() => {
+ expect(input).toHaveAttribute('aria-expanded', 'true');
+ });
+ rerender(renderField({search: () => [], bootstrap: () => []}, 'b'));
+
+ await waitFor(() => {
+ expect(input).toHaveAttribute('aria-expanded', 'false');
+ });
+ });
+
+ it('closes an open focus list when the reload fails', async () => {
+ const user = userEvent.setup();
+ const {rerender} = render(
+ renderField({search: () => [], bootstrap: () => [resultItem]}, 'a'),
+ );
+ const input = screen.getByRole('combobox');
+
+ await user.click(input);
+ await waitFor(() => {
+ expect(input).toHaveAttribute('aria-expanded', 'true');
+ });
+ rerender(
+ renderField(
+ {
+ search: () => [],
+ bootstrap: async () => {
+ throw new Error('offline');
+ },
+ },
+ 'b',
+ ),
+ );
+
+ await waitFor(() => {
+ expect(input).toHaveAttribute('aria-expanded', 'false');
+ });
+ });
+
+ it('closes an open focus list when focus entries are turned off', async () => {
+ const user = userEvent.setup();
+ const source = {search: () => [], bootstrap: () => [resultItem]};
+ const {rerender} = render(renderField(source, 'a'));
+ const input = screen.getByRole('combobox');
+
+ await user.click(input);
+ await waitFor(() => {
+ expect(input).toHaveAttribute('aria-expanded', 'true');
+ });
+ rerender(renderField(source, 'b', {hasEntriesOnFocus: false}));
+
+ await waitFor(() => {
+ expect(input).toHaveAttribute('aria-expanded', 'false');
+ });
+ });
+
+ it('does not reload or move the highlight when only the source is rebuilt', async () => {
+ const user = userEvent.setup();
+ const items = [
+ {id: '1', label: 'First'},
+ {id: '2', label: 'Second'},
+ ];
+ const bootstrap = vi.fn(() => items);
+ const {rerender} = render(
+ renderField({search: () => [], bootstrap: () => bootstrap()}, 'a'),
+ );
+ const input = screen.getByRole('combobox');
+
+ await user.click(input);
+ await waitFor(() => {
+ expect(
+ screen.getByRole('option', {name: 'Second', hidden: true}),
+ ).toBeInTheDocument();
+ });
+ await user.keyboard('{ArrowDown}');
+ const second = screen.getByRole('option', {name: 'Second', hidden: true});
+ expect(input).toHaveAttribute('aria-activedescendant', second.id);
+ expect(bootstrap).toHaveBeenCalledTimes(1);
+
+ // A caller that builds its source in render passes a new object.
+ rerender(
+ renderField({search: () => [], bootstrap: () => bootstrap()}, 'a'),
+ );
+ await act(async () => {
+ await new Promise(resolve => setTimeout(resolve, 20));
+ });
+
+ expect(bootstrap).toHaveBeenCalledTimes(1);
+ expect(input).toHaveAttribute(
+ 'aria-activedescendant',
+ screen.getByRole('option', {name: 'Second', hidden: true}).id,
+ );
+ });
+ });
+
it('re-shows cached results without bootstrapping again when the source is unchanged', async () => {
const user = userEvent.setup();
const bootstrap = vi.fn(() => [resultItem]);
diff --git a/packages/core/src/Typeahead/BaseTypeahead.tsx b/packages/core/src/Typeahead/BaseTypeahead.tsx
index 495a8c4882..b60a08c3d1 100644
--- a/packages/core/src/Typeahead/BaseTypeahead.tsx
+++ b/packages/core/src/Typeahead/BaseTypeahead.tsx
@@ -33,6 +33,7 @@ import React, {
import * as stylex from '@stylexjs/stylex';
import {useBusyIndicatorLane} from './busyIndicatorLane';
import {useTrailingKeyDown} from './trailingKeyDown';
+import {useCommittedChoices} from './committedChoicesKey';
import type {StyleXStyles} from '@stylexjs/stylex';
import {usePopover} from '../Popover/usePopover';
import {useAnnounce} from '../hooks/useAnnounce';
@@ -600,6 +601,36 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
() => displayOrder(results, queryEntryCount),
[results, queryEntryCount],
);
+ // Committed values (Tokenizer's tokens) leave the shown rows in the same
+ // render that commits them, before any reload answers, so a list never
+ // offers a token (component:Tokenizer FR13). The highlight stays on its item
+ // when that item remains. The previous key is remembered in state, like
+ // `sourceOfState` below.
+ const committedChoices = useCommittedChoices();
+ const committedChoicesKey = committedChoices?.key;
+ const isAtCommitLimit = committedChoices?.isAtLimit === true;
+ const [committedKeyOfState, setCommittedKeyOfState] =
+ useState(committedChoicesKey);
+ if (committedKeyOfState !== committedChoicesKey) {
+ setCommittedKeyOfState(committedChoicesKey);
+ const committedIds = committedChoices?.ids;
+ const kept =
+ committedIds == null
+ ? results
+ : results.filter(item => !committedIds.has(item.id));
+ if (kept.length !== results.length) {
+ const highlightedId = displayedResults[highlightedIndex]?.id;
+ const keptOrder = displayOrder(kept, queryEntryCount);
+ const keptIndex =
+ highlightedId == null
+ ? -1
+ : keptOrder.findIndex(item => item.id === highlightedId);
+ setResults(kept);
+ setHighlightedIndex(
+ keptIndex >= 0 ? keptIndex : keptOrder.length > 0 ? 0 : -1,
+ );
+ }
+ }
// The popup's listbox, measured when a later list arrives so the appended
// rows scroll instead of moving the shown rows or flipping the popup to
// the other side of the field (spec:AST-092 FR6).
@@ -784,6 +815,11 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
}
}, [searchSource]);
+ // True from the moment the list is asked to open until it closes, including
+ // a show deferred past the active click, so committed values that change in
+ // the same event that opened the list still reload it.
+ const isShowingRef = useRef(false);
+
// Layer for dropdown. The list is a manual popover (see usePopover below):
// while it is open, a press on the combobox itself (its input or its
// buttons) or in the list is inside, and a press anywhere else closes it
@@ -794,6 +830,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
// own light dismiss.
const outsidePress = useOutsidePress();
const handleLayerShow = useCallback(() => {
+ isShowingRef.current = true;
onOpenChange?.(true);
const anchorEl = anchorRef?.current ?? fallbackAnchorRef.current;
if (anchorEl == null) {
@@ -817,6 +854,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
}, [onOpenChange, anchorRef, outsidePress]);
const handleLayerHide = useCallback(() => {
+ isShowingRef.current = false;
outsidePress.stop();
onOpenChange?.(false);
setHighlightedIndex(-1);
@@ -870,6 +908,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
if (isDisabledRef.current) {
return;
}
+ isShowingRef.current = true;
if (pointerActiveRef.current) {
document.addEventListener(
'click',
@@ -1089,9 +1128,23 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
setHighlightedIndex(nextHighlightedIndex);
if (bootstrapResults.length > 0) {
showLayer();
+ } else if (committedChoices != null) {
+ // A Tokenizer list left with no eligible choice (its focus entries
+ // all committed, or the request failed) closes rather than staying
+ // open and empty (component:Tokenizer FR15). A plain Typeahead
+ // provides no committed choices and keeps its current behavior.
+ popover.hide();
}
},
- [highlightedIndex, maxMenuItems, results.length, showLayer, replaceResults],
+ [
+ highlightedIndex,
+ maxMenuItems,
+ results.length,
+ showLayer,
+ replaceResults,
+ popover,
+ committedChoices,
+ ],
);
// Perform bootstrap
@@ -1101,8 +1154,9 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
try {
bootstrapResult = searchSource.bootstrap();
} catch {
+ // A failed request offers nothing: an open list closes (FR15).
+ applyBootstrapResults([], gen);
if (searchGenRef.current === gen) {
- replaceResults([]);
setLoading(false);
}
return;
@@ -1118,15 +1172,90 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
try {
applyBootstrapResults(await bootstrapResult, gen);
} catch {
- if (searchGenRef.current === gen) {
- replaceResults([]);
- }
+ applyBootstrapResults([], gen);
} finally {
if (searchGenRef.current === gen) {
setLoading(false);
}
}
- }, [searchSource, applyBootstrapResults, setLoading, replaceResults]);
+ }, [searchSource, applyBootstrapResults, setLoading]);
+
+ // A list shown before the caller's committed values changed is no longer
+ // current (component:Tokenizer FR13, spec:AST-092 FR4). While the list is
+ // open, it reloads the same query, its typed text or the focus list, from
+ // the source those values now filter. A closed list stays closed; opening it
+ // loads that source.
+ // Decided from the state at the moment the committed values change, with
+ // no remembered outcome (the state table in the pull request):
+ // - at the limit: close, whatever the query (FR15);
+ // - a closed list with no search waiting: stays closed, and opening it
+ // loads the current source;
+ // - typed text: search it again, also replacing a search still waiting
+ // for its debounce; an empty answer shows the empty-search message;
+ // - a focus list the commit emptied (no row left, no load waiting): close
+ // (FR15); with rows left, or a load waiting: load the focus list again;
+ // an empty or failed answer closes (FR15);
+ // - a focus list with focus entries off: close.
+ const reloadForCommittedChoices = useCallback(() => {
+ // A search waiting for its debounce would use the source from before the
+ // commit, so the reload replaces it.
+ const hadPendingSearch = searchTimeoutRef.current != null;
+ if (searchTimeoutRef.current != null) {
+ clearTimeout(searchTimeoutRef.current);
+ searchTimeoutRef.current = null;
+ }
+ if (isDisabled || !isMountedRef.current) {
+ return;
+ }
+ if (isAtCommitLimit) {
+ popover.hide();
+ return;
+ }
+ if (!isShowingRef.current && !hadPendingSearch) {
+ return;
+ }
+ if (query.length > 0) {
+ if (!isBelowMinQueryLength(query, minQueryLength)) {
+ void performSearch(query);
+ }
+ return;
+ }
+ if (!hasEntriesOnFocus || (results.length === 0 && !hadPendingSearch)) {
+ popover.hide();
+ return;
+ }
+ void performBootstrap();
+ }, [
+ isDisabled,
+ isAtCommitLimit,
+ query,
+ minQueryLength,
+ hasEntriesOnFocus,
+ results.length,
+ performSearch,
+ performBootstrap,
+ popover,
+ ]);
+ // The latest reload, read when the key changes, as an effect event.
+ const reloadForCommittedChoicesRef = useRef(reloadForCommittedChoices);
+ useIsomorphicLayoutEffect(() => {
+ reloadForCommittedChoicesRef.current = reloadForCommittedChoices;
+ });
+ const reloadedKeyRef = useRef(committedChoicesKey);
+ useIsomorphicLayoutEffect(() => {
+ if (reloadedKeyRef.current === committedChoicesKey) {
+ return;
+ }
+ reloadedKeyRef.current = committedChoicesKey;
+ // The reload is a source request, started after the commit like one a
+ // keystroke starts. Queued from a layout effect, it runs before paint, so
+ // a list the commit emptied closes without showing empty.
+ queueMicrotask(() => {
+ if (reloadedKeyRef.current === committedChoicesKey) {
+ reloadForCommittedChoicesRef.current();
+ }
+ });
+ }, [committedChoicesKey]);
// Handle query change
const handleQueryChange = useCallback(
@@ -1182,7 +1311,10 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
if (debounceMs <= 0) {
triggerSearch();
} else {
- searchTimeoutRef.current = setTimeout(triggerSearch, debounceMs);
+ searchTimeoutRef.current = setTimeout(() => {
+ searchTimeoutRef.current = null;
+ triggerSearch();
+ }, debounceMs);
}
},
[
diff --git a/packages/core/src/Typeahead/committedChoicesKey.tsx b/packages/core/src/Typeahead/committedChoicesKey.tsx
new file mode 100644
index 0000000000..ffc3b11bd2
--- /dev/null
+++ b/packages/core/src/Typeahead/committedChoicesKey.tsx
@@ -0,0 +1,37 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file committedChoicesKey.tsx
+ * @input React context
+ * @output Exports CommittedChoicesKeyContext and useCommittedChoices
+ * @position Package-internal; not exported from the package entry point.
+ * Tokenizer passes a key for its committed values through it, and whether
+ * those values reached its limit. When the key changes while the list is
+ * open, BaseTypeahead reloads the list, so a committed value leaves it and a
+ * removed one returns (component:Tokenizer FR13, spec:AST-092 FR4); at the
+ * limit it closes the list instead (FR15). A source that is only rebuilt in
+ * render does not change the key and reloads nothing.
+ */
+
+import {createContext, use} from 'react';
+
+export type CommittedChoices = {
+ /** Changes exactly when the committed values change. */
+ key: string;
+ /** The committed values' ids: never offered as choices. */
+ ids: ReadonlySet<string>;
+ /** No further value can be committed, so no list is offered. */
+ isAtLimit: boolean;
+};
+
+export const CommittedChoicesKeyContext = createContext<
+ CommittedChoices | undefined
+>(undefined);
+CommittedChoicesKeyContext.displayName = 'CommittedChoicesKeyContext';
+
+/** The caller's committed values, if a caller provides them. */
+export function useCommittedChoices(): CommittedChoices | undefined {
+ return use(CommittedChoicesKeyContext);
+}