feat(dockview-core): rebindable keymap + keyboard tab switching

mathuo · claude · mathuo · commit 65b39667445c · 2026-06-11T08:46:18.000+01:00
Generalise the keyboard-docking option into `keyboardNavigation` (still
opt-in), backed by a rebindable `DockviewKeybindings` keymap, and add
within-group tab switching:

- `Ctrl+]` / `Ctrl+[` cycle the focused group's tabs (wrapping round) via the
  group model's moveToNext/moveToPrevious.
- `Ctrl+M` docking is now just another keymap entry (`dock`).

Pass `keyboardNavigation: { keymap: { ... } }` to rebind any action — the
defaults deliberately avoid Cmd-based and browser-reserved combinations so they
survive on macOS. Bindings are matched modifier-exact against KeyboardEvent.key.

Renames the unreleased `keyboardDocking` option to `keyboardNavigation`.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/__generated__/dockview-core-exports.txt b/__generated__/dockview-core-exports.txt
diff --git a/packages/dockview-core/src/__tests__/dockview/accessibilityDocking.spec.ts b/packages/dockview-core/src/__tests__/dockview/accessibilityDocking.spec.ts
@@ -23,12 +23,14 @@ describe('accessibility: keyboard docking', () => {
     let container: HTMLElement;
     let dockview: DockviewComponent;
 
-    const make = (keyboardDocking: boolean): void => {
+    const make = (
+        keyboardNavigation: boolean | { keymap?: Record<string, string> }
+    ): void => {
         container = document.createElement('div');
         document.body.appendChild(container);
         dockview = new DockviewComponent(container, {
             createComponent: () => new TestPanel(),
-            keyboardDocking,
+            keyboardNavigation,
         });
         dockview.layout(1000, 1000);
     };
@@ -96,7 +98,7 @@ describe('accessibility: keyboard docking', () => {
         expect(dockview.groups.length).toBe(2);
     });
 
-    test('does nothing when keyboardDocking is off (default)', () => {
+    test('does nothing when keyboardNavigation is off (default)', () => {
         make(false);
         twoGroups();
 
@@ -105,3 +107,79 @@ describe('accessibility: keyboard docking', () => {
         expect(dockview.groups.length).toBe(2);
     });
 });
+
+/**
+ * Switch tabs within the focused group by keyboard — Ctrl+] / Ctrl+[ cycle
+ * the active group's panels (wrapping round), driven by the rebindable keymap.
+ */
+describe('accessibility: tab switching', () => {
+    let container: HTMLElement;
+    let dockview: DockviewComponent;
+
+    const make = (
+        keyboardNavigation: boolean | { keymap?: Record<string, string> }
+    ): void => {
+        container = document.createElement('div');
+        document.body.appendChild(container);
+        dockview = new DockviewComponent(container, {
+            createComponent: () => new TestPanel(),
+            keyboardNavigation,
+        });
+        dockview.layout(1000, 1000);
+    };
+
+    const threeTabs = (): void => {
+        dockview.addPanel({ id: 'p1', component: 'default', title: 'P1' });
+        dockview.addPanel({ id: 'p2', component: 'default', title: 'P2' });
+        dockview.addPanel({ id: 'p3', component: 'default', title: 'P3' });
+    };
+
+    afterEach(() => {
+        dockview.dispose();
+        container.remove();
+    });
+
+    test('Ctrl+] advances to the next tab and wraps round', () => {
+        make(true);
+        threeTabs(); // one group, p3 active
+        expect(dockview.activePanel?.id).toBe('p3');
+
+        fireEvent.keyDown(dockview.element, { key: ']', ctrlKey: true });
+        expect(dockview.activePanel?.id).toBe('p1'); // wrapped past the end
+
+        fireEvent.keyDown(dockview.element, { key: ']', ctrlKey: true });
+        expect(dockview.activePanel?.id).toBe('p2');
+    });
+
+    test('Ctrl+[ steps back to the previous tab and wraps round', () => {
+        make(true);
+        threeTabs(); // p3 active
+
+        fireEvent.keyDown(dockview.element, { key: '[', ctrlKey: true });
+        expect(dockview.activePanel?.id).toBe('p2');
+
+        fireEvent.keyDown(dockview.element, { key: '[', ctrlKey: true });
+        fireEvent.keyDown(dockview.element, { key: '[', ctrlKey: true });
+        expect(dockview.activePanel?.id).toBe('p3'); // wrapped past the start
+    });
+
+    test('a rebound keymap is honoured (and the default no longer fires)', () => {
+        make({ keymap: { nextTab: 'alt+n' } });
+        threeTabs(); // p3 active
+
+        // default binding is overridden, so Ctrl+] does nothing now
+        fireEvent.keyDown(dockview.element, { key: ']', ctrlKey: true });
+        expect(dockview.activePanel?.id).toBe('p3');
+
+        fireEvent.keyDown(dockview.element, { key: 'n', altKey: true });
+        expect(dockview.activePanel?.id).toBe('p1');
+    });
+
+    test('does nothing when keyboardNavigation is off', () => {
+        make(false);
+        threeTabs(); // p3 active
+
+        fireEvent.keyDown(dockview.element, { key: ']', ctrlKey: true });
+        expect(dockview.activePanel?.id).toBe('p3');
+    });
+});
diff --git a/packages/dockview-core/src/dockview/accessibilityService.ts b/packages/dockview-core/src/dockview/accessibilityService.ts
@@ -2,7 +2,11 @@ import { CompositeDisposable, IDisposable } from '../lifecycle';
 import { Position } from '../dnd/droptarget';
 import { DockviewGroupPanel } from './dockviewGroupPanel';
 import { IDockviewPanel } from './dockviewPanel';
-import { DockviewComponentOptions } from './options';
+import {
+    DockviewComponentOptions,
+    DockviewKeybindings,
+    KeyboardNavigationOptions,
+} from './options';
 import { defineModule } from './modules';
 import { AdvancedDnDModule } from './advancedDnDService';
 import { LiveRegionModule } from './liveRegionService';
@@ -23,6 +27,10 @@ export interface IAccessibilityHost {
     readonly options: DockviewComponentOptions;
     readonly groups: DockviewGroupPanel[];
     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;
     showDropPreview(group: DockviewGroupPanel, position: Position): IDisposable;
     announce(message: string): void;
     dockPanel(
@@ -51,18 +59,45 @@ const EDGE_FROM_KEY: Record<string, Position> = {
     ArrowDown: 'bottom',
 };
 
+const DEFAULT_KEYMAP: DockviewKeybindings = {
+    nextTab: 'ctrl+]',
+    prevTab: 'ctrl+[',
+    dock: 'ctrl+m',
+};
+
+/**
+ * Does `e` match a binding string like `'ctrl+]'` / `'shift+f6'`? Modifiers
+ * are matched exactly (a binding without `shift` will not fire while Shift is
+ * held), and the final part is compared to `KeyboardEvent.key`, lower-cased.
+ */
+function matchesBinding(e: KeyboardEvent, binding: string): boolean {
+    const parts = binding.toLowerCase().split('+');
+    const key = parts[parts.length - 1];
+    const mods = parts.slice(0, -1);
+    return (
+        e.ctrlKey === mods.includes('ctrl') &&
+        e.shiftKey === mods.includes('shift') &&
+        e.altKey === mods.includes('alt') &&
+        e.metaKey === (mods.includes('meta') || mods.includes('cmd')) &&
+        e.key.toLowerCase() === key
+    );
+}
+
 /**
- * Pro accessibility module — operate the dock without a mouse. Keyboard
- * docking: `Ctrl+M` on the active panel arms a two-phase move with a live drop
- * preview + screen-reader narration:
- *   1. PICK TARGET — arrows cycle the groups (incl. the panel's own, so a tab
- *      can be split out); `Enter` selects one.
- *   2. PICK EDGE — arrows choose a split edge (left/right/top/bottom) or the
- *      centre (tab-into); `Enter` commits, `Escape` steps back.
- * `Escape` from the target phase cancels. Opt-in via `keyboardDocking`.
+ * Pro accessibility module — operate the dock without a mouse. Opt-in via
+ * `keyboardNavigation`, with a rebindable {@link DockviewKeybindings} keymap.
  *
- * Float / popout terminals, spatial F6 navigation and cross-window focus
- * management are later phases.
+ * - **Switch tab** (`Ctrl+]` / `Ctrl+[`) — cycle the focused group's tabs.
+ * - **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
+ *        can be split out); `Enter` selects one.
+ *     2. PICK EDGE — arrows choose a split edge (left/right/top/bottom) or the
+ *        centre (tab-into); `Enter` commits, `Escape` steps back.
+ *   `Escape` from the target phase cancels.
+ *
+ * Inter-group focus navigation (F6 / spatial), float / popout terminals and
+ * cross-window focus management are later phases.
  */
 export class AccessibilityService
     extends CompositeDisposable
@@ -91,24 +126,42 @@ export class AccessibilityService
         );
     }
 
+    private get _nav(): KeyboardNavigationOptions | undefined {
+        const opt = this.host.options.keyboardNavigation;
+        if (!opt) {
+            return undefined;
+        }
+        return opt === true ? {} : opt;
+    }
+
+    private get _keymap(): DockviewKeybindings {
+        return { ...DEFAULT_KEYMAP, ...this._nav?.keymap };
+    }
+
     private _onKeyDown(e: KeyboardEvent): void {
-        if (!this.host.options.keyboardDocking) {
+        if (!this._nav) {
             return;
         }
         if (this._move) {
             this._onMoveKey(e);
             return;
         }
-        // Ctrl+M only — NOT Cmd+M (macOS minimise-window, OS-intercepted).
-        // Scope to events originating inside *this* dockview.
+        // Only act on events originating inside *this* dockview.
         if (
-            e.ctrlKey &&
-            !e.metaKey &&
-            (e.key === 'm' || e.key === 'M') &&
-            e.target instanceof Node &&
-            this.host.rootElement.contains(e.target)
+            !(e.target instanceof Node) ||
+            !this.host.rootElement.contains(e.target)
         ) {
+            return;
+        }
+        const keymap = this._keymap;
+        if (matchesBinding(e, keymap.dock)) {
             this._enterMoveMode(e);
+        } else if (matchesBinding(e, keymap.nextTab)) {
+            this._consume(e);
+            this.host.focusNextPanel();
+        } else if (matchesBinding(e, keymap.prevTab)) {
+            this._consume(e);
+            this.host.focusPreviousPanel();
         }
     }
 
diff --git a/packages/dockview-core/src/dockview/dockviewComponent.ts b/packages/dockview-core/src/dockview/dockviewComponent.ts
@@ -706,6 +706,14 @@ export class DockviewComponent
         return this._shellManager?.element ?? this.element;
     }
 
+    focusNextPanel(): void {
+        this.activeGroup?.model.moveToNext();
+    }
+
+    focusPreviousPanel(): void {
+        this.activeGroup?.model.moveToPrevious();
+    }
+
     showDropPreview(
         group: DockviewGroupPanel,
         position: Position
diff --git a/packages/dockview-core/src/dockview/options.ts b/packages/dockview-core/src/dockview/options.ts
@@ -71,6 +71,27 @@ export interface LiveRegionEvent {
     panel: IDockviewPanel;
 }
 
+/**
+ * Key bindings for {@link DockviewComponentOptions.keyboardNavigation}. Each
+ * value is a string of `+`-separated parts, modifiers first, e.g. `'ctrl+]'`,
+ * `'shift+f6'`, `'ctrl+m'`. Recognised modifiers: `ctrl`, `shift`, `alt`,
+ * `meta` (alias `cmd`). The final part is the `KeyboardEvent.key` to match,
+ * case-insensitively (`'m'`, `']'`, `'f6'`, `'arrowleft'`).
+ */
+export interface DockviewKeybindings {
+    /** Switch to the next tab in the focused group. Default `ctrl+]`. */
+    nextTab: string;
+    /** Switch to the previous tab in the focused group. Default `ctrl+[`. */
+    prevTab: string;
+    /** Arm keyboard docking of the active panel. Default `ctrl+m`. */
+    dock: string;
+}
+
+export interface KeyboardNavigationOptions {
+    /** Override individual {@link DockviewKeybindings}; unset keys keep their defaults. */
+    keymap?: Partial<DockviewKeybindings>;
+}
+
 export interface GetTabContextMenuItemsParams {
     panel: IDockviewPanel;
     group: DockviewGroupPanel;
@@ -256,15 +277,20 @@ export interface DockviewOptions {
      */
     getAnnouncement?: (event: LiveRegionEvent) => string | null | undefined;
     /**
-     * Enable keyboard docking — move the active panel without a mouse:
-     * `Ctrl`+`M` enters move mode, arrows cycle the target group (with a live
-     * drop preview + screen-reader narration), `Enter` docks it, `Escape`
-     * cancels. Off by default (opt-in while the feature matures).
+     * Operate the dock with the keyboard. `true` enables the default bindings;
+     * pass an object to override individual ones via `keymap`. Off by default
+     * (opt-in while the feature matures). Enables:
+     *
+     * - **Switch tab** within the focused group — `Ctrl`+`]` / `Ctrl`+`[`.
+     * - **Dock the active panel** without a mouse — `Ctrl`+`M` arms a two-phase
+     *   move (arrows cycle the target group with a live drop preview +
+     *   screen-reader narration, `Enter` docks, `Escape` cancels).
      *
-     * (`Cmd`+`M` is intentionally not used — it's the macOS minimise-window
-     * shortcut. A rebindable keymap is a planned follow-up.)
+     * Defaults avoid `Cmd`-based and browser-reserved combinations (e.g.
+     * `Cmd`+`M` is the macOS minimise-window shortcut); use {@link keymap} to
+     * rebind for your platform.
      */
-    keyboardDocking?: boolean;
+    keyboardNavigation?: boolean | KeyboardNavigationOptions;
     /**
      * Replace the built-in tab group color palette with a user-defined list.
      *
@@ -349,7 +375,7 @@ export const PROPERTY_KEYS_DOCKVIEW: (keyof DockviewOptions)[] = (() => {
         dropOverlayModel: undefined,
         announcements: undefined,
         getAnnouncement: undefined,
-        keyboardDocking: undefined,
+        keyboardNavigation: undefined,
         tabGroupColors: undefined,
         tabGroupAccent: undefined,
     };
