@datalayer/lexical-loro 0.0.7 → 0.1.0

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

@@ -0,0 +1,111 @@
+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
+     */
+    deleteMapping(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,258 @@
+/**
+ * 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) {
+        // Create the tree node first
+        const treeNode = this.tree.createNode(parentTreeID, index);
+        // Get the TreeID from the created node
+        const treeId = treeNode.id;
+        // Debug logging for parent relationship issues
+        if (parentTreeID) {
+            const actualParent = treeNode.parent();
+            if (!actualParent || actualParent.id !== parentTreeID) {
+                console.warn(`⚠️  Parent relationship not set correctly for ${nodeKey}: expected ${parentTreeID}, got ${actualParent?.id || 'None'}`);
+            }
+        }
+        // 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, ...cleanedData } = lexicalNodeJSON;
+                    treeNode.data.set('lexical', cleanedData);
+                }
+                else {
+                    treeNode.data.set('lexical', lexicalNodeJSON);
+                }
+            }
+            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
+     */
+    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);
+            }
+        }
+    }
+    /**
+     * 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;