An open source design system that's fully customizable and agent ready
TypeScript
fix(a11y): announce file selection, page changes, and multiselect count via live region (forms-17, navigation-10, comboboxes-7) (#3447)
Cindy Zhang7d902060c520
diff --git a/.changeset/announce-wiring.md b/.changeset/announce-wiring.mdnew file mode 100644index 0000000000..0a42a11b22--- /dev/null+++ b/.changeset/announce-wiring.md@@ -0,0 +1,8 @@+---+'@astryxdesign/core': patch+---++[fix] Announce file selection, page changes, and multi-select count via the live-region hook (#3343)++FileInput now announces successful file selection, Pagination announces page changes, and MultiSelector announces selection-count changes, all through the shared visually-hidden polite live region so these previously-silent surfaces are audible to screen-reader users.+@cixzhangdiff --git a/packages/core/src/FileInput/FileInput.test.tsx b/packages/core/src/FileInput/FileInput.test.tsxindex 53a712efe7..6ba6ff545f 100644--- a/packages/core/src/FileInput/FileInput.test.tsx+++ b/packages/core/src/FileInput/FileInput.test.tsx@@ -9,10 +9,27 @@* SYNC: When FileInput.tsx changes, update tests to match new behavior*/-import {describe, it, expect, vi} from 'vitest';-import {render, screen, fireEvent} from '@testing-library/react';+import {describe, it, expect, vi, afterEach} from 'vitest';+import {render, screen, fireEvent, waitFor} from '@testing-library/react';import userEvent from '@testing-library/user-event';import {FileInput} from './FileInput';+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';++afterEach(() => {+ __resetLiveRegionsForTest();+});++function politeRegion(): HTMLElement | null {+ return document.querySelector('[data-astryx-live-region="polite"]');+}++function fileInputEl(): HTMLInputElement {+ const el = document.querySelector('input[type="file"]');+ if (!(el instanceof HTMLInputElement)) {+ throw new Error('file input not found');+ }+ return el;+}function createFile(name: string,@@ -245,6 +262,55 @@ describe('FileInput', () => {});});+ describe('announcements', () => {+ it('announces a single file selection politely', async () => {+ render(<FileInput label="Upload" value={null} onChange={() => {}} />);+ fireEvent.change(fileInputEl(), {+ target: {files: [createFile('report.pdf', 100)]},+ });+ await waitFor(() => {+ expect(politeRegion()).toHaveTextContent('1 file selected: report.pdf');+ });+ });++ it('announces a multi-file count politely', async () => {+ render(+ <FileInput+ label="Upload"+ value={null}+ onChange={() => {}}+ isMultiple+ />,+ );+ const files = [+ createFile('a.txt', 100),+ createFile('b.txt', 200),+ createFile('c.txt', 300),+ ];+ fireEvent.change(fileInputEl(), {target: {files}});+ await waitFor(() => {+ expect(politeRegion()).toHaveTextContent('3 files selected');+ });+ });++ it('does not announce a selection when validation rejects all files', async () => {+ render(+ <FileInput+ label="Upload"+ value={null}+ onChange={() => {}}+ accept=".pdf"+ />,+ );+ fireEvent.change(fileInputEl(), {+ target: {files: [createFile('note.txt', 100)]},+ });+ // A rejected selection creates no polite region (only the error goes to+ // the existing role="status" region).+ expect(politeRegion()).toBeNull();+ });+ });+describe('validation', () => {it('rejects files exceeding maxSize', () => {const handleChange = vi.fn();diff --git a/packages/core/src/FileInput/FileInput.tsx b/packages/core/src/FileInput/FileInput.tsxindex bd33dbdcb3..df18e3a5ce 100644--- a/packages/core/src/FileInput/FileInput.tsx+++ b/packages/core/src/FileInput/FileInput.tsx@@ -44,6 +44,7 @@ import {} from '../Field';import {Icon, type IconName} from '../Icon';import {Spinner} from '../Spinner';+import {useAnnounce} from '../hooks/useAnnounce';export type {InputStatus as FileInputStatus,@@ -410,6 +411,11 @@ export function FileInput({const [validationError, setValidationError] = useState<string | null>(null);const [, startTransition] = useTransition();+ // Announce successful file selection to screen readers via a persistent+ // live region (forms-17). The component's own role="status" region only+ // carries validation errors, so a successful attach was previously silent.+ const announce = useAnnounce();+const status =statusProp ??(validationError@@ -470,6 +476,17 @@ export function FileInput({const result = isMultiple ? valid : valid[0];onChange(result);+ // Announce the successful selection politely. Validation errors are+ // handled by the role="status" region below, so only announce the+ // attach here (do not double-announce errors).+ if (errors.length === 0) {+ announce(+ valid.length === 1+ ? `1 file selected: ${valid[0].name}`+ : `${valid.length} files selected`,+ );+ }+if (changeAction) {startTransition(async () => {await changeAction(result);@@ -485,6 +502,7 @@ export function FileInput({onChange,changeAction,startTransition,+ announce,],);diff --git a/packages/core/src/MultiSelector/MultiSelector.test.tsx b/packages/core/src/MultiSelector/MultiSelector.test.tsxindex 71b016ce30..57d6c42823 100644--- a/packages/core/src/MultiSelector/MultiSelector.test.tsx+++ b/packages/core/src/MultiSelector/MultiSelector.test.tsx@@ -9,10 +9,19 @@* SYNC: When MultiSelector.tsx API changes, update these tests.*/-import {describe, it, expect, vi, beforeEach} from 'vitest';-import {render, screen} from '@testing-library/react';+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';+import {render, screen, waitFor} from '@testing-library/react';import userEvent from '@testing-library/user-event';import {MultiSelector} from './MultiSelector';+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';++// Module-level constants to satisfy @eslint-react/no-unstable-default-props.+const ANNOUNCE_OPTIONS = ['Apple', 'Banana', 'Orange'] as const;+const EMPTY_VALUE: string[] = [];++function politeRegion(): HTMLElement | null {+ return document.querySelector('[data-astryx-live-region="polite"]');+}// Mock showPopover and hidePopover methods since they're not implemented in jsdombeforeEach(() => {@@ -40,6 +49,10 @@ beforeEach(() => {};});+afterEach(() => {+ __resetLiveRegionsForTest();+});+// Helper: jsdom popover content is in the DOM but may not be// "visible" in the accessibility tree. Use hidden: true to find it.const h = {hidden: true} as const;@@ -771,4 +784,59 @@ describe('MultiSelector', () => {}});});++ describe('announcements', () => {+ it('announces the selection count politely when toggling an option', async () => {+ const user = userEvent.setup();+ render(+ <MultiSelector+ label="Fruit"+ options={[...ANNOUNCE_OPTIONS]}+ value={EMPTY_VALUE}+ onChange={() => {}}+ />,+ );+ await user.click(screen.getByRole('combobox'));+ const options = screen.getAllByRole('option', {hidden: true});+ await user.click(options[0]);+ await waitFor(() => {+ expect(politeRegion()).toHaveTextContent('1 of 3 selected');+ });+ });++ it('announces "All selected" when select-all selects everything', async () => {+ const user = userEvent.setup();+ render(+ <MultiSelector+ label="Fruit"+ options={[...ANNOUNCE_OPTIONS]}+ value={EMPTY_VALUE}+ onChange={() => {}}+ hasSelectAll+ />,+ );+ await user.click(screen.getByRole('combobox'));+ await user.click(screen.getByText('Select all'));+ await waitFor(() => {+ expect(politeRegion()).toHaveTextContent('All selected');+ });+ });++ it('announces "Selection cleared" when clearing', async () => {+ const user = userEvent.setup();+ render(+ <MultiSelector+ label="Fruit"+ options={[...ANNOUNCE_OPTIONS]}+ value={['Apple', 'Banana']}+ onChange={() => {}}+ hasClear+ />,+ );+ await user.click(screen.getByRole('button', {name: 'Clear all Fruit'}));+ await waitFor(() => {+ expect(politeRegion()).toHaveTextContent('Selection cleared');+ });+ });+ });});diff --git a/packages/core/src/MultiSelector/MultiSelector.tsx b/packages/core/src/MultiSelector/MultiSelector.tsxindex 31b3ec0c20..b7180902f9 100644--- a/packages/core/src/MultiSelector/MultiSelector.tsx+++ b/packages/core/src/MultiSelector/MultiSelector.tsx@@ -65,6 +65,7 @@ import {} from '../Selector/utils';import {useMultiCombobox} from './hooks';import {mergeProps} from '../utils';+import {useAnnounce} from '../hooks/useAnnounce';import type {BaseProps} from '../BaseProps';import type {SizeValue} from '../utils/types';import {useSize} from '../SizeContext/SizeContext';@@ -607,6 +608,25 @@ export function MultiSelector<T extends MultiSelectorOptionType>({[options],);+ // Announce selection-count changes politely (comboboxes-7 announce path).+ // Toggling options / select-all previously produced no audible feedback.+ const announce = useAnnounce();+ const announceSelection = useCallback(+ (nextValue: string[]) => {+ const total = selectableItems.length;+ const selectableSet = new Set(selectableItems.map(item => item.value));+ const selectedCount = nextValue.filter(v => selectableSet.has(v)).length;+ if (selectedCount === 0) {+ announce('Selection cleared');+ } else if (total > 0 && selectedCount === total) {+ announce('All selected');+ } else {+ announce(`${selectedCount} of ${total} selected`);+ }+ },+ [announce, selectableItems],+ );+// Filter items by search queryconst filteredItems = useMemo(() => {if (!searchQuery) {@@ -715,6 +735,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({(e: React.MouseEvent) => {e.stopPropagation(); // Don't open dropdownonChange([]);+ announceSelection([]);if (changeAction) {startTransition(async () => {setOptimisticValue([]);@@ -722,7 +743,13 @@ export function MultiSelector<T extends MultiSelectorOptionType>({});}},- [onChange, changeAction, startTransition, setOptimisticValue],+ [+ onChange,+ changeAction,+ startTransition,+ setOptimisticValue,+ announceSelection,+ ],);const handleToggle = useCallback(@@ -732,6 +759,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({: [...optimisticValue, itemValue];onChange(newValue);+ announceSelection(newValue);if (changeAction) {startTransition(async () => {setOptimisticValue(newValue);@@ -745,6 +773,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({changeAction,startTransition,setOptimisticValue,+ announceSelection,],);@@ -790,6 +819,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({}onChange(newValue);+ announceSelection(newValue);if (changeAction) {startTransition(async () => {setOptimisticValue(newValue);@@ -804,6 +834,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({changeAction,startTransition,setOptimisticValue,+ announceSelection,]);// Route toggle: select-all sentinel → handleSelectAll, everything else → handleTogglediff --git a/packages/core/src/Pagination/Pagination.test.tsx b/packages/core/src/Pagination/Pagination.test.tsxindex 6390bc50ea..3c8e8f6c50 100644--- a/packages/core/src/Pagination/Pagination.test.tsx+++ b/packages/core/src/Pagination/Pagination.test.tsx@@ -9,10 +9,26 @@* SYNC: When Pagination.tsx changes, update tests to match new behavior*/-import {describe, it, expect, vi} from 'vitest';-import {render, screen, within, fireEvent, act} from '@testing-library/react';+import {describe, it, expect, vi, afterEach} from 'vitest';+import {+ render,+ screen,+ within,+ fireEvent,+ act,+ waitFor,+} from '@testing-library/react';import userEvent from '@testing-library/user-event';import {Pagination, generatePageRange} from './Pagination';+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';++afterEach(() => {+ __resetLiveRegionsForTest();+});++function politeRegion(): HTMLElement | null {+ return document.querySelector('[data-astryx-live-region="polite"]');+}// =============================================================================// generatePageRange helper@@ -363,6 +379,38 @@ describe('Pagination', () => {// ---------------------------------------------------------------------------describe('page change callbacks', () => {+ it('does not announce on initial mount', () => {+ render(<Pagination page={1} onChange={() => {}} totalPages={10} />);+ expect(politeRegion()).toBeNull();+ });++ it('announces the new page politely when navigating', async () => {+ const user = userEvent.setup();+ render(<Pagination page={2} onChange={() => {}} totalPages={10} />);+ await user.click(screen.getByRole('button', {name: 'Go to page 3'}));+ await waitFor(() => {+ expect(politeRegion()).toHaveTextContent('Page 3 of 10');+ });+ });++ it('announces the next page when clicking next', async () => {+ const user = userEvent.setup();+ render(<Pagination page={2} onChange={() => {}} totalPages={5} />);+ await user.click(screen.getByRole('button', {name: 'Go to next page'}));+ await waitFor(() => {+ expect(politeRegion()).toHaveTextContent('Page 3 of 5');+ });+ });++ it('announces without a total when only hasMore is known', async () => {+ const user = userEvent.setup();+ render(<Pagination page={1} onChange={() => {}} hasMore />);+ await user.click(screen.getByRole('button', {name: 'Go to next page'}));+ await waitFor(() => {+ expect(politeRegion()).toHaveTextContent('Page 2');+ });+ });+it('calls onChange when clicking a page button', async () => {const user = userEvent.setup();const onChange = vi.fn();@@ -454,7 +502,9 @@ describe('Pagination', () => {// reflects the page being navigated to.await user.click(screen.getByRole('button', {name: 'Go to next page'}));expect(changeAction).toHaveBeenCalledWith(2);- expect(screen.getByText('Page 2 of 5')).toBeInTheDocument();+ expect(+ within(screen.getByRole('navigation')).getByText('Page 2 of 5'),+ ).toBeInTheDocument();await act(async () => {resolveAction?.();@@ -484,14 +534,17 @@ describe('Pagination', () => {);const next = screen.getByRole('button', {name: 'Go to next page'});+ const nav = screen.getByRole('navigation');await act(async () => {fireEvent.click(next);});- expect(screen.getByText('Page 2 of 5')).toBeInTheDocument();+ // Scope to the nav landmark: the live region on document.body also+ // carries the announced page text.+ expect(within(nav).getByText('Page 2 of 5')).toBeInTheDocument();await act(async () => {fireEvent.click(next);});- expect(screen.getByText('Page 3 of 5')).toBeInTheDocument();+ expect(within(nav).getByText('Page 3 of 5')).toBeInTheDocument();expect(changeAction).toHaveBeenCalledTimes(2);expect(changeAction).toHaveBeenNthCalledWith(1, 2);diff --git a/packages/core/src/Pagination/Pagination.tsx b/packages/core/src/Pagination/Pagination.tsxindex 37eb236601..3daa77f88d 100644--- a/packages/core/src/Pagination/Pagination.tsx+++ b/packages/core/src/Pagination/Pagination.tsx@@ -34,6 +34,7 @@ import {Button} from '../Button';import {Icon} from '../Icon';import {Selector} from '../Selector';import {Text} from '../Text';+import {useAnnounce} from '../hooks/useAnnounce';import {mergeProps} from '../utils';import type {BaseProps} from '../BaseProps';import {themeProps} from '../utils/themeProps';@@ -359,6 +360,12 @@ export function Pagination({? Math.max(1, Math.floor(pageSizeProp)): 10;+ // Announce page changes politely (navigation-10). The controls carry no+ // live region, so page transitions were previously silent to screen readers.+ // Only user-driven changes go through handlePageChange, so initial mount is+ // never announced.+ const announce = useAnnounce();+// Track the page optimistically so rapid prev/next clicks advance from the// in-flight target instead of stalling on the last committed page.const [optimisticPage, setOptimisticPage] = useOptimistic(page);@@ -392,6 +399,11 @@ export function Pagination({// Keep onChange urgent so controlled page state updates in the same commit// as the click; only the optimistic indicator and changeAction defer.onChange(newPage);+ announce(+ computedTotalPages != null+ ? `Page ${newPage} of ${computedTotalPages}`+ : `Page ${newPage}`,+ );startTransition(async () => {setOptimisticPage(newPage);await changeAction?.(newPage);