weifuwu 0.53.0 → 0.54.0

package/README.md

@@ -8,6 +8,11 @@ npm install weifuwu
 
 一个包 = 后端 (`weifuwu`) + 前端 (`weifuwu/client`) + 组件库 (`weifuwu/components`) + 布局系统 (`weifuwu/layout`)。
 
+> ⚠️ **注意：前后端都有 `ctx.ui`，但用途完全不同**
+> - **后端** `ctx.ui`（SSR/编译）：`ctx.ui.html`（HTML 模板）、`ctx.ui.js`（TSX→JS 动态编译）、`ctx.ui.css`（CSS 编译）
+> - **前端** `ctx.ui`（渲染引擎）：`ctx.ui.$()`（响应式状态）、`ctx.ui.render()` / `dirty()`（渲染控制）、`useMedia()` / `useBreakpoint()` / `usePopupPosition()`（浏览器事件监听）
+> 后端的是「把页面和代码交给浏览器」，前端的是「在浏览器里驱动 UI」。
+
 ---
 
 ## 设计理念
@@ -61,9 +66,13 @@ const Home: Component = () => () => <h1>Hello weifuwu</h1>
 
 createApp()
   .use(router({ routes: [{ path: '/', component: Home }] }))
-  .mount('#root', () => <RouteView />)
+  .mount('#root', () => () => <RouteView />)  // 根组件也要两阶段：外层返回 render 函数
 ```
 
+运行 `node server.ts`，访问 `http://localhost:3000` 即可看到页面。后端 `ctx.ui.js()` 会实时编译 `src/main.tsx`，改代码刷新即生效，无需任何构建步骤。
+
+> 想**零后端、零构建**最快跑起来？直接跳到下面的「CDN 快速原型」。
+
 ---
 
 ## CDN 快速原型（零构建、纯 HTML）
@@ -165,9 +174,9 @@ createApp()
 | `weifuwu/client` | **api / auth / ws** | HTTP 客户端 / 认证 / WebSocket 中间件 | createApp |
 | `weifuwu/client` | **i18n** | 国际化中间件（运行时切换语言） | createApp |
 | `weifuwu/client` | **ErrorBoundary** | 错误边界组件 | createApp |
-| `weifuwu/client` | **confirm** | Promise 化确认对话框 | createApp |
 | `weifuwu/client` | **lockScroll/trapFocus** | 滚动锁定 / 焦点陷阱工具 | — |
-| `weifuwu/components` | **41 个组件** | Button/Table/Modal/Toast/... | weifuwu/client |
+| `weifuwu/client` | **popup** | 弹层 fixed 定位工具（`computeFixedPos` / `computeFixedPosRect`） | — |
+| `weifuwu/components` | **42 个组件** | Button/Table/Modal/Confirm/Toast/... + `confirm()` / `toast()` 命令式中间件 | weifuwu/client |
 | `weifuwu/layout` | **CSS 布局** | 35 个布局原语 + 72 个主题 Token（也支持 `weifuwu/layout/style.css`） | — |
 
 ---
@@ -889,6 +898,20 @@ h('div', { class: 'x' }, child1, child2)
 
 ## 状态管理
 
+### ctx.ui 方法速查
+
+| 方法 | 签名 | 一句话说明 |
+|------|------|-----------|
+| `$()` | `$(): Record<string, any>` | 深度 Proxy 响应式状态容器，赋值自动触发渲染（**推荐首选**） |
+| `render()` | `render(ids?: string[])` | 同步强制渲染；无参 = 当前组件，传参 = 指定组件列表 |
+| `dirty()` | `dirty(ids?: string[])` | 异步渲染（微任务批处理合并）；`$` 内部就是调它 |
+| `selfId()` | `selfId(name: string)` | 注册组件自定义 ID，配合 `render(['id'])` 跨组件精准刷新 |
+| `useMedia()` | `useMedia(query, cb)` | 响应式媒体查询，断点变化时自动回调 |
+| `useBreakpoint()` | `useBreakpoint(cb \| bps, cb?)` | 命名断点 mobile/tablet/desktop |
+| `usePopupPosition()` | `usePopupPosition(opts)` | 弹层坐标跟随：scroll/resize 时自动重算 fixed 坐标 |
+
+> 每个方法的完整说明见下文对应章节。
+
 ### Render 机制总览
 
 | API | 触发时机 | 渲染方式 | 作用域 | 使用场景 |
@@ -899,6 +922,7 @@ h('div', { class: 'x' }, child1, child2)
 | `ctx.ui.render(['id'])` | 主动调用 | 立即同步 | 指定组件 | **跨组件精准刷新** — 全局事件、Portal 远程控制 |
 | `ctx.ui.useMedia()` | 注册监听 | 浏览器事件驱动 | 当前组件 | **响应式媒体查询** — 断点变化时自动 dirty |
 | `ctx.ui.useBreakpoint()` | 注册监听 | 浏览器事件驱动 | 当前组件 | **命名断点** — mobile/tablet/desktop 自动 dirty |
+| `ctx.ui.usePopupPosition()` | 注册监听 | 浏览器事件驱动 | 当前组件 | **弹层坐标跟随** — scroll/resize 时自动重算 fixed 坐标 |
 
 `render()` 和 `dirty()` 无参 = 当前组件，传参 = 指定组件列表。三套 API 同一 scope 机制。
 
@@ -996,6 +1020,73 @@ ctx.ui.useBreakpoint(
 )
 ```
 
+#### `ctx.ui.usePopupPosition(options)` — 弹层坐标跟随
+
+解决弹出层（Popover / Tooltip / Dropdown / DatePicker 等）在 **页面滚动 / 窗口缩放后不跟随触发元素** 的问题。基于 `position: fixed` + `getBoundingClientRect()`（视口坐标）的弹层，滚动后坐标需要重算——本 API 用全局 scroll/resize 监听（rAF 节流）自动重算并精准刷新当前组件。
+
+```tsx
+const DatePicker = (_init, ctx) => {
+  let show = false
+  let inputEl: HTMLElement | null = null
+  let prevOpen = false
+
+  // mount 阶段注册：scroll/resize 时自动重算 pos
+  const pos = ctx.ui.usePopupPosition({
+    el: () => inputEl,                  // 锚定元素（ref 保存）
+    isOpen: () => show,                 // 弹层是否显示
+    compute: (r) => ({ top: r.bottom + 4, left: r.left }),  // rect → 坐标
+  })
+
+  return (props) => {
+    const isOpen = show
+    // 打开瞬间算一次初始坐标（受控/非受控统一覆盖）
+    if (isOpen && !prevOpen) pos.refresh()
+    prevOpen = isOpen
+
+    return h('div', {}, [
+      h('input', {
+        ref: (el) => { inputEl = el as HTMLElement },
+        onClick: () => { show = !show; ctx.ui.render() },
+      }),
+      isOpen ? h('div', { style: { top: pos.top, left: pos.left } }) : null,
+    ].filter(Boolean))
+  }
+}
+```
+
+要点：
+
+- `pos` 是稳定对象，render 闭包直接读取 `top/left/width`，滚动重算原地更新，无需重新绑定
+- `pos.refresh()` 只重算不渲染——配合打开路径上已有的 `render()`，避免重复渲染
+- 监听是**全局单例**（capture 捕获所有嵌套滚动容器 + rAF 节流），按组件 selfId 注册，组件多时开销 O(1)
+- `compute` 是纯函数（rect → 坐标），可单独单测
+
+已内置接入的组件：**Popover / Tooltip / Dropdown / DatePicker / Chart**（tooltip）——它们的弹出层在页面滚动、嵌套容器滚动、窗口缩放时都会自动跟随触发元素，无需额外配置。
+
+#### `ctx.ui.selfId(name)` — 跨组件精准刷新
+
+用于全局事件通知、Portal 远程控制、兄弟组件协调等场景——绕过多层 props 传递，直接按 ID 刷新目标组件：
+
+```tsx
+// 组件 A：mount 阶段注册自定义 ID
+const StatsPanel = (_init, ctx) => {
+  ctx.ui.selfId('stats')
+  const $ = ctx.ui.$()
+  $.data = []
+  return (props) => h('div', {}, String($.data.length))
+}
+
+// 组件 B（或其他任何地方）用 ID 精准刷新
+ctx.ui.render(['stats'])        // 同步刷新
+// 或：ctx.ui.dirty(['stats'])   // 异步批处理版本
+```
+
+**语义**：
+
+- 必须在 **mount 阶段**调用（组件初始化时），注册后组件即可被 `render(['id'])` / `dirty(['id'])` 精准定位
+- **同名冲突直接抛错**，每个自定义 ID 必须全局唯一
+- 配合 `selfId` 注册的组件在跨组件场景下无需把刷新逻辑层层传 props
+
 #### CSS 层响应式（不碰 JS）
 
 配合 `weifuwu/layout` 的断点变体，纯 CSS 实现布局方向切换：
@@ -1023,6 +1114,8 @@ ctx.ui.useBreakpoint(
 
 异步版本，无参 = 当前组件，传参 = 指定组件列表。多次调用合并为一次微任务渲染。`$` 内部就是调 `dirty()`。
 
+与 `render()` 的区别：`dirty()` 是**异步**（微任务批量合并，同帧多次调用只渲染一次），`render()` 是**同步**（立即执行 VDOM diff + patch）。日常 UI 状态用 `$` 或 `dirty()`，需要立即拿到最新 DOM（测量/动画/第三方库）时用 `render()`。
+
 ### `ctx.ui.render()` — 同步强制渲染
 
 与 `dirty()` 的微任务批量不同，`render()` 是**同步执行**的。调用后立即执行 VDOM diff + patch，DOM 立刻更新。无参时只刷新当前组件，传参时可精准刷新指定组件。
@@ -1107,7 +1200,7 @@ const DatePicker = (_init, ctx) => {
 
 ```tsx
 const OrderPage = (_init, ctx) => {
-  const $ = ctx.ui.$
+  const $ = ctx.ui.$()
   $.orders = []                // $ 赋值自动触发渲染
   $.loading = false
   return (props) => h('div', {}, $.loading ? h(Spinner) : h(OrderList, { orders: $.orders }))
@@ -1223,7 +1316,7 @@ createApp()
     mode: 'history',  // 或 'hash'
     notFound: NotFoundPage,
   }))
-  .mount('#root', () => <RouteView />)
+  .mount('#root', () => () => <RouteView />)  // 根组件也要两阶段：外层返回 render 函数
 ```
 
 ### 嵌套布局
@@ -1241,7 +1334,7 @@ const routes = [
 ]
 
 function DashboardLayout(_props: {}, ctx: WfuiContext) {
-  return (
+  return (props) => (
     <div style="display:flex">
       <aside>导航菜单</aside>
       <main><RouteView /></main>  {/* 渲染子路由 */}
@@ -1348,8 +1441,10 @@ createApp()
 
 // 在组件中
 function Profile(_props: {}, ctx: WfuiContext) {
-  if (!ctx.auth?.isLoggedIn) return <p>请登录</p>
-  return <p>欢迎, {ctx.auth?.user?.name}</p>
+  return (props) => {
+    if (!ctx.auth?.isLoggedIn) return <p>请登录</p>
+    return <p>欢迎, {ctx.auth?.user?.name}</p>
+  }
 }
 
 // 登录
@@ -1510,14 +1605,19 @@ import { ErrorBoundary } from 'weifuwu/client'
 
 ## confirm — 确认对话框
 
+两种用法，共享同一视觉与行为（基于 Modal 封装）：
+
+**① 命令式 `ctx.confirm()`（推荐，操作前询问）**
+
 ```tsx
-import { createApp, confirm } from 'weifuwu/client'
+import { createApp } from 'weifuwu/client'
+import { confirm } from 'weifuwu/components'
 
 createApp()
   .use(confirm())
   .mount('#root', App)
 
-// 在组件中使用
+// 任意代码中（组件事件、async 逻辑）
 async function handleDelete(ctx: WfuiContext) {
   const ok = await ctx.confirm?.('确定删除这条记录？', {
     title: '确认删除',
@@ -1531,17 +1631,63 @@ async function handleDelete(ctx: WfuiContext) {
 }
 ```
 
+**② 声明式 `<Confirm>`（需要受控状态时）**
+
+```tsx
+import { Confirm } from 'weifuwu/components'
+
+<Confirm
+  open={confirming}
+  title="确认删除"
+  message="确定删除这条记录？"
+  confirmText="删除"
+  variant="danger"
+  onConfirm={() => doDelete()}
+  onCancel={() => setConfirming(false)}
+/>
+```
+
 | ConfirmOptions | 类型 | 默认值 | 说明 |
 |----------------|------|--------|------|
 | `title` | `string` | `'确认操作'` | 对话框标题 |
 | `confirmText` | `string` | `'确定'` | 确认按钮文字 |
 | `cancelText` | `string` | `'取消'` | 取消按钮文字 |
 | `variant` | `'primary' \| 'danger'` | `'primary'` | 按钮样式变体 |
+| `width` | `string` | Modal 默认 | 对话框宽度 |
 
-- 直接 DOM 渲染（不经过 VDOM）
-- 返回 `Promise<boolean>`
-- ESC / 点击遮罩 → resolve(false)
-- 自动锁定背景滚动
+- `ctx.confirm()` 返回 `Promise<boolean>`，ESC / 点击遮罩 / 取消 → resolve(false)
+- 组件化渲染（Modal + portal），自动锁定滚动 + 焦点陷阱，i18n 文案可配置
+- 多次调用各自独立渲染（叠放语义），互不干扰
+
+---
+
+## toast — 命令式消息提示
+
+`ctx.toast()` 是 `<Toast>` 组件的全局命令式封装：任意代码中一行调用，自动消失、自动清理，无需宿主状态。
+
+```tsx
+import { createApp } from 'weifuwu/client'
+import { toast } from 'weifuwu/components'
+
+createApp()
+  .use(toast({ position: 'top-right', duration: 3000, max: 3 }))
+  .mount('#root', App)
+
+// 任意代码中（组件事件、api 拦截器、WS 回调、定时器）
+ctx.toast?.('保存成功', 'success')
+ctx.toast?.('请求失败', 'error')
+ctx.toast?.('普通消息')          // 默认 type = 'info'
+```
+
+| ToastOptions | 类型 | 默认值 | 说明 |
+|-------------|------|--------|------|
+| `position` | `ToastPosition` | `'top-right'` | 容器位置 |
+| `duration` | `number` | `3000` | 默认自动消失时间（ms），0 = 不消失 |
+| `max` | `number` | `3` | 最大显示条数，超出移除最早 |
+
+单条可覆盖自动消失时间：`ctx.toast('慢一点消失', 'info', 5000)`。
+
+与声明式 `<Toast toasts={...}/>` 共存：声明式用于局部列表（合并消息、自定义布局），命令式用于全局一次性反馈。
 
 ---
 
@@ -1591,7 +1737,9 @@ import type { ApiClient, ApiOptions, ApiRequestOptions, ApiError } from 'weifuwu
 import type { AuthClient, AuthOptions } from 'weifuwu/client'
 import type { ErrorBoundaryProps } from 'weifuwu/client'
 import type { I18nOptions, I18nState, LocalePackage } from 'weifuwu/client'
-import type { ConfirmOptions, ConfirmState } from 'weifuwu/client'
+import type { PopupPositionOptions, PopupPosition } from 'weifuwu/client'
+import type { ConfirmProps, ConfirmOptions } from 'weifuwu/components'
+import type { ToastOptions, ToastPosition } from 'weifuwu/components'
 import type { RouterOptions } from 'weifuwu/client'
 ```
 
@@ -1600,7 +1748,7 @@ import type { RouterOptions } from 'weifuwu/client'
 | `VNode` | `{ type, props, key? }` |
 | `VNodeType` | `string \| Component \| typeof Fragment` |
 | `Component<P>` | `(initProps: P, ctx: WfuiContext) => (props: P) => VNode \| null` |
-| `WfuiContext` | `{ ui, route?, app?, ws?, api?, auth?, i18n?, confirm?, [key]: unknown }` |
+| `WfuiContext` | `{ ui, route?, app?, ws?, api?, auth?, i18n?, confirm?, toast?, [key]: unknown }` |
 | `AppMiddleware` | `(ctx: WfuiContext) => WfuiContext` |
 | `RouteDef` | `{ path, component?, layout?, children?, auth?, title? }` |
 | `ApiClient` | `{ get, post, put, patch, delete }` |
@@ -1609,13 +1757,17 @@ import type { RouterOptions } from 'weifuwu/client'
 | `I18nOptions` | `{ locale?, messages?, components? }` |
 | `I18nState` | `{ locale, t, setLocale, components }` |
 | `ErrorBoundaryProps` | `{ fallback?, children? }` |
-| `ConfirmOptions` | `{ title?, confirmText?, cancelText?, variant? }` |
+| `ConfirmProps` | `{ open?, title?, message?, confirmText?, cancelText?, variant?, width?, onConfirm?, onCancel? }` |
+| `ConfirmOptions` | `{ title?, confirmText?, cancelText?, variant?, width? }` — 命令式 ctx.confirm 选项 |
+| `ToastOptions` | `{ position?, duration?, max? }` — 命令式 ctx.toast 配置 |
+| `PopupPositionOptions` | `{ el, isOpen, compute }` — 弹层位置跟踪配置（见 usePopupPosition） |
+| `PopupPosition` | `{ top, left, width?, refresh }` — 弹层位置跟踪器 |
 
 ---
 
 # 组件库 (`weifuwu/components`)
 
-41 个 HTML 原语组件。每个是 `(props, ctx) => VNode` 纯函数，引用 `--wf-*` CSS 变量做主题。
+42 个 HTML 原语组件。每个是 `(_init, ctx) => (props) => VNode`（两阶段组件，与前端框架同一模型），引用 `--wf-*` CSS 变量做主题。另含 `confirm()` / `toast()` 命令式中间件。
 
 ```ts
 import { Button, Input, Table, Modal, Toast } from 'weifuwu/components'
@@ -1632,8 +1784,9 @@ import 'weifuwu/components/style.css'   // 包含 Token + 35 布局原语 + 组
 
 // ├─ 输入框
 <Input placeholder="请输入邮箱" />
-<Input label="用户名" required error="必填" />
-<Input type="password" hint="至少6位" prefix="🔒" />
+<Input label="用户名" name="username" required error="必填" />
+<Input type="password" hint="至少6位" />
+<Input name="email" type="email" disabled placeholder="name@example.com" />
 
 // ├─ 选择器
 <Select options={[{ value: 'a', label: '选项A' }]} placeholder="请选择" />
@@ -1648,10 +1801,12 @@ import 'weifuwu/components/style.css'   // 包含 Token + 35 布局原语 + 组
 <Table columns={[{ key: 'id', label: 'ID', sortable: true }, { key: 'name', label: '名称' }]}
        data={rows} sortKey="id" sortOrder="asc" onSort={(k, o) => setSort(k, o)} />
 
-// ├─ 模态框 / 抽屉
+// ├─ 模态框 / 确认框 / 抽屉
 <Modal open={show} title="提示" onClose={() => setShow(false)} width="500px" closable>
   <p>确认删除？</p>
 </Modal>
+<Confirm open={confirming} message="确定删除？" variant="danger" onConfirm={doDelete} onCancel={() => setConfirming(false)} />
+// 命令式：await ctx.confirm?.('确定删除？') —— 组件里直接调用
 <Drawer open={open} title="详情" onClose={() => setOpen(false)} position="right">内容</Drawer>
 
 // ├─ 消息提示
@@ -1695,7 +1850,7 @@ import 'weifuwu/components/style.css'   // 包含 Token + 35 布局原语 + 组
 
 // ├─ 表单验证
 <Form validation={{ email: [{ required: true, message: '请输入邮箱' }] }}
-      onSubmit={values => api.post('/login', values)}
+      onSubmit={values => ctx.api?.post('/login', values)}   // ctx.api 由中间件注入
       onError={errors => setErrors(errors)}>
   <Field label="邮箱" error={errors.email}>
     <Input name="email" />
@@ -1751,7 +1906,7 @@ props 变化 ──────────────────────
 | 组件 | 导入名 | 关键 Props | 说明 |
 |-----|--------|-----------|------|
 | Button | `Button` | `variant`, `size`, `loading`, `disabled`, `block`, `type` | 按钮 |
-| Input | `Input` | `variant`, `size`, `placeholder`, `disabled`, `error`, `prefix`, `suffix` | 输入框 |
+| Input | `Input` | `label`, `name`, `type`, `value`, `placeholder`, `required`, `disabled`, `error`, `hint`, `onInput`, `onChange` | 输入框 |
 | Textarea | `Textarea` | `rows`, `resize`, `maxLength`, `error` | 文本域 |
 | Select | `Select` | `options: SelectOption[]`, `placeholder`, `searchable` | 下拉选择 |
 
@@ -1793,14 +1948,15 @@ props 变化 ──────────────────────
 | 组件 | 导入名 | 关键 Props | 说明 |
 |-----|--------|-----------|------|
 | Modal | `Modal` | `open`, `title`, `onClose`, `width`, `footer`, `closable` | 模态框 |
+| Confirm | `Confirm` | `open`, `message`, `confirmText`, `cancelText`, `variant`, `onConfirm`, `onCancel` | 确认对话框（同 `ctx.confirm()` 命令式） |
 | Drawer | `Drawer` | `open`, `title`, `onClose`, `position: DrawerPosition`, `width` | 抽屉 |
-| Tooltip | `Tooltip` | `content`, `position: TooltipPosition`, `trigger` | 工具提示 |
-| Popover | `Popover` | `content`, `position: PopoverPosition`, `trigger` | 弹出层 |
+| Tooltip | `Tooltip` | `content`, `position: TooltipPosition`, `disabled` | 工具提示（hover/focus 触发） |
+| Popover | `Popover` | `content`, `position: PopoverPosition`, `trigger`, `open`, `onOpenChange`, `disabled` | 弹出层 |
 | Toast | `Toast` | `items: ToastItem[]`, `position`, `max` | 消息提示 |
 | Alert | `Alert` | `variant: AlertVariant`, `title`, `closable`, `icon` | 警告提示 |
 | Loading | `Loading` | `size`, `text`, `fullscreen` | 加载中 |
 | EmptyState | `EmptyState` | `title`, `description`, `action`, `icon` | 空状态 |
-| Skeleton | `Skeleton` | `variant: SkeletonVariant`, `rows`, `width`, `height` | 骨架屏 |
+| Skeleton | `Skeleton` | `variant: SkeletonVariant`, `lines`, `cols`, `width`, `height` | 骨架屏 |
 
 ### 导航组件
 
@@ -1808,7 +1964,7 @@ props 变化 ──────────────────────
 |-----|--------|-----------|------|
 | Breadcrumb | `Breadcrumb` | `items: BreadcrumbItem[]` | 面包屑 |
 | Tabs | `Tabs` | `items: TabItem[]`, `activeKey`, `onChange`, `type` | 标签页 |
-| Dropdown | `Dropdown` | `items: DropdownItem[]`, `trigger`, `placement` | 下拉菜单 |
+| Dropdown | `Dropdown` | `trigger`, `items: DropdownItem[]`, `open` | 下拉菜单 |
 | Pagination | `Pagination` | `total`, `page`, `pageSize`, `onChange` | 分页 |
 | Steps | `Steps` | `items: StepItem[]`, `current`, `direction`, `size` | 步骤条 |
 | Accordion | `Accordion` | `items: AccordionItem[]`, `multiple`, `defaultActive` | 手风琴 |
@@ -1818,7 +1974,7 @@ props 变化 ──────────────────────
 | 组件 | 导入名 | 关键 Props | 说明 |
 |-----|--------|-----------|------|
 | Chart | `Chart` | `type: ChartType`, `data`, `options`, `title`, `area` | SVG 图表（line/bar/pie）|
-| DatePicker | `DatePicker` | `mode: DatePickerMode`, `value`, `onChange`, `placeholder` | 日期选择器（date/datetime/time/range）|
+| DatePicker | `DatePicker` | `mode: DatePickerMode`, `value`, `onChange`, `placeholder`, `disabled` | 日期选择器（date/datetime/time/range）|
 | Editor | `Editor` | `value`, `onChange`, `toolbar`, `placeholder`, `disabled` | 富文本编辑器，零依赖 |
 
 ### 布局
@@ -2038,7 +2194,7 @@ const LoginPage = (_init, ctx) => {
             },
             onSubmit: async (values) => {
               $.submitting = true
-              await api.post('/login', values)
+              await ctx.api?.post('/login', values)   // api 客户端由中间件注入 ctx.api
               $.submitting = false
             },
             onError: (errors) => { $.errors = errors },
@@ -2068,12 +2224,13 @@ const UserList = (_init, ctx) => {
     { id: 2, name: '李四', email: 'li@example.com', role: '编辑' },
   ]
 
-  const filtered = users.filter(u =>
-    !$.keyword || u.name.includes($.keyword) || u.email.includes($.keyword)
-  )
+  return (props) => {
+    // 派生数据必须在 render 内计算（每次 render 读最新 $.keyword）
+    const filtered = users.filter(u =>
+      !$.keyword || u.name.includes($.keyword) || u.email.includes($.keyword)
+    )
 
-  return (props) =>
-    h('div', { class: 'wf-stack', style: { gap: 'var(--wf-space-md)' } },
+    return h('div', { class: 'wf-stack', style: { gap: 'var(--wf-space-md)' } },
       h('div', { class: 'wf-row', style: { justifyContent: 'space-between', alignItems: 'center' } },
         h(SearchInput, { placeholder: '搜索用户...', value: $.keyword, onSearch: (v: string) => { $.keyword = v } }),
         h(Button, { variant: 'primary' }, '新建用户'),
@@ -2093,6 +2250,7 @@ const UserList = (_init, ctx) => {
       }),
       h(Pagination, { total: filtered.length, page: 1, pageSize: 10, onChange: (p: number) => {} }),
     )
+  }
 }
 ```
 

package/dist/client/index.d.ts

@@ -35,7 +35,5 @@ export { lockScroll, unlockScroll } from './scroll-lock.ts';
 export { trapFocus } from './focus-trap.ts';
 export { computeFixedPos } from './popup.ts';
 export type { FixedPos, Placement } from './popup.ts';
-export { confirm } from './confirm.ts';
-export type { ConfirmOptions, ConfirmState } from './confirm.ts';
 export { zhCN } from './locale/zh_CN.ts';
 export { enUS } from './locale/en_US.ts';

package/dist/client/index.js

@@ -625,6 +625,25 @@ function createApp() {
   let _dirtyBatch = /* @__PURE__ */ new Set();
   let _dirtyScheduled = false;
   const _mediaRegistry = /* @__PURE__ */ new Map();
+  const _popupTrackers = /* @__PURE__ */ new Map();
+  let _popupListenersReady = false;
+  let _popupRaf = 0;
+  function schedulePopupRecompute() {
+    if (_popupRaf) return;
+    _popupRaf = requestAnimationFrame(() => {
+      _popupRaf = 0;
+      const ids = [];
+      for (const [id, t] of _popupTrackers) {
+        if (!t.isOpen()) continue;
+        const el = t.getEl();
+        if (!el) continue;
+        const p = t.compute(el.getBoundingClientRect());
+        Object.assign(t.pos, p);
+        ids.push(id);
+      }
+      if (ids.length > 0) ctx.ui.render(ids);
+    });
+  }
   function renderByIds(ids) {
     if (_rendering) return;
     _rendering = true;
@@ -805,6 +824,43 @@ function createApp() {
             _mediaRegistry.set(key, { mql: null, handler: null });
           }
         },
+        /**
+         * 弹层位置跟踪：滚动/resize 时自动重算 fixed 坐标
+         *
+         * 用法（mount 阶段）：
+         *   const pos = ctx.ui.usePopupPosition({
+         *     el: () => inputEl,                    // ref 保存的锚定元素
+         *     isOpen: () => show,                   // 弹层是否显示
+         *     compute: (r) => ({ top: r.bottom + 4, left: r.left }),
+         *   })
+         *
+         * pos 是稳定对象，render 闭包直接读取 top/left；
+         * 滚动/resize 时自动重算并定向刷新；打开弹层瞬间调用 pos.refresh()。
+         */
+        usePopupPosition: function(options) {
+          const selfId = getSelfId(this);
+          const pos = { top: 0, left: 0, refresh: () => {
+          } };
+          if (!selfId) return pos;
+          const tracker = {
+            pos,
+            getEl: options.el,
+            isOpen: options.isOpen,
+            compute: options.compute
+          };
+          _popupTrackers.set(selfId, tracker);
+          if (!_popupListenersReady) {
+            _popupListenersReady = true;
+            window.addEventListener("scroll", schedulePopupRecompute, { capture: true, passive: true });
+            window.addEventListener("resize", schedulePopupRecompute);
+          }
+          pos.refresh = () => {
+            const el2 = tracker.getEl();
+            if (!el2) return;
+            Object.assign(pos, tracker.compute(el2.getBoundingClientRect()));
+          };
+          return pos;
+        },
         /** 注册组件实例的自定义 ID（用于跨组件精准刷新） */
         selfId: function(name) {
           if (typeof name !== "string" || !name) {
@@ -837,6 +893,12 @@ function createApp() {
       if (container) container.innerHTML = "";
       container = null;
       ctx = {};
+      if (_popupListenersReady) {
+        window.removeEventListener("scroll", schedulePopupRecompute, { capture: true });
+        window.removeEventListener("resize", schedulePopupRecompute);
+        _popupListenersReady = false;
+        _popupTrackers.clear();
+      }
     }
   };
   return app;
@@ -1298,6 +1360,7 @@ var zhCN = {
     Switch: { ariaLabel: "\u5207\u6362" },
     Breadcrumb: { ariaLabel: "\u9762\u5305\u5C51" },
     Modal: { ariaLabel: "\u5F39\u7A97" },
+    Confirm: { confirmText: "\u786E\u5B9A", cancelText: "\u53D6\u6D88" },
     Drawer: { ariaLabel: "\u4FA7\u8FB9\u9762\u677F" },
     DatePicker: {
       w0: "\u65E5",
@@ -1332,6 +1395,7 @@ var enUS = {
     Switch: { ariaLabel: "Toggle" },
     Breadcrumb: { ariaLabel: "Breadcrumb" },
     Modal: { ariaLabel: "Dialog" },
+    Confirm: { confirmText: "OK", cancelText: "Cancel" },
     Drawer: { ariaLabel: "Panel" },
     DatePicker: {
       w0: "Su",
@@ -1476,8 +1540,7 @@ function trapFocus(container) {
 }
 
 // src/client/popup.ts
-function computeFixedPos(el, placement = "bottom", gap = 6, center = true) {
-  const rect = el.getBoundingClientRect();
+function computeFixedPosRect(rect, placement = "bottom", gap = 6, center = true) {
   switch (placement) {
     case "bottom":
       return {
@@ -1501,77 +1564,8 @@ function computeFixedPos(el, placement = "bottom", gap = 6, center = true) {
       };
   }
 }
-
-// src/client/confirm.ts
-function createConfirmModal(message, options) {
-  return new Promise((resolve) => {
-    const {
-      title = "\u786E\u8BA4\u64CD\u4F5C",
-      confirmText = "\u786E\u5B9A",
-      cancelText = "\u53D6\u6D88",
-      variant = "primary"
-    } = options;
-    const overlay = document.createElement("div");
-    overlay.className = "wf-modal";
-    overlay.style.cssText = "position:fixed;inset:0;z-index:10000;display:flex;align-items:center;justify-content:center";
-    const bg = document.createElement("div");
-    bg.style.cssText = "position:fixed;inset:0;background:rgba(0,0,0,0.4);z-index:-1";
-    const box = document.createElement("div");
-    box.style.cssText = `background:var(--wf-color-bg,#fff);border-radius:var(--wf-radius-md,8px);box-shadow:var(--wf-shadow-lg,0 4px 24px rgba(0,0,0,0.12));min-width:360px;max-width:90vw;z-index:1`;
-    if (title) {
-      const header = document.createElement("div");
-      header.style.cssText = "display:flex;align-items:center;justify-content:space-between;padding:16px 20px;border-bottom:1px solid var(--wf-color-border,#e5e7eb);font-family:var(--wf-font-sans);font-size:var(--wf-font-size-lg);font-weight:var(--wf-font-weight-semibold);color:var(--wf-color-text);line-height:1.4";
-      header.textContent = title;
-      box.appendChild(header);
-    }
-    const body = document.createElement("div");
-    body.style.cssText = "padding:20px;font-family:var(--wf-font-sans);font-size:var(--wf-font-size-sm);color:var(--wf-color-text);line-height:var(--wf-line-height-normal)";
-    body.textContent = message;
-    box.appendChild(body);
-    const footer = document.createElement("div");
-    footer.style.cssText = "display:flex;align-items:center;justify-content:flex-end;gap:8px;padding:12px 20px;border-top:1px solid var(--wf-color-border,#e5e7eb)";
-    const cancelBtn = document.createElement("button");
-    cancelBtn.className = "wf-btn wf-btn--secondary wf-btn--md";
-    cancelBtn.textContent = cancelText;
-    const confirmBtn = document.createElement("button");
-    confirmBtn.className = `wf-btn wf-btn--${variant} wf-btn--md`;
-    confirmBtn.textContent = confirmText;
-    footer.appendChild(cancelBtn);
-    footer.appendChild(confirmBtn);
-    box.appendChild(footer);
-    overlay.appendChild(bg);
-    overlay.appendChild(box);
-    document.body.appendChild(overlay);
-    lockScroll();
-    const close = (result) => {
-      unlockScroll();
-      overlay.remove();
-      resolve(result);
-    };
-    const onKeyDown = (e) => {
-      if (e.key === "Escape") close(false);
-    };
-    document.addEventListener("keydown", onKeyDown);
-    cancelBtn.onclick = () => {
-      document.removeEventListener("keydown", onKeyDown);
-      close(false);
-    };
-    confirmBtn.onclick = () => {
-      document.removeEventListener("keydown", onKeyDown);
-      close(true);
-    };
-    bg.onclick = () => {
-      document.removeEventListener("keydown", onKeyDown);
-      close(false);
-    };
-  });
-}
-function confirm() {
-  return (ctx) => {
-    ;
-    ctx.confirm = (message, options) => createConfirmModal(message, options ?? {});
-    return ctx;
-  };
+function computeFixedPos(el, placement = "bottom", gap = 6, center = true) {
+  return computeFixedPosRect(el.getBoundingClientRect(), placement, gap, center);
 }
 export {
   ApiError,
@@ -1582,7 +1576,6 @@ export {
   api,
   auth,
   computeFixedPos,
-  confirm,
   createApp,
   createPortal,
   enUS,

package/dist/client/locale/en_US.d.ts

@@ -27,6 +27,10 @@ export declare const enUS: {
         Modal: {
             ariaLabel: string;
         };
+        Confirm: {
+            confirmText: string;
+            cancelText: string;
+        };
         Drawer: {
             ariaLabel: string;
         };

package/dist/client/locale/zh_CN.d.ts

@@ -27,6 +27,10 @@ export declare const zhCN: {
         Modal: {
             ariaLabel: string;
         };
+        Confirm: {
+            confirmText: string;
+            cancelText: string;
+        };
         Drawer: {
             ariaLabel: string;
         };