Add chord keyboard shortcuts and staged capture UI

2026-03-22 16:28:09 +07:00
parent d9bcf2a439
commit 57f8c7615c
16 changed files with 498 additions and 99 deletions
@@ -1,8 +1,11 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import {
  buildKeyboardShortcutHelpSections,
+  buildEffectiveBindings,
  resolveKeyboardShortcut,
+  type ChordState,
  type KeyboardShortcutContext,
+  type ParsedShortcutBinding,
 } from "./keyboard-shortcuts";

 function keyboardEvent(overrides: Partial<KeyboardEvent>): KeyboardEvent {
@@ -31,6 +34,30 @@ function shortcutContext(
  };
 }

+function initialChordState(): ChordState {
+  return {
+    candidateIndices: [],
+    step: 0,
+    timeoutId: null,
+  };
+}
+
+function resolveShortcut(input: {
+  event: Partial<KeyboardEvent>;
+  context?: Partial<KeyboardShortcutContext>;
+  chordState?: ChordState;
+  onChordReset?: () => void;
+  bindings?: readonly ParsedShortcutBinding[];
+}) {
+  return resolveKeyboardShortcut({
+    event: keyboardEvent(input.event),
+    context: shortcutContext(input.context),
+    chordState: input.chordState ?? initialChordState(),
+    onChordReset: input.onChordReset ?? (() => undefined),
+    ...(input.bindings ? { bindings: input.bindings } : {}),
+  });
+}
+
 function expectShortcutResolution(input: {
  event: Partial<KeyboardEvent>;
  context?: Partial<KeyboardShortcutContext>;
@@ -39,29 +66,33 @@ function expectShortcutResolution(input: {
  preventDefault?: boolean;
  stopPropagation?: boolean;
 }) {
-  const match = resolveKeyboardShortcut({
-    event: keyboardEvent(input.event),
-    context: shortcutContext(input.context),
+  const result = resolveShortcut({
+    event: input.event,
+    context: input.context,
  });

-  expect(match?.action).toBe(input.action);
+  expect(result.match?.action).toBe(input.action);
  if ("payload" in input) {
-    expect(match?.payload).toEqual(input.payload);
+    expect(result.match?.payload).toEqual(input.payload);
  }
-  expect(match?.preventDefault).toBe(input.preventDefault ?? true);
-  expect(match?.stopPropagation).toBe(input.stopPropagation ?? true);
+  expect(result.match?.preventDefault).toBe(input.preventDefault ?? true);
+  expect(result.match?.stopPropagation).toBe(input.stopPropagation ?? true);
+  expect(result.preventDefault).toBe(false);
+  expect(result.nextChordState).toEqual(initialChordState());
 }

 function expectNoShortcutResolution(input: {
  event: Partial<KeyboardEvent>;
  context?: Partial<KeyboardShortcutContext>;
 }) {
-  const match = resolveKeyboardShortcut({
-    event: keyboardEvent(input.event),
-    context: shortcutContext(input.context),
+  const result = resolveShortcut({
+    event: input.event,
+    context: input.context,
  });

-  expect(match).toBeNull();
+  expect(result.match).toBeNull();
+  expect(result.preventDefault).toBe(false);
+  expect(result.nextChordState).toEqual(initialChordState());
 }

 type MatchingShortcutCase = {
@@ -338,6 +369,66 @@ describe("keyboard-shortcuts", () => {
  it.each(nonMatchingCases)("$name", ({ event, context }) => {
    expectNoShortcutResolution({ event, context });
  });
+
+  it("prefers advancing chord candidates over single-combo matches on the same prefix", () => {
+    const bindings = buildEffectiveBindings({
+      "workspace-terminal-new-ctrl-shift-t-non-mac": "Ctrl+W S",
+    });
+    const chordBindingIndex = bindings.findIndex(
+      (binding) => binding.id === "workspace-terminal-new-ctrl-shift-t-non-mac",
+    );
+    expect(chordBindingIndex).toBeGreaterThan(-1);
+
+    const firstResult = resolveShortcut({
+      event: { key: "w", code: "KeyW", ctrlKey: true },
+      context: { isMac: false, isDesktop: true },
+      bindings,
+    });
+
+    expect(firstResult.match).toBeNull();
+    expect(firstResult.preventDefault).toBe(true);
+    expect(firstResult.nextChordState.step).toBe(1);
+    expect(firstResult.nextChordState.candidateIndices).toEqual([chordBindingIndex]);
+
+    const secondResult = resolveShortcut({
+      event: { key: "s", code: "KeyS" },
+      context: { isMac: false, isDesktop: true },
+      chordState: firstResult.nextChordState,
+      bindings,
+    });
+
+    expect(secondResult.match?.action).toBe("workspace.terminal.new");
+    expect(secondResult.match?.payload).toBeNull();
+    expect(secondResult.match?.preventDefault).toBe(true);
+    expect(secondResult.match?.stopPropagation).toBe(true);
+    expect(secondResult.preventDefault).toBe(false);
+    expect(secondResult.nextChordState).toEqual(initialChordState());
+  });
+
+  it("schedules a chord reset timeout for advancing candidates", () => {
+    vi.useFakeTimers();
+
+    const bindings = buildEffectiveBindings({
+      "workspace-terminal-new-ctrl-shift-t-non-mac": "Ctrl+W S",
+    });
+    const onChordReset = vi.fn();
+
+    const result = resolveShortcut({
+      event: { key: "w", code: "KeyW", ctrlKey: true },
+      context: { isMac: false, isDesktop: true },
+      onChordReset,
+      bindings,
+    });
+
+    expect(result.match).toBeNull();
+    expect(result.preventDefault).toBe(true);
+    expect(result.nextChordState.timeoutId).not.toBeNull();
+
+    vi.advanceTimersByTime(1500);
+
+    expect(onChordReset).toHaveBeenCalledTimes(1);
+    vi.useRealTimers();
+  });
 });

 describe("keyboard-shortcut help sections", () => {
@@ -5,7 +5,7 @@ import type {
  KeyboardShortcutPayload,
  MessageInputKeyboardActionKind,
 } from "@/keyboard/actions";
-import { type KeyCombo, parseShortcutString } from "@/keyboard/shortcut-string";
+import { type KeyCombo, parseChordString } from "@/keyboard/shortcut-string";

 export type { KeyCombo } from "@/keyboard/shortcut-string";

@@ -88,7 +88,13 @@ interface ShortcutBinding {
 }

 export interface ParsedShortcutBinding extends ShortcutBinding {
-  parsedCombo: KeyCombo;
+  parsedChord: KeyCombo[];
+}
+
+export interface ChordState {
+  candidateIndices: number[];
+  step: number;
+  timeoutId: ReturnType<typeof setTimeout> | null;
 }

 // --- Constants ---
@@ -817,11 +823,12 @@ const SHORTCUT_BINDINGS: readonly ShortcutBinding[] = [
 // --- Parse bindings at module load ---

 function parseBinding(binding: ShortcutBinding): ParsedShortcutBinding {
-  const parsedCombo = parseShortcutString(binding.combo);
-  if (binding.repeat === false) {
-    parsedCombo.repeat = false;
+  const parsedChord = parseChordString(binding.combo);
+  const lastCombo = parsedChord.at(-1);
+  if (binding.repeat === false && lastCombo) {
+    lastCombo.repeat = false;
  }
-  return { ...binding, parsedCombo };
+  return { ...binding, parsedChord };
 }

 export const DEFAULT_BINDINGS: readonly ParsedShortcutBinding[] =
@@ -835,16 +842,17 @@ export function buildEffectiveBindings(
    if (override === undefined) {
      return binding;
    }
-    let parsedCombo: KeyCombo;
+    let parsedChord: KeyCombo[];
    try {
-      parsedCombo = parseShortcutString(override);
+      parsedChord = parseChordString(override);
    } catch {
      return binding;
    }
-    if (binding.repeat === false) {
-      parsedCombo.repeat = false;
+    const lastCombo = parsedChord.at(-1);
+    if (binding.repeat === false && lastCombo) {
+      lastCombo.repeat = false;
    }
-    return { ...binding, combo: override, parsedCombo };
+    return { ...binding, combo: override, parsedChord };
  });
 }

@@ -921,6 +929,27 @@ function resolvePayload(
  }
 }

+const CHORD_TIMEOUT_MS = 1500;
+
+function clearChordTimeout(timeoutId: ReturnType<typeof setTimeout> | null): void {
+  if (timeoutId !== null) {
+    clearTimeout(timeoutId);
+  }
+}
+
+function createChordTimeout(onChordReset: () => void): ReturnType<typeof setTimeout> {
+  return setTimeout(onChordReset, CHORD_TIMEOUT_MS);
+}
+
+function resetChordState(input: ChordState): ChordState {
+  clearChordTimeout(input.timeoutId);
+  return {
+    candidateIndices: [],
+    step: 0,
+    timeoutId: null,
+  };
+}
+
 function helpMatchesPlatform(
  when: ShortcutWhen | undefined,
  context: KeyboardShortcutPlatformContext,
@@ -935,24 +964,131 @@ function helpMatchesPlatform(
 export function resolveKeyboardShortcut(input: {
  event: KeyboardEvent;
  context: KeyboardShortcutContext;
+  chordState: ChordState;
+  onChordReset: () => void;
  bindings?: readonly ParsedShortcutBinding[];
-}): KeyboardShortcutMatch | null {
-  const { event, context, bindings = DEFAULT_BINDINGS } = input;
-  for (const binding of bindings) {
-    if (!matchesCombo(binding.parsedCombo, event, context.isMac)) {
+}): {
+  match: KeyboardShortcutMatch | null;
+  nextChordState: ChordState;
+  preventDefault: boolean;
+};
+export function resolveKeyboardShortcut(input: {
+  event: KeyboardEvent;
+  context: KeyboardShortcutContext;
+  chordState: ChordState;
+  onChordReset: () => void;
+  bindings?: readonly ParsedShortcutBinding[];
+}): {
+  match: KeyboardShortcutMatch | null;
+  nextChordState: ChordState;
+  preventDefault: boolean;
+} {
+  const { event, context, chordState, onChordReset, bindings = DEFAULT_BINDINGS } = input;
+
+  if (chordState.step === 0) {
+    const advancingCandidateIndices: number[] = [];
+    let singleComboMatch: KeyboardShortcutMatch | null = null;
+
+    for (const [index, binding] of bindings.entries()) {
+      const firstCombo = binding.parsedChord[0];
+      if (!firstCombo) {
+        continue;
+      }
+      if (!matchesCombo(firstCombo, event, context.isMac)) {
+        continue;
+      }
+      if (!matchesWhen(binding.when, context)) {
+        continue;
+      }
+      if (binding.parsedChord.length > 1) {
+        advancingCandidateIndices.push(index);
+        continue;
+      }
+      if (!singleComboMatch) {
+        singleComboMatch = {
+          action: binding.action,
+          payload: resolvePayload(binding.payload, event),
+          preventDefault: binding.preventDefault ?? true,
+          stopPropagation: binding.stopPropagation ?? true,
+        };
+      }
+    }
+
+    if (advancingCandidateIndices.length > 0) {
+      return {
+        match: null,
+        nextChordState: {
+          candidateIndices: advancingCandidateIndices,
+          step: 1,
+          timeoutId: createChordTimeout(onChordReset),
+        },
+        preventDefault: true,
+      };
+    }
+
+    return {
+      match: singleComboMatch,
+      nextChordState: resetChordState(chordState),
+      preventDefault: false,
+    };
+  }
+
+  const matchingCandidateIndices: number[] = [];
+  let completedMatch: KeyboardShortcutMatch | null = null;
+
+  for (const index of chordState.candidateIndices) {
+    const binding = bindings[index];
+    if (!binding) {
+      continue;
+    }
+    const combo = binding.parsedChord[chordState.step];
+    if (!combo) {
+      continue;
+    }
+    if (!matchesCombo(combo, event, context.isMac)) {
      continue;
    }
    if (!matchesWhen(binding.when, context)) {
      continue;
    }
+    if (chordState.step + 1 === binding.parsedChord.length) {
+      completedMatch = {
+        action: binding.action,
+        payload: resolvePayload(binding.payload, event),
+        preventDefault: binding.preventDefault ?? true,
+        stopPropagation: binding.stopPropagation ?? true,
+      };
+      break;
+    }
+    matchingCandidateIndices.push(index);
+  }
+
+  if (completedMatch) {
    return {
-      action: binding.action,
-      payload: resolvePayload(binding.payload, event),
-      preventDefault: binding.preventDefault ?? true,
-      stopPropagation: binding.stopPropagation ?? true,
+      match: completedMatch,
+      nextChordState: resetChordState(chordState),
+      preventDefault: false,
    };
  }
-  return null;
+
+  if (matchingCandidateIndices.length > 0) {
+    clearChordTimeout(chordState.timeoutId);
+    return {
+      match: null,
+      nextChordState: {
+        candidateIndices: matchingCandidateIndices,
+        step: chordState.step + 1,
+        timeoutId: createChordTimeout(onChordReset),
+      },
+      preventDefault: true,
+    };
+  }
+
+  return {
+    match: null,
+    nextChordState: resetChordState(chordState),
+    preventDefault: false,
+  };
 }

 export function getBindingIdForAction(
@@ -103,6 +103,10 @@ export function parseShortcutString(s: string): KeyCombo {
  return combo;
 }

+export function parseChordString(s: string): KeyCombo[] {
+  return s.split(" ").map(parseShortcutString);
+}
+
 export function keyComboToString(combo: KeyCombo): string {
  const parts: string[] = [];

@@ -122,6 +126,10 @@ export function keyComboToString(combo: KeyCombo): string {
  return parts.join("+");
 }

+export function chordToString(chord: KeyCombo[]): string {
+  return chord.map(keyComboToString).join(" ");
+}
+
 const MODIFIER_CODES = new Set([
  "MetaLeft",
  "MetaRight",
@@ -158,6 +166,10 @@ export function comboStringToShortcutKeys(comboString: string): ShortcutKey[] {
  return keys;
 }

+export function chordStringToShortcutKeys(s: string): ShortcutKey[][] {
+  return s.split(" ").map(comboStringToShortcutKeys);
+}
+
 export function keyboardEventToComboString(event: KeyboardEvent): string | null {
  if (MODIFIER_CODES.has(event.code)) {
    return null;