weifuwu 0.86.0 → 0.87.0

package/content/components/codeblock.md

@@ -0,0 +1,48 @@
+# CodeBlock · components
+
+## 概述
+
+代码块：语言标签 + 复制按钮 + 横向滚动
+
+## 典型场景
+
+- 页面模式：workspace、docs（复制即用蓝本——examples/patterns/）
+- 数据展示——列表页、详情页、信息呈现
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `code` | `string` | 是 |  |
+| `lang` | `string` | 否 |  |
+| `title` | `string` | 否 |  |
+
+## 用法示例
+
+```tsx
+<CodeBlock lang="ts" title="示例.ts" code={...} />
+{/* 复制按钮 + 语言标签 + 横向滚动 */}
+```
+
+## 纪律/坑
+
+> 三层一致（§6.3）：条件渲染 false 是空洞占位——数组项 key 由业务声明
+
+## 关系
+
+- ↑ 用于页面模式：[workspace](../patterns/workspace.md) · [docs](../patterns/docs.md)
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/CodeBlock/CodeBlock.ts` |
+| 样式 | `src/client/components/CodeBlock/CodeBlock.css` |
+| 测试 | `src/client/components/CodeBlock/CodeBlock.test.ts` |
+| demo | `apps/showcase/src/demos/DemoCodeBlock.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/display/codeblock` ——（P1 填充具体步骤）

package/content/components/codeeditor.md

@@ -0,0 +1,47 @@
+# CodeEditor · components
+
+## 概述
+
+轻量代码编辑器——textarea + 行号 + Tab 缩进（零依赖，不引 Monaco）
+
+## 典型场景
+
+- office 文档/代码/内容编辑——xlsx/pptx/代码/公式/裁剪
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `value` | `string` | 是 |  |
+| `onChange` | `(value: string) => void` | 否 |  |
+| `lang` | `'ts' \| 'tsx' \| 'js' \| 'css' \| 'json' \| 'md' \| 'text'` | 否 |  |
+| `rows` | `number` | 否 |  |
+| `readOnly` | `boolean` | 否 |  |
+| `placeholder` | `string` | 否 |  |
+| `className` | `string` | 否 |  |
+
+## 用法示例
+
+> （P1 迁移 CODE 字符串）
+
+## 纪律/坑
+
+> 内容编辑：textarea value 走 property（attribute 只是 defaultValue）；受控输入纪律
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/CodeEditor/CodeEditor.ts` |
+| 样式 | `src/client/components/CodeEditor/CodeEditor.css` |
+| 测试 | `src/client/components/CodeEditor/CodeEditor.test.ts` |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/editor/codeeditor` ——（P1 填充具体步骤）

package/content/components/collapse.md

@@ -0,0 +1,49 @@
+# Collapse · components
+
+## 概述
+
+行内折叠：异步 loading + extra 操作区（区别于 Accordion）
+
+## 典型场景
+
+- 页面导航——侧栏、页头、标签页、步骤、分页
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `items` | `CollapseItem[]` | 否 |  |
+| `active` | `string[]` | 否 | 受控展开 keys |
+| `onChange` | `(keys: string[]) => void` | 否 |  |
+| `multiple` | `boolean` | 否 | false = 手风琴互斥（同一时间只开一个）；默认 true 多开 |
+| `className` | `string` | 否 |  |
+
+## 用法示例
+
+```tsx
+<Collapse items={[{key:'1',title:'标题',content:'内容',loading}]}
+  active={['1']} />
+```
+
+## 纪律/坑
+
+- 受控纪律（§5.2）：受控 activeKeys 必须配回调——缺回调静默不可点（console.warn 防护）
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Collapse/Collapse.ts` |
+| 样式 | `src/client/components/Collapse/Collapse.css` |
+| 测试 | `src/client/components/Collapse/Collapse.test.ts` |
+| demo | `apps/showcase/src/demos/DemoCollapse.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/navigation/collapse` ——（P1 填充具体步骤）

package/content/components/colorpicker.md

@@ -0,0 +1,50 @@
+# ColorPicker · components
+
+## 概述
+
+颜色选择：预设色板 + hex 输入（Popover 弹层）
+
+## 典型场景
+
+- 浮层交互——弹窗、下拉、气泡、抽屉、命令面板
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `value` | `string` | 否 | 受控颜色值（hex，如 #4f6ef7） |
+| `onChange` | `(value: string) => void` | 否 |  |
+| `colors` | `string[]` | 否 | 预设色板（默认内置 10 色） |
+| `size` | `'sm' \| 'md' \| 'lg'` | 否 |  |
+| `disabled` | `boolean` | 否 |  |
+| `showInput` | `boolean` | 否 | 显示 hex 输入框（自由输入） |
+
+## 用法示例
+
+```tsx
+<ColorPicker value={color} showInput
+  onChange={setColor} />
+```
+
+## 纪律/坑
+
+> 弹窗纪律（§5.4）：浮层必须 createPortal 渲染（#__wf_portal）——禁 absolute 相对父容器（overflow/transform 裁剪）；统一走 ctx.ui.usePopup
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/ColorPicker/ColorPicker.ts` |
+| 样式 | `src/client/components/ColorPicker/ColorPicker.css` |
+| 测试 | `src/client/components/ColorPicker/ColorPicker.test.ts` |
+| demo | `apps/showcase/src/demos/DemoColorPicker.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/overlay/colorpicker` ——（P1 填充具体步骤）

package/content/components/command.md

@@ -0,0 +1,50 @@
+# Command · components
+
+## 概述
+
+命令面板：⌘K 全局快捷键 + 键盘流（shadcn Command）
+
+## 典型场景
+
+- 浮层交互——弹窗、下拉、气泡、抽屉、命令面板
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `open` | `boolean` | 否 |  |
+| `onOpenChange` | `(open: boolean) => void` | 否 |  |
+| `items` | `CommandItem[]` | 否 |  |
+| `placeholder` | `string` | 否 |  |
+| `emptyText` | `string` | 否 |  |
+| `globalShortcut` | `string \| null` | 否 | 全局快捷键，如 'mod+k'（cmd/ctrl + k）；null 关闭全局监听 |
+
+## 用法示例
+
+```tsx
+<Command items={items} open={open}
+  onOpenChange={setOpen} />
+```
+
+## 纪律/坑
+
+> 弹窗纪律（§5.4）：浮层必须 createPortal 渲染（#__wf_portal）——禁 absolute 相对父容器（overflow/transform 裁剪）；统一走 ctx.ui.usePopup
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Command/Command.ts` |
+| 样式 | `src/client/components/Command/Command.css` |
+| 测试 | `src/client/components/Command/Command.test.ts` |
+| demo | `apps/showcase/src/demos/DemoCommand.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/overlay/command` ——（P1 填充具体步骤）

package/content/components/confirm.md

@@ -0,0 +1,57 @@
+# Confirm · components
+
+## 概述
+
+确认对话框，Promise 化 await 调用
+
+## 典型场景
+
+- 操作反馈/结果页/确认——保存成功、删除确认、空态/加载态
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `open` | `boolean` | 否 |  |
+| `title` | `string` | 否 |  |
+| `message` | `any` | 否 | 提示内容（文本或任意 VNode） |
+| `confirmText` | `string` | 否 |  |
+| `cancelText` | `string` | 否 |  |
+| `variant` | `'primary' \| 'danger'` | 否 |  |
+| `width` | `string` | 否 | 对话框宽度，如 '500px'、'80%'，默认 Modal 的 400px |
+| `maskClosable` | `boolean` | 否 | 遮罩点击是否取消（默认 false：危险操作防误触；显式传 true 可恢复） |
+| `onConfirm` | `() => void` | 否 |  |
+| `onCancel` | `() => void` | 否 |  |
+| `onClose` | `() => void` | 否 | Modal 关闭回调（Escape/遮罩——onCancel 缺省时兜底——命令式兼容） |
+
+## 用法示例
+
+```tsx
+const ok = await ctx.confirm?.('确定删除？', {
+  confirmText: '删除',
+  variant: 'danger',
+})
+if (ok) { /* 执行 */ }
+```
+
+## 纪律/坑
+
+> 退场动画（§8）：exit 类必须挂载（animationend 驱动）+ reduced-motion 降级
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Confirm/Confirm.ts` |
+| 测试 | `src/client/components/Confirm/Confirm.test.ts` |
+| demo | `apps/showcase/src/demos/DemoConfirm.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/feedback/confirm` ——（P1 填充具体步骤）

package/content/components/contextmenu.md

@@ -0,0 +1,48 @@
+# ContextMenu · components
+
+## 概述
+
+右键菜单：光标定位 + 方向键 + danger 变体（shadcn）
+
+## 典型场景
+
+- 浮层交互——弹窗、下拉、气泡、抽屉、命令面板
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `items` | `ContextMenuItem[]` | 否 |  |
+| `children` | `any` | 是 |  |
+| `className` | `string` | 否 |  |
+
+## 用法示例
+
+```tsx
+<ContextMenu items={[{key:'edit',label:'编辑'}]}>
+  <div>右键区域</div>
+</ContextMenu>
+```
+
+## 纪律/坑
+
+- portal 槽豁免；右键 + 触屏长按双通道
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/ContextMenu/ContextMenu.ts` |
+| 样式 | `src/client/components/ContextMenu/ContextMenu.css` |
+| 测试 | `src/client/components/ContextMenu/ContextMenu.test.ts` |
+| demo | `apps/showcase/src/demos/DemoContextMenu.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/overlay/contextmenu` ——（P1 填充具体步骤）

package/content/components/copybutton.md

@@ -0,0 +1,51 @@
+# CopyButton · components
+
+## 概述
+
+复制按钮：clipboard + execCommand 降级 + 成功状态机
+
+## 典型场景
+
+- 基础元素（按钮/图标/文本/卡片/标签）——任意页面的构成单元
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `value` | `string` | 是 | 要复制的文本 |
+| `label` | `string` | 否 | 按钮文字（默认仅图标） |
+| `size` | `'sm' \| 'md' \| 'lg'` | 否 |  |
+| `variant` | `'ghost' \| 'secondary' \| 'default'` | 否 |  |
+| `iconOnly` | `boolean` | 否 | 仅图标（无文字） |
+| `successText` | `string` | 否 | 成功提示文字（默认「已复制」） |
+| `onCopied` | `() => void` | 否 |  |
+| `className` | `string` | 否 |  |
+
+## 用法示例
+
+```tsx
+<CopyButton value="https://..." label="复制" />
+```
+
+## 纪律/坑
+
+> 浏览器纪律（§5.5）：组件能力经 ctx.browser / ctx.ui.useXXX——禁裸 window/document
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/CopyButton/CopyButton.ts` |
+| 样式 | `src/client/components/CopyButton/CopyButton.css` |
+| 测试 | `src/client/components/CopyButton/CopyButton.test.ts` |
+| demo | `apps/showcase/src/demos/DemoCopyButton.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/core/copybutton` ——（P1 填充具体步骤）

package/content/components/datepicker.md

@@ -0,0 +1,52 @@
+# DatePicker · components
+
+## 概述
+
+日期选择器，四种模式：date/datetime/time/range
+
+## 典型场景
+
+- 复杂数据交互——穿梭、树、级联、看板、流水线
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `mode` | `DatePickerMode` | 否 |  |
+| `value` | `string` | 否 |  |
+| `onChange` | `(value: string) => void` | 否 |  |
+| `placeholder` | `string` | 否 |  |
+| `disabled` | `boolean` | 否 |  |
+| `error` | `string` | 否 | 错误态（F2 状态矩阵——输入类基线） |
+
+## 用法示例
+
+```tsx
+<DatePicker mode="date" onChange={v => ...} />
+<DatePicker mode="datetime" />
+<DatePicker mode="time" />
+<DatePicker mode="range" />
+```
+
+## 纪律/坑
+
+- 受控纪律：受控 value/month 必须配回调——缺回调静默不可点
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/DatePicker/DatePicker.ts` |
+| 样式 | `src/client/components/DatePicker/DatePicker.css` |
+| 测试 | `src/client/components/DatePicker/DatePicker.test.ts` |
+| demo | `apps/showcase/src/demos/DemoDatePicker.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/advanced/datepicker` ——（P1 填充具体步骤）

package/content/components/descriptions-v2.md

@@ -0,0 +1,39 @@
+# Descriptions 紧凑 · components
+
+## 概述
+
+size=small 详情页密度（变体覆盖）
+
+## 典型场景
+
+- 数据展示——列表页、详情页、信息呈现
+
+## API
+
+> props 提取降级（接口格式特殊）——见源码：`—`
+
+## 用法示例
+
+```tsx
+<Descriptions size="sm" items={[{label:'姓名',value:'张三'}]} column={2} />
+```
+
+## 纪律/坑
+
+> 三层一致（§6.3）：条件渲染 false 是空洞占位——数组项 key 由业务声明
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| demo | `apps/showcase/src/demos/DemoDescriptionsSize.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/display/descriptions-v2` ——（P1 填充具体步骤）

package/content/components/descriptions.md

@@ -0,0 +1,52 @@
+# Descriptions · components
+
+## 概述
+
+描述列表：label/value 栅格 + bordered + span（详情页）
+
+## 典型场景
+
+- 页面模式：workspace、detail-page（复制即用蓝本——examples/patterns/）
+- 数据展示——列表页、详情页、信息呈现
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `items` | `DescriptionItem[]` | 是 |  |
+| `column` | `1 \| 2 \| 3 \| 4` | 否 |  |
+| `bordered` | `boolean` | 否 |  |
+| `size` | `'sm' \| 'md' \| 'lg'` | 否 |  |
+| `className` | `string` | 否 |  |
+
+## 用法示例
+
+```tsx
+<Descriptions column={2} items={[
+  { label: '名称', value: '小码' },
+  { label: '状态', value: <Badge variant="success">运行中</Badge> },
+]} />
+```
+
+## 纪律/坑
+
+> 三层一致（§6.3）：条件渲染 false 是空洞占位——数组项 key 由业务声明
+
+## 关系
+
+- ↑ 用于页面模式：[workspace](../patterns/workspace.md) · [detail-page](../patterns/detail-page.md)
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Descriptions/Descriptions.ts` |
+| 样式 | `src/client/components/Descriptions/Descriptions.css` |
+| 测试 | `src/client/components/Descriptions/Descriptions.test.ts` |
+| demo | `apps/showcase/src/demos/DemoDescriptions.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/display/descriptions` ——（P1 填充具体步骤）

package/content/components/diffview-v2.md

@@ -0,0 +1,39 @@
+# DiffView 标题 · components
+
+## 概述
+
+oldTitle/newTitle 标记版本对比（变体覆盖）
+
+## 典型场景
+
+- 数据展示——列表页、详情页、信息呈现
+
+## API
+
+> props 提取降级（接口格式特殊）——见源码：`—`
+
+## 用法示例
+
+```tsx
+<DiffView oldTitle="旧实现" newTitle="新实现" oldCode={...} newCode={...} />
+```
+
+## 纪律/坑
+
+> 三层一致（§6.3）：条件渲染 false 是空洞占位——数组项 key 由业务声明
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| demo | `apps/showcase/src/demos/DemoDiffViewBig.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/display/diffview-v2` ——（P1 填充具体步骤）

package/content/components/diffview.md

@@ -0,0 +1,50 @@
+# DiffView · components
+
+## 概述
+
+代码 diff：LCS 行级对比 + 未变块折叠 + 三态着色
+
+## 典型场景
+
+- 数据展示——列表页、详情页、信息呈现
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `oldCode` | `string` | 是 | 旧代码 |
+| `newCode` | `string` | 是 | 新代码 |
+| `oldTitle` | `string` | 否 | 旧标题 |
+| `newTitle` | `string` | 否 | 新标题 |
+| `foldThreshold` | `number` | 否 | 连续未变行超过该值折叠为「↕ N 行」（默认 5；0 = 不折叠） |
+| `maxLines` | `number` | 否 | 最大渲染行数（超出的变化行显示省略提示——防超大 diff 卡顿） |
+| `className` | `string` | 否 |  |
+
+## 用法示例
+
+```tsx
+<DiffView oldCode={oldCode} newCode={newCode} oldTitle="重构前" newTitle="重构后" />
+```
+
+## 纪律/坑
+
+> 三层一致（§6.3）：条件渲染 false 是空洞占位——数组项 key 由业务声明
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/DiffView/DiffView.ts` |
+| 样式 | `src/client/components/DiffView/DiffView.css` |
+| 测试 | `src/client/components/DiffView/DiffView.test.ts` |
+| demo | `apps/showcase/src/demos/DemoDiffView.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/display/diffview` ——（P1 填充具体步骤）

package/content/components/divider.md

@@ -0,0 +1,48 @@
+# Divider · components
+
+## 概述
+
+分割线，支持 horizontal/vertical/带文字
+
+## 典型场景
+
+- 页面模式：app-shell、workspace、focus-task、docs、dashboard、landing、mobile、detail-page（复制即用蓝本——examples/patterns/）
+- 基础元素（按钮/图标/文本/卡片/标签）——任意页面的构成单元
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `vertical` | `boolean` | 否 |  |
+| `children` | `any` | 否 |  |
+
+## 用法示例
+
+```tsx
+<Divider />
+<Divider vertical />
+<Divider>或</Divider>
+```
+
+## 纪律/坑
+
+> 浏览器纪律（§5.5）：组件能力经 ctx.browser / ctx.ui.useXXX——禁裸 window/document
+
+## 关系
+
+- ↑ 用于页面模式：[app-shell](../patterns/app-shell.md) · [workspace](../patterns/workspace.md) · [focus-task](../patterns/focus-task.md) · [docs](../patterns/docs.md) · [dashboard](../patterns/dashboard.md) · [landing](../patterns/landing.md) · [mobile](../patterns/mobile.md) · [detail-page](../patterns/detail-page.md)
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Divider/Divider.ts` |
+| 样式 | `src/client/components/Divider/Divider.css` |
+| 测试 | `src/client/components/Divider/Divider.test.ts` |
+| demo | `apps/showcase/src/demos/DemoDivider.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/core/divider` ——（P1 填充具体步骤）