@multiplatform.one/rich-text 6.1.0 → 6.3.0

package/src/editor/codeBlockPreview.spec.ts

@@ -0,0 +1,144 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { Editor } from "@tiptap/core";
+import StarterKit from "@tiptap/starter-kit";
+import { common, createLowlight } from "lowlight";
+
+const renderMermaidDiagram = vi.fn(
+  async (code: string, _options?: { scheme?: "light" | "dark"; fontFamily?: string }) =>
+    code.includes("bad")
+      ? { ok: false as const, error: "Parse error on line 1: mock" }
+      : { ok: true as const, svg: "<svg data-mock='true'></svg>" },
+);
+const mountDiagramSvg = vi.fn((container: HTMLElement, _svg: string) => {
+  const el = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+  el.setAttribute("data-mock", "true");
+  container.replaceChildren(el);
+  return true;
+});
+
+vi.mock("@multiplatform.one/markdown/mermaid", () => ({
+  renderMermaidDiagram,
+  mountDiagramSvg,
+}));
+
+import {
+  CodeBlockWithPreview,
+  PreviewChromeStore,
+  getPreviewKind,
+  setPreviewChrome,
+} from "./codeBlockPreview";
+
+const lowlight = createLowlight(common);
+
+function createEditor(content: string) {
+  return new Editor({
+    element: document.createElement("div"),
+    extensions: [
+      StarterKit.configure({ codeBlock: false }),
+      CodeBlockWithPreview.configure({ lowlight }),
+      PreviewChromeStore,
+    ],
+    content,
+  });
+}
+
+async function waitFor(check: () => boolean, timeoutMs = 4000): Promise<void> {
+  const start = Date.now();
+  while (!check()) {
+    if (Date.now() - start > timeoutMs) throw new Error("waitFor timed out");
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+}
+
+beforeEach(() => {
+  renderMermaidDiagram.mockClear();
+  mountDiagramSvg.mockClear();
+});
+
+describe("getPreviewKind", () => {
+  it("previews only mermaid and math languages", () => {
+    expect(getPreviewKind("mermaid")).toBe("mermaid");
+    expect(getPreviewKind("math")).toBe("math");
+    expect(getPreviewKind("javascript")).toBeNull();
+    expect(getPreviewKind(null)).toBeNull();
+  });
+});
+
+describe("CodeBlockWithPreview node view", () => {
+  it("renders a mermaid diagram preview below the source", async () => {
+    const editor = createEditor(
+      '<pre><code class="language-mermaid">graph TD\n A--&gt;B</code></pre>',
+    );
+    const preview = editor.view.dom.querySelector<HTMLElement>(".rt-block-preview");
+    expect(preview).not.toBeNull();
+    await waitFor(() => preview!.dataset.state === "ok");
+    expect(preview!.querySelector("svg[data-mock]")).not.toBeNull();
+    expect(renderMermaidDiagram).toHaveBeenCalledWith(
+      "graph TD\n A-->B",
+      expect.objectContaining({ scheme: "light" }),
+    );
+    // source stays an editable code block (contentDOM)
+    expect(editor.view.dom.querySelector("pre code.language-mermaid")).not.toBeNull();
+    editor.destroy();
+  });
+
+  it("shows the parse error for invalid diagrams (Axiom 6: never blank)", async () => {
+    const editor = createEditor('<pre><code class="language-mermaid">bad graph</code></pre>');
+    const preview = editor.view.dom.querySelector<HTMLElement>(".rt-block-preview");
+    await waitFor(() => preview!.dataset.state === "error");
+    const error = preview!.querySelector(".rt-preview-error");
+    expect(error?.getAttribute("role")).toBe("alert");
+    expect(error?.textContent).toContain("Parse error on line 1: mock");
+    editor.destroy();
+  });
+
+  it("renders display-mode KaTeX for math blocks", async () => {
+    const editor = createEditor('<pre><code class="language-math">x^2 + y^2</code></pre>');
+    const preview = editor.view.dom.querySelector<HTMLElement>(".rt-block-preview");
+    await waitFor(() => preview!.dataset.state === "ok");
+    expect(preview!.querySelector(".rt-preview-math .katex")).not.toBeNull();
+    editor.destroy();
+  });
+
+  it("shows the TeX parse error for invalid math", async () => {
+    const editor = createEditor('<pre><code class="language-math">\\nope{</code></pre>');
+    const preview = editor.view.dom.querySelector<HTMLElement>(".rt-block-preview");
+    await waitFor(() => preview!.dataset.state === "error");
+    expect(preview!.querySelector(".rt-preview-error")?.textContent).toMatch(/parse error/i);
+    editor.destroy();
+  });
+
+  it("hides the preview pane for plain code and when switching away", async () => {
+    const editor = createEditor('<pre><code class="language-js">const a = 1;</code></pre>');
+    const preview = editor.view.dom.querySelector<HTMLElement>(".rt-block-preview");
+    expect(preview!.dataset.state).toBe("hidden");
+    editor.destroy();
+  });
+
+  it("re-renders when the language switches to a previewable one", async () => {
+    const editor = createEditor('<pre><code class="language-js">graph TD</code></pre>');
+    editor.commands.selectAll();
+    editor.commands.updateAttributes("codeBlock", { language: "mermaid" });
+    await waitFor(
+      () => editor.view.dom.querySelector<HTMLElement>(".rt-block-preview")?.dataset.state === "ok",
+    );
+    editor.destroy();
+  });
+
+  it("re-renders diagrams when the theme scheme flips", async () => {
+    const editor = createEditor('<pre><code class="language-mermaid">graph TD</code></pre>');
+    const preview = editor.view.dom.querySelector<HTMLElement>(".rt-block-preview");
+    await waitFor(() => preview!.dataset.state === "ok");
+    setPreviewChrome(editor, { scheme: "dark" });
+    await waitFor(() =>
+      renderMermaidDiagram.mock.calls.some(([, opts]) => opts?.scheme === "dark"),
+    );
+    editor.destroy();
+  });
+
+  it("keeps markdown fences lossless through getHTML (round-trip base)", () => {
+    const editor = createEditor('<pre><code class="language-mermaid">graph TD</code></pre>');
+    expect(editor.getHTML()).toContain("language-mermaid");
+    editor.destroy();
+  });
+});

package/src/editor/codeBlockPreview.ts

@@ -0,0 +1,266 @@
+/**
+ * Code block with live below-block preview for `mermaid` and `math`
+ * languages — GitLab content-editor parity.
+ *
+ * The code stays a normal editable code block (language picker, copy,
+ * tab-indent, lowlight all keep working through contentDOM); when the
+ * language is `mermaid` or `math` a preview pane renders below the source:
+ *
+ * - mermaid: SVG via the canonical `@multiplatform.one/markdown` renderer
+ *   (LC-16 — one implementation; the engine is dynamically imported on the
+ *   first diagram, zero eager bytes).
+ * - math: display-mode KaTeX via lazyKatex (same discipline).
+ *
+ * Re-renders are debounced while typing; the previous preview stays
+ * visible until the new one lands (no flicker). Invalid source shows the
+ * parse error in the pane (Axiom 6: show the error, never blank).
+ *
+ * `$$ ` at the start of a line opens a math block (GitLab-style display
+ * math input); ```mermaid and ```math fences already work through the
+ * inherited code block input rule.
+ */
+
+import CodeBlockLowlight from "@tiptap/extension-code-block-lowlight";
+import { Extension, textblockTypeInputRule } from "@tiptap/core";
+import type { Editor } from "@tiptap/core";
+import { t } from "../shared/t";
+import { mountKatexHtml, renderKatexHtml } from "./lazyKatex";
+
+// ===========================================================================
+// Preview chrome (theme scheme pushed by the editor host)
+// ===========================================================================
+
+export interface PreviewChrome {
+  /** Color scheme forwarded to the diagram/math renderers */
+  scheme: "light" | "dark";
+  /** CSS font family forwarded to mermaid's theme config */
+  fontFamily?: string;
+}
+
+interface PreviewChromeStorage {
+  value: PreviewChrome;
+  listeners: Set<() => void>;
+}
+
+declare module "@tiptap/core" {
+  interface Storage {
+    previewChrome: PreviewChromeStorage;
+  }
+}
+
+/**
+ * Storage-only extension carrying the resolved scheme for block previews.
+ * The editor host pushes values (setPreviewChrome) from React land; node
+ * views subscribe so a theme flip re-renders live diagrams.
+ */
+export const PreviewChromeStore = Extension.create({
+  name: "previewChrome",
+  addStorage(): PreviewChromeStorage {
+    return { value: { scheme: "light" }, listeners: new Set() };
+  },
+});
+
+export function setPreviewChrome(editor: Editor, chrome: PreviewChrome): void {
+  const storage = editor.storage.previewChrome;
+  if (!storage) return;
+  if (storage.value.scheme === chrome.scheme && storage.value.fontFamily === chrome.fontFamily) {
+    return;
+  }
+  storage.value = chrome;
+  for (const listener of storage.listeners) listener();
+}
+
+function getPreviewChrome(editor: Editor): PreviewChrome {
+  return editor?.storage?.previewChrome?.value ?? { scheme: "light" };
+}
+
+// ===========================================================================
+// Preview languages
+// ===========================================================================
+
+export const PREVIEW_LANGUAGES = ["mermaid", "math"] as const;
+export type PreviewLanguage = (typeof PREVIEW_LANGUAGES)[number];
+
+export function getPreviewKind(language: string | null | undefined): PreviewLanguage | null {
+  return (PREVIEW_LANGUAGES as readonly string[]).includes(language ?? "")
+    ? (language as PreviewLanguage)
+    : null;
+}
+
+const PREVIEW_DEBOUNCE_MS = 250;
+
+// ===========================================================================
+// Extension
+// ===========================================================================
+
+export const CodeBlockWithPreview = CodeBlockLowlight.extend({
+  addInputRules() {
+    return [
+      ...(this.parent?.() ?? []),
+      // `$$ ` opens a math block (GitLab display math), mirroring ```math
+      textblockTypeInputRule({
+        find: /^\$\$\s$/,
+        type: this.type,
+        getAttributes: { language: "math" },
+      }),
+    ];
+  },
+
+  addNodeView() {
+    return ({ node, editor, extension }) => {
+      const languageClassPrefix: string = extension.options.languageClassPrefix ?? "language-";
+
+      const dom = document.createElement("div");
+      dom.className = "rt-codeblock";
+      const pre = document.createElement("pre");
+      const code = document.createElement("code");
+      pre.appendChild(code);
+      dom.appendChild(pre);
+      const preview = document.createElement("div");
+      preview.className = "rt-block-preview";
+      preview.contentEditable = "false";
+      preview.dataset.state = "hidden";
+      dom.appendChild(preview);
+
+      let currentNode = node;
+      let destroyed = false;
+      let timer: ReturnType<typeof setTimeout> | null = null;
+      let renderSeq = 0;
+      let renderedKey: string | null = null;
+
+      const applyLanguageClass = () => {
+        const language = currentNode.attrs.language as string | null;
+        code.className = language ? `${languageClassPrefix}${language}` : "";
+        const kind = getPreviewKind(language);
+        if (kind) preview.dataset.previewType = kind;
+        else delete preview.dataset.previewType;
+      };
+
+      const showError = (message: string) => {
+        const el = document.createElement("div");
+        el.className = "rt-preview-error";
+        el.setAttribute("role", "alert");
+        // Axiom 6: surface the parse error, never a blank pane
+        el.textContent = message;
+        preview.replaceChildren(el);
+        preview.dataset.state = "error";
+      };
+
+      const showHost = (host: HTMLElement) => {
+        preview.replaceChildren(host);
+        preview.dataset.state = "ok";
+      };
+
+      const renderPreview = async () => {
+        const kind = getPreviewKind(currentNode.attrs.language);
+        if (!kind || destroyed) return;
+        const source = currentNode.textContent;
+        const chrome = getPreviewChrome(editor);
+        const key = `${kind}|${chrome.scheme}|${source}`;
+        if (key === renderedKey) return;
+        const seq = ++renderSeq;
+
+        if (!source.trim()) {
+          renderedKey = key;
+          const hint = document.createElement("div");
+          hint.className = "rt-preview-hint";
+          hint.textContent =
+            kind === "mermaid" ? t("Type a mermaid diagram") : t("Type a TeX expression");
+          preview.replaceChildren(hint);
+          preview.dataset.state = "empty";
+          return;
+        }
+
+        if (kind === "mermaid") {
+          // canonical lazy renderer (LC-16) via the dedicated dependency-
+          // free subpath entry — the editor chunk carries zero mermaid
+          // bytes, and the markdown barrel's closure never becomes
+          // graph-reachable (chunk-group tests would pin it eager)
+          const markdown = await import("@multiplatform.one/markdown/mermaid");
+          const result = await markdown.renderMermaidDiagram(source, {
+            scheme: chrome.scheme,
+            fontFamily: chrome.fontFamily,
+          });
+          if (destroyed || seq !== renderSeq) return;
+          renderedKey = key;
+          if (result.ok) {
+            const host = document.createElement("div");
+            host.className = "rt-preview-diagram";
+            host.setAttribute("role", "img");
+            host.setAttribute("aria-label", t("Mermaid diagram preview"));
+            if (markdown.mountDiagramSvg(host, result.svg)) showHost(host);
+            else showError(t("Diagram produced no output"));
+          } else {
+            showError(result.error);
+          }
+          return;
+        }
+
+        const result = await renderKatexHtml(source, { displayMode: true });
+        if (destroyed || seq !== renderSeq) return;
+        renderedKey = key;
+        if (result.ok) {
+          const host = document.createElement("div");
+          host.className = "rt-preview-math";
+          host.setAttribute("role", "img");
+          host.setAttribute("aria-label", source);
+          mountKatexHtml(host, result.html);
+          showHost(host);
+        } else {
+          showError(result.error);
+        }
+      };
+
+      const sync = (immediate = false) => {
+        applyLanguageClass();
+        if (timer) clearTimeout(timer);
+        const kind = getPreviewKind(currentNode.attrs.language);
+        if (!kind) {
+          preview.replaceChildren();
+          preview.dataset.state = "hidden";
+          renderedKey = null;
+          return;
+        }
+        if (preview.dataset.state === "hidden") {
+          const hint = document.createElement("div");
+          hint.className = "rt-preview-hint";
+          hint.textContent = t("Rendering preview…");
+          preview.replaceChildren(hint);
+          preview.dataset.state = "loading";
+        }
+        timer = setTimeout(() => void renderPreview(), immediate ? 0 : PREVIEW_DEBOUNCE_MS);
+      };
+
+      const themeListener = () => {
+        renderedKey = null;
+        sync(true);
+      };
+      editor.storage.previewChrome?.listeners.add(themeListener);
+
+      sync(true);
+
+      return {
+        dom,
+        contentDOM: code,
+        update: (updatedNode) => {
+          if (updatedNode.type !== currentNode.type) return false;
+          const languageChanged = updatedNode.attrs.language !== currentNode.attrs.language;
+          const textChanged = updatedNode.textContent !== currentNode.textContent;
+          currentNode = updatedNode;
+          if (languageChanged || textChanged) sync(languageChanged);
+          return true;
+        },
+        ignoreMutation: (mutation) => {
+          if (mutation.type === "selection") return false;
+          // the preview pane is chrome, not document content
+          return !code.contains(mutation.target);
+        },
+        destroy: () => {
+          destroyed = true;
+          if (timer) clearTimeout(timer);
+          editor.storage.previewChrome?.listeners.delete(themeListener);
+        },
+      };
+    };
+  },
+});

package/src/editor/css.d.ts

@@ -0,0 +1,2 @@
+/** Side-effect CSS imports (e.g. katex stylesheet) carried by bundlers */
+declare module "*.css";

package/src/editor/details.spec.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { Editor } from "@tiptap/core";
+import StarterKit from "@tiptap/starter-kit";
+import { Details, DetailsContent, DetailsSummary } from "@tiptap/extension-details";
+
+function createEditor(content = "<p>hello</p>") {
+  return new Editor({
+    element: document.createElement("div"),
+    extensions: [StarterKit, Details, DetailsSummary, DetailsContent],
+    content,
+  });
+}
+
+describe("collapsible details (GitLab <details> parity)", () => {
+  it("setDetails wraps the current block into a details section", () => {
+    const editor = createEditor("<p>body text</p>");
+    editor.commands.selectAll();
+    expect(editor.commands.setDetails()).toBe(true);
+    const html = editor.getHTML();
+    expect(html).toContain("<details");
+    expect(html).toContain("<summary");
+    expect(html).toContain("body text");
+    editor.destroy();
+  });
+
+  it("parses <details> HTML (the markdown round-trip shape) back into nodes", () => {
+    const editor = createEditor(
+      "<details><summary>Click</summary>" +
+        '<div data-type="detailsContent"><p>hidden</p></div></details>',
+    );
+    const html = editor.getHTML();
+    expect(html).toContain("<summary");
+    expect(html).toContain("Click");
+    expect(html).toContain("hidden");
+    editor.destroy();
+  });
+
+  it("unsetDetails unwraps back to plain blocks", () => {
+    const editor = createEditor("<p>body</p>");
+    editor.commands.selectAll();
+    editor.commands.setDetails();
+    // place cursor inside the summary and unwrap
+    editor.commands.setTextSelection(2);
+    expect(editor.commands.unsetDetails()).toBe(true);
+    expect(editor.getHTML()).not.toContain("<details");
+    editor.destroy();
+  });
+});

package/src/editor/editorStyles.spec.ts

@@ -9,6 +9,18 @@ describe("getEditorCSS", () => {
     expect(css).toContain("var(--blue10");
   });
 
+  it("carries no raw hex or rgba color literals (Axiom 5 / LC-18)", () => {
+    const css = getEditorCSS();
+    expect(css).not.toMatch(/#[0-9a-fA-F]{3,8}\b/);
+    expect(css).not.toMatch(/rgba?\(/);
+  });
+
+  it("placeholder uses the AA-passing muted text token (Axiom 12)", () => {
+    const css = getEditorCSS();
+    const placeholderRule = css.slice(css.indexOf("is-editor-empty"));
+    expect(placeholderRule).toContain("var(--color11)");
+  });
+
   it("applies minHeight and maxHeight options", () => {
     const css = getEditorCSS({ minHeight: 200, maxHeight: 500 });
     expect(css).toContain("min-height: 200px");
@@ -21,4 +33,17 @@ describe("getEditorCSS", () => {
     expect(css).toContain("min-height: 100px");
     expect(css).not.toContain("max-height");
   });
+
+  it("animation none (motionMs 0) silences bubble and drag-handle motion", () => {
+    const css = getEditorCSS({ motionMs: 0 });
+    expect(css).toContain("opacity 0ms");
+    expect(css).not.toContain("opacity 120ms");
+  });
+
+  it("default motion pairs enter and exit transitions on bubbles (LC-24)", () => {
+    const css = getEditorCSS({ motionMs: 120 });
+    expect(css).toContain("opacity 120ms");
+    // destination-state selector keeps the exit fade visible
+    expect(css).toContain('[style*="visibility: visible"]');
+  });
 });