ompchamber 2.0.2 → 3.1.0

package/src/client/components/common/code-editor/handler.test.ts

@@ -0,0 +1,274 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The editor's keydown dispatcher, exercised with a fake textarea.
+ *
+ * These assertions are the routing contract: which layer owns a key, and what
+ * happens to the event when nobody does. The failures they guard against are
+ * all silent — a chord that reaches the browser's own find bar, an Escape that
+ * throws away a multi-selection instead of dropping it, a Tab that escapes the
+ * editor mid-line.
+ *
+ * The platform is PINNED rather than detected. The dispatcher resolves chords
+ * through `isMacPlatform()`, so a test written with ⌘ chords passes on a
+ * developer's Mac and fails on the Linux CI runner — which is exactly what
+ * happened. `usePlatform()` below makes each case state the platform it means.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { handleEditorKeydown, runEditorCommand, type EditorKeydownDeps } from '@/client/components/common/code-editor/handler';
+import { createHistory, pushRecord } from '@/shared/lib/code/editor/history';
+import type { EditorHistory } from '@/client/hooks/editor/use-editor-history';
+import type { OccurrencesApi } from '@/client/hooks/editor/use-occurrences';
+import type { EditorCommand } from '@/shared/lib/code/editor/keymap';
+import type { TextRange } from '@/shared/lib/code/editor/commands';
+
+/** A textarea stand-in: the dispatcher only reads value/selection and calls blur. */
+function fakeInput(value: string, start: number, end = start) {
+  return {
+    value,
+    selectionStart: start,
+    selectionEnd: end,
+    blurred: false,
+    blur() {
+      this.blurred = true;
+    },
+  };
+}
+
+interface Harness {
+  deps: EditorKeydownDeps;
+  committed: Array<{ value: string; selectionStart: number; selectionEnd: number }>;
+  steps: string[];
+  delegated: EditorCommand[];
+  cleared: number;
+  selected: Array<[number, number]>;
+  ranges: TextRange[];
+  captureToggles: number;
+}
+
+function harness(options: { value: string; start?: number; end?: number; ranges?: TextRange[]; language?: string; delegate?: (c: EditorCommand) => boolean } = { value: '' }): Harness {
+  const committed: Harness['committed'] = [];
+  const steps: string[] = [];
+  const delegated: EditorCommand[] = [];
+  const selected: Array<[number, number]> = [];
+  const state = { ranges: options.ranges ? [...options.ranges] : [] as TextRange[] };
+  let cleared = 0;
+  let captureToggles = 0;
+
+  const history: EditorHistory = {
+    history: createHistory(),
+    buffer: options.value,
+    commit: (edit) => committed.push(edit),
+    commitEdit: (edit) => committed.push(edit),
+    step: (direction) => steps.push(direction),
+    markApplied: () => {},
+  };
+
+  const multi: OccurrencesApi = {
+    get ranges() {
+      return state.ranges;
+    },
+    set: (ranges) => {
+      state.ranges = [...ranges];
+    },
+    clear: () => {
+      cleared++;
+      state.ranges = [];
+    },
+    selectNext: (input, select) => select(input.selectionStart, input.selectionEnd + 1),
+    selectAll: (input, select) => select(0, input.value.length),
+    insertCursorBelow: () => {},
+    replicate: () => null,
+  };
+
+  const input = fakeInput(options.value, options.start ?? 0, options.end ?? options.start ?? 0);
+  const deps: EditorKeydownDeps = {
+    input: input as unknown as HTMLTextAreaElement,
+    language: options.language ?? 'typescript',
+    captureTab: true,
+    toggleCaptureTab: () => captureToggles++,
+    history,
+    multi,
+    select: (start, end) => selected.push([start, end]),
+    delegate: (command) => {
+      delegated.push(command);
+      options.delegate?.(command);
+    },
+  };
+
+  return {
+    deps,
+    committed,
+    steps,
+    delegated,
+    selected,
+    get cleared() {
+      return cleared;
+    },
+    get captureToggles() {
+      return captureToggles;
+    },
+    get ranges() {
+      return state.ranges;
+    },
+  } as Harness;
+}
+
+/** Run `body` with `navigator.platform` reporting `platform`. */
+function usePlatform<T>(platform: string, body: () => T): T {
+  const globals = globalThis as Record<string, unknown>;
+  const previous = globals.navigator;
+  globals.navigator = { platform };
+  try {
+    return body();
+  } finally {
+    if (previous === undefined) delete globals.navigator;
+    else globals.navigator = previous;
+  }
+}
+
+/** A keydown event with only the fields the dispatcher reads. */
+function press(key: string, code: string, modifiers: Partial<{ metaKey: boolean; ctrlKey: boolean; altKey: boolean; shiftKey: boolean }> = {}) {
+  const prevented = { value: false };
+  const event = {
+    key,
+    code,
+    metaKey: false,
+    ctrlKey: false,
+    altKey: false,
+    shiftKey: false,
+    ...modifiers,
+    preventDefault: () => {
+      prevented.value = true;
+    },
+  };
+  return { event: event as never, prevented };
+}
+
+describe('handleEditorKeydown', () => {
+  test('Escape drops a live multi-selection before it leaves the editor', () => {
+    const first = harness({ value: 'abc', ranges: [{ start: 1, end: 2 }] });
+    const one = press('Escape', 'Escape');
+    handleEditorKeydown(one.event, first.deps);
+
+    expect(first.cleared).toBe(1);
+    expect(one.prevented.value).toBe(true);
+
+    // With no extra ranges left, Escape is a plain blur.
+    const input = first.deps.input as unknown as { blurred: boolean };
+    const two = press('Escape', 'Escape');
+    handleEditorKeydown(two.event, first.deps);
+
+    expect(input.blurred).toBe(true);
+    expect(two.prevented.value).toBe(false);
+  });
+
+  test('Tab indents through the history, not through a raw write', () => {
+    const h = harness({ value: 'one', start: 0 });
+    const { event, prevented } = press('Tab', 'Tab');
+    handleEditorKeydown(event, h.deps);
+
+    expect(prevented.value).toBe(true);
+    expect(h.committed[0].value).toBe('  one');
+  });
+
+  test('undo and redo step the history and drop the extra ranges', () => {
+    const h = harness({ value: 'abc', ranges: [{ start: 1, end: 2 }] });
+    usePlatform('MacIntel', () => handleEditorKeydown(press('z', 'KeyZ', { metaKey: true }).event, h.deps));
+
+    expect(h.steps).toEqual(['undo']);
+    expect(h.cleared).toBe(1);
+  });
+
+  test('a line command commits and clears the ranges it just invalidated', () => {
+    const h = harness({ value: 'one\ntwo', start: 0, end: 3, ranges: [{ start: 8, end: 9 }] });
+    handleEditorKeydown(press('ArrowDown', 'ArrowDown', { altKey: true }).event, h.deps);
+
+    expect(h.committed[0].value).toBe('two\none');
+    expect(h.cleared).toBe(1);
+  });
+
+  test('⌘D routes to the occurrence grower with the editor’s own select', () => {
+    const h = harness({ value: 'alpha', start: 0, end: 5 });
+    usePlatform('MacIntel', () => handleEditorKeydown(press('d', 'KeyD', { metaKey: true }).event, h.deps));
+
+    expect(h.selected).toEqual([[0, 6]]);
+  });
+
+  test('a find-bar chord is delegated and consumed', () => {
+    // The bar may not be open: nothing handles ⌘F, but the browser's own find
+    // bar must not open over the editor either — so the chord is consumed
+    // whatever the panel does with it.
+    const h = harness({ value: 'abc' });
+    const { event, prevented } = press('f', 'KeyF', { metaKey: true });
+    usePlatform('MacIntel', () => handleEditorKeydown(event, h.deps));
+
+    expect(h.delegated).toEqual(['find']);
+    expect(prevented.value).toBe(true);
+  });
+
+  test('a palette-style call runs a text command with no event at all', () => {
+    const h = harness({ value: 'one\ntwo', start: 0, end: 3 });
+    runEditorCommand('copyLineDown', h.deps);
+
+    expect(h.committed[0].value).toBe('one\none\ntwo');
+  });
+
+  test('an unbound chord is left to the browser', () => {
+    const h = harness({ value: 'abc' });
+    const { event, prevented } = press('a', 'KeyA', { metaKey: true });
+    handleEditorKeydown(event, h.deps);
+
+    expect(h.delegated).toEqual([]);
+    expect(prevented.value).toBe(false);
+  });
+
+  test('a chord built on Enter reaches the keymap instead of the plain-Enter branch', () => {
+    // ⌘⏎ is `insertLineBelow`; the plain-Enter auto-indent branch used to catch
+    // it first and do nothing on an unindented line, making the command dead.
+    const h = harness({ value: 'const a = 1;\nconst b = 2;', start: 20 });
+    usePlatform('MacIntel', () => handleEditorKeydown(press('Enter', 'Enter', { metaKey: true }).event, h.deps));
+
+    expect(h.committed[0].value).toBe('const a = 1;\nconst b = 2;\n');
+  });
+
+  test('plain Enter still auto-indents', () => {
+    const h = harness({ value: '  one', start: 5 });
+    handleEditorKeydown(press('Enter', 'Enter').event, h.deps);
+
+    expect(h.committed[0].value).toBe('  one\n  ');
+  });
+
+  test('⌘[ outdents the line the caret is on, with nothing selected', () => {
+    const h = harness({ value: '  one', start: 2 });
+    usePlatform('MacIntel', () => handleEditorKeydown(press('[', 'BracketLeft', { metaKey: true }).event, h.deps));
+
+    expect(h.committed[0].value).toBe('one');
+    expect(h.committed[0].selectionStart).toBe(0);
+  });
+
+  test('Ctrl+M still toggles Tab capture', () => {
+    const h = harness({ value: 'abc' });
+    // On macOS the chord needs Shift (Ctrl+M alone is Return in the terminal's
+    // own vocabulary), which is what the handler encodes. Both platforms are
+    // exercised explicitly rather than detected.
+    usePlatform('Win32', () => handleEditorKeydown(press('m', 'KeyM', { ctrlKey: true }).event, h.deps));
+    expect(h.captureToggles).toBe(1);
+
+    usePlatform('MacIntel', () => handleEditorKeydown(press('m', 'KeyM', { ctrlKey: true, shiftKey: true }).event, h.deps));
+    expect(h.captureToggles).toBe(2);
+  });
+});
+
+describe('editor keymap ownership', () => {
+  test('the editor’s own history is seeded, not the browser’s', () => {
+    const history = createHistory();
+    pushRecord(history, { value: 'a', selectionStart: 1, selectionEnd: 1, timestamp: 1 });
+    expect(history.stack.length).toBe(1);
+  });
+});

package/src/client/components/common/code-editor/handler.ts

@@ -0,0 +1,175 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The editor's keydown handler.
+ *
+ * This is dispatch, not rendering: it reads the textarea, resolves the event
+ * against the keymap, and routes the command to whoever owns it — the undo
+ * stack, the multi-selection, the pure text commands, or the panel (the find
+ * bar's chords, word wrap). It lives outside the component because the
+ * component is at the repository's line ceiling and because this is the one
+ * place that must agree with the keymap about what each key means.
+ *
+ * The rules that are NOT obvious, each of which was a bug in the naive version:
+ *
+ * - **Escape is not a plain blur.** With extra ⌘D ranges live, its first job is
+ *   to drop them; only the next press hands the keyboard back to the page.
+ * - **Tab / Backspace / Enter are not keymap entries.** Their behaviour is
+ *   about the DOM node (indentation, focus, the Tab-capture toggle) as much as
+ *   the buffer, so they are handled before the keymap is consulted.
+ * - **A command the editor does not own is not consumed** unless the panel
+ *   accepts it, so ⌘F still reaches the panel's capture handler and the
+ *   browser's own find bar never opens by accident.
+ */
+
+import type { TargetedKeyboardEvent } from 'preact';
+
+import { editForBackspace, editForEnter, editForTab } from '@/shared/lib/code/editor/edits';
+import { isTextCommand, runTextCommand, type CommittedEdit } from '@/shared/lib/code/editor/text-commands';
+import type { OccurrencesApi } from '@/client/hooks/editor/use-occurrences';
+import type { EditorHistory } from '@/client/hooks/editor/use-editor-history';
+import { EDITOR_KEY_BINDINGS, isFindBarCommand, type EditorCommand } from '@/shared/lib/code/editor/keymap';
+import { resolveBinding } from '@/shared/lib/ui/key-binding';
+import { isMacPlatform } from '@/shared/lib/util/platform';
+
+export interface EditorKeydownDeps {
+  /** The live `<textarea>`, which owns the buffer and the primary selection. */
+  input: HTMLTextAreaElement;
+  /** Shiki language id, for the comment syntax. */
+  language: string;
+  /** Whether Tab is captured (Ctrl+M toggles it). */
+  captureTab: boolean;
+  toggleCaptureTab: () => void;
+  history: EditorHistory;
+  multi: OccurrencesApi;
+  /** Select `[start, end)` and focus the field. */
+  select: (start: number, end: number) => void;
+  /** Hand a command the editor does not own to the panel. */
+  delegate: (command: EditorCommand) => void;
+}
+
+/**
+ * Run a command that is already resolved — the routing half of the handler,
+ * shared by the keydown path and by callers that have no event at all (the
+ * command palette, a toolbar button). Splitting it out is what stops the
+ * palette from being a second, partial dispatcher: a command reachable from
+ * the keyboard is reachable from the palette by construction.
+ */
+export function runEditorCommand(command: EditorCommand, deps: EditorKeydownDeps, extend = false): void {
+  const { input, history, multi, select } = deps;
+  const { value: text, selectionStart, selectionEnd } = input;
+
+  if (command === 'undo' || command === 'redo') {
+    multi.clear();
+    history.step(command === 'undo' ? 'undo' : 'redo');
+    return;
+  }
+  if (command === 'selectNextOccurrence' || command === 'selectAllOccurrences') {
+    if (command === 'selectNextOccurrence') multi.selectNext(input, select);
+    else multi.selectAll(input, select);
+    return;
+  }
+  if (command === 'insertCursorBelow') {
+    multi.insertCursorBelow(input);
+    return;
+  }
+
+  if (isTextCommand(command)) {
+    runTextCommand(command, {
+      value: text,
+      selectionStart,
+      selectionEnd,
+      extend,
+      language: deps.language,
+      commit: (edit: CommittedEdit) => {
+        // A line command replaces the whole selection model: the extra ranges
+        // pointed at text that has just moved, and keeping them would leave
+        // carets on the wrong lines.
+        multi.clear();
+        history.commitEdit(edit);
+      },
+      setCaret: (offset) => select(offset, offset),
+      selectRange: (start, end) => select(start, end),
+      setDocumentEdge: (edge) => {
+        const offset = edge === 'start' ? 0 : text.length;
+        select(offset, offset);
+      },
+    });
+    return;
+  }
+
+  deps.delegate(command);
+}
+
+/** Run the keydown handler. Every branch returns, so exactly one action fires. */
+export function handleEditorKeydown(e: TargetedKeyboardEvent<HTMLTextAreaElement>, deps: EditorKeydownDeps): void {
+  const { input, history, multi } = deps;
+  const { value: text, selectionStart, selectionEnd } = input;
+  const isMac = isMacPlatform();
+
+  if (e.key === 'Escape') {
+    if (multi.ranges.length > 0) {
+      e.preventDefault();
+      multi.clear();
+      return;
+    }
+    input.blur();
+    return;
+  }
+
+  // The bare-key handling below runs only for an UNMODIFIED key: ⌘⏎ and ⌘[
+  // are chords in the keymap, and catching them here first is what made the
+  // insert-line and indent commands unreachable (the plain-Enter branch
+  // swallowed them and did nothing, because the line had no indentation).
+  const unmodified = !e.metaKey && !e.ctrlKey && !e.altKey;
+
+  if (e.key === 'Tab' && deps.captureTab && unmodified) {
+    e.preventDefault();
+    // ⇧Tab with nothing selected is not an unindent — `editForTab` returns the
+    // buffer unchanged, and the key is consumed so focus cannot escape the
+    // editor mid-line.
+    const edit = editForTab(text, selectionStart, selectionEnd, e.shiftKey);
+    if (edit.value !== text) history.commitEdit(edit);
+    return;
+  }
+  if (e.key === 'Backspace' && unmodified) {
+    const edit = editForBackspace(text, selectionStart, selectionEnd);
+    if (edit) {
+      e.preventDefault();
+      history.commitEdit(edit);
+    }
+    return;
+  }
+  if (e.key === 'Enter' && unmodified) {
+    const edit = editForEnter(text, selectionStart, selectionEnd);
+    if (edit) {
+      e.preventDefault();
+      history.commitEdit(edit);
+    }
+    return;
+  }
+
+  const command = resolveBinding(EDITOR_KEY_BINDINGS, e);
+  if (!command) {
+    // Ctrl+M / Ctrl+Shift+M toggles Tab capture so keyboard users can leave.
+    if (e.ctrlKey && e.key.toLowerCase() === 'm' && (isMac ? e.shiftKey : true)) {
+      e.preventDefault();
+      deps.toggleCaptureTab();
+    }
+    return;
+  }
+
+  // The editor owns everything except the panel's own commands, which the
+  // delegate reports on. A find-bar chord is consumed either way, so the
+  // browser's find bar never opens over the editor.
+  e.preventDefault();
+  if (isFindBarCommand(command)) {
+    deps.delegate(command);
+    return;
+  }
+  runEditorCommand(command, deps, e.shiftKey);
+
+}