weifuwu 0.36.2 → 0.38.0

package/README.md

@@ -22,7 +22,8 @@ npm install weifuwu
 | **redis** | `weifuwu` | Redis 客户端 → `ctx.redis` | `Router` |
 | **ui** | `weifuwu` | SSR 渲染 + 动态 JS/CSS 编译 → `ctx.ui` | `Router` |
 | **graphql** | `weifuwu` | GraphQL 端点 | `Router` |
-| **client** | `weifuwu/client` | 前端 VDOM + Proxy 框架 | — |
+| **client** | `weifuwu/client` | 前端 VDOM + Proxy 框架 + i18n + ErrorBoundary | — |
+| **components** | `weifuwu/components` | 36 个 HTML 原语组件（Button/Table/Modal/...） | `client` |
 | **layout** | `weifuwu/layout` | 纯 CSS 布局原语 + 主题 Token | — |
 
 ---
@@ -39,6 +40,7 @@ npm install weifuwu
          ctx.sql                              ctx.ws
          ctx.redis                            ctx.route
          ctx.ui                               ctx.api / ctx.auth
+                                             ctx.i18n
 ```
 
 ---
@@ -71,7 +73,7 @@ serve(app, { port: 3000 })
 
 ```tsx
 // src/main.tsx —— 前端
-import { createApp, router, RouteView } from 'weifuwu/client'
+import { createApp, router, RouteView, i18n } from 'weifuwu/client'
 import type { WfuiContext, RouteDef } from 'weifuwu/client'
 
 function Home(_props: {}, ctx: WfuiContext) {
@@ -497,9 +499,81 @@ import { ErrorBoundary } from 'weifuwu/client'
 |------|------|
 | `extendCtx(ctx, fields)` | 创建新 ctx，继承原 ctx 的 getter |
 
+### 国际化 — `ctx.i18n`
+
+`i18n()` 中间件注入 `ctx.i18n`，支持运行时语言切换：
+
+```ts
+import { createApp, i18n } from 'weifuwu/client'
+
+createApp()
+  .use(i18n({
+    locale: 'zh-CN',
+    messages: { 'users.title': '用户管理' },
+  }))
+  .mount('#root', () => <App />)
+
+// 页面中使用
+ctx.i18n?.t('users.title')      // → '用户管理'
+
+// 运行时切换
+ctx.i18n?.setLocale('en-US')    // → 自动触发重渲染
+```
+
+内置语言包：`zh-CN`（默认）、`en-US`。组件文案（Button 的 `加载中...`、FileUpload 的 `点击或拖拽上传文件`）随语言自动切换。组件通过 `ctx.i18n?.components?.ComponentName.field` 读取，支持 `props.locale` 局部覆盖。
+
+```ts
+import { i18n, zhCN, enUS } from 'weifuwu/client'
+```
+
+### confirm —— 确认对话框
+
+```ts
+import { createApp, confirm } from 'weifuwu/client'
+
+createApp()
+  .use(confirm())
+  .mount('#root', App)
+
+// 在组件中使用
+async function handleDelete(ctx: WfuiContext) {
+  const ok = await ctx.confirm?.('确定删除？', {
+    title: '确认',
+    confirmText: '删除',
+    cancelText: '取消',
+    variant: 'danger',  // 'default' | 'danger'
+  })
+  if (ok) { /* 执行 */ }
+}
+```
+
+- 直接 DOM 渲染（不依赖 VDOM）
+- 返回 `Promise<boolean>` — `await ctx.confirm(msg, opts?)`
+- 自动锁定背景滚动（ScrollLock）
+- ESC / 点击遮罩关闭
+
+### ScrollLock / FocusTrap 工具
+
+```ts
+import { lockScroll, unlockScroll } from 'weifuwu/client'
+import { trapFocus } from 'weifuwu/client'
+
+// 锁定/解锁滚动（支持嵌套计数）
+lockScroll()
+unlockScroll()
+
+// 焦点陷阱，返回 cleanup 函数
+const cleanup = trapFocus(containerEl)
+// 组件卸载时
+cleanup()  // 恢复焦点
+```
+
+- `lockScroll()`: 多层级可嵌套锁定，iOS Safari `position:fixed` 兼容
+- `trapFocus(el)`: Tab/Shift+Tab 在容器内循环，restore 之前焦点
+
 ### 前端类型
 
-`VNode`, `VNodeType`, `Component`, `WfuiContext`, `AppMiddleware`, `RouteDef`, `ApiClient`, `ApiOptions`, `ApiRequestOptions`, `ApiError`, `AuthClient`, `AuthOptions`, `ErrorBoundaryProps`
+`VNode`, `VNodeType`, `Component`, `WfuiContext`, `AppMiddleware`, `RouteDef`, `ApiClient`, `ApiOptions`, `ApiRequestOptions`, `ApiError`, `AuthClient`, `AuthOptions`, `ErrorBoundaryProps`, `I18nOptions`, `I18nState`, `LocalePackage`
 
 ---
 
@@ -614,6 +688,64 @@ document.documentElement.setAttribute('data-theme', 'dark')
 
 ---
 
+## 组件库 — `weifuwu/components`
+
+36 个 **HTML 原语**，覆盖 90% 的 SaaS 页面 HTML 需求。每个组件是 `(props, ctx) => VNode` 纯函数，引用 `weifuwu/layout` 的 CSS 变量做主题。
+
+```ts
+import { Button, Input, Table, Modal, Toast } from 'weifuwu/components'
+import 'weifuwu/components/style.css'
+```
+
+### 模块总览
+
+| 类别 | 组件 | 用途 |
+|------|------|------|
+| **表单核心** | `Button` `Input` `Textarea` `Select` | 4 个最常用的表单元素 |
+| **表单选择** | `Checkbox` `Switch` `RadioGroup` `Slider` | 选择类输入 |
+| **表单增强** | `Form` `Field` `FileUpload` `SearchInput` `ProgressBar` | 文件上传、搜索、进度 |
+| **数据展示** | `Table` `Card` `Badge` `Tag` `Avatar` `StatCard` `PageHeader` `Img` | 数据展示与页面标题 |
+| **数据反馈** | `Modal` `Drawer` `Tooltip` `Popover` `Toast` `Alert` `Loading` `EmptyState` `Skeleton` | 弹窗、抽屉、弹出层、骨架屏 |
+| **导航组件** | `Breadcrumb` `Tabs` `Dropdown` `Pagination` `Steps` `Accordion` | 面包屑、标签页、分页 |
+| **布局** | `Divider` | 分割线 (水平/垂直/带文字) |
+
+### 状态管理说明
+
+`ctx.ui.$` 是**组件级**状态——每个组件实例有独立的 Proxy（基于 `vnode._$`），同名变量不会冲突：
+
+```tsx
+// 组件 A
+const $ = ctx.ui.$
+$.open = true  // 只影响组件 A
+
+// 组件 B（在同一页面）
+const $ = ctx.ui.$
+$.open = false // 只影响组件 B，不影响 A
+```
+
+跨组件共享状态请使用 `ctx` 直接挂载属性（延续中间件模式）：
+
+```ts
+ctx.theme = 'dark'          // 所有组件可读
+ctx.toast?.success('成功')   // 如已注入 toast 中间件
+```
+
+### 页面模板 — `docs/pages/`
+
+| 模板 | 文件 | 用途 |
+|------|------|------|
+| **列表页** | `docs/pages/list-page.md` | 搜索 + 表格 + 分页 + 加载/空/错误状态 |
+| **表单页** | `docs/pages/form-page.md` | 表单 + 字段 + 校验 + 提交 |
+| **详情页** | `docs/pages/detail-page.md` | 信息展示 + Tabs + 操作 |
+| **设置页** | `docs/pages/settings-page.md` | 分组设置 + 独立保存 |
+| **仪表盘** | `docs/pages/dashboard-page.md` | KPI 卡片 + 图表 + 列表 |
+| **认证页** | `docs/pages/auth-page.md` | 居中卡片 + 表单 + 错误提示 |
+| **应用壳** | `docs/pages/app-layout.md` | 侧边栏 + 导航菜单 + 认证守卫 |
+
+每个模板标注了「改这里」——复制代码后改 API 路径、字段定义、操作按钮、导航项即可使用。
+
+---
+
 ## 环境变量
 
 | 变量 | 用途 | 默认值 |
@@ -654,6 +786,12 @@ src/
 │       ├── api.ts
 │       ├── auth.ts
 │       └── ws.ts
+├── components/            # 29 个 HTML 原语组件
+│   ├── index.ts
+│   ├── Button/            # Button.ts + .css + .test.ts
+│   ├── Input/
+│   ├── ...
+│   └── PageHeader/
 └── layout/                # 纯 CSS 布局 + 主题
     ├── weifuwu-layout.css
     ├── _tokens.css

package/dist/client/app.d.ts

@@ -5,15 +5,12 @@
  *
  * ctx.ui 在 mount 时注入：
  *   ctx.ui.render()    触发组件重渲染
- *   ctx.ui.$          持久化组件状态（由渲染器管理）
+ *   ctx.ui.$          组件级状态 Proxy（由 renderComponent 创建）
  *   ctx.ui.ready       首次执行标记（由渲染器管理）
  *
- * ctx.ui.$ 是深度 Proxy：
- *   $.x = val              → 自动渲染（顶层属性赋值）
- *   $.items.push(val)      → 自动渲染（数组突变方法）
- *   $.items[0].x = val     → 自动渲染（对象属性突变）
- *   $.items.push({x: 1})   → 新对象自动深度包装
- *   ctx.ui.dirty()         → 极少需要（仅当绕过 Proxy 直接操作底层对象）
+ * ctx.ui.$ 是组件级 Proxy（组件间隔离）：
+ *   $.x = val              → 设置当前组件状态，自动触发渲染
+ *   ctx.ui.dirty()         → 标记脏状态（仅深层突变时需要）
  */
 import type { WfuiContext, AppMiddleware } from './types.ts';
 import type { Component } from './vnode.ts';

package/dist/client/confirm.d.ts

@@ -0,0 +1,26 @@
+/**
+ * weifuwu/client — Confirm 对话框
+ *
+ * 使用：
+ *   import { createApp, confirm } from 'weifuwu/client'
+ *
+ *   createApp()
+ *     .use(confirm())
+ *     .mount('#root', () => <App />)
+ *
+ *   // 页面中使用
+ *   if (await ctx.confirm?.('确定删除？')) {
+ *     // 执行删除
+ *   }
+ */
+import type { AppMiddleware } from './types.ts';
+export interface ConfirmOptions {
+    title?: string;
+    confirmText?: string;
+    cancelText?: string;
+    variant?: 'primary' | 'danger';
+}
+export interface ConfirmState {
+    confirm: (message: string, options?: ConfirmOptions) => Promise<boolean>;
+}
+export declare function confirm(): AppMiddleware;

package/dist/client/focus-trap.d.ts

@@ -0,0 +1,4 @@
+/**
+ * weifuwu/client — FocusTrap
+ */
+export declare function trapFocus(container: HTMLElement): () => void;

package/dist/client/i18n.d.ts

@@ -0,0 +1,27 @@
+/**
+ * weifuwu i18n — 中间件
+ *
+ * 注入 ctx.i18n 支持运行时语言切换。
+ *
+ * 使用:
+ *   app.use(i18n({ locale: 'en', messages: { 'title': 'Dashboard' } }))
+ *   ctx.i18n?.t('title')        // → 'Dashboard'
+ *   ctx.i18n?.setLocale('zh-CN') // → 切换语言，自动重渲染
+ */
+import type { AppMiddleware } from './types.ts';
+export interface I18nOptions {
+    locale?: string;
+    messages?: Record<string, string>;
+    components?: Record<string, Record<string, string>>;
+}
+export interface LocalePackage {
+    messages?: Record<string, string>;
+    components?: Record<string, Record<string, string>>;
+}
+export interface I18nState {
+    locale: string;
+    t: (key: string, fallback?: string) => string;
+    setLocale: (lang: string) => void;
+    components: Record<string, Record<string, string>>;
+}
+export declare function i18n(opts?: I18nOptions): AppMiddleware;

package/dist/client/index.d.ts

@@ -29,3 +29,11 @@ export { extendCtx } from './types.ts';
 export type { WfuiContext, AppMiddleware, RouteDef } from './types.ts';
 export { ErrorBoundary } from './error-boundary.ts';
 export type { ErrorBoundaryProps } from './error-boundary.ts';
+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 { 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';