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.mdnew file mode 100644index 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 @duytbpdiff --git a/packages/core/locales/en.json b/packages/core/locales/en.jsonindex 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.tsxindex 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 againstdiff --git a/packages/core/src/PowerSearch/PowerSearch.tsx b/packages/core/src/PowerSearch/PowerSearch.tsxindex 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.mdindex 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 sheetpresentation.- **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 thetrigger and the field's announcements follow the same FR14 route fromwherever 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.tsxindex 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.tsxindex 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 tokenconst 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.tsxindex 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.tsnew file mode 100644index 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';