@coding01/docsjs 0.1.0 → 0.1.3

package/README.md

@@ -1,11 +1,17 @@
 # @coding01/docsjs
 
-`@coding01/docsjs` 是一个 Render-first 的 Word 高保真组件，目标是把 Word/WPS/Google Docs 内容以“先渲染、后编辑”的方式无损导入到 Web 端。
+Render-first Word fidelity component for the web.  
+Import Word/WPS/Google Docs content from paste or `.docx` while preserving structure and layout as much as possible.
 
-当前提供：
-- Web Component 内核：`docs-word-editor`
-- React 适配组件：`WordFidelityEditorReact`
-- Vue 适配组件：`WordFidelityEditorVue`
+[中文文档](./README.zh-CN.md)
+
+## What You Get
+
+- Web Component core: `docs-word-editor`
+- React adapter: `WordFidelityEditorReact`
+- Vue adapter: `WordFidelityEditorVue`
+- Import pipeline: clipboard paste + `.docx` upload
+- HTML snapshot output for downstream rendering/storage
 
 ## Installation
 
@@ -18,17 +24,13 @@ npm i @coding01/docsjs
 ### React
 
 ```tsx
-import { WordFidelityEditorReact } from "@coding01/docsjs";
+import { WordFidelityEditorReact } from "@coding01/docsjs/react";
 
 export default function Page() {
   return (
     <WordFidelityEditorReact
-      onChange={(payload) => {
-        console.log(payload.htmlSnapshot);
-      }}
-      onError={(payload) => {
-        console.error(payload.message);
-      }}
+      onChange={(payload) => console.log(payload.htmlSnapshot)}
+      onError={(payload) => console.error(payload.message)}
     />
   );
 }
@@ -42,19 +44,13 @@ export default function Page() {
 </template>
 
 <script setup lang="ts">
-import { WordFidelityEditorVue } from "@coding01/docsjs";
-
-const onChange = (payload: { htmlSnapshot: string }) => {
-  console.log(payload.htmlSnapshot);
-};
-
-const onError = (payload: { message: string }) => {
-  console.error(payload.message);
-};
+import { WordFidelityEditorVue } from "@coding01/docsjs/vue";
+const onChange = (payload: { htmlSnapshot: string }) => console.log(payload.htmlSnapshot);
+const onError = (payload: { message: string }) => console.error(payload.message);
 </script>
 ```
 
-### Web Component (Vanilla)
+### Web Component
 
 ```ts
 import { defineDocsWordElement } from "@coding01/docsjs";
@@ -71,102 +67,136 @@ el.addEventListener("docsjs-change", (e) => {
 
 ## API
 
-### Component Events
+### Events
 
 - `docsjs-change`
-  - payload: `{ htmlSnapshot: string }`
-  - 触发时机：粘贴、上传 Word、手动 `setSnapshot`、`clear`
+  - payload: `{ htmlSnapshot: string; source: "paste" | "upload" | "api" | "clear"; fileName?: string }`
 - `docsjs-error`
   - payload: `{ message: string }`
-  - 触发时机：剪贴板读取失败、DOCX 解析失败等
+- `docsjs-ready`
+  - payload: `{ version: string }`
 
-### Web Component Methods
+### Methods
 
-- `setSnapshot(rawHtml: string): void`
-  - 将外部 HTML 快照注入渲染层
+- `loadHtml(rawHtml: string): void`
+- `loadDocx(file: File): Promise<void>`
+- `loadClipboard(): Promise<void>`
+- `getSnapshot(): string`
 - `clear(): void`
-  - 清空当前文档
-
-## Semantic Coverage
-
-下表描述“语义与格式覆盖”当前状态。
-
-### Completed
-
-- 输入链路
-  - 粘贴：Word / WPS / Google Docs HTML
-  - 上传：`.docx` 文件解析并渲染
-- 页面模型
-  - A4 页高/页边距/版心宽度映射
-- 段落语义
-  - 对齐、段前段后、行距（`auto` / `exact` / `atLeast`）
-  - 缩进（left/right/firstLine/hanging）
-  - keep 规则（`keepNext` / `keepLines` / `pageBreakBefore` / `lastRenderedPageBreak`）
-- Run 语义
-  - 字号、字体、颜色、粗体、斜体、下划线、删除线
-  - 高亮、底纹、上下标、字距、阴影
-- 列表语义
-  - 多级编号（`numId` + `ilvl`）
-  - `numFmt` 和 `lvlText` 模板（如 `%1.%2.`）
-  - section break 计数重置
-- 表格语义
-  - `table/tr/td` 结构保留
-  - 单元格段落保留与边框/基础 padding 映射
-- 图片语义
-  - 提取关系映射（`rId -> media`）
-  - `wp:extent` 尺寸映射为像素（稳定布局）
-
-### In Progress / Not Completed
-
-- 复杂 Word 对象
-  - 浮动锚点对象（复杂 `wp:anchor`）
-  - 图表、SmartArt、公式（OMML）深层渲染
-- 文档语义高级能力
-  - Track Changes / Comments / Footnotes / Endnotes
-  - 域代码（目录、页码域）刷新
-- 分页精度
-  - widow/orphan 规则完整覆盖
-  - 跨页表格与复杂 keep 组合场景
-- 编辑能力
-  - 当前提供的是渲染导入组件，完整富文本编辑工具栏与协同编辑仍在规划中
-
-## Build & Local Develop
+
+### Attributes
+
+- `lang="zh|en"`
+- `show-toolbar="true|false|1|0"`
+
+## Feature Checklist
+
+- ✅ Web Component core (`docs-word-editor`)
+- ✅ React adapter (`@coding01/docsjs/react`)
+- ✅ Vue adapter (`@coding01/docsjs/vue`)
+- ✅ Paste import (`text/html`, `text/plain`)
+- ✅ Clipboard image hydration (`file:/blob:/cid:/mhtml:` to data URL)
+- ✅ `.docx` upload and parse
+- ✅ Basic paragraph semantics (alignment, headings, line break)
+- ✅ Basic run styles (bold/italic/underline/strike/color/highlight/super/sub)
+- ✅ List reconstruction (`numId` + `ilvl` + `lvlText`)
+- ✅ Basic table structure (`table/tr/td`)
+- ✅ Embedded image relationship mapping (`rId -> media`)
+- ✅ Page geometry mapping (page height, margins, content width)
+- ✅ Runtime render fixes (`mso-*` compatibility, pagination spacer, empty paragraph normalization)
+- ✅ Events and public methods
+- ✅ React and Vue runnable demos
+- ✅ npm publish workflow with OIDC trusted publishing
+- ⏳ Floating anchors (`wp:anchor`) full layout fidelity
+- ⏳ Merged cells / nested tables full fidelity
+- ⏳ Footnotes / endnotes / comments / track changes
+- ⏳ OMML / charts / SmartArt
+- ⏳ Automated fidelity benchmark scorecard
+
+## What's New in v0.1.3
+
+- Added deep DOCX semantics:
+  - numbering overrides (`lvlOverride/startOverride`)
+  - merged cells (`vMerge/gridSpan`) and nested tables
+  - footnotes and endnotes (read-only rendering)
+  - comments (read-only rendering)
+  - revisions insert/delete markers (read-only rendering)
+  - page break semantic markers (`w:br type=page`, `lastRenderedPageBreak`)
+- Added floating image MVP:
+  - anchor position mapping (`wp:anchor`)
+  - wrap mode markers (`square`, `tight`, `topAndBottom`, `none`)
+- Added fidelity tooling:
+  - semantic stats collector
+  - fidelity score calculator
+  - baseline regression framework (config-driven)
+  - visual regression workflow scaffold (Playwright + diff artifacts)
+- Added engineering quality gates:
+  - ESLint + strict verify pipeline (`lint`, `typecheck`, `test`, `build`, `sizecheck`)
+  - CI workflow for mandatory quality checks
+  - contribution/rules/deep-plan docs
+- Demo upgrades:
+  - React and Vue demos now include bilingual toggle (`zh` / `en`)
+  - component inner toolbar language follows selected locale
+  - semantic dashboard expanded with new indicators (anchor/wrap/comments/revisions/page-break)
+
+## Development
 
 ```bash
 npm install
 npm run typecheck
+npm run test
 npm run build
 ```
 
-## Publish to npm
+## Demos
 
-### Manual publish
+### React demo
 
 ```bash
-npm login
-npm version patch
-git push origin main --tags
-npm publish --access public
+cd demos/react-demo
+npm install
+npm run dev
 ```
 
-### GitHub Actions auto publish
+### Vue demo
 
-This repo includes `.github/workflows/publish.yml`:
-- Trigger: push tag `v*.*.*`
-- Steps: `npm ci` -> `typecheck` -> `build` -> `npm publish`
+```bash
+cd demos/vue-demo
+npm install
+npm run dev
+```
 
-Trusted Publishing (recommended):
-- No long-lived `NPM_TOKEN` secret required
-- Uses GitHub OIDC (`id-token: write`) to publish
+## Publishing
 
-Release flow:
+### Manual
 
 ```bash
+npm login
 npm version patch
 git push origin main --follow-tags
+npm publish --access public
 ```
 
+### GitHub Actions
+
+Workflow: `.github/workflows/publish.yml`
+
+- Trigger: push tag `v*.*.*`
+- Steps: `npm ci` -> `npm run typecheck` -> `npm run build` -> `npm publish --provenance`
+
+## Roadmap
+
+See [ROADMAP.md](./ROADMAP.md) for prioritized execution plan (P0/P1/P2) and acceptance criteria.
+
 ## Security Notes
 
-- 本组件默认不清洗 Word 内联样式（保真优先）。
-- 生产环境请在宿主应用侧配置 CSP、iframe sandbox 和上传白名单策略。
+- Default mode is fidelity-first and keeps Word inline styles.
+- In production, configure CSP, iframe sandbox, file upload allowlist, and optional host-side sanitization.
+
+## Support This Project
+
+If this project saves your time, a small tip is appreciated.
+
+![Support docsjs](https://image.coding01.cn/Coding01%20%E8%B5%9E%E8%B5%8F%E7%A0%81.png)
+
+`“加个鸡腿💪(ﾟωﾟ💪)”`

package/README.zh-CN.md

@@ -0,0 +1,179 @@
+# @coding01/docsjs
+
+面向 Web 的 Render-first Word 高保真导入组件。  
+目标是在粘贴或上传 `.docx` 时，尽可能无损保留 Word/WPS/Google Docs 的结构和版式。
+
+[English README](./README.md)
+
+## 核心能力
+
+- Web Component 内核：`docs-word-editor`
+- React 适配：`WordFidelityEditorReact`
+- Vue 适配：`WordFidelityEditorVue`
+- 导入链路：剪贴板粘贴 + `.docx` 上传
+- 输出：完整 HTML Snapshot，便于后续渲染与存储
+
+## 安装
+
+```bash
+npm i @coding01/docsjs
+```
+
+## 快速开始
+
+### React
+
+```tsx
+import { WordFidelityEditorReact } from "@coding01/docsjs/react";
+
+export default function Page() {
+  return (
+    <WordFidelityEditorReact
+      onChange={(payload) => console.log(payload.htmlSnapshot)}
+      onError={(payload) => console.error(payload.message)}
+    />
+  );
+}
+```
+
+### Vue
+
+```vue
+<template>
+  <WordFidelityEditorVue @change="onChange" @error="onError" />
+</template>
+
+<script setup lang="ts">
+import { WordFidelityEditorVue } from "@coding01/docsjs/vue";
+const onChange = (payload: { htmlSnapshot: string }) => console.log(payload.htmlSnapshot);
+const onError = (payload: { message: string }) => console.error(payload.message);
+</script>
+```
+
+### Web Component
+
+```ts
+import { defineDocsWordElement } from "@coding01/docsjs";
+
+defineDocsWordElement();
+const el = document.createElement("docs-word-editor");
+document.body.appendChild(el);
+```
+
+## API
+
+### 事件
+
+- `docsjs-change`
+  - payload: `{ htmlSnapshot: string; source: "paste" | "upload" | "api" | "clear"; fileName?: string }`
+- `docsjs-error`
+  - payload: `{ message: string }`
+- `docsjs-ready`
+  - payload: `{ version: string }`
+
+### 方法
+
+- `loadHtml(rawHtml: string): void`
+- `loadDocx(file: File): Promise<void>`
+- `loadClipboard(): Promise<void>`
+- `getSnapshot(): string`
+- `clear(): void`
+
+### 属性
+
+- `lang="zh|en"`
+- `show-toolbar="true|false|1|0"`
+
+## 功能清单
+
+- ✅ Web Component 内核（`docs-word-editor`）
+- ✅ React 适配（`@coding01/docsjs/react`）
+- ✅ Vue 适配（`@coding01/docsjs/vue`）
+- ✅ 粘贴导入（`text/html`、`text/plain`）
+- ✅ 剪贴板不稳定图片源替换（`file:/blob:/cid:/mhtml:` -> data URL）
+- ✅ `.docx` 上传解析
+- ✅ 段落基础语义（对齐、标题映射、换行）
+- ✅ Run 基础样式（粗斜体、下划线、删除线、颜色、高亮、上下标）
+- ✅ 列表基础恢复（`numId` + `ilvl` + `lvlText`）
+- ✅ 表格基础结构（`table/tr/td`）
+- ✅ 图片关系映射（`rId -> media`）
+- ✅ 页面几何映射（页高、页边距、版心宽）
+- ✅ 运行时渲染修正（`mso-*` 兼容、分页 spacer、空段落修正）
+- ✅ 事件与公共 API
+- ✅ React/Vue 可运行示例
+- ✅ npm OIDC 自动发布流水线
+- ⏳ 浮动锚点对象（`wp:anchor`）完整还原
+- ⏳ 合并单元格/嵌套表格完整还原
+- ⏳ 批注/脚注/修订等高级语义
+- ⏳ OMML/图表/SmartArt
+- ⏳ 自动化保真评分体系
+
+## v0.1.3 更新内容
+
+- 深度 DOCX 语义增强：
+  - 编号覆盖（`lvlOverride/startOverride`）
+  - 合并单元格（`vMerge/gridSpan`）和嵌套表格
+  - 脚注与尾注（只读渲染）
+  - 批注（只读渲染）
+  - 修订新增/删除标记（只读渲染）
+  - 分页语义标记（`w:br type=page`、`lastRenderedPageBreak`）
+- 浮动图片 MVP：
+  - 锚点定位（`wp:anchor`）
+  - 绕排模式标记（`square`、`tight`、`topAndBottom`、`none`）
+- 保真工具链增强：
+  - 语义统计器
+  - 保真评分器
+  - 配置驱动的基准回归测试框架
+  - 视觉回归工作流骨架（Playwright + diff artifacts）
+- 工程质量门增强：
+  - ESLint + 严格 `verify`（`lint/typecheck/test/build/sizecheck`）
+  - CI 必过质量门
+  - 贡献规范 / 规则 / 深度开发计划文档
+- Demo 升级：
+  - React/Vue demo 支持中英文切换
+  - 组件内置工具栏文案随语言切换
+  - 语义统计面板新增浮动图/绕排图/批注/修订/分页断点等指标
+
+## 本地开发
+
+```bash
+npm install
+npm run typecheck
+npm run test
+npm run build
+```
+
+## 演示
+
+### React demo
+
+```bash
+cd demos/react-demo
+npm install
+npm run dev
+```
+
+### Vue demo
+
+```bash
+cd demos/vue-demo
+npm install
+npm run dev
+```
+
+## 路线图
+
+执行优先级与验收标准见 [ROADMAP.md](./ROADMAP.md)。
+
+## 安全说明
+
+- 默认策略是保真优先，不主动清洗 Word 内联样式。
+- 生产环境建议宿主侧配置 CSP、iframe sandbox、上传白名单及可选清洗策略。
+
+## 打赏支持
+
+如果这个项目帮你节省了时间，欢迎打赏支持。
+
+![支持 docsjs](https://image.coding01.cn/Coding01%20%E8%B5%9E%E8%B5%8F%E7%A0%81.png)
+
+`“加个鸡腿💪(ﾟωﾟ💪)”`