Skip to content

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.md
new file mode 100644
index 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.
+@cixzhang
diff --git a/packages/core/src/FileInput/FileInput.test.tsx b/packages/core/src/FileInput/FileInput.test.tsx
index 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.tsx
index 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.tsx
index 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 jsdom
beforeEach(() => {
@@ -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.tsx
index 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 query
const filteredItems = useMemo(() => {
if (!searchQuery) {
@@ -715,6 +735,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
(e: React.MouseEvent) => {
e.stopPropagation(); // Don't open dropdown
onChange([]);
+ 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 → handleToggle
diff --git a/packages/core/src/Pagination/Pagination.test.tsx b/packages/core/src/Pagination/Pagination.test.tsx
index 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.tsx
index 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);