weifuwu 0.85.0 → 0.87.0

package/content/components/space.md

@@ -0,0 +1,52 @@
+# Space · components
+
+## 概述
+
+间距容器：size/direction/wrap + split 分隔符
+
+## 典型场景
+
+- 页面模式：app-shell、workspace、focus-task、docs、dashboard、data-screen、landing、mobile、detail-page、settings-page（复制即用蓝本——examples/patterns/）
+- 基础元素（按钮/图标/文本/卡片/标签）——任意页面的构成单元
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `size` | `number \| 'sm' \| 'md' \| 'lg'` | 否 |  |
+| `direction` | `'horizontal' \| 'vertical'` | 否 |  |
+| `wrap` | `boolean` | 否 |  |
+| `align` | `'start' \| 'center' \| 'end' \| 'baseline'` | 否 |  |
+| `split` | `any` | 否 |  |
+| `children` | `any` | 否 |  |
+
+## 用法示例
+
+```tsx
+<Space split={<Divider vertical />}>
+  <span>一</span><span>二</span><span>三</span>
+</Space>
+```
+
+## 纪律/坑
+
+> 浏览器纪律（§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) · [data-screen](../patterns/data-screen.md) · [landing](../patterns/landing.md) · [mobile](../patterns/mobile.md) · [detail-page](../patterns/detail-page.md) · [settings-page](../patterns/settings-page.md)
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Space/Space.ts` |
+| 样式 | `src/client/components/Space/Space.css` |
+| 测试 | `src/client/components/Space/Space.test.ts` |
+| demo | `apps/showcase/src/demos/DemoSpace.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/core/space` ——（P1 填充具体步骤）

package/content/components/sparkline.md

@@ -0,0 +1,52 @@
+# Sparkline · components
+
+## 概述
+
+迷你趋势线：SVG 自绘 + 归一化 + 平滑曲线 + 面积填充
+
+## 典型场景
+
+- 页面模式：data-screen（复制即用蓝本——examples/patterns/）
+- 数据看板/统计报表——指标卡、图表、趋势
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `data` | `number[]` | 是 | 数据序列 |
+| `width` | `number` | 否 | SVG 宽（默认 120） |
+| `height` | `number` | 否 | SVG 高（默认 32） |
+| `stroke` | `string` | 否 | 描边色（默认语义 primary，随 currentColor 可继承） |
+| `fill` | `boolean` | 否 | 面积填充（默认关） |
+| `smooth` | `boolean` | 否 | 平滑曲线（Catmull-Rom）——默认折线 |
+| `label` | `string` | 否 | 可访问名（提供则 role=img + aria-label，否则 aria-hidden 装饰） |
+| `className` | `string` | 否 |  |
+
+## 用法示例
+
+```tsx
+<Sparkline data={[12, 18, 15, 22, 30, 28, 35]} width={140} height={36} fill />
+```
+
+## 纪律/坑
+
+> 图表自研 SVG：数据点 label 为轴名；交互 tooltip 经 usePopup（视口夹紧）
+
+## 关系
+
+- ↑ 用于页面模式：[data-screen](../patterns/data-screen.md)
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Sparkline/Sparkline.ts` |
+| 样式 | `src/client/components/Sparkline/Sparkline.css` |
+| 测试 | `src/client/components/Sparkline/Sparkline.test.ts` |
+| demo | `apps/showcase/src/demos/DemoSparkline.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/viz/sparkline` ——（P1 填充具体步骤）

package/content/components/statcard-countdown.md

@@ -0,0 +1,39 @@
+# StatCard Countdown · components
+
+## 概述
+
+倒计时模式：剩余 HH:MM:SS + 结束回调
+
+## 典型场景
+
+- 数据展示——列表页、详情页、信息呈现
+
+## API
+
+> props 提取降级（接口格式特殊）——见源码：`—`
+
+## 用法示例
+
+```tsx
+<StatCard label="倒计时" countdown={deadline} />
+```
+
+## 纪律/坑
+
+> 三层一致（§6.3）：条件渲染 false 是空洞占位——数组项 key 由业务声明
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| demo | `apps/showcase/src/demos/DemoStatCountdown.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/display/statcard-countdown` ——（P1 填充具体步骤）

package/content/components/statcard.md

@@ -0,0 +1,56 @@
+# StatCard · components
+
+## 概述
+
+KPI 指标卡，支持 trend/icon
+
+## 典型场景
+
+- 页面模式：app-shell、dashboard、data-screen（复制即用蓝本——examples/patterns/）
+- 应用模板：admin、agent-platform（examples/apps/ 完整可跑）
+- 数据看板/统计报表——指标卡、图表、趋势
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `label` | `string` | 是 |  |
+| `value` | `string \| number` | 否 | 展示值——countdown 模式下可选（显示剩余时间） |
+| `trend` | `'up' \| 'down'` | 否 |  |
+| `trendLabel` | `string` | 否 |  |
+| `icon` | `string \| VNode \| null` | 否 | 图标——字符串（emoji/字形）或 VNode（推荐 <Icon name=... />，禁 emoji 装饰的场景用后者） |
+| `onClick` | `() => void` | 否 | 点击跳转/交互（悬停抬升 + role=button） |
+| `animate` | `boolean` | 否 | 数字从 0 递增动画（reduced-motion 下直接终值），仅数值类型生效 |
+| `countdown` | `number` | 否 | 倒计时目标时间戳（ms）——显示剩余 HH:MM:SS（antd Statistic.Countdown 等价） |
+| `onFinish` | `() => void` | 否 | 倒计时结束回调 |
+
+## 用法示例
+
+```tsx
+<StatCard label="用户"
+  value="1,234" icon={<Icon name="users" />}
+  trend="up" trendLabel="12%" />
+```
+
+## 纪律/坑
+
+> 图表自研 SVG：数据点 label 为轴名；交互 tooltip 经 usePopup（视口夹紧）
+
+## 关系
+
+- ↑ 用于页面模式：[app-shell](../patterns/app-shell.md) · [dashboard](../patterns/dashboard.md) · [data-screen](../patterns/data-screen.md)
+- ↑ 用于应用：[admin](../apps/admin.md) · [agent-platform](../apps/agent-platform.md)
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/StatCard/StatCard.ts` |
+| 样式 | `src/client/components/StatCard/StatCard.css` |
+| 测试 | `src/client/components/StatCard/StatCard.test.ts` |
+| demo | `apps/showcase/src/demos/DemoStatCard.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/viz/statcard` ——（P1 填充具体步骤）

package/content/components/steps.md

@@ -0,0 +1,48 @@
+# Steps · components
+
+## 概述
+
+分步指示器，支持 active/current
+
+## 典型场景
+
+- 页面导航——侧栏、页头、标签页、步骤、分页
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `items` | `StepItem[]` | 否 |  |
+| `active` | `string` | 否 |  |
+| `current` | `number` | 否 |  |
+
+## 用法示例
+
+```tsx
+<Steps items={[
+  {key:'a',label:'第一步'},
+]} active="b" />
+```
+
+## 纪律/坑
+
+> 键盘可达（P1）：方向键导航焦点跟随（roving tabindex）；受控 props 配回调
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Steps/Steps.ts` |
+| 样式 | `src/client/components/Steps/Steps.css` |
+| 测试 | `src/client/components/Steps/Steps.test.ts` |
+| demo | `apps/showcase/src/demos/DemoSteps.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/navigation/steps` ——（P1 填充具体步骤）

package/content/components/switch.md

@@ -0,0 +1,50 @@
+# Switch · components
+
+## 概述
+
+开关切换，视觉替代 checkbox
+
+## 典型场景
+
+- 页面模式：dashboard、settings-page（复制即用蓝本——examples/patterns/）
+- 表单输入/搜索/筛选——查询区、编辑表单、设置页
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `label` | `string` | 否 |  |
+| `checked` | `boolean` | 否 |  |
+| `disabled` | `boolean` | 否 |  |
+| `onChange` | `(checked: boolean) => void` | 否 |  |
+
+## 用法示例
+
+```tsx
+<Switch label="启用"
+  checked={notify}
+  onChange={v => notify = v} />
+```
+
+## 纪律/坑
+
+> 受控输入纪律（§5.3）：输入期间 value 走内部态（useControlledInput）——依赖回流会重挂 input 丢焦点；IME composition 门控
+
+## 关系
+
+- ↑ 用于页面模式：[dashboard](../patterns/dashboard.md) · [settings-page](../patterns/settings-page.md)
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Switch/Switch.ts` |
+| 样式 | `src/client/components/Switch/Switch.css` |
+| 测试 | `src/client/components/Switch/Switch.test.ts` |
+| demo | `apps/showcase/src/demos/DemoSwitch.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/input/switch` ——（P1 填充具体步骤）

package/content/components/tabbar.md

@@ -0,0 +1,45 @@
+# TabBar · components
+
+## 概述
+
+底部标签栏——移动端 App 主导航（3-5 tab + icon/badge/受控激活 + safe-area 避让）
+
+## 典型场景
+
+- 页面导航——侧栏、页头、标签页、步骤、分页
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `items` | `TabBarItem[]` | 是 |  |
+| `activeKey` | `string` | 否 | 受控激活 key（不传 = 非受控自管理） |
+| `onChange` | `(key: string) => void` | 否 |  |
+| `fixed` | `boolean` | 否 | 底部固定（position:fixed + safe-area 避让）——移动端 App 主导航 |
+| `className` | `string` | 否 |  |
+
+## 用法示例
+
+> （P1 迁移 CODE 字符串）
+
+## 纪律/坑
+
+> 键盘可达（P1）：方向键导航焦点跟随（roving tabindex）；受控 props 配回调
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/TabBar/TabBar.ts` |
+| 样式 | `src/client/components/TabBar/TabBar.css` |
+| 测试 | `src/client/components/TabBar/TabBar.test.ts` |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/navigation/tabbar` ——（P1 填充具体步骤）

package/content/components/table-v2.md

@@ -0,0 +1,40 @@
+# Table 行选择 · components
+
+## 概述
+
+rowSelection 勾选列 + 受控 keys（状态矩阵覆盖）
+
+## 典型场景
+
+- 数据展示——列表页、详情页、信息呈现
+
+## API
+
+> props 提取降级（接口格式特殊）——见源码：`—`
+
+## 用法示例
+
+```tsx
+<Table rowSelection={{selectedRowKeys, onChange:setKeys}}
+  data={rows} columns={[{key:'name',label:'姓名'}]} />
+```
+
+## 纪律/坑
+
+> 三层一致（§6.3）：条件渲染 false 是空洞占位——数组项 key 由业务声明
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| demo | `apps/showcase/src/demos/DemoTableRowSelect.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/display/table-v2` ——（P1 填充具体步骤）

package/content/components/table.md

@@ -0,0 +1,66 @@
+# Table · components
+
+## 概述
+
+可排序 + 自定义 render + 空状态
+
+## 典型场景
+
+- 页面模式：app-shell、dashboard、list-page（复制即用蓝本——examples/patterns/）
+- 应用模板：admin、agent-platform（examples/apps/ 完整可跑）
+- 数据展示——列表页、详情页、信息呈现
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `data` | `any[]` | 否 |  |
+| `columns` | `TableColumn[]` | 是 |  |
+| `onRowClick` | `(row: any, index: number) => void` | 否 |  |
+| `sortKey` | `string` | 否 | 当前排序列的 key |
+| `sortOrder` | `'asc' \| 'desc'` | 否 | 当前排序方向 |
+| `onSort` | `(key: string, order: 'asc' \| 'desc') => void` | 否 | 排序变化回调 |
+| `rowSelection` | `TableRowSelection` | 否 | 行选择（受控） |
+| `emptyText` | `string` | 否 | 数据为空时显示的文本 |
+| `minWidth` | `string` | 否 | 表格最小宽度（窄屏横向滚动，如 '720px'） |
+| `onCellEdit` | `(key: string, rowIndex: number, value: string, row: any) => void` | 否 | 行内编辑提交回调（editable 列必配——受控纪律） |
+| `loading` | `boolean` | 否 | 加载中：保留表头，渲染骨架行 |
+| `loadingRows` | `number` | 否 | 骨架行数，默认 3 |
+
+## 用法示例
+
+```tsx
+<Table data={items} columns={[
+  {key:'id', label:'ID'},
+  {key:'name', label:'姓名', sortable: true},
+  {key:'status', label:'状态',
+    render: v => <Badge>{v}</Badge>},
+]}
+  sortKey="name" sortOrder="asc"
+  onSort={(k,o) => setSort(k,o)} />
+```
+
+## 纪律/坑
+
+- 固定列必须显式 width（缺省 140 估算 + console.warn——sticky 偏移累计依赖）
+- 数组空洞：children 里 {cond && <X/>} 是占位——不得误删下一个兄弟（提交按钮消失事故同源）
+- 行内编辑（editable 列）必须配 onCellEdit（受控纪律）
+
+## 关系
+
+- ↑ 用于页面模式：[app-shell](../patterns/app-shell.md) · [dashboard](../patterns/dashboard.md) · [list-page](../patterns/list-page.md)
+- ↑ 用于应用：[admin](../apps/admin.md) · [agent-platform](../apps/agent-platform.md)
+- → 后端能力：[sql](../backend/sql.md) · [redis](../backend/redis.md)
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Table/Table.ts` |
+| 样式 | `src/client/components/Table/Table.css` |
+| 测试 | `src/client/components/Table/Table.test.ts` |
+| demo | `apps/showcase/src/demos/DemoTable.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/display/table` ——（P1 填充具体步骤）

package/content/components/tabs.md

@@ -0,0 +1,56 @@
+# Tabs · components
+
+## 概述
+
+标签页切换，支持 active/onChange
+
+## 典型场景
+
+- 页面模式：workspace、settings-page（复制即用蓝本——examples/patterns/）
+- 应用模板：multi（examples/apps/ 完整可跑）
+- 页面导航——侧栏、页头、标签页、步骤、分页
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `items` | `TabItem[]` | 否 |  |
+| `active` | `string` | 否 |  |
+| `onChange` | `(key: string) => void` | 否 |  |
+| `closable` | `boolean` | 否 | 可关闭 tab（浏览器标签类应用——关闭中间 tab 自动激活邻居） |
+| `onClose` | `(key: string) => void` | 否 | 关闭回调（父负责从 items 移除；受控纪律：closable 必须配 onClose） |
+| `addable` | `boolean` | 否 | 显示新增 + 按钮 |
+| `onAdd` | `() => void` | 否 | 新增回调（父负责追加 items） |
+
+## 用法示例
+
+```tsx
+<Tabs items={[
+  {key:'a',label:'详情',
+    content:<p>...</p>},
+]} active="a" onChange={fn} />
+```
+
+## 纪律/坑
+
+- 混合数组稳定 key：tabList+addBtn+ink 全 keyed——无 key 项退 unkeyed 位置配对（新增 tab 错位事故）
+- closable 必须配 onClose / addable 必须配 onAdd（受控纪律——console.warn）
+
+## 关系
+
+- ↑ 用于页面模式：[workspace](../patterns/workspace.md) · [settings-page](../patterns/settings-page.md)
+- ↑ 用于应用：[multi](../apps/multi.md)
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Tabs/Tabs.ts` |
+| 样式 | `src/client/components/Tabs/Tabs.css` |
+| 测试 | `src/client/components/Tabs/Tabs.test.ts` |
+| demo | `apps/showcase/src/demos/DemoTabs.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/navigation/tabs` ——（P1 填充具体步骤）

package/content/components/tag.md

@@ -0,0 +1,51 @@
+# Tag · components
+
+## 概述
+
+标签，支持 closable/onClose
+
+## 典型场景
+
+- 页面模式：docs、list-page、detail-page（复制即用蓝本——examples/patterns/）
+- 应用模板：todo、admin、multi（examples/apps/ 完整可跑）
+- 基础元素（按钮/图标/文本/卡片/标签）——任意页面的构成单元
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `closable` | `boolean` | 否 |  |
+| `onClose` | `() => void` | 否 |  |
+| `variant` | `'default' \| 'primary' \| 'success' \| 'danger'` | 否 |  |
+| `children` | `any` | 否 |  |
+
+## 用法示例
+
+```tsx
+<Tag>标签</Tag>
+<Tag variant="primary" />
+<Tag closable>可关闭</Tag>
+```
+
+## 纪律/坑
+
+> 浏览器纪律（§5.5）：组件能力经 ctx.browser / ctx.ui.useXXX——禁裸 window/document
+
+## 关系
+
+- ↑ 用于页面模式：[docs](../patterns/docs.md) · [list-page](../patterns/list-page.md) · [detail-page](../patterns/detail-page.md)
+- ↑ 用于应用：[todo](../apps/todo.md) · [admin](../apps/admin.md) · [multi](../apps/multi.md)
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Tag/Tag.ts` |
+| 样式 | `src/client/components/Tag/Tag.css` |
+| 测试 | `src/client/components/Tag/Tag.test.ts` |
+| demo | `apps/showcase/src/demos/DemoTag.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/core/tag` ——（P1 填充具体步骤）

package/content/components/tagsinput-v2.md

@@ -0,0 +1,39 @@
+# TagsInput 限制/错误 · components
+
+## 概述
+
+maxTags 限制 + error 校验态（状态矩阵覆盖）
+
+## 典型场景
+
+- 表单输入/搜索/筛选——查询区、编辑表单、设置页
+
+## API
+
+> props 提取降级（接口格式特殊）——见源码：`—`
+
+## 用法示例
+
+```tsx
+<TagsInput value={tags} maxTags={3} error="标签超限" onChange={t => set(t)} />
+```
+
+## 纪律/坑
+
+> 受控输入纪律（§5.3）：输入期间 value 走内部态（useControlledInput）——依赖回流会重挂 input 丢焦点；IME composition 门控
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| demo | `apps/showcase/src/demos/DemoTagsInputErr.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/input/tagsinput-v2` ——（P1 填充具体步骤）

package/content/components/tagsinput.md

@@ -0,0 +1,54 @@
+# TagsInput · components
+
+## 概述
+
+标签输入：回车/逗号添加 + 中文输入法感知
+
+## 典型场景
+
+- 表单输入/搜索/筛选——查询区、编辑表单、设置页
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `value` | `string[]` | 否 |  |
+| `onChange` | `(tags: string[]) => void` | 否 |  |
+| `placeholder` | `string` | 否 |  |
+| `maxTags` | `number` | 否 |  |
+| `allowDuplicates` | `boolean` | 否 |  |
+| `disabled` | `boolean` | 否 |  |
+| `label` | `string` | 否 |  |
+| `error` | `string` | 否 |  |
+| `hint` | `string` | 否 |  |
+| `className` | `string` | 否 |  |
+
+## 用法示例
+
+```tsx
+<TagsInput value={tags} placeholder="回车添加标签"
+  maxTags={10} onChange={setTags} />
+```
+
+## 纪律/坑
+
+> 受控输入纪律（§5.3）：输入期间 value 走内部态（useControlledInput）——依赖回流会重挂 input 丢焦点；IME composition 门控
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/TagsInput/TagsInput.ts` |
+| 样式 | `src/client/components/TagsInput/TagsInput.css` |
+| 测试 | `src/client/components/TagsInput/TagsInput.test.ts` |
+| demo | `apps/showcase/src/demos/DemoTagsInput.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/input/tagsinput` ——（P1 填充具体步骤）