@kabmo-labs/kabmo 0.8.0 → 0.9.0

package/src/client/hooks/editor/scroll-container.test.ts

@@ -1,102 +0,0 @@
-/**
- * @license
- * SPDX-License-Identifier: Apache-2.0
- */
-
-/**
- * The scroll-container walk, shared by the editor's lazy window and the find
- * widget's reveal.
- *
- * The two must agree: one resolves which lines to draw from the visible band,
- * the other moves that band. Two copies of this walk would let the widget scroll
- * a container the window never reads — the match would be marked somewhere
- * nobody can see. Exercised against a real DOM (happy-dom) because the answer is
- * a computed style.
- */
-
-import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
-import { Window } from 'happy-dom';
-
-import { findScrollContainer } from '@/client/hooks/editor/scroll-container';
-
-const installed: Record<string, unknown> = {};
-const displaced: Record<string, unknown> = {};
-
-beforeAll(() => {
-  const win = new Window({ url: 'http://localhost' });
-  for (const key of ['window', 'document', 'Node', 'Element', 'HTMLElement', 'getComputedStyle']) {
-    displaced[key] = (globalThis as Record<string, unknown>)[key];
-    installed[key] = (win as unknown as Record<string, unknown>)[key];
-    (globalThis as Record<string, unknown>)[key] = installed[key];
-  }
-});
-
-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];
-  }
-});
-
-/** An element whose computed style reports `overflow-y`, with a scrollable height. */
-function makeElement(overflowY: string, scrollable: boolean): HTMLElement {
-  const element = document.createElement('div');
-  element.style.overflowY = overflowY;
-  if (scrollable) {
-    // happy-dom reports clientHeight 0, so the walk's `scrollHeight > clientHeight`
-    // test needs a stubbed pair to describe a container that can actually scroll.
-    Object.defineProperty(element, 'scrollHeight', { value: 400, configurable: true });
-    Object.defineProperty(element, 'clientHeight', { value: 100, configurable: true });
-  }
-  return element;
-}
-
-describe('findScrollContainer', () => {
-  test('finds the nearest ancestor that scrolls', () => {
-    const outer = makeElement('auto', true);
-    const inner = makeElement('visible', false);
-    const surface = document.createElement('div');
-    inner.appendChild(surface);
-    outer.appendChild(inner);
-    document.body.appendChild(outer);
-
-    expect(findScrollContainer(surface)).toBe(outer);
-    outer.remove();
-  });
-
-  test('skips a container that cannot actually scroll', () => {
-    // `overflow: auto` on a box whose content fits is not a scroller: returning
-    // it would make `revealOffset` write scrollTop onto a box that ignores it.
-    const outer = makeElement('auto', true);
-    const fitted = makeElement('auto', false);
-    const surface = document.createElement('div');
-    fitted.appendChild(surface);
-    outer.appendChild(fitted);
-    document.body.appendChild(outer);
-
-    expect(findScrollContainer(surface)).toBe(outer);
-    outer.remove();
-  });
-
-  test('reports nothing when no ancestor scrolls', () => {
-    const plain = document.createElement('div');
-    const surface = document.createElement('div');
-    plain.appendChild(surface);
-    document.body.appendChild(plain);
-
-    expect(findScrollContainer(surface)).toBeNull();
-    plain.remove();
-  });
-
-  test('prefers the nearest scroller, so a nested panel scrolls itself', () => {
-    const outer = makeElement('auto', true);
-    const inner = makeElement('scroll', true);
-    const surface = document.createElement('div');
-    inner.appendChild(surface);
-    outer.appendChild(inner);
-    document.body.appendChild(outer);
-
-    expect(findScrollContainer(surface)).toBe(inner);
-    outer.remove();
-  });
-});

package/src/client/hooks/editor/scroll-container.ts

@@ -1,26 +0,0 @@
-/**
- * @license
- * SPDX-License-Identifier: Apache-2.0
- */
-
-/**
- * The ancestor a code surface actually scrolls inside.
- *
- * The lazy editor window and the find widget's "scroll to this match" both need
- * this answer, and they must agree: one resolves which lines to draw from the
- * visible band, the other moves that band. Two copies of the walk would let the
- * widget scroll a container the window never reads.
- *
- * Walks up rather than taking a ref: the surface is mounted under different
- * scrollers (the desktop editor panel, the phone's full-screen editor) and is
- * also mounted inside a page that scrolls itself, which is the `null` case.
- */
-export function findScrollContainer(element: HTMLElement): HTMLElement | null {
-  for (let node = element.parentElement; node; node = node.parentElement) {
-    const overflowY = getComputedStyle(node).overflowY;
-    if ((overflowY === 'auto' || overflowY === 'scroll' || overflowY === 'overlay') && node.scrollHeight > node.clientHeight) {
-      return node;
-    }
-  }
-  return null;
-}

package/src/client/hooks/editor/use-code-window.ts

@@ -1,100 +0,0 @@
-import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'preact/hooks';
-import type { RefObject } from 'preact';
-
-import { codeWindow, firstWindow, resolveWindow, sameWindow, type CodeWindow, type LineGeometry, type LineWindow } from '@/shared/lib/code/lazy-window';
-import { findScrollContainer } from '@/client/hooks/editor/scroll-container';
-
-export interface UseCodeWindowOptions {
-  /** The surface's root box: the frame every line offset in `geometry` is measured from. */
-  rootRef: RefObject<HTMLElement | null>;
-  /** Lines in the document on screen. */
-  lineCount: number;
-  /** Document geometry, or null until the wrap/row measurement lands. */
-  geometry: LineGeometry | null;
-  /** False for short documents (they render whole) and when geometry cannot be measured. */
-  enabled: boolean;
-}
-
-/**
- * The lines visible inside the scroll container `root` lives in.
- *
- * Both rectangles are read in viewport coordinates, so this needs no knowledge
- * of scroll offsets: the part of the editor's box the container actually shows
- * is exactly the band between the two.
- */
-function visibleWindow(root: HTMLElement, geometry: LineGeometry): LineWindow {
-  const frameTop = root.getBoundingClientRect().top;
-  const container = findScrollContainer(root);
-  const viewTop = container ? container.getBoundingClientRect().top : 0;
-  const viewBottom = container
-    ? container.getBoundingClientRect().bottom
-    : globalThis.innerHeight || geometry.rowHeight;
-  return resolveWindow(geometry, viewTop - frameTop, viewBottom - viewTop);
-}
-
-/**
- * Rendering window for the lazy editor surface.
- *
- * A long document is highlighted, gutters and all, only where it can be seen;
- * this hook owns which lines those are and re-resolves them on scroll, on
- * resize, and whenever the geometry moves (a keystroke re-wraps a line). The
- * scroll listener is a capturing one on the window: scroll events do not
- * bubble, but they do reach a capturing listener, so the surface follows
- * whichever ancestor scrolls — the desktop editor panel, the phone's
- * full-screen editor, or the page.
- *
- * Returns null for a document that renders whole, which is the caller's cue to
- * keep the plain, unwindowed surface.
- */
-export function useCodeWindow({ rootRef, lineCount, geometry, enabled }: UseCodeWindowOptions): CodeWindow | null {
-  const [lineWindow, setLineWindow] = useState<LineWindow | null>(null);
-
-  const compute = useCallback(() => {
-    const root = rootRef.current;
-    if (!enabled || !root) return;
-    const next = geometry ? visibleWindow(root, geometry) : firstWindow(lineCount);
-    setLineWindow((previous) => (sameWindow(previous, next) ? previous : next));
-  }, [enabled, geometry, lineCount, rootRef]);
-
-  // Layout effect: the first window has to be resolved before the browser
-  // paints, or a long document flashes its untouched opening lines.
-  useLayoutEffect(() => {
-    compute();
-  }, [compute]);
-
-  // The listeners follow `enabled`, not `compute`: re-resolving on every
-  // keystroke must not tear down and rebuild the observer each time.
-  const computeRef = useRef(compute);
-  computeRef.current = compute;
-  useEffect(() => {
-    if (!enabled) return;
-    let frame = 0;
-    const schedule = () => {
-      if (frame) return;
-      frame = requestAnimationFrame(() => {
-        frame = 0;
-        computeRef.current();
-      });
-    };
-    window.addEventListener('scroll', schedule, { passive: true, capture: true });
-    window.addEventListener('resize', schedule);
-    const observer = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(schedule);
-    const root = rootRef.current;
-    if (root) observer?.observe(root);
-    return () => {
-      if (frame) cancelAnimationFrame(frame);
-      window.removeEventListener('scroll', schedule, { capture: true });
-      window.removeEventListener('resize', schedule);
-      observer?.disconnect();
-    };
-  }, [enabled, rootRef]);
-
-  if (!enabled) return null;
-  if (!geometry) {
-    // First commit: the layout effect above lands the real window in the same
-    // frame, so this only bounds how much the opening render is allowed to draw.
-    const opening = firstWindow(lineCount);
-    return { ...opening, top: 0, bottom: 0, breakAtEnd: opening.end >= lineCount };
-  }
-  return codeWindow(geometry, lineWindow ?? firstWindow(geometry.lineCount));
-}

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;
-    },
-  };
-}