@multiplatform.one/rich-text 6.1.0 → 6.4.0

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

package/src/editor/pasteCleanup.ts

@@ -0,0 +1,124 @@
+/**
+ * Paste sanitizer for HTML clipboard payloads from Google Docs and
+ * Microsoft Word/Outlook.
+ *
+ * Both sources wrap content in junk that either breaks ProseMirror parsing
+ * or smuggles presentation into the document:
+ * - Google Docs wraps the entire fragment in
+ *   `<b style="font-weight:normal" id="docs-internal-guid-...">` (which
+ *   ProseMirror would read as bold) and inlines font/size styles on spans.
+ * - Word ships `<o:p>` tags, `Mso*` classes, `mso-*` style declarations,
+ *   XML islands, and conditional comments.
+ *
+ * The cleanup keeps semantics (b/strong/i/em/u/lists/headings/links and
+ * color/background-color styles the editor actually supports) and drops
+ * the rest. Non-office HTML passes through untouched.
+ */
+
+const OFFICE_SIGNATURES = [
+  "docs-internal-guid",
+  "urn:schemas-microsoft-com",
+  "MsoNormal",
+  "mso-",
+  "<o:p>",
+  "office:office",
+];
+
+/** True when the clipboard HTML comes from Google Docs or Microsoft Office */
+export function isOfficeHtml(html: string): boolean {
+  return OFFICE_SIGNATURES.some((sig) => html.includes(sig));
+}
+
+/** Style declarations the editor supports (everything else is junk) */
+const KEPT_STYLES = new Set([
+  "color",
+  "background-color",
+  // Docs/Word mark bold/italic/underline/strike with span styles rather
+  // than semantic tags; ProseMirror parses these into real marks.
+  "font-weight",
+  "font-style",
+  "text-decoration",
+  "text-decoration-line",
+]);
+
+function cleanElement(el: Element): void {
+  // Word XML-namespaced elements (<o:p>, <w:sdt>, ...) contribute nothing
+  if (el.tagName.includes(":")) {
+    el.remove();
+    return;
+  }
+
+  if (el.hasAttribute("class")) el.removeAttribute("class");
+  if (el.hasAttribute("lang")) el.removeAttribute("lang");
+  if (el.hasAttribute("id")) el.removeAttribute("id");
+
+  if (el.hasAttribute("style")) {
+    // Parse the attribute text directly (not CSSStyleDeclaration) so the
+    // result is identical across browsers and DOM test environments.
+    const declarations = (el.getAttribute("style") ?? "")
+      .split(";")
+      .map((decl) => decl.trim())
+      .filter((decl) => decl.includes(":"));
+    const kept: string[] = [];
+    for (const decl of declarations) {
+      const colon = decl.indexOf(":");
+      const prop = decl.slice(0, colon).trim().toLowerCase();
+      const value = decl.slice(colon + 1).trim();
+      if (!KEPT_STYLES.has(prop)) continue;
+      // Office emits default inks explicitly; dropping them keeps content
+      // on theme text color instead of hardcoded near-black
+      if (prop === "color" && /^(rgb\(0,\s*0,\s*0\)|#000000|#000|windowtext)$/i.test(value)) {
+        continue;
+      }
+      if (
+        prop === "background-color" &&
+        /^(transparent|#ffffff|#fff|rgb\(255,\s*255,\s*255\))$/i.test(value)
+      ) {
+        continue;
+      }
+      // Non-emphasis values are the office default state, not authored marks
+      if (prop === "font-weight" && !/^(bold(er)?|[5-9]\d\d)$/i.test(value)) continue;
+      if (prop === "font-style" && !/^(italic|oblique)/i.test(value)) continue;
+      if (
+        (prop === "text-decoration" || prop === "text-decoration-line") &&
+        !/(underline|line-through)/i.test(value)
+      ) {
+        continue;
+      }
+      kept.push(`${prop}: ${value}`);
+    }
+    if (kept.length > 0) el.setAttribute("style", kept.join("; "));
+    else el.removeAttribute("style");
+  }
+
+  for (const child of Array.from(el.children)) cleanElement(child);
+}
+
+/**
+ * Sanitize office-suite clipboard HTML. Non-office HTML is returned as-is
+ * (regular web copy already parses cleanly).
+ */
+export function cleanPastedHtml(html: string): string {
+  if (typeof document === "undefined" || !isOfficeHtml(html)) return html;
+
+  // Strip XML islands and conditional comments before parsing
+  const source = html
+    .replace(/<xml>[\s\S]*?<\/xml>/gi, "")
+    .replace(/<!--\[if[\s\S]*?<!\[endif\]-->/gi, "")
+    .replace(/<!--StartFragment-->|<!--EndFragment-->/gi, "");
+
+  const doc = new DOMParser().parseFromString(source, "text/html");
+  doc.querySelectorAll("style, meta, link, script, title").forEach((el) => el.remove());
+
+  // Google Docs: unwrap the non-bold <b> guid wrapper so content is not bold
+  for (const b of Array.from(doc.body.querySelectorAll("b"))) {
+    const weight = (b as HTMLElement).style.fontWeight;
+    if (weight === "normal" || weight === "400") {
+      b.replaceWith(...Array.from(b.childNodes));
+    }
+  }
+
+  for (const child of Array.from(doc.body.children)) cleanElement(child);
+
+  return doc.body.innerHTML;
+}

package/src/editor/suggestionPopup.spec.tsx

@@ -0,0 +1,105 @@
+import { describe, expect, it, vi } from "vitest";
+import { act, createRef } from "react";
+import { render } from "@testing-library/react";
+import {
+  SuggestionList,
+  fallbackSuggestionChrome,
+  getSuggestionChrome,
+  type SuggestionListRef,
+  type SuggestionRow,
+} from "./suggestionPopup";
+
+const rows: SuggestionRow[] = [
+  { key: "a", title: "Alpha", description: "first" },
+  { key: "b", title: "Beta", description: "second" },
+  { key: "c", title: "Gamma", description: "third" },
+];
+
+const chrome = { ...fallbackSuggestionChrome, rowPaddingX: 12 };
+
+function renderList(onSelect = vi.fn()) {
+  const ref = createRef<SuggestionListRef>();
+  const utils = render(
+    <SuggestionList
+      ref={ref}
+      rows={rows}
+      chrome={chrome}
+      emptyLabel="No results"
+      onSelect={onSelect}
+    />,
+  );
+  return { ref, onSelect, ...utils };
+}
+
+describe("SuggestionList", () => {
+  it("renders one option per row with LC-16 menu-row geometry", () => {
+    const { container } = renderList();
+    const options = container.querySelectorAll('[role="option"]');
+    expect(options.length).toBe(3);
+    const style = (options[0] as HTMLElement).style;
+    // menuRowFrame-derived horizontal padding, flat corners, full width
+    expect(style.padding).toBe("8px 12px");
+    expect(style.borderRadius).toBe("0px");
+    expect(style.width).toBe("100%");
+  });
+
+  it("marks the first row selected and navigates with arrows (wrapping)", () => {
+    const { ref, container } = renderList();
+    const selected = () =>
+      Array.from(container.querySelectorAll('[role="option"]')).findIndex(
+        (el) => el.getAttribute("aria-selected") === "true",
+      );
+    expect(selected()).toBe(0);
+    act(() => {
+      ref.current!.onKeyDown({ event: new KeyboardEvent("keydown", { key: "ArrowDown" }) });
+    });
+    expect(selected()).toBe(1);
+    act(() => {
+      ref.current!.onKeyDown({ event: new KeyboardEvent("keydown", { key: "ArrowUp" }) });
+      ref.current!.onKeyDown({ event: new KeyboardEvent("keydown", { key: "ArrowUp" }) });
+    });
+    expect(selected()).toBe(2);
+  });
+
+  it("selects with Enter and Tab", () => {
+    const { ref, onSelect } = renderList();
+    act(() => {
+      ref.current!.onKeyDown({ event: new KeyboardEvent("keydown", { key: "ArrowDown" }) });
+    });
+    let handled = false;
+    act(() => {
+      handled = ref.current!.onKeyDown({
+        event: new KeyboardEvent("keydown", { key: "Enter" }),
+      });
+    });
+    expect(handled).toBe(true);
+    expect(onSelect).toHaveBeenCalledWith(1);
+  });
+
+  it("selects on click", () => {
+    const { container, onSelect } = renderList();
+    const options = container.querySelectorAll('[role="option"]');
+    (options[2] as HTMLElement).click();
+    expect(onSelect).toHaveBeenCalledWith(2);
+  });
+
+  it("shows the empty label when there are no rows", () => {
+    const { container } = render(
+      <SuggestionList rows={[]} chrome={chrome} emptyLabel="No results" onSelect={vi.fn()} />,
+    );
+    expect(container.textContent).toContain("No results");
+    expect(container.querySelectorAll('[role="option"]').length).toBe(0);
+  });
+});
+
+describe("getSuggestionChrome", () => {
+  it("reads the chrome pushed by the editor host", () => {
+    const editor = { storage: { suggestionChrome: { value: chrome } } };
+    expect(getSuggestionChrome(editor)).toBe(chrome);
+  });
+
+  it("falls back to the neutral chrome before the host pushes values", () => {
+    expect(getSuggestionChrome(null)).toBe(fallbackSuggestionChrome);
+    expect(getSuggestionChrome({ storage: {} })).toBe(fallbackSuggestionChrome);
+  });
+});