weifuwu 0.86.0 → 0.87.0

package/content/components/form.md

@@ -0,0 +1,60 @@
+# Form · components
+
+## 概述
+
+内置验证规则：required/pattern/minLength/自定义
+
+## 典型场景
+
+- 页面模式：focus-task、settings-page（复制即用蓝本——examples/patterns/）
+- 应用模板：todo、auth、admin、agent-platform（examples/apps/ 完整可跑）
+- 创建/编辑表单页——提交、校验、字段编排
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `onSubmit` | `(values: Record<string, any>) => void \| Promise<void>` | 否 | 提交回调，接收字段名→值的对象 |
+| `validation` | `Record<string, ValidationRule[]>` | 否 | 验证规则：字段名 → 规则数组 |
+| `onError` | `(errors: Record<string, string>) => void` | 否 | 验证失败时回调，接收字段名→错误消息的对象 |
+| `children` | `any` | 否 |  |
+
+## 用法示例
+
+```tsx
+<Form
+  validation={{
+    email: {required: true, message: '必填'},
+  }}
+  onSubmit={values => ...}
+  onError={errors => ...}>
+  <Field label="邮箱" error={errors.email}>
+    <Input name="email" />
+  </Field>
+  <Button type="submit">提交</Button>
+</Form>
+```
+
+## 纪律/坑
+
+- 三层一致（§6.3）：条件渲染 false 是空洞占位——{cond && <Alert/>} 不滤除不塌缩（提交按钮消失事故）
+- 受控纪律：受控 value 必须配 onChange——缺回调静默不可点
+
+## 关系
+
+- ↑ 用于页面模式：[focus-task](../patterns/focus-task.md) · [settings-page](../patterns/settings-page.md)
+- ↑ 用于应用：[todo](../apps/todo.md) · [auth](../apps/auth.md) · [admin](../apps/admin.md) · [agent-platform](../apps/agent-platform.md)
+- → 后端能力：[sql](../backend/sql.md)
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Form/Form.ts` |
+| 样式 | `src/client/components/Form/Form.css` |
+| 测试 | `src/client/components/Form/Form.test.ts` |
+| demo | `apps/showcase/src/demos/DemoForm.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/form/form` ——（P1 填充具体步骤）

package/content/components/grid.md

@@ -0,0 +1,51 @@
+# Grid · components
+
+## 概述
+
+24 栅格 + gutter + flex 容器模式（Row/Col/Flex 等价）
+
+## 典型场景
+
+- 基础元素（按钮/图标/文本/卡片/标签）——任意页面的构成单元
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `gutter` | `number` | 否 |  |
+| `flex` | `boolean` | 否 |  |
+| `gap` | `number` | 否 |  |
+| `direction` | `'row' \| 'column'` | 否 |  |
+| `align` | `'start' \| 'center' \| 'end' \| 'stretch'` | 否 |  |
+| `children` | `any` | 否 |  |
+
+## 用法示例
+
+```tsx
+<Grid gutter={16}>
+  <Col span={8}>A</Col><Col span={8}>B</Col><Col span={8}>C</Col>
+</Grid>
+```
+
+## 纪律/坑
+
+> 浏览器纪律（§5.5）：组件能力经 ctx.browser / ctx.ui.useXXX——禁裸 window/document
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Grid/Grid.ts` |
+| 样式 | `src/client/components/Grid/Grid.css` |
+| 测试 | `src/client/components/Grid/Grid.test.ts` |
+| demo | `apps/showcase/src/demos/DemoGrid.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/core/grid` ——（P1 填充具体步骤）

package/content/components/highlight-v2.md

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

package/content/components/highlight.md

@@ -0,0 +1,46 @@
+# Highlight · components
+
+## 概述
+
+搜索词高亮：分词渲染 mark，大小写不敏感
+
+## 典型场景
+
+- 数据展示——列表页、详情页、信息呈现
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `text` | `string` | 是 |  |
+| `query` | `string \| string[]` | 否 |  |
+| `className` | `string` | 否 |  |
+
+## 用法示例
+
+```tsx
+<Highlight text="搜索 张三 的订单" query={['张三']} />
+```
+
+## 纪律/坑
+
+> 三层一致（§6.3）：条件渲染 false 是空洞占位——数组项 key 由业务声明
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Highlight/Highlight.ts` |
+| 样式 | `src/client/components/Highlight/Highlight.css` |
+| 测试 | `src/client/components/Highlight/Highlight.test.ts` |
+| demo | `apps/showcase/src/demos/DemoHighlight.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/display/highlight` ——（P1 填充具体步骤）

package/content/components/hovercard.md

@@ -0,0 +1,51 @@
+# HoverCard · components
+
+## 概述
+
+悬停富内容卡：openDelay 延迟 + 任意 VNode（shadcn）
+
+## 典型场景
+
+- 浮层交互——弹窗、下拉、气泡、抽屉、命令面板
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `content` | `any` | 是 | 富内容（任意 VNode，区别于 Tooltip 的 string） |
+| `position` | `HoverCardPosition` | 否 |  |
+| `children` | `any` | 是 |  |
+| `disabled` | `boolean` | 否 |  |
+| `openDelay` | `number` | 否 | 悬停打开延迟（ms），默认 150 |
+| `closeDelay` | `number` | 否 | 移出关闭延迟（ms），默认 0 |
+
+## 用法示例
+
+```tsx
+<HoverCard content={<UserCard />}>
+  <Button>悬停</Button>
+</HoverCard>
+```
+
+## 纪律/坑
+
+- portal 槽豁免：浮层插槽打开/关闭不触发 A 级动态数组检测（框架管理切换槽）
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/HoverCard/HoverCard.ts` |
+| 样式 | `src/client/components/HoverCard/HoverCard.css` |
+| 测试 | `src/client/components/HoverCard/HoverCard.test.ts` |
+| demo | `apps/showcase/src/demos/DemoHoverCard.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/overlay/hovercard` ——（P1 填充具体步骤）

package/content/components/icon.md

@@ -0,0 +1,50 @@
+# Icon · components
+
+## 概述
+
+stroke SVG 图标集，currentColor 着色，随字号缩放
+
+## 典型场景
+
+- 页面模式：app-shell、workspace、focus-task、docs、dashboard、data-screen、landing、mobile、list-page（复制即用蓝本——examples/patterns/）
+- 基础元素（按钮/图标/文本/卡片/标签）——任意页面的构成单元
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `name` | `IconName` | 是 |  |
+| `size` | `number \| string` | 否 | 尺寸，默认 1em（随字号缩放） |
+| `className` | `string` | 否 |  |
+
+## 用法示例
+
+```tsx
+<Icon name="check" size={16} />
+<Icon name="search" />
+<Icon name="settings" size={20} />
+{/* stroke SVG · currentColor · 1em 随字号 */}
+```
+
+## 纪律/坑
+
+> 浏览器纪律（§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) · [list-page](../patterns/list-page.md)
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Icon/Icon.ts` |
+| 样式 | `src/client/components/Icon/Icon.css` |
+| 测试 | `src/client/components/Icon/Icon.test.ts` |
+| demo | `apps/showcase/src/demos/DemoIcon.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/core/icon` ——（P1 填充具体步骤）

package/content/components/imagecropper.md

@@ -0,0 +1,45 @@
+# ImageCropper · components
+
+## 概述
+
+图片裁剪——canvas 原生 API + 拖拽裁剪框 + 比例控制（零依赖）
+
+## 典型场景
+
+- office 文档/代码/内容编辑——xlsx/pptx/代码/公式/裁剪
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `src` | `string` | 是 |  |
+| `aspect` | `number` | 否 | 裁剪比例（宽/高——默认 1） |
+| `onCrop` | `(dataUrl: string) => void` | 否 |  |
+| `onError` | `(err: Error) => void` | 否 |  |
+| `className` | `string` | 否 |  |
+
+## 用法示例
+
+> （P1 迁移 CODE 字符串）
+
+## 纪律/坑
+
+> 内容编辑：textarea value 走 property（attribute 只是 defaultValue）；受控输入纪律
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/ImageCropper/ImageCropper.ts` |
+| 样式 | `src/client/components/ImageCropper/ImageCropper.css` |
+| 测试 | `src/client/components/ImageCropper/ImageCropper.test.ts` |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/editor/imagecropper` ——（P1 填充具体步骤）

package/content/components/img.md

@@ -0,0 +1,56 @@
+# Img · components
+
+## 概述
+
+图片 \<img\> 组件：fallback / lazy / preview 点击放大
+
+## 典型场景
+
+- 数据展示——列表页、详情页、信息呈现
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `src` | `string` | 否 |  |
+| `alt` | `string` | 否 |  |
+| `fallback` | `string` | 否 |  |
+| `loading` | `'lazy' \| 'eager'` | 否 |  |
+| `width` | `number \| string` | 否 |  |
+| `height` | `number \| string` | 否 |  |
+| `className` | `string` | 否 |  |
+| `style` | `Record<string, string>` | 否 |  |
+| `preview` | `boolean` | 否 | 点击放大预览（对应 antd/EP Image preview） |
+| `previewScale` | `number` | 否 | 预览缩放倍率，默认 1 |
+
+## 用法示例
+
+```tsx
+<Img src="/photo.jpg" alt="照片" />
+<Img src="/photo.jpg" fallback="/placeholder.png" />
+<Img src="..." loading="lazy" width={200} />
+<Img src="..." preview /> {/* 点击放大：Escape/遮罩关闭 */}
+```
+
+## 纪律/坑
+
+> 三层一致（§6.3）：条件渲染 false 是空洞占位——数组项 key 由业务声明
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Img/Img.ts` |
+| 样式 | `src/client/components/Img/Img.css` |
+| 测试 | `src/client/components/Img/Img.test.ts` |
+| demo | `apps/showcase/src/demos/DemoImage.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/display/img` ——（P1 填充具体步骤）

package/content/components/infinitescroll-v2.md

@@ -0,0 +1,40 @@
+# InfiniteScroll 失败重试 · components
+
+## 概述
+
+加载失败提示 + 滚动重试（状态矩阵覆盖）
+
+## 典型场景
+
+- 大数据列表/表格/树——千级+数据量的性能场景
+
+## API
+
+> props 提取降级（接口格式特殊）——见源码：`—`
+
+## 用法示例
+
+```tsx
+<InfiniteScroll hasMore loading onLoadMore={加载}
+  endText="已全部加载">...</InfiniteScroll>
+```
+
+## 纪律/坑
+
+> 大数据渲染：固定行高 + 窗口化（VirtualList）——动态高度裁剪登记
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| demo | `apps/showcase/src/demos/DemoInfiniteScrollRetry.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/virtual/infinitescroll-v2` ——（P1 填充具体步骤）

package/content/components/infinitescroll.md

@@ -0,0 +1,54 @@
+# InfiniteScroll · components
+
+## 概述
+
+无限滚动：底部哨兵触底加载 + loading/end 态
+
+## 典型场景
+
+- 大数据列表/表格/树——千级+数据量的性能场景
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `hasMore` | `boolean` | 否 |  |
+| `loading` | `boolean` | 否 |  |
+| `onLoadMore` | `() => void` | 否 | 触底加载回调（sentinel 进入视口触发） |
+| `threshold` | `number` | 否 | 提前触发距离（px） |
+| `children` | `any` | 否 |  |
+| `loadMoreText` | `string` | 否 |  |
+| `endText` | `string` | 否 |  |
+| `className` | `string` | 否 |  |
+
+## 用法示例
+
+```tsx
+<InfiniteScroll hasMore loading={loading}
+  onLoadMore={loadMore}>
+  {items.map(i => <div>{i}</div>)}
+</InfiniteScroll>
+```
+
+## 纪律/坑
+
+> 大数据渲染：固定行高 + 窗口化（VirtualList）——动态高度裁剪登记
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/InfiniteScroll/InfiniteScroll.ts` |
+| 样式 | `src/client/components/InfiniteScroll/InfiniteScroll.css` |
+| 测试 | `src/client/components/InfiniteScroll/InfiniteScroll.test.ts` |
+| demo | `apps/showcase/src/demos/DemoInfiniteScroll.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/virtual/infinitescroll` ——（P1 填充具体步骤）

package/content/components/input.md

@@ -0,0 +1,65 @@
+# Input · components
+
+## 概述
+
+text/email/password/number，支持 label/error/hint/required
+
+## 典型场景
+
+- 页面模式：focus-task、settings-page（复制即用蓝本——examples/patterns/）
+- 应用模板：todo、auth、multi（examples/apps/ 完整可跑）
+- 表单输入/搜索/筛选——查询区、编辑表单、设置页
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `label` | `string` | 否 |  |
+| `name` | `string` | 否 |  |
+| `type` | `'text' \| 'email' \| 'password' \| 'number' \| 'url' \| 'date' \| 'tel' \| 'time' \| 'color'` | 否 |  |
+| `value` | `string` | 否 |  |
+| `placeholder` | `string` | 否 |  |
+| `required` | `boolean` | 否 |  |
+| `disabled` | `boolean` | 否 |  |
+| `readonly` | `boolean` | 否 | 只读（不可编辑但可复制） |
+| `error` | `string` | 否 |  |
+| `hint` | `string` | 否 |  |
+| `variant` | `'default' \| 'borderless'` | 否 | 边框变体：borderless 用于可编辑标题/内联编辑（hover/focus 才显边框） |
+| `onInput` | `(e: Event) => void` | 否 |  |
+| `onChange` | `(e: Event) => void` | 否 |  |
+| `min` | `string \| number` | 否 | 原生 input 属性透传（type=number 时 min/max/step 等） |
+| `max` | `string \| number` | 否 |  |
+| `step` | `string \| number` | 否 |  |
+
+## 用法示例
+
+```tsx
+<Input label="文本" value={text}
+  onInput={e => text = e.target.value} />
+<Input label="邮箱" type="email" required />
+<Input error="错误提示" />
+<Input hint="辅助文字" />
+```
+
+## 纪律/坑
+
+> 受控输入纪律（§5.3）：输入期间 value 走内部态（useControlledInput）——依赖回流会重挂 input 丢焦点；IME composition 门控
+
+## 关系
+
+- ↑ 用于页面模式：[focus-task](../patterns/focus-task.md) · [settings-page](../patterns/settings-page.md)
+- ↑ 用于应用：[todo](../apps/todo.md) · [auth](../apps/auth.md) · [multi](../apps/multi.md)
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Input/Input.ts` |
+| 样式 | `src/client/components/Input/Input.css` |
+| 测试 | `src/client/components/Input/Input.test.ts` |
+| demo | `apps/showcase/src/demos/DemoInput.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/input/input` ——（P1 填充具体步骤）

package/content/components/inputnumber.md

@@ -0,0 +1,58 @@
+# InputNumber · components
+
+## 概述
+
+数字输入：min/max/step + 增减按钮 + precision
+
+## 典型场景
+
+- 表单输入/搜索/筛选——查询区、编辑表单、设置页
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `value` | `number \| null` | 否 |  |
+| `onChange` | `(value: number \| null) => void` | 否 |  |
+| `min` | `number` | 否 |  |
+| `max` | `number` | 否 |  |
+| `step` | `number` | 否 |  |
+| `precision` | `number` | 否 |  |
+| `label` | `string` | 否 |  |
+| `name` | `string` | 否 |  |
+| `placeholder` | `string` | 否 |  |
+| `disabled` | `boolean` | 否 |  |
+| `error` | `string` | 否 |  |
+| `hint` | `string` | 否 |  |
+| `required` | `boolean` | 否 |  |
+| `className` | `string` | 否 |  |
+
+## 用法示例
+
+```tsx
+<InputNumber value={0.7} min={0} max={1} step={0.1} precision={1}
+  onChange={v => setTemp(v)} />
+```
+
+## 纪律/坑
+
+> 受控输入纪律（§5.3）：输入期间 value 走内部态（useControlledInput）——依赖回流会重挂 input 丢焦点；IME composition 门控
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/InputNumber/InputNumber.ts` |
+| 样式 | `src/client/components/InputNumber/InputNumber.css` |
+| 测试 | `src/client/components/InputNumber/InputNumber.test.ts` |
+| demo | `apps/showcase/src/demos/DemoInputNumber.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/input/inputnumber` ——（P1 填充具体步骤）

package/content/components/inview.md

@@ -0,0 +1,56 @@
+# InView · components
+
+## 概述
+
+进入视窗后懒加载内容，支持 IntersectionObserver
+
+## 典型场景
+
+- 数据展示——列表页、详情页、信息呈现
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `once` | `boolean` | 否 |  |
+| `threshold` | `number` | 否 |  |
+| `rootMargin` | `string` | 否 |  |
+| `placeholder` | `any` | 否 |  |
+| `onEnter` | `() => void` | 否 |  |
+| `children` | `any` | 否 |  |
+
+## 用法示例
+
+```tsx
+<InView>
+  <ExpensiveComponent />
+</InView>
+
+<InView once={false} rootMargin="200px"
+  onEnter={() => console.log('进入')}>
+  <img src="large.jpg" />
+</InView>
+```
+
+## 纪律/坑
+
+> 三层一致（§6.3）：条件渲染 false 是空洞占位——数组项 key 由业务声明
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/InView/InView.ts` |
+| 样式 | `src/client/components/InView/InView.css` |
+| 测试 | `src/client/components/InView/InView.test.ts` |
+| demo | `apps/showcase/src/demos/DemoInView.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/display/inview` ——（P1 填充具体步骤）