diff --git a/.changeset/select-panel-announcement-debounce.md b/.changeset/select-panel-announcement-debounce.md
new file mode 100644
index 00000000000..b458fc1bdc7
--- /dev/null
+++ b/.changeset/select-panel-announcement-debounce.md
@@ -0,0 +1,5 @@
+---
+'@primer/react': patch
+---
+
+SelectPanel: Debounce screen reader announcements for list updates so rapid keystrokes while filtering don't queue up duplicate messages
diff --git a/packages/react/src/FilteredActionList/useAnnouncements.test.tsx b/packages/react/src/FilteredActionList/useAnnouncements.test.tsx
index 4b69f232963..49061eff853 100644
--- a/packages/react/src/FilteredActionList/useAnnouncements.test.tsx
+++ b/packages/react/src/FilteredActionList/useAnnouncements.test.tsx
@@ -1,6 +1,7 @@
import {act, renderHook} from '@testing-library/react'
import {announce} from '@primer/live-region-element'
-import {beforeEach, describe, expect, it, vi} from 'vitest'
+import {StrictMode} from 'react'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
import {useAnnouncements} from './useAnnouncements'
vi.mock('@primer/live-region-element', () => ({
@@ -12,6 +13,12 @@ describe('useAnnouncements', () => {
vi.mocked(announce).mockClear()
})
+ afterEach(() => {
+ // Tests using fake timers restore real timers themselves, but make sure
+ // a failure can never leak fake timers into the next test.
+ vi.useRealTimers()
+ })
+
it('includes the input label in the initial focus announcement', async () => {
const input = document.createElement('input')
input.setAttribute('aria-label', 'Filter fields')
@@ -156,4 +163,253 @@ describe('useAnnouncements', () => {
await expect.poll(() => announce).toHaveBeenCalledWith("Nothing found. There's nothing here.", {delayMs: 500})
})
+
+ it('debounces list update announcements while the filter value changes rapidly', () => {
+ const {rerender} = renderHook(
+ ({filterValue, items}) =>
+ useAnnouncements(
+ items,
+ {current: null},
+ {current: null},
+ true,
+ false,
+ undefined,
+ 'roving-tabindex',
+ filterValue,
+ ),
+ {
+ initialProps: {
+ filterValue: '',
+ items: [{id: 'start-date', text: 'Start date', selected: false}],
+ },
+ },
+ )
+
+ vi.useFakeTimers()
+
+ // First update schedules an announcement for one item; it must not
+ // fire before the 250ms debounce window elapses.
+ rerender({
+ filterValue: 's',
+ items: [{id: 'start-date', text: 'Start date', selected: false}],
+ })
+ act(() => {
+ vi.advanceTimersByTime(100)
+ })
+ expect(announce).not.toHaveBeenCalled()
+
+ // A second update inside the window replaces the pending
+ // announcement; the first text must never be announced.
+ rerender({
+ filterValue: 'st',
+ items: [
+ {id: 'start-date', text: 'Start date', selected: false},
+ {id: 'end-date', text: 'End date', selected: false},
+ ],
+ })
+ act(() => {
+ vi.advanceTimersByTime(100)
+ })
+ expect(announce).not.toHaveBeenCalled()
+
+ // A third update replaces it again; advancing past the deadline from
+ // the last update fires exactly once, with the latest text.
+ rerender({
+ filterValue: 'sta',
+ items: [
+ {id: 'start-date', text: 'Start date', selected: false},
+ {id: 'end-date', text: 'End date', selected: false},
+ {id: 'due-date', text: 'Due date', selected: false},
+ ],
+ })
+ act(() => {
+ vi.advanceTimersByTime(200)
+ })
+ expect(announce).not.toHaveBeenCalled()
+ act(() => {
+ vi.advanceTimersByTime(100)
+ })
+ expect(announce).toHaveBeenCalledTimes(1)
+ expect(announce).toHaveBeenCalledWith('3 items available, 0 selected.', {delayMs: 500, from: undefined})
+
+ vi.useRealTimers()
+ })
+
+ it('still announces list updates after StrictMode replays effects on mount', () => {
+ vi.useFakeTimers()
+ const {rerender} = renderHook(
+ ({filterValue}) =>
+ useAnnouncements(
+ [{id: 'start-date', text: 'Start date', selected: false}],
+ {current: null},
+ {current: null},
+ true,
+ false,
+ undefined,
+ 'roving-tabindex',
+ filterValue,
+ ),
+ {
+ initialProps: {filterValue: ''},
+ wrapper: ({children}: {children: React.ReactNode}) => {children},
+ },
+ )
+
+ // With the previous memoized debouncer, StrictMode's mount cleanup
+ // permanently disabled it, so this update was never announced.
+ rerender({filterValue: 's'})
+ act(() => {
+ vi.advanceTimersByTime(300)
+ })
+ expect(announce).toHaveBeenCalledTimes(1)
+ expect(announce).toHaveBeenCalledWith('1 item available, 0 selected.', {delayMs: 500, from: undefined})
+
+ vi.useRealTimers()
+ })
+
+ it.each([100, 250])('cancels list-update delivery when unmounted after %i ms', async elapsed => {
+ const {announce: announceToLiveRegion} = await vi.importActual<{announce: typeof announce}>(
+ '@primer/live-region-element',
+ )
+ const liveRegion = document.createElement('live-region')
+ document.body.append(liveRegion)
+ vi.mocked(announce).mockImplementation(announceToLiveRegion)
+ vi.useFakeTimers()
+
+ try {
+ const {rerender, unmount} = renderHook(
+ ({filterValue}) =>
+ useAnnouncements(
+ [{text: 'Start date'}],
+ {current: null},
+ {current: null},
+ true,
+ false,
+ undefined,
+ 'roving-tabindex',
+ filterValue,
+ ),
+ {initialProps: {filterValue: ''}},
+ )
+
+ rerender({filterValue: 's'})
+ await act(() => vi.advanceTimersByTimeAsync(elapsed))
+ expect(announce).toHaveBeenCalledTimes(elapsed === 250 ? 1 : 0)
+ unmount()
+ await act(() => vi.advanceTimersByTimeAsync(1000))
+ expect(liveRegion.getMessage('polite')).toBe('')
+ } finally {
+ vi.mocked(announce).mockReset()
+ liveRegion.remove()
+ }
+ })
+
+ it('cancels a queued list update when announcements are disabled without a content change', () => {
+ vi.useFakeTimers()
+ const {rerender} = renderHook(
+ ({enabled, filterValue}) =>
+ useAnnouncements(
+ [{text: 'Start date'}],
+ {current: null},
+ {current: null},
+ enabled,
+ false,
+ undefined,
+ 'roving-tabindex',
+ filterValue,
+ ),
+ {initialProps: {enabled: true, filterValue: ''}},
+ )
+
+ rerender({enabled: true, filterValue: 's'})
+ act(() => vi.advanceTimersByTime(100))
+ rerender({enabled: false, filterValue: 's'})
+ act(() => vi.advanceTimersByTime(1000))
+ expect(announce).not.toHaveBeenCalled()
+
+ rerender({enabled: true, filterValue: 'st'})
+ act(() => vi.advanceTimersByTime(250))
+ expect(announce).toHaveBeenCalledTimes(1)
+ })
+
+ it('announces current focus once after the final active-descendant list update', () => {
+ vi.useFakeTimers({toFake: ['requestAnimationFrame', 'cancelAnimationFrame', 'setTimeout', 'clearTimeout']})
+ const list = document.createElement('ul')
+ const start = document.createElement('li')
+ start.setAttribute('role', 'option')
+ start.setAttribute('data-is-active-descendant', 'true')
+ start.textContent = 'Start date'
+ const end = document.createElement('li')
+ end.setAttribute('role', 'option')
+ end.textContent = 'End date'
+ list.append(start, end)
+
+ const {rerender} = renderHook(
+ ({filterValue}) =>
+ useAnnouncements(
+ [{text: 'Start date'}, {text: 'End date', selected: true}],
+ {current: list},
+ {current: null},
+ true,
+ false,
+ undefined,
+ 'active-descendant',
+ filterValue,
+ ),
+ {initialProps: {filterValue: ''}},
+ )
+
+ rerender({filterValue: 's'})
+ act(() => vi.advanceTimersToNextFrame())
+ act(() => vi.advanceTimersByTime(100))
+ rerender({filterValue: 'st'})
+ rerender({filterValue: 'sta'})
+ act(() => vi.advanceTimersToNextFrame())
+
+ start.removeAttribute('data-is-active-descendant')
+ end.setAttribute('data-is-active-descendant', 'true')
+ act(() => vi.advanceTimersByTime(249))
+ expect(announce).not.toHaveBeenCalled()
+ act(() => vi.advanceTimersByTime(1))
+ expect(announce).toHaveBeenCalledExactlyOnceWith('List updated, Focused item: End date, selected, 2 of 2', {
+ delayMs: 500,
+ from: undefined,
+ })
+ })
+
+ it('cancels a queued empty-result announcement when a new query starts loading', () => {
+ vi.useFakeTimers()
+ const message = {title: 'Nothing found', description: "There's nothing here."}
+ const {rerender} = renderHook(
+ ({loading, filterValue}) =>
+ useAnnouncements(
+ [],
+ {current: null},
+ {current: null},
+ true,
+ loading,
+ message,
+ 'active-descendant',
+ filterValue,
+ ),
+ {initialProps: {loading: false, filterValue: ''}},
+ )
+
+ // Queue the empty-result announcement.
+ rerender({loading: false, filterValue: 'zero'})
+ act(() => {
+ vi.advanceTimersByTime(100)
+ })
+ expect(announce).not.toHaveBeenCalled()
+
+ // A new query starts loading before the window elapses; the stale
+ // "Nothing found" message must not be announced.
+ rerender({loading: true, filterValue: 'zero'})
+ act(() => {
+ vi.advanceTimersByTime(300)
+ })
+ expect(announce).not.toHaveBeenCalled()
+
+ vi.useRealTimers()
+ })
})
diff --git a/packages/react/src/FilteredActionList/useAnnouncements.tsx b/packages/react/src/FilteredActionList/useAnnouncements.tsx
index b34bf87f793..8462bb93de8 100644
--- a/packages/react/src/FilteredActionList/useAnnouncements.tsx
+++ b/packages/react/src/FilteredActionList/useAnnouncements.tsx
@@ -8,6 +8,7 @@ import type {ItemInput} from '../SelectPanel'
// we add a delay so that it does not interrupt default screen reader announcement and queues after it
const delayMs = 500
+const listUpdateDelayMs = 250
const getInputLabel = (input: HTMLInputElement | null) => {
if (!input) return
@@ -93,6 +94,14 @@ export const useAnnouncements = (
[enabled],
)
+ const pendingListAnnouncement = useRef<(() => void) | null>(null)
+ const cancelPendingListAnnouncement = useCallback(() => {
+ pendingListAnnouncement.current?.()
+ pendingListAnnouncement.current = null
+ }, [])
+
+ useEffect(() => cancelPendingListAnnouncement, [cancelPendingListAnnouncement, enabled, usingRovingTabindex])
+
const onInputFocus = useCallback(() => {
if (usingRovingTabindex) {
const announcementText = `${items.length} item${items.length > 1 ? 's' : ''} available, ${selectedItems} selected.`
@@ -129,45 +138,64 @@ export const useAnnouncements = (
if (previousAnnouncementState.current === announcementState) return
previousAnnouncementState.current = announcementState
+ cancelPendingListAnnouncement()
+ // eslint-disable-next-line react-you-might-not-need-an-effect/no-event-handler -- Updates can come from props, independently of input events.
+ if (!enabled) return
+
liveRegion?.clear() // clear previous announcements
+ let frameId: number | undefined
+ let timeoutId: number | undefined
+ let delivery: ReturnType
+ pendingListAnnouncement.current = () => {
+ if (frameId !== undefined) window.cancelAnimationFrame(frameId)
+ if (timeoutId !== undefined) window.clearTimeout(timeoutId)
+ delivery?.cancel()
+ }
+
+ const schedule = (getText: () => string | undefined, options: Parameters[1]) => {
+ timeoutId = window.setTimeout(() => {
+ const text = getText()
+ if (text !== undefined) delivery = announce(text, options)
+ }, listUpdateDelayMs)
+ }
+
// eslint-disable-next-line react-you-might-not-need-an-effect/no-event-handler
if (items.length === 0 && !loading) {
- announce(`${message?.title}. ${message?.description}`, {delayMs})
+ schedule(() => `${message?.title}. ${message?.description}`, {delayMs})
return
}
+ const options = {delayMs, from: liveRegion ?? undefined}
if (usingRovingTabindex) {
- const announcementText = `${items.length} item${items.length > 1 ? 's' : ''} available, ${selectedItems} selected.`
-
- announce(announcementText, {
- delayMs,
- from: liveRegion ? liveRegion : undefined,
- })
+ schedule(
+ () => `${items.length} item${items.length > 1 ? 's' : ''} available, ${selectedItems} selected.`,
+ options,
+ )
} else {
- // give @primer/behaviors a moment to update active-descendant
- window.requestAnimationFrame(() => {
- const activeItem = getItemWithActiveDescendant(listContainerRef, items)
- if (!activeItem) return
- const {index, text, selected} = activeItem
-
- const announcementText = [
- `List updated`,
- `Focused item: ${text}`,
- `${selected ? 'selected' : 'not selected'}`,
- `${index + 1} of ${items.length}`,
- ].join(', ')
-
- announce(announcementText, {
- delayMs,
- from: liveRegion ? liveRegion : undefined, // announce will create a liveRegion if it doesn't find one
- })
+ // Give @primer/behaviors a frame to update active-descendant, then
+ // read focus when the delay ends so intervening navigation is included.
+ frameId = window.requestAnimationFrame(() => {
+ schedule(() => {
+ const activeItem = getItemWithActiveDescendant(listContainerRef, items)
+ if (!activeItem) return
+ const {index, text, selected} = activeItem
+
+ return [
+ 'List updated',
+ `Focused item: ${text}`,
+ selected ? 'selected' : 'not selected',
+ `${index + 1} of ${items.length}`,
+ ].join(', ')
+ }, options)
})
}
},
[
announce,
announcementState,
+ cancelPendingListAnnouncement,
+ enabled,
items,
listContainerRef,
liveRegion,