weifuwu 0.86.0 → 0.87.0

package/content/components/jsonschemaform.md

@@ -0,0 +1,53 @@
+# JsonSchemaForm · components
+
+## 概述
+
+JSON Schema → 参数输入表单：类型映射 + 必填/范围校验 + 嵌套/数组（AI 工具参数输入面）
+
+## 典型场景
+
+- 创建/编辑表单页——提交、校验、字段编排
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `schema` | `JsonSchema` | 是 | 顶层对象 schema（type: 'object' + properties） |
+| `value` | `Record<string, any>` | 否 | 初始值（非受控语义）；内部状态由编辑驱动 |
+| `onChange` | `(values: Record<string, any>) => void` | 否 | 每次编辑通知（父层可读最新值；不回流控制） |
+| `onSubmit` | `(values: Record<string, any>) => void` | 否 | 提交（校验通过才触发）；不传则不渲染提交按钮 |
+| `submitLabel` | `string` | 否 |  |
+
+## 用法示例
+
+```tsx
+<JsonSchemaForm
+  schema={toolSchema}
+  value={{ city: '北京' }}
+  onSubmit={(v) => console.log('执行', v)}
+  submitLabel="执行工具"
+/>
+```
+
+## 纪律/坑
+
+> 受控纪律（§5.2）：受控 props 必须配回调——缺回调静默不可点；受控输入（§5.3）输入态不依赖 value 回流（焦点丢失）
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/JsonSchemaForm/JsonSchemaForm.ts` |
+| 样式 | `src/client/components/JsonSchemaForm/JsonSchemaForm.css` |
+| 测试 | `src/client/components/JsonSchemaForm/JsonSchemaForm.test.ts` |
+| demo | `apps/showcase/src/demos/DemoJsonSchemaForm.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/form/jsonschemaform` ——（P1 填充具体步骤）

package/content/components/jsonviewer-v2.md

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

package/content/components/jsonviewer.md

@@ -0,0 +1,49 @@
+# JSONViewer · components
+
+## 概述
+
+结构化 JSON：递归折叠 + 类型色 + 路径复制 + 懒展开
+
+## 典型场景
+
+- 数据展示——列表页、详情页、信息呈现
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `data` | `unknown` | 是 |  |
+| `defaultExpandDepth` | `number` | 否 | 默认展开深度（默认 2）——更深折叠为摘要 |
+| `maxKeys` | `number` | 否 | 对象键数超过该值时懒展开（只渲染前 N 个 + "+N 项"，默认 100） |
+| `rootName` | `string` | 否 | 根键名（默认 'root'）——复制路径前缀 |
+| `onCopy` | `(path: string, value: unknown) => void` | 否 | 复制路径回调（默认 navigator.clipboard 写入 JSON 路径） |
+| `className` | `string` | 否 |  |
+
+## 用法示例
+
+```tsx
+<JSONViewer data={payload} defaultExpandDepth={2} maxKeys={100} />
+```
+
+## 纪律/坑
+
+> 三层一致（§6.3）：条件渲染 false 是空洞占位——数组项 key 由业务声明
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/JSONViewer/JSONViewer.ts` |
+| 样式 | `src/client/components/JSONViewer/JSONViewer.css` |
+| 测试 | `src/client/components/JSONViewer/JSONViewer.test.ts` |
+| demo | `apps/showcase/src/demos/DemoJSONViewer.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/display/jsonviewer` ——（P1 填充具体步骤）

package/content/components/kanban.md

@@ -0,0 +1,46 @@
+# Kanban · components
+
+## 概述
+
+看板：原生 DnD 拖拽 + 跨列/重排 + 悬停高亮
+
+## 典型场景
+
+- 数据看板/统计报表——指标卡、图表、趋势
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `columns` | `KanbanColumn[]` | 是 |  |
+| `onMove` | `(from: KanbanMove, to: KanbanMove) => void` | 否 | 受控：移动回调（from → to）。缺回调交互静默失效——受控纪律 warn |
+| `className` | `string` | 否 |  |
+
+## 用法示例
+
+```tsx
+<Kanban columns={cols} onMove={(from, to) => {}} />
+```
+
+## 纪律/坑
+
+- enumerated 属性（§6.2）：draggable 空字符串解析为 false——必须显式 setAttribute true/false（拖动变文本选中事故）
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Kanban/Kanban.ts` |
+| 样式 | `src/client/components/Kanban/Kanban.css` |
+| 测试 | `src/client/components/Kanban/Kanban.test.ts` |
+| demo | `apps/showcase/src/demos/DemoKanban.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/viz/kanban` ——（P1 填充具体步骤）

package/content/components/label.md

@@ -0,0 +1,48 @@
+# Label · components
+
+## 概述
+
+独立标签（required 星号）+ 宽高比容器（内容填满）
+
+## 典型场景
+
+- 基础元素（按钮/图标/文本/卡片/标签）——任意页面的构成单元
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `htmlFor` | `string` | 否 |  |
+| `required` | `boolean` | 否 | 必填星号 |
+| `children` | `any` | 否 |  |
+| `className` | `string` | 否 |  |
+
+## 用法示例
+
+```tsx
+<Label htmlFor="name">用户名</Label>
+<Label required>必填</Label>
+```
+
+## 纪律/坑
+
+> 浏览器纪律（§5.5）：组件能力经 ctx.browser / ctx.ui.useXXX——禁裸 window/document
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Label/Label.ts` |
+| 样式 | `src/client/components/Label/Label.css` |
+| 测试 | `src/client/components/Label/Label.test.ts` |
+| demo | `apps/showcase/src/demos/DemoLabel.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/core/label` ——（P1 填充具体步骤）

package/content/components/layout.md

@@ -0,0 +1,54 @@
+# Layout · components
+
+## 概述
+
+布局外壳：Sider 折叠 + Header/Content/Footer 骨架（antd Layout / shadcn Sidebar 等价）
+
+## 典型场景
+
+- 应用模板：admin（examples/apps/ 完整可跑）
+- 基础元素（按钮/图标/文本/卡片/标签）——任意页面的构成单元
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `style` | `any` | 否 |  |
+| `className` | `string` | 否 |  |
+| `children` | `any` | 否 |  |
+
+## 用法示例
+
+```tsx
+<Layout>
+  <LayoutSider collapsible collapsed onCollapse={setCollapsed}>导航</LayoutSider>
+  <Layout>
+    <LayoutHeader>顶部</LayoutHeader>
+    <LayoutContent>主区</LayoutContent>
+    <LayoutFooter>底部</LayoutFooter>
+  </Layout>
+</Layout>
+```
+
+## 纪律/坑
+
+> 浏览器纪律（§5.5）：组件能力经 ctx.browser / ctx.ui.useXXX——禁裸 window/document
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：[admin](../apps/admin.md)
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Layout/Layout.ts` |
+| 样式 | `src/client/components/Layout/Layout.css` |
+| 测试 | `src/client/components/Layout/Layout.test.ts` |
+| demo | `apps/showcase/src/demos/DemoLayout.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/core/layout` ——（P1 填充具体步骤）

package/content/components/layoutcontent.md

@@ -0,0 +1,43 @@
+# LayoutContent · components
+
+## 概述
+
+布局内容区——Layout 家族
+
+## 典型场景
+
+- 基础元素（按钮/图标/文本/卡片/标签）——任意页面的构成单元
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `style` | `any` | 否 |  |
+| `className` | `string` | 否 |  |
+| `children` | `any` | 否 |  |
+
+## 用法示例
+
+> （P1 迁移 CODE 字符串）
+
+## 纪律/坑
+
+> 浏览器纪律（§5.5）：组件能力经 ctx.browser / ctx.ui.useXXX——禁裸 window/document
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Layout/Layout.ts` |
+| 样式 | `src/client/components/Layout/Layout.css` |
+| 测试 | `src/client/components/Layout/Layout.test.ts` |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/core/layoutcontent` ——（P1 填充具体步骤）

package/content/components/layoutheader.md

@@ -0,0 +1,43 @@
+# LayoutHeader · components
+
+## 概述
+
+布局顶栏——Layout 家族（Layout/LayoutHeader/LayoutSider/LayoutContent/LayoutFooter）
+
+## 典型场景
+
+- 基础元素（按钮/图标/文本/卡片/标签）——任意页面的构成单元
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `style` | `any` | 否 |  |
+| `className` | `string` | 否 |  |
+| `children` | `any` | 否 |  |
+
+## 用法示例
+
+> （P1 迁移 CODE 字符串）
+
+## 纪律/坑
+
+> 浏览器纪律（§5.5）：组件能力经 ctx.browser / ctx.ui.useXXX——禁裸 window/document
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Layout/Layout.ts` |
+| 样式 | `src/client/components/Layout/Layout.css` |
+| 测试 | `src/client/components/Layout/Layout.test.ts` |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/core/layoutheader` ——（P1 填充具体步骤）

package/content/components/layoutsider.md

@@ -0,0 +1,43 @@
+# LayoutSider · components
+
+## 概述
+
+布局侧栏（可折叠 collapsed/collapsible）——Layout 家族
+
+## 典型场景
+
+- 基础元素（按钮/图标/文本/卡片/标签）——任意页面的构成单元
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `style` | `any` | 否 |  |
+| `className` | `string` | 否 |  |
+| `children` | `any` | 否 |  |
+
+## 用法示例
+
+> （P1 迁移 CODE 字符串）
+
+## 纪律/坑
+
+> 浏览器纪律（§5.5）：组件能力经 ctx.browser / ctx.ui.useXXX——禁裸 window/document
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Layout/Layout.ts` |
+| 样式 | `src/client/components/Layout/Layout.css` |
+| 测试 | `src/client/components/Layout/Layout.test.ts` |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/core/layoutsider` ——（P1 填充具体步骤）

package/content/components/link.md

@@ -0,0 +1,52 @@
+# Link · components
+
+## 概述
+
+文字链接：语义色/下划线/disabled/新窗口
+
+## 典型场景
+
+- 页面模式：landing（复制即用蓝本——examples/patterns/）
+- 基础元素（按钮/图标/文本/卡片/标签）——任意页面的构成单元
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `href` | `string` | 否 |  |
+| `variant` | `'default' \| 'primary' \| 'danger' \| 'muted'` | 否 |  |
+| `underline` | `boolean` | 否 |  |
+| `disabled` | `boolean` | 否 |  |
+| `target` | `string` | 否 |  |
+| `icon` | `any` | 否 |  |
+| `onClick` | `(e: any) => void` | 否 |  |
+| `children` | `any` | 否 |  |
+
+## 用法示例
+
+```tsx
+<Link href="/docs" variant="primary">文档</Link>
+```
+
+## 纪律/坑
+
+> 浏览器纪律（§5.5）：组件能力经 ctx.browser / ctx.ui.useXXX——禁裸 window/document
+
+## 关系
+
+- ↑ 用于页面模式：[landing](../patterns/landing.md)
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Link/Link.ts` |
+| 样式 | `src/client/components/Link/Link.css` |
+| 测试 | `src/client/components/Link/Link.test.ts` |
+| demo | `apps/showcase/src/demos/DemoLink.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/core/link` ——（P1 填充具体步骤）

package/content/components/list.md

@@ -0,0 +1,44 @@
+# List · components
+
+## 概述
+
+通用列表：renderItem + divided + header/footer/empty
+
+## 典型场景
+
+- 页面模式：workspace、mobile（复制即用蓝本——examples/patterns/）
+- 数据展示——列表页、详情页、信息呈现
+
+## API
+
+> props 提取降级（接口格式特殊）——见源码：`src/client/components/List/List.ts`
+
+## 用法示例
+
+```tsx
+<List divided header="最近文件" items={files}
+  renderItem={f => <div>{f.name}</div>} />
+```
+
+## 纪律/坑
+
+> 三层一致（§6.3）：条件渲染 false 是空洞占位——数组项 key 由业务声明
+
+## 关系
+
+- ↑ 用于页面模式：[workspace](../patterns/workspace.md) · [mobile](../patterns/mobile.md)
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/List/List.ts` |
+| 样式 | `src/client/components/List/List.css` |
+| 测试 | `src/client/components/List/List.test.ts` |
+| demo | `apps/showcase/src/demos/DemoList.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/display/list` ——（P1 填充具体步骤）

package/content/components/loading.md

@@ -0,0 +1,45 @@
+# Loading · components
+
+## 概述
+
+加载状态，支持自定义文字
+
+## 典型场景
+
+- 操作反馈/结果页/确认——保存成功、删除确认、空态/加载态
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `text` | `string` | 否 |  |
+
+## 用法示例
+
+```tsx
+<Loading />
+<Loading text="提交中..." />
+```
+
+## 纪律/坑
+
+> 退场动画（§8）：exit 类必须挂载（animationend 驱动）+ reduced-motion 降级
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Loading/Loading.ts` |
+| 样式 | `src/client/components/Loading/Loading.css` |
+| 测试 | `src/client/components/Loading/Loading.test.ts` |
+| demo | `apps/showcase/src/demos/DemoLoading.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/feedback/loading` ——（P1 填充具体步骤）

package/content/components/logviewer-v2.md

@@ -0,0 +1,39 @@
+# LogViewer 自定义 · components
+
+## 概述
+
+自定义日志源 + 行号 + 复制（变体覆盖）
+
+## 典型场景
+
+- 数据展示——列表页、详情页、信息呈现
+
+## API
+
+> props 提取降级（接口格式特殊）——见源码：`—`
+
+## 用法示例
+
+```tsx
+<LogViewer height={140} lines={ANSI日志} showLineNumbers showCopy />
+```
+
+## 纪律/坑
+
+> 三层一致（§6.3）：条件渲染 false 是空洞占位——数组项 key 由业务声明
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| demo | `apps/showcase/src/demos/DemoLogViewerCustom.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/display/logviewer-v2` ——（P1 填充具体步骤）

package/content/components/logviewer.md

@@ -0,0 +1,53 @@
+# LogViewer · components
+
+## 概述
+
+日志流：ANSI 着色 + 虚拟滚动 + 自动跟随 + 复制
+
+## 典型场景
+
+- 数据展示——列表页、详情页、信息呈现
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `lines` | `string[]` | 是 |  |
+| `height` | `number` | 否 | 视口高度（px），默认 400 |
+| `lineHeight` | `number` | 否 | 行高（px），默认 24 |
+| `overscan` | `number` | 否 | 可见区外额外渲染行数 |
+| `follow` | `boolean` | 否 | 自动跟随：新行到达时若已在底部则滚到底（默认 true） |
+| `maxLines` | `number` | 否 | 只显示尾部 N 行（内存保护，默认不限） |
+| `showCopy` | `boolean` | 否 | 显示复制按钮（默认 true） |
+| `showLineNumbers` | `boolean` | 否 | 显示行号（默认 true） |
+| `className` | `string` | 否 |  |
+
+## 用法示例
+
+```tsx
+<LogViewer lines={logs} height={260} follow
+  showCopy showLineNumbers maxLines={500} />
+```
+
+## 纪律/坑
+
+> 三层一致（§6.3）：条件渲染 false 是空洞占位——数组项 key 由业务声明
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/LogViewer/LogViewer.ts` |
+| 样式 | `src/client/components/LogViewer/LogViewer.css` |
+| 测试 | `src/client/components/LogViewer/LogViewer.test.ts` |
+| demo | `apps/showcase/src/demos/DemoLogViewer.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/display/logviewer` ——（P1 填充具体步骤）