kindy-editor 3.2.1 → 3.2.2

package/dist-lib/{webmcp-KVT__0GH.js → webmcp-DrpPKUeh.js}

@@ -1,4 +1,4 @@
-import { a as j, j as _, A as F, t as k, D as L } from "./toc-DSwkNKls.js";
+import { a as j, j as _, A as F, t as k, D as L } from "./toc-C6XLbDEA.js";
 const s = (e) => Math.round(e * 100) / 100;
 function A(e) {
   const o = { font: e.fontFamily, sizePx: e.fontSizePx };
@@ -332,7 +332,7 @@ function H(e, o = {}, r = {}) {
       if (i && e.search(i).total === 0)
         return e.searchClear(), f(`text not found: ${i}`);
       if (!e.getSelection()) return f("no selection (pass 'find' or select_range first)");
-      const { insertText: d } = await import("./editorApp-7-JzxxVn.js").then((m) => m.c);
+      const { insertText: d } = await import("./editorApp-N20nk5uQ.js").then((m) => m.c);
       return e.dispatch(d(t)), i && e.searchClear(), g("inserted");
     }
   }), a({

package/docs/.vitepress/config.ts

@@ -6,6 +6,7 @@ export default defineConfig({
   themeConfig: {
     nav: [
       { text: 'Home', link: '/' },
+      { text: 'Template Variables', link: '/template-variables' },
       { text: 'Fonts & CDN', link: '/fonts' },
       { text: 'Table editing', link: '/table-editing' },
       { text: 'Public Events', link: '/public-events' },
@@ -16,6 +17,7 @@ export default defineConfig({
         text: 'Integration & Events',
         items: [
           { text: 'Overview', link: '/' },
+          { text: 'Template Variables & Metadata', link: '/template-variables' },
           { text: 'Fonts & CDN', link: '/fonts' },
           { text: 'Table editing', link: '/table-editing' },
           { text: 'Public Events API', link: '/public-events' },

package/docs/public-events.md

@@ -98,6 +98,7 @@ general-purpose analytics services.
 | Export | `document.export.*` |
 | Changes | `document.change.applied`, `document.change.committed`, `document.change.rejected`, `document.remoteChange.applied` |
 | Review | `review.operation.applied`, `review.suggestion.*`, `review.thread.*`, `review.comment.*` |
+| Template & Metadata | `template.variable.clicked`, `template.variable.changed`, `template.displayMode.changed` |
 | Collaboration | `collaboration.connecting`, `collaboration.connected`, `collaboration.disconnected`, `collaboration.user.*`, `collaboration.presence.changed` |
 | Other | `document.shared`, `selection.changed`, `custom` |
 

package/docs/template-variables.md

@@ -0,0 +1,310 @@
+# Template Variables & Contract Metadata API
+
+Kindy Editor hỗ trợ quản lý các **biến mẫu (Template Variables)** và **Metadata Hợp đồng** trực tiếp trong mô hình tài liệu (AST level). 
+
+Các biến mẫu được liên kết chặt chẽ với văn bản thông qua thuộc tính `CharStyle.variableKey`, đảm bảo tính toàn vẹn (atomic tokens), hỗ trợ định dạng tự động theo kiểu dữ liệu (`TEXT`, `NUMBER`, `DATE`, `CURRENCY`, `SELECT`), và cung cấp hệ thống event phong phú để host application (React, Vue, Angular, v.v.) tự do dựng giao diện popover/drawer theo design system riêng.
+
+---
+
+## 1. Khởi tạo & Cấu hình (Options)
+
+Khi khởi tạo `KindyEditor`, bạn có thể cấu hình các tùy chọn liên quan đến biến mẫu:
+
+```ts
+import { KindyEditor } from "kindy-editor";
+import type { VariableClickInfo } from "kindy-editor";
+
+const editor = new KindyEditor({
+  container: document.getElementById("editor-container")!,
+  
+  // Callback khi người dùng click vào một biến mẫu trong văn bản
+  onVariableClick: (info: VariableClickInfo) => {
+    console.log("Clicked variable:", info.key, info.def);
+    // info.clientRect chứa tọa độ viewport { top, left, width, height }
+    // để host app hiển thị Popover / Drawer / Modal tùy biến
+  },
+
+  // Có hiển thị Popover mặc định của editor không (mặc định: false)
+  // Nếu đặt là false, host app toàn quyền hiển thị UI qua onVariableClick
+  showVariablePopover: false,
+});
+```
+
+---
+
+## 2. Các phương thức của Editor API (`EditorHandle` / `KindyEditor`)
+
+Tất cả các phương thức sau có thể gọi thông qua instance của `KindyEditor` hoặc thông qua `handle` nhận được từ `onReady` / `editor.ready`:
+
+### 2.1. `setTemplateVariables(values, options?)`
+Cập nhật giá trị hàng loạt biến mà không cần reload tài liệu. Trạng thái con trỏ, lịch sử undo/redo và vị trí scroll đều được bảo toàn.
+
+```ts
+await editor.setTemplateVariables(
+  {
+    contract_code: "HD-2026/001",
+    contract_value: 25000000,
+    signing_date: "2026-10-04",
+    customer_name: "Công ty Cổ phần Công nghệ ABC",
+  },
+  {
+    author: { id: "user-1", firstName: "Hùng", lastName: "Ngô" },
+    source: "sidebar", // "api" | "editor" | "sidebar" | "inline" | "import" | "palette"
+  }
+);
+```
+
+### 2.2. `insertTemplateVariable(item, author?)`
+Chèn một token biến mẫu atomic tại vị trí con trỏ hiện tại (hoặc thay thế vùng chọn hiện tại).
+
+```ts
+await editor.insertTemplateVariable(
+  {
+    key: "contract_value",
+    label: "Giá trị hợp đồng",
+    dataType: "CURRENCY",
+    value: 50000000,
+    defaultValue: "{{contract_value}}",
+    group: "TAI_CHINH",
+    metadataId: 102,
+  },
+  { id: "user-1", firstName: "Hùng", lastName: "Ngô" }
+);
+```
+
+### 2.3. `setVariableDisplayMode(mode)` & `getVariableDisplayMode()`
+Thay đổi chế độ hiển thị biến trên toàn bộ văn bản:
+* `'code'` / `'placeholder'`: Hiển thị mã placeholder, ví dụ `{{contract_code}}`. Thích hợp khi soạn thảo mẫu hợp đồng (Template Editor).
+* `'value'`: Hiển thị giá trị thực tế sau khi đã format theo `dataType`, ví dụ `HD-2026/001` hoặc `25.000.000 VNĐ`. Nếu biến chưa có giá trị, tự động fallback về mã placeholder.
+* `'label'`: Hiển thị nhãn tiếng Việt của biến.
+
+```ts
+// Chuyển sang hiển thị giá trị thực tế
+await editor.setVariableDisplayMode("value");
+
+// Đọc chế độ hiện tại
+const currentMode = await editor.getVariableDisplayMode(); // "value" | "code"
+```
+
+### 2.4. `getTemplateVariables()` & `getTemplateVariable(key)`
+Truy vấn danh sách hoặc chi tiết các biến đã đăng ký trong tài liệu.
+
+```ts
+// Lấy toàn bộ biến đã đăng ký
+const allVariables = await editor.getTemplateVariables();
+console.log(allVariables["contract_code"]);
+
+// Lấy 1 biến cụ thể
+const codeVar = await editor.getTemplateVariable("contract_code");
+```
+
+### 2.5. `getUsedMetadataIds()`
+Trả về danh sách các `metadataId` (ID số định danh từ cơ sở dữ liệu backend) hiện đang thực sự được nhúng trong tài liệu. Rất hữu ích cho backend khi cần kiểm tra những metadata nào đang được văn bản sử dụng.
+
+```ts
+const usedIds = await editor.getUsedMetadataIds();
+// Ví dụ: [101, 102, 105]
+```
+
+### 2.6. `setMetadataCatalog(catalog)` & `openMetadataPalette()`
+Cung cấp danh mục các biến từ backend cho tính năng gợi ý autocomplete (`@`), hoặc chủ động mở thanh tìm kiếm biến tại vị trí con trỏ.
+
+```ts
+// Cung cấp danh mục biến cho autocomplete
+await editor.setMetadataCatalog([
+  {
+    key: "contract_code",
+    label: "Mã hợp đồng",
+    dataType: "TEXT",
+    group: "THONG_TIN_CHUNG",
+    metadataId: 1,
+  },
+  {
+    key: "contract_value",
+    label: "Giá trị hợp đồng",
+    dataType: "CURRENCY",
+    group: "TAI_CHINH",
+    metadataId: 2,
+  },
+  {
+    key: "effective_date",
+    label: "Ngày hiệu lực",
+    dataType: "DATE",
+    dateFormat: "dd/MM/yyyy",
+    group: "THOI_HAN",
+    metadataId: 3,
+  },
+]);
+
+// Chủ động mở bảng chọn @ tại vị trí con trỏ
+await editor.openMetadataPalette();
+```
+
+---
+
+## 3. Public Events API
+
+Lắng nghe các sự kiện liên quan đến Template Variables thông qua `editor.on(...)`:
+
+### 3.1. `template.variable.clicked`
+Kích hoạt khi người dùng click vào một biến mẫu trong văn bản:
+
+```ts
+editor.on("template.variable.clicked", (event) => {
+  const { key, def, position, rect, clientRect } = event.data;
+  
+  console.log(`Clicked variable: ${key}`);
+  console.log(`Current value:`, def.value);
+  console.log(`Bounding Box trên màn hình:`, clientRect);
+  // clientRect: { left, top, right, bottom, width, height }
+  // Dùng để định vị floating popover/tooltip cạnh biến vừa click
+});
+```
+
+### 3.2. `template.variable.changed`
+Kích hoạt khi một biến được tạo mới, cập nhật giá trị hoặc hoàn tác:
+
+```ts
+editor.on("template.variable.changed", (event) => {
+  const { key, newValue, previousValue, action, source, def } = event.data;
+  console.log(`Variable ${key} was ${action} from source ${source}`);
+  console.log(`Old: ${previousValue} -> New: ${newValue}`);
+});
+```
+
+### 3.3. `template.displayMode.changed`
+Kích hoạt khi chế độ hiển thị biến thay đổi:
+
+```ts
+editor.on("template.displayMode.changed", (event) => {
+  const { mode, previousMode } = event.data;
+  console.log(`Display mode changed from ${previousMode} to ${mode}`);
+});
+```
+
+---
+
+## 4. Định dạng tự động theo Kiểu dữ liệu (`MetadataDataType`)
+
+Khi ở chế độ `value`, hàm định dạng tự động chuyển đổi giá trị dựa vào trường `dataType`:
+
+| `dataType` | Ví dụ đầu vào | Kết quả hiển thị |
+| :--- | :--- | :--- |
+| `TEXT` | `"Hà Nội"` | `Hà Nội` |
+| `NUMBER` | `1500000` | `1.500.000` (định dạng theo locale vi-VN) |
+| `CURRENCY` | `25000000` | `25.000.000 VNĐ` |
+| `DATE` | `"2026-10-04"` | `04/10/2026` (hỗ trợ `dateFormat: "dd/MM/yyyy"` hoặc `"yyyy-MM-dd"`) |
+| `SELECT` | `"Đã ký"` | `Đã ký` |
+
+---
+
+## 5. Tương tác Người dùng (UX & Hành vi gõ phím)
+
+1. **Kích hoạt Autocomplete qua `@`**:
+   - Khi gõ ký tự `@` ở đầu dòng hoặc sau một khoảng trắng, bảng **Metadata Palette** sẽ tự động mở ra.
+   - Người dùng có thể dùng các phím mũi tên `↑` `↓` để duyệt, `Enter` hoặc `Tab` để chèn, và `Escape` để đóng.
+   - Gõ email (ví dụ: `sales@gmail.com`) sẽ **không** bị kích hoạt bảng chọn vì trước `@` không phải là khoảng trắng.
+
+2. **Tính chất Atomic Token**:
+   - Khi bấm phím `Backspace` hoặc `Delete` tại biên của biến, toàn bộ token biến sẽ được xóa sạch trong một thao tác (thay vì xóa từng ký tự placeholder).
+   - Khi gõ phím tiếp theo ngay sau một biến, văn bản mới sẽ tự động nhận style thông thường và không bị dính thuộc tính `variableKey`.
+   - Khi click vào biến, văn bản của biến sẽ tự động được chọn toàn bộ.
+
+---
+
+## 6. Ví dụ Tích hợp với React
+
+```tsx
+import React, { useEffect, useRef, useState } from "react";
+import { KindyEditor, type VariableClickInfo } from "kindy-editor";
+import "kindy-editor/style";
+
+export function ContractEditor() {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const editorRef = useRef<KindyEditor | null>(null);
+  const [selectedVar, setSelectedVar] = useState<VariableClickInfo | null>(null);
+
+  useEffect(() => {
+    if (!containerRef.current) return;
+
+    const editor = new KindyEditor({
+      container: containerRef.current,
+      showVariablePopover: false, // tắt popup mặc định để dùng React Popover
+      onVariableClick: (info) => {
+        setSelectedVar(info);
+      },
+    });
+
+    editorRef.current = editor;
+
+    // Lắng nghe sự kiện click ra ngoài để đóng popover
+    const handleMouseDown = (e: MouseEvent) => {
+      if (!(e.target as HTMLElement).closest(".custom-variable-popover")) {
+        setSelectedVar(null);
+      }
+    };
+    window.addEventListener("mousedown", handleMouseDown);
+
+    return () => {
+      window.removeEventListener("mousedown", handleMouseDown);
+      editor.destroy();
+    };
+  }, []);
+
+  return (
+    <div style={{ position: "relative", width: "100%", height: "100vh" }}>
+      {/* Editor Canvas Container */}
+      <div ref={containerRef} style={{ width: "100%", height: "100%" }} />
+
+      {/* Custom React Floating Popover */}
+      {selectedVar && selectedVar.clientRect && (
+        <div
+          className="custom-variable-popover"
+          style={{
+            position: "fixed",
+            left: `${selectedVar.clientRect.left}px`,
+            top: `${selectedVar.clientRect.bottom + 8}px`,
+            background: "#ffffff",
+            border: "1px solid #e2e8f0",
+            borderRadius: "8px",
+            boxShadow: "0 10px 15px -3px rgba(0,0,0,0.1)",
+            padding: "12px 16px",
+            zIndex: 1000,
+            minWidth: "260px",
+          }}
+        >
+          <div style={{ fontWeight: "bold", color: "#0284c7" }}>
+            {selectedVar.def.label} ({`{{${selectedVar.key}}}`})
+          </div>
+          <div style={{ fontSize: "12px", color: "#64748b", marginTop: "4px" }}>
+            Loại: {selectedVar.def.dataType}
+          </div>
+          <div style={{ fontSize: "14px", marginTop: "6px" }}>
+            Giá trị: <strong>{String(selectedVar.def.value ?? "Chưa có")}</strong>
+          </div>
+          <button
+            onClick={() => {
+              const nextVal = prompt("Nhập giá trị mới:", String(selectedVar.def.value ?? ""));
+              if (nextVal !== null) {
+                editorRef.current?.setTemplateVariables({ [selectedVar.key]: nextVal });
+                setSelectedVar(null);
+              }
+            }}
+            style={{
+              marginTop: "8px",
+              padding: "4px 8px",
+              background: "#0284c7",
+              color: "#fff",
+              border: "none",
+              borderRadius: "4px",
+              cursor: "pointer",
+            }}
+          >
+            Chỉnh sửa giá trị
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kindy-editor",
-  "version": "3.2.1",
+  "version": "3.2.2",
   "type": "module",
   "description": "Trình soạn thảo tài liệu Word chính xác, vẽ bằng canvas",
   "license": "MIT",

package/types/kindy-editor.d.ts

@@ -54,7 +54,71 @@ export interface RevealRangeOptions {
   align?: "center" | "nearest" | "top" | "bottom";
 }
 
-export type TemplateVariableValues = Record<string, string | number | null | undefined>;
+export type TemplateVariableValues = Record<string, string | number | boolean | null | undefined>;
+
+export type MetadataDataType = "TEXT" | "NUMBER" | "DATE" | "CURRENCY" | "SELECT";
+export type VariableDisplayMode = "code" | "value" | "placeholder" | "label";
+
+export interface VariableBoundingBox {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+  width: number;
+  height: number;
+}
+
+export interface VariableClickInfo {
+  key: string;
+  def: TemplateVariableDef;
+  position: DocPosition;
+  rect: VariableBoundingBox;
+  clientRect?: VariableBoundingBox;
+}
+
+export interface MetadataAuditEntry {
+  id: string;
+  author: UserInfo;
+  timestamp: number;
+  previousValue: unknown;
+  newValue: unknown;
+  action: "created" | "updated" | "reverted";
+  source?: "api" | "editor" | "sidebar" | "palette" | "inline" | "import";
+}
+
+export interface TemplateVariableDef {
+  key: string;
+  label: string;
+  dataType: MetadataDataType;
+  dateFormat?: string;
+  value?: unknown;
+  defaultValue?: string;
+  metadataId?: number | string;
+  group?: string;
+  createdBy?: UserInfo;
+  createdAt?: number;
+  lastModifiedBy?: UserInfo;
+  lastModifiedAt?: number;
+  history?: MetadataAuditEntry[];
+}
+
+export interface SetTemplateVariablesOptions {
+  author?: UserInfo;
+  source?: "api" | "editor" | "sidebar" | "inline" | "import" | "palette";
+  trackInReview?: boolean;
+  metadata?: Record<string, Partial<TemplateVariableDef>>;
+}
+
+export interface InsertTemplateVariableItem {
+  key: string;
+  label: string;
+  dataType?: MetadataDataType;
+  dateFormat?: string;
+  value?: unknown;
+  defaultValue?: string;
+  metadataId?: number | string;
+  group?: string;
+}
 
 export interface EditorPermissions {
   editContent: boolean;
@@ -547,6 +611,13 @@ export interface KindyEditorOptions {
   onLoadProgress?: (progress: LoadProgress) => void;
   /** Granular capabilities governing content edits, annotations, and selection. */
   permissions?: Partial<EditorPermissions>;
+  /** Callback fired when a template variable token is clicked in the editor.
+   *  Provides variable key, definition, doc position, and bounding rects (container & client viewport).
+   *  Allows host application (React/Vue/etc.) to render custom modals, drawers, or popovers. */
+  onVariableClick?: (info: VariableClickInfo) => void;
+  /** Whether to show the built-in variable audit popover UI on click. Defaults to false.
+   *  When false, the built-in popover does not appear, leaving UI rendering to the host via onVariableClick / event. */
+  showVariablePopover?: boolean;
 }
 
 /** Initial view-chrome state (see KindyEditorOptions.view). Every field is
@@ -805,7 +876,31 @@ export interface EditorHandle {
   revealRange(range: ExternalRange, options?: RevealRangeOptions): void;
   /** Live-update {{KEY}} template placeholders in the document without full reload,
    *  preserving zoom, scroll position, and selection. */
-  setTemplateVariables(values: TemplateVariableValues): void;
+  setTemplateVariables(values: TemplateVariableValues, options?: SetTemplateVariablesOptions): void;
+  /** Revert a template variable to an earlier value recorded in its audit history. */
+  revertTemplateVariable(key: string, historyId: string, actor?: UserInfo): boolean;
+  /** Insert an atomic template variable token at current caret/selection. */
+  insertTemplateVariable(item: InsertTemplateVariableItem, author?: UserInfo): boolean;
+  /** Open the contract metadata palette autocomplete at current caret position. */
+  openMetadataPalette(): void;
+  /** Set template variable display mode ('code' | 'value' | 'placeholder'). */
+  setVariableDisplayMode(mode: VariableDisplayMode): void;
+  /** Get current template variable display mode. */
+  getVariableDisplayMode(): VariableDisplayMode;
+  /** Get all registered template variables in the document. */
+  getTemplateVariables(): Record<string, TemplateVariableDef>;
+  /** Get a single registered template variable definition by key. */
+  getTemplateVariable(key: string): TemplateVariableDef | null;
+  /** Get audit trail history for a template variable. */
+  getVariableHistory(key: string): MetadataAuditEntry[];
+  /** Open built-in variable popover explicitly. */
+  openVariablePopover(key: string, pos?: DocPosition): void;
+  /** Close built-in variable popover. */
+  closeVariablePopover(): void;
+  /** Get all metadata IDs (numbers) currently used by template variables in the document. */
+  getUsedMetadataIds(): number[];
+  /** Set custom metadata catalog for autocomplete palette. */
+  setMetadataCatalog(catalog: TemplateVariableDef[]): void;
   /** Update fine-grained capabilities (e.g. allow comments/selection in view mode). */
   setPermissions(permissions: Partial<EditorPermissions>): void;
   /** Current effective permissions. */
@@ -894,7 +989,31 @@ export declare class KindyEditor {
   revealRange(range: ExternalRange, options?: RevealRangeOptions): Promise<void>;
   /** Live-update {{KEY}} template placeholders in the document without full reload,
    *  preserving zoom, scroll position, and selection. */
-  setTemplateVariables(values: TemplateVariableValues): Promise<void>;
+  setTemplateVariables(values: TemplateVariableValues, options?: SetTemplateVariablesOptions): Promise<void>;
+  /** Revert a template variable to an earlier value recorded in its audit history. */
+  revertTemplateVariable(key: string, historyId: string, actor?: UserInfo): Promise<boolean>;
+  /** Insert an atomic template variable token at current caret/selection. */
+  insertTemplateVariable(item: InsertTemplateVariableItem, author?: UserInfo): Promise<boolean>;
+  /** Open the contract metadata palette autocomplete at current caret position. */
+  openMetadataPalette(): Promise<void>;
+  /** Set template variable display mode ('code' | 'value' | 'placeholder'). */
+  setVariableDisplayMode(mode: VariableDisplayMode): Promise<void>;
+  /** Get current template variable display mode. */
+  getVariableDisplayMode(): Promise<VariableDisplayMode>;
+  /** Get all registered template variables in the document. */
+  getTemplateVariables(): Promise<Record<string, TemplateVariableDef>>;
+  /** Get a single registered template variable definition by key. */
+  getTemplateVariable(key: string): Promise<TemplateVariableDef | null>;
+  /** Get audit trail history for a template variable. */
+  getVariableHistory(key: string): Promise<MetadataAuditEntry[]>;
+  /** Open built-in variable popover explicitly. */
+  openVariablePopover(key: string, pos?: DocPosition): Promise<void>;
+  /** Close built-in variable popover. */
+  closeVariablePopover(): Promise<void>;
+  /** Get all metadata IDs (numbers) currently used by template variables in the document. */
+  getUsedMetadataIds(): Promise<number[]>;
+  /** Set custom metadata catalog for autocomplete palette. */
+  setMetadataCatalog(catalog: TemplateVariableDef[]): Promise<void>;
   /** Update fine-grained capabilities (e.g. allow comments/selection in view mode). */
   setPermissions(permissions: Partial<EditorPermissions>): Promise<void>;
   /** Current effective permissions. */