@multiplatform.one/rich-text 6.1.0 → 6.3.0

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

package/src/editor/suggestionPopup.tsx

@@ -0,0 +1,414 @@
+/**
+ * Shared suggestion popup for editor typeahead menus (slash commands and
+ * @ mentions).
+ *
+ * One implementation (LC-16): both menus render the same row anatomy with
+ * the shared menu-row geometry (SP-EDGE -- the container owns only its
+ * border, rows own all padding and span edge-to-edge, matching
+ * SelectRow / DropdownMenuItemFrame / MentionSuggestionItem: 12px
+ * horizontal x 8px vertical padding, 8px in-row gap, flat corners).
+ *
+ * The popup is portaled to document.body (it must escape the editor frame
+ * and the fullscreen z-index), which puts it OUTSIDE the Tamagui theme
+ * scope -- so no Tamagui components and no raw CSS fallbacks. Every color
+ * and structural role comes from `SuggestionChrome`, resolved from the
+ * live theme + knobs by the editor and pushed through editor storage.
+ * Enter/exit motion (LC-24) fades through `motionMs`, which is 0 when the
+ * animation knob is "none".
+ */
+
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ReactNode,
+} from "react";
+import { Extension } from "@tiptap/core";
+import { ReactRenderer } from "@tiptap/react";
+
+// ===========================================================================
+// Chrome (resolved theme + knob values, no raw fallbacks)
+// ===========================================================================
+
+export interface SuggestionChrome {
+  /** Panel surface color (theme background) */
+  background: string;
+  /** Panel border color */
+  borderColor: string;
+  /** Row highlight surface (active/hover) */
+  activeBackground: string;
+  /** Leading icon tile surface */
+  iconTileBackground: string;
+  /** Primary row text color */
+  titleColor: string;
+  /** Secondary row text color */
+  descriptionColor: string;
+  /** Panel corner radius in px */
+  radius: number;
+  /** Shared floating-panel shadow (Axiom 14/15 light source) */
+  shadow: string;
+  /** Enter/exit fade duration in ms (0 = animation none) */
+  motionMs: number;
+  /**
+   * Row horizontal padding in px, resolved from the shared LC-16
+   * `menuRowFrame` recipe (theme) by the editor host — the DOM popup never
+   * invents its own geometry.
+   */
+  rowPaddingX: number;
+}
+
+/**
+ * Chrome used only when the editor has not pushed resolved values yet
+ * (first paint edge — a popup cannot open before the host's push effect
+ * runs). Colors reference the tamagui `:root` default-theme custom
+ * properties rather than literal values, so even this edge stays sourced
+ * from the theme system (Axiom 5).
+ */
+export const fallbackSuggestionChrome: SuggestionChrome = {
+  background: "var(--background)",
+  borderColor: "var(--borderColor)",
+  activeBackground: "var(--color4)",
+  iconTileBackground: "var(--color3)",
+  titleColor: "var(--color12)",
+  descriptionColor: "var(--color11)",
+  radius: 8,
+  shadow: "0px 8px 28px var(--shadow2), 0px 2px 6px var(--shadow1)",
+  motionMs: 120,
+  rowPaddingX: 12,
+};
+
+declare module "@tiptap/core" {
+  interface Storage {
+    suggestionChrome: { value: SuggestionChrome };
+  }
+}
+
+/**
+ * Storage-only extension carrying the resolved suggestion chrome. The
+ * editor host (TiptapEditor) resolves theme + knob values in React land and
+ * pushes them here so the DOM-portaled popups never invent their own colors.
+ */
+export const SuggestionChromeStore = Extension.create({
+  name: "suggestionChrome",
+  addStorage(): { value: SuggestionChrome } {
+    return { value: fallbackSuggestionChrome };
+  },
+});
+
+/** Reads the resolved chrome pushed by the editor host */
+export function getSuggestionChrome(editor: any): SuggestionChrome {
+  return editor?.storage?.suggestionChrome?.value ?? fallbackSuggestionChrome;
+}
+
+// ===========================================================================
+// Rows
+// ===========================================================================
+
+export interface SuggestionRow {
+  key: string;
+  title: string;
+  description?: string;
+  /** Leading glyph rendered inside the icon tile */
+  icon?: ReactNode;
+  /** Avatar image URL (mentions); takes the icon tile slot */
+  avatarUrl?: string;
+}
+
+export interface SuggestionListProps {
+  rows: SuggestionRow[];
+  chrome: SuggestionChrome;
+  emptyLabel: string;
+  onSelect: (index: number) => void;
+}
+
+export interface SuggestionListRef {
+  onKeyDown: (props: { event: KeyboardEvent }) => boolean;
+}
+
+export const SuggestionList = forwardRef<SuggestionListRef, SuggestionListProps>(
+  ({ rows, chrome, emptyLabel, onSelect }, ref) => {
+    const [selectedIndex, setSelectedIndex] = useState(0);
+    const listRef = useRef<HTMLDivElement>(null);
+
+    useEffect(() => {
+      setSelectedIndex(0);
+    }, [rows]);
+
+    useEffect(() => {
+      const el = listRef.current?.children[selectedIndex] as HTMLElement | undefined;
+      el?.scrollIntoView({ block: "nearest" });
+    }, [selectedIndex]);
+
+    const selectItem = useCallback(
+      (index: number) => {
+        if (rows[index]) onSelect(index);
+      },
+      [rows, onSelect],
+    );
+
+    useImperativeHandle(ref, () => ({
+      onKeyDown: ({ event }: { event: KeyboardEvent }) => {
+        if (rows.length === 0) return false;
+        if (event.key === "ArrowUp") {
+          setSelectedIndex((i) => (i + rows.length - 1) % rows.length);
+          return true;
+        }
+        if (event.key === "ArrowDown") {
+          setSelectedIndex((i) => (i + 1) % rows.length);
+          return true;
+        }
+        if (event.key === "Enter" || event.key === "Tab") {
+          selectItem(selectedIndex);
+          return true;
+        }
+        return false;
+      },
+    }));
+
+    const containerStyle: CSSProperties = {
+      background: chrome.background,
+      border: `1px solid ${chrome.borderColor}`,
+      borderRadius: `${chrome.radius}px`,
+      boxShadow: chrome.shadow,
+      // SP-EDGE: container owns only its border -- rows own all padding
+      padding: 0,
+      maxHeight: "320px",
+      overflowY: "auto",
+      minWidth: "220px",
+      maxWidth: "320px",
+    };
+
+    if (rows.length === 0) {
+      return (
+        <div style={containerStyle} data-suggestion-popup="true">
+          <div
+            style={{
+              padding: `8px ${chrome.rowPaddingX}px`,
+              color: chrome.descriptionColor,
+              fontSize: "13px",
+            }}
+          >
+            {emptyLabel}
+          </div>
+        </div>
+      );
+    }
+
+    return (
+      <div style={containerStyle} ref={listRef} role="listbox" data-suggestion-popup="true">
+        {rows.map((row, index) => (
+          <button
+            key={row.key}
+            role="option"
+            aria-selected={index === selectedIndex}
+            type="button"
+            style={{
+              // LC-16 shared menu-row geometry (menuRowFrame): horizontal
+              // padding resolved from the theme recipe, 8px vertical, 8px
+              // in-row gap, full-width flat rows (SP-EDGE)
+              display: "flex",
+              alignItems: "center",
+              gap: "8px",
+              padding: `8px ${chrome.rowPaddingX}px`,
+              border: "none",
+              background: index === selectedIndex ? chrome.activeBackground : "none",
+              width: "100%",
+              textAlign: "start",
+              cursor: "pointer",
+              borderRadius: 0,
+              fontSize: "13px",
+              lineHeight: "1.3",
+              fontFamily: "inherit",
+            }}
+            onClick={() => selectItem(index)}
+            onMouseEnter={() => setSelectedIndex(index)}
+          >
+            {row.avatarUrl ? (
+              <img
+                src={row.avatarUrl}
+                alt=""
+                style={{
+                  width: "24px",
+                  height: "24px",
+                  borderRadius: "50%",
+                  flexShrink: 0,
+                  objectFit: "cover",
+                }}
+              />
+            ) : row.icon !== undefined && row.icon !== null ? (
+              <span
+                aria-hidden="true"
+                style={{
+                  width: "28px",
+                  height: "28px",
+                  display: "flex",
+                  alignItems: "center",
+                  justifyContent: "center",
+                  borderRadius: "4px",
+                  background: chrome.iconTileBackground,
+                  color: chrome.titleColor,
+                  fontWeight: 700,
+                  fontSize: "12px",
+                  flexShrink: 0,
+                }}
+              >
+                {row.icon}
+              </span>
+            ) : null}
+            <span style={{ display: "flex", flexDirection: "column", gap: "1px", minWidth: 0 }}>
+              <span
+                style={{
+                  fontWeight: 600,
+                  color: chrome.titleColor,
+                  whiteSpace: "nowrap",
+                  overflow: "hidden",
+                  textOverflow: "ellipsis",
+                }}
+              >
+                {row.title}
+              </span>
+              {row.description ? (
+                <span style={{ fontSize: "11px", color: chrome.descriptionColor }}>
+                  {row.description}
+                </span>
+              ) : null}
+            </span>
+          </button>
+        ))}
+      </div>
+    );
+  },
+);
+
+SuggestionList.displayName = "SuggestionList";
+
+// ===========================================================================
+// Popup lifecycle (shared tiptap suggestion render())
+// ===========================================================================
+
+interface PopupHandle {
+  element: HTMLDivElement;
+  destroy: (immediate?: boolean) => void;
+  position: (clientRect?: (() => DOMRect | null) | null) => void;
+}
+
+function createPopup(editorDom: HTMLElement, motionMs: number): PopupHandle {
+  const popup = document.createElement("div");
+  popup.style.position = "fixed";
+  // above the fullscreen editor frame (zIndex 100000), which the
+  // body-portaled popup would otherwise render underneath
+  popup.style.zIndex = "100001";
+  // Portal lives on document.body, outside the app font scope; inherit the
+  // editor's computed font so the menu matches the app
+  popup.style.fontFamily = getComputedStyle(editorDom).fontFamily;
+  if (motionMs > 0) {
+    popup.style.opacity = "0";
+    popup.style.transform = "translateY(4px)";
+    popup.style.transition = `opacity ${motionMs}ms ease, transform ${motionMs}ms ease`;
+    requestAnimationFrame(() => {
+      popup.style.opacity = "1";
+      popup.style.transform = "translateY(0)";
+    });
+  }
+  document.body.appendChild(popup);
+
+  return {
+    element: popup,
+    position: (clientRect) => {
+      const rect = clientRect?.();
+      if (!rect) return;
+      const menuHeight = Math.min(popup.offsetHeight || 320, 320);
+      const below = rect.bottom + 4;
+      const flip = below + menuHeight > window.innerHeight && rect.top - menuHeight - 4 > 0;
+      popup.style.left = `${Math.min(rect.left, Math.max(8, window.innerWidth - popup.offsetWidth - 8))}px`;
+      popup.style.top = flip ? `${rect.top - menuHeight - 4}px` : `${below}px`;
+    },
+    destroy: (immediate = false) => {
+      if (immediate || motionMs === 0) {
+        popup.remove();
+        return;
+      }
+      popup.style.opacity = "0";
+      popup.style.transform = "translateY(4px)";
+      popup.style.pointerEvents = "none";
+      window.setTimeout(() => popup.remove(), motionMs);
+    },
+  };
+}
+
+export interface SuggestionRendererOptions<ItemType> {
+  /** Maps suggestion items to shared rows */
+  toRow: (item: ItemType) => SuggestionRow;
+  /** Reads resolved chrome (editor storage) at open time */
+  getChrome: (editor: any) => SuggestionChrome;
+  /** Copy for the empty state */
+  getEmptyLabel: () => string;
+}
+
+/**
+ * Builds the `render()` lifecycle for a tiptap Suggestion configuration,
+ * portaling the shared SuggestionList and wiring keyboard navigation,
+ * Escape (consumed -- it must not reach outer handlers like fullscreen
+ * exit), repositioning, and enter/exit motion.
+ */
+export function createSuggestionRenderer<ItemType>({
+  toRow,
+  getChrome,
+  getEmptyLabel,
+}: SuggestionRendererOptions<ItemType>) {
+  return () => {
+    let component: ReactRenderer<SuggestionListRef> | null = null;
+    let popup: PopupHandle | null = null;
+
+    const makeProps = (props: any) => ({
+      rows: (props.items as ItemType[]).map(toRow),
+      chrome: getChrome(props.editor),
+      emptyLabel: getEmptyLabel(),
+      onSelect: (index: number) => {
+        const item = (props.items as ItemType[])[index];
+        if (item !== undefined) props.command(item);
+      },
+    });
+
+    return {
+      onStart: (props: any) => {
+        component = new ReactRenderer(SuggestionList, {
+          props: makeProps(props),
+          editor: props.editor,
+        });
+        popup = createPopup(props.editor.view.dom, getChrome(props.editor).motionMs);
+        popup.element.appendChild(component.element);
+        popup.position(props.clientRect);
+        // reposition once content has laid out (flip needs real height)
+        requestAnimationFrame(() => popup?.position(props.clientRect));
+      },
+      onUpdate: (props: any) => {
+        component?.updateProps(makeProps(props));
+        popup?.position(props.clientRect);
+      },
+      onKeyDown: (props: any) => {
+        if (props.event.key === "Escape") {
+          // consume the Escape entirely: closing the menu must not also
+          // trigger outer Escape handlers (e.g. fullscreen exit)
+          props.event.stopPropagation();
+          popup?.destroy();
+          component?.destroy();
+          popup = null;
+          component = null;
+          return true;
+        }
+        return component?.ref?.onKeyDown(props) ?? false;
+      },
+      onExit: () => {
+        popup?.destroy();
+        component?.destroy();
+        popup = null;
+        component = null;
+      },
+    };
+  };
+}