@elabs-ai/components-editor 4.0.0

package/src/lib/editor-content-access.test.ts

@@ -0,0 +1,182 @@
+/**
+ * Unit tests for monacoContentAccess — the Monaco adapter for EditorContentAccess.
+ *
+ * Monaco can't render in jsdom, so we mock the editor instance and assert the
+ * adapter's pure-logic contract (the markdown-commands.test.ts precedent).
+ * Live Monaco behavior (real selection round-trips) is verified in Storybook.
+ */
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// Mock monaco-editor (pure value types only; no rendering engine needed).
+vi.mock("monaco-editor", () => ({
+  editor: {},
+}));
+
+import { monacoContentAccess } from "./editor-content-access";
+
+// ---------------------------------------------------------------------------
+// Minimal Monaco editor mock — mirrors the shape used by markdown-commands.test.ts
+// ---------------------------------------------------------------------------
+
+function makeMockEditor(selectedText = "", isEmpty = false) {
+  const selectionChangeHandlers: Array<() => void> = [];
+  const disposable = { dispose: vi.fn() };
+
+  const selection = {
+    isEmpty: vi.fn(() => isEmpty),
+  };
+  const model = {
+    getValueInRange: vi.fn(() => selectedText),
+  };
+  const editor = {
+    getModel: vi.fn(() => model),
+    getSelection: vi.fn(() => selection),
+    getValue: vi.fn(() => "full document text"),
+    executeEdits: vi.fn(),
+    pushUndoStop: vi.fn(),
+    focus: vi.fn(),
+    onDidChangeCursorSelection: vi.fn((cb: () => void) => {
+      selectionChangeHandlers.push(cb);
+      return disposable;
+    }),
+  };
+  return { editor, model, selection, disposable, selectionChangeHandlers };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+beforeEach(() => vi.clearAllMocks());
+
+describe("monacoContentAccess — getText", () => {
+  it("returns editor.getValue()", () => {
+    const { editor } = makeMockEditor();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const access = monacoContentAccess(editor as any);
+    expect(access.getText()).toBe("full document text");
+    expect(editor.getValue).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("monacoContentAccess — getSelection", () => {
+  it("maps getValueInRange to text, isEmpty() to empty:false when selected", () => {
+    const { editor } = makeMockEditor("bold text", false);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const access = monacoContentAccess(editor as any);
+    const sel = access.getSelection();
+    expect(sel.text).toBe("bold text");
+    expect(sel.empty).toBe(false);
+  });
+
+  it("returns empty:true and text:'' for a collapsed caret", () => {
+    const { editor } = makeMockEditor("", true);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const access = monacoContentAccess(editor as any);
+    const sel = access.getSelection();
+    expect(sel.text).toBe("");
+    expect(sel.empty).toBe(true);
+  });
+
+  it("returns empty:true when getSelection() returns null", () => {
+    const { editor } = makeMockEditor("", false);
+    editor.getSelection.mockReturnValue(null as unknown as ReturnType<typeof editor.getSelection>);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const access = monacoContentAccess(editor as any);
+    expect(access.getSelection()).toEqual({ text: "", empty: true });
+  });
+
+  it("returns empty:true when getModel() returns null", () => {
+    const { editor } = makeMockEditor("text", false);
+    editor.getModel.mockReturnValue(null as unknown as ReturnType<typeof editor.getModel>);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const access = monacoContentAccess(editor as any);
+    expect(access.getSelection()).toEqual({ text: "", empty: true });
+  });
+});
+
+describe("monacoContentAccess — replaceSelection / insertAtCursor", () => {
+  it("replaceSelection calls executeEdits with the selection range + text", () => {
+    const { editor, selection } = makeMockEditor("old", false);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const access = monacoContentAccess(editor as any);
+    access.replaceSelection("new text");
+    expect(editor.executeEdits).toHaveBeenCalledWith("editor-content-access", [
+      { range: selection, text: "new text", forceMoveMarkers: true },
+    ]);
+    expect(editor.pushUndoStop).toHaveBeenCalledTimes(1);
+  });
+
+  it("insertAtCursor calls executeEdits identically (same primitive)", () => {
+    const { editor, selection } = makeMockEditor("", true);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const access = monacoContentAccess(editor as any);
+    access.insertAtCursor("inserted");
+    expect(editor.executeEdits).toHaveBeenCalledWith("editor-content-access", [
+      { range: selection, text: "inserted", forceMoveMarkers: true },
+    ]);
+    expect(editor.pushUndoStop).toHaveBeenCalledTimes(1);
+  });
+
+  it("no-ops when getSelection() returns null", () => {
+    const { editor } = makeMockEditor();
+    editor.getSelection.mockReturnValue(null as unknown as ReturnType<typeof editor.getSelection>);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const access = monacoContentAccess(editor as any);
+    access.replaceSelection("x");
+    expect(editor.executeEdits).not.toHaveBeenCalled();
+  });
+});
+
+describe("monacoContentAccess — focus", () => {
+  it("calls editor.focus()", () => {
+    const { editor } = makeMockEditor();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const access = monacoContentAccess(editor as any);
+    access.focus();
+    expect(editor.focus).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("monacoContentAccess — onSelectionChange", () => {
+  it("registers onDidChangeCursorSelection and fires the listener with a fresh snapshot", () => {
+    const { editor, selectionChangeHandlers, model, selection } = makeMockEditor("abc", false);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const access = monacoContentAccess(editor as any);
+    const listener = vi.fn();
+    access.onSelectionChange(listener);
+
+    expect(editor.onDidChangeCursorSelection).toHaveBeenCalledTimes(1);
+
+    // Simulate Monaco firing the selection-change event.
+    model.getValueInRange.mockReturnValue("xyz");
+    selectionChangeHandlers[0]?.();
+
+    expect(listener).toHaveBeenCalledWith({ text: "xyz", empty: false });
+    expect(selection.isEmpty).toHaveBeenCalled();
+  });
+
+  it("returns an unsubscribe fn that calls disposable.dispose()", () => {
+    const { editor, disposable } = makeMockEditor();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const access = monacoContentAccess(editor as any);
+    const unsub = access.onSelectionChange(vi.fn());
+    expect(disposable.dispose).not.toHaveBeenCalled();
+    unsub();
+    expect(disposable.dispose).toHaveBeenCalledTimes(1);
+  });
+
+  it("calling the unsubscribe calls dispose() on the Monaco IDisposable", () => {
+    // Contract: the adapter calls sub.dispose() when the caller unsubscribes.
+    // In production Monaco stops firing the handler after dispose(); in jsdom
+    // the mock doesn't truly gate on dispose, so we assert the dispose call
+    // rather than trying to gate the mock handler.
+    const { editor, disposable } = makeMockEditor();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const access = monacoContentAccess(editor as any);
+    const unsub = access.onSelectionChange(vi.fn());
+    expect(disposable.dispose).not.toHaveBeenCalled();
+    unsub();
+    expect(disposable.dispose).toHaveBeenCalledTimes(1);
+  });
+});

package/src/lib/editor-content-access.ts

@@ -0,0 +1,109 @@
+/**
+ * Engine-agnostic editor content-access interface + Monaco adapter.
+ *
+ * ISOLATION INVARIANT: this file imports ONLY `monaco-editor` and the
+ * `MonacoCodeEditor` type from `../code-editor`. It MUST NOT import
+ * `editor-content-access-prose.ts` or anything from `@milkdown`, or the
+ * `@milkdown` graph leaks into the `.` barrel (#271-inverse).
+ */
+import type { MonacoCodeEditor } from "../code-editor";
+
+/** A snapshot of the editor's current selection. Text, not engine positions —
+ *  that is what an AI assistant needs and it keeps the interface engine-agnostic. */
+export interface EditorSelection {
+  /**
+   * The selected text. Plain text for Monaco. For the Milkdown WYSIWYG it is the
+   * selection SERIALIZED TO MARKDOWN by default (so `**bold**`, links, lists round-trip);
+   * pass `{ fidelity: "plainText" }` to the adapter to get `doc.textBetween` instead.
+   */
+  text: string;
+  /** `true` when the selection is collapsed (a bare caret, nothing highlighted). */
+  empty: boolean;
+}
+
+/**
+ * Engine-agnostic, text-oriented access to an editor's content + selection — the
+ * uniform surface an external AI assistant drives across the Monaco code editors
+ * AND the Milkdown WYSIWYG markdown editor.
+ *
+ * D5: this manipulates EDITOR CONTENT only. It performs no model calls, no transport,
+ * no fetch. The app owns the AI call and APPLIES the result via these methods.
+ *
+ * `replaceSelection` and `insertAtCursor` are equivalent primitives (both replace the
+ * active range; an empty range is the caret) — two names for two reader intents.
+ */
+export interface EditorContentAccess {
+  /** The full document text (Monaco: source; Milkdown: serialized markdown). */
+  getText(): string;
+  /** A snapshot of the current selection (selected text + whether collapsed). */
+  getSelection(): EditorSelection;
+  /** Replace the current selection; a collapsed selection inserts at the caret. */
+  replaceSelection(text: string): void;
+  /**
+   * Insert at the caret; a non-empty selection is replaced (platform "typing" semantics).
+   * Equivalent to `replaceSelection` — two names for two reader intents (agent-legibility).
+   */
+  insertAtCursor(text: string): void;
+  /** Move focus to the editing surface (so the user can keep typing after an apply). */
+  focus(): void;
+  /**
+   * Subscribe to selection changes. Fires with a fresh `EditorSelection` whenever the
+   * selection or caret moves. Returns an unsubscribe function — the caller MUST call it
+   * (e.g. in a React effect cleanup) to dispose the underlying engine listener.
+   */
+  onSelectionChange(listener: (selection: EditorSelection) => void): () => void;
+}
+
+/**
+ * Wrap a live Monaco `IStandaloneCodeEditor` as the engine-agnostic
+ * {@link EditorContentAccess}. The `CodeEditor` / `DiffEditor` / `CodeWorkspace`
+ * `ref` already exposes the raw Monaco instance — pass it here to get the
+ * uniform shape used by the markdown surfaces.
+ *
+ * For a `DiffEditor`, pass the modified (editable) side:
+ * `monacoContentAccess(diffRef.current!.getModifiedEditor())`.
+ *
+ * @example
+ *   const editorRef = useRef<MonacoCodeEditor>(null);
+ *   // ...later
+ *   const access = monacoContentAccess(editorRef.current!);
+ *   access.insertAtCursor(aiText);
+ */
+export function monacoContentAccess(editor: MonacoCodeEditor): EditorContentAccess {
+  const readSelection = (): EditorSelection => {
+    const model = editor.getModel();
+    const selection = editor.getSelection();
+    if (!model || !selection) return { text: "", empty: true };
+    const text = model.getValueInRange(selection);
+    return { text, empty: selection.isEmpty() };
+  };
+
+  /**
+   * Replace the active selection range. An empty selection (caret) inserts at
+   * the caret — one path covers both insert & replace (executeEdits over an empty
+   * range == insert at that position, exactly the markdown-commands.ts pattern).
+   */
+  const applyAtSelection = (text: string): void => {
+    const selection = editor.getSelection();
+    if (!selection) return;
+    editor.executeEdits("editor-content-access", [
+      { range: selection, text, forceMoveMarkers: true },
+    ]);
+    // An explicit undo stop makes this AI apply independently undoable. The
+    // toolbar helpers omit it because they immediately re-select (their own stop);
+    // for the AI path an explicit stop is the right call.
+    editor.pushUndoStop();
+  };
+
+  return {
+    getText: () => editor.getValue(),
+    getSelection: readSelection,
+    replaceSelection: applyAtSelection,
+    insertAtCursor: applyAtSelection,
+    focus: () => editor.focus(),
+    onSelectionChange: (listener) => {
+      const sub = editor.onDidChangeCursorSelection(() => listener(readSelection()));
+      return () => sub.dispose();
+    },
+  };
+}

package/src/lib/languages.ts

@@ -0,0 +1,32 @@
+/**
+ * Curated language list for the editor toolbar's language picker. Ids are
+ * Monaco's built-in language ids (`monaco.languages.getLanguages()`), so they
+ * map straight onto `setModelLanguage` / model creation.
+ */
+export interface EditorLanguage {
+  /** Monaco language id (e.g. "typescript"). */
+  id: string;
+  /** Human-readable label for the picker. */
+  label: string;
+}
+
+export const EDITOR_LANGUAGES: EditorLanguage[] = [
+  { id: "typescript", label: "TypeScript" },
+  { id: "javascript", label: "JavaScript" },
+  { id: "json", label: "JSON" },
+  { id: "html", label: "HTML" },
+  { id: "css", label: "CSS" },
+  { id: "scss", label: "SCSS" },
+  { id: "markdown", label: "Markdown" },
+  { id: "python", label: "Python" },
+  { id: "sql", label: "SQL" },
+  { id: "yaml", label: "YAML" },
+  { id: "xml", label: "XML" },
+  { id: "shell", label: "Shell" },
+  { id: "plaintext", label: "Plain text" },
+];
+
+/** Look up a language's label, falling back to the raw id. */
+export function languageLabel(id: string): string {
+  return EDITOR_LANGUAGES.find((l) => l.id === id)?.label ?? id;
+}

package/src/lib/markdown/diff.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  annotationForRange,
+  computeMarkdownAnnotations,
+  removedMarkerAt,
+  shiftAnnotations,
+} from "./diff";
+
+describe("computeMarkdownAnnotations", () => {
+  it("returns [] for identical inputs", () => {
+    expect(computeMarkdownAnnotations("a\nb", "a\nb")).toEqual([]);
+  });
+
+  it("flags pure additions with after-relative 1-based lines", () => {
+    const before = "one\ntwo";
+    const after = "one\nnew line\ntwo";
+    expect(computeMarkdownAnnotations(before, after)).toEqual([
+      { kind: "added", startLine: 2, endLine: 2 },
+    ]);
+  });
+
+  it("flags replaced runs as modified", () => {
+    const before = "# Title\n\nold paragraph\n";
+    const after = "# Title\n\nnew paragraph\n";
+    expect(computeMarkdownAnnotations(before, after)).toEqual([
+      { kind: "modified", startLine: 3, endLine: 3 },
+    ]);
+  });
+
+  it("anchors pure deletions on the next surviving line", () => {
+    const before = "one\ngone\ngone too\ntwo";
+    const after = "one\ntwo";
+    expect(computeMarkdownAnnotations(before, after)).toEqual([
+      { kind: "removed-before", startLine: 2, endLine: 2, removedCount: 2 },
+    ]);
+  });
+
+  it("clamps a trailing deletion to the last line", () => {
+    const before = "one\ntwo\nthree";
+    const after = "one";
+    const [ann] = computeMarkdownAnnotations(before, after);
+    expect(ann).toEqual({ kind: "removed-before", startLine: 1, endLine: 1, removedCount: 2 });
+  });
+
+  it("merges adjacent hunks of the same kind", () => {
+    const before = "a\nb\nc";
+    const after = "a\nx\ny\nb\nz\nc";
+    const anns = computeMarkdownAnnotations(before, after);
+    expect(anns.every((x) => x.kind === "added")).toBe(true);
+  });
+});
+
+describe("shiftAnnotations", () => {
+  it("shifts by the frontmatter offset and drops swallowed hunks", () => {
+    const anns = shiftAnnotations(
+      [
+        { kind: "added" as const, startLine: 2, endLine: 3 },
+        { kind: "added" as const, startLine: 6, endLine: 7 },
+      ],
+      4,
+    );
+    expect(anns).toEqual([{ kind: "added", startLine: 2, endLine: 3 }]);
+  });
+});
+
+describe("annotationForRange / removedMarkerAt", () => {
+  const anns = [
+    { kind: "added" as const, startLine: 3, endLine: 5 },
+    { kind: "removed-before" as const, startLine: 8, endLine: 8, removedCount: 2 },
+  ];
+  it("finds overlapping wash", () => {
+    expect(annotationForRange(anns, 5, 6)?.kind).toBe("added");
+    expect(annotationForRange(anns, 6, 7)).toBeUndefined();
+  });
+  it("finds the removed marker only at its anchor line", () => {
+    expect(removedMarkerAt(anns, 8)?.removedCount).toBe(2);
+    expect(removedMarkerAt(anns, 9)).toBeUndefined();
+  });
+});

package/src/lib/markdown/diff.ts

@@ -0,0 +1,194 @@
+/**
+ * Line-level markdown diff → block annotations for `MarkdownPreview` (#L18).
+ *
+ * `computeMarkdownAnnotations(before, after)` diffs two markdown sources and
+ * returns the annotation set the preview renders as a "ghost diff": added /
+ * modified blocks get a wash + accent rail, pure deletions become a slim
+ * "removed here" marker before the next surviving block.
+ *
+ * Lines are 1-based and refer to the AFTER source **including** any YAML
+ * frontmatter — `MarkdownPreview` shifts them when it strips frontmatter, so
+ * callers never have to think about the offset.
+ *
+ * The diff is a classic LCS (O(n·m) DP) — markdown documents are
+ * authoring-sized. Inputs beyond {@link MAX_DIFF_LINES} lines fall back to an
+ * empty annotation set (the UI simply shows no wash) instead of freezing.
+ */
+
+export type MarkdownAnnotationKind = "added" | "modified" | "removed-before";
+
+export interface MarkdownAnnotation {
+  kind: MarkdownAnnotationKind;
+  /**
+   * For `added`/`modified`: the 1-based inclusive line range in the AFTER
+   * source. For `removed-before`: `startLine === endLine` is the line in the
+   * AFTER source that now sits where the removed content used to be.
+   */
+  startLine: number;
+  endLine: number;
+  /** For `removed-before`: how many lines were removed. */
+  removedCount?: number;
+}
+
+/** Above this many lines on either side the diff degrades to "no annotations". */
+export const MAX_DIFF_LINES = 5000;
+
+const splitLines = (s: string): string[] => s.split("\n");
+
+/**
+ * LCS keep-table via dynamic programming. Returns pairs of kept (before-index,
+ * after-index) in ascending order. Indices are 0-based.
+ *
+ * Exported for the normalization-aware merge (`merge.ts`) — not public API.
+ */
+export function lcsPairs(a: string[], b: string[]): [number, number][] {
+  const n = a.length;
+  const m = b.length;
+  // dp rows as typed arrays to keep memory flat.
+  const dp: Uint32Array[] = Array.from({ length: n + 1 }, () => new Uint32Array(m + 1));
+  for (let i = n - 1; i >= 0; i--) {
+    const row = dp[i]!;
+    const next = dp[i + 1]!;
+    for (let j = m - 1; j >= 0; j--) {
+      row[j] = a[i] === b[j] ? next[j + 1]! + 1 : Math.max(next[j]!, row[j + 1]!);
+    }
+  }
+  const pairs: [number, number][] = [];
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) {
+      pairs.push([i, j]);
+      i++;
+      j++;
+    } else if (dp[i + 1]![j]! >= dp[i]![j + 1]!) {
+      i++;
+    } else {
+      j++;
+    }
+  }
+  return pairs;
+}
+
+/**
+ * Diff two markdown sources into preview annotations.
+ *
+ * Hunk semantics: a run of only-added lines → `added`; a run that replaces
+ * removed lines → `modified`; a run of only-removed lines → `removed-before`
+ * anchored on the first surviving AFTER line at-or-after the removal.
+ */
+export function computeMarkdownAnnotations(before: string, after: string): MarkdownAnnotation[] {
+  if (before === after) return [];
+  const a = splitLines(before);
+  const b = splitLines(after);
+  if (a.length > MAX_DIFF_LINES || b.length > MAX_DIFF_LINES) return [];
+
+  const pairs = lcsPairs(a, b);
+  const annotations: MarkdownAnnotation[] = [];
+
+  let prevA = -1;
+  let prevB = -1;
+  // Sentinel pair past the end flushes the trailing hunk.
+  const walk: [number, number][] = [...pairs, [a.length, b.length]];
+  for (const [ai, bi] of walk) {
+    const removed = ai - prevA - 1;
+    const added = bi - prevB - 1;
+    if (added > 0 && removed > 0) {
+      annotations.push({ kind: "modified", startLine: prevB + 2, endLine: bi });
+    } else if (added > 0) {
+      annotations.push({ kind: "added", startLine: prevB + 2, endLine: bi });
+    } else if (removed > 0) {
+      // Anchor on the next surviving AFTER line (1-based); clamp into range.
+      const anchor = Math.min(bi + 1, b.length);
+      annotations.push({
+        kind: "removed-before",
+        startLine: anchor,
+        endLine: anchor,
+        removedCount: removed,
+      });
+    }
+    prevA = ai;
+    prevB = bi;
+  }
+  return mergeAdjacent(annotations);
+}
+
+/** Honest "+a −r" totals for an annotation set (commit churn, drift rows). */
+export function summarizeAnnotations(annotations: MarkdownAnnotation[]): {
+  added: number;
+  removed: number;
+} {
+  let added = 0;
+  let removed = 0;
+  for (const a of annotations) {
+    const span = a.endLine - a.startLine + 1;
+    if (a.kind === "added") added += span;
+    else if (a.kind === "modified") {
+      added += span;
+      removed += span;
+    } else if (a.kind === "removed-before") removed += a.removedCount ?? 1;
+  }
+  return { added, removed };
+}
+
+/** Merge touching/overlapping wash hunks of the same kind (keeps the DOM quiet). */
+function mergeAdjacent(annotations: MarkdownAnnotation[]): MarkdownAnnotation[] {
+  const out: MarkdownAnnotation[] = [];
+  for (const ann of annotations) {
+    const last = out[out.length - 1];
+    if (
+      last &&
+      last.kind !== "removed-before" &&
+      last.kind === ann.kind &&
+      ann.startLine <= last.endLine + 1
+    ) {
+      last.endLine = Math.max(last.endLine, ann.endLine);
+    } else {
+      out.push({ ...ann });
+    }
+  }
+  return out;
+}
+
+/**
+ * Shift annotation lines by `-offset` (used when frontmatter is stripped before
+ * rendering). Annotations that fall entirely inside the stripped region drop out.
+ */
+export function shiftAnnotations(
+  annotations: MarkdownAnnotation[],
+  offset: number,
+): MarkdownAnnotation[] {
+  if (offset === 0) return annotations;
+  const out: MarkdownAnnotation[] = [];
+  for (const ann of annotations) {
+    const startLine = ann.startLine - offset;
+    const endLine = ann.endLine - offset;
+    if (endLine < 1) continue;
+    out.push({ ...ann, startLine: Math.max(1, startLine), endLine });
+  }
+  return out;
+}
+
+/** Does the annotation set wash the given block line range? Most specific wins. */
+export function annotationForRange(
+  annotations: MarkdownAnnotation[],
+  startLine: number,
+  endLine: number,
+): MarkdownAnnotation | undefined {
+  let hit: MarkdownAnnotation | undefined;
+  for (const ann of annotations) {
+    if (ann.kind === "removed-before") continue;
+    if (ann.startLine <= endLine && ann.endLine >= startLine) {
+      if (!hit || ann.endLine - ann.startLine < hit.endLine - hit.startLine) hit = ann;
+    }
+  }
+  return hit;
+}
+
+/** The removed-marker (if any) anchored exactly at this block's first line. */
+export function removedMarkerAt(
+  annotations: MarkdownAnnotation[],
+  startLine: number,
+): MarkdownAnnotation | undefined {
+  return annotations.find((a) => a.kind === "removed-before" && a.startLine === startLine);
+}