tiptop-editor 1.2.0 → 1.4.0

package/README.md

@@ -43,7 +43,7 @@ export function Editor() {
 }
 ```
 
-`editorOptions` accepts the same options as `useEditor` from `@tiptap/react`, except `extensions`, which is managed internally by the package.
+`editorOptions` accepts the same options as `useEditor` from `@tiptap/react`, except `extensions`, which is managed internally by the package. To add your own extensions, use `editorOptions.extraExtensions`.
 
 ## Editor Ref and Events
 
@@ -79,6 +79,99 @@ Available ref methods:
 - `off(event, callback?)`
 - `once(event, callback)`
 
+## Extending the Editor
+
+The package now supports two extension points:
+
+- `editorOptions.extraExtensions`
+  Appends custom Tiptap extensions after the built-in set.
+- `slots`
+  Lets you inject custom React UI around the editor and inside the selection menus.
+
+### Add custom Tiptap extensions
+
+```tsx
+import { Extension } from '@tiptap/core'
+import { TiptopEditor } from 'tiptop-editor'
+
+const MyExtension = Extension.create({
+  name: 'myExtension',
+})
+
+export function EditorWithExtraExtensions() {
+  return (
+    <TiptopEditor
+      editorOptions={{
+        immediatelyRender: false,
+        extraExtensions: [MyExtension],
+      }}
+    />
+  )
+}
+```
+
+`extraExtensions` is additive only. If you pass an extension with the same name as one of the built-in extensions, the editor will warn in the console and show a toast because duplicate extension names can lead to unstable behavior.
+
+### Add custom UI with slots
+
+Supported slots:
+
+- `editorTop`
+- `editorBottom`
+- `selectionMenuPrepend`
+- `selectionMenuAppend`
+- `tableMenuPrepend`
+- `tableMenuAppend`
+
+Each slot accepts either:
+
+- a React node
+- a render function receiving `{ editor }`
+
+```tsx
+<TiptopEditor
+  slots={{
+    editorTop: ({ editor }) => (
+      <button onClick={() => editor.chain().focus().insertContent('<p>Draft</p>').run()}>
+        Insert draft
+      </button>
+    ),
+  }}
+/>
+```
+
+### Use the editor context hook
+
+For slotted components, you can consume the current editor instance through `useTiptopEditor()` instead of passing `editor` down manually.
+
+```tsx
+import { TiptopEditor, useTiptopEditor } from 'tiptop-editor'
+
+function AiToolbar() {
+  const editor = useTiptopEditor()
+
+  if (!editor) {
+    return null
+  }
+
+  return (
+    <button onClick={() => editor.chain().focus().insertContent('<p>AI draft</p>').run()}>
+      Insert draft
+    </button>
+  )
+}
+
+export function EditorWithSlots() {
+  return (
+    <TiptopEditor
+      slots={{
+        editorTop: <AiToolbar />,
+      }}
+    />
+  )
+}
+```
+
 ## Custom Editor UI Options
 
 `TiptopEditor` also supports a few package-specific options inside `editorOptions`:
@@ -97,6 +190,8 @@ Available ref methods:
   Disables the default HeroUI `Card` wrapper and removes the editor's built-in padding. Use this when you want the editor to live inside your own container/layout.
 - `showDragHandle`
   Controls whether the block drag handle is rendered. Default: `true`.
+- `extraExtensions`
+  Appends custom Tiptap extensions after the built-in editor set.
 
 ## Built-in Extensions
 
@@ -242,7 +337,7 @@ Example:
 ## Notes
 
 - If you use SSR, keep `immediatelyRender: false`.
-- The package manages the editor extensions internally, so custom `extensions` are intentionally not accepted yet.
+- The package manages the built-in editor extensions internally. Use `editorOptions.extraExtensions` to append your own feature extensions.
 
 ## Feedback
 

package/dist/components/editor/TableSelectionMenu.d.ts

@@ -1,4 +1,4 @@
 import { default as React } from 'react';
 import { TextSelectionMenuProps } from '../../types';
-declare const _default: React.MemoExoticComponent<({ editor }: TextSelectionMenuProps) => import("react/jsx-runtime").JSX.Element>;
+declare const _default: React.MemoExoticComponent<({ editor, prepend, append }: TextSelectionMenuProps) => import("react/jsx-runtime").JSX.Element>;
 export default _default;

package/dist/components/editor/TiptopEditor.stories.d.ts

@@ -14,3 +14,4 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 export declare const Default: Story;
 export declare const Frameless: Story;
+export declare const WithSlots: Story;

package/dist/components/editor/TiptopEditorContext.d.ts

@@ -0,0 +1,3 @@
+import { Editor } from '@tiptap/react';
+export declare const TiptopEditorContext: import('react').Context<Editor | null>;
+export declare const useTiptopEditor: () => Editor | null;

package/dist/components/editor/createDefaultExtensions.d.ts

@@ -0,0 +1,8 @@
+import { Extensions } from '@tiptap/core';
+import { ImageUploadResponseResolver } from '../../types';
+interface CreateDefaultExtensionsOptions {
+    imgUploadUrl?: string;
+    imgUploadResponseKey?: ImageUploadResponseResolver;
+}
+export declare const createDefaultExtensions: ({ imgUploadUrl, imgUploadResponseKey, }: CreateDefaultExtensionsOptions) => Extensions;
+export {};

package/dist/components/editor/renderTiptopSlot.d.ts

@@ -0,0 +1,4 @@
+import { Editor } from '@tiptap/react';
+import { ReactNode } from 'react';
+import { TiptopEditorSlot } from '../../types';
+export declare const renderTiptopSlot: (slot: TiptopEditorSlot | undefined, editor: Editor | null) => ReactNode;

package/dist/components/editor/useDuplicateExtensionWarnings.d.ts

@@ -0,0 +1,2 @@
+import { Extensions } from '@tiptap/core';
+export declare const useDuplicateExtensionWarnings: (baseExtensions: Extensions, extraExtensions: Extensions) => void;

package/dist/helpers.d.ts

@@ -1,6 +1,6 @@
 import { Editor } from '@tiptap/core';
 import { EditorState } from '@tiptap/pm/state';
-import { SlashCommandGroupCommandsProps } from './types';
+import { DocumentMap, SlashCommandGroupCommandsProps, TargetedUpdate } from './types';
 import { Node } from '@tiptap/pm/model';
 export declare const isTextSelected: (editor: Editor) => boolean;
 export declare const hasTextNodeInSelection: (editor: Editor) => boolean;
@@ -38,3 +38,31 @@ export declare const getUploaderAtPos: (state: Editor["state"], pos: number) =>
     depth: number;
     node: Node;
 } | undefined;
+/**
+ * Returns a structured snapshot of every top-level block in the editor.
+ * Send this to your AI model so it can reference nodes and words by index.
+ */
+export declare const getDocumentMap: (editor: Editor) => DocumentMap;
+/**
+ * Applies a single targeted content update.
+ *
+ * @example
+ * // Translate the first word of the second paragraph
+ * applyTargetedUpdate(editor, { nodeIndex: 1, wordIndex: 0, replacement: 'Bonjour' })
+ */
+export declare const applyTargetedUpdate: (editor: Editor, update: TargetedUpdate) => boolean;
+/**
+ * Applies multiple targeted updates in a single atomic ProseMirror transaction.
+ *
+ * All positions are resolved against the document state *before* any mutations,
+ * then applied from the bottom of the document upward so that earlier replacements
+ * never shift the absolute positions of later ones.
+ *
+ * @example
+ * // Bold-ify two specific words in one go
+ * applyTargetedUpdates(editor, [
+ *   { nodeIndex: 0, wordIndex: 2, replacement: [{ type: 'text', text: 'foo', marks: [{ type: 'bold' }] }] },
+ *   { nodeIndex: 2, wordRange: [0, 1], replacement: 'Hello world' },
+ * ])
+ */
+export declare const applyTargetedUpdates: (editor: Editor, updates: TargetedUpdate[]) => boolean;

package/dist/index.d.ts

@@ -1,2 +1,4 @@
 export { default as TiptopEditor } from './components/editor/TiptopEditor';
+export { TiptopEditorContext, useTiptopEditor } from './components/editor/TiptopEditorContext';
+export { getDocumentMap, applyTargetedUpdate, applyTargetedUpdates } from './helpers';
 export * from './types';