Skip to content

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

TypeScript

fix(Tokenizer, PowerSearch): Clear all is announced, once, in each component's own words (#9038)

Cindy Zhang3b0a56a02726
diff --git a/.changeset/tokenizer-clear-all-announced.md b/.changeset/tokenizer-clear-all-announced.md
new file mode 100644
index 0000000000..3a6050a301
--- /dev/null
+++ b/.changeset/tokenizer-clear-all-announced.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] The inline `Tokenizer` Clear all button announces "All items removed", once, as the touch sheet does, so a screen reader user learns the selection was emptied. `PowerSearch`'s Clear all announces its own words, "All filters removed".
+
+@cixzhang @duytbp
diff --git a/packages/core/locales/en.json b/packages/core/locales/en.json
index 7f27140ba7..d53184f023 100644
--- a/packages/core/locales/en.json
+++ b/packages/core/locales/en.json
@@ -1123,6 +1123,10 @@
"defaultMessage": "Search…",
"description": "Grey placeholder text inside the empty PowerSearch input. Imperative verb; trailing `…` is one character."
},
+ "@astryx.powersearch.allFiltersRemoved": {
+ "defaultMessage": "All filters removed",
+ "description": "Screen-reader announcement after a PowerSearch field's Clear all removes every filter. Distinct from @astryx.tokenizer.allRemoved: PowerSearch words its items as filters."
+ },
"@astryx.resizable.collapsed": {
"defaultMessage": "Collapsed",
"description": "aria-valuetext for the Resizable drag handle (role=separator) while its panel is collapsed to zero size. Replaces the numeric value announcement, since the numeric value is clamped to the minimum while collapsed. Adjective describing the panel state, not a verb/command."
@@ -1741,7 +1745,7 @@
},
"@astryx.tokenizer.allRemoved": {
"defaultMessage": "All items removed",
- "description": "Polite screen-reader announcement after a confirmed Clear all in a Tokenizer's bottom sheet has removed every selected item. Live-region text, never shown on screen."
+ "description": "Polite screen-reader announcement after a Tokenizer's Clear all has removed every selected item: the inline Clear all button, or a confirmed Clear all in the bottom sheet. Live-region text, never shown on screen."
},
"@astryx.tokenizer.selectedCount": {
"defaultMessage": "{count, number} selected",
diff --git a/packages/core/src/PowerSearch/PowerSearch.test.tsx b/packages/core/src/PowerSearch/PowerSearch.test.tsx
index 113c03e88f..07440bc3b4 100644
--- a/packages/core/src/PowerSearch/PowerSearch.test.tsx
+++ b/packages/core/src/PowerSearch/PowerSearch.test.tsx
@@ -476,6 +476,30 @@ describe('PowerSearch', () => {
});
});
+ it('announces Clear all in its own words, "All filters removed" (component:PowerSearch; Tokenizer AR7)', async () => {
+ const onChange = vi.fn();
+ render(
+ <PowerSearch
+ config={config}
+ filters={[
+ {
+ field: 'status',
+ operator: 'is',
+ value: {type: 'enum', value: 'open'},
+ },
+ ]}
+ onChange={onChange}
+ />,
+ );
+ fireEvent.click(screen.getByRole('button', {name: 'Clear all'}));
+ expect(onChange).toHaveBeenCalledWith([], 'remove', 0);
+ await waitFor(() => {
+ expect(politeRegion()).toHaveTextContent('All filters removed');
+ });
+ // Not the Tokenizer's own words.
+ expect(politeRegion()).not.toHaveTextContent('All items removed');
+ });
+
it('does not announce the result count present on mount under StrictMode, only a later change', async () => {
// StrictMode replays the mount effects: a mounted-flag guard is reset by
// the replay and speaks the initial count unprompted; comparing against
diff --git a/packages/core/src/PowerSearch/PowerSearch.tsx b/packages/core/src/PowerSearch/PowerSearch.tsx
index 50f5154aac..2927f7021c 100644
--- a/packages/core/src/PowerSearch/PowerSearch.tsx
+++ b/packages/core/src/PowerSearch/PowerSearch.tsx
@@ -30,6 +30,7 @@ import {
type TokenizerHandle,
type TokenizerOverflowBehavior,
} from '../Tokenizer';
+import {TokenizerClearAllMessageContext} from '../Tokenizer/TokenizerClearAllMessageContext';
import {TypeaheadItem} from '../Typeahead/TypeaheadItem';
import {Token} from '../Token';
import {Avatar} from '../Avatar';
@@ -1062,6 +1063,12 @@ export function PowerSearch({
// replay (which resets a flag and would speak the count present on mount
// unprompted) announces nothing until the count changes.
const announce = useAnnounce();
+ // PowerSearch words its Clear all as its record does; the field announces
+ // these words instead of Tokenizer's (component:Tokenizer AR7).
+ const clearAllMessage = useMemo(
+ () => t('@astryx.powersearch.allFiltersRemoved'),
+ [t],
+ );
const announcedResultCountRef = useRef(resultCountText);
useEffect(() => {
if (resultCountText === announcedResultCountRef.current) {
@@ -1099,37 +1106,41 @@ export function PowerSearch({
popover.triggerRef as React.Ref<HTMLDivElement>,
)}
{...themeProps('power-search')}>
- <Tokenizer
- handleRef={tokenizerRef}
- label={label}
- isLabelHidden={isLabelHidden}
- searchSource={searchSource}
- value={tokenizerValue}
- onChange={handleTokenizerChange}
- renderToken={renderToken}
- renderItem={renderItem}
- maxMenuItems={MAX_BROWSE_MENU_ITEMS}
- menuWidth={menuWidth}
- placeholder={filters.length === 0 ? placeholder : ''}
- hasAutoFocus={hasAutoFocus}
- hasClear={hasClear && !isReadOnly}
- startIcon={startIcon}
- endContent={combinedEndContent}
- isDisabled={isDisabled}
- disabledMessage={disabledMessage}
- size={size}
- tokenOverflowBehavior={tokenOverflowBehavior}
- hasEntriesOnFocus
- debounceMs={0}
- status={status}
- statusVariant={statusVariant}
- onFocus={onFocus}
- onBlur={onBlur}
- containerXstyle={xstyle}
- containerClassName={className}
- containerStyle={style}
- data-testid={testId}
- />
+ {/* The field's Clear all announces PowerSearch's own words
+ (component:PowerSearch; component:Tokenizer AR7). */}
+ <TokenizerClearAllMessageContext value={clearAllMessage}>
+ <Tokenizer
+ handleRef={tokenizerRef}
+ label={label}
+ isLabelHidden={isLabelHidden}
+ searchSource={searchSource}
+ value={tokenizerValue}
+ onChange={handleTokenizerChange}
+ renderToken={renderToken}
+ renderItem={renderItem}
+ maxMenuItems={MAX_BROWSE_MENU_ITEMS}
+ menuWidth={menuWidth}
+ placeholder={filters.length === 0 ? placeholder : ''}
+ hasAutoFocus={hasAutoFocus}
+ hasClear={hasClear && !isReadOnly}
+ startIcon={startIcon}
+ endContent={combinedEndContent}
+ isDisabled={isDisabled}
+ disabledMessage={disabledMessage}
+ size={size}
+ tokenOverflowBehavior={tokenOverflowBehavior}
+ hasEntriesOnFocus
+ debounceMs={0}
+ status={status}
+ statusVariant={statusVariant}
+ onFocus={onFocus}
+ onBlur={onBlur}
+ containerXstyle={xstyle}
+ containerClassName={className}
+ containerStyle={style}
+ data-testid={testId}
+ />
+ </TokenizerClearAllMessageContext>
</div>
{popover.render(popoverContent, {
placement: 'below',
diff --git a/packages/core/src/Tokenizer/Tokenizer.spec.md b/packages/core/src/Tokenizer/Tokenizer.spec.md
index 39e77b0de8..7297ea5209 100644
--- a/packages/core/src/Tokenizer/Tokenizer.spec.md
+++ b/packages/core/src/Tokenizer/Tokenizer.spec.md
@@ -16,6 +16,7 @@ verified_by:
packages/core/src/Tokenizer/Tokenizer.ssr.test.tsx,
packages/core/src/Tokenizer/TokenizerBottomSheet.test.tsx,
packages/core/src/Tokenizer/Tokenizer.props-type.test.tsx,
+ packages/core/src/PowerSearch/PowerSearch.test.tsx,
packages/core/src/internal/tokenizer-presentation.test.ts,
packages/core/src/Typeahead/Typeahead.test.tsx,
packages/core/src/Layer/useLayer.test.tsx,
@@ -325,7 +326,7 @@ presentation, which has no inline combobox, suggestion menu, or end lane.
## Accessibility contract
-AR1–AR5 describe the `popover` presentation; AR6 describes the sheet
+AR1–AR5 and AR7 describe the `popover` presentation; AR6 describes the sheet
presentation.
- **AR1 — Modality equivalence.** The same input or token/control produces the
@@ -382,6 +383,16 @@ presentation.
through `spec:AST-020/FR1`). After the sheet closes focus returns to the
trigger and the field's announcements follow the same FR14 route from
wherever the field renders.
+- **AR7 — Clear all is announced.** In the `popover` presentation, the field's
+ Clear all, which empties every token at once and moves focus to the input,
+ announces "All items removed" (`@astryx.tokenizer.allRemoved`, the words of
+ the sheet's Clear all in AR6) the same way the field announces a token added
+ or removed: politely, through the shared channel (`spec:AST-086/FR2`, FR5).
+ It is announced once per Clear all (`spec:AST-086/FR6`); a Clear all
+ confirmed in the sheet is announced by the sheet alone (AR6), and the field
+ stays silent for it (WCAG 2.2 SC 4.1.3 through `spec:AST-020/FR9`). A
+ component that composes Tokenizer and words its own Clear all announces its
+ own words instead (`component:PowerSearch`).
## Design relationships
@@ -462,6 +473,7 @@ become Tokenizer policy.
| FR13–FR15, AR5 | Focused Tokenizer/BaseTypeahead tests and exact-head Chromium interaction evidence | pointer/keyboard commit, first/middle/last choice, rejected/deferred control, loading, disabled, max, exhaustion, Escape, Tab, outside focus | Selected values remain available, order changes, focus leaves the combobox, active descendant names no option, stale work reopens, or a terminal state stays interactive. | `audit:Tokenizer/multi-select` |
| PR1–PR5 | Instrumented reads, pending-frame cleanup tests, and first-frame Chromium capture | open, close before frame, reopen opposite side, resize while open | Render-time/repeated reads, observer/pointer tracking, uncancelled frame, or first-frame jump occurs. | `audit:Tokenizer/performance` |
| AR1–AR5 | Existing interaction suites plus focused pointer/keyboard/browser checks; native-disabled assertions pending conformance (`spec:AST-085`) | add/edit, focus/refocus, overflow, disabled, dismissal, retained bootstrap selection | Modality changes placement, semantics/focus regress, active descendant becomes invalid, or visible placement is wrong before fallback. | `audit:Tokenizer/accessibility` |
+| AR7 | Focused Tokenizer tests, inline and sheet, and the PowerSearch test | inline Clear all; a localized catalog; a Clear all confirmed in the sheet counted across every live region; PowerSearch's own words | The inline Clear all is silent, speaks words other than its catalog message, a sheet Clear all is announced twice, or PowerSearch speaks Tokenizer's words. | `audit:Tokenizer/accessibility` |
| FR16–FR24, AR6, PR6 | Focused Tokenizer sheet tests with the compact-touch query stubbed both ways, a server-render-then-hydrate test, plus real-engine touch evidence | default popover, forced sheet, adaptive both ways, `adaptive` server-rendered as the combobox and hydrated without a recoverable error, then the trigger on a coarse-pointer client with the body still active, with `hasAutoFocus` the autofocused input's focus on the trigger after the swap and no `onBlur`/`onFocus` reported, the trigger's box against the hydrating field's at 390 and 414px, base props and ref on the trigger, the trigger's description in the inline input's order — a disabled trigger with `disabledMessage`, `description` and a status exposing the caller's ids, the description, the status message and the reason before the count and the tokens —, inert-prop warning, pending search, in-sheet announcements of toggles, busy start, result count and the rendered empty outcome, the confirmed Clear all announced once the confirmation has closed, a below-threshold query, a rejecting source, focus on the panel at open, the query cleared by a swipe, scrim, or Escape close, focus after a presentation change with the sheet closed, focus after the create row, focus after a confirmed Clear all, a spent Clear all focusable with `aria-disabled` and no action, focus after a settled search removes the focused row, no busy feedback or busy-start announcement on open with an instant source, only the search field — no list, no message, no announcement — for an empty query with nothing to list (a search-only source, nothing selected), and the list once a query finds items, element counts under a fine and a coarse pointer at rest and open (Chromium, Experimental stories: adaptive 154/120 at rest — the closed trigger in place of the inline field, a different element that stays under the fine count — and 157/165 open at the query "e" with no footer, the coarse total reconciled as rest − the re-hosted surfaces host + the dialog of 47 by part, forced sheet 114/114 and 165/165; the two owner exceptions DEC-3 records beyond the FR60 allowance, with before and after counts), no confirmation dialog in the DOM while none is pending, the query kept across a disabled-forced close, `aria-setsize`/`aria-posinset` on each row's `listitem` and the next batch on focus reaching the last rendered row, open/toggle/reopen order, create, batches, limit, Clear all, disabled while open, focus return | A field without `experimental` changes, a toggle moves a row, Clear all skips confirmation, the limit disables checked rows, or the popover bundle carries the sheet. | `audit:Tokenizer/sheet` |
| Record structure | `scripts/check-knowledge.mjs` | Template-v3 current record and current-only frontmatter links | Invalid metadata, authority, or relationship references fail repository validation. | `audit:Tokenizer/knowledge` |
diff --git a/packages/core/src/Tokenizer/Tokenizer.test.tsx b/packages/core/src/Tokenizer/Tokenizer.test.tsx
index 2413e3a960..22b1578c02 100644
--- a/packages/core/src/Tokenizer/Tokenizer.test.tsx
+++ b/packages/core/src/Tokenizer/Tokenizer.test.tsx
@@ -1403,6 +1403,33 @@ describe('Tokenizer', () => {
});
});
describe('announcements', () => {
+ it("announces Clear all politely, in the sheet's words", async () => {
+ const onChange = vi.fn();
+ render(
+ <InternationalizationProvider
+ locale="fr"
+ overrides={{
+ fr: {'@astryx.tokenizer.allRemoved': 'Tout a été retiré'},
+ }}>
+ <Tokenizer
+ label="Members"
+ searchSource={userSource}
+ value={[users[0], users[1]]}
+ onChange={onChange}
+ hasClear
+ />
+ </InternationalizationProvider>,
+ );
+ fireEvent.click(screen.getByRole('button', {name: /clear/i}));
+ expect(onChange).toHaveBeenCalledWith(
+ [],
+ expect.objectContaining({type: 'remove'}),
+ );
+ await waitFor(() => {
+ expect(politeRegion()?.textContent).toBe('Tout a été retiré');
+ });
+ });
+
it('announces removal politely on Backspace with an empty input', async () => {
const onChange = vi.fn();
render(
diff --git a/packages/core/src/Tokenizer/Tokenizer.tsx b/packages/core/src/Tokenizer/Tokenizer.tsx
index 005ae1422c..9b02bd2b4a 100644
--- a/packages/core/src/Tokenizer/Tokenizer.tsx
+++ b/packages/core/src/Tokenizer/Tokenizer.tsx
@@ -27,6 +27,7 @@
import React, {
lazy,
Suspense,
+ use,
useCallback,
useEffect,
useId,
@@ -51,6 +52,7 @@ import {
useFieldInputStyling,
} from '../Field/fieldParts';
import {useMergedRefs} from '../hooks/useMergedRefs';
+import {TokenizerClearAllMessageContext} from './TokenizerClearAllMessageContext';
import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
import {useAdaptivePresentation} from '../hooks/useAdaptivePresentation';
import {useIsHydrating} from '../hooks/useIsHydrating';
@@ -1223,15 +1225,27 @@ export function Tokenizer<T extends SearchableItem>({
);
// Handle clearing all items
- const handleClearAll = useCallback(() => {
- if (isDisabled || value.length === 0) {
- return;
- }
- // Report the last item as removed (convention)
- const lastItem = value[value.length - 1];
- onChange([], {item: lastItem, type: 'remove'});
- inputRef.current?.focus();
- }, [value, onChange, isDisabled]);
+ // A composing component that words its own Clear all (PowerSearch) provides
+ // its words; otherwise the field's own (component:Tokenizer AR7).
+ const clearAllMessage =
+ use(TokenizerClearAllMessageContext) ?? t('@astryx.tokenizer.allRemoved');
+ const handleClearAll = useCallback(
+ (options?: {silent?: boolean}) => {
+ if (isDisabled || value.length === 0) {
+ return;
+ }
+ // Report the last item as removed (convention)
+ const lastItem = value[value.length - 1];
+ onChange([], {item: lastItem, type: 'remove'});
+ // Focus moves to the input, so the emptied selection is announced, in
+ // the sheet's words (WCAG 4.1.3). The sheet announces its own Clear all.
+ if (!options?.silent) {
+ announce(clearAllMessage);
+ }
+ inputRef.current?.focus();
+ },
+ [value, onChange, isDisabled, announce, clearAllMessage],
+ );
// Handle backspace on empty input — remove last token
const handleKeyDown = useCallback(
@@ -1636,7 +1650,7 @@ export function Tokenizer<T extends SearchableItem>({
emptySearchText={emptySearchText}
onAdd={handleAdd}
onRemove={handleRemove}
- onClearAll={handleClearAll}
+ onClearAll={() => handleClearAll({silent: true})}
onChangeQuery={handleSheetQueryChange}
/>
)}
diff --git a/packages/core/src/Tokenizer/TokenizerBottomSheet.test.tsx b/packages/core/src/Tokenizer/TokenizerBottomSheet.test.tsx
index f1b8078945..fe866a5208 100644
--- a/packages/core/src/Tokenizer/TokenizerBottomSheet.test.tsx
+++ b/packages/core/src/Tokenizer/TokenizerBottomSheet.test.tsx
@@ -808,6 +808,14 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {
),
).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();
}
diff --git a/packages/core/src/Tokenizer/TokenizerClearAllMessageContext.ts b/packages/core/src/Tokenizer/TokenizerClearAllMessageContext.ts
new file mode 100644
index 0000000000..19eaed8dd0
--- /dev/null
+++ b/packages/core/src/Tokenizer/TokenizerClearAllMessageContext.ts
@@ -0,0 +1,21 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file TokenizerClearAllMessageContext.ts
+ * @input None
+ * @output A context carrying the words a composing component announces for
+ * the field's Clear all
+ * @position Internal to Core: not exported from the Tokenizer barrel. A
+ * component that composes Tokenizer and words its own Clear all (PowerSearch:
+ * "All filters removed") provides it; Tokenizer otherwise announces its own
+ * words (component:Tokenizer AR7).
+ */
+
+import {createContext} from 'react';
+
+export const TokenizerClearAllMessageContext = createContext<string | null>(
+ null,
+);
+TokenizerClearAllMessageContext.displayName = 'TokenizerClearAllMessageContext';