weifuwu 0.85.0 → 0.87.0

package/content/components/drawer.md

@@ -0,0 +1,55 @@
+# Drawer · components
+
+## 概述
+
+侧边面板，左右滑入 + ESC 关闭
+
+## 典型场景
+
+- 应用模板：agent-platform（examples/apps/ 完整可跑）
+- 浮层交互——弹窗、下拉、气泡、抽屉、命令面板
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `open` | `boolean` | 否 |  |
+| `title` | `string` | 否 |  |
+| `position` | `DrawerPosition` | 否 |  |
+| `onClose` | `() => void` | 否 |  |
+| `children` | `any` | 否 |  |
+| `footer` | `any` | 否 |  |
+| `width` | `string` | 否 | 面板宽度（默认 360px——--wf-drawer-width 变量） |
+
+## 用法示例
+
+```tsx
+<Drawer open={open}
+  title="编辑" position="right"
+  onClose={() => open = false}>
+  <p>内容</p>
+</Drawer>
+```
+
+## 纪律/坑
+
+- 退场动画：--enter/--exit 类必须成对（audit 强制）——只定义不挂是死代码（CS-01）
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：[agent-platform](../apps/agent-platform.md)
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Drawer/Drawer.ts` |
+| 样式 | `src/client/components/Drawer/Drawer.css` |
+| 测试 | `src/client/components/Drawer/Drawer.test.ts` |
+| demo | `apps/showcase/src/demos/DemoDrawer.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/overlay/drawer` ——（P1 填充具体步骤）

package/content/components/dropdown.md

@@ -0,0 +1,53 @@
+# Dropdown · components
+
+## 概述
+
+下拉菜单，支持 danger variant
+
+## 典型场景
+
+- 浮层交互——弹窗、下拉、气泡、抽屉、命令面板
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `trigger` | `any` | 是 |  |
+| `items` | `DropdownItem[]` | 否 |  |
+| `open` | `boolean` | 否 |  |
+| `onOpenChange` | `(open: boolean) => void` | 否 | 关闭回调（面板内 Escape / 外部点击） |
+
+## 用法示例
+
+```tsx
+<Dropdown trigger={<Button>菜单</Button>}
+  open={open}
+  items={[
+    {label:'编辑', onClick},
+    {label:'删除', variant:'danger'},
+  ]} />
+```
+
+## 纪律/坑
+
+- 受控纪律：受控 open 必须配 onOpenChange——缺回调静默不可点
+- 命令式弹窗：浮层经 ctx.ui.openPopup（唯一形态——toast 心智——内核自管理生命周期）
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Dropdown/Dropdown.ts` |
+| 样式 | `src/client/components/Dropdown/Dropdown.css` |
+| 测试 | `src/client/components/Dropdown/Dropdown.test.ts` |
+| demo | `apps/showcase/src/demos/DemoDropdown.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/overlay/dropdown` ——（P1 填充具体步骤）

package/content/components/editor.md

@@ -0,0 +1,49 @@
+# Editor · components
+
+## 概述
+
+富文本编辑器，contentEditable + toolbar，零依赖
+
+## 典型场景
+
+- office 文档/代码/内容编辑——xlsx/pptx/代码/公式/裁剪
+
+## API
+
+> props 提取降级（接口格式特殊）——见源码：`src/client/components/Editor/Editor.ts`
+
+## 用法示例
+
+```tsx
+<Editor value={html} onChange={v => html = v}
+  placeholder="输入内容..." />
+
+<Editor toolbar={['bold','italic']}
+  minHeight="150px" />
+
+<Editor disabled value="只读" />
+
+```
+
+## 纪律/坑
+
+> 内容编辑：textarea value 走 property（attribute 只是 defaultValue）；受控输入纪律
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Editor/Editor.ts` |
+| 样式 | `src/client/components/Editor/Editor.css` |
+| 测试 | `src/client/components/Editor/Editor.test.ts` |
+| demo | `apps/showcase/src/demos/DemoEditor.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/editor/editor` ——（P1 填充具体步骤）

package/content/components/emptystate.md

@@ -0,0 +1,51 @@
+# EmptyState · components
+
+## 概述
+
+空状态占位，支持 icon/text/hint/action
+
+## 典型场景
+
+- 页面模式：list-page（复制即用蓝本——examples/patterns/）
+- 应用模板：todo（examples/apps/ 完整可跑）
+- 操作反馈/结果页/确认——保存成功、删除确认、空态/加载态
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `icon` | `string \| VNode \| null` | 否 | 图标——VNode（推荐 <Icon />）或字符串（emoji/字形）；默认 Icon inbox（P3：组件内禁裸 emoji） |
+| `text` | `string` | 否 |  |
+| `hint` | `string` | 否 |  |
+| `children` | `any` | 否 |  |
+
+## 用法示例
+
+```tsx
+<EmptyState
+  text="暂无数据"
+  hint="提示信息" />
+```
+
+## 纪律/坑
+
+> 退场动画（§8）：exit 类必须挂载（animationend 驱动）+ reduced-motion 降级
+
+## 关系
+
+- ↑ 用于页面模式：[list-page](../patterns/list-page.md)
+- ↑ 用于应用：[todo](../apps/todo.md)
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/EmptyState/EmptyState.ts` |
+| 样式 | `src/client/components/EmptyState/EmptyState.css` |
+| 测试 | `src/client/components/EmptyState/EmptyState.test.ts` |
+| demo | `apps/showcase/src/demos/DemoEmptyState.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/feedback/emptystate` ——（P1 填充具体步骤）

package/content/components/exportcsv.md

@@ -0,0 +1,38 @@
+# ExportCSV · components
+
+## 概述
+
+数据导出 CSV——RFC 4180 转义 + BOM（Excel 兼容）零依赖
+
+## 典型场景
+
+- 数据展示——列表页、详情页、信息呈现
+
+## API
+
+> props 提取降级（接口格式特殊）——见源码：`src/client/components/ExportCSV/ExportCSV.ts`
+
+## 用法示例
+
+> （P1 迁移 CODE 字符串）
+
+## 纪律/坑
+
+> 三层一致（§6.3）：条件渲染 false 是空洞占位——数组项 key 由业务声明
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/ExportCSV/ExportCSV.ts` |
+| 测试 | `src/client/components/ExportCSV/ExportCSV.test.ts` |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/display/exportcsv` ——（P1 填充具体步骤）

package/content/components/field.md

@@ -0,0 +1,54 @@
+# Field · components
+
+## 概述
+
+label+error+hint 容器
+
+## 典型场景
+
+- 页面模式：focus-task、settings-page（复制即用蓝本——examples/patterns/）
+- 创建/编辑表单页——提交、校验、字段编排
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `label` | `string` | 否 |  |
+| `required` | `boolean` | 否 |  |
+| `error` | `string` | 否 |  |
+| `hint` | `string` | 否 |  |
+| `children` | `any` | 否 |  |
+
+## 用法示例
+
+```tsx
+<Field label="姓名" required>
+  <Input />
+</Field>
+<Field error="错误信息">
+  <Input />
+</Field>
+```
+
+## 纪律/坑
+
+> 受控纪律（§5.2）：受控 props 必须配回调——缺回调静默不可点；受控输入（§5.3）输入态不依赖 value 回流（焦点丢失）
+
+## 关系
+
+- ↑ 用于页面模式：[focus-task](../patterns/focus-task.md) · [settings-page](../patterns/settings-page.md)
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Field/Field.ts` |
+| 样式 | `src/client/components/Field/Field.css` |
+| 测试 | `src/client/components/Field/Field.test.ts` |
+| demo | `apps/showcase/src/demos/DemoField.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/form/field` ——（P1 填充具体步骤）

package/content/components/filepreview-office.md

@@ -0,0 +1,37 @@
+# FilePreview Office · components
+
+## 概述
+
+office 前端导入/导出（零依赖转换——无需后端）
+
+## 典型场景
+
+- office 文档/代码/内容编辑——xlsx/pptx/代码/公式/裁剪
+
+## API
+
+> props 提取降级（接口格式特殊）——见源码：`—`
+
+## 用法示例
+
+> （P1 迁移 CODE 字符串）
+
+## 纪律/坑
+
+> 内容编辑：textarea value 走 property（attribute 只是 defaultValue）；受控输入纪律
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| demo | `apps/showcase/src/demos/DemoFilePreviewOffice.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/editor/filepreview-office` ——（P1 填充具体步骤）

package/content/components/filepreview.md

@@ -0,0 +1,49 @@
+# FilePreview · components
+
+## 概述
+
+文件预览（md/html/pdf/office）——基于事件流，可编辑
+
+## 典型场景
+
+- office 文档/代码/内容编辑——xlsx/pptx/代码/公式/裁剪
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `type` | `FileType` | 否 | 文件类型（缺省按 fileName/url 扩展名自动探测） |
+| `content` | `string` | 否 | md/html/text 内容（直接传入）；pdf/office 用 url |
+| `url` | `string` | 否 | pdf/office 文件 URL（或 html 远程加载） |
+| `fileName` | `string` | 否 |  |
+| `editable` | `boolean` | 否 | md/text：切换 Editor（复用事件流事务层——编辑/撤销/时光机/AI） |
+| `ai` | `EditorAiOptions` | 否 | 编辑模式 AI 协作（透传 Editor） |
+| `onSave` | `(content: string, type: 'md' \| 'text') => void` | 否 | 编辑保存回调（md/text 序列化回写） |
+| `height` | `string` | 否 | 内容高度 |
+
+## 用法示例
+
+> （P1 迁移 CODE 字符串）
+
+## 纪律/坑
+
+> 内容编辑：textarea value 走 property（attribute 只是 defaultValue）；受控输入纪律
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/FilePreview/FilePreview.ts` |
+| 样式 | `src/client/components/FilePreview/FilePreview.css` |
+| 测试 | `src/client/components/FilePreview/FilePreview.test.ts` |
+| demo | `apps/showcase/src/demos/DemoFilePreview.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/editor/filepreview` ——（P1 填充具体步骤）

package/content/components/filetree.md

@@ -0,0 +1,56 @@
+# FileTree · components
+
+## 概述
+
+文件树浏览器——面包屑 + 列表/编辑态 + 上传（受控——数据源无关）
+
+## 典型场景
+
+- office 文档/代码/内容编辑——xlsx/pptx/代码/公式/裁剪
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `entries` | `FileTreeEntry[]` | 否 | 当前目录条目（父层数据源驱动） |
+| `path` | `string` | 否 | 当前目录路径（面包屑） |
+| `loading` | `boolean` | 否 |  |
+| `openFile` | `FileTreeOpenFile \| null` | 否 | 编辑态（非空 = 文件编辑中——列表替换为编辑器） |
+| `editValue` | `string` | 否 | 编辑内容（受控） |
+| `saving` | `boolean` | 否 |  |
+| `emptyText` | `string` | 否 | 目录空态文案 |
+| `onBack` | `() => void` | 否 | 编辑态返回列表 |
+| `onOpenDir` | `(path: string) => void` | 否 |  |
+| `onOpenFile` | `(path: string) => void` | 否 |  |
+| `onSave` | `(content: string) => void` | 否 |  |
+| `onEditChange` | `(value: string) => void` | 否 |  |
+| `onUpload` | `(file: File) => void` | 否 | 上传（父层处理 File——组件只触发选择） |
+| `onRefresh` | `() => void` | 否 |  |
+| `accept` | `string` | 否 | 上传 accept（默认全部） |
+
+## 用法示例
+
+> （P1 迁移 CODE 字符串）
+
+## 纪律/坑
+
+> 内容编辑：textarea value 走 property（attribute 只是 defaultValue）；受控输入纪律
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/FileTree/FileTree.ts` |
+| 样式 | `src/client/components/FileTree/FileTree.css` |
+| 测试 | `src/client/components/FileTree/FileTree.test.ts` |
+| demo | `apps/showcase/src/demos/DemoFileTree.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/editor/filetree` ——（P1 填充具体步骤）

package/content/components/fileupload-v2.md

@@ -0,0 +1,39 @@
+# FileUpload 禁用 · components
+
+## 概述
+
+disabled + accept 限定（状态矩阵覆盖）
+
+## 典型场景
+
+- office 文档/代码/内容编辑——xlsx/pptx/代码/公式/裁剪
+
+## API
+
+> props 提取降级（接口格式特殊）——见源码：`—`
+
+## 用法示例
+
+```tsx
+<FileUpload accept="image/*" multiple disabled error />
+```
+
+## 纪律/坑
+
+> 内容编辑：textarea value 走 property（attribute 只是 defaultValue）；受控输入纪律
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| demo | `apps/showcase/src/demos/DemoFileUploadDis.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/editor/fileupload-v2` ——（P1 填充具体步骤）

package/content/components/fileupload.md

@@ -0,0 +1,57 @@
+# FileUpload · components
+
+## 概述
+
+文件上传，拖拽区 + 文件列表 + accept/maxSize
+
+## 典型场景
+
+- office 文档/代码/内容编辑——xlsx/pptx/代码/公式/裁剪
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `accept` | `string` | 否 |  |
+| `multiple` | `boolean` | 否 |  |
+| `maxSize` | `number` | 否 |  |
+| `disabled` | `boolean` | 否 |  |
+| `error` | `string` | 否 |  |
+| `hint` | `string` | 否 |  |
+| `value` | `File[]` | 否 |  |
+| `onChange` | `(files: File[]) => void` | 否 |  |
+| `uploading` | `boolean` | 否 | 上传中状态（父层驱动——组件不做 xhr，诚实裁剪） |
+| `progress` | `number` | 否 | 上传进度 0-100（父层驱动） |
+| `children` | `any` | 否 |  |
+
+## 用法示例
+
+```tsx
+<FileUpload accept="image/*,.pdf"
+  multiple maxSize={5242880}
+  value={files}
+  onChange={f => files = f} />
+```
+
+## 纪律/坑
+
+> 内容编辑：textarea value 走 property（attribute 只是 defaultValue）；受控输入纪律
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/FileUpload/FileUpload.ts` |
+| 样式 | `src/client/components/FileUpload/FileUpload.css` |
+| 测试 | `src/client/components/FileUpload/FileUpload.test.ts` |
+| demo | `apps/showcase/src/demos/DemoFileUpload.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/editor/fileupload` ——（P1 填充具体步骤）

package/content/components/floatbutton.md

@@ -0,0 +1,52 @@
+# FloatButton · components
+
+## 概述
+
+悬浮按钮组：展开状态机 + badge
+
+## 典型场景
+
+- 基础元素（按钮/图标/文本/卡片/标签）——任意页面的构成单元
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `icon` | `any` | 否 |  |
+| `badge` | `number \| string` | 否 |  |
+| `position` | `FloatButtonPosition` | 否 |  |
+| `static` | `boolean` | 否 | 'static'：组内子项（不 fixed——独立 fixed 会与主按钮重叠） |
+| `disabled` | `boolean` | 否 |  |
+| `onClick` | `() => void` | 否 |  |
+| `children` | `any` | 否 |  |
+
+## 用法示例
+
+```tsx
+<FloatButtonGroup>
+  <FloatButton icon={editIcon} onClick={edit} />
+</FloatButtonGroup>
+```
+
+## 纪律/坑
+
+> 浏览器纪律（§5.5）：组件能力经 ctx.browser / ctx.ui.useXXX——禁裸 window/document
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/FloatButton/FloatButton.ts` |
+| 样式 | `src/client/components/FloatButton/FloatButton.css` |
+| 测试 | `src/client/components/FloatButton/FloatButton.test.ts` |
+| demo | `apps/showcase/src/demos/DemoFloatButton.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/core/floatbutton` ——（P1 填充具体步骤）

package/content/components/form-v2.md

@@ -0,0 +1,41 @@
+# Form 提交 · components
+
+## 概述
+
+loading 提交 + 校验错误（状态矩阵覆盖）
+
+## 典型场景
+
+- 创建/编辑表单页——提交、校验、字段编排
+
+## API
+
+> props 提取降级（接口格式特殊）——见源码：`—`
+
+## 用法示例
+
+```tsx
+<Form validation={{name:[{required:true,minLength:2}]}}
+  onSubmit={submit}><Field label="项目名称" required><Input name="name" /></Field>
+  <Button type="submit" loading={loading}>提交</Button></Form>
+```
+
+## 纪律/坑
+
+> 受控纪律（§5.2）：受控 props 必须配回调——缺回调静默不可点；受控输入（§5.3）输入态不依赖 value 回流（焦点丢失）
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| demo | `apps/showcase/src/demos/DemoFormSubmit.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/form/form-v2` ——（P1 填充具体步骤）