@veltdev/lexical-velt-comments 4.5.2-beta.2 → 4.5.2-beta.3

package/esm/types/src/features/renderComments.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Render comments feature module.
+ *
+ * Purpose: Public API entry point for rendering comment annotations.
+ * Orchestrates state updates, subscriptions, and delegates to commentRenderer.
+ *
+ * Key responsibilities:
+ * - Update state with new annotations
+ * - Subscribe to selected annotations from Velt
+ * - Delegate rendering logic to commentRenderer
+ *
+ * Dependencies:
+ * - adapters/velt.ts (for Velt SDK subscription)
+ * - adapters/host/doc.ts (for editor setup)
+ * - core/state.ts (for state management)
+ * - core/registry.ts (for editor ID extraction)
+ * - features/commentRenderer.ts (for rendering logic)
+ * - types/velt.ts (for CommentAnnotation)
+ *
+ * IMPORTANT: This module MUST NOT import editor or Velt types directly.
+ * All SDK access goes through adapters.
+ */
+import type { RenderCommentsRequest } from '@/types/common';
+/**
+ * Renders comment annotations as marks in the editor.
+ *
+ * This function renders comment annotations as visual marks in the editor.
+ * It filters annotations for the specific editor and applies marks accordingly.
+ *
+ * @param request - Object containing editor, editorId (optional), and commentAnnotations (optional)
+ *
+ * @example
+ * ```typescript
+ * // Simple usage
+ * renderComments({ editor });
+ *
+ * // With editor ID
+ * renderComments({ editorId: 'my-editor', editor });
+ *
+ * // With annotations
+ * renderComments({
+ *   editorId: 'my-editor',
+ *   editor,
+ *   commentAnnotations: [
+ *     {
+ *       annotationId: 'ann-123',
+ *       context: {
+ *         textEditorConfig: {
+ *           text: 'Hello world',
+ *           occurrence: 1,
+ *           editorId: 'my-editor'
+ *         }
+ *       }
+ *     }
+ *   ]
+ * });
+ * ```
+ *
+ * @remarks
+ * - Only annotations with matching editorId are rendered
+ * - Automatically subscribes to selected annotations changes
+ * - Filters out terminal/resolved comments unless they're selected
+ * - Removes marks when comments become resolved
+ * - Re-applies marks when resolved comments are selected
+ */
+export declare const renderComments: ({ editor, editorId, commentAnnotations, }: RenderCommentsRequest) => void;
+/**
+ * Cleans up subscriptions and renderer state for an editor.
+ * Should be called when editor is destroyed.
+ *
+ * @param editorId Unique identifier for the editor
+ */
+export declare const cleanupRenderComments: (editorId: string) => void;

package/esm/types/src/features/updateContent.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Update content feature module.
+ *
+ * Purpose: Handle document changes and annotation context updates.
+ * Orchestrates adapters and core to detect and process annotation changes.
+ *
+ * Key responsibilities:
+ * - Detect document changes during transactions
+ * - Compare current state with original annotations
+ * - Detect content, occurrence, and container changes
+ * - Update Velt contexts for changed annotations
+ * - Update marks in editor if needed
+ *
+ * Dependencies:
+ * - adapters/host/doc.ts (for change detection)
+ * - adapters/velt.ts (for context updates)
+ * - adapters/host/marks.ts (for mark updates)
+ * - core/state.ts (for state access)
+ * - types/host.ts (for AnnotationChange)
+ *
+ * IMPORTANT: This module MUST NOT import Lexical or Velt types directly.
+ * All SDK access goes through adapters.
+ */
+/**
+ * Handles content updates when document changes occur.
+ * Detects annotation changes and updates Velt contexts accordingly.
+ *
+ * @param editorId Unique identifier for the editor
+ * @param editor The editor instance
+ * @param transaction The transaction object
+ */
+export declare const handleContentUpdate: (editorId: string, editor: unknown, transaction: unknown) => void;

package/esm/types/src/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Public API for Lexical-Velt Comments extension.
+ *
+ * This module exports the public API surface for the v2 implementation.
+ *
+ * @example
+ * ```typescript
+ * import { addComment, renderComments, CommentNode } from 'lexical-velt-comments';
+ *
+ * // Create editor with CommentNode registered
+ * const editor = createEditor({
+ *   nodes: [CommentNode, ...otherNodes]
+ * });
+ *
+ * // Add a comment (auto-registers editor)
+ * await addComment({ editor, context: { customData: 'value' } });
+ *
+ * // Render existing comments (auto-registers editor)
+ * renderComments({ editor, commentAnnotations: annotations });
+ * ```
+ */
+export { addComment } from '@/features/addComment';
+export { renderComments } from '@/features/renderComments';
+export type { AddCommentRequest, CommentAnnotationContext, LexicalVeltCommentConfig, RenderCommentsRequest } from '@/types/common';
+export { CommentNode } from '@/adapters/host/marks';
+export { exportJSONWithoutComments } from '@/utils/serializer';

package/esm/types/src/types/common.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Common type definitions shared across the entire codebase.
+ * These types are SDK-agnostic and represent domain concepts.
+ */
+import type { CommentAnnotation } from '@/types/velt';
+/**
+ * Context object for comment annotations.
+ * Contains text editor configuration and any additional context data.
+ */
+export interface CommentAnnotationContext {
+    textEditorConfig?: {
+        text: string;
+        occurrence: number;
+        editorId?: string;
+        targetTextNodeId?: string;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Configuration options for Lexical Velt Comments extension.
+ * Matches Tiptap's TiptapVeltCommentConfig structure.
+ */
+export interface LexicalVeltCommentConfig {
+    editorId?: string;
+    context?: CommentAnnotationContext;
+}
+/**
+ * Extension configuration options for LexicalVeltComments.
+ * Matches Tiptap's TiptapVeltCommentsOptions structure.
+ * Note: Lexical doesn't use HTMLAttributes or persistVeltMarks, but we keep the structure for consistency.
+ */
+export interface LexicalVeltCommentsOptions {
+    HTMLAttributes?: Record<string, unknown>;
+    persistVeltMarks?: boolean;
+    editorId?: string;
+    context?: CommentAnnotationContext;
+}
+/**
+ * Extension configuration for registry.
+ */
+export interface ExtensionConfig {
+    persistVeltMarks?: boolean;
+    editorId?: string;
+    HTMLAttributes?: Record<string, unknown>;
+}
+/**
+ * Request interface for addComment function.
+ * Matches legacy AddCommentRequest interface.
+ */
+export interface AddCommentRequest {
+    editorId?: string;
+    editor: unknown;
+    context?: CommentAnnotationContext;
+}
+/**
+ * Request interface for renderComments function.
+ * Matches legacy RenderCommentsRequest interface.
+ */
+export interface RenderCommentsRequest {
+    editor: unknown;
+    editorId?: string;
+    commentAnnotations?: CommentAnnotation[];
+}
+/**
+ * Editor context containing editor instance and related state.
+ * Note: Editor type is generic to avoid importing Lexical/Tiptap types here.
+ */
+export interface EditorContext<TEditor = unknown> {
+    editorId: string;
+    editor: TEditor;
+    config: ExtensionConfig;
+}

package/esm/types/src/types/host.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Lexical editor-specific type definitions
+ *
+ * This is the ONLY place where Lexical types may be imported.
+ * All other modules must use adapter interfaces instead of concrete Lexical types.
+ */
+import type { AnnotationData } from '@/types/state';
+/**
+ * Selection context extracted from editor
+ * Contains all information needed about the current selection
+ */
+export interface SelectionContext {
+    text: string;
+    from: number;
+    to: number;
+    occurrence: number;
+    targetTextNodeId?: string;
+    locationId?: string;
+}
+/**
+ * Occurrence match found in document
+ * Represents one occurrence of a text pattern
+ */
+export interface OccurrenceMatch {
+    start: number;
+    end: number;
+    occurrence: number;
+}
+/**
+ * Document change event
+ * Represents a change to the document content
+ */
+export interface DocumentChangeEvent {
+    type: 'insert' | 'delete' | 'replace';
+    from: number;
+    to: number;
+    insertedText?: string;
+    deletedText?: string;
+}
+/**
+ * Represents a detected change to an annotation during document editing.
+ * Matches Tiptap's AnnotationChange interface.
+ */
+export interface AnnotationChange {
+    annotationId: string;
+    multiThreadAnnotationId?: string;
+    originalText: string;
+    currentText: string;
+    originalOccurrence: number;
+    currentOccurrence: number;
+    originalTargetTextNodeId: string;
+    newTargetTextNodeId: string;
+    annotation: AnnotationData;
+    contentChanged: boolean;
+    occurrenceChanged: boolean;
+    targetTextNodeIdChanged: boolean;
+}
+/**
+ * Text match interface for search results.
+ * Represents a range of text found in the document.
+ */
+export interface TextMatch {
+    start: number;
+    end: number;
+}

package/esm/types/src/types/state.d.ts

@@ -0,0 +1,28 @@
+/**
+ * State management type definitions.
+ * These types represent the internal state structure for managing annotations.
+ */
+import type { CommentAnnotationContext } from '@/types/common';
+import type { CommentAnnotation } from '@/types/velt';
+/**
+ * Represents a single annotation with its associated data and position.
+ */
+export interface AnnotationData {
+    annotationId: string;
+    multiThreadAnnotationId?: string;
+    context: CommentAnnotationContext;
+    position?: {
+        from: number;
+        to: number;
+    };
+}
+/**
+ * Complete annotation state for a single editor instance.
+ * Maintains annotations map, comment annotations array (with status), and selected annotations set.
+ */
+export interface AnnotationState {
+    annotations: Map<string, AnnotationData>;
+    commentAnnotations: CommentAnnotation[];
+    selectedAnnotations: Set<string>;
+    editorId: string;
+}

package/esm/types/src/types/velt.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Velt SDK type definitions.
+ * Re-exports Velt types for convenience.
+ * NOTE: This is the ONLY place where @veltdev/types should be imported.
+ */
+export type { CommentAnnotation, Location, Velt, CommentElement, } from '@veltdev/types';

package/esm/types/src/utils/common.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Pure utility functions with zero side effects
+ *
+ * This module contains pure, testable utility functions extracted from src/utility.ts.
+ * These functions have NO dependencies on Lexical, Velt, or any external SDKs.
+ */
+/**
+ * KMP Search implementation for finding text patterns
+ *
+ * Pure function for efficient string pattern matching using the Knuth-Morris-Pratt algorithm.
+ * Migrated from src/utility.ts UtilityService.kmpSearch()
+ *
+ * @param text - The text to search in
+ * @param pattern - The pattern to search for
+ * @param startPos - Starting position offset (default: 0)
+ * @param maxOccurrences - Maximum number of occurrences to find (optional)
+ * @returns Array of positions where pattern was found
+ */
+export declare const kmpSearch: (text: string, pattern: string, startPos?: number, maxOccurrences?: number) => number[];
+/**
+ * Compute KMP failure function table
+ *
+ * Pure function that computes the longest proper prefix which is also a suffix (LPS) table
+ * for the Knuth-Morris-Pratt algorithm.
+ * Migrated from src/utility.ts UtilityService.computeKMPTable()
+ *
+ * @param pattern - The pattern to compute table for
+ * @returns Array representing the failure function (LPS table)
+ */
+export declare const computeKMPTable: (pattern: string) => number[];
+/**
+ * Find text occurrences in a string
+ *
+ * Convenience function that uses KMP search to find all occurrences.
+ *
+ * @param text - Text to search in
+ * @param searchText - Text to search for
+ * @returns Array of occurrence matches with start/end positions
+ */
+export declare const findTextOccurrences: (text: string, searchText: string) => Array<{
+    start: number;
+    end: number;
+}>;
+/**
+ * Calculate occurrence index for a given position
+ *
+ * Determines which occurrence (1-indexed) a given position corresponds to.
+ *
+ * @param matches - Array of match positions with start/end
+ * @param position - Position to find occurrence for
+ * @returns 1-indexed occurrence number, or null if not found
+ */
+export declare const calculateOccurrenceIndex: (matches: Array<{
+    start: number;
+    end: number;
+}>, position: number) => number | null;

package/esm/types/src/utils/console.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Console utility class providing controlled logging with debug mode support.
+ *
+ * Logging methods (log, warn, error, debug, info) are only active when debug mode
+ * is enabled via sessionStorage. The `catch` method always outputs as warnings
+ * for error handling visibility.
+ */
+export declare class Console {
+    /** Log a message (only when debug mode is enabled via sessionStorage) */
+    static log: (...data: any[]) => void;
+    /** Log a warning (only when debug mode is enabled via sessionStorage) */
+    static warn: (...data: any[]) => void;
+    /** Log an error (only when debug mode is enabled via sessionStorage) */
+    static error: (...data: any[]) => void;
+    /** Log debug info (only when debug mode is enabled via sessionStorage) */
+    static debug: (...data: any[]) => void;
+    /** Log info (only when debug mode is enabled via sessionStorage) */
+    static info: (...data: any[]) => void;
+    /** Flag indicating if logging is enabled (used by catch method) */
+    static logsEnabled: boolean;
+    /**
+     * Log caught errors from try/catch blocks.
+     * Always outputs as console.warn with the LOG_PREFIX for visibility.
+     * Use this instead of console.error in catch blocks.
+     *
+     * @param message - Descriptive message about what operation failed
+     * @param error - Optional error object caught in the try/catch
+     */
+    static catch: (message: string, error?: unknown) => void;
+    /**
+     * Check if debug logging should be shown.
+     * Checks sessionStorage for debugMode or forceDebugMode flags.
+     *
+     * @returns true if debug mode is enabled, false otherwise
+     */
+    static showLogs(): boolean;
+}

package/esm/types/src/utils/host.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Host editor-specific utility functions
+ *
+ * This module contains host editor-specific utility functions that are shared
+ * across multiple adapters. These functions depend on host editor types (Lexical).
+ *
+ * For pure utilities without host editor dependencies, see utils/common.ts
+ */
+import { type LexicalEditor, type LexicalNode, type TextNode } from 'lexical';
+/**
+ * Collect all text content including paragraph breaks.
+ * Migrated from src/utility.ts UtilityService.collectTextContent()
+ *
+ * @param root - Root Lexical node to traverse
+ * @returns Object with combined text and node map
+ */
+export declare const collectTextContent: (root: LexicalNode) => {
+    combinedText: string;
+    nodeMap: Array<{
+        node: TextNode | null;
+        start: number;
+        end: number;
+        isParagraphBreak?: boolean;
+    }>;
+};
+/**
+ * Get text content for a specific container.
+ * Migrated from src/utility.ts UtilityService.getContainerTextContent()
+ *
+ * @param containerElement - DOM element representing the container
+ * @param editor - Lexical editor instance
+ * @param nodeMap - Node map from collectTextContent
+ * @param combinedText - Combined text from collectTextContent
+ * @returns Container text content with start offset, or null if not found
+ */
+export declare const getContainerTextContent: (containerElement: HTMLElement, editor: LexicalEditor, nodeMap: Array<{
+    node: TextNode | null;
+    start: number;
+    end: number;
+    isParagraphBreak?: boolean;
+}>, combinedText: string) => {
+    text: string;
+    startOffset: number;
+} | null;

package/esm/types/src/utils/serializer.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Serializer utilities for Lexical editor state
+ *
+ * This module provides utilities for serializing Lexical editor state,
+ * particularly for removing comment nodes from serialized JSON.
+ *
+ * Migrated from src/serializer.ts
+ */
+import type { LexicalEditor, SerializedEditorState, SerializedLexicalNode } from 'lexical';
+/**
+ * Export JSON without comment nodes.
+ *
+ * This function serializes the editor state and removes all comment nodes,
+ * unwrapping their children and normalizing adjacent text nodes.
+ *
+ * @param editor - Lexical editor instance
+ * @returns Serialized editor state without comment nodes
+ */
+export declare const exportJSONWithoutComments: (editor: LexicalEditor) => SerializedEditorState<SerializedLexicalNode>;