tiptop-editor 1.2.0 → 1.4.0

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+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);
@@ -27,6 +28,12 @@ export type TiptopEditorOptions = Omit<Partial<UseEditorOptions & {
    * @default true
    */
     showDragHandle?: boolean;
+    /**
+   * Additional Tiptap extensions to append after the built-in editor set.
+   * Use this to add feature-specific extensions like AI commands or collaboration.
+   * @default undefined
+   */
+    extraExtensions?: Extensions;
 }>, 'extensions'>;
 export interface EditorButtonProps {
     tooltipText?: React.ReactNode;
@@ -64,6 +71,7 @@ export type TiptopEditorProps = Omit<EditorContentProps, 'editor'> & {
    * implementation.
    */
     editorOptions?: TiptopEditorOptions;
+    slots?: TiptopEditorSlots;
 };
 export interface ColorButtonProps {
     editor: Editor;
@@ -79,11 +87,99 @@ export interface TextSelectionMenuProps {
     prepend?: React.ReactNode;
     append?: React.ReactNode;
 }
+export interface TiptopEditorSlotProps {
+    editor: Editor;
+}
+export type TiptopEditorSlot = React.ReactNode | ((props: TiptopEditorSlotProps) => React.ReactNode);
+export interface TiptopEditorSlots {
+    editorTop?: TiptopEditorSlot;
+    editorBottom?: TiptopEditorSlot;
+    selectionMenuPrepend?: TiptopEditorSlot;
+    selectionMenuAppend?: TiptopEditorSlot;
+    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.2.0",
+  "version": "1.4.0",
   "description": "Notion-like editor built with Tiptap v3 and HeroUI",
   "type": "module",
   "main": "./dist/tiptop-editor.umd.js",