Select panel: custom screen reader announcements

[siddharthkp]

• Fixes https://github.com/github/primer/issues/3409
• Based on https://github.com/github/multi-select-user-testing
• Only available behind feature flag (primer_react_select_panel_with_modern_action_list)

Context

Browser + screen reader combinations have different default announcements. We are trying to fill in the gaps, which leads to great results for some combinations but redundant/verbose results for others. See notes below for more information.

We shy away from browser + OS (proxy for screen reader) detection to optimise these results, in order to avoid accidentally doing more harm than good. We are choosing redundancy/verbosity over missing information.

Rollout strategy

• Patch release
• Minor release
• Major release; if selected, include a written rollout or migration plan
• None; if selected, include a brief description as to why

Testing & Reviewing

Voiceover on MacOS + Safari

Notes: Safari has the least amount of automated announcements, so our additions fill in the gaps very nicely.

• 🟢 On first open, Safari (default announcements) tells the user about the structure, Then, we inform the user about focus state.
• 🟢 On updates to results, Safari announces nothing. We inform user about focused item, selection state and number of items

Event	Before	After (with custom announcements)
recording	voiceover-safari-without-custom-announcements.mov	voiceover-safari-with-custom-announcements.mov
On panel open	Select labels Filter items, web dialogue, with 6 items, Filter items. Items will be filtered as you type, edit text.	Select labels Filter items, web dialogue, with 6 items, Filter items. Items will be filtered as you type, edit text. Focus on filter text box and list of items, Focused item: enhancement, selected, 1 of 7
type letter "b"	silence	List updated, Focused item: bug, selected, 1 of 3
type letter "l"	silence	List updated, Focused item: blocker, not selected, 1 of 1
type letter "a" (no results)	silence	No matching items.

Voiceover on MacOS + Chrome

Notes: Chrome has more automated announcements than Safari, so our additions could sometimes be seen as noisy or redundant

• 🟡 On first open, Chrome (default announcements) tells the user about the structure without any details + the focused item, selection state and number of items. Then, we inform the user about the focused input AND the focused item, selection state and number of items.
• 🟡 On updates to results, Chrome announces the current selected item, selection state and number of items. We also inform the user about focused item, selection state and number of items

Event	Before	After (with custom announcements)
recording	voiceover-chrome-without-announcements.mov	voiceover-chrome-with-custom-announcements.mov
On panel open	dialogue, with 6 items enhancement selected, selected, (1 of 7)	dialogue, with 6 items enhancement selected, selected, (1 of 7) Focus on filter text box and list of labels, Focused item: enhancement, selected, 1 of 7
type letter "b"	bug selected, selected, (1 of 3)	bug selected, selected, (1 of 3) List updated, Focused item: bug, selected, 1 of 3
type letter "l"	blocker not selected, selected, (1 of 1)	blocker not selected, selected, (1 of 1) List updated, Focused item: blocker, not selected, 1 of 1
type letter "a" (no results)	bla, Insertion at end of text., Filter items Items will be filtered as you type, edit text	bla, Insertion at end of text., Filter items Items will be filtered as you type, edit text No matching items.

NVDA on Windows + Edge/Chrome

Notes: NVDA includes more information about the structure, so our additions could sometimes be seen as noisy or redundant. Chrome has the same exact behavior as Edge.

• 🟡 On first open, Edge/Chrome (default announcements) tells the user about the structure + the focused item and number of items, but not it's selection state. Then, we inform the user about the focused input AND the focused item, selection state and number of items.
• 🟢 On updates to results, Edge/Chrome announces the current selected item but not it's selection state or number of items. We also inform the user about focused item, selection state and number of items

Event	Before	After (with custom announcements)
recording	nvda-edge-without-announcements.mov	nvda-edge-with-announcements.mov
On panel open	Select labels dialog. Use labels to organize issues and pull requests. Select labels list. enhancement 1 of 7	Select labels dialog. Use labels to organize issues and pull requests. Select labels list. enhancement 1 of 7 Focus on filter text box and list of labels, Focused item: enhancement, selected, 1 of 7
type letter "b"	b. bug	b. bug. List updated, Focused item: bug, selected, 1 of 3
type letter "l"	l. blocker, not selected	l. blocker, not selected. List updated, Focused item: blocker, not selected, 1 of 1
type letter "a" (no results)	a. Filter items edit Items will be filtered as you type, bla	a. Filter items edit Items will be filtered as you type, bla. No matching items.

Merge checklist

• Added/updated tests
• Added/updated documentation
• Added/updated previews (Storybook)
• Changes are SSR compatible
• Tested in Chrome
• Tested in Firefox
• Tested in Safari
• Tested in Edge
• (GitHub staff only) Integration tests pass at github/github (Learn more about how to run integration tests)

[changeset-bot]

🦋 Changeset detected

Latest commit: 473a5a2

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@primer/react	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

size-limit report 📦

Path	Size
packages/react/dist/browser.esm.js	97.78 KB (+0.33% 🔺)
packages/react/dist/browser.umd.js	98.18 KB (+0.51% 🔺)

[camertron]

Awesome, well done!

[siddharthkp]

• ⚠️ Note: Failing test needs Fix race condition caused by calling clear immediately after announce live-region-element#141

Update: merged and upgraded 🎉