@datalayer/lexical-loro 0.2.3 → 0.2.5

package/lib/collab/loro/State.d.ts

@@ -0,0 +1,53 @@
+import type { LexicalCommand } from 'lexical';
+import type { LoroDoc, Cursor } from 'loro-crdt';
+import { UndoManager } from 'loro-crdt';
+import type { Binding } from './Bindings';
+export type UserState = {
+    anchorPos: Cursor | null;
+    color: string;
+    focusing: boolean;
+    focusPos: Cursor | null;
+    name: string;
+    awarenessData: object;
+    [key: string]: unknown;
+};
+export declare const CONNECTED_COMMAND: LexicalCommand<boolean>;
+export declare const TOGGLE_CONNECT_COMMAND: LexicalCommand<boolean>;
+export type AwarenessProvider = {
+    getLocalState: () => UserState | null;
+    getStates: () => Map<number, UserState>;
+    off: (type: 'update', cb: () => void) => void;
+    on: (type: 'update', cb: () => void) => void;
+    setLocalState: (userState: UserState) => void;
+    setLocalStateField: (field: string, value: unknown) => void;
+};
+export type Provider = {
+    awareness: AwarenessProvider;
+    connect(): void | Promise<void>;
+    disconnect(): void;
+    off(type: 'sync', cb: (isSynced: boolean) => void): void;
+    off(type: 'update', cb: (update: unknown) => void): void;
+    off(type: 'status', cb: (status: {
+        status: string;
+    }) => void): void;
+    off(type: 'reload', cb: (doc: LoroDoc) => void): void;
+    on(type: 'sync', cb: (isSynced: boolean) => void): void;
+    on(type: 'status', cb: (status: {
+        status: string;
+    }) => void): void;
+    on(type: 'update', cb: (update: unknown) => void): void;
+    on(type: 'reload', cb: (doc: LoroDoc) => void): void;
+};
+export type Operation = {
+    attributes: {
+        __type: string;
+    };
+    insert: string | Record<string, unknown>;
+};
+export type Delta = Array<Operation>;
+export type LoroNode = Record<string, unknown>;
+export type LoroEvent = Record<string, unknown>;
+export declare function createUndoManager(binding: Binding): UndoManager;
+export declare function initLocalState(provider: Provider, name: string, color: string, focusing: boolean, awarenessData: object): void;
+export declare function setLocalStateFocus(provider: Provider, name: string, color: string, focusing: boolean, awarenessData: object): void;
+export declare function updateLocalStateName(provider: Provider, name: string, color: string): void;

package/lib/collab/loro/State.js

@@ -0,0 +1,94 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the MIT License.
+ */
+import { createCommand } from 'lexical';
+import { UndoManager } from 'loro-crdt';
+export const CONNECTED_COMMAND = createCommand('CONNECTED_COMMAND');
+export const TOGGLE_CONNECT_COMMAND = createCommand('TOGGLE_CONNECT_COMMAND');
+export function createUndoManager(binding) {
+    // Create Loro UndoManager with configuration
+    const undoManager = new UndoManager(binding.doc, {
+        mergeInterval: 1000, // Merge operations within 1 second
+        maxUndoSteps: 100, // Keep up to 100 undo steps
+        excludeOriginPrefixes: ['collab-', 'sync-'], // Exclude collaboration operations
+        /*
+        onPush: (isUndo, counterRange, event) => {
+          // Save cursor positions when adding to undo stack
+          const selection = binding.editor.getEditorState().read(() => {
+            return binding.editor.getEditorState()._selection;
+          });
+          // Get cursors for the current state
+          const cursors: Cursor[] = [];
+          if (selection) {
+            // TODO: Convert Lexical selection to Loro cursors
+            // This would need to be implemented based on the specific selection format
+          }
+          return {
+            value: binding.doc.toJSON(), // Save document state
+            cursors: cursors
+          };
+        },
+        onPop: (isUndo, metadata, counterRange) => {
+          // Restore cursor positions when undoing/redoing
+          if (metadata?.cursors && metadata.cursors.length > 0) {
+            binding.editor.update(() => {
+              // TODO: Restore selection state from cursors
+              // This would need to convert Loro cursors back to Lexical selection
+            });
+          }
+        }
+        */
+    });
+    return undoManager;
+}
+export function initLocalState(provider, name, color, focusing, awarenessData) {
+    provider.awareness.setLocalState({
+        anchorPos: null,
+        awarenessData,
+        color,
+        focusPos: null,
+        focusing,
+        name,
+    });
+}
+export function setLocalStateFocus(provider, name, color, focusing, awarenessData) {
+    const { awareness } = provider;
+    let localState = awareness.getLocalState();
+    if (localState === null) {
+        localState = {
+            anchorPos: null,
+            awarenessData,
+            color,
+            focusPos: null,
+            focusing: focusing,
+            name,
+        };
+    }
+    // Always update name and color in case they changed
+    localState.name = name;
+    localState.color = color;
+    localState.focusing = focusing;
+    awareness.setLocalState(localState);
+}
+export function updateLocalStateName(provider, name, color) {
+    const { awareness } = provider;
+    let localState = awareness.getLocalState();
+    if (localState === null) {
+        // Initialize with the new name if no state exists
+        localState = {
+            anchorPos: null,
+            awarenessData: {},
+            color,
+            focusPos: null,
+            focusing: false,
+            name,
+        };
+    }
+    else {
+        // Update existing state with new name and color
+        localState.name = name;
+        localState.color = color;
+    }
+    awareness.setLocalState(localState);
+}

package/lib/collab/loro/components/LoroCollaborationUI.d.ts

@@ -0,0 +1,13 @@
+import type { Binding } from '../Bindings';
+export interface LoroCollaborationUIProps {
+    binding: Binding;
+    cursorsContainer: JSX.Element | null;
+    currentUserName?: string;
+    currentUserColor?: string;
+    showCollaborators?: boolean;
+}
+/**
+ * Combines the cursors container with the collaborators list
+ */
+export declare function LoroCollaborationUI({ binding, cursorsContainer, currentUserName, currentUserColor, showCollaborators }: LoroCollaborationUIProps): JSX.Element;
+export default LoroCollaborationUI;

package/lib/collab/loro/components/LoroCollaborationUI.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { LoroCollaborators } from './LoroCollaborators';
+/**
+ * Combines the cursors container with the collaborators list
+ */
+export function LoroCollaborationUI({ binding, cursorsContainer, currentUserName = 'You', currentUserColor = '#007acc', showCollaborators = true }) {
+    return (_jsxs(_Fragment, { children: [showCollaborators && (_jsx(LoroCollaborators, { binding: binding, currentUserName: currentUserName, currentUserColor: currentUserColor })), cursorsContainer] }));
+}
+export default LoroCollaborationUI;

package/lib/collab/loro/components/LoroCollaborators.d.ts

@@ -0,0 +1,8 @@
+import type { Binding } from '../Bindings';
+export interface LoroCollaboratorsProps {
+    binding: Binding;
+    currentUserName?: string;
+    currentUserColor?: string;
+}
+export declare function LoroCollaborators({ binding, currentUserName, currentUserColor }: LoroCollaboratorsProps): JSX.Element;
+export default LoroCollaborators;

package/lib/collab/loro/components/LoroCollaborators.js

@@ -0,0 +1,102 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the MIT License.
+ */
+import { useState, useEffect } from 'react';
+export function LoroCollaborators({ binding, currentUserName = 'Me', currentUserColor = '#007acc' }) {
+    // Force re-render when cursors change
+    const [updateTrigger, setUpdateTrigger] = useState(0);
+    // Monitor cursors map changes
+    useEffect(() => {
+        const interval = setInterval(() => {
+            setUpdateTrigger(prev => prev + 1);
+        }, 1000); // Check for updates every second
+        return () => clearInterval(interval);
+    }, []);
+    // Get current user's client ID
+    const currentClientID = binding.clientID;
+    // Debug: Log cursor information
+    const allCursorsDebug = Array.from(binding.cursors.entries()).map(([id, cursor]) => ({
+        clientId: id,
+        name: cursor.name,
+        color: cursor.color,
+        isCurrentUser: id === currentClientID
+    }));
+    // Get all collaborators including current user
+    const allCollaborators = Array.from(binding.cursors.entries())
+        .map(([clientId, cursor]) => ({ clientId, cursor, isCurrentUser: clientId === currentClientID }));
+    // Get current user's cursor if it exists
+    const currentUserCursor = binding.cursors.get(currentClientID);
+    const currentDisplayColor = currentUserCursor?.color || currentUserColor;
+    const currentDisplayName = currentUserCursor?.name || currentUserName;
+    // Separate current user and others for display order (current user first)
+    const currentUserData = allCollaborators.find(({ isCurrentUser }) => isCurrentUser);
+    const otherCollaborators = allCollaborators.filter(({ isCurrentUser }) => !isCurrentUser);
+    return (_jsxs("div", { style: {
+            display: 'flex',
+            alignItems: 'center',
+            padding: '8px 12px',
+            backgroundColor: 'var(--bgColor-muted, #f8f9fa)',
+            borderBottom: '1px solid var(--borderColor-default, #e1e5e9)',
+            fontSize: '14px',
+            fontFamily: 'system-ui, -apple-system, sans-serif',
+            gap: '8px',
+            flexWrap: 'wrap',
+            color: 'var(--fgColor-default, inherit)',
+        }, children: [currentUserData && (_jsx(CollaboratorBadge, { name: `${currentUserData.cursor.name}`, color: currentDisplayColor, isCurrentUser: true, clientId: currentClientID })), !currentUserData && (_jsx(CollaboratorBadge, { name: `${currentDisplayName} (Me)`, color: currentDisplayColor, isCurrentUser: true, clientId: currentClientID })), otherCollaborators.length > 0 && (_jsx("div", { style: {
+                    width: '1px',
+                    height: '20px',
+                    backgroundColor: 'var(--borderColor-muted, #d1d5db)',
+                    margin: '0 4px'
+                } })), otherCollaborators.map(({ clientId, cursor }) => (_jsx(CollaboratorBadge, { name: cursor.name, color: cursor.color, isCurrentUser: false, clientId: clientId }, clientId))), otherCollaborators.length === 0 && (_jsx("span", { style: {
+                    color: 'var(--fgColor-muted, #6b7280)',
+                    fontStyle: 'italic',
+                    marginLeft: '8px'
+                }, children: "No other collaborators" }))] }));
+}
+function CollaboratorBadge({ name, color, isCurrentUser, clientId }) {
+    // Convert color to rgba for transparency when current user
+    const getColorWithOpacity = (color, opacity = 1) => {
+        // If it's a hex color, convert to rgba
+        if (color.startsWith('#')) {
+            const hex = color.slice(1);
+            const r = parseInt(hex.slice(0, 2), 16);
+            const g = parseInt(hex.slice(2, 4), 16);
+            const b = parseInt(hex.slice(4, 6), 16);
+            return `rgba(${r}, ${g}, ${b}, ${opacity})`;
+        }
+        // If it's already rgba or rgb, just return as is (basic support)
+        return color;
+    };
+    const circleColor = isCurrentUser ? getColorWithOpacity(color, 0.1) : color;
+    const badgeColor = isCurrentUser ? getColorWithOpacity(color, 0.1) : color;
+    return (_jsxs("div", { style: {
+            display: 'flex',
+            alignItems: 'center',
+            gap: '6px'
+        }, title: `${name} (Client ID: ${clientId})`, children: [_jsx("div", { style: {
+                    width: '12px',
+                    height: '12px',
+                    borderRadius: '50%',
+                    backgroundColor: circleColor,
+                    border: isCurrentUser ? '2px solid #ffffff' : 'none',
+                    boxShadow: isCurrentUser ? '0 0 0 1px #d1d5db' : 'none',
+                    flexShrink: 0
+                } }), _jsx("span", { style: {
+                    backgroundColor: badgeColor,
+                    color: '#ffffff',
+                    padding: '3px 8px',
+                    borderRadius: '12px',
+                    fontSize: '12px',
+                    fontWeight: '500',
+                    lineHeight: '1.2',
+                    whiteSpace: 'nowrap',
+                    textShadow: '0 1px 2px rgba(0,0,0,0.1)',
+                    boxShadow: isCurrentUser
+                        ? '0 1px 3px rgba(0,0,0,0.2), inset 0 1px 0 rgba(255,255,255,0.2)'
+                        : '0 1px 2px rgba(0,0,0,0.1)',
+                    opacity: isCurrentUser ? 0.9 : 1
+                }, children: name })] }));
+}
+export default LoroCollaborators;

package/lib/collab/loro/components/index.d.ts

@@ -0,0 +1,2 @@
+export { LoroCollaborators, type LoroCollaboratorsProps } from './LoroCollaborators';
+export { LoroCollaborationUI, type LoroCollaborationUIProps } from './LoroCollaborationUI';

package/lib/collab/loro/components/index.js

@@ -0,0 +1,6 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the MIT License.
+ */
+export { LoroCollaborators } from './LoroCollaborators';
+export { LoroCollaborationUI } from './LoroCollaborationUI';

package/lib/collab/loro/index.d.ts

@@ -0,0 +1,6 @@
+export * from './Bindings';
+export * from './LexicalCollaborationContext';
+export * from './LexicalCollaborationPlugin';
+export * from './State';
+export * from './useCollaboration';
+export * from './wsProvider';

package/lib/collab/loro/index.js

@@ -0,0 +1,10 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the MIT License.
+ */
+export * from './Bindings';
+export * from './LexicalCollaborationContext';
+export * from './LexicalCollaborationPlugin';
+export * from './State';
+export * from './useCollaboration';
+export * from './wsProvider';

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

@@ -0,0 +1,14 @@
+import { Binding } from '../Bindings';
+import { Provider } from '../State';
+/**
+ * Base interface for all diff integrators
+ */
+export interface BaseIntegrator<T = any> {
+    /**
+     * Handle the diff event
+     * @param diff The diff event to integrate
+     * @param binding The binding instance
+     * @param provider The provider instance
+     */
+    integrate(diff: T, binding: Binding, provider: Provider): void;
+}

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

@@ -0,0 +1,5 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the MIT License.
+ */
+export {};

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

@@ -0,0 +1,23 @@
+import { BaseIntegrator } from './BaseIntegrator';
+import { Binding } from '../Bindings';
+import { Provider } from '../State';
+interface CounterDiff {
+    type: 'counter';
+    increment?: number;
+    value?: number;
+}
+/**
+ * Handles counter changes (increment/decrement operations)
+ */
+export declare class CounterIntegrator implements BaseIntegrator<CounterDiff> {
+    integrate(diff: CounterDiff, binding: Binding, provider: Provider): void;
+    integrateInternal(diff: CounterDiff, binding: Binding, provider: Provider): void;
+    private integrateIncrement;
+    private integrateSetValue;
+    /**
+     * Helper method to update a counter property in a specific node
+     * This would be used when counters are associated with particular nodes
+     */
+    private updateNodeCounter;
+}
+export {};

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

@@ -0,0 +1,44 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the MIT License.
+ */
+/**
+ * Handles counter changes (increment/decrement operations)
+ */
+export class CounterIntegrator {
+    integrate(diff, binding, provider) {
+        this.integrateInternal(diff, binding, provider);
+    }
+    // Internal method for use when already inside editor.update()
+    integrateInternal(diff, binding, provider) {
+        if (diff.increment !== undefined) {
+            this.integrateIncrement(diff.increment, binding, provider);
+        }
+        if (diff.value !== undefined) {
+            this.integrateSetValue(diff.value, binding, provider);
+        }
+    }
+    integrateIncrement(increment, binding, provider) {
+        // Counter operations in Lexical context might be used for:
+        // - Version numbers
+        // - Reference counts
+        // - Numeric properties in nodes
+        // - Analytics or tracking data
+        // For now, this is a placeholder since counters are not commonly
+        // used in basic text editing scenarios
+    }
+    integrateSetValue(value, binding, provider) {
+        // Similar to increment, the specific implementation would depend
+        // on what the counter represents in the document structure
+    }
+    /**
+     * Helper method to update a counter property in a specific node
+     * This would be used when counters are associated with particular nodes
+     */
+    updateNodeCounter(nodeKey, counterName, operation, value, binding) {
+        // This is a hypothetical implementation
+        // Real usage would depend on how counters are integrated into the document model
+        // In practice, this might update metadata or special numeric properties
+        // associated with Lexical nodes
+    }
+}

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

@@ -0,0 +1,23 @@
+import { BaseIntegrator } from './BaseIntegrator';
+import { Binding } from '../Bindings';
+import { Provider } from '../State';
+interface ListDiff {
+    type: 'list';
+    diff?: Array<{
+        type: 'insert' | 'delete' | 'retain';
+        index?: number;
+        length?: number;
+        value?: any;
+    }>;
+}
+/**
+ * Handles list changes (insertions, deletions, moves in ordered structures)
+ */
+export declare class ListIntegrator implements BaseIntegrator<ListDiff> {
+    integrate(diff: ListDiff, binding: Binding, provider: Provider): void;
+    integrateInternal(diff: ListDiff, binding: Binding, provider: Provider): void;
+    private integrateInsert;
+    private integrateDelete;
+    private integrateRetain;
+}
+export {};

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

@@ -0,0 +1,53 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the MIT License.
+ */
+/**
+ * Handles list changes (insertions, deletions, moves in ordered structures)
+ */
+export class ListIntegrator {
+    integrate(diff, binding, provider) {
+        console.log('📋 Handling ListDiff:', diff);
+        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.integrateInsert(change, binding, provider);
+                        break;
+                    case 'delete':
+                        this.integrateDelete(change, binding, provider);
+                        break;
+                    case 'retain':
+                        this.integrateRetain(change, binding, provider);
+                        break;
+                    default:
+                        console.warn(`📋 Unknown list change type: ${change.type}`);
+                }
+            });
+        }
+    }
+    integrateInsert(change, binding, provider) {
+        // This typically represents insertion of child nodes in an ElementNode
+        // The actual node creation should be integrated by TreeIntegrator
+        // This integrater focuses on the ordering and position updates
+        // For now, log the operation - specific implementation would depend on
+        // the context of which list/container this change applies to
+    }
+    integrateDelete(change, binding, provider) {
+        // This typically represents removal of child nodes from an ElementNode
+        // The actual node deletion should be integrated by TreeIntegrator
+        // This integrater focuses on the ordering and position updates
+    }
+    integrateRetain(change, binding, provider) {
+        // Retain operations typically don't require action in Lexical
+        // They represent portions of the list that remain unchanged
+        if (change.attributes) {
+            console.log(`📋 List retain with attributes at ${change.index}, length: ${change.length}`, change.attributes);
+            // Handle any attribute changes if needed
+        }
+    }
+}

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

@@ -0,0 +1,24 @@
+import { BaseIntegrator } from './BaseIntegrator';
+import { Binding } from '../Bindings';
+import { Provider } from '../State';
+interface MapDiff {
+    type: 'map';
+    updated?: Record<string, any>;
+    deleted?: string[];
+}
+/**
+ * Handles map data changes (node properties, metadata updates)
+ */
+export declare class MapIntegrator implements BaseIntegrator<MapDiff> {
+    integrate(diff: MapDiff, binding: Binding, provider: Provider): void;
+    integrateWithContext(diff: MapDiff, treeId: any, binding: Binding, provider: Provider): void;
+    integrateInternal(diff: MapDiff, binding: Binding, provider: Provider): void;
+    integrateWithContextInternal(diff: MapDiff, treeId: any, binding: Binding, provider: Provider): void;
+    private integratePropertyUpdateWithContext;
+    private integratePropertyUpdateWithContextInternal;
+    private integratePropertyUpdate;
+    private integratePropertyDelete;
+    private integrateLexicalDataUpdateWithContext;
+    private integrateLexicalDataUpdateInternal;
+}
+export {};