kindy-editor 1.0.1 → 2.0.0

package/CAPABILITIES.md

@@ -0,0 +1,39 @@
+# Kindy DOCX Compatibility Matrix
+
+Chỉ đánh dấu “Supported” khi có automated fixture/test tương ứng. “Preview” là khả năng editor/browser, không phải Word layout engine.
+
+| Capability | v2.0 | Ghi chú |
+|---|---:|---|
+| Unicode/tiếng Việt | Supported | OOXML text round-trip test |
+| Bold/italic/underline/strike | Supported | Semantic marks |
+| Font, size, color | Supported | Basic `textStyle` mapping |
+| Paragraph alignment, line spacing, indent | Supported | Profile cơ bản |
+| Heading 1–6 | Supported | Word heading styles |
+| Bullet/number list | Supported | Numbering profile cơ bản |
+| Table, colspan, rowspan | Supported | `gridSpan` và vertical merge `vMerge` có round-trip test |
+| Inline/block image | Supported | DrawingML, VML và `mc:AlternateContent`; ưu tiên fallback browser-safe; ảnh import có `AssetReference` |
+| Hyperlink | Supported | External hyperlink |
+| Global page size/orientation/margins | Supported | Đơn vị canonical là cm |
+| Manual page break | Supported | Import tách thành semantic block `pageBreak`; editor chừa đúng phần trắng còn lại của trang |
+| Automatic page preview | Preview | Chừa phần còn lại của trang và page gap giữa các top-level block; status bar hiển thị/điều hướng `Trang hiện tại / tổng trang` |
+| OOXML validation/report | Supported | ZIP/content types/feature detection |
+| Browser print | Supported | Chromium visual regression cần chạy trong CI ứng dụng |
+| PDF Blob deterministic | Not supported | Dùng print/Save as PDF |
+| Multiple sections | Supported v2.1 | Stable `sectionBreak`, per-section size/orientation/margin/page-number metadata; pagination và print đổi geometry theo section. Editing canvas vẫn là một ProseMirror surface, không phải Word layout engine |
+| Header/footer sub-document | Supported v2.1 codec | Default/first/even, ảnh header và relationship parts có golden test; banner header được giữ tỷ lệ và lặp trong page preview |
+| Page-number variants | Supported v2.1 codec | Page-number start, different-first và odd/even header/footer trong profile |
+| Comments DOCX round-trip | Supported v2.2 | Range, thread, reply và resolved state qua comments/commentsExtended parts |
+| Track Changes DOCX round-trip | Supported v2.2 | `w:ins`/`w:del`, author/timestamp, insert/delete/replace transaction, accept/reject, undo/redo và table text có test |
+| Yjs realtime | Adapter available | Ứng dụng chủ cung cấp provider/server |
+| Floating image | Best effort | Chuyển thành inline image và báo `FLOATING_IMAGE_FLATTENED` |
+| EMF/WMF/TIFF, SmartArt, macros, equations | Not supported | Báo compatibility warning/best-effort |
+
+Automatic pagination là browser preview và có thể khác Word do font metrics, printer driver và Word layout rules. v2.0 không chèn page gap vào giữa một top-level node quá cao (ví dụ một bảng cao hơn một trang); node đó được hiển thị liên tục để không phá cấu trúc/selection. Print CSS cho phép browser ngắt theo hàng, nhưng vị trí có thể khác Word.
+
+Các profile v2.1/v2.2 là opt-in qua `profile` của codec hoặc `docxProfile` của workspace; mặc định vẫn là v2.0. Import có thể nhúng `PNG`, `JPEG`, `GIF`, `SVG`, `WebP`, `BMP` vào state. Serializer strict ghi trực tiếp `PNG`, `JPEG`, `GIF`, `BMP`; `SVG`, `WebP`, `EMF`, `WMF`, `TIFF` hoặc URL không xác định được liệt kê trong `CompatibilityReport` và cần chuyển đổi trước khi export.
+
+File vừa import, chưa chỉnh sửa có một đường tải riêng qua `DocumentRecord.originalSource`; SDK trả lại artifact `original-docx` nên giữ nguyên byte và mọi feature Word chưa hiểu. Sau revision chỉnh sửa đầu tiên, tài liệu được serialize từ JSON và bảng capability phía trên là giới hạn cam kết—không có bảo đảm 100% với toàn bộ OOXML.
+
+## Giới hạn hiệu năng v2.0
+
+Import parser chạy trong Web Worker, nhưng editing surface vẫn render document trong một ProseMirror instance liên tục. Compatibility “Supported” không đồng nghĩa mọi file 100–200 trang đều đạt cùng typing latency. Hệ thống tích hợp phải benchmark corpus thật theo [`docs/performance.md`](./docs/performance.md) trước khi đặt SLA.

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+## 2.0.0
+
+Breaking release chuyển Kindy Editor thành DOCX Document Library SDK.
+
+### Added
+
+- `KindyDocumentState` v2 làm canonical editing state.
+- `DocumentLibraryClient` và `DocumentApiAdapter` contract.
+- REST, Memory và legacy callback adapters.
+- `KindyDocumentLibrary`, `KindyDocumentExplorer`, `KindyVersionPanel`.
+- Responsive `KindyDocumentLibraryShell`, theme tokens và locale message contract.
+- Autosave có debounce/cancellation và optimistic concurrency.
+- Version preview read-only, restore và workspace status UI.
+- DOCX import Worker, compatibility report và OOXML export thật.
+- Browser print/Save as PDF flow.
+- OpenAPI contract và REST mock transport.
+- Tiptap engine adapter và Yjs collaboration adapter boundary.
+- Compatibility profiles v2.1 cho section/header/footer/page numbering và v2.2 cho comments/Track Changes.
+- Section-aware pagination/print, header/footer variants và Yjs workspace lifecycle.
+- Corpus benchmark text/mixed 100–200 trang và measurement cache theo block.
+- Playwright E2E production cho import/edit/autosave/version/restore/export/print và benchmark 100 trang.
+- LibreOffice headless golden gate xác nhận DOCX v2.2 mở/convert PDF không yêu cầu repair.
+- Packed-consumer smoke test cho ESM core, Vue UI, stylesheet và relative DOCX Worker URL.
+- Reproducible npm lockfile và CI dùng `npm ci` trên cả unit, LibreOffice và browser E2E jobs.
+
+### Changed
+
+- Vue 3/Tiptap vẫn là UI/editor engine mặc định.
+- HTML không còn là state lưu trữ dài hạn.
+- PDF API là `preparePrint()`/`print()`, không phải deterministic PDF Blob.
+- DOCX fidelity được định nghĩa theo Kindy Compatibility Profile.
+- Track Changes ghi nhận insert/delete/replace transaction, kể cả lệnh xóa từ API/toolbar.
+- State sync mặc định 300ms; demo autosave 5 giây để tránh chặn input trên tài liệu dài.
+- Loại dependency runtime `@umoteam/editor-external` không sử dụng và thay SVG build plugin bằng sprite generator nội bộ.
+- Dependency audit đầy đủ không còn advisory tại thời điểm chốt release candidate local.
+
+### Fixed
+
+- Print iframe trước đây có thể rỗng do gán sai Vue ref.
+- Find/Replace, TOC, scroll page tracking và trạng thái before-unload dùng đúng Vue ref.
+- Ảnh DOCX body/header, section break, page geometry và metadata numbering được round-trip theo profile.
+- Bộ đếm ký tự cập nhật reactive; mở document không còn tạo dirty/autosave giả.
+- `KindyEditor.getState()` giữ assets, sections và header/footer variants.
+- ESM entry không còn import CSS ngầm; ứng dụng import `kindy-editor/style` đúng một lần như public guide. Node/SSR dùng subpath `kindy-editor/core`.
+- DOCX Worker trong package resolve tương đối theo `import.meta.url`, không còn hard-code base path của demo `/kindy-editor/`.
+
+### Removed from public promise
+
+- Backend/storage/auth tích hợp sẵn.
+- API v1 đầy đủ.
+- HTML Blob giả đuôi `.docx`.
+- AI/collaboration/IO placeholder chưa hoàn thiện trong public build.
+
+Xem [Migration v1 → v2](./MIGRATION.md).

package/GUIDE.md

@@ -0,0 +1,190 @@
+# Hướng dẫn tích hợp Document Library SDK v2
+
+## 1. Ranh giới trách nhiệm
+
+Kindy SDK chịu trách nhiệm:
+
+- Hiển thị responsive `DocumentLibraryShell`, Explorer, Editor và VersionPanel.
+- Chuẩn hóa trạng thái UI `idle/dirty/saving/saved/read-only/preview/conflict/error`.
+- Chuyển DOCX thuộc compatibility profile sang ProseMirror JSON.
+- Validate OOXML, báo feature ngoài profile và export OOXML DOCX thật.
+- Debounce autosave, cancellation, event và optimistic concurrency.
+- Chuẩn hóa API client, REST adapter và error codes.
+
+Server ứng dụng chủ chịu trách nhiệm:
+
+- User, authentication, authorization và tenant isolation.
+- Database metadata, object storage, retention, backup và audit log.
+- Sinh revision/version bền vững, chống ghi đè đồng thời.
+- Malware scanning, quota, rate limiting và signed URL nếu sử dụng.
+- Yjs provider/WebSocket server nếu bật realtime.
+
+## 1.1. UI engine và lifecycle
+
+`KindyDocumentLibrary` là orchestration component; `KindyDocumentLibraryShell` chỉ làm layout. Luồng mở tài liệu chuẩn:
+
+```text
+Explorer open event
+  → client.open(documentId)
+  → adapter.loadState
+  → migrate KindyDocumentState
+  → mount KindyEditor
+  → apply capabilities.edit
+  → ready/opened events
+```
+
+Không để Explorer, toolbar tùy biến hoặc application component ghi thẳng storage. Mọi save/version/artifact phải đi qua workspace handle, `DocumentLibraryClient` hoặc adapter để giữ `baseRevisionId` và event semantics.
+
+Khi preview một version cũ, workspace chỉ load snapshot read-only và giữ live snapshot riêng. Chỉ `restoreVersion` mới thay state hiện hành ở backend. Chi tiết UI, slots và theme nằm tại [`docs/ui-engine.md`](./docs/ui-engine.md).
+
+Workspace mặc định dùng preset `Contract`: page-only, toolbar compact và loại toàn bộ công cụ web/diagram/chuyển đổi tiếng Trung. Không cần truyền cấu hình để có giao diện này. Chỉ dùng `editorOptions` khi ứng dụng chủ chủ động mở rộng UI; xem [`docs/ui-engine.md`](./docs/ui-engine.md#preset-contract-mặc-định).
+
+## 2. Dữ liệu lưu trên server
+
+Một triển khai tối thiểu thường có:
+
+```text
+documents
+  id, title, file_name, folder_id, tags, metadata
+  current_revision_id, current_version_id, created_at, updated_at
+
+document_revisions
+  id, document_id, base_revision_id, state_json, reason
+  client_mutation_id (unique per document), created_at, created_by
+
+document_versions
+  id, document_id, revision_id, number, label, created_at, created_by
+
+document_artifacts
+  id, document_id, version_id, format, object_key
+  file_name, mime_type, size, checksum, created_at
+
+folders
+  id, parent_id, name
+```
+
+`state_json` là `KindyDocumentState`. Không dùng HTML làm state lâu dài. Artifact `original-docx` phải giữ nguyên bytes người dùng upload; artifact `docx` là output của serializer. Record import phải liên kết artifact gốc với revision đầu tiên:
+
+```json
+{
+  "originalSource": {
+    "artifactId": "artifact-original-1",
+    "revisionId": "rev-import-1",
+    "format": "original-docx",
+    "fileName": "hop-dong.docx"
+  }
+}
+```
+
+## 3. Save và conflict
+
+`PUT /documents/{id}/state` nhận:
+
+```json
+{
+  "state": { "schemaVersion": "2.0", "content": {}, "page": {}, "assets": [] },
+  "baseRevisionId": "rev-10",
+  "reason": "autosave",
+  "clientMutationId": "70f8..."
+}
+```
+
+Transaction phía server:
+
+1. Lock hoặc compare-and-swap document.
+2. Nếu `current_revision_id !== baseRevisionId`, trả HTTP 409 với code `VERSION_CONFLICT`.
+3. Nếu `clientMutationId` đã xử lý, trả lại kết quả cũ (idempotency).
+4. Ghi revision mới và cập nhật `current_revision_id` atomically.
+5. Với manual save, có thể tạo version bền vững và trả trong `version`.
+
+SDK dừng autosave sau conflict. Ứng dụng chủ phải cho người dùng reload hoặc tạo document copy; không nên tự merge âm thầm.
+
+## 4. Import DOCX
+
+```text
+File input
+  → Worker validate ZIP/OOXML
+  → compatibility report
+  → semantic conversion
+  → người dùng xác nhận warning
+  → POST /documents/import (original file + JSON + report)
+```
+
+Response của `/documents/import` phải có `originalSource`. Nếu người dùng tải xuống khi current revision vẫn bằng `originalSource.revisionId`, workspace dùng artifact gốc nên kết quả byte-for-byte giống file upload. Sau khi state đã được save thành revision mới, workspace dùng serializer và áp dụng compatibility profile; không được quảng bá đây là Word-fidelity 100%.
+
+Các guard server vẫn bắt buộc dù client đã validate:
+
+- Extension, MIME, magic bytes và OOXML content types.
+- Giới hạn compressed size, uncompressed size, số ZIP entry và compression ratio.
+- Từ chối encrypted/password-protected package.
+- Virus/malware scanning.
+- Không tin file name hoặc URL do client gửi.
+
+## 5. Export DOCX và print/PDF
+
+`exportDocx(state)` mặc định strict. Khi có node ngoài profile, hàm ném `DOCX_UNSUPPORTED`. UI có thể hiển thị report rồi gọi lại `{ mode: 'best-effort' }` sau khi người dùng xác nhận.
+
+Profile mặc định là `kindy-docx-v2.0`. Dùng `{ profile: 'kindy-docx-v2.1' }`
+cho sections/header/footer và `kindy-docx-v2.2` cho comments/Track Changes.
+Workspace nhận prop `docxProfile` tương ứng; không tự nâng profile âm thầm.
+
+DOCX output là ZIP/OOXML từ package `docx`; test phải kiểm tra `word/document.xml` và mở qua LibreOffice/Word mà không repair.
+
+Ảnh import hỗ trợ DrawingML, VML và `mc:AlternateContent` có fallback render được. Browser có thể hiển thị PNG/JPEG/GIF/SVG/WebP/BMP, nhưng serializer DOCX strict chỉ ghi trực tiếp PNG/JPEG/GIF/BMP. SVG/WebP, EMF/WMF/TIFF và nguồn ảnh không xác định phải sinh compatibility warning hoặc được hệ thống chủ chuyển đổi trước khi export.
+
+PDF v2.0:
+
+```ts
+await workspace.preparePrint()
+workspace.print()
+```
+
+Nếu hệ thống cần PDF Blob deterministic hoặc render server-side, đó là service của ứng dụng chủ và nằm ngoài runtime browser của SDK.
+
+## 6. Auth và transport
+
+```ts
+const adapter = createRestDocumentAdapter({
+  baseUrl: '/document-api',
+  transport: async (url, init) => fetch(url, {
+    ...init,
+    credentials: 'include',
+    headers: {
+      ...init?.headers,
+      Authorization: `Bearer ${await getAccessToken()}`,
+    },
+  }),
+})
+```
+
+Không đưa access token vào Kindy state, asset metadata, localStorage hoặc log. Backend phải kiểm tra quyền trên từng document/artifact/version; quyền UI chỉ giúp ẩn thao tác, không phải security boundary.
+
+## 7. Audit
+
+Audit phía server tối thiểu gồm: actor, tenant, document, action, revision/version, timestamp, result, IP/request ID và client mutation ID. Không log toàn bộ nội dung hợp đồng hay token. Các action quan trọng: import, view, save, export, artifact download, restore, permission denied và conflict.
+
+## 8. Realtime
+
+`YjsCollaborationAdapter` chỉ nhận `providerFactory`:
+
+```ts
+const collaboration = createYjsCollaborationAdapter({
+  providerFactory: ({ documentId, user, editor }) => createCompanyYjsProvider({ documentId, user, editor }),
+})
+```
+
+SDK không tạo WebSocket URL và không ship server. Provider phải xử lý auth, reconnect, awareness và document isolation.
+
+## 9. Contract test
+
+Chạy cùng một test suite với Memory adapter, REST mock và adapter thật. Tối thiểu kiểm tra create → load → save → conflict → versions → restore → artifact. OpenAPI không quy định auth bắt buộc để không khóa kiến trúc của hệ thống tích hợp.
+
+## 10. Production checklist
+
+- Chạy `npm run typecheck`, `npm test` và `npm run build` với đúng package lock.
+- Validate OpenAPI implementation bằng contract test.
+- Kiểm tra permission ở backend, không chỉ dựa vào `document.capabilities` trên UI.
+- Test import/export bằng golden DOCX corpus và Microsoft Word/LibreOffice.
+- Test responsive layout và keyboard navigation sau khi override theme.
+- Benchmark corpus 100 trang của hệ thống theo [`docs/performance.md`](./docs/performance.md).
+- Thiết lập backup/restore object storage và database; SDK không thực hiện backup.

package/MIGRATION.md

@@ -0,0 +1,46 @@
+# Migration v1 → v2
+
+v2 là breaking release.
+
+## State
+
+V1 thường lưu HTML hoặc raw ProseMirror JSON. V2 lưu:
+
+```ts
+const state = migrateDocumentState(rawProseMirrorJson)
+// { schemaVersion: '2.0', content, page, assets }
+```
+
+SDK tự migrate lúc mở; server chỉ ghi state mới sau lần save kế tiếp.
+
+## Save callback
+
+Khuyến nghị thay `onSave`/`onFileUpload` bằng `DocumentApiAdapter`. Giai đoạn chuyển tiếp:
+
+```ts
+const adapter = createLegacyCallbackAdapter({
+  async onSave({ state }) {
+    await oldSaveEndpoint(state)
+  },
+})
+```
+
+Legacy adapter phục vụ migration, không mô phỏng đầy đủ backend/versioning v1.
+
+## DOCX
+
+V1 Word toolbar tạo HTML Blob mang đuôi `.docx`. V2 tạo ZIP/OOXML thật bằng `exportDocx`. Import state không còn lấy HTML layout từ `docx-preview`; `docx-preview` không phải canonical converter.
+
+## PDF
+
+Xóa mọi code kỳ vọng `exportPdf()` trả Blob. Dùng `preparePrint()` và `print()`.
+
+## Mount helper
+
+```ts
+const { app, instance, unmount } = mountKindyEditor(element, options)
+instance.getState()
+```
+
+V2 trả thêm `instance` là editor handle.
+