weifuwu 0.64.1 → 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.md

@@ -5,6 +5,7 @@
 92 个 HTML 原语组件。每个是 `(_init, ctx) => (props) => VNode`（两阶段组件，与前端框架同一模型），引用 `--wf-*` CSS 变量做主题。另含 `confirm()` / `toast()` 命令式中间件。
 
 > **组件速查（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'

package/docs/custom-components.md

@@ -0,0 +1,237 @@
+# 自定义组件开发指南
+
+> 用 weifuwu/client 写自己的组件——与内置组件同权：同渲染引擎、同弹层原语、同类型安全。
+> 前置：[前端概念](frontend.md)（两阶段模型/ctx.ui）+ [组件列表](components.md)。
+
+---
+
+## 0. 最小骨架
+
+```tsx
+import { h, type Component } from 'weifuwu/client'
+
+// Component<P, C>：P = props（JSX 自动推断），C = ctx 注入依赖（默认 {}）
+const Badge: Component<{ text: string; color?: string }> = () =>
+  (props) => h('span', { class: 'my-badge', style: { color: props.color } }, props.text)
+```
+
+- 两阶段：外层 `(initProps, ctx) => …` 只执行一次（mount），内层 `(props) => VNode` 每次渲染执行
+- 不需要状态就不调 `ctx.ui.$()`；需要交互才用
+
+## 1. 有状态组件
+
+```tsx
+const Toggle: Component = (_init, ctx) => {
+  const $ = ctx.ui.$()        // 深度 Proxy：赋值自动触发渲染（微任务批量）
+  $.on = false
+
+  return (props) => h('button', {
+    class: 'my-toggle',
+    onClick: () => $.on = !$.on,
+  }, $.on ? '开' : '关')
+}
+```
+
+| 状态类型 | 存放位置 | 触发渲染 |
+|---------|---------|---------|
+| 自动 UI 状态 | `$.xxx` | 赋值自动（微任务） |
+| 手动 UI 状态 | 闭包 `let` | 需 `ctx.ui.render()` |
+| 内部缓存 | 闭包 `let` | 不触发 |
+
+## 2. 带弹层的组件（最高频的自定义场景）
+
+用 `ctx.ui.usePopup`——一个组合器收敛 open 状态 + 触发（hover→tap 降级/longpress）+ Escape + 外部点击 + 定位/视口 clamp + portal：
+
+```tsx
+const MyPopover: Component<{ content: string }> = (_init, ctx) => {
+  const $ = ctx.ui.$()
+  $.open = false
+  let wrapEl: HTMLElement | null = null
+  const wrapRef = (el: HTMLElement | null) => { wrapEl = el }
+
+  const popup = ctx.ui.usePopup({
+    trigger: 'hover',          // 触屏自动降级 tap（useHoverCapable 内部判定）
+    el: () => wrapEl,          // 锚点
+    isOpen: () => $.open,
+    setOpen: (v) => { $.open = v },   // $ 赋值自动渲染
+    width: 320,                // 自动 clamp 视口
+    closeOnOutside: true,      // 外部点击关闭（默认）
+    closeOnEscape: true,       // Escape 关闭（默认，document 级——portal 焦点也生效）
+  })
+
+  return (props) =>
+    h('span', { class: 'anchor', ref: wrapRef, ...popup.wrapProps },
+      props.children,
+      popup.portal(h('div', { class: 'wf-panel' }, props.content)),
+    )
+}
+```
+
+> **受控弹层**：传 `open` getter + `onOpenChange` 即受控（父组件独占开关）；缺 onOpenChange 时 usePopup 内部 warn 提示。
+
+## 3. 对话框类组件（Modal 系）
+
+全屏对话框（焦点 trap + 滚动锁 + 退场动画）不在 usePopup 范围——用 **`ctx.ui.useDialog`** 组合器（Modal/Drawer 同款：退场状态机 + 滚动锁 + 焦点 trap + animationend 卸载）：
+
+```tsx
+import { createPortal } from 'weifuwu/client'
+
+const MyDialog: Component<{ open: boolean; onClose: () => void }> = (_init, ctx) => {
+  const dialog = ctx.ui.useDialog({ name: 'MyDialog' })   // mount 创建
+
+  return (props) => {
+    const phase = dialog.sync(!!props.open)                // render 同步 open
+    if (phase === 'closed') return null
+
+    return createPortal(h('div', {
+      class: 'wf-overlay',
+      onClick: (e: any) => { if (e.target === e.currentTarget) props.onClose() },
+    }, h('div', {
+      class: `wf-modal ${phase === 'exit' ? 'wf-modal--exit' : 'wf-modal--enter'}`,
+      ref: dialog.panelRef,                                // 焦点 trap 目标
+      onKeyDown: (e: any) => { if (e.key === 'Escape') props.onClose() },  // Escape 语义组件层
+    }, props.children)), document.body)
+  }
+}
+```
+
+> `dialog.rootRef` 挂到 portal 根（lockScroll + animationend 退场监听）；`panelRef` 挂到面板（trapFocus）。
+> 低层原语 `trapFocus`/`lockScroll`/`animateOut` 仍从 `weifuwu/client` 导出（特殊场景组装用）。
+
+## 4. AI 组件
+
+会话语义由 `ctx.ui.useChat` 提供（消息/流式/工具/审批/stop/retry 全封装），返回的 handle 与 `$` 同一容器：
+
+```tsx
+const ChatPanel: Component = (_init, ctx) => {
+  const $ = ctx.ui.useChat({
+    url: '/api/chat',
+    approveUrl: '/api/approve',   // HITL 审批上行（缺省 approve() 只清卡片）
+    body: (messages) => ({ messages, mode: 'agent' }),
+  })
+
+  return () => h('div', { class: 'chat' },
+    $.messages.map((m) => h('div', { class: `msg-${m.role}` }, m.content)),
+    h('input', { value: $.input, onInput: (e: any) => $.input = e.target.value }),
+    h('button', { onClick: () => $.send() }, $.streaming ? '…' : '发送'),
+  )
+}
+```
+
+**共享 `$` 给子组件**（如 `<AiChat chat={$} />`）：父组件 dirty 不驱动子组件（三态 skip），子组件 mount 期 `initProps.chat.__watch?.(() => ctx.ui.dirty())` 自订阅。
+
+## 5. 异步组件（数据声明在工厂层）
+
+```tsx
+import { asyncComponent } from 'weifuwu/client'
+
+const UserCard = asyncComponent(async (ctx) => {
+  const user = await ctx.data.get(`/api/user/${ctx.route.params.id}`)  // 工厂层取数（SSR 序列化进 HTML）
+  return (_init, ctx) => {
+    const $ = ctx.ui.$()
+    $.liked = false
+    return (props) => h('div', {}, user.name, h('button', { onClick: () => $.liked = !$.liked }))
+  }
+})
+```
+
+- 工厂只执行一次（WeakMap 缓存）；客户端首次渲染占位 → resolve 后整树补全；服务端直接 await（无占位）
+- **个性化数据不进 ctx.data**（SSR 会序列化给所有客户端）——留在客户端 `$` + fetch
+
+## 6. 类型纪律（编译期防线）
+
+```tsx
+const Badge: Component<{ variant: 'primary' | 'muted' }> = () =>
+  (props) => h('span', { class: `badge-${props.variant}` }, props.children)
+
+// 负例：variant 传错 → tsc 报错（@ts-expect-error 是类型流测试的写法）
+// @ts-expect-error variant 不允许 'bogus'
+const bad: { variant: 'primary' | 'muted' } = { variant: 'bogus' }
+
+// ctx 注入声明（C 泛型）：声明了才能用，未声明编译期报错
+const Page: Component<{}, { api: ApiInjected['api'] }> = (_init, ctx) => {
+  ctx.api.get('/x')
+  return () => null
+}
+```
+
+| 规则 | 违反后果 |
+|------|---------|
+| `Component<P, C>` 类型化（禁 `_init: any`） | 编译期不可查 |
+| 受控 props 必须配回调 | 交互静默失效（组件 console.warn） |
+| ref 用 `ctx.ui.useStableRef`（禁内联 ref） | 清理逻辑每次渲染误触 |
+| 初始状态确定性（禁 `window.innerWidth` 直接初始化） | SSR/hydration mismatch |
+| 小尺寸按钮固定 min/max-height | 被全局 36px 撑成竖条 |
+
+## 7. 测试写法
+
+```tsx
+function renderVNode(Comp: any, props: any, ctx: any) {
+  const result = Comp(props, ctx)
+  return typeof result === 'function' ? result(props) : result
+}
+
+const ctx = { ui: { $: () => ({}), render: () => {}, dirty: () => {}, useControlled: (o: any) => ({ value: o.value, setValue: o.onChange ?? (() => {}), controlled: o.value !== undefined }) } }
+const vnode = renderVNode(Toggle, {}, ctx)
+// 断言 vnode 结构（子组件 VNode.type 是组件函数，不是标签名）
+```
+
+- 类型流测试：`@ts-expect-error` 负例（见 [type-flow.test.ts](../src/components/type-flow.test.ts)）
+- 组件测试跑在 node --test；DOM 事件级测试需 `document.body.appendChild(container)`
+
+## 8. 受控组件标准
+
+新受控组件**必须**用 `ctx.ui.useControlled`（受控判定 + 缺回调 warn 一次 + 非受控内部状态跨渲染保持）：
+
+```tsx
+const CollapseItem: Component<{ active?: boolean; onChange?: (v: boolean) => void }> = (_init, ctx) => {
+  return (props) => {
+    const ctrl = ctx.ui.useControlled<boolean>({ value: props.active, onChange: props.onChange, name: 'CollapseItem' })
+    return h('button', {
+      onClick: () => ctrl.setValue(!(ctrl.value ?? false)),   // 受控走 onChange；非受控内部状态
+    }, (ctrl.value ?? false) ? '开' : '关')
+  }
+}
+```
+
+> 多受控维度组件（Tree 的 expandedKeys+checkedKeys）不适用单值 useControlled——保留手工受控判定（参考 Tree.ts），warn 文案与 useControlled 保持一致。
+
+## 8.5 动画（4 层能力）
+
+| 层 | 原语 | 用法 |
+|----|------|------|
+| CSS 语言 | Token（`--wf-dur-*`/`--wf-ease-*`/`--wf-motion-*`）+ `--enter`/`--exit` 成对 | 组件动画统一引用 Token，禁硬编码 |
+| 生命周期 | `useAnimationEnd(cb, { once })`（完成回调）/ `usePresence({ name })`（显隐状态机）/ `animateOut(el, done)`（命令式退场） | 入场 settle / 退场延迟卸载 / 命令式播动画 |
+| 数值驱动 | `useTween(target, { duration, ease })`（补间）/ `useInView` / `useScrollPosition` | count-up / 进入视口播 / 滚动联动 |
+| 偏好感知 | `useReducedMotion()` | JS 动画（rAF/tween）侧跳过；CSS 动画 `_base.css` 已全局降级 |
+
+**纪律**：组件内动画事件监听**唯一入口是 `useAnimationEnd`**——禁直接 `addEventListener('animationend')`（DatePicker 已收敛）；退场优先 `usePresence`（声明式状态机）或 `animateOut`（命令式）。
+
+## 9. 样式纪律（style-audit 强制）
+
+- 动效用 Token：`--wf-dur-*` / `--wf-ease-*` / `--wf-motion-*`（禁硬编码）
+- 语义色用 `-text` 变体（700 级）；实心填充文字用 `--wf-color-on-brand`；遮罩 `--wf-overlay`
+- 图标用 `Icon` 组件（禁裸文本字形 ✕✓⚠▲）
+- 触屏（coarse pointer）自动 44px 命中区
+
+---
+
+## 内置组件 = 最佳实践范本
+
+| 想要的能力 | 参考源码 |
+|-----------|---------|
+| 弹层组合（hover/click/longpress） | [Tooltip.ts](../src/components/Tooltip/Tooltip.ts) / [ContextMenu.ts](../src/components/ContextMenu/ContextMenu.ts) |
+| 对话框状态机 | [Modal.ts](../src/components/Modal/Modal.ts) / [Drawer.ts](../src/components/Drawer/Drawer.ts) |
+| AI 会话 | [AiChat.ts](../src/components/AiChat/AiChat.ts) |
+| 受控 + 键盘导航 | [Collapse.ts](../src/components/Collapse/Collapse.ts) / [Tabs.ts](../src/components/Tabs/Tabs.ts) |
+| 异步数据 | [UserProfile](../src/components/Img/Img.ts) 的 factory 模式 |
+| 命令式 API（toast/confirm） | [Toast.ts](../src/components/Toast/Toast.ts) |
+
+## 已知边界（诚实裁剪）
+
+- `usePopup` 覆盖浮层（Tooltip/Popover/Dropdown/Mentions/Cascader/ContextMenu）；**全屏对话框**（Modal/Drawer）用 useDialog（Escape 语义留组件层）；Command/Img preview 保持独立实现
+- **事件监听纪律**：组件库内部浏览器事件监听**统一走 `ctx.ui.useXXX`**——滚动/观察/弹层/对话框/快捷键/拖拽/DnD 全覆盖：
+  `useInView`（InfiniteScroll）、`useScrollPosition`（AiChat/Affix/BackTop/VirtualList）、`usePopupPosition`（Affix 阈值重算）、`usePopup`（ContextMenu 自由定位）、`useDialog`（Modal/Drawer）、`useGlobalKey`（Command 快捷键/Img preview Escape）、`useDrag`（Resizable）、`useDragDrop`（FileUpload）、`useControlled`/`useStableRef`（状态/ref）
+- 唯一保留：**DatePicker 元素级 `animationend`**（入场动画完成后坐标 settle——与 usePopup panelRef/motion.animateOut 同款框架基础设施，非浏览器全局事件）
+- **Select/DatePicker** 是 inline/absolute 菜单（自适宽），不迁移 usePopup——菜单直接挂在锚点下
+- `createReactiveState` 已导出：组件外建全局 store（`createReactiveState(() => {})` + `$.__watch(cb)` 订阅）

package/docs/frontend.md

@@ -155,6 +155,16 @@ ctx.ui.render(['name'])
 | `selfId()` | `selfId(name: string)` | 注册组件自定义 ID，配合 `render(['id'])` 跨组件精准刷新 |
 | `useChat()` | `useChat({ url, approveUrl?, body? })` | AI 对话会话：消息/流式/工具/审批，与 `$` 同容器（AiChat 配套） |
 | `useAsync()` | `useAsync(fetcher)` | 异步取数：`data/loading/error` 响应式 + `reload()` |
+| `useControlled()` | `useControlled({ value, onChange, name })` | 受控/非受控统一：受控判定 + 缺回调 warn + 内部状态跨渲染保持 |
+| `useStableRef()` | `useStableRef(init, cleanup?)` | 稳定 ref 引用（根治内联 ref 陷阱） |
+| `useDialog()` | `useDialog({ name })` | 全屏对话框：退场状态机 + 滚动锁 + 焦点 trap（Modal/Drawer 同款） |
+| `useGlobalKey()` | `useGlobalKey(handler)` | 全局键盘监听（window keydown：mount 注册 + 卸载清理） |
+| `useDrag()` | `useDrag({ onMove, onStart?, onEnd? })` | 指针拖拽（pointerdown 捕获 → window move delta / up 释放） |
+| `useDragDrop()` | `useDragDrop({ onDrop, onDragOver?, onDragLeave? })` | 原生 DnD（drop/dragover/dragleave + preventDefault，dropProps spread） |
+| `useReducedMotion()` | `useReducedMotion()` | 响应式系统偏好（JS 动画侧跳过；CSS 动画已有全局降级） |
+| `useAnimationEnd()` | `useAnimationEnd(cb, { once? })` | 元素动画完成回调（stableRef：挂载绑定/卸载清理/引用恒定） |
+| `useTween()` | `useTween(target, { duration?, ease? })` | 数值补间（rAF + easeOutCubic + reduced-motion 直落；幂等 reset） |
+| `usePresence()` | `usePresence({ name? })` | 通用显隐状态机（open→exit→closed，animationend 延迟卸载；useDialog 是其特例） |
 | `useMedia()` | `useMedia(query, cb)` | 响应式媒体查询，断点变化时自动回调 |
 | `useBreakpoint()` | `useBreakpoint(cb \| bps, cb?)` | 命名断点 mobile/tablet/desktop |
 | `usePopupPosition()` | `usePopupPosition(opts)` | 弹层坐标跟随：scroll/resize 时自动重算 fixed 坐标 |
@@ -462,6 +472,39 @@ return () => list.loading ? h(Loading) : list.data?.map(u => h('div', {}, u.name
 - `list.data` / `list.loading` / `list.error` 赋值自动 dirty 当前组件
 - `list.reload()` 重跑；组件卸载后旧 Promise resolve 不再触发渲染（idRegistry 查无此组件，安全忽略）
 
+#### 动画原语（4 层能力）
+
+动画能力按层组织（CSS 语言已有：`--wf-dur-*`/`--wf-ease-*`/`--wf-motion-*` Token + `--enter`/`--exit` 成对纪律）：
+
+| 原语 | 层 | 说明 |
+|------|----|------|
+| `useAnimationEnd(cb, { once? })` | 生命周期 | 元素动画完成回调（stableRef：挂载绑定/卸载清理/引用恒定）——**组件内动画事件唯一入口** |
+| `usePresence({ name? })` | 生命周期 | 显隐状态机：open → exit → closed（animationend 延迟卸载）；`useDialog` 是其对话框特例 |
+| `useTween(target, { duration?, ease? })` | 数值驱动 | 数值补间（rAF + easeOutCubic + reduced-motion 直落；幂等 reset + 每帧自动渲染） |
+| `useReducedMotion()` | 偏好感知 | 响应式系统偏好——**JS 动画**（rAF/tween）侧跳过（CSS 动画已有全局降级） |
+| `useInView` / `useScrollPosition` | 数值驱动 | 进入视口播 / 滚动位置联动（已有） |
+
+```tsx
+// 入场 settle（面板坐标夹紧：动画期间矩形非稳态，结束后按稳态几何计算）
+const settleRef = ctx.ui.useAnimationEnd(() => pos.refresh(), { once: true })
+return () => h('div', { class: 'wf-panel', ref: settleRef }, ...)
+
+// 退场（显隐状态机：open=false 播退场动画，animationend 后才真正卸载）
+const { phase, ref, sync } = ctx.ui.usePresence()
+const p = sync(props.open)
+if (p === 'closed') return null
+return h('div', { class: `wf-panel ${p === 'exit' ? '--exit' : '--enter'}`, ref }, ...)
+
+// 数值动画（count-up：0 → 42，每帧自动渲染）
+const n = ctx.ui.useTween(42, { duration: 400 })
+return () => h('span', { class: 'wf-nums' }, String(n.value))
+
+// 偏好感知（JS 动画侧跳过；CSS 动画 _base.css 已全局降级）
+if (!ctx.ui.useReducedMotion()) { /* 启动 rAF/动画 */ }
+```
+
+> 完整动画纪律见 [custom-components.md](custom-components.md) 的「8.5 动画」章节。
+
 #### CSS 层响应式（不碰 JS）
 
 配合 `weifuwu/layout` 的断点变体，纯 CSS 实现布局方向切换：

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "weifuwu",
   "type": "module",
-  "version": "0.64.1",
+  "version": "0.65.0",
   "description": "AI SaaS framework — (req, ctx) => Response",
   "exports": {
     ".": {