Merge pull request #1368 from mathuo/feat/a11y-popout-live-region

feat(dockview-core): cross-window accessibility for popout windows

Author: mathuo

e2e/fixtures/index.html

@@ -65,13 +65,16 @@
                 dockview.layout(el.clientWidth, el.clientHeight);
 
                 // Test-facing handle.
+                const panels = {};
                 window.__dv = {
-                    addPanel: (id) =>
-                        dockview.addPanel({
+                    addPanel: (id) => {
+                        panels[id] = dockview.addPanel({
                             id,
                             component: 'default',
                             title: id,
-                        }),
+                        });
+                    },
+                    closePanel: (id) => panels[id] && panels[id].api.close(),
                     popoutActiveGroup: () =>
                         dockview.addPopoutGroup(dockview.activeGroup),
                     groupCount: () => dockview.groups.length,

e2e/tests/keyboard-docking.spec.ts

@@ -0,0 +1,75 @@
+import { test, expect, Page } from '@playwright/test';
+
+/**
+ * Cross-window keyboard docking: the keyboard services attach their listeners to
+ * each popout document and gate on `ownsElement`, so `Ctrl+M` docking can be
+ * driven from *inside* a popped-out window — and its narration routes to that
+ * window's live region. None of this is reachable in jsdom (the mock popout
+ * shares the main document, so there is no second window to listen on).
+ */
+test.describe('cross-window keyboard docking', () => {
+    const popout = async (page: Page, context) => {
+        await page.goto('/e2e/fixtures/index.html');
+        await page.waitForFunction(() => (window as any).__ready === true);
+        await page.evaluate(() => {
+            (window as any).__dv.addPanel('alpha');
+            (window as any).__dv.addPanel('beta'); // beta active, same group
+        });
+        const [win] = await Promise.all([
+            context.waitForEvent('page'),
+            page.evaluate(() => (window as any).__dv.popoutActiveGroup()),
+        ]);
+        await (win as Page).waitForLoadState();
+        return win as Page;
+    };
+
+    test('Ctrl+M inside a popout narrates into the popout and Esc cancels there', async ({
+        page,
+        context,
+    }) => {
+        const win = await popout(page, context);
+
+        // Activate + focus a panel in the popout, then arm keyboard docking
+        // with a keystroke made *in the popout document*.
+        await win.locator('.dv-test-panel').first().click();
+        await win.keyboard.press('Control+m');
+
+        // The keydown was seen by the popout's own listener (not the opener's),
+        // passed the cross-document `ownsElement` gate, and the narration routed
+        // to the popout's live region.
+        await expect(win.locator('.dv-live-region')).toContainText(
+            'Moving beta'
+        );
+
+        await win.keyboard.press('Escape');
+        await expect(win.locator('.dv-live-region')).toHaveText(
+            'Move cancelled.'
+        );
+    });
+
+    test('a keyboard split committed inside a popout acts on the popout group', async ({
+        page,
+        context,
+    }) => {
+        const win = await popout(page, context);
+
+        // Popping out leaves a placeholder group in the main grid, so capture
+        // the starting count rather than assume it.
+        const before = await page.evaluate(() =>
+            (window as any).__dv.groupCount()
+        );
+
+        await win.locator('.dv-test-panel').first().click();
+        await win.keyboard.press('Control+m'); // arm: target = own group
+        await win.keyboard.press('Enter'); // choose this group -> edge phase
+        await win.keyboard.press('ArrowLeft'); // left edge (split)
+        await win.keyboard.press('Enter'); // commit
+
+        // The split ran inside the popout's own gridview: beta is now its own
+        // group, so the component reports exactly one more group than before.
+        await expect
+            .poll(() => page.evaluate(() => (window as any).__dv.groupCount()))
+            .toBe(before + 1);
+        await expect(win.locator('.dv-live-region')).toContainText('beta');
+    });
+});

e2e/tests/live-region.spec.ts

@@ -0,0 +1,58 @@
+import { test, expect, Page } from '@playwright/test';
+
+/**
+ * Per-window live regions: a popout window gets its own aria-live regions, and
+ * announcements route to the window that currently has focus — so a screen
+ * reader user working in a popout actually hears them. None of this is
+ * expressible in jsdom (the mock popout shares the main document).
+ */
+test.describe('cross-window live regions', () => {
+    const popout = async (page: Page, context) => {
+        await page.goto('/e2e/fixtures/index.html');
+        await page.waitForFunction(() => (window as any).__ready === true);
+        await page.evaluate(() => {
+            (window as any).__dv.addPanel('alpha');
+            (window as any).__dv.addPanel('beta'); // beta active, same group
+        });
+        const [win] = await Promise.all([
+            context.waitForEvent('page'),
+            page.evaluate(() => (window as any).__dv.popoutActiveGroup()),
+        ]);
+        await (win as Page).waitForLoadState();
+        return win as Page;
+    };
+
+    test('a popout window has its own polite and assertive regions', async ({
+        page,
+        context,
+    }) => {
+        const win = await popout(page, context);
+
+        await expect(win.locator('.dv-live-region')).toHaveCount(1);
+        await expect(win.locator('.dv-live-region-assertive')).toHaveCount(1);
+    });
+
+    test('announcements route to the focused popout, not the opener', async ({
+        page,
+        context,
+    }) => {
+        const win = await popout(page, context);
+
+        // Put focus in the popout, then close a panel there. The "closed"
+        // announcement must land in the popout's region, not the opener's.
+        await win.locator('.dv-test-panel').first().focus();
+        await page.evaluate(() => (window as any).__dv.closePanel('beta'));
+
+        // The close lands in the popout's region...
+        await expect(win.locator('.dv-live-region')).toHaveText('beta closed');
+        // ...and never leaks into the opener's region. (The opener's region
+        // still holds the earlier "opened in a new window" note, which routed
+        // to it because the main window had focus at popout time.)
+        await expect(page.locator('.dv-live-region')).not.toHaveText(
+            'beta closed'
+        );
+        await expect(page.locator('.dv-live-region')).toHaveText(
+            'beta opened in a new window'
+        );
+    });
+});

packages/dockview-core/src/__tests__/dockview/liveRegion.spec.ts

@@ -255,6 +255,22 @@ describe('LiveRegion announcer', () => {
         expect(region().textContent).toBe('P2 opened in a new window');
     });
 
+    test('a popout sharing the document does not get a duplicate region', async () => {
+        window.open = () => setupMockWindow();
+        dockview.addPanel({ id: 'p1', component: 'default', title: 'P1' });
+        const p2 = dockview.addPanel({
+            id: 'p2',
+            component: 'default',
+            title: 'P2',
+        });
+        await dockview.addPopoutGroup(p2);
+        // The mock popout reuses the main document, so per-window mounting is
+        // skipped — there is still exactly one polite region and announcements
+        // stay on it. (Real cross-document behaviour is covered by the e2e.)
+        expect(container.querySelectorAll('.dv-live-region')).toHaveLength(1);
+        expect(region().textContent).toBe('P2 opened in a new window');
+    });
+
     test('the messages catalog localises announcement strings', () => {
         dockview.dispose();
         container = document.createElement('div');

packages/dockview-core/src/__tests__/dockview/ownsElement.spec.ts

@@ -0,0 +1,96 @@
+import { DockviewComponent } from '../../dockview/dockviewComponent';
+import { IContentRenderer } from '../../dockview/types';
+
+class TestPanel implements IContentRenderer {
+    element = document.createElement('div');
+    init(): void {
+        // noop
+    }
+    layout(): void {
+        // noop
+    }
+    dispose(): void {
+        // noop
+    }
+}
+
+/**
+ * `ownsElement` is the cross-document containment primitive the keyboard
+ * accessibility services use instead of a single-document `rootElement.contains`
+ * — so a keydown / focus inside a popped-out window (a separate `document`) is
+ * still recognised as belonging to this dock. jsdom can't open a real second
+ * window, so the popout document is simulated by stubbing `getPopoutWindows`.
+ */
+describe('DockviewComponent.ownsElement', () => {
+    let container: HTMLElement;
+    let dockview: DockviewComponent;
+
+    beforeEach(() => {
+        container = document.createElement('div');
+        document.body.appendChild(container);
+        dockview = new DockviewComponent(container, {
+            createComponent: () => new TestPanel(),
+        });
+        dockview.layout(800, 600);
+    });
+
+    afterEach(() => {
+        dockview.dispose();
+        container.remove();
+    });
+
+    test('owns an element inside its own shell', () => {
+        dockview.addPanel({ id: 'panel1', component: 'default' });
+        const tab = container.querySelector('.dv-tab')!;
+        expect(dockview.ownsElement(tab)).toBe(true);
+        expect(dockview.ownsElement(dockview.element)).toBe(true);
+    });
+
+    test('does not own an element in the main document outside the dock', () => {
+        const stray = document.createElement('div');
+        document.body.appendChild(stray);
+        expect(dockview.ownsElement(stray)).toBe(false);
+        stray.remove();
+    });
+
+    test('does not own a foreign-document element with no matching popout', () => {
+        const foreignDoc =
+            document.implementation.createHTMLDocument('foreign');
+        const node = foreignDoc.createElement('div');
+        foreignDoc.body.appendChild(node);
+        expect(dockview.ownsElement(node)).toBe(false);
+    });
+
+    test('owns an element in a popout document it controls', () => {
+        const popoutDoc = document.implementation.createHTMLDocument('popout');
+        const node = popoutDoc.createElement('div');
+        popoutDoc.body.appendChild(node);
+        const popoutWindow = { document: popoutDoc } as unknown as Window;
+
+        jest.spyOn(dockview, 'getPopoutWindows').mockReturnValue([
+            popoutWindow,
+        ]);
+
+        expect(dockview.ownsElement(node)).toBe(true);
+
+        // A node in a *different* foreign document is still not owned.
+        const otherDoc = document.implementation.createHTMLDocument('other');
+        const otherNode = otherDoc.createElement('div');
+        otherDoc.body.appendChild(otherNode);
+        expect(dockview.ownsElement(otherNode)).toBe(false);
+    });
+
+    test('a same-document popout never claims sibling main-document nodes', () => {
+        // The jsdom mock popout shares the main document; ownsElement must fall
+        // back to true containment for it (not blanket-own the whole document).
+        const samedocWindow = { document } as unknown as Window;
+        jest.spyOn(dockview, 'getPopoutWindows').mockReturnValue([
+            samedocWindow,
+        ]);
+
+        const stray = document.createElement('div');
+        document.body.appendChild(stray);
+        expect(dockview.ownsElement(stray)).toBe(false);
+        stray.remove();
+    });
+});

packages/dockview-core/src/dockview/dockviewComponent.ts

@@ -553,6 +553,12 @@ export class DockviewComponent
     readonly onDidRemovePopoutGroup: Event<PopoutGroup> =
         this._onDidRemovePopoutGroup.event;
 
+    private readonly _onDidChangePopouts = new Emitter<void>();
+    /** Fires whenever a popout window opens or closes — i.e. the set of popout
+     *  documents changed. Used by accessibility services that mirror per-window
+     *  state (e.g. a live region in each popout). */
+    readonly onDidChangePopouts: Event<void> = this._onDidChangePopouts.event;
+
     private readonly _onDidOpenPopoutWindowFail = new Emitter<void>();
     readonly onDidOpenPopoutWindowFail: Event<void> =
         this._onDidOpenPopoutWindowFail.event;
@@ -828,6 +834,26 @@ export class DockviewComponent
         return this._shellManager?.element ?? this.element;
     }
 
+    /**
+     * Does this dock own `node`, in any of its windows? True when the node is
+     * inside the main shell, or inside one of this component's popout documents.
+     * A popout window hosts only this component's content, so whole-document
+     * membership is sufficient there; the main document may hold sibling docks,
+     * so it must be a containment check. A same-document popout (the jsdom mock)
+     * is already covered by the main check and contributes nothing.
+     */
+    ownsElement(node: Node): boolean {
+        if (this.rootElement.contains(node)) {
+            return true;
+        }
+        const mainDoc = this.rootElement.ownerDocument;
+        const doc = node.ownerDocument;
+        if (!doc || doc === mainDoc) {
+            return false;
+        }
+        return this.getPopoutWindows().some((win) => win.document === doc);
+    }
+
     /**
      * The next / previous group in gridview (spatial) order, wrapping round.
      * The keyboard accessibility module's focus navigation is built on this
@@ -1094,6 +1120,15 @@ export class DockviewComponent
             this._onDidPopoutGroupPositionChange,
             this._onDidAddPopoutGroup,
             this._onDidRemovePopoutGroup,
+            this._onDidChangePopouts,
+            // Coalesce popout add/remove into a single "the popout set changed"
+            // signal for per-window accessibility state.
+            this._onDidAddPopoutGroup.event(() =>
+                this._onDidChangePopouts.fire()
+            ),
+            this._onDidRemovePopoutGroup.event(() =>
+                this._onDidChangePopouts.fire()
+            ),
             this._onDidOpenPopoutWindowFail,
             this._onDidCreateTabGroup,
             this._onDidDestroyTabGroup,
@@ -1299,6 +1334,12 @@ export class DockviewComponent
         );
     }
 
+    /** The live popout `Window` handles — one per open popout group. The
+     *  narrow surface accessibility services need to mirror per-window state. */
+    getPopoutWindows(): Window[] {
+        return this.getPopouts().map((popout) => popout.window);
+    }
+
     private _doAddPopoutGroup(
         itemToPopout: DockviewPanel | DockviewGroupPanel,
         options?: DockviewPopoutGroupOptionsInternal