@apollohg/react-native-rich-text-editor 2.0.0

package/src/EditorToolbarItems.tsx

@@ -0,0 +1,64 @@
+import {
+    type EditorToolbarDefaultIconId,
+    type EditorToolbarIcon,
+    type EditorToolbarItemPlacement,
+    type EditorToolbarItem,
+} from './EditorToolbarTypes';
+
+export function defaultIcon(id: EditorToolbarDefaultIconId): EditorToolbarIcon {
+    return { type: 'default', id };
+}
+
+export function resolveToolbarItemPlacement(
+    placement: EditorToolbarItemPlacement | undefined
+): EditorToolbarItemPlacement {
+    return placement ?? 'scroll';
+}
+
+/**
+ * The toolbar layout used when `toolbarItems` is not supplied. Spread it to
+ * extend the built-in set rather than restating it:
+ * `[...DEFAULT_EDITOR_TOOLBAR_ITEMS, myItem]`.
+ */
+export const DEFAULT_EDITOR_TOOLBAR_ITEMS: readonly EditorToolbarItem[] = [
+    { type: 'mark', mark: 'bold', label: 'Bold', icon: defaultIcon('bold') },
+    { type: 'mark', mark: 'italic', label: 'Italic', icon: defaultIcon('italic') },
+    { type: 'mark', mark: 'underline', label: 'Underline', icon: defaultIcon('underline') },
+    { type: 'mark', mark: 'strike', label: 'Strikethrough', icon: defaultIcon('strike') },
+    { type: 'blockquote', label: 'Blockquote', icon: defaultIcon('blockquote') },
+    { type: 'separator' },
+    {
+        type: 'list',
+        listType: 'bullet_list',
+        label: 'Bullet List',
+        icon: defaultIcon('bulletList'),
+    },
+    {
+        type: 'list',
+        listType: 'ordered_list',
+        label: 'Ordered List',
+        icon: defaultIcon('orderedList'),
+    },
+    {
+        type: 'command',
+        command: 'indentList',
+        label: 'Indent List',
+        icon: defaultIcon('indentList'),
+    },
+    {
+        type: 'command',
+        command: 'outdentList',
+        label: 'Outdent List',
+        icon: defaultIcon('outdentList'),
+    },
+    { type: 'node', nodeType: 'hard_break', label: 'Line Break', icon: defaultIcon('lineBreak') },
+    {
+        type: 'node',
+        nodeType: 'horizontal_rule',
+        label: 'Horizontal Rule',
+        icon: defaultIcon('horizontalRule'),
+    },
+    { type: 'separator' },
+    { type: 'command', command: 'undo', label: 'Undo', icon: defaultIcon('undo') },
+    { type: 'command', command: 'redo', label: 'Redo', icon: defaultIcon('redo') },
+] as const;

package/src/EditorToolbarRegistry.tsx

@@ -0,0 +1,254 @@
+import React, { createContext, useEffect, useSyncExternalStore, useState } from 'react';
+import type { MentionSuggestion } from './addons';
+import type { EditorMentionTheme } from './EditorTheme';
+
+export interface EditorToolbarFrame {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+export type EditorToolbarFrameListener = () => void;
+
+export interface EditorToolbarFrameRegistration {
+    ownerId: number | null;
+    frame: EditorToolbarFrame;
+}
+
+export const editorToolbarFrames = new Map<number, EditorToolbarFrameRegistration>();
+
+export const editorToolbarFrameListeners = new Set<EditorToolbarFrameListener>();
+
+export const editorToolbarMentionStateListeners = new Set<EditorToolbarFrameListener>();
+
+export let nextEditorToolbarRegistrationId = 1;
+
+export let activeEditorToolbarInteractions = 0;
+
+export let editorToolbarFocusPreserveUntil = 0;
+
+export let activeEditorToolbarFrameOwnerId: number | null = null;
+
+export function allocateEditorToolbarRegistrationId(): number {
+    return nextEditorToolbarRegistrationId++;
+}
+
+export const EditorToolbarFrameOwnerContext = createContext<number | null>(null);
+
+export function EditorToolbarFrameOwnerProvider({
+    ownerId,
+    children,
+}: {
+    ownerId: number;
+    children: React.ReactNode;
+}) {
+    return (
+        <EditorToolbarFrameOwnerContext.Provider value={ownerId}>
+            {children}
+        </EditorToolbarFrameOwnerContext.Provider>
+    );
+}
+
+export interface EditorToolbarMentionState {
+    ownerId: number;
+    trigger: string;
+    suggestions: readonly MentionSuggestion[];
+    theme?: EditorMentionTheme;
+    suggestionThemes?: Readonly<Record<string, EditorMentionTheme | undefined>>;
+    onSelectSuggestion: (suggestion: MentionSuggestion) => void;
+}
+
+export let editorToolbarMentionState: EditorToolbarMentionState | null = null;
+
+export const EDITOR_TOOLBAR_FOCUS_PRESERVE_MS = 750;
+
+export function areToolbarFramesEqual(
+    left: EditorToolbarFrame | undefined,
+    right: EditorToolbarFrame | undefined
+): boolean {
+    return (
+        left?.x === right?.x &&
+        left?.y === right?.y &&
+        left?.width === right?.width &&
+        left?.height === right?.height
+    );
+}
+
+export function areToolbarFrameListsEqual(
+    left: readonly EditorToolbarFrame[],
+    right: readonly EditorToolbarFrame[]
+): boolean {
+    if (left.length !== right.length) {
+        return false;
+    }
+    return left.every((frame, index) => areToolbarFramesEqual(frame, right[index]));
+}
+
+export function notifyEditorToolbarFrameListeners() {
+    editorToolbarFrameListeners.forEach((listener) => listener());
+}
+
+export function notifyEditorToolbarMentionStateListeners() {
+    editorToolbarMentionStateListeners.forEach((listener) => listener());
+}
+
+export function getEditorToolbarFramesSnapshot(ownerId: number): EditorToolbarFrame[] {
+    return Array.from(editorToolbarFrames.values())
+        .filter(
+            (registration) =>
+                registration.ownerId === ownerId ||
+                (registration.ownerId == null && activeEditorToolbarFrameOwnerId === ownerId)
+        )
+        .map((registration) => registration.frame);
+}
+
+export function subscribeEditorToolbarMentionState(listener: EditorToolbarFrameListener) {
+    editorToolbarMentionStateListeners.add(listener);
+    return () => {
+        editorToolbarMentionStateListeners.delete(listener);
+    };
+}
+
+export function getEditorToolbarMentionStateSnapshot(): EditorToolbarMentionState | null {
+    return editorToolbarMentionState;
+}
+
+export function useEditorToolbarMentionState(): EditorToolbarMentionState | null {
+    return useSyncExternalStore(
+        subscribeEditorToolbarMentionState,
+        getEditorToolbarMentionStateSnapshot,
+        getEditorToolbarMentionStateSnapshot
+    );
+}
+
+export function registerEditorToolbarFrame(
+    id: number,
+    frame: EditorToolbarFrame | null,
+    ownerId: number | null
+) {
+    if (frame == null || frame.width <= 0 || frame.height <= 0) {
+        if (editorToolbarFrames.delete(id)) {
+            notifyEditorToolbarFrameListeners();
+        }
+        return;
+    }
+
+    const currentRegistration = editorToolbarFrames.get(id);
+    if (
+        currentRegistration?.ownerId === ownerId &&
+        areToolbarFramesEqual(currentRegistration.frame, frame)
+    ) {
+        return;
+    }
+
+    editorToolbarFrames.set(id, { ownerId, frame });
+    notifyEditorToolbarFrameListeners();
+}
+
+export function unregisterEditorToolbarFrame(id: number) {
+    if (editorToolbarFrames.delete(id)) {
+        notifyEditorToolbarFrameListeners();
+    }
+}
+
+export function preserveEditorToolbarFocusForNextBlur() {
+    editorToolbarFocusPreserveUntil = Date.now() + EDITOR_TOOLBAR_FOCUS_PRESERVE_MS;
+}
+
+export function beginEditorToolbarInteraction() {
+    activeEditorToolbarInteractions += 1;
+    preserveEditorToolbarFocusForNextBlur();
+}
+
+export function endEditorToolbarInteraction() {
+    activeEditorToolbarInteractions = Math.max(0, activeEditorToolbarInteractions - 1);
+    preserveEditorToolbarFocusForNextBlur();
+}
+
+export function isEditorToolbarFocusPreservationActive(): boolean {
+    return activeEditorToolbarInteractions > 0 || Date.now() <= editorToolbarFocusPreserveUntil;
+}
+
+export function setActiveEditorToolbarFrameOwnerForEditor(ownerId: number, isActive: boolean) {
+    const nextOwnerId = isActive
+        ? ownerId
+        : activeEditorToolbarFrameOwnerId === ownerId
+          ? null
+          : activeEditorToolbarFrameOwnerId;
+    if (activeEditorToolbarFrameOwnerId === nextOwnerId) {
+        return;
+    }
+    activeEditorToolbarFrameOwnerId = nextOwnerId;
+    notifyEditorToolbarFrameListeners();
+}
+
+export function useEditorToolbarFrames(ownerId: number): readonly EditorToolbarFrame[] {
+    const [frames, setFrames] = useState<EditorToolbarFrame[]>(() =>
+        getEditorToolbarFramesSnapshot(ownerId)
+    );
+
+    useEffect(() => {
+        const listener = () => {
+            const nextFrames = getEditorToolbarFramesSnapshot(ownerId);
+            setFrames((currentFrames) =>
+                areToolbarFrameListsEqual(currentFrames, nextFrames) ? currentFrames : nextFrames
+            );
+        };
+        editorToolbarFrameListeners.add(listener);
+        listener();
+        return () => {
+            editorToolbarFrameListeners.delete(listener);
+        };
+    }, [ownerId]);
+
+    return frames;
+}
+
+export function setEditorToolbarMentionState(
+    ownerId: number,
+    state: Omit<EditorToolbarMentionState, 'ownerId'> | null
+) {
+    if (state == null) {
+        if (editorToolbarMentionState?.ownerId !== ownerId) {
+            return;
+        }
+        editorToolbarMentionState = null;
+        notifyEditorToolbarMentionStateListeners();
+        return;
+    }
+
+    editorToolbarMentionState = {
+        ownerId,
+        ...state,
+    };
+    notifyEditorToolbarMentionStateListeners();
+}
+
+export function _setEditorToolbarFrameForTests(
+    id: number,
+    frame: EditorToolbarFrame | null,
+    ownerId: number | null = null
+) {
+    registerEditorToolbarFrame(id, frame, ownerId);
+}
+
+export function _resetEditorToolbarFrameRegistryForTests() {
+    editorToolbarFrames.clear();
+    editorToolbarMentionState = null;
+    activeEditorToolbarInteractions = 0;
+    editorToolbarFocusPreserveUntil = 0;
+    activeEditorToolbarFrameOwnerId = null;
+    notifyEditorToolbarFrameListeners();
+    notifyEditorToolbarMentionStateListeners();
+}
+
+export function _beginEditorToolbarInteractionForTests() {
+    beginEditorToolbarInteraction();
+}
+
+export function _endEditorToolbarInteractionForTests() {
+    endEditorToolbarInteraction();
+}
+
+export const BUTTON_HIT = 44;

package/src/EditorToolbarTypes.tsx

@@ -0,0 +1,322 @@
+import type { HistoryState, ReadonlyActiveState } from './NativeEditorBridge';
+import type { EditorToolbarTheme } from './EditorTheme';
+
+/** List kinds a first-class `list` toolbar item can toggle. */
+export type EditorToolbarListType = 'bullet_list' | 'ordered_list' | 'bulletList' | 'orderedList';
+
+/** Heading levels the toolbar and `toggleHeading` accept. */
+export type EditorToolbarHeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+/** Commands a `command` toolbar item can run. */
+export type EditorToolbarCommand = 'indentList' | 'outdentList' | 'undo' | 'redo';
+
+/**
+ * How a group's children are shown: `'expand'` reveals them inline in the
+ * toolbar row, `'menu'` opens them in a popover.
+ */
+export type EditorToolbarGroupPresentation = 'expand' | 'menu';
+
+/**
+ * Which region of the toolbar an item sits in. `'start'` and `'end'` pin the
+ * item to that edge; `'scroll'` (the default) puts it in the scrolling middle
+ * row.
+ */
+export type EditorToolbarItemPlacement = 'start' | 'scroll' | 'end';
+
+/** Icons the package draws itself, on both platforms. */
+export type EditorToolbarDefaultIconId =
+    | 'bold'
+    | 'italic'
+    | 'underline'
+    | 'strike'
+    | 'link'
+    | 'image'
+    | 'h1'
+    | 'h2'
+    | 'h3'
+    | 'h4'
+    | 'h5'
+    | 'h6'
+    | 'blockquote'
+    | 'bulletList'
+    | 'orderedList'
+    | 'indentList'
+    | 'outdentList'
+    | 'lineBreak'
+    | 'horizontalRule'
+    | 'undo'
+    | 'redo';
+
+/** An SF Symbol, used for the iOS half of a `platform` icon. */
+export interface EditorToolbarSFSymbolIcon {
+    type: 'sfSymbol';
+    /** SF Symbol name, e.g. `'bold'`. */
+    name: string;
+}
+
+/** A Material icon, used for the Android half of a `platform` icon. */
+export interface EditorToolbarMaterialIcon {
+    type: 'material';
+    /** Material icon name, e.g. `'format_bold'`. */
+    name: string;
+}
+
+/**
+ * A toolbar button's icon:
+ *
+ * - `default` — one of the package's built-in icons.
+ * - `glyph` — arbitrary text or an emoji, drawn as-is.
+ * - `platform` — per-platform native icons, with `fallbackText` when the
+ *   platform cannot resolve the named icon.
+ */
+export type EditorToolbarIcon =
+    | {
+          type: 'default';
+          id: EditorToolbarDefaultIconId;
+      }
+    | {
+          type: 'glyph';
+          text: string;
+      }
+    | {
+          type: 'platform';
+          ios?: EditorToolbarSFSymbolIcon;
+          android?: EditorToolbarMaterialIcon;
+          fallbackText?: string;
+      };
+
+/** Visual overrides for one toolbar button. */
+export interface EditorToolbarButtonStyle {
+    iconSize?: number;
+    color?: string;
+    backgroundColor?: string;
+    activeColor?: string;
+    disabledColor?: string;
+    activeBackgroundColor?: string;
+    disabledBackgroundColor?: string;
+    borderRadius?: number;
+}
+
+/**
+ * A single toolbar button. Every variant takes a `label` (its accessible
+ * name), an `icon`, an optional `key` (defaults to something derived from the
+ * variant), and an optional `placement`.
+ *
+ * - `mark` — toggles the named mark; active and enabled state come from the engine.
+ * - `link` / `image` — calls the editor's `onRequestLink` / `onRequestImage`.
+ * - `heading` — toggles the given heading level.
+ * - `blockquote` — toggles blockquote wrapping.
+ * - `list` — toggles the given list type.
+ * - `command` — runs an {@link EditorToolbarCommand}.
+ * - `node` — inserts the named node type, e.g. `'horizontalRule'`.
+ * - `action` — host-defined; calls `onToolbarAction` with its `key`, and the
+ *   host supplies `isActive`/`isDisabled` since the engine knows nothing about it.
+ */
+export type EditorToolbarLeafItem = (
+    | {
+          type: 'mark';
+          mark: string;
+          label: string;
+          icon: EditorToolbarIcon;
+          key?: string;
+          placement?: EditorToolbarItemPlacement;
+      }
+    | {
+          type: 'link';
+          label: string;
+          icon: EditorToolbarIcon;
+          key?: string;
+          placement?: EditorToolbarItemPlacement;
+      }
+    | {
+          type: 'image';
+          label: string;
+          icon: EditorToolbarIcon;
+          key?: string;
+          placement?: EditorToolbarItemPlacement;
+      }
+    | {
+          type: 'heading';
+          level: EditorToolbarHeadingLevel;
+          label: string;
+          icon: EditorToolbarIcon;
+          key?: string;
+          placement?: EditorToolbarItemPlacement;
+      }
+    | {
+          type: 'blockquote';
+          label: string;
+          icon: EditorToolbarIcon;
+          key?: string;
+          placement?: EditorToolbarItemPlacement;
+      }
+    | {
+          type: 'list';
+          listType: EditorToolbarListType;
+          label: string;
+          icon: EditorToolbarIcon;
+          key?: string;
+          placement?: EditorToolbarItemPlacement;
+      }
+    | {
+          type: 'command';
+          command: EditorToolbarCommand;
+          label: string;
+          icon: EditorToolbarIcon;
+          key?: string;
+          placement?: EditorToolbarItemPlacement;
+      }
+    | {
+          type: 'node';
+          nodeType: string;
+          label: string;
+          icon: EditorToolbarIcon;
+          key?: string;
+          placement?: EditorToolbarItemPlacement;
+      }
+    | {
+          type: 'action';
+          key: string;
+          label: string;
+          icon: EditorToolbarIcon;
+          isActive?: boolean;
+          isDisabled?: boolean;
+          placement?: EditorToolbarItemPlacement;
+      }
+) & {
+    buttonStyle?: EditorToolbarButtonStyle;
+};
+
+/** What a group may contain. Groups do not nest. */
+export type EditorToolbarGroupChildItem = EditorToolbarLeafItem;
+
+/**
+ * Several buttons collapsed behind one — heading levels, say. The group
+ * reports active when any child is active, and disabled when every child is.
+ */
+export interface EditorToolbarGroupItem {
+    type: 'group';
+    /** Identity of the group. Required, unlike a leaf item's key. */
+    key: string;
+    /** Accessible name for the group button. */
+    label: string;
+    icon: EditorToolbarIcon;
+    /** How the children are revealed. Defaults to `'expand'`. */
+    presentation?: EditorToolbarGroupPresentation;
+    placement?: EditorToolbarItemPlacement;
+    buttonStyle?: EditorToolbarButtonStyle;
+    items: readonly EditorToolbarGroupChildItem[];
+}
+
+/**
+ * One entry in `toolbarItems`: a button, a group of buttons, or a separator.
+ * The same list drives the JavaScript `EditorToolbar` and the native keyboard
+ * toolbar.
+ */
+export type EditorToolbarItem =
+    | EditorToolbarLeafItem
+    | EditorToolbarGroupItem
+    | {
+          type: 'separator';
+          key?: string;
+          placement?: EditorToolbarItemPlacement;
+      };
+
+export interface ToolbarButton {
+    key: string;
+    label: string;
+    icon: EditorToolbarIcon;
+    buttonStyle?: EditorToolbarButtonStyle;
+    action: () => void;
+    isActive?: boolean;
+    isDisabled?: boolean;
+    groupKey?: string;
+    placement: EditorToolbarItemPlacement;
+}
+
+export interface ToolbarGroupButton {
+    key: string;
+    label: string;
+    icon: EditorToolbarIcon;
+    buttonStyle?: EditorToolbarButtonStyle;
+    presentation: EditorToolbarGroupPresentation;
+    placement: EditorToolbarItemPlacement;
+    children: readonly ToolbarButton[];
+    isActive: boolean;
+    isDisabled: boolean;
+    isExpanded: boolean;
+    isOpen: boolean;
+}
+
+export interface ToolbarMenuState {
+    groupKey: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+export type ToolbarRenderedItem =
+    | { type: 'separator'; key: string; placement: EditorToolbarItemPlacement }
+    | { type: 'button'; button: ToolbarButton }
+    | { type: 'group'; group: ToolbarGroupButton };
+
+export interface EditorToolbarProps {
+    /** Currently active marks and nodes from the Rust engine. */
+    activeState: ReadonlyActiveState;
+    /** Current undo/redo availability. */
+    historyState: HistoryState;
+    /** Toggle bold mark. */
+    onToggleBold: () => void;
+    /** Toggle italic mark. */
+    onToggleItalic: () => void;
+    /** Toggle underline mark. */
+    onToggleUnderline: () => void;
+    /** Toggle strikethrough mark. */
+    onToggleStrike: () => void;
+    /** Toggle bullet list. */
+    onToggleBulletList?: () => void;
+    /** Toggle blockquote wrapping. */
+    onToggleBlockquote?: () => void;
+    /** Toggle ordered list. */
+    onToggleOrderedList?: () => void;
+    /** Indent the current list item. */
+    onIndentList?: () => void;
+    /** Outdent the current list item. */
+    onOutdentList?: () => void;
+    /** Insert horizontal rule. */
+    onInsertHorizontalRule?: () => void;
+    /** Insert inline hard break. */
+    onInsertLineBreak?: () => void;
+    /** Undo the last operation. */
+    onUndo: () => void;
+    /** Redo the last undone operation. */
+    onRedo: () => void;
+    /** Generic mark toggle handler used by configurable mark buttons. */
+    onToggleMark?: (mark: string) => void;
+    /** Generic list toggle handler used by configurable list buttons. */
+    onToggleListType?: (listType: EditorToolbarListType) => void;
+    /** Generic heading toggle handler used by configurable heading buttons. */
+    onToggleHeading?: (level: EditorToolbarHeadingLevel) => void;
+    /** Generic node insertion handler used by configurable node buttons. */
+    onInsertNodeType?: (nodeType: string) => void;
+    /** Generic command handler used by configurable command buttons. */
+    onRunCommand?: (command: EditorToolbarCommand) => void;
+    /** Generic action handler for arbitrary JS-defined toolbar buttons. */
+    onToolbarAction?: (key: string) => void;
+    /** Link button handler used by first-class link toolbar items. */
+    onRequestLink?: () => void;
+    /** Image button handler used by first-class image toolbar items. */
+    onRequestImage?: () => void;
+    /** Displayed toolbar items, in order. Defaults to the built-in toolbar. */
+    toolbarItems?: readonly EditorToolbarItem[];
+    /** Optional theme overrides for toolbar chrome and button colors. */
+    theme?: EditorToolbarTheme;
+    /** Whether to render the built-in top separator line. */
+    showTopBorder?: boolean;
+    /**
+     * Keep RichTextEditor focused when this toolbar is rendered outside
+     * the editor wrapper. Defaults to true.
+     */
+    preserveEditorFocus?: boolean;
+}