@kabmo-labs/kabmo 0.8.0 → 0.9.0

package/src/client/components/common/code-surface/keymap.test.ts

@@ -0,0 +1,133 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The keymap generator.
+ *
+ * Its whole contract is negative: a command the palette lists must be BOUND, or
+ * the palette advertises a shortcut nothing listens for. That property is only
+ * checkable by comparing the generated CM6 bindings against `EDITOR_KEY_BINDINGS`
+ * — which is what this does, row by row, so adding a row to the table and
+ * forgetting the binding fails here instead of in a user's hands.
+ *
+ * The name mapping is the part that is easy to get silently wrong: CM6 matches
+ * on `event.keyCode` through `w3c-keyname`, so `Digit1` is `1` and `Slash` is
+ * `/` — a binding written `Digit1` never fires.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { EditorState, type TransactionSpec } from '@codemirror/state';
+import type { EditorView } from '@codemirror/view';
+
+import { EDITOR_KEY_BINDINGS } from '@/shared/lib/code/editor/keymap';
+import { codeMirrorKey, runSurfaceCommand } from '@/client/components/common/code-surface/keymap';
+
+describe('codeMirrorKey', () => {
+  test('maps letters, digits and function keys to the names CM6 matches', () => {
+    // Lower case for a bare letter: `keyName` reports the character the key
+    // produces, which is `d` unshifted. The shifted form (`D`) is reached
+    // through CM6's own base-character fallback, so the row still fires.
+    expect(codeMirrorKey({ code: 'KeyD', meta: true })).toBe('Meta-d');
+    expect(codeMirrorKey({ code: 'Digit1', meta: true, shift: true })).toBe('Shift-Meta-1');
+    expect(codeMirrorKey({ code: 'F3' })).toBe('F3');
+  });
+
+  test('maps punctuation to the character the key produces unshifted', () => {
+    // `Slash` is `/` on every layout that has it; `BracketRight` is `]`.
+    expect(codeMirrorKey({ code: 'Slash', ctrl: true })).toBe('Ctrl-/');
+    expect(codeMirrorKey({ code: 'BracketRight', meta: true })).toBe('Meta-]');
+    expect(codeMirrorKey({ code: 'BracketLeft', ctrl: true })).toBe('Ctrl-[');
+  });
+
+  test('names the keys that have their own spelling', () => {
+    expect(codeMirrorKey({ code: 'Enter', meta: true })).toBe('Meta-Enter');
+    expect(codeMirrorKey({ code: 'ArrowUp', alt: true })).toBe('Alt-ArrowUp');
+    expect(codeMirrorKey({ code: 'Home' })).toBe('Home');
+  });
+
+  test('orders modifiers the way CM6 canonicalises them', () => {
+    // CM6's `modifiers()` prepends alt, then ctrl, then meta, then shift, so
+    // the canonical spelling runs `Shift-Meta-Ctrl-Alt-<key>`. A different
+    // order here would be a binding CM6 never matches.
+    expect(codeMirrorKey({ code: 'ArrowDown', ctrl: true, alt: true, shift: true })).toBe('Shift-Ctrl-Alt-ArrowDown');
+  });
+
+  test('reports null for a key with no name, so the row is skipped', () => {
+    expect(codeMirrorKey({ code: 'IntlBackslash' })).toBeNull();
+  });
+});
+
+describe('EDITOR_KEY_BINDINGS coverage', () => {
+  test('every row resolves to a chord on both platforms', () => {
+    const missing = EDITOR_KEY_BINDINGS.filter(
+      (binding) => codeMirrorKey(binding.mac) === null || codeMirrorKey(binding.other) === null,
+    ).map((binding) => binding.command);
+
+    // A row whose chord cannot be named is a palette entry that does nothing —
+    // the exact failure this table exists to prevent.
+    expect(missing).toEqual([]);
+  });
+
+  test('no two rows claim the same chord on the same platform', () => {
+    for (const platform of ['mac', 'other'] as const) {
+      const seen = new Map<string, string>();
+      for (const binding of EDITOR_KEY_BINDINGS) {
+        const chord = codeMirrorKey(binding[platform]);
+        if (!chord) continue;
+        // A duplicate would make the first row win silently and leave the
+        // second's palette entry dead.
+        expect(seen.has(chord) ? `${chord} (${seen.get(chord)} and ${binding.command})` : null).toBeNull();
+        seen.set(chord, binding.command);
+      }
+    }
+  });
+});
+
+/**
+ * The two commands the surface implements itself, run against a state.
+ *
+ * `insertLineAbove` is the one that has no CM6 equivalent, and its indentation
+ * rule is the part a rewrite loses silently: a bare newline above an indented
+ * line puts the caret at column 0, so the next thing typed lands outside the
+ * block. Driven through `runSurfaceCommand` — the palette's and the handle's own
+ * path in — with a `{ state, dispatch }` view, which is all a `StateCommand`
+ * touches.
+ */
+describe('surface commands', () => {
+  /**
+   * The two commands are `StateCommand`s: they read `state` and hand a
+   * transaction SPEC to `dispatch`, nothing else. A view-shaped stand-in is what
+   * `runSurfaceCommand` takes, so the cast states that boundary once rather than
+   * mounting an `EditorView` in happy-dom for a rule with no DOM in it.
+   */
+  function viewFor(doc: string, anchor: number): EditorView {
+    let state = EditorState.create({ doc, selection: { anchor } });
+    const view = {
+      get state() {
+        return state;
+      },
+      // A command dispatches a `TransactionSpec`; `EditorState.update` is the
+      // half of the real view's `dispatch` these commands depend on.
+      dispatch: (...specs: TransactionSpec[]) => {
+        state = state.update(...specs).state;
+      },
+    };
+    return view as unknown as EditorView;
+  }
+
+  test('insertLineAbove keeps the current line’s indentation and lands after it', () => {
+    const view = viewFor('  const a = 1;\nconst b = 2;\n', 4);
+    expect(runSurfaceCommand('insertLineAbove', view)).toBe(true);
+    expect(view.state.doc.toString()).toBe('  \n  const a = 1;\nconst b = 2;\n');
+    expect(view.state.selection.main.head).toBe(2);
+  });
+
+  test('insertLineAbove on an unindented line inserts a bare blank line', () => {
+    const view = viewFor('one\ntwo\n', 5);
+    runSurfaceCommand('insertLineAbove', view);
+    expect(view.state.doc.toString()).toBe('one\n\ntwo\n');
+    expect(view.state.selection.main.head).toBe(4);
+  });
+});

package/src/client/components/common/code-surface/keymap.ts

@@ -0,0 +1,267 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The editor's chords, generated from `EDITOR_KEY_BINDINGS`.
+ *
+ * The table in `shared/lib/code/editor/keymap.ts` is the ONE statement of what
+ * each chord means: the command palette lists it, the find bar's tooltips print
+ * it, and this module turns it into CodeMirror bindings. A hand-written CM6
+ * keymap would be a second statement that drifts — the palette would advertise
+ * `⌥⌘C` for a key CM6 never bound.
+ *
+ * Panel-owned commands (`find`, `replace`, the match steps, word wrap) are bound
+ * HERE too and delegate outward through `onCommand`, so a chord pressed inside
+ * the document reaches the same dispatcher the palette uses. Consuming the key
+ * is the point: `⌘F` inside the editor must open Kabmo's find bar, never the
+ * browser's.
+ */
+
+import type { Extension, StateCommand } from '@codemirror/state';
+import { EditorSelection } from '@codemirror/state';
+import {
+  addCursorBelow,
+  defaultKeymap,
+  copyLineDown,
+  copyLineUp,
+  cursorDocEnd,
+  cursorDocStart,
+  cursorLineEnd,
+  cursorLineStart,
+  deleteLine,
+  indentLess,
+  indentMore,
+  insertBlankLine,
+  moveLineDown,
+  moveLineUp,
+  redo,
+  selectDocEnd,
+  selectDocStart,
+  selectLine,
+  selectLineEnd,
+  selectLineStart,
+  simplifySelection,
+  toggleComment,
+  undo,
+} from '@codemirror/commands';
+import { selectNextOccurrence, selectSelectionMatches } from '@codemirror/search';
+import { keymap, type Command, type EditorView, type KeyBinding } from '@codemirror/view';
+
+import { EDITOR_KEY_BINDINGS, type EditorCommand } from '@/shared/lib/code/editor/keymap';
+import type { KeyStroke } from '@/shared/lib/ui/key-binding';
+
+/** A command as this module invokes it: CM6's `Command` and `StateCommand` both fit. */
+type SurfaceCommand = (view: EditorView) => boolean;
+
+/**
+ * Insert a blank line ABOVE the caret's line, which CM6 has no command for.
+ *
+ * The new line carries the current line's own leading whitespace, and the caret
+ * lands after it — the rule the textarea surface applied, and the one that makes
+ * the key useful inside a block: a bare newline above an indented line left the
+ * caret at column 0 and the new line unindented, so the very next thing typed
+ * was in the wrong place. (CM6's `insertBlankLine`, used for "below", derives
+ * the same indentation from `IndentContext`; this mirrors it without needing a
+ * grammar.)
+ */
+const insertLineAbove: SurfaceCommand = (view) => {
+  const { state } = view;
+  const range = state.selection.main;
+  const line = state.doc.lineAt(range.from);
+  const indent = /^[ \t]*/.exec(line.text)?.[0] ?? '';
+  view.dispatch({
+    changes: { from: line.from, insert: `${indent}\n` },
+    selection: { anchor: line.from + indent.length },
+  });
+  return true;
+};
+
+/** Select the word under the caret, or nothing when the caret is between words. */
+const selectWord: SurfaceCommand = (view) => {
+  const { state } = view;
+  const range = state.selection.main;
+  if (range.from !== range.to) return false;
+  const line = state.doc.lineAt(range.from);
+  const offset = range.from - line.from;
+  const isWord = (char: string | undefined) => char !== undefined && /[\w$]/.test(char);
+  let start = offset;
+  let end = offset;
+  if (!isWord(line.text[start]) && isWord(line.text[start - 1])) start--;
+  if (!isWord(line.text[start])) return false;
+  end = start;
+  while (isWord(line.text[start - 1])) start--;
+  while (isWord(line.text[end])) end++;
+  view.dispatch({
+    selection: EditorSelection.range(line.from + start, line.from + end),
+  });
+  return true;
+};
+
+/**
+ * Collapse extra selections, keeping the main one.
+ *
+ * Escape's first job when ⌘D left several carets behind; only the next press
+ * hands the keyboard back to the page, which the panel's own capture handler
+ * does once this reports there was nothing left to collapse.
+ */
+const collapseSelections: SurfaceCommand = (view) => {
+  if (view.state.selection.ranges.length <= 1) return false;
+  return (simplifySelection as StateCommand)(view);
+};
+
+/**
+ * Commands the BUFFER owns. Everything absent from this table is either the
+ * panel's (`find`, `replace`, `toggleWordWrap`) or a chord with no meaning in a
+ * CM6 surface.
+ */
+const BUFFER_COMMANDS: Partial<Record<EditorCommand, SurfaceCommand>> = {
+  undo: undo as SurfaceCommand,
+  redo: redo as SurfaceCommand,
+  selectNextOccurrence: selectNextOccurrence as SurfaceCommand,
+  selectAllOccurrences: selectSelectionMatches as SurfaceCommand,
+  insertCursorBelow: addCursorBelow as SurfaceCommand,
+  moveLineUp: moveLineUp as SurfaceCommand,
+  moveLineDown: moveLineDown as SurfaceCommand,
+  copyLineUp: copyLineUp as SurfaceCommand,
+  copyLineDown: copyLineDown as SurfaceCommand,
+  deleteLine: deleteLine as SurfaceCommand,
+  toggleComment: toggleComment as SurfaceCommand,
+  insertLineBelow: insertBlankLine as SurfaceCommand,
+  insertLineAbove,
+  indent: indentMore as SurfaceCommand,
+  outdent: indentLess as SurfaceCommand,
+  lineStart: cursorLineStart as SurfaceCommand,
+  lineEnd: cursorLineEnd as SurfaceCommand,
+  documentStart: cursorDocStart as SurfaceCommand,
+  documentEnd: cursorDocEnd as SurfaceCommand,
+  selectToLineStart: selectLineStart as SurfaceCommand,
+  selectToLineEnd: selectLineEnd as SurfaceCommand,
+  selectToDocumentStart: selectDocStart as SurfaceCommand,
+  selectToDocumentEnd: selectDocEnd as SurfaceCommand,
+  selectWord,
+  selectLine: selectLine as SurfaceCommand,
+  escape: collapseSelections,
+};
+
+/** Run a command against a live view — the palette's and the handle's path in. */
+export function runSurfaceCommand(command: EditorCommand, view: EditorView, onCommand?: (command: EditorCommand) => void): boolean {
+  const run = BUFFER_COMMANDS[command];
+  if (run) return run(view);
+  onCommand?.(command);
+  return true;
+}
+
+/** Codes whose printed name is not their `KeyboardEvent.code` suffix. */
+const NAMED_KEYS: Record<string, string> = {
+  Enter: 'Enter',
+  Escape: 'Escape',
+  Backspace: 'Backspace',
+  Delete: 'Delete',
+  Tab: 'Tab',
+  Space: 'Space',
+  ArrowUp: 'ArrowUp',
+  ArrowDown: 'ArrowDown',
+  ArrowLeft: 'ArrowLeft',
+  ArrowRight: 'ArrowRight',
+  Home: 'Home',
+  End: 'End',
+  PageUp: 'PageUp',
+  PageDown: 'PageDown',
+};
+
+const PUNCTUATION_KEYS: Record<string, string> = {
+  Slash: '/',
+  Backslash: '\\',
+  Comma: ',',
+  Period: '.',
+  Semicolon: ';',
+  Quote: "'",
+  Backquote: '`',
+  Minus: '-',
+  Equal: '=',
+  BracketLeft: '[',
+  BracketRight: ']',
+};
+
+/**
+ * The key CodeMirror names a physical key by, WITHOUT modifiers.
+ *
+ * CM6 matches on `event.keyCode` through `w3c-keyname`, so the base name is the
+ * character the key produces unshifted — `Digit1` is `1`, not `!`, and a
+ * `Shift` binding is written `Shift-1`. Punctuation is its US character, which
+ * is what that library reports for the same key code.
+ */
+function baseKey(code: string): string | null {
+  if (/^Key[A-Z]$/.test(code)) return code.slice(3).toLowerCase();
+  if (/^Digit\d$/.test(code)) return code.slice(5);
+  if (/^F\d{1,2}$/.test(code)) return code;
+  return NAMED_KEYS[code] ?? PUNCTUATION_KEYS[code] ?? null;
+}
+
+/** `{code:'Digit1', meta:true, shift:true}` → `Meta-Shift-1` (CM6's canonical order). */
+export function codeMirrorKey(stroke: KeyStroke): string | null {
+  const key = baseKey(stroke.code);
+  if (!key) return null;
+  let name = key;
+  if (stroke.alt) name = `Alt-${name}`;
+  if (stroke.ctrl) name = `Ctrl-${name}`;
+  if (stroke.meta) name = `Meta-${name}`;
+  if (stroke.shift) name = `Shift-${name}`;
+  return name;
+}
+
+/**
+ * One CM6 binding per keymap row, carrying each platform's own chord.
+ *
+ * `key` is the Windows/Linux chord, `mac` the macOS one, and `win` the Windows
+ * override for the single row that has one (`redo` is `Ctrl-Y` there and
+ * `Ctrl-Shift-Z` on Linux). CM6 falls back to `key` when a platform field is
+ * absent, so a row without an override needs nothing extra.
+ */
+function bindingsFor(onCommand?: (command: EditorCommand) => void): KeyBinding[] {
+  const bindings: KeyBinding[] = [];
+  for (const binding of EDITOR_KEY_BINDINGS) {
+    const other = codeMirrorKey(binding.other);
+    const mac = codeMirrorKey(binding.mac);
+    const win = binding.windows ? codeMirrorKey(binding.windows) : null;
+    if (!other && !mac) continue;
+    const command = binding.command;
+    bindings.push({
+      key: other ?? undefined,
+      mac: mac ?? undefined,
+      win: win ?? undefined,
+      run: (view) => runSurfaceCommand(command, view, onCommand),
+    });
+  }
+  return bindings;
+}
+
+/**
+ * Tab indents and ⇧Tab outdents, exactly as `indentWithTab` does.
+ *
+ * Written out rather than imported so the row can be dropped when the surface is
+ * read-only: a viewer that still indented would edit the document. Leaving the
+ * editor with the keyboard is CM6's own answer — `Escape` arms a two-second tab
+ * focus mode, after which `Tab` moves focus instead of indenting.
+ */
+const TAB_BINDINGS: KeyBinding[] = [
+  { key: 'Tab', run: indentMore as Command, shift: indentLess as Command },
+];
+
+/**
+ * The editor's own keymap, as one extension.
+ *
+ * CM6's `defaultKeymap` is APPENDED rather than omitted: it is what makes the
+ * ordinary editing keys work — Enter, Backspace, arrows, Home/End, `Mod-End` to
+ * the document end, word-wise movement — and none of that is a Kabmo command.
+ * Appending it AFTER our rows is what keeps a chord the table claims from being
+ * shadowed by a CM6 default (`Mod-a` is a good example: both mean "select all",
+ * but only one of them also moves the selection the way the palette describes).
+ */
+export function surfaceKeymap(onCommand?: (command: EditorCommand) => void, readOnly = false): Extension {
+  const rows = readOnly ? [] : TAB_BINDINGS;
+  return keymap.of([...bindingsFor(onCommand), ...rows, ...defaultKeymap]);
+}
+

package/src/client/components/common/code-surface/marks.ts

@@ -0,0 +1,74 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Find matches, as a decoration field.
+ *
+ * The old surface spliced `<mark>` elements into the highlighter's own HTML, so
+ * every find result forced a re-tokenize of the window and the marks could not
+ * exist without the token layer. A field is the CM6 shape: the ranges are state,
+ * the decorations are derived from it, and a keystroke in the query costs one
+ * rebuild of the ranges instead of a second trip through Shiki.
+ *
+ * The geometry rules are inherited from that markup layer and are still
+ * load-bearing: `<mark>` had a background and no padding, and the current match
+ * is marked with horizontal edges only. A match routinely spans several tokens,
+ * so any decoration that draws vertical edges would paint a seam in the middle
+ * of it.
+ */
+
+import { RangeSetBuilder, StateEffect, StateField, type Text } from '@codemirror/state';
+import { Decoration, EditorView, type DecorationSet } from '@codemirror/view';
+
+/** A document-offset range; the editor's own `TextRange` shape. */
+export interface MarkRange {
+  start: number;
+  end: number;
+}
+
+export interface FindMarkState {
+  marks: readonly MarkRange[];
+  /** Index into `marks` of the match the caret is aimed at, or -1. */
+  current: number;
+}
+
+/** Replace the whole mark set. */
+export const setFindMarks = StateEffect.define<FindMarkState>();
+
+const MATCH = Decoration.mark({ class: 'find-match' });
+const CURRENT = Decoration.mark({ class: 'find-match', attributes: { 'data-find-current': '' } });
+
+function build(state: FindMarkState, doc: Text): DecorationSet {
+  if (state.marks.length === 0) return Decoration.none;
+  const builder = new RangeSetBuilder<Decoration>();
+  for (let index = 0; index < state.marks.length; index++) {
+    const mark = state.marks[index];
+    const from = Math.max(0, Math.min(mark.start, doc.length));
+    const to = Math.max(from, Math.min(mark.end, doc.length));
+    if (to === from) continue;
+    builder.add(from, to, index === state.current ? CURRENT : MATCH);
+  }
+  return builder.finish();
+}
+
+/**
+ * The mark set as editor state.
+ *
+ * A document edit MAPS the existing decorations rather than dropping them: the
+ * owner recomputes the list on the next render anyway (`matches` is derived from
+ * the live buffer), and mapping keeps the highlights roughly right for the frame
+ * in between instead of blinking off on every keystroke.
+ */
+export const findMarksField = StateField.define<DecorationSet>({
+  create: () => Decoration.none,
+  update(marks, transaction) {
+    for (const effect of transaction.effects) {
+      if (effect.is(setFindMarks)) return build(effect.value, transaction.state.doc);
+    }
+    if (transaction.docChanged) return marks.map(transaction.changes);
+    return marks;
+  },
+  provide: (field) => EditorView.decorations.from(field),
+});