tiptap-notion-editor 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aicademy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+# tiptap-notion-editor
+
+Editor rich text kiểu Notion, dựng trên Tiptap 3.
+
+Slash command, bubble menu, kéo-thả block, bảng có handle, upload ảnh, công thức
+toán (KaTeX), emoji, `@mention` và mục lục ở lề.
+
+## Cài đặt
+
+```bash
+pnpm add tiptap-notion-editor
+```
+
+Peer dependency phải có sẵn trong app chủ — đây là chủ ý, không phải thiếu sót:
+gói kèm `@tiptap/*` sẽ tạo instance ProseMirror thứ hai và schema từ hai instance
+khác nhau không nhận nhau.
+
+```bash
+pnpm add @tiptap/core @tiptap/pm @tiptap/react react react-dom
+```
+
+## Dùng
+
+```tsx
+import { NotionEditor } from "tiptap-notion-editor";
+import "tiptap-notion-editor/style.css";
+
+export function PageEditor({ page }) {
+  return (
+    <NotionEditor
+      key={page.id}
+      content={page.content}
+      onChange={(json) => savePage(page.id, json)}
+      uploadImage={async (file) => {
+        const url = await uploadToStorage(file);
+        return url;
+      }}
+      mentionSource={async (query) => {
+        const users = await searchUsers(query);
+        return users.map((u) => ({ id: u.id, label: u.fullName }));
+      }}
+    />
+  );
+}
+```
+
+## Tailwind
+
+Component dùng class tiện ích của Tailwind, và các class đó do **app chủ** biên
+dịch chứ không nằm sẵn trong `style.css`. Thêm dòng sau vào file CSS entry của
+app, ngay sau `@import "tailwindcss"`:
+
+```css
+@source "../node_modules/tiptap-notion-editor/lib/*.js";
+```
+
+Không có dòng này editor vẫn chạy nhưng gần như không có style.
+
+Editor cũng đọc các biến theme của app (`--color-background`, `--color-border`,
+`--color-primary`…). Thiếu biến nào thì token trong `lib/styles/tokens.css` tự
+rơi về giá trị dự phòng.
+
+## Ngôn ngữ
+
+Mặc định là **tiếng Việt**. Đổi bằng prop `locale`:
+
+```tsx
+<NotionEditor locale="en" />
+```
+
+Từ điển gồm hai bản `vi` và `en`, xuất ra ngoài để app chủ ghi đè từng chuỗi
+mà không phải fork package:
+
+```tsx
+import { NotionEditor, getMessages, type Messages } from "tiptap-notion-editor";
+
+const t: Messages = getMessages("vi");
+const custom: Messages = {
+  ...t,
+  slash: { ...t.slash, groups: { ...t.slash.groups, insert: "Thêm vào" } },
+};
+```
+
+Kiểu `Messages` suy ra từ bản tiếng Việt, nên thiếu một khoá ở bản dịch khác là
+lỗi biên dịch chứ không phải chuỗi rỗng lúc chạy.
+
+## Props
+
+| Prop | Kiểu | Mặc định | Ý nghĩa |
+| --- | --- | --- | --- |
+| `content` | `JSONContent \| string` | — | Nội dung khởi tạo. **Không kiểm soát** — xem ghi chú bên dưới. |
+| `onChange` | `(json, editor) => void` | — | Gọi mỗi lần document đổi. |
+| `onReady` | `(editor) => void` | — | Gọi một lần khi editor khởi tạo xong. |
+| `editable` | `boolean` | `true` | `false` để chỉ đọc; đổi được lúc chạy. |
+| `uploadImage` | `(file, onProgress?, signal?) => Promise<string>` | — | Đẩy ảnh lên server, trả URL. |
+| `maxImageSize` | `number` | `1048576` | Giới hạn dung lượng ảnh, tính bằng byte. |
+| `uploadAttachment` | `(file, onProgress?, signal?) => Promise<string \| { src?, fileId? }>` | — | Tải tệp đính kèm lên. Trả `src` nếu storage cấp URL cố định, trả `fileId` nếu storage riêng tư chỉ phát URL ngắn hạn. |
+| `maxAttachmentSize` | `number` | `26214400` | Giới hạn dung lượng tệp đính kèm, tính bằng byte. |
+| `onOpenAttachment` | `(attachment) => void` | — | Mở tệp chỉ có `fileId`. Tệp có `src` dùng thẻ `<a>` thật nên không gọi tới. |
+| `mentionSource` | `(query) => MentionItem[] \| Promise<MentionItem[]>` | — | Không truyền thì tắt hẳn `@mention`. |
+| `locale` | `"vi" \| "en"` | `"vi"` | Ngôn ngữ của nhãn trong editor. |
+| `placeholder` | `string \| (({ editor, node }) => string)` | — | Chữ mờ cho document rỗng. Heading rỗng luôn hiện `Heading N`; node rỗng khác không hiện gì. Truyền hàm để tự quyết hoàn toàn. |
+| `showToc` | `boolean` | `true` | Thanh mục lục ở lề phải. |
+| `tocVariant` | `"content" \| "line"` | `"line"` | Kiểu hiển thị mục lục. |
+| `onReplaceImage` | `() => void` | — | Xử lý nút "Replace" trên bubble menu của ảnh. |
+| `extensions` | `AnyExtension[]` | `[]` | Extension Tiptap bổ sung. |
+| `className` / `editorClassName` | `string` | — | Class cho khung ngoài / vùng soạn thảo. |
+| `ref` | `Ref<NotionEditorHandle>` | — | Truy cập `editor`, `getJSON`, `getHTML`, `setContent`, `focus`. |
+
+### Tệp đính kèm
+
+Package không biết gì về storage. Nó gọi `uploadAttachment`, lưu lại thứ hàm đó
+trả về, và khi người dùng bấm tải thì hoặc dùng `src` trực tiếp, hoặc gọi
+`onOpenAttachment` để app chủ tự lấy nội dung.
+
+```tsx
+<NotionEditor
+  uploadAttachment={async (file) => {
+    const { fileId } = await uploadToPrivateStorage(file);
+    // Storage riêng tư chỉ phát URL ngắn hạn, nhúng vào nội dung là bảo đảm
+    // nó hỏng sau vài phút — nên lưu id và đổi lấy URL lúc cần.
+    return { fileId };
+  }}
+  onOpenAttachment={async ({ fileId, name }) => {
+    const blob = await fetchFromPrivateStorage(fileId);
+    saveAs(blob, name);
+  }}
+/>
+```
+
+`collectFileUrls(doc)` trả về mọi URL tệp mà một document đang tham chiếu, đã
+loại ảnh base64 — dùng khi app chủ cần dọn storage sau khi xoá trang.
+
+### `content` không phải prop kiểm soát
+
+Đổi giá trị `content` sẽ **không** nạp lại document. Muốn chuyển sang document
+khác thì remount bằng `key` như ví dụ trên — cách này rẻ hơn việc so sánh cây
+node, và tránh con trỏ nhảy về đầu bài mỗi khi state cha render lại giữa lúc
+đang gõ. Nếu cần ghi đè có chủ đích thì dùng `ref.current.setContent(...)`.
+
+### Upload ảnh
+
+Không truyền `uploadImage` thì khối upload báo lỗi khi người dùng chọn file, còn
+ảnh kéo-thả rơi về nhúng base64. Base64 làm document phình rất nhanh, nên đừng
+để mặc định này đi vào nội dung lưu xuống backend.
+
+## Phát triển
+
+```bash
+pnpm install
+pnpm build       # -> lib/
+pnpm type-check
+```
+
+### Thử với app chủ trước khi publish
+
+Dùng tarball, **không** dùng `link:` hay `pnpm link`:
+
+```bash
+pnpm build && pnpm pack                                            # trong repo này
+pnpm add file:../notion-editor/aicademy-notion-editor-0.1.0.tgz    # trong app chủ
+```
+
+`link:` trỏ ra ngoài cây `node_modules` của app, nên package vẫn nạp `react` và
+`prosemirror-*` từ `node_modules` của chính nó. Hai bản ProseMirror giữ hai bộ
+đếm `PluginKey` riêng, cùng sinh ra key `plugin$`, và ProseMirror ném
+`RangeError: Adding different instances of a keyed plugin` ngay lúc dựng editor
+view. `resolve.dedupe` của Vite không cứu được, vì Vitest coi package nằm ngoài
+thư mục gốc là external rồi để Node tự resolve.
+
+Cài từ tarball thì pnpm đặt package vào đúng store của app và peer dependency
+resolve về một bản duy nhất — giống hệt lúc cài từ npm.

package/lib/NotionEditor.d.ts

@@ -0,0 +1,58 @@
+import { Editor, JSONContent } from '@tiptap/core';
+import { NotionEditorExtensionOptions } from './components/extensions';
+import { Locale } from './i18n';
+import { AttachmentAttributes } from './components/node/attachment';
+export type NotionEditorHandle = {
+    /** Instance Tiptap, cho các thao tác không nằm trong props. */
+    editor: Editor | null;
+    /** Nội dung hiện tại dưới dạng JSON. */
+    getJSON: () => JSONContent | null;
+    /** Nội dung hiện tại dưới dạng HTML. */
+    getHTML: () => string;
+    /** Ghi đè toàn bộ nội dung mà không phát `onChange`. */
+    setContent: (content: JSONContent | string) => void;
+    focus: () => void;
+};
+export type NotionEditorProps = NotionEditorExtensionOptions & {
+    /**
+     * Nội dung khởi tạo. Đây là prop **không kiểm soát**: thay đổi giá trị sẽ
+     * không nạp lại document. Khi chuyển sang document khác, hãy remount bằng
+     * `key` — cách này rẻ hơn và tránh con trỏ nhảy lung tung khi đang gõ.
+     */
+    content?: JSONContent | string;
+    /** Gọi mỗi lần document đổi. */
+    onChange?: (json: JSONContent, editor: Editor) => void;
+    /** Gọi một lần khi editor sẵn sàng. */
+    onReady?: (editor: Editor) => void;
+    /** false để chuyển sang chế độ chỉ đọc. Đổi lúc chạy được. */
+    editable?: boolean;
+    /** Hiện thanh điều hướng mục lục ở lề phải. */
+    showToc?: boolean;
+    /** Kiểu hiển thị mục lục. */
+    tocVariant?: "content" | "line";
+    /**
+     * Mở một tệp đính kèm không có URL công khai.
+     *
+     * Chỉ cần khi `uploadAttachment` trả về `fileId`: lúc đó chỉ app chủ mới
+     * đổi được id lấy nội dung. Tệp có `src` dùng thẻ <a> thật, không gọi tới.
+     */
+    onOpenAttachment?: (attachment: AttachmentAttributes) => void;
+    /** Xử lý nút "Replace" trên bubble menu của ảnh. */
+    onReplaceImage?: () => void;
+    className?: string;
+    /** Class gắn vào vùng soạn thảo, nối sau bộ class typography mặc định. */
+    editorClassName?: string;
+    /** Ngôn ngữ của nhãn trong editor. Mặc định tiếng Việt. */
+    locale?: Locale;
+    autofocus?: boolean;
+    ref?: React.Ref<NotionEditorHandle>;
+};
+/**
+ * Editor kiểu Notion: slash command, bubble menu, kéo-thả block, bảng, ảnh,
+ * công thức toán và mục lục.
+ *
+ * Component tự bọc `TooltipProvider` và `EditorContext` nên chỗ dùng chỉ cần
+ * render thẻ này. Style phải được import riêng một lần cho cả app:
+ * `import "tiptap-notion-editor/style.css"`.
+ */
+export declare function NotionEditor({ content, onChange, onReady, editable, showToc, tocVariant, onOpenAttachment, onReplaceImage, className, editorClassName, locale, autofocus, ref, ...extensionOptions }: NotionEditorProps): import("react").JSX.Element | null;

package/lib/components/Draggable/index.d.ts

@@ -0,0 +1,5 @@
+import { Editor } from '@tiptap/core';
+declare const Dragable: ({ editor }: {
+    editor: Editor | null;
+}) => import("react").JSX.Element | undefined;
+export default Dragable;

package/lib/components/ToggleButton.d.ts

@@ -0,0 +1,16 @@
+import { LucideIcon } from 'lucide-react';
+import { default as React } from 'react';
+interface ToggleButtonProps {
+    onClick: () => void;
+    isActive?: boolean;
+    icon: LucideIcon | React.JSX.Element;
+    className?: string;
+    text?: string;
+    showTooltip?: boolean;
+    tooltip?: string;
+    disabled?: boolean;
+    size?: "icon" | "default" | "xs" | "sm" | "lg" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
+    [key: string]: any;
+}
+declare const ToggleButton: ({ onClick, isActive, icon, className, text, size, showTooltip, tooltip, disabled, ...props }: ToggleButtonProps) => React.JSX.Element;
+export default ToggleButton;

package/lib/components/TooltipWrapper.d.ts

@@ -0,0 +1,9 @@
+import { default as React } from 'react';
+interface PropsType {
+    children: React.ReactNode;
+    content: string | undefined;
+    showTooltip?: boolean;
+    className?: string;
+}
+declare const TooltipWrapper: ({ children, content, className, showTooltip, }: PropsType) => React.JSX.Element;
+export default TooltipWrapper;

package/lib/components/blocks/attachment.d.ts

@@ -0,0 +1,2 @@
+import { BlockItem } from './types';
+export declare const attachment: BlockItem;

package/lib/components/blocks/code.d.ts

@@ -0,0 +1,2 @@
+import { BlockItem } from './types';
+export declare const htmlCodeBlock: BlockItem;

package/lib/components/blocks/emoji.d.ts

@@ -0,0 +1,2 @@
+import { BlockItem } from './types';
+export declare const emoji: BlockItem;

package/lib/components/blocks/image.d.ts

@@ -0,0 +1,2 @@
+import { BlockItem } from './types';
+export declare const uploadImage: BlockItem;

package/lib/components/blocks/list.d.ts

@@ -0,0 +1,4 @@
+import { BlockItem } from './types';
+export declare const bulletList: BlockItem;
+export declare const orderedList: BlockItem;
+export declare const taskList: BlockItem;

package/lib/components/blocks/separator.d.ts

@@ -0,0 +1,2 @@
+import { BlockItem } from './types';
+export declare const separator: BlockItem;

package/lib/components/blocks/table.d.ts

@@ -0,0 +1,2 @@
+import { BlockItem } from './types';
+export declare const table: BlockItem;

package/lib/components/blocks/tableOfContents.d.ts

@@ -0,0 +1,2 @@
+import { BlockItem } from './types';
+export declare const tableOfContents: BlockItem;

package/lib/components/blocks/types.d.ts

@@ -0,0 +1,26 @@
+import { Range, Editor } from '@tiptap/core';
+import { JSX } from 'react/jsx-runtime';
+export interface CommandProps {
+    editor: Editor;
+    range: Range;
+}
+export type BlockItem = {
+    title: string;
+    description?: string;
+    searchTerms: string[];
+    icon?: JSX.Element;
+    render?: (editor: Editor) => JSX.Element | null | true;
+    preview?: string | ((editor: Editor) => JSX.Element | null);
+} & ({
+    command: (options: CommandProps) => void;
+    id?: never;
+    commands?: never;
+} | {
+    id: string;
+    command?: never;
+    commands?: BlockItem[];
+});
+export type BlockGroupItem = {
+    title: string;
+    commands: BlockItem[];
+};

package/lib/components/blocks/typography.d.ts

@@ -0,0 +1,8 @@
+import { BlockItem } from './types';
+export declare const text: BlockItem;
+export declare const heading1: BlockItem;
+export declare const heading2: BlockItem;
+export declare const heading3: BlockItem;
+export declare const hardBreak: BlockItem;
+export declare const blockquote: BlockItem;
+export declare const clearLine: BlockItem;

package/lib/components/bubble/BubbleMoreOption.d.ts

@@ -0,0 +1,5 @@
+import { Editor } from '@tiptap/core';
+declare const BubbleMoreOption: ({ editor }: {
+    editor: Editor;
+}) => import("react").JSX.Element;
+export default BubbleMoreOption;

package/lib/components/bubble/ImageBubbleMenu.d.ts

@@ -0,0 +1,7 @@
+import { Editor } from '@tiptap/core';
+interface ImageBubbleMenuProps {
+    editor: Editor | null;
+    onReplaceClick: () => void;
+}
+declare const ImageBubbleMenu: ({ editor, onReplaceClick }: ImageBubbleMenuProps) => import("react").JSX.Element | undefined;
+export default ImageBubbleMenu;

package/lib/components/bubble/IndentButtons.d.ts

@@ -0,0 +1,5 @@
+import { Editor } from '@tiptap/react';
+declare const IndentButtons: ({ editor }: {
+    editor: Editor;
+}) => import("react").JSX.Element;
+export default IndentButtons;

package/lib/components/bubble/MyBubbleMenu.d.ts

@@ -0,0 +1,5 @@
+import { Editor } from '@tiptap/core';
+declare const MyBubbleMenu: ({ editor }: {
+    editor: Editor | null;
+}) => import("react").JSX.Element | undefined;
+export default MyBubbleMenu;

package/lib/components/bubble/PickLink.d.ts

@@ -0,0 +1,6 @@
+import { default as React } from 'react';
+import { Editor } from '@tiptap/core';
+declare const PickLink: ({ editor }: {
+    editor: Editor;
+}) => React.JSX.Element;
+export default PickLink;

package/lib/components/bubble/TextTurnInto.d.ts

@@ -0,0 +1,5 @@
+import { Editor } from '@tiptap/core';
+declare const TextTurnInto: ({ editor }: {
+    editor: Editor;
+}) => import("react").JSX.Element;
+export default TextTurnInto;

package/lib/components/bubble/icon.d.ts

@@ -0,0 +1,4 @@
+export declare const AlignLeft: (props: any) => import("react").JSX.Element;
+export declare const AlignRight: (props: any) => import("react").JSX.Element;
+export declare const AlignCenter: (props: any) => import("react").JSX.Element;
+export declare const CaptionIcon: (props: any) => import("react").JSX.Element;

package/lib/components/color/ColorDropdown.d.ts

@@ -0,0 +1,5 @@
+import { Editor } from '@tiptap/core';
+declare const ColorDropdown: ({ editor }: {
+    editor: Editor;
+}) => import("react").JSX.Element;
+export default ColorDropdown;

package/lib/components/color/ColorItem.d.ts

@@ -0,0 +1,5 @@
+import { Color } from './type';
+export declare const ColorItem: ({ color, onClick, }: {
+    color: Color;
+    onClick: () => void;
+}) => import("react").JSX.Element;

package/lib/components/color/ColorSubMenu.d.ts

@@ -0,0 +1,7 @@
+import { Color } from './type';
+import { Editor } from '@tiptap/core';
+declare const Colors: ({ editor, setColor, }: {
+    editor: Editor | null;
+    setColor: (color: Color) => void;
+}) => import("react").JSX.Element;
+export default Colors;

package/lib/components/color/HighlightButton.d.ts

@@ -0,0 +1,15 @@
+import { Editor } from '@tiptap/react';
+type Color = {
+    name: string;
+    value: string;
+    type: string;
+};
+interface HighlightButtonProps {
+    tooltip: string;
+    color: Color;
+    onClick: () => void;
+    isActive?: boolean;
+    editor: Editor;
+}
+declare const HighlightButton: ({ tooltip, color, onClick, editor, }: HighlightButtonProps) => import("react").JSX.Element;
+export default HighlightButton;

package/lib/components/color/TextButton.d.ts

@@ -0,0 +1,9 @@
+import { Editor } from '@tiptap/core';
+interface TextButtonProps {
+    tooltip: string;
+    color: string;
+    onClick: () => void;
+    editor: Editor;
+}
+declare const TextButton: ({ tooltip, color, onClick, editor }: TextButtonProps) => import("react").JSX.Element;
+export default TextButton;

package/lib/components/color/constant.d.ts

@@ -0,0 +1,12 @@
+import { Color, GroupColors } from './type';
+import { Messages } from '../../i18n';
+export declare const RECENT_COLORS_KEY = "recentlyUsedColors";
+export declare const MAX_RECENT = 3;
+export declare const colors: Color[];
+/**
+ * Nhóm màu, dựng theo ngôn ngữ đang dùng.
+ *
+ * Là hàm chứ không phải hằng vì nhãn phải dịch được, mà module cấp cao nhất
+ * thì không gọi hook được.
+ */
+export declare const createGroupColors: (t: Messages) => GroupColors[];

package/lib/components/color/icon.d.ts

@@ -0,0 +1,2 @@
+export declare const TextIcon: (props: any) => import("react").JSX.Element;
+export declare const AlignmentIcon: (props: any) => import("react").JSX.Element;

package/lib/components/color/type.d.ts

@@ -0,0 +1,9 @@
+export type Color = {
+    name: string;
+    value: string;
+    type: string;
+};
+export type GroupColors = {
+    title: string;
+    colors: Color[];
+};

package/lib/components/color/utils.d.ts

@@ -0,0 +1,5 @@
+import { Dispatch, SetStateAction } from 'react';
+import { Messages } from '../../i18n';
+import { Color, GroupColors } from './type';
+export declare const getRecentColors: () => Color[];
+export declare const handleAddRecentUsed: (color: Color, setItems: Dispatch<SetStateAction<GroupColors[]>>, t: Messages) => void;

package/lib/components/extensions/Indent.d.ts

@@ -0,0 +1,16 @@
+import { Extension } from '@tiptap/core';
+export interface IndentOptions {
+    types: string[];
+    minLevel: number;
+    maxLevel: number;
+    indentSize: number;
+}
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        indent: {
+            indent: () => ReturnType;
+            outdent: () => ReturnType;
+        };
+    }
+}
+export declare const Indent: Extension<any, any>;

package/lib/components/extensions/emoji-picker/EmojiList.d.ts

@@ -0,0 +1,8 @@
+import { EmojiItem } from '@tiptap/extension-emoji';
+interface EmojiListProps {
+    items: EmojiItem[];
+    selectedIndex: number;
+    onSelectIndex: (index: number) => void;
+}
+declare const EmojiList: ({ items, onSelectIndex }: EmojiListProps) => import("react").JSX.Element;
+export default EmojiList;

package/lib/components/extensions/emoji-picker/EmojiPicker.d.ts

@@ -0,0 +1,14 @@
+import { EmojiItem } from '@tiptap/extension-emoji';
+import { Editor } from '@tiptap/core';
+type CommandProps = {
+    name: string;
+};
+type EmojiListProps = {
+    items: EmojiItem[];
+    editor: Editor;
+    command: (arg0: CommandProps) => void;
+    range: Range;
+    query: string;
+};
+declare const EmojiPicker: import('react').ForwardRefExoticComponent<EmojiListProps & import('react').RefAttributes<unknown>>;
+export default EmojiPicker;

package/lib/components/extensions/emoji-picker/emoji-suggestion.d.ts

@@ -0,0 +1,3 @@
+import { SuggestionOptions } from '@tiptap/suggestion';
+declare const _default: Omit<SuggestionOptions, "editor">;
+export default _default;

package/lib/components/extensions/file-handle.d.ts

@@ -0,0 +1,19 @@
+import { UploadFunction } from '../node/image-upload/image-upload-node-extension';
+import { AttachmentUploadFunction } from '../node/attachment';
+type Handlers = {
+    /** Ảnh: chèn thành node `image` để xem trực tiếp. */
+    uploadImage?: UploadFunction;
+    /** Tệp khác: chèn thành node `attachment` để tải về. */
+    uploadAttachment?: AttachmentUploadFunction;
+};
+/**
+ * Xử lý tệp được kéo-thả hoặc dán vào editor.
+ *
+ * Không giới hạn `allowedMimeTypes` nữa: bản trước chỉ nhận bốn định dạng ảnh,
+ * nên kéo một file Word vào editor thì trình duyệt mở file đó thay vì chèn.
+ *
+ * Ảnh và tệp thường đi hai đường khác nhau vì hiển thị khác nhau, nhưng cả hai
+ * đều chỉ nhận URL do app chủ trả về.
+ */
+export declare function createFileHandler({ uploadImage, uploadAttachment }: Handlers): import('@tiptap/core').Extension<Omit<import('@tiptap/extension-file-handler').FileHandlePluginOptions, "editor" | "key">, any>;
+export {};

package/lib/components/extensions/global-block-background.d.ts

@@ -0,0 +1,2 @@
+import { Extension } from '@tiptap/core';
+export declare const GlobalBlockBackground: Extension<any, any>;

package/lib/components/extensions/index.d.ts

@@ -0,0 +1,51 @@
+import { AnyExtension, Editor } from '@tiptap/core';
+import { Node as ProseMirrorNode } from '@tiptap/pm/model';
+import { BlockGroupItem } from '../blocks/types';
+import { Locale } from '../../i18n';
+import { AttachmentUploadFunction } from '../node/attachment';
+import { UploadFunction } from '../node/image-upload/image-upload-node-extension';
+import { MentionSource } from './mention/types';
+export type NotionEditorExtensionOptions = {
+    /** Extension bổ sung của app chủ, nối vào sau bộ mặc định. */
+    extensions?: AnyExtension[];
+    /** Nhóm block hiển thị trong slash menu. */
+    blocks?: BlockGroupItem[];
+    /**
+     * Chữ mờ cho document rỗng. Heading rỗng luôn hiện `Heading N`, còn các
+     * node rỗng khác không hiện gì.
+     *
+     * Truyền hàm để tự quyết định hoàn toàn — khi đó quy tắc trên bị bỏ qua.
+     */
+    placeholder?: string | ((props: {
+        editor: Editor;
+        node: ProseMirrorNode;
+    }) => string);
+    /**
+     * Hàm đẩy ảnh lên server, trả về URL công khai. Không truyền thì khối
+     * upload ảnh sẽ báo lỗi khi người dùng chọn file, còn kéo-thả rơi về base64.
+     */
+    uploadImage?: UploadFunction;
+    /**
+     * Hàm đưa tệp (Word, PDF, bảng tính…) lên và trả về URL công khai.
+     *
+     * Package chỉ nhận URL — nó không biết gì về R2 hay bất kỳ storage nào.
+     * Không truyền thì khối đính kèm báo lỗi khi người dùng chọn tệp.
+     */
+    uploadAttachment?: AttachmentUploadFunction;
+    /** Dung lượng tối đa cho tệp đính kèm, tính bằng byte. */
+    maxAttachmentSize?: number;
+    /** Kích thước file tối đa cho khối upload ảnh, tính bằng byte. */
+    maxImageSize?: number;
+    /** Nguồn dữ liệu cho `@mention`. Bỏ trống thì tắt hẳn tính năng mention. */
+    mentionSource?: MentionSource;
+    /** Ngôn ngữ của nhãn trong editor. Mặc định tiếng Việt. */
+    locale?: Locale;
+};
+/**
+ * Dựng bộ extension của editor.
+ *
+ * Mọi thứ phụ thuộc môi trường (upload ảnh, danh bạ mention, placeholder) đều
+ * đi vào qua tham số, nên bản thân package không giữ tham chiếu nào tới app
+ * chủ.
+ */
+export declare function extensions(options?: NotionEditorExtensionOptions): AnyExtension[];

package/lib/components/extensions/mention/MentionList.d.ts

@@ -0,0 +1,11 @@
+import { default as React } from 'react';
+import { SuggestionProps } from '@tiptap/suggestion';
+import { MentionItem } from './types';
+export interface DropdownMenuRef {
+    onKeyDown: (params: {
+        event: KeyboardEvent | React.KeyboardEvent;
+    }) => boolean;
+}
+type MentionListProps = SuggestionProps<MentionItem>;
+declare const MentionList: React.ForwardRefExoticComponent<MentionListProps & React.RefAttributes<DropdownMenuRef>>;
+export default MentionList;

package/lib/components/extensions/mention/mentionSuggestion.d.ts

@@ -0,0 +1,11 @@
+import { SuggestionOptions } from '@tiptap/suggestion';
+import { MentionItem, MentionSource } from './types';
+/**
+ * Dựng cấu hình suggestion cho `@mention` quanh một nguồn dữ liệu do app chủ
+ * cung cấp.
+ *
+ * Bản template gốc hardcode danh sách diễn viên thập niên 80 ngay trong file
+ * này. Tách thành factory để cùng một editor phục vụ được nhiều ngữ cảnh
+ * (nhân sự, tài liệu, khách hàng…) mà không phải fork extension.
+ */
+export declare function createMentionSuggestion(source: MentionSource): Omit<SuggestionOptions<MentionItem>, "editor">;