@datalayer/lexical-loro 0.2.5 → 1.0.0

package/lib/collab/loro/sync/SyncLoroToLexical.js

@@ -1,100 +0,0 @@
-/*
- * Copyright (c) 2023-2025 Datalayer, Inc.
- * Distributed under the terms of the MIT License.
- */
-import { $addUpdateTag, $createParagraphNode, $getRoot, $getSelection, $isRangeSelection, $setSelection, SKIP_COLLAB_TAG, SKIP_SCROLL_INTO_VIEW_TAG } from 'lexical';
-import { $syncLocalCursorPosition, syncCursorPositions, syncLexicalSelectionToLoro } from './SyncCursors';
-// Import the new diff integrators
-import { TreeIntegrator } from '../integrators/TreeIntegrator';
-import { MapIntegrator } from '../integrators/MapIntegrator';
-import { ListIntegrator } from '../integrators/ListIntegrator';
-import { TextIntegrator } from '../integrators/TextIntegrator';
-import { CounterIntegrator } from '../integrators/CounterIntegrator';
-import { $moveSelectionToPreviousNode, doesSelectionNeedRecovering } from '../utils/Utils';
-// Create singleton instances of the diff integrators (created once, reused across calls)
-const treeIntegrator = new TreeIntegrator();
-const mapIntegrator = new MapIntegrator();
-const listIntegrator = new ListIntegrator();
-const textIntegrator = new TextIntegrator();
-const counterIntegrator = new CounterIntegrator();
-export function syncLoroToLexical(binding, provider, eventBatch, isFromUndoManger, syncCursorPositionsFn = syncCursorPositions) {
-    const editor = binding.editor;
-    const currentEditorState = editor._editorState;
-    // Batch all events into a single discrete editor.update() to avoid race conditions
-    // Using discrete: true ensures immediate synchronous commit before other operations
-    binding.editor.update(() => {
-        // Clear selection temporarily to avoid cursor position conflicts during text updates
-        const currentSelection = $getSelection();
-        if (currentSelection) {
-            $setSelection(null);
-        }
-        // Process Loro events and apply them to Lexical using the appropriate integrators
-        eventBatch.events.forEach((event, index) => {
-            switch (event.diff.type) {
-                case 'tree':
-                    // Call internal method that doesn't wrap in editor.update()
-                    treeIntegrator.integrateInternal(event.diff, binding, provider);
-                    break;
-                case 'map':
-                    // Call internal method that doesn't wrap in editor.update()
-                    if (event.target) {
-                        mapIntegrator.integrateWithContextInternal(event.diff, event.target, binding, provider);
-                    }
-                    else {
-                        mapIntegrator.integrateInternal(event.diff, binding, provider);
-                    }
-                    break;
-                case 'list':
-                    listIntegrator.integrateInternal(event.diff, binding, provider);
-                    break;
-                case 'text':
-                    textIntegrator.integrateInternal(event.diff, binding, provider);
-                    break;
-                case 'counter':
-                    counterIntegrator.integrateInternal(event.diff, binding, provider);
-                    break;
-                default:
-                    throw new Error(`Unsupported event diff type: ${event.diff.type}. Supported types are: 'tree', 'map', 'list', 'text', 'counter'.`);
-            }
-        });
-        const selection = $getSelection();
-        if ($isRangeSelection(selection)) {
-            if (doesSelectionNeedRecovering(selection)) {
-                const prevSelection = currentEditorState._selection;
-                if ($isRangeSelection(prevSelection)) {
-                    $syncLocalCursorPosition(binding, provider);
-                    if (doesSelectionNeedRecovering(selection)) {
-                        // If the selected node is deleted, move the selection to the previous or parent node.
-                        const anchorNodeKey = selection.anchor.key;
-                        $moveSelectionToPreviousNode(anchorNodeKey, currentEditorState);
-                    }
-                }
-                syncLexicalSelectionToLoro(binding, provider, prevSelection, $getSelection());
-            }
-            else {
-                $syncLocalCursorPosition(binding, provider);
-            }
-        }
-        if (!isFromUndoManger) {
-            // If it is an external change, we don't want the current scroll position to get changed
-            // since the user might've intentionally scrolled somewhere else in the document.
-            $addUpdateTag(SKIP_SCROLL_INTO_VIEW_TAG);
-        }
-    }, {
-        onUpdate: () => {
-            syncCursorPositionsFn(binding, provider);
-            // If there was a collision on the top level paragraph
-            // we need to re-add a paragraph. To ensure this insertion properly syncs with other clients,
-            // it must be placed outside of the update block above that has tags 'collaboration' or 'historic'.
-            editor.update(() => {
-                if ($getRoot().getChildrenSize() === 0) {
-                    $getRoot().append($createParagraphNode());
-                }
-            });
-        },
-        //    discrete: true,
-        skipTransforms: true,
-        //    tag: isFromUndoManger ? HISTORIC_TAG : COLLABORATION_TAG,
-        tag: SKIP_COLLAB_TAG
-    });
-}

package/lib/collab/loro/types/LexicalNodeData.d.ts

@@ -1,32 +0,0 @@
-import { LexicalNode } from 'lexical';
-/**
- * Data structure stored in Loro tree node data
- */
-export interface LexicalNodeData {
-    lexicalNode: LexicalNode;
-}
-/**
- * Helper functions for working with LexicalNodeData
- */
-export declare class LexicalNodeDataHelper {
-    /**
-     * Create LexicalNodeData from a Lexical node
-     */
-    static create(lexicalNode: LexicalNode): LexicalNodeData;
-    /**
-     * Serialize LexicalNodeData for storage in Loro
-     */
-    static serialize(data: LexicalNodeData): string;
-    /**
-     * Deserialize LexicalNodeData from Loro storage
-     */
-    static deserialize(serialized: string): LexicalNodeData | null;
-    /**
-     * Extract the LexicalNode from LexicalNodeData
-     */
-    static getLexicalNode(data: LexicalNodeData): LexicalNode;
-    /**
-     * Get node type from LexicalNodeData
-     */
-    static getNodeType(data: LexicalNodeData): string;
-}

package/lib/collab/loro/types/LexicalNodeData.js

@@ -1,75 +0,0 @@
-/*
- * Copyright (c) 2023-2025 Datalayer, Inc.
- * Distributed under the terms of the MIT License.
- */
-/**
- * Helper functions for working with LexicalNodeData
- */
-export class LexicalNodeDataHelper {
-    /**
-     * Create LexicalNodeData from a Lexical node
-     */
-    static create(lexicalNode) {
-        return {
-            lexicalNode
-        };
-    }
-    /**
-     * Serialize LexicalNodeData for storage in Loro
-     */
-    static serialize(data) {
-        try {
-            return JSON.stringify({
-                lexicalNode: data.lexicalNode.exportJSON()
-            });
-        }
-        catch (error) {
-            console.warn('Failed to serialize LexicalNodeData:', error);
-            return JSON.stringify({
-                lexicalNode: {
-                    type: data.lexicalNode.getType(),
-                    key: data.lexicalNode.getKey()
-                }
-            });
-        }
-    }
-    /**
-     * Deserialize LexicalNodeData from Loro storage
-     */
-    static deserialize(serialized) {
-        try {
-            const parsed = JSON.parse(serialized);
-            // Validate that we have the expected structure
-            if (!parsed || !parsed.lexicalNode) {
-                console.warn('Invalid LexicalNodeData structure:', parsed);
-                return null;
-            }
-            return {
-                lexicalNode: parsed.lexicalNode
-            };
-        }
-        catch (error) {
-            console.warn('Failed to deserialize LexicalNodeData:', error);
-            return null;
-        }
-    }
-    /**
-     * Extract the LexicalNode from LexicalNodeData
-     */
-    static getLexicalNode(data) {
-        return data.lexicalNode;
-    }
-    /**
-     * Get node type from LexicalNodeData
-     */
-    static getNodeType(data) {
-        // Handle both actual Lexical nodes (with getType method) and deserialized JSON objects
-        if (typeof data.lexicalNode.getType === 'function') {
-            return data.lexicalNode.getType();
-        }
-        else {
-            // Fallback to direct property access for deserialized JSON
-            return data.lexicalNode.__type || 'unknown';
-        }
-    }
-}

package/lib/collab/loro/useCollaboration.d.ts

@@ -1,12 +0,0 @@
-import * as React from 'react';
-import type { JSX } from 'react';
-import type { LexicalEditor } from 'lexical';
-import { InitialEditorStateType } from '@lexical/react/LexicalComposer';
-import { LoroDoc } from 'loro-crdt';
-import type { Provider } from './State';
-import { Binding } from './Bindings';
-import { SyncCursorPositionsFn } from './sync/SyncCursors';
-export type CursorsContainerRef = React.MutableRefObject<HTMLElement | null>;
-export declare function useCollaboration(editor: LexicalEditor, id: string, provider: Provider, docMap: Map<string, LoroDoc>, name: string, color: string, shouldBootstrap: boolean, binding: Binding, setDoc: React.Dispatch<React.SetStateAction<LoroDoc | undefined>>, cursorsContainerRef?: CursorsContainerRef, initialEditorState?: InitialEditorStateType, awarenessData?: object, syncCursorPositionsFn?: SyncCursorPositionsFn, onInitialization?: (isInitialized: boolean) => void): JSX.Element;
-export declare function useFocusTracking(editor: LexicalEditor, provider: Provider, name: string, color: string, awarenessData?: object): void;
-export declare function useHistory(editor: LexicalEditor, binding: Binding): () => void;

package/lib/collab/loro/useCollaboration.js

@@ -1,260 +0,0 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-/*
- * Copyright (c) 2023-2025 Datalayer, Inc.
- * Distributed under the terms of the MIT License.
- */
-import * as React from 'react';
-import { useCallback, useEffect, useMemo, useRef } from 'react';
-import { createPortal } from 'react-dom';
-import { mergeRegister } from '@lexical/utils';
-import { $getRoot, BLUR_COMMAND, CAN_REDO_COMMAND, CAN_UNDO_COMMAND, COMMAND_PRIORITY_EDITOR, FOCUS_COMMAND, HISTORY_MERGE_TAG, REDO_COMMAND, SKIP_COLLAB_TAG, UNDO_COMMAND, } from 'lexical';
-import { CONNECTED_COMMAND, createUndoManager, initLocalState, setLocalStateFocus, TOGGLE_CONNECT_COMMAND, } from './State';
-import { syncLexicalToLoro } from './sync/SyncLexicalToLoro';
-import { syncLoroToLexical } from './sync/SyncLoroToLexical';
-import { syncCursorPositions } from './sync/SyncCursors';
-export function useCollaboration(editor, id, provider, docMap, name, color, shouldBootstrap, binding, setDoc, cursorsContainerRef, initialEditorState, awarenessData, syncCursorPositionsFn = syncCursorPositions, onInitialization) {
-    const isReloadingDoc = useRef(false);
-    const connect = useCallback(() => provider.connect(), [provider]);
-    const disconnect = useCallback(() => {
-        try {
-            provider.disconnect();
-        }
-        catch (e) {
-            // Do nothing
-        }
-    }, [provider]);
-    useEffect(() => {
-        const { awareness } = provider;
-        const onStatus = ({ status }) => {
-            editor.dispatchCommand(CONNECTED_COMMAND, status === 'connected');
-        };
-        const onSync = (isSynced) => {
-            if (shouldBootstrap &&
-                isSynced &&
-                isReloadingDoc.current === false) {
-                initializeEditor(editor, initialEditorState);
-                // Call the initialization callback after initializing the editor
-                if (onInitialization) {
-                    onInitialization(true);
-                }
-            }
-            isReloadingDoc.current = false;
-        };
-        const onAwarenessUpdate = () => {
-            syncCursorPositionsFn(binding, provider);
-        };
-        initLocalState(provider, name, color, document.activeElement === editor.getRootElement(), awarenessData || {});
-        const onProviderDocReload = (doc) => {
-            clearEditorSkipCollab(editor, binding);
-            setDoc(doc);
-            docMap.set(id, doc);
-            isReloadingDoc.current = true;
-        };
-        provider.on('reload', onProviderDocReload);
-        provider.on('status', onStatus);
-        provider.on('sync', onSync);
-        awareness.on('update', onAwarenessUpdate);
-        const onLoroUpdates = (eventBatch) => {
-            // Only skip if the origin is from this specific editor's changes.
-            // We set 'lexical-edit' as origin when making changes from this editor.
-            // So we should skip only if the origin is 'lexical-edit' (our own changes).
-            if (eventBatch.origin !== binding.doc.peerIdStr) {
-                // Check if this change is from the undo manager
-                // const isFromUndoManger = origin instanceof UndoManager;
-                const isFromUndoManager = false;
-                syncLoroToLexical(binding, provider, eventBatch, isFromUndoManager, syncCursorPositionsFn);
-            }
-        };
-        // This updates the local editor state when we receive updates from other clients.
-        const unsubscribe = binding.doc.subscribe(onLoroUpdates);
-        const removeListener = editor.registerUpdateListener((update) => {
-            if (update.tags.has(SKIP_COLLAB_TAG) === false) {
-                syncLexicalToLoro(binding, provider, update);
-            }
-        });
-        const connectionPromise = connect();
-        return () => {
-            if (isReloadingDoc.current === false) {
-                if (connectionPromise) {
-                    connectionPromise.then(disconnect);
-                }
-                else {
-                    // Workaround for race condition in StrictMode. It's possible there
-                    // is a different race for the above case where connect returns a
-                    // promise, but we don't have an example of that in-repo.
-                    // It's possible that there is a similar issue with
-                    // TOGGLE_CONNECT_COMMAND below when the provider connect returns a
-                    // promise.
-                    // https://github.com/facebook/lexical/issues/6640
-                    disconnect();
-                }
-            }
-            provider.off('sync', onSync);
-            provider.off('status', onStatus);
-            provider.off('reload', onProviderDocReload);
-            awareness.off('update', onAwarenessUpdate);
-            // Unsubscribe from Loro document changes
-            unsubscribe?.();
-            docMap.delete(id);
-            removeListener();
-        };
-    }, [
-        binding,
-        color,
-        connect,
-        disconnect,
-        docMap,
-        editor,
-        id,
-        initialEditorState,
-        name,
-        provider,
-        shouldBootstrap,
-        awarenessData,
-        setDoc,
-        syncCursorPositionsFn,
-        onInitialization,
-    ]);
-    const cursorsContainer = useMemo(() => {
-        const ref = (element) => {
-            binding.cursorsContainer = element;
-        };
-        return createPortal(_jsx("div", { ref: ref, style: {
-                position: 'fixed',
-                top: 0,
-                left: 0,
-                width: '100vw',
-                height: '100vh',
-                pointerEvents: 'none',
-                zIndex: 1000,
-                overflow: 'visible',
-            } }), (cursorsContainerRef && cursorsContainerRef.current) || document.body);
-    }, [binding, cursorsContainerRef]);
-    useEffect(() => {
-        return editor.registerCommand(TOGGLE_CONNECT_COMMAND, (payload) => {
-            const shouldConnect = payload;
-            if (shouldConnect) {
-                connect();
-            }
-            else {
-                disconnect();
-            }
-            return true;
-        }, COMMAND_PRIORITY_EDITOR);
-    }, [connect, disconnect, editor]);
-    return cursorsContainer;
-}
-export function useFocusTracking(editor, provider, name, color, awarenessData) {
-    useEffect(() => {
-        return mergeRegister(editor.registerCommand(FOCUS_COMMAND, () => {
-            setLocalStateFocus(provider, name, color, true, awarenessData || {});
-            return false;
-        }, COMMAND_PRIORITY_EDITOR), editor.registerCommand(BLUR_COMMAND, () => {
-            setLocalStateFocus(provider, name, color, false, awarenessData || {});
-            return false;
-        }, COMMAND_PRIORITY_EDITOR));
-    }, [color, editor, name, provider, awarenessData]);
-}
-export function useHistory(editor, binding) {
-    const undoManager = useMemo(() => createUndoManager(binding), [binding]);
-    useEffect(() => {
-        const undo = () => {
-            undoManager.undo();
-        };
-        const redo = () => {
-            undoManager.redo();
-        };
-        return mergeRegister(editor.registerCommand(UNDO_COMMAND, () => {
-            undo();
-            return true;
-        }, COMMAND_PRIORITY_EDITOR), editor.registerCommand(REDO_COMMAND, () => {
-            redo();
-            return true;
-        }, COMMAND_PRIORITY_EDITOR));
-    });
-    const clearHistory = useCallback(() => {
-        undoManager.clear();
-    }, [undoManager]);
-    // Exposing undo and redo states
-    React.useEffect(() => {
-        const updateUndoRedoStates = () => {
-            editor.dispatchCommand(CAN_UNDO_COMMAND, undoManager.canUndo());
-            editor.dispatchCommand(CAN_REDO_COMMAND, undoManager.canRedo());
-        };
-        // Initial state update
-        updateUndoRedoStates();
-        // Loro UndoManager doesn't have event listeners like YJS
-        // We would need to check state periodically or after operations
-        // For now, update after each operation
-        return () => {
-            // No cleanup needed for Loro UndoManager events
-        };
-    }, [editor, undoManager]);
-    return clearHistory;
-}
-function initializeEditor(editor, initialEditorState) {
-    editor.update(() => {
-        const root = $getRoot();
-        if (root.isEmpty()) {
-            if (initialEditorState) {
-                switch (typeof initialEditorState) {
-                    case 'string': {
-                        const parsedEditorState = editor.parseEditorState(initialEditorState);
-                        editor.setEditorState(parsedEditorState, {
-                            tag: HISTORY_MERGE_TAG,
-                        });
-                        break;
-                    }
-                    case 'object': {
-                        editor.setEditorState(initialEditorState, {
-                            tag: HISTORY_MERGE_TAG,
-                        });
-                        break;
-                    }
-                    case 'function': {
-                        editor.update(() => {
-                            const root1 = $getRoot();
-                            if (root1.isEmpty()) {
-                                initialEditorState(editor);
-                            }
-                        }, { tag: HISTORY_MERGE_TAG });
-                        break;
-                    }
-                }
-            }
-        }
-    }, { tag: HISTORY_MERGE_TAG });
-}
-function clearEditorSkipCollab(editor, binding) {
-    // reset editor state
-    editor.update(() => {
-        const root = $getRoot();
-        root.clear();
-        root.select();
-    }, {
-        tag: SKIP_COLLAB_TAG,
-    });
-    if (binding.cursors == null) {
-        return;
-    }
-    const cursors = binding.cursors;
-    if (cursors == null) {
-        return;
-    }
-    const cursorsContainer = binding.cursorsContainer;
-    if (cursorsContainer == null) {
-        return;
-    }
-    // reset cursors in dom
-    const cursorsArr = Array.from(cursors.values());
-    for (let i = 0; i < cursorsArr.length; i++) {
-        const cursor = cursorsArr[i];
-        const selection = cursor.selection;
-        if (selection && selection.selections != null) {
-            const selections = selection.selections;
-            for (let j = 0; j < selections.length; j++) {
-                cursorsContainer.removeChild(selections[i]);
-            }
-        }
-    }
-}

package/lib/collab/loro/utils/InitialContent.d.ts

@@ -1,64 +0,0 @@
-import { LoroDoc } from 'loro-crdt';
-/**
- * Initial Lexical JSON structure that matches what the Python server uses
- */
-export declare const INITIAL_LEXICAL_JSON: {
-    root: {
-        children: ({
-            children: {
-                detail: number;
-                format: number;
-                mode: string;
-                style: string;
-                text: string;
-                type: string;
-                version: number;
-            }[];
-            direction: any;
-            format: string;
-            indent: number;
-            type: string;
-            version: number;
-            tag: string;
-            textFormat?: undefined;
-            textStyle?: undefined;
-        } | {
-            children: {
-                detail: number;
-                format: number;
-                mode: string;
-                style: string;
-                text: string;
-                type: string;
-                version: number;
-            }[];
-            direction: any;
-            format: string;
-            indent: number;
-            type: string;
-            version: number;
-            textFormat: number;
-            textStyle: string;
-            tag?: undefined;
-        })[];
-        direction: any;
-        format: string;
-        indent: number;
-        type: string;
-        version: number;
-    };
-};
-/**
- * Initialize a new Loro document with the initial Lexical content
- * This ensures consistent starting state across all clients
- */
-export declare function initializeLoroDocWithLexicalContent(doc: LoroDoc): void;
-/**
- * Check if a Loro document is empty (has no tree content)
- */
-export declare function isLoroDocumentEmpty(doc: LoroDoc): boolean;
-/**
- * Check if a Loro document should be initialized (more robust check)
- * This helps prevent race conditions where multiple clients try to initialize
- */
-export declare function shouldInitializeLoroDoc(doc: LoroDoc): boolean;

package/lib/collab/loro/utils/InitialContent.js

@@ -1,113 +0,0 @@
-/*
- * Copyright (c) 2023-2025 Datalayer, Inc.
- * Distributed under the terms of the MIT License.
- */
-import { lexicalToLoroTree } from './LexicalToLoro';
-/**
- * Initial Lexical JSON structure that matches what the Python server uses
- */
-export const INITIAL_LEXICAL_JSON = {
-    "root": {
-        "children": [
-            {
-                "children": [
-                    {
-                        "detail": 0,
-                        "format": 0,
-                        "mode": "normal",
-                        "style": "",
-                        "text": "Lexical with Loro",
-                        "type": "text",
-                        "version": 1
-                    }
-                ],
-                "direction": null,
-                "format": "",
-                "indent": 0,
-                "type": "heading",
-                "version": 1,
-                "tag": "h1"
-            },
-            {
-                "children": [
-                    {
-                        "detail": 0,
-                        "format": 0,
-                        "mode": "normal",
-                        "style": "",
-                        "text": "Type something...",
-                        "type": "text",
-                        "version": 1
-                    }
-                ],
-                "direction": null,
-                "format": "",
-                "indent": 0,
-                "type": "paragraph",
-                "version": 1,
-                "textFormat": 0,
-                "textStyle": ""
-            }
-        ],
-        "direction": null,
-        "format": "",
-        "indent": 0,
-        "type": "root",
-        "version": 1
-    }
-};
-/**
- * Initialize a new Loro document with the initial Lexical content
- * This ensures consistent starting state across all clients
- */
-export function initializeLoroDocWithLexicalContent(doc) {
-    const tree = doc.getTree('tree');
-    tree.enableFractionalIndex(0.001);
-    // Convert the initial Lexical JSON to Loro tree structure
-    lexicalToLoroTree(INITIAL_LEXICAL_JSON, tree);
-}
-/**
- * Check if a Loro document is empty (has no tree content)
- */
-export function isLoroDocumentEmpty(doc) {
-    const tree = doc.getTree('tree');
-    try {
-        // Get all root nodes
-        const roots = tree.roots();
-        // Also check if the document has any nodes at all
-        const allNodes = tree.nodes();
-        return roots.length === 0 && allNodes.length === 0;
-    }
-    catch (error) {
-        // If there's an error accessing roots, consider it empty
-        return true;
-    }
-}
-/**
- * Check if a Loro document should be initialized (more robust check)
- * This helps prevent race conditions where multiple clients try to initialize
- */
-export function shouldInitializeLoroDoc(doc) {
-    const tree = doc.getTree('tree');
-    try {
-        const allNodes = tree.nodes();
-        const roots = tree.roots();
-        // Only initialize if there are truly no nodes
-        const isEmpty = allNodes.length === 0;
-        // Additional check: look for any existing root nodes with our content
-        if (!isEmpty) {
-            // Check if any root has the expected initial structure
-            for (const root of roots) {
-                const data = Object.fromEntries(root.data.entries());
-                if (data.elementType === 'root') {
-                    return false;
-                }
-            }
-        }
-        return isEmpty;
-    }
-    catch (error) {
-        console.warn('Error checking if doc should be initialized:', error);
-        return false; // Don't initialize if there's an error
-    }
-}

package/lib/collab/loro/utils/LexicalToLoro.d.ts

@@ -1,18 +0,0 @@
-import { LoroTree, TreeID } from 'loro-crdt';
-/**
- * Utility to convert Lexical JSON structure to Loro tree
- */
-interface LexicalNodeJSON {
-    type: string;
-    children?: LexicalNodeJSON[];
-    [key: string]: any;
-}
-interface LexicalJSON {
-    root: LexicalNodeJSON;
-}
-/**
- * Convert a Lexical JSON structure to a Loro tree
- * This is used to initialize a Loro tree from existing Lexical content
- */
-export declare function lexicalToLoroTree(lexicalJson: string | LexicalJSON, tree: LoroTree): TreeID;
-export {};