weifuwu 0.64.0 → 0.65.0

package/dist/index.js

@@ -4345,6 +4345,65 @@ function createSsrContext(serverCtx, dataStore) {
     },
     usePopupPosition: () => ({ top: 0, left: 0, refresh: () => {
     } }),
+    // 新原语族：SSR 确定性 no-op（不启动监听/会话/取数；组件挂载不崩即契约）
+    useHoverCapable: () => false,
+    useVisualViewport: () => ({ height: 0, offsetTop: 0, keyboardOpen: false }),
+    useLongPress: () => ({}),
+    useInView: () => ({ isIn: false, ready: false, observe: () => {
+    }, refresh: () => {
+    }, disconnect: () => {
+    } }),
+    useScrollPosition: () => ({ y: 0, refresh: () => {
+    } }),
+    useStableRef: (init) => (el) => {
+      if (el) init?.(el);
+    },
+    useGlobalKey: () => () => {
+    },
+    useReducedMotion: () => false,
+    useAnimationEnd: () => () => {
+    },
+    useTween: (target) => {
+      const handle = { value: target, reset: (to) => {
+        handle.value = to;
+      } };
+      return handle;
+    },
+    useDrag: () => ({ onPointerDown: () => {
+    } }),
+    useDragDrop: () => ({ dropProps: {} }),
+    useControlled: (options) => ({
+      value: options.value,
+      setValue: (v) => {
+        options.onChange?.(v);
+      },
+      controlled: options.value !== void 0
+    }),
+    useAsync: () => ({ data: void 0, loading: true, error: void 0, reload: () => {
+    } }),
+    usePopup: () => ({
+      open: false,
+      setOpen: () => {
+      },
+      wrapProps: {},
+      portal: () => null,
+      refresh: () => {
+      }
+    }),
+    usePresence: () => ({
+      phase: "closed",
+      ref: () => {
+      },
+      sync: (open2) => open2 ? "open" : "closed"
+    }),
+    useDialog: () => ({
+      phase: "closed",
+      rootRef: () => {
+      },
+      panelRef: () => {
+      },
+      sync: (open2) => open2 ? "open" : "closed"
+    }),
     // SSR 确定性空态：会话不启动（无事件/无网络），仅保证挂载不崩
     useChat: () => ({
       messages: [],

package/docs/components-map.md

@@ -0,0 +1,153 @@
+# weifuwu/components 组件速查（对应 antd / Element Plus / shadcn-ui）
+
+> **开发者迁移速查**：从 antd / Element Plus / shadcn-ui 迁到 weifuwu，按功能找到对应组件。
+> 左侧是 **weifuwu 组件**（已提供），右侧是对应的三库组件 + 差异备注。
+> 真实未实现清单（仅 4 项）：见文末「weifuwu 尚未实现」。
+
+## 通用基础
+
+| 功能 | weifuwu | antd | Element Plus | shadcn-ui | 差异说明 |
+|------|---------|------|-------------|-----------|---------|
+| 按钮 | `<Button variant size loading block>` | Button | Button | Button | 命名基本一致；weifuwu `variant`=primary/secondary/ghost/danger |
+| 图标 | `<Icon name>`（自研 30+ stroke SVG） | Icon | Icon | lucide-react | weifuwu 零依赖、currentColor、1em 随字号；组件内部统一走 Icon |
+| 文本排版 | `<Title/Text/Paragraph>` | Typography | Typography | — | 语义标签 + 语义色 `-text` 变体 + mark/code/删除线 |
+| 分割线 | `<Divider>`（horizontal/vertical/带文字） | Divider | Divider | Separator | 等价 |
+| 头像 | `<Avatar name src color size>` | Avatar | Avatar | Avatar | weifuwu 支持名字哈希色 + 指定色 |
+| 头像组 | `<AvatarGroup items max size>` | Avatar.Group | 手动组合 | 手动组合 | weifuwu 独立组件，`max` 溢出显示 +N |
+| 标签/标签组 | `<Label>`（required 星号）/ `<TagsInput>`（回车/逗号/去重） | Form.Item 标签 / Select tags | — | Label | Label 独立组件 |
+
+## 导航
+
+| 功能 | weifuwu | antd | Element Plus | shadcn-ui | 差异说明 |
+|------|---------|------|-------------|-----------|---------|
+| 菜单/侧栏 | `<Menu items group activeKey onSelect>`（方向键导航） | Menu | Menu | NavigationMenu / Sidebar | 分组 group 已支持；**子菜单/折叠未实现** |
+| 面包屑 | `<Breadcrumb items>` | Breadcrumb | Breadcrumb | Breadcrumb | 等价 |
+| 标签页 | `<Tabs items active onChange>`（方向键 + 移动端横向滚动） | Tabs | Tabs | Tabs | 等价 |
+| 分页 | `<Pagination total page onChange>`（页码折叠 + 移动端 44px） | Pagination | Pagination | Pagination | 等价 |
+| 步骤条 | `<Steps items current>` | Steps | Steps | — | 等价 |
+| 下拉菜单 | `<Dropdown items>`（danger variant） | Dropdown | Dropdown | DropdownMenu | 等价（usePopup：外部点击/Escape 关闭） |
+| 水平菜单栏 | `<Menubar menus>`（←→↓ 键盘 + 触屏） | Menu 水平 | Menu | Menubar | 等价 |
+| 页面标题 | `<PageHeader title sub>` | PageHeader（v5 移除） | PageHeader | — | weifuwu 保留独立组件 |
+| 回到顶部 | `<BackTop threshold>` | FloatButton / BackTop | Backtop | — | 滚动超阈值显示 |
+| 固定定位 | `<Affix offsetTop>` | Affix | Affix | — | useScrollPosition 实现 |
+| 锚点 | 未实现 | Anchor | Anchor | — | 待补 |
+
+## 表单
+
+| 功能 | weifuwu | antd | Element Plus | shadcn-ui | 差异说明 |
+|------|---------|------|-------------|-----------|---------|
+| 输入框 | `<Input label error hint variant>` | Input | Input | Input | weifuwu 自带 label/error/hint 包装（antd 需 Form.Item）；`variant="borderless"` 内联编辑 |
+| 文本域 | `<Textarea rows showCount maxLength>` | Input.TextArea | Input textarea | Textarea | weifuwu 独立组件 + 字数统计 |
+| 选择器 | `<Select options searchable multiple>` | Select | Select | Select / Combobox | **searchable + 键盘 ↑↓ + multiple 已实现**（近 Combobox） |
+| 复选框 | `<Checkbox checked label>` | Checkbox | Checkbox | Checkbox | 等价 |
+| 复选组 | `<CheckboxGroup options value>` | Checkbox.Group | Checkbox 组 | — | 数组受控 + 栅格列数 |
+| 单选 | `<RadioGroup options value>` | Radio.Group | Radio | RadioGroup | 等价 |
+| 开关 | `<Switch checked>` | Switch | Switch | Switch | 等价 |
+| 滑块 | `<Slider min max step>` | Slider | Slider | Slider | 等价 |
+| 数字输入 | `<InputNumber min max step precision>`（增减按钮+clamp） | InputNumber | InputNumber | — | 等价 |
+| 密码输入 | `<PasswordInput>`（眼睛切换） | Input.Password | Input show-password | — | weifuwu 独立组件 |
+| 日期选择 | `<DatePicker mode="date\|datetime\|time\|range">`（四合一） | DatePicker / TimePicker / RangePicker | DatePicker / DateTimePicker / TimePicker | Calendar + DatePicker 组合 | **一个组件覆盖三库四个**；移动端 range 自动堆叠 |
+| 评分 | `<Rate value>`（键盘方向键） | Rate | Rate | — | allowClear/readOnly |
+| 验证码 | `<PinInput length>`（粘贴/回退/自动聚焦） | — | — | InputOTP | 等价 |
+| 颜色选择 | `<ColorPicker value>`（预设色板 + hex） | ColorPicker | ColorPicker | — | Popover 弹层 |
+| 标签输入 | `<TagsInput value onChange>`（回车/逗号/去重） | Select mode="tags" | 手动组合 | — | weifuwu 独立组件 |
+| 搜索框 | `<SearchInput>` | Input.Search | Input search | — | weifuwu 独立组件 |
+| 分段控件 | `<SegmentedControl options value>` | Segmented | — | ToggleGroup 近似 | weifuwu 独立组件 |
+| 切换按钮 | `<Toggle>/<ToggleGroup>`（single/multiple） | — | — | ToggleGroup | shadcn 对齐 |
+| 表单 | `<Form>` + `<Field label error>`（校验规则） | Form + Form.Item | Form + Form.Item | Form | weifuwu Field 轻量（无 Provider 样板） |
+| 文件上传 | `<FileUpload drag multiple accept maxSize>` | Upload | Upload | — | 拖拽已支持；文件列表/预览/进度待增强 |
+
+## 数据展示
+
+| 功能 | weifuwu | antd | Element Plus | shadcn-ui | 差异说明 |
+|------|---------|------|-------------|-----------|---------|
+| 表格 | `<Table columns data sortable onSort>` | Table | Table | Table | 列排序 + **行选择/筛选/列宽已实现**；虚拟表格待补 |
+| 卡片 | `<Card clickable hover padding>` | Card | Card | Card | clickable/hover 抬升/active 选中态 |
+| 标签 | `<Tag variant closable>` | Tag | Tag | Badge（variant） | closable 已支持 |
+| 徽标 | `<Badge variant dot>`（8px 状态点） | Badge | Badge | Badge | `dot` = 状态点 |
+| 列表 | `<List items renderItem empty>` | List | 手动 v-for | — | 通用列表 |
+| 时间线 | `<Timeline items status>` | Timeline | Timeline | — | 节点状态色 + 图标 |
+| 描述列表 | `<Descriptions items column bordered>`（dl/dt/dd 语义） | Descriptions | Descriptions | — | 等价 |
+| 统计卡片 | `<StatCard label value trend animate>` | Statistic | Statistic | — | 卡片形态 + 点击 + 动画 |
+| 图片 | `<Img src fallback lazy preview>` | Image | Image | — | **preview 点击放大已实现** |
+| 图表 | `<Chart type data>`（自研零依赖） | — | — | Chart（recharts 包装） | 自研 line/bar/pie，无运行时依赖 |
+| 骨架屏 | `<Skeleton variant count>` | Skeleton | Skeleton | Skeleton | 等价 |
+| 空状态 | `<EmptyState icon text hint>` | Empty | Empty | — | icon 用 emoji/Icon + 操作区 |
+| 结果页 | `<Result status title desc extra>` | Result | Result | — | 等价（success/error/warning/info） |
+| 搜索高亮 | `<Highlight text query>`（`<mark>` 分词） | — | — | — | weifuwu 独有（配 SearchInput/Table） |
+| 树 | `<Tree data checkable checkedKeys>` | Tree | Tree | — | 勾选父子联动 + indeterminate |
+| 级联 | `<Cascader options value>` | Cascader | Cascader | — | 多列面板逐级推进 |
+| 穿梭框 | `<Transfer data targetKeys>` | Transfer | Transfer | — | 双列表 + 移动；移动端自动堆叠 |
+| 月历 | `<Calendar month year events>` | Calendar | Calendar | — | 事件点 + 月切换 |
+| 虚拟列表 | `<VirtualList height itemHeight>` | — | — | — | spacer + 可见窗口，200 条只渲染 ~12 |
+
+## 反馈
+
+| 功能 | weifuwu | antd | Element Plus | shadcn-ui | 差异说明 |
+|------|---------|------|-------------|-----------|---------|
+| 提示条 | `<Alert variant closable>` | Alert | Alert | Alert | 等价 |
+| 模态框 | `<Modal open title onClose width>` | Modal | Dialog | Dialog | `open/onClose`（antd v5 同）；焦点 trap + 归还；移动端 bottom-sheet |
+| 确认框 | `<Confirm>` + `await confirm()` 命令式 | Popconfirm / Modal.confirm | Popconfirm / MessageBox | AlertDialog | 声明式 + 命令式双模式 |
+| 抽屉 | `<Drawer position="left\|right\|top\|bottom">` | Drawer | Drawer | Sheet / Drawer | **四方向覆盖 shadcn Sheet + Drawer**；移动端全宽 |
+| 气泡 | `<Popover position>`（视口夹紧） | Popover | Popover | Popover | 等价（usePopup：外部点击/Escape/tap 降级） |
+| 悬浮提示 | `<Tooltip content position>`（string） | Tooltip | Tooltip | Tooltip | usePopup：桌面 hover / 触屏 tap |
+| 悬停卡 | `<HoverCard content>`（富内容 + 延迟） | — | — | HoverCard | shadcn 对齐；触屏 tap |
+| 右键菜单 | `<ContextMenu items>` | Dropdown context | — | ContextMenu | 桌面右键 + **触屏长按**双通道 |
+| 消息 | `<Toast>` + `toast()` 命令式 | message | Message | Sonner | 命令式 `toast('已保存','success')` |
+| 通知 | `<Notification>` + `notification.success()` | notification | Notification | — | 队列式通知 |
+| 加载 | `<Loading>` | Spin | Loading | — | 等价 |
+| 进度条 | `<ProgressBar value>` | Progress | Progress | Progress | 等价（线性） |
+| 折叠 | `<Collapse items active>`（异步 loading + extra） | Collapse | Collapse | Collapse | 行内折叠（区别于 Accordion） |
+| 手风琴 | `<Accordion items>` | Collapse accordion | Collapse accordion | Accordion | 单开折叠 |
+| 复制按钮 | `<CopyButton value>`（clipboard + 降级 + 成功态） | — | — | — | Chat/CodeBlock 证据驱动 |
+| 水印 | `<Watermark text>`（canvas 平铺 + overlay） | Watermark | — | — | 自研 |
+| 二维码 | `<QRCode value>`（Reed-Solomon + 8 掩码） | QRCode | QRCode | — | **自研编码零依赖** |
+| 轮播 | `<Carousel autoplay>`（箭头/圆点/循环 + 触摸） | Carousel | Carousel | — | 触摸滑动 + 触屏命中区 |
+| 分割面板 | `<Resizable defaultSize>`（拖拽 + 键盘 + clamp） | Splitter | — | Resizable | 指针 + 方向键 |
+| 回到顶部按钮 | `<BackTop>` | FloatButton.BackTop | Backtop | — | 滚动监听 |
+
+## AI / 特色（三库无，weifuwu 独有）
+
+| 组件 | 说明 |
+|------|------|
+| `<AiChat>` | 完整 AI 对话界面（流式 token/工具卡/审批卡/自动滚动），配 `ctx.ui.useChat()`；移动端 `raiseOnKeyboard` |
+| `<Markdown content>` | 零依赖安全子集 parser（无 raw HTML 注入，VNode 渲染天然转义） |
+| `<CodeBlock code lang>` | 代码块 + 语言标签 + 复制按钮 |
+| `<MessageBubble role status>` | 聊天气泡（独立复用，AiChat 抽取） |
+| `<ToolCallCard>` | AI 工具调用状态机（running/ok/error） |
+| `<ApprovalCard>` | HITL 人工审批卡片（pending/approved/rejected/timeout） |
+| `<Editor>` | 富文本编辑器（contentEditable + 工具栏/表格/图片，零依赖） |
+| `<ThemeSwitch>` | 明暗主题切换（CSS 变量驱动，配 `data-theme`） |
+| `<InView>` | 交叉观察（进入视口触发，可做无限滚动） |
+| `<AspectRatio>` | 宽高比容器（内容填满） |
+| `<CopyButton>` | 复制（clipboard + execCommand 降级 + 成功状态机） |
+
+## 快速迁移路径（三库 → weifuwu）
+
+```tsx
+// antd / shadcn 开发者
+<Modal open={show} onClose={f}>…</Modal>          // antd v5 同命名，直接迁移
+<Select options={opts} value={v} onChange={f} />   // 同命名
+<Button variant="primary">保存</Button>            // antd type="primary" → variant
+
+// Element Plus 开发者（v-model 模板语法 → value/onChange）
+<Input :value="v" @input="f" />                    // → <Input value={v} onInput={f} />
+<ElDialog :visible="s" @close="f" />               // → <Modal open={s} onClose={f} />
+<ElMessage>成功</ElMessage>                        // → toast('成功','success')
+
+// shadcn 开发者（原子组合 → 成品）
+<Dialog><DialogTrigger/>…</Dialog>                 // → <Modal open onClose> 一体组件
+<Sheet><SheetTrigger/>…</Sheet>                    // → <Drawer position="bottom">
+<Badge variant="secondary">x</Badge>               // → <Tag variant="secondary">x</Tag>
+```
+
+## weifuwu 尚未实现（三库有）→ 待补清单
+
+仅 4 项：
+
+- **Anchor**（锚点导航，三库均有）
+- **Menu 子菜单/折叠**（分组 group 已支持，子级/折叠待补）
+- **FileUpload 增强**（拖拽已支持；文件列表/预览/进度待补）
+- **VirtualTable**（VirtualList 已有，表格虚拟化待补）
+
+> 难度阶梯（L1-L6）与验证的 client 能力点：见 `design/components-cdd.md`；三库 → weifuwu 覆盖矩阵：见 `design/components-migration.md`。

package/docs/components.md

@@ -4,7 +4,8 @@
 
 92 个 HTML 原语组件。每个是 `(_init, ctx) => (props) => VNode`（两阶段组件，与前端框架同一模型），引用 `--wf-*` CSS 变量做主题。另含 `confirm()` / `toast()` 命令式中间件。
 
-> **组件速查（weifuwu 组件 ↔ antd / Element Plus / shadcn-ui 对应 + 迁移示例）**：见 [`design/components-map.md`](../design/components-map.md)——从其他组件库迁来的开发者按功能直接找对应组件。
+> **组件速查（weifuwu 组件 ↔ antd / Element Plus / shadcn-ui 对应 + 迁移示例）**：见 [`docs/components-map.md`](components-map.md)——从其他组件库迁来的开发者按功能直接找对应组件。
+> **自定义组件开发**：见 [docs/custom-components.md](custom-components.md)——usePopup/useControlled/对话框/AI 组件/类型纪律逐步指南。
 
 ```ts
 import { Button, Input, Table, Modal, Toast } from 'weifuwu/components'
@@ -163,6 +164,350 @@ props 变化 ──────────────────────
 | `局部刷新` | `ctx.ui.render()` 或 `$.x = val` |
 | `跨组件刷新` | `ctx.ui.selfId('name')` + `render(['name'])` |
 
+## 通用约定（所有组件一致）
+
+### 受控模式
+
+| 组件类型 | 受控 prop | 必须配回调 |
+|----------|-----------|-----------|
+| 开关/勾选（Checkbox/Switch/RadioGroup） | `checked` | `onChange` |
+| 输入（Input/Select/DatePicker/Textarea） | `value` | `onChange` / `onInput` |
+| 标签页/折叠（Tabs/Collapse） | `active` | `onChange` |
+| 弹层（Modal/Drawer/Dropdown/Popover） | `open` | `onClose` / `onOpenChange` |
+| 树/级联/穿梭（Tree/Cascader/Transfer） | `checkedKeys`/`value`/`targetKeys` | `onChange` |
+| 月历（Calendar） | `month`/`year` | `onMonthChange` |
+
+**规则**：传受控 props 而不传回调时，交互**静默失效**——组件 `console.warn` 明确提示（Collapse/Tree/Calendar/Cascader/Dropdown 已有防护）。非受控（不传受控 props）即可直接点击。
+
+### size 变体
+
+- `sm` / `md` / `lg`（Button/Avatar/Input 族）。未提供 size 的组件使用默认尺寸（CSS `--wf-control-pad-*` 驱动）。
+- 触屏（coarse pointer）自动 44px 命中区，不受 size 影响。
+
+### 事件命名
+
+| 语义 | 命名 |
+|------|------|
+| 值变化（受控） | `onChange` |
+| 原生输入 | `onInput` |
+| 列表选中 | `onSelect` |
+| 弹层开关 | `onOpenChange`（弹层）/ `onClose`（对话框） |
+| 表格排序 | `onSort` |
+
+### 命令式 API（无需组件）
+
+`confirm()` / `toast()` / `notification.success()`——组件内 `ctx.confirm?.('确定？')` 直接可用（中间件注入）。
+
+## 关键组件 Props 参考
+> 从组件 TS 类型自动提取（`src/components/*/*.ts` 的 `interface XxxProps`）。
+> 完整 props 以 TS 类型为准——`tsc` 编译期校验；此处为速查。受控约定：传受控 props 必须配回调（缺回调运行期 warn）。
+
+### Button（表单/通用）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `variant` | `'primary' \| 'secondary' \| 'ghost' \| 'danger'` | — |
+| `size` | `'sm' \| 'md' \| 'lg'` | — |
+| `block` | `boolean` | — |
+| `loading` | `boolean` | — |
+| `disabled` | `boolean` | — |
+| `type` | `'button' \| 'submit'` | — |
+| `title` | `string` | — |
+| `class` | `string` | 透传原生 class（覆盖默认 wf-btn 组合） |
+| `onClick` | `(e: MouseEvent) => void` | — |
+| `children` | `any` | — |
+
+### Input（表单核心）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `label` | `string` | — |
+| `name` | `string` | — |
+| `type` | `'text' \| 'email' \| 'password' \| 'number' \| 'url' \| 'date' \| 'tel' \| 'time' \| 'color'` | — |
+| `value` | `string` | — |
+| `placeholder` | `string` | — |
+| `required` | `boolean` | — |
+| `disabled` | `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` | — |
+| `key` | `string]: any` | — |
+
+### Textarea（表单核心）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `label` | `string` | — |
+| `value` | `string` | — |
+| `placeholder` | `string` | — |
+| `required` | `boolean` | — |
+| `disabled` | `boolean` | — |
+| `error` | `string` | — |
+| `hint` | `string` | — |
+| `rows` | `number` | — |
+| `maxLength` | `number` | 最大字符数（同时限制输入） |
+| `showCount` | `boolean` | 显示字数统计（右下角；配合受控 value 实时更新） |
+| `onInput` | `(e: Event) => void` | — |
+
+### Select（表单选择）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `label` | `string` | — |
+| `value` | `string \| string[]` | — |
+| `options` | `SelectOption[]` | — |
+| `placeholder` | `string` | — |
+| `required` | `boolean` | — |
+| `disabled` | `boolean` | — |
+| `error` | `string` | — |
+| `onChange` | `(value: string \| string[]) => void` | — |
+| `children` | `any` | — |
+| `searchable` | `boolean` | 启用搜索过滤 |
+| `multiple` | `boolean` | 多选模式（searchable 下生效；value/onChange 为数组） |
+| `onSearch` | `(keyword: string) => SelectOption[] \| Promise<SelectOption[]>` | 异步搜索回调，返回值作为新选项列表 |
+
+### Checkbox（表单选择）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `label` | `string` | — |
+| `checked` | `boolean` | — |
+| `disabled` | `boolean` | — |
+| `onChange` | `(checked: boolean) => void` | — |
+
+### Switch（表单选择）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `label` | `string` | — |
+| `checked` | `boolean` | — |
+| `disabled` | `boolean` | — |
+| `onChange` | `(checked: boolean) => void` | — |
+
+### RadioGroup（表单选择）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `name` | `string` | — |
+| `value` | `string` | — |
+| `options` | `RadioOption[]` | — |
+| `inline` | `boolean` | — |
+| `onChange` | `(value: string) => void` | — |
+
+### DatePicker（表单选择）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `mode` | `DatePickerMode` | — |
+| `value` | `string` | — |
+| `onChange` | `(value: string) => void` | — |
+| `placeholder` | `string` | — |
+| `disabled` | `boolean` | — |
+
+### Form（表单增强）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `onSubmit` | `(values: Record<string, any>) => void \| Promise<void>` | 提交回调，接收字段名→值的对象 |
+| `validation` | `Record<string, ValidationRule[]>` | 验证规则：字段名 → 规则数组 |
+| `onError` | `(errors: Record<string, string>) => void` | 验证失败时回调，接收字段名→错误消息的对象 |
+| `children` | `any` | — |
+
+### Field（表单增强）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `label` | `string` | — |
+| `required` | `boolean` | — |
+| `error` | `string` | — |
+| `hint` | `string` | — |
+| `children` | `any` | — |
+
+### Table（数据展示）
+| 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'） |
+| `loading` | `boolean` | 加载中：保留表头，渲染骨架行 |
+| `loadingRows` | `number` | 骨架行数，默认 3 |
+
+### Modal（数据反馈）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `open` | `boolean` | — |
+| `title` | `string` | — |
+| `onClose` | `() => void` | — |
+| `children` | `any` | — |
+| `footer` | `any` | — |
+| `width` | `string` | 自定义宽度，如 '500px'、'80%'，默认 400px |
+| `closable` | `boolean` | 是否显示关闭按钮，默认 true |
+| `maskClosable` | `boolean` | 点击遮罩是否关闭，默认 true（危险确认应设 false） |
+
+### Drawer（数据反馈）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `open` | `boolean` | — |
+| `title` | `string` | — |
+| `position` | `DrawerPosition` | — |
+| `onClose` | `() => void` | — |
+| `children` | `any` | — |
+| `footer` | `any` | — |
+
+### Confirm（数据反馈）
+| 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` | — |
+
+### Toast（数据反馈）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `toasts` | `ToastItem[]` | — |
+| `onRemove` | `(id: string) => void` | — |
+| `position` | `ToastPosition` | 容器位置，默认 top-right |
+| `duration` | `number` | 全局默认自动消失时间（ms），0 = 不自动消失，默认 0 |
+| `max` | `number` | 最大显示条数，超出时移除最早条目，默认 0 = 不限制 |
+
+### Tooltip（数据反馈）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `content` | `string` | — |
+| `position` | `TooltipPosition` | — |
+| `children` | `any` | — |
+| `disabled` | `boolean` | — |
+
+### Popover（数据反馈）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `content` | `any` | — |
+| `trigger` | `'click' \| 'hover'` | — |
+| `position` | `PopoverPosition` | — |
+| `open` | `boolean` | — |
+| `onOpenChange` | `(open: boolean) => void` | — |
+| `disabled` | `boolean` | — |
+| `children` | `any` | — |
+
+### Dropdown（导航组件）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `trigger` | `any` | — |
+| `items` | `DropdownItem[]` | — |
+| `open` | `boolean` | — |
+| `onOpenChange` | `(open: boolean) => void` | 关闭回调（面板内 Escape / 外部点击） |
+
+### Tabs（导航组件）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `items` | `TabItem[]` | — |
+| `active` | `string` | — |
+| `onChange` | `(key: string) => void` | — |
+
+### Pagination（导航组件）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `total` | `number` | — |
+| `page` | `number` | — |
+| `pageSize` | `number` | — |
+| `onChange` | `(page: number) => void` | — |
+
+### Tree（新增批次）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `data` | `TreeNode[]` | — |
+| `selectedKeys` | `string[]` | 受控选中 keys |
+| `onSelect` | `(keys: string[]) => void` | — |
+| `expandedKeys` | `string[]` | 受控展开 keys |
+| `onExpand` | `(keys: string[]) => void` | — |
+| `checkable` | `boolean` | 勾选模式（父子联动，antd 非 strict 语义） |
+| `checkedKeys` | `string[]` | — |
+| `onCheck` | `(keys: string[]) => void` | — |
+| `className` | `string` | — |
+
+### Cascader（新增批次）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `options` | `CascaderOption[]` | — |
+| `value` | `string[]` | 选中路径（数组，如 ['zj','hz','xh']） |
+| `onChange` | `(value: string[]) => void` | — |
+| `placeholder` | `string` | — |
+| `disabled` | `boolean` | — |
+| `error` | `string` | — |
+| `label` | `string` | — |
+
+### Transfer（新增批次）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `data` | `TransferItem[]` | — |
+| `targetKeys` | `string[]` | 目标侧已选 keys |
+| `onChange` | `(targetKeys: string[]) => void` | — |
+| `titles` | `[string, string]` | — |
+| `size` | `'sm' \| 'md' \| 'lg'` | — |
+| `disabled` | `boolean` | — |
+
+### Carousel（新增批次）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `children` | `any[]` | — |
+| `autoplay` | `boolean` | 自动播放 |
+| `interval` | `number` | 自动播放间隔（ms），默认 3000 |
+| `showArrows` | `boolean` | — |
+| `showDots` | `boolean` | — |
+| `loop` | `boolean` | 循环播放（尾 → 头），默认 true |
+| `className` | `string` | — |
+
+### Calendar（新增批次）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `events` | `CalendarEvent[]` | — |
+| `month` | `number` | 受控年月：month 0-11，year 四位数 |
+| `year` | `number` | — |
+| `onMonthChange` | `(month: number, year: number) => void` | — |
+| `onSelectDate` | `(date: string) => void` | — |
+| `selectedDate` | `string` | — |
+
+### AiChat（AI 交互）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `chat` | `UseChatHandle` | ctx.ui.useChat() 返回的会话 handle（同一 $，状态变化自动重渲染） |
+| `maxHeight` | `string` | 消息列表最大高度（默认 '70vh'） |
+| `labels` | `Partial<AiChatLabels>` | 界面文案覆盖 |
+| `renderMessage` | `(msg: UiMessage) => any` | 自定义气泡渲染逃生舱（默认纯文本） |
+| `renderToolArgs` | `(args: Record<string, unknown>) => any` | 工具参数渲染（透传 ToolCallCard） |
+| `raiseOnKeyboard` | `boolean` | 键盘弹起时输入区 fixed 抬升（全屏 chat 布局用；内联卡片默认 false——原生聚焦滚动已够） |
+
+### FileUpload（表单增强）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `accept` | `string` | — |
+| `multiple` | `boolean` | — |
+| `maxSize` | `number` | — |
+| `disabled` | `boolean` | — |
+| `error` | `string` | — |
+| `hint` | `string` | — |
+| `value` | `File[]` | — |
+| `onChange` | `(files: File[]) => void` | — |
+| `children` | `any` | — |
+
+### Slider（表单选择）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `label` | `string` | — |
+| `value` | `number \| string` | — |
+| `min` | `number` | — |
+| `max` | `number` | — |
+| `step` | `number` | — |
+| `onChange` | `(value: number) => void` | — |
+
 ## 组件列表
 
 ### 表单核心