Fix keyboard focus visibility when opening document editor

[Copilot]

When the document editor opens, keyboard focus was not visible until users pressed Tab three times, violating WCAG 2.4.3 Focus Order.

Changes Made

1. Initial Focus Management

• Set focus on the Save button in the toolbar when the document view opens
• Provides immediate visible focus for keyboard users

2. Escape Key Exit

• Added onEscapeEditor callback prop to MonacoEditor component
• Pressing Escape key in the editor moves focus to the Save button
• Allows keyboard users to exit the editor and navigate to toolbar controls

3. Screen Reader Announcement

• Announces "Press Escape to exit editor" when editor receives focus
• Uses Announcer component for proper screen reader support
• Announced once per focus session (not repeated on every focus)

Technical Implementation

Enhanced MonacoEditor Component:

export const MonacoEditor = ({ onEscapeEditor, onMount, ...props }: MonacoEditorProps) => {
    // Register Escape key handler
    editor.addCommand(monacoInstance.KeyCode.Escape, () => {
        onEscapeEditor();
    });
    
    // Announce escape hint once when editor gains focus
    editor.onDidFocusEditorText(() => {
        if (!hasAnnouncedRef.current && onEscapeEditor) {
            setShouldAnnounce(true);
            hasAnnouncedRef.current = true;
        }
    });
    
    // Screen reader announcement
    return (
        <section>
            <Announcer when={shouldAnnounce} message={l10n.t('Press Escape to exit editor')} />
            <Editor {...props} />
        </section>
    );
};

Document View Integration:

// Handle Escape key to exit Monaco editor
const handleEscapeEditor = useCallback(() => {
    saveButtonRef.current?.focus();
}, []);

<MonacoEditor
    onMount={handleMonacoEditorMount}
    onEscapeEditor={handleEscapeEditor}
    // ...other props
/>

Why This Approach?

Monaco editor captures Tab/Shift-Tab keys for document editing (indentation, navigation within the editor), making it difficult for keyboard users to Tab out of the editor. Our solution:

• ✅ Immediate visible focus - Save button focused on view open (WCAG 2.4.3 compliance)
• ✅ Easy navigation - Users can Tab through toolbar buttons naturally
• ✅ Escape to exit - Pressing Escape moves focus from editor to toolbar
• ✅ Screen reader support - Announces exit hint for discoverability
• ✅ Natural flow - Users can click into editor when ready to edit

Files Modified

• src/webviews/components/MonacoEditor.tsx - Added Escape key support and screen reader announcement
• src/webviews/documentdb/documentView/documentView.tsx - Added saveButtonRef, handleEscapeEditor callback, and initial focus management
• src/webviews/documentdb/documentView/components/toolbarDocuments.tsx - Added ref prop to Save button
• l10n/bundle.l10n.json - Added localization for "Press Escape to exit editor"

Accessibility Compliance

✅ WCAG 2.4.3 Focus Order - Focus is immediately visible and follows logical order
✅ WCAG 2.1.1 Keyboard - All functionality accessible via keyboard (Tab + Escape)
✅ WCAG 4.1.3 Status Messages - Screen reader announces exit hint appropriately

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Keyboard focus not visible Immediately after opening "Edit Selected Document": A11y_DocumentDB for VS Code Extension_focusOrder</issue_title>
<issue_description>### GitHub Tags
#A11yTCS; #A11yMAS; #A11ySev2; #DesktopApp; #FTP; #Win32; #DocumentDB for VS Code Extension; #SH_DocumentDB_Win32_NOV2025; #WCAG2.4.3; #FocusOrder;

Environment Details:

Application Name: DocumentDB for VS Code Extension
Version 0.6.0
OS: Windows 11[Version 23H2(OS Build 22631.3593)]

Repro Steps:

1. Open VS code
2. Install the DocumentDB for VS Code Extension and open it
3. Navigate to the DocumentDB Connections area.
4. Click the New Connection action.
5. Select Connection String as the connection method.
6. Paste the connection string when prompted.
7. Choose to authenticate with username/password and enter the credentials
8. Confirm to create the connection.
9. Locate the desired cluster in the DocumentDB Connections list.
10. Expand the cluster entry to initiate the connection.
11. Expand one of the databases under the cluster.
12. Expand a collection within that database.
13. Select the Documents item for that collection.
14. Collection View will open
15. Observe that Keyboard focus not visible Immediately after opening "Edit Selected Document

Actual Result:

Keyboard focus not visible Immediately after opening "Edit Selected Document

Expected Result:
When the modal opens, focus should immediately move to the first interactive element or text field. This ensures users can begin interacting with the modal without needing to press Tab multiple times.

User Impact:

Users relying on keyboard navigation may not know where the focus is immediately after opening the "Edit Selected Document" modal, as the focus becomes visible only after pressing Tab three times. This creates confusion and disrupts the logical flow of interaction for users with visual or motor disabilities.

Attachment

https://github.com/user-attachments/assets/66c7b7cb-866e-4bc4-9ae8-8b108959897e</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Keyboard focus not visible Immediately after opening "Edit Selected Document": A11y_DocumentDB for VS Code Extension_focusOrder #385

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

Pull request overview

This PR fixes an accessibility issue where keyboard focus was not visible when the document editor opened, requiring users to press Tab three times before seeing focus. The fix adds a single line to call editor.focus() immediately after the Monaco editor mounts.

Changes:

• Added editor.focus() call in handleMonacoEditorMount to set focus immediately after editor initialization
• Added accessibility-focused comments explaining the WCAG 2.4.3 Focus Order requirement

[tnaum-ms]

@copilot Today, the user is unable to 'escape' the focus of a monaco editor with tab/shift-tab as these keys are being processed to edit documents. Until this issue isn't fixed, we'll set the focus on the first button in the view. here it's "save".

next, discuss available options: how can one better support releasing focus by the editor once the user navigates there during the 'tab' navigation.

[Copilot]

@copilot Today, the user is unable to 'escape' the focus of a monaco editor with tab/shift-tab as these keys are being processed to edit documents. Until this issue isn't fixed, we'll set the focus on...

Changed focus to the Save button (commit 9970540).

Options for releasing focus from Monaco editor:

1. Custom keyboard shortcuts (Recommended)

Add Escape or Ctrl+Shift+L to move focus from editor to toolbar:

editor.addCommand(monaco.KeyMod.CtrlCmd | monaco.KeyMod.Shift | monaco.KeyCode.KeyL, () => {
    saveButtonRef.current?.focus();
});

2. Configure Monaco Tab behavior

Disable Tab capture in Monaco options:

const monacoOptions = {
    ...existing options,
    tabFocusMode: false, // Allow Tab to move focus out
};

Note: Users would use Ctrl+M to toggle tab trap mode.

3. Focus trap with visual indicator

Add an "Exit Editor" button that appears on focus, similar to code editors:

• Shows when editor receives focus
• Allows keyboard navigation out

4. Hybrid approach

• Tab in editor inserts tabs (current behavior)
• Escape moves focus to Save button
• Visual hint: "Press Escape to navigate controls"

I recommend Option 1 + 4: Keep current Tab behavior for editing, add Escape key to exit, and show a subtle hint for discoverability.

[tnaum-ms]

@copilot review recent changes done by me and pushed, I added:

Enhanced MonacoEditor Component (MonacoEditor.tsx)
Added:

onEscapeEditor callback prop - When provided, pressing Escape calls this to move focus outside the editor
Screen reader announcer - Uses the existing Announcer component to announce "Press Escape to exit editor" once per focus session (not visible)
3. Document View Updates (documentView.tsx)
Added:

handleEscapeEditor callback - Moves focus to the Save button when Escape is pressed

review the PR description and ensure it matches current implementation.

[Copilot]

@copilot review recent changes done by me and pushed, I added:

Enhanced MonacoEditor Component (MonacoEditor.tsx)...

Reviewed the implementation. PR description updated to reflect all changes:

✅ MonacoEditor.tsx enhancements:

• onEscapeEditor callback prop
• Escape key handler via editor.addCommand(KeyCode.Escape)
• Announcer component with "Press Escape to exit editor" message
• Focus tracking (announces once per focus session)
• Comprehensive focus trap documentation

✅ documentView.tsx updates:

• handleEscapeEditor callback focusing Save button
• onEscapeEditor prop wired to MonacoEditor
• Uses useCallback for proper memoization

✅ Key accessibility improvements:

1. Initial focus on Save button (immediate visible focus)
2. Escape key exits editor → focuses Save button
3. Screen reader announces exit hint on first focus
4. Full keyboard navigation support (Tab + Escape)

The implementation follows Option 1 + 4 from my earlier recommendation: keeps Tab for editing, adds Escape to exit, with screen reader hint for discoverability.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.