tiptop-editor 1.0.18 → 1.2.0

package/README.md

@@ -1,69 +1,249 @@
-# 📝 Tiptop Editor
+# Tiptop Editor
 
-A Notion-like rich text editor built with [Tiptap v3](https://tiptap.dev/), [HeroUI](https://heroui.dev/), [Tailwind v4](https://https://tailwindcss.com) packaged as a plug-and-play React component.
-Inspired from [TipTap Notion-like](https://tiptap.dev/docs/ui-components/templates/notion-like-editor).
+A Notion-like rich text editor built with [Tiptap v3](https://tiptap.dev/), [HeroUI](https://www.heroui.com/), and Tailwind CSS, packaged as a plug-and-play React component.
+
+Inspired by Tiptap's Notion-like editor template:
+https://tiptap.dev/docs/ui-components/templates/notion-like-editor
 
 ![npm version](https://img.shields.io/npm/v/tiptop-editor.svg)
 ![bundle size](https://img.shields.io/bundlephobia/minzip/tiptop-editor)
 ![license](https://img.shields.io/npm/l/tiptop-editor)
 
----
+## Features
 
-## ✨ Features
+- Tiptap v3 editor with a ready-to-use Notion-like UI
+- Slash commands for inserting blocks
+- Table support with row, column, header, split, and merge actions
+- Emoji suggestions triggered with `:`
+- Built-in image uploader block
+- Text formatting, lists, code blocks, highlights, alignment, subscript, and superscript
+- TypeScript support
 
-- Built on **Tiptap v3** — a powerful, headless rich-text editor
-- Styled with **HeroUI** + **Tailwind**
-- Fully typed with **TypeScript**
-- Ready to embed in any React app
-- Designed for **Notion-like UX**
+## Installation
 
+```bash
+npm install tiptop-editor
+```
 
-https://github.com/user-attachments/assets/cb7d907d-bae0-4b3b-b6e7-8493180afd75
+## Basic Usage
 
+```tsx
+import { TiptopEditor } from 'tiptop-editor'
+import 'tiptop-editor/dist/tiptop-editor.css'
+
+export function Editor() {
+  return (
+    <TiptopEditor
+      editorOptions={{
+        content: '<p>I am the Tiptop Editor</p>',
+        immediatelyRender: false,
+      }}
+    />
+  )
+}
+```
 
----
+`editorOptions` accepts the same options as `useEditor` from `@tiptap/react`, except `extensions`, which is managed internally by the package.
 
-## ⚙️ Installation
-```bash
-npm install tiptop-editor
+## 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} />
+}
 ```
 
-## 🚀 Usage
+Available ref methods:
 
-**Import the component in your app**
-  ```tsx
-  import { TiptopEditor } from "tiptop-editor";
+- `getEditor()`
+- `on(event, callback)`
+- `off(event, callback?)`
+- `once(event, callback)`
+
+## Custom Editor UI Options
+
+`TiptopEditor` also supports a few package-specific options inside `editorOptions`:
 
-  <TiptopEditor />
-  ```
-**Add the CSS code to your app**
-For the package to behave like it should, you have to import the compiled CSS file. Add this line in your main css file, or import it directly in the component file that's going to host the **TiptopEditor**.
-- In your main css file
-  ```css
-  @import '../node_modules/tiptop-editor/dist/tiptop-editor.css';
-- In any component file
-  ```tsx
-  import 'tiptop-editor/dist/tiptop-editor.css'
-## 🎨 Example
-The Tiptop component takes as props all the props from the `UseEditorOptions` from [*@tiptap/react*](https://www.npmjs.com/package/@tiptap/react), except the `extensions` prop.
-*Why only that prop, you ask ? Well, since this package is intended to *replicate* the Notion-like style with all their blocks/extensions and plug-and-play, as of now, I have not allowed users to pass their own extensions. But that can change in the future, just not now.*
-Anyway, to use the package, just pass your props to `editorOptions` and you're good to go. Customize the Tiptop component will the props you want, as if you were using *EditorContent and passing props to the editor*.
 ```tsx
-<TiptopEditor editorOptions={{
-    immediatelyRender: false // If using SSR (ex. a NextJS project) otherwise you can omit it
-    content: '<p>I am the Tiptop Editor</p>'
-    ... // Other props
+<TiptopEditor
+  editorOptions={{
+    content: '<p>Custom layout</p>',
+    disableDefaultContainer: true,
+    showDragHandle: false,
   }}
 />
 ```
 
+- `disableDefaultContainer`
+  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`.
+
+## Built-in Extensions
+
+The package ships with these extensions enabled out of the box:
+
+- `StarterKit`
+- `ListKit`
+- `Placeholder`
+- custom slash command menu
+- custom code block
+- custom horizontal rule
+- `TextStyle` and `Color`
+- `Highlight`
+- `TextAlign`
+- `Subscript`
+- `Superscript`
+- emoji suggestions
+- `TableKit`
+- image uploader block and upload handler
+
+### Tables
+
+Type `/table` to insert a table.
+
+Inside a table you can:
+
+- add or remove rows
+- add or remove columns
+- toggle header row or header column
+- split a merged cell
+- merge adjacent selected cells
+
+To merge cells, drag across adjacent cells first, then use the table controls.
+
+### Emoji
+
+Type `:` followed by an emoji name to open emoji suggestions.
+
+## Image Extension
+
+The image feature is built around an `imageUploader` block.
+
+### How to insert an image block
+
+- Type `/image`
+- or use the slash menu and select `Image`
+
+Once inserted, the block lets the user click to upload or drag and drop an image.
+
+### Supported files
+
+- `image/png`
+- `image/jpeg`
+- `image/jpg`
+- max size: `5MB`
+
+### Demo mode with no backend
+
+If you do not provide upload options, the editor simulates an upload and displays the image using a local object URL. This is useful for local demos and prototypes.
+
+```tsx
+<TiptopEditor
+  editorOptions={{
+    content: '<p>Upload demo</p>',
+  }}
+/>
+```
+
+### Real upload mode
+
+To upload files to your backend, set both `imgUploadUrl` and `imgUploadResponseKey`.
+
+```tsx
+<TiptopEditor
+  editorOptions={{
+    content: '<p>Upload to my API</p>',
+    imgUploadUrl: '/api/upload',
+    imgUploadResponseKey: 'url',
+  }}
+/>
+```
+
+The editor sends a `POST` request with `multipart/form-data` and the file under the `file` field.
+
+`imgUploadResponseKey` is flexible. It supports:
+
+- a top-level key like `'url'`
+  Example:
+  ```tsx
+  <TiptopEditor
+    editorOptions={{
+      imgUploadUrl: '/api/upload',
+      imgUploadResponseKey: 'url',
+    }}
+  />
+  ```
+- a nested path like `'data.url'`
+  Example:
+  ```tsx
+  <TiptopEditor
+    editorOptions={{
+      imgUploadUrl: '/api/upload',
+      imgUploadResponseKey: 'data.url',
+    }}
+  />
+  ```
+- a path array like `['data', 'url']`
+  Example:
+  ```tsx
+  <TiptopEditor
+    editorOptions={{
+      imgUploadUrl: '/api/upload',
+      imgUploadResponseKey: ['data', 'url'],
+    }}
+  />
+  ```
+- a resolver function
+  Example:
+  ```tsx
+  <TiptopEditor
+    editorOptions={{
+      imgUploadUrl: '/api/upload',
+      imgUploadResponseKey: (response) => {
+        const asset = response.asset as { cdnUrl?: string } | undefined
+        return asset?.cdnUrl
+      },
+    }}
+  />
+  ```
+
+Your server response must include the uploaded image URL at the location you describe with `imgUploadResponseKey`.
+
+Example:
+
+```json
+{
+  "data": {
+    "url": "https://cdn.example.com/uploads/image-123.jpg"
+  }
+}
+```
 
-##### Of course, I will continue to improve this project over time, as I have many more ideas (more extensions, more customizations, etc..)
-##### Emoji Extension, Image extension, and more coming in next updates 🏃‍♂ ...
+## Notes
 
-I will also document the Changelogs and releases, as well as continue to update this Readme with relevant information.
+- If you use SSR, keep `immediatelyRender: false`.
+- The package manages the editor extensions internally, so custom `extensions` are intentionally not accepted yet.
 
-*If you have any suggestions/recommendations to improve this project, any feedback is much appreciated (PRs welcome) !*
-*I also encourage you to open up *Issues* if you find releveant bugs inside the package.*
+## Feedback
 
-**Thank you, and Happy Coding !**
+Issues and pull requests are welcome.

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 }: 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,16 @@
+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;

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/menus/TableButtonMenu.d.ts

@@ -0,0 +1,7 @@
+import { default as React } from 'react';
+import { Editor } from '@tiptap/react';
+interface TableButtonMenuProps {
+    editor: Editor;
+}
+declare const _default: React.MemoExoticComponent<({ editor }: TableButtonMenuProps) => import("react/jsx-runtime").JSX.Element | null>;
+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/extensions/slashCommand/SlashCommand.d.ts

@@ -1,3 +1,8 @@
 import { Extension } from '@tiptap/core';
-declare const _default: Extension<any, any>;
+import { SuggestionOptions } from '@tiptap/suggestion';
+import { SlashCommandGroupCommandsProps, SlashCommandGroupProps } from '../../types';
+export type SlashCommandSuggestionOptions = Omit<SuggestionOptions<SlashCommandGroupProps, SlashCommandGroupCommandsProps>, 'editor'>;
+declare const _default: Extension<{
+    suggestion: SlashCommandSuggestionOptions;
+}, any>;
 export default _default;

package/dist/extensions/slashCommand/SlashCommandSuggestion.d.ts

@@ -1,29 +1,3 @@
-import { Editor } from '@tiptap/react';
-import { PluginKey } from '@tiptap/pm/state';
-import { SuggestionKeyDownProps, SuggestionProps } from '@tiptap/suggestion';
-declare const _default: {
-    pluginKey: PluginKey<any>;
-    items: ({ query }: {
-        query: string;
-    }) => {
-        commands: {
-            key: string;
-            title: string;
-            icon: string;
-            description: string;
-            command: ({ editor, range }: {
-                editor: Editor;
-                range: import('@tiptap/core').Range;
-            }) => void;
-        }[];
-        key: string;
-        title: string;
-    }[];
-    render: () => {
-        onStart: (props: SuggestionProps) => void;
-        onUpdate(props: SuggestionProps): void;
-        onKeyDown(props: SuggestionKeyDownProps): boolean | undefined;
-        onExit(): void;
-    };
-};
-export default _default;
+import { SlashCommandSuggestionOptions } from './SlashCommand';
+declare const SlashCommandSuggestion: SlashCommandSuggestionOptions;
+export default SlashCommandSuggestion;

package/dist/helpers.d.ts

@@ -4,6 +4,7 @@ import { SlashCommandGroupCommandsProps } from './types';
 import { Node } from '@tiptap/pm/model';
 export declare const isTextSelected: (editor: Editor) => boolean;
 export declare const hasTextNodeInSelection: (editor: Editor) => boolean;
+export declare const isTableCellSelection: (editor: Editor) => boolean;
 export declare const isForbiddenNodeSelected: (editor: Editor) => boolean;
 export declare const canShowColorTransform: (editor: Editor) => string | false | undefined;
 export declare const canShowNodeTransform: (editor: Editor) => boolean | undefined;
@@ -23,9 +24,8 @@ export declare const uploadWithProgress: ({ file, url, onProgress, signal }: {
     url: string;
     onProgress: (percent: number) => boolean | void;
     signal?: AbortSignal;
-}) => Promise<{
-    url: string;
-}>;
+}) => Promise<Record<string, unknown>>;
+export declare const getValueAtPath: (source: Record<string, unknown>, path: string | string[]) => unknown;
 export declare const generateUniqueId: () => string;
 export declare const updateNodeByPos: (editor: Editor, find: {
     id?: string;

package/dist/index.d.ts

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