@elabs-ai/components-editor 4.0.0

package/src/calc-block/calc-editor-prose.ts

@@ -0,0 +1,128 @@
+"use client";
+
+/**
+ * Milkdown / ProseMirror calc layer (#220) — live highlighting + result inlays for
+ * ```calc fences inside the WYSIWYG editor.
+ *
+ * A self-owned raw `$prose` plugin (zero new deps) that builds a `DecorationSet`
+ * over every `code_block` whose language is `calc`:
+ *   - inline decorations color each token from the `--calc-*` tokens (calc-editor.css);
+ *   - a widget decoration after each line shows the computed result inlay.
+ * The set is recomputed when the document changes. Hooks are read through a getter
+ * so a fresh `calc` prop identity never rebuilds the editor (mirrors `slashConfigRef`).
+ *
+ * The position math reuses the engine-neutral helpers in `calc-editor.ts`; a
+ * ProseMirror code block stores its body as plain text with literal `\n`, so a
+ * line's absolute position is `codeBlockContentStart + lineOffset + column`.
+ */
+import type { MilkdownPlugin } from "@milkdown/kit/ctx";
+import type { Node as ProseNode } from "@milkdown/kit/prose/model";
+import { Plugin, PluginKey } from "@milkdown/kit/prose/state";
+import { Decoration, DecorationSet } from "@milkdown/kit/prose/view";
+import { $prose } from "@milkdown/kit/utils";
+
+import "./calc-editor.css";
+
+import {
+  CALC_FENCE_LANG,
+  calcLineLayout,
+  calcTokenClassName,
+  resolveHighlight,
+  resolveInlays,
+  type CalcInlay,
+} from "./calc-editor";
+import type { CalcEditorHooks } from "./types";
+
+const clamp = (n: number, lo: number, hi: number): number => Math.min(hi, Math.max(lo, n));
+
+const calcDecorationKey = new PluginKey<DecorationSet>("brand-calc-decorations");
+
+/**
+ * Build the inline result-inlay widget DOM (non-editable, announced as text).
+ *
+ * a11y: the computed value is rendered as TEXT (never color-only) and is NOT
+ * `aria-hidden`, so AT reads it in browse mode; a native `title` labels it for
+ * mouse users. It is a ProseMirror decoration (not a model node), so a host that
+ * must guarantee results to AT in active-editing/forms mode should also surface
+ * them via a `role="status"` live region outside the editor.
+ */
+function inlayWidget(inlay: CalcInlay): HTMLElement {
+  const span = document.createElement("span");
+  span.className = inlay.isError ? "brand-calc-inlay brand-calc-inlay--error" : "brand-calc-inlay";
+  // The number itself is the signal (rendered as text); color is enhancement only.
+  span.textContent = inlay.text;
+  span.setAttribute("contenteditable", "false");
+  span.setAttribute("title", inlay.isError ? "Calc error" : "Calc result");
+  return span;
+}
+
+/** Walk the doc, decorating every ```calc code block with highlight + inlays. */
+function buildCalcDecorations(doc: ProseNode, hooks: CalcEditorHooks | undefined): DecorationSet {
+  if (!hooks || (!hooks.tokenize && !hooks.evaluate)) return DecorationSet.empty;
+  const decorations: Decoration[] = [];
+
+  doc.descendants((node, pos) => {
+    if (node.type.name !== "code_block" || node.attrs.language !== CALC_FENCE_LANG) {
+      return undefined;
+    }
+    const source = node.textContent;
+    const contentStart = pos + 1; // first char inside the code block
+    const layout = calcLineLayout(source);
+    const tokensByLine = resolveHighlight(hooks, source);
+
+    layout.forEach((span, i) => {
+      const lineStart = contentStart + span.offset;
+      for (const t of tokensByLine[i] ?? []) {
+        const start = clamp(t.start, 0, span.text.length);
+        const end = clamp(t.end, start, span.text.length);
+        if (end <= start) continue;
+        decorations.push(
+          Decoration.inline(lineStart + start, lineStart + end, {
+            class: calcTokenClassName(t.kind, t.resolved),
+          }),
+        );
+      }
+    });
+
+    for (const inlay of resolveInlays(hooks, source)) {
+      const span = layout[inlay.lineNumber - 1];
+      if (!span) continue;
+      const at = contentStart + span.offset + span.text.length;
+      decorations.push(
+        Decoration.widget(at, () => inlayWidget(inlay), {
+          side: 1,
+          ignoreSelection: true,
+          key: `brand-calc-inlay:${String(inlay.lineNumber)}:${inlay.text}`,
+        }),
+      );
+    }
+    return false; // a code block's content is plain text — don't descend
+  });
+
+  return DecorationSet.create(doc, decorations);
+}
+
+/**
+ * Build the calc decoration plugin. `getHooks` is read on every recompute so the
+ * editor never rebuilds when the `calc` prop identity changes. Returns a Milkdown
+ * plugin array to `.use()` (only when calc authoring is enabled).
+ */
+export function calcProsePlugins(getHooks: () => CalcEditorHooks | undefined): MilkdownPlugin[] {
+  const plugin = $prose(
+    () =>
+      new Plugin<DecorationSet>({
+        key: calcDecorationKey,
+        state: {
+          init: (_config, state) => buildCalcDecorations(state.doc, getHooks()),
+          apply: (tr, value, _old, newState) =>
+            tr.docChanged ? buildCalcDecorations(newState.doc, getHooks()) : value,
+        },
+        props: {
+          decorations(state) {
+            return calcDecorationKey.getState(state);
+          },
+        },
+      }),
+  );
+  return [plugin as unknown as MilkdownPlugin];
+}

package/src/calc-block/calc-editor.css

@@ -0,0 +1,80 @@
+/**
+ * Calc authoring decorations (#220) — shared by the Monaco source surface
+ * (decoration `inlineClassName`) and the Milkdown WYSIWYG surface (ProseMirror
+ * inline decorations + result-inlay widgets).
+ *
+ * Colors come from the `--calc-*` syntax tokens — the SAME tokens `CalcBlock`
+ * paints with (#221), already AA-verified against `--background` (the editor
+ * surface) and `--card` in all three themes — so highlighting tracks the theme via
+ * the cascade with no hardcoded hex. The compound `.brand-calc-tok.brand-calc-tok--x`
+ * selector raises specificity above Monaco's own token color class (`.mtkN`) so
+ * the calc color wins regardless of stylesheet load order (no `!important`).
+ *
+ * Hue is never the SOLE cue (var-def = weight, unresolved = dotted underline), so
+ * roles stay distinct in the high-contrast theme where the calc colors collapse
+ * toward the foreground — mirroring `CalcBlock.tokenClass`.
+ */
+
+.brand-calc-tok.brand-calc-tok--number,
+.brand-calc-tok.brand-calc-tok--constant {
+  color: var(--calc-number);
+}
+.brand-calc-tok.brand-calc-tok--unit {
+  color: var(--calc-unit);
+}
+.brand-calc-tok.brand-calc-tok--currency {
+  color: var(--calc-currency);
+}
+.brand-calc-tok.brand-calc-tok--operator {
+  color: var(--calc-operator);
+}
+.brand-calc-tok.brand-calc-tok--function {
+  color: var(--calc-function);
+}
+.brand-calc-tok.brand-calc-tok--var-ref {
+  color: var(--calc-variable);
+}
+.brand-calc-tok.brand-calc-tok--var-def {
+  color: var(--calc-variable);
+  font-weight: 500;
+}
+.brand-calc-tok.brand-calc-tok--line-ref {
+  color: var(--calc-reference);
+  font-variant-numeric: tabular-nums;
+}
+.brand-calc-tok.brand-calc-tok--comment {
+  color: var(--calc-comment);
+  font-style: italic;
+}
+.brand-calc-tok.brand-calc-tok--unknown {
+  color: var(--calc-warning);
+}
+
+/* Non-hue cue for unresolved identifiers / dangling refs — carries the role in
+   high-contrast, where hue is flattened. */
+.brand-calc-tok.brand-calc-tok--unresolved {
+  text-decoration: underline dotted;
+  text-decoration-thickness: 1px;
+  text-underline-offset: 2px;
+}
+
+/**
+ * WYSIWYG result inlay — a ProseMirror widget after each calc line showing the
+ * computed answer. The number IS the signal (shown as text), color is only an
+ * enhancement, and it is non-editable / non-selectable so it never enters the
+ * document. (The Monaco surface uses Monaco's own inlay hints, themed via the
+ * theme bridge's `editorInlayHint.*` colors — not this class.)
+ */
+.brand-calc-inlay {
+  /* Full strength (no opacity de-emphasis): the result is the answer, and the
+     `--calc-result` token is AA-verified at FULL opacity (#221) — reducing it
+     would drop effective contrast below what the contrast gate models. */
+  margin-inline-start: 1ch;
+  color: var(--calc-result);
+  font-variant-numeric: tabular-nums;
+  user-select: none;
+  white-space: pre;
+}
+.brand-calc-inlay--error {
+  color: var(--calc-warning);
+}

package/src/calc-block/calc-editor.stories.tsx

@@ -0,0 +1,272 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import type { ReactNode } from "react";
+
+import { MarkdownEditor } from "../markdown-editor";
+import { MarkdownWorkspace } from "../markdown-workspace";
+import type {
+  CalcComplete,
+  CalcCompletion,
+  CalcEditorHooks,
+  CalcToken,
+  CalcTokenize,
+  EvaluateCalc,
+} from "./types";
+
+/**
+ * Calc AUTHORING (#220) — the editor side of calc. The same `--calc-*` tokens
+ * `CalcBlock` renders with now drive LIVE highlighting + autocomplete + result
+ * inlays inside `calc` fences, in BOTH the Monaco source surface and the Milkdown
+ * WYSIWYG surface. Opt in via the `calc` prop with the consumer's hooks — the
+ * library decorates, the consumer computes (no calc engine is bundled).
+ *
+ * The `demoEngine` below stands in for the consumer's real evaluator (a tiny
+ * arithmetic + currency engine); it is intentionally OUTSIDE the package.
+ */
+const meta = {
+  title: "Editor/CalcEditor",
+  component: MarkdownWorkspace,
+  tags: ["autodocs"],
+  parameters: { layout: "fullscreen" },
+} satisfies Meta<typeof MarkdownWorkspace>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/* ----------------------------- demo calc engine ---------------------------- */
+/* A toy arithmetic + currency engine — the CONSUMER's domain logic, here only to
+   make the stories live. A real app supplies its own `tokenize`/`evaluate`/`complete`. */
+
+const CURRENCIES: Record<string, string> = { EUR: "€", USD: "$", GBP: "£" };
+const FUNCTIONS = ["sum", "avg", "min", "max", "round"];
+
+function createDemoEngine(): Required<CalcEditorHooks> {
+  /** Var names seen by the latest evaluate — lets `tokenize` mark dangling refs. */
+  const defined = new Set<string>();
+
+  const tokenize: CalcTokenize = (line) => {
+    const tokens: CalcToken[] = [];
+    const commentAt = line.indexOf("//");
+    const code = commentAt >= 0 ? line.slice(0, commentAt) : line;
+    if (commentAt >= 0) {
+      tokens.push({ start: commentAt, end: line.length, kind: "comment", resolved: true });
+    }
+    const isDef = /^\s*[A-Za-z_]\w*\s*=/.test(code);
+    let seenEq = false;
+    const re = /([A-Za-z_]\w*)|(\d[\d,]*(?:\.\d+)?)|([-+*/=()])|(%)/g;
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(code))) {
+      const text = m[0];
+      const start = m.index;
+      const end = start + text.length;
+      if (m[1]) {
+        if (text in CURRENCIES) tokens.push({ start, end, kind: "currency", resolved: true });
+        else if (FUNCTIONS.includes(text))
+          tokens.push({ start, end, kind: "function", resolved: true });
+        else if (isDef && !seenEq) tokens.push({ start, end, kind: "var-def", resolved: true });
+        else tokens.push({ start, end, kind: "var-ref", resolved: defined.has(text) });
+      } else if (m[2]) {
+        tokens.push({ start, end, kind: "number", resolved: true });
+      } else if (m[3]) {
+        if (text === "=") seenEq = true;
+        tokens.push({ start, end, kind: "operator", resolved: true });
+      } else if (m[4]) {
+        tokens.push({ start, end, kind: "unit", resolved: true });
+      }
+    }
+    return tokens.sort((a, b) => a.start - b.start);
+  };
+
+  /** Evaluate one expression string against the numeric env (precedence-correct). */
+  function evalExpr(expr: string, env: Map<string, number>): number {
+    const toks =
+      expr.replace(/\b(EUR|USD|GBP)\b/g, " ").match(/\d[\d,]*\.?\d*|[A-Za-z_]\w*|[-+*/()]/g) ?? [];
+    let i = 0;
+    const peek = () => toks[i];
+    const prim = (): number => {
+      const t = toks[i++];
+      if (t === "(") {
+        const v = addsub();
+        if (peek() === ")") i++;
+        return v;
+      }
+      if (t && /^\d/.test(t)) return Number(t.replace(/,/g, ""));
+      const v = t ? env.get(t) : undefined;
+      if (v === undefined) throw new Error(`Undefined symbol "${t ?? "?"}"`);
+      return v;
+    };
+    const muldiv = (): number => {
+      let v = prim();
+      while (peek() === "*" || peek() === "/") {
+        const op = toks[i++];
+        const r = prim();
+        v = op === "*" ? v * r : v / r;
+      }
+      return v;
+    };
+    function addsub(): number {
+      let v = muldiv();
+      while (peek() === "+" || peek() === "-") {
+        const op = toks[i++];
+        const r = muldiv();
+        v = op === "+" ? v + r : v - r;
+      }
+      return v;
+    }
+    return addsub();
+  }
+
+  const evaluate: EvaluateCalc = (source) => {
+    const env = new Map<string, number>();
+    const units = new Map<string, string>();
+    defined.clear();
+    const results = source.split("\n").map((raw, idx) => {
+      const line = idx + 1;
+      const tokens = tokenize(raw);
+      const code = raw.includes("//") ? raw.slice(0, raw.indexOf("//")) : raw;
+      const trimmed = code.trim();
+      if (trimmed === "" || trimmed.startsWith("#")) return { line, tokens };
+      const def = /^\s*([A-Za-z_]\w*)\s*=\s*(.+)$/.exec(code);
+      const name = def?.[1];
+      const expr = def ? def[2] : code;
+      const curMatch = /\b(EUR|USD|GBP)\b/.exec(expr);
+      try {
+        const value = evalExpr(expr, env);
+        // Unit: an explicit currency in the line, else inherited from a referenced var.
+        let unit = curMatch?.[1];
+        if (!unit) {
+          for (const id of expr.match(/[A-Za-z_]\w*/g) ?? []) {
+            if (units.has(id)) {
+              unit = units.get(id);
+              break;
+            }
+          }
+        }
+        if (name) {
+          env.set(name, value);
+          defined.add(name);
+          if (unit) units.set(name, unit);
+        }
+        const display = unit
+          ? `${CURRENCIES[unit] ?? ""}${value.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`
+          : value.toLocaleString("en-US", { maximumFractionDigits: 2 });
+        return {
+          line,
+          tokens,
+          value: {
+            kind: unit ? ("currency" as const) : ("number" as const),
+            raw: value,
+            unit,
+            display,
+          },
+        };
+      } catch (err) {
+        return { line, tokens, error: { message: (err as Error).message } };
+      }
+    });
+    const totals = results.filter((r) => r.value).map((r) => Number(r.value!.raw));
+    const last = results.filter((r) => r.value).at(-1);
+    return {
+      results,
+      total: last?.value
+        ? { ...last.value }
+        : totals.length
+          ? {
+              kind: "number",
+              raw: totals.reduce((a, b) => a + b, 0),
+              display: String(totals.reduce((a, b) => a + b, 0)),
+            }
+          : undefined,
+    };
+  };
+
+  const complete: CalcComplete = ({ source, prefix }) => {
+    const vars = new Set<string>();
+    for (const line of source.split("\n")) {
+      const m = /^\s*([A-Za-z_]\w*)\s*=/.exec(line);
+      if (m?.[1]) vars.add(m[1]);
+    }
+    const items: CalcCompletion[] = [];
+    for (const v of vars) items.push({ label: v, insert: v, kind: "variable", detail: "variable" });
+    for (const f of FUNCTIONS)
+      items.push({ label: f, insert: `${f}()`, kind: "function", detail: "function" });
+    for (const c of Object.keys(CURRENCIES))
+      items.push({ label: c, insert: c, kind: "currency", detail: "currency unit" });
+    const p = prefix.toLowerCase();
+    return p ? items.filter((i) => i.label.toLowerCase().startsWith(p)) : items;
+  };
+
+  return { tokenize, evaluate, complete };
+}
+
+const demoEngine = createDemoEngine();
+
+const DOC = [
+  "# Trip budget",
+  "",
+  "Live numbers for the Lisbon trip — edit a value and the answers update.",
+  "",
+  "```calc",
+  "flights = 320 EUR",
+  "hotel = 95 EUR * 4",
+  "transit = 60 EUR",
+  "total = flights + hotel + transit",
+  "mystery = ghost + 1 // a dangling ref",
+  "```",
+  "",
+  "The fence above is highlighted and shows each line's result inline.",
+].join("\n");
+
+function Frame({ children }: { children: ReactNode }) {
+  return <div className="h-[520px] bg-background p-4 text-foreground">{children}</div>;
+}
+
+/**
+ * The hybrid workspace in SPLIT mode: the Monaco source pane highlights the
+ * `calc` fence + shows result inlays, and the preview renders the same fence as
+ * a branded `CalcBlock`. Type inside the fence (e.g. `flights`) for completions.
+ */
+export const Workspace: Story = {
+  render: () => (
+    <Frame>
+      <MarkdownWorkspace defaultValue={DOC} defaultMode="split" calc={demoEngine} />
+    </Frame>
+  ),
+};
+
+/**
+ * SOURCE mode — the Monaco surface alone: calc highlighting, end-of-line result
+ * inlays, and autocomplete (Ctrl+Space or type a variable prefix inside the fence).
+ */
+export const SourceEditor: Story = {
+  render: () => (
+    <Frame>
+      <MarkdownWorkspace defaultValue={DOC} defaultMode="source" calc={demoEngine} />
+    </Frame>
+  ),
+};
+
+/**
+ * The Milkdown WYSIWYG surface — the `calc` fence renders as an editable code
+ * block with the SAME calc highlighting + result inlays via a ProseMirror
+ * decoration plugin. Type `/calc` on a new line to insert a fresh fence.
+ */
+export const Wysiwyg: Story = {
+  render: () => (
+    <Frame>
+      <MarkdownEditor defaultValue={DOC} calc={demoEngine} className="h-full" />
+    </Frame>
+  ),
+};
+
+/** Highlight + inlays with NO `complete` hook — a consumer who only wrote `evaluate`. */
+export const EvaluateOnly: Story = {
+  render: () => (
+    <Frame>
+      <MarkdownWorkspace
+        defaultValue={DOC}
+        defaultMode="split"
+        calc={{ evaluate: demoEngine.evaluate }}
+      />
+    </Frame>
+  ),
+};