@multiplatform.one/rich-text 6.1.0 → 6.3.0

package/src/editor/mathematics.ts

@@ -0,0 +1,179 @@
+/**
+ * Inline math node (`$x^2$`) rendered with lazy-loaded KaTeX — GitLab
+ * parity for dollar math in the rich text editor.
+ *
+ * - Typing `$latex$` converts to a rendered formula (input rule; prices
+ *   like "$5 and $10" never convert — content cannot start/end with
+ *   whitespace).
+ * - The node is an inline atom carrying the raw TeX in `data-latex`; the
+ *   MathBubble edits it in place (updateInlineMath command).
+ * - Invalid TeX shows the raw source in an error style with the KaTeX
+ *   parse message (Axiom 6: show the error, never blank).
+ * - Block math (`$$ ... $$`) is a code block with language "math" — see
+ *   codeBlockPreview.ts — matching GitLab's ```math fence model.
+ *
+ * Serialization: `<span data-type="inline-math" data-latex="...">` <->
+ * `$...$` (editor/markdown.ts), so the source toggle is lossless.
+ */
+
+import { Node, mergeAttributes, nodeInputRule } from "@tiptap/core";
+import { NodeSelection } from "@tiptap/pm/state";
+import { t } from "../shared/t";
+import { mountKatexHtml, renderKatexHtml } from "./lazyKatex";
+
+export interface InlineMathOptions {
+  HTMLAttributes: Record<string, any>;
+}
+
+declare module "@tiptap/core" {
+  interface Commands<ReturnType> {
+    inlineMath: {
+      /** Inserts an inline math node and selects it (opens the MathBubble) */
+      insertInlineMath: (attributes?: { latex?: string }) => ReturnType;
+      /** Updates the latex of the selected inline math node */
+      updateInlineMath: (attributes: { latex: string }) => ReturnType;
+    };
+  }
+}
+
+/**
+ * Matches `$...$` as the last thing typed. match[1] is the dollar span
+ * (what the node replaces), match[2] the TeX. The character before the
+ * opening `$` must not be another `$` (that is block math), and content
+ * cannot start/end with whitespace or contain `$`/newlines.
+ */
+export const INLINE_MATH_INPUT_RULE = /(?:^|[^$])(\$([^$\n \t](?:[^$\n]*[^$\n \t])?)\$)$/;
+
+export const InlineMath = Node.create<InlineMathOptions>({
+  name: "inlineMath",
+  inline: true,
+  group: "inline",
+  atom: true,
+  marks: "",
+
+  addOptions() {
+    return { HTMLAttributes: {} };
+  },
+
+  addAttributes() {
+    return {
+      latex: {
+        default: "",
+        parseHTML: (element) => element.getAttribute("data-latex") ?? element.textContent ?? "",
+        renderHTML: (attributes) => ({ "data-latex": attributes.latex }),
+      },
+    };
+  },
+
+  parseHTML() {
+    return [{ tag: 'span[data-type="inline-math"]' }];
+  },
+
+  renderHTML({ node, HTMLAttributes }) {
+    // raw TeX as text content: non-web surfaces (native preview, plain
+    // parsers) degrade to readable source
+    return [
+      "span",
+      mergeAttributes({ "data-type": "inline-math" }, this.options.HTMLAttributes, HTMLAttributes),
+      node.attrs.latex,
+    ];
+  },
+
+  addCommands() {
+    return {
+      insertInlineMath:
+        (attributes) =>
+        ({ tr, dispatch }) => {
+          if (dispatch) {
+            const pos = tr.selection.from;
+            tr.replaceSelectionWith(this.type.create({ latex: attributes?.latex ?? "" }), false);
+            tr.setSelection(NodeSelection.create(tr.doc, pos));
+            tr.scrollIntoView();
+          }
+          return true;
+        },
+      updateInlineMath:
+        (attributes) =>
+        ({ tr, dispatch }) => {
+          const { selection } = tr;
+          if (!(selection instanceof NodeSelection) || selection.node.type !== this.type) {
+            return false;
+          }
+          if (dispatch) {
+            const pos = selection.from;
+            tr.setNodeMarkup(pos, undefined, { latex: attributes.latex });
+            tr.setSelection(NodeSelection.create(tr.doc, pos));
+          }
+          return true;
+        },
+    };
+  },
+
+  addInputRules() {
+    return [
+      nodeInputRule({
+        find: INLINE_MATH_INPUT_RULE,
+        type: this.type,
+        getAttributes: (match) => ({ latex: match[2] ?? "" }),
+      }),
+    ];
+  },
+
+  addNodeView() {
+    return ({ node }) => {
+      const dom = document.createElement("span");
+      dom.className = "rt-math-inline";
+      dom.setAttribute("data-type", "inline-math");
+      dom.contentEditable = "false";
+
+      let currentLatex: string | null = null;
+      let destroyed = false;
+
+      const render = (latex: string) => {
+        if (destroyed || latex === currentLatex) return;
+        currentLatex = latex;
+        dom.setAttribute("data-latex", latex);
+        if (!latex.trim()) {
+          dom.classList.add("rt-math-empty");
+          dom.classList.remove("rt-math-error");
+          dom.removeAttribute("title");
+          dom.textContent = t("math");
+          return;
+        }
+        dom.classList.remove("rt-math-empty");
+        // raw TeX stays visible while KaTeX loads (first render only)
+        dom.textContent = latex;
+        void renderKatexHtml(latex).then((result) => {
+          if (destroyed || currentLatex !== latex) return;
+          if (result.ok) {
+            mountKatexHtml(dom, result.html);
+            dom.classList.remove("rt-math-error");
+            dom.removeAttribute("title");
+            dom.setAttribute("role", "img");
+            dom.setAttribute("aria-label", latex);
+          } else {
+            // Axiom 6: raw source + parse message, never a blank chip
+            dom.textContent = latex;
+            dom.classList.add("rt-math-error");
+            dom.title = result.error;
+          }
+        });
+      };
+
+      render((node.attrs.latex as string) ?? "");
+
+      return {
+        dom,
+        update: (updatedNode) => {
+          if (updatedNode.type.name !== "inlineMath") return false;
+          render((updatedNode.attrs.latex as string) ?? "");
+          return true;
+        },
+        ignoreMutation: () => true,
+        destroy: () => {
+          destroyed = true;
+        },
+      };
+    };
+  },
+});

package/src/editor/media.spec.ts

@@ -0,0 +1,121 @@
+/**
+ * Media paste/drop upload behavior against a headless Tiptap editor.
+ */
+
+import { describe, expect, it, vi } from "vitest";
+import { Editor } from "@tiptap/core";
+import StarterKit from "@tiptap/starter-kit";
+import Image from "@tiptap/extension-image";
+import { MediaUpload } from "./media";
+
+function createEditor() {
+  return new Editor({
+    element: document.createElement("div"),
+    extensions: [StarterKit, Image.configure({ inline: true, allowBase64: true }), MediaUpload],
+    content: "<p>start</p>",
+  });
+}
+
+function firePaste(editor: Editor, files: File[]) {
+  const event = {
+    clipboardData: { files, types: ["Files"], getData: () => "" },
+    preventDefault: vi.fn(),
+  } as unknown as ClipboardEvent;
+  // someProp mirrors ProseMirror dispatch: handlers run in order until one
+  // claims the event by returning truthy
+  const handled = !!editor.view.someProp("handlePaste", (fn) =>
+    fn(editor.view, event, editor.state.tr.doc.slice(0)),
+  );
+  return { handled, event };
+}
+
+async function waitFor(check: () => boolean, timeoutMs = 2000) {
+  const start = Date.now();
+  while (!check()) {
+    if (Date.now() - start > timeoutMs) throw new Error("waitFor timed out");
+    await new Promise((r) => setTimeout(r, 10));
+  }
+}
+
+describe("MediaUpload", () => {
+  it("inserts an uploaded image URL when onImageUpload is wired", async () => {
+    const editor = createEditor();
+    const onImageUpload = vi.fn(async () => "https://cdn.example.com/pic.png");
+    editor.storage.mediaUpload.handlers = { onImageUpload };
+
+    const file = new File(["binary"], "pic.png", { type: "image/png" });
+    const { handled, event } = firePaste(editor, [file]);
+
+    expect(handled).toBe(true);
+    expect(event.preventDefault).toHaveBeenCalled();
+    await waitFor(() => editor.getHTML().includes("<img"));
+    expect(onImageUpload).toHaveBeenCalledWith(file);
+    expect(editor.getHTML()).toContain('src="https://cdn.example.com/pic.png"');
+    expect(editor.getHTML()).toContain('alt="pic"');
+    editor.destroy();
+  });
+
+  it("falls back to base64 data URI without an image handler", async () => {
+    const editor = createEditor();
+    const file = new File(["binary"], "photo.jpg", { type: "image/jpeg" });
+    const { handled } = firePaste(editor, [file]);
+
+    expect(handled).toBe(true);
+    await waitFor(() => editor.getHTML().includes("<img"));
+    expect(editor.getHTML()).toContain('src="data:');
+    editor.destroy();
+  });
+
+  it("inserts an attachment chip link for non-image files via onFileUpload", async () => {
+    const editor = createEditor();
+    const onFileUpload = vi.fn(async () => ({
+      url: "https://cdn.example.com/report.pdf",
+      name: "report.pdf",
+    }));
+    editor.storage.mediaUpload.handlers = { onFileUpload };
+
+    const file = new File(["%PDF"], "report.pdf", { type: "application/pdf" });
+    const { handled } = firePaste(editor, [file]);
+
+    expect(handled).toBe(true);
+    await waitFor(() => editor.getHTML().includes("<a"));
+    const html = editor.getHTML();
+    expect(html).toContain('href="https://cdn.example.com/report.pdf"');
+    expect(html).toContain("rt-attachment");
+    expect(html).toContain("report.pdf");
+    editor.destroy();
+  });
+
+  it("ignores non-image files without a file handler (honest no-op)", () => {
+    const editor = createEditor();
+    const file = new File(["%PDF"], "report.pdf", { type: "application/pdf" });
+    const { handled } = firePaste(editor, [file]);
+    expect(handled).toBe(false);
+    expect(editor.getHTML()).not.toContain("<a");
+    editor.destroy();
+  });
+
+  it("does not intercept text-only pastes", () => {
+    const editor = createEditor();
+    const { handled } = firePaste(editor, []);
+    expect(handled).toBeFalsy();
+    editor.destroy();
+  });
+
+  it("survives a failing upload without crashing", async () => {
+    const editor = createEditor();
+    const onImageUpload = vi.fn(async () => {
+      throw new Error("upload broke");
+    });
+    editor.storage.mediaUpload.handlers = { onImageUpload };
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    const file = new File(["binary"], "pic.png", { type: "image/png" });
+    const { handled } = firePaste(editor, [file]);
+    expect(handled).toBe(true);
+    await waitFor(() => warn.mock.calls.length > 0);
+    expect(editor.getHTML()).not.toContain("<img");
+    warn.mockRestore();
+    editor.destroy();
+  });
+});

package/src/editor/media.ts

@@ -0,0 +1,133 @@
+/**
+ * Image / attachment paste-and-drop handling (web).
+ *
+ * Files pasted or dropped into the editor route through prop-driven upload
+ * hooks -- the package assumes no backend:
+ * - Images: `onImageUpload(file) -> Promise<url>` inserts an image node at
+ *   the paste/drop position. Without a hook, images fall back to an inline
+ *   base64 data URI so the flow still works in demos and offline hosts.
+ * - Other files: `onFileUpload(file) -> Promise<{ url, name? }>` inserts an
+ *   attachment chip (a link with `data-attachment`). Without a hook there is
+ *   no URL to link, so the file is ignored (honest no-op).
+ */
+
+import { Extension } from "@tiptap/core";
+import type { Editor } from "@tiptap/core";
+import { Plugin, PluginKey } from "@tiptap/pm/state";
+
+export interface MediaUploadHandlers {
+  /** Uploads a pasted/dropped image and resolves its URL */
+  onImageUpload?: (file: File) => Promise<string>;
+  /** Uploads a pasted/dropped non-image file and resolves its URL (+ display name) */
+  onFileUpload?: (file: File) => Promise<{ url: string; name?: string }>;
+}
+
+export interface MediaUploadStorage {
+  handlers: MediaUploadHandlers;
+}
+
+declare module "@tiptap/core" {
+  interface Storage {
+    mediaUpload: MediaUploadStorage;
+  }
+}
+
+function readFileAsDataUrl(file: File): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(String(reader.result));
+    reader.onerror = () => reject(reader.error);
+    reader.readAsDataURL(file);
+  });
+}
+
+function insertImage(editor: Editor, src: string, alt: string, pos?: number) {
+  const chain = editor.chain().focus();
+  if (pos !== undefined) {
+    chain.insertContentAt(pos, { type: "image", attrs: { src, alt } }).run();
+  } else {
+    chain.setImage({ src, alt }).run();
+  }
+}
+
+function insertAttachment(editor: Editor, url: string, name: string, pos?: number) {
+  const content = {
+    type: "text",
+    text: name,
+    marks: [
+      {
+        type: "link",
+        // the Link mark schema only allows href/target/rel/class -- the
+        // chip presentation rides on the class
+        attrs: { href: url, class: "rt-attachment" },
+      },
+    ],
+  };
+  const chain = editor.chain().focus();
+  if (pos !== undefined) chain.insertContentAt(pos, content).run();
+  else chain.insertContent(content).run();
+}
+
+async function handleFiles(editor: Editor, files: File[], pos?: number): Promise<void> {
+  const { handlers } = editor.storage.mediaUpload as MediaUploadStorage;
+  for (const file of files) {
+    try {
+      if (file.type.startsWith("image/")) {
+        const src = handlers.onImageUpload
+          ? await handlers.onImageUpload(file)
+          : await readFileAsDataUrl(file);
+        insertImage(editor, src, file.name.replace(/\.[a-z0-9]+$/i, ""), pos);
+      } else if (handlers.onFileUpload) {
+        const { url, name } = await handlers.onFileUpload(file);
+        insertAttachment(editor, url, name ?? file.name, pos);
+      }
+    } catch (err) {
+      console.warn("[rich-text] media upload failed:", err);
+    }
+  }
+}
+
+export const MediaUpload = Extension.create({
+  name: "mediaUpload",
+
+  addStorage(): MediaUploadStorage {
+    return { handlers: {} };
+  },
+
+  addProseMirrorPlugins() {
+    const { editor } = this;
+
+    return [
+      new Plugin({
+        key: new PluginKey("mediaUpload"),
+        props: {
+          handlePaste(_view, event) {
+            const files = Array.from(event.clipboardData?.files ?? []);
+            if (files.length === 0) return false;
+            const { handlers } = editor.storage.mediaUpload as MediaUploadStorage;
+            const actionable = files.some(
+              (f) => f.type.startsWith("image/") || handlers.onFileUpload,
+            );
+            if (!actionable) return false;
+            event.preventDefault();
+            void handleFiles(editor, files);
+            return true;
+          },
+          handleDrop(view, event) {
+            const files = Array.from(event.dataTransfer?.files ?? []);
+            if (files.length === 0) return false;
+            const { handlers } = editor.storage.mediaUpload as MediaUploadStorage;
+            const actionable = files.some(
+              (f) => f.type.startsWith("image/") || handlers.onFileUpload,
+            );
+            if (!actionable) return false;
+            event.preventDefault();
+            const coords = view.posAtCoords({ left: event.clientX, top: event.clientY });
+            void handleFiles(editor, files, coords?.pos);
+            return true;
+          },
+        },
+      }),
+    ];
+  },
+});

package/src/editor/mentions.spec.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import { createMentionExtension } from "./mentions";
+
+describe("createMentionExtension", () => {
+  it("creates a mention extension with @ as the default trigger", () => {
+    const ext = createMentionExtension({ items: () => [] });
+    expect(ext.name).toBe("mention");
+    expect(ext.options.suggestion.char).toBe("@");
+  });
+
+  it("honors a custom trigger", () => {
+    const ext = createMentionExtension({ trigger: "#", items: () => [] });
+    expect(ext.options.suggestion.char).toBe("#");
+  });
+
+  it("maps the forms MentionItem contract (display -> label) and caps at 20", async () => {
+    const data = Array.from({ length: 30 }, (_, i) => ({
+      id: `u${i}`,
+      display: `User ${i}`,
+      description: `Role ${i}`,
+      avatar: `https://a.b/${i}.png`,
+    }));
+    const ext = createMentionExtension({ items: () => data });
+    const items = await ext.options.suggestion.items!({ query: "", editor: null as any });
+    expect(items).toHaveLength(20);
+    expect(items[0]).toEqual({
+      id: "u0",
+      label: "User 0",
+      description: "Role 0",
+      avatar: "https://a.b/0.png",
+    });
+  });
+
+  it("supports async item sources", async () => {
+    const ext = createMentionExtension({
+      items: async (query) => [{ id: "1", display: `match:${query}` }],
+    });
+    const items = await ext.options.suggestion.items!({ query: "ada", editor: null as any });
+    expect(items[0]!.label).toBe("match:ada");
+  });
+});

package/src/editor/mentions.ts

@@ -0,0 +1,55 @@
+/**
+ * @ mention support for the rich text editor (web).
+ *
+ * Reuses the forms `MentionItem` contract (LC-16: same suggestion data
+ * shape as `MentionInput`) and the shared suggestion popup (same rows,
+ * chrome, and keyboard handling as the slash menu). The host wires data via
+ * the `mentions` prop -- the package assumes no backend.
+ *
+ * Inserted mentions are Tiptap mention nodes rendered as
+ * `<span data-type="mention" data-id="...">@label</span>` chips.
+ */
+
+import Mention from "@tiptap/extension-mention";
+import type { RichTextMentionOptions } from "../types";
+import { t } from "../shared/t";
+import { createSuggestionRenderer, getSuggestionChrome } from "./suggestionPopup";
+
+export type { RichTextMentionOptions };
+
+/** Internal suggestion payload: Mention's default command reads id + label */
+interface MentionSuggestionItem {
+  id: string;
+  label: string;
+  description?: string;
+  avatar?: string;
+}
+
+export function createMentionExtension(options: RichTextMentionOptions) {
+  return Mention.configure({
+    HTMLAttributes: { class: "rt-mention" },
+    deleteTriggerWithBackspace: true,
+    suggestion: {
+      char: options.trigger ?? "@",
+      items: async ({ query }: { query: string }): Promise<MentionSuggestionItem[]> => {
+        const items = await options.items(query);
+        return items.slice(0, 20).map((item) => ({
+          id: item.id,
+          label: item.display,
+          description: item.description,
+          avatar: item.avatar,
+        }));
+      },
+      render: createSuggestionRenderer<MentionSuggestionItem>({
+        toRow: (item) => ({
+          key: item.id,
+          title: item.label,
+          description: item.description,
+          avatarUrl: item.avatar,
+        }),
+        getChrome: getSuggestionChrome,
+        getEmptyLabel: () => t("No results"),
+      }),
+    },
+  });
+}

package/src/editor/pasteCleanup.spec.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from "vitest";
+import { cleanPastedHtml, isOfficeHtml } from "./pasteCleanup";
+
+const GOOGLE_DOCS_HTML =
+  '<meta charset="utf-8"><b style="font-weight:normal;" id="docs-internal-guid-abc123">' +
+  '<p dir="ltr" style="line-height:1.38;margin-top:0pt;margin-bottom:0pt;">' +
+  '<span style="font-size:11pt;font-family:Arial;color:#000000;background-color:transparent;' +
+  'font-weight:400;font-style:normal;">Hello from Docs</span></p>' +
+  '<p dir="ltr"><span style="font-weight:700;color:#ff0000;">Red bold</span></p></b>';
+
+const WORD_HTML =
+  "<html xmlns:o='urn:schemas-microsoft-com:office:office'><body>" +
+  "<!--[if gte mso 9]><xml><o:shapedefaults/></xml><![endif]-->" +
+  '<p class="MsoNormal" style="mso-margin-top-alt:auto;color:windowtext;">Hello from Word<o:p></o:p></p>' +
+  "</body></html>";
+
+describe("isOfficeHtml", () => {
+  it("detects Google Docs clipboard payloads", () => {
+    expect(isOfficeHtml(GOOGLE_DOCS_HTML)).toBe(true);
+  });
+
+  it("detects Microsoft Word clipboard payloads", () => {
+    expect(isOfficeHtml(WORD_HTML)).toBe(true);
+  });
+
+  it("returns false for regular web HTML", () => {
+    expect(isOfficeHtml("<p><strong>plain</strong> web copy</p>")).toBe(false);
+  });
+});
+
+describe("cleanPastedHtml", () => {
+  it("passes non-office HTML through untouched", () => {
+    const html = '<p class="keep-me"><strong>web</strong></p>';
+    expect(cleanPastedHtml(html)).toBe(html);
+  });
+
+  it("unwraps the Google Docs non-bold <b> guid wrapper", () => {
+    const cleaned = cleanPastedHtml(GOOGLE_DOCS_HTML);
+    // The wrapper <b> is gone so content does not become bold
+    expect(cleaned).not.toContain("docs-internal-guid");
+    expect(cleaned).not.toMatch(/<b[\s>]/);
+    expect(cleaned).toContain("Hello from Docs");
+  });
+
+  it("drops font junk but keeps meaningful colors", () => {
+    const cleaned = cleanPastedHtml(GOOGLE_DOCS_HTML);
+    expect(cleaned).not.toContain("font-family");
+    expect(cleaned).not.toContain("font-size");
+    // Default black ink is dropped (stays on theme text color)
+    expect(cleaned).not.toContain("#000000");
+    // Explicit non-default color survives as data (authored hex preserved)
+    expect(cleaned).toContain("color: #ff0000");
+  });
+
+  it("keeps span-styled bold (Docs marks bold with font-weight, not <b>)", () => {
+    const cleaned = cleanPastedHtml(GOOGLE_DOCS_HTML);
+    // Authored bold survives so ProseMirror parses it into a bold mark
+    expect(cleaned).toContain("font-weight: 700");
+    // The default-weight span (font-weight:400) carries no mark
+    expect(cleaned).not.toContain("font-weight: 400");
+    expect(cleaned).not.toContain("font-style: normal");
+  });
+
+  it("keeps span-styled italic/underline/strike, drops default values", () => {
+    const html =
+      '<p class="MsoNormal">' +
+      '<span style="font-style:italic;">it</span>' +
+      '<span style="text-decoration:underline;">un</span>' +
+      '<span style="text-decoration:none;">plain</span></p>';
+    const cleaned = cleanPastedHtml(html);
+    expect(cleaned).toContain("font-style: italic");
+    expect(cleaned).toContain("text-decoration: underline");
+    expect(cleaned).not.toContain("text-decoration: none");
+  });
+
+  it("strips Word Mso classes, o:p tags, and conditional comments", () => {
+    const cleaned = cleanPastedHtml(WORD_HTML);
+    expect(cleaned).not.toContain("MsoNormal");
+    expect(cleaned).not.toContain("mso-");
+    expect(cleaned).not.toContain("<o:p>");
+    expect(cleaned).not.toContain("[if gte mso");
+    expect(cleaned).toContain("Hello from Word");
+  });
+});