facebook / facebook/docusaurus
Single page app (SPA) route navigations sometimes not announced by screen readers (NVDA, VoiceOver)
- Dominant language
- TypeScript
- Stars
- 66.2k
- Forks
- 10k
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 52
Description
### Have you read the Contributing Guidelines on issues?
- [x] I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#issues).
### Prerequisites
- [x] I'm using the latest version of Docusaurus.
- [x] I have tried the `npm run clear` or `yarn clear` command.
- [x] I have tried `rm -rf node_modules yarn.lock package-lock.json` and re-installing packages.
- [x] I have tried creating a repro with https://new.docusaurus.io.
- [x] I have read the console error message carefully (if applicable).
### Description
I believe Docusaurus is a single page app (SPA). When internal links are invoked, the history API is used to update the browser's URL bar. This unfortunately doesn't come with out-of-the-box accessibility support https://www.matuzo.at/blog/2023/single-page-applications-criticism/. The new [Navigation API](https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API) _should_ be better but not ready for prime time yet 🤞🏻
As a result, here's NVDA invoking the "Community" link in the top nav. I'm tabbing to the link, then press Enter to invoke. NVDA announces nothing.
https://github.com/user-attachments/assets/16960c37-aaac-49b4-89b9-323071c3ffde
macOS VoiceOver is a little inconsistent. I'm again tabbing to the link. First I'm using Enter to invoke. VoiceOver consistently announces nothing. But VO+Space is another common way to invoke links/buttons. VoiceOver sometimes announces the document title in that case, it seems inconsistent.
https://github.com/user-attachments/assets/6819e9a8-7346-4ac3-b271-8a3e16a8c0d4
FWIW there's a bit of debate as to whether this is is a WCAG [4.1.3 Status Messages](https://www.w3.org/TR/WCAG22/#status-messages) failure (does it fit the [definition of a status message](https://www.w3.org/TR/WCAG22/#dfn-status-messages)?).
### Reproducible demo
https://docusaurus.io/
### Steps to reproduce
1. With NVDA (and Chrome in my testing), visit docusaurus.io
2. Tab to a link in the top navigation
3. Press Enter
### Expected behavior
There's a bit of debate on this (see linked blog posts), but I'd argue that since this is basically a MPA (multi page app) navigation, the MPA UX should be mimicked. In a standard MPA nav, NVDA will announce `" document"` when the page is fully loaded.
Note that slower network connections should be considered — the user needs to be aware when the page is fully rendered and ready for interaction. It'd also be nice if they were informed while loading was still taking place. I know the History API doesn't give many options for this, IIRC the Navigation API has the necessary hooks.
### Actual behavior
NVDA announces nothing.
### Your environment
N/A
### Self-service
- [ ] I'd be willing to fix this bug myself.
Contributor guide
Assessment
This issue has not been assessed yet.