@kabmo-labs/kabmo 0.7.0 → 0.9.0

package/src/client/hooks/editor/use-editor-history.test.ts

@@ -1,216 +0,0 @@
-/**
- * @license
- * SPDX-License-Identifier: Apache-2.0
- */
-
-/**
- * The editor's undo stack.
- *
- * The rule under test is the one that was wrong: the re-seed exists for a value
- * replaced from the OUTSIDE (a file switch, a refresh), but it also fired for
- * the component's own edits — every keystroke pushed a second, identical entry,
- * so the first ⌘Z restored the buffer to the state it was already in and undo
- * looked broken until the second press. `markApplied` is what separates the two,
- * and these assertions are what keeps it separating them.
- *
- * Runs against a real DOM (happy-dom) because it is a Preact hook holding a
- * `<textarea>`; the modules below are imported dynamically, after those globals
- * exist (Preact binds its environment at evaluation time).
- */
-
-import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
-import { Window } from 'happy-dom';
-import type { h as PreactH, render as PreactRender } from 'preact';
-import type { act as PreactAct } from 'preact/test-utils';
-import type { EditorHistory, useEditorHistory as UseEditorHistoryHook } from '@/client/hooks/editor/use-editor-history';
-
-let useEditorHistory: typeof UseEditorHistoryHook;
-let h: typeof PreactH;
-let render: typeof PreactRender;
-let act: typeof PreactAct;
-
-let api: EditorHistory | null = null;
-let container: HTMLElement;
-let textarea: HTMLTextAreaElement;
-
-/** The buffer the hook is told is on screen, changed from the outside by a test. */
-let externalValue = 'one';
-
-function Harness() {
-  api = useEditorHistory({
-    value: externalValue,
-    inputRef: { current: textarea },
-    onValueChange: (next) => {
-      textarea.value = next;
-    },
-  });
-  return null;
-}
-
-/** Flush the effect that watches `value`, with no timers: it resolves on a render. */
-async function flush() {
-  for (let i = 0; i < 3; i++) {
-    await act(async () => {
-      for (let turn = 0; turn < 4; turn++) await Promise.resolve();
-    });
-  }
-}
-
-function domGlobals(win: Window): Record<string, unknown> {
-  return {
-    window: win,
-    document: win.document,
-    navigator: win.navigator,
-    Node: win.Node,
-    Element: win.Element,
-    HTMLElement: win.HTMLElement,
-    HTMLTextAreaElement: win.HTMLTextAreaElement,
-  };
-}
-
-const installed: Record<string, unknown> = {};
-const displaced: Record<string, unknown> = {};
-
-beforeAll(async () => {
-  const win = new Window({ url: 'http://localhost' });
-  for (const [key, value] of Object.entries(domGlobals(win))) {
-    displaced[key] = (globalThis as Record<string, unknown>)[key];
-    installed[key] = value;
-    (globalThis as Record<string, unknown>)[key] = value;
-  }
-  ({ useEditorHistory } = await import('@/client/hooks/editor/use-editor-history'));
-  ({ h, render } = await import('preact'));
-  ({ act } = await import('preact/test-utils'));
-});
-
-afterAll(() => {
-  for (const key of Object.keys(installed)) {
-    if (displaced[key] === undefined) delete (globalThis as Record<string, unknown>)[key];
-    else (globalThis as Record<string, unknown>)[key] = displaced[key];
-  }
-});
-
-beforeEach(async () => {
-  api = null;
-  externalValue = 'one';
-  container = document.createElement('div');
-  document.body.appendChild(container);
-  textarea = document.createElement('textarea');
-  textarea.value = 'one';
-  container.appendChild(textarea);
-  await act(async () => {
-    render(h(Harness, {}), container);
-  });
-});
-
-afterEach(() => {
-  if (container) render(null, container);
-  container?.remove();
-});
-
-describe('useEditorHistory', () => {
-  test('commit writes the buffer, the caret and the caller’s state', async () => {
-    await act(async () => {
-      api?.commit({ value: 'two', selectionStart: 2, selectionEnd: 2 });
-    });
-
-    expect(textarea.value).toBe('two');
-    expect(textarea.selectionStart).toBe(2);
-  });
-
-  test('an external value replacement is recorded, so undo reaches the old file', async () => {
-    // A file switch: the hook did not write this, so it becomes a history entry
-    // rather than silently replacing the stack.
-    externalValue = 'switched';
-    await act(async () => {
-      render(h(Harness, {}), container);
-    });
-    await flush();
-
-    await act(async () => {
-      api?.step('undo');
-    });
-
-    expect(textarea.value).toBe('one');
-  });
-
-  test('a value the hook itself wrote is NOT re-recorded', async () => {
-    // The bug this guards: an extra entry per keystroke made the first ⌘Z a
-    // no-op, because it restored the buffer to what was already on screen.
-    await act(async () => {
-      api?.commit({ value: 'two', selectionStart: 2, selectionEnd: 2 });
-    });
-    externalValue = 'two';
-    await act(async () => {
-      render(h(Harness, {}), container);
-    });
-    await flush();
-
-    await act(async () => {
-      api?.step('undo');
-    });
-
-    // One press reaches the ORIGINAL buffer; a duplicate entry would have
-    // restored 'two' again.
-    expect(textarea.value).toBe('one');
-  });
-
-  test('markApplied declares a browser edit as already recorded', async () => {
-    await act(async () => {
-      api?.markApplied('typed');
-    });
-    externalValue = 'typed';
-    await act(async () => {
-      render(h(Harness, {}), container);
-    });
-    await flush();
-
-    await act(async () => {
-      api?.step('undo');
-    });
-
-    // Nothing was pushed for `typed`, so there is nothing to step back to: the
-    // stack still holds only the initial record.
-    expect(textarea.value).toBe('one');
-  });
-
-  test('step at the ends of the stack is a no-op', async () => {
-    await act(async () => {
-      api?.step('undo');
-    });
-    const afterUndo = textarea.value;
-    await act(async () => {
-      api?.step('redo');
-    });
-
-    expect(afterUndo).toBe('one');
-    expect(textarea.value).toBe('one');
-  });
-
-  test('commitEdit supersedes the top entry, keeping its caret for the undo', async () => {
-    // A line command replaces a whole range at once; undo must return the caret
-    // to the selection the command replaced, not to where the edit ended.
-    textarea.selectionStart = 1;
-    textarea.selectionEnd = 3;
-    await act(async () => {
-      api?.commitEdit({ value: 'one-changed', selectionStart: 11, selectionEnd: 11 });
-    });
-    await act(async () => {
-      api?.step('undo');
-    });
-
-    expect(textarea.value).toBe('one');
-    expect(textarea.selectionStart).toBe(1);
-    expect(textarea.selectionEnd).toBe(3);
-  });
-
-  test('the exposed buffer is never a render behind', async () => {
-    // `handleChange` diffs against this; a value that lagged a keystroke read a
-    // one-character edit as a whole-word replacement.
-    await act(async () => {
-      api?.commit({ value: 'fresh', selectionStart: 5, selectionEnd: 5 });
-    });
-
-    expect(api?.buffer).toBe('fresh');
-  });
-});

package/src/client/hooks/editor/use-editor-history.ts

@@ -1,134 +0,0 @@
-/**
- * @license
- * SPDX-License-Identifier: Apache-2.0
- */
-
-/**
- * The editor's undo stack, wired to the DOM node.
- *
- * `history.ts` is the pure bookkeeping (push, merge, step, cap); this is the
- * part that has to touch the `<textarea>`: committing an edit as one entry,
- * restoring a stepped record, and re-seeding the stack when the value is
- * replaced from the OUTSIDE.
- *
- * The re-seed is the subtle one. It exists for a file switch or a refresh, but
- * a naive `[value]` effect also fires for the component's own edits — every
- * keystroke then pushed a second, identical entry, so the first ⌘Z restored the
- * buffer to the state it was already in and undo looked broken until the second
- * press (and the no-op `onValueChange` truncated the redo stack). The `applied`
- * ref is what distinguishes "someone else replaced the value" from "we did".
- */
-
-import { useEffect, useRef } from 'preact/hooks';
-
-import { createHistory, pushEdit, pushRecord, stepHistory, type History, type HistoryRecord } from '@/shared/lib/code/editor/history';
-
-/** The fields every write path needs: a buffer and where the caret goes. */
-export type HistoryEdit = Pick<HistoryRecord, 'value' | 'selectionStart' | 'selectionEnd'>;
-
-export interface EditorHistory {
-  /** The stack itself, for the typing-burst merge in the change handler. */
-  history: History;
-  /**
-   * The buffer as this component last knew it — its own writes included, and
-   * never a render behind. Diffing a browser edit has to start from here: the
-   * `value` prop lags a keystroke, and a stale `before` reads a one-character
-   * edit as a whole-word replacement.
-   */
-  readonly buffer: string;
-  /** Commit an edit as ONE undoable entry. */
-  commit: (edit: HistoryEdit) => void;
-  /**
-   * Commit an edit that SUPERSEDES the entry on top, keeping that entry's
-   * caret so undo returns to the selection the edit replaced.
-   */
-  commitEdit: (edit: HistoryEdit) => void;
-  /** Step the stack and restore the record; no-op at either end. */
-  step: (direction: 'undo' | 'redo') => void;
-  /**
-   * Declare a value the BROWSER produced as already applied, so the re-seed
-   * effect below does not record it a second time. The change handler calls
-   * this for every keystroke and every replicated multi-cursor edit.
-   */
-  markApplied: (value: string) => void;
-}
-
-export interface UseEditorHistoryOptions {
-  /** The controlled buffer, used to detect an external replacement. */
-  value: string;
-  /** The live `<textarea>`, so an external replacement records its own caret. */
-  inputRef: { current: HTMLTextAreaElement | null };
-  /** Push the committed buffer to the caller. */
-  onValueChange: (value: string) => void;
-}
-
-export function useEditorHistory({ value, inputRef, onValueChange }: UseEditorHistoryOptions): EditorHistory {
-  const historyRef = useRef<History>(createHistory());
-  /** The value this component itself last wrote — see the module note. */
-  const appliedRef = useRef<string | null>(null);
-
-  // Re-record when the controlled value is replaced from the outside
-  // (file switch, refresh) so undo does not jump between documents.
-  useEffect(() => {
-    const input = inputRef.current;
-    if (!input || appliedRef.current === value) return;
-    appliedRef.current = value;
-    pushRecord(historyRef.current, {
-      value: input.value,
-      selectionStart: input.selectionStart,
-      selectionEnd: input.selectionEnd,
-      timestamp: Date.now(),
-    });
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [value]);
-
-  /** Put a buffer on screen without touching the stack. */
-  const write = (edit: HistoryEdit) => {
-    appliedRef.current = edit.value;
-    onValueChange(edit.value);
-    const input = inputRef.current;
-    if (!input) return;
-    input.value = edit.value;
-    input.selectionStart = edit.selectionStart;
-    input.selectionEnd = edit.selectionEnd;
-  };
-
-  return {
-    history: historyRef.current,
-
-    get buffer() {
-      return appliedRef.current ?? value;
-    },
-
-    commit: (edit) => {
-      pushEdit(historyRef.current, { ...edit, timestamp: Date.now() });
-      write(edit);
-    },
-
-    commitEdit: (edit) => {
-      const history = historyRef.current;
-      const last = history.stack[history.offset];
-      const input = inputRef.current;
-      if (last && input) {
-        // The entry on top is about to be superseded: keep where its caret was,
-        // so undo returns to the selection this edit replaced.
-        history.stack[history.offset] = {
-          ...last,
-          selectionStart: input.selectionStart,
-          selectionEnd: input.selectionEnd,
-        };
-      }
-      pushEdit(history, { ...edit, timestamp: Date.now() });
-      write(edit);
-    },
-
-    step: (direction) => {
-      const record = stepHistory(historyRef.current, direction);
-      if (record) write(record);
-    },
-
-    markApplied: (next) => {
-      appliedRef.current = next;
-    },
-  };
-}

package/src/client/hooks/editor/use-occurrences.test.ts

@@ -1,236 +0,0 @@
-/**
- * @license
- * SPDX-License-Identifier: Apache-2.0
- */
-
-/**
- * `useOccurrences` — the ranges behind ⌘D, ⌘⇧L and ⌘⇧D.
- *
- * The rules live in `shared/lib/code/editor/occurrences` and are tested there;
- * what this file covers is the hook's own contract: the caller's copy wins
- * (clearing the ranges in the panel must clear them here), every change is
- * announced so the surface repaints, and the textarea is read rather than
- * assumed.
- *
- * Runs against a real DOM (happy-dom) because it is a Preact hook; the modules
- * below are imported dynamically, after those globals exist.
- */
-
-import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
-import { Window } from 'happy-dom';
-import type { h as PreactH, render as PreactRender } from 'preact';
-import type { act as PreactAct } from 'preact/test-utils';
-import type { OccurrencesApi, useOccurrences as UseOccurrencesHook } from '@/client/hooks/editor/use-occurrences';
-import type { TextRange } from '@/shared/lib/code/editor/commands';
-
-let useOccurrences: typeof UseOccurrencesHook;
-let h: typeof PreactH;
-let render: typeof PreactRender;
-let act: typeof PreactAct;
-
-let api: OccurrencesApi | null = null;
-let container: HTMLElement;
-let textarea: HTMLTextAreaElement;
-/** What the caller passes in as its own copy, changed per test. */
-let controlled: TextRange[] | undefined;
-const announced: Array<readonly TextRange[]> = [];
-const selections: Array<[number, number]> = [];
-
-function Harness() {
-  api = useOccurrences({
-    controlled,
-    onChange: (ranges) => announced.push(ranges),
-  });
-  return null;
-}
-
-async function flush() {
-  for (let i = 0; i < 3; i++) {
-    await act(async () => {
-      for (let turn = 0; turn < 4; turn++) await Promise.resolve();
-    });
-  }
-}
-
-async function rerender() {
-  await act(async () => {
-    render(h(Harness, {}), container);
-  });
-  await flush();
-}
-
-function select(start: number, end = start) {
-  textarea.selectionStart = start;
-  textarea.selectionEnd = end;
-}
-
-/**
- * Stands in for the editor's own `select`: it MOVES the textarea's selection and
- * records it. The hook reads the textarea, so a callback that only recorded the
- * range would leave every later press looking at the original caret.
- */
-function selectingSurface() {
-  return (start: number, end: number) => {
-    selections.push([start, end]);
-    select(start, end);
-  };
-}
-
-function domGlobals(win: Window): Record<string, unknown> {
-  return {
-    window: win,
-    document: win.document,
-    navigator: win.navigator,
-    Node: win.Node,
-    Element: win.Element,
-    HTMLElement: win.HTMLElement,
-    HTMLTextAreaElement: win.HTMLTextAreaElement,
-  };
-}
-
-const installed: Record<string, unknown> = {};
-const displaced: Record<string, unknown> = {};
-
-beforeAll(async () => {
-  const win = new Window({ url: 'http://localhost' });
-  for (const [key, value] of Object.entries(domGlobals(win))) {
-    displaced[key] = (globalThis as Record<string, unknown>)[key];
-    installed[key] = value;
-    (globalThis as Record<string, unknown>)[key] = value;
-  }
-  ({ useOccurrences } = await import('@/client/hooks/editor/use-occurrences'));
-  ({ h, render } = await import('preact'));
-  ({ act } = await import('preact/test-utils'));
-});
-
-afterAll(() => {
-  for (const key of Object.keys(installed)) {
-    if (displaced[key] === undefined) delete (globalThis as Record<string, unknown>)[key];
-    else (globalThis as Record<string, unknown>)[key] = displaced[key];
-  }
-});
-
-beforeEach(async () => {
-  api = null;
-  controlled = undefined;
-  announced.length = 0;
-  selections.length = 0;
-  container = document.createElement('div');
-  document.body.appendChild(container);
-  textarea = document.createElement('textarea');
-  textarea.value = 'alpha beta alpha gamma alpha';
-  container.appendChild(textarea);
-  await rerender();
-});
-
-afterEach(() => {
-  if (container) render(null, container);
-  container?.remove();
-});
-
-describe('useOccurrences', () => {
-  test('starts with no extra ranges', () => {
-    expect(api?.ranges).toEqual([]);
-  });
-
-  test('⌘D selects the word first, then grows one occurrence per press', async () => {
-    select(2);
-    await act(async () => {
-      api?.selectNext(textarea, selectingSurface());
-    });
-    expect(selections.at(-1)).toEqual([0, 5]);
-    expect(api?.ranges).toEqual([]);
-
-    await act(async () => {
-      api?.selectNext(textarea, selectingSurface());
-    });
-    expect(api?.ranges).toEqual([{ start: 11, end: 16 }]);
-  });
-
-  test('⌘⇧L takes every occurrence, primary first', async () => {
-    select(0, 5);
-    await act(async () => {
-      api?.selectAll(textarea, selectingSurface());
-    });
-
-    expect(selections.at(-1)).toEqual([0, 5]);
-    expect(api?.ranges).toEqual([
-      { start: 11, end: 16 },
-      { start: 23, end: 28 },
-    ]);
-  });
-
-  test('every change is announced so the surface can repaint', async () => {
-    select(0, 5);
-    await act(async () => {
-      api?.selectAll(textarea, () => {});
-    });
-
-    expect(announced.at(-1)?.length).toBe(2);
-  });
-
-  test('clear drops every range and says so', async () => {
-    select(0, 5);
-    await act(async () => {
-      api?.selectAll(textarea, () => {});
-    });
-    await act(async () => {
-      api?.clear();
-    });
-
-    expect(api?.ranges).toEqual([]);
-    expect(announced.at(-1)).toEqual([]);
-  });
-
-  test('the caller’s copy is authoritative', async () => {
-    // The panel can clear the ranges without the editor asking (a file switch,
-    // a save); the hook has to follow, not keep its own stale list.
-    controlled = [{ start: 1, end: 3 }];
-    await rerender();
-
-    expect(api?.ranges).toEqual([{ start: 1, end: 3 }]);
-
-    controlled = [];
-    await rerender();
-
-    expect(api?.ranges).toEqual([]);
-  });
-
-  test('⌘⇧D adds a caret below on the same column', async () => {
-    textarea.value = 'one\ntwo\nthree';
-    select(1);
-    await act(async () => {
-      api?.insertCursorBelow(textarea);
-    });
-
-    expect(api?.ranges).toEqual([{ start: 5, end: 5 }]);
-  });
-
-  test('⌘⇧D on the last line adds nothing', async () => {
-    textarea.value = 'one\ntwo';
-    select(5);
-    await act(async () => {
-      api?.insertCursorBelow(textarea);
-    });
-
-    expect(api?.ranges).toEqual([]);
-  });
-
-  test('replicate reports nothing without extra ranges', () => {
-    expect(api?.replicate('abc', 'abXc', { start: 2, end: 2 })).toBeNull();
-  });
-
-  test('replicate replays the browser’s edit at every extra range', async () => {
-    select(0, 5);
-    await act(async () => {
-      api?.selectAll(textarea, () => {});
-    });
-
-    // The browser replaced `alpha` at 0..5 with `Z`; the other two follow.
-    const applied = api?.replicate('alpha beta alpha gamma alpha', 'Z beta alpha gamma alpha', { start: 0, end: 5 });
-
-    expect(applied?.value).toBe('Z beta Z gamma Z');
-    expect(applied?.caret).toBe(1);
-    expect(applied?.rest.length).toBe(2);
-  });
-});

package/src/client/hooks/editor/use-occurrences.ts

@@ -1,98 +0,0 @@
-/**
- * @license
- * SPDX-License-Identifier: Apache-2.0
- */
-
-/**
- * The hook that owns the editor's extra selection ranges.
- *
- * It is a thin shell over `shared/lib/code/editor/occurrences`: the rules live
- * there as pure functions, and this holds the ranges in a ref (the keydown and
- * `input` handlers read them synchronously, inside one event) and tells the
- * caller through `onChange` so the surface can paint them.
- *
- * The split is deliberate: a hook that decides where a range goes cannot be
- * tested without a DOM, and every rule here is one a user notices when it is
- * wrong.
- */
-
-import { useRef } from 'preact/hooks';
-
-import {
-  growToNextOccurrence,
-  offsetBelow,
-  replicateAtRanges,
-  selectAllOccurrences,
-} from '@/shared/lib/code/editor/occurrences';
-import type { TextRange } from '@/shared/lib/code/editor/commands';
-
-export interface UseOccurrencesOptions {
-  /** Called with the extra ranges whenever they change, so the surface repaints. */
-  onChange: (ranges: readonly TextRange[]) => void;
-  /** The caller's copy of the ranges — clearing them there must clear them here. */
-  controlled?: readonly TextRange[];
-}
-
-export interface OccurrencesApi {
-  /** The extra ranges, excluding the textarea's own (primary) selection. */
-  readonly ranges: readonly TextRange[];
-  /** Replace the ranges and notify the surface. */
-  set: (ranges: readonly TextRange[]) => void;
-  /** Drop every extra range. */
-  clear: () => void;
-  /** ⌘D — grow the primary selection to the next occurrence of what it covers. */
-  selectNext: (input: HTMLTextAreaElement, select: (start: number, end: number) => void) => void;
-  /** ⌘⇧L — select every occurrence of the selection/word at the caret. */
-  selectAll: (input: HTMLTextAreaElement, select: (start: number, end: number) => void) => void;
-  /** ⌘⇧D — add an empty caret on the line below. */
-  insertCursorBelow: (input: HTMLTextAreaElement) => void;
-  /**
-   * Replay the browser's edit at every extra range. Returns the buffer and
-   * caret the caller should commit, or null when there is nothing to replicate.
-   */
-  replicate: (before: string, after: string, primaryBefore: TextRange) => { value: string; caret: number; rest: TextRange[] } | null;
-}
-
-export function useOccurrences({ onChange, controlled }: UseOccurrencesOptions): OccurrencesApi {
-  const ref = useRef<readonly TextRange[]>([]);
-  // The caller may clear the ranges without the editor asking (a file switch, a
-  // save), so its copy is mirrored into the ref the handlers read.
-  if (controlled && controlled !== ref.current) ref.current = controlled;
-
-  const set = (ranges: readonly TextRange[]) => {
-    ref.current = ranges;
-    onChange(ranges);
-  };
-
-  return {
-    get ranges() {
-      return ref.current;
-    },
-    set,
-    clear: () => set([]),
-
-    selectNext: (input, select) => {
-      const current: TextRange = { start: input.selectionStart, end: input.selectionEnd };
-      const next = growToNextOccurrence(input.value, current, ref.current);
-      if (!next) return;
-      select(next.primary.start, next.primary.end);
-      set(next.extras);
-    },
-
-    selectAll: (input, select) => {
-      const current: TextRange = { start: input.selectionStart, end: input.selectionEnd };
-      const all = selectAllOccurrences(input.value, current);
-      if (!all) return;
-      select(all.primary.start, all.primary.end);
-      set(all.extras);
-    },
-
-    insertCursorBelow: (input) => {
-      const target = offsetBelow(input.value, input.selectionStart);
-      if (target === null) return;
-      set([...ref.current, { start: target, end: target }]);
-    },
-
-    replicate: (before, after, primaryBefore) => replicateAtRanges(before, after, primaryBefore, ref.current),
-  };
-}