@datalayer/lexical-loro 0.2.5 → 1.0.0

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

@@ -1,101 +0,0 @@
-/*
- * Copyright (c) 2023-2025 Datalayer, Inc.
- * Distributed under the terms of the MIT License.
- */
-/**
- * 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
-    if (!loroTree.has(treeId)) {
-        return null;
-    }
-    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: construct a minimal serialization from elementType metadata
-        const fallbackType = nodeDataFromDiff?.elementType ||
-            treeNode?.data.get('elementType') ||
-            treeNode?.data.get('nodeType');
-        if (!fallbackType || typeof fallbackType !== 'string') {
-            console.warn('🏭 NodeFactory: No lexical data or elementType for TreeID:', treeId);
-            return null;
-        }
-        lexicalData = { type: fallbackType, version: 1 };
-    }
-    const nodeType = lexicalData.type || lexicalData.__type;
-    if (!nodeType) {
-        console.warn('🏭 NodeFactory: No type field in lexical data for TreeID:', treeId);
-        return null;
-    }
-    // Get the registered node class from the editor
-    const registeredNodes = binding.editor._nodes;
-    const nodeInfo = registeredNodes.get(nodeType);
-    if (!nodeInfo) {
-        console.warn(`🏭 NodeFactory: Node type '${nodeType}' is not registered in the editor`);
-        return null;
-    }
-    // ---------- 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.
-    try {
-        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 itself does not
-        // recurse into children — that is handled by TreeIntegrator).
-        if (!('children' in serializedData)) {
-            serializedData.children = [];
-        }
-        const lexicalNode = nodeInfo.klass.importJSON(serializedData);
-        return lexicalNode;
-    }
-    catch (importError) {
-        console.warn(`🏭 NodeFactory: importJSON failed for '${nodeType}', trying constructor fallback:`, importError);
-        // Fallback: try no-arg constructor (works for simple nodes)
-        try {
-            const lexicalNode = new nodeInfo.klass();
-            return lexicalNode;
-        }
-        catch (ctorError) {
-            console.warn(`🏭 NodeFactory: Constructor also failed for '${nodeType}':`, ctorError);
-            return null;
-        }
-    }
-}

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

@@ -1,120 +0,0 @@
-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

@@ -1,277 +0,0 @@
-/*
- * Copyright (c) 2023-2025 Datalayer, Inc.
- * Distributed under the terms of the MIT License.
- */
-/**
- * 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, 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

@@ -1,60 +0,0 @@
-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;