@datalayer/lexical-loro 0.2.4 → 0.2.5

package/lib/collab/yjs/sync/SyncEditorStates.js

@@ -0,0 +1,200 @@
+import { $addUpdateTag, $createParagraphNode, $getNodeByKey, $getRoot, $getSelection, $getWritableNodeState, $isRangeSelection, $isTextNode, COLLABORATION_TAG, HISTORIC_TAG, SKIP_SCROLL_INTO_VIEW_TAG, } from 'lexical';
+import { Map as YMap, XmlElement, XmlText, YMapEvent, YTextEvent, YXmlEvent, } from 'yjs';
+import invariant from '../../utils/invariant';
+import { $getOrInitCollabNodeFromSharedType, $moveSelectionToPreviousNode, doesSelectionNeedRecovering, getNodeTypeFromSharedType, syncWithTransaction, } from '../utils/Utils';
+import { CollabDecoratorNode } from '../nodes/CollabDecoratorNode';
+import { CollabElementNode } from '../nodes/CollabElementNode';
+import { CollabTextNode } from '../nodes/CollabTextNode';
+import { $syncLocalCursorPosition, syncCursorPositions, syncLexicalSelectionToYjs, } from './SyncCursors';
+/******************************************************************************
+ * Yjs -> Lexical
+ *****************************************************************************/
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function $syncStateEvent(binding, event) {
+    const { target } = event;
+    if (!(target._item &&
+        target._item.parentSub === '__state' &&
+        getNodeTypeFromSharedType(target) === undefined &&
+        (target.parent instanceof XmlText ||
+            target.parent instanceof XmlElement ||
+            target.parent instanceof YMap))) {
+        // TODO there might be a case to handle in here when a YMap
+        // is used as a value  of __state? It would probably be desirable
+        // to mark the node as dirty when that happens.
+        return false;
+    }
+    const collabNode = $getOrInitCollabNodeFromSharedType(binding, target.parent);
+    const node = collabNode.getNode();
+    if (node) {
+        const state = $getWritableNodeState(node.getWritable());
+        for (const k of event.keysChanged) {
+            state.updateFromUnknown(k, target.get(k));
+        }
+    }
+    return true;
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function $syncEvent(binding, event) {
+    if (event instanceof YMapEvent && $syncStateEvent(binding, event)) {
+        return;
+    }
+    const { target } = event;
+    const collabNode = $getOrInitCollabNodeFromSharedType(binding, target);
+    if (collabNode instanceof CollabElementNode && event instanceof YTextEvent) {
+        // @ts-expect-error We need to access the private childListChanged property of the class
+        const { keysChanged, childListChanged, delta } = event;
+        // Update
+        if (keysChanged.size > 0) {
+            collabNode.syncPropertiesFromYjs(binding, keysChanged);
+        }
+        if (childListChanged) {
+            collabNode.applyChildrenYjsDelta(binding, delta);
+            collabNode.syncChildrenFromYjs(binding);
+        }
+    }
+    else if (collabNode instanceof CollabTextNode &&
+        event instanceof YMapEvent) {
+        const { keysChanged } = event;
+        // Update
+        if (keysChanged.size > 0) {
+            collabNode.syncPropertiesAndTextFromYjs(binding, keysChanged);
+        }
+    }
+    else if (collabNode instanceof CollabDecoratorNode &&
+        event instanceof YXmlEvent) {
+        const { attributesChanged } = event;
+        // Update
+        if (attributesChanged.size > 0) {
+            collabNode.syncPropertiesFromYjs(binding, attributesChanged);
+        }
+    }
+    else {
+        invariant(false, 'Expected text, element, or decorator event');
+    }
+}
+export function syncYjsUpdatesToLexical(binding, provider, events, isFromUndoManger, syncCursorPositionsFn = syncCursorPositions) {
+    const editor = binding.editor;
+    const currentEditorState = editor._editorState;
+    // This line precompute the delta before editor update. The reason is
+    // delta is computed when it is accessed. Note that this can only be
+    // safely computed during the event call. If it is accessed after event
+    // call it might result in unexpected behavior.
+    // https://github.com/yjs/yjs/blob/00ef472d68545cb260abd35c2de4b3b78719c9e4/src/utils/YEvent.js#L132
+    events.forEach((event) => event.delta);
+    editor.update(() => {
+        for (let i = 0; i < events.length; i++) {
+            const event = events[i];
+            $syncEvent(binding, event);
+        }
+        const selection = $getSelection();
+        if ($isRangeSelection(selection)) {
+            if (doesSelectionNeedRecovering(selection)) {
+                const prevSelection = currentEditorState._selection;
+                if ($isRangeSelection(prevSelection)) {
+                    $syncLocalCursorPosition(binding, provider);
+                    if (doesSelectionNeedRecovering(selection)) {
+                        // If the selected node is deleted, move the selection to the previous or parent node.
+                        const anchorNodeKey = selection.anchor.key;
+                        $moveSelectionToPreviousNode(anchorNodeKey, currentEditorState);
+                    }
+                }
+                syncLexicalSelectionToYjs(binding, provider, prevSelection, $getSelection());
+            }
+            else {
+                $syncLocalCursorPosition(binding, provider);
+            }
+        }
+        if (!isFromUndoManger) {
+            // If it is an external change, we don't want the current scroll position to get changed
+            // since the user might've intentionally scrolled somewhere else in the document.
+            $addUpdateTag(SKIP_SCROLL_INTO_VIEW_TAG);
+        }
+    }, {
+        onUpdate: () => {
+            syncCursorPositionsFn(binding, provider);
+            // If there was a collision on the top level paragraph
+            // we need to re-add a paragraph. To ensure this insertion properly syncs with other clients,
+            // it must be placed outside of the update block above that has tags 'collaboration' or 'historic'.
+            editor.update(() => {
+                if ($getRoot().getChildrenSize() === 0) {
+                    $getRoot().append($createParagraphNode());
+                }
+            });
+        },
+        skipTransforms: true,
+        tag: isFromUndoManger ? HISTORIC_TAG : COLLABORATION_TAG,
+    });
+}
+/******************************************************************************
+ * Lexical -> Yjs
+ *****************************************************************************/
+function $handleNormalizationMergeConflicts(binding, normalizedNodes) {
+    // We handle the merge operations here
+    const normalizedNodesKeys = Array.from(normalizedNodes);
+    const collabNodeMap = binding.collabNodeMap;
+    const mergedNodes = [];
+    const removedNodes = [];
+    for (let i = 0; i < normalizedNodesKeys.length; i++) {
+        const nodeKey = normalizedNodesKeys[i];
+        const lexicalNode = $getNodeByKey(nodeKey);
+        const collabNode = collabNodeMap.get(nodeKey);
+        if (collabNode instanceof CollabTextNode) {
+            if ($isTextNode(lexicalNode)) {
+                // We mutate the text collab nodes after removing
+                // all the dead nodes first, otherwise offsets break.
+                mergedNodes.push([collabNode, lexicalNode.__text]);
+            }
+            else {
+                const offset = collabNode.getOffset();
+                if (offset === -1) {
+                    continue;
+                }
+                const parent = collabNode._parent;
+                collabNode._normalized = true;
+                parent._xmlText.delete(offset, 1);
+                removedNodes.push(collabNode);
+            }
+        }
+    }
+    for (let i = 0; i < removedNodes.length; i++) {
+        const collabNode = removedNodes[i];
+        const nodeKey = collabNode.getKey();
+        collabNodeMap.delete(nodeKey);
+        const parentChildren = collabNode._parent._children;
+        const index = parentChildren.indexOf(collabNode);
+        parentChildren.splice(index, 1);
+    }
+    for (let i = 0; i < mergedNodes.length; i++) {
+        const [collabNode, text] = mergedNodes[i];
+        collabNode._text = text;
+    }
+}
+export function syncLexicalUpdatesToYjs(binding, provider, prevEditorState, currEditorState, dirtyElements, dirtyLeaves, normalizedNodes, tags) {
+    syncWithTransaction(binding, () => {
+        currEditorState.read(() => {
+            // We check if the update has come from a origin where the origin
+            // was the collaboration binding previously. This can help us
+            // prevent unnecessarily re-diffing and possible re-applying
+            // the same change editor state again. For example, if a user
+            // types a character and we get it, we don't want to then insert
+            // the same character again. The exception to this heuristic is
+            // when we need to handle normalization merge conflicts.
+            if (tags.has(COLLABORATION_TAG) || tags.has(HISTORIC_TAG)) {
+                if (normalizedNodes.size > 0) {
+                    $handleNormalizationMergeConflicts(binding, normalizedNodes);
+                }
+                return;
+            }
+            if (dirtyElements.has('root')) {
+                const prevNodeMap = prevEditorState._nodeMap;
+                const nextLexicalRoot = $getRoot();
+                const collabRoot = binding.root;
+                collabRoot.syncPropertiesFromLexical(binding, nextLexicalRoot, prevNodeMap);
+                collabRoot.syncChildrenFromLexical(binding, nextLexicalRoot, prevNodeMap, dirtyElements, dirtyLeaves);
+            }
+            const selection = $getSelection();
+            const prevSelection = prevEditorState._selection;
+            syncLexicalSelectionToYjs(binding, provider, prevSelection, selection);
+        });
+    });
+}

package/lib/collab/yjs/useCollaboration.d.ts

@@ -0,0 +1,12 @@
+import * as React from 'react';
+import type { JSX } from 'react';
+import { Doc } from 'yjs';
+import type { LexicalEditor } from 'lexical';
+import { InitialEditorStateType } from '@lexical/react/LexicalComposer';
+import type { Provider } from './State';
+import { Binding } from './Bindings';
+import { SyncCursorPositionsFn } from './sync/SyncCursors';
+export type CursorsContainerRef = React.MutableRefObject<HTMLElement | null>;
+export declare function useCollaboration(editor: LexicalEditor, id: string, provider: Provider, docMap: Map<string, Doc>, name: string, color: string, shouldBootstrap: boolean, binding: Binding, setDoc: React.Dispatch<React.SetStateAction<Doc | undefined>>, cursorsContainerRef?: CursorsContainerRef, initialEditorState?: InitialEditorStateType, awarenessData?: object, syncCursorPositionsFn?: SyncCursorPositionsFn): JSX.Element;
+export declare function useFocusTracking(editor: LexicalEditor, provider: Provider, name: string, color: string, awarenessData?: object): void;
+export declare function useHistory(editor: LexicalEditor, binding: Binding): () => void;

package/lib/collab/yjs/useCollaboration.js

@@ -0,0 +1,255 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from 'react';
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+import { createPortal } from 'react-dom';
+import { UndoManager } from 'yjs';
+import { $createParagraphNode, $getRoot, $getSelection, BLUR_COMMAND, CAN_REDO_COMMAND, CAN_UNDO_COMMAND, COMMAND_PRIORITY_EDITOR, FOCUS_COMMAND, HISTORY_MERGE_TAG, REDO_COMMAND, SKIP_COLLAB_TAG, UNDO_COMMAND, } from 'lexical';
+import { mergeRegister } from '@lexical/utils';
+import { CONNECTED_COMMAND, createUndoManager, initLocalState, setLocalStateFocus, TOGGLE_CONNECT_COMMAND, } from './State';
+import { syncYjsUpdatesToLexical, syncLexicalUpdatesToYjs } from './sync/SyncEditorStates';
+import { syncCursorPositions } from './sync/SyncCursors';
+export function useCollaboration(editor, id, provider, docMap, name, color, shouldBootstrap, binding, setDoc, cursorsContainerRef, initialEditorState, awarenessData, syncCursorPositionsFn = syncCursorPositions) {
+    const isReloadingDoc = useRef(false);
+    const connect = useCallback(() => provider.connect(), [provider]);
+    const disconnect = useCallback(() => {
+        try {
+            provider.disconnect();
+        }
+        catch (e) {
+            // Do nothing
+        }
+    }, [provider]);
+    useEffect(() => {
+        const { root } = binding;
+        const { awareness } = provider;
+        const onStatus = ({ status }) => {
+            editor.dispatchCommand(CONNECTED_COMMAND, status === 'connected');
+        };
+        const onSync = (isSynced) => {
+            if (shouldBootstrap &&
+                isSynced &&
+                root.isEmpty() &&
+                root._xmlText._length === 0 &&
+                isReloadingDoc.current === false) {
+                initializeEditor(editor, initialEditorState);
+            }
+            isReloadingDoc.current = false;
+        };
+        const onAwarenessUpdate = () => {
+            syncCursorPositionsFn(binding, provider);
+        };
+        initLocalState(provider, name, color, document.activeElement === editor.getRootElement(), awarenessData || {});
+        const onProviderDocReload = (ydoc) => {
+            clearEditorSkipCollab(editor, binding);
+            setDoc(ydoc);
+            docMap.set(id, ydoc);
+            isReloadingDoc.current = true;
+        };
+        provider.on('reload', onProviderDocReload);
+        provider.on('status', onStatus);
+        provider.on('sync', onSync);
+        awareness.on('update', onAwarenessUpdate);
+        const onYjsTreeChanges = (
+        // The below `any` type is taken directly from the vendor types for YJS.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        events, transaction) => {
+            const origin = transaction.origin;
+            if (origin !== binding) {
+                const isFromUndoManager = origin instanceof UndoManager;
+                syncYjsUpdatesToLexical(binding, provider, events, isFromUndoManager, syncCursorPositionsFn);
+            }
+        };
+        // This updates the local editor state when we receive updates from other clients
+        root.getSharedType().observeDeep(onYjsTreeChanges);
+        const removeListener = editor.registerUpdateListener(({ prevEditorState, editorState, dirtyLeaves, dirtyElements, normalizedNodes, tags, }) => {
+            if (tags.has(SKIP_COLLAB_TAG) === false) {
+                syncLexicalUpdatesToYjs(binding, provider, prevEditorState, editorState, dirtyElements, dirtyLeaves, normalizedNodes, tags);
+            }
+        });
+        const connectionPromise = connect();
+        return () => {
+            if (isReloadingDoc.current === false) {
+                if (connectionPromise) {
+                    connectionPromise.then(disconnect);
+                }
+                else {
+                    // Workaround for race condition in StrictMode. It's possible there
+                    // is a different race for the above case where connect returns a
+                    // promise, but we don't have an example of that in-repo.
+                    // It's possible that there is a similar issue with
+                    // TOGGLE_CONNECT_COMMAND below when the provider connect returns a
+                    // promise.
+                    // https://github.com/facebook/lexical/issues/6640
+                    disconnect();
+                }
+            }
+            provider.off('sync', onSync);
+            provider.off('status', onStatus);
+            provider.off('reload', onProviderDocReload);
+            awareness.off('update', onAwarenessUpdate);
+            root.getSharedType().unobserveDeep(onYjsTreeChanges);
+            docMap.delete(id);
+            removeListener();
+        };
+    }, [
+        binding,
+        color,
+        connect,
+        disconnect,
+        docMap,
+        editor,
+        id,
+        initialEditorState,
+        name,
+        provider,
+        shouldBootstrap,
+        awarenessData,
+        setDoc,
+        syncCursorPositionsFn,
+    ]);
+    const cursorsContainer = useMemo(() => {
+        const ref = (element) => {
+            binding.cursorsContainer = element;
+        };
+        return createPortal(_jsx("div", { ref: ref }), (cursorsContainerRef && cursorsContainerRef.current) || document.body);
+    }, [binding, cursorsContainerRef]);
+    useEffect(() => {
+        return editor.registerCommand(TOGGLE_CONNECT_COMMAND, (payload) => {
+            const shouldConnect = payload;
+            if (shouldConnect) {
+                connect();
+            }
+            else {
+                disconnect();
+            }
+            return true;
+        }, COMMAND_PRIORITY_EDITOR);
+    }, [connect, disconnect, editor]);
+    return cursorsContainer;
+}
+export function useFocusTracking(editor, provider, name, color, awarenessData) {
+    useEffect(() => {
+        return mergeRegister(editor.registerCommand(FOCUS_COMMAND, () => {
+            setLocalStateFocus(provider, name, color, true, awarenessData || {});
+            return false;
+        }, COMMAND_PRIORITY_EDITOR), editor.registerCommand(BLUR_COMMAND, () => {
+            setLocalStateFocus(provider, name, color, false, awarenessData || {});
+            return false;
+        }, COMMAND_PRIORITY_EDITOR));
+    }, [color, editor, name, provider, awarenessData]);
+}
+export function useHistory(editor, binding) {
+    const undoManager = useMemo(() => createUndoManager(binding, binding.root.getSharedType()), [binding]);
+    useEffect(() => {
+        const undo = () => {
+            undoManager.undo();
+        };
+        const redo = () => {
+            undoManager.redo();
+        };
+        return mergeRegister(editor.registerCommand(UNDO_COMMAND, () => {
+            undo();
+            return true;
+        }, COMMAND_PRIORITY_EDITOR), editor.registerCommand(REDO_COMMAND, () => {
+            redo();
+            return true;
+        }, COMMAND_PRIORITY_EDITOR));
+    });
+    const clearHistory = useCallback(() => {
+        undoManager.clear();
+    }, [undoManager]);
+    // Exposing undo and redo states
+    React.useEffect(() => {
+        const updateUndoRedoStates = () => {
+            editor.dispatchCommand(CAN_UNDO_COMMAND, undoManager.undoStack.length > 0);
+            editor.dispatchCommand(CAN_REDO_COMMAND, undoManager.redoStack.length > 0);
+        };
+        undoManager.on('stack-item-added', updateUndoRedoStates);
+        undoManager.on('stack-item-popped', updateUndoRedoStates);
+        undoManager.on('stack-cleared', updateUndoRedoStates);
+        return () => {
+            undoManager.off('stack-item-added', updateUndoRedoStates);
+            undoManager.off('stack-item-popped', updateUndoRedoStates);
+            undoManager.off('stack-cleared', updateUndoRedoStates);
+        };
+    }, [editor, undoManager]);
+    return clearHistory;
+}
+function initializeEditor(editor, initialEditorState) {
+    editor.update(() => {
+        const root = $getRoot();
+        if (root.isEmpty()) {
+            if (initialEditorState) {
+                switch (typeof initialEditorState) {
+                    case 'string': {
+                        const parsedEditorState = editor.parseEditorState(initialEditorState);
+                        editor.setEditorState(parsedEditorState, {
+                            tag: HISTORY_MERGE_TAG,
+                        });
+                        break;
+                    }
+                    case 'object': {
+                        editor.setEditorState(initialEditorState, {
+                            tag: HISTORY_MERGE_TAG,
+                        });
+                        break;
+                    }
+                    case 'function': {
+                        editor.update(() => {
+                            const root1 = $getRoot();
+                            if (root1.isEmpty()) {
+                                initialEditorState(editor);
+                            }
+                        }, { tag: HISTORY_MERGE_TAG });
+                        break;
+                    }
+                }
+            }
+            else {
+                const paragraph = $createParagraphNode();
+                root.append(paragraph);
+                const { activeElement } = document;
+                if ($getSelection() !== null ||
+                    (activeElement !== null &&
+                        activeElement === editor.getRootElement())) {
+                    paragraph.select();
+                }
+            }
+        }
+    }, {
+        tag: HISTORY_MERGE_TAG,
+    });
+}
+function clearEditorSkipCollab(editor, binding) {
+    // reset editor state
+    editor.update(() => {
+        const root = $getRoot();
+        root.clear();
+        root.select();
+    }, {
+        tag: SKIP_COLLAB_TAG,
+    });
+    if (binding.cursors == null) {
+        return;
+    }
+    const cursors = binding.cursors;
+    if (cursors == null) {
+        return;
+    }
+    const cursorsContainer = binding.cursorsContainer;
+    if (cursorsContainer == null) {
+        return;
+    }
+    // reset cursors in dom
+    const cursorsArr = Array.from(cursors.values());
+    for (let i = 0; i < cursorsArr.length; i++) {
+        const cursor = cursorsArr[i];
+        const selection = cursor.selection;
+        if (selection && selection.selections != null) {
+            const selections = selection.selections;
+            for (let j = 0; j < selections.length; j++) {
+                cursorsContainer.removeChild(selections[i]);
+            }
+        }
+    }
+}

package/lib/collab/yjs/utils/Utils.d.ts

@@ -0,0 +1,25 @@
+import { EditorState, LexicalNode, NodeKey, RangeSelection } from 'lexical';
+import { Map as YMap, XmlElement, XmlText } from 'yjs';
+import type { YjsNode } from './../State';
+import type { Binding } from './../Bindings';
+import { CollabElementNode } from './../nodes/CollabElementNode';
+import { AnyCollabNode } from '../nodes/AnyCollabNode';
+/*****************************************************************************/
+export declare function createLexicalNodeFromCollabNode(binding: Binding, collabNode: AnyCollabNode, parentKey: NodeKey): LexicalNode;
+export declare function getIndexOfYjsNode(yjsParentNode: YjsNode, yjsNode: YjsNode): number;
+export declare function getNodeTypeFromSharedType(sharedType: XmlText | YMap<unknown> | XmlElement): string | undefined;
+export declare function syncPropertiesFromLexical(binding: Binding, sharedType: XmlText | YMap<unknown> | XmlElement, prevLexicalNode: null | LexicalNode, nextLexicalNode: LexicalNode): void;
+export declare function spliceString(str: string, index: number, delCount: number, newText: string): string;
+export declare function getPositionFromElementAndOffset(node: CollabElementNode, offset: number, boundaryIsEdge: boolean): {
+    length: number;
+    node: AnyCollabNode | null;
+    nodeIndex: number;
+    offset: number;
+};
+export declare function doesSelectionNeedRecovering(selection: RangeSelection): boolean;
+export declare function syncWithTransaction(binding: Binding, fn: () => void): void;
+/*****************************************************************************/
+export declare function $createCollabNodeFromLexicalNode(binding: Binding, lexicalNode: LexicalNode, parent: CollabElementNode): AnyCollabNode;
+export declare function $getOrInitCollabNodeFromSharedType(binding: Binding, sharedType: XmlText | YMap<unknown> | XmlElement, parent?: CollabElementNode): AnyCollabNode;
+export declare function $syncPropertiesFromYjs(binding: Binding, sharedType: XmlText | YMap<unknown> | XmlElement, lexicalNode: LexicalNode, keysChanged: null | Set<string>): void;
+export declare function $moveSelectionToPreviousNode(anchorNodeKey: string, currentEditorState: EditorState): void;