@multiplatform.one/rich-text 6.1.0 → 6.4.0

package/src/editor/blockAnchor.ts

@@ -0,0 +1,42 @@
+/**
+ * Block-rect anchoring for bubble menus (web).
+ *
+ * Tiptap's BubbleMenu anchors to the text caret by default. For tall blocks
+ * (tables, code blocks) that puts the bubble INSIDE the block box — hovering
+ * over the first table row / first code line, where it traps pointer events
+ * and chases the caret on every keystroke. Anchoring to the block's own DOM
+ * rect keeps the bubble outside the block (above it, or flipped below by
+ * floating-ui), so block content stays clickable and the bubble holds still
+ * while typing. GitLab's content editor anchors its table/code chrome the
+ * same way.
+ */
+
+import type { Editor } from "@tiptap/core";
+
+interface BlockVirtualElement {
+  getBoundingClientRect: () => DOMRect;
+  contextElement: Element;
+}
+
+/**
+ * Returns a floating-ui VirtualElement for the nearest ancestor node of
+ * `nodeTypeName` containing the selection, or null when the selection is
+ * not inside one (the bubble is hidden by `shouldShow` in that case).
+ */
+export function getBlockVirtualElement(
+  editor: Editor,
+  nodeTypeName: string,
+): BlockVirtualElement | null {
+  const { $from } = editor.state.selection;
+  for (let depth = $from.depth; depth > 0; depth--) {
+    if ($from.node(depth).type.name !== nodeTypeName) continue;
+    const dom = editor.view.nodeDOM($from.before(depth));
+    if (dom instanceof HTMLElement) {
+      return {
+        getBoundingClientRect: () => dom.getBoundingClientRect(),
+        contextElement: dom,
+      };
+    }
+  }
+  return null;
+}

package/src/editor/capabilities.spec.ts

@@ -0,0 +1,190 @@
+/**
+ * VERIFY arm for LC-52 MARKDOWN-EXPRESSIBLE-EDITING.
+ *
+ * Proves the markdown capability surface is a real constraint, not a
+ * visual one: non-markdown extensions are NOT registered on the editor
+ * (their commands do not exist), and markdown in → edit → markdown out
+ * round-trips for the whole GFM-expressible set.
+ */
+import { describe, expect, it } from "vitest";
+import { Editor } from "@tiptap/core";
+import { MARKDOWN_COMMANDS, isCommandInCapabilities } from "./capabilities";
+import { buildEditorExtensions } from "./extensions";
+import { htmlToMarkdown, markdownToHtml } from "./markdown";
+import type { EditorCommand } from "../types";
+
+function createEditor(capabilities: "full" | "markdown", content = "<p>hello</p>") {
+  return new Editor({
+    element: document.createElement("div"),
+    extensions: buildEditorExtensions({ capabilities }),
+    content,
+  });
+}
+
+const NON_MARKDOWN_COMMANDS: EditorCommand[] = [
+  "underline",
+  "highlight",
+  "textColor",
+  "subscript",
+  "superscript",
+  "alignLeft",
+  "alignCenter",
+  "alignRight",
+  "alignJustify",
+  "mergeCells",
+  "splitCell",
+];
+
+describe("isCommandInCapabilities", () => {
+  it("allows everything in full capabilities", () => {
+    for (const command of [...MARKDOWN_COMMANDS, ...NON_MARKDOWN_COMMANDS]) {
+      expect(isCommandInCapabilities(command, "full")).toBe(true);
+    }
+  });
+
+  it("rejects non-markdown commands in markdown capabilities", () => {
+    for (const command of NON_MARKDOWN_COMMANDS) {
+      expect(isCommandInCapabilities(command, "markdown")).toBe(false);
+    }
+  });
+
+  it("keeps the GFM-expressible commands in markdown capabilities", () => {
+    for (const command of MARKDOWN_COMMANDS) {
+      expect(isCommandInCapabilities(command, "markdown")).toBe(true);
+    }
+  });
+});
+
+describe("markdown capabilities: extension registration", () => {
+  it("does not register underline/highlight/color/align/sub/sup extensions", () => {
+    const editor = createEditor("markdown");
+    const names = new Set(editor.extensionManager.extensions.map((e) => e.name));
+    expect(names.has("underline")).toBe(false);
+    expect(names.has("highlight")).toBe(false);
+    expect(names.has("textStyle")).toBe(false);
+    expect(names.has("color")).toBe(false);
+    expect(names.has("textAlign")).toBe(false);
+    expect(names.has("subscript")).toBe(false);
+    expect(names.has("superscript")).toBe(false);
+    expect(names.has("inlineMath")).toBe(false);
+    expect(names.has("details")).toBe(false);
+    editor.destroy();
+  });
+
+  it("commands markdown cannot express do not exist on the editor", () => {
+    const editor = createEditor("markdown");
+    const commands = editor.commands as unknown as Record<string, unknown>;
+    expect(commands.toggleUnderline).toBeUndefined();
+    expect(commands.toggleHighlight).toBeUndefined();
+    expect(commands.setColor).toBeUndefined();
+    expect(commands.setTextAlign).toBeUndefined();
+    expect(commands.toggleSubscript).toBeUndefined();
+    expect(commands.toggleSuperscript).toBeUndefined();
+    editor.destroy();
+  });
+
+  it("full capabilities keep the whole surface (control)", () => {
+    const editor = createEditor("full");
+    const names = new Set(editor.extensionManager.extensions.map((e) => e.name));
+    expect(names.has("underline")).toBe(true);
+    expect(names.has("highlight")).toBe(true);
+    expect(names.has("textAlign")).toBe(true);
+    const commands = editor.commands as unknown as Record<string, unknown>;
+    expect(typeof commands.toggleUnderline).toBe("function");
+    expect(typeof commands.toggleHighlight).toBe("function");
+    editor.destroy();
+  });
+
+  it("keeps the markdown-expressible surface registered", () => {
+    const editor = createEditor("markdown");
+    const commands = editor.commands as unknown as Record<string, unknown>;
+    for (const name of [
+      "toggleBold",
+      "toggleItalic",
+      "toggleStrike",
+      "toggleCode",
+      "toggleHeading",
+      "toggleBulletList",
+      "toggleOrderedList",
+      "toggleTaskList",
+      "toggleBlockquote",
+      "toggleCodeBlock",
+      "setLink",
+      "setImage",
+      "setHorizontalRule",
+      "insertTable",
+    ]) {
+      expect(typeof commands[name], name).toBe("function");
+    }
+    editor.destroy();
+  });
+
+  it("parses pasted underline/highlight HTML without those marks", () => {
+    const editor = createEditor(
+      "markdown",
+      "<p><u>under</u> and <mark>marked</mark> and <strong>bold</strong></p>",
+    );
+    const html = editor.getHTML();
+    expect(html).not.toContain("<u>");
+    expect(html).not.toContain("<mark>");
+    expect(html).toContain("<strong>bold</strong>");
+    editor.destroy();
+  });
+});
+
+describe("markdown round-trip (markdown in → edit → markdown out)", () => {
+  const roundTrip = (markdown: string): string => {
+    const editor = createEditor("markdown", markdownToHtml(markdown));
+    const out = htmlToMarkdown(editor.getHTML());
+    editor.destroy();
+    return out;
+  };
+
+  it("preserves headings, emphasis, strike, and inline code", () => {
+    const out = roundTrip(
+      "# Title\n\nSome **bold** and _italic_ and ~~gone~~ and `code` text.\n\n## Sub",
+    );
+    expect(out).toContain("# Title");
+    expect(out).toContain("**bold**");
+    expect(out).toContain("_italic_");
+    expect(out).toContain("~~gone~~");
+    expect(out).toContain("`code`");
+    expect(out).toContain("## Sub");
+  });
+
+  it("preserves bullet, ordered, and task lists", () => {
+    const out = roundTrip("- one\n- two\n\n1. first\n2. second\n\n- [x] done\n- [ ] todo");
+    expect(out).toMatch(/[-*] {1,3}one/);
+    expect(out).toMatch(/1\. {1,2}first/);
+    expect(out).toContain("[x] done");
+    expect(out).toContain("[ ] todo");
+  });
+
+  it("preserves blockquotes, fenced code, hr, links, and images", () => {
+    const out = roundTrip(
+      "> quoted\n\n```js\nconst a = 1;\n```\n\n---\n\n[site](https://example.com) ![alt](https://example.com/i.png)",
+    );
+    expect(out).toContain("> quoted");
+    expect(out).toContain("```");
+    expect(out).toContain("const a = 1;");
+    // any valid markdown thematic break (turndown emits "* * *")
+    expect(out).toMatch(/^(-{3,}|_{3,}|(\* ?){3,})$/m);
+    expect(out).toContain("[site](https://example.com)");
+    expect(out).toContain("![alt](https://example.com/i.png)");
+  });
+
+  it("preserves GFM pipe tables", () => {
+    const out = roundTrip("| Name | Role |\n| --- | --- |\n| Ada | Analyst |");
+    expect(out).toContain("| Name | Role |");
+    expect(out).toContain("| --- | --- |");
+    expect(out).toContain("| Ada | Analyst |");
+  });
+
+  it("edits made through markdown commands serialize to markdown", () => {
+    const editor = createEditor("markdown", markdownToHtml("plain text"));
+    editor.commands.selectAll();
+    editor.commands.toggleBold();
+    expect(htmlToMarkdown(editor.getHTML())).toContain("**plain text**");
+    editor.destroy();
+  });
+});

package/src/editor/capabilities.ts

@@ -0,0 +1,76 @@
+/**
+ * Editor capability presets.
+ *
+ * "markdown" constrains the WYSIWYG editor to exactly what GFM markdown can
+ * express (owner ruling, LC-52 MARKDOWN-EXPRESSIBLE-EDITING): bold, italic,
+ * strikethrough, inline code, links, headings, bullet/ordered/task lists,
+ * blockquote, fenced code blocks, images, horizontal rule, and simple pipe
+ * tables. Everything markdown cannot express — underline, highlight, text
+ * color, alignment, sub/superscript, collapsible details, inline math,
+ * mention chips, table cell merge/split — is ABSENT in this mode: the
+ * extensions are not registered (commands do not exist) and the toolbar
+ * controls do not render.
+ *
+ * This module is the single source of truth both the runtime (extension
+ * factory, toolbars, executeCommand guard) and the VERIFY specs consume.
+ */
+
+import type { EditorCapabilities, EditorCommand } from "../types";
+
+/** Commands expressible in GFM markdown (the "markdown" capability surface) */
+export const MARKDOWN_COMMANDS: ReadonlySet<EditorCommand> = new Set<EditorCommand>([
+  "bold",
+  "italic",
+  "strike",
+  "code",
+  "heading1",
+  "heading2",
+  "heading3",
+  "heading4",
+  "heading5",
+  "heading6",
+  "paragraph",
+  "bulletList",
+  "orderedList",
+  "taskList",
+  "blockquote",
+  "codeBlock",
+  "link",
+  "image",
+  "undo",
+  "redo",
+  "horizontalRule",
+  "clearFormatting",
+  // GFM pipe tables (simple grid — mergeCells/splitCell are NOT expressible)
+  "insertTable",
+  "addColumnBefore",
+  "addColumnAfter",
+  "deleteColumn",
+  "addRowBefore",
+  "addRowAfter",
+  "deleteRow",
+  "deleteTable",
+  "toggleHeaderRow",
+]);
+
+/** True when the command exists in the given capability surface */
+export function isCommandInCapabilities(
+  command: EditorCommand,
+  capabilities: EditorCapabilities = "full",
+): boolean {
+  if (capabilities === "full") return true;
+  return MARKDOWN_COMMANDS.has(command);
+}
+
+/**
+ * Slash-menu items excluded in markdown capabilities. Mermaid stays out of
+ * the INSERT surface to keep it strictly GFM (a hand-typed ``` fence still
+ * produces a plain code block); math and details have no markdown syntax.
+ * Emoji stays — it inserts a plain unicode character (just text).
+ */
+export const MARKDOWN_EXCLUDED_SLASH_IDS: readonly string[] = [
+  "mermaid",
+  "mathBlock",
+  "inlineMath",
+  "details",
+];

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();
+  });
+});