@coding01/docsjs 0.1.2 → 0.1.5

package/README.md

@@ -1,11 +1,21 @@
 # @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`
+[![npm version](https://img.shields.io/npm/v/@coding01/docsjs)](https://www.npmjs.com/package/@coding01/docsjs)
+[![npm downloads](https://img.shields.io/npm/dm/@coding01/docsjs)](https://www.npmjs.com/package/@coding01/docsjs)
+[![CI](https://github.com/fanly/docsjs/actions/workflows/ci.yml/badge.svg)](https://github.com/fanly/docsjs/actions/workflows/ci.yml)
+
+[中文文档](./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 +28,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 +48,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 +71,159 @@ 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`)
+- ✅ Table merge + nested table read-only fidelity (`vMerge/gridSpan`)
+- ✅ Table width mapping (`tblGrid/gridCol`, `tcW`)
+- ✅ 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
+- ✅ Footnotes / endnotes / comments / track changes read-only semantics
+- ✅ Comment range markers (`commentRangeStart/commentRangeEnd`)
+- ✅ Revision metadata markers (`id/author/date`)
+- ✅ Floating anchors (`wp:anchor`) v1 fidelity (position ref / overlap / layer / wrap distance markers)
+- ✅ Word table v1 fidelity (border model / cell spacing / table-layout mapping)
+- ✅ OMML / charts / SmartArt semantic fallback rendering (v1)
+- ✅ Automated fidelity benchmark v1 (golden corpus + CI trend artifacts)
+- ⏳ Floating anchor text-wrap collision fidelity (pixel-level)
+- ⏳ Word table auto layout parity with desktop Word
+- ⏳ OMML high-fidelity renderer (MathML/KaTeX pipeline)
+
+## 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)
+  - comment range markers and revision metadata attributes
+  - page break semantic markers (`w:br type=page`, `lastRenderedPageBreak`)
+  - table width mapping (`tblGrid/gridCol`, `tcW`)
+  - table border model / cell spacing / table-layout mapping
+  - OMML formula fallback rendering and chart/SmartArt semantic fallback
+- Added floating image MVP:
+  - anchor position mapping (`wp:anchor`)
+  - wrap mode markers (`square`, `tight`, `topAndBottom`, `none`)
+  - anchor layout metadata (`relativeFrom`, `behindDoc`, `allowOverlap`, `layoutInCell`, `relativeHeight`, `dist*`)
+- Added fidelity tooling:
+  - semantic stats collector
+  - fidelity score calculator
+  - baseline regression framework (config-driven)
+  - visual regression workflow scaffold (Playwright + diff artifacts)
+  - golden corpus benchmark + trend report workflow (`fidelity-benchmark.yml`)
+- 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
+npm run benchmark:fidelity
 ```
 
-## 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`
+
+### GitHub Packages (repo sidebar "Packages")
+
+Workflow: `.github/workflows/publish-github-packages.yml`
+
+- Trigger: push tag `v*.*.*` or manual run
+- Target registry: `https://npm.pkg.github.com`
+- Package name in GitHub Packages: `@fanly/docsjs`
+- Note: GitHub sidebar "Packages" only shows packages published to GitHub Packages, not npmjs
+
+## 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,204 @@
+# @coding01/docsjs
+
+面向 Web 的 Render-first Word 高保真导入组件。  
+目标是在粘贴或上传 `.docx` 时，尽可能无损保留 Word/WPS/Google Docs 的结构和版式。
+
+[![npm version](https://img.shields.io/npm/v/@coding01/docsjs)](https://www.npmjs.com/package/@coding01/docsjs)
+[![npm downloads](https://img.shields.io/npm/dm/@coding01/docsjs)](https://www.npmjs.com/package/@coding01/docsjs)
+[![CI](https://github.com/fanly/docsjs/actions/workflows/ci.yml/badge.svg)](https://github.com/fanly/docsjs/actions/workflows/ci.yml)
+
+[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`）
+- ✅ 表格合并与嵌套表格只读保真（`vMerge/gridSpan`）
+- ✅ 表格宽度映射（`tblGrid/gridCol`、`tcW`）
+- ✅ 图片关系映射（`rId -> media`）
+- ✅ 页面几何映射（页高、页边距、版心宽）
+- ✅ 运行时渲染修正（`mso-*` 兼容、分页 spacer、空段落修正）
+- ✅ 事件与公共 API
+- ✅ React/Vue 可运行示例
+- ✅ npm OIDC 自动发布流水线
+- ✅ 批注/脚注/修订只读语义支持
+- ✅ 批注区间标记（`commentRangeStart/commentRangeEnd`）
+- ✅ 修订元数据标记（`id/author/date`）
+- ✅ 浮动锚点对象 v1 保真（定位参照/层级/避让距离/重叠策略标记）
+- ✅ Word 表格 v1 保真（边框模型/单元格间距/布局类型映射）
+- ✅ OMML/图表/SmartArt 语义降级渲染（v1）
+- ✅ 自动化保真评分 v1（golden corpus + CI 趋势产物）
+- ⏳ 浮动对象文字绕排碰撞的像素级还原
+- ⏳ Word 表格自动布局与桌面 Word 深度一致
+- ⏳ OMML 高保真渲染（MathML/KaTeX 渲染链）
+
+## v0.1.3 更新内容
+
+- 深度 DOCX 语义增强：
+  - 编号覆盖（`lvlOverride/startOverride`）
+  - 合并单元格（`vMerge/gridSpan`）和嵌套表格
+  - 脚注与尾注（只读渲染）
+  - 批注（只读渲染）
+  - 修订新增/删除标记（只读渲染）
+  - 批注区间标记与修订元数据属性
+  - 分页语义标记（`w:br type=page`、`lastRenderedPageBreak`）
+  - 表格宽度映射（`tblGrid/gridCol`、`tcW`）
+  - 表格边框模型/单元格间距/布局类型映射
+  - OMML 公式降级渲染、图表/SmartArt 语义降级渲染
+- 浮动图片 MVP：
+  - 锚点定位（`wp:anchor`）
+  - 绕排模式标记（`square`、`tight`、`topAndBottom`、`none`）
+  - 锚点布局元数据（`relativeFrom`、`behindDoc`、`allowOverlap`、`layoutInCell`、`relativeHeight`、`dist*`）
+- 保真工具链增强：
+  - 语义统计器
+  - 保真评分器
+  - 配置驱动的基准回归测试框架
+  - 视觉回归工作流骨架（Playwright + diff artifacts）
+  - golden corpus 基准评分 + 趋势报告工作流（`fidelity-benchmark.yml`）
+- 工程质量门增强：
+  - ESLint + 严格 `verify`（`lint/typecheck/test/build/sizecheck`）
+  - CI 必过质量门
+  - 贡献规范 / 规则 / 深度开发计划文档
+- Demo 升级：
+  - React/Vue demo 支持中英文切换
+  - 组件内置工具栏文案随语言切换
+  - 语义统计面板新增浮动图/绕排图/批注/修订/分页断点等指标
+
+## 本地开发
+
+```bash
+npm install
+npm run typecheck
+npm run test
+npm run build
+npm run benchmark:fidelity
+```
+
+## 演示
+
+### 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)。
+
+## 发布与关联
+
+- npmjs 发布工作流：`.github/workflows/publish.yml`
+- GitHub Packages 发布工作流：`.github/workflows/publish-github-packages.yml`
+- GitHub 侧栏 `Packages` 只显示发布到 GitHub Packages 的包，不显示 npmjs 包
+- 当前 GitHub Packages 包名：`@fanly/docsjs`
+
+## 安全说明
+
+- 默认策略是保真优先，不主动清洗 Word 内联样式。
+- 生产环境建议宿主侧配置 CSP、iframe sandbox、上传白名单及可选清洗策略。
+
+## 打赏支持
+
+如果这个项目帮你节省了时间，欢迎打赏支持。
+
+![支持 docsjs](https://image.coding01.cn/Coding01%20%E8%B5%9E%E8%B5%8F%E7%A0%81.png)
+
+`“加个鸡腿💪(ﾟωﾟ💪)”`