@veltdev/tiptap-velt-comments/esm/features/addComment.d.ts

Tiptap Extension to add Google Docs-style overlay comments to your Tiptap editor. Works with the Velt Collaboration SDK.

/**
 * 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 extension 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>;