kindy-editor 3.2.1 → 3.2.3

package/dist-lib/{webmcp-KVT__0GH.js → webmcp-QA5rVg1F.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 { p as j, c as _, e as F, t as k, D as L } from "./toc-BIj8uQ-W.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-zIpjgEaZ.js").then((m) => m.c);
       return e.dispatch(d(t)), i && e.searchClear(), g("inserted");
     }
   }), a({

package/docs/http-event-sink.md

@@ -13,6 +13,13 @@ const sink = createHttpEventSink({
   headers: async () => ({
     Authorization: `Bearer ${await session.accessToken()}`,
   }),
+  // Transmit ONLY clean semantic committed events + review/export lifecycle:
+  eventTypes: [
+    "document.change.committed",
+    "document.export.completed",
+    "review.comment.added",
+    "review.comment.deleted",
+  ],
   batchSize: 25,
   flushIntervalMs: 1000,
   maxAttempts: 4,

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` |
 
@@ -109,6 +110,108 @@ includes `newlyMentionedUserIds`, and tombstoning emits
 `review.comment.deleted`. See [Review comments and @mentions](./review-comments.md)
 for the integration and notification flow.
 
+## Document change events: Raw vs Semantic layer
+
+Kindy Editor divides content changes into two distinct tiers:
+
+```text
+User Input / Keystrokes
+         │
+         ▼
+[ RAW LAYER ]  document.change.applied (keystroke mutations, internal / collab / debug)
+         │
+         ▼
+   ChangeAggregator (Session Buffer, IME, continuous typing merge, no-op filter)
+         │
+         ├────── CommitPolicy (idle debounce ~1s, blur, save, block jump, enter)
+         │
+         ▼
+[ SEMANTIC LAYER ] document.change.committed (clean diffs for CRM, Audit, AI, Outbox)
+```
+
+### 1. Raw layer: `document.change.applied`
+Fires immediately on every editor mutation (keystrokes, backspace, paste, undo/redo).
+Best used for: internal extensions, presence sync, local undo history, or low-level operation debugging.
+
+Payload (`DocumentChangeEventData`):
+```ts
+interface DocumentChangeEventData {
+  origin: "typing" | "command" | "paste" | "undo" | "redo";
+  operationCount: number;
+  affectedBlockIds: string[];
+  operations?: Op[];            // Present when detail !== "metadata"
+  textDiffs?: TextDiffSummary[]; // Discrete changes computed against pre-mutation shadow state
+  selectionBefore?: DocSelection | null;
+  selectionAfter?: DocSelection | null;
+  change?: Change;
+}
+```
+
+### 2. Semantic layer: `document.change.committed`
+Fires only when a logical editing session finishes across a commit boundary (idle debounce, blur, save, block switch).
+Best used for: **external integrations (CRM, Audit Log, AI processors, Webhook sinks, Notifications)**.
+
+Payload (`DocumentChangeCommittedData`):
+```ts
+interface DocumentChangeCommittedData {
+  transactionId: string;
+  changeGroupId: string;         // Stable group id tying all transactions in this session
+  beforeVersion: number;         // Document baseline version before session began
+  afterVersion: number;          // Document version after session completed
+  origin: "typing" | "command" | "paste" | "undo" | "redo";
+  textDiffs: TextDiffSummary[];   // Clean, aggregated text diffs (no-ops stripped)
+  intent?: string;
+  affectedBlockIds?: string[];
+}
+```
+
+### `TextDiffSummary` structure
+```ts
+interface TextDiffSummary {
+  action: "insert" | "delete" | "replace";
+  blockId: string;
+  offset: number;
+  fromText: string;
+  toText: string;
+}
+```
+
+### How specific scenarios are handled:
+
+1. **Continuous Typing Session (Gõ liên tục):**
+   - User types characters one by one.
+   - Raw `document.change.applied` events fire on each keystroke for immediate UI responsiveness.
+   - `ChangeAggregator` buffers the keystrokes without spamming downstream sinks.
+   - When the user stops typing for ~1000ms (idle) or clicks outside (blur), a single `document.change.committed` is emitted with the consolidated change (e.g., `action: "insert"`, `fromText: ""`, `toText: "Đà Nẵng"`).
+
+2. **Selected Range Replacement (Bôi đen ghi đè):**
+   - User selects `"Hà Nội"` and types `"Đà Nẵng"`.
+   - The editor runs `deleteRange` followed by `insertText`.
+   - Shadow state evaluation and `mergeRelatedChanges` combine them into:
+     `{ action: "replace", blockId: "p-5", offset: 13, fromText: "Hà Nội", toText: "Đà Nẵng" }`.
+
+3. **Multiple Independent Edits in One Transaction / Session (Nhiều sửa đổi độc lập):**
+   - E.g. Editing `"50"` -> `"75"` at offset 5 and `"30"` -> `"45"` at offset 25.
+   - `textDiffs` contains two separate items, preserving exact offsets without string concatenation corruption:
+     ```json
+     [
+       { "action": "replace", "blockId": "p-5", "offset": 5, "fromText": "50", "toText": "75" },
+       { "action": "replace", "blockId": "p-5", "offset": 25, "fromText": "30", "toText": "45" }
+     ]
+     ```
+
+4. **No-op Edits (Gõ rồi xóa về nguyên bản):**
+   - User types `" thêm"` and immediately backspaces it back to original text.
+   - When session boundary triggers, `ChangeAggregator` compares baseline vs current text.
+   - Since text is identical, **no event is emitted**, preventing dirty garbage data from reaching downstream databases.
+
+5. **Batch Commands & Paste (Dán hoặc chạy command):**
+   - Paste, cut, or formatting commands commit immediately (`CommitBoundaryReason = "explicit"`).
+   - Any prior typing session is automatically flushed before the new action begins.
+
+6. **Cursor Jump / Block Switch (Chuyển khối hoặc nhảy chuột):**
+   - If user edits block `p-1`, then clicks block `p-2` or moves caret far away, `CommitPolicy` detects a boundary (`"selection-jump"` / `"block-switch"`), flushes block `p-1`'s session, and opens a new session for `p-2`.
+
 ## What each layer owns
 
 The editor library owns content changes, review operations, editor state,

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>
+  );
+}
+```