@datalayer/lexical-loro 1.0.2 → 1.0.5

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

@@ -0,0 +1,55 @@
+import { TreeID, LoroTree } from 'loro-crdt';
+import { UpdateListenerPayload, NodeKey, RootNode } from 'lexical';
+import { Binding } from '../Bindings';
+/**
+ * RootNode Propagator for Loro Tree Collaboration
+ *
+ * The RootNode is special in Lexical:
+ * - Only one RootNode exists per EditorState
+ * - Cannot be subclassed or replaced
+ * - Represents the contenteditable element itself
+ * - Does not participate in mutation listeners
+ * - Has no parent or siblings
+ *
+ * Note: RootNode typically doesn't need mutation handling since it's
+ * always present and doesn't change structure, but we include it for completeness
+ */
+export interface RootNodeMutatorOptions {
+    binding: Binding;
+    tree: LoroTree;
+    peerId: number;
+}
+/**
+ * Handle RootNode creation (typically only happens once during initialization)
+ */
+export declare function createRootNodeInLoro(nodeKey: NodeKey, lexicalNodeJSON?: any, // JSON object from exportJSON()
+options?: RootNodeMutatorOptions): TreeID;
+/**
+ * Handle RootNode updates (rarely needed since root doesn't change much)
+ */
+export declare function updateRootNodeInLoro(nodeKey: NodeKey, lexicalNodeJSON?: any, // JSON object from exportJSON()
+options?: RootNodeMutatorOptions): void;
+/**
+ * Handle RootNode deletion (should rarely happen, but included for completeness)
+ */
+export declare function deleteRootNodeInLoro(nodeKey: NodeKey, options: RootNodeMutatorOptions): void;
+/**
+ * Create RootNode in Lexical from Loro tree data
+ */
+export declare function createRootNodeFromLoro(treeId: TreeID, options: RootNodeMutatorOptions): RootNode | null;
+/**
+ * Update RootNode in Lexical from Loro tree data
+ */
+export declare function updateRootNodeFromLoro(treeId: TreeID, options: RootNodeMutatorOptions): void;
+/**
+ * Delete RootNode in Lexical (should not happen in normal operation)
+ */
+export declare function deleteRootNodeFromLoro(treeId: TreeID, options: RootNodeMutatorOptions): void;
+/**
+ * Utility to check if a tree node represents a RootNode
+ */
+export declare function isRootNodeInTree(treeId: TreeID, tree: LoroTree): boolean;
+/**
+ * Main propagate method for RootNode - propagates all mutation types
+ */
+export declare function propagateRootNode(update: UpdateListenerPayload, mutation: 'created' | 'updated' | 'destroyed', nodeKey: NodeKey, options: RootNodeMutatorOptions): void;

package/lib/collab/loro/propagators/RootNodePropagator.js

@@ -0,0 +1,174 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the MIT License.
+ */
+import { $getRoot } from 'lexical';
+import { getNodeMapper } from '../nodes/NodesMapper';
+/**
+ * Handle RootNode creation (typically only happens once during initialization)
+ */
+export function createRootNodeInLoro(nodeKey, lexicalNodeJSON, // JSON object from exportJSON()
+options) {
+    const { tree, peerId } = options;
+    const mapper = getNodeMapper();
+    // Use mapper to get or create the tree node (don't pass lexicalNode to avoid context issues)
+    // Root node has no parent (undefined) and is always at index 0
+    const rootTreeNode = mapper.getLoroNodeByLexicalKey(nodeKey, undefined, // don't pass lexicalNode to avoid context issues
+    undefined, // no parent for root
+    0 // always at index 0
+    );
+    // Store complete lexical node data as clean JSON if provided
+    if (lexicalNodeJSON) {
+        try {
+            // Store complete lexical JSON without all key-related fields
+            if ('key' in lexicalNodeJSON || '__key' in lexicalNodeJSON || 'lexicalKey' in lexicalNodeJSON) {
+                const { key, __key, lexicalKey, children, ...cleanedData } = lexicalNodeJSON;
+                rootTreeNode.data.set('lexical', cleanedData);
+            }
+            else {
+                const { children, ...cleanedData } = lexicalNodeJSON;
+                rootTreeNode.data.set('lexical', cleanedData);
+            }
+        }
+        catch (error) {
+            console.warn('Failed to store lexical node JSON for RootNode:', error);
+        }
+    }
+    // Store only essential metadata
+    rootTreeNode.data.set('elementType', 'root');
+    rootTreeNode.data.set('createdAt', Date.now());
+    // The exported Lexical node data is already propagated by the mapper
+    // Return the TreeID from the node's ID
+    return rootTreeNode.id;
+}
+/**
+ * Handle RootNode updates (rarely needed since root doesn't change much)
+ */
+export function updateRootNodeInLoro(nodeKey, lexicalNodeJSON, // JSON object from exportJSON()
+options) {
+    const mapper = getNodeMapper();
+    // Get the existing tree node using the mapper (don't pass lexicalNode to avoid context issues)
+    const treeNode = mapper.getLoroNodeByLexicalKey(nodeKey, undefined);
+    // Store complete lexical node data as clean JSON if provided
+    if (lexicalNodeJSON) {
+        try {
+            // Store complete lexical JSON without all key-related fields
+            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 store lexical node JSON for RootNode update:', error);
+        }
+    }
+    // Update only essential metadata
+    treeNode.data.set('elementType', 'root');
+    treeNode.data.set('lastUpdated', Date.now());
+}
+/**
+ * Handle RootNode deletion (should rarely happen, but included for completeness)
+ */
+export function deleteRootNodeInLoro(nodeKey, options) {
+    const mapper = getNodeMapper();
+    // Note: Deleting root node should be done with extreme caution
+    // as it represents the entire editor content
+    mapper.deleteMapping(nodeKey);
+}
+/**
+ * Create RootNode in Lexical from Loro tree data
+ */
+export function createRootNodeFromLoro(treeId, options) {
+    // In Lexical, there's always exactly one root node
+    // This function would typically be called during initialization
+    const root = $getRoot();
+    // Root node already exists, just return it
+    return root;
+}
+/**
+ * Update RootNode in Lexical from Loro tree data
+ */
+export function updateRootNodeFromLoro(treeId, options) {
+    // Root node updates are typically propagated at the document level
+    // Most changes to root would be indirect (children changes)
+    console.log('Root node update from Loro:', treeId);
+}
+/**
+ * Delete RootNode in Lexical (should not happen in normal operation)
+ */
+export function deleteRootNodeFromLoro(treeId, options) {
+    // Root node deletion should not happen in normal circumstances
+    // This would essentially clear the entire editor
+    console.warn('Attempting to delete root node - this should not happen:', treeId);
+}
+/**
+ * Utility to check if a tree node represents a RootNode
+ */
+export function isRootNodeInTree(treeId, tree) {
+    if (!tree.has(treeId)) {
+        return false;
+    }
+    const treeNode = tree.getNodeByID(treeId);
+    return treeNode?.data.get('nodeType') === 'root';
+}
+/**
+ * Main propagate method for RootNode - propagates all mutation types
+ */
+export function propagateRootNode(update, mutation, nodeKey, options) {
+    const { tree, peerId } = options;
+    switch (mutation) {
+        case 'created': {
+            // Get the current editor state to find the root node
+            const currentNode = update.editorState._nodeMap.get(nodeKey);
+            if (currentNode) {
+                // Export node data as JSON object within editor context where node methods are available
+                let lexicalNodeJSON = undefined;
+                update.editorState.read(() => {
+                    if (currentNode.getType() === 'root') {
+                        try {
+                            lexicalNodeJSON = currentNode.exportJSON();
+                        }
+                        catch (error) {
+                            console.warn('Failed to export root node JSON:', error);
+                        }
+                    }
+                });
+                if (lexicalNodeJSON) {
+                    createRootNodeInLoro(nodeKey, lexicalNodeJSON, options);
+                }
+            }
+            break;
+        }
+        case 'updated': {
+            // Root nodes typically don't change much, but we can update metadata
+            const currentNode = update.editorState._nodeMap.get(nodeKey);
+            if (currentNode) {
+                // Export node data as JSON object within editor context where node methods are available
+                let lexicalNodeJSON = undefined;
+                update.editorState.read(() => {
+                    if (currentNode.getType() === 'root') {
+                        try {
+                            lexicalNodeJSON = currentNode.exportJSON();
+                        }
+                        catch (error) {
+                            console.warn('Failed to export root node JSON for update:', error);
+                        }
+                    }
+                });
+                if (lexicalNodeJSON) {
+                    updateRootNodeInLoro(nodeKey, lexicalNodeJSON, options);
+                }
+            }
+            break;
+        }
+        case 'destroyed': {
+            // Delete the root node from Loro tree
+            deleteRootNodeInLoro(nodeKey, options);
+            break;
+        }
+    }
+}

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

@@ -0,0 +1,60 @@
+import { TreeID, LoroTree } from 'loro-crdt';
+import { TextNode, TextFormatType, UpdateListenerPayload, NodeKey, ElementNode } from 'lexical';
+import { Binding } from '../Bindings';
+/**
+ * TextNode Propagator for Loro Tree Collaboration
+ *
+ * TextNode characteristics:
+ * - Leaf nodes that represent text content
+ * - Can have formatting (bold, italic, underline, strikethrough, etc.)
+ * - Can have different modes: normal, token, segmented, inert
+ * - Cannot have children (always leaf nodes)
+ * - Support text content and format operations
+ */
+export interface TextNodeMutatorOptions {
+    binding: Binding;
+    tree: LoroTree;
+    peerId: number;
+}
+/**
+ * Create TextNode in Loro tree
+ */
+export declare function createTextNodeInLoro(nodeKey: NodeKey, textContent: string, format?: number, mode?: string, parentId?: TreeID, index?: number, lexicalNodeJSON?: any, // JSON object from exportJSON()
+options?: TextNodeMutatorOptions): TreeID;
+/**
+ * Update TextNode in Loro tree
+ */
+export declare function updateTextNodeInLoro(nodeKey: NodeKey, newTextContent?: string, format?: number, mode?: string, lexicalNodeJSON?: any, // JSON object from exportJSON()
+options?: TextNodeMutatorOptions): void;
+/**
+ * Delete TextNode from Loro tree
+ */
+export declare function deleteTextNodeInLoro(nodeKey: NodeKey, options: TextNodeMutatorOptions): void;
+/**
+ * Create TextNode in Lexical from Loro tree data
+ */
+export declare function createTextNodeFromLoro(treeId: TreeID, parentNode: ElementNode, index?: number, options?: TextNodeMutatorOptions): TextNode | null;
+/**
+ * Update TextNode in Lexical from Loro tree data
+ */
+export declare function updateTextNodeFromLoro(treeId: TreeID, textNode: TextNode, newParentNode?: ElementNode, newIndex?: number, options?: TextNodeMutatorOptions): void;
+/**
+ * Delete TextNode from Lexical
+ */
+export declare function deleteTextNodeFromLoro(treeId: TreeID, lexicalNode: TextNode, options?: TextNodeMutatorOptions): void;
+/**
+ * Utility to check if a tree node represents a TextNode
+ */
+export declare function isTextNodeInTree(treeId: TreeID, tree: LoroTree): boolean;
+/**
+ * Get TextNode data from Loro tree
+ */
+export declare function getTextNodeDataFromTree(treeId: TreeID, tree: LoroTree): any;
+/**
+ * Apply text formatting operations (bold, italic, etc.)
+ */
+export declare function applyTextFormatInLoro(nodeKey: NodeKey, formatType: TextFormatType, apply: boolean, options: TextNodeMutatorOptions): void;
+/**
+ * Main propagate method for TextNode - propagates all mutation types
+ */
+export declare function propagateTextNode(update: UpdateListenerPayload, mutation: 'created' | 'updated' | 'destroyed', nodeKey: NodeKey, options: TextNodeMutatorOptions): void;