Merge pull request #1320 from mathuo/feat/keyboard-directional-focus

mathuo · web-flow · commit 055c07cf7360 · 2026-06-11T19:59:34.000+01:00
feat(dockview-core): spatial keyboard group focus + focus-logic refactor
diff --git a/packages/dockview-core/src/__tests__/dockview/accessibilityDocking.spec.ts b/packages/dockview-core/src/__tests__/dockview/accessibilityDocking.spec.ts
@@ -270,3 +270,113 @@ describe('accessibility: group focus navigation', () => {
         expect(dockview.activeGroup?.id).toBe(before);
     });
 });
+
+/**
+ * Spatial group focus — Ctrl+Shift+Arrow focuses the group geometrically in
+ * that direction. jsdom has no layout, so a clean 2x2 grid is mocked via
+ * getBoundingClientRect.
+ */
+describe('accessibility: spatial group focus', () => {
+    let container: HTMLElement;
+    let dockview: DockviewComponent;
+
+    const make = (): void => {
+        container = document.createElement('div');
+        document.body.appendChild(container);
+        dockview = new DockviewComponent(container, {
+            createComponent: () => new TestPanel(),
+            keyboardNavigation: true,
+        });
+        dockview.layout(200, 200);
+    };
+
+    const groupOf = (panelId: string) =>
+        dockview.groups.find((g) => g.panels.some((p) => p.id === panelId))!;
+
+    const setRect = (panelId: string, left: number, top: number): void => {
+        groupOf(panelId).element.getBoundingClientRect = () =>
+            ({
+                left,
+                top,
+                width: 100,
+                height: 100,
+                right: left + 100,
+                bottom: top + 100,
+                x: left,
+                y: top,
+                toJSON: () => ({}),
+            }) as DOMRect;
+    };
+
+    const grid2x2 = (): void => {
+        dockview.addPanel({ id: 'tl', component: 'default' });
+        dockview.addPanel({
+            id: 'tr',
+            component: 'default',
+            position: { referencePanel: 'tl', direction: 'right' },
+        });
+        dockview.addPanel({
+            id: 'bl',
+            component: 'default',
+            position: { referencePanel: 'tl', direction: 'below' },
+        });
+        dockview.addPanel({
+            id: 'br',
+            component: 'default',
+            position: { referencePanel: 'tr', direction: 'below' },
+        });
+        // pin a clean 2x2 geometry regardless of jsdom's (absent) layout
+        setRect('tl', 0, 0);
+        setRect('tr', 100, 0);
+        setRect('bl', 0, 100);
+        setRect('br', 100, 100);
+    };
+
+    const dir = (key: string): void => {
+        fireEvent.keyDown(dockview.element, {
+            key,
+            ctrlKey: true,
+            shiftKey: true,
+        });
+    };
+
+    afterEach(() => {
+        dockview.dispose();
+        container.remove();
+    });
+
+    test('Ctrl+Shift+Right / Down focus the neighbouring group', () => {
+        make();
+        grid2x2();
+        expect(dockview.groups.length).toBe(4);
+        groupOf('tl').api.setActive();
+        expect(dockview.activeGroup).toBe(groupOf('tl'));
+
+        dir('ArrowRight');
+        expect(dockview.activeGroup).toBe(groupOf('tr'));
+
+        groupOf('tl').api.setActive();
+        dir('ArrowDown');
+        expect(dockview.activeGroup).toBe(groupOf('bl'));
+    });
+
+    test('picks the dominant-axis neighbour, not a diagonal one', () => {
+        make();
+        grid2x2();
+        groupOf('tl').api.setActive();
+
+        // 'right' from top-left must land on top-right, never bottom-right
+        dir('ArrowRight');
+        expect(dockview.activeGroup).toBe(groupOf('tr'));
+        expect(dockview.activeGroup).not.toBe(groupOf('br'));
+    });
+
+    test('does nothing when there is no group in that direction', () => {
+        make();
+        grid2x2();
+        groupOf('tl').api.setActive();
+
+        dir('ArrowLeft'); // nothing to the left of top-left
+        expect(dockview.activeGroup).toBe(groupOf('tl'));
+    });
+});
diff --git a/packages/dockview-core/src/dockview/accessibilityService.ts b/packages/dockview-core/src/dockview/accessibilityService.ts
@@ -26,17 +26,17 @@ export interface IAccessibilityHost {
     readonly rootElement: HTMLElement;
     readonly options: DockviewComponentOptions;
     readonly groups: DockviewGroupPanel[];
+    readonly activeGroup: DockviewGroupPanel | undefined;
     readonly activePanel: IDockviewPanel | undefined;
-    /** Activate the next tab in the focused group (wraps round). */
-    focusNextPanel(): void;
-    /** Activate the previous tab in the focused group (wraps round). */
-    focusPreviousPanel(): void;
-    /** Move focus to the next group (wraps round). */
-    focusNextGroup(): void;
-    /** Move focus to the previous group (wraps round). */
-    focusPreviousGroup(): void;
-    /** Return DOM focus to the active group's content (keeps it inside the dock). */
-    focusActiveContent(): void;
+    /**
+     * The next / previous group in gridview (spatial) order, wrapping round —
+     * the one piece of navigation that needs the grid internals. All other
+     * focus logic lives in the service, using the public group API.
+     */
+    adjacentGroup(
+        group: DockviewGroupPanel,
+        reverse: boolean
+    ): DockviewGroupPanel | undefined;
     showDropPreview(group: DockviewGroupPanel, position: Position): IDisposable;
     announce(message: string): void;
     dockPanel(
@@ -70,6 +70,10 @@ const DEFAULT_KEYMAP: DockviewKeybindings = {
     prevTab: 'ctrl+[',
     focusNextGroup: 'f6',
     focusPrevGroup: 'shift+f6',
+    focusGroupLeft: 'ctrl+shift+arrowleft',
+    focusGroupRight: 'ctrl+shift+arrowright',
+    focusGroupUp: 'ctrl+shift+arrowup',
+    focusGroupDown: 'ctrl+shift+arrowdown',
     dock: 'ctrl+m',
 };
 
@@ -96,7 +100,8 @@ function matchesBinding(e: KeyboardEvent, binding: string): boolean {
  * `keyboardNavigation`, with a rebindable {@link DockviewKeybindings} keymap.
  *
  * - **Switch tab** (`Ctrl+]` / `Ctrl+[`) — cycle the focused group's tabs.
- * - **Focus group** (`F6` / `Shift+F6`) — move focus between groups.
+ * - **Focus group** (`F6` / `Shift+F6` sequential, `Ctrl+Shift+Arrows`
+ *   spatial) — move focus between groups.
  * - **Keyboard docking** (`Ctrl+M`) — arms a two-phase move of the active
  *   panel with a live drop preview + screen-reader narration:
  *     1. PICK TARGET — arrows cycle the groups (incl. the panel's own, so a tab
@@ -105,8 +110,7 @@ function matchesBinding(e: KeyboardEvent, binding: string): boolean {
  *        centre (tab-into); `Enter` commits, `Escape` steps back.
  *   `Escape` from the target phase cancels.
  *
- * Spatial (directional) group focus, float / popout terminals and cross-window
- * focus management are later phases.
+ * Float / popout terminals and cross-window focus management are later phases.
  */
 export class AccessibilityService
     extends CompositeDisposable
@@ -167,17 +171,112 @@ export class AccessibilityService
             this._enterMoveMode(e);
         } else if (matchesBinding(e, keymap.nextTab)) {
             this._consume(e);
-            this.host.focusNextPanel();
+            this._switchTab(false);
         } else if (matchesBinding(e, keymap.prevTab)) {
             this._consume(e);
-            this.host.focusPreviousPanel();
+            this._switchTab(true);
         } else if (matchesBinding(e, keymap.focusNextGroup)) {
             this._consume(e);
-            this.host.focusNextGroup();
+            this._cycleGroup(false);
         } else if (matchesBinding(e, keymap.focusPrevGroup)) {
             this._consume(e);
-            this.host.focusPreviousGroup();
+            this._cycleGroup(true);
+        } else if (matchesBinding(e, keymap.focusGroupLeft)) {
+            this._consume(e);
+            this._focusGroupInDirection('left');
+        } else if (matchesBinding(e, keymap.focusGroupRight)) {
+            this._consume(e);
+            this._focusGroupInDirection('right');
+        } else if (matchesBinding(e, keymap.focusGroupUp)) {
+            this._consume(e);
+            this._focusGroupInDirection('up');
+        } else if (matchesBinding(e, keymap.focusGroupDown)) {
+            this._consume(e);
+            this._focusGroupInDirection('down');
+        }
+    }
+
+    // --- navigation (uses the public group API + the adjacentGroup primitive) ---
+
+    private _switchTab(reverse: boolean): void {
+        const group = this.host.activeGroup;
+        if (!group) {
+            return;
+        }
+        if (reverse) {
+            group.model.moveToPrevious();
+        } else {
+            group.model.moveToNext();
+        }
+        // Keep DOM focus inside the dock: switching hides the previously
+        // focused content, which would otherwise drop focus to <body> and
+        // leave the keymap unable to see the next key.
+        group.model.focusContent();
+    }
+
+    private _cycleGroup(reverse: boolean): void {
+        const current = this.host.activeGroup;
+        const target = current
+            ? this.host.adjacentGroup(current, reverse)
+            : this.host.groups[0];
+        this._focusGroup(target);
+    }
+
+    private _focusGroupInDirection(
+        direction: 'left' | 'right' | 'up' | 'down'
+    ): void {
+        const current = this.host.activeGroup;
+        if (!current || current.api.location.type !== 'grid') {
+            return;
+        }
+        const from = current.element.getBoundingClientRect();
+        const fromX = from.left + from.width / 2;
+        const fromY = from.top + from.height / 2;
+
+        let best: DockviewGroupPanel | undefined;
+        let bestDistance = Number.POSITIVE_INFINITY;
+        for (const group of this.host.groups) {
+            if (group === current || group.api.location.type !== 'grid') {
+                continue;
+            }
+            const rect = group.element.getBoundingClientRect();
+            const dx = rect.left + rect.width / 2 - fromX;
+            const dy = rect.top + rect.height / 2 - fromY;
+            // require the candidate to sit predominantly in the asked-for
+            // direction (dominant axis), so 'left' ignores a group that's
+            // mostly above/below.
+            const inDirection =
+                direction === 'left'
+                    ? dx < 0 && Math.abs(dx) >= Math.abs(dy)
+                    : direction === 'right'
+                      ? dx > 0 && Math.abs(dx) >= Math.abs(dy)
+                      : direction === 'up'
+                        ? dy < 0 && Math.abs(dy) >= Math.abs(dx)
+                        : dy > 0 && Math.abs(dy) >= Math.abs(dx);
+            if (!inDirection) {
+                continue;
+            }
+            const distance = dx * dx + dy * dy;
+            if (distance < bestDistance) {
+                bestDistance = distance;
+                best = group;
+            }
+        }
+
+        this._focusGroup(best);
+    }
+
+    private _focusGroup(target: DockviewGroupPanel | undefined): void {
+        if (!target) {
+            return;
         }
+        target.api.setActive();
+        target.model.focusContent();
+    }
+
+    /** Return DOM focus to the active group's content, keeping it in the dock. */
+    private _restoreFocus(): void {
+        this.host.activeGroup?.model.focusContent();
     }
 
     private _enterMoveMode(e: KeyboardEvent): void {
@@ -213,7 +312,7 @@ export class AccessibilityService
             } else {
                 this._exit();
                 this.host.announce('Move cancelled.');
-                this.host.focusActiveContent();
+                this._restoreFocus();
             }
             return;
         }
@@ -298,7 +397,7 @@ export class AccessibilityService
         }
         // The move re-renders the grid; pull focus back into the dock so the
         // keymap keeps working without a click.
-        this.host.focusActiveContent();
+        this._restoreFocus();
     }
 
     private _describe(position: Position): string {
diff --git a/packages/dockview-core/src/dockview/dockviewComponent.ts b/packages/dockview-core/src/dockview/dockviewComponent.ts
@@ -706,60 +706,28 @@ export class DockviewComponent
         return this._shellManager?.element ?? this.element;
     }
 
-    focusNextPanel(): void {
-        const group = this.activeGroup;
-        if (!group) {
-            return;
-        }
-        group.model.moveToNext();
-        // Keep DOM focus inside the dock: switching hides the previously
-        // focused content, which would otherwise drop focus to <body> and
-        // leave the keymap unable to see the next key.
-        group.model.focusContent();
-    }
-
-    focusPreviousPanel(): void {
-        const group = this.activeGroup;
-        if (!group) {
-            return;
-        }
-        group.model.moveToPrevious();
-        group.model.focusContent();
-    }
-
-    focusNextGroup(): void {
-        this._focusAdjacentGroup(false);
-    }
-
-    focusPreviousGroup(): void {
-        this._focusAdjacentGroup(true);
-    }
-
-    /** Land DOM focus on the active group's content, keeping it inside the dock. */
-    focusActiveContent(): void {
-        this.activeGroup?.model.focusContent();
-    }
-
-    private _focusAdjacentGroup(reverse: boolean): void {
-        const current = this.activeGroup;
+    /**
+     * The next / previous group in gridview (spatial) order, wrapping round.
+     * The keyboard accessibility module's focus navigation is built on this
+     * primitive — the only piece that needs the grid internals; the rest of
+     * the navigation logic lives in the AccessibilityService.
+     */
+    adjacentGroup(
+        group: DockviewGroupPanel,
+        reverse: boolean
+    ): DockviewGroupPanel | undefined {
         // gridview traversal only covers grid groups; a floating/popout group
         // isn't in the grid, so there's no adjacent grid group to step to.
-        if (current && current.api.location.type !== 'grid') {
-            return;
-        }
-        const location = current ? getGridLocation(current.element) : undefined;
-        const target = current
-            ? <DockviewGroupPanel | undefined>(
-                  (reverse
-                      ? this.gridview.previous(location!)
-                      : this.gridview.next(location!)
-                  )?.view
-              )
-            : this.groups[0];
-        if (target) {
-            this.doSetGroupAndPanelActive(target);
-            target.model.focusContent();
+        if (group.api.location.type !== 'grid') {
+            return undefined;
         }
+        const location = getGridLocation(group.element);
+        return <DockviewGroupPanel | undefined>(
+            (reverse
+                ? this.gridview.previous(location)
+                : this.gridview.next(location)
+            )?.view
+        );
     }
 
     showDropPreview(
diff --git a/packages/dockview-core/src/dockview/options.ts b/packages/dockview-core/src/dockview/options.ts
