weifuwu 0.38.2 → 0.40.0

package/README.md

@@ -709,21 +709,30 @@ app.destroy()
 ```tsx
 import type { Component, WfuiContext } from 'weifuwu/client'
 
-// 组件 = 纯函数 (props, ctx) => VNode
-const Greeting: Component<{ name: string }> = (props, ctx) => {
-  return <div>Hello, {props.name}!</div>
-}
+// 两阶段组件：mount（只一次）→ render（每次 dirty/props 变化）
+const Counter: Component = (_init, ctx) => {
+  // ── mount ──
+  let count = 0
+
+  ctx.ui.onmounted((el) => {
+    console.log('DOM 已创建', el)
+  })
 
-// 使用
-<Greeting name="world" />
+  // ── render ──
+  return (props) =>
+    h('button', { onClick: () => { count++; ctx.ui.render() } }, count)
+}
 ```
 
 | 规则 | 说明 |
 |------|------|
-| 组件签名 | `(props: P, ctx: WfuiContext) => VNode \| null` |
+| 组件签名 | `(initProps: P, ctx: WfuiContext) => (props: P) => VNode \| null` |
+| mount 阶段 | 外层函数只执行一次，初始化状态/注册生命周期 |
+| render 阶段 | 内层函数每次 dirty/props 变化时执行，返回 VNode |
 | 无 class | 无 `this`，无实例方法 |
 | 无 hook | 无 `useState` / `useEffect` / `useMemo` |
-| 无生命周期 | 替代方案：`ref` 回调管理 mount/unmount |
+| 状态 | 闭包变量 + `ctx.ui.render()` 手动触发，或 `ctx.ui.$()` 响应式容器 |
+| 生命周期 | `ctx.ui.onmount / onmounted / onunmount / onupdate` |
 
 ### JSX 工厂
 
@@ -744,53 +753,40 @@ h('div', { class: 'x' }, child1, child2)
 | `jsx` / `jsxs` / `jsxDEV` | JSX 编译目标 |
 | `Fragment` | 片段 |
 
-### VNode 结构
+---
 
-```ts
-interface VNode {
-  type: string | Component | typeof Fragment
-  props: Record<string, any>
-  key?: string
-  el?: Node           // 对应 DOM（框架内部）
-  _$?: Record<string, any>  // 组件状态（框架内部）
-  _child?: any        // 子 VNode 缓存
-  _cleanup?: (() => void)  // ref 清理函数
-}
-```
+## 状态管理
 
----
+### 闭包变量 + `ctx.ui.render()`（推荐）
 
-## 状态管理 — ctx.ui.$
+```tsx
+const Counter: Component = (_init, ctx) => {
+  let count = 0
+  return (props) =>
+    h('button', { onClick: () => { count++; ctx.ui.render() } }, count)
+}
+```
 
-`ctx.ui.$` 是**组件级深度 Proxy**：
+### `ctx.ui.$()` — 响应式状态容器
 
-- `$.x = val` → 自动标记 dirty → 下个微任务批量 VDOM patch
-- `$.arr.push(val)` → Proxy 拦截数组突变 → 自动渲染
-- `$.arr[0].x = y` → 深度拦截嵌套对象 → 自动渲染
-- 每个组件实例有独立 Proxy（`vnode._$`），同名变量不冲突
+`ctx.ui.$()` 返回浅 Proxy，赋值自动触发渲染（微任务批量合并）：
 
 ```tsx
-function Counter(_props: {}, ctx: WfuiContext) {
-  const $ = ctx.ui.$
-  if (!ctx.ui.ready) $.count = 0     // 初始化（仅首次执行）
-
-  return (
-    <div>
-      <span>{$.count}</span>
-      <button onClick={() => $.count++}>+</button>
-    </div>
-  )
+const FormPage: Component = (_init, ctx) => {
+  const $ = ctx.ui.$()
+  $.email = ''
+  return (props) =>
+    h('input', { value: $.email, onInput: (e: any) => { $.email = e.target.value } })
 }
 ```
 
+**注意**：mount/render/生命周期回调中 `$.x = val` 不触发渲染。仅事件/timer/Promise.then 中生效。
+
 | API | 说明 |
 |-----|------|
-| `ctx.ui.$` | 组件级深度 Proxy |
-| `ctx.ui.ready` | `boolean`，首次执行后为 `true` |
-| `ctx.ui.dirty()` | 手动标记脏状态（仅绕过 Proxy 时使用） |
-| `ctx.ui.render()` | 手动触发渲染（框架内部使用，页面代码不用） |
-
-**重要规则**：render 函数内部不写 `$`。`$` 的写入只在事件回调（onClick/onInput）、ref 回调、或 `if (!ctx.ui.ready)` 初始化块中进行。
+| `ctx.ui.$()` | 创建响应式状态容器 |
+| `ctx.ui.render()` | 立即同步渲染 |
+| `ctx.ui.dirty()` | 标记脏状态，下个微任务批量渲染 |
 
 ---
 
@@ -811,27 +807,62 @@ function Counter(_props: {}, ctx: WfuiContext) {
 
 ---
 
-## 生命周期 — ref 回调
+## 生命周期
 
-`ref` 回调在 mount 时触发，接收 DOM 元素。返回的清理函数在 unmount 时由框架保证调用：
+框架不提供 `ref` prop。使用 `ctx.ui.onmount / onmounted / onunmount / onupdate`：
+
+| API | 触发时机 | 参数 | 返回值 |
+|-----|---------|------|--------|
+| `ctx.ui.onmount(fn)` | render 前（DOM 未创建） | `() => void` | — |
+| `ctx.ui.onmounted(fn)` | 首次 render 后（DOM 已创建） | `(el: Element) => cleanup` | `() => void`（可选 cleanup）|
+| `ctx.ui.onunmount(fn)` | 组件移除前 | `() => void` | — |
+| `ctx.ui.onupdate(fn)` | props 变化时 | `(prevProps) => void` | — |
 
 ```tsx
-function Timer(_props: {}, ctx: WfuiContext) {
-  return (
-    <div ref={el => {
-      const timer = setInterval(() => console.log('tick'), 1000)
-      return () => { clearInterval(timer); console.log('cleanup') }
-    }}>Timer</div>
-  )
+const Timer: Component = (_init, ctx) => {
+  let timer: ReturnType<typeof setInterval> | undefined
+
+  ctx.ui.onmounted((el) => {
+    timer = setInterval(() => console.log('tick'), 1000)
+    return () => clearInterval(timer)
+  })
+
+  return (props) => h('div', {}, 'Timer')
 }
 ```
 
-| 场景 | 写法 |
-|------|------|
-| 事件监听 | `ref={el => { el.addEventListener(...); return () => el.removeEventListener(...) }}` |
-| 定时器 | `ref={el => { const t = setInterval(...); return () => clearInterval(t) }}` |
-| 第三方库 | `ref={el => { const c = new Chart(el); return () => c.destroy() }}` |
-| 仅 mount | `ref={el => { init(el) }}`（无返回） |
+**注意**：`onmounted` 在首次渲染后触发，此时 DOM 已创建。生命周期回调中 `$.x = val` 不触发渲染（仅事件/timer 中生效）。
+
+对于**内嵌元素**（非根元素），用 `el.querySelector()`：
+
+```tsx
+ctx.ui.onmounted((el) => {
+  const input = el.querySelector('input[type="text"]') as HTMLElement
+  input?.focus()
+})
+```
+
+所有钩子遵循替换模式：多次注册只保留最后一次。
+
+### 异步组件
+
+在 mount 阶段发起请求，数据通过 `$.x = val` 自动触发渲染：
+
+```tsx
+const UserProfile: Component = (initProps, ctx) => {
+  const $ = ctx.ui.$()
+  $.loading = true
+
+  fetch(`/api/user/${initProps.id}`)
+    .then(r => r.json())
+    .then(user => { $.user = user; $.loading = false })
+
+  return (props) =>
+    $.loading
+      ? h('div', {}, '加载中...')
+      : h('div', {}, $.user?.name ?? '')
+}
+```
 
 ---
 
@@ -1122,7 +1153,7 @@ import { ErrorBoundary } from 'weifuwu/client'
 <ErrorBoundary fallback={({ error }) => (
   <div>
     <p>出错了: {String(error)}</p>
-    <button onClick={() => ctx.ui.$.error = null}>重试</button>
+    <button onClick={() => location.reload()}>重试</button>
   </div>
 )}>
   <UserProfile />
@@ -1134,7 +1165,7 @@ import { ErrorBoundary } from 'weifuwu/client'
 | `fallback` | `VNode \| ((props: { error }) => VNode) \| null` | `null` | 错误时渲染的内容 |
 | `children` | `any` | — | 子组件 |
 
-捕获子组件 render 时的错误 → `$.error` → 渲染 fallback。清除 `$.error` 即可重试。
+捕获子组件 render 时的错误 → 渲染 fallback。清除 `error` 即可重试。
 
 ---
 
@@ -1148,8 +1179,7 @@ createApp()
   .mount('#root', App)
 
 // 在组件中使用
-const $ = ctx.ui.$
-async function handleDelete() {
+async function handleDelete(ctx: WfuiContext) {
   const ok = await ctx.confirm?.('确定删除这条记录？', {
     title: '确认删除',
     confirmText: '删除',
@@ -1157,7 +1187,7 @@ async function handleDelete() {
     variant: 'danger',  // 'primary' | 'danger'
   })
   if (ok) {
-    $.deleted = true
+    // 执行删除...
   }
 }
 ```
@@ -1228,9 +1258,9 @@ import type { RouterOptions } from 'weifuwu/client'
 
 | 类型 | 说明 |
 |------|------|
-| `VNode` | `{ type, props, key?, el?, _$?, _child?, _cleanup? }` |
+| `VNode` | `{ type, props, key? }` |
 | `VNodeType` | `string \| Component \| typeof Fragment` |
-| `Component<P>` | `(props: P, ctx: WfuiContext) => VNode \| null` |
+| `Component<P>` | `(initProps: P, ctx: WfuiContext) => (props: P) => VNode \| null` |
 | `WfuiContext` | `{ ui, route?, app?, ws?, api?, auth?, i18n?, confirm?, [key]: unknown }` |
 | `AppMiddleware` | `(ctx: WfuiContext) => WfuiContext` |
 | `RouteDef` | `{ path, component?, layout?, children?, auth?, title? }` |
@@ -1471,7 +1501,7 @@ document.documentElement.setAttribute('data-theme', 'dark')
 |------|------|------|
 | 注入 | 中间件注入 ctx.field | 中间件注入 ctx.field |
 | 读取 | handler 读取 ctx | 组件读取 ctx |
-| 渲染 | 返回 Response | Proxy 自动触发 VDOM patch |
+| 渲染 | 返回 Response | `ctx.ui.render()` / `ctx.ui.dirty()` 触发 VDOM patch |
 
 ## Closeable 接口
 

package/dist/client/app.d.ts

@@ -5,12 +5,8 @@
  *
  * ctx.ui 在 mount 时注入：
  *   ctx.ui.render()    触发组件重渲染
- *   ctx.ui.$          组件级状态 Proxy（由 renderComponent 创建）
- *   ctx.ui.ready       首次执行标记（由渲染器管理）
- *
- * ctx.ui.$ 是组件级 Proxy（组件间隔离）：
- *   $.x = val              → 设置当前组件状态，自动触发渲染
- *   ctx.ui.dirty()         → 标记脏状态（仅深层突变时需要）
+ *   ctx.ui.dirty()     标记脏状态，下个微任务批量渲染
+ *   ctx.ui.$()         创建响应式状态容器（$.x = val 自动 dirty）
  */
 import type { WfuiContext, AppMiddleware } from './types.ts';
 import type { Component } from './vnode.ts';

package/dist/client/error-boundary.d.ts

@@ -10,7 +10,7 @@
  * ```
  *
  * 基于 ctx.ui._errorHandler 机制：在渲染子组件前注入错误处理器，
- * 子组件 render 抛错时设置 $.error → 重新渲染 fallback。
+ * 子组件 render 抛错时设置 error → 重新渲染 fallback。
  */
 import type { WfuiContext } from './types.ts';
 import type { VNode } from './vnode.ts';
@@ -20,4 +20,4 @@ export interface ErrorBoundaryProps {
     }) => VNode) | null;
     children?: any;
 }
-export declare function ErrorBoundary(props: ErrorBoundaryProps, ctx: WfuiContext): VNode | null;
+export declare function ErrorBoundary(props: ErrorBoundaryProps, ctx: WfuiContext): (props2: ErrorBoundaryProps) => VNode | null;

package/dist/client/index.d.ts

@@ -15,7 +15,7 @@
  *   extendCtx                            → ctx 扩展
  *   WfuiContext / AppMiddleware / RouteDef → 类型
  */
-export { h, jsx, jsxs, jsxDEV, Fragment } from './vnode.ts';
+export { h, jsx, jsxs, jsxDEV, Fragment, Portal, createPortal } from './vnode.ts';
 export type { VNode, VNodeType, Component } from './vnode.ts';
 export { createApp } from './app.ts';
 export { router, RouteView } from './router.ts';
@@ -33,6 +33,8 @@ export { i18n } from './i18n.ts';
 export type { I18nOptions, I18nState } from './i18n.ts';
 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';