tiptop-editor 1.3.0 → 1.5.0

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import { Extensions } from '@tiptap/core';
+import { Extensions, JSONContent } from '@tiptap/core';
 import { Editor, EditorContentProps, Range, UseEditorOptions } from '@tiptap/react';
 import { icons } from 'lucide-react';
 export type ImageUploadResponseResolver = string | string[] | ((response: Record<string, unknown>) => string | null | undefined);
@@ -99,11 +99,87 @@ export interface TiptopEditorSlots {
     tableMenuPrepend?: TiptopEditorSlot;
     tableMenuAppend?: TiptopEditorSlot;
 }
+export interface DocumentWord {
+    /** 0-based index of this word within its block node */
+    index: number;
+    /** Plain text of this word */
+    text: string;
+    /** Absolute ProseMirror position of the word's first character */
+    absFrom: number;
+    /** Absolute ProseMirror position after the word's last character */
+    absTo: number;
+}
+export interface DocumentNode {
+    /** 0-based index of this block in the document */
+    index: number;
+    /** ProseMirror node type name (e.g. "paragraph", "heading") */
+    type: string;
+    /** Full plain-text content of this block */
+    text: string;
+    /** Absolute ProseMirror position of the block's opening tag */
+    absFrom: number;
+    /** Absolute ProseMirror position after the block's closing tag */
+    absTo: number;
+    /** Words extracted from this block's text */
+    words: DocumentWord[];
+    /**
+     * Maps each character index in `text` to its absolute ProseMirror position.
+     * Use this when word-level precision is not enough.
+     */
+    charMap: number[];
+}
+export interface DocumentMap {
+    nodes: DocumentNode[];
+}
+/**
+ * Replacement content for a targeted update.
+ * - `string`: plain text — marks from the replaced range are automatically preserved.
+ * - `JSONContent[]`: rich inline content (text nodes with explicit marks, etc.).
+ */
+export type TargetedUpdateReplacement = string | JSONContent[];
+export interface TargetedUpdate {
+    /** 0-based index of the target block in the document */
+    nodeIndex?: number;
+    /** 0-based word index within the target block */
+    wordIndex?: number;
+    /** Inclusive `[startWordIndex, endWordIndex]` word range within the target block */
+    wordRange?: [number, number];
+    /**
+     * 0-based character offset from the start of the block's text content.
+     * Must be paired with `charTo`.
+     */
+    charFrom?: number;
+    /**
+     * 0-based exclusive character offset from the start of the block's text content.
+     * Must be paired with `charFrom`.
+     */
+    charTo?: number;
+    /** Content to replace the targeted range with */
+    replacement: TargetedUpdateReplacement;
+}
 export interface TiptopEditorHandle {
     getEditor: () => Editor | null;
     on: Editor['on'];
     off: Editor['off'];
     once: Editor['once'];
+    /**
+     * Returns a structured map of all top-level block nodes in the document with
+     * their text content, word boundaries, and absolute ProseMirror positions.
+     * Pass this to your AI model so it can reference specific locations.
+     * Returns `null` if the editor is not yet mounted.
+     */
+    getDocumentMap: () => DocumentMap | null;
+    /**
+     * Applies a single targeted content update, preserving marks on plain-text
+     * replacements. Returns `true` on success.
+     */
+    applyTargetedUpdate: (update: TargetedUpdate) => boolean;
+    /**
+     * Applies multiple targeted updates in one atomic ProseMirror transaction,
+     * processing from the bottom of the document upward so earlier replacements
+     * never shift the positions of later ones. Returns `true` on success.
+     */
+    applyTargetedUpdates: (updates: TargetedUpdate[]) => boolean;
 }
 export interface KeyDownRef {
     onKeyDown: (props: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiptop-editor",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Notion-like editor built with Tiptap v3 and HeroUI",
   "type": "module",
   "main": "./dist/tiptop-editor.umd.js",