tiptop-editor 1.1.0 → 1.3.0

package/README.md

@@ -43,7 +43,134 @@ 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
+
+You can access the editor instance and bind Tiptap runtime event listeners through the component ref.
+
+```tsx
+import { useEffect, useRef } from 'react'
+import { TiptopEditor, type TiptopEditorHandle } from 'tiptop-editor'
+
+export function EditorWithEvents() {
+  const editorRef = useRef<TiptopEditorHandle>(null)
+
+  useEffect(() => {
+    const handleUpdate = ({ editor }: { editor: NonNullable<ReturnType<TiptopEditorHandle['getEditor']>> }) => {
+      console.log(editor.getHTML())
+    }
+
+    editorRef.current?.on('update', handleUpdate)
+
+    return () => {
+      editorRef.current?.off('update', handleUpdate)
+    }
+  }, [])
+
+  return <TiptopEditor ref={editorRef} />
+}
+```
+
+Available ref methods:
+
+- `getEditor()`
+- `on(event, callback)`
+- `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
 
@@ -63,6 +190,8 @@ export function Editor() {
   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
 
@@ -208,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

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

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

@@ -0,0 +1,3 @@
+import { TiptopEditorHandle, TiptopEditorProps } from '../../types';
+declare const TiptopEditor: import('react').ForwardRefExoticComponent<Omit<TiptopEditorProps, "ref"> & import('react').RefAttributes<TiptopEditorHandle>>;
+export default TiptopEditor;

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

@@ -0,0 +1,17 @@
+import { StoryObj } from '@storybook/react-vite';
+declare const meta: {
+    title: string;
+    component: import('react').ForwardRefExoticComponent<Omit<import('../..').TiptopEditorProps, "ref"> & import('react').RefAttributes<import('../..').TiptopEditorHandle>>;
+    tags: string[];
+    args: {
+        editorOptions: {
+            content: string;
+            immediatelyRender: false;
+        };
+    };
+};
+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/components/{ColorButton.d.ts → menus/ColorButton.d.ts}

@@ -1,4 +1,4 @@
 import { default as React } from 'react';
-import { ColorButtonProps } from '../types';
+import { ColorButtonProps } from '../../types';
 declare const _default: React.MemoExoticComponent<({ editor, buttonType, hsl, color, bgColor, tooltipText, tooltipDisabled, }: ColorButtonProps) => import("react/jsx-runtime").JSX.Element>;
 export default _default;

package/dist/components/{TextSelectionMenu.d.ts → menus/TextSelectionMenu.d.ts}

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

package/dist/components/{EditorButton.d.ts → ui/EditorButton.d.ts}

@@ -1,4 +1,4 @@
-import { EditorButtonProps } from '../types';
+import { EditorButtonProps } from '../../types';
 import { default as React } from 'react';
 declare const _default: React.MemoExoticComponent<({ editor, buttonKey, tooltipText, isIconOnly, color, variant, isDisabled, icon, iconClass, text, withActive, onPressed, }: EditorButtonProps) => import("react/jsx-runtime").JSX.Element>;
 export default _default;

package/dist/index.d.ts

@@ -1,2 +1,3 @@
-export { default as TiptopEditor } from './components/TiptopEditor';
+export { default as TiptopEditor } from './components/editor/TiptopEditor';
+export { TiptopEditorContext, useTiptopEditor } from './components/editor/TiptopEditorContext';
 export * from './types';