microsoft / microsoft/vscode-documentdb
Announce DocumentDB Local tree state transitions to screen readers
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 31
- Forks
- 22
- Avg merge
- 2d 20h
- Merged PRs (30d)
- 21
Description
Problem
The DocumentDB Local row in the Connections view changes state on its own — provisioning finishes, a container starts or stops, a background probe corrects a stale Running. A sighted user sees the row redraw. A screen reader user gets nothing: VS Code does not announce a TreeItem description or icon change, and the extension does not announce it either.
This was recorded as item 26 of the DocumentDB Local UX review (PR #790) and deferred as "post-redesign".
Why now
The redesign is done, and #876 changed the mechanism in a way that makes this more relevant, not less:
- Transitional states used to swap the whole row. They now apply the tree framework's node-progress overlay (
ext.state.runWithTemporaryDescription), which mutatesdescriptionandiconPathin place. - An in-place mutation is exactly the case a screen reader is least likely to surface on its own.
So the states a user most needs to hear about — "starting", "stopping", "provisioning", "refreshing", and the terminal state that follows — are now the quietest ones.
Scope to investigate
- Which transitions are worth announcing, and which would be noise. A background freshness probe firing every time the view re-renders must not announce anything.
- The right mechanism:
vscode.window.showInformationMessageis wrong (too heavy), an ARIA live region is a webview concept and does not apply to the tree. Options worth checking:vscode.window.setStatusBarMessage, an accessibility-specific announcement API if one exists for tree views, or accepting that the terminal state notification is the announcement. - Whether the same gap exists for other long-running tree operations in the extension (deleting a collection, importing documents) — if so this is a shared fix, not a Quick Start one.
- Verify with an actual screen reader (NVDA / VoiceOver) rather than by reasoning about the API.
Out of scope
Webview accessibility. The Quick Start setup panel is a separate surface with its own announcer.
References
- UX review item 26 — PR #790
- Progress overlay and the bridge — #876,
src/tree/connections-view/LocalQuickStart/quickStartProgressBridge.ts
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with src/tree/connections-view/LocalQuickStart/quickStartProgressBridge.ts and trace how progress overlays mutate the tree node, then inspect related long-running tree operations and the available VS Code announcement APIs. Determine which transitions should be announced without background-refresh noise, implement the selected mechanism, and verify the result with NVDA or VoiceOver.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- accessibility
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 45/100