Skip to content

fix: screenreader dropdown announcements and option navigation - #691

Open
k-gerner wants to merge 11 commits into
mainfrom
screen-reader-rework-5482
Open

fix: screenreader dropdown announcements and option navigation#691
k-gerner wants to merge 11 commits into
mainfrom
screen-reader-rework-5482

Conversation

@k-gerner

@k-gerner k-gerner commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

Why:

  • VoiceOver could produce interrupted or duplicate speech when dropdown state, result counts, and active options changed together.
  • Highlighted matches were split across visual spans, causing assistive technology to pronounce option values as separate fragments.
  • SearchBar and FilterSearch require different navigation behavior because FilterSearch automatically selects its first option.

Changes:

  • Replace remounted announcement content with a stable polite status region that clears pending text and cancels stale delayed updates.
  • Separate one-time usage instructions from result-count announcements and suppress result counts while users navigate options.
  • Report the combobox as expanded only when the dropdown is active and contains a listbox.
  • Keep DOM focus on the combobox and identify the highlighted option through aria-activedescendant.
  • Preserve typed SearchBar text while navigating suggestions and commit the highlighted value only when selected.
  • Preserve FilterSearch’s automatic first selection while making Arrow Down advance to the following option.
  • Render dropdown entries as listbox options with selection state and complete accessible names.
  • Hide visually split highlighted markup from assistive technology so each option is announced as one phrase.
  • Remove unnamed grouping semantics from SearchBar previews and unlabeled FilterSearch sections.
  • Avoid announcing FilterSearch result counts until an actual filter-search response exists.
  • Correct the plural result-preview translation from “recent previews” to “result previews.”
  • Make Enter consistently submit and select the active option’s value.

Tests:

  • Add ScreenReader coverage for stable nodes, delayed updates, and stale-announcement cancellation.
  • Expand Dropdown tests for combobox state, active descendants, option semantics, selection state, and keyboard behavior.
  • Expand SearchBar and FilterSearch tests for complete accessible names, query preservation, automatic selection, result counts, and one-time instructions.

Known gaps:

  • On the Universal SearchBar page, VoiceOver queues the usage instructions but evicts them when the expanded-listbox and result-count announcements arrive.
  • The current implementation marks instructions as announced even when VoiceOver does not finish speaking them, so they are not retried.
  • The fixed result-announcement delay reduces contention but cannot guarantee speech ordering across browsers, screen readers, or speech rates.
  • Automated DOM and axe tests verify accessibility semantics but cannot confirm the final spoken sequence; manual VoiceOver verification remains required.
  • A follow-up could combine the one-time instructions with the first result count in one atomic announcement.

J=WAT-5482
Mini Demo:

search-ui-react-screenreader-update.mov

@k-gerner
k-gerner requested a review from a team as a code owner July 24, 2026 20:36
@github-actions

github-actions Bot commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

Current unit coverage is 89.46337641989815%
Current visual coverage is 69.28934010152284%
Current combined coverage is 91.88461538461539%

@coveralls

coveralls commented Jul 24, 2026

Copy link
Copy Markdown

Coverage Status

coverage: 84.912% (+0.2%) from 84.727% — screen-reader-rework-5482 into main

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants