kindy-editor 1.0.0 → 2.0.0

package/README.md

@@ -1,269 +1,278 @@
-# kindy-editor (Kindy Editor)
-
-Trình biên tập tài liệu chuẩn Office (Word-like Document Editor) hiện đại dựa trên **Vue 3** và **Tiptap 3**. Được tùy biến, tối ưu hóa và hỗ trợ 100% giao diện **Tiếng Việt**.
-
-[![npm version](https://img.shields.io/npm/v/kindy-editor.svg)](https://www.npmjs.com/package/kindy-editor)
-[![license](https://img.shields.io/github/license/hotienky/editor.svg)](./LICENSE)
-
----
-
-## ✨ Tính năng nổi bật
-
-- 📄 **Phân trang dạng Word (Page-based Pagination)**: Hỗ trợ ngắt trang, căn lề, khổ giấy (A4, A3, Letter, Legal...) chân trang & đầu trang (Header/Footer).
-- 💬 **Hệ thống Bình luận (Word-style Comments)**: Bôi đen văn bản để gắn bình luận, phản hồi (Reply), hoàn thành (Resolve), cuộn mượt và highlight từng người dùng.
-- 🇻🇳 **Tiếng Việt 100%**: Chuẩn hóa toàn bộ nhãn giao diện, bộ cỡ chữ tiêu chuẩn (`pt`), từ điển ký hiệu và phông chữ mượt mà.
-- 🎨 **Giao diện hiện đại (Ribbon & Classic)**: Hỗ trợ 2 chế độ thanh công cụ dạng Ribbon (như MS Word) hoặc Classic, chế độ tối (Dark mode).
-- 🔠 **Phông chữ hệ thống & Web Fonts chuẩn**: Tích hợp phông hệ thống mượt nét (`San Francisco`, `Segoe UI`, `Roboto`, `Arial`, `Times New Roman`...) không bị vỡ hay lệch dấu Tiếng Việt.
-- 🗄️ **Lưu trữ linh hoạt**: Tự động mã hóa nhúng bình luận vào HTML/JSON hoặc tách riêng lưu vào cơ sở dữ liệu (Database).
+# Kindy Editor v2
+
+Kindy Editor là SDK Document Library chuyên cho DOCX, xây dựng bằng Vue 3 và Tiptap/ProseMirror. Thư viện cung cấp giao diện quản lý tài liệu, editor trên web, lịch sử phiên bản, DOCX codec và hợp đồng API để ứng dụng chủ kết nối backend của mình.
+
+Kindy Editor **không** cung cấp backend, database, authentication, object storage hoặc nghiệp vụ hợp đồng. JSON `KindyDocumentState` là trạng thái chỉnh sửa chuẩn; DOCX gốc và DOCX export là artifact do server ứng dụng chủ lưu.
+
+## Phạm vi v2.0
+
+- Import DOCX trong Web Worker, kiểm tra ZIP/OOXML và trả `CompatibilityReport`.
+- Chỉnh sửa nội dung bằng Tiptap/ProseMirror với preset `Contract`: toolbar compact, page-only và chỉ giữ công cụ cần cho hợp đồng.
+- Explorer theo thư mục, tìm kiếm, tạo tài liệu trống và tạo từ template.
+- Autosave có debounce, cancellation và optimistic concurrency.
+- Lưu thủ công tạo version, xem read-only và khôi phục version.
+- Export DOCX OOXML thật bằng package `docx`.
+- In hoặc Save as PDF qua print dialog của trình duyệt.
+- UI engine có shell responsive, theme tokens, locale messages, slots và typed hooks.
+
+Khả năng round-trip DOCX chỉ được cam kết trong [Kindy DOCX Compatibility Profile](./CAPABILITIES.md). Kindy không phải Microsoft Word layout engine và không cam kết giữ nguyên mọi tính năng OOXML.
+
+Ngoại lệ duy nhất có thể bảo đảm byte-for-byte là tài liệu vừa import và **chưa có revision chỉnh sửa**: workspace tải lại artifact `original-docx` thay vì serialize JSON. Sau lần chỉnh sửa/save đầu tiên, DOCX mới được dựng từ `KindyDocumentState` và chỉ có cam kết theo compatibility profile.
+
+## Kiến trúc
+
+```text
+Ứng dụng chủ
+  ├─ KindyDocumentLibrary
+  │    ├─ DocumentLibraryShell       layout/responsive/theme
+  │    ├─ KindyDocumentExplorer      list/search/folder/import/template
+  │    ├─ KindyEditor                Tiptap/ProseMirror editor
+  │    └─ KindyVersionPanel          preview/restore
+  ├─ DocumentLibraryClient           autosave/conflict/events
+  ├─ DOCX codecs / browser print
+  └─ DocumentApiAdapter
+       ├─ RestDocumentAdapter
+       ├─ MemoryDocumentAdapter
+       └─ adapter riêng của ứng dụng
+```
 
----
+UI không gọi URL cố định và không biết token. Mọi IO đi qua `DocumentApiAdapter`.
 
-## 📦 Cài đặt
+## Cài đặt
 
 ```bash
 npm install kindy-editor
-# hoặc
-pnpm add kindy-editor
-# hoặc
-yarn add kindy-editor
 ```
 
----
-
-## 🚀 Hướng dẫn tích hợp cho dự án khác (Integration Methods)
+```ts
+import 'kindy-editor/style'
+```
 
-Thư viện `kindy-editor` hỗ trợ 4 cách tích hợp linh hoạt cho mọi môi trường dự án:
+Vue phải được cài trong ứng dụng chủ và đáp ứng peer dependency `vue ^3.5.0`.
 
-### Cách 1: Import Component (Vite / Webpack / Vue 3 SPA)
+## Quick start với REST API
 
 ```vue
 <template>
-  <div style="height: 100vh;">
-    <KindyEditor ref="editorRef" v-bind="editorOptions" />
-  </div>
+  <KindyDocumentLibrary
+    ref="workspace"
+    :adapter="adapter"
+    :autosave="{ enabled: true, delay: 5000 }"
+    :ui="{ explorerWidth: '320px', versionsWidth: '300px' }"
+    :theme="{ '--kindy-library-primary': '#0b74de' }"
+    locale="vi-VN"
+    style="height: 100vh"
+    @saved="onSaved"
+    @error="onError"
+  />
 </template>
 
-<script setup>
+<script setup lang="ts">
 import { ref } from 'vue'
-import { KindyEditor } from 'kindy-editor'
+import {
+  KindyDocumentLibrary,
+  createRestDocumentAdapter,
+} from 'kindy-editor'
 import 'kindy-editor/style'
 
-const editorRef = ref(null)
-const editorOptions = ref({
-  locale: 'vi-VN',
-  document: {
-    title: 'Tài liệu mới',
-    content: '<h1>Nội dung ban đầu</h1>',
-  },
+const workspace = ref()
+const adapter = createRestDocumentAdapter({
+  baseUrl: '/document-api',
+  transport: (url, init) => fetch(url, {
+    ...init,
+    credentials: 'include',
+    headers: { ...init?.headers, 'x-tenant-id': 'acme' },
+  }),
 })
+
+function onSaved(result: unknown) {
+  console.info('Saved', result)
+}
+
+function onError(error: unknown) {
+  console.error(error)
+}
 </script>
 ```
 
-### Cách 2: Đăng ký Global Vue Plugin (`main.js`)
+Server phải triển khai contract trong [`openapi/document-api.yaml`](./openapi/document-api.yaml). OpenAPI không bắt buộc cơ chế auth; cookie, bearer token hoặc API gateway do ứng dụng chủ quyết định.
 
-```javascript
-import { createApp } from 'vue'
-import App from './App.vue'
-import { useKindyEditor } from 'kindy-editor'
-import 'kindy-editor/style'
+### UI hợp đồng mặc định
 
-const app = createApp(App)
+`KindyDocumentLibrary` tự dùng `CONTRACT_EDITOR_OPTIONS`: toolbar một hàng theo hướng Google Docs, chỉ có Định dạng/Chèn/Bảng/Trang/Xuất, không có Web view, Mermaid, biểu đồ, media web hoặc chuyển đổi số tiếng Trung. Nhóm Xuất chỉ gọi pipeline an toàn của Document Library cho Import DOCX, Export DOCX và In/PDF. Thanh trạng thái chỉ còn `Trang X / Y`, số ký tự, zoom và ngôn ngữ.
 
-// Đăng ký toàn cục component <KindyEditor />
-app.use(useKindyEditor, {
-  locale: 'vi-VN',
-  theme: 'light',
-})
+Ứng dụng chủ vẫn có thể override rõ ràng qua `editorOptions`:
 
-app.mount('#app')
+```vue
+<KindyDocumentLibrary
+  :adapter="adapter"
+  :editor-options="{
+    toolbar: { menus: ['base', 'insert', 'table', 'page', 'export'] },
+    statusbar: { showLocale: false },
+  }"
+/>
 ```
 
-### Cách 3: Tích hợp SSR / Nuxt 3 (CommonJS Bundle)
+Để dùng preset với `KindyEditor` độc lập:
 
-```javascript
-// Nuxt 3 Plugin hoặc Client-only component
-import { KindyEditor } from 'kindy-editor' // Tự động resolve qua package.json "require"/"import"
-import 'kindy-editor/style'
-```
+```ts
+import { createContractEditorOptions } from 'kindy-editor'
 
-### Cách 4: Tích hợp qua CDN / Direct Script Tag (IIFE Bundle)
-
-```html
-<!DOCTYPE html>
-<html>
-<head>
-  <!-- 1. CSS -->
-  <link rel="stylesheet" href="https://unpkg.com/kindy-editor/dist/kindy-editor.css">
-  <!-- 2. Vue 3 -->
-  <script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
-  <!-- 3. Kindy Editor IIFE Bundle -->
-  <script src="https://unpkg.com/kindy-editor/dist/kindy-editor.iife.js"></script>
-</head>
-<body>
-  <div id="app">
-    <kindy-editor :locale="'vi-VN'"></kindy-editor>
-  </div>
-
-  <script>
-    const { createApp } = Vue;
-    const app = createApp({});
-    app.use(KindyEditor.useKindyEditor);
-    app.mount('#app');
-  </script>
-</body>
-### Cách 5: Tích hợp vào React.js & Next.js (Sử dụng `mountKindyEditor`)
-
-Hàm `mountKindyEditor` cho phép bạn gắn `kindy-editor` vào bất kỳ thẻ HTML nào trong React.js / Next.js / Angular / Svelte mà **không cần cài thêm bất kỳ thư viện phụ thuộc nào**:
-
-#### A. Trong React.js (Component Wrapper):
-
-```tsx
-import React, { useEffect, useRef } from 'react'
-import { mountKindyEditor } from 'kindy-editor'
-import 'kindy-editor/style'
+const editorOptions = createContractEditorOptions({ locale: 'vi-VN' })
+```
 
-export function KindyEditorReact(props) {
-  const containerRef = useRef(null)
+## Chạy demo không cần backend
 
-  useEffect(() => {
-    if (!containerRef.current) return
-    // Gắn Editor vào DOM container
-    const instance = mountKindyEditor(containerRef.current, props)
-    // Cleanup khi component bị unmount
-    return () => instance.unmount()
-  }, [])
+```ts
+import { createMemoryDocumentAdapter } from 'kindy-editor'
 
-  return <div ref={containerRef} style={{ width: '100%', height: '100vh' }} />
-}
+const adapter = createMemoryDocumentAdapter()
 ```
 
-#### B. Trong Next.js (App Router / Pages Router):
+`MemoryDocumentAdapter` chỉ dành cho demo và test; dữ liệu mất khi reload trang.
 
-Do trình biên tập tài liệu Rich Text phụ thuộc vào DOM trình duyệt (`window`, `document`), trong Next.js bạn cần nạp component dưới dạng Client Component với `next/dynamic` (`ssr: false`):
+Trong repository:
 
-```tsx
-'use client'
+```bash
+npm install
+npm run dev
+```
 
-import dynamic from 'next/dynamic'
+Mở `http://localhost:9000/kindy-editor`.
 
-// 1. Tắt SSR cho Editor component
-const KindyEditor = dynamic(
-  () => import('./KindyEditorReact').then((mod) => mod.KindyEditorReact),
-  { ssr: false }
-)
+## Dùng editor độc lập
 
-export default function DocumentPage() {
-  return (
-    <main style={{ height: '100vh' }}>
-      <KindyEditor locale="vi-VN" />
-    </main>
-  )
-}
+```vue
+<KindyEditor
+  ref="editor"
+  :document="{ content: initialState.content, assets: initialState.assets }"
+  :page="initialState.page"
+/>
 ```
 
----
+```ts
+const state = editor.value.getState()
+editor.value.setContent(nextContent)
+editor.value.setReadOnly(true)
+const printable = await editor.value.preparePrint()
+editor.value.print()
+```
 
-## 💬 Hướng dẫn & API Hệ thống Bình luận (Comments)
+Vanilla/React/Angular/Svelte có thể dùng mount helper:
 
-### 1. Cơ chế hoạt động
+```ts
+import { mountKindyEditor } from 'kindy-editor'
 
-Bình luận được lưu trực tiếp dưới dạng thẻ `span` chứa thuộc tính `data-comment` và `data-thread` trong tài liệu HTML/JSON:
+const mounted = mountKindyEditor('#editor', {
+  locale: 'vi-VN',
+  document: { content: initialState.content },
+})
 
-```html
-<span
-  data-comment="c1a2b3"
-  data-color="rgba(255, 213, 79, 0.4)"
-  data-thread='{"id":"c1a2b3","text":"Cần chỉnh sửa","replies":[]}'
-  class="kindy-comment"
->
-  Đoạn văn bản được bình luận
-</span>
+mounted.instance.setContent(nextState.content)
+mounted.instance.print()
+mounted.unmount()
 ```
 
-### 2. Các API tương tác với Bình luận
+V2.0 chưa có native React component; wrapper dùng Vue mount helper.
 
-Thông qua `ref` của component `<KindyEditor ref="editorRef" />`:
+## Dùng headless client
 
-```javascript
-// 1. Thêm bình luận cho vùng bôi đen hiện tại
-editorRef.value.addComment('Nội dung bình luận mới')
+Subpath `kindy-editor/core` không tải Vue UI:
 
-// 2. Thêm phản hồi (Reply) cho 1 bình luận
-editorRef.value.addReply(commentId, 'Nội dung phản hồi')
+```ts
+import {
+  createDocumentLibrary,
+  createRestDocumentAdapter,
+} from 'kindy-editor/core'
 
-// 3. Đánh dấu Đã giải quyết (Resolve) hoặc Mở lại
-editorRef.value.resolveComment(commentId, true) // true: Đã giải quyết, false: Mở lại
+const client = createDocumentLibrary({
+  adapter: createRestDocumentAdapter({ baseUrl: '/document-api' }),
+  autosave: { enabled: true, delay: 5000 },
+})
 
-// 4. Xóa bình luận
-editorRef.value.removeComment(commentId)
+const snapshot = await client.open('document-123')
+client.updateState(snapshot.state)
+await client.save('manual')
+```
 
-// 5. Tập trung con trỏ & cuộn màn hình tới vị trí bình luận
-editorRef.value.focusComment(commentId)
+`VERSION_CONFLICT` dừng autosave. SDK không tự merge hoặc ghi đè revision mới hơn:
 
-// 6. Lấy danh sách toàn bộ bình luận dưới dạng mảng Object
-const comments = editorRef.value.getComments()
+```ts
+client.on('save-failed', (error) => {
+  if (error.code === 'VERSION_CONFLICT') {
+    // Hiển thị lựa chọn reload hoặc lưu thành bản sao.
+  }
+})
+```
 
-// 7. Đếm tổng số bình luận
-const total = editorRef.value.getCommentCount()
+`kindy-editor/core` dùng được trong Node/SSR. Entry `kindy-editor` chứa Vue UI và
+các công cụ browser như cropper/print, vì vậy chỉ import nó trong bundle phía client.
 
-// 8. Ẩn / Hiện thanh Sidebar bình luận
-editorRef.value.toggleCommentSidebar(true) // true: hiện, false: ẩn
-```
+## Import và export DOCX
 
----
+```ts
+import { importDocxInWorker, exportDocx } from 'kindy-editor'
 
-## 🗄️ Hướng dẫn tích hợp Cơ sở dữ liệu (Database Integration)
+const imported = await importDocxInWorker(file, {
+  mode: 'best-effort',
+  profile: 'kindy-docx-v2.0',
+})
+if (imported.report.issues.length) {
+  // Hiển thị warning trước khi tiếp tục.
+}
 
-### Cách 1: Gộp chung vào Nội dung (Khuyên dùng - Đơn giản nhất)
+const output = await exportDocx(imported.state) // strict mặc định
+```
 
-Khi bạn lưu `content` thu được từ `onSave` hoặc `editorRef.value.getHTML()`, toàn bộ bình luận đã nằm sẵn bên trong thẻ `<span data-comment>`:
+UI workspace tự xử lý luồng xác nhận best-effort khi import hoặc download. API programmatic mặc định strict và ném `DOCX_UNSUPPORTED` nếu state có feature ngoài profile.
+Mặc định là v2.0. Chọn `kindy-docx-v2.1` cho sections/header/footer hoặc
+`kindy-docx-v2.2` cho comments/Track Changes sau khi integration đã chạy corpus tương ứng.
 
-- **Lưu DB**: Lưu chuỗi `content` vào cột `content TEXT` trong bảng `documents`.
-- **Đọc DB**: Truyền lại `content` vào `:options="{ document: { content: data.content } }"` ➔ Bình luận tự động hiển thị lại 100%.
+`POST /documents/import` phải lưu blob gốc và trả `DocumentRecord.originalSource` gồm `artifactId`, `revisionId`, `format: 'original-docx'` và `fileName`. Nhờ đó `KindyDocumentLibrary.downloadDocx()` trả đúng file gốc khi revision chưa đổi. URL artifact của REST backend phải là URL tải được (thường là signed URL); Memory adapter trả trực tiếp `Blob`.
 
-### Cách 2: Tách Bình luận ra Bảng Database riêng
+## Public components
 
-Nếu bạn muốn quản lý bình luận riêng trong bảng `comments` (để thông báo, phân quyền):
+| Export | Mục đích |
+|---|---|
+| `KindyDocumentLibrary` | Workspace hoàn chỉnh, kết nối adapter và điều phối state |
+| `KindyDocumentLibraryShell` | Layout ba vùng độc lập cho UI tùy biến |
+| `KindyDocumentExplorer` | List/search/folder/import/template độc lập |
+| `KindyEditor` | Editor độc lập |
+| `KindyVersionPanel` | Lịch sử version độc lập |
 
-```javascript
-const saveToBackend = async () => {
-  const htmlContent = editorRef.value.getHTML()
-  const commentsList = editorRef.value.getComments()
+## Events chuẩn
 
-  await fetch('/api/documents/save', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      docId: 'doc_123',
-      content: htmlContent,
-      comments: commentsList, // Danh sách mảng comment object
-    }),
-  })
-}
-```
+`ready`, `opened`, `changed`, `save-started`, `saved`, `save-failed`, `created`, `imported`, `compatibility-warning`, `version-restored`, `printed`, `error`.
 
----
+## Error codes
 
-## 🛠️ Lệnh phát triển (Development Commands)
+`DOCX_INVALID`, `DOCX_UNSUPPORTED`, `IMPORT_FAILED`, `EXPORT_FAILED`, `ADAPTER_ERROR`, `NETWORK_ERROR`, `VERSION_CONFLICT`, `DOCUMENT_NOT_FOUND`, `OPERATION_CANCELLED`.
 
-```bash
-# Cài đặt phụ thuộc
-npm install
+## Hiệu năng tài liệu dài
 
-# Chạy server phát triển (Dev server tại http://localhost:9000/kindy-editor)
-npm run dev
+Import parsing đã chạy ngoài main thread. Editor vẫn dùng một ProseMirror instance liên tục; pagination cache phép đo block và workspace gom state sync. Trên production preview cục bộ (Chrome 151, Apple M2/24GB, 40 mẫu), corpus 100 trang text mở khoảng 0,49 giây với typing p95 21,5ms; mixed mở khoảng 0,85 giây với typing p95 36,5ms. Pagination cached của hai corpus lần lượt khoảng 2,8ms và 3,7ms. Đây là regression baseline, không phải SLA cho mọi thiết bị. Corpus mixed 200 trang vẫn chỉ được xem là stress limit. Xem [Performance guide](./docs/performance.md) để biết phương pháp đo và giới hạn.
 
-# Đóng gói sản phẩm (Production build ra thư mục dist/)
-npm run build
+## Tài liệu
 
-# Định dạng code
-npm run format
-```
+- [Bắt đầu tích hợp](./docs/getting-started.md)
+- [UI engine, theme, responsive và slots](./docs/ui-engine.md)
+- [API reference](./docs/api-reference.md)
+- [Backend, security và adapter](./GUIDE.md)
+- [DOCX capability matrix](./CAPABILITIES.md)
+- [Performance và tài liệu 100 trang](./docs/performance.md)
+- [Migration v1 → v2](./MIGRATION.md)
+- [REST OpenAPI](./openapi/document-api.yaml)
 
----
+## Phát triển và kiểm thử
 
-## 📄 License & Credits
+```bash
+npm test
+npm run test:e2e
+npm run test:package
+npm run test:libreoffice # cần có soffice; CI tự cài LibreOffice
+npm run typecheck
+npm run lint:check
+npm run build
+```
 
-- Phát hành theo giấy phép [MIT License](./LICENSE).
-- Dựa trên mã nguồn gốc [Umo Editor](https://github.com/umodoc/editor) bởi đội ngũ umodoc.
-- Bản quyền thuộc về **Kindy** ([GitHub](https://github.com/hotienky)).
+License: MIT.