@veltdev/plate-comments-react 1.0.0

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

@@ -0,0 +1,62 @@
+/**
+ * Shared constants for Plate-Velt Comments integration
+ *
+ * This module contains all magic strings and configuration constants
+ * used across the application.
+ */
+export declare const Constants: {
+    /**
+     * DOM attribute names used for editor identification and location tracking.
+     */
+    readonly ATTRIBUTES: {
+        readonly EDITOR_ID: "data-editor-id";
+        readonly LOCATION_ID: "data-velt-location-id";
+        readonly ANNOTATION_ID: "annotation-id";
+        readonly MULTI_THREAD_ANNOTATION_ID: "multi-thread-annotation-id";
+    };
+    /**
+     * Element types used in the editor's document model.
+     */
+    readonly ELEMENT_TYPE: {
+        readonly VELT_COMMENT: "veltComment";
+    };
+    /**
+     * Mark/extension name constant.
+     * Generic constant name, value is Plate-specific for this package.
+     */
+    readonly MARK_NAME: "veltComment";
+    /**
+     * Plugin key for Plate.js plugin system.
+     */
+    readonly PLUGIN_KEY: "veltComments";
+    /**
+     * Storage key constant.
+     * Generic constant name, value is Plate-specific for this package.
+     */
+    readonly STORAGE_KEY: "plateVeltComments";
+    /**
+     * Default extension name for error messages.
+     */
+    readonly DEFAULT_EXTENSION_NAME: "VeltComments";
+    /**
+     * Default editor ID used when no editor ID is provided.
+     * Uses '__default__' to avoid collision with user-provided values.
+     */
+    readonly DEFAULT_EDITOR_ID: "__default__";
+    /**
+     * Terminal status type for resolved/closed comments.
+     */
+    readonly STATUS_TERMINAL: "terminal";
+    /**
+     * Log prefix for console messages.
+     */
+    readonly LOG_PREFIX: "PlateVeltComments: ";
+    /**
+     * Session storage key for debug mode.
+     */
+    readonly DEBUG_MODE_KEY: "debugMode";
+    /**
+     * Session storage key for forced debug mode.
+     */
+    readonly FORCE_DEBUG_MODE_KEY: "forceDebugMode";
+};

package/esm/types/core/ExtensionComponent.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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>.
+ */
+import React from 'react';
+import type { RenderElementProps } from 'slate-react';
+import type { VeltCommentsElement } from '@/types/host';
+export declare const PlateVeltComment: (props: Omit<RenderElementProps, "element"> & {
+    element: VeltCommentsElement;
+}) => React.ReactElement;

package/esm/types/core/extension.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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 })
+ */
+import type { VeltCommentsPluginConfig } from '@/types/host';
+/**
+ * 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' }
+ *     })
+ *   ],
+ * });
+ * ```
+ */
+export declare const VeltCommentsPlugin: any;
+/**
+ * Export plugin configuration type for external use.
+ */
+export type { VeltCommentsPluginConfig };

package/esm/types/core/registry.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Core registry module.
+ *
+ * Purpose: Maintains a registry mapping editorId → editor context.
+ * Replaces the singleton pattern from legacy Plugin class with a proper registry.
+ *
+ * Key responsibilities:
+ * - Register editor instances with their configuration
+ * - Retrieve editor contexts by ID
+ * - Unregister editors when they're destroyed
+ * - Extract editor IDs from editor instances
+ *
+ * Dependencies: types/common.ts, core/state.ts, adapters/host/doc.ts
+ */
+import type { EditorContext, ExtensionConfig } from '@/types/common';
+/**
+ * Registers an editor instance in the registry.
+ * Creates initial state for the editor.
+ *
+ * @param editorId Unique identifier for the editor
+ * @param editor The editor instance
+ * @param config Extension configuration options
+ * @returns EditorContext for the registered editor
+ */
+export declare const registerEditor: <TEditor = unknown>(editorId: string, editor: TEditor, config?: ExtensionConfig) => EditorContext<TEditor>;
+/**
+ * Retrieves the editor context for a given editor ID.
+ *
+ * @param editorId Unique identifier for the editor
+ * @returns EditorContext or null if not found
+ */
+export declare const getEditorContext: <TEditor = unknown>(editorId: string) => EditorContext<TEditor> | null;
+/**
+ * Unregisters an editor from the registry and cleans up its state.
+ *
+ * @param editorId Unique identifier for the editor
+ */
+export declare const unregisterEditor: (editorId: string) => void;
+/**
+ * Extracts the editor ID from an editor instance.
+ * Checks editor storage first, then DOM attributes.
+ *
+ * @param editor The editor instance
+ * @returns Editor ID or null if not found
+ */
+export declare const getEditorIdFromEditor: (editor: unknown) => string | null;
+/**
+ * Gets all registered editor IDs.
+ *
+ * @returns Array of editor IDs
+ */
+export declare const getAllEditorIds: () => string[];

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

@@ -0,0 +1,80 @@
+/**
+ * Core state management module.
+ *
+ * Purpose: Single source of truth for annotation state per editor.
+ * This module manages annotation data and selected annotations for each editor instance.
+ *
+ * Key responsibilities:
+ * - Create and manage per-editor annotation state
+ * - CRUD operations for annotations
+ * - Track selected annotations
+ * - Ensure state isolation between editor instances
+ *
+ * Dependencies: types/state.ts, types/common.ts
+ */
+import type { AnnotationData, AnnotationState } from '@/types/state';
+import type { CommentAnnotation } from '@/types/velt';
+/**
+ * Creates a new annotation state for an editor instance.
+ *
+ * @param editorId Unique identifier for the editor
+ * @returns New AnnotationState instance
+ */
+export declare const createAnnotationState: (editorId: string) => AnnotationState;
+/**
+ * Updates annotations in state from Velt SDK data.
+ * Converts CommentAnnotation[] to AnnotationData[] and stores them.
+ *
+ * @param editorId Unique identifier for the editor
+ * @param annotations Array of CommentAnnotation from Velt SDK
+ */
+export declare const updateAnnotations: (editorId: string, annotations: CommentAnnotation[]) => void;
+/**
+ * Retrieves a single annotation by ID.
+ *
+ * @param editorId Unique identifier for the editor
+ * @param annotationId The annotation ID to retrieve
+ * @returns AnnotationData or null if not found
+ */
+export declare const getAnnotation: (editorId: string, annotationId: string) => AnnotationData | null;
+/**
+ * Removes an annotation from state.
+ *
+ * @param editorId Unique identifier for the editor
+ * @param annotationId The annotation ID to remove
+ */
+export declare const removeAnnotation: (editorId: string, annotationId: string) => void;
+/**
+ * Gets the set of selected annotation IDs for an editor.
+ *
+ * @param editorId Unique identifier for the editor
+ * @returns Set of selected annotation IDs
+ */
+export declare const getSelectedAnnotations: (editorId: string) => Set<string>;
+/**
+ * Updates the set of selected annotation IDs for an editor.
+ *
+ * @param editorId Unique identifier for the editor
+ * @param selectedIds Set of selected annotation IDs
+ */
+export declare const setSelectedAnnotations: (editorId: string, selectedIds: Set<string>) => void;
+/**
+ * Gets all annotations for an editor.
+ *
+ * @param editorId Unique identifier for the editor
+ * @returns Map of annotation ID to AnnotationData
+ */
+export declare const getAllAnnotations: (editorId: string) => Map<string, AnnotationData>;
+/**
+ * Gets all comment annotations for an editor (with status field).
+ *
+ * @param editorId Unique identifier for the editor
+ * @returns Array of CommentAnnotation with status field
+ */
+export declare const getCommentAnnotations: (editorId: string) => CommentAnnotation[];
+/**
+ * Clears all state for an editor (used during cleanup).
+ *
+ * @param editorId Unique identifier for the editor
+ */
+export declare const clearState: (editorId: string) => void;

package/esm/types/features/addComment.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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.
+ */
+import type { AddCommentRequest } from '@/types/common';
+/**
+ * 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
+ */
+export declare function addComment({ editorId, editor, context: clientContext, }: AddCommentRequest): Promise<void>;

package/esm/types/features/commentRenderer.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Comment renderer module.
+ *
+ * Purpose: Handle filtering, comparison, and mark updates for comment annotations.
+ * This module manages the rendering state and applies marks based on resolved/selected status.
+ *
+ * Key responsibilities:
+ * - Filter annotations based on status (terminal/resolved) and selected state
+ * - Compare previous vs current filtered annotations to detect removals
+ * - Remove marks for annotations that should no longer be shown
+ * - Re-apply marks for all filtered annotations
+ *
+ * Dependencies:
+ * - core/state.ts (for reading annotations and selected state)
+ * - adapters/host/doc.ts (for finding text occurrences)
+ * - adapters/host/marks.ts (for applying/removing marks)
+ * - types/velt.ts (for CommentAnnotation)
+ *
+ * IMPORTANT: This module MUST NOT import editor or Velt types directly.
+ * All SDK access goes through adapters.
+ */
+import type { CommentAnnotation } from '@/types/velt';
+/**
+ * Updates comments for an editor by filtering, comparing, removing, and re-applying marks.
+ * This is the core rendering logic that handles resolved comment filtering.
+ *
+ * @param editorId Unique identifier for the editor
+ * @param editor The editor instance
+ * @param annotations All CommentAnnotation from Velt SDK (with status)
+ */
+export declare const updateComments: (editorId: string, editor: unknown, annotations: CommentAnnotation[]) => void;
+/**
+ * Updates comments when selected annotations change.
+ * Re-reads annotations from state and triggers re-rendering.
+ *
+ * @param editorId Unique identifier for the editor
+ * @param selectedIds Set of selected annotation IDs (already updated in state)
+ */
+export declare const updateSelection: (editorId: string, selectedIds: Set<string>) => void;
+/**
+ * Cleans up renderer store for an editor.
+ * Should be called when editor is destroyed.
+ *
+ * @param editorId Unique identifier for the editor
+ */
+export declare const cleanupRenderer: (editorId: string) => void;

package/esm/types/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/features/updateContent.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Update content feature module.
+ *
+ * Handles document content changes and updates annotation positions.
+ * Called when text changes are detected in the editor.
+ *
+ * Dependencies:
+ * - adapters/host/doc.ts (document operations)
+ * - adapters/velt.ts (Velt SDK operations)
+ * - core/state.ts (state management)
+ */
+/**
+ * Handles content updates in the editor.
+ * Detects changes to annotations and updates their positions/contexts.
+ *
+ * @param editorId The editor ID
+ * @param editor The editor instance
+ * @param transaction The transaction/operation that triggered the update
+ */
+export declare const handleContentUpdate: (editorId: string, editor: unknown, transaction: unknown) => void;

package/esm/types/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Public API for Plate-Velt Comments integration.
+ *
+ * This module exports the public API for the Plate.js Velt Comments extension.
+ * All internal imports use path aliases (@/) for clean dependency management.
+ *
+ * @module PlateVeltComments
+ */
+export { VeltCommentsPlugin } from '@/core/extension';
+export type { VeltCommentsPluginConfig } from '@/core/extension';
+export { addComment } from '@/features/addComment';
+export { renderComments, cleanupRenderComments } from '@/features/renderComments';
+export { exportJSONWithoutComments } from '@/utils/serializer';
+export { PlateVeltComment } from '@/core/ExtensionComponent';
+export type { AddCommentRequest, CommentAnnotationContext, RenderCommentsRequest } from '@/types/common';
+export type { VeltCommentsEditor, VeltCommentsElement } from '@/types/host';

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

@@ -0,0 +1,54 @@
+/**
+ * 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;
+}
+/**
+ * Request interface for addComment function.
+ * Matches legacy AddCommentRequest interface.
+ */
+export interface AddCommentRequest {
+    editorId?: string;
+    editor: unknown;
+    context?: unknown;
+}
+/**
+ * Request interface for renderComments function.
+ * Matches legacy RenderCommentsRequest interface.
+ */
+export interface RenderCommentsRequest {
+    editor: unknown;
+    editorId?: string;
+    commentAnnotations?: CommentAnnotation[];
+}
+/**
+ * Extension configuration for registry.
+ */
+export interface ExtensionConfig {
+    persistVeltMarks?: boolean;
+    editorId?: string;
+    HistoryEditor?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * Editor context containing editor instance and related state.
+ * Note: Editor type is generic to avoid importing editor types here.
+ */
+export interface EditorContext<TEditor = unknown> {
+    editorId: string;
+    editor: TEditor;
+    config: ExtensionConfig;
+}

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

@@ -0,0 +1,74 @@
+/**
+ * Editor-specific type definitions for Plate.js.
+ * This is the ONLY place where editor-specific types may be defined.
+ */
+import type { Descendant } from 'slate';
+import type { PlateEditor } from '@platejs/core/react';
+import type { AnnotationData } from '@/types/state';
+/**
+ * Extended PlateEditor interface with Velt comments functionality.
+ */
+export interface VeltCommentsEditor extends PlateEditor {
+}
+/**
+ * Velt comment element type for the editor.
+ * This represents a comment annotation node/element in the editor's document model.
+ */
+export type VeltCommentsElement = {
+    type: 'veltComment';
+    children: Descendant[];
+    annotationId?: string;
+    multiThreadAnnotationId?: string;
+};
+/**
+ * Selection context extracted from editor.
+ */
+export interface SelectionContext {
+    text: string;
+    from: number;
+    to: number;
+    occurrence: number;
+    targetTextNodeId?: string;
+    locationId?: string;
+}
+/**
+ * Occurrence match result.
+ */
+export interface OccurrenceMatch {
+    index: number;
+    start: number;
+    end: number;
+    text: string;
+}
+/**
+ * Represents a detected change to an annotation during document editing.
+ */
+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;
+}
+/**
+ * Document change event data.
+ */
+export interface DocumentChangeEvent {
+    editorId: string;
+    changes: Map<string, AnnotationChange>;
+}
+/**
+ * Plugin configuration options for VeltCommentsPlugin.
+ */
+export interface VeltCommentsPluginConfig {
+    editorId?: string;
+    persistVeltMarks?: boolean;
+    HistoryEditor?: unknown;
+}

package/esm/types/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;
+    };
+}
+/**
+ * Annotation state per editor instance.
+ * Stores both simplified AnnotationData[] for core logic and full CommentAnnotation[] for rendering.
+ */
+export interface AnnotationState {
+    editorId: string;
+    annotations: Map<string, AnnotationData>;
+    commentAnnotations: CommentAnnotation[];
+    selectedAnnotations: Set<string>;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Velt SDK type definitions.
+ * This is the ONLY place where @veltdev/types may be imported.
+ */
+import type { CommentAnnotation, Location, Velt } from '@veltdev/types';
+export type { CommentAnnotation, Location, Velt };
+/**
+ * Comment element from Velt SDK.
+ */
+export type CommentElement = {
+    addManualComment: (params: {
+        context: unknown;
+        location?: Location;
+    }) => Promise<CommentAnnotation | null>;
+    updateContext: (annotationId: string, context: unknown) => void;
+    getSelectedComments?: () => {
+        subscribe: (callback: (comments: CommentAnnotation[]) => void) => () => void;
+    };
+};
+/**
+ * Unsubscribe function for Velt SDK subscriptions.
+ */
+export type UnsubscribeFn = () => void;