@cueloop/client 0.1.0-alpha.7 → 0.1.0-alpha.71

package/src/key-bindings.test.ts

@@ -0,0 +1,156 @@
+/** Config keys resolve to per-layer actions, and status hints derive from getActiveKeys() so rebinds surface. */
+
+import { describe, expect, test } from "bun:test";
+import { DEFAULT_KEYS } from "./config";
+import { KeyBindings } from "./key-bindings";
+
+function bindings(
+  context: { overlay?: "none" | "walk" | "compose" | "submit"; spanMode?: boolean } = {},
+): KeyBindings {
+  const resolver = new KeyBindings(DEFAULT_KEYS);
+
+  resolver.setContext({ overlay: context.overlay ?? "none", spanMode: context.spanMode ?? false });
+
+  return resolver;
+}
+
+describe("grammar-layer resolution", () => {
+  const table: [name: string, shift: boolean, action: string | undefined][] = [
+    ["j", false, "down"],
+    ["down", false, "down"],
+    ["k", false, "up"],
+    ["g", false, "top"],
+    ["g", true, "bottom"],
+    ["v", false, "span"],
+    ["c", false, "comment"],
+    ["s", false, "split_diff"],
+    ["x", false, "cut"],
+    ["e", false, "edit"],
+    ["n", false, "next_annotation"],
+    ["p", false, "prev_annotation"],
+    ["backspace", false, "delete_annotation"],
+    ["return", false, "submit"],
+    ["enter", false, "submit"],
+    ["q", false, "quit"],
+    ["z", false, undefined],
+  ];
+
+  for (const [name, shift, action] of table) {
+    test(`${shift ? "shift+" : ""}${name} -> ${action}`, () => {
+      expect(bindings().resolveAction({ name, shift })).toBe(action!);
+    });
+  }
+});
+
+describe("mode layers own their keys", () => {
+  test("span mode resolves the span primitives, not the grammar", () => {
+    // Arrange
+    const resolver = bindings({ spanMode: true });
+
+    // Assert
+    expect(resolver.resolveAction({ name: "l", shift: false })).toBe("span_grow");
+    expect(resolver.resolveAction({ name: "c", shift: false })).toBe("span_comment");
+    expect(resolver.resolveAction({ name: "escape", shift: false })).toBe("span_cancel");
+  });
+
+  test("the compose overlay only knows save and cancel", () => {
+    // Arrange
+    const resolver = bindings({ overlay: "compose" });
+
+    // Assert
+    expect(resolver.resolveAction({ name: "return", shift: false })).toBe("save_compose");
+    expect(resolver.resolveAction({ name: "escape", shift: false })).toBe("cancel_overlay");
+    expect(resolver.resolveAction({ name: "j", shift: false })).toBeUndefined();
+  });
+
+  test("the submit overlay adds the verdict arrows", () => {
+    // Arrange
+    const resolver = bindings({ overlay: "submit" });
+
+    // Assert
+    expect(resolver.resolveAction({ name: "left", shift: false })).toBe("cycle_verdict_left");
+    expect(resolver.resolveAction({ name: "right", shift: false })).toBe("cycle_verdict_right");
+    expect(resolver.resolveAction({ name: "return", shift: false })).toBe("submit_verdict");
+  });
+
+  test("the walk overlay owns the bracket stepping and leaves the grammar keys dead", () => {
+    // Arrange
+    const resolver = bindings({ overlay: "walk" });
+
+    // Assert
+    expect(resolver.resolveAction({ name: "]", shift: false })).toBe("walk_next");
+    expect(resolver.resolveAction({ name: "[", shift: false })).toBe("walk_prev");
+    expect(resolver.resolveAction({ name: "escape", shift: false })).toBe("walk_leave");
+    expect(resolver.resolveAction({ name: "return", shift: false })).toBe("walk_submit");
+    expect(resolver.resolveAction({ name: "q", shift: false })).toBe("quit");
+    expect(resolver.resolveAction({ name: "j", shift: false })).toBeUndefined();
+    expect(resolver.resolveAction({ name: "c", shift: false })).toBeUndefined();
+  });
+});
+
+describe("getActiveKeys-generated status hints", () => {
+  test("normal mode hint matches the locked string", () => {
+    expect(bindings().statusHint("normal")).toBe(
+      "j/k move · v span · drag selects · c comment · x cut · e edit · n/p annotations · enter submit · q quit",
+    );
+  });
+
+  test("card-selected hint keeps the locked Cut label", () => {
+    expect(bindings().statusHint("card")).toBe(
+      "card · e edit · x Cut · n/p cards · esc deselect · enter submit",
+    );
+  });
+
+  test("span hint", () => {
+    expect(bindings({ spanMode: true }).statusHint("span")).toBe(
+      "span · l/h grow/shrink · w/b slide · $ end · c comment · esc",
+    );
+  });
+
+  test("compose hint", () => {
+    expect(bindings({ overlay: "compose" }).statusHint("compose")).toBe(
+      "typing · enter save · esc cancel",
+    );
+  });
+
+  test("submit hint", () => {
+    expect(bindings({ overlay: "submit" }).statusHint("submit")).toBe(
+      "decision ←/→ · enter submit · esc cancel",
+    );
+  });
+
+  test("walk hint", () => {
+    expect(bindings({ overlay: "walk" }).statusHint("walk")).toBe(
+      "walk · ] next (marks viewed) · [ back · esc leave walk · q quit",
+    );
+  });
+
+  test("read-only hint", () => {
+    expect(bindings().statusHint("read-only")).toBe(
+      "observer - read-only · j/k move · n/p annotations · q quit",
+    );
+  });
+
+  test("collaborator hint annotates but shows no plan edit or submit", () => {
+    // Arrange / Act
+    const hint = bindings().statusHint("collaborator");
+
+    // Assert
+    expect(hint).toBe("j/k move · v span · drag selects · c comment · n/p annotations · q quit");
+    expect(hint).not.toContain("cut");
+    expect(hint).not.toContain("edit");
+    expect(hint).not.toContain("submit");
+  });
+
+  test("a rebound key shows its real binding in the hint", () => {
+    // Arrange
+    const resolver = new KeyBindings({ ...DEFAULT_KEYS, comment: ["m"] });
+
+    resolver.setContext({ overlay: "none", spanMode: false });
+
+    // Assert
+    expect(resolver.resolveAction({ name: "m", shift: false })).toBe("comment");
+    expect(resolver.resolveAction({ name: "c", shift: false })).toBeUndefined();
+    expect(resolver.statusHint("normal")).toContain("m comment");
+  });
+});

package/src/key-bindings.ts

@@ -0,0 +1,465 @@
+/**
+ * Binding resolution over @opentui/keymap: the loaded config keymap
+ * registers as layers (grammar, span, compose, submit, completion) on one
+ * Keymap instance, key events resolve to action names through its dispatch,
+ * and the status-line hints generate from getActiveKeys() - a rebound key
+ * shows its real binding in the hints. The pure intent reducer (keymap.ts)
+ * stays the dispatch layer beneath: this module answers "which action", the
+ * reducer answers "which intents".
+ */
+
+import { Keymap, type KeymapEvent, type KeymapHost } from "@opentui/keymap";
+import { registerDefaultKeys } from "@opentui/keymap/addons";
+import * as v from "valibot";
+import type { KeyState } from "./keymap";
+
+export interface ResolvableKey {
+  name: string;
+  shift: boolean;
+}
+
+/** The layer-activation slice of the view state. */
+export interface KeyLayerContext {
+  overlay: KeyState["overlay"];
+  spanMode: boolean;
+}
+
+/** Hint templates keyed by the same view states the status line shows. */
+export type HintMode =
+  | "normal"
+  | "collaborator"
+  | "card"
+  | "span"
+  | "compose"
+  | "submit"
+  | "walk"
+  | "read-only";
+
+/** Display glyph for the Agent-tab terminal detach chord (ctrl+], App-owned). */
+export const AGENT_DETACH_HINT = "⌃]";
+
+export interface CheatsheetEntry {
+  keys: string;
+  label: string;
+}
+export interface CheatsheetSection {
+  title: string;
+  entries: CheatsheetEntry[];
+}
+
+type HintEntry = { text: string } | { commands: string[]; label: string; labelFirst?: boolean };
+
+const HINT_TEMPLATES: Record<HintMode, HintEntry[]> = {
+  normal: [
+    { commands: ["down", "up"], label: "move" },
+    { commands: ["span"], label: "span" },
+    { text: "drag selects" },
+    { commands: ["comment"], label: "comment" },
+    { commands: ["cut"], label: "cut" },
+    { commands: ["edit"], label: "edit" },
+    { commands: ["next_annotation", "prev_annotation"], label: "annotations" },
+    { commands: ["submit"], label: "submit" },
+    { commands: ["quit"], label: "quit" },
+  ],
+  // A share viewer: annotate and navigate, no plan edit / verdict submit.
+  collaborator: [
+    { commands: ["down", "up"], label: "move" },
+    { commands: ["span"], label: "span" },
+    { text: "drag selects" },
+    { commands: ["comment"], label: "comment" },
+    { commands: ["next_annotation", "prev_annotation"], label: "annotations" },
+    { commands: ["quit"], label: "quit" },
+  ],
+  card: [
+    { text: "card" },
+    { commands: ["edit"], label: "edit" },
+    { commands: ["cut"], label: "Cut" },
+    { commands: ["next_annotation", "prev_annotation"], label: "cards" },
+    { commands: ["deselect"], label: "deselect" },
+    { commands: ["submit"], label: "submit" },
+  ],
+  span: [
+    { text: "span" },
+    { commands: ["span_grow", "span_shrink"], label: "grow/shrink" },
+    { commands: ["span_slide_forward", "span_slide_back"], label: "slide" },
+    { commands: ["span_to_end"], label: "end" },
+    { commands: ["span_comment"], label: "comment" },
+    { commands: ["span_cancel"], label: "" },
+  ],
+  compose: [
+    { text: "typing" },
+    { commands: ["save_compose"], label: "save" },
+    { commands: ["cancel_overlay"], label: "cancel" },
+  ],
+  submit: [
+    {
+      commands: ["cycle_verdict_left", "cycle_verdict_right"],
+      label: "decision",
+      labelFirst: true,
+    },
+    { commands: ["submit_verdict"], label: "submit" },
+    { commands: ["cancel_submit"], label: "cancel" },
+  ],
+  walk: [
+    { text: "walk" },
+    { commands: ["walk_next"], label: "next (marks viewed)" },
+    { commands: ["walk_prev"], label: "back" },
+    { commands: ["walk_leave"], label: "leave walk" },
+    { commands: ["quit"], label: "quit" },
+  ],
+  "read-only": [
+    { text: "observer - read-only" },
+    { commands: ["down", "up"], label: "move" },
+    { commands: ["next_annotation", "prev_annotation"], label: "annotations" },
+    { commands: ["quit"], label: "quit" },
+  ],
+};
+
+/** Status-line glyphs for named keys. */
+interface KeyGlyphs {
+  [key: string]: string;
+}
+
+const KEY_GLYPHS: KeyGlyphs = {
+  return: "enter",
+  enter: "enter",
+  escape: "esc",
+  left: "←",
+  right: "→",
+  backspace: "⌫",
+  down: "↓",
+  up: "↑",
+};
+
+function makeKeymapEvent(name: string, shift = false): KeymapEvent {
+  return {
+    name,
+    ctrl: false,
+    shift,
+    meta: false,
+    preventDefault: () => {},
+    stopPropagation: () => {},
+    propagationStopped: false,
+  };
+}
+
+class HeadlessKeymapHost implements KeymapHost<object, KeymapEvent> {
+  readonly metadata = {
+    platform: "unknown" as const,
+    primaryModifier: "unknown" as const,
+    modifiers: {
+      ctrl: "supported" as const,
+      shift: "supported" as const,
+      meta: "supported" as const,
+      super: "unknown" as const,
+      hyper: "unknown" as const,
+    },
+  };
+  readonly rootTarget = {};
+  readonly isDestroyed = false;
+  private readonly pressListeners = new Set<(event: KeymapEvent) => void>();
+
+  getFocusedTarget(): object | null {
+    return null;
+  }
+  getParentTarget(): object | null {
+    return null;
+  }
+  isTargetDestroyed(): boolean {
+    return false;
+  }
+  onKeyPress(listener: (event: KeymapEvent) => void): () => void {
+    this.pressListeners.add(listener);
+
+    return () => this.pressListeners.delete(listener);
+  }
+  onKeyRelease(): () => void {
+    return () => {};
+  }
+  onFocusChange(): () => void {
+    return () => {};
+  }
+  onTargetDestroy(): () => void {
+    return () => {};
+  }
+  createCommandEvent(): KeymapEvent {
+    return makeKeymapEvent("");
+  }
+  emitKeyPress(event: KeymapEvent): void {
+    for (const listener of this.pressListeners) listener(event);
+  }
+}
+
+/**
+ * Terminal key events name shifted letters either "g"+shift or "G"; the
+ * keymap's canonical form is lowercase + the shift modifier. Non-letter
+ * single characters ("$", "0") already encode their shift in the character.
+ */
+function normalizedEvent(key: ResolvableKey) {
+  if (key.name.length === 1) {
+    if (/[a-zA-Z]/.test(key.name)) {
+      return {
+        name: key.name.toLowerCase(),
+        shift: key.shift || key.name !== key.name.toLowerCase(),
+      };
+    }
+
+    return { name: key.name, shift: false };
+  }
+
+  return { name: key.name, shift: key.shift };
+}
+
+/** Config combos write shifted letters as uppercase; the parser wants shift+. */
+function bindingKeyFor(combo: string): string {
+  if (combo.length === 1 && /[A-Z]/.test(combo)) return `shift+${combo.toLowerCase()}`;
+
+  return combo;
+}
+
+/** The grammar actions live in the base layer; these live in mode layers. */
+const SPAN_COMMANDS: [key: string, command: string][] = [
+  ["l", "span_grow"],
+  ["h", "span_shrink"],
+  ["w", "span_slide_forward"],
+  ["b", "span_slide_back"],
+  ["$", "span_to_end"],
+  ["0", "span_to_start"],
+  ["c", "span_comment"],
+  ["escape", "span_cancel"],
+];
+
+function isConditionMatcher(value: unknown): value is () => boolean {
+  return typeof value === "function";
+}
+
+export class KeyBindings {
+  private readonly host = new HeadlessKeymapHost();
+  private readonly keymap = new Keymap<object, KeymapEvent>(this.host);
+  private context: KeyLayerContext = { overlay: "none", spanMode: false };
+  private resolvedCommand: string | undefined;
+  private unregisterGrammarLayer: (() => void) | null = null;
+
+  constructor(keys: Record<string, string[]>) {
+    // the standard binding-string parser and event matcher
+    registerDefaultKeys(this.keymap);
+    // binding/layer `when` fields register runtime matchers, so getActiveKeys
+    // and dispatch only see the layer that owns the current mode
+    this.keymap.registerLayerFields({
+      when: (value, fieldContext) => {
+        if (isConditionMatcher(value)) fieldContext.activeWhen(value);
+      },
+    });
+    this.registerModeLayers();
+    this.setKeys(keys);
+  }
+
+  /** Rebuild the grammar layer from a (re)loaded config keymap. */
+  setKeys(keys: Record<string, string[]>): void {
+    this.unregisterGrammarLayer?.();
+    const bindings: { key: string; cmd: string }[] = [];
+    const commandNames = new Set<string>();
+
+    for (const [action, combos] of Object.entries(keys)) {
+      commandNames.add(action);
+      for (const combo of combos) bindings.push({ key: bindingKeyFor(combo), cmd: action });
+    }
+    // deselect is a hardwired escape in the plan grammar; hints show it
+    commandNames.add("deselect");
+    bindings.push({ key: "escape", cmd: "deselect" });
+    this.unregisterGrammarLayer = this.keymap.registerLayer({
+      priority: 0,
+      when: () => this.context.overlay === "none" && !this.context.spanMode,
+      bindings,
+      commands: [...commandNames].map((name) => ({
+        name,
+        run: () => {
+          this.resolvedCommand = name;
+
+          return true;
+        },
+      })),
+    });
+  }
+
+  private registerModeLayers(): void {
+    const record = (name: string) => ({
+      name,
+      run: () => {
+        this.resolvedCommand = name;
+
+        return true;
+      },
+    });
+
+    this.keymap.registerLayer({
+      priority: 10,
+      when: () => this.context.overlay === "none" && this.context.spanMode,
+      bindings: SPAN_COMMANDS.map(([key, command]) => ({ key, cmd: command })),
+      commands: SPAN_COMMANDS.map(([, command]) => record(command)),
+    });
+    // the walk wizard: prev/next stepping, leave, and submit from the end card
+    this.keymap.registerLayer({
+      priority: 20,
+      when: () => this.context.overlay === "walk",
+      bindings: [
+        { key: "]", cmd: "walk_next" },
+        { key: "[", cmd: "walk_prev" },
+        { key: "escape", cmd: "walk_leave" },
+        { key: "return", cmd: "walk_submit" },
+        { key: "enter", cmd: "walk_submit" },
+        { key: "q", cmd: "quit" },
+      ],
+      commands: [
+        record("walk_next"),
+        record("walk_prev"),
+        record("walk_leave"),
+        record("walk_submit"),
+        record("quit"),
+      ],
+    });
+    this.keymap.registerLayer({
+      priority: 20,
+      when: () => this.context.overlay === "compose",
+      bindings: [
+        { key: "return", cmd: "save_compose" },
+        { key: "enter", cmd: "save_compose" },
+        { key: "escape", cmd: "cancel_overlay" },
+      ],
+      commands: [record("save_compose"), record("cancel_overlay")],
+    });
+    this.keymap.registerLayer({
+      priority: 20,
+      when: () => this.context.overlay === "submit",
+      bindings: [
+        { key: "return", cmd: "submit_verdict" },
+        { key: "enter", cmd: "submit_verdict" },
+        { key: "left", cmd: "cycle_verdict_left" },
+        { key: "right", cmd: "cycle_verdict_right" },
+        { key: "escape", cmd: "cancel_submit" },
+      ],
+      commands: [
+        record("submit_verdict"),
+        record("cycle_verdict_left"),
+        record("cycle_verdict_right"),
+        record("cancel_submit"),
+      ],
+    });
+    this.keymap.registerLayer({
+      priority: 20,
+      when: () =>
+        this.context.overlay === "completion-prompt" ||
+        this.context.overlay === "completion-counting",
+      bindings: [
+        { key: "return", cmd: "finish_review" },
+        { key: "enter", cmd: "finish_review" },
+        { key: "q", cmd: "finish_review" },
+        { key: "a", cmd: "opt_in_auto_close" },
+        { key: "escape", cmd: "dismiss_completion" },
+      ],
+      commands: [
+        record("finish_review"),
+        record("opt_in_auto_close"),
+        record("dismiss_completion"),
+      ],
+    });
+  }
+
+  setContext(context: KeyLayerContext): void {
+    this.context = context;
+  }
+
+  /**
+   * Resolve a key event to its command name through the keymap's dispatch.
+   * In the base grammar layer the command IS the config action name, so the
+   * result feeds straight into the intent reducer.
+   */
+  resolveAction(key: ResolvableKey): string | undefined {
+    const normalized = normalizedEvent(key);
+
+    this.resolvedCommand = undefined;
+    this.host.emitKeyPress(makeKeymapEvent(normalized.name, normalized.shift));
+
+    return this.resolvedCommand;
+  }
+
+  /** First active key display for a command, mapped through the glyph table. */
+  private keyDisplayFor(command: string): string | null {
+    for (const activeKey of this.keymap.getActiveKeys({ includeBindings: true })) {
+      const parsedCommand = v.safeParse(v.string(), activeKey.command);
+      const bindingCommand = parsedCommand.success
+        ? parsedCommand.output
+        : activeKey.bindings?.[0]?.command;
+
+      if (bindingCommand !== command) continue;
+
+      return KEY_GLYPHS[activeKey.stroke.name] ?? activeKey.display;
+    }
+
+    return null;
+  }
+
+  /** The status-line hint for a view state, generated from the active keys. */
+  statusHint(mode: HintMode): string {
+    const fragments: string[] = [];
+
+    for (const entry of HINT_TEMPLATES[mode]) {
+      if ("text" in entry) {
+        fragments.push(entry.text);
+        continue;
+      }
+      const displays = entry.commands
+        .map((command) => this.keyDisplayFor(command))
+        .filter((display): display is string => display !== null);
+
+      if (!displays.length) continue;
+      const keyPart = displays.join("/");
+
+      if (!entry.label) fragments.push(keyPart);
+      else
+        fragments.push(
+          entry.labelFirst ? `${entry.label} ${keyPart}` : `${keyPart} ${entry.label}`,
+        );
+    }
+
+    return fragments.join(" · ");
+  }
+
+  /**
+   * The full keybinding cheatsheet, grouped by mode. Each section sets the
+   * layer context so getActiveKeys resolves that mode's real bindings, then
+   * restores it - a rebound key shows its live binding here too.
+   */
+  cheatsheet(): CheatsheetSection[] {
+    const saved = this.context;
+    const build = (context: KeyLayerContext, mode: HintMode, title: string): CheatsheetSection => {
+      this.context = context;
+      const entries: CheatsheetEntry[] = [];
+
+      for (const entry of HINT_TEMPLATES[mode]) {
+        if ("text" in entry || !entry.label) continue;
+        const keys = entry.commands
+          .map((command) => this.keyDisplayFor(command))
+          .filter((display): display is string => display !== null)
+          .join(" / ");
+
+        if (keys) entries.push({ keys, label: entry.label });
+      }
+
+      return { title, entries };
+    };
+    const sections = [
+      build({ overlay: "none", spanMode: false }, "normal", "Review"),
+      build({ overlay: "none", spanMode: true }, "span", "Selection"),
+      build({ overlay: "submit", spanMode: false }, "submit", "Submit"),
+      build({ overlay: "walk", spanMode: false }, "walk", "Walk"),
+      // The Agent-tab terminal chord is owned by App (not the rebindable keymap),
+      // so it is listed statically rather than resolved from the active keys.
+      { title: "Agent terminal", entries: [{ keys: AGENT_DETACH_HINT, label: "detach" }] },
+    ];
+
+    this.context = saved;
+
+    return sections.filter((section) => section.entries.length > 0);
+  }
+}