@comitor/ui 3.4.0 → 3.6.0

package/dist/editor/rich-text-editor.d.ts

@@ -0,0 +1,48 @@
+import * as React from 'react';
+import { g as EditorBaseProps, a as EditorToolbarMode, E as EditorHandleBase } from '../editor-types-BMST7-VR.js';
+import '@tiptap/core';
+import './markdown-editor-constants.js';
+
+/**
+ * RichTextEditor — trình soạn văn bản giàu định dạng LƯU bằng HTML, cho nội dung xuất bản (CMS):
+ * bài viết, trang tin, mô tả sản phẩm, mẫu email — nơi nội dung được hiển thị lại ngoài trình soạn và
+ * người soạn chờ đợi một thanh công cụ.
+ *
+ * Cùng lõi với `MarkdownEditor` (`editor-core.tsx`): menu `/`, nhắc tên `@`, ảnh, liên kết, phím tắt và
+ * cú pháp gõ tắt (`## `, `- `…) y hệt. Khác ở ba chỗ:
+ *   · giá trị là CHUỖI HTML (`editor.getHTML()`), tài liệu rỗng là `""`;
+ *   · lược đồ RỘNG hơn — gạch chân, ô bảng chứa nhiều khối (danh sách, ảnh, nhiều đoạn): HTML giữ được
+ *     cả hai, markdown thì không (lý do ở `createSchemaExtensions`);
+ *   · thanh công cụ mặc định là `fixed` — thanh dính đầu khung, kiểu CMS.
+ *
+ * ⚠ HTML ĐI VÀO đi qua lược đồ, và lược đồ là một danh sách cho phép: thẻ và thuộc tính nó không biết
+ * (`<script>`, `style`, `onerror`, `<iframe>`) rơi mất khi nạp. Nhưng HTML ĐÃ LƯU là dữ liệu người dùng
+ * — ai gọi thẳng API của app thì ghi được bất cứ chuỗi nào. Hiển thị lại bằng
+ * `<RichTextEditor editable={false} value={html} />` (đi qua cùng lược đồ), đừng `dangerouslySetInnerHTML`
+ * khi chưa có bộ lọc phía máy chủ. Chi tiết ở docs/editor.md.
+ */
+
+/** Điều khiển trình soạn từ ngoài — lấy qua prop `ref`. */
+interface RichTextEditorHandle extends EditorHandleBase {
+    /** HTML hiện tại — cùng chuỗi mà `onChange` nhận (`""` khi rỗng). */
+    getHTML: () => string;
+    /** Thay toàn bộ nội dung bằng HTML (đi qua lược đồ — xem đầu file). Có gọi `onChange`. */
+    setHTML: (html: string) => void;
+}
+interface RichTextEditorProps extends EditorBaseProps {
+    /** HTML — điều khiển từ ngoài. Đổi giá trị KHÁC thứ trình soạn vừa phát là nạp lại nội dung. */
+    value?: string;
+    /** HTML ban đầu khi KHÔNG điều khiển. */
+    defaultValue?: string;
+    /** Mỗi lần nội dung đổi, nhận HTML của tài liệu — `""` khi tài liệu rỗng. */
+    onChange?: (html: string) => void;
+    /**
+     * `fixed` (mặc định) — thanh dính đầu khung, mọi thao tác luôn thấy. `bubble` — kiểu Linear, định
+     * dạng hiện ở chỗ bôi chọn. Xem `EditorToolbarMode`.
+     */
+    toolbar?: EditorToolbarMode;
+    ref?: React.Ref<RichTextEditorHandle>;
+}
+declare function RichTextEditor({ toolbar, ref, ...props }: RichTextEditorProps): React.JSX.Element;
+
+export { RichTextEditor, type RichTextEditorHandle, type RichTextEditorProps };

package/dist/editor/rich-text-editor.js

@@ -0,0 +1,33 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { EditorCore } from "./editor-core.js";
+function createRichTextHandle(core) {
+  return {
+    focus: core.focus,
+    getHTML: core.getValue,
+    setHTML: core.setValue,
+    clear: core.clear,
+    isEmpty: core.isEmpty,
+    isUploading: core.isUploading,
+    get editor() {
+      return core.editor;
+    }
+  };
+}
+function RichTextEditor({ toolbar = "fixed", ref, ...props }) {
+  return /* @__PURE__ */ jsx(
+    EditorCore,
+    {
+      ...props,
+      format: "html",
+      toolbar,
+      slot: "rich-text-editor",
+      handleRef: ref,
+      createHandle: createRichTextHandle
+    }
+  );
+}
+export {
+  RichTextEditor
+};
+//# sourceMappingURL=rich-text-editor.js.map

package/dist/editor/rich-text-editor.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/editor/rich-text-editor.tsx"],"sourcesContent":["\"use client\";\n\n/**\n * RichTextEditor — trình soạn văn bản giàu định dạng LƯU bằng HTML, cho nội dung xuất bản (CMS):\n * bài viết, trang tin, mô tả sản phẩm, mẫu email — nơi nội dung được hiển thị lại ngoài trình soạn và\n * người soạn chờ đợi một thanh công cụ.\n *\n * Cùng lõi với `MarkdownEditor` (`editor-core.tsx`): menu `/`, nhắc tên `@`, ảnh, liên kết, phím tắt và\n * cú pháp gõ tắt (`## `, `- `…) y hệt. Khác ở ba chỗ:\n *   · giá trị là CHUỖI HTML (`editor.getHTML()`), tài liệu rỗng là `\"\"`;\n *   · lược đồ RỘNG hơn — gạch chân, ô bảng chứa nhiều khối (danh sách, ảnh, nhiều đoạn): HTML giữ được\n *     cả hai, markdown thì không (lý do ở `createSchemaExtensions`);\n *   · thanh công cụ mặc định là `fixed` — thanh dính đầu khung, kiểu CMS.\n *\n * ⚠ HTML ĐI VÀO đi qua lược đồ, và lược đồ là một danh sách cho phép: thẻ và thuộc tính nó không biết\n * (`<script>`, `style`, `onerror`, `<iframe>`) rơi mất khi nạp. Nhưng HTML ĐÃ LƯU là dữ liệu người dùng\n * — ai gọi thẳng API của app thì ghi được bất cứ chuỗi nào. Hiển thị lại bằng\n * `<RichTextEditor editable={false} value={html} />` (đi qua cùng lược đồ), đừng `dangerouslySetInnerHTML`\n * khi chưa có bộ lọc phía máy chủ. Chi tiết ở docs/editor.md.\n */\n\nimport type * as React from \"react\";\nimport { EditorCore, type EditorCoreHandle } from \"./editor-core.js\";\nimport type { EditorBaseProps, EditorHandleBase, EditorToolbarMode } from \"./editor-types.js\";\n\n/** Điều khiển trình soạn từ ngoài — lấy qua prop `ref`. */\nexport interface RichTextEditorHandle extends EditorHandleBase {\n  /** HTML hiện tại — cùng chuỗi mà `onChange` nhận (`\"\"` khi rỗng). */\n  getHTML: () => string;\n  /** Thay toàn bộ nội dung bằng HTML (đi qua lược đồ — xem đầu file). Có gọi `onChange`. */\n  setHTML: (html: string) => void;\n}\n\nexport interface RichTextEditorProps extends EditorBaseProps {\n  /** HTML — điều khiển từ ngoài. Đổi giá trị KHÁC thứ trình soạn vừa phát là nạp lại nội dung. */\n  value?: string;\n  /** HTML ban đầu khi KHÔNG điều khiển. */\n  defaultValue?: string;\n  /** Mỗi lần nội dung đổi, nhận HTML của tài liệu — `\"\"` khi tài liệu rỗng. */\n  onChange?: (html: string) => void;\n  /**\n   * `fixed` (mặc định) — thanh dính đầu khung, mọi thao tác luôn thấy. `bubble` — kiểu Linear, định\n   * dạng hiện ở chỗ bôi chọn. Xem `EditorToolbarMode`.\n   */\n  toolbar?: EditorToolbarMode;\n  ref?: React.Ref<RichTextEditorHandle>;\n}\n\nfunction createRichTextHandle(core: EditorCoreHandle): RichTextEditorHandle {\n  return {\n    focus: core.focus,\n    getHTML: core.getValue,\n    setHTML: core.setValue,\n    clear: core.clear,\n    isEmpty: core.isEmpty,\n    isUploading: core.isUploading,\n    get editor() {\n      return core.editor;\n    }\n  };\n}\n\nexport function RichTextEditor({ toolbar = \"fixed\", ref, ...props }: RichTextEditorProps) {\n  return (\n    <EditorCore\n      {...props}\n      format=\"html\"\n      toolbar={toolbar}\n      slot=\"rich-text-editor\"\n      handleRef={ref}\n      createHandle={createRichTextHandle}\n    />\n  );\n}\n"],"mappings":";AAgEI;AA1CJ,SAAS,kBAAyC;AA0BlD,SAAS,qBAAqB,MAA8C;AAC1E,SAAO;AAAA,IACL,OAAO,KAAK;AAAA,IACZ,SAAS,KAAK;AAAA,IACd,SAAS,KAAK;AAAA,IACd,OAAO,KAAK;AAAA,IACZ,SAAS,KAAK;AAAA,IACd,aAAa,KAAK;AAAA,IAClB,IAAI,SAAS;AACX,aAAO,KAAK;AAAA,IACd;AAAA,EACF;AACF;AAEO,SAAS,eAAe,EAAE,UAAU,SAAS,KAAK,GAAG,MAAM,GAAwB;AACxF,SACE;AAAA,IAAC;AAAA;AAAA,MACE,GAAG;AAAA,MACJ,QAAO;AAAA,MACP;AAAA,MACA,MAAK;AAAA,MACL,WAAW;AAAA,MACX,cAAc;AAAA;AAAA,EAChB;AAEJ;","names":[]}

package/dist/editor/slash-commands.d.ts

@@ -0,0 +1,65 @@
+import { Editor, Range, Extension } from '@tiptap/core';
+import { PluginKey } from '@tiptap/pm/state';
+import { SuggestionOptions } from '@tiptap/suggestion';
+import { LucideIcon } from 'lucide-react';
+import { f as EditorFormat } from '../editor-types-BMST7-VR.js';
+import { MarkdownEditorBlockId, MarkdownEditorLabels } from './markdown-editor-constants.js';
+
+/**
+ * Menu `/` — danh sách khối chèn được, và extension Tiptap mở nó.
+ *
+ * Không `"use client"`: bảng dưới đây là dữ liệu (icon là component, `run` là hàm) — file thuần.
+ * Chữ hiển thị KHÔNG nằm ở đây: tên khối và từ đồng nghĩa đi qua namespace `markdownEditor`; ở đây
+ * chỉ có bí danh MÁY tiếng Anh (`h1`, `ul`, `todo`…), thứ người dùng gõ như nhau ở mọi ngôn ngữ.
+ */
+
+/** Thứ menu cần mà chỉ component biết — vd mở hộp chọn tệp. */
+interface SlashCommandContext {
+    /** Định dạng lưu — quyết định khối nào chèn được vào ô bảng. Mặc định `markdown`. */
+    format?: EditorFormat;
+    /** Có = app đã truyền `onImageUpload`, khối "Ảnh" hiện ra. */
+    pickImage?: () => void;
+}
+interface SlashCommand {
+    id: MarkdownEditorBlockId;
+    icon: LucideIcon;
+    /**
+     * Cú pháp gõ tắt, hiện mờ bên phải mục — kiểu Linear. Menu `/` vì vậy cũng là chỗ DẠY cú pháp:
+     * lần sau người dùng gõ thẳng `## ` mà không cần mở menu.
+     */
+    hint?: string;
+    /** Bí danh máy, cách nhau bằng dấu cách — luôn tìm được, ở mọi ngôn ngữ. */
+    aliases: string;
+    /** Mục có hiện ở vị trí con trỏ này không. Bỏ trống = hiện ở mọi chỗ chèn được KHỐI (`blockAllowed`). */
+    when?: (editor: Editor, context: SlashCommandContext) => boolean;
+    run: (editor: Editor, range: Range, context: SlashCommandContext) => void;
+}
+/** Mục hiện trong menu: lệnh + chữ đã dịch, ngữ cảnh đã buộc sẵn. */
+interface SlashMenuItem {
+    id: MarkdownEditorBlockId;
+    icon: LucideIcon;
+    hint?: string;
+    label: string;
+    execute: (editor: Editor, range: Range) => void;
+}
+declare const SLASH_COMMANDS: readonly SlashCommand[];
+/**
+ * Các mục hiện được ở vị trí con trỏ, khớp với chữ đã gõ.
+ *
+ * Khớp = MỌI từ của chữ gõ nằm trong (tên đã dịch + từ đồng nghĩa đã dịch + bí danh máy) — không
+ * dấu, không phân biệt hoa thường, đúng luật `matchesSearch` của `Combobox`: "/tieu" ra "Tiêu đề",
+ * "/h2" ra "Tiêu đề 2" ở mọi ngôn ngữ.
+ */
+declare function filterSlashCommands(editor: Editor, query: string, labels: MarkdownEditorLabels, context: SlashCommandContext): SlashMenuItem[];
+declare const SLASH_PLUGIN_KEY: PluginKey<any>;
+/**
+ * Extension mở menu `/`. Phần GIAO DIỆN (danh sách, bàn phím) đến qua `render` — xem
+ * `SuggestionStore`.
+ *
+ * `/` chỉ kích hoạt ở đầu dòng hoặc sau dấu cách (`allowedPrefixes` mặc định của Tiptap), nên gõ
+ * đường dẫn `a/b` hay ngày `02/10` không bật menu. Không bật trong khối mã và mã nội dòng: ở đó `/`
+ * là chữ của mã.
+ */
+declare function createSlashCommandExtension(options: Pick<SuggestionOptions<SlashMenuItem, SlashMenuItem>, "items" | "render">): Extension;
+
+export { SLASH_COMMANDS, SLASH_PLUGIN_KEY, type SlashCommand, type SlashCommandContext, type SlashMenuItem, createSlashCommandExtension, filterSlashCommands };

package/dist/editor/slash-commands.js

@@ -0,0 +1,191 @@
+import { Extension } from "@tiptap/core";
+import { PluginKey } from "@tiptap/pm/state";
+import { Suggestion } from "@tiptap/suggestion";
+import {
+  BetweenHorizontalEnd,
+  BetweenVerticalEnd,
+  Columns3,
+  Heading1,
+  Heading2,
+  Heading3,
+  ImagePlus,
+  List,
+  ListChecks,
+  ListOrdered,
+  Minus,
+  Pilcrow,
+  Rows3,
+  SquareCode,
+  Table,
+  TextQuote,
+  Trash2
+} from "lucide-react";
+import { matchesSearch } from "../lib/text-search.js";
+const inTable = (editor) => editor.isActive("table");
+const blockAllowed = (editor, context) => context.format === "html" || !inTable(editor);
+const SLASH_COMMANDS = [
+  {
+    id: "text",
+    icon: Pilcrow,
+    aliases: "p text paragraph",
+    run: (editor, range) => editor.chain().focus().deleteRange(range).setParagraph().run()
+  },
+  {
+    id: "heading1",
+    icon: Heading1,
+    hint: "#",
+    aliases: "h1 heading",
+    run: (editor, range) => editor.chain().focus().deleteRange(range).setHeading({ level: 1 }).run()
+  },
+  {
+    id: "heading2",
+    icon: Heading2,
+    hint: "##",
+    aliases: "h2 heading",
+    run: (editor, range) => editor.chain().focus().deleteRange(range).setHeading({ level: 2 }).run()
+  },
+  {
+    id: "heading3",
+    icon: Heading3,
+    hint: "###",
+    aliases: "h3 heading",
+    run: (editor, range) => editor.chain().focus().deleteRange(range).setHeading({ level: 3 }).run()
+  },
+  {
+    id: "bulletList",
+    icon: List,
+    hint: "-",
+    aliases: "ul bullet list",
+    run: (editor, range) => editor.chain().focus().deleteRange(range).toggleBulletList().run()
+  },
+  {
+    id: "orderedList",
+    icon: ListOrdered,
+    hint: "1.",
+    aliases: "ol ordered number list",
+    run: (editor, range) => editor.chain().focus().deleteRange(range).toggleOrderedList().run()
+  },
+  {
+    id: "taskList",
+    icon: ListChecks,
+    hint: "[]",
+    aliases: "todo task checklist checkbox",
+    run: (editor, range) => editor.chain().focus().deleteRange(range).toggleTaskList().run()
+  },
+  {
+    id: "blockquote",
+    icon: TextQuote,
+    hint: ">",
+    aliases: "quote blockquote",
+    run: (editor, range) => editor.chain().focus().deleteRange(range).toggleBlockquote().run()
+  },
+  {
+    id: "codeBlock",
+    icon: SquareCode,
+    hint: "```",
+    aliases: "code pre codeblock",
+    run: (editor, range) => editor.chain().focus().deleteRange(range).setCodeBlock().run()
+  },
+  {
+    id: "table",
+    icon: Table,
+    aliases: "table spreadsheet",
+    // Không lồng bảng trong bảng — GFM không có, và hiếm khi là điều người soạn muốn.
+    when: (editor) => !inTable(editor),
+    run: (editor, range) => editor.chain().focus().deleteRange(range).insertTable({ rows: 3, cols: 3, withHeaderRow: true }).run()
+  },
+  {
+    id: "divider",
+    icon: Minus,
+    hint: "---",
+    aliases: "hr divider rule separator",
+    run: (editor, range) => editor.chain().focus().deleteRange(range).setHorizontalRule().run()
+  },
+  {
+    id: "image",
+    icon: ImagePlus,
+    aliases: "img image picture upload",
+    when: (editor, context) => blockAllowed(editor, context) && Boolean(context.pickImage),
+    run: (editor, range, context) => {
+      editor.chain().focus().deleteRange(range).run();
+      context.pickImage?.();
+    }
+  },
+  {
+    id: "tableAddRow",
+    icon: BetweenHorizontalEnd,
+    aliases: "row add insert",
+    when: inTable,
+    run: (editor, range) => editor.chain().focus().deleteRange(range).addRowAfter().run()
+  },
+  {
+    id: "tableAddColumn",
+    icon: BetweenVerticalEnd,
+    aliases: "column col add insert",
+    when: inTable,
+    run: (editor, range) => editor.chain().focus().deleteRange(range).addColumnAfter().run()
+  },
+  {
+    id: "tableDeleteRow",
+    icon: Rows3,
+    aliases: "row delete remove",
+    when: inTable,
+    run: (editor, range) => editor.chain().focus().deleteRange(range).deleteRow().run()
+  },
+  {
+    id: "tableDeleteColumn",
+    icon: Columns3,
+    aliases: "column col delete remove",
+    when: inTable,
+    run: (editor, range) => editor.chain().focus().deleteRange(range).deleteColumn().run()
+  },
+  {
+    id: "tableDelete",
+    icon: Trash2,
+    aliases: "table delete remove",
+    when: inTable,
+    run: (editor, range) => editor.chain().focus().deleteRange(range).deleteTable().run()
+  }
+];
+function filterSlashCommands(editor, query, labels, context) {
+  const words = query.trim().split(/\s+/).filter(Boolean);
+  return SLASH_COMMANDS.filter(
+    (command) => command.when ? command.when(editor, context) : blockAllowed(editor, context)
+  ).filter((command) => {
+    const haystack = `${labels[command.id]} ${labels.slashKeywords[command.id]} ${command.aliases}`;
+    return words.every((word) => matchesSearch(haystack, word));
+  }).map((command) => ({
+    id: command.id,
+    icon: command.icon,
+    hint: command.hint,
+    label: labels[command.id],
+    execute: (target, range) => command.run(target, range, context)
+  }));
+}
+const SLASH_PLUGIN_KEY = new PluginKey("comitorSlashMenu");
+function createSlashCommandExtension(options) {
+  return Extension.create({
+    name: "comitorSlashMenu",
+    addProseMirrorPlugins() {
+      return [
+        Suggestion({
+          editor: this.editor,
+          pluginKey: SLASH_PLUGIN_KEY,
+          char: "/",
+          allowSpaces: false,
+          items: options.items,
+          render: options.render,
+          command: ({ editor, range, props }) => props.execute(editor, range),
+          allow: ({ editor }) => editor.isEditable && !editor.isActive("codeBlock") && !editor.isActive("code")
+        })
+      ];
+    }
+  });
+}
+export {
+  SLASH_COMMANDS,
+  SLASH_PLUGIN_KEY,
+  createSlashCommandExtension,
+  filterSlashCommands
+};
+//# sourceMappingURL=slash-commands.js.map

package/dist/editor/slash-commands.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/editor/slash-commands.ts"],"sourcesContent":["/**\n * Menu `/` — danh sách khối chèn được, và extension Tiptap mở nó.\n *\n * Không `\"use client\"`: bảng dưới đây là dữ liệu (icon là component, `run` là hàm) — file thuần.\n * Chữ hiển thị KHÔNG nằm ở đây: tên khối và từ đồng nghĩa đi qua namespace `markdownEditor`; ở đây\n * chỉ có bí danh MÁY tiếng Anh (`h1`, `ul`, `todo`…), thứ người dùng gõ như nhau ở mọi ngôn ngữ.\n */\n\nimport { type Editor, Extension, type Range } from \"@tiptap/core\";\nimport { PluginKey } from \"@tiptap/pm/state\";\nimport { Suggestion, type SuggestionOptions } from \"@tiptap/suggestion\";\nimport {\n  BetweenHorizontalEnd,\n  BetweenVerticalEnd,\n  Columns3,\n  Heading1,\n  Heading2,\n  Heading3,\n  ImagePlus,\n  List,\n  ListChecks,\n  ListOrdered,\n  type LucideIcon,\n  Minus,\n  Pilcrow,\n  Rows3,\n  SquareCode,\n  Table,\n  TextQuote,\n  Trash2\n} from \"lucide-react\";\nimport { matchesSearch } from \"../lib/text-search.js\";\nimport type { EditorFormat } from \"./editor-types.js\";\nimport type { MarkdownEditorBlockId, MarkdownEditorLabels } from \"./markdown-editor-constants.js\";\n\n/** Thứ menu cần mà chỉ component biết — vd mở hộp chọn tệp. */\nexport interface SlashCommandContext {\n  /** Định dạng lưu — quyết định khối nào chèn được vào ô bảng. Mặc định `markdown`. */\n  format?: EditorFormat;\n  /** Có = app đã truyền `onImageUpload`, khối \"Ảnh\" hiện ra. */\n  pickImage?: () => void;\n}\n\nexport interface SlashCommand {\n  id: MarkdownEditorBlockId;\n  icon: LucideIcon;\n  /**\n   * Cú pháp gõ tắt, hiện mờ bên phải mục — kiểu Linear. Menu `/` vì vậy cũng là chỗ DẠY cú pháp:\n   * lần sau người dùng gõ thẳng `## ` mà không cần mở menu.\n   */\n  hint?: string;\n  /** Bí danh máy, cách nhau bằng dấu cách — luôn tìm được, ở mọi ngôn ngữ. */\n  aliases: string;\n  /** Mục có hiện ở vị trí con trỏ này không. Bỏ trống = hiện ở mọi chỗ chèn được KHỐI (`blockAllowed`). */\n  when?: (editor: Editor, context: SlashCommandContext) => boolean;\n  run: (editor: Editor, range: Range, context: SlashCommandContext) => void;\n}\n\n/** Mục hiện trong menu: lệnh + chữ đã dịch, ngữ cảnh đã buộc sẵn. */\nexport interface SlashMenuItem {\n  id: MarkdownEditorBlockId;\n  icon: LucideIcon;\n  hint?: string;\n  label: string;\n  execute: (editor: Editor, range: Range) => void;\n}\n\nconst inTable = (editor: Editor) => editor.isActive(\"table\");\n\n/**\n * Chỗ con trỏ đứng có nhận một KHỐI không. Ô bảng của trình soạn MARKDOWN chỉ chứa một đoạn văn (xem\n * `ComitorTableCell`), nên ở đó mọi khối có hiện cũng không chèn được; ô bảng HTML thì nhận.\n */\nconst blockAllowed = (editor: Editor, context: SlashCommandContext) => context.format === \"html\" || !inTable(editor);\n\n/*\n * Thứ tự theo tần suất dùng của một mô tả công việc (văn bản → tiêu đề → danh sách → khối), không\n * theo bảng chữ cái: menu lọc theo chữ gõ, nên thứ tự chỉ có nghĩa ở lượt mở ĐẦU, khi chưa gõ gì.\n *\n * Trong bảng có thêm thao tác bảng (thêm/xoá hàng, cột); ở trình soạn markdown thì CHỈ còn chúng.\n */\nexport const SLASH_COMMANDS: readonly SlashCommand[] = [\n  {\n    id: \"text\",\n    icon: Pilcrow,\n    aliases: \"p text paragraph\",\n    run: (editor, range) => editor.chain().focus().deleteRange(range).setParagraph().run()\n  },\n  {\n    id: \"heading1\",\n    icon: Heading1,\n    hint: \"#\",\n    aliases: \"h1 heading\",\n    run: (editor, range) => editor.chain().focus().deleteRange(range).setHeading({ level: 1 }).run()\n  },\n  {\n    id: \"heading2\",\n    icon: Heading2,\n    hint: \"##\",\n    aliases: \"h2 heading\",\n    run: (editor, range) => editor.chain().focus().deleteRange(range).setHeading({ level: 2 }).run()\n  },\n  {\n    id: \"heading3\",\n    icon: Heading3,\n    hint: \"###\",\n    aliases: \"h3 heading\",\n    run: (editor, range) => editor.chain().focus().deleteRange(range).setHeading({ level: 3 }).run()\n  },\n  {\n    id: \"bulletList\",\n    icon: List,\n    hint: \"-\",\n    aliases: \"ul bullet list\",\n    run: (editor, range) => editor.chain().focus().deleteRange(range).toggleBulletList().run()\n  },\n  {\n    id: \"orderedList\",\n    icon: ListOrdered,\n    hint: \"1.\",\n    aliases: \"ol ordered number list\",\n    run: (editor, range) => editor.chain().focus().deleteRange(range).toggleOrderedList().run()\n  },\n  {\n    id: \"taskList\",\n    icon: ListChecks,\n    hint: \"[]\",\n    aliases: \"todo task checklist checkbox\",\n    run: (editor, range) => editor.chain().focus().deleteRange(range).toggleTaskList().run()\n  },\n  {\n    id: \"blockquote\",\n    icon: TextQuote,\n    hint: \">\",\n    aliases: \"quote blockquote\",\n    run: (editor, range) => editor.chain().focus().deleteRange(range).toggleBlockquote().run()\n  },\n  {\n    id: \"codeBlock\",\n    icon: SquareCode,\n    hint: \"```\",\n    aliases: \"code pre codeblock\",\n    run: (editor, range) => editor.chain().focus().deleteRange(range).setCodeBlock().run()\n  },\n  {\n    id: \"table\",\n    icon: Table,\n    aliases: \"table spreadsheet\",\n    // Không lồng bảng trong bảng — GFM không có, và hiếm khi là điều người soạn muốn.\n    when: (editor) => !inTable(editor),\n    run: (editor, range) =>\n      editor.chain().focus().deleteRange(range).insertTable({ rows: 3, cols: 3, withHeaderRow: true }).run()\n  },\n  {\n    id: \"divider\",\n    icon: Minus,\n    hint: \"---\",\n    aliases: \"hr divider rule separator\",\n    run: (editor, range) => editor.chain().focus().deleteRange(range).setHorizontalRule().run()\n  },\n  {\n    id: \"image\",\n    icon: ImagePlus,\n    aliases: \"img image picture upload\",\n    when: (editor, context) => blockAllowed(editor, context) && Boolean(context.pickImage),\n    run: (editor, range, context) => {\n      editor.chain().focus().deleteRange(range).run();\n      context.pickImage?.();\n    }\n  },\n  {\n    id: \"tableAddRow\",\n    icon: BetweenHorizontalEnd,\n    aliases: \"row add insert\",\n    when: inTable,\n    run: (editor, range) => editor.chain().focus().deleteRange(range).addRowAfter().run()\n  },\n  {\n    id: \"tableAddColumn\",\n    icon: BetweenVerticalEnd,\n    aliases: \"column col add insert\",\n    when: inTable,\n    run: (editor, range) => editor.chain().focus().deleteRange(range).addColumnAfter().run()\n  },\n  {\n    id: \"tableDeleteRow\",\n    icon: Rows3,\n    aliases: \"row delete remove\",\n    when: inTable,\n    run: (editor, range) => editor.chain().focus().deleteRange(range).deleteRow().run()\n  },\n  {\n    id: \"tableDeleteColumn\",\n    icon: Columns3,\n    aliases: \"column col delete remove\",\n    when: inTable,\n    run: (editor, range) => editor.chain().focus().deleteRange(range).deleteColumn().run()\n  },\n  {\n    id: \"tableDelete\",\n    icon: Trash2,\n    aliases: \"table delete remove\",\n    when: inTable,\n    run: (editor, range) => editor.chain().focus().deleteRange(range).deleteTable().run()\n  }\n];\n\n/**\n * Các mục hiện được ở vị trí con trỏ, khớp với chữ đã gõ.\n *\n * Khớp = MỌI từ của chữ gõ nằm trong (tên đã dịch + từ đồng nghĩa đã dịch + bí danh máy) — không\n * dấu, không phân biệt hoa thường, đúng luật `matchesSearch` của `Combobox`: \"/tieu\" ra \"Tiêu đề\",\n * \"/h2\" ra \"Tiêu đề 2\" ở mọi ngôn ngữ.\n */\nexport function filterSlashCommands(\n  editor: Editor,\n  query: string,\n  labels: MarkdownEditorLabels,\n  context: SlashCommandContext\n): SlashMenuItem[] {\n  const words = query.trim().split(/\\s+/).filter(Boolean);\n  return SLASH_COMMANDS.filter((command) =>\n    command.when ? command.when(editor, context) : blockAllowed(editor, context)\n  )\n    .filter((command) => {\n      const haystack = `${labels[command.id]} ${labels.slashKeywords[command.id]} ${command.aliases}`;\n      return words.every((word) => matchesSearch(haystack, word));\n    })\n    .map((command) => ({\n      id: command.id,\n      icon: command.icon,\n      hint: command.hint,\n      label: labels[command.id],\n      execute: (target, range) => command.run(target, range, context)\n    }));\n}\n\nexport const SLASH_PLUGIN_KEY = new PluginKey(\"comitorSlashMenu\");\n\n/**\n * Extension mở menu `/`. Phần GIAO DIỆN (danh sách, bàn phím) đến qua `render` — xem\n * `SuggestionStore`.\n *\n * `/` chỉ kích hoạt ở đầu dòng hoặc sau dấu cách (`allowedPrefixes` mặc định của Tiptap), nên gõ\n * đường dẫn `a/b` hay ngày `02/10` không bật menu. Không bật trong khối mã và mã nội dòng: ở đó `/`\n * là chữ của mã.\n */\nexport function createSlashCommandExtension(\n  options: Pick<SuggestionOptions<SlashMenuItem, SlashMenuItem>, \"items\" | \"render\">\n): Extension {\n  return Extension.create({\n    name: \"comitorSlashMenu\",\n    addProseMirrorPlugins() {\n      return [\n        Suggestion<SlashMenuItem, SlashMenuItem>({\n          editor: this.editor,\n          pluginKey: SLASH_PLUGIN_KEY,\n          char: \"/\",\n          allowSpaces: false,\n          items: options.items,\n          render: options.render,\n          command: ({ editor, range, props }) => props.execute(editor, range),\n          allow: ({ editor }) => editor.isEditable && !editor.isActive(\"codeBlock\") && !editor.isActive(\"code\")\n        })\n      ];\n    }\n  });\n}\n"],"mappings":"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","names":[]}

package/dist/editor/suggestion-menu.d.ts

@@ -0,0 +1,38 @@
+import { Editor } from '@tiptap/core';
+import * as React from 'react';
+import { SuggestionStore } from './suggestion-store.js';
+import '@tiptap/pm/state';
+import '@tiptap/suggestion';
+
+/**
+ * Danh sách gợi ý nổi của trình soạn — DÙNG CHUNG cho menu `/` (khối) và `@` (người).
+ *
+ * Con trỏ KHÔNG rời vùng soạn: người dùng vẫn đang gõ chữ lọc, nên focus ở lại ProseMirror và bàn
+ * phím đi đường plugin → `SuggestionStore.keyHandler` → đây. Vì vậy danh sách là `role="listbox"`
+ * điều khiển bằng `aria-activedescendant` đặt lên CHÍNH vùng soạn (khuôn combobox của ARIA), không
+ * phải một danh sách nhận focus.
+ *
+ * Mở bằng `Popover` của gói neo vào một phần tử ẢO (khung của đoạn `/que…` đang gõ) — lý do không
+ * gắn thẳng vào `document.body` ở đầu `suggestion-store.ts`.
+ */
+
+interface SuggestionMenuProps<Item, Selected> {
+    editor: Editor;
+    store: SuggestionStore<Item, Selected>;
+    /** Tên của listbox cho trình đọc màn hình */
+    label: string;
+    emptyLabel: string;
+    loadingLabel?: string;
+    getKey: (item: Item) => string;
+    renderItem: (item: Item) => React.ReactNode;
+    /**
+     * Ẩn hẳn menu (và thoát chế độ gợi ý) khi KHÔNG có kết quả. Dùng cho `@`: tên người có dấu cách
+     * nên chữ lọc được phép chứa dấu cách — khi không còn ai khớp, người dùng đang viết câu thường
+     * chứ không còn tìm người, và một ô "Không tìm thấy" bám theo từng chữ là phiền.
+     */
+    exitWhenEmpty?: (query: string) => boolean;
+    className?: string;
+}
+declare function SuggestionMenu<Item, Selected>({ editor, store, label, emptyLabel, loadingLabel, getKey, renderItem, exitWhenEmpty, className }: SuggestionMenuProps<Item, Selected>): React.JSX.Element;
+
+export { SuggestionMenu, type SuggestionMenuProps };

package/dist/editor/suggestion-menu.js

@@ -0,0 +1,144 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Popover, PopoverAnchor, PopoverContent } from "../components/ui/popover.js";
+import { cn } from "../lib/cn.js";
+import { useAsRef } from "../lib/use-as-ref.js";
+function SuggestionMenu({
+  editor,
+  store,
+  label,
+  emptyLabel,
+  loadingLabel,
+  getKey,
+  renderItem,
+  exitWhenEmpty,
+  className
+}) {
+  const snapshot = React.useSyncExternalStore(
+    store.subscribe,
+    store.getSnapshot,
+    store.getServerSnapshot
+  );
+  const [lastSnapshot, setLastSnapshot] = React.useState(snapshot);
+  if (snapshot && snapshot !== lastSnapshot) setLastSnapshot(snapshot);
+  const shown = snapshot ?? lastSnapshot;
+  const [activeIndex, setActiveIndex] = React.useState(0);
+  const activeIndexRef = useAsRef(activeIndex);
+  const listId = React.useId();
+  const optionId = (index) => `${listId}-option-${index}`;
+  const items = shown?.items ?? [];
+  const query = shown?.query ?? "";
+  const loading = Boolean(shown?.loading);
+  const hidden = Boolean(snapshot && !loading && items.length === 0 && exitWhenEmpty?.(snapshot.query));
+  React.useEffect(() => setActiveIndex(0), [query, items.length]);
+  React.useEffect(() => {
+    if (hidden) snapshot?.exit();
+  }, [hidden, snapshot]);
+  React.useEffect(() => {
+    store.keyHandler = (event) => {
+      const current = store.getSnapshot();
+      const count = current?.items.length ?? 0;
+      if (!current || count === 0) return false;
+      if (event.key === "ArrowDown") {
+        setActiveIndex((index) => (index + 1) % count);
+        return true;
+      }
+      if (event.key === "ArrowUp") {
+        setActiveIndex((index) => (index - 1 + count) % count);
+        return true;
+      }
+      if (event.key === "Enter" || event.key === "Tab") {
+        const item = current.items[Math.min(activeIndexRef.current, count - 1)];
+        if (item === void 0) return false;
+        current.select(item);
+        return true;
+      }
+      return false;
+    };
+    return () => {
+      store.keyHandler = null;
+    };
+  }, [store, activeIndexRef]);
+  const open = Boolean(snapshot) && !hidden;
+  const activeOption = open && items.length > 0 ? optionId(Math.min(activeIndex, items.length - 1)) : null;
+  React.useEffect(() => {
+    const dom = editor.view.dom;
+    if (!open) return;
+    dom.setAttribute("aria-controls", listId);
+    if (activeOption) dom.setAttribute("aria-activedescendant", activeOption);
+    else dom.removeAttribute("aria-activedescendant");
+    return () => {
+      dom.removeAttribute("aria-controls");
+      dom.removeAttribute("aria-activedescendant");
+    };
+  }, [editor, open, listId, activeOption]);
+  React.useEffect(() => {
+    if (activeOption) document.getElementById(activeOption)?.scrollIntoView({ block: "nearest" });
+  }, [activeOption]);
+  const latest = useAsRef(shown);
+  const anchorRect = React.useRef(null);
+  const anchor = React.useRef({
+    getBoundingClientRect: () => {
+      const rect = latest.current?.clientRect();
+      if (rect) anchorRect.current = rect;
+      return anchorRect.current ?? new DOMRect();
+    }
+  });
+  return /* @__PURE__ */ jsxs(
+    Popover,
+    {
+      open,
+      onOpenChange: (next) => {
+        if (!next) snapshot?.exit();
+      },
+      children: [
+        /* @__PURE__ */ jsx(PopoverAnchor, { virtualRef: anchor }),
+        /* @__PURE__ */ jsx(
+          PopoverContent,
+          {
+            align: "start",
+            side: "bottom",
+            sideOffset: 6,
+            updatePositionStrategy: "always",
+            onOpenAutoFocus: (event) => event.preventDefault(),
+            onCloseAutoFocus: (event) => event.preventDefault(),
+            className: cn("max-h-80 w-72 overflow-y-auto p-1", className),
+            children: /* @__PURE__ */ jsx("div", { role: "listbox", id: listId, "aria-label": label, children: items.length === 0 ? /* @__PURE__ */ jsx("div", { className: "px-2 py-6 text-center text-sm text-muted-foreground", children: loading && loadingLabel ? loadingLabel : emptyLabel }) : items.map((item, index) => {
+              const active = index === activeIndex;
+              return (
+                // biome-ignore lint/a11y/useKeyWithClickEvents: bàn phím đi qua vùng soạn (aria-activedescendant), xem đầu file
+                /* @__PURE__ */ jsx(
+                  "div",
+                  {
+                    id: optionId(index),
+                    role: "option",
+                    tabIndex: -1,
+                    "aria-selected": active,
+                    "data-selected": active || void 0,
+                    onMouseDown: (event) => event.preventDefault(),
+                    onPointerMove: () => setActiveIndex(index),
+                    onClick: () => snapshot?.select(item),
+                    className: cn(
+                      // Bộ lớp của `CommandItem`: mục sáng `bg-accent`, đệm theo trục mật độ, icon mặc định 16px.
+                      "relative flex cursor-default items-center gap-2 rounded-sm px-2 py-(--menu-item-py) text-sm outline-hidden select-none",
+                      "mt-1 first:mt-0 data-[selected=true]:bg-accent data-[selected=true]:text-accent-foreground",
+                      "[&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+                      "[&_svg:not([class*='text-'])]:text-muted-foreground"
+                    ),
+                    children: renderItem(item)
+                  },
+                  getKey(item)
+                )
+              );
+            }) })
+          }
+        )
+      ]
+    }
+  );
+}
+export {
+  SuggestionMenu
+};
+//# sourceMappingURL=suggestion-menu.js.map

package/dist/editor/suggestion-menu.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/editor/suggestion-menu.tsx"],"sourcesContent":["\"use client\";\n\n/**\n * Danh sách gợi ý nổi của trình soạn — DÙNG CHUNG cho menu `/` (khối) và `@` (người).\n *\n * Con trỏ KHÔNG rời vùng soạn: người dùng vẫn đang gõ chữ lọc, nên focus ở lại ProseMirror và bàn\n * phím đi đường plugin → `SuggestionStore.keyHandler` → đây. Vì vậy danh sách là `role=\"listbox\"`\n * điều khiển bằng `aria-activedescendant` đặt lên CHÍNH vùng soạn (khuôn combobox của ARIA), không\n * phải một danh sách nhận focus.\n *\n * Mở bằng `Popover` của gói neo vào một phần tử ẢO (khung của đoạn `/que…` đang gõ) — lý do không\n * gắn thẳng vào `document.body` ở đầu `suggestion-store.ts`.\n */\n\nimport type { Editor } from \"@tiptap/core\";\nimport * as React from \"react\";\nimport { Popover, PopoverAnchor, PopoverContent } from \"../components/ui/popover.js\";\nimport { cn } from \"../lib/cn.js\";\nimport { useAsRef } from \"../lib/use-as-ref.js\";\nimport type { SuggestionSnapshot, SuggestionStore } from \"./suggestion-store.js\";\n\nexport interface SuggestionMenuProps<Item, Selected> {\n  editor: Editor;\n  store: SuggestionStore<Item, Selected>;\n  /** Tên của listbox cho trình đọc màn hình */\n  label: string;\n  emptyLabel: string;\n  loadingLabel?: string;\n  getKey: (item: Item) => string;\n  renderItem: (item: Item) => React.ReactNode;\n  /**\n   * Ẩn hẳn menu (và thoát chế độ gợi ý) khi KHÔNG có kết quả. Dùng cho `@`: tên người có dấu cách\n   * nên chữ lọc được phép chứa dấu cách — khi không còn ai khớp, người dùng đang viết câu thường\n   * chứ không còn tìm người, và một ô \"Không tìm thấy\" bám theo từng chữ là phiền.\n   */\n  exitWhenEmpty?: (query: string) => boolean;\n  className?: string;\n}\n\nexport function SuggestionMenu<Item, Selected>({\n  editor,\n  store,\n  label,\n  emptyLabel,\n  loadingLabel,\n  getKey,\n  renderItem,\n  exitWhenEmpty,\n  className\n}: SuggestionMenuProps<Item, Selected>) {\n  const snapshot: SuggestionSnapshot<Item> | null = React.useSyncExternalStore(\n    store.subscribe,\n    store.getSnapshot,\n    store.getServerSnapshot\n  );\n\n  /*\n   * Giữ ảnh chụp CUỐI để vẽ trong lúc `Popover` chạy hiệu ứng đóng: plugin xoá trạng thái ngay khi\n   * thoát, mà nội dung biến mất trước khung thì thấy một ô rỗng co lại.\n   */\n  const [lastSnapshot, setLastSnapshot] = React.useState(snapshot);\n  if (snapshot && snapshot !== lastSnapshot) setLastSnapshot(snapshot);\n  const shown = snapshot ?? lastSnapshot;\n\n  const [activeIndex, setActiveIndex] = React.useState(0);\n  // Bản ĐỌC của chỉ số cho bộ xử lý phím: nó sống trong một effect, nên state trong closure cũ một nhịp.\n  const activeIndexRef = useAsRef(activeIndex);\n  const listId = React.useId();\n  const optionId = (index: number) => `${listId}-option-${index}`;\n\n  const items = shown?.items ?? [];\n  const query = shown?.query ?? \"\";\n  const loading = Boolean(shown?.loading);\n  const hidden = Boolean(snapshot && !loading && items.length === 0 && exitWhenEmpty?.(snapshot.query));\n\n  // Danh sách đổi → về mục đầu. Theo CHỮ LỌC chứ không theo mảng (mảng mới mỗi lần plugin cập nhật).\n  // biome-ignore lint/correctness/useExhaustiveDependencies: chủ đích chạy lại theo chữ lọc và số mục\n  React.useEffect(() => setActiveIndex(0), [query, items.length]);\n\n  React.useEffect(() => {\n    if (hidden) snapshot?.exit();\n  }, [hidden, snapshot]);\n\n  // Bàn phím: plugin giữ focus ở vùng soạn và chuyển phím vào đây.\n  React.useEffect(() => {\n    store.keyHandler = (event) => {\n      const current = store.getSnapshot();\n      const count = current?.items.length ?? 0;\n      // Không có mục nào: trả phím cho vùng soạn — Enter xuống dòng như thường.\n      if (!current || count === 0) return false;\n      if (event.key === \"ArrowDown\") {\n        setActiveIndex((index) => (index + 1) % count);\n        return true;\n      }\n      if (event.key === \"ArrowUp\") {\n        setActiveIndex((index) => (index - 1 + count) % count);\n        return true;\n      }\n      if (event.key === \"Enter\" || event.key === \"Tab\") {\n        const item = current.items[Math.min(activeIndexRef.current, count - 1)];\n        if (item === undefined) return false;\n        current.select(item);\n        return true;\n      }\n      return false;\n    };\n    return () => {\n      store.keyHandler = null;\n    };\n  }, [store, activeIndexRef]);\n\n  // Quan hệ combobox trên chính vùng soạn — xem đầu file. Gỡ sạch khi menu đóng.\n  const open = Boolean(snapshot) && !hidden;\n  const activeOption = open && items.length > 0 ? optionId(Math.min(activeIndex, items.length - 1)) : null;\n  React.useEffect(() => {\n    const dom = editor.view.dom;\n    if (!open) return;\n    dom.setAttribute(\"aria-controls\", listId);\n    if (activeOption) dom.setAttribute(\"aria-activedescendant\", activeOption);\n    else dom.removeAttribute(\"aria-activedescendant\");\n    return () => {\n      dom.removeAttribute(\"aria-controls\");\n      dom.removeAttribute(\"aria-activedescendant\");\n    };\n  }, [editor, open, listId, activeOption]);\n\n  // Mục đang sáng luôn trong tầm nhìn khi đi bằng phím.\n  React.useEffect(() => {\n    if (activeOption) document.getElementById(activeOption)?.scrollIntoView({ block: \"nearest\" });\n  }, [activeOption]);\n\n  /*\n   * Neo ẢO: Radix đọc `getBoundingClientRect()` của nó mỗi lần tính vị trí. Đối tượng phải ỔN ĐỊNH\n   * (Popper gọi `onAnchorChange` sau mỗi render), còn khung thì đọc từ ảnh chụp MỚI NHẤT qua ref.\n   *\n   * ⚠ Nhớ khung CUỐI còn đo được: lúc menu đóng, plugin gỡ decoration của đoạn `/…` trước, nên\n   * `clientRect()` ra `null` đúng trong lúc `Popover` còn chạy hiệu ứng đóng — trả `DOMRect` rỗng\n   * ở đó là menu văng lên góc trái trên khi đang mờ dần (đã thấy trên harness).\n   */\n  const latest = useAsRef(shown);\n  const anchorRect = React.useRef<DOMRect | null>(null);\n  const anchor = React.useRef({\n    getBoundingClientRect: () => {\n      const rect = latest.current?.clientRect();\n      if (rect) anchorRect.current = rect;\n      return anchorRect.current ?? new DOMRect();\n    }\n  });\n\n  return (\n    <Popover\n      open={open}\n      onOpenChange={(next) => {\n        // Đóng từ PHÍA MENU (Escape, bấm ra ngoài) → thoát chế độ gợi ý của plugin cho khớp.\n        if (!next) snapshot?.exit();\n      }}\n    >\n      <PopoverAnchor virtualRef={anchor} />\n      <PopoverContent\n        align=\"start\"\n        side=\"bottom\"\n        sideOffset={6}\n        // Neo di chuyển theo chữ gõ (dòng xuống, khung cuộn) — đo lại mỗi khung hình khi đang mở.\n        updatePositionStrategy=\"always\"\n        onOpenAutoFocus={(event) => event.preventDefault()}\n        onCloseAutoFocus={(event) => event.preventDefault()}\n        className={cn(\"max-h-80 w-72 overflow-y-auto p-1\", className)}\n      >\n        {/* Không đặt `aria-multiselectable`: mỗi lần chọn là một lệnh, không phải tập chọn. */}\n        <div role=\"listbox\" id={listId} aria-label={label}>\n          {items.length === 0 ? (\n            <div className=\"px-2 py-6 text-center text-sm text-muted-foreground\">\n              {loading && loadingLabel ? loadingLabel : emptyLabel}\n            </div>\n          ) : (\n            items.map((item, index) => {\n              const active = index === activeIndex;\n              return (\n                // biome-ignore lint/a11y/useKeyWithClickEvents: bàn phím đi qua vùng soạn (aria-activedescendant), xem đầu file\n                <div\n                  key={getKey(item)}\n                  id={optionId(index)}\n                  role=\"option\"\n                  // -1: tới được bằng mã (biome đòi `option` focus được), không vào thứ tự Tab — focus\n                  // thật vẫn ở vùng soạn, mục sáng đi theo `aria-activedescendant`.\n                  tabIndex={-1}\n                  aria-selected={active}\n                  data-selected={active || undefined}\n                  // Giữ focus ở vùng soạn: mousedown mặc định sẽ kéo focus ra khỏi ProseMirror.\n                  onMouseDown={(event) => event.preventDefault()}\n                  onPointerMove={() => setActiveIndex(index)}\n                  onClick={() => snapshot?.select(item)}\n                  className={cn(\n                    // Bộ lớp của `CommandItem`: mục sáng `bg-accent`, đệm theo trục mật độ, icon mặc định 16px.\n                    \"relative flex cursor-default items-center gap-2 rounded-sm px-2 py-(--menu-item-py) text-sm outline-hidden select-none\",\n                    \"mt-1 first:mt-0 data-[selected=true]:bg-accent data-[selected=true]:text-accent-foreground\",\n                    \"[&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4\",\n                    \"[&_svg:not([class*='text-'])]:text-muted-foreground\"\n                  )}\n                >\n                  {renderItem(item)}\n                </div>\n              );\n            })\n          )}\n        </div>\n      </PopoverContent>\n    </Popover>\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/editor/suggestion-store.d.ts

@@ -0,0 +1,47 @@
+import { PluginKey } from '@tiptap/pm/state';
+import { SuggestionOptions } from '@tiptap/suggestion';
+
+/**
+ * Cầu nối giữa plugin gợi ý của Tiptap (`@tiptap/suggestion` — vòng đời onStart/onUpdate/onExit,
+ * sống trong ProseMirror) và một component React (`SuggestionMenu`).
+ *
+ * Không dùng `ReactRenderer` + `props.mount()` như ví dụ của Tiptap: cách đó gắn danh sách vào
+ * `document.body` ngoài mọi lớp Radix, và trong một `Dialog` (form tạo việc) thì Radix coi cú bấm
+ * vào danh sách là bấm RA NGOÀI hộp thoại — hộp thoại đóng ngay giữa lúc chọn khối. Ở đây plugin
+ * chỉ ĐẨY trạng thái vào một kho nhỏ; menu là cây React bình thường của trình soạn, mở bằng `Popover`
+ * của gói — một lớp Radix lồng đúng thứ bậc, nên Escape đóng menu chứ không đóng hộp thoại.
+ */
+
+interface SuggestionSnapshot<Item> {
+    items: Item[];
+    /** Chữ gõ sau ký tự kích hoạt */
+    query: string;
+    /** `true` khi `items()` bất đồng bộ chưa trả về */
+    loading: boolean;
+    /** Khung của đoạn đang gõ (`/que…`) — neo cho menu. `null` khi plugin chưa vẽ xong decoration. */
+    clientRect: () => DOMRect | null;
+    select: (item: Item) => void;
+    /** Thoát hẳn chế độ gợi ý (gỡ decoration) — dùng khi menu bị đóng từ PHÍA MENU (Escape, bấm ra ngoài). */
+    exit: () => void;
+}
+declare class SuggestionStore<Item, Selected = Item> {
+    private readonly pluginKey;
+    private readonly toSelected;
+    private snapshot;
+    private readonly listeners;
+    /**
+     * Bàn phím trong lúc menu mở: ProseMirror nhận phím (con trỏ vẫn ở trình soạn), plugin chuyển cho
+     * hàm này. Menu đăng ký nó khi mount. Trả `true` = đã xử lý, ProseMirror không làm gì thêm.
+     */
+    keyHandler: ((event: KeyboardEvent) => boolean) | null;
+    constructor(pluginKey: PluginKey, toSelected: (item: Item) => Selected);
+    subscribe: (listener: () => void) => () => void;
+    getSnapshot: () => SuggestionSnapshot<Item> | null;
+    getServerSnapshot: () => null;
+    private set;
+    private fromProps;
+    /** Truyền thẳng vào `render` của `Suggestion` / `Mention.suggestion`. */
+    render: NonNullable<SuggestionOptions<Item, Selected>["render"]>;
+}
+
+export { type SuggestionSnapshot, SuggestionStore };