@datalayer/lexical-loro 0.0.7 → 0.1.0

package/lib/collab/loro/integrators/MapIntegrator.js

@@ -0,0 +1,177 @@
+import { $getNodeByKey } from 'lexical';
+import { $diffTextContentAndApplyDelta } from '../utils/Utils';
+/**
+ * Handles map data changes (node properties, metadata updates)
+ */
+export class MapIntegrator {
+    integrate(diff, binding, provider) {
+        // Handle updated properties
+        if (diff.updated) {
+            Object.entries(diff.updated).forEach(([key, value]) => {
+                this.integratePropertyUpdate(key, value, binding, provider);
+            });
+        }
+        // Handle deleted properties
+        if (diff.deleted) {
+            diff.deleted.forEach((key) => {
+                this.integratePropertyDelete(key, binding, provider);
+            });
+        }
+    }
+    // Enhanced integrate method with TreeID context
+    integrateWithContext(diff, treeId, binding, provider) {
+        this.integrateWithContextInternal(diff, treeId, binding, provider);
+    }
+    // Internal method for use when already inside editor.update()
+    integrateInternal(diff, binding, provider) {
+        // Handle updated properties
+        if (diff.updated) {
+            Object.entries(diff.updated).forEach(([key, value]) => {
+                this.integratePropertyUpdate(key, value, binding, provider);
+            });
+        }
+        // Handle deleted properties
+        if (diff.deleted) {
+            diff.deleted.forEach((key) => {
+                this.integratePropertyDelete(key, binding, provider);
+            });
+        }
+    }
+    // Internal method for use when already inside editor.update() with context
+    integrateWithContextInternal(diff, treeId, binding, provider) {
+        // Handle updated properties with TreeID context
+        if (diff.updated) {
+            Object.entries(diff.updated).forEach(([key, value]) => {
+                this.integratePropertyUpdateWithContextInternal(key, value, treeId, binding, provider);
+            });
+        }
+        // Handle deleted properties
+        if (diff.deleted) {
+            diff.deleted.forEach((key) => {
+                this.integratePropertyDelete(key, binding, provider);
+            });
+        }
+    }
+    integratePropertyUpdateWithContext(key, value, treeId, binding, provider) {
+        // Handle specific property updates with TreeID context
+        switch (key) {
+            case 'lexical':
+                this.integrateLexicalDataUpdateWithContext(value, treeId, binding);
+                break;
+            case 'textContent':
+                // Text content updates should be integrated via lexical data updates
+                break;
+            case 'elementType':
+                // Element type changes are rare, mostly for debugging
+                break;
+            default:
+            //
+        }
+    }
+    // Internal version for use when already inside editor.update()
+    integratePropertyUpdateWithContextInternal(key, value, treeId, binding, provider) {
+        // Handle specific property updates with TreeID context
+        switch (key) {
+            case 'lexical':
+                // Extract TreeID and call internal method directly (already inside editor.update())
+                let actualTreeID = treeId;
+                if (typeof treeId === 'string' && treeId.startsWith('cid:')) {
+                    const parts = treeId.split(':');
+                    if (parts.length >= 3) {
+                        actualTreeID = parts[1];
+                    }
+                }
+                const lexicalKey = binding.nodeMapper.getLexicalKeyByLoroId(actualTreeID);
+                if (lexicalKey) {
+                    this.integrateLexicalDataUpdateInternal(value, lexicalKey, actualTreeID);
+                }
+                break;
+            case 'textContent':
+                // Text content updates should be integrated via lexical data updates
+                break;
+            case 'elementType':
+                // Element type changes are rare, mostly for debugging
+                break;
+            default:
+                // Generic property update with context
+                break;
+        }
+    }
+    integratePropertyUpdate(key, value, binding, provider) {
+        // Handle specific property updates
+        switch (key) {
+            case 'lexical':
+                // Use targeted update only - the broad heuristic causes scrambling
+                break;
+            case 'textContent':
+                // Text content updates should be integrated via lexical data updates
+                break;
+            case 'elementType':
+                // Element type changes are rare, mostly for debugging
+                break;
+            default:
+                // Generic property update
+                break;
+        }
+    }
+    integratePropertyDelete(key, binding, provider) {
+        // Handle specific property deletions
+        switch (key) {
+            case 'lexical':
+                break;
+            default:
+                // Generic property deleted
+                break;
+        }
+    }
+    integrateLexicalDataUpdateWithContext(lexicalData, treeId, binding) {
+        // Extract the actual TreeID from container ID format
+        // Container ID format: "cid:6@7648424808278730813:Map"
+        // TreeID format: "6@7648424808278730813"
+        let actualTreeID = treeId;
+        if (typeof treeId === 'string' && treeId.startsWith('cid:')) {
+            const parts = treeId.split(':');
+            if (parts.length >= 3) {
+                actualTreeID = parts[1]; // Extract "6@7648424808278730813" from "cid:6@7648424808278730813:Map"
+            }
+        }
+        // Use the TreeID to find the specific Lexical node
+        const lexicalKey = binding.nodeMapper.getLexicalKeyByLoroId(actualTreeID);
+        if (!lexicalKey) {
+            return;
+        }
+        if (lexicalData && typeof lexicalData === 'object') {
+            binding.editor.update(() => {
+                this.integrateLexicalDataUpdateInternal(lexicalData, lexicalKey, actualTreeID);
+            });
+        }
+    }
+    // Internal method for use when already inside editor.update()
+    integrateLexicalDataUpdateInternal(lexicalData, lexicalKey, treeId) {
+        const targetType = lexicalData.type || lexicalData.__type;
+        const targetNode = $getNodeByKey(lexicalKey);
+        if (!targetNode) {
+            return;
+        }
+        const textContent = lexicalData.__text || lexicalData.text || lexicalData.textContent;
+        if (targetType === 'text' && textContent !== undefined) {
+            // Cast to TextNode to access text-specific methods
+            if (targetNode.getType() === 'text') {
+                const textNode = targetNode;
+                // Only update if the content is actually different to avoid unnecessary updates
+                const currentText = textNode.getTextContent();
+                if (currentText !== textContent) {
+                    // Apply the text update using delta to preserve cursor position and minimize disruption
+                    $diffTextContentAndApplyDelta(textNode, lexicalKey, currentText, textContent);
+                }
+                // Apply other text properties if present
+                if (lexicalData.format !== undefined) {
+                    textNode.setFormat(lexicalData.format);
+                }
+                if (lexicalData.style !== undefined) {
+                    textNode.setStyle(lexicalData.style);
+                }
+            }
+        }
+    }
+}

package/lib/collab/loro/integrators/TextIntegrator.d.ts

@@ -0,0 +1,25 @@
+import { BaseIntegrator } from './BaseIntegrator';
+import { Binding } from '../Bindings';
+import { Provider } from '../State';
+interface TextDiff {
+    type: 'text';
+    diff?: Array<{
+        type: 'insert' | 'delete' | 'retain';
+        index?: number;
+        length?: number;
+        value?: string;
+        attributes?: any;
+    }>;
+}
+/**
+ * Handles text changes (character insertions, deletions, formatting)
+ */
+export declare class TextIntegrator implements BaseIntegrator<TextDiff> {
+    integrate(diff: TextDiff, binding: Binding, provider: Provider): void;
+    integrateInternal(diff: TextDiff, binding: Binding, provider: Provider): void;
+    private integrateTextInsert;
+    private integrateTextDelete;
+    private integrateTextRetain;
+    private applyTextFormatting;
+}
+export {};

package/lib/collab/loro/integrators/TextIntegrator.js

@@ -0,0 +1,51 @@
+/**
+ * Handles text changes (character insertions, deletions, formatting)
+ */
+export class TextIntegrator {
+    integrate(diff, binding, provider) {
+        this.integrateInternal(diff, binding, provider);
+    }
+    // Internal method for use when already inside editor.update()
+    integrateInternal(diff, binding, provider) {
+        if (diff.diff) {
+            diff.diff.forEach((change) => {
+                switch (change.type) {
+                    case 'insert':
+                        this.integrateTextInsert(change, binding, provider);
+                        break;
+                    case 'delete':
+                        this.integrateTextDelete(change, binding, provider);
+                        break;
+                    case 'retain':
+                        this.integrateTextRetain(change, binding, provider);
+                        break;
+                    default:
+                        console.warn(`📝 Unknown text change type: ${change.type}`);
+                }
+            });
+        }
+    }
+    integrateTextInsert(change, binding, provider) {
+        // To integrate text insertion, we need to know which TextNode this applies to
+        // This information should come from the event context or be tracked separately
+        // For now, this is a placeholder - in a complete implementation,
+        // we would need to identify the target TextNode and update it
+    }
+    integrateTextDelete(change, binding, provider) {
+        // Similar to insert, we need target node context for text deletion
+    }
+    integrateTextRetain(change, binding, provider) {
+        if (change.attributes) {
+            // Handle text formatting changes
+            this.applyTextFormatting({ ...change, attributes: change.attributes }, binding, provider);
+        }
+    }
+    applyTextFormatting(change, binding, provider) {
+        // Text formatting in Lexical is typically integrated through TextNode format property
+        // This would need to be coordinated with the specific TextNode being modified
+        // Example formatting attributes might include:
+        // - bold, italic, underline
+        // - font size, color
+        // - etc.
+    }
+}

package/lib/collab/loro/integrators/TreeIntegrator.d.ts

@@ -0,0 +1,25 @@
+import { TreeID } from 'loro-crdt';
+import { BaseIntegrator } from './BaseIntegrator';
+import { Binding } from '../Bindings';
+import { Provider } from '../State';
+interface TreeDiff {
+    type: 'tree';
+    diff: Array<{
+        action: 'create' | 'move' | 'delete';
+        target: TreeID;
+        parent?: TreeID;
+        index?: number;
+    }>;
+}
+/**
+ * Simplified tree diff integrater that trusts Loro's CRDT conflict resolution
+ * and applies operations directly without complex filtering or context classification
+ */
+export declare class TreeIntegrator implements BaseIntegrator<TreeDiff> {
+    integrate(diff: TreeDiff, binding: Binding, provider: Provider): void;
+    integrateInternal(diff: TreeDiff, binding: Binding, provider: Provider): void;
+    private integrateCreate;
+    private integrateMove;
+    private integrateDelete;
+}
+export {};

package/lib/collab/loro/integrators/TreeIntegrator.js

@@ -0,0 +1,201 @@
+import { $getRoot, $getNodeByKey, $isElementNode } from 'lexical';
+import { parseTreeID } from '../utils/Utils';
+import { createLexicalNodeFromLoro } from '../nodes/NodeFactory';
+/**
+ * Simplified tree diff integrater that trusts Loro's CRDT conflict resolution
+ * and applies operations directly without complex filtering or context classification
+ */
+export class TreeIntegrator {
+    integrate(diff, binding, provider) {
+        // Batch all changes in a single editor update
+        binding.editor.update(() => {
+            this.integrateInternal(diff, binding, provider);
+        });
+    }
+    // Internal method that can be called when already inside editor.update()
+    integrateInternal(diff, binding, provider) {
+        // Sort operations: deletes first, then creates (element nodes before text), then moves
+        const operations = [...diff.diff];
+        operations.sort((a, b) => {
+            // Delete operations first
+            if (a.action === 'delete' && b.action !== 'delete')
+                return -1;
+            if (b.action === 'delete' && a.action !== 'delete')
+                return 1;
+            // Move operations last
+            if (a.action === 'move' && b.action !== 'move')
+                return 1;
+            if (b.action === 'move' && a.action !== 'move')
+                return -1;
+            // For create operations, prioritize element nodes over text nodes
+            if (a.action === 'create' && b.action === 'create') {
+                const aNode = binding.tree.getNodeByID(a.target);
+                const bNode = binding.tree.getNodeByID(b.target);
+                const aIsText = aNode?.data.get('elementType') === 'text';
+                const bIsText = bNode?.data.get('elementType') === 'text';
+                if (aIsText && !bIsText)
+                    return 1; // b (element) comes before a (text)
+                if (!aIsText && bIsText)
+                    return -1; // a (element) comes before b (text)
+            }
+            return 0; // Keep original order for same priority
+        });
+        operations.forEach(operation => {
+            switch (operation.action) {
+                case 'create':
+                    this.integrateCreate(operation, binding, provider);
+                    break;
+                case 'move':
+                    this.integrateMove(operation, binding, provider);
+                    break;
+                case 'delete':
+                    this.integrateDelete(operation, binding, provider);
+                    break;
+                default:
+                    console.warn(`🌳 Unknown tree operation: ${operation.action}`);
+            }
+        });
+    }
+    integrateCreate(operation, binding, provider) {
+        try {
+            let { nodeKey } = parseTreeID(operation.target);
+            // Skip root node creation - root is integrated during initial setup
+            // But ensure the root mapping exists
+            // Only treat as root if it's actually a root-type node in Loro
+            if (nodeKey === "0") {
+                const treeNode = binding.tree.getNodeByID(operation.target);
+                const elementType = treeNode?.data.get('elementType');
+                if (elementType === 'root' || !elementType) {
+                    const root = $getRoot();
+                    binding.nodeMapper.setMapping(root.getKey(), operation.target);
+                    return;
+                }
+                // If nodeKey is "0" but it's not actually a root element, continue with normal processing
+            }
+            // Check if node already exists and if it's the same TreeID
+            const existingNode = $getNodeByKey(nodeKey);
+            if (existingNode) {
+                const existingTreeID = binding.nodeMapper.getTreeIDByLexicalKey(nodeKey);
+                if (existingTreeID === operation.target) {
+                    return;
+                }
+                else {
+                    // Don't reuse existing keys for different TreeIDs - let Lexical generate a fresh one
+                    nodeKey = undefined; // Let createLexicalNodeFromLoro generate a fresh key
+                }
+            }
+            // Create Lexical node from Loro data
+            const lexicalNode = createLexicalNodeFromLoro(operation.target, binding.tree, binding);
+            if (!lexicalNode) {
+                return;
+            }
+            // Find parent node
+            let parentNode;
+            if (operation.parent) {
+                const parentKey = binding.nodeMapper.getLexicalKeyByLoroId(operation.parent);
+                const parentLexicalNode = parentKey ? $getNodeByKey(parentKey) : null;
+                if (parentLexicalNode && $isElementNode(parentLexicalNode)) {
+                    parentNode = parentLexicalNode;
+                }
+                else {
+                    // For text nodes, we MUST have a proper parent element
+                    if (lexicalNode.getType() === 'text') {
+                        return;
+                    }
+                    parentNode = $getRoot();
+                }
+            }
+            else {
+                parentNode = $getRoot();
+            }
+            // Normal insertion
+            if (operation.index !== undefined) {
+                parentNode.splice(operation.index, 0, [lexicalNode]);
+            }
+            else {
+                parentNode.append(lexicalNode);
+            }
+            // Set up mapping
+            binding.nodeMapper.setMapping(lexicalNode.getKey(), operation.target);
+        }
+        catch (error) {
+            console.warn(`🌳 Error creating node for ${operation.target}:`, error);
+        }
+    }
+    integrateMove(operation, binding, provider) {
+        try {
+            const lexicalKey = binding.nodeMapper.getLexicalKeyByLoroId(operation.target);
+            if (!lexicalKey) {
+                console.warn(`🌳 No Lexical key found for move target ${operation.target}`);
+                return;
+            }
+            const nodeToMove = $getNodeByKey(lexicalKey);
+            if (!nodeToMove) {
+                console.warn(`🌳 Node to move not found: ${lexicalKey}`);
+                return;
+            }
+            // Find new parent
+            let newParent;
+            if (operation.parent) {
+                const parentKey = binding.nodeMapper.getLexicalKeyByLoroId(operation.parent);
+                const parentNode = parentKey ? $getNodeByKey(parentKey) : null;
+                if (parentNode && $isElementNode(parentNode)) {
+                    newParent = parentNode;
+                }
+                else {
+                    // For text nodes, we can't move them to root - skip this move operation
+                    // The node is already in the correct position from our create fix
+                    if (nodeToMove.getType() === 'text') {
+                        return;
+                    }
+                    newParent = $getRoot();
+                }
+            }
+            else {
+                // For text nodes without a parent, skip the move
+                if (nodeToMove.getType() === 'text') {
+                    return;
+                }
+                newParent = $getRoot();
+            }
+            // Remove from current position and insert at new position
+            nodeToMove.remove();
+            if (operation.index !== undefined) {
+                newParent.splice(operation.index, 0, [nodeToMove]);
+            }
+            else {
+                newParent.append(nodeToMove);
+            }
+        }
+        catch (error) {
+            console.warn(`🌳 Error moving node ${operation.target}:`, error);
+        }
+    }
+    integrateDelete(operation, binding, provider) {
+        try {
+            const lexicalKey = binding.nodeMapper.getLexicalKeyByLoroId(operation.target);
+            if (!lexicalKey) {
+                console.warn(`🌳 No Lexical key found for delete target ${operation.target}`);
+                return;
+            }
+            const nodeToDelete = $getNodeByKey(lexicalKey);
+            if (!nodeToDelete) {
+                console.warn(`🌳 Node to delete not found: ${lexicalKey}`);
+                return;
+            }
+            // Remove from Lexical tree
+            nodeToDelete.remove();
+            // Clean up mapping
+            binding.nodeMapper.deleteMapping(lexicalKey);
+        }
+        catch (error) {
+            // Handle the case where Loro is trying to delete an already deleted node
+            if (error.message && error.message.includes('is deleted or does not exist')) {
+                console.log(`🌳 Node ${operation.target} already deleted (normal during restructuring):`, error.message);
+            }
+            else {
+                console.warn(`🌳 Error deleting node ${operation.target}:`, error);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,8 @@
+import { TreeID, LoroTree } from 'loro-crdt';
+import { LexicalNode, NodeKey } from 'lexical';
+import { Binding } from '../Bindings';
+/**
+ * Factory function to create Lexical nodes from Loro TreeID
+ * Uses the editor's registered node classes, similar to YJS implementation
+ */
+export declare function createLexicalNodeFromLoro(treeId: TreeID, loroTree: LoroTree, binding: Binding, parentKey?: NodeKey, nodeDataFromDiff?: any): LexicalNode | null;

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

@@ -0,0 +1,105 @@
+/**
+ * Factory function to create Lexical nodes from Loro TreeID
+ * Uses the editor's registered node classes, similar to YJS implementation
+ */
+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 integrater (has immediate lexical data)
+    let lexicalData = nodeDataFromDiff?.lexical;
+    // Fallback to tree node data
+    if (!lexicalData) {
+        lexicalData = treeNode?.data.get('lexical');
+    }
+    let nodeType;
+    let deserializedData = null;
+    if (lexicalData && typeof lexicalData === 'object') {
+        // JSON object format - the only supported format
+        nodeType = lexicalData.type || lexicalData.__type;
+        deserializedData = { lexicalNode: lexicalData };
+    }
+    else {
+        // Fallback to element type from nodeDataFromDiff or old nodeType
+        const fallbackType = nodeDataFromDiff?.elementType || treeNode?.data.get('nodeType');
+        if (!fallbackType || typeof fallbackType !== 'string') {
+            console.warn('No lexical data or nodeType found for TreeID:', treeId);
+            return null;
+        }
+        nodeType = fallbackType;
+    }
+    // Get the registered node class from the editor (following YJS pattern)
+    const registeredNodes = binding.editor._nodes;
+    const nodeInfo = registeredNodes.get(nodeType);
+    if (!nodeInfo) {
+        return null;
+    }
+    // Create new instance of the registered node class
+    let lexicalNode;
+    // Special handling for HeadingNode which requires tag parameter in constructor
+    if (nodeType === 'heading') {
+        const tag = (deserializedData?.lexicalNode?.tag ||
+            (lexicalData && typeof lexicalData === 'object' && lexicalData.tag) ||
+            'h1');
+        try {
+            // HeadingNode constructor signature: new HeadingNode(tag, key)
+            // We pass tag as first argument, let Lexical generate the key
+            lexicalNode = new nodeInfo.klass(tag);
+        }
+        catch (error) {
+            console.warn(`🏭 NodeFactory: Failed to create HeadingNode:`, error);
+            return null;
+        }
+    }
+    else {
+        try {
+            lexicalNode = new nodeInfo.klass();
+        }
+        catch (error) {
+            console.warn(`🏭 NodeFactory: Failed to create ${nodeType} instance:`, error);
+            return null;
+        }
+    }
+    // Note: DO NOT set __parent manually - let Lexical integrate parent-child relationships
+    // through proper $ methods like append(), insertBefore(), etc.
+    // Apply properties from the deserialized data if available
+    if (deserializedData?.lexicalNode) {
+        const nodeData = deserializedData.lexicalNode;
+        // Apply all properties except system ones and tag (for HeadingNode)
+        Object.keys(nodeData).forEach(key => {
+            if (key !== '__parent' && key !== '__key') {
+                try {
+                    if (key === 'tag' && nodeType === 'heading') {
+                        // Tag is already set in HeadingNode constructor, skip
+                    }
+                    else {
+                        lexicalNode[key] = nodeData[key];
+                    }
+                }
+                catch (error) {
+                    console.warn(`Failed to set property ${key} on node:`, error);
+                }
+            }
+        });
+    }
+    else if (lexicalData && typeof lexicalData === 'object') {
+        // For direct object format (like heading data), apply properties directly
+        const applicableKeys = Object.keys(lexicalData).filter(key => key !== '__parent' && key !== '__key' && key !== 'type' && key !== 'children');
+        applicableKeys.forEach(key => {
+            try {
+                if (key === 'tag' && nodeType === 'heading') {
+                    // Tag is already set in HeadingNode constructor, skip
+                }
+                else {
+                    lexicalNode[key] = lexicalData[key];
+                }
+            }
+            catch (error) {
+                console.warn(`Failed to set property ${key} on node:`, error);
+            }
+        });
+    }
+    return lexicalNode;
+}