@datalayer/lexical-loro 0.2.5 → 1.0.1

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

@@ -1,235 +0,0 @@
-/*
- * Copyright (c) 2023-2025 Datalayer, Inc.
- * Distributed under the terms of the MIT License.
- */
-import { $getNodeByKey, $isDecoratorNode } 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, 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:
-                // 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, binding);
-            });
-        }
-    }
-    // Internal method for use when already inside editor.update()
-    integrateLexicalDataUpdateInternal(lexicalData, lexicalKey, treeId, binding) {
-        // Handle Loro container objects that need conversion to plain JS
-        let data = lexicalData;
-        if (data && typeof data === 'object' && typeof data.toJSON === 'function') {
-            data = data.toJSON();
-        }
-        const targetNode = $getNodeByKey(lexicalKey);
-        if (!targetNode) {
-            return;
-        }
-        const targetType = targetNode.getType();
-        const textContent = data.__text || data.text || data.textContent;
-        if (targetType === 'text' && textContent !== undefined) {
-            // Text nodes: use diff approach to preserve cursor position
-            const textNode = targetNode;
-            const currentText = textNode.getTextContent();
-            if (currentText !== textContent) {
-                $diffTextContentAndApplyDelta(textNode, lexicalKey, currentText, textContent);
-            }
-            // Apply text-specific properties
-            if (data.format !== undefined) {
-                textNode.setFormat(data.format);
-            }
-            if (data.style !== undefined) {
-                textNode.setStyle(data.style);
-            }
-        }
-        else if ($isDecoratorNode(targetNode)) {
-            // Decorator nodes (excalidraw, images, counters, JupyterCellNode, …):
-            // Many decorator implementations do NOT override `updateFromJSON` for
-            // their custom properties — they only set them in the constructor via
-            // `importJSON`.  Since decorators are leaf nodes (no children), it is
-            // safe to replace the whole node with a fresh `importJSON` instance.
-            try {
-                const registeredNodes = binding.editor._nodes;
-                const nodeInfo = registeredNodes.get(targetType);
-                if (!nodeInfo) {
-                    console.warn(`🗺️ MapIntegrator: Node type '${targetType}' not registered`);
-                    return;
-                }
-                const serializedData = { ...data };
-                if (!serializedData.type)
-                    serializedData.type = targetType;
-                if (serializedData.version === undefined)
-                    serializedData.version = 1;
-                if (!('children' in serializedData))
-                    serializedData.children = [];
-                const newNode = nodeInfo.klass.importJSON(serializedData);
-                targetNode.replace(newNode);
-                // Update bidirectional mapping: old key → remove, new key → treeId
-                // Use removeMappingForKey (not deleteMapping) because we are on the
-                // integration side — the Loro tree node must NOT be deleted; we are
-                // only swapping which Lexical key points to it.
-                binding.nodeMapper.removeMappingForKey(lexicalKey);
-                binding.nodeMapper.setMapping(newNode.getKey(), treeId);
-            }
-            catch (error) {
-                console.warn(`🗺️ MapIntegrator: importJSON+replace failed for decorator ${targetType} node ${lexicalKey}:`, error);
-            }
-        }
-        else {
-            try {
-                const serializedData = { ...data };
-                if (!serializedData.type) {
-                    serializedData.type = targetType;
-                }
-                if (serializedData.version === undefined) {
-                    serializedData.version = 1;
-                }
-                // Provide empty children (TreeIntegrator manages children separately)
-                if (!('children' in serializedData)) {
-                    serializedData.children = [];
-                }
-                const writable = targetNode.getWritable();
-                writable.updateFromJSON(serializedData);
-            }
-            catch (error) {
-                console.warn(`🗺️ MapIntegrator: updateFromJSON failed for ${targetType} node ${lexicalKey}:`, error);
-            }
-        }
-    }
-}

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

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

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

@@ -1,36 +0,0 @@
-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;
-    /**
-     * Topologically sort create operations so that parent nodes are created
-     * before their children.
-     *
-     * Computes depth using the `parent` field from the diff operations
-     * themselves rather than querying the Loro tree API (which may behave
-     * unexpectedly during event processing).  For each create op, we count
-     * how many of its ancestors are also being created in this same batch.
-     * Ties at the same depth preserve the original diff order (stable sort).
-     */
-    private topologicalSortCreates;
-}
-export {};

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

@@ -1,251 +0,0 @@
-/*
- * Copyright (c) 2023-2025 Datalayer, Inc.
- * Distributed under the terms of the MIT License.
- */
-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) {
-        // Separate operations by action type
-        const deletes = [];
-        const creates = [];
-        const moves = [];
-        for (const op of diff.diff) {
-            switch (op.action) {
-                case 'delete':
-                    deletes.push(op);
-                    break;
-                case 'create':
-                    creates.push(op);
-                    break;
-                case 'move':
-                    moves.push(op);
-                    break;
-            }
-        }
-        // Topologically sort create operations so parents are created before children.
-        // Without this, a TableCellNode may arrive before its parent TableRowNode,
-        // causing the cell to fall back to $getRoot() and appear on one flat line.
-        const sortedCreates = this.topologicalSortCreates(creates, binding);
-        // Execute: deletes → creates (parent-first) → moves
-        const operations = [...deletes, ...sortedCreates, ...moves];
-        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 {
-                    console.warn(`🌳 Parent NOT found for ${lexicalNode.getType()} target=${operation.target} parent=${operation.parent} parentKey=${parentKey} parentFound=${!!parentLexicalNode} isElement=${parentLexicalNode ? $isElementNode(parentLexicalNode) : 'N/A'}`);
-                    // 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 only — do NOT call deleteMapping() here because
-            // the Loro tree has already processed this deletion from the remote
-            // peer.  Calling tree.delete() again would throw "is deleted or does
-            // not exist".
-            binding.nodeMapper.removeMappingForKey(lexicalKey);
-        }
-        catch (error) {
-            console.warn(`🌳 Error deleting node ${operation.target}:`, error);
-        }
-    }
-    /**
-     * Topologically sort create operations so that parent nodes are created
-     * before their children.
-     *
-     * Computes depth using the `parent` field from the diff operations
-     * themselves rather than querying the Loro tree API (which may behave
-     * unexpectedly during event processing).  For each create op, we count
-     * how many of its ancestors are also being created in this same batch.
-     * Ties at the same depth preserve the original diff order (stable sort).
-     */
-    topologicalSortCreates(creates, binding) {
-        if (creates.length <= 1)
-            return creates;
-        // Build lookup: target → parent (only for operations in this batch)
-        const batchTargets = new Set(creates.map(op => String(op.target)));
-        const parentOf = new Map();
-        for (const op of creates) {
-            if (op.parent) {
-                parentOf.set(String(op.target), String(op.parent));
-            }
-        }
-        const depthCache = new Map();
-        const getDepth = (targetStr) => {
-            if (depthCache.has(targetStr))
-                return depthCache.get(targetStr);
-            let depth = 0;
-            let current = targetStr;
-            const visited = new Set();
-            // Walk up the parent chain; count only ancestors that are also being
-            // created in this batch (i.e. don't exist yet and must come first).
-            while (parentOf.has(current)) {
-                const parent = parentOf.get(current);
-                if (visited.has(parent))
-                    break; // cycle guard
-                visited.add(parent);
-                if (batchTargets.has(parent)) {
-                    depth++;
-                    current = parent;
-                }
-                else {
-                    break; // parent already exists locally — stop counting
-                }
-            }
-            depthCache.set(targetStr, depth);
-            return depth;
-        };
-        // Tag each operation with its original index (for stable tie-breaking)
-        const tagged = creates.map((op, i) => ({ op, depth: getDepth(String(op.target)), idx: i }));
-        tagged.sort((a, b) => a.depth - b.depth || a.idx - b.idx);
-        return tagged.map(t => t.op);
-    }
-}

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

@@ -1,15 +0,0 @@
-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 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 declare function createLexicalNodeFromLoro(treeId: TreeID, loroTree: LoroTree, binding: Binding, parentKey?: NodeKey, nodeDataFromDiff?: any): LexicalNode | null;