@elabs-ai/components-editor 4.0.0 → 4.2.0

package/src/code-editor/code-editor.test.tsx

@@ -1,13 +1,23 @@
 import { act, cleanup, render } from "@testing-library/react";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from "vitest";
 
 // Monaco needs real layout/canvas, so it cannot mount in jsdom — mock the engine
 // and assert the wrapper's lifecycle contract. Real rendering + a11y are covered
 // by the Storybook interaction tests.
 const h = vi.hoisted(() => {
   const state = { changeHandler: undefined as undefined | (() => void), value: "" };
-  const model = { dispose: vi.fn() };
+  const models: {
+    dispose: Mock;
+    uri: { toString(): string } | undefined;
+    getValue: () => string;
+    getPositionAt: (offset: number) => { lineNumber: number; column: number };
+    _value: string;
+  }[] = [];
   const actionDisposable = { dispose: vi.fn() };
+  // The most recently created/set model — a simple single-document stand-in
+  // (columns are 1-based character OFFSETS, not real Monaco line/column) good
+  // enough to exercise `executeEdits`'s edit shape without a real Monaco model.
+  let currentModel: (typeof models)[number] | undefined;
   const editor = {
     onDidChangeModelContent: vi.fn((cb: () => void) => {
       state.changeHandler = cb;
@@ -17,7 +27,19 @@ const h = vi.hoisted(() => {
     setValue: vi.fn((v: string) => {
       state.value = v;
     }),
-    getModel: vi.fn(() => model),
+    getModel: vi.fn(() => currentModel),
+    setModel: vi.fn((m: (typeof models)[number]) => {
+      currentModel = m;
+    }),
+    executeEdits: vi.fn(
+      (_source: string, edits: { range: { start: number; end: number }; text: string }[]) => {
+        const edit = edits[0]!;
+        const next =
+          state.value.slice(0, edit.range.start) + edit.text + state.value.slice(edit.range.end);
+        state.value = next;
+        if (currentModel) currentModel._value = next;
+      },
+    ),
     updateOptions: vi.fn(),
     addAction: vi.fn(() => actionDisposable),
     // Minimal DOM node so the aria-forwarding effect can find (or not) a textarea.
@@ -26,13 +48,29 @@ const h = vi.hoisted(() => {
   };
   return {
     state,
-    model,
+    models,
+    get model() {
+      return models[0];
+    },
     actionDisposable,
     editor,
     create: vi.fn(() => editor),
-    createModel: vi.fn((value: string) => {
+    createModel: vi.fn((value: string, _language: string, uri?: { toString(): string }) => {
       state.value = value;
-      return model;
+      const m = {
+        dispose: vi.fn(),
+        uri,
+        _value: value,
+        getValue(this: { _value: string }) {
+          return this._value;
+        },
+        getPositionAt(offset: number) {
+          return { lineNumber: 1, column: offset };
+        },
+      };
+      models.push(m);
+      currentModel = m;
+      return m;
     }),
   };
 });
@@ -46,38 +84,56 @@ vi.mock("monaco-editor", () => ({
     setTheme: vi.fn(),
   },
   Uri: { parse: (s: string) => ({ toString: () => s }) },
+  Range: {
+    fromPositions: (start: { column: number }, end: { column: number }) => ({
+      start: start.column,
+      end: end.column,
+    }),
+  },
 }));
 
 import { CodeEditor } from "./code-editor";
 
+// The engine now loads via a dynamic `import("monaco-editor")` inside the
+// mount effect (kept lazy so the barrel never evaluates Monaco just for
+// `CopyButton`/`EDITOR_LANGUAGES` — see barrel-monaco-lazy.test.ts). The mock
+// module still resolves through that dynamic import, but only after a
+// microtask: flush it with `await act(async () => {})` after every
+// render/rerender that expects the editor to already exist.
+const flush = () => act(async () => {});
+
 beforeEach(() => {
   h.state.changeHandler = undefined;
   h.state.value = "";
+  h.models.length = 0;
   vi.clearAllMocks();
 });
 afterEach(cleanup);
 
 describe("CodeEditor", () => {
-  it("creates a Monaco editor with the initial value + language", () => {
+  it("creates a Monaco editor with the initial value + language", async () => {
     const { getByTestId } = render(
       <CodeEditor defaultValue="const a = 1;" language="typescript" />,
     );
     expect(getByTestId("code-editor")).toBeInTheDocument();
+    await flush();
     expect(h.create).toHaveBeenCalledTimes(1);
     // No `path` → no model URI.
     expect(h.createModel).toHaveBeenCalledWith("const a = 1;", "typescript", undefined);
   });
 
-  it("creates the model with a URI derived from `path`", () => {
+  it("creates the model with a URI derived from `path`", async () => {
     render(<CodeEditor defaultValue="x" language="json" path="config/app.json" />);
+    await flush();
     expect(h.createModel).toHaveBeenCalledWith("x", "json", {
       toString: expect.any(Function),
     });
   });
 
-  it("forwards content edits to onChange", () => {
+  it("forwards content edits to onChange", async () => {
     const onChange = vi.fn();
     render(<CodeEditor defaultValue="" onChange={onChange} />);
+    await flush();
     expect(h.state.changeHandler).toBeTypeOf("function");
     act(() => {
       h.state.value = "typed";
@@ -86,32 +142,35 @@ describe("CodeEditor", () => {
     expect(onChange).toHaveBeenCalledWith("typed");
   });
 
-  it("disposes the editor + model on unmount", () => {
+  it("disposes the editor + model on unmount", async () => {
     const { unmount } = render(<CodeEditor defaultValue="x" />);
+    await flush();
     unmount();
     expect(h.editor.dispose).toHaveBeenCalledTimes(1);
-    expect(h.model.dispose).toHaveBeenCalledTimes(1);
+    expect(h.model!.dispose).toHaveBeenCalledTimes(1);
   });
 
   describe("actions prop", () => {
-    it("calls addAction once per descriptor on mount", () => {
+    it("calls addAction once per descriptor on mount", async () => {
       const actions = [
         { id: "test.one", label: "One", run: vi.fn() },
         { id: "test.two", label: "Two", run: vi.fn() },
       ];
       render(<CodeEditor defaultValue="" actions={actions} />);
+      await flush();
       expect(h.editor.addAction).toHaveBeenCalledTimes(2);
       expect(h.editor.addAction).toHaveBeenCalledWith(actions[0]);
       expect(h.editor.addAction).toHaveBeenCalledWith(actions[1]);
     });
 
-    it("disposes old disposables and re-adds when the actions array identity changes", () => {
+    it("disposes old disposables and re-adds when the actions array identity changes", async () => {
       const actionsV1 = [{ id: "test.a", label: "A", run: vi.fn() }];
       const actionsV2 = [
         { id: "test.a", label: "A", run: vi.fn() },
         { id: "test.b", label: "B", run: vi.fn() },
       ];
       const { rerender } = render(<CodeEditor defaultValue="" actions={actionsV1} />);
+      await flush();
       expect(h.editor.addAction).toHaveBeenCalledTimes(1);
 
       rerender(<CodeEditor defaultValue="" actions={actionsV2} />);
@@ -120,15 +179,83 @@ describe("CodeEditor", () => {
       expect(h.editor.addAction).toHaveBeenCalledTimes(3); // 1 + 2
     });
 
-    it("disposes all action disposables on unmount", () => {
+    it("disposes all action disposables on unmount", async () => {
       const actions = [
         { id: "test.x", label: "X", run: vi.fn() },
         { id: "test.y", label: "Y", run: vi.fn() },
       ];
       const { unmount } = render(<CodeEditor defaultValue="" actions={actions} />);
+      await flush();
       expect(h.editor.addAction).toHaveBeenCalledTimes(2);
       unmount();
       expect(h.actionDisposable.dispose).toHaveBeenCalledTimes(2);
     });
   });
+
+  describe("path changes after mount", () => {
+    it("swaps the model instead of ignoring the new path (Monaco has no URI setter)", async () => {
+      const { rerender } = render(
+        <CodeEditor defaultValue="x" path="a.ts" language="typescript" />,
+      );
+      await flush();
+      expect(h.createModel).toHaveBeenCalledTimes(1);
+      const firstModel = h.models[0]!;
+
+      rerender(<CodeEditor defaultValue="x" path="b.ts" language="typescript" />);
+
+      expect(h.createModel).toHaveBeenCalledTimes(2);
+      expect(h.editor.setModel).toHaveBeenCalledWith(h.models[1]);
+      expect(firstModel.dispose).toHaveBeenCalledTimes(1);
+    });
+
+    it("does not rebuild the model when path is unchanged across a re-render", async () => {
+      const { rerender } = render(<CodeEditor defaultValue="x" path="a.ts" />);
+      await flush();
+      expect(h.createModel).toHaveBeenCalledTimes(1);
+
+      rerender(<CodeEditor defaultValue="x" path="a.ts" ariaLabel="renamed" />);
+
+      expect(h.createModel).toHaveBeenCalledTimes(1);
+      expect(h.editor.setModel).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("controlled value sync", () => {
+    it("applies a single-character change via executeEdits, never setValue", async () => {
+      const { rerender } = render(<CodeEditor value="abc" onChange={vi.fn()} />);
+      await flush();
+      expect(h.state.value).toBe("abc");
+
+      rerender(<CodeEditor value="abd" onChange={vi.fn()} />);
+
+      expect(h.editor.executeEdits).toHaveBeenCalledTimes(1);
+      expect(h.editor.setValue).not.toHaveBeenCalled();
+      expect(h.state.value).toBe("abd");
+    });
+
+    it("does nothing when the controlled value already matches the model", async () => {
+      render(<CodeEditor value="same" onChange={vi.fn()} />);
+      await flush();
+      h.editor.executeEdits.mockClear();
+
+      render(<CodeEditor value="same" onChange={vi.fn()} />);
+      await flush();
+
+      expect(h.editor.executeEdits).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("options changes after mount", () => {
+    it("re-applies a changed `options` prop via updateOptions", async () => {
+      const { rerender } = render(
+        <CodeEditor defaultValue="" options={{ minimap: { enabled: false } }} />,
+      );
+      await flush();
+      h.editor.updateOptions.mockClear();
+
+      rerender(<CodeEditor defaultValue="" options={{ minimap: { enabled: true } }} />);
+
+      expect(h.editor.updateOptions).toHaveBeenCalledWith({ minimap: { enabled: true } });
+    });
+  });
 });

package/src/code-editor/code-editor.tsx

@@ -1,6 +1,13 @@
 "use client";
 
-import * as monaco from "monaco-editor";
+// Type-only: the barrel (`.`) exports this component alongside lightweight
+// chrome (`CopyButton`, `EDITOR_LANGUAGES`) that must stay import-safe without
+// Monaco. A `monaco-editor` VALUE import here would be evaluated the moment
+// anything imports the barrel, pulling megabytes of Monaco + touching browser
+// globals even for a consumer that only wants `CopyButton`. The engine is
+// loaded at RUNTIME via `import("monaco-editor")` inside the mount effect
+// below — see `monacoRef`.
+import type * as monaco from "monaco-editor";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 import {
   forwardRef,
@@ -20,6 +27,14 @@ export type MonacoCodeEditor = monaco.editor.IStandaloneCodeEditor;
 /** A Monaco editor action (system command + optional hotkey + palette/menu entry). */
 export type EditorAction = monaco.editor.IActionDescriptor;
 
+/**
+ * The runtime value type handed back by `import("monaco-editor")` — same
+ * namespace as the type-only `monaco` import above (`typeof` a type-only
+ * namespace import resolves to the module's own type), used for `monacoRef`
+ * and `onMount`'s second argument.
+ */
+type MonacoNamespace = typeof monaco;
+
 export interface CodeEditorProps extends Omit<
   HTMLAttributes<HTMLDivElement>,
   "onChange" | "defaultValue"
@@ -58,7 +73,7 @@ export interface CodeEditorProps extends Omit<
    */
   contextMenu?: "brand" | "monaco" | "none";
   /** Called once the editor instance + monaco namespace are ready. */
-  onMount?: (editor: MonacoCodeEditor, monacoApi: typeof monaco) => void;
+  onMount?: (editor: MonacoCodeEditor, monacoApi: MonacoNamespace) => void;
   /**
    * Declarative Monaco editor actions — each registers a command (run on its
    * `keybindings`, in the command palette, and optionally the context menu via
@@ -73,6 +88,38 @@ export interface CodeEditorProps extends Omit<
   actions?: EditorAction[];
 }
 
+/**
+ * The smallest single edit that turns `oldValue` into `newValue`, found by
+ * trimming the common prefix and suffix. Used instead of a wholesale
+ * `editor.setValue()` when syncing a controlled `value`: `setValue` replaces
+ * the entire model in one shot, which wipes the undo stack and always resets
+ * the cursor to the start of the document. Routing the same change through
+ * `editor.executeEdits` with just the differing middle span keeps it a single
+ * coalescable undo entry and leaves the cursor/selection outside the edited
+ * span untouched by Monaco's own position mapping.
+ */
+function computeMinimalEdit(
+  oldValue: string,
+  newValue: string,
+): { start: number; endOld: number; text: string } {
+  const maxCommon = Math.min(oldValue.length, newValue.length);
+  let start = 0;
+  while (start < maxCommon && oldValue.charCodeAt(start) === newValue.charCodeAt(start)) {
+    start++;
+  }
+  let endOld = oldValue.length;
+  let endNew = newValue.length;
+  while (
+    endOld > start &&
+    endNew > start &&
+    oldValue.charCodeAt(endOld - 1) === newValue.charCodeAt(endNew - 1)
+  ) {
+    endOld--;
+    endNew--;
+  }
+  return { start, endOld, text: newValue.slice(start, endNew) };
+}
+
 const BASE_OPTIONS: monaco.editor.IStandaloneEditorConstructionOptions = {
   automaticLayout: true,
   minimap: { enabled: false },
@@ -89,7 +136,7 @@ const BASE_OPTIONS: monaco.editor.IStandaloneEditorConstructionOptions = {
  * A token-themed Monaco editor wrapped as a brand-ui React component. Monaco
  * renders its own editing surface + widgets; this wrapper owns lifecycle,
  * controlled/uncontrolled value, and applies the brand theme bridge so the
- * editor matches the active `data-theme` (all three themes).
+ * editor matches the active `data-theme` (every theme).
  *
  * Workers (for completions/diagnostics) are wired by importing
  * `@elabs-ai/components-editor/monaco-environment` once at the app entry.
@@ -119,6 +166,15 @@ export const CodeEditor = forwardRef<MonacoCodeEditor | null, CodeEditorProps>(f
   const containerRef = useRef<HTMLDivElement>(null);
   const [editor, setEditor] = useState<MonacoCodeEditor | null>(null);
   const { theme, revision } = useDataTheme();
+  // The CURRENT model, tracked outside React state: a `path` change swaps it
+  // (see the effect below) without waiting on a re-render, and unmount must
+  // dispose whichever model is live at that point, not the one from mount.
+  const modelRef = useRef<monaco.editor.ITextModel | null>(null);
+  // The dynamically-imported `monaco-editor` module, once loaded. `editor`
+  // (React state) is only ever set AFTER this ref is populated (see the mount
+  // effect), so every other effect below that reads both may assume: `editor`
+  // truthy implies `monacoRef.current` truthy.
+  const monacoRef = useRef<MonacoNamespace | null>(null);
 
   // Latest callbacks via refs so the mount effect can run exactly once.
   const onChangeRef = useRef(onChange);
@@ -130,64 +186,139 @@ export const CodeEditor = forwardRef<MonacoCodeEditor | null, CodeEditorProps>(f
     editor,
   ]);
 
-  // Mount once.
+  // Mount once. Monaco itself loads lazily (`import("monaco-editor")`) so the
+  // engine is only fetched/evaluated once a `CodeEditor` actually mounts, never
+  // merely by importing this module (see the top-of-file note). `cancelled`
+  // guards against the component unmounting (or `container` going away) before
+  // the dynamic import resolves.
   useEffect(() => {
     const container = containerRef.current;
     if (!container) return;
+    let cancelled = false;
+    let instance: MonacoCodeEditor | null = null;
+    let model: monaco.editor.ITextModel | null = null;
+    let sub: { dispose(): void } | null = null;
 
-    const model = monaco.editor.createModel(
-      value ?? defaultValue ?? "",
-      language,
-      path ? monaco.Uri.parse(`inmemory://brand/${path}`) : undefined,
-    );
-    const instance = monaco.editor.create(container, {
-      ...BASE_OPTIONS,
-      readOnly,
-      // Disable Monaco's own menu unless explicitly opted into; "brand" renders
-      // brand-ui's ContextMenu around the editor instead.
-      contextmenu: contextMenu === "monaco",
-      // Monaco's accessible name comes from this construction option (it writes it
-      // onto its inner screen-reader <textarea>), not from a wrapper-div attribute.
-      ...(ariaLabel !== undefined ? { ariaLabel } : null),
-      model,
-      ...options,
+    import("monaco-editor").then((monacoApi) => {
+      if (cancelled) return;
+      monacoRef.current = monacoApi;
+      model = monacoApi.editor.createModel(
+        value ?? defaultValue ?? "",
+        language,
+        path ? monacoApi.Uri.parse(`inmemory://brand/${path}`) : undefined,
+      );
+      modelRef.current = model;
+      instance = monacoApi.editor.create(container, {
+        ...BASE_OPTIONS,
+        readOnly,
+        // Disable Monaco's own menu unless explicitly opted into; "brand" renders
+        // brand-ui's ContextMenu around the editor instead.
+        contextmenu: contextMenu === "monaco",
+        // Monaco's accessible name comes from this construction option (it writes it
+        // onto its inner screen-reader <textarea>), not from a wrapper-div attribute.
+        ...(ariaLabel !== undefined ? { ariaLabel } : null),
+        model,
+        ...options,
+      });
+      sub = instance.onDidChangeModelContent(() => {
+        onChangeRef.current?.(instance!.getValue());
+      });
+      // Monaco now mounts asynchronously, so stamp the initial aria-* onto its
+      // textarea right away — otherwise it is briefly exposed without a name
+      // until the aria sync effect below runs on the next commit.
+      const textarea = instance.getDomNode()?.querySelector("textarea");
+      if (textarea) {
+        if (ariaLabel !== undefined) textarea.setAttribute("aria-label", ariaLabel);
+        if (ariaInvalid !== undefined) textarea.setAttribute("aria-invalid", String(ariaInvalid));
+        if (ariaDescribedBy !== undefined)
+          textarea.setAttribute("aria-describedby", ariaDescribedBy);
+      }
+      // `setEditor` triggers the theming effect below; keeping theme application
+      // there (not here) guarantees it never blocks editor setup.
+      setEditor(instance);
+      onMountRef.current?.(instance, monacoApi);
     });
-    const sub = instance.onDidChangeModelContent(() => {
-      onChangeRef.current?.(instance.getValue());
-    });
-    // `setEditor` triggers the theming effect below; keeping theme application
-    // there (not here) guarantees it never blocks editor setup.
-    setEditor(instance);
-    onMountRef.current?.(instance, monaco);
 
     return () => {
-      sub.dispose();
-      instance.dispose();
-      model.dispose();
+      cancelled = true;
+      sub?.dispose();
+      instance?.dispose();
+      model?.dispose();
+      modelRef.current = null;
+      monacoRef.current = null;
       setEditor(null);
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
-  // Controlled value sync (only when it diverges, to preserve cursor/undo).
+  // `path` drives the model's URI, which Monaco never lets you change on an
+  // existing model — a later `path` change (e.g. `CodeWorkspace` switching
+  // files) was previously just ignored. Swap in a fresh model carrying the
+  // CURRENT value/language under the new URI, and dispose the old one; a
+  // per-file undo stack is Monaco's normal behavior for a model swap.
   useEffect(() => {
-    if (!editor || value === undefined) return;
-    if (value !== editor.getValue()) editor.setValue(value);
+    const monacoApi = monacoRef.current;
+    if (!editor || !monacoApi) return;
+    const current = modelRef.current;
+    const currentUri = current?.uri?.toString();
+    const nextUri = path ? monacoApi.Uri.parse(`inmemory://brand/${path}`).toString() : undefined;
+    if (currentUri === nextUri) return;
+
+    const nextModel = monacoApi.editor.createModel(
+      current?.getValue() ?? value ?? defaultValue ?? "",
+      language,
+      path ? monacoApi.Uri.parse(`inmemory://brand/${path}`) : undefined,
+    );
+    editor.setModel(nextModel);
+    modelRef.current = nextModel;
+    current?.dispose();
+    // `value`/`defaultValue`/`language` are read once, at the moment of the
+    // swap, to seed the new model — not tracked as reactive deps here; the
+    // controlled-value and language effects below correct them independently.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [editor, path]);
+
+  // Controlled value sync — only when it diverges, and via the smallest
+  // `executeEdits` span rather than `setValue()`: a full-document `setValue`
+  // wipes the undo stack and always resets the cursor to the start.
+  useEffect(() => {
+    const monacoApi = monacoRef.current;
+    if (!editor || !monacoApi || value === undefined) return;
+    const model = editor.getModel();
+    if (!model) return;
+    const current = model.getValue();
+    if (value === current) return;
+    const { start, endOld, text } = computeMinimalEdit(current, value);
+    const range = monacoApi.Range.fromPositions(
+      model.getPositionAt(start),
+      model.getPositionAt(endOld),
+    );
+    editor.executeEdits("controlled-value-sync", [{ range, text }]);
   }, [editor, value]);
 
   useEffect(() => {
+    const monacoApi = monacoRef.current;
     const model = editor?.getModel();
-    if (model) monaco.editor.setModelLanguage(model, language);
+    if (model && monacoApi) monacoApi.editor.setModelLanguage(model, language);
   }, [editor, language]);
 
   useEffect(() => {
     editor?.updateOptions({ readOnly, contextmenu: contextMenu === "monaco" });
   }, [editor, readOnly, contextMenu]);
 
+  // `options` after mount: the construction-time spread only ever applied it
+  // once. A caller changing `options` (e.g. toggling `minimap`) now reaches
+  // the live editor via `updateOptions`, same as `readOnly`/`contextMenu` above.
   useEffect(() => {
-    if (!editor) return;
+    if (!editor || !options) return;
+    editor.updateOptions(options);
+  }, [editor, options]);
+
+  useEffect(() => {
+    const monacoApi = monacoRef.current;
+    if (!editor || !monacoApi) return;
     try {
-      applyBrandTheme(monaco, theme);
+      applyBrandTheme(monacoApi, theme);
     } catch (err) {
       console.error("[@elabs-ai/components-editor] failed to apply brand theme", err);
     }