@multiplatform.one/rich-text 6.0.0

package/src/RichTextEditor/index.tsx

@@ -0,0 +1,245 @@
+/**
+ * RichTextEditor with form integration
+ *
+ * Three-branch architecture following field architecture standard:
+ * - Branch 1: Skeleton loading state
+ * - Branch 2: Standalone (no form context)
+ * - Branch 3: Form-integrated (with TanStack Form)
+ *
+ * Wraps RichEditor compound component with FieldLayout and validation.
+ * Uses custom empty check for '<p></p>' which is Tiptap's empty state.
+ */
+import type { DeepKeys, DeepValue } from "@tanstack/form-core";
+import type React from "react";
+import { useCallback, useRef, useState } from "react";
+import type { LabelProps, SizeTokens } from "tamagui";
+import { YStack } from "tamagui";
+
+import {
+  Field,
+  FieldLayout,
+  Skeleton,
+  getFieldError,
+  mergeFieldHandler,
+  useFormField,
+  useResolvedValidators,
+  type FormFieldProps,
+  type FieldComponentProps,
+  type Validator,
+} from "@multiplatform.one/forms";
+import type { ToolbarSection } from "../types";
+import type { RichEditorRef } from "../types";
+import { RichEditor } from "../RichEditor";
+
+// ---------------------------------------------------------------------------
+// Custom empty check for rich text
+// ---------------------------------------------------------------------------
+
+/**
+ * Rich text empty check: treats null, undefined, empty string, and
+ * Tiptap's default empty paragraph as empty values.
+ */
+const richTextIsEmpty = (v: unknown): boolean => !v || v === "<p></p>" || v === "";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type RichTextEditorProps<
+  TParentData = any,
+  TName extends DeepKeys<TParentData> = any,
+  TFieldValidator extends Validator<DeepValue<TParentData, TName>, unknown> | undefined = undefined,
+  TFormValidator extends Validator<TParentData, unknown> | undefined = undefined,
+  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
+> = Omit<
+  FormFieldProps<TParentData, TName, TFieldValidator, TFormValidator, TData>,
+  "children" | "field"
+> &
+  Partial<
+    Omit<
+      FieldComponentProps<TParentData, TName, TFieldValidator, TFormValidator, TData>,
+      "children"
+    >
+  > & {
+    value?: string;
+    defaultValue?: string;
+    onChange?: (value: string) => void;
+    onBlur?: (...args: any[]) => void;
+    placeholder?: string;
+    disabled?: boolean;
+    readOnly?: boolean;
+    minHeight?: number;
+    maxHeight?: number;
+    label?: React.ReactNode;
+    labelProps?: Omit<LabelProps, "htmlFor" | "ref">;
+    helperText?: string;
+    error?: string | boolean;
+    required?: boolean;
+    size?: SizeTokens;
+    /** Show the formatting toolbar (default: true) */
+    showToolbar?: boolean;
+    /** Use compact sizing for toolbar (default: false) */
+    compact?: boolean;
+    /** Show the bubble toolbar on text selection (default: false, web only) */
+    showBubbleToolbar?: boolean;
+    /** Toolbar sections to display (shows all when omitted) */
+    sections?: ToolbarSection[];
+    /** When true, renders a skeleton placeholder instead of the editor */
+    skeleton?: boolean;
+  };
+
+// ---------------------------------------------------------------------------
+// RichTextEditor Component
+// ---------------------------------------------------------------------------
+
+export function RichTextEditor<
+  TParentData,
+  TName extends DeepKeys<TParentData>,
+  TFieldValidator extends Validator<DeepValue<TParentData, TName>, unknown> | undefined = undefined,
+  TFormValidator extends Validator<TParentData, unknown> | undefined = undefined,
+  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
+>(props: RichTextEditorProps<TParentData, TName, TFieldValidator, TFormValidator, TData>) {
+  const {
+    defaultValue = "",
+    form,
+    placeholder = "Write something...",
+    disabled,
+    readOnly,
+    minHeight = 150,
+    maxHeight,
+    mode,
+    name,
+    preserveValue,
+    validators,
+    label,
+    labelProps,
+    error: errorProp,
+    helperText,
+    required,
+    size,
+    value: controlledValue,
+    onChange,
+    onBlur,
+    showToolbar = true,
+    compact = false,
+    showBubbleToolbar = false,
+    sections,
+    skeleton,
+    ..._restProps
+  } = props;
+
+  const { resolvedForm, knobProps, id } = useFormField({ form });
+  const resolvedValidators = useResolvedValidators(
+    required,
+    validators,
+    label,
+    name,
+    richTextIsEmpty,
+  );
+  const editorRef = useRef<RichEditorRef>(null);
+  const [internalValue, setInternalValue] = useState(controlledValue ?? defaultValue);
+
+  const value = controlledValue ?? internalValue;
+
+  const handleChange = useCallback(
+    (html: string) => {
+      setInternalValue(html);
+      onChange?.(html);
+    },
+    [onChange],
+  );
+
+  // ── Branch 1: Skeleton ──────────────────────────────────────────
+  if (skeleton) {
+    return (
+      <YStack gap="$2">
+        {label && <Skeleton variant="text" width="30%" height={14} />}
+        <Skeleton variant="rounded" width="100%" height={minHeight} />
+      </YStack>
+    );
+  }
+
+  // ── Shared editor renderer ──────────────────────────────────────
+  const renderEditor = (
+    currentValue: string,
+    onValueChange: (v: string) => void,
+    handleBlur?: () => void,
+    hasError?: boolean,
+  ) => {
+    return (
+      <RichEditor
+        ref={editorRef}
+        initialContent={currentValue}
+        onChange={(html) => onValueChange(html)}
+        onBlur={handleBlur}
+        placeholder={placeholder}
+        editable={!disabled && !readOnly}
+        minHeight={minHeight}
+        maxHeight={maxHeight}
+        showToolbar={showToolbar}
+        showBubbleToolbar={showBubbleToolbar}
+        sections={sections}
+        hasError={hasError}
+        size={size}
+        compact={compact}
+      />
+    );
+  };
+
+  // ── Branch 2: Standalone (no form context) ──────────────────────
+  if (!resolvedForm || !name) {
+    return (
+      <FieldLayout
+        id={id}
+        label={label}
+        labelProps={labelProps}
+        error={errorProp}
+        helperText={helperText}
+        required={required}
+        size={size}
+        knobProps={knobProps}
+        onBlur={onBlur}
+      >
+        {renderEditor(value, handleChange, onBlur as any, !!errorProp)}
+      </FieldLayout>
+    );
+  }
+
+  // ── Branch 3: Form-integrated ───────────────────────────────────
+  return (
+    <Field
+      defaultValue={defaultValue}
+      form={resolvedForm}
+      mode={mode}
+      name={name}
+      preserveValue={preserveValue}
+      validators={resolvedValidators}
+    >
+      {(field) => {
+        const resolvedError = getFieldError(field, errorProp);
+        const fieldValue = (field.state.value as string) ?? "";
+
+        return (
+          <FieldLayout
+            id={id}
+            label={label}
+            labelProps={labelProps}
+            error={resolvedError}
+            helperText={helperText}
+            required={required}
+            size={size}
+            knobProps={knobProps}
+            onBlur={mergeFieldHandler(field, "handleBlur", onBlur)}
+          >
+            {renderEditor(
+              fieldValue,
+              (v) => field.handleChange(v as any),
+              () => field.handleBlur(),
+              !!resolvedError,
+            )}
+          </FieldLayout>
+        );
+      }}
+    </Field>
+  );
+}

package/src/RichTextEditor/richTextEditor.spec.tsx

@@ -0,0 +1,239 @@
+import { describe, it, expect, vi } from "vitest";
+
+// ---------------------------------------------------------------------------
+// Mocks -- must come before imports
+// ---------------------------------------------------------------------------
+
+vi.mock("@multiplatform.one/forms", () => {
+  return {
+    Field: ({ children, ...props }: any) => {
+      const field = {
+        state: { value: props.defaultValue ?? "", meta: { errors: [] } },
+        handleChange: vi.fn(),
+        handleBlur: vi.fn(),
+      };
+      return <div data-testid="tanstack-field">{children(field)}</div>;
+    },
+    FieldLayout: ({ children, label, error, ...props }: any) => (
+      <div
+        data-testid="field-layout"
+        data-label={label}
+        data-error={error || undefined}
+        data-skeleton={props.skeleton || undefined}
+      >
+        {children}
+      </div>
+    ),
+    Skeleton: ({ variant, width, height, ..._props }: any) => (
+      <div data-testid="skeleton" data-variant={variant} style={{ width, height }} />
+    ),
+    getFieldError: (field: any, propError: any) => {
+      const fieldError = field.state.meta.errors.length
+        ? String(field.state.meta.errors[0])
+        : undefined;
+      return propError ?? fieldError;
+    },
+    useFormField: ({ form }: any) => ({
+      resolvedForm: form || undefined,
+      knobProps: {
+        body: {},
+        borderRadius: { borderRadius: "$3", borderWidth: 1 },
+        elevation: undefined,
+        sizeToken: "$4",
+        outlined: false,
+        inputBackground: "$color2",
+        textAccentColor: "$color",
+        transition: undefined,
+        heading: {},
+        gap: { gap: "$2" },
+      },
+      id: "test-id",
+    }),
+    useResolvedValidators: (
+      required: boolean | undefined,
+      validators: any,
+      label: any,
+      name: any,
+      isEmpty?: (v: unknown) => boolean,
+    ) => {
+      if (!required) return validators;
+      const check = isEmpty || ((v: unknown) => v == null || v === "");
+      const requiredValidator = ({ value }: { value: unknown }) =>
+        check(value)
+          ? `${typeof label === "string" ? label : name || "Field"} is required`
+          : undefined;
+      if (!validators) return { onSubmit: requiredValidator };
+      return { ...validators, onSubmit: requiredValidator };
+    },
+    mergeFieldHandler: (field: any, name: string, handler: any) => {
+      return (...args: any[]) => {
+        (field[name] as Function)(...args);
+        handler?.(...args);
+      };
+    },
+    clampRadiusForLargeComponent: (radiusToken: string | undefined, maxTokenNum = 4) => {
+      if (!radiusToken) return "$3";
+      if (radiusToken === "$0") return 0;
+      if (typeof radiusToken === "string" && radiusToken.startsWith("$")) {
+        const num = Number.parseInt(radiusToken.slice(1), 10);
+        return num > maxTokenNum ? `$${maxTokenNum}` : radiusToken;
+      }
+      return radiusToken;
+    },
+    Button: (props: any) => <button>{props.children}</button>,
+  };
+});
+
+vi.mock("@multiplatform.one/components", () => ({
+  Tooltip: ({ children }: any) => children,
+}));
+
+vi.mock("@multiplatform.one/theme", () => ({
+  useResolvedKnobs: () => ({
+    knobProps: {
+      body: {},
+      borderRadius: { borderRadius: "$3", borderWidth: 1 },
+      elevation: undefined,
+      sizeToken: "$4",
+      outlined: false,
+      inputBackground: "$color2",
+      textAccentColor: "$color",
+      transition: undefined,
+      heading: {},
+      gap: { gap: "$2" },
+    },
+    control: {
+      hoverKnobProps: undefined,
+      pressKnobProps: undefined,
+      focusKnobProps: undefined,
+      focusVisibleKnobProps: undefined,
+    },
+  }),
+}));
+
+vi.mock("@tiptap/react/menus", () => ({
+  BubbleMenu: ({ children }: any) => <div data-testid="bubble-menu">{children}</div>,
+}));
+
+const mockEditor = {
+  isActive: vi.fn().mockReturnValue(false),
+  getAttributes: vi.fn().mockReturnValue({}),
+  can: vi.fn().mockReturnValue({ undo: () => false, redo: () => false }),
+  getHTML: vi.fn().mockReturnValue("<p></p>"),
+  getJSON: vi.fn().mockReturnValue({ type: "doc", content: [] }),
+  chain: vi.fn().mockReturnValue({
+    focus: vi.fn().mockReturnValue({
+      toggleBold: vi.fn().mockReturnValue({ run: vi.fn() }),
+    }),
+  }),
+  commands: {
+    setContent: vi.fn(),
+    focus: vi.fn(),
+    blur: vi.fn(),
+  },
+  setEditable: vi.fn(),
+};
+
+vi.mock("@tiptap/react", () => ({
+  useEditor: vi.fn().mockReturnValue(mockEditor),
+  EditorContent: ({ editor: _editor }: any) => <div data-testid="editor-content">Editor</div>,
+}));
+
+vi.mock("@tiptap/starter-kit", () => ({
+  default: { configure: vi.fn().mockReturnValue({}) },
+}));
+vi.mock("@tiptap/extension-underline", () => ({ default: {} }));
+vi.mock("@tiptap/extension-link", () => ({
+  default: { configure: vi.fn().mockReturnValue({}) },
+}));
+vi.mock("@tiptap/extension-placeholder", () => ({
+  default: { configure: vi.fn().mockReturnValue({}) },
+}));
+vi.mock("@tiptap/extension-text-align", () => ({
+  default: { configure: vi.fn().mockReturnValue({}) },
+}));
+vi.mock("@tiptap/extension-color", () => ({ Color: {} }));
+vi.mock("@tiptap/extension-text-style", () => ({ TextStyle: {} }));
+vi.mock("@tiptap/extension-highlight", () => ({
+  Highlight: { configure: vi.fn().mockReturnValue({}) },
+}));
+vi.mock("@tiptap/extension-subscript", () => ({ Subscript: {} }));
+vi.mock("@tiptap/extension-superscript", () => ({ Superscript: {} }));
+vi.mock("@tiptap/extension-task-list", () => ({ default: {} }));
+vi.mock("@tiptap/extension-task-item", () => ({
+  default: { configure: vi.fn().mockReturnValue({}) },
+}));
+vi.mock("@tiptap/extension-image", () => ({
+  default: { configure: vi.fn().mockReturnValue({}) },
+}));
+
+// ---------------------------------------------------------------------------
+// Imports (after mocks)
+// ---------------------------------------------------------------------------
+
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+
+const { RichTextEditor } = await import("./index");
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("RichTextEditor form-integrated field", () => {
+  it("renders skeleton loading state when skeleton={true}", () => {
+    const { getAllByTestId, queryByTestId } = renderWithProviders(
+      <RichTextEditor skeleton label="Content" />,
+    );
+    const skeletons = getAllByTestId("skeleton");
+    // Should render label skeleton + editor skeleton
+    expect(skeletons.length).toBe(2);
+    // Should NOT render the editor content
+    expect(queryByTestId("editor-content")).toBeNull();
+  });
+
+  it("renders standalone (Branch 2) without form context and manages internal state", () => {
+    const handleChange = vi.fn();
+    const { container } = renderWithProviders(
+      <RichTextEditor label="Content" onChange={handleChange} placeholder="Write something..." />,
+    );
+    // Should render FieldLayout wrapper
+    const fieldLayout = container.querySelector("[data-testid='field-layout']");
+    expect(fieldLayout).toBeTruthy();
+    // Should render the RichEditor inside
+    const editorContent = container.querySelector("[data-testid='editor-content']");
+    expect(editorContent).toBeTruthy();
+  });
+
+  it("renders form-integrated (Branch 3) when form and name are provided", () => {
+    const mockForm = { store: {} } as any;
+    const { getByTestId } = renderWithProviders(
+      <RichTextEditor form={mockForm} name="content" label="Content" required />,
+    );
+    // Should render the TanStack Field wrapper
+    const field = getByTestId("tanstack-field");
+    expect(field).toBeTruthy();
+    // Should render FieldLayout inside the field
+    const fieldLayout = getByTestId("field-layout");
+    expect(fieldLayout).toBeTruthy();
+  });
+
+  it("custom empty check recognizes '<p></p>' and '' as empty for required validation", () => {
+    // The custom isEmpty function should treat '<p></p>' and '' as empty
+    const isEmpty = (v: unknown) => !v || v === "<p></p>" || v === "";
+
+    expect(isEmpty("")).toBe(true);
+    expect(isEmpty("<p></p>")).toBe(true);
+    expect(isEmpty(null)).toBe(true);
+    expect(isEmpty(undefined)).toBe(true);
+    expect(isEmpty("<p>Hello</p>")).toBe(false);
+    expect(isEmpty("<h1>Title</h1>")).toBe(false);
+  });
+
+  it("passes showBubbleToolbar and sections props through to RichEditor", () => {
+    const { container } = renderWithProviders(
+      <RichTextEditor label="Content" showBubbleToolbar sections={["formatting", "list"]} />,
+    );
+    // Should render without error (props are passed through)
+    expect(container.firstChild).toBeTruthy();
+  });
+});

package/src/constants.ts

@@ -0,0 +1,100 @@
+/**
+ * Shared constants for the rich text editor
+ */
+
+import type { NativeCapability } from "./types";
+
+// ===========================================================================
+// Color Palettes
+// ===========================================================================
+
+export interface ColorEntry {
+  /** Display name for the color */
+  name: string;
+  /** Hex color value, or null for default/none */
+  value: string | null;
+}
+
+export const TEXT_COLORS: ColorEntry[] = [
+  { name: "Default", value: null },
+  { name: "Black", value: "#000000" },
+  { name: "Dark Gray", value: "#4a4a4a" },
+  { name: "Gray", value: "#9b9b9b" },
+  { name: "Red", value: "#e53935" },
+  { name: "Orange", value: "#fb8c00" },
+  { name: "Yellow", value: "#fdd835" },
+  { name: "Green", value: "#43a047" },
+  { name: "Blue", value: "#1e88e5" },
+  { name: "Purple", value: "#8e24aa" },
+  { name: "Pink", value: "#d81b60" },
+];
+
+export const HIGHLIGHT_COLORS: ColorEntry[] = [
+  { name: "None", value: null },
+  { name: "Yellow", value: "#fff59d" },
+  { name: "Green", value: "#c8e6c9" },
+  { name: "Blue", value: "#bbdefb" },
+  { name: "Pink", value: "#f8bbd9" },
+  { name: "Purple", value: "#e1bee7" },
+  { name: "Orange", value: "#ffe0b2" },
+  { name: "Red", value: "#ffcdd2" },
+  { name: "Cyan", value: "#b2ebf2" },
+];
+
+// ===========================================================================
+// Native (10Tap) Supported Commands
+// ===========================================================================
+
+/**
+ * Maps each EditorCommand to whether 10Tap supports it via bridge extensions.
+ *
+ * Supported commands use actual bridge methods (ColorBridge, HighlightBridge,
+ * ImageBridge, TaskListBridge, etc.).
+ *
+ * Unsupported commands (subscript, superscript, textAlign, codeBlock,
+ * horizontalRule, clearFormatting) have no 10Tap bridge equivalent.
+ */
+export const NATIVE_SUPPORTED_COMMANDS: NativeCapability = {
+  bold: true,
+  italic: true,
+  underline: true,
+  strike: true,
+  code: true,
+  subscript: false,
+  superscript: false,
+  heading1: true,
+  heading2: true,
+  heading3: true,
+  heading4: true,
+  heading5: true,
+  heading6: true,
+  paragraph: true,
+  bulletList: true,
+  orderedList: true,
+  taskList: true,
+  blockquote: true,
+  codeBlock: false,
+  link: true,
+  image: true,
+  undo: true,
+  redo: true,
+  alignLeft: false,
+  alignCenter: false,
+  alignRight: false,
+  alignJustify: false,
+  textColor: true,
+  highlight: true,
+  horizontalRule: false,
+  clearFormatting: false,
+  insertTable: false,
+  addColumnBefore: false,
+  addColumnAfter: false,
+  deleteColumn: false,
+  addRowBefore: false,
+  addRowAfter: false,
+  deleteRow: false,
+  deleteTable: false,
+  mergeCells: false,
+  splitCell: false,
+  toggleHeaderRow: false,
+};

package/src/context.spec.ts

@@ -0,0 +1,9 @@
+import { describe, it, expect } from "vitest";
+import { RichEditorContext } from "./context";
+
+describe("RichEditorContext", () => {
+  it("is a valid styled context with expected default values", () => {
+    expect(RichEditorContext).toBeDefined();
+    expect(RichEditorContext.Provider).toBeDefined();
+  });
+});

package/src/context.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared context for the rich text editor compound component
+ */
+
+import type { FontSizeTokens } from "tamagui";
+import { createStyledContext } from "tamagui";
+
+export const RichEditorContext = createStyledContext<{
+  size: FontSizeTokens;
+  compact: boolean;
+  disabled: boolean;
+}>({
+  size: "$true" as FontSizeTokens,
+  compact: false,
+  disabled: false,
+});