fix(a11y): announce file selection, page changes, and multiselect count via live region (forms-17, navigation-10, comboboxes-7)

Author: cixzhang

.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

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();

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,
     ],
   );
 

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');
+      });
+    });
+  });
 });

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,14 +735,21 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     (e: React.MouseEvent) => {
       e.stopPropagation(); // Don't open dropdown
       onChange([]);
+      announceSelection([]);
       if (changeAction) {
         startTransition(async () => {
           setOptimisticValue([]);
           await changeAction([]);
         });
       }
     },
-    [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