@veltdev/plate-comments-react 1.0.0

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

@@ -0,0 +1,80 @@
+/**
+ * Pure utility functions with zero side effects.
+ * These functions contain algorithmic logic extracted from legacy code.
+ *
+ * IMPORTANT: This module MUST NOT import any external SDKs or have side effects.
+ * All functions must be pure: input → output, deterministic, no mutations.
+ */
+/**
+ * Computes the KMP (Knuth-Morris-Pratt) failure function (LPS array).
+ * This is used for efficient pattern matching in text search.
+ *
+ * @param pattern The pattern string to compute the failure function for
+ * @returns Longest proper prefix array (LPS array)
+ *
+ * @example
+ * ```typescript
+ * const lps = computeKMPTable("abcabc");
+ * // Returns: [0, 0, 0, 1, 2, 3]
+ * ```
+ */
+export declare const computeKMPTable: (pattern: string) => number[];
+/**
+ * Finds all occurrences of a pattern in text using the KMP algorithm.
+ *
+ * @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 start positions (0-based indices in the text)
+ *
+ * @example
+ * ```typescript
+ * const positions = kmpSearch("abcabcabc", "abc", 0, 2);
+ * // Returns: [0, 3] (first 2 occurrences)
+ * ```
+ */
+export declare const kmpSearch: (text: string, pattern: string, startPos?: number, maxOccurrences?: number) => number[];
+/**
+ * Maps text positions in a combined string back to document positions.
+ * Used when searching across multiple text nodes that have been concatenated.
+ *
+ * @param textNodes Array of text nodes with their document positions
+ * @param textPositions Positions in the combined text (from kmpSearch)
+ * @param patternLength Length of the pattern being searched for
+ * @returns Array of { from, to } ranges in document coordinates
+ *
+ * @example
+ * ```typescript
+ * const textNodes = [
+ *   { text: "Hello ", pos: 0 },
+ *   { text: "World", pos: 6 }
+ * ];
+ * const positions = [0]; // Found at start of combined text
+ * const ranges = mapTextPositionsToDocument(textNodes, positions, 5);
+ * // Returns: [{ from: 0, to: 5 }]
+ * ```
+ */
+export declare const mapTextPositionsToDocument: (textNodes: Array<{
+    text: string;
+    pos: number;
+}>, textPositions: number[], patternLength: number) => Array<{
+    from: number;
+    to: number;
+}>;
+/**
+ * Compares two maps for equality.
+ * Checks if both maps have the same size and identical key-value pairs.
+ *
+ * @param map1 First map to compare
+ * @param map2 Second map to compare
+ * @returns True if maps are equal, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const map1 = new Map([['a', true], ['b', false]]);
+ * const map2 = new Map([['a', true], ['b', false]]);
+ * areMapsEqual(map1, map2); // Returns: true
+ * ```
+ */
+export declare const areMapsEqual: <K, V>(map1: Map<K, V>, map2: Map<K, V>) => boolean;

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

@@ -0,0 +1,10 @@
+export declare class Console {
+    static log: (...data: any[]) => void;
+    static warn: (...data: any[]) => void;
+    static error: (...data: any[]) => void;
+    static debug: (...data: any[]) => void;
+    static info: (...data: any[]) => void;
+    static logsEnabled: boolean;
+    static catch: (message: string, error?: unknown) => void;
+    static showLogs(): boolean;
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Serializer utilities for Plate editor content
+ *
+ * This module provides utilities for serializing Plate editor content,
+ * particularly for removing comment nodes from serialized JSON.
+ *
+ * Use this when persisting editor content to remove Velt comment elements
+ * while preserving the original text content.
+ */
+import type { Descendant } from 'slate';
+/**
+ * Export JSON without comment nodes.
+ *
+ * This function takes Plate editor content and removes all comment nodes,
+ * unwrapping their children and merging adjacent text nodes with same formatting.
+ *
+ * @param content - Plate editor content (Descendant[])
+ * @returns Serialized content without comment nodes
+ */
+export declare const exportJSONWithoutComments: (content: Descendant[]) => Descendant[];

package/index.d.ts

@@ -0,0 +1,291 @@
+import { CommentAnnotation } from '@veltdev/types';
+import { Descendant } from 'slate';
+import React from 'react';
+import { RenderElementProps } from 'slate-react';
+import { PlateEditor } from '@platejs/core/react';
+
+/**
+ * Common type definitions shared across the entire codebase.
+ * These types are SDK-agnostic and represent domain concepts.
+ */
+
+/**
+ * Context object for comment annotations.
+ * Contains text editor configuration and any additional context data.
+ */
+interface CommentAnnotationContext {
+    textEditorConfig?: {
+        text: string;
+        occurrence: number;
+        editorId?: string;
+        targetTextNodeId?: string;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Request interface for addComment function.
+ * Matches legacy AddCommentRequest interface.
+ */
+interface AddCommentRequest {
+    editorId?: string;
+    editor: unknown;
+    context?: unknown;
+}
+/**
+ * Request interface for renderComments function.
+ * Matches legacy RenderCommentsRequest interface.
+ */
+interface RenderCommentsRequest {
+    editor: unknown;
+    editorId?: string;
+    commentAnnotations?: CommentAnnotation[];
+}
+
+/**
+ * Editor-specific type definitions for Plate.js.
+ * This is the ONLY place where editor-specific types may be defined.
+ */
+
+/**
+ * Extended PlateEditor interface with Velt comments functionality.
+ */
+interface VeltCommentsEditor extends PlateEditor {
+}
+/**
+ * Velt comment element type for the editor.
+ * This represents a comment annotation node/element in the editor's document model.
+ */
+type VeltCommentsElement = {
+    type: 'veltComment';
+    children: Descendant[];
+    annotationId?: string;
+    multiThreadAnnotationId?: string;
+};
+/**
+ * Plugin configuration options for VeltCommentsPlugin.
+ */
+interface VeltCommentsPluginConfig {
+    editorId?: string;
+    persistVeltMarks?: boolean;
+    HistoryEditor?: unknown;
+}
+
+/**
+ * Core extension module for Plate.js.
+ * This module creates the Plate plugin that wires everything together.
+ *
+ * Responsibilities:
+ * - Create plugin using Plate's createPlatePlugin
+ * - Wire features into editor lifecycle hooks
+ * - Register editor in registry
+ * - Handle cleanup on editor destruction
+ *
+ * Architectural Rules:
+ * - This module MAY import Plate types (it's the extension entry point)
+ * - It delegates to features and adapters for actual work
+ *
+ * KEY DIFFERENCE FROM SLATE:
+ * - Slate uses HOC pattern: withVeltComments(editor)
+ * - Plate uses plugin pattern: createPlatePlugin({ key, node, handlers })
+ */
+
+/**
+ * VeltCommentsPlugin - Plate.js plugin for Velt Comments integration.
+ *
+ * This is the main entry point that enhances the editor with comment functionality.
+ * It creates an inline element type for comment highlighting and sets up
+ * change detection for updating comment positions.
+ *
+ * @example
+ * ```typescript
+ * import { usePlateEditor } from '@platejs/core/react';
+ * import { VeltCommentsPlugin } from '@veltdev/plate-comments-react';
+ *
+ * const editor = usePlateEditor({
+ *   plugins: [VeltCommentsPlugin],
+ * });
+ *
+ * // With configuration
+ * const editor = usePlateEditor({
+ *   plugins: [
+ *     VeltCommentsPlugin.configure({
+ *       options: { editorId: 'my-editor' }
+ *     })
+ *   ],
+ * });
+ * ```
+ */
+declare const VeltCommentsPlugin: any;
+
+/**
+ * Add comment feature module.
+ *
+ * Purpose: End-to-end add comment orchestration.
+ * Orchestrates adapters and core to implement the add comment flow.
+ *
+ * Key responsibilities:
+ * - Get Velt comment element
+ * - Extract selection context from editor
+ * - Create comment via Velt SDK
+ * - Apply mark to editor document
+ * - Update state with annotation data
+ *
+ * Dependencies:
+ * - adapters/velt.ts (for Velt SDK calls)
+ * - adapters/host/doc.ts (for selection extraction, editor setup, and selection reset)
+ * - adapters/host/marks.ts (for mark application)
+ * - adapters/host/storage.ts (for mark application configuration)
+ * - core/state.ts (for state updates)
+ * - types/common.ts (for CommentAnnotationContext)
+ *
+ * IMPORTANT: This module MUST NOT import editor or Velt types directly.
+ * All SDK access goes through adapters.
+ */
+
+/**
+ * Adds a comment to the currently selected text in the editor.
+ *
+ * This is the main entry point for adding comments. It handles:
+ * - Extracting selection context from the editor
+ * - Creating the comment via Velt SDK
+ * - Applying marks to the editor if configured
+ * - Updating state with annotation data
+ *
+ * @param request - Object containing editorId (optional), editor, and context (optional)
+ * @returns Promise that resolves when the comment is added (or fails silently)
+ *
+ * @example
+ * ```typescript
+ * // Simple usage
+ * await addComment({ editor });
+ *
+ * // With editor ID
+ * await addComment({ editorId: 'my-editor', editor });
+ *
+ * // With custom context
+ * await addComment({
+ *   editorId: 'my-editor',
+ *   editor,
+ *   context: {
+ *     userId: 'user123',
+ *     metadata: { source: 'web-app' }
+ *   }
+ * });
+ * ```
+ *
+ * @remarks
+ * - Requires text to be selected in the editor
+ * - Requires Velt SDK to be available (window.Velt)
+ * - Marks are only applied if persistVeltMarks is FALSE in plugin config (matching legacy behavior)
+ * - Fails silently if Velt SDK is unavailable or selection is invalid
+ */
+declare function addComment({ editorId, editor, context: clientContext, }: AddCommentRequest): Promise<void>;
+
+/**
+ * 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.
+ */
+
+/**
+ * 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
+ */
+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
+ */
+declare const cleanupRenderComments: (editorId: string) => void;
+
+/**
+ * Serializer utilities for Plate editor content
+ *
+ * This module provides utilities for serializing Plate editor content,
+ * particularly for removing comment nodes from serialized JSON.
+ *
+ * Use this when persisting editor content to remove Velt comment elements
+ * while preserving the original text content.
+ */
+
+/**
+ * Export JSON without comment nodes.
+ *
+ * This function takes Plate editor content and removes all comment nodes,
+ * unwrapping their children and merging adjacent text nodes with same formatting.
+ *
+ * @param content - Plate editor content (Descendant[])
+ * @returns Serialized content without comment nodes
+ */
+declare const exportJSONWithoutComments: (content: Descendant[]) => Descendant[];
+
+/**
+ * React component for rendering Velt comment elements in Plate editor.
+ * This component renders the <velt-comment-text> custom element.
+ *
+ * Note: velt-comment-text is an inline element, so it should only contain text nodes
+ * or other inline elements, never block elements like <p>.
+ */
+
+declare const PlateVeltComment: (props: Omit<RenderElementProps, "element"> & {
+    element: VeltCommentsElement;
+}) => React.ReactElement;
+
+export { AddCommentRequest, CommentAnnotationContext, PlateVeltComment, RenderCommentsRequest, VeltCommentsEditor, VeltCommentsElement, VeltCommentsPlugin, VeltCommentsPluginConfig, addComment, cleanupRenderComments, exportJSONWithoutComments, renderComments };

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@veltdev/plate-comments-react",
+  "version": "1.0.0",
+  "description": "Velt Comments integration for Plate.js editor",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "version:update": "node ../update-npm-package.mjs",
+    "publish:extension": "npm publish --access public"
+  },
+  "main": "cjs/index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./esm/index.js",
+      "require": "./cjs/index.js",
+      "types": "./index.d.ts"
+    }
+  },
+  "peerDependencies": {
+    "react": "^19.0.0 || ^18.0.0 || ^17.0.0 || ^16.0.0",
+    "react-dom": "^19.0.0 || ^18.0.0 || ^17.0.0 || ^16.0.0",
+    "@platejs/core": "^49.0.0",
+    "slate": "^0.112.0",
+    "slate-react": "^0.112.1"
+  },
+  "license": "Proprietary"
+}