@elabs-ai/components-editor 4.0.0

package/src/calc-block/types.ts

@@ -0,0 +1,164 @@
+/**
+ * CalcBlock contracts — the shape the consumer's `evaluate` hook returns.
+ *
+ * The library RENDERS; the consumer EVALUATES. The math engine is app/domain
+ * logic and must NOT live in the design system — so these are pure types and the
+ * library never bundles a calculator (mirrors how `resolveUrl` keeps URL
+ * resolution in the consumer). A consumer produces a `CalcSheet` from a ```calc
+ * source; CalcBlock paints it.
+ */
+
+export type CalcValueKind =
+  | "number"
+  | "quantity"
+  | "currency"
+  | "date"
+  | "duration"
+  | "percent"
+  | "text"
+  | "error";
+
+/** A typed result value; `display` is the locale-formatted, tabular-ready string. */
+export interface CalcValue {
+  kind: CalcValueKind;
+  raw: number | string;
+  unit?: string;
+  display: string;
+}
+
+export type CalcTokenKind =
+  | "number"
+  | "unit"
+  | "currency"
+  | "operator"
+  | "function"
+  | "constant"
+  | "comment"
+  | "var-def"
+  | "var-ref"
+  | "line-ref"
+  | "unknown";
+
+/** One highlighted span within a source line — 0-based columns, `end` exclusive. */
+export interface CalcToken {
+  start: number;
+  end: number;
+  kind: CalcTokenKind;
+  /** `false` → a non-fatal warning style (unknown identifier / dangling ref). */
+  resolved: boolean;
+}
+
+/**
+ * Presentation hint: a rule (horizontal divider) drawn below a row — a `"dotted"`
+ * hairline, a `"single"` solid line, or a `"double"` line (e.g. above a subtotal).
+ * Pure presentation: the library renders it; the evaluator decides which rows get one.
+ */
+export type CalcRule = "dotted" | "single" | "double";
+
+/**
+ * Presentation hint: tint a row's background with a semantic status wash
+ * (theme-safe `bg-<token>/10`, matching the house status vocabulary). `"muted"`
+ * is a neutral, non-status tint. The evaluator decides; the library paints.
+ */
+export type CalcTint = "primary" | "success" | "warning" | "destructive" | "info" | "muted";
+
+/** One evaluated source line: its highlight tokens, and a value OR an error. */
+export interface CalcLineResult {
+  /** 1-based line within the calc source. */
+  line: number;
+  tokens: CalcToken[];
+  value?: CalcValue;
+  /** A per-line error rendered inline; never thrown. */
+  error?: { message: string };
+  /** Presentation hint: draw a rule (divider) below this row. */
+  rule?: CalcRule;
+  /** Presentation hint: tint this row's background with a semantic wash. */
+  tint?: CalcTint;
+}
+
+export interface CalcSheet {
+  results: CalcLineResult[];
+  /** Running total for the block. */
+  total?: CalcValue;
+}
+
+export interface CalcContext {
+  docPath?: string;
+}
+
+/** The consumer-supplied evaluator (sync, like `resolveUrl`). */
+export type EvaluateCalc = (source: string, ctx?: CalcContext) => CalcSheet;
+
+/* ------------------------------------------------------------------------- *
+ * Authoring hooks (#220) — the EDITOR side of calc.
+ *
+ * The render side (`CalcBlock`/`CalcInline`) takes `evaluate`; the editor side
+ * adds live highlighting + autocomplete + result inlays inside ```calc fences,
+ * in both the Monaco source surface and the Milkdown WYSIWYG surface. Same
+ * governing rule: the library DECORATES, the consumer COMPUTES — these are pure
+ * function types and the package bundles no calc engine (mirrors `resolveUrl`).
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Tokenize ONE calc source line into highlight spans (the columns the library
+ * paints). Called per line, so the returned {@link CalcToken} `start`/`end`
+ * columns are relative to `line` — the same shape `evaluate` already returns on
+ * each `CalcLineResult.tokens`. Sync, like `resolveUrl`.
+ */
+export type CalcTokenize = (line: string, ctx?: CalcContext) => CalcToken[];
+
+/** A completion category — drives the icon (Monaco) / glyph + label (WYSIWYG). */
+export type CalcCompletionKind =
+  | "variable"
+  | "function"
+  | "unit"
+  | "currency"
+  | "constant"
+  | "reference"
+  | "keyword"
+  | "snippet";
+
+/** One autocomplete suggestion offered inside a ```calc fence. */
+export interface CalcCompletion {
+  /** Text shown in the completion list. */
+  label: string;
+  /** Text inserted when the item is chosen (replaces the typed `prefix`). */
+  insert: string;
+  /** Secondary detail shown muted beside the label (e.g. a type or preview). */
+  detail?: string;
+  /** Category; selects the suggestion icon. Defaults to `"variable"`. */
+  kind?: CalcCompletionKind;
+}
+
+/** What the editor knows at the caret when it asks the consumer for completions. */
+export interface CalcCompletionContext extends CalcContext {
+  /** The full calc fence body (all lines). */
+  source: string;
+  /** The current line's text (the line the caret is on). */
+  line: string;
+  /** 1-based line of the caret within the fence body. */
+  lineNumber: number;
+  /** 0-based caret column within `line`. */
+  column: number;
+  /** The identifier characters immediately before the caret (the word typed). */
+  prefix: string;
+}
+
+/** Suggest completions at the caret inside a ```calc fence (sync). */
+export type CalcComplete = (ctx: CalcCompletionContext) => CalcCompletion[];
+
+/**
+ * The opt-in authoring hooks threaded onto `MarkdownEditor` / `MarkdownWorkspace`
+ * via the `calc` prop (off by default). Each capability is independent:
+ *   - `tokenize` → syntax highlighting (falls back to `evaluate`'s per-line
+ *     `tokens` when omitted, so a consumer who already wrote `evaluate` gets
+ *     highlighting for free).
+ *   - `evaluate` → per-line result inlays (the computed answer, shown after the
+ *     line). Reuses the existing {@link EvaluateCalc} contract.
+ *   - `complete` → autocomplete inside the fence (Monaco surface).
+ */
+export interface CalcEditorHooks {
+  tokenize?: CalcTokenize;
+  complete?: CalcComplete;
+  evaluate?: EvaluateCalc;
+}

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

@@ -0,0 +1,218 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, fireEvent, waitFor, within } from "storybook/test";
+import { useMemo, useState } from "react";
+import * as monaco from "monaco-editor";
+import { CodeEditor } from "./code-editor";
+import { EditorToolbar } from "../editor-toolbar";
+
+const meta = {
+  title: "Editor/CodeEditor",
+  component: CodeEditor,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          "A token-themed Monaco editor. The editing surface + widgets are Monaco; " +
+          "brand-ui supplies the chrome (toolbar/Select/Button). Colors track the " +
+          "active `data-theme` across all three themes via the theming bridge.",
+      },
+    },
+  },
+} satisfies Meta<typeof CodeEditor>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const TS_SAMPLE = `import { useState } from "react";
+
+interface CounterProps {
+  /** Starting value. */
+  start?: number;
+}
+
+export function Counter({ start = 0 }: CounterProps) {
+  const [count, setCount] = useState(start);
+  // Increment on click.
+  return <button onClick={() => setCount((c) => c + 1)}>{count}</button>;
+}
+`;
+
+const JSON_SAMPLE = `{
+  "name": "@elabs-ai/components-editor",
+  "version": "0.1.0",
+  "private": true,
+  "keywords": ["monaco", "editor", "tokens"],
+  "engines": { "node": ">=20" }
+}
+`;
+
+export const Default: Story = {
+  render: () => (
+    <div className="h-[440px] w-full border-border [&]:border">
+      <CodeEditor language="typescript" defaultValue={TS_SAMPLE} />
+    </div>
+  ),
+};
+
+export const WithToolbar: Story = {
+  render: function WithToolbarStory() {
+    const [language, setLanguage] = useState("typescript");
+    const [value, setValue] = useState(TS_SAMPLE);
+    return (
+      <div className="flex h-[440px] w-full flex-col overflow-hidden rounded-lg border border-border">
+        <EditorToolbar
+          filename="counter.tsx"
+          language={language}
+          onLanguageChange={setLanguage}
+          copyValue={value}
+        />
+        <div className="min-h-0 flex-1">
+          <CodeEditor language={language} value={value} onChange={setValue} />
+        </div>
+      </div>
+    );
+  },
+};
+
+export const JsonReadOnly: Story = {
+  name: "JSON (read-only)",
+  render: () => (
+    <div className="h-[300px] w-full border border-border">
+      <CodeEditor language="json" defaultValue={JSON_SAMPLE} readOnly />
+    </div>
+  ),
+};
+
+/**
+ * The minimap (right-edge "mini navigation view") enabled + themed, and the
+ * brand-ui context menu (right-click) that replaces Monaco's built-in one. The
+ * play test right-clicks the editor and asserts the brand menu items render.
+ */
+export const ContextMenuAndMinimap: Story = {
+  name: "Context menu + minimap",
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Right-click the editor: the menu is brand-ui's `ContextMenu` (not Monaco's), " +
+          "wired to the editor's actions. The minimap on the right edge is enabled via " +
+          "`options` and themed from tokens.",
+      },
+    },
+  },
+  render: () => (
+    <div className="h-[440px] w-full border border-border">
+      <CodeEditor
+        language="typescript"
+        defaultValue={TS_SAMPLE}
+        contextMenu="brand"
+        options={{ minimap: { enabled: true } }}
+      />
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    // Monaco mounts asynchronously — wait for the editor surface, then right-click.
+    const surface = await within(canvasElement).findByTestId("code-editor", {}, { timeout: 10000 });
+    fireEvent.contextMenu(surface);
+    const menu = within(document.body);
+    // `findBy*` retries only until the node EXISTS — but ContextMenuContent carries
+    // `data-[state=open]:fade-in-0`, so it starts at opacity 0 and a one-shot
+    // `toBeVisible()` races the entrance animation (#51, #278 pattern D). waitFor
+    // rides it out — the dropdown-menu.stories.tsx precedent.
+    const copy = await menu.findByRole("menuitem", { name: /copy/i });
+    await waitFor(() => expect(copy).toBeVisible());
+    const palette = await menu.findByRole("menuitem", { name: /command palette/i });
+    await waitFor(() => expect(palette).toBeVisible());
+  },
+};
+
+/**
+ * Accessibility: the editor forwards `ariaLabel` / `ariaInvalid` / `ariaDescribedBy`
+ * onto Monaco's inner screen-reader `<textarea>` (its real focusable surface) — NOT
+ * the wrapper div. This is the locking test for #34, asserted against REAL Monaco in
+ * a browser (a jsdom mock that swaps in a `<textarea>` cannot prove the real surface).
+ */
+export const Accessibility: Story = {
+  name: "Accessibility (aria forwarding)",
+  render: () => (
+    <div className="h-[300px] w-full border border-border">
+      <CodeEditor
+        language="typescript"
+        defaultValue={TS_SAMPLE}
+        ariaLabel="Source code editor"
+        ariaInvalid
+        ariaDescribedBy="editor-help"
+      />
+      <span id="editor-help" className="sr-only">
+        Edit the source code.
+      </span>
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    // Wait for Monaco to mount, then assert its inner screen-reader <textarea> (the
+    // real focusable surface) carries the aria-* — proving they reached Monaco, not
+    // just the wrapper div. We query the element directly (Monaco also stamps
+    // role="textbox" on a wrapper div, so a role query is ambiguous).
+    const surface = await within(canvasElement).findByTestId("code-editor", {}, { timeout: 10000 });
+    let textarea: HTMLTextAreaElement | null = null;
+    await waitFor(
+      () => {
+        textarea = surface.querySelector("textarea");
+        if (!textarea) throw new Error("Monaco textarea not mounted yet");
+      },
+      { timeout: 10000 },
+    );
+    await expect(textarea!).toHaveAttribute("aria-label", "Source code editor");
+    await expect(textarea!).toHaveAttribute("aria-invalid", "true");
+    await expect(textarea!).toHaveAttribute("aria-describedby", "editor-help");
+  },
+};
+
+/**
+ * Demonstrates the `actions` prop: a declarative array of Monaco editor actions
+ * that register commands in the keybinding system and the command palette. Press
+ * `Ctrl+K` / `Cmd+K` (or open the command palette and search "Say Hi") to
+ * trigger the action. The action is memoized to avoid re-registering on every
+ * render.
+ */
+export const WithActions: Story = {
+  name: "Declarative actions",
+  tags: ["autodocs"],
+  render: function WithActionsStory() {
+    const [feedback, setFeedback] = useState<string | null>(null);
+    const actions = useMemo(
+      () => [
+        {
+          id: "demo.sayHi",
+          label: "Say Hi",
+          keybindings: [monaco.KeyMod.CtrlCmd | monaco.KeyCode.KeyK],
+          contextMenuGroupId: "navigation",
+          contextMenuOrder: 1,
+          run: () => {
+            setFeedback("Action fired! (Ctrl+K / Cmd+K)");
+            setTimeout(() => setFeedback(null), 2500);
+          },
+        },
+      ],
+      [],
+    );
+    return (
+      <div className="flex h-[380px] w-full flex-col gap-2">
+        <div className="flex-1 rounded-md border border-border overflow-hidden">
+          <CodeEditor
+            language="typescript"
+            defaultValue={TS_SAMPLE}
+            actions={actions}
+            contextMenu="monaco"
+            ariaLabel="Actions demo editor"
+          />
+        </div>
+        <p className="text-caption text-muted-foreground">
+          {feedback ?? "Press Ctrl+K / Cmd+K — or open the command palette and search “Say Hi”."}
+        </p>
+      </div>
+    );
+  },
+};

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

@@ -0,0 +1,134 @@
+import { act, cleanup, render } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } 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 actionDisposable = { dispose: vi.fn() };
+  const editor = {
+    onDidChangeModelContent: vi.fn((cb: () => void) => {
+      state.changeHandler = cb;
+      return { dispose: vi.fn() };
+    }),
+    getValue: vi.fn(() => state.value),
+    setValue: vi.fn((v: string) => {
+      state.value = v;
+    }),
+    getModel: vi.fn(() => model),
+    updateOptions: vi.fn(),
+    addAction: vi.fn(() => actionDisposable),
+    // Minimal DOM node so the aria-forwarding effect can find (or not) a textarea.
+    getDomNode: vi.fn(() => null as HTMLElement | null),
+    dispose: vi.fn(),
+  };
+  return {
+    state,
+    model,
+    actionDisposable,
+    editor,
+    create: vi.fn(() => editor),
+    createModel: vi.fn((value: string) => {
+      state.value = value;
+      return model;
+    }),
+  };
+});
+
+vi.mock("monaco-editor", () => ({
+  editor: {
+    create: h.create,
+    createModel: h.createModel,
+    setModelLanguage: vi.fn(),
+    defineTheme: vi.fn(),
+    setTheme: vi.fn(),
+  },
+  Uri: { parse: (s: string) => ({ toString: () => s }) },
+}));
+
+import { CodeEditor } from "./code-editor";
+
+beforeEach(() => {
+  h.state.changeHandler = undefined;
+  h.state.value = "";
+  vi.clearAllMocks();
+});
+afterEach(cleanup);
+
+describe("CodeEditor", () => {
+  it("creates a Monaco editor with the initial value + language", () => {
+    const { getByTestId } = render(
+      <CodeEditor defaultValue="const a = 1;" language="typescript" />,
+    );
+    expect(getByTestId("code-editor")).toBeInTheDocument();
+    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`", () => {
+    render(<CodeEditor defaultValue="x" language="json" path="config/app.json" />);
+    expect(h.createModel).toHaveBeenCalledWith("x", "json", {
+      toString: expect.any(Function),
+    });
+  });
+
+  it("forwards content edits to onChange", () => {
+    const onChange = vi.fn();
+    render(<CodeEditor defaultValue="" onChange={onChange} />);
+    expect(h.state.changeHandler).toBeTypeOf("function");
+    act(() => {
+      h.state.value = "typed";
+      h.state.changeHandler?.();
+    });
+    expect(onChange).toHaveBeenCalledWith("typed");
+  });
+
+  it("disposes the editor + model on unmount", () => {
+    const { unmount } = render(<CodeEditor defaultValue="x" />);
+    unmount();
+    expect(h.editor.dispose).toHaveBeenCalledTimes(1);
+    expect(h.model.dispose).toHaveBeenCalledTimes(1);
+  });
+
+  describe("actions prop", () => {
+    it("calls addAction once per descriptor on mount", () => {
+      const actions = [
+        { id: "test.one", label: "One", run: vi.fn() },
+        { id: "test.two", label: "Two", run: vi.fn() },
+      ];
+      render(<CodeEditor defaultValue="" actions={actions} />);
+      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", () => {
+      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} />);
+      expect(h.editor.addAction).toHaveBeenCalledTimes(1);
+
+      rerender(<CodeEditor defaultValue="" actions={actionsV2} />);
+      // Old disposable disposed, then re-added for both new actions.
+      expect(h.actionDisposable.dispose).toHaveBeenCalledTimes(1);
+      expect(h.editor.addAction).toHaveBeenCalledTimes(3); // 1 + 2
+    });
+
+    it("disposes all action disposables on unmount", () => {
+      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} />);
+      expect(h.editor.addAction).toHaveBeenCalledTimes(2);
+      unmount();
+      expect(h.actionDisposable.dispose).toHaveBeenCalledTimes(2);
+    });
+  });
+});