@multiplatform.one/rich-text 6.1.0 → 6.4.0

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

package/src/editor/tiptapEditor.spec.tsx

@@ -1,6 +1,7 @@
 import { describe, it, expect, vi } from "vitest";
 
-vi.mock("@multiplatform.one/forms", () => ({
+vi.mock("@multiplatform.one/forms", async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
   Button: (props: any) => (
     <button
       role="button"
@@ -13,7 +14,8 @@ vi.mock("@multiplatform.one/forms", () => ({
   ),
 }));
 
-vi.mock("@multiplatform.one/components", () => ({
+vi.mock("@multiplatform.one/components", async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
   Tooltip: ({ children }: any) => children,
 }));
 
@@ -39,6 +41,10 @@ const mockEditor = {
     blur: vi.fn(),
   },
   setEditable: vi.fn(),
+  storage: {
+    mediaUpload: { handlers: {} },
+    suggestionChrome: { value: null },
+  },
 };
 
 vi.mock("@tiptap/react", () => ({
@@ -127,18 +133,19 @@ describe("TiptapEditor", () => {
     expect(container.querySelector("[data-testid='editor-content']")).toBeTruthy();
   });
 
-  it("renders BubbleToolbar when showBubbleToolbar is true and does not when false", () => {
-    // With showBubbleToolbar={true}
+  it("gates the formatting bubbles behind showBubbleToolbar (math bubble stays)", () => {
+    // With showBubbleToolbar={true}: formatting bubbles + math bubble
     const { container: withBubble } = renderWithProviders(
       withContext(<TiptapEditor showBubbleToolbar />),
     );
-    expect(withBubble.querySelector("[data-testid='bubble-menu']")).toBeTruthy();
+    expect(withBubble.querySelectorAll("[data-testid='bubble-menu']").length).toBeGreaterThan(1);
 
-    // With showBubbleToolbar={false} (default)
+    // With showBubbleToolbar={false} (default): only the MathBubble stays
+    // mounted — it is the only edit path for inline math atoms.
     const { container: withoutBubble } = renderWithProviders(
       withContext(<TiptapEditor showBubbleToolbar={false} />),
     );
-    expect(withoutBubble.querySelector("[data-testid='bubble-menu']")).toBeNull();
+    expect(withoutBubble.querySelectorAll("[data-testid='bubble-menu']").length).toBe(1);
   });
 
   it("exposes RichEditorRef methods via forwardRef and useImperativeHandle", () => {
@@ -164,6 +171,6 @@ describe("TiptapEditor", () => {
     const cssContent = styleTag?.textContent ?? "";
     // Should use CSS custom properties for theme-aware colors
     expect(cssContent).toContain("var(--color12)");
-    expect(cssContent).toContain("var(--color8");
+    expect(cssContent).toContain("var(--color10");
   });
 });

package/src/exports.spec.ts

@@ -4,7 +4,8 @@ import { describe, it, expect, vi } from "vitest";
 // Mocks -- must come before imports to prevent Tiptap module errors
 // ---------------------------------------------------------------------------
 
-vi.mock("@multiplatform.one/forms", () => ({
+vi.mock("@multiplatform.one/forms", async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
   Field: () => null,
   FieldLayout: ({ children }: any) => children,
   Skeleton: () => null,
@@ -35,7 +36,8 @@ vi.mock("@multiplatform.one/components", () => ({
   Tooltip: ({ children }: any) => children,
 }));
 
-vi.mock("@multiplatform.one/theme", () => ({
+vi.mock("@multiplatform.one/theme", async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
   useResolvedKnobs: () => ({
     knobProps: {
       body: {},

package/src/index.ts

@@ -10,4 +10,13 @@ export type { RichEditorCombinedProps } from "./RichEditor";
 export { RichTextEditor } from "./RichTextEditor";
 export type { RichTextEditorProps } from "./RichTextEditor";
 
-export type { RichEditorRef, RichEditorProps, EditorCommand, EditorState } from "./types";
+export type {
+  RichEditorRef,
+  RichEditorProps,
+  EditorCapabilities,
+  EditorCommand,
+  EditorState,
+  RichTextMentionOptions,
+} from "./types";
+
+export { MARKDOWN_COMMANDS, isCommandInCapabilities } from "./editor/capabilities";

package/src/integration.spec.tsx

@@ -59,11 +59,13 @@ describe("getEditorCSS defaults", () => {
 // 3. ToolbarButton disabled state from context
 // ===========================================================================
 
-vi.mock("@multiplatform.one/forms", () => ({
+vi.mock("@multiplatform.one/forms", async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
   Button: (props: any) => (
     <button
       role="button"
       aria-label={props["aria-label"]}
+      aria-disabled={props["aria-disabled"]}
       disabled={props.disabled}
       onClick={props.onPress}
       data-active={props.theme === "active" ? "true" : undefined}
@@ -117,7 +119,7 @@ vi.mock("@multiplatform.one/forms", () => ({
     isEmpty?: (v: unknown) => boolean,
   ) => {
     if (!required) return validators;
-    const check = isEmpty || ((v: unknown) => v == null || v === "");
+    const check = isEmpty || ((v: unknown) => v === null || v === undefined || v === "");
     const requiredValidator = ({ value }: { value: unknown }) =>
       check(value)
         ? `${typeof label === "string" ? label : name || "Field"} is required`
@@ -142,11 +144,13 @@ vi.mock("@multiplatform.one/forms", () => ({
   },
 }));
 
-vi.mock("@multiplatform.one/components", () => ({
+vi.mock("@multiplatform.one/components", async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
   Tooltip: ({ children }: any) => children,
 }));
 
-vi.mock("@multiplatform.one/theme", () => ({
+vi.mock("@multiplatform.one/theme", async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
   useResolvedKnobs: () => ({
     knobProps: {
       body: {},
@@ -189,6 +193,10 @@ const mockEditor = {
     blur: vi.fn(),
   },
   setEditable: vi.fn(),
+  storage: {
+    mediaUpload: { handlers: {} },
+    suggestionChrome: { value: null },
+  },
 };
 
 vi.mock("@tiptap/react", () => ({
@@ -225,6 +233,7 @@ vi.mock("@tiptap/extension-image", () => ({
 }));
 
 import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { fireEvent } from "@testing-library/react";
 import { RichEditorContext } from "./context";
 import { defaultEditorState } from "./types";
 import type { EditorCommand, EditorState, ToolbarSection } from "./types";
@@ -236,15 +245,21 @@ const { RichTextEditor } = await import("./RichTextEditor/index");
 
 describe("ToolbarButton disabled state from context", () => {
   it("inherits disabled state from RichEditorContext", () => {
+    const onPress = vi.fn();
     const { getByRole } = renderWithProviders(
       <RichEditorContext.Provider size="$true" compact={false} disabled>
-        <ToolbarButton onPress={() => {}} aria-label="Test">
+        <ToolbarButton onPress={onPress} aria-label="Test">
           T
         </ToolbarButton>
       </RichEditorContext.Provider>,
     );
     const button = getByRole("button");
-    expect(button.getAttribute("disabled")).not.toBeNull();
+    // DG-ST-03 / LC-40: an unavailable toolbar action is aria-disabled
+    // (stays focusable, swallows presses), never bare-`disabled`.
+    expect(button.getAttribute("aria-disabled")).toBe("true");
+    expect(button.getAttribute("disabled")).toBeNull();
+    fireEvent.click(button);
+    expect(onPress).not.toHaveBeenCalled();
   });
 });
 
@@ -394,6 +409,17 @@ describe("NATIVE_SUPPORTED_COMMANDS completeness", () => {
       "highlight",
       "horizontalRule",
       "clearFormatting",
+      "insertTable",
+      "addColumnBefore",
+      "addColumnAfter",
+      "deleteColumn",
+      "addRowBefore",
+      "addRowAfter",
+      "deleteRow",
+      "deleteTable",
+      "mergeCells",
+      "splitCell",
+      "toggleHeaderRow",
     ];
 
     for (const cmd of allCommands) {
@@ -421,10 +447,13 @@ describe("RichEditor passes showBubbleToolbar to TiptapEditor", () => {
     expect(bubbleMenu).toBeTruthy();
   });
 
-  it("does not render BubbleMenu when showBubbleToolbar is false", () => {
+  it("renders only the always-on MathBubble when showBubbleToolbar is false", () => {
     const { container } = renderWithProviders(<RichEditor showBubbleToolbar={false} />);
 
-    const bubbleMenu = container.querySelector("[data-testid='bubble-menu']");
-    expect(bubbleMenu).toBeNull();
+    // showBubbleToolbar gates the OPTIONAL formatting bubbles; the math
+    // bubble stays mounted because it is the only edit path for inline
+    // math atoms (a typed $x$ would otherwise be a dead end).
+    const bubbleMenus = container.querySelectorAll("[data-testid='bubble-menu']");
+    expect(bubbleMenus.length).toBe(1);
   });
 });