tiptap-office 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,509 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import react__default, { ReactNode } from 'react';
+import { Editor } from '@tiptap/react';
+
+type ProviderName = 'anthropic' | 'openai' | 'google';
+interface TiptapOfficeConfig {
+    /** Base URL of your backend (no trailing slash). All editor API calls and
+     *  the LLM proxy are rooted here. */
+    apiBaseUrl: string;
+    /** Path under `apiBaseUrl` that proxies LLM provider requests. The library
+     *  POSTs to `${apiBaseUrl}${llmProxyPath}` using the Vercel AI SDK's
+     *  `baseURL` convention. Defaults to `/llm/proxy`. */
+    llmProxyPath?: string;
+    /** Credentials mode for backend fetches. Defaults to `'include'`
+     *  (cookie-based auth). Set to `'omit'` for token-only auth. */
+    includeCredentials?: RequestCredentials;
+    /** Returns the headers (e.g. auth) to attach to every backend fetch.
+     *  May return synchronously or as a promise. */
+    getAuthHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+    /** Returns extra headers for LLM proxy requests, scoped by provider and
+     *  chat id. Use this if your proxy needs routing hints
+     *  (e.g. provider selection, per-chat tracing). */
+    getProxyHeaders?: (params: {
+        provider: ProviderName;
+        chatId: string;
+    }) => Record<string, string>;
+    /** Default model id (e.g. `'gpt-4o'`, `'claude-3-7-sonnet-latest'`). The
+     *  consumer must supply this — no vendor model is hardcoded in the library. */
+    defaultModel: string;
+    /** Default provider matching `defaultModel`. */
+    defaultProvider: ProviderName;
+}
+declare function TiptapOfficeProvider({ config, children, }: {
+    config: TiptapOfficeConfig;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function useTiptapOfficeConfig(): TiptapOfficeConfig;
+
+/**
+ * Edit operation types for the AI editing pipeline (ADR-014).
+ * 13 operation types across paragraph and table categories.
+ */
+interface ReplaceTextOp {
+    type: 'replace_text';
+    target: string;
+    find: string;
+    replace: string;
+    reasoning: string;
+}
+interface ReplaceParagraphOp {
+    type: 'replace_paragraph';
+    target: string;
+    content: string;
+    reasoning: string;
+}
+interface InsertAfterOp {
+    type: 'insert_after';
+    target: string;
+    new_id: string;
+    content: string;
+    reasoning: string;
+}
+interface InsertBeforeOp {
+    type: 'insert_before';
+    target: string;
+    new_id: string;
+    content: string;
+    reasoning: string;
+}
+interface DeleteOp {
+    type: 'delete';
+    target: string;
+    reasoning: string;
+}
+interface ReplaceSectionOp {
+    type: 'replace_section';
+    target: string;
+    content: string;
+    reasoning: string;
+}
+interface AddCommentOp {
+    type: 'add_comment';
+    target: string;
+    comment_text: string;
+    comment_author: string;
+    comment_severity: string;
+    comment_act: string;
+    comment_article: string;
+    reasoning: string;
+}
+interface ReplaceCellOp {
+    type: 'replace_cell';
+    target: string;
+    content?: string;
+    paragraphs?: {
+        id: string;
+        content: string;
+    }[];
+    reasoning: string;
+}
+interface InsertRowOp {
+    type: 'insert_row';
+    table: string;
+    after_row: number;
+    cells: {
+        id: string;
+        content: string;
+    }[];
+    reasoning: string;
+}
+interface DeleteRowOp {
+    type: 'delete_row';
+    table: string;
+    row: number;
+    reasoning: string;
+}
+interface InsertColumnOp {
+    type: 'insert_column';
+    table: string;
+    after_column: number;
+    header: {
+        id: string;
+        content: string;
+    };
+    cells: {
+        id: string;
+        content: string;
+    }[];
+    reasoning: string;
+}
+interface DeleteColumnOp {
+    type: 'delete_column';
+    table: string;
+    column: number;
+    reasoning: string;
+}
+interface InsertTableOp {
+    type: 'insert_table';
+    after: string;
+    table_id: string;
+    headers: {
+        id: string;
+        content: string;
+    }[];
+    rows: {
+        id: string;
+        content: string;
+    }[][];
+    reasoning: string;
+}
+interface ReplaceTableOp {
+    type: 'replace_table';
+    target: string;
+    headers: {
+        id: string;
+        content: string;
+    }[];
+    rows: {
+        id: string;
+        content: string;
+    }[][];
+    reasoning: string;
+}
+type EditOperation = ReplaceTextOp | ReplaceParagraphOp | InsertAfterOp | InsertBeforeOp | DeleteOp | ReplaceSectionOp | AddCommentOp | ReplaceCellOp | InsertRowOp | DeleteRowOp | InsertColumnOp | DeleteColumnOp | InsertTableOp | ReplaceTableOp;
+type EditOperationType = EditOperation['type'];
+interface EditPlan {
+    operations: EditOperationWithStatus[];
+    summary: string;
+}
+type OperationStatus = 'pending' | 'applied' | 'failed' | 'skipped' | 'conflicted';
+type EditOperationWithStatus = EditOperation & {
+    /** Runtime status set by the client during preview/apply */
+    status?: OperationStatus;
+    /** Error message if status is 'failed' */
+    error?: string;
+    /** Section ID this operation belongs to (from backend edit_plan) */
+    target_section?: string;
+    /** When true, the target ID is a backend-generated placeholder for an empty section */
+    empty_section_placeholder?: boolean;
+};
+
+type SuggestionType = 'insertion' | 'deletion';
+interface SuggestionAuthor {
+    username: string;
+    isAI: boolean;
+}
+interface Suggestion {
+    id: string;
+    type: SuggestionType;
+    author: SuggestionAuthor;
+    text: string;
+    from: number;
+    to: number;
+    data?: Record<string, any>;
+}
+interface TrackChangesState {
+    enabled: boolean;
+    suggestions: Suggestion[];
+    showPanel: boolean;
+    suggestionCount: number;
+}
+type CommentSeverity = 'high' | 'moderate' | 'low';
+interface CommentAuthor {
+    username: string;
+    isAI: boolean;
+}
+interface CommentReply {
+    id: string;
+    author: CommentAuthor;
+    text: string;
+    createdAt: string;
+}
+interface Comment {
+    id: string;
+    author: CommentAuthor;
+    text: string;
+    replies: CommentReply[];
+    resolved: boolean;
+    severity: CommentSeverity;
+    createdAt: string;
+    from: number;
+    to: number;
+    selectedText: string;
+}
+interface CommentsState {
+    comments: Comment[];
+    showPanel: boolean;
+    commentCount: number;
+    activeCommentId: string | null;
+}
+
+interface TiptapEditorProps {
+    content: string | Record<string, unknown>;
+    onChange?: (html: string) => void;
+    onJsonChange?: (json: Record<string, unknown>) => void;
+    onCommentsChange?: (comments: Comment[]) => void;
+    onEditorReady?: (editor: Editor) => void;
+    editable?: boolean;
+    /** Reviewer mode: editable but locked to suggestion mode + comments only */
+    reviewerMode?: boolean;
+    placeholder?: string;
+    username?: string;
+    draftId?: string;
+    documentId?: string;
+    /** Enable persistent node-id extension (needed for AI edit operations) */
+    enableNodeIds?: boolean;
+    /** Enable AI drafting panel + section indexing hooks */
+    enableAIDrafting?: boolean;
+    /** Override the prose content area class (e.g. to center/constrain width) */
+    contentClassName?: string;
+    /** Force show comment bubble even when not editable (e.g. locked canvas) */
+    forceShowCommentBubble?: boolean;
+    /** When viewing a historical version, comment actions are read-only */
+    isHistoricalVersion?: boolean;
+    /** Show toolbar even when editor is not editable (e.g. locked canvas still needs AI/comment tools) */
+    showToolbar?: boolean;
+}
+declare const TiptapEditor: react__default.FC<TiptapEditorProps>;
+
+declare function useTrackChanges(editor: Editor | null): TrackChangesState & {
+    toggleSuggestionMode: () => void;
+    acceptSuggestion: (s: Suggestion) => void;
+    rejectSuggestion: (s: Suggestion) => void;
+    acceptAll: () => void;
+    rejectAll: () => void;
+    setShowPanel: (show: boolean) => void;
+};
+type UseTrackChangesReturn = ReturnType<typeof useTrackChanges>;
+
+declare function useComments(editor: Editor | null, draftId: string, username: string, initialComments?: Comment[]): {
+    comments: Comment[];
+    showPanel: boolean;
+    commentCount: number;
+    activeCommentId: string | null;
+    pendingSelectionText: string | null;
+    clickedCommentInfo: {
+        commentId: string;
+        source: "dot" | "highlight";
+    } | null;
+    setActiveCommentId: react.Dispatch<react.SetStateAction<string | null>>;
+    setShowPanel: react.Dispatch<react.SetStateAction<boolean>>;
+    setClickedCommentInfo: react.Dispatch<react.SetStateAction<{
+        commentId: string;
+        source: "dot" | "highlight";
+    } | null>>;
+    captureSelection: () => void;
+    clearPendingHighlight: () => void;
+    addComment: (text: string, severity?: CommentSeverity) => void;
+    addBatchComments: (newComments: Comment[]) => void;
+    deleteComment: (commentId: string) => void;
+    resolveComment: (commentId: string) => void;
+    resolveCommentsByIds: (ids: string[]) => void;
+    unresolveComment: (commentId: string) => void;
+    setSeverity: (commentId: string, severity: CommentSeverity) => void;
+    addReply: (commentId: string, text: string) => void;
+    deleteReply: (commentId: string, replyId: string) => void;
+    resolveAll: () => void;
+};
+type UseCommentsReturn = ReturnType<typeof useComments>;
+
+/** Subset of the agent hook the toolbar actually uses — keeps the toolbar
+ * decoupled from the full UseEditorAgentReturn surface. */
+interface PanelController {
+    isPanelOpen: boolean;
+    openPanel: () => void;
+    closePanel: () => void;
+}
+interface EditorToolbarProps {
+    editor: Editor | null;
+    trackChanges?: UseTrackChangesReturn;
+    comments?: UseCommentsReturn;
+    aiDrafting?: PanelController;
+    /** Reviewer mode: only show track changes + comments toolbar */
+    reviewerMode?: boolean;
+    /** Whether the review panel is currently open */
+    reviewPanelOpen?: boolean;
+    /** Toggle the review panel */
+    onToggleReviewPanel?: () => void;
+}
+declare const EditorToolbar: react__default.FC<EditorToolbarProps>;
+
+interface EditOperationCardProps {
+    operation: EditOperationWithStatus;
+    index: number;
+    editor: Editor | null;
+    onToggle: (index: number) => void;
+    onApplySingle: (index: number) => void;
+}
+declare const EditOperationCard: react__default.FC<EditOperationCardProps>;
+
+/**
+ * Shared types for the agent module.
+ */
+
+/**
+ * Lightweight content shape for a playbook surfaced to the system prompt.
+ * The editor's playbook system fetches raw text out-of-band; we only need
+ * a title + body for the prompt.
+ */
+interface AgentPlaybook {
+    id: string;
+    title: string;
+    content: string;
+}
+interface AgentComplianceAct {
+    id: string;
+    title: string;
+    description?: string;
+}
+/**
+ * A single agent-recorded change. Exactly one of `suggestionIds` (content op
+ * tracked via suggestion-mode marks) or `inverseOp` (structural op that bypassed
+ * suggestion mode) is populated.
+ */
+interface AgentChange {
+    id: string;
+    tool: EditOperationType;
+    args: unknown;
+    suggestionIds?: number[];
+    inverseOp?: EditOperation;
+    appliedAt: number;
+    revertedAt?: number;
+}
+
+/**
+ * Backend API client for editor chat sessions, history, and per-turn cost.
+ *
+ * Every export takes a `TiptapOfficeConfig` as its first argument. The library
+ * itself owns no URL constants, no auth headers, and no env-var lookups —
+ * everything comes from the config you pass to <TiptapOfficeProvider>.
+ *
+ * Your backend must expose:
+ *   POST {apiBaseUrl}/editor/chat                  → { chatId, created }
+ *   GET  {apiBaseUrl}/editor/history?page&pageSize → { sessions, total, page, pageSize }
+ *   GET  {apiBaseUrl}/editor/history/{chatId}      → { chatId, documentId, chatTitle, messages }
+ *   POST {apiBaseUrl}/editor/history/{chatId}/append → ack body ignored
+ *   POST {apiBaseUrl}/llm/cost                     → cost breakdown (or omit; `null` is tolerated)
+ *
+ * The LLM provider proxy lives under `{apiBaseUrl}{llmProxyPath}` and is
+ * handled by `agent/providers.ts`.
+ */
+
+interface ChatSession {
+    chatId: string;
+    documentId: string;
+    chatTitle: string;
+    messageCount: number;
+    lastEdited: string;
+}
+
+/**
+ * Phase 2a — Agent-loop hook for the rewritten AI editor (spec §11).
+ *
+ * Owns: state machine, message projection from the Vercel AI SDK `fullStream`,
+ * provider/model selection, journal lifetime, chat history persistence.
+ *
+ * Phase 1's `runAgent` drives the loop; this hook reduces stream parts into UI
+ * state and persists transcripts after each turn.
+ */
+
+type AgentUIState = 'IDLE' | 'INITIALIZING' | 'RUNNING' | 'AWAITING_USER' | 'ERROR';
+type AgentToolProgressStatus = 'running' | 'done' | 'failed';
+interface AgentToolProgress {
+    id: string;
+    tool: string;
+    label: string;
+    status: AgentToolProgressStatus;
+    error?: string;
+}
+interface AgentChatMessage {
+    id: string;
+    role: 'user' | 'assistant';
+    content: string;
+    timestamp: number;
+    toolProgress?: AgentToolProgress[];
+    clarificationQuestions?: string[];
+}
+interface UseEditorAgentReturn {
+    state: AgentUIState;
+    messages: AgentChatMessage[];
+    statusMessage: string;
+    errorMessage: string;
+    isPanelOpen: boolean;
+    streamingMessageId: string | null;
+    activeChanges: AgentChange[];
+    provider: ProviderName;
+    model: string;
+    setProvider: (p: ProviderName, model: string) => void;
+    /** USD cost of the most recently completed turn. `null` until the first turn finishes or if pricing lookup failed. */
+    lastTurnCostUsd: number | null;
+    /** Sum of all per-turn costs since the chat was opened or reset. */
+    cumulativeCostUsd: number;
+    openPanel: () => void;
+    closePanel: () => void;
+    submitPrompt: (prompt: string, opts?: {
+        playbook?: AgentPlaybook;
+    }) => void;
+    submitClarificationAnswer: (answers: string[]) => void;
+    cancel: () => void;
+    startNewChat: () => void;
+    historySessions: ChatSession[];
+    isHistoryLoading: boolean;
+    fetchHistory: () => void;
+    loadSession: (chatId: string) => void;
+}
+declare function useEditorAgent(editor: Editor | null, documentId: string, options?: {
+    onAICommentsCreated?: (comments: Comment[]) => void;
+    comments?: Comment[];
+    suggestions?: Suggestion[];
+    onCommentsResolved?: (commentIds: string[]) => void;
+    /** Optional callback the agent can use to fetch a playbook by id mid-turn
+     *  (exposed via the `lookup_playbook` tool). */
+    loadPlaybook?: (playbookId: string) => Promise<AgentPlaybook | null>;
+    /** Optional callback the agent can use to fetch a compliance act by id mid-turn
+     *  (exposed via the `lookup_compliance_act` tool). */
+    loadComplianceAct?: (actId: string) => Promise<AgentComplianceAct | null>;
+}): UseEditorAgentReturn;
+
+declare function docxToHtml(arrayBuffer: ArrayBuffer): Promise<string>;
+
+/**
+ * Apply an AI-generated text suggestion as a tracked change.
+ * The suggestion appears as a reviewable change the user can accept/reject.
+ *
+ * Temporarily enables suggest-changes mode (if not already on), performs the
+ * replacement, then restores the original mode. The dispatchTransaction wrapper
+ * automatically converts the replacement into insertion/deletion marks.
+ */
+declare function applyAISuggestion(editor: Editor, suggestion: {
+    textToReplace: string;
+    textReplacement: string;
+    reason?: string;
+    textBefore?: string;
+    textAfter?: string;
+}): boolean;
+/**
+ * Apply multiple AI suggestions to the document.
+ * Applies them in order; each suggestion should have enough context
+ * (textBefore/textAfter) to locate the correct position.
+ */
+declare function applyAISuggestions(editor: Editor, suggestions: Array<{
+    textToReplace: string;
+    textReplacement: string;
+    reason?: string;
+    textBefore?: string;
+    textAfter?: string;
+}>): {
+    applied: number;
+    failed: number;
+};
+
+/**
+ * Edit applicator — converts AI edit operations into a single ProseMirror transaction.
+ * Implements all 13 operation types from ADR-014.
+ */
+
+/**
+ * Apply a list of edit operations as a single ProseMirror transaction.
+ * One Ctrl+Z undoes the entire edit plan atomically.
+ * Returns the list of operations with updated status.
+ */
+declare function applyEditPlan(editor: Editor, operations: EditOperationWithStatus[]): EditOperationWithStatus[];
+/**
+ * Generate a string key for an applied operation (used in confirm request).
+ */
+declare function operationKey(op: EditOperationWithStatus): string;
+
+export { type AgentChange, type AgentChatMessage, type AgentComplianceAct, type AgentPlaybook, type AgentToolProgress, type AgentUIState, type Comment, type CommentAuthor, type CommentReply, type CommentSeverity, type CommentsState, type EditOperation, EditOperationCard, type EditOperationWithStatus, type EditPlan, EditorToolbar, type ProviderName, type Suggestion, type SuggestionAuthor, TiptapEditor, type TiptapOfficeConfig, TiptapOfficeProvider, type TrackChangesState, type UseEditorAgentReturn, applyAISuggestion, applyAISuggestions, applyEditPlan, docxToHtml, operationKey, useComments, useEditorAgent, useTiptapOfficeConfig, useTrackChanges };