weifuwu 0.40.1 → 0.51.0

package/README.md

@@ -10,30 +10,17 @@ npm install weifuwu
 
 ---
 
-## 模块总览
+## 设计理念
 
-| 导入路径 | 模块 | 用途 | 依赖 |
-|---------|------|------|------|
-| `weifuwu` | **Router** | Trie 路由 + 中间件链 + WebSocket + GraphQL | — |
-| `weifuwu` | **serve** | HTTP 服务器 | Router |
-| `weifuwu` | **cors** | CORS 跨域中间件 | Router |
-| `weifuwu` | **serveStatic** | 静态文件服务（ETag/304/目录索引） | Router |
-| `weifuwu` | **postgres** | PostgreSQL 连接池 → `ctx.sql` | Router, DATABASE_URL |
-| `weifuwu` | **redis** | Redis 客户端 → `ctx.redis` | Router, REDIS_URL |
-| `weifuwu` | **ui** | SSR 渲染 + esbuild JS/CSS 动态编译 → `ctx.ui` | Router |
-| `weifuwu` | **graphql** | GraphQL 端点（支持 GraphiQL） | Router |
-| `weifuwu` | **createMiddleware** | 类型安全中间件工厂 | — |
-| `weifuwu` | **response** | HTTP 响应辅助函数（ok/badRequest/...） | — |
-| `weifuwu` | **parseBody** | JSON 请求体安全解析 | — |
-| `weifuwu/client` | **createApp** | 应用引导 + VDOM 渲染引擎 | — |
-| `weifuwu/client` | **router / RouteView** | 前端路由（history/hash 模式） | 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/layout` | **CSS 布局** | 35 个布局原语 + 72 个主题 Token | — |
+**零运行时依赖** — 前端无 npm 运行时依赖，不引入 Virtual DOM 库、rxjs、immer 等重型依赖。esbuild 编译 TSX 的结果即可直接运行。
+
+**两阶段组件模型** — 组件 = `(initProps, ctx) => (props) => VNode`。外层函数只执行一次（mount），内层函数每次状态/props 变化时执行（render）。无 class、无 `this`、无 Hook。
+
+**Proxy 驱动渲染** — `ctx.ui.$()` 返回深度 Proxy，`$.x = val` 自动触发当前组件的 VDOM patch。也支持手动 `ctx.ui.render()` 精确控制渲染时机。无需手动调用 `useState`/`useEffect`。
+
+**中间件注入一切** — 后端和前端共用同一理念：中间件向 `ctx` 注入能力（`ctx.sql` / `ctx.redis` / `ctx.api` / `ctx.auth` / `ctx.i18n` 等），Handler/组件从 `ctx` 读取。
+
+**SSR + 动态编译** — 后端 `ctx.ui.js()` 用 esbuild 实时编译 TSX，开发时改代码即刷即用，零构建步骤。
 
 ---
 
@@ -68,8 +55,9 @@ serve(app, { port: 3000 })
 ```tsx
 // src/main.tsx
 import { createApp, router, RouteView } from 'weifuwu/client'
+import type { Component } from 'weifuwu/client'
 
-function Home() { return <h1>Hello weifuwu</h1> }
+const Home: Component = () => () => <h1>Hello weifuwu</h1>
 
 createApp()
   .use(router({ routes: [{ path: '/', component: Home }] }))
@@ -78,8 +66,68 @@ createApp()
 
 ---
 
+## 模块总览
+
+| 导入路径 | 模块 | 用途 | 依赖 |
+|---------|------|------|------|
+| `weifuwu` | **Router** | Trie 路由 + 中间件链 + WebSocket + GraphQL | — |
+| `weifuwu` | **serve** | HTTP 服务器 | Router |
+| `weifuwu` | **cors** | CORS 跨域中间件 | Router |
+| `weifuwu` | **serveStatic** | 静态文件服务（ETag/304/目录索引） | Router |
+| `weifuwu` | **postgres** | PostgreSQL 连接池 → `ctx.sql` | Router, DATABASE_URL |
+| `weifuwu` | **redis** | Redis 客户端 → `ctx.redis` | Router, REDIS_URL |
+| `weifuwu` | **ui** | SSR 渲染 + esbuild JS/CSS 动态编译 → `ctx.ui` | Router |
+| `weifuwu` | **graphql** | GraphQL 端点（支持 GraphiQL） | Router |
+| `weifuwu` | **createMiddleware** | 类型安全中间件工厂 | — |
+| `weifuwu` | **response** | HTTP 响应辅助函数（ok/badRequest/...） | — |
+| `weifuwu` | **parseBody** | JSON 请求体安全解析 | — |
+| `weifuwu/client` | **createApp** | 应用引导 + VDOM 渲染引擎 | — |
+| `weifuwu/client` | **router / RouteView** | 前端路由（history/hash 模式） | 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/layout` | **CSS 布局** | 35 个布局原语 + 72 个主题 Token（也支持 `weifuwu/layout/style.css`） | — |
+
+---
+
+## 核心概念
+
+### 中间件模式（前后端一致）
+
+```
+后端:  app.use(cors())
+       app.use(postgres())
+       app.get('/users', (req, ctx) => { ctx.sql`SELECT *` })
+       // ctx 已注入 ctx.sql
+
+前端:  createApp()
+         .use(api({ baseURL: '/api' }))
+         .use(auth())
+         .mount('#root', App)
+       // ctx 已注入 ctx.api, ctx.auth
+```
+
+### 状态管理
+
+| 模式 | 后端 | 前端 |
+|------|------|------|
+| 注入 | 中间件注入 ctx.field | 中间件注入 ctx.field |
+| 读取 | handler 读取 ctx | 组件读取 ctx |
+| 渲染 | 返回 Response | `ctx.ui.render()` / `ctx.ui.dirty()` / `$.x = val` 触发局部 VDOM patch |
+
+### Closeable 接口
+
+所有有状态模块（postgres、redis）实现 `close(): Promise<void>`，serve 关闭时自动调用。
+
+---
+
 # 后端 API (`weifuwu`)
 
+> 以下为完整 API 参考，按需查阅。新手建议先阅读上文的「核心概念」和「快速开始」。
+
 ## Router
 
 Trie 路由，支持 URL 参数、通配符、中间件链、WebSocket、GraphQL。
@@ -417,7 +465,7 @@ app.use(ui())
 | `ctx.ui.html` | `` (strings, ...values) => Response `` | HTML 模板 (转义防 XSS) |
 | `ctx.ui.html.unsafe(str)` | `(string) => string` | 插入原始 HTML |
 | `ctx.ui.js(entryPath)` | `(string) => Promise<Response>` | esbuild 编译 TSX → JS bundle |
-| `ctx.ui.css(entryPath)` | `(string) => Promise<Response>` | 读取/编译 CSS（自动 PostCSS + Tailwind） |
+| `ctx.ui.css(entryPath)` | `(string) => Promise<Response>` | 读取 CSS 文件 → CSS Response（如安装 postcss + @tailwindcss/postcss 则自动编译） |
 
 ### ctx.ui.html — HTML 模板
 
@@ -433,7 +481,8 @@ app.get('/page', (req, ctx) => ctx.ui.html`
 ### ctx.ui.js — 编译 TSX → JS
 
 ```ts
-app.get('/app.js', (req, ctx) => ctx.ui.js('./src/main.tsx'))
+app.get('/app.js', (req, ctx) => ctx.ui.js('./src/main.tsx'))   // 相对路径
+app.get('/app.js', (req, ctx) => ctx.ui.js('weifuwu/client'))   // 或包名
 ```
 
 使用 esbuild 编译：
@@ -444,12 +493,14 @@ app.get('/app.js', (req, ctx) => ctx.ui.js('./src/main.tsx'))
 ### ctx.ui.css — CSS 编译
 
 ```ts
-app.get('/style.css', (req, ctx) => ctx.ui.css('./src/style.css'))
+app.get('/style.css', (req, ctx) => ctx.ui.css('./src/style.css'))               // 相对路径
+app.get('/style.css', (req, ctx) => ctx.ui.css('weifuwu/components/style.css'))   // 或包名
 ```
 
-- 纯 CSS 文件直接返回
-- 检测到 `postcss` + `@tailwindcss/postcss` 时自动编译 Tailwind CSS
-- 带 mtime 缓存验证
+- 无编译工具时直接返回原始 CSS
+- 检测到已安装 `postcss` + `@tailwindcss/postcss` 时自动编译 Tailwind CSS
+- 支持包名（`weifuwu/layout/style.css`, `weifuwu/components/style.css`）或文件路径
+- 带 mtime 缓存验证（开发时编辑文件后自动失效）
 
 ---
 
@@ -659,7 +710,9 @@ import type { GraphQLOptions, GraphQLHandler } from 'weifuwu'
 
 # 前端 API (`weifuwu/client`)
 
-零外部 npm 运行时依赖。组件模型：纯函数 `(props, ctx) => VNode`。
+> 以下为完整 API 参考，按需查阅。新手建议先阅读上文的「组件模型」和「状态管理」。
+
+零外部 npm 运行时依赖。组件签名：`(initProps, ctx) => (props) => VNode`（两阶段模型，外层 mount 只一次，内层 render 每次变化时执行）。无状态组件可简写为 `() => () => VNode`。
 
 构建配置（esbuild）：
 
@@ -714,25 +767,25 @@ const Counter: Component = (_init, ctx) => {
   // ── mount ──
   let count = 0
 
-  ctx.ui.onmounted((el) => {
-    console.log('DOM 已创建', el)
-  })
-
   // ── render ──
   return (props) =>
     h('button', { onClick: () => { count++; ctx.ui.render() } }, count)
 }
+
+// 无状态组件：只有 render
+const Badge: Component = () =>
+  (props) => h('span', { class: `badge-${props.variant}` }, props.children)
 ```
 
 | 规则 | 说明 |
 |------|------|
 | 组件签名 | `(initProps: P, ctx: WfuiContext) => (props: P) => VNode \| null` |
-| mount 阶段 | 外层函数只执行一次，初始化状态/注册生命周期 |
+| mount 阶段 | 外层函数只执行一次，初始化状态 |
 | render 阶段 | 内层函数每次 dirty/props 变化时执行，返回 VNode |
 | 无 class | 无 `this`，无实例方法 |
 | 无 hook | 无 `useState` / `useEffect` / `useMemo` |
 | 状态 | 闭包变量 + `ctx.ui.render()` 手动触发，或 `ctx.ui.$()` 响应式容器 |
-| 生命周期 | `ctx.ui.onmount / onmounted / onunmount / onupdate` |
+| ref 引用 | `ref={el => { if (el) init; else cleanup }}` 获取 DOM |
 
 ### JSX 工厂
 
@@ -757,7 +810,18 @@ h('div', { class: 'x' }, child1, child2)
 
 ## 状态管理
 
-### 闭包变量 + `ctx.ui.render()`（推荐）
+### Render 机制总览
+
+| API | 触发时机 | 渲染方式 | 作用域 | 使用场景 |
+|------|---------|---------|--------|---------|
+| `$.x = val` | 赋值后自动 | 微任务批量（异步） | 当前组件 | **日常 UI 状态** — 表单输入、切换开关、异步数据加载等 |
+| `ctx.ui.dirty()` | 主动调用 | 微任务批量（异步） | 当前/指定 | **绕过 Proxy 后手动标记** |
+| `ctx.ui.render()` | 主动调用 | 立即同步 | 当前/指定 | **需要立即拿到最新 DOM** — DOM 测量、动画触发 |
+| `ctx.ui.render(['id'])` | 主动调用 | 立即同步 | 指定组件 | **跨组件精准刷新** — 全局事件、Portal 远程控制 |
+
+`render()` 和 `dirty()` 无参 = 当前组件，传参 = 指定组件列表。三套 API 同一 scope 机制。
+
+### 闭包变量 + `ctx.ui.render()`（简单场景）
 
 ```tsx
 const Counter: Component = (_init, ctx) => {
@@ -767,26 +831,132 @@ const Counter: Component = (_init, ctx) => {
 }
 ```
 
-### `ctx.ui.$()` — 响应式状态容器
+适合状态极少的简单组件。每次修改后手动调用 `ctx.ui.render()` 同步刷新 DOM。
+
+### `ctx.ui.$()` — 响应式 Proxy（推荐首选）
 
-`ctx.ui.$()` 返回浅 Proxy，赋值自动触发渲染（微任务批量合并）：
+`ctx.ui.$()` 返回**深度 Proxy** 容器。任意层级赋值操作自动触发渲染（微任务批量合并）：
 
 ```tsx
 const FormPage: Component = (_init, ctx) => {
   const $ = ctx.ui.$()
   $.email = ''
+  $.loading = false
   return (props) =>
-    h('input', { value: $.email, onInput: (e: any) => { $.email = e.target.value } })
+    h('input', {
+      value: $.email,
+      onInput: (e: any) => { $.email = e.target.value }
+    })
 }
 ```
 
-**注意**：mount/render/生命周期回调中 `$.x = val` 不触发渲染。仅事件/timer/Promise.then 中生效。
+**深度 Proxy 拦截**：
+- `$.x = val` → 自动排队重渲染
+- `$.obj.a = 1` → 自动 dirty（嵌套对象递归包装）
+- `$.arr.push(val)` / `$.arr[0].x = y` → 自动 dirty（数组变异 + 嵌套属性拦截）
+- `delete $.x` → 自动 dirty
+- 每个组件实例独立 Proxy，同名变量不冲突
 
-| API | 说明 |
-|-----|------|
-| `ctx.ui.$()` | 创建响应式状态容器 |
-| `ctx.ui.render()` | 立即同步渲染 |
-| `ctx.ui.dirty()` | 标记脏状态，下个微任务批量渲染 |
+**注意**：mount/render 中 `$.x = val` **不触发渲染**，仅事件/timer/Promise.then 中生效。这是有意设计——初始化和 mount 阶段设置状态不应触发额外渲染。
+
+**何时用 `$`**：所有需要触发 UI 重新渲染的状态。90% 以上的场景用 `$` 就够。
+
+**何时不用**：
+- 不需要触发渲染的内部缓存（用闭包变量 `let`）
+- 简单组件只有一两个状态变量（闭包变量 + `render()` 更轻量）
+
+### `ctx.ui.dirty()` — 异步标记脏
+
+异步版本，无参 = 当前组件，传参 = 指定组件列表。多次调用合并为一次微任务渲染。`$` 内部就是调 `dirty()`。
+
+### `ctx.ui.render()` — 同步强制渲染
+
+与 `dirty()` 的微任务批量不同，`render()` 是**同步执行**的。调用后立即执行 VDOM diff + patch，DOM 立刻更新。无参时只刷新当前组件，传参时可精准刷新指定组件。
+
+**何时必须用 `render()`**：
+
+```tsx
+// 1. DOM 测量（读取 offsetHeight/scrollWidth 等）
+// 用 ref 在 DOM 创建后操作
+ref: (el) => {
+  if (!el) return
+  el.style.height = 'auto'
+  ctx.ui.render()
+  const h = el.offsetHeight
+  el.style.height = h + 'px'
+}
+
+// 2. 动画触发（需要确保上一帧 DOM 已提交）
+function startAnimation() {
+  $.animating = true
+  ctx.ui.render()                // 同步刷新 DOM
+  el.startViewTransition(...)    // 拿到最新 DOM 启动动画
+}
+
+// 3. 第三方库需要在事件回调中读取最新 DOM
+onClick: () => {
+  $.selected = !$.selected
+  ctx.ui.render()                // 确保 DOM 已更新
+  thirdPartyLib.measure(el)      // 读取最新状态
+}
+```
+
+**规则**：能用 `$` 就用 `$`。只有当你**必须同步拿到最新 DOM 状态**时才用 `render()`。
+
+### 三种方式速查
+
+```tsx
+// 自动：$.x = val — 微任务批量，绑定当前组件
+const $ = ctx.ui.$()
+$.count++
+$.name = 'hello'         // 多次赋值合并为一次渲染
+
+// 手动：ctx.ui.render() — 同步，无参=当前，传参=指定
+let count = 0
+count++
+ctx.ui.render()          // DOM 立刻更新
+ctx.ui.render(['stats']) // 精准刷新指定组件
+
+// 异步：ctx.ui.dirty() — 微任务批量，同 render() 作用域
+ctx.ui.dirty()
+ctx.ui.dirty(['stats'])  // 批处理合并
+```
+
+**性能说明**：
+- `$.x = val` 和 `dirty()` 都是微任务批量合并
+- `render()` 每次调用都触发一次完整 diff/patch
+- 三个入口同一套 scope 机制，不想要的渲染不触发
+
+### 实践建议
+
+**组件库**（可分享组件）推荐手动模式：
+
+```tsx
+const DatePicker = (_init, ctx) => {
+  let show = false             // let 不触发渲染
+  return (props) =>
+    h('input', {
+      onClick: () => { show = true; ctx.ui.render() }
+    })
+}
+```
+
+行为只由 `render()` 显式控制，不依赖 `$`，测试中 `render()` 直接 mock 为空函数。
+
+**业务层**推荐自动模式：
+
+```tsx
+const OrderPage = (_init, ctx) => {
+  const $ = ctx.ui.$
+  $.orders = []                // $ 赋值自动触发渲染
+  $.loading = false
+  return (props) => h('div', {}, $.loading ? h(Spinner) : h(OrderList, { orders: $.orders }))
+}
+```
+
+省事、安全、`$` 绑定所属组件不波及兄弟。
+
+同一个组件内可以按变量混用两种模式：需要渲染的用 `$`，不需要的用 `let`。
 
 ---
 
@@ -807,43 +977,41 @@ const FormPage: Component = (_init, ctx) => {
 
 ---
 
-## 生命周期
-
-框架不提供 `ref` prop。使用 `ctx.ui.onmount / onmounted / onunmount / onupdate`：
+## ref 管理 DOM
 
-| 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` | — |
+使用 `ref` prop 获取元素引用，适合管理第三方库或读取 DOM：
 
 ```tsx
 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')
+  return (props) =>
+    h('div', {
+      ref: (el) => {
+        if (el) {
+          timer = setInterval(() => console.log('tick'), 1000)
+        } else {
+          clearInterval(timer)
+        }
+      },
+    }, 'Timer')
 }
 ```
 
-**注意**：`onmounted` 在首次渲染后触发，此时 DOM 已创建。生命周期回调中 `$.x = val` 不触发渲染（仅事件/timer 中生效）。
+`ref` 在元素创建时调用 `ref(el)`，元素移除时调用 `ref(null)`。
+`ref` 不接受返回值，清理逻辑直接在 `else` 分支处理。
 
-对于**内嵌元素**（非根元素），用 `el.querySelector()`：
+对于**内嵌元素**（非根元素），直接在目标元素上放 `ref`：
 
 ```tsx
-ctx.ui.onmounted((el) => {
-  const input = el.querySelector('input[type="text"]') as HTMLElement
-  input?.focus()
-})
+return h('div', {},
+  h('input', {
+    type: 'text',
+    ref: (el) => el?.focus(),
+  })
+)
 ```
 
-所有钩子遵循替换模式：多次注册只保留最后一次。
-
 ### 异步组件
 
 在 mount 阶段发起请求，数据通过 `$.x = val` 自动触发渲染：
@@ -1109,7 +1277,7 @@ createApp()
 
 // 运行时切换语言
 ctx.i18n?.setLocale('en-US')
-// → 自动触发全应用重渲染
+// → 自动触发根组件重渲染（所有组件使用新语言文案）
 ```
 
 | I18nOptions | 类型 | 默认值 | 说明 |
@@ -1280,9 +1448,131 @@ import type { RouterOptions } from 'weifuwu/client'
 
 ```ts
 import { Button, Input, Table, Modal, Toast } from 'weifuwu/components'
-import 'weifuwu/components/style.css'
+import 'weifuwu/components/style.css'   // 包含 Token + 35 布局原语 + 组件样式，一次性引入
+```
+
+### 使用示例
+
+```tsx
+// ├─ 按钮
+<Button variant="primary" onClick={() => alert('提交')}>提交</Button>
+<Button variant="ghost" loading>加载中</Button>
+<Button variant="danger" size="lg" block>删除</Button>
+
+// ├─ 输入框
+<Input placeholder="请输入邮箱" />
+<Input label="用户名" required error="必填" />
+<Input type="password" hint="至少6位" prefix="🔒" />
+
+// ├─ 选择器
+<Select options={[{ value: 'a', label: '选项A' }]} placeholder="请选择" />
+<Select searchable options={options} onChange={v => setVal(v)} />
+
+// ├─ 复选框 / 开关 / 单选
+<Checkbox checked={agree} onChange={setAgree} label="同意协议" />
+<Switch checked={enabled} onChange={setEnabled} />
+<RadioGroup options={[{ value: '1', label: '男' }, { value: '2', label: '女' }]} value={gender} />
+
+// ├─ 表格
+<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>
+<Drawer open={open} title="详情" onClose={() => setOpen(false)} position="right">内容</Drawer>
+
+// ├─ 消息提示
+<Toast toasts={items} position="top-right" max={5} onRemove={id => remove(id)} />
+<Alert variant="warning" closable>注意：磁盘空间不足</Alert>
+
+// ├─ 标签 / 徽标 / 头像
+<Badge count={5}>消息</Badge>
+<Badge variant="success">通过</Badge>
+<Tag variant="blue" closable onClose={() => {}}>标签</Tag>
+<Avatar name="张三" size="lg" />
+
+// ├─ 卡片 / 统计卡片
+<Card title="卡片标题" extra={<a href="#">更多</a>}>卡片内容</Card>
+<StatCard title="总用户" value="1,234" trend={12.5} variant="primary" />
+
+// ├─ 标签页 / 下拉菜单
+<Tabs items={[{ key: 'a', label: '标签A' }, { key: 'b', label: '标签B' }]} activeKey="a" onChange={setTab} />
+<Dropdown items={[{ label: '编辑', onClick: () => {} }, { label: '删除', danger: true }]}>操作</Dropdown>
+
+// ├─ 分页 / 步骤条
+<Pagination total={100} page={1} pageSize={10} onChange={setPage} />
+<Steps items={[{ title: '第一步' }, { title: '第二步' }]} current={1} />
+
+// ├─ 滑块 / 进度条
+<Slider min={0} max={100} value={50} onChange={setValue} />
+<ProgressBar value={75} variant="success" label="75%" />
+
+// ├─ 面包屑 / 分割线
+<Breadcrumb items={[{ label: '首页' }, { label: '用户管理' }]} />
+<Divider />
+<Divider orientation="left">分割文字</Divider>
+
+// ├─ 加载 / 空状态 / 骨架屏
+<Loading text="加载中..." />
+<EmptyState title="暂无数据" description="请先创建一条记录" action={<Button>新建</Button>} />
+<Skeleton variant="text" lines={3} />
+<Skeleton variant="table" lines={5} cols={4} />
+<Skeleton variant="avatar" />
+<Skeleton variant="image" />
+
+// ├─ 表单验证
+<Form validation={{ email: [{ required: true, message: '请输入邮箱' }] }}
+      onSubmit={values => api.post('/login', values)}
+      onError={errors => setErrors(errors)}>
+  <Field label="邮箱" error={errors.email}>
+    <Input name="email" />
+  </Field>
+  <Button type="submit">登录</Button>
+</Form>
+```
+
+> 所有组件引用 `--wf-*` CSS 变量做主题，详见下文的「样式定制指南」。
+
+### 生命周期映射
+
+组件没有生命周期函数。每个阶段对应到代码的明确位置：
+
+```
+mount ──────────────────────────────────────────
+  const Counter = (_init, ctx) => {       ← mount（只一次）
+    let count = 0                           ← 初始化状态
+    return (props) => {                     ← render 函数
+      // ...                                 ← 每次 dirty/props 变化执行
+    }
+  }
+
+ref ────────────────────────────────────────────
+  h('div', {
+    ref: (el) => {
+      if (el) { /* 元素已创建 */ }           ← 相当于 onmounted
+      else     { /* 元素已移除 */ }           ← 相当于 onunmount
+    }
+  })
+
+props 变化 ─────────────────────────────────────
+  return (props) => {
+    // 每次 render 都收到最新 props           ← 相当于 onupdate
+    if (props.value !== prevValue) { ... }
+  }
 ```
 
+| 旧概念 | 新写法 |
+|--------|--------|
+| `onmount` | mount 外层函数直接写 |
+| `onmounted` | `ref` 的 `if (el)` 分支 |
+| `onunmount` | `ref` 的 `else` 分支 |
+| `onupdate` | render 内层函数收新 props 自行比较 |
+| `全局刷新` | `ctx.ui.render(['_wf_root'])` |
+| `局部刷新` | `ctx.ui.render()` 或 `$.x = val` |
+| `跨组件刷新` | `ctx.ui.selfId('name')` + `render(['name'])` |
+
 ## 组件列表
 
 ### 表单核心
@@ -1372,14 +1662,24 @@ import 'weifuwu/components/style.css'
 
 纯 CSS 布局原语 + 72 个主题 Token。不绑定任何 JS 框架。
 
+> **全栈 weifuwu 项目**：`weifuwu/components/style.css` 已包含布局系统，一条 import 就够了，无需单独引用本页。
+> 本页仅适用于**非 weifuwu 项目**或**只需 CSS 布局**的场景。
+
 ```html
-<link rel="stylesheet" href="/node_modules/weifuwu/dist/layout/weifuwu-layout.css">
+<link rel="stylesheet" href="/node_modules/weifuwu/layout">
 ```
 
-或通过 `ctx.ui.css` 服务：
+或在 weifuwu 服务端通过 `ctx.ui.css` 直接引用包名（`ctx.ui.css` 自动解析 exports map）：
 
 ```ts
-app.get('/layout.css', (req, ctx) => ctx.ui.css('./node_modules/weifuwu/dist/layout/weifuwu-layout.css'))
+// 方案 A：组件 + 布局全部搞定（推荐）
+app.get('/style.css', (req, ctx) => ctx.ui.css('weifuwu/components/style.css'))
+
+// 方案 B：只用布局
+app.get('/layout.css', (req, ctx) => ctx.ui.css('weifuwu/layout'))
+```
+
+也支持相对路径：`ctx.ui.css('./src/style.css')`。
 ```
 
 ## 35 个布局原语
@@ -1486,34 +1786,185 @@ document.documentElement.setAttribute('data-theme', 'dark')
 
 ---
 
-# 核心概念
+# 样式定制指南
 
-## 中间件模式（前后端一致）
+## 全局主题变量
 
+所有组件引用 `--wf-*` CSS 变量。在根元素覆盖即可定制主题：
+
+```css
+:root {
+  --wf-color-primary: #6366f1;
+  --wf-color-primary-hover: #4f46e5;
+  --wf-radius: 8px;
+  --wf-font-sans: 'Inter', system-ui, sans-serif;
+}
 ```
-后端:  app.use(cors())
-       app.use(postgres())
-       app.get('/users', (req, ctx) => { ctx.sql`SELECT *` })
-       // ctx 已注入 ctx.sql
 
-前端:  createApp()
-         .use(api({ baseURL: '/api' }))
-         .use(auth())
-         .mount('#root', App)
-       // ctx 已注入 ctx.api, ctx.auth
+## 暗色模式
+
+```ts
+document.documentElement.setAttribute('data-theme', 'dark')
 ```
 
-## 状态管理
+所有 `--wf-*` 变量在 `[data-theme="dark"]` 下自动切换。可自定义暗色变量：
 
-| 模式 | 后端 | 前端 |
-|------|------|------|
-| 注入 | 中间件注入 ctx.field | 中间件注入 ctx.field |
-| 读取 | handler 读取 ctx | 组件读取 ctx |
-| 渲染 | 返回 Response | `ctx.ui.render()` / `ctx.ui.dirty()` 触发 VDOM patch |
+```css
+[data-theme="dark"] {
+  --wf-color-bg: #1a1a2e;
+  --wf-color-text: #e0e0e0;
+  --wf-color-border: #2a2a4a;
+}
+```
 
-## Closeable 接口
+## 组件级覆盖
 
-所有有状态模块（postgres、redis）实现 `close(): Promise<void>`，serve 关闭时自动调用。
+```css
+/* 覆盖 Button 主色 */
+.wf-btn--primary {
+  background: #06b6d4;
+  border-color: #06b6d4;
+}
+
+/* 覆盖 Modal 圆角 */
+.wf-modal-content {
+  border-radius: 16px;
+}
+```
+
+## 作用域主题
+
+```html
+<div style="--wf-color-primary: #f59e0b;">
+  <!-- 此区域内组件使用金色主题，外部不受影响 -->
+  <button class="wf-btn wf-btn--primary">金色按钮</button>
+</div>
+```
+
+CSS 变量会沿 DOM 树继承，利用这一点可实现多主题共存。
+
+---
+
+# 组合场景示例
+
+## 登录表单
+
+```tsx
+const LoginPage = (_init, ctx) => {
+  const $ = ctx.ui.$()
+  $.errors = {}
+  $.submitting = false
+
+  return (props) =>
+    h('div', { class: 'wf-stack', style: { maxWidth: 400, margin: '40px auto' } },
+      h(Card, { shadow: 'md' },
+        h('div', { class: 'wf-stack', style: { gap: 'var(--wf-space-md)' } },
+          h('h2', {}, '登录'),
+          h(Form, {
+            validation: {
+              email: [{ required: true, pattern: /@/, message: '请输入有效邮箱' }],
+              password: [{ required: true, minLength: 6, message: '密码至少6位' }],
+            },
+            onSubmit: async (values) => {
+              $.submitting = true
+              await api.post('/login', values)
+              $.submitting = false
+            },
+            onError: (errors) => { $.errors = errors },
+          }, [
+            h(Field, { label: '邮箱', error: $.errors.email },
+              h(Input, { name: 'email', type: 'email', placeholder: 'name@example.com' })),
+            h(Field, { label: '密码', error: $.errors.password },
+              h(Input, { name: 'password', type: 'password' })),
+            h(Button, { type: 'submit', loading: $.submitting, block: true }, '登录'),
+          ])
+        )
+      )
+    )
+}
+```
+
+## 数据列表 + 搜索
+
+```tsx
+const UserList = (_init, ctx) => {
+  const $ = ctx.ui.$()
+  $.keyword = ''
+  $.sortKey = 'name'
+  $.sortOrder = 'asc'
+  const users = [
+    { id: 1, name: '张三', email: 'zhang@example.com', role: '管理员' },
+    { id: 2, name: '李四', email: 'li@example.com', role: '编辑' },
+  ]
+
+  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)' } },
+      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' }, '新建用户'),
+      ),
+      h(Table, {
+        columns: [
+          { key: 'id', label: 'ID', width: 60 },
+          { key: 'name', label: '姓名', sortable: true },
+          { key: 'email', label: '邮箱', sortable: true },
+          { key: 'role', label: '角色' },
+        ],
+        data: filtered,
+        sortKey: $.sortKey,
+        sortOrder: $.sortOrder,
+        onSort: (key, order) => { $.sortKey = key; $.sortOrder = order },
+        emptyText: '无匹配用户',
+      }),
+      h(Pagination, { total: filtered.length, page: 1, pageSize: 10, onChange: (p: number) => {} }),
+    )
+}
+```
+
+## 消息提示
+
+```tsx
+// 在任意组件中调用
+let toastId = 0
+
+function showToast(ctx: WfuiContext, type: ToastType, message: string) {
+  // 通过 ctx 管理 Toast 列表
+  const $ = ctx.ui.$()
+  $.toasts = $.toasts ?? []
+  const id = String(++toastId)
+  $.toasts = [...$.toasts, { id, type, message }]
+
+  // 自动消失
+  if (type !== 'error') {
+    setTimeout(() => {
+      $.toasts = $.toasts.filter((t: any) => t.id !== id)
+    }, 3000)
+  }
+}
+
+// 页面中使用
+const App = (_init, ctx) => {
+  const $ = ctx.ui.$()
+  $.toasts = []
+
+  return (props) =>
+    h('div', {}, [
+      h(Button, {
+        onClick: () => showToast(ctx, 'success', '操作成功'),
+      }, '显示提示'),
+      h(Toast, {
+        toasts: $.toasts,
+        position: 'top-right',
+        max: 3,
+        onRemove: (id) => { $.toasts = $.toasts.filter((t: any) => t.id !== id) },
+      }),
+    ])
+}
+```
 
 ---