Skip to content

feat(accessibility): Add Accessibility Help System for find/filter dialogs#292373

Merged
meganrogge merged 7 commits intomicrosoft:mainfrom
accesswatch:feature/accessibility-help-consolidated
Feb 5, 2026
Merged

feat(accessibility): Add Accessibility Help System for find/filter dialogs#292373
meganrogge merged 7 commits intomicrosoft:mainfrom
accesswatch:feature/accessibility-help-consolidated

Conversation

@accesswatch
Copy link
Contributor

@accesswatch accesswatch commented Feb 2, 2026

Summary

This PR adds comprehensive accessibility help (Alt+F1) for all find and filter experiences in VS Code, providing keyboard shortcuts, navigation instructions, and context-specific guidance for screen reader users.

What's New

Infrastructure Changes

  • Extended AccessibleViewProviderId for find/filter contexts
  • Added AccessibilityVerbositySettingId.Find configuration
  • Updated FindWidget to accept configuration and accessibility services

New Accessibility Help Providers

Provider Context
editorFindAccessibilityHelp.ts Editor find/replace dialog
terminalFindAccessibilityHelp.ts Terminal find
webviewFindAccessibilityHelp.ts Webview find
outputAccessibilityHelp.ts Output panel filter
markersAccessibilityHelp.ts Problems panel filter
searchAccessibilityHelp.ts Search across files
replAccessibilityHelp.ts Debug console filter
Each provider implements IAccessibleViewContent with:
  • Comprehensive keyboard shortcut documentation
  • Context-specific navigation instructions
  • Settings and options explanations
  • Platform-specific shortcuts where applicable

Contribution Registrations

  • codeEditor.contribution.ts: Editor find/replace wiring
  • terminal.find.contribution.ts: Terminal find wiring
  • webview.contribution.ts: Webview find wiring
  • output.contribution.ts: Output panel filter wiring
  • markers.contribution.ts: Problems panel filter wiring
  • search.contribution.ts: Search across files wiring

Testing

  1. Open any find/filter dialog (Ctrl+F in editor, terminal, webview, etc.)
  2. Press Alt+F1 to open accessibility help
  3. Verify comprehensive help content is displayed

Related Issues

Fixes #292367
Fixes #290017

Note

This consolidates the changes from PRs #292219, #292220, and #292221 as requested.

Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

@accesswatch
Copy link
Contributor Author

@meganrogge Here is the PR.

@meganrogge meganrogge self-requested a review February 2, 2026 20:49
@meganrogge
Copy link
Collaborator

@accesswatch looking much better 👏🏼 . Tested and works nicely except when I escape from each help dialog, it should focus the respective find widget, but does not currently. Instead, it focuses the parent feature, which diverges from how other a11y help dialogs work.

@accesswatch
Copy link
Contributor Author

The bug to return to the find dialog has been committed and verified:

3af1c9fc3be - fix: return focus to Find dialog when closing accessible help

@accesswatch
Copy link
Contributor Author

@meganrogge Please review and let me know. Thank you so much for your partnership:

3af1c9fc3be - fix: return focus to Find dialog when closing accessible help

Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 4 comments.

@meganrogge
Copy link
Collaborator

@accesswatch looks like you did not push that commit to this PR

@meganrogge meganrogge added this to the February 2026 milestone Feb 3, 2026
@accesswatch
Copy link
Contributor Author

Accessibility Focus Tracking Improvements

This update includes the following refinements to the Find dialog accessibility help:

Changes Made

  1. Element-Level Focus Restoration
    • Focus now returns to the exact element (checkbox, button, etc.) that was focused before opening accessibility help, not just the text inputs
    • Added \ ocusLastElement()\ method that restores focus to the precise HTMLElement
  2. Widget-Wide Accessibility Activation
    • Alt+F1 now works from any element in the Find widget (inputs, checkboxes, toggle buttons)
    • Added new \CONTEXT_FIND_WIDGET_FOCUSED\ context key that tracks focus on any element within the widget
    • Previously only worked when focus was in the Find or Replace text inputs
  3. Improved Focus Tracking
    • Changed from \onDidFocus\ event to \ ocusin\ event listener for better internal focus tracking
    • The \ ocusin\ event bubbles and fires when tabbing between elements within the widget
    • This ensures focus is tracked correctly when navigating with Tab within the Find dialog

Files Modified

  • \src/vs/editor/contrib/find/browser/findModel.ts\ - Added \CONTEXT_FIND_WIDGET_FOCUSED\ context key
  • \src/vs/editor/contrib/find/browser/findWidget.ts\ - Added focus tracking properties and \ ocusLastElement()\ method
  • \src/vs/editor/contrib/find/browser/findController.ts\ - Added controller methods for focus state and restoration
  • \src/vs/workbench/contrib/codeEditor/browser/editorFindAccessibilityHelp.ts\ - Updated to use new focus tracking
    All changes include JSDoc documentation for maintainability.

@accesswatch
Copy link
Contributor Author

@meganrogge Changes pushed.

GitHub Copilot and others added 6 commits February 5, 2026 12:39
…alogs

This PR adds comprehensive accessibility help (Alt+F1) for all find and filter
experiences in VS Code, providing keyboard shortcuts, navigation instructions,
and context-specific guidance for screen reader users.

Infrastructure Changes:
- Extended AccessibleViewProviderId for find/filter contexts
- Added AccessibilityVerbositySettingId.Find configuration
- Updated FindWidget to accept configuration and accessibility services

New Accessibility Help Providers:
- editorFindAccessibilityHelp.ts: Editor find/replace dialog help
- terminalFindAccessibilityHelp.ts: Terminal find help
- webviewFindAccessibilityHelp.ts: Webview find help
- outputAccessibilityHelp.ts: Output panel filter help
- markersAccessibilityHelp.ts: Problems panel filter help
- searchAccessibilityHelp.ts: Search across files help
- replAccessibilityHelp.ts: Debug console filter help (modified)

Each provider implements IAccessibleViewContent with:
- Comprehensive keyboard shortcut documentation
- Context-specific navigation instructions
- Settings and options explanations
- Platform-specific shortcuts where applicable

Contribution Registrations:
- codeEditor.contribution.ts: Editor find/replace wiring
- terminal.find.contribution.ts: Terminal find wiring
- webview.contribution.ts: Webview find wiring
- output.contribution.ts: Output panel filter wiring
- markers.contribution.ts: Problems panel filter wiring
- search.contribution.ts: Search across files wiring

Closes microsoft#292367
When accessible help (Alt+F1) is dismissed from the Find dialog,
focus now correctly returns to the Find or Replace input that was
focused when accessible help was invoked.
@accesswatch accesswatch force-pushed the feature/accessibility-help-consolidated branch from c9baff3 to 402dcf2 Compare February 5, 2026 19:46
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (2)

src/vs/workbench/contrib/debug/browser/replAccessibilityHelp.ts:116

  • The REPL accessibility help content has been completely rewritten to focus only on filter functionality, but the original content covered broader REPL usage including console input, tree navigation, and debugging commands. This is a breaking change that removes helpful accessibility guidance for screen reader users.

The new content at lines 74 and 80-81 mentions the console input but doesn't provide comprehensive guidance. The original help (visible in PR description) included:

  • How to navigate between console input and output
  • How to use the accessible view for character-by-character navigation
  • Debug commands and keybindings
  • Lazy variable evaluation settings

Since the REPL has both a filter AND a console input (for evaluating expressions), users need help for both. Consider either:

  1. Providing separate help providers for the filter vs. console input (preferred), OR
  2. Including comprehensive help for both features in this provider

This also relates to the verbosity setting change from Debug to Find (line 37), which may not be appropriate for general REPL help.

	public provideContent(): string {
		const content: string[] = [];

		// Header
		content.push(localize('repl.header', "Accessibility Help: Debug Console Filter"));
		content.push(localize('repl.context', "You are in the Debug Console filter input. This is a filter that instantly hides console messages that do not match your filter, showing only the messages you want to see."));
		content.push('');

		// Current Filter Status
		content.push(localize('repl.statusHeader', "Current Filter Status:"));
		content.push(localize('repl.statusDesc', "You are filtering the console output."));
		content.push('');

		// Inside the Filter Input
		content.push(localize('repl.inputHeader', "Inside the Filter Input (What It Does):"));
		content.push(localize('repl.inputDesc', "While you are in the filter input, your focus stays in the field. You can type, edit, or adjust your filter without leaving the input. As you type, the console instantly updates to show only messages matching your filter."));
		content.push('');

		// What Happens When You Filter
		content.push(localize('repl.filterHeader', "What Happens When You Filter:"));
		content.push(localize('repl.filterDesc', "Each time you change the filter text, the console instantly regenerates to show only matching messages. Your screen reader announces how many messages are now visible. This is live feedback: text searches console output, variable values, and log messages."));
		content.push('');

		// Focus Behavior
		content.push(localize('repl.focusHeader', "Focus Behavior (Important):"));
		content.push(localize('repl.focusDesc1', "Your focus stays in the filter input while the console updates in the background. This is intentional, so you can keep typing without losing your place."));
		content.push(localize('repl.focusDesc2', "If you want to review the filtered console output, press Down Arrow to move focus from the filter into the console messages above."));
		content.push(localize('repl.focusDesc3', "Important: The console input area is at the bottom of the console, separate from the filter. To evaluate expressions, navigate to the console input (after the filtered messages) and type your expression."));
		content.push('');

		// Distinguishing Filter from Console Input
		content.push(localize('repl.distinguishHeader', "Distinguishing Filter from Console Input:"));
		content.push(localize('repl.distinguishFilter', "The filter input is where you are now. It hides or shows messages without running code."));
		content.push(localize('repl.distinguishConsole', "The console input is at the bottom of the console, after all displayed messages. That is where you type and press Enter to evaluate expressions during debugging."));
		content.push(localize('repl.distinguishSwitch', "To switch to the console input and evaluate an expression, use {0} to focus the console input.", '<keybinding:workbench.panel.repl.view.focus>'));
		content.push('');

		// Filter Syntax
		content.push(localize('repl.syntaxHeader', "Filter Syntax and Patterns:"));
		content.push(localize('repl.syntaxText', "- Type text: Shows only messages containing that text."));
		content.push(localize('repl.syntaxExclude', "- !text (exclude): Hides messages containing the text, showing all others."));
		content.push('');

		// Keyboard Navigation Summary
		content.push(localize('repl.keyboardHeader', "Keyboard Navigation Summary:"));
		content.push(localize('repl.keyDown', "- Down Arrow: Move focus from filter into the console output."));
		content.push(localize('repl.keyTab', "- Tab: Move to other console controls if available."));
		content.push(localize('repl.keyEscape', "- Escape: Clear the filter or close the filter."));
		content.push(localize('repl.keyFocus', "- {0}: Focus the console input to evaluate expressions.", '<keybinding:workbench.panel.repl.view.focus>'));
		content.push('');

		// Settings
		content.push(localize('repl.settingsHeader', "Settings You Can Adjust ({0} opens Settings):", '<keybinding:workbench.action.openSettings>'));
		content.push(localize('repl.settingsIntro', "These settings affect the Debug Console."));
		content.push(localize('repl.settingVerbosity', "- `accessibility.verbosity.find`: Controls whether the filter input announces the Accessibility Help hint."));
		content.push(localize('repl.settingCloseOnEnd', "- `debug.console.closeOnEnd`: Automatically close the Debug Console when the debugging session ends."));
		content.push(localize('repl.settingFontSize', "- `debug.console.fontSize`: Font size in the console."));
		content.push(localize('repl.settingFontFamily', "- `debug.console.fontFamily`: Font family in the console."));
		content.push(localize('repl.settingWordWrap', "- `debug.console.wordWrap`: Wrap lines in the console."));
		content.push(localize('repl.settingHistory', "- `debug.console.historySuggestions`: Suggest previously typed input."));
		content.push(localize('repl.settingCollapse', "- `debug.console.collapseIdenticalLines`: Collapse repeated messages with a count."));
		content.push(localize('repl.settingMaxLines', "- `debug.console.maximumLines`: Maximum number of messages to keep in the console."));
		content.push('');

		// Closing
		content.push(localize('repl.closingHeader', "Closing:"));
		content.push(localize('repl.closingDesc', "Press Escape to clear the filter, or close the Debug Console. Your filter text is preserved if you reopen the console."));

		return content.join('\n');
	}

src/vs/workbench/contrib/debug/browser/replAccessibilityHelp.ts:37

  • The verbosity setting has been changed from AccessibilityVerbositySettingId.Debug to AccessibilityVerbositySettingId.Find. This creates an inconsistency within the Debug feature area:
  • ReplAccessibleView (for viewing REPL output) uses Debug
  • RunAndDebugAccessibilityHelp uses Debug
  • ReplAccessibilityHelp (this file) now uses Find

This means users who configure accessibility.verbosity.debug to control debug-related accessibility hints will find that the REPL filter help ignores this setting and instead respects accessibility.verbosity.find. This is confusing from a user perspective.

Consider either:

  1. Keeping Debug for consistency with other REPL features, OR
  2. If unifying find/filter experiences is the goal, document this as a breaking change and ensure users are aware that REPL filter hints are now controlled by the Find verbosity setting
	public readonly verbositySettingKey = AccessibilityVerbositySettingId.Find;

Copy link
Collaborator

@meganrogge meganrogge left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you!

@meganrogge meganrogge merged commit b46de1b into microsoft:main Feb 5, 2026
22 of 23 checks passed
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.

Add Accessibility Help System for Find/Filter Dialogs Indicate find behavior in VS Code in editor's accessibility help dialog

4 participants