weifuwu 0.87.0 → 0.89.0

package/content/guides/middleware.md

@@ -1,459 +0,0 @@
-# 中间件与 ctx 注入链
-
-> 从 docs/frontend-middleware.md 迁移（content/ 文档库——随 npm 包发布，与框架版本同步）。
-> 本页为叙述性指南——组件/能力逐项参考见 content/ 各域目录。
-
-# 前端中间件与工具（weifuwu/ui-dom）
-
-> ⚠️ **`weifuwu/client` 已并入 `weifuwu/ui-dom`**——中间件（api/auth/ws/i18n）位于 `weifuwu/ui-dom`，前端运行时唯一入口为 `weifuwu/ui-dom`（vdom3 事件流引擎：createRouter + createRoot），见 [ui-dom 指南](ui-dom-guide.md)。
-
-## createRouter — 前端路由（vdom3）
-
-```tsx
-import { createRouter, h } from 'weifuwu/ui-dom'
-
-let ctx: any = {}
-ctx = v3Toast()(ctx)                  // 中间件面展开（ctx 注入——对齐后端 app.use）
-ctx = v3Notification()(ctx)          // 注入 ctx.notification
-
-const handle = createRouter(
-  [
-    { path: '/', render: () => h(Home, {}) },
-    { path: '/users', render: () => h(UserList, {}) },
-    { path: '/users/:id', render: (params) => h(UserDetail, { id: params.id }) },
-    { path: '*', render: () => h(NotFound, {}) },
-  ],
-  document.querySelector('#root')!,
-  { ctx },
-)
-```
-
-### 嵌套布局（RouteDef.layout——跨路由工厂不重跑）
-
-```tsx
-const DashboardLayout = async (page: any) => {
-  let open = true
-  return h('div', { class: 'wf-row' },
-    h('aside', {}, '导航菜单'),
-    h('main', {}, page),   // 子路由内容（layout 包装——工厂复用——状态保持）
-  )
-}
-// { path: '/users', layout: DashboardLayout, render: () => h(UserList, {}) }
-```
-
-### 编程式导航
-
-```tsx
-// 在任意组件/页面中（ctx.app——createRouter 注入）
-ctx.app?.navigate('/users/123?tab=profile')
-```
-
-| ctx 注入 | 类型 | 说明 |
-|----------|------|------|
-| `ctx.params` / `ctx.query` | `Record<string, string>` | 路由参数 / URL query（顶层注入） |
-| `ctx.route.path` | `string` | 当前路由路径 |
-| `ctx.route.params` | `Record<string, string>` | URL 参数 |
-| `ctx.route.query` | `Record<string, string>` | 查询参数 |
-| `ctx.app.navigate(path)` | `(string) => void` | 编程式导航 |
-
-| RouteDef | 签名 | 说明 |
-|---------|------|------|
-| `path` | `string` | 路径（`:id` 参数 / `*` 通配） |
-| `render(params)` | `(params) => VNode` | 页面（params 注入——`ctx.route.params` 同源） |
-| `layout(page)` | `(VNode) => VNode` | 嵌套布局（跨路由工厂不重跑——状态保持） |
-
-| UIHandler | 类型 | 说明 |
-|-----------|------|------|
-| 签名 | `(location, ctx) => Promise<VNode> \| VNode` | 页面 = 异步组件（`ctx.data.get` 三场景；async 组件无需包装） |
-| 返回值 | `VNode \| null` | 数据结构（落地由 createRouter 事件流渲染决定） |
-
----
-
-## api — HTTP 客户端中间件
-
-```tsx
-import { createRouter, h, api } from 'weifuwu/ui-dom'
-
-let ctx: any = {}
-const root = document.querySelector('#root')!
-ctx = api({ baseURL: '/api' })(ctx)
-createRouter([], root, { ctx })
-
-// 在组件中使用
-async function loadUsers(ctx: WfuiContext) {
-  const users = await ctx.api?.get<User[]>('/users')
-  const user = await ctx.api?.get<User>('/users/1')
-  const created = await ctx.api?.post<User>('/users', { name: 'Alice' })
-  await ctx.api?.put('/users/1', { name: 'Bob' })
-  await ctx.api?.patch('/users/1', { name: 'Bob' })
-  await ctx.api?.delete('/users/1')
-}
-```
-
-| 选项 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `baseURL` | `string` | `''` | API 基础路径 |
-| `headers` | `Record<string, string>` | `{ 'Content-Type': 'application/json' }` | 默认请求头 |
-| `onRequest` | `(req) => { url, init }` | — | 请求拦截器 |
-| `onResponse` | `(res) => Promise<T>` | — | 响应拦截器 |
-| `timeout` | `number` | `0`（无超时） | 请求超时（ms）|
-
-| ctx.api 方法 | 签名 | 说明 |
-|-------------|------|------|
-| `api.get(url, opts?)` | `<T>(string, ApiRequestOptions?) => Promise<T>` | GET |
-| `api.post(url, body?, opts?)` | `<T>(string, unknown?, ApiRequestOptions?) => Promise<T>` | POST |
-| `api.put(url, body?, opts?)` | `<T>(string, unknown?, ApiRequestOptions?) => Promise<T>` | PUT |
-| `api.patch(url, body?, opts?)` | `<T>(string, unknown?, ApiRequestOptions?) => Promise<T>` | PATCH |
-| `api.delete(url, opts?)` | `<T>(string, ApiRequestOptions?) => Promise<T>` | DELETE |
-
-```ts
-// 错误处理
-try {
-  await ctx.api!.get('/users')
-} catch (e) {
-  if (e instanceof ApiError) {
-    console.log(e.status, e.body)  // e.g. 404, 'Not Found'
-  }
-}
-```
-
-`ApiError`：`{ status: number, body: string }`，继承 `Error`。
-
-| ApiRequestOptions | 类型 | 说明 |
-|-------------------|------|------|
-| `headers` | `Record<string, string>` | 本次请求自定义请求头 |
-| `signal` | `AbortSignal` | 取消请求 |
-
----
-
-## auth — 认证中间件
-
-```tsx
-import { createRouter, h, auth } from 'weifuwu/ui-dom'
-
-let ctx: any = {}
-const root = document.querySelector('#root')!
-ctx = auth()(ctx)
-createRouter([], root, { ctx })
-
-// 在组件中
-async function Profile(_props: {}, ctx: WfuiContext) {
-  return async (props) => {
-    if (!ctx.auth?.isLoggedIn) return <p>请登录</p>
-    return <p>欢迎, {ctx.auth?.user?.name}</p>
-  }
-}
-
-// 登录
-ctx.auth?.login(token, { id: 1, name: 'Alice' }, refreshToken)
-
-// 登出
-ctx.auth?.logout()
-
-// 更新用户信息
-ctx.auth?.setUser({ id: 1, name: 'Bob' })
-
-// 刷新 token
-await ctx.auth?.refresh()  // → boolean
-```
-
-| 选项 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `storage` | `Storage` | `localStorage` | 存储方式 |
-| `tokenKey` | `string` | `'weifuwu_token'` | Token 存储 key |
-| `userKey` | `string` | `'weifuwu_user'` | 用户信息存储 key |
-| `refreshTokenKey` | `string` | `'weifuwu_refresh'` | Refresh token 存储 key |
-| `refreshEndpoint` | `string` | `'/api/auth/refresh'` | 刷新端点 |
-
-| ctx.auth | 类型 | 说明 |
-|----------|------|------|
-| `.token` | `string \| null` | JWT token |
-| `.user` | `any` | 用户对象 |
-| `.isLoggedIn` | `boolean` | 是否已登录（基于 token 存在） |
-| `.login(token, user, refreshToken?)` | `void` | 登录 |
-| `.logout()` | `void` | 登出（清除存储） |
-| `.setUser(user)` | `void` | 更新用户信息 |
-| `.refresh()` | `Promise<boolean>` | 刷新 token（自动检测过期） |
-
-启动时自动检测 token 是否过期（JWT `exp` 提前 30 秒），过期则自动调用 `refresh()`。
-
----
-
-## ws — WebSocket 客户端中间件
-
-```tsx
-import { createRouter, h, ws } from 'weifuwu/ui-dom'
-
-let ctx: any = {}
-const root = document.querySelector('#root')!
-ctx = ws({ url: '/ws' })(ctx)
-createRouter([], root, { ctx })
-
-// 发送消息
-ctx.ws?.send({ type: 'chat', body: 'hello' })
-
-// 接收消息 — 返回 unsubscribe 函数
-const unsubscribe = ctx.ws?.onMessage((msg) => {
-  console.log('收到:', msg)
-})
-
-// 清理
-unsubscribe?.()
-```
-
-| 选项 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `url` | `string` | `'/ws'` | WebSocket 连接地址 |
-| `reconnectInterval` | `number` | `3000` | 重连间隔（ms） |
-| `maxReconnect` | `number` | `10` | 最大重连次数 |
-| `pingInterval` | `number` | `30000` | 心跳发送间隔 |
-| `pingTimeout` | `number` | `10000` | 心跳超时断开 |
-
-| ctx.ws | 类型 | 说明 |
-|--------|------|------|
-| `.send(msg)` | `(unknown) => void` | 发送 JSON 消息 |
-| `.onMessage(fn)` | `(fn) => () => void` | 订阅消息，返回 unsubscribe |
-| `.isConnected` | `boolean` | 连接状态 |
-| `.close()` | `() => void` | 断开连接 |
-
-自动重连（指数退避）、心跳保活、JSON 序列化/反序列化。
-
----
-
-## i18n — 国际化中间件
-
-```tsx
-import { createRouter, h, i18n } from 'weifuwu/ui-dom'
-
-let ctx: any = {}
-const root = document.querySelector('#root')!
-app.use(i18n({
-    locale: 'zh-CN',
-    messages: {
-      'title': '仪表盘',
-      'welcome': '欢迎光临',
-    },
-  }))
-  .mount('#root', App)
-
-// 组件中使用
-<h1>{ctx.i18n?.t('title')}</h1>
-<p>{ctx.i18n?.t('welcome')}</p>
-
-// 运行时切换语言
-ctx.i18n?.setLocale('en-US')
-// → 自动触发根组件重渲染（所有组件使用新语言文案）
-```
-
-| I18nOptions | 类型 | 默认值 | 说明 |
-|-------------|------|--------|------|
-| `locale` | `string` | `'zh-CN'` | 初始语言 |
-| `messages` | `Record<string, string>` | `{}` | 翻译键值对 |
-| `components` | `Record<string, Record<string, string>>` | `{}` | 组件文案覆盖 |
-
-| ctx.i18n | 类型 | 说明 |
-|----------|------|------|
-| `.t(key, fallback?)` | `(string, string?) => string` | 翻译 |
-| `.locale` | `string` | 当前语言 |
-| `.setLocale(lang)` | `(string) => void` | 切换语言（触发重渲染） |
-| `.components` | `Record<string, Record<string, string>>` | 组件文案映射 |
-
-内置语言包：
-
-```ts
-import { zhCN, enUS } from 'weifuwu/ui-dom'
-```
-
-- `zh-CN`：默认中文
-- `en-US`：英文
-
-组件文案（Button 的 `加载中...`、FileUpload 的 `点击或拖拽上传文件` 等）随语言自动切换。组件内部通过 `ctx.i18n?.components?.ComponentName.field` 读取。
-
-组件支持 `props.locale` 局部覆盖语言。
-
----
-
-## ErrorBoundary — 错误边界
-
-```tsx
-import { ErrorBoundary } from 'weifuwu/ui-dom'
-
-<ErrorBoundary fallback={<p>出错了，请刷新页面</p>}>
-  <UserProfile />
-</ErrorBoundary>
-
-// fallback 也可以是一个接收 error 的函数
-<ErrorBoundary fallback={({ error }) => (
-  <div>
-    <p>出错了: {String(error)}</p>
-    <button onClick={() => location.reload()}>重试</button>
-  </div>
-)}>
-  <UserProfile />
-</ErrorBoundary>
-```
-
-| ErrorBoundaryProps | 类型 | 默认值 | 说明 |
-|--------------------|------|--------|------|
-| `fallback` | `VNode \| ((props: { error }) => VNode) \| null` | `null` | 错误时渲染的内容 |
-| `children` | `any` | — | 子组件 |
-
-捕获子组件 render 时的错误 → 渲染 fallback。清除 `error` 即可重试。
-
----
-
-## confirm — 确认对话框
-
-两种用法，共享同一视觉与行为（基于 Modal 封装）：
-
-**① 命令式 `ctx.confirm()`（推荐，操作前询问）**
-
-```tsx
-import { createRouter, h } from 'weifuwu/ui-dom'
-import { confirm } from 'weifuwu/components'
-
-let ctx: any = {}
-const root = document.querySelector('#root')!
-ctx = confirm()(ctx)
-createRouter([], root, { ctx })
-
-// 任意代码中（组件事件、async 逻辑）
-async function handleDelete(ctx: WfuiContext) {
-  const ok = await ctx.confirm?.('确定删除这条记录？', {
-    title: '确认删除',
-    confirmText: '删除',
-    cancelText: '取消',
-    variant: 'danger',  // 'primary' | 'danger'
-  })
-  if (ok) {
-    // 执行删除...
-  }
-}
-```
-
-**② 声明式 `<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 默认 | 对话框宽度 |
-
-- `ctx.confirm()` 返回 `Promise<boolean>`，ESC / 点击遮罩 / 取消 → resolve(false)
-- 组件化渲染（Modal + portal），自动锁定滚动 + 焦点陷阱，i18n 文案可配置
-- 多次调用各自独立渲染（叠放语义），互不干扰
-
----
-
-## toast — 命令式消息提示
-
-`ctx.toast()` 是 `<Toast>` 组件的全局命令式封装：任意代码中一行调用，自动消失、自动清理，无需宿主状态。
-
-```tsx
-import { createRouter, h } from 'weifuwu/ui-dom'
-import { toast } from 'weifuwu/components'
-
-let ctx: any = {}
-const root = document.querySelector('#root')!
-ctx = toast({ position: 'top-right', duration: 3000, max: 3 })(ctx)
-createRouter([], root, { ctx })
-
-// 任意代码中（组件事件、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={...}/>` 共存：声明式用于局部列表（合并消息、自定义布局），命令式用于全局一次性反馈。
-
----
-
-## notification — 命令式通知
-
-`ctx.notification()` 是 `<Notification>` 组件的全局命令式封装：队列式通知（title + description + icon + 操作），自动消失、手动关闭、四角定位。
-
-```tsx
-import { v3Notification } from 'weifuwu/ui-dom'
-
-let ctx: any = {}
-ctx = v3Notification({ position: 'top-right', duration: 4500, max: 5 })(ctx)
-
-// 任意代码中（组件事件、api 拦截器、WS 回调、定时器）
-ctx.notification?.success({ title: '部署成功', description: 'v0.63.0 已上线' })
-ctx.notification?.warning({ title: '磁盘空间不足', description: '已使用 92%' })
-ctx.notification?.('普通通知')
-ctx.notification?.open({ type: 'error', title: '请求失败', duration: 8000, action: { label: '重试', onClick: retry } })
-```
-
-| NotificationOptions | 类型 | 默认值 | 说明 |
-|-------------|------|--------|------|
-| `position` | `NotificationPosition` | `'top-right'` | 容器位置（top-right/top-left/bottom-right/bottom-left） |
-| `duration` | `number` | `4500` | 默认自动消失时间（ms），0 = 不消失 |
-| `max` | `number` | `5` | 最大显示条数，超出移除最早 |
-
-单条可覆盖自动消失时间：`ctx.notification({ title: 'x', duration: 8000 })`。
-
----
-
-## ScrollLock / FocusTrap
-
-```tsx
-import { lockScroll, unlockScroll } from 'weifuwu/ui-dom'
-import { trapFocus } from 'weifuwu/ui-dom'
-
-// 锁定/解锁滚动（支持嵌套计数）
-lockScroll()
-unlockScroll()
-
-// 焦点陷阱 — 返回 cleanup 函数
-const cleanup = trapFocus(containerElement)
-cleanup()  // 恢复之前的焦点
-```
-
-| API | 说明 |
-|-----|------|
-| `lockScroll()` | 锁定 body 滚动（iOS 兼容） |
-| `unlockScroll()` | 解锁滚动，恢复滚动位置 |
-| `trapFocus(el)` | Tab/Shift+Tab 在容器内循环，返回 cleanup |
-
----
-
-## extendCtx — 上下文扩展
-
-```tsx
-import { extendCtx } from 'weifuwu/ui-dom'
-
-// 在 AppMiddleware 中创建新 ctx，原 ctx getter 通过原型链继承
-function myMw(ctx: WfuiContext): WfuiContext {
-  return extendCtx(ctx, { myField: 'value' })
-}
-```
-
-`extendCtx` 使用 `Object.create(ctx)` 保持原型链，再用 `Object.assign` 添加新字段。保证 getter 不被快照化。
-
----
-

package/content/guides/mobile-guide.md

@@ -1,105 +0,0 @@
-# 移动端开发指南
-
-> 从 docs/mobile.md 迁移（content/ 文档库——随 npm 包发布，与框架版本同步）。
-> 本页为叙述性指南——组件/能力逐项参考见 content/ 各域目录。
-
-# 移动端开发指南（weifuwu）
-
-> 移动端友好由框架构造保证：**用对原语 + 守 audit 规则**，不靠每个组件"记得"。
-> 落地依据：移动端支持计划（P0-P3 全落地——openPopup 全系 + safe-area + 44px 命中区 + docs/mobile 指南）。
-
-## 一、断点体系（布局原语）
-
-移动优先，640/768/1024 三个断点（与 `useBreakpoint` 的 mobile/tablet/desktop 对齐）：
-
-| 断点 | 类前缀 | 语义 |
-|------|--------|------|
-| ≥640px | `@sm` | 小屏以上 |
-| ≥768px | `@md` | 平板以上 |
-| ≥1024px | `@lg` | 桌面 |
-
-```html
-<div class="wf-stack wf-stack@md">…</div>   <!-- 移动纵向堆叠，md 起横向 -->
-<div class="wf-hidden@sm">…</div>           <!-- 移动端隐藏 -->
-```
-
-- 组件级移动适配用 `@media (max-width: 639px)`（bottom-sheet/全宽抽屉）或 `(max-width: 767px)`（双栏堆叠）
-- 触屏判定用 `@media (pointer: coarse)`（44px 命中区），**不要**用 width 猜触屏
-
-## 二、命中区纪律（44px，Apple HIG / WCAG 2.5.8）
-
-- **button/input/select 由全局 coarse 规则自动覆盖**（`_base.css`）
-- **非 button 交互元素**（div/label/span 带 onClick）必须进 coarse 44px 清单——style-audit 规则强制，新组件漏了测试红
-- **小组件**（圆点/星/勾选框）视觉尺寸不变，用 `::after` 扩展命中区（参考 Carousel dot）：
-
-```css
-@media (pointer: coarse) {
-  .wf-carousel-dot {
-    position: relative;
-  }
-  .wf-carousel-dot::after {
-    content: '';
-    position: absolute;
-    inset: -14px;
-  }
-}
-```
-
-- 小按钮（显式 `min-height` 覆盖了全局）需在组件 CSS 补 coarse 44px（参考 Pagination/Transfer/Calendar nav）
-
-## 三、弹层（openPopup 命令式弹窗）
-
-**弹层组件必须用 `ctx.ui.openPopup`**——移动端友好由构造保证：
-
-```tsx
-let handle: PopupHandle | null = null
-if (open && !handle)
-  handle = ctx.ui.openPopup({
-    anchor: () => anchorEl,   // **anchor 必传**（触发区是锚点——否则被当外部点击关闭）
-    content: () => h('div', { class: 'wf-popover' }, props.content),
-    onClose: () => { handle = null; open = false; ctx.ui.render() },
-  })
-else if (!open && handle) { handle.close(); handle = null }
-else if (handle) handle.update(h('div', { class: 'wf-popover' }, props.content))
-```
-
-## 四、手势原语
-
-| 原语 | 用法 | 场景 |
-|------|------|------|
-| `ctx.ui.useLongPress({ onLongPress, duration })` | spread 到目标 | ContextMenu 触屏长按（已内置双通道） |
-| `ctx.ui.useVisualViewport()` | 返回 `{ height, offsetTop, keyboardOpen }` 响应式 | fixed 底部栏被键盘遮挡（AiChat `raiseOnKeyboard`） |
-| `ctx.ui.useBreakpoint()` / `useMedia()` | 断点回调 | JS 侧响应式 |
-| `ctx.ui.useHoverCapable()` | boolean | 自定义 hover/tap 双模式 |
-
-## 五、safe-area（刘海屏/Home 条）
-
-```html
-<div class="wf-safe-bottom">…</div>   <!-- padding-bottom: env(safe-area-inset-bottom) -->
-<div class="wf-safe-top">…</div>
-```
-
-底部抽屉/Modal bottom-sheet 已内置（P2）。
-
-## 六、防横向溢出（375px 验收基线）
-
-- 弹层宽度：openPopup 自动视口夹紧（`calc(100vw - 32px)`）；手动浮层加 `.wf-popup` 基类
-- 宽内容（表格/双栏）：容器 `overflow-x: auto`（Table/Resizable 已内置）
-- 网格：`minmax(min(100%, 420px), 1fr)`（防 minmax 固定值撑破窄屏）
-- 验收：375×667 视口 `document.documentElement.scrollWidth <= innerWidth`
-
-## 七、验证清单
-
-1. 375px 视口无横向溢出
-2. 交互元素 tap 可达（44px 命中区）
-3. hover 组件 tap 可开、点外部可关、Escape 可关
-4. ContextMenu 长按触发
-5. 键盘弹起不遮挡输入（fixed 底部栏）
-6. 桌面视口行为不变（hover 仍 hover）
-7. style-audit 18 规则全绿 + `npm test` ≤15s
-
-## 八、已知裁剪/例外（诚实声明）
-
-- Rate 星 / Tree 勾选 / Slider 手柄：视觉小标记，命中区依赖行级容器（不做元素级 44px，避免破坏视觉）
-- ⌘K 类快捷键在移动端无键盘语义（Command 需显式触发按钮）
-- `raiseOnKeyboard` 默认 false：内联 chat 靠原生聚焦滚动；全屏 chat 布局才抬升

package/content/guides/page-building.md

@@ -1,98 +0,0 @@
-# 页面组装方法论（从零搭一个页面）
-
-> 解决"我会组件、会原语，但打开编辑器不知道第一行写什么"。
-> 与 [布局选型](layout-choice.md) 配合：选型决定"用什么"，本页决定"怎么搭"。
-> 前提：先查 patterns（`content/patterns/*.md`）——有现成蓝本直接复制，
-> 本方法论用于"没有蓝本时从零搭"。
-
-## 1. 页面解剖学（页面 = 五层）
-
-```
-骨架层     页面的大形状：wf-app-shell（壳）/ wf-container（定宽）/ wf-stack（纵列）
-分区层     区域划分：header / content / footer / sider（用 row/stack 组合）
-内容层     组件就位：Table/Form/Card…（组件文档查 API）
-间距层     呼吸感：wf-gap-* / wf-p-*（间距工具）
-响应式层   多设备：wf-hidden@lg / 断点变体（布局降级）
-```
-
-## 2. 组装 5 步套路（固定流程，不是自由发挥）
-
-```
-① 定骨架：这个页面是"壳内页面"（有侧栏/顶栏 → app-shell 已存在）还是
-   "独立页面"（→ wf-container + wf-stack）？
-② 划分区：从上到下/从左到右画出区域（header 标题区 / 主体区 / 底部操作区）
-③ 填内容：每个区域放什么组件（标题 → PageHeader；列表 → Table；表单 → Form）
-④ 调间距：区域间 wf-gap-lg、卡片内 wf-gap-sm、标题下 wf-mb-*
-⑤ 响应式：窄屏时哪些隐藏（wf-hidden@lg）、哪些堆叠（grid 列数自适应）
-```
-
-## 3. 完整示例：从零搭"订单详情页"（逐步）
-
-### 第 1 步：定骨架（独立页面——container + stack）
-
-```tsx
-return (
-  <div class="wf-container wf-stack" style="--wf-max:960px;--wf-gap:16px;padding:24px 16px">
-    {/* 分区占位 */}
-  </div>
-)
-```
-
-### 第 2 步：划分区 + 第 3 步：填内容
-
-```tsx
-// ① 标题区：PageHeader（标题 + 状态 Tag + 操作按钮）
-<PageHeader title={`订单 ${id}`} sub="客户：张伟">
-  <Button variant="primary">导出</Button>
-</PageHeader>
-
-// ② 主体区：Descriptions（详情字段栅格）
-<Descriptions items={[{ label: '订单号', value: id }, { label: '金额', value: '¥3,200' }]} bordered />
-
-// ③ 历史区：Timeline（执行流）
-<Timeline items={[{ key: '1', title: '已支付', time: '08-12 09:15' }]} />
-```
-
-### 第 4 步：调间距（gap 阶梯）
-
-```tsx
-// 区域间 gap-lg（16px）已有（骨架 --wf-gap:16px）
-// 卡片内紧凑 gap-sm、标题下留白 wf-mb-sm
-<Card>
-  <div class="wf-text-bold wf-mb-sm">补充信息</div>
-  <div class="wf-stack wf-gap-xs">…</div>
-</Card>
-```
-
-### 第 5 步：响应式降级
-
-```tsx
-// 双栏 → 窄屏单栏（grid auto-fit）
-<div class="wf-grid" style="--wf-cols:repeat(auto-fit,minmax(min(100%,300px),1fr))">
-  <Card>补充信息</Card><Card>执行历史</Card>
-</div>
-```
-
-**完整成品**：`examples/patterns/DetailPage.tsx`（本示例的落地版——5 步的每一步都可在源码中对应）。
-
-## 4. 常见页面的搭法速查
-
-| 页面类型 | 骨架 | 分区 | 核心组件 |
-|---------|------|------|---------|
-| 列表页 | container+stack | 标题区/表格区/分页区 | PageHeader + SearchInput + Table + Pagination |
-| 详情页 | container+stack | 标题区/详情区/历史区 | PageHeader + Descriptions + Timeline |
-| 设置页 | container+stack | 标题区/分区 Tabs | PageHeader + Tabs + Form + Switch |
-| 表单页 | container+stack | 标题区/表单区/操作区 | PageHeader + Form + Field + Button |
-| 仪表盘 | container+stack | KPI 行/图表区/表格区 | StatCard + Chart + Table |
-
-（每种都有对应 patterns 蓝本——`content/patterns/*.md`）
-
-## 5. 纪律（搭页面时的红线）
-
-```
-□ 布局结构只用 wf-* 原语（不手写 CSS/内联 style 自定义）
-□ 内容元素用组件（不裸 div/span 手搓结构）
-□ 间距走 wf-gap-*/wf-p-*（不用魔数 px）
-□ 图标用 Icon 组件（禁 emoji 装饰）
-□ 先查 patterns——重复造轮子是最常见的浪费
-```