@datalayer/lexical-loro 1.0.2 → 1.0.5

package/lib/collab/loro/nodes/NodeFactory.js

@@ -0,0 +1,80 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the MIT License.
+ */
+import { invariant } from '../utils/Invariant';
+/**
+ * Resolve lexical data from Loro, handling Loro container objects.
+ * When a JS object is stored in a LoroMap, Loro may return a LoroMap
+ * container internally. This helper ensures we always get a plain JS object.
+ */
+function resolveLexicalData(raw) {
+    if (raw && typeof raw === 'object' && typeof raw.toJSON === 'function') {
+        return raw.toJSON();
+    }
+    return raw;
+}
+/**
+ * Factory function to create Lexical nodes from Loro TreeID.
+ *
+ * Uses the registered node's static `importJSON()` method, which is the
+ * canonical Lexical API for restoring nodes from serialized data. This works
+ * generically for ALL node types — built-in (paragraph, heading, table,
+ * list, quote, code…), decorator (excalidraw, image, counter…), and any
+ * externally-defined custom nodes (e.g. JupyterCellNode) as long as they
+ * are registered with the editor and implement the standard `importJSON`
+ * static method required by Lexical's serialization contract.
+ */
+export function createLexicalNodeFromLoro(treeId, loroTree, binding, parentKey, nodeDataFromDiff) {
+    // Get node data from Loro tree. A create op for a tree node that does not
+    // exist is a real inconsistency.
+    invariant(loroTree.has(treeId), 'NodeFactory: TreeID not present in Loro tree', { treeId });
+    const treeNode = loroTree.getNodeByID(treeId);
+    // First try nodeData passed from TreeDiff integrator (has immediate lexical data)
+    let lexicalData = resolveLexicalData(nodeDataFromDiff?.lexical);
+    // Fallback to tree node data
+    if (!lexicalData) {
+        lexicalData = resolveLexicalData(treeNode?.data.get('lexical'));
+    }
+    if (!lexicalData || typeof lexicalData !== 'object') {
+        // Last resort: reconstruct a minimal serialization from elementType metadata.
+        const fallbackType = nodeDataFromDiff?.elementType ||
+            treeNode?.data.get('elementType') ||
+            treeNode?.data.get('nodeType');
+        invariant(typeof fallbackType === 'string' && fallbackType.length > 0, 'NodeFactory: no lexical data or elementType for TreeID', { treeId });
+        lexicalData = { type: fallbackType, version: 1 };
+    }
+    const nodeType = lexicalData.type || lexicalData.__type;
+    invariant(!!nodeType, 'NodeFactory: no type field in lexical data for TreeID', { treeId });
+    // Get the registered node class from the editor.
+    const registeredNodes = binding.editor._nodes;
+    const nodeInfo = registeredNodes.get(nodeType);
+    invariant(nodeInfo != null, 'NodeFactory: node type is not registered in the editor', { treeId, nodeType });
+    // ---------- Generic creation via importJSON ----------
+    // Every Lexical node class must implement the static `importJSON` method.
+    // Using it guarantees that:
+    //   • Constructor parameters are handled correctly (heading tag, excalidraw
+    //     data, JupyterCellNode code/outputs, …)
+    //   • Node state (Lexical 0.35+ `createState` / `$config`) is restored
+    //   • Base properties (format, indent, direction, style, mode, detail, …)
+    //     are applied via the chained `updateFromJSON` call
+    // This removes the need for any node-type-specific branching.
+    const serializedData = { ...lexicalData };
+    // Ensure required serialization fields.
+    if (!serializedData.type) {
+        serializedData.type = nodeType;
+    }
+    if (serializedData.version === undefined) {
+        serializedData.version = 1;
+    }
+    // Provide an empty children array for element-type nodes whose children are
+    // managed as separate Loro tree nodes (importJSON does not recurse into
+    // children — that is handled by TreeIntegrator).
+    if (!('children' in serializedData)) {
+        serializedData.children = [];
+    }
+    // Every registered Lexical node implements importJSON. If it throws, the
+    // serialized data is malformed — surface it instead of silently substituting
+    // a blank node via a constructor fallback (which hides the real problem).
+    return nodeInfo.klass.importJSON(serializedData);
+}

package/lib/collab/loro/nodes/NodesMapper.d.ts

@@ -0,0 +1,120 @@
+import { LoroTree, LoroTreeNode, TreeID } from 'loro-crdt';
+import { LexicalNode, NodeKey, EditorState } from 'lexical';
+import { Binding } from '../Bindings';
+/**
+ * Bidirectional mapping between Lexical NodeKeys and Loro TreeIDs
+ */
+export declare class NodeMapper {
+    private lexicalToLoro;
+    private loroToLexical;
+    private tree;
+    constructor(binding: Binding);
+    /**
+     * Create a bidirectional mapping between Lexical NodeKey and Loro TreeID
+     */
+    private createMapping;
+    /**
+     * Remove bidirectional mapping
+     */
+    private removeMapping;
+    /**
+     * Get Loro TreeNode based on Lexical NodeKey
+     * If the node doesn't exist, create it with proper parent-child relationship
+     */
+    getLoroNodeByLexicalKey(nodeKey: NodeKey, lexicalNode?: LexicalNode, parentTreeID?: TreeID, index?: number): LoroTreeNode;
+    /**
+     * Get Lexical NodeKey based on Loro TreeID
+     * If the node doesn't exist in Lexical, it needs to be created externally
+     */
+    getLexicalKeyByLoroId(treeId: TreeID): NodeKey | null;
+    /**
+     * Get Lexical Node from EditorState based on Loro TreeID
+     */
+    getLexicalNodeByLoroId(treeId: TreeID, editorState: EditorState): LexicalNode | null;
+    /**
+     * Get Lexical parent node key for a Loro TreeID
+     * Returns null if no parent or if parent not found in Lexical
+     * Note: This method needs the LoroTree API to be clarified for parent relationships
+     */
+    getLexicalParentByLoroId(treeId: TreeID, loroTree: LoroTree): NodeKey | null;
+    /**
+     * Manually set bidirectional mapping between Lexical NodeKey and Loro TreeID
+     */
+    setMapping(nodeKey: NodeKey, treeId: TreeID): void;
+    /**
+     * Create a new Loro TreeNode and establish mapping
+     */
+    private createLoroNode;
+    /**
+     * Update the mapping when a node is moved or modified
+     */
+    updateMapping(oldNodeKey: NodeKey, newNodeKey: NodeKey): void;
+    /**
+     * Remove mapping when a node is deleted (also deletes from Loro tree).
+     * Use this on the ORIGINATING side (propagation) where the local peer
+     * is actively deleting a node.
+     */
+    deleteMapping(nodeKey: NodeKey): void;
+    /**
+     * Remove bidirectional mapping WITHOUT deleting from the Loro tree.
+     * Use this on the INTEGRATION side (receiving remote events) where the
+     * Loro tree has already been updated by the remote peer — we only need
+     * to clean up the local key↔TreeID association.
+     */
+    removeMappingForKey(nodeKey: NodeKey): void;
+    /**
+     * Get TreeID by Lexical NodeKey (without creating if not found)
+     */
+    getTreeIDByLexicalKey(nodeKey: NodeKey): TreeID | undefined;
+    /**
+     * Check if a mapping exists for a Lexical NodeKey
+     */
+    hasLexicalMapping(nodeKey: NodeKey): boolean;
+    /**
+     * Check if a mapping exists for a Loro TreeID
+     */
+    hasLoroMapping(treeId: TreeID): boolean;
+    /**
+     * Get all current mappings (for debugging)
+     */
+    getAllMappings(): {
+        lexicalToLoro: Map<NodeKey, TreeID>;
+        loroToLexical: Map<TreeID, NodeKey>;
+    };
+    /**
+     * Clear all mappings (useful for testing or reset)
+     */
+    clearMappings(): void;
+    /**
+     * Synchronize existing tree nodes with Lexical editor state
+     * This should be called during initialization to establish mappings
+     *
+     * Note: Since lexicalKey is no longer persisted in tree node data,
+     * this method now relies on the TreeIntegrator to create mappings
+     * as nodes are integrated from Loro tree operations.
+     */
+    syncExistingNodes(editorState: EditorState): void;
+}
+/**
+ * Initialize the global node mapper
+ */
+export declare function initializeNodeMapper(binding: Binding): NodeMapper;
+/**
+ * Get the global node mapper instance
+ */
+export declare function getNodeMapper(): NodeMapper;
+/**
+ * Utility functions for common operations
+ */
+/**
+ * Get Loro TreeNode by Lexical NodeKey (using global mapper)
+ */
+export declare function getLoroNodeByLexicalKey(nodeKey: NodeKey, lexicalNode?: LexicalNode, parentTreeID?: TreeID, index?: number): LoroTreeNode;
+/**
+ * Get Lexical NodeKey by Loro TreeID (using global mapper)
+ */
+export declare function getLexicalKeyByLoroId(treeId: TreeID): NodeKey | null;
+/**
+ * Get Lexical Node by Loro TreeID (using global mapper)
+ */
+export declare function getLexicalNodeByLoroId(treeId: TreeID, editorState: EditorState): LexicalNode | null;

package/lib/collab/loro/nodes/NodesMapper.js

@@ -0,0 +1,289 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the MIT License.
+ */
+import { invariant } from '../utils/Invariant';
+/**
+ * Bidirectional mapping between Lexical NodeKeys and Loro TreeIDs
+ */
+export class NodeMapper {
+    // Maps Lexical NodeKey to Loro TreeID
+    lexicalToLoro = new Map();
+    // Maps Loro TreeID to Lexical NodeKey
+    loroToLexical = new Map();
+    tree;
+    constructor(binding) {
+        this.tree = binding.tree;
+    }
+    /**
+     * Create a bidirectional mapping between Lexical NodeKey and Loro TreeID
+     */
+    createMapping(nodeKey, treeId) {
+        this.lexicalToLoro.set(nodeKey, treeId);
+        this.loroToLexical.set(treeId, nodeKey);
+    }
+    /**
+     * Remove bidirectional mapping
+     */
+    removeMapping(nodeKey, treeId) {
+        this.lexicalToLoro.delete(nodeKey);
+        this.loroToLexical.delete(treeId);
+    }
+    /**
+     * Get Loro TreeNode based on Lexical NodeKey
+     * If the node doesn't exist, create it with proper parent-child relationship
+     */
+    getLoroNodeByLexicalKey(nodeKey, lexicalNode, parentTreeID, index) {
+        // Check if mapping already exists
+        const existingTreeID = this.lexicalToLoro.get(nodeKey);
+        if (existingTreeID && this.tree.has(existingTreeID)) {
+            return this.tree.getNodeByID(existingTreeID);
+        }
+        // Get parent TreeID from Lexical node if not provided
+        if (!parentTreeID && lexicalNode) {
+            const lexicalParent = lexicalNode.getParent();
+            if (lexicalParent) {
+                const parentKey = lexicalParent.getKey();
+                parentTreeID = this.lexicalToLoro.get(parentKey);
+                // If parent doesn't exist in Loro, create it first
+                if (!parentTreeID) {
+                    const parentLoroNode = this.getLoroNodeByLexicalKey(parentKey, lexicalParent, undefined, undefined);
+                    parentTreeID = parentLoroNode.id;
+                }
+            }
+        }
+        // Get index from Lexical node if not provided
+        if (index === undefined && lexicalNode) {
+            index = lexicalNode.getIndexWithinParent();
+        }
+        // Create new tree node if it doesn't exist
+        const newTreeID = this.createLoroNode(nodeKey, lexicalNode, parentTreeID, index);
+        return this.tree.getNodeByID(newTreeID);
+    }
+    /**
+     * Get Lexical NodeKey based on Loro TreeID
+     * If the node doesn't exist in Lexical, it needs to be created externally
+     */
+    getLexicalKeyByLoroId(treeId) {
+        // Check if mapping exists
+        const existingNodeKey = this.loroToLexical.get(treeId);
+        if (existingNodeKey) {
+            return existingNodeKey;
+        }
+        // If no mapping exists, we can't create a Lexical node here
+        // The caller should integrate Lexical node creation
+        return null;
+    }
+    /**
+     * Get Lexical Node from EditorState based on Loro TreeID
+     */
+    getLexicalNodeByLoroId(treeId, editorState) {
+        const nodeKey = this.getLexicalKeyByLoroId(treeId);
+        if (!nodeKey) {
+            return null;
+        }
+        return editorState._nodeMap.get(nodeKey) || null;
+    }
+    /**
+     * Get Lexical parent node key for a Loro TreeID
+     * Returns null if no parent or if parent not found in Lexical
+     * Note: This method needs the LoroTree API to be clarified for parent relationships
+     */
+    getLexicalParentByLoroId(treeId, loroTree) {
+        // TODO: Implement once LoroTree parent API is confirmed
+        // For now, we'll rely on the bidirectional mapping without tree traversal
+        return null;
+    }
+    /**
+     * Manually set bidirectional mapping between Lexical NodeKey and Loro TreeID
+     */
+    setMapping(nodeKey, treeId) {
+        this.lexicalToLoro.set(nodeKey, treeId);
+        this.loroToLexical.set(treeId, nodeKey);
+    }
+    /**
+     * Create a new Loro TreeNode and establish mapping
+     */
+    createLoroNode(nodeKey, lexicalNode, parentTreeID, index) {
+        const insertionIndex = index;
+        // Loro requires the insertion index to be within [0, children.length]. An
+        // out-of-range index means the position was computed against stale/unsynced
+        // siblings; surface it instead of silently clamping (which would drop the
+        // node at the wrong position and hide the real ordering bug).
+        if (insertionIndex !== undefined) {
+            const parentNode = parentTreeID !== undefined ? this.tree.getNodeByID(parentTreeID) : null;
+            const childrenLength = parentNode
+                ? (parentNode.children()?.length ?? 0)
+                : this.tree.roots().length;
+            invariant(insertionIndex >= 0 && insertionIndex <= childrenLength, 'createLoroNode: insertion index out of range', { nodeKey, parentTreeID, insertionIndex, childrenLength });
+        }
+        // Create the tree node first
+        const treeNode = this.tree.createNode(parentTreeID, insertionIndex);
+        // Get the TreeID from the created node
+        const treeId = treeNode.id;
+        // A requested parent must actually become this node's parent. If it does
+        // not, the CRDT structure diverges from Lexical — surface it.
+        if (parentTreeID) {
+            const actualParent = treeNode.parent();
+            invariant(actualParent != null && actualParent.id === parentTreeID, 'createLoroNode: parent relationship not established', { nodeKey, expected: parentTreeID, actual: actualParent?.id ?? null });
+        }
+        // Store basic metadata
+        treeNode.data.set('createdAt', Date.now());
+        // Store complete lexical node data if lexical node is provided
+        if (lexicalNode) {
+            try {
+                const lexicalNodeJSON = lexicalNode.exportJSON();
+                // Remove all key-related fields to avoid duplication (TreeID serves as the key)
+                if ('key' in lexicalNodeJSON || '__key' in lexicalNodeJSON || 'lexicalKey' in lexicalNodeJSON) {
+                    const { key, __key, lexicalKey, children, ...cleanedData } = lexicalNodeJSON;
+                    treeNode.data.set('lexical', cleanedData);
+                }
+                else {
+                    const { children, ...cleanedData } = lexicalNodeJSON;
+                    treeNode.data.set('lexical', cleanedData);
+                }
+            }
+            catch (error) {
+                console.warn('Failed to export lexical node JSON in NodesMapper:', error);
+            }
+        }
+        // Create bidirectional mapping
+        this.createMapping(nodeKey, treeId);
+        return treeId;
+    }
+    /**
+     * Update the mapping when a node is moved or modified
+     */
+    updateMapping(oldNodeKey, newNodeKey) {
+        const treeId = this.lexicalToLoro.get(oldNodeKey);
+        if (treeId) {
+            this.removeMapping(oldNodeKey, treeId);
+            this.createMapping(newNodeKey, treeId);
+            // Update timestamp in tree node data
+            const treeNode = this.tree.getNodeByID(treeId);
+            if (treeNode) {
+                treeNode.data.set('updatedAt', Date.now());
+            }
+        }
+    }
+    /**
+     * Remove mapping when a node is deleted (also deletes from Loro tree).
+     * Use this on the ORIGINATING side (propagation) where the local peer
+     * is actively deleting a node.
+     */
+    deleteMapping(nodeKey) {
+        const treeId = this.lexicalToLoro.get(nodeKey);
+        if (treeId) {
+            this.removeMapping(nodeKey, treeId);
+            // Delete the tree node
+            if (this.tree.has(treeId)) {
+                this.tree.delete(treeId);
+            }
+        }
+    }
+    /**
+     * Remove bidirectional mapping WITHOUT deleting from the Loro tree.
+     * Use this on the INTEGRATION side (receiving remote events) where the
+     * Loro tree has already been updated by the remote peer — we only need
+     * to clean up the local key↔TreeID association.
+     */
+    removeMappingForKey(nodeKey) {
+        const treeId = this.lexicalToLoro.get(nodeKey);
+        if (treeId) {
+            this.removeMapping(nodeKey, treeId);
+        }
+    }
+    /**
+     * Get TreeID by Lexical NodeKey (without creating if not found)
+     */
+    getTreeIDByLexicalKey(nodeKey) {
+        return this.lexicalToLoro.get(nodeKey);
+    }
+    /**
+     * Check if a mapping exists for a Lexical NodeKey
+     */
+    hasLexicalMapping(nodeKey) {
+        return this.lexicalToLoro.has(nodeKey);
+    }
+    /**
+     * Check if a mapping exists for a Loro TreeID
+     */
+    hasLoroMapping(treeId) {
+        return this.loroToLexical.has(treeId);
+    }
+    /**
+     * Get all current mappings (for debugging)
+     */
+    getAllMappings() {
+        return {
+            lexicalToLoro: new Map(this.lexicalToLoro),
+            loroToLexical: new Map(this.loroToLexical)
+        };
+    }
+    /**
+     * Clear all mappings (useful for testing or reset)
+     */
+    clearMappings() {
+        this.lexicalToLoro.clear();
+        this.loroToLexical.clear();
+    }
+    /**
+     * Synchronize existing tree nodes with Lexical editor state
+     * This should be called during initialization to establish mappings
+     *
+     * Note: Since lexicalKey is no longer persisted in tree node data,
+     * this method now relies on the TreeIntegrator to create mappings
+     * as nodes are integrated from Loro tree operations.
+     */
+    syncExistingNodes(editorState) {
+        // Since we no longer persist lexicalKey in tree node data,
+        // we cannot automatically establish mappings from existing tree nodes.
+        // 
+        // Instead, mappings will be established through:
+        // 1. TreeIntegrator processing tree diffs during initialization
+        // 2. Normal collaboration flow as nodes are created/updated
+        // 
+        // This method is kept for compatibility but is now a no-op.
+        console.log(' syncExistingNodes: Skipping sync - mappings established through TreeIntegrator');
+    }
+}
+// Global instance to be shared across the application
+let globalNodeMapper = null;
+/**
+ * Initialize the global node mapper
+ */
+export function initializeNodeMapper(binding) {
+    globalNodeMapper = new NodeMapper(binding);
+    return globalNodeMapper;
+}
+/**
+ * Get the global node mapper instance
+ */
+export function getNodeMapper() {
+    if (!globalNodeMapper) {
+        throw new Error('NodeMapper not initialized. Call initializeNodeMapper() first.');
+    }
+    return globalNodeMapper;
+}
+/**
+ * Utility functions for common operations
+ */
+/**
+ * Get Loro TreeNode by Lexical NodeKey (using global mapper)
+ */
+export function getLoroNodeByLexicalKey(nodeKey, lexicalNode, parentTreeID, index) {
+    return getNodeMapper().getLoroNodeByLexicalKey(nodeKey, lexicalNode, parentTreeID, index);
+}
+/**
+ * Get Lexical NodeKey by Loro TreeID (using global mapper)
+ */
+export function getLexicalKeyByLoroId(treeId) {
+    return getNodeMapper().getLexicalKeyByLoroId(treeId);
+}
+/**
+ * Get Lexical Node by Loro TreeID (using global mapper)
+ */
+export function getLexicalNodeByLoroId(treeId, editorState) {
+    return getNodeMapper().getLexicalNodeByLoroId(treeId, editorState);
+}
+// createLexicalNodeFromLoro function is now imported from NodeFactory

package/lib/collab/loro/propagators/DecoratorNodePropagator.d.ts

@@ -0,0 +1,60 @@
+import { TreeID, LoroTree } from 'loro-crdt';
+import { DecoratorNode, UpdateListenerPayload, NodeKey, ElementNode } from 'lexical';
+import { Binding } from '../Bindings';
+/**
+ * DecoratorNode Propagator for Loro Tree Collaboration
+ *
+ * DecoratorNode characteristics:
+ * - Wraps arbitrary view (React components, DOM nodes, etc.)
+ * - Acts as opaque wrapper around external components
+ * - Cannot have children in the traditional sense
+ * - Renders through decorate() method which returns the view
+ * - Examples: Images, Videos, Tweets, Charts, Custom Widgets
+ */
+export interface DecoratorNodeMutatorOptions {
+    binding: Binding;
+    tree: LoroTree;
+    peerId: number;
+}
+/**
+ * Create DecoratorNode in Loro tree
+ */
+export declare function createDecoratorNodeInLoro(nodeKey: NodeKey, decoratorType: string, // 'image', 'video', 'tweet', 'chart', etc.
+decoratorData: any, // The data needed to render the decorator
+parentId?: TreeID, index?: number, metadata?: Record<string, any>, lexicalNodeJSON?: any, // JSON object from exportJSON()
+options?: DecoratorNodeMutatorOptions): TreeID;
+/**
+ * Update DecoratorNode in Loro tree
+ */
+export declare function updateDecoratorNodeInLoro(nodeKey: NodeKey, decoratorType?: string, decoratorData?: any, parentId?: TreeID, index?: number, metadata?: Record<string, any>, lexicalNodeJSON?: any, // JSON object from exportJSON()
+options?: DecoratorNodeMutatorOptions): void;
+/**
+ * Delete DecoratorNode from Loro tree
+ */
+export declare function deleteDecoratorNodeInLoro(nodeKey: NodeKey, options: DecoratorNodeMutatorOptions): void;
+/**
+ * Create DecoratorNode in Lexical from Loro tree data
+ * Note: This is a generic implementation. In practice, you'd need
+ * specific decorator node classes for each type (ImageNode, VideoNode, etc.)
+ */
+export declare function createDecoratorNodeFromLoro(treeId: TreeID, parentNode: ElementNode, index?: number, options?: DecoratorNodeMutatorOptions): DecoratorNode<any> | null;
+/**
+ * Update DecoratorNode in Lexical from Loro tree data
+ */
+export declare function updateDecoratorNodeFromLoro(treeId: TreeID, lexicalNode: DecoratorNode<any>, newParentNode?: ElementNode, newIndex?: number, options?: DecoratorNodeMutatorOptions): void;
+/**
+ * Delete DecoratorNode from Lexical
+ */
+export declare function deleteDecoratorNodeFromLoro(treeId: TreeID, lexicalNode: DecoratorNode<any>, options?: DecoratorNodeMutatorOptions): void;
+/**
+ * Utility to check if a tree node represents a DecoratorNode
+ */
+export declare function isDecoratorNodeInTree(treeId: TreeID, tree: LoroTree): boolean;
+/**
+ * Get DecoratorNode data from Loro tree
+ */
+export declare function getDecoratorNodeDataFromTree(treeId: TreeID, tree: LoroTree): any;
+/**
+ * Main propagate method for DecoratorNode - propagates all mutation types
+ */
+export declare function propagateDecoratorNode(update: UpdateListenerPayload, mutation: 'created' | 'updated' | 'destroyed', nodeKey: NodeKey, options: DecoratorNodeMutatorOptions): void;