From 8a531d896e7feb1a408fd2f6b2d52b193309734b Mon Sep 17 00:00:00 2001 From: Ultroncn <82553854+Ultroncn@users.noreply.github.com> Date: Mon, 16 Nov 2026 21:48:06 +0000 Subject: [PATCH 1/3] fix(SelectPanel): debounce screen reader announcements for list updates The built-in announcements for SelectPanel fired after every single keystroke while filtering, queueing up a burst of duplicate screen reader messages. Debounce the list-update announcements (250ms, same pattern and window as AutocompleteMenu's debounceAnnouncement) so only the latest state is announced once typing pauses. Focus announcements still fire immediately, and any pending announcement is cancelled on unmount. Fixes #7611 --- .../select-panel-announcement-debounce.md | 5 +++ .../useAnnouncements.test.tsx | 40 +++++++++++++++++++ .../FilteredActionList/useAnnouncements.tsx | 25 ++++++++++-- 3 files changed, 66 insertions(+), 4 deletions(-) create mode 100644 .changeset/select-panel-announcement-debounce.md 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..8b64bca1ce7 100644 --- a/packages/react/src/FilteredActionList/useAnnouncements.test.tsx +++ b/packages/react/src/FilteredActionList/useAnnouncements.test.tsx @@ -156,4 +156,44 @@ 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', async () => { + const list = document.createElement('ul') + list.setAttribute('role', 'listbox') + const activeOption = document.createElement('li') + activeOption.setAttribute('role', 'option') + activeOption.setAttribute('data-is-active-descendant', 'true') + activeOption.textContent = 'Start date' + list.append(activeOption) + + const items = [ + {id: 'start-date', text: 'Start date', selected: false}, + {id: 'end-date', text: 'End date', selected: false}, + ] + + const {rerender} = renderHook( + ({filterValue}) => + useAnnouncements( + items, + {current: list}, + {current: null}, + true, + false, + undefined, + 'active-descendant', + filterValue, + ), + {initialProps: {filterValue: ''}}, + ) + + rerender({filterValue: 's'}) + rerender({filterValue: 'st'}) + rerender({filterValue: 'sta'}) + + await expect.poll(() => vi.mocked(announce).mock.calls.length).toBe(1) + expect(announce).toHaveBeenCalledWith('List updated, Focused item: Start date, not selected, 1 of 2', { + delayMs: 500, + from: undefined, + }) + }) }) diff --git a/packages/react/src/FilteredActionList/useAnnouncements.tsx b/packages/react/src/FilteredActionList/useAnnouncements.tsx index b34bf87f793..bbb6198cf79 100644 --- a/packages/react/src/FilteredActionList/useAnnouncements.tsx +++ b/packages/react/src/FilteredActionList/useAnnouncements.tsx @@ -1,8 +1,9 @@ // Announcements for FilteredActionList (and SelectPanel) based // on https://github.com/github/multi-select-user-testing +import {debounce} from '@github/mini-throttle' import {announce as liveRegionAnnounce} from '@primer/live-region-element' -import {useCallback, useEffect, useRef} from 'react' +import {useCallback, useEffect, useMemo, useRef} from 'react' import type {FilteredActionListProps} from './index' import type {ItemInput} from '../SelectPanel' @@ -93,6 +94,21 @@ export const useAnnouncements = ( [enabled], ) + // Debounce list-update announcements so rapid keystrokes while filtering + // don't queue up a burst of duplicate screen reader messages. + // (Same pattern as AutocompleteMenu's debounceAnnouncement.) + const debouncedAnnounce = useMemo( + () => + debounce((text: string, options?: Parameters[1]) => { + announce(text, options) + }, 250), + [announce], + ) + + // Cancel any pending announcement on unmount so nothing is announced + // after the component is gone + useEffect(() => () => debouncedAnnounce.cancel(), [debouncedAnnounce]) + const onInputFocus = useCallback(() => { if (usingRovingTabindex) { const announcementText = `${items.length} item${items.length > 1 ? 's' : ''} available, ${selectedItems} selected.` @@ -133,14 +149,14 @@ export const useAnnouncements = ( // 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}) + debouncedAnnounce(`${message?.title}. ${message?.description}`, {delayMs}) return } if (usingRovingTabindex) { const announcementText = `${items.length} item${items.length > 1 ? 's' : ''} available, ${selectedItems} selected.` - announce(announcementText, { + debouncedAnnounce(announcementText, { delayMs, from: liveRegion ? liveRegion : undefined, }) @@ -158,7 +174,7 @@ export const useAnnouncements = ( `${index + 1} of ${items.length}`, ].join(', ') - announce(announcementText, { + debouncedAnnounce(announcementText, { delayMs, from: liveRegion ? liveRegion : undefined, // announce will create a liveRegion if it doesn't find one }) @@ -167,6 +183,7 @@ export const useAnnouncements = ( }, [ announce, + debouncedAnnounce, announcementState, items, listContainerRef, From b2afbcc4ebd195e2bd82931b3c42e7f8bfa12f29 Mon Sep 17 00:00:00 2001 From: Ultroncn <82553854+Ultroncn@users.noreply.github.com> Date: Tue, 17 Nov 2026 04:01:06 +0000 Subject: [PATCH 2/3] fix(SelectPanel): recreate announcement debouncer per effect run Copilot review on #8769: cancel() in @github/mini-throttle permanently disables the debouncer, so the memoized instance was disabled by StrictMode's cleanup replay on mount and every later list-update announcement was silently dropped. A queued empty-result message could also be announced after a new query started loading. Hold the debouncer in a ref and (re)create it lazily: each state change cancels the pending announcement and discards the cancelled instance, so the next schedule gets a fresh one. Cancelling happens in the effect body on state change (including transitions that schedule no replacement); unmount cancels via a separate effect whose cleanup only runs on unmount. Pending announcements survive unrelated re-renders, as before. Tests: rewrite the debounce test with fake timers (spaced updates, varying payloads, assert silence before the deadline and exactly one call with the final text), add a StrictMode regression test and a stale empty-result test. --- .../useAnnouncements.test.tsx | 152 +++++++++++++++--- .../FilteredActionList/useAnnouncements.tsx | 54 +++++-- 2 files changed, 173 insertions(+), 33 deletions(-) diff --git a/packages/react/src/FilteredActionList/useAnnouncements.test.tsx b/packages/react/src/FilteredActionList/useAnnouncements.test.tsx index 8b64bca1ce7..dc0f054f985 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') @@ -157,43 +164,142 @@ 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', async () => { - const list = document.createElement('ul') - list.setAttribute('role', 'listbox') - const activeOption = document.createElement('li') - activeOption.setAttribute('role', 'option') - activeOption.setAttribute('data-is-active-descendant', 'true') - activeOption.textContent = 'Start date' - list.append(activeOption) + 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() - const items = [ - {id: 'start-date', text: 'Start date', selected: false}, - {id: 'end-date', text: 'End date', selected: false}, - ] + // 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( - items, - {current: list}, + [{id: 'start-date', text: 'Start date', selected: false}], + {current: null}, {current: null}, true, false, undefined, - 'active-descendant', + 'roving-tabindex', filterValue, ), - {initialProps: {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'}) - rerender({filterValue: 'st'}) - rerender({filterValue: 'sta'}) + act(() => { + vi.advanceTimersByTime(300) + }) + expect(announce).toHaveBeenCalledTimes(1) + expect(announce).toHaveBeenCalledWith('1 item available, 0 selected.', {delayMs: 500, from: undefined}) + + vi.useRealTimers() + }) + + 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() - await expect.poll(() => vi.mocked(announce).mock.calls.length).toBe(1) - expect(announce).toHaveBeenCalledWith('List updated, Focused item: Start date, not selected, 1 of 2', { - delayMs: 500, - from: undefined, + // 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 bbb6198cf79..5628ae4830d 100644 --- a/packages/react/src/FilteredActionList/useAnnouncements.tsx +++ b/packages/react/src/FilteredActionList/useAnnouncements.tsx @@ -3,7 +3,7 @@ import {debounce} from '@github/mini-throttle' import {announce as liveRegionAnnounce} from '@primer/live-region-element' -import {useCallback, useEffect, useMemo, useRef} from 'react' +import {useCallback, useEffect, useRef} from 'react' import type {FilteredActionListProps} from './index' import type {ItemInput} from '../SelectPanel' @@ -97,17 +97,41 @@ export const useAnnouncements = ( // Debounce list-update announcements so rapid keystrokes while filtering // don't queue up a burst of duplicate screen reader messages. // (Same pattern as AutocompleteMenu's debounceAnnouncement.) - const debouncedAnnounce = useMemo( - () => - debounce((text: string, options?: Parameters[1]) => { + // + // The debouncer lives in a ref and is (re)created lazily: `cancel()` in + // `@github/mini-throttle` permanently disables the instance it is called + // on, so a cancelled instance must be discarded and never reused. A + // memoized instance shared across effect runs would be disabled by + // StrictMode's cleanup replay on mount (and by any later cleanup), which + // silently drops every subsequent list-update announcement. + type DebouncedAnnounce = { + (text: string, options?: Parameters[1]): void + cancel(): void + } + const debouncedAnnounceRef = useRef(null) + + // Drop the current debouncer, cancelling any pending announcement. + const cancelPendingAnnouncement = useCallback(() => { + debouncedAnnounceRef.current?.cancel() + debouncedAnnounceRef.current = null + }, []) + + const getDebouncedAnnounce = useCallback((): DebouncedAnnounce => { + let debounced = debouncedAnnounceRef.current + if (!debounced) { + debounced = debounce((text: string, options?: Parameters[1]) => { announce(text, options) - }, 250), - [announce], - ) + }, 250) + debouncedAnnounceRef.current = debounced + } + return debounced + }, [announce]) // Cancel any pending announcement on unmount so nothing is announced - // after the component is gone - useEffect(() => () => debouncedAnnounce.cancel(), [debouncedAnnounce]) + // after the component is gone. This effect's cleanup only runs on + // unmount (and on StrictMode's mount replay, where nothing is pending + // yet), so it never cancels announcements for a live component. + useEffect(() => cancelPendingAnnouncement, [cancelPendingAnnouncement]) const onInputFocus = useCallback(() => { if (usingRovingTabindex) { @@ -147,6 +171,15 @@ export const useAnnouncements = ( liveRegion?.clear() // clear previous announcements + // A state change supersedes any pending announcement from the + // previous state, so cancel it even when this transition schedules + // no replacement — e.g. an empty-result message queued just before + // a new query starts loading must not be announced afterwards. + // The cancelled instance is discarded (see above) and the next + // schedule gets a fresh one. + cancelPendingAnnouncement() + const debouncedAnnounce = getDebouncedAnnounce() + // eslint-disable-next-line react-you-might-not-need-an-effect/no-event-handler if (items.length === 0 && !loading) { debouncedAnnounce(`${message?.title}. ${message?.description}`, {delayMs}) @@ -183,8 +216,9 @@ export const useAnnouncements = ( }, [ announce, - debouncedAnnounce, announcementState, + cancelPendingAnnouncement, + getDebouncedAnnounce, items, listContainerRef, liveRegion, From 55e5292b301ebfadc09a9c450456dc44471a8eb6 Mon Sep 17 00:00:00 2001 From: Ultron <82553854+Ultroncn@users.noreply.github.com> Date: Fri, 20 Nov 2026 17:24:00 +0800 Subject: [PATCH 3/3] Cancel stale list update announcements --- .../useAnnouncements.test.tsx | 110 ++++++++++++++++ .../FilteredActionList/useAnnouncements.tsx | 119 +++++++----------- 2 files changed, 158 insertions(+), 71 deletions(-) diff --git a/packages/react/src/FilteredActionList/useAnnouncements.test.tsx b/packages/react/src/FilteredActionList/useAnnouncements.test.tsx index dc0f054f985..49061eff853 100644 --- a/packages/react/src/FilteredActionList/useAnnouncements.test.tsx +++ b/packages/react/src/FilteredActionList/useAnnouncements.test.tsx @@ -267,6 +267,116 @@ describe('useAnnouncements', () => { 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."} diff --git a/packages/react/src/FilteredActionList/useAnnouncements.tsx b/packages/react/src/FilteredActionList/useAnnouncements.tsx index 5628ae4830d..8462bb93de8 100644 --- a/packages/react/src/FilteredActionList/useAnnouncements.tsx +++ b/packages/react/src/FilteredActionList/useAnnouncements.tsx @@ -1,7 +1,6 @@ // Announcements for FilteredActionList (and SelectPanel) based // on https://github.com/github/multi-select-user-testing -import {debounce} from '@github/mini-throttle' import {announce as liveRegionAnnounce} from '@primer/live-region-element' import {useCallback, useEffect, useRef} from 'react' import type {FilteredActionListProps} from './index' @@ -9,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 @@ -94,44 +94,13 @@ export const useAnnouncements = ( [enabled], ) - // Debounce list-update announcements so rapid keystrokes while filtering - // don't queue up a burst of duplicate screen reader messages. - // (Same pattern as AutocompleteMenu's debounceAnnouncement.) - // - // The debouncer lives in a ref and is (re)created lazily: `cancel()` in - // `@github/mini-throttle` permanently disables the instance it is called - // on, so a cancelled instance must be discarded and never reused. A - // memoized instance shared across effect runs would be disabled by - // StrictMode's cleanup replay on mount (and by any later cleanup), which - // silently drops every subsequent list-update announcement. - type DebouncedAnnounce = { - (text: string, options?: Parameters[1]): void - cancel(): void - } - const debouncedAnnounceRef = useRef(null) - - // Drop the current debouncer, cancelling any pending announcement. - const cancelPendingAnnouncement = useCallback(() => { - debouncedAnnounceRef.current?.cancel() - debouncedAnnounceRef.current = null + const pendingListAnnouncement = useRef<(() => void) | null>(null) + const cancelPendingListAnnouncement = useCallback(() => { + pendingListAnnouncement.current?.() + pendingListAnnouncement.current = null }, []) - const getDebouncedAnnounce = useCallback((): DebouncedAnnounce => { - let debounced = debouncedAnnounceRef.current - if (!debounced) { - debounced = debounce((text: string, options?: Parameters[1]) => { - announce(text, options) - }, 250) - debouncedAnnounceRef.current = debounced - } - return debounced - }, [announce]) - - // Cancel any pending announcement on unmount so nothing is announced - // after the component is gone. This effect's cleanup only runs on - // unmount (and on StrictMode's mount replay, where nothing is pending - // yet), so it never cancels announcements for a live component. - useEffect(() => cancelPendingAnnouncement, [cancelPendingAnnouncement]) + useEffect(() => cancelPendingListAnnouncement, [cancelPendingListAnnouncement, enabled, usingRovingTabindex]) const onInputFocus = useCallback(() => { if (usingRovingTabindex) { @@ -169,56 +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 - // A state change supersedes any pending announcement from the - // previous state, so cancel it even when this transition schedules - // no replacement — e.g. an empty-result message queued just before - // a new query starts loading must not be announced afterwards. - // The cancelled instance is discarded (see above) and the next - // schedule gets a fresh one. - cancelPendingAnnouncement() - const debouncedAnnounce = getDebouncedAnnounce() + 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) { - debouncedAnnounce(`${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.` - - debouncedAnnounce(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(', ') - - debouncedAnnounce(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, - cancelPendingAnnouncement, - getDebouncedAnnounce, + cancelPendingListAnnouncement, + enabled, items, listContainerRef, liveRegion,