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

package/src/addons.ts

@@ -0,0 +1,311 @@
+import { normalizeEditorAddons, type NormalizedEditorAddons } from './EditorAddonNormalization';
+import type { EditorAddons, CodeHighlightingAddonOptions } from './EditorAddon';
+export { normalizeEditorAddons } from './EditorAddonNormalization';
+export { createMentionsAddon, type EditorAddons } from './EditorAddon';
+import type { EditorMentionTheme } from './EditorTheme';
+import {
+    normalizeEditorMentionTheme,
+    type SerializedEditorMentionTheme,
+} from './EditorMentionThemeNormalization';
+import type { DocumentJSON, ReadonlyActiveState } from './NativeEditorBridge';
+import {
+    buildDocumentFragmentJson,
+    type ResolvedDocumentSchema,
+    type SchemaDefinition,
+    type NodeSpec,
+} from './schemas';
+
+/** One row offered in the mention suggestion list. */
+export interface MentionSuggestion {
+    /** Identity of this suggestion. Must be unique within the offered list. */
+    key: string;
+    /** Primary text shown in the suggestion row. */
+    title: string;
+    /** Secondary text shown in the suggestion row. */
+    subtitle?: string;
+    /** Text rendered in the document once inserted. Defaults to `title`. */
+    label?: string;
+    /** Extra attributes stored on the inserted mention node, e.g. a user id. */
+    attrs?: Record<string, unknown>;
+}
+
+/** The mention query under the caret changed. */
+export interface MentionQueryChangeEvent {
+    /** Text typed after the trigger, without the trigger itself. */
+    query: string;
+    /** Trigger character that opened this query. */
+    trigger: string;
+    /** Engine document positions the mention would replace. */
+    range: {
+        anchor: number;
+        head: number;
+    };
+    /** False once the query closed — supply an empty suggestion list. */
+    isActive: boolean;
+    /** Engine document revision the query was computed against. */
+    documentVersion?: string;
+}
+
+/** A suggestion was inserted into the document. */
+export interface MentionSelectEvent {
+    trigger: string;
+    suggestion: MentionSuggestion;
+    /** The attributes actually written onto the mention node. */
+    attrs: Record<string, unknown>;
+    documentVersion?: string;
+}
+
+/**
+ * A suggestion is about to be inserted. Passed to
+ * {@link MentionsAddonConfig.resolveSelectionAttrs} and
+ * {@link MentionsAddonConfig.resolveTheme} so the host can decide the node's
+ * attributes and styling from live document context.
+ */
+export interface MentionSelectionAttrsEvent {
+    trigger: string;
+    suggestion: MentionSuggestion;
+    /** Attributes resolved so far — the suggestion's own, plus `label` and `mentionSuggestionChar`. */
+    attrs: Record<string, unknown>;
+    /** Mark attributes active at the insertion point. */
+    markAttrs: ReadonlyActiveState['markAttrs'];
+    /** Engine document positions the mention will replace. */
+    range: {
+        anchor: number;
+        head: number;
+    };
+    documentVersion?: string;
+}
+
+/** Payload of {@link MentionsAddonConfig.resolveTheme}, carrying the attributes
+ *  `resolveSelectionAttrs` already resolved. */
+export type MentionThemeResolveEvent = MentionSelectionAttrsEvent;
+
+/**
+ * Mentions for `RichTextEditor`. The schema belongs to the document
+ * handle, so create the handle with {@link withMentionsSchema} applied to
+ * your schema — this config alone does not add the `mention` node.
+ * (`RichTextViewer` adds it for you.)
+ *
+ * The host owns the suggestion list: react to `onQueryChange` by filtering
+ * your own data, then pass the result back through `suggestions`.
+ */
+export interface MentionsAddonConfig {
+    /** Character that opens a mention query. Defaults to `'@'`. */
+    trigger?: string;
+    /** Rows currently offered for the open query. */
+    suggestions?: readonly MentionSuggestion[];
+    /** Default mention styling. See {@link EditorMentionTheme}. */
+    theme?: EditorMentionTheme;
+    /**
+     * Extra attributes merged over the suggestion's own, just before
+     * insertion. Return `null`/`undefined` to keep them unchanged. Throwing
+     * is caught and treated the same way.
+     */
+    resolveSelectionAttrs?: (
+        event: MentionSelectionAttrsEvent
+    ) => Record<string, unknown> | null | undefined;
+    /**
+     * Per-mention styling, stored on the inserted node and used in place of
+     * `theme`. Runs after `resolveSelectionAttrs`. A value that is not a
+     * valid {@link EditorMentionTheme} is dropped rather than written into
+     * the document.
+     */
+    resolveTheme?: (event: MentionThemeResolveEvent) => EditorMentionTheme | null | undefined;
+    /** Called whenever the open query changes, including when it closes. */
+    onQueryChange?: (event: MentionQueryChangeEvent) => void;
+    /** Called after a suggestion has been inserted. */
+    onSelect?: (event: MentionSelectEvent) => void;
+}
+
+export interface SerializedMentionSuggestion {
+    key: string;
+    title: string;
+    subtitle?: string;
+    label: string;
+    attrs: Record<string, unknown>;
+}
+
+export interface SerializedMentionsAddonConfig {
+    trigger: string;
+    theme?: SerializedEditorMentionTheme;
+    resolveSelectionAttrs?: boolean;
+    resolveTheme?: boolean;
+    suggestions: SerializedMentionSuggestion[];
+}
+
+export interface SerializedEditorAddons {
+    mentions?: SerializedMentionsAddonConfig;
+    codeHighlighting?: CodeHighlightingAddonOptions;
+}
+
+/**
+ * The raw addon event the native view emits, before the editor turns it into
+ * the typed {@link MentionsAddonConfig} callbacks. Exported for hosts that
+ * inspect the native stream directly; ordinary use needs `onQueryChange` and
+ * `onSelect` instead.
+ */
+export type EditorAddonEvent =
+    | {
+          type: 'mentionsQueryChange';
+          query: string;
+          trigger: string;
+          range: {
+              anchor: number;
+              head: number;
+          };
+          isActive: boolean;
+          documentVersion?: string;
+      }
+    | {
+          type: 'mentionsSelectRequest';
+          trigger: string;
+          suggestionKey: string;
+          attrs: Record<string, unknown>;
+          range: {
+              anchor: number;
+              head: number;
+          };
+          documentVersion?: string;
+          updateJson?: string;
+      }
+    | {
+          type: 'mentionsSelect';
+          trigger: string;
+          suggestionKey: string;
+          attrs: Record<string, unknown>;
+          documentVersion?: string;
+      };
+
+/** Node name mentions are stored under in the document. */
+export const MENTION_NODE_NAME = 'mention';
+const DEFAULT_MENTION_TRIGGER = '@';
+
+/**
+ * The mention node spec: a void inline node that round-trips arbitrary
+ * app-defined attributes. Add it through {@link withMentionsSchema} rather
+ * than assembling it by hand.
+ */
+export function mentionNodeSpec(): NodeSpec {
+    return {
+        name: MENTION_NODE_NAME,
+        content: '',
+        group: 'inline',
+        role: 'inline',
+        isVoid: true,
+        // Mention nodes round-trip arbitrary app-defined metadata (id, kind,
+        // mentionSuggestionChar, mentionTheme, and anything supplied via
+        // MentionSuggestion.attrs / resolveSelectionAttrs) that this fixed
+        // attrs map cannot enumerate. Opt out of the schema-declared-attrs
+        // filter that Rust's set_json ingestion otherwise applies.
+        allowUndeclaredAttrs: true,
+        attrs: {
+            label: { default: null },
+        },
+    };
+}
+
+/**
+ * Return `schema` with the mention node added, or `schema` unchanged when it
+ * already declares one. Apply it when creating the document handle for an
+ * editor that uses mentions.
+ *
+ * @example
+ * ```ts
+ * createNativeEditorDocumentHandle({
+ *     initialization: { type: 'localEmpty' },
+ *     schema: withMentionsSchema(defaultSchema),
+ * });
+ * ```
+ */
+export function withMentionsSchema(schema: SchemaDefinition): SchemaDefinition {
+    const hasMentionNode = schema.nodes.some((node) => node.name === MENTION_NODE_NAME);
+    if (hasMentionNode) {
+        return schema;
+    }
+
+    return {
+        ...schema,
+        nodes: [...schema.nodes, mentionNodeSpec()],
+    };
+}
+
+export function normalizeNativeEditorAddons(
+    addons?: NormalizedEditorAddons
+): SerializedEditorAddons | undefined {
+    if (!addons?.mentions) {
+        return addons?.codeHighlighting ? { codeHighlighting: addons.codeHighlighting } : undefined;
+    }
+
+    const trigger = addons.mentions.trigger?.trim() || DEFAULT_MENTION_TRIGGER;
+    const suggestions = (addons.mentions.suggestions ?? []).map((suggestion) => {
+        const label = suggestion.label?.trim() || suggestion.title;
+        const attrs = {
+            label,
+            mentionSuggestionChar: trigger,
+            ...(suggestion.attrs ?? {}),
+        };
+
+        return {
+            key: suggestion.key,
+            title: suggestion.title,
+            subtitle: suggestion.subtitle,
+            label,
+            attrs,
+        };
+    });
+
+    return {
+        mentions: {
+            trigger,
+            theme: normalizeEditorMentionTheme(addons.mentions.theme),
+            ...(typeof addons.mentions.resolveSelectionAttrs === 'function'
+                ? { resolveSelectionAttrs: true }
+                : {}),
+            ...(typeof addons.mentions.resolveTheme === 'function' ? { resolveTheme: true } : {}),
+            suggestions,
+        },
+        ...(addons.codeHighlighting ? { codeHighlighting: addons.codeHighlighting } : {}),
+    };
+}
+
+export function serializeEditorAddons(addons?: EditorAddons): string | undefined {
+    return serializeNormalizedEditorAddons(normalizeEditorAddons(addons));
+}
+
+export function serializeNormalizedEditorAddons(
+    addons?: NormalizedEditorAddons
+): string | undefined {
+    const normalized = normalizeNativeEditorAddons(addons);
+    return normalized ? JSON.stringify(normalized) : undefined;
+}
+
+/** Options for {@link buildMentionFragmentJson}. */
+export interface MentionFragmentOptions {
+    /** Append a plain, unmarked space so typing continues after the mention. */
+    trailingSpace?: boolean;
+}
+
+/**
+ * Build a document fragment holding one mention node, ready for
+ * `insertContentJson`. Use it to insert a mention outside the suggestion
+ * flow — from a picker, say.
+ *
+ * @param attrs Attributes for the mention node, e.g. `{ label, id }`.
+ * @param descriptor Document node name to wrap the fragment in. Defaults to `doc`.
+ */
+export function buildMentionFragmentJson(
+    attrs: Record<string, unknown>,
+    descriptor?: Pick<ResolvedDocumentSchema, 'documentNodeName'>,
+    options?: MentionFragmentOptions
+): DocumentJSON {
+    return buildDocumentFragmentJson(
+        [
+            {
+                type: MENTION_NODE_NAME,
+                attrs,
+            },
+            ...(options?.trailingSpace ? [{ type: 'text', text: ' ' }] : []),
+        ],
+        descriptor
+    );
+}

package/src/atomConstants.ts

@@ -0,0 +1,3 @@
+export const DEFAULT_ATOM_CHIP_HEIGHT = 32;
+export const ATOM_NATIVE_ID_PREFIX = 'prose-atom:';
+export const ATOM_CONTENT_NATIVE_ID_PREFIX = 'prose-atom-content:';

package/src/atomInstances.ts

@@ -0,0 +1,123 @@
+import type { Selection } from './NativeEditorBridge';
+
+export { DEFAULT_ATOM_CHIP_HEIGHT } from './atomConstants';
+
+export interface AtomInstance {
+    key: string;
+    hasStableKey: boolean;
+    nodeType: string;
+    attrs: Readonly<Record<string, unknown>>;
+    docPos: number;
+}
+
+export interface AtomInstanceCollection {
+    instanceBlocks: AtomInstance[][];
+    instances: AtomInstance[];
+    hasOnlyStableKeys: boolean;
+}
+
+export const NATIVE_VOID_BLOCK_TYPES: ReadonlySet<string> = new Set([
+    'horizontalRule',
+    'horizontal_rule',
+    'image',
+]);
+
+export type AtomUpdateAttrsErrorCode =
+    | 'not-applicable'
+    | 'stale-revision'
+    | 'not-ready'
+    | 'engine-error';
+
+export class AtomUpdateAttrsError extends Error {
+    readonly code: AtomUpdateAttrsErrorCode;
+
+    constructor(code: AtomUpdateAttrsErrorCode, message: string) {
+        super(message);
+        this.name = 'AtomUpdateAttrsError';
+        this.code = code;
+    }
+}
+
+interface AtomRenderElement {
+    readonly type: string;
+    readonly nodeType?: string;
+    readonly docPos?: number;
+    readonly atomId?: string;
+    readonly attrs?: Readonly<Record<string, unknown>>;
+}
+
+const EMPTY_ATOM_ATTRS: Readonly<Record<string, unknown>> = Object.freeze({});
+
+export function collectAtomInstanceBlocks(
+    renderBlocks: ReadonlyArray<ReadonlyArray<AtomRenderElement>>,
+    registeredTypes: ReadonlySet<string>
+): AtomInstanceCollection {
+    const occurrences = new Map<string, number>();
+    const instanceBlocks: AtomInstance[][] = [];
+    const instances: AtomInstance[] = [];
+    let hasOnlyStableKeys = true;
+    for (const block of renderBlocks) {
+        const blockInstances: AtomInstance[] = [];
+        for (const element of block) {
+            if (
+                element.type !== 'voidBlock' ||
+                typeof element.nodeType !== 'string' ||
+                typeof element.docPos !== 'number'
+            ) {
+                continue;
+            }
+            const occurrence = occurrences.get(element.nodeType) ?? 0;
+            occurrences.set(element.nodeType, occurrence + 1);
+            if (
+                !registeredTypes.has(element.nodeType) &&
+                NATIVE_VOID_BLOCK_TYPES.has(element.nodeType)
+            ) {
+                continue;
+            }
+            const hasStableKey = typeof element.atomId === 'string';
+            const instance = {
+                key: hasStableKey ? element.atomId! : `${element.nodeType}:${occurrence}`,
+                hasStableKey,
+                nodeType: element.nodeType,
+                attrs: element.attrs ?? EMPTY_ATOM_ATTRS,
+                docPos: element.docPos,
+            };
+            hasOnlyStableKeys &&= hasStableKey;
+            blockInstances.push(instance);
+            instances.push(instance);
+        }
+        instanceBlocks.push(blockInstances);
+    }
+    return { instanceBlocks, instances, hasOnlyStableKeys };
+}
+
+export function collectAtomInstances(
+    renderBlocks: ReadonlyArray<ReadonlyArray<AtomRenderElement>>,
+    registeredTypes: ReadonlySet<string>
+): AtomInstance[] {
+    return collectAtomInstanceBlocks(renderBlocks, registeredTypes).instances;
+}
+
+export function applyRenderPatch<Element>(
+    previousBlocks: ReadonlyArray<ReadonlyArray<Element>>,
+    patch: {
+        readonly startIndex: number;
+        readonly deleteCount: number;
+        readonly renderBlocks: ReadonlyArray<ReadonlyArray<Element>>;
+    }
+): Array<ReadonlyArray<Element>> {
+    return [
+        ...previousBlocks.slice(0, patch.startIndex),
+        ...patch.renderBlocks,
+        ...previousBlocks.slice(patch.startIndex + patch.deleteCount),
+    ];
+}
+
+export function atomSelected(selection: Selection, docPos: number): boolean {
+    if (selection.type === 'all') return true;
+    if (selection.type === 'node') return selection.pos === docPos;
+    const { anchor, head } = selection;
+    if (anchor == null || head == null) return false;
+    const [from, to] = anchor <= head ? [anchor, head] : [head, anchor];
+    return from <= docPos && docPos + 1 <= to;
+}

package/src/atomPolicy.ts

@@ -0,0 +1,47 @@
+export const RESERVED_WIRE_NODE_TYPES: ReadonlySet<string> = new Set([
+    '__opaque',
+    '__opaque_json',
+    '__skip',
+]);
+
+export const ATOM_HTML_IDENTIFIER = /^[a-z][a-z0-9-]*$/;
+
+export const ATOM_HTML_DENIED_TAGS: ReadonlySet<string> = new Set([
+    'script',
+    'style',
+    'iframe',
+    'object',
+    'embed',
+    'link',
+    'meta',
+    'base',
+    'title',
+    'head',
+    'html',
+    'body',
+    'form',
+    'textarea',
+    'select',
+    'option',
+    'button',
+    'area',
+    'br',
+    'col',
+    'hr',
+    'img',
+    'input',
+    'param',
+    'source',
+    'track',
+    'wbr',
+]);
+
+export const ATOM_HTML_DENIED_ATTRS: ReadonlySet<string> = new Set([
+    'style',
+    'srcdoc',
+    'href',
+    'src',
+    'srcset',
+    'action',
+    'formaction',
+]);

package/src/atomUpdates.ts

@@ -0,0 +1,52 @@
+import type { AtomAttrsUpdate } from './atoms';
+import { AtomUpdateAttrsError } from './atomInstances';
+
+function copyJson(value: unknown, ancestors = new Set<object>()): unknown {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+    if (typeof value === 'number' && Number.isFinite(value)) return value;
+    if (typeof value !== 'object' || ancestors.has(value) || ancestors.size > 128) {
+        throw new AtomUpdateAttrsError(
+            'not-applicable',
+            'Atom attributes must contain finite JSON values.'
+        );
+    }
+    if (
+        !Array.isArray(value) &&
+        Object.getPrototypeOf(value) !== Object.prototype &&
+        Object.getPrototypeOf(value) !== null
+    ) {
+        throw new AtomUpdateAttrsError(
+            'not-applicable',
+            'Atom attributes must contain plain JSON objects.'
+        );
+    }
+    ancestors.add(value);
+    const result = Array.isArray(value)
+        ? Array.from(value, (entry) => copyJson(entry, ancestors))
+        : Object.fromEntries(
+              Object.entries(value).map(([key, entry]) => [key, copyJson(entry, ancestors)])
+          );
+    ancestors.delete(value);
+    return Object.freeze(result);
+}
+
+export function resolveAtomAttrsUpdate(
+    attrs: Readonly<Record<string, unknown>>,
+    update: AtomAttrsUpdate
+): Record<string, unknown> {
+    let current = copyJson(attrs) as Record<string, unknown>;
+    let patch: Record<string, unknown> = {};
+    for (const entry of Array.isArray(update) ? update : [update]) {
+        const value: unknown = typeof entry === 'function' ? entry(current) : entry;
+        if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+            throw new AtomUpdateAttrsError(
+                'not-applicable',
+                'Atom updates must return an attribute object.'
+            );
+        }
+        const partial = copyJson(value) as Record<string, unknown>;
+        patch = { ...patch, ...partial };
+        current = Object.freeze({ ...current, ...partial });
+    }
+    return patch;
+}