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

package/dist/useRichTextEditorCommands.js

@@ -0,0 +1,299 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useRichTextEditorCommands = useRichTextEditorCommands;
+const react_1 = require("react");
+const atomInstances_1 = require("./atomInstances");
+const atomUpdates_1 = require("./atomUpdates");
+const NativeEditorBoundaryError_1 = require("./NativeEditorBoundaryError");
+const schemas_1 = require("./schemas");
+const ExternalTextComposition_1 = require("./ExternalTextComposition");
+const RichTextEditorSerialization_1 = require("./RichTextEditorSerialization");
+function useRichTextEditorCommands(context) {
+    const { editable, documentHandle, latestRevisionRef, atomStateRef, bridge, refreshAtomsFromUpdate, document, afterLocalEngineMutation, pushEngineUpdateToView, nativeViewRef, activeStateRef, documentDescriptor, onRequestLinkRef, selectionRef, onRequestImageRef, ref, externalCompositionManager, } = context;
+    const editableRef = (0, react_1.useRef)(editable);
+    editableRef.current = editable;
+    const atomOwnerRef = (0, react_1.useRef)(documentHandle);
+    atomOwnerRef.current = documentHandle;
+    const updateAtomAttrs = (0, react_1.useCallback)(async (atomKey, nodeType, expectedDocPos, expectedDocumentVersion, hasStableKey, update) => {
+        const baseDocumentRevision = latestRevisionRef.current;
+        if (documentHandle.isDestroyed || baseDocumentRevision == null) {
+            throw new atomInstances_1.AtomUpdateAttrsError('not-ready', 'The editor is not ready');
+        }
+        if (!editableRef.current) {
+            throw new atomInstances_1.AtomUpdateAttrsError('not-applicable', 'The editor is not editable');
+        }
+        const instance = atomStateRef.current.instances.find((candidate) => candidate.key === atomKey && candidate.nodeType === nodeType);
+        if (instance == null ||
+            (!hasStableKey &&
+                (atomStateRef.current.documentVersion !== expectedDocumentVersion ||
+                    instance.docPos !== expectedDocPos))) {
+            throw new atomInstances_1.AtomUpdateAttrsError('not-applicable', 'The atom no longer exists in the document');
+        }
+        const attrs = (0, atomUpdates_1.resolveAtomAttrsUpdate)(instance.attrs, update);
+        let outcome;
+        try {
+            outcome = bridge.applyCommand({
+                baseDocumentRevision,
+                command: { type: 'updateNodeAttrs', docPos: instance.docPos, attrs },
+            });
+        }
+        catch (error) {
+            if ((0, RichTextEditorSerialization_1.isRevisionMismatchError)(error)) {
+                refreshAtomsFromUpdate(bridge.renderUpdate());
+                document.refresh();
+                throw new atomInstances_1.AtomUpdateAttrsError('stale-revision', 'The atom changed before its attributes were updated');
+            }
+            if (error instanceof NativeEditorBoundaryError_1.NativeEditorErrorBase &&
+                (error.code === 'ENGINE_NOT_READY' ||
+                    error.code === 'ENGINE_DESTROYING' ||
+                    error.code === 'ENGINE_DESTROYED')) {
+                throw new atomInstances_1.AtomUpdateAttrsError('not-ready', 'The editor is not ready');
+            }
+            throw new atomInstances_1.AtomUpdateAttrsError('engine-error', error instanceof Error ? error.message : 'The atom update failed');
+        }
+        if (outcome.type === 'notApplicable') {
+            refreshAtomsFromUpdate(bridge.renderUpdate());
+            document.refresh();
+            throw new atomInstances_1.AtomUpdateAttrsError('not-applicable', 'The atom no longer exists at this document position');
+        }
+        if (outcome.type !== 'transaction') {
+            throw new atomInstances_1.AtomUpdateAttrsError('engine-error', 'Unexpected atom update outcome');
+        }
+        afterLocalEngineMutation();
+    }, [afterLocalEngineMutation, bridge, document, documentHandle, refreshAtomsFromUpdate]);
+    const runAtomAction = (0, react_1.useCallback)(async (owner, instance, documentVersion, action) => {
+        if (owner !== atomOwnerRef.current ||
+            documentHandle.isDestroyed ||
+            latestRevisionRef.current == null)
+            throw new atomInstances_1.AtomUpdateAttrsError('not-ready', 'The editor is not ready.');
+        if (action === 'delete' && !editableRef.current)
+            throw new atomInstances_1.AtomUpdateAttrsError('not-applicable', 'The editor is not editable.');
+        const current = atomStateRef.current.instances.find((candidate) => candidate.key === instance.key && candidate.nodeType === instance.nodeType);
+        if (!current ||
+            (!instance.hasStableKey &&
+                (documentVersion !== atomStateRef.current.documentVersion ||
+                    current.docPos !== instance.docPos)))
+            throw new atomInstances_1.AtomUpdateAttrsError('not-applicable', 'The atom no longer exists.');
+        try {
+            const baseDocumentRevision = latestRevisionRef.current;
+            const selection = bridge.setSelection({
+                baseDocumentRevision,
+                selection: {
+                    type: 'atom',
+                    docPos: current.docPos,
+                    edge: action === 'select' || action === 'delete' ? 'node' : action,
+                },
+            });
+            if (selection.type !== 'transaction')
+                throw new atomInstances_1.AtomUpdateAttrsError('not-applicable', 'The atom could not be selected.');
+            if (action === 'delete') {
+                const outcome = bridge.applyCommand({
+                    baseDocumentRevision,
+                    command: { type: 'deleteBackward' },
+                });
+                if (outcome.type !== 'transaction')
+                    throw new atomInstances_1.AtomUpdateAttrsError('not-applicable', 'The atom could not be deleted.');
+                afterLocalEngineMutation();
+            }
+            else {
+                pushEngineUpdateToView();
+                document.refresh();
+                if (action !== 'select')
+                    nativeViewRef.current?.focus?.();
+            }
+        }
+        catch (error) {
+            if (error instanceof atomInstances_1.AtomUpdateAttrsError)
+                throw error;
+            if ((0, RichTextEditorSerialization_1.isRevisionMismatchError)(error)) {
+                refreshAtomsFromUpdate(bridge.renderUpdate());
+                document.refresh();
+                throw new atomInstances_1.AtomUpdateAttrsError('stale-revision', 'The document changed before the atom action.');
+            }
+            throw new atomInstances_1.AtomUpdateAttrsError('engine-error', error instanceof Error ? error.message : String(error));
+        }
+    }, [
+        afterLocalEngineMutation,
+        bridge,
+        document,
+        documentHandle,
+        pushEngineUpdateToView,
+        refreshAtomsFromUpdate,
+    ]);
+    const runEngineMutation = (0, react_1.useCallback)((invoke) => {
+        if (!editableRef.current) {
+            throw new NativeEditorBoundaryError_1.NativeEditorOperationError({
+                domain: 'operation',
+                code: 'MUTATION_REJECTED',
+                message: 'NativeRichTextEditor: mutation rejected while editable is false',
+                requestId: null,
+                operationIndex: null,
+                limit: null,
+                actual: null,
+                details: null,
+            });
+        }
+        const baseRevision = latestRevisionRef.current;
+        if (baseRevision == null) {
+            // Engine not ready (room awaiting the server document).
+            return;
+        }
+        try {
+            invoke(baseRevision);
+        }
+        catch (error) {
+            if ((0, RichTextEditorSerialization_1.isRevisionMismatchError)(error)) {
+                // Refresh from the engine; NEVER retry against guessed
+                // positions (native adapter parity).
+                document.refresh();
+                return;
+            }
+            throw error;
+        }
+        afterLocalEngineMutation();
+    }, [afterLocalEngineMutation, document]);
+    const applyEngineCommand = (0, react_1.useCallback)((command) => {
+        runEngineMutation((baseDocumentRevision) => bridge.applyCommand({ command, baseDocumentRevision }));
+    }, [bridge, runEngineMutation]);
+    const commandToggleMark = (0, react_1.useCallback)((markType) => applyEngineCommand({ type: 'toggleMark', markType }), [applyEngineCommand]);
+    const commandSetLink = (0, react_1.useCallback)((href) => {
+        const trimmedHref = href.trim();
+        if (!trimmedHref)
+            return;
+        applyEngineCommand({
+            type: 'setMark',
+            markType: 'link',
+            attrs: { href: trimmedHref },
+        });
+    }, [applyEngineCommand]);
+    const commandUnsetLink = (0, react_1.useCallback)(() => applyEngineCommand({ type: 'unsetMark', markType: 'link' }), [applyEngineCommand]);
+    const commandToggleBlockquote = (0, react_1.useCallback)(() => applyEngineCommand({ type: 'toggleBlockquote' }), [applyEngineCommand]);
+    const commandToggleHeading = (0, react_1.useCallback)((level) => applyEngineCommand({ type: 'toggleHeading', level }), [applyEngineCommand]);
+    const commandToggleList = (0, react_1.useCallback)((listType) => {
+        if (activeStateRef.current.nodes[listType] === true) {
+            applyEngineCommand({ type: 'unwrapFromList' });
+            return;
+        }
+        applyEngineCommand({
+            type: 'wrapInList',
+            listType,
+            itemType: listType === 'taskList'
+                ? 'taskItem'
+                : listType === 'bullet_list' || listType === 'ordered_list'
+                    ? 'list_item'
+                    : 'listItem',
+        });
+    }, [applyEngineCommand]);
+    const commandIndentListItem = (0, react_1.useCallback)(() => applyEngineCommand({ type: 'indentListItem' }), [applyEngineCommand]);
+    const commandOutdentListItem = (0, react_1.useCallback)(() => applyEngineCommand({ type: 'outdentListItem' }), [applyEngineCommand]);
+    const commandInsertNode = (0, react_1.useCallback)((nodeType) => applyEngineCommand({ type: 'insertNode', nodeType }), [applyEngineCommand]);
+    const commandInsertImage = (0, react_1.useCallback)((src, attrs) => {
+        applyEngineCommand({
+            type: 'insertContentJson',
+            json: (0, schemas_1.buildImageFragmentJson)({ src, ...attrs }, documentDescriptor),
+        });
+    }, [applyEngineCommand, documentDescriptor]);
+    const commandInsertText = (0, react_1.useCallback)((text) => {
+        if (!text)
+            return;
+        runEngineMutation((baseDocumentRevision) => bridge.applyInput({ text, baseDocumentRevision }));
+    }, [bridge, runEngineMutation]);
+    const commandInsertContentHtml = (0, react_1.useCallback)((html) => applyEngineCommand({ type: 'insertContentHtml', html }), [applyEngineCommand]);
+    const commandInsertContentJson = (0, react_1.useCallback)((doc) => applyEngineCommand({ type: 'insertContentJson', json: doc }), [applyEngineCommand]);
+    const openLinkRequest = (0, react_1.useCallback)(() => {
+        const linkAttrs = activeStateRef.current.markAttrs?.link;
+        onRequestLinkRef.current?.({
+            href: typeof linkAttrs?.href === 'string' ? linkAttrs.href : undefined,
+            isActive: activeStateRef.current.marks.link === true,
+            selection: selectionRef.current,
+            setLink: commandSetLink,
+            unsetLink: commandUnsetLink,
+        });
+    }, [commandSetLink, commandUnsetLink]);
+    const openImageRequest = (0, react_1.useCallback)(() => {
+        onRequestImageRef.current?.({
+            selection: selectionRef.current,
+            insertImage: commandInsertImage,
+        });
+    }, [commandInsertImage]);
+    (0, react_1.useImperativeHandle)(ref, () => ({
+        focus() {
+            nativeViewRef.current?.focus?.();
+        },
+        blur() {
+            nativeViewRef.current?.blur?.();
+        },
+        supportsExternalTextComposition() {
+            return externalCompositionManager.supports();
+        },
+        beginExternalTextComposition(options) {
+            if (!editable) {
+                return Promise.reject((0, ExternalTextComposition_1.createExternalCompositionLifecycleError)('EXTERNAL_COMPOSITION_UNAVAILABLE', 'The editor view is not editable'));
+            }
+            return externalCompositionManager.begin(options);
+        },
+        toggleMark: commandToggleMark,
+        setLink: commandSetLink,
+        unsetLink: commandUnsetLink,
+        toggleBlockquote: commandToggleBlockquote,
+        toggleHeading: commandToggleHeading,
+        toggleList: commandToggleList,
+        indentListItem: commandIndentListItem,
+        outdentListItem: commandOutdentListItem,
+        insertNode: commandInsertNode,
+        insertImage: commandInsertImage,
+        insertText: commandInsertText,
+        insertContentHtml: commandInsertContentHtml,
+        insertContentJson: commandInsertContentJson,
+        setContent: document.setContent,
+        setContentJson: document.setContentJson,
+        clearContent: document.clearContent,
+        getContent: document.getContent,
+        getContentJson: document.getContentJson,
+        getIsEmpty: document.getIsEmpty,
+        getTextContent: document.getTextContent,
+        async getCaretRect() {
+            const nativeView = nativeViewRef.current;
+            if (!nativeView?.getCaretRect)
+                return null;
+            const raw = await Promise.resolve(nativeView.getCaretRect());
+            return (0, RichTextEditorSerialization_1.parseCaretRectJson)(raw);
+        },
+        undo: document.undo,
+        redo: document.redo,
+        canUndo: document.canUndo,
+        canRedo: document.canRedo,
+    }), [
+        document,
+        commandToggleMark,
+        commandSetLink,
+        commandUnsetLink,
+        commandToggleBlockquote,
+        commandToggleHeading,
+        commandToggleList,
+        commandIndentListItem,
+        commandOutdentListItem,
+        commandInsertNode,
+        commandInsertImage,
+        commandInsertText,
+        commandInsertContentHtml,
+        commandInsertContentJson,
+        editable,
+        externalCompositionManager,
+    ]);
+    return {
+        openLinkRequest,
+        openImageRequest,
+        editableRef,
+        runAtomAction,
+        updateAtomAttrs,
+        atomOwnerRef,
+        commandToggleMark,
+        commandToggleList,
+        commandToggleHeading,
+        commandToggleBlockquote,
+        commandInsertNode,
+        commandIndentListItem,
+        commandOutdentListItem,
+    };
+}

package/dist/useRichTextEditorEvents.d.ts

@@ -0,0 +1,18 @@
+import { type NativeSyntheticEvent } from 'react-native';
+import { useRichTextEditorState } from './useRichTextEditorState';
+import { useRichTextEditorUpdates } from './useRichTextEditorUpdates';
+import { useRichTextEditorCommands } from './useRichTextEditorCommands';
+import { type NativeUpdateEvent, type NativeErrorEvent, type NativeExternalTextCompositionEvent, type NativeSelectionEvent, type NativeFocusEvent, type NativeContentHeightEvent, type NativeAtomLayoutEvent, type NativeToolbarActionEvent } from './RichTextEditorNativeTypes';
+export declare function useRichTextEditorEvents(context: Pick<ReturnType<typeof useRichTextEditorState>, 'editorId' | 'documentHandle' | 'lastAcceptedNativeCommitRevisionRef' | 'lastNativeDrivenRevisionRef' | 'document' | 'onLocalCommitRef' | 'nativeErrorBindingRef' | 'nativeErrorBinding' | 'externalCompositionManager' | 'scalarSelectionRef' | 'selectionRef' | 'onSelectionChangeRef' | 'isFocusedRef' | 'toolbarFrameOwnerId' | 'setIsFocused' | 'onFocusRef' | 'onBlurRef' | 'heightBehavior' | 'setAutoGrowHeight' | 'setAtomContentWidth' | 'setNativeAtomViewport' | 'setAtomPositions' | 'onToolbarActionRef'> & Pick<ReturnType<typeof useRichTextEditorUpdates>, 'refreshAtomsFromUpdate' | 'applyTypedUpdateState' | 'applyUpdateState' | 'updateAtomSelection'> & Pick<ReturnType<typeof useRichTextEditorCommands>, 'openLinkRequest' | 'openImageRequest'>): {
+    isForThisEditor: (payload: {
+        editorId: string;
+    }) => boolean;
+    handleEditorUpdate: (event: NativeSyntheticEvent<NativeUpdateEvent>) => void;
+    handleEditorError: (event: NativeSyntheticEvent<NativeErrorEvent>) => void;
+    handleExternalTextCompositionEnd: (event: NativeSyntheticEvent<NativeExternalTextCompositionEvent>) => void;
+    handleSelectionChange: (event: NativeSyntheticEvent<NativeSelectionEvent>) => void;
+    handleFocusChange: (event: NativeSyntheticEvent<NativeFocusEvent>) => void;
+    handleContentHeightChange: (event: NativeSyntheticEvent<NativeContentHeightEvent>) => void;
+    handleAtomLayout: (event: NativeSyntheticEvent<NativeAtomLayoutEvent>) => void;
+    handleToolbarAction: (event: NativeSyntheticEvent<NativeToolbarActionEvent>) => void;
+};

package/dist/useRichTextEditorEvents.js

@@ -0,0 +1,216 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useRichTextEditorEvents = useRichTextEditorEvents;
+const react_1 = require("react");
+const react_native_1 = require("react-native");
+const NativeEditorBridge_1 = require("./NativeEditorBridge");
+const EditorToolbar_1 = require("./EditorToolbar");
+const RichTextEditorSerialization_1 = require("./RichTextEditorSerialization");
+function useRichTextEditorEvents(context) {
+    const { editorId, documentHandle, lastAcceptedNativeCommitRevisionRef, lastNativeDrivenRevisionRef, refreshAtomsFromUpdate, applyTypedUpdateState, document, onLocalCommitRef, nativeErrorBindingRef, nativeErrorBinding, externalCompositionManager, scalarSelectionRef, applyUpdateState, selectionRef, updateAtomSelection, onSelectionChangeRef, isFocusedRef, toolbarFrameOwnerId, setIsFocused, onFocusRef, onBlurRef, heightBehavior, setAutoGrowHeight, setAtomContentWidth, setNativeAtomViewport, setAtomPositions, openLinkRequest, openImageRequest, onToolbarActionRef, } = context;
+    const isForThisEditor = (0, react_1.useCallback)((payload) => payload.editorId === editorId, [editorId]);
+    const handleEditorUpdate = (0, react_1.useCallback)((event) => {
+        if (documentHandle.isDestroyed)
+            return;
+        const accepted = (0, RichTextEditorSerialization_1.acceptNativeCommitPayload)(event.nativeEvent, documentHandle.editorId, lastAcceptedNativeCommitRevisionRef.current);
+        if (accepted == null)
+            return;
+        // Record both native-scoped revisions before any observable
+        // state/callback/refresh work. This makes duplicate delivery and
+        // the handle's same-revision signal deterministic.
+        lastAcceptedNativeCommitRevisionRef.current = accepted.documentRevision;
+        lastNativeDrivenRevisionRef.current = accepted.documentRevision;
+        refreshAtomsFromUpdate(accepted.snapshot);
+        applyTypedUpdateState(accepted.snapshot);
+        // The adapter already committed; re-read for content callbacks.
+        document.refresh();
+        onLocalCommitRef.current?.();
+    }, [applyTypedUpdateState, document, documentHandle, refreshAtomsFromUpdate]);
+    const admitNativeBindingEvent = (0, react_1.useCallback)((payload) => {
+        if (!(0, RichTextEditorSerialization_1.isRecord)(payload))
+            return null;
+        const currentBinding = nativeErrorBindingRef.current;
+        if (currentBinding !== nativeErrorBinding ||
+            !currentBinding.mounted ||
+            currentBinding.generation !== nativeErrorBinding.generation ||
+            currentBinding.handle !== nativeErrorBinding.handle ||
+            currentBinding.editorId !== nativeErrorBinding.editorId ||
+            nativeErrorBinding.handle.isDestroyed) {
+            return null;
+        }
+        const presentedEditorId = payload.editorId;
+        if (typeof presentedEditorId !== 'string' ||
+            (0, NativeEditorBridge_1.normalizeNativeEditorV2DecimalId)(presentedEditorId) !== presentedEditorId ||
+            presentedEditorId !== nativeErrorBinding.editorId) {
+            return null;
+        }
+        return currentBinding;
+    }, [nativeErrorBinding]);
+    const handleEditorError = (0, react_1.useCallback)((event) => {
+        const payload = event?.nativeEvent;
+        const binding = admitNativeBindingEvent(payload);
+        if (binding == null || !(0, RichTextEditorSerialization_1.isRecord)(payload))
+            return;
+        binding.handle.bridge._emitAutonomousError(payload.error);
+    }, [admitNativeBindingEvent]);
+    const handleExternalTextCompositionEnd = (0, react_1.useCallback)((event) => {
+        const payload = event?.nativeEvent;
+        const binding = admitNativeBindingEvent(payload);
+        if (binding == null || !(0, RichTextEditorSerialization_1.isRecord)(payload))
+            return;
+        if (typeof payload.resultJson !== 'string')
+            return;
+        try {
+            externalCompositionManager.handleNativeEnd(binding.editorId, payload.resultJson);
+        }
+        catch (error) {
+            binding.handle.bridge._emitAutonomousError((0, RichTextEditorSerialization_1.externalCompositionErrorPayload)(error));
+        }
+    }, [admitNativeBindingEvent, externalCompositionManager]);
+    const handleSelectionChange = (0, react_1.useCallback)((event) => {
+        if (documentHandle.isDestroyed || !isForThisEditor(event.nativeEvent))
+            return;
+        const { anchor, head, stateJson } = event.nativeEvent;
+        scalarSelectionRef.current = { anchor, head };
+        let selection = { type: 'text', anchor, head };
+        const parsed = applyUpdateState(stateJson);
+        const parsedSelection = (0, RichTextEditorSerialization_1.parseSelectionFromUpdate)(parsed?.selection);
+        if (parsedSelection) {
+            selection = parsedSelection;
+        }
+        selectionRef.current = selection;
+        updateAtomSelection(selection);
+        onSelectionChangeRef.current?.(selection);
+    }, [applyUpdateState, documentHandle, isForThisEditor, updateAtomSelection]);
+    const handleFocusChange = (0, react_1.useCallback)((event) => {
+        if (documentHandle.isDestroyed || !isForThisEditor(event.nativeEvent))
+            return;
+        const focused = event.nativeEvent.isFocused;
+        const wasFocused = isFocusedRef.current;
+        isFocusedRef.current = focused;
+        (0, EditorToolbar_1.setActiveEditorToolbarFrameOwnerForEditor)(toolbarFrameOwnerId, focused);
+        setIsFocused(focused);
+        if (focused && !wasFocused) {
+            onFocusRef.current?.();
+        }
+        else if (!focused && wasFocused) {
+            onBlurRef.current?.();
+        }
+    }, [documentHandle, isForThisEditor, toolbarFrameOwnerId]);
+    const handleContentHeightChange = (0, react_1.useCallback)((event) => {
+        if (documentHandle.isDestroyed || !isForThisEditor(event.nativeEvent))
+            return;
+        if (heightBehavior !== 'autoGrow')
+            return;
+        const density = react_native_1.Platform.OS === 'android' ? react_native_1.PixelRatio.get() : 1;
+        const nextHeight = Math.ceil(event.nativeEvent.contentHeight / density);
+        if (!(nextHeight > 0))
+            return;
+        setAutoGrowHeight((prev) => (prev === nextHeight ? prev : nextHeight));
+    }, [documentHandle, heightBehavior, isForThisEditor]);
+    const handleAtomLayout = (0, react_1.useCallback)((event) => {
+        if (documentHandle.isDestroyed || !isForThisEditor(event.nativeEvent))
+            return;
+        const width = event.nativeEvent.width;
+        if (!Number.isFinite(width) || width < 0)
+            return;
+        setAtomContentWidth((current) => (current === width ? current : width));
+        const viewport = event.nativeEvent.viewport;
+        if (viewport &&
+            Number.isFinite(viewport.y) &&
+            Number.isFinite(viewport.height) &&
+            viewport.height >= 0) {
+            setNativeAtomViewport((previous) => previous?.y === viewport.y && previous.height === viewport.height
+                ? previous
+                : viewport);
+        }
+        const positions = event.nativeEvent.positions;
+        if (!Array.isArray(positions))
+            return;
+        const next = new Map();
+        for (const position of positions) {
+            if (typeof position?.key !== 'string' ||
+                !Number.isFinite(position.x) ||
+                !Number.isFinite(position.y) ||
+                (position.hostX !== undefined && !Number.isFinite(position.hostX)) ||
+                (position.hostY !== undefined && !Number.isFinite(position.hostY)) ||
+                (position.width !== undefined &&
+                    (!Number.isFinite(position.width) || position.width < 0))) {
+                continue;
+            }
+            next.set(position.key, position);
+        }
+        setAtomPositions((current) => {
+            if (current.size !== next.size)
+                return next;
+            for (const [key, position] of next) {
+                const previous = current.get(key);
+                if (previous?.x !== position.x ||
+                    previous.hostX !== position.hostX ||
+                    previous.hostY !== position.hostY ||
+                    previous.y !== position.y ||
+                    previous.height !== position.height ||
+                    previous.width !== position.width)
+                    return next;
+            }
+            return current;
+        });
+    }, [documentHandle, isForThisEditor]);
+    const handleToolbarAction = (0, react_1.useCallback)((event) => {
+        if (documentHandle.isDestroyed || !isForThisEditor(event.nativeEvent))
+            return;
+        const { key, updateJson, stateJson, documentRevision } = event.nativeEvent;
+        // A toolbar event carrying update data is a native commit. It
+        // must satisfy the same atomic admission path as typing; a pure
+        // action (link/image/custom key) has no commit to refresh.
+        if (updateJson != null || documentRevision != null) {
+            if (typeof updateJson === 'string' && typeof documentRevision === 'string') {
+                const accepted = (0, RichTextEditorSerialization_1.acceptNativeCommitPayload)({
+                    editorId: event.nativeEvent.editorId,
+                    documentRevision,
+                    updateJson,
+                }, documentHandle.editorId, lastAcceptedNativeCommitRevisionRef.current);
+                if (accepted != null) {
+                    lastAcceptedNativeCommitRevisionRef.current = accepted.documentRevision;
+                    lastNativeDrivenRevisionRef.current = accepted.documentRevision;
+                    refreshAtomsFromUpdate(accepted.snapshot);
+                    applyTypedUpdateState(accepted.snapshot);
+                    document.refresh();
+                    onLocalCommitRef.current?.();
+                }
+            }
+        }
+        else if (typeof stateJson === 'string') {
+            applyUpdateState(stateJson);
+        }
+        if (key === RichTextEditorSerialization_1.LINK_TOOLBAR_ACTION_KEY) {
+            openLinkRequest();
+            return;
+        }
+        if (key === RichTextEditorSerialization_1.IMAGE_TOOLBAR_ACTION_KEY) {
+            openImageRequest();
+            return;
+        }
+        onToolbarActionRef.current?.(key);
+    }, [
+        applyTypedUpdateState,
+        applyUpdateState,
+        document,
+        documentHandle,
+        isForThisEditor,
+        openImageRequest,
+        openLinkRequest,
+        refreshAtomsFromUpdate,
+    ]);
+    return {
+        isForThisEditor,
+        handleEditorUpdate,
+        handleEditorError,
+        handleExternalTextCompositionEnd,
+        handleSelectionChange,
+        handleFocusChange,
+        handleContentHeightChange,
+        handleAtomLayout,
+        handleToolbarAction,
+    };
+}

package/dist/useRichTextEditorMentions.d.ts

@@ -0,0 +1,11 @@
+import { type EditorMentionTheme } from './EditorTheme';
+import { type NativeSyntheticEvent } from 'react-native';
+import { useRichTextEditorState } from './useRichTextEditorState';
+import { useRichTextEditorCommands } from './useRichTextEditorCommands';
+import { useRichTextEditorUpdates } from './useRichTextEditorUpdates';
+import { useRichTextEditorEvents } from './useRichTextEditorEvents';
+import { type NativeAddonEvent } from './RichTextEditorNativeTypes';
+export declare function useRichTextEditorMentions(context: Pick<ReturnType<typeof useRichTextEditorState>, 'addonsRef' | 'bridge' | 'documentHandle' | 'currentPushedUpdateEditorIdRef' | 'documentDescriptor' | 'latestRevisionRef' | 'document' | 'setMentionQuery' | 'mentionQuery' | 'addons' | 'editable' | 'isFocused' | 'activeStateRef' | 'toolbarFrameOwnerId'> & Pick<ReturnType<typeof useRichTextEditorCommands>, 'editableRef'> & Pick<ReturnType<typeof useRichTextEditorUpdates>, 'afterLocalEngineMutation'> & Pick<ReturnType<typeof useRichTextEditorEvents>, 'isForThisEditor'>): {
+    mentionSuggestionTheme: EditorMentionTheme | undefined;
+    handleAddonEvent: (event: NativeSyntheticEvent<NativeAddonEvent>) => void;
+};