microsoft / microsoft/vscode-documentdb

Announce DocumentDB Local tree state transitions to screen readers

Open
#878 0 comments 0 reactions 0 assignees View on GitHub

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 mutates description and iconPath in 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.showInformationMessage is 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.