@multiplatform.one/rich-text 6.1.0 → 6.4.0

package/src/editor/extensions.ts

@@ -0,0 +1,315 @@
+/**
+ * Extension factory for the web Tiptap editor.
+ *
+ * One canonical list (LC-16) consumed by TiptapEditor AND by the
+ * capability specs, so what ships is exactly what is verified. With
+ * `capabilities: "markdown"` the non-markdown extensions are NOT
+ * registered — their commands do not exist on the editor (LC-52
+ * MARKDOWN-EXPRESSIBLE-EDITING), and StarterKit's underline sub-extension
+ * is disabled.
+ */
+
+import { Extension, type Extensions } from "@tiptap/core";
+import StarterKit from "@tiptap/starter-kit";
+import Placeholder from "@tiptap/extension-placeholder";
+import TextAlign from "@tiptap/extension-text-align";
+import { Color } from "@tiptap/extension-color";
+import { TextStyle } from "@tiptap/extension-text-style";
+import { Highlight } from "@tiptap/extension-highlight";
+import { Subscript } from "@tiptap/extension-subscript";
+import { Superscript } from "@tiptap/extension-superscript";
+import TaskList from "@tiptap/extension-task-list";
+import TaskItem from "@tiptap/extension-task-item";
+import Image from "@tiptap/extension-image";
+import Typography from "@tiptap/extension-typography";
+import CharacterCount from "@tiptap/extension-character-count";
+import { Details, DetailsContent, DetailsSummary } from "@tiptap/extension-details";
+import { Table } from "@tiptap/extension-table";
+import { TableRow } from "@tiptap/extension-table-row";
+import { TableHeader } from "@tiptap/extension-table-header";
+import { TableCell } from "@tiptap/extension-table-cell";
+import { common, createLowlight } from "lowlight";
+import type { EditorCapabilities } from "../types";
+import { MARKDOWN_EXCLUDED_SLASH_IDS } from "./capabilities";
+import { SlashCommands } from "./SlashCommands";
+import { MarkdownPaste } from "./MarkdownPaste";
+import { BlockDragHandle } from "./BlockDragHandle";
+import { MediaUpload } from "./media";
+import { EmojiSuggestion } from "./emoji";
+import { InlineMath } from "./mathematics";
+import { CodeBlockWithPreview, PreviewChromeStore } from "./codeBlockPreview";
+import { SuggestionChromeStore } from "./suggestionPopup";
+import { t } from "../shared/t";
+
+const lowlight = createLowlight(common);
+
+/**
+ * Tab / Shift-Tab indentation inside code blocks.
+ * Inserts or removes 2 spaces at the cursor (or start of each selected line).
+ */
+export const CodeBlockTabIndent = Extension.create({
+  name: "codeBlockTabIndent",
+  addKeyboardShortcuts() {
+    return {
+      Tab: ({ editor }) => {
+        if (!editor.isActive("codeBlock")) return false;
+        const { state, dispatch } = editor.view;
+        const { from, to } = state.selection;
+
+        if (from === to) {
+          dispatch(state.tr.insertText("  ", from, to));
+          return true;
+        }
+
+        const doc = state.doc;
+        const lines: { start: number }[] = [];
+        doc.nodesBetween(from, to, (node, pos) => {
+          if (node.isTextblock) {
+            lines.push({ start: pos + 1 });
+          }
+        });
+        if (lines.length === 0) {
+          dispatch(state.tr.insertText("  ", from, to));
+          return true;
+        }
+
+        let tr = state.tr;
+        let offset = 0;
+        for (const line of lines) {
+          const lineStart = line.start + offset;
+          tr = tr.insertText("  ", lineStart);
+          offset += 2;
+        }
+        dispatch(tr);
+        return true;
+      },
+      "Shift-Tab": ({ editor }) => {
+        if (!editor.isActive("codeBlock")) return false;
+        const { state, dispatch } = editor.view;
+        const { from, to, $from } = state.selection;
+
+        if (from === to) {
+          const lineStart = from - $from.parentOffset;
+          const text = state.doc.textBetween(lineStart, from);
+          const leadingSpaces = text.match(/^ {1,2}/)?.[0];
+          if (leadingSpaces) {
+            dispatch(state.tr.delete(lineStart, lineStart + leadingSpaces.length));
+          }
+          return true;
+        }
+
+        const doc = state.doc;
+        let tr = state.tr;
+        let offset = 0;
+        doc.nodesBetween(from, to, (node, pos) => {
+          if (node.isTextblock) {
+            const lineStart = pos + 1 + offset;
+            const text = tr.doc.textBetween(
+              lineStart,
+              Math.min(lineStart + node.content.size, tr.doc.content.size),
+            );
+            const leadingSpaces = text.match(/^ {1,2}/)?.[0];
+            if (leadingSpaces) {
+              tr = tr.delete(lineStart, lineStart + leadingSpaces.length);
+              offset -= leadingSpaces.length;
+            }
+          }
+        });
+        dispatch(tr);
+        return true;
+      },
+    };
+  },
+});
+
+/**
+ * Override Shift-Enter and Mod-Enter to create new paragraphs instead of
+ * hard breaks (<br>). Mirrors GitLab's approach: HardBreak node stays
+ * registered (so <br> in pasted HTML is preserved) but its keyboard
+ * shortcuts are replaced with the default enter (split paragraph) behavior.
+ */
+export const ParagraphEnterKeys = Extension.create({
+  name: "paragraphEnterKeys",
+  priority: 1000,
+  addKeyboardShortcuts() {
+    return {
+      "Shift-Enter": ({ editor }) =>
+        editor.commands.first([
+          () => editor.commands.newlineInCode(),
+          () => editor.commands.splitListItem("listItem"),
+          () => editor.commands.createParagraphNear(),
+          () => editor.commands.liftEmptyBlock(),
+          () => editor.commands.splitBlock(),
+        ]),
+      "Mod-Enter": ({ editor }) =>
+        editor.commands.first([
+          () => editor.commands.newlineInCode(),
+          () => editor.commands.createParagraphNear(),
+          () => editor.commands.liftEmptyBlock(),
+          () => editor.commands.splitBlock(),
+        ]),
+    };
+  },
+});
+
+/**
+ * Tab/Shift-Tab indent/dedent and Alt+Arrow move for list items.
+ * Tab sinks (indents), Shift-Tab lifts (dedents).
+ * Alt+Up/Down moves the list item up or down among siblings.
+ */
+export const ListItemKeys = Extension.create({
+  name: "listItemKeys",
+  addKeyboardShortcuts() {
+    return {
+      Tab: ({ editor }) => {
+        if (editor.isActive("codeBlock")) return false;
+        if (
+          editor.isActive("bulletList") ||
+          editor.isActive("orderedList") ||
+          editor.isActive("taskList")
+        ) {
+          return (
+            editor.commands.sinkListItem("listItem") || editor.commands.sinkListItem("taskItem")
+          );
+        }
+        return false;
+      },
+      "Shift-Tab": ({ editor }) => {
+        if (editor.isActive("codeBlock")) return false;
+        if (
+          editor.isActive("bulletList") ||
+          editor.isActive("orderedList") ||
+          editor.isActive("taskList")
+        ) {
+          return (
+            editor.commands.liftListItem("listItem") || editor.commands.liftListItem("taskItem")
+          );
+        }
+        return false;
+      },
+    };
+  },
+});
+
+// ===========================================================================
+// Factory
+// ===========================================================================
+
+export interface BuildEditorExtensionsOptions {
+  /** Capability preset (default "full") */
+  capabilities?: EditorCapabilities;
+  /** Placeholder text (defaults to the translated "Start writing...") */
+  placeholder?: string;
+  /** Pre-built mention extension (ignored in markdown capabilities) */
+  mentionExtension?: Extensions[number] | null;
+}
+
+/** Build the production extension list for the given capability surface */
+export function buildEditorExtensions({
+  capabilities = "full",
+  placeholder,
+  mentionExtension = null,
+}: BuildEditorExtensionsOptions = {}): Extensions {
+  const markdown = capabilities === "markdown";
+
+  return [
+    StarterKit.configure({
+      heading: {
+        levels: [1, 2, 3, 4, 5, 6],
+        HTMLAttributes: { dir: "auto" },
+      },
+      paragraph: {
+        HTMLAttributes: { dir: "auto" },
+      },
+      link: {
+        openOnClick: false,
+        HTMLAttributes: {
+          rel: "noopener noreferrer",
+          target: "_blank",
+        },
+      },
+      bulletList: {
+        keepMarks: true,
+      },
+      orderedList: {
+        keepMarks: true,
+      },
+      codeBlock: false,
+      hardBreak: false,
+      // Markdown has no underline syntax — the mark must not exist
+      ...(markdown && { underline: false }),
+    }),
+    CodeBlockWithPreview.configure({
+      lowlight,
+      exitOnTripleEnter: true,
+      exitOnArrowDown: false,
+    }),
+    ParagraphEnterKeys,
+    CodeBlockTabIndent,
+    ListItemKeys,
+    // superscriptTwo/Three would mangle typed TeX (`$E=mc^2$` became
+    // `E=mc²` before the math input rule ran) — off, rest stays.
+    Typography.configure({
+      superscriptTwo: false,
+      superscriptThree: false,
+    }),
+    CharacterCount,
+    SlashCommands.configure({
+      excludeIds: markdown ? [...MARKDOWN_EXCLUDED_SLASH_IDS] : [],
+    }),
+    MarkdownPaste,
+    MediaUpload,
+    SuggestionChromeStore,
+    PreviewChromeStore,
+    // Emoji suggestions insert plain unicode characters (just text), so
+    // they stay available in markdown capabilities.
+    EmojiSuggestion,
+    ...(markdown
+      ? []
+      : [
+          InlineMath,
+          // Collapsible sections (GitLab <details> parity). persist: true
+          // is the extension's supported mode: its node view re-syncs the
+          // open state from node.attrs on every update, so ephemeral
+          // (persist: false) toggles get reverted by the next transaction.
+          // The open state therefore lives in the doc and serializes as
+          // `<details open>` — valid GitLab markdown.
+          Details.configure({ persist: true }),
+          DetailsSummary,
+          DetailsContent,
+        ]),
+    // Mention chips have no markdown representation — full surface only
+    ...(mentionExtension && !markdown ? [mentionExtension] : []),
+    BlockDragHandle,
+    Table.configure({ resizable: true }),
+    TableRow,
+    TableHeader,
+    TableCell,
+    Placeholder.configure({
+      placeholder: placeholder ?? t("Start writing..."),
+    }),
+    ...(markdown
+      ? []
+      : [
+          TextAlign.configure({
+            types: ["heading", "paragraph"],
+            defaultAlignment: "left",
+          }),
+          TextStyle,
+          Color,
+          Highlight.configure({
+            multicolor: true,
+          }),
+          Subscript,
+          Superscript,
+        ]),
+    TaskList,
+    TaskItem.configure({
+      nested: true,
+    }),
+    Image.configure({
+      inline: true,
+      allowBase64: true,
+    }),
+  ];
+}

package/src/editor/lazyKatex.spec.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { mountKatexHtml, renderKatexHtml } from "./lazyKatex";
+
+describe("renderKatexHtml", () => {
+  it("renders valid TeX to KaTeX markup", async () => {
+    const result = await renderKatexHtml("x^2");
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.html).toContain("katex");
+  });
+
+  it("renders display mode for block math", async () => {
+    const result = await renderKatexHtml("\\sum_{i=0}^n i", { displayMode: true });
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.html).toContain("katex-display");
+  });
+
+  it("returns the parse error for invalid TeX (Axiom 6: never blank)", async () => {
+    const result = await renderKatexHtml("\\undefinedmacro{");
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error).toMatch(/parse error/i);
+  });
+});
+
+describe("mountKatexHtml", () => {
+  it("mounts markup as real nodes", async () => {
+    const result = await renderKatexHtml("x^2");
+    const container = document.createElement("span");
+    if (result.ok) mountKatexHtml(container, result.html);
+    expect(container.querySelector(".katex")).not.toBeNull();
+  });
+
+  it("strips executable elements (defense in depth)", () => {
+    const container = document.createElement("span");
+    mountKatexHtml(container, '<span class="katex">ok</span><script>alert(1)</script>');
+    expect(container.querySelector("script")).toBeNull();
+    expect(container.querySelector(".katex")?.textContent).toBe("ok");
+  });
+});

package/src/editor/lazyKatex.ts

@@ -0,0 +1,68 @@
+/**
+ * Lazy KaTeX renderer for `$...$` inline and `$$...$$` block math.
+ *
+ * Bundle discipline: KaTeX (~70 KB gz JS + CSS + fonts) never rides the
+ * editor chunk. Both the library and its stylesheet load through dynamic
+ * import on the first math render and are cached for the session. The
+ * stylesheet colors inherit `currentColor`, so dark schemes work without
+ * a separate dark CSS pass.
+ *
+ * The result contract is Axiom 6 friendly — invalid TeX returns
+ * `{ ok: false, error }` with KaTeX's parse message so callers can show
+ * the error instead of a blank node.
+ */
+
+export type KatexRenderResult = { ok: true; html: string } | { ok: false; error: string };
+
+type KatexModule = typeof import("katex").default;
+
+let katexPromise: Promise<KatexModule> | null = null;
+
+function loadKatex(): Promise<KatexModule> {
+  if (!katexPromise) {
+    katexPromise = Promise.all([
+      import("katex"),
+      // the stylesheet (fonts included) code-splits with this async chunk
+      import("katex/dist/katex.min.css"),
+    ]).then(([mod]) => (mod as any).default ?? mod);
+  }
+  return katexPromise;
+}
+
+/** Renders TeX to KaTeX HTML markup (display mode for `$$` blocks) */
+export async function renderKatexHtml(
+  latex: string,
+  options: { displayMode?: boolean } = {},
+): Promise<KatexRenderResult> {
+  try {
+    const katex = await loadKatex();
+    const html = katex.renderToString(latex, {
+      displayMode: options.displayMode ?? false,
+      throwOnError: true,
+      strict: false,
+    });
+    return { ok: true, html };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/**
+ * Mounts KaTeX markup as real DOM nodes. KaTeX output is spans + MathML by
+ * construction; parsing inert and stripping executables is defense in
+ * depth, mirroring the mermaid mount helper.
+ */
+export function mountKatexHtml(container: HTMLElement, html: string): void {
+  const doc = new DOMParser().parseFromString(html, "text/html");
+  for (const el of Array.from(doc.body.querySelectorAll("script, iframe, object, embed"))) {
+    el.remove();
+  }
+  container.replaceChildren(
+    ...Array.from(doc.body.childNodes).map((node) => document.importNode(node, true)),
+  );
+}
+
+/** Test seam: reset the cached library promise */
+export function resetKatexForTesting(): void {
+  katexPromise = null;
+}

package/src/editor/markdown.spec.ts

@@ -0,0 +1,196 @@
+import { describe, expect, it } from "vitest";
+import { htmlToMarkdown, markdownToHtml } from "./markdown";
+
+describe("htmlToMarkdown", () => {
+  it("converts headings, emphasis, and inline code to GFM", () => {
+    const md = htmlToMarkdown(
+      "<h1>Title</h1><p><strong>bold</strong> and <em>italic</em> and <code>code</code></p>",
+    );
+    expect(md).toContain("# Title");
+    expect(md).toContain("**bold**");
+    expect(md).toContain("_italic_");
+    expect(md).toContain("`code`");
+  });
+
+  it("converts strikethrough to ~~", () => {
+    expect(htmlToMarkdown("<p><s>gone</s></p>")).toContain("~~gone~~");
+    expect(htmlToMarkdown("<p><del>gone</del></p>")).toContain("~~gone~~");
+  });
+
+  it("converts fenced code blocks", () => {
+    const md = htmlToMarkdown('<pre><code class="language-js">const a = 1;</code></pre>');
+    expect(md).toContain("```");
+    expect(md).toContain("const a = 1;");
+  });
+
+  it("converts Tiptap task items to GFM checkboxes", () => {
+    const html =
+      '<ul data-type="taskList">' +
+      '<li data-type="taskItem" data-checked="true"><label><input type="checkbox" checked><span></span></label><div><p>done</p></div></li>' +
+      '<li data-type="taskItem" data-checked="false"><label><input type="checkbox"><span></span></label><div><p>todo</p></div></li>' +
+      "</ul>";
+    const md = htmlToMarkdown(html);
+    expect(md).toContain("- [x] done");
+    expect(md).toContain("- [ ] todo");
+  });
+
+  it("converts tables to GFM pipe tables", () => {
+    const html =
+      "<table><tr><th>Name</th><th>Role</th></tr><tr><td>Ada</td><td>Analyst</td></tr></table>";
+    const md = htmlToMarkdown(html);
+    expect(md).toContain("| Name | Role |");
+    expect(md).toContain("| --- | --- |");
+    expect(md).toContain("| Ada | Analyst |");
+  });
+
+  it("escapes pipes inside table cells", () => {
+    const md = htmlToMarkdown("<table><tr><th>A</th></tr><tr><td>x | y</td></tr></table>");
+    expect(md).toContain("x \\| y");
+  });
+
+  it("keeps marks markdown cannot express as inline HTML (lossless)", () => {
+    const md = htmlToMarkdown(
+      '<p><u>under</u> <sub>sub</sub> <sup>sup</sup> <mark>hi</mark> <span style="color: rgb(255, 0, 0)">red</span></p>',
+    );
+    expect(md).toContain("<u>under</u>");
+    expect(md).toContain("<sub>sub</sub>");
+    expect(md).toContain("<sup>sup</sup>");
+    expect(md).toContain("<mark>hi</mark>");
+    expect(md).toMatch(/<span style="color:\s*rgb\(255,\s*0,\s*0\)/);
+  });
+});
+
+describe("markdownToHtml", () => {
+  it("converts GFM to HTML", () => {
+    const html = markdownToHtml("# Title\n\n**bold** and ~~strike~~");
+    expect(html).toContain("<h1>Title</h1>");
+    expect(html).toContain("<strong>bold</strong>");
+    expect(html).toContain("<del>strike</del>");
+  });
+
+  it("upgrades GFM task lists to the Tiptap taskList schema", () => {
+    const html = markdownToHtml("- [x] done\n- [ ] todo");
+    expect(html).toContain('data-type="taskList"');
+    expect(html).toContain('data-type="taskItem"');
+    expect(html).toContain('data-checked="true"');
+    expect(html).toContain('data-checked="false"');
+    // marked's raw checkbox inputs are removed after the upgrade
+    expect(html).not.toContain("<input");
+  });
+
+  it("parses pipe tables", () => {
+    const html = markdownToHtml("| A | B |\n| --- | --- |\n| 1 | 2 |");
+    expect(html).toContain("<table>");
+    expect(html).toContain("<th>A</th>");
+    expect(html).toContain("<td>1</td>");
+  });
+});
+
+describe("math markdown (GitLab-flavored dollar math)", () => {
+  it("converts inline math spans to $...$", () => {
+    const md = htmlToMarkdown(
+      '<p>energy <span data-type="inline-math" data-latex="E=mc^2">E=mc^2</span> here</p>',
+    );
+    expect(md).toContain("$E=mc^2$");
+  });
+
+  it("converts math code blocks to $$ fences", () => {
+    const md = htmlToMarkdown('<pre><code class="language-math">\\frac{a}{b}</code></pre>');
+    expect(md).toContain("$$\n\\frac{a}{b}\n$$");
+  });
+
+  it("parses $...$ into inline math spans", () => {
+    const html = markdownToHtml("the mass $E=mc^2$ equation");
+    expect(html).toContain('data-type="inline-math"');
+    expect(html).toContain('data-latex="E=mc^2"');
+  });
+
+  it("parses $$ blocks (own-line and single-line) into math code blocks", () => {
+    expect(markdownToHtml("$$\n\\sqrt{x}\n$$")).toContain('<code class="language-math">');
+    expect(markdownToHtml("$$\\sqrt{x}$$")).toContain('<code class="language-math">');
+  });
+
+  it("parses ```math fences into the same math code block", () => {
+    expect(markdownToHtml("```math\n\\sqrt{x}\n```")).toContain('class="language-math"');
+  });
+
+  it("does not treat prices as math", () => {
+    const html = markdownToHtml("costs $5 and $10 total");
+    expect(html).not.toContain("inline-math");
+    expect(html).toContain("costs $5 and $10 total");
+  });
+
+  it("escapes HTML inside latex both directions", () => {
+    const html = markdownToHtml("$a<b$");
+    expect(html).toContain("a&lt;b");
+    expect(html).not.toContain("<b$");
+  });
+
+  it("round-trips inline and block math losslessly", () => {
+    const source =
+      '<p>inline <span data-type="inline-math" data-latex="x^2">x^2</span></p>' +
+      '<pre><code class="language-math">\\sum_{i=0}^n i</code></pre>';
+    const roundTripped = markdownToHtml(htmlToMarkdown(source));
+    expect(roundTripped).toContain('data-latex="x^2"');
+    expect(roundTripped).toContain('<code class="language-math">');
+    expect(roundTripped).toContain("\\sum_{i=0}^n i");
+  });
+});
+
+describe("mermaid markdown", () => {
+  it("round-trips mermaid fences losslessly", () => {
+    const source = '<pre><code class="language-mermaid">graph TD\n  A--&gt;B</code></pre>';
+    const md = htmlToMarkdown(source);
+    expect(md).toContain("```mermaid");
+    expect(md).toContain("graph TD");
+    const roundTripped = markdownToHtml(md);
+    expect(roundTripped).toContain('class="language-mermaid"');
+    expect(roundTripped).toContain("A--&gt;B");
+  });
+});
+
+describe("details markdown (collapsible sections)", () => {
+  it("keeps <details> as raw HTML (GitLab behavior) and round-trips it", () => {
+    const source =
+      "<details><summary>Click me</summary>" +
+      '<div data-type="detailsContent"><p>hidden <strong>content</strong></p></div></details>';
+    const md = htmlToMarkdown(source);
+    expect(md).toContain("<details>");
+    expect(md).toContain("<summary>Click me</summary>");
+    const roundTripped = markdownToHtml(md);
+    expect(roundTripped).toContain("<details>");
+    expect(roundTripped).toContain("<summary>Click me</summary>");
+    expect(roundTripped).toContain("<strong>content</strong>");
+  });
+});
+
+describe("round-trip (rich -> markdown -> rich)", () => {
+  it("preserves headings, lists, tasks, quotes, and inline marks", () => {
+    const source =
+      "<h2>Notes</h2>" +
+      "<p><strong>bold</strong> <em>em</em> <s>strike</s> <code>code</code> <u>under</u></p>" +
+      "<ul><li><p>one</p></li><li><p>two</p></li></ul>" +
+      '<ul data-type="taskList"><li data-type="taskItem" data-checked="true"><label><input type="checkbox" checked><span></span></label><div><p>task</p></div></li></ul>' +
+      "<blockquote><p>quote</p></blockquote>";
+    const roundTripped = markdownToHtml(htmlToMarkdown(source));
+    expect(roundTripped).toContain("<h2>Notes</h2>");
+    expect(roundTripped).toContain("<strong>bold</strong>");
+    expect(roundTripped).toContain("<em>em</em>");
+    expect(roundTripped).toContain("<del>strike</del>");
+    expect(roundTripped).toContain("<code>code</code>");
+    expect(roundTripped).toContain("<u>under</u>");
+    // Tiptap emits loose lists (<li><p>…</p></li>); either form is fine
+    expect(roundTripped).toMatch(/<li>(<p>)?one(<\/p>)?\s*<\/li>/);
+    expect(roundTripped).toContain('data-type="taskItem"');
+    expect(roundTripped).toContain('data-checked="true"');
+    expect(roundTripped).toContain("<blockquote>");
+  });
+
+  it("preserves tables through the round trip", () => {
+    const source = "<table><tr><th>H</th></tr><tr><td>cell</td></tr></table>";
+    const roundTripped = markdownToHtml(htmlToMarkdown(source));
+    expect(roundTripped).toContain("<table>");
+    expect(roundTripped).toContain("<th>H</th>");
+    expect(roundTripped).toContain("<td>cell</td>");
+  });
+});