@veltdev/tiptap-velt-comments/cjs/adapters/host/doc.d.ts

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

/**
 * Host adapter for document operations.
 *
 * Purpose: Tiptap/ProseMirror document operations (selection, text extraction, occurrence finding).
 * This is ONE OF ONLY TWO places where Tiptap/ProseMirror types may be imported.
 *
 * Key responsibilities:
 * - Extract current selection context (text, position, occurrence)
 * - Find text occurrences in document or specific DOM element
 * - Detect document changes during transactions
 * - Extract editor IDs from editor instances
 * - Find parent nodes with IDs
 *
 * Dependencies:
 * - @tiptap/core (ONLY place allowed to import Editor, Node, Transaction)
 * - utils/common.ts (for pure text search algorithms)
 * - types/host.ts (for SelectionContext, AnnotationChange)
 * - constants/common.ts (for attribute constants)
 * - utils/console.ts (for logging)
 */
import type { Editor } from '@tiptap/core';
import type { Transaction } from '@tiptap/pm/state';
import type { AnnotationChange, SelectionContext } from '@/types/host';
/**
 * Extracts the current selection context from the editor.
 * Includes text, position, occurrence number, and container information.
 *
 * @param editor The Tiptap editor instance
 * @returns SelectionContext with all selection information, or null if no valid selection
 */
export declare const getCurrentSelectionContext: (editor: Editor) => SelectionContext | null;
/**
 * Finds the occurrence index (1-based) of the selected text.
 *
 * @param editor The editor instance
 * @param selectedText The text to find occurrences for
 * @param targetTextNode Target text node for scoped searching (optional)
 * @param selectionFrom The from position of current selection
 * @param selectionTo The to position of current selection
 * @returns The 1-indexed occurrence number (defaults to 1)
 */
export declare const findOccurrenceIndex: (editor: Editor, selectedText: string, targetTextNode: HTMLElement | null, selectionFrom: number, selectionTo: number) => number;
/**
 * Finds all occurrences of text in the document or a specific DOM element.
 *
 * @param editor The editor instance
 * @param text The text to search for
 * @param targetTextNodeId Optional DOM element ID to scope search
 * @param desiredOccurrence Optional maximum occurrence to find
 * @returns Array of { from, to } position ranges
 */
export declare const findTextOccurrences: (editor: Editor, text: string, targetTextNodeId?: string, desiredOccurrence?: number) => Array<{
    from: number;
    to: number;
}>;
/**
 * Extracts the editor ID from the editor instance.
 * Checks editor storage first, then DOM attributes.
 *
 * @param editor The editor instance
 * @returns Editor ID string or null if not found
 */
export declare const getEditorId: (editor: Editor) => string | null;
/**
 * Ensures editor is set up (registered and document listeners configured).
 * This is a unified adapter function that handles both registration and setup.
 *
 * @param editorId Optional editor ID (will be resolved from editor if not provided)
 * @param editor The editor instance (typed as unknown to avoid importing editor types in feature modules)
 * @returns Object with editorId string
 *
 * @remarks
 * - This function abstracts editor-specific setup logic
 * - For TipTap, just resolves editor ID (document listeners are handled by extension)
 * - Fails silently if setup fails
 */
export declare const ensureEditorSetup: (editorId: string | undefined, editor: unknown) => {
    editorId: string;
};
/**
 * Resets the editor selection by focusing the editor.
 * Uses TipTap's chain API to reset selection/focus after comment operations.
 *
 * @param editor The editor instance (typed as unknown to avoid importing editor types in feature modules)
 * @returns void
 *
 * @remarks
 * - This function abstracts editor-specific selection reset logic
 * - For TipTap, uses the chain API: `editor.chain().focus().run()`
 * - Fails silently if chain API is unavailable
 */
export declare const resetEditorSelection: (editor: unknown) => void;
/**
 * Finds the parent DOM node with an ID attribute, starting from the current selection.
 *
 * @param editor The editor instance
 * @returns HTMLElement with ID, or null if not found
 */
export declare const findParentNodeWithId: (editor: Editor) => HTMLElement | null;
/**
 * Detects document changes during a transaction and identifies annotation changes.
 * This collects all annotations with marks from the document and prepares change data.
 *
 * @param editor The editor instance
 * @param transaction The ProseMirror transaction
 * @param markType The mark type to look for (default: 'tiptapVeltComments')
 * @param getAnnotationData Function to retrieve annotation data by ID
 * @returns Map of annotation ID to AnnotationChange
 */
export declare const detectDocumentChanges: (editor: Editor, transaction: Transaction, markType: string | undefined, getAnnotationData: (annotationId: string) => {
    annotation: unknown;
    originalText: string;
    originalOccurrence: number;
    targetTextNodeId: string;
} | null) => Map<string, AnnotationChange>;