@elabs-ai/components-editor 4.0.0

package/src/code-workspace/code-workspace.tsx

@@ -0,0 +1,253 @@
+"use client";
+
+import { Tabs, TabsList, TabsTrigger } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState,
+  type CSSProperties,
+  type HTMLAttributes,
+} from "react";
+import { CodeEditor, type MonacoCodeEditor } from "../code-editor";
+import { CopyButton } from "../copy-button";
+import {
+  monacoContentAccess,
+  type EditorContentAccess,
+  type EditorSelection,
+} from "../lib/editor-content-access";
+
+export interface EditorFile {
+  /** Unique path/name; shown (basename) on the tab and used as the model path. */
+  path: string;
+  /** Monaco language id. Inferred from the extension when omitted. */
+  language?: string;
+  /** File content. */
+  value: string;
+}
+
+export interface CodeWorkspaceProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  "onChange" | "defaultValue"
+> {
+  /** Open files, one tab each. */
+  files: EditorFile[];
+  /** Controlled active file path. */
+  activePath?: string;
+  /** Initial active path for uncontrolled use. Defaults to the first file. */
+  defaultActivePath?: string;
+  /** Called when the active tab changes. */
+  onActivePathChange?: (path: string) => void;
+  /** Called on every edit with the file path + new content. */
+  onFileChange?: (path: string, value: string) => void;
+  /** Render all files read-only. */
+  readOnly?: boolean;
+  /** Workspace height. Number → px. Defaults to "100%". */
+  height?: number | string;
+}
+
+const EXT_LANGUAGE: Record<string, string> = {
+  ts: "typescript",
+  tsx: "typescript",
+  mts: "typescript",
+  cts: "typescript",
+  js: "javascript",
+  jsx: "javascript",
+  mjs: "javascript",
+  cjs: "javascript",
+  json: "json",
+  css: "css",
+  scss: "scss",
+  less: "less",
+  html: "html",
+  md: "markdown",
+  py: "python",
+  sql: "sql",
+  yml: "yaml",
+  yaml: "yaml",
+  xml: "xml",
+  sh: "shell",
+};
+
+const basename = (path: string) => path.split("/").pop() || path;
+
+function inferLanguage(file: EditorFile): string {
+  if (file.language) return file.language;
+  const ext = file.path.split(".").pop()?.toLowerCase() ?? "";
+  return EXT_LANGUAGE[ext] ?? "plaintext";
+}
+
+/**
+ * Imperative handle exposed via `CodeWorkspace`'s `ref`.
+ *
+ * **Migration note:** the forwarded `ref` type changed from `HTMLDivElement` to
+ * `CodeWorkspaceHandle` (mirrors the #273 `MarkdownWorkspaceHandle` precedent).
+ * Replace any `ref.current` / `ref.current.scrollIntoView()` DOM access with
+ * `ref.current?.getElement()`. This is the only breaking change in this work.
+ */
+export interface CodeWorkspaceHandle extends EditorContentAccess {
+  /**
+   * The live Monaco editor for the currently active tab, or `null` while booting
+   * or when no files are open. Consumers needing the full Monaco API can use this
+   * and pass it to `monacoContentAccess(handle.getActiveEditor()!)`.
+   */
+  getActiveEditor(): MonacoCodeEditor | null;
+  /**
+   * The workspace root DOM element. Preserves the old `HTMLDivElement` ref access
+   * that existed before the ref-type change (#273 `MarkdownWorkspace` playbook).
+   */
+  getElement(): HTMLDivElement | null;
+}
+
+/** No-op EditorContentAccess returned when no Monaco editor is mounted. */
+const NULL_ACCESS: EditorContentAccess = {
+  getText: () => "",
+  getSelection: () => ({ text: "", empty: true }),
+  replaceSelection: () => undefined,
+  insertAtCursor: () => undefined,
+  focus: () => undefined,
+  onSelectionChange: () => () => undefined,
+};
+
+/**
+ * Multi-file editor shell: brand-ui `Tabs` for the file bar above a single
+ * {@link CodeEditor} that swaps to the active file. This is the "reuse our
+ * components for the chrome" surface — Tabs/Button are ours; the editing surface
+ * is Monaco. Edits bubble through `onFileChange`.
+ *
+ * The forwarded `ref` exposes a {@link CodeWorkspaceHandle} (not `HTMLDivElement`).
+ * Use `ref.current?.getElement()` to access the root DOM node.
+ */
+export const CodeWorkspace = forwardRef<CodeWorkspaceHandle, CodeWorkspaceProps>(
+  function CodeWorkspace(
+    {
+      files,
+      activePath,
+      defaultActivePath,
+      onActivePathChange,
+      onFileChange,
+      readOnly = false,
+      height = "100%",
+      className,
+      style,
+      ...props
+    },
+    ref,
+  ) {
+    const [internalActive, setInternalActive] = useState(defaultActivePath ?? files[0]?.path ?? "");
+    const isControlled = activePath !== undefined;
+    const requested = isControlled ? activePath : internalActive;
+    const activeFile = files.find((f) => f.path === requested) ?? files[0];
+    const active = activeFile?.path ?? "";
+
+    // The root div ref (getElement() preserves old HTMLDivElement access).
+    const rootRef = useRef<HTMLDivElement | null>(null);
+
+    // The live Monaco editor for the active tab. Nulled when there is no active file.
+    const [activeEditor, setActiveEditor] = useState<MonacoCodeEditor | null>(null);
+
+    // Defensive: if the active file is removed (no `activeFile`), null the held instance
+    // so getActiveEditor() and content-access methods don't act on a disposed editor.
+    useEffect(() => {
+      if (!activeFile) setActiveEditor(null);
+    }, [activeFile]);
+
+    // A STABLE listener set for onSelectionChange. The handle adds/removes here;
+    // the binding effect below forwards the ACTIVE editor's selection changes into
+    // it. This is what makes a subscribe-in-mount-effect survive the editor's async
+    // mount (and tab swaps): the consumer subscribes once; binding re-attaches as
+    // `activeEditor` changes. (Delegating onSelectionChange to a call-time snapshot
+    // would bind to the not-yet-mounted editor and silently never fire.)
+    const [selectionListeners] = useState(() => new Set<(sel: EditorSelection) => void>());
+    useEffect(() => {
+      if (!activeEditor) return;
+      const unsub = monacoContentAccess(activeEditor).onSelectionChange((sel) =>
+        selectionListeners.forEach((l) => l(sel)),
+      );
+      return unsub;
+    }, [activeEditor, selectionListeners]);
+
+    const selectTab = useCallback(
+      (path: string) => {
+        if (!isControlled) setInternalActive(path);
+        onActivePathChange?.(path);
+      },
+      [isControlled, onActivePathChange],
+    );
+
+    useImperativeHandle(ref, () => {
+      const access = activeEditor ? monacoContentAccess(activeEditor) : NULL_ACCESS;
+      return {
+        getActiveEditor: () => activeEditor,
+        getElement: () => rootRef.current,
+        getText: () => access.getText(),
+        getSelection: () => access.getSelection(),
+        replaceSelection: (text: string) => access.replaceSelection(text),
+        insertAtCursor: (text: string) => access.insertAtCursor(text),
+        focus: () => access.focus(),
+        // Stable set (not the call-time `access`) so a subscription survives the
+        // editor's async mount + tab swaps; the binding effect forwards events.
+        onSelectionChange: (listener) => {
+          selectionListeners.add(listener);
+          return () => selectionListeners.delete(listener);
+        },
+      };
+    }, [activeEditor, selectionListeners]);
+
+    const resolvedStyle: CSSProperties = {
+      height: typeof height === "number" ? `${height}px` : height,
+      ...style,
+    };
+
+    return (
+      <div
+        ref={rootRef}
+        className={cn(
+          "flex flex-col overflow-hidden rounded-lg border border-border bg-surface",
+          className,
+        )}
+        style={resolvedStyle}
+        {...props}
+      >
+        <Tabs
+          value={active}
+          onValueChange={selectTab}
+          className="flex min-h-0 flex-1 flex-col gap-0"
+        >
+          <div className="flex items-center border-b border-border bg-surface">
+            <TabsList className="h-9 flex-1 justify-start gap-0 rounded-none bg-transparent p-0">
+              {files.map((file) => (
+                <TabsTrigger
+                  key={file.path}
+                  value={file.path}
+                  className="h-9 rounded-none border-e border-border px-3 text-xs data-[state=active]:bg-background data-[state=active]:shadow-none"
+                >
+                  {basename(file.path)}
+                </TabsTrigger>
+              ))}
+            </TabsList>
+            {activeFile ? <CopyButton value={activeFile.value} className="me-1.5" /> : null}
+          </div>
+
+          <div className="min-h-0 flex-1">
+            {activeFile ? (
+              <CodeEditor
+                key={activeFile.path}
+                path={activeFile.path}
+                language={inferLanguage(activeFile)}
+                value={activeFile.value}
+                readOnly={readOnly}
+                onChange={(next) => onFileChange?.(activeFile.path, next)}
+                onMount={(editor) => setActiveEditor(editor)}
+                height="100%"
+              />
+            ) : null}
+          </div>
+        </Tabs>
+      </div>
+    );
+  },
+);

package/src/code-workspace/index.ts

@@ -0,0 +1,6 @@
+export {
+  CodeWorkspace,
+  type CodeWorkspaceHandle,
+  type CodeWorkspaceProps,
+  type EditorFile,
+} from "./code-workspace";

package/src/copy-button/copy-button.tsx

@@ -0,0 +1,51 @@
+"use client";
+
+import { Button, useCopyToClipboard } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { CheckIcon, CopyIcon } from "lucide-react";
+import { useCallback, type ComponentProps } from "react";
+
+export interface CopyButtonProps extends Omit<ComponentProps<typeof Button>, "value"> {
+  /** Text written to the clipboard on click. */
+  value: string;
+  /** Show the "Copy" / "Copied" label next to the icon. Defaults to true. */
+  label?: boolean;
+}
+
+/**
+ * Brand-ui copy-to-clipboard button with a transient "Copied" state. Shared by
+ * the editor toolbar and workspace so the copy affordance is defined once.
+ */
+export function CopyButton({ value, label = true, className, ...props }: CopyButtonProps) {
+  // Clipboard write + transient flag come from the shared `@elabs-ai/components-ui`
+  // hook, so this button and `CopyableValue` cannot drift on timing or on what
+  // happens where there is no clipboard.
+  const { copied, copy } = useCopyToClipboard();
+
+  const onClick = useCallback(() => {
+    void copy(value);
+  }, [copy, value]);
+
+  return (
+    <Button
+      variant="ghost"
+      size="sm"
+      {...props}
+      type="button"
+      className={cn("h-7 gap-1.5", className)}
+      onClick={onClick}
+      aria-label={copied ? "Copied" : "Copy"}
+    >
+      {copied ? (
+        <CheckIcon
+          key={String(copied)}
+          className="size-4 text-success animate-in fade-in zoom-in-95 duration-fast ease-entrance"
+          aria-hidden="true"
+        />
+      ) : (
+        <CopyIcon className="size-4" aria-hidden="true" />
+      )}
+      {label ? <span className="text-xs">{copied ? "Copied" : "Copy"}</span> : null}
+    </Button>
+  );
+}

package/src/copy-button/index.ts

@@ -0,0 +1 @@
+export { CopyButton, type CopyButtonProps } from "./copy-button";

package/src/css.d.ts

@@ -0,0 +1,3 @@
+/** Ambient declaration so `tsc` accepts CSS side-effect imports (resolved by the
+ * consuming bundler — Vite for apps/Storybook). */
+declare module "*.css";

package/src/diff-editor/diff-editor.stories.tsx

@@ -0,0 +1,44 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { DiffEditor } from "./diff-editor";
+
+const meta = {
+  title: "Editor/DiffEditor",
+  component: DiffEditor,
+  tags: ["autodocs"],
+  parameters: { layout: "fullscreen" },
+} satisfies Meta<typeof DiffEditor>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const ORIGINAL = `export function greet(name) {
+  return "Hello " + name;
+}
+`;
+
+const MODIFIED = `export function greet(name: string): string {
+  // Use a template literal.
+  return \`Hello \${name}!\`;
+}
+`;
+
+export const SideBySide: Story = {
+  render: () => (
+    <div className="h-[360px] w-full border border-border">
+      <DiffEditor language="typescript" original={ORIGINAL} modified={MODIFIED} />
+    </div>
+  ),
+};
+
+export const Inline: Story = {
+  render: () => (
+    <div className="h-[360px] w-full border border-border">
+      <DiffEditor
+        language="typescript"
+        original={ORIGINAL}
+        modified={MODIFIED}
+        renderSideBySide={false}
+      />
+    </div>
+  ),
+};

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

@@ -0,0 +1,68 @@
+import { cleanup, render } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// Monaco can't mount in jsdom — mock it and assert the wrapper's lifecycle.
+const h = vi.hoisted(() => {
+  interface MockModel {
+    value: string;
+    language: string;
+    getValue: () => string;
+    setValue: ReturnType<typeof vi.fn>;
+    dispose: ReturnType<typeof vi.fn>;
+  }
+  const models: MockModel[] = [];
+  const createModel = vi.fn((value: string, language: string) => {
+    const m = { value, language, getValue: () => value, setValue: vi.fn(), dispose: vi.fn() };
+    models.push(m);
+    return m;
+  });
+  const diff = {
+    setModel: vi.fn(),
+    getModel: vi.fn(() => ({ original: models[0], modified: models[1] })),
+    updateOptions: vi.fn(),
+    dispose: vi.fn(),
+  };
+  return { models, createModel, diff, createDiffEditor: vi.fn(() => diff) };
+});
+
+vi.mock("monaco-editor", () => ({
+  editor: {
+    createDiffEditor: h.createDiffEditor,
+    createModel: h.createModel,
+    setModelLanguage: vi.fn(),
+    defineTheme: vi.fn(),
+    setTheme: vi.fn(),
+  },
+  Uri: { parse: (s: string) => ({ toString: () => s }) },
+}));
+
+import { DiffEditor } from "./diff-editor";
+
+beforeEach(() => {
+  h.models.length = 0;
+  vi.clearAllMocks();
+});
+afterEach(cleanup);
+
+describe("DiffEditor", () => {
+  it("creates a diff editor with original + modified models", () => {
+    const { getByTestId } = render(<DiffEditor original="a" modified="b" language="typescript" />);
+    expect(getByTestId("diff-editor")).toBeInTheDocument();
+    expect(h.createDiffEditor).toHaveBeenCalledTimes(1);
+    expect(h.createModel).toHaveBeenNthCalledWith(1, "a", "typescript");
+    expect(h.createModel).toHaveBeenNthCalledWith(2, "b", "typescript");
+    expect(h.diff.setModel).toHaveBeenCalledWith({
+      original: h.models[0],
+      modified: h.models[1],
+    });
+  });
+
+  it("disposes the editor + both models on unmount", () => {
+    const { unmount } = render(<DiffEditor original="a" modified="b" />);
+    const [original, modified] = h.models;
+    unmount();
+    expect(h.diff.dispose).toHaveBeenCalledTimes(1);
+    expect(original!.dispose).toHaveBeenCalledTimes(1);
+    expect(modified!.dispose).toHaveBeenCalledTimes(1);
+  });
+});

package/src/diff-editor/diff-editor.tsx

@@ -0,0 +1,151 @@
+"use client";
+
+import * as monaco from "monaco-editor";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import {
+  forwardRef,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState,
+  type CSSProperties,
+  type HTMLAttributes,
+} from "react";
+import { applyBrandTheme } from "../lib/monaco-theme-bridge";
+import { useDataTheme } from "../lib/use-data-theme";
+
+export type MonacoDiffEditor = monaco.editor.IStandaloneDiffEditor;
+
+export interface DiffEditorProps extends Omit<HTMLAttributes<HTMLDivElement>, "defaultValue"> {
+  /** Left/original document. */
+  original: string;
+  /** Right/modified document. */
+  modified: string;
+  /** Monaco language id applied to both sides. Defaults to "typescript". */
+  language?: string;
+  /** Read-only (diffs are read-only by default). */
+  readOnly?: boolean;
+  /** Side-by-side (true) vs inline (false) diff. Defaults to side-by-side. */
+  renderSideBySide?: boolean;
+  /** Editor height. Number → px. Defaults to "100%". */
+  height?: number | string;
+  /** Passthrough Monaco diff options (merged over the defaults). */
+  options?: monaco.editor.IStandaloneDiffEditorConstructionOptions;
+  /** Called once the diff editor + monaco namespace are ready. */
+  onMount?: (editor: MonacoDiffEditor, monacoApi: typeof monaco) => void;
+}
+
+const BASE_OPTIONS: monaco.editor.IStandaloneDiffEditorConstructionOptions = {
+  automaticLayout: true,
+  minimap: { enabled: false },
+  scrollBeyondLastLine: false,
+  fontSize: 13,
+  ignoreTrimWhitespace: false,
+  padding: { top: 12, bottom: 12 },
+  scrollbar: { verticalScrollbarSize: 10, horizontalScrollbarSize: 10 },
+};
+
+/**
+ * A token-themed Monaco diff editor (original ↔ modified). Same theming bridge
+ * and chrome story as {@link CodeEditor}; reads as a side-by-side or inline diff.
+ */
+export const DiffEditor = forwardRef<MonacoDiffEditor | null, DiffEditorProps>(function DiffEditor(
+  {
+    original,
+    modified,
+    language = "typescript",
+    readOnly = true,
+    renderSideBySide = true,
+    height = "100%",
+    options,
+    onMount,
+    className,
+    style,
+    ...props
+  },
+  ref,
+) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [editor, setEditor] = useState<MonacoDiffEditor | null>(null);
+  const { theme, revision } = useDataTheme();
+
+  const onMountRef = useRef(onMount);
+  onMountRef.current = onMount;
+
+  useImperativeHandle<MonacoDiffEditor | null, MonacoDiffEditor | null>(ref, () => editor, [
+    editor,
+  ]);
+
+  // Mount once.
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    const instance = monaco.editor.createDiffEditor(container, {
+      ...BASE_OPTIONS,
+      readOnly,
+      renderSideBySide,
+      ...options,
+    });
+    const originalModel = monaco.editor.createModel(original, language);
+    const modifiedModel = monaco.editor.createModel(modified, language);
+    instance.setModel({ original: originalModel, modified: modifiedModel });
+    // Theme is applied by the effect below once `setEditor` runs.
+    setEditor(instance);
+    onMountRef.current?.(instance, monaco);
+
+    return () => {
+      instance.dispose();
+      originalModel.dispose();
+      modifiedModel.dispose();
+      setEditor(null);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  useEffect(() => {
+    const original_ = editor?.getModel()?.original;
+    if (original_ && original_.getValue() !== original) original_.setValue(original);
+  }, [editor, original]);
+
+  useEffect(() => {
+    const modified_ = editor?.getModel()?.modified;
+    if (modified_ && modified_.getValue() !== modified) modified_.setValue(modified);
+  }, [editor, modified]);
+
+  useEffect(() => {
+    const models = editor?.getModel();
+    if (!models) return;
+    monaco.editor.setModelLanguage(models.original, language);
+    monaco.editor.setModelLanguage(models.modified, language);
+  }, [editor, language]);
+
+  useEffect(() => {
+    editor?.updateOptions({ readOnly, renderSideBySide });
+  }, [editor, readOnly, renderSideBySide]);
+
+  useEffect(() => {
+    if (!editor) return;
+    try {
+      applyBrandTheme(monaco, theme);
+    } catch (err) {
+      console.error("[@elabs-ai/components-editor] failed to apply brand theme", err);
+    }
+    // `revision` re-applies once the data-theme attribute settles. See CodeEditor.
+  }, [editor, theme, revision]);
+
+  const resolvedStyle: CSSProperties = {
+    height: typeof height === "number" ? `${height}px` : height,
+    ...style,
+  };
+
+  return (
+    <div
+      ref={containerRef}
+      data-testid="diff-editor"
+      className={cn("h-full w-full overflow-hidden bg-background text-foreground", className)}
+      style={resolvedStyle}
+      {...props}
+    />
+  );
+});

package/src/diff-editor/index.ts

@@ -0,0 +1 @@
+export { DiffEditor, type DiffEditorProps, type MonacoDiffEditor } from "./diff-editor";