@veltdev/lexical-velt-comments 1.0.0

package/esm/types/editor.d.ts

@@ -0,0 +1,384 @@
+import { LexicalEditor, LexicalNode, RangeSelection, TextNode } from 'lexical';
+import { CommentNode } from './comment-node';
+import type { Plugin } from './plugin';
+import { AnnotationData } from './types';
+interface TextMatch {
+    start: number;
+    end: number;
+    startNode?: LexicalNode;
+    endNode?: LexicalNode;
+}
+/**
+ * Interface for tracking annotation data during processing
+ */
+interface AnnotationToCheck {
+    id: string;
+    multiThreadAnnotationId?: string;
+    annotation: AnnotationData;
+    nodes: {
+        node: {
+            text?: string;
+            nodeSize?: number;
+        };
+        pos: number;
+    }[];
+    originalText: string;
+    originalOccurrence: number;
+    targetTextNodeId: string;
+}
+/**
+ * Interface for tracking annotation changes during a transaction
+ */
+interface AnnotationChange {
+    annotationId: string;
+    multiThreadAnnotationId?: string;
+    originalText: string;
+    currentText: string;
+    originalOccurrence: number;
+    currentOccurrence: number;
+    originalTargetTextNodeId: string;
+    newTargetTextNodeId: string;
+    annotation: any;
+    contentChanged: boolean;
+    occurrenceChanged: boolean;
+    targetTextNodeIdChanged: boolean;
+}
+export declare class EditorService {
+    plugin: Plugin;
+    private editorUpdateListenerRemover?;
+    constructor(plugin: Plugin);
+    static getEditorId: (editor: LexicalEditor) => string | null;
+    /**
+     * Initialize the transaction listener (equivalent to TipTap's onTransaction)
+     * Call this method when setting up the plugin
+     */
+    initializeTransactionListener(editor: LexicalEditor): void;
+    /**
+     * Clean up the transaction listener
+     */
+    destroyTransactionListener(): void;
+    /**
+     * Check if the document content has actually changed
+     */
+    private hasDocumentChanged;
+    /**
+     * Process editor changes
+     */
+    onTransaction(editor: LexicalEditor): void;
+    /**
+     * Extract text from a CommentNode while preserving paragraph structure.
+     * This method ensures that text extracted from existing comment nodes maintains
+     * the same newline characters that were present during initial selection.
+     *
+     * @param commentNode - The CommentNode to extract text from
+     * @returns Text content with preserved paragraph breaks (newlines)
+     */
+    private getCommentNodeTextWithStructure;
+    /**
+     * Collect all annotations present in the document for processing
+     */
+    collectDocumentAnnotations(editor: LexicalEditor): Map<string, AnnotationToCheck>;
+    /**
+     * Process annotation changes
+     */
+    processAnnotationChanges(editor: LexicalEditor, data: AnnotationToCheck): AnnotationChange | null;
+    /**
+     * Detect content changes while preserving paragraph structure.
+     * When multiple CommentNodes represent different paragraphs of the same annotation,
+     * we need to join them with newlines to match the original text format.
+     */
+    detectContentChanges(nodes: AnnotationToCheck['nodes'], originalText: string): {
+        currentText: string;
+        contentChanged: boolean;
+    };
+    /**
+     * Detect container changes
+     */
+    detectContainerChanges(editor: LexicalEditor, params: {
+        annotationId?: string;
+        currentText: string;
+        targetTextNodeId: string;
+        nodes: AnnotationToCheck['nodes'];
+    }): {
+        targetTextNodeIdChanged: boolean;
+        newTargetTextNodeId: string;
+        searchResults: TextMatch[];
+    };
+    /**
+     * Process container changes
+     */
+    processContainerChanges(editor: LexicalEditor, params: {
+        annotationId?: string;
+        currentText: string;
+        targetTextNodeId: string;
+        nodes: {
+            node: {
+                text?: string;
+                nodeSize?: number;
+            };
+            pos: number;
+        }[];
+    }): {
+        changed: boolean;
+        newId: string;
+        searchResults: TextMatch[];
+    } | null;
+    /**
+     * Find new container for moved content
+     */
+    findNewContainer(editor: LexicalEditor, currentText: string): HTMLElement | null;
+    /**
+     * Calculate new occurrence
+     */
+    calculateNewOccurrence(editor: LexicalEditor, params: {
+        searchResults: TextMatch[];
+        nodes: {
+            node: {
+                text?: string;
+                nodeSize?: number;
+            };
+            pos: number;
+        }[];
+        contentChanged: boolean;
+        currentText: string;
+        targetTextNodeId: string | null;
+        originalOccurrence: number;
+    }): number;
+    /**
+     * Create annotation change object
+     */
+    createAnnotationChange(data: AnnotationToCheck, changes: {
+        currentText: string;
+        contentChanged: boolean;
+        currentOccurrence: number;
+        occurrenceChanged: boolean;
+        targetTextNodeIdChanged: boolean;
+        newTargetTextNodeId: string;
+    }): AnnotationChange;
+    /**
+     * Update Velt comments
+     */
+    updateVeltComments(commentElement: {
+        updateContext: (id: string, context: unknown) => void;
+    }, changes: Map<string, AnnotationChange>, editor: LexicalEditor): Promise<void>;
+    getSelectedText(editor: LexicalEditor): string;
+    /**
+     * Find occurrence index of selected text in Lexical editor.
+     * This method determines which occurrence of a text pattern the current selection represents,
+     * which is crucial for multi-paragraph text selections that span across different paragraphs.
+     *
+     * @param editor - The Lexical editor instance
+     * @param selectedText - The text that is currently selected (may include newlines for multi-paragraph selections)
+     * @param targetContainer - Optional container element to limit search scope
+     * @returns The 1-indexed occurrence number of the selected text
+     */
+    findOccurrenceIndex(editor: LexicalEditor, selectedText: string, targetContainer: HTMLElement | null): number;
+    /**
+     * Get the text range of current selection, accounting for paragraph breaks.
+     * This method maps Lexical selection positions to text offsets in the combined text
+     * representation that includes newline characters between paragraphs.
+     *
+     * @param editor - The Lexical editor instance
+     * @param selection - The current range selection
+     * @returns Object with start and end positions in the combined text
+     */
+    getSelectionTextRange(editor: LexicalEditor, selection: RangeSelection): {
+        start: number;
+        end: number;
+    };
+    /**
+     * Collect all text content including paragraph breaks.
+     * This method creates a combined text representation of the entire document,
+     * inserting newline characters between paragraphs to maintain text structure
+     * for accurate multi-paragraph text matching.
+     *
+     * @param root - The root Lexical node to traverse
+     * @returns Object containing:
+     *   - combinedText: Complete text with newlines between paragraphs
+     *   - nodeMap: Array mapping each text node and paragraph break to its position
+     */
+    collectTextContent(root: LexicalNode): {
+        combinedText: string;
+        nodeMap: {
+            node: TextNode | null;
+            start: number;
+            end: number;
+            isParagraphBreak?: boolean;
+        }[];
+    };
+    /**
+     * Find all text occurrences in the entire Lexical editor.
+     * This method supports multi-paragraph text search by using the combined text
+     * representation that includes newline characters between paragraphs.
+     *
+     * @param editor - The Lexical editor instance
+     * @param searchText - The text to search for (may include newlines for multi-paragraph searches)
+     * @returns Array of TextMatch objects with start and end positions
+     */
+    findTextInEditor(editor: LexicalEditor, searchText: string): TextMatch[];
+    /**
+     * Find text occurrences within a specific DOM container (Updated to handle paragraph breaks)
+     */
+    findTextInContainer(editor: LexicalEditor, searchText: string, containerId: string): TextMatch[];
+    /**
+     * Get text content for a specific container
+     */
+    getContainerTextContent(containerElement: HTMLElement, editor: LexicalEditor, nodeMap: {
+        node: TextNode | null;
+        start: number;
+        end: number;
+        isParagraphBreak?: boolean;
+    }[], combinedText: string): {
+        text: string;
+        startOffset: number;
+    } | null;
+    /**
+     * Filter text nodes that are within a specific DOM container
+     */
+    filterNodesInContainer(textNodes: any[], containerElement: HTMLElement, editor: LexicalEditor): any[];
+    /**
+     * Collect all text nodes with their cumulative text offsets (helper method)
+     */
+    collectTextNodes(root: LexicalNode): {
+        node: TextNode;
+        text: string;
+        textOffset: number;
+    }[];
+    /**
+     * Get text nodes within a specific character range (Updated to handle paragraph breaks)
+     */
+    getTextNodesInRange(root: LexicalNode, fromPos: number, toPos: number, excludeAnnotationId?: string): {
+        node: TextNode;
+        startOffset: number;
+        endOffset: number;
+        isPartial: boolean;
+    }[];
+    /**
+     * Check if a text range is already wrapped (Updated to handle paragraph breaks)
+     */
+    isRangeAlreadyWrapped(root: LexicalNode, fromPos: number, toPos: number, annotationId: string): boolean;
+    /**
+     * Collect text nodes within a specific range
+     */
+    collectTextNodesInRange(root: LexicalNode, range: {
+        start: number;
+        end: number;
+    }): {
+        node: TextNode;
+        text: string;
+        start: number;
+        end: number;
+    }[];
+    /**
+     * Get the text range for a specific DOM container
+     */
+    getContainerRange(editor: LexicalEditor, containerElement: HTMLElement): {
+        start: number;
+        end: number;
+    } | null;
+    /**
+     * KMP Search implementation
+     */
+    kmpSearch(text: string, pattern: string, startPos?: number, maxOccurrences?: number): number[];
+    /**
+     * Compute KMP failure function
+     */
+    computeKMPTable(pattern: string): number[];
+    findParentContainerWithId(selection: RangeSelection, editor: LexicalEditor): HTMLElement | null;
+    /**
+     * Highlights text in the editor with a Velt comment annotation.
+     * This method supports multi-paragraph text highlighting by preserving paragraph structure
+     * and creating separate comment nodes for each paragraph when necessary.
+     *
+     * @param editor - The Lexical editor instance
+     * @param textToFind - The text to highlight (may include newlines for multi-paragraph selections)
+     * @param commentOptions - Configuration options for the comment annotation
+     */
+    highlightTextWithVeltComment(editor: LexicalEditor, textToFind: string, commentOptions: {
+        annotationId?: string;
+        multiThreadAnnotationId?: string;
+        occurrence?: number;
+        targetTextNodeId?: string;
+        originalAnnotation?: any;
+    }): void;
+    /**
+     * Find text within a specific DOM element
+     */
+    findTextInDomElement(editor: LexicalEditor, text: string, domElementId: string, desiredOccurrence?: number): TextMatch[];
+    /**
+     * Find text in the entire document with support for multi-paragraph searches.
+     * This method is used by the highlighting system to locate text that needs to be wrapped
+     * with comment annotations, including text that spans across multiple paragraphs.
+     *
+     * @param editor - The Lexical editor instance
+     * @param text - The text to search for (may include newlines for multi-paragraph searches)
+     * @param desiredOccurrence - Optional limit on the number of occurrences to find
+     * @returns Array of TextMatch objects with start and end positions
+     */
+    findTextInDocument(editor: LexicalEditor, text: string, desiredOccurrence?: number): TextMatch[];
+    /**
+     * Creates a Velt comment highlight at the specified range.
+     * This method intelligently handles different scenarios including single text nodes,
+     * partial text nodes, and multi-paragraph selections while preserving document structure.
+     *
+     * @param editor - The Lexical editor instance
+     * @param annotationId - The annotation ID for the comment
+     * @param multiThreadAnnotationId - Optional multi-thread annotation ID
+     * @param fromPos - Start position in the combined text representation
+     * @param toPos - End position in the combined text representation
+     */
+    setVeltComment(editor: LexicalEditor, annotationId: string, multiThreadAnnotationId: string | undefined, fromPos: number, toPos: number): void;
+    /**
+     * Wrap a partial text node (when selection is within the node) - PRESERVING FORMATTING
+     */
+    wrapPartialTextNode(textNode: TextNode, startOffset: number, endOffset: number, commentNode: CommentNode): void;
+    /**
+     * Wrap an entire text node - PRESERVING FORMATTING
+     */
+    wrapEntireTextNode(textNode: TextNode, commentNode: CommentNode): void;
+    /**
+     * Wrap multiple text nodes while preserving formatting and paragraph structure.
+     * This method groups text nodes by their paragraph parent and creates separate
+     * comment nodes for each paragraph to maintain document structure integrity.
+     *
+     * @param textNodesToWrap - Array of text nodes with their offset information
+     * @param commentNode - The base comment node to use (additional nodes will be created for other paragraphs)
+     */
+    wrapMultipleTextNodesWithFormatting(textNodesToWrap: {
+        node: TextNode;
+        startOffset: number;
+        endOffset: number;
+        isPartial: boolean;
+    }[], commentNode: CommentNode): void;
+    /**
+     * Find the paragraph parent of a text node.
+     * Traverses up the node hierarchy to find the paragraph element that contains this text node.
+     *
+     * @param node - The text node to find the paragraph parent for
+     * @returns The paragraph node or null if not found
+     */
+    findParagraphParent(node: TextNode): LexicalNode | null;
+    /**
+     * Wrap multiple text nodes within the same paragraph.
+     * This method handles complex scenarios where multiple text nodes need to be wrapped
+     * while maintaining their original formatting and order within the paragraph.
+     *
+     * @param nodesInParagraph - Array of text nodes within the same paragraph
+     * @param commentNode - The comment node to wrap the text nodes with
+     */
+    wrapMultipleNodesInSameParagraph(nodesInParagraph: {
+        node: TextNode;
+        startOffset: number;
+        endOffset: number;
+        isPartial: boolean;
+    }[], commentNode: CommentNode): void;
+    /**
+     * Removes a Velt comment from the Lexical document
+     * @param editor - The Lexical editor instance
+     * @param annotationId - The ID of the annotation to remove
+     * @returns boolean - True if the annotation was successfully removed, false otherwise
+     * @throws Error if the stored data is invalid
+     */
+    removeVeltCommentFromEditor(editor: LexicalEditor, annotationId: string): boolean;
+}
+export {};

package/esm/types/index.d.ts

@@ -0,0 +1,24 @@
+import { CommentAnnotation } from '@veltdev/types';
+import { LexicalEditor } from 'lexical';
+import { LexicalVeltCommentConfig } from "./types";
+export * from './comment-node';
+export * from './serializer';
+export declare const triggerAddComment: (editor: LexicalEditor, config?: LexicalVeltCommentConfig) => Promise<void>;
+export interface AddCommentRequest {
+    editorId?: string;
+    editor: LexicalEditor;
+    context?: unknown;
+}
+/**
+ * Creates a comment annotation for the currently selected text in the editor
+ * This function handles the entire flow from getting the selected text to creating
+ * the actual comment through the Velt service
+ */
+export declare const addComment: ({ editorId, editor, context: clientContext, }: AddCommentRequest) => Promise<void>;
+export declare function highlightComments(editor: LexicalEditor, commentAnnotations: CommentAnnotation[], editorId?: string): void;
+export interface RenderCommentsRequest {
+    editor: LexicalEditor;
+    editorId?: string;
+    commentAnnotations?: CommentAnnotation[];
+}
+export declare const renderComments: ({ editor, editorId, commentAnnotations }: RenderCommentsRequest) => void;

package/esm/types/plugin.d.ts

@@ -0,0 +1,14 @@
+import { LexicalEditor } from 'lexical';
+import { EditorService } from './editor';
+import { StoreService } from './store';
+export declare class Plugin {
+    editorId: string;
+    editor: LexicalEditor | undefined;
+    editorService: EditorService;
+    storeService: StoreService;
+    constructor(editorId: string, editor?: LexicalEditor);
+    static getInstance(config?: {
+        editorId?: string | null;
+        editor?: LexicalEditor;
+    }): Plugin;
+}

package/esm/types/serializer.d.ts

@@ -0,0 +1,9 @@
+import { LexicalEditor } from "lexical";
+/**
+ * Enhanced export function with multiple strategies
+ */
+export declare const exportCleanEditorContent: (editor: LexicalEditor) => string;
+/**
+ * Deserializes editor state from clean JSON
+ */
+export declare function deserializeCleanState(editor: LexicalEditor, jsonString: string): void;

package/esm/types/store.d.ts

@@ -0,0 +1,39 @@
+import type { CommentAnnotation } from '@veltdev/types';
+import { LexicalEditor } from 'lexical';
+import type { Plugin } from './plugin';
+import type { AnnotationData, PluginReference } from './types';
+type GlobalStore = {
+    editor?: LexicalEditor | null;
+    comments?: CommentAnnotation[];
+    filteredComments?: CommentAnnotation[];
+    selectedCommentsMap?: Map<string, boolean>;
+};
+/**
+ * Interface for annotation store entry
+ */
+interface AnnotationStoreEntry {
+    annotation: AnnotationData;
+    pluginReference: PluginReference;
+}
+export declare class StoreService {
+    static storeInstanceMap: Map<string, StoreService>;
+    plugin: Plugin;
+    isSubscribed: boolean;
+    globalStore: GlobalStore;
+    globalAnnotationStore: Map<string, AnnotationStoreEntry>;
+    /**
+     * Helper to get and set annotations with debug messages
+     */
+    annotationStore: {
+        get: (id: string) => AnnotationStoreEntry | undefined;
+        set: (id: string, data: AnnotationStoreEntry) => void;
+        getAll: () => Map<string, AnnotationStoreEntry>;
+        clear: () => void;
+        remove: (id: string) => void;
+        hasAnnotationTextChanged: (annotationId: string, currentAnnotation: AnnotationData) => boolean;
+    };
+    constructor(plugin: Plugin);
+    updateGlobalStore: (store: GlobalStore) => void;
+    highlightCommentsFromGlobalStore: () => void;
+}
+export {};

package/esm/types/types.d.ts

@@ -0,0 +1,40 @@
+export type CommentAnnotationContext = {
+    textEditorConfig?: {
+        text: string;
+        occurrence: number;
+        editorId?: string;
+        targetTextNodeId?: string;
+    };
+} & Record<string, unknown>;
+export interface LexicalVeltCommentConfig {
+    context?: any;
+}
+/**
+ * Interface for annotation data
+ */
+export interface AnnotationData {
+    annotationId?: string;
+    multiThreadAnnotationId?: string;
+    text?: string;
+    context?: AnnotationContext;
+}
+/**
+ * Interface for annotation context
+ */
+export interface AnnotationContext {
+    textEditorConfig?: {
+        text?: string;
+        occurrence?: number;
+        targetTextNodeId?: string;
+    };
+}
+/**
+ * Interface for plugin reference in annotation store
+ */
+export interface PluginReference {
+    node: HTMLElement;
+    position: {
+        from: number;
+        to: number;
+    };
+}

package/esm/types/velt.d.ts

@@ -0,0 +1,21 @@
+import type { Location } from '@veltdev/types';
+import type { CommentAnnotationContext } from './types';
+export declare class VeltService {
+    static selectedCommentsMap: Map<string, boolean>;
+    static subscribers: Map<string, (selectedCommentsMap: Map<string, boolean>) => void>;
+    static isSubscribed: boolean;
+    static getCommentElement: () => import("@veltdev/types").CommentElement | null;
+    static addManualComment: ({ context, location, }: {
+        context: CommentAnnotationContext;
+        location?: Location | undefined;
+    }) => Promise<any>;
+    static updateContext: ({ annotationId, context, }: {
+        annotationId: string;
+        context: CommentAnnotationContext;
+    }) => Promise<any> | undefined;
+    static subscribeToSelectedCommentsMap: (id: string, subscriber: (selectedCommentsMap: Map<string, boolean>) => void) => void;
+    static unsubscribeFromSelectedCommentsMap: (id: string) => void;
+    static catchError: (message: string, otherProperties?: any) => void;
+    static subscribeToSelectedAnnotationsMapSingleton: () => Map<any, any> | undefined;
+    private static updateSelectedCommentsMap;
+}

package/index.d.ts

@@ -0,0 +1,58 @@
+import { CommentAnnotation } from '@veltdev/types';
+import { ElementNode, NodeKey, EditorConfig, LexicalNode, Spread, SerializedElementNode, LexicalEditor } from 'lexical';
+
+interface LexicalVeltCommentConfig {
+    context?: any;
+}
+
+type SerializedCommentNode = Spread<{
+    annotationId?: string;
+    multiThreadAnnotationId?: string;
+    type: 'comment';
+    version: 1;
+}, SerializedElementNode>;
+declare class CommentNode extends ElementNode {
+    __annotationId?: string;
+    __multiThreadAnnotationId?: string;
+    static getType(): string;
+    static clone(node: CommentNode): CommentNode;
+    constructor(annotationId?: string, multiThreadAnnotationId?: string, key?: NodeKey);
+    createDOM(config: EditorConfig): HTMLElement;
+    updateDOM(prevNode: CommentNode, dom: HTMLElement, config: EditorConfig): boolean;
+    static importJSON(serializedNode: SerializedCommentNode): CommentNode;
+    exportJSON(): SerializedCommentNode;
+    isInline(): boolean;
+}
+declare function $createCommentNode(annotationId?: string, multiThreadAnnotationId?: string): CommentNode;
+declare function $isCommentNode(node: LexicalNode | null | undefined): node is CommentNode;
+
+/**
+ * Enhanced export function with multiple strategies
+ */
+declare const exportCleanEditorContent: (editor: LexicalEditor) => string;
+/**
+ * Deserializes editor state from clean JSON
+ */
+declare function deserializeCleanState(editor: LexicalEditor, jsonString: string): void;
+
+declare const triggerAddComment: (editor: LexicalEditor, config?: LexicalVeltCommentConfig) => Promise<void>;
+interface AddCommentRequest {
+    editorId?: string;
+    editor: LexicalEditor;
+    context?: unknown;
+}
+/**
+ * Creates a comment annotation for the currently selected text in the editor
+ * This function handles the entire flow from getting the selected text to creating
+ * the actual comment through the Velt service
+ */
+declare const addComment: ({ editorId, editor, context: clientContext, }: AddCommentRequest) => Promise<void>;
+declare function highlightComments(editor: LexicalEditor, commentAnnotations: CommentAnnotation[], editorId?: string): void;
+interface RenderCommentsRequest {
+    editor: LexicalEditor;
+    editorId?: string;
+    commentAnnotations?: CommentAnnotation[];
+}
+declare const renderComments: ({ editor, editorId, commentAnnotations }: RenderCommentsRequest) => void;
+
+export { $createCommentNode, $isCommentNode, AddCommentRequest, CommentNode, RenderCommentsRequest, addComment, deserializeCleanState, exportCleanEditorContent, highlightComments, renderComments, triggerAddComment };

package/package.json

@@ -0,0 +1,44 @@
+{
+    "name": "@veltdev/lexical-velt-comments",
+    "version": "1.0.0",
+    "description": "Lexical Extension to add Google Docs-style overlay comments to your Lexical editor. Works with the Velt Collaboration SDK.",
+    "homepage": "https://velt.dev",
+    "keywords": [
+        "lexical",
+        "react",
+        "velt",
+        "real-time",
+        "realtime",
+        "toolkit",
+        "multiplayer",
+        "websockets",
+        "collaboration",
+        "collaborative",
+        "presence",
+        "rooms",
+        "documents",
+        "conflict resolution",
+        "crdts",
+        "comment",
+        "comments",
+        "recording",
+        "screen recording",
+        "cursors",
+        "notifications",
+        "cord",
+        "liveblocks"
+    ],
+    "scripts": {
+        "test": "echo \"Error: no test specified\" && exit 1",
+        "version:update": "node ../update-npm-package.mjs",
+        "publish:extension": "npm publish --access public"
+    },
+    "author": "Velt",
+    "license": "Proprietary",
+    "main": "cjs/index.js",
+    "module": "esm/index.js",
+    "types": "index.d.ts",
+    "peerDependencies": {
+        "lexical": "*"
+    }
+}