weifuwu 0.85.0 → 0.86.0

package/docs/components.md

@@ -2,7 +2,7 @@
 
 > 本页为 weifuwu 官方文档拆分页 · [返回 README](../README.md)
 
-115 个 HTML 原语组件。每个是 `async (initProps, ctx) => (props) => Promise<VNode>`（两阶段组件，与前端框架同一模型——外层工厂 + 内层 renderFn 强制异步），引用 `--wf-*` CSS 变量做主题。另含 `confirm()` / `toast()` 命令式中间件。
+118 个 HTML 原语组件。每个是 `async (initProps, ctx) => (props) => Promise<VNode>`（两阶段组件，与前端框架同一模型——外层工厂 + 内层 renderFn 强制异步），引用 `--wf-*` CSS 变量做主题。另含 `confirm()` / `toast()` 命令式中间件。
 
 > **组件速查（weifuwu 组件 ↔ antd / Element Plus / shadcn-ui 对应 + 迁移示例）**：见 [`docs/components-map.md`](components-map.md)——从其他组件库迁来的开发者按功能直接找对应组件。
 > **自定义组件开发**：见 [docs/custom-components.md](custom-components.md)——usePopup/useControlled/对话框/AI 组件/类型纪律逐步指南。
@@ -634,7 +634,129 @@ props 变化 ──────────────────────
 |-----|--------|-----------|------|
 | Chart | `Chart` | `type: ChartType`, `data`, `options`, `title`, `area` | SVG 图表（line/bar/pie）|
 | DatePicker | `DatePicker` | `mode: DatePickerMode`, `value`, `onChange`, `placeholder`, `disabled` | 日期选择器（date/datetime/time/range）|
-| Editor | `Editor` | `value`, `onChange`, `toolbar`, `placeholder`, `disabled` | 富文本编辑器，零依赖 |
+| Editor | `Editor` | `value`, `onChange`, `toolbar`, `placeholder`, `disabled`, `ai?` | 富文本编辑器（事件流事务层：撤销/重做/时光机；AI 协作可选） |
+| FilePreview | `FilePreview` | `type`, `content?`, `url?`, `editable?`, `ai?`, `onSave?` | 文件预览（md/html/pdf/office/text）——基于事件流，md/text 可编辑 |
+
+### Editor（富文本编辑器 + AI 协作）
+
+基于 contentEditable 的富文本编辑器，**事件流事务层**：语义操作（格式/链接/图片/表格/AI 替换）→ `edit:commit`（before 快照 + 事件）→ 撤销/重做/时光机精确到任意版本。
+
+```tsx
+import { Editor } from 'weifuwu/components'
+
+<Editor value={html} onChange={v => setHtml(v)} placeholder="输入内容..." />
+```
+
+**Props**：
+
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `value` / `onChange` | `string` / `(html) => void` | 受控 HTML（内部模型为准——输出经序列化归一化） |
+| `toolbar` | `ToolbarItem[]` | 工具栏项（bold/italic/h1-3/align/link/image/table/clear/source…）；默认 18 项 |
+| `placeholder` / `disabled` / `minHeight` | | 占位符 / 禁用 / 最小高度 |
+| `onUpload` | `(file) => Promise<string>` | 图片上传（返回 URL）；不传则 URL 输入 |
+| `ai` | `EditorAiOptions` | **AI 协作（可选）**——见下 |
+| `draftKey` | `string` | **草稿持久化（可选）**：内容自动保存（防抖 500ms），挂载时 `value` 为空且存在草稿 → 自动恢复（刷新/崩溃不丢） |
+
+**撤销/重做/时光机**：
+
+- `Ctrl+Z` / `Ctrl+Y`：一步撤销/重做**语义操作**（输入合并为单步——连续打字一次撤销全退）
+- 工具栏 🕘 **操作历史**：commit 列表（标签 + 时间）→ 点击回到任意版本（redo 保留可重做回来）
+
+**AI 协作**（`ai` prop——不传则无 AI 能力）：
+
+```tsx
+<Editor
+  value={html}
+  onChange={v => setHtml(v)}
+  ai={{ url: '/api/ai-editor' }}          // wf: SSE 端点（docs/ai-contract.md）
+/>
+```
+
+- 工具栏 AI 动作组（默认：润色/翻译/缩写/扩写/纠错）——选中文本（无选区 = 全文）→ 点击 → 浮层**流式**生成建议（原文 diff 对比）→ **接受**（替换 = 一个原子撤销步）/ **拒绝**
+- `Ctrl+Enter`：快速触发最近使用的 AI 动作
+- 自定义动作：`ai.actions`（prompt 模板注入 `{selection}`）
+
+```tsx
+<Editor value={html} onChange={v => setHtml(v)}
+  ai={{
+    url: '/api/ai-editor',
+    actions: [{
+      id: 'tone', label: '改语气',
+      prompt: ({ selection }) => `请把以下文本改为正式语气：\n\n${selection}`,
+    }],
+  }} />
+```
+
+### FilePreview（文件预览——基于事件流）
+
+md/html/pdf/office/text 文件预览——**文档 = fold(事件流)**（复用 Editor 文档模型）：
+md/text 解析为 DocState——预览/编辑/撤销/AI 同一模型；编辑后可序列化回 md 保存。
+
+```tsx
+import { FilePreview } from 'weifuwu/components'
+
+// md 预览 + 编辑 + AI 协作（润色文档 = 原子撤销）
+<FilePreview type="md" content={md} editable ai={{ url: '/api/ai' }}
+  onSave={(md) => saveToSandbox(md)} fileName="README.md" />
+```
+
+**类型支持矩阵**：
+
+| 类型 | 预览 | 编辑 | 说明 |
+|------|------|------|------|
+| `md` | ✅ 复用 `<Markdown>`（安全 token 渲染：表格/任务列表/URL 白名单） | ✅ 复用 `<Editor>`（事件流事务层——撤销/时光机/AI） | 编辑保存 = 序列化回 Markdown |
+| `text` | `<pre>` | ✅ 复用 `<Editor>` | 纯文本 |
+| `html` | ✅ iframe `sandbox`（安全隔离——不直插 DOM） | ❌（安全边界） | 只读 |
+| `pdf` | ✅ iframe（浏览器原生查看器） | ❌ | 只读 |
+| `office` | ✅ iframe（服务端转换产物 URL） | ❌ | 转换由服务端提供（前端零依赖——诚实裁剪） |
+
+**Props**：`type`（可选——按 `fileName`/`url` 扩展名自动探测：md/txt/html/pdf/
+docx 等）、`content`（md/html/text）、`url`（远程加载/文件服务路径）、
+`editable`（md/text 切换 Editor）、`ai`（编辑模式透传 Editor AI 协作）、
+`onSave(content, type)`（保存回写）、`onLoad`（解析完成）、`height`。
+
+**交互**：工具条「复制」（原始内容——`ctx.browser.copyText`）+「保存」；
+编辑模式 `Ctrl+S` 保存。远程文件（sandbox 路径）：`url` 加载 + `onSave` 回写。
+
+### SheetGrid（xlsx 网格编辑器——ODES 事件流）
+
+**Props**：`workbook`（受控 WorkbookState——稀疏 cells Map）、`onChange`、
+`ai`（AI 公式——SSE wf:）、`readonly`、`height`。
+
+**能力**：单元格编辑（点击 → input → Enter/focusout 提交）、行列增删（引用平移）、
+撤销（Ctrl+Z——commit 快照）、sheet 标签切换、**AI 公式**（选中单元格 → 相邻数据
+上下文提示 → 浮层确认 → 接受 = cell-set commit 原子撤销）。
+
+**事件流**：每个编辑 = `OfficeOp` → `__edit_tail(50, 'office')` 审计；AI 接受带
+`target=messageId`（跨端关联 `__ai_events`）。
+
+### SlideCanvas（pptx 画布编辑器——ODES 事件流）
+
+**Props**：`deck`（受控 DeckState——slide → shape 几何集合）、`onChange`、
+`ai`（AI 润色）、`readonly`、`height`。
+
+**能力**：960×540 画布（scale 适配）、shape 拖拽移动/右下角缩放（pointerup 原子
+提交）、双击文本编辑、幻灯片增删、Delete 删除、撤销、**AI 润色**（选中 shape →
+浮层确认 → 接受 = shape-set commit）。
+
+### Office 前端转换（零依赖——无需后端）
+
+`weifuwu/office`（源码 `src/office/`——打包进 components）：docx/xlsx/pptx ↔
+ODES 模型（DocState/WorkbookState/DeckState）双向转换——自研 ZIP（EOCD→central→
+local + `DecompressionStream('deflate-raw')`）+ 轻量 XML 解析器 + VNode 组件化
+生成 OOXML（OOXML 也是 VNode——与前端 VNode → DOM 同构）。
+
+**用法**（FilePreview 内置）：`editable` office 类型 → 打开本地 docx/xlsx/pptx →
+对应编辑器（Editor/SheetGrid/SlideCanvas）→ 下载导出。裁剪：复杂分节/公式计算/
+动画母版——诚实提示。
+
+**事件流**：预览加载 `editEmit('preview')`（`__edit_tail` 可审计）；编辑走 Editor
+commit 事件流（同一时间线）。**sandbox 集成**：`url` 加载 + `onSave` 回写由消费方接
+文件读写工具。
+
+**裁剪**：docx/xlsx/pptx 前端解析不做（零依赖——office 由服务端转换）；代码块/
+表格编辑时降级（超 Editor 模型——见 md 转换文档）。
 
 ### 布局
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "weifuwu",
   "type": "module",
-  "version": "0.85.0",
+  "version": "0.86.0",
   "description": "AI SaaS framework — (req, ctx) => Response",
   "exports": {
     ".": {

package/dist/components/Editor/tools/format.d.ts

@@ -1,11 +0,0 @@
-/**
- * weifuwu/components/Editor/tools — 格式化命令
- */
-import type { FormatState, ToolbarItem } from './types.ts';
-/** 查询当前选区格式状态 */
-export declare function queryFormats(): FormatState;
-/** 执行 execCommand（经 browser 环境抽象） */
-export declare function exec(cmd: string, value?: string): void;
-/** 根据工具项执行格式化（formatBlock 类带 toggle：当前已是该块格式 → 回默认块——
- *  真实浏览器验收发现 Chrome 对重复 formatBlock 同值不切换，标题/引用无法反选） */
-export declare function execFormat(item: ToolbarItem): void;