Skip to content

Fix/a11y speak queue#79883

Draft
pranvinit wants to merge 2 commits into
WordPress:trunkfrom
pranvinit:fix/a11y-speak-queue
Draft

Fix/a11y speak queue#79883
pranvinit wants to merge 2 commits into
WordPress:trunkfrom
pranvinit:fix/a11y-speak-queue

Conversation

@pranvinit

Copy link
Copy Markdown
Contributor

What?

Closes #79561

Improves @wordpress/a11y speak() reliability by queueing polite announcements and adding a short clear-fill delay before writing them to the live region.

Why?

speak() previously cleared and filled live regions synchronously. In Safari with VoiceOver, that can cause announcements to be missed because the cleared and filled states may be batched into one accessibility tree update.

It also meant rapid polite announcements could be dropped, since each new speak() call immediately cleared and overwrote the previous message before assistive technology had a chance to process it.

How?

  • Adds an internal polite announcement queue in packages/a11y/src/shared/queue.ts.
  • Polite announcements now:
    • clear the polite live region,
    • wait briefly before filling it,
    • preserve FIFO order for rapid calls.
  • Assertive announcements remain synchronous so urgent messages still interrupt immediately.
  • Keeps the public speak( message, ariaLive? ) API unchanged.
  • Updates @wordpress/a11y tests for async polite behavior, queue ordering, and assertive/polite channel independence.
  • Updates affected tests that assert polite live-region output.
  • Documents the behavior change in the package README and changelog.

Testing Instructions

  1. Run:
    npm run test:unit packages/a11y
  2. Run:
    npm run test:unit packages/a11y packages/components/src/combobox-control/test/index.tsx packages/ui/src/notice/test/index.test.tsx
  3. Run:
    npm run test:unit packages/components/src/form-token-field/test/index.tsx packages/components/src/tools-panel/test/index.tsx
  4. In Safari with VoiceOver enabled, open the editor.
  5. Trigger multiple polite announcements quickly, for example from the console:
    wp.a11y.speak( 'Step 1 complete' );
    wp.a11y.speak( 'Step 2 complete' );
    wp.a11y.speak( 'Step 3 complete' );
  6. Confirm all three polite announcements are spoken in order.
  7. Trigger an assertive announcement:
    wp.a11y.speak( 'Important message', 'assertive' );
  8. Confirm the assertive announcement is spoken immediately.

Testing Instructions for Keyboard

No UI or keyboard interaction changes are introduced. Existing keyboard flows should behave the same.

Screenshots or screencast

Not applicable. This is an internal accessibility announcement behavior change.

Use of AI Tools

This PR was developed with assistance from OpenAI Codex. Codex was used to inspect the issue and codebase, implement the patch, update tests and documentation, and run focused verification. I reviewed the generated changes and am responsible for the final code.

@github-actions github-actions Bot added [Package] A11y /packages/a11y [Package] Components /packages/components [Package] UI /packages/ui labels Jul 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Package] A11y /packages/a11y [Package] Components /packages/components [Package] UI /packages/ui

Projects

None yet

Development

Successfully merging this pull request may close these issues.

@wordpress/a11y: speak() misses announcements on VoiceOver due to synchronous clear+fill, and drops polite messages during rapid calls

1 participant