weifuwu 0.55.1 → 0.55.3

package/README.md

@@ -17,7 +17,7 @@ npm install weifuwu
 
 ## 设计理念
 
-**零运行时依赖** — 前端无 npm 运行时依赖（自研 VDOM，不引入 Virtual DOM 库、rxjs、immer 等）。后端仅依赖 `graphql` + `ws`（语言/协议本身）——**数据库客户端（PostgreSQL/Redis 协议）、GraphQL schema 工具全部自研**。esbuild 编译 TSX 的结果即可直接运行。
+**零运行时依赖** — 前端无 npm 运行时依赖（自研 VDOM，不引入 Virtual DOM 库、rxjs、immer 等）。后端仅依赖 `esbuild`（TSX→JS 编译）+ `graphql` + `ws`（语言/协议本身）——**数据库客户端（PostgreSQL/Redis 协议）、GraphQL schema 工具全部自研**。esbuild 作为运行时依赖随 `npm install weifuwu` 自动安装，`ctx.ui.js()` 开箱即用。
 
 **两阶段组件模型** — 组件 = `(initProps, ctx) => (props) => VNode`。外层函数只执行一次（mount），内层函数每次状态/props 变化时执行（render）。无 class、无 `this`、无 Hook。
 
@@ -149,8 +149,8 @@ createApp()
 | 资源 | CDN 地址 | 说明 |
 |------|---------|------|
 | `weifuwu/client` | `https://unpkg.com/weifuwu@latest/dist/client/index.js` | 客户端核心（createApp, h, 路由, 状态管理等） |
-| `weifuwu/components` | `https://unpkg.com/weifuwu@latest/dist/components/index.js` | 41 个 UI 组件（Button, Card, Table, Modal 等） |
-| 组件样式 | `https://unpkg.com/weifuwu@latest/dist/components/style.css` | 组件 CSS + 82 个主题 Token + 35 个布局原语 |
+| `weifuwu/components` | `https://unpkg.com/weifuwu@latest/dist/components/index.js` | 43 个 UI 组件（Button, Card, Table, Modal 等） |
+| 组件样式 | `https://unpkg.com/weifuwu@latest/dist/components/style.css` | 组件 CSS + 91 个主题 Token + 35 个布局原语 |
 | 独立布局系统 | `https://unpkg.com/weifuwu@latest/dist/layout/weifuwu-layout.css` | 仅 CSS 布局，不依赖 JS |
 
 
@@ -169,8 +169,9 @@ createApp()
 | `weifuwu` | **ui** | SSR 渲染 + esbuild JS/CSS 动态编译 → `ctx.ui` | Router |
 | `weifuwu` | **graphql** | GraphQL 端点（支持 GraphiQL） | Router |
 | `weifuwu` | **createMiddleware** | 类型安全中间件工厂 | — |
-| `weifuwu` | **response** | HTTP 响应辅助函数（ok/badRequest/...） | — |
+| `weifuwu` | **ok / badRequest / …** | HTTP 响应辅助函数（ok/badRequest/... 等 12 个） | — |
 | `weifuwu` | **parseBody** | JSON 请求体安全解析 | — |
+| Router 方法 | **app.graphql()** | GraphQL 端点（支持 GraphiQL），Router 实例方法（无需单独 import） | Router |
 | `weifuwu/client` | **createApp** | 应用引导 + VDOM 渲染引擎 | — |
 | `weifuwu/client` | **router / RouteView** | 前端路由（history/hash 模式） | createApp |
 | `weifuwu/client` | **api / auth / ws** | HTTP 客户端 / 认证 / WebSocket 中间件 | createApp |
@@ -178,8 +179,8 @@ createApp()
 | `weifuwu/client` | **ErrorBoundary** | 错误边界组件 | createApp |
 | `weifuwu/client` | **lockScroll/trapFocus** | 滚动锁定 / 焦点陷阱工具 | — |
 | `weifuwu/client` | **popup** | 弹层 fixed 定位工具（`computeFixedPos` / `computeFixedPosRect`） | — |
-| `weifuwu/components` | **42 个组件** | Button/Table/Modal/Confirm/Toast/... + `confirm()` / `toast()` 命令式中间件 | weifuwu/client |
-| `weifuwu/layout` | **CSS 布局** | 35 个布局原语 + 82 个主题 Token（也支持 `weifuwu/layout/style.css`） | — |
+| `weifuwu/components` | **43 个组件** | Button/Table/Modal/Confirm/Toast/... + `confirm()` / `toast()` 命令式中间件 | weifuwu/client |
+| `weifuwu/layout` | **CSS 布局** | 35 个布局原语 + 91 个主题 Token（也支持 `weifuwu/layout/style.css`） | — |
 
 ---
 
@@ -991,6 +992,35 @@ const Badge: Component = () =>
   (props) => h('span', { class: `badge-${props.variant}` }, props.children)
 ```
 
+### 类型流（props 泛型 + ctx 注入）
+
+```tsx
+import type { Component } from 'weifuwu/client'
+import type { ApiInjected, RouteInjected } from 'weifuwu/client'
+
+// ① props 泛型：JSX 使用时自动类型检查（传错类型编译期报错）
+interface DeckCardProps { title: string; pages: number }
+const DeckCard: Component<DeckCardProps> = (_init, ctx) =>
+  (props) => <div>{props.title} / {props.pages} 页</div>
+// <DeckCard title="x" pages={8} />     ✓
+// <DeckCard title="x" pages="8" />     ✗ 编译期报错
+
+// ② ctx 注入声明：use(api()).use(router()) 后组件声明依赖，ctx 直接访问
+const Home: Component<{}, ApiInjected & RouteInjected> = (_init, ctx) => {
+  ctx.api.get('/users')   // ✓ 有类型
+  ctx.app.navigate('/x')  // ✓ 有类型
+  return () => <h1>Home</h1>
+}
+// 未声明的注入字段编译期报错——注入从"文档约定"变成"类型保证"
+
+createApp()
+  .use(api())                    // 注入 ctx.api
+  .use(router({ routes }))       // 注入 ctx.route / ctx.app
+  .mount('#root', Home)          // mount 时类型累积完整
+```
+
+> 各中间件的注入接口：`api()` → `ApiInjected`、`auth()` → `AuthInjected`、`ws()` → `WsInjected`、`i18n()` → `I18nInjected`、`router()` → `RouteInjected`（均可从 `weifuwu/client` 导入）。
+
 | 规则 | 说明 |
 |------|------|
 | 组件签名 | `(initProps: P, ctx: WfuiContext) => (props: P) => VNode \| null` |
@@ -1907,7 +1937,7 @@ import type { RouterOptions } from 'weifuwu/client'
 
 # 组件库 (`weifuwu/components`)
 
-42 个 HTML 原语组件。每个是 `(_init, ctx) => (props) => VNode`（两阶段组件，与前端框架同一模型），引用 `--wf-*` CSS 变量做主题。另含 `confirm()` / `toast()` 命令式中间件。
+43 个 HTML 原语组件。每个是 `(_init, ctx) => (props) => VNode`（两阶段组件，与前端框架同一模型），引用 `--wf-*` CSS 变量做主题。另含 `confirm()` / `toast()` 命令式中间件。
 
 ```ts
 import { Button, Input, Table, Modal, Toast } from 'weifuwu/components'
@@ -2123,11 +2153,17 @@ props 变化 ──────────────────────
 |-----|--------|-----------|------|
 | Divider | `Divider` | `orientation`, `plain` | 分割线（水平/垂直/带文字） |
 
+### 全局工具
+
+| 组件 | 导入名 | 关键 Props | 说明 |
+|-----|--------|-----------|------|
+| ThemeSwitch | `ThemeSwitch` | `mode: 'auto'\|'light'\|'dark'`, `onChange`, `storageKey` | 主题切换（auto/light/dark，localStorage 持久化）；另有 `applyTheme()` / `getTheme()` 命令式工具 |
+
 ---
 
 # 布局系统 (`weifuwu/layout`)
 
-纯 CSS 布局原语 + 82 个主题 Token。不绑定任何 JS 框架。
+纯 CSS 布局原语 + 91 个主题 Token。不绑定任何 JS 框架。
 
 > **全栈 weifuwu 项目**：`weifuwu/components/style.css` 已包含布局系统，一条 import 就够了，无需单独引用本页。
 > 本页仅适用于**非 weifuwu 项目**或**只需 CSS 布局**的场景。
@@ -2187,7 +2223,7 @@ app.get('/layout.css', (req, ctx) => ctx.ui.css('weifuwu/layout'))
 | | `wf-inline-block` | display: inline-block |
 | | `wf-contents` | display: contents |
 
-## 82 个主题 Token
+## 91 个主题 Token
 
 ```css
 /* 品牌色 */
@@ -2246,9 +2282,15 @@ app.get('/layout.css', (req, ctx) => ctx.ui.css('weifuwu/layout'))
 
 ### 暗色模式
 
+两种激活方式（显式 `data-theme` 优先级更高）：
+
 ```ts
-document.documentElement.setAttribute('data-theme', 'dark')
-// 所有 var(--wf-*) 自动切换
+// 1. 手动切换
+// document.documentElement.setAttribute('data-theme', 'dark')
+// document.documentElement.setAttribute('data-theme', 'light') // 强制亮色
+
+// 2. 自动：系统暗色偏好（无需任何代码）
+// 系统为暗色时自动生效；加 data-theme="light" 可强制亮色
 ```
 
 ---
@@ -2270,11 +2312,19 @@ document.documentElement.setAttribute('data-theme', 'dark')
 
 ## 暗色模式
 
+两种激活方式（显式 `data-theme` 优先级高于系统偏好）：
+
 ```ts
+// 手动切换
 document.documentElement.setAttribute('data-theme', 'dark')
+
+// 强制亮色（系统为暗色时也保持亮色）
+document.documentElement.setAttribute('data-theme', 'light')
 ```
 
-所有 `--wf-*` 变量在 `[data-theme="dark"]` 下自动切换。可自定义暗色变量：
+未设置 `data-theme` 时，自动跟随系统偏好：`@media (prefers-color-scheme: dark)` 下自动切换暗色。
+
+所有 `--wf-*` 变量在暗色下自动切换。可自定义暗色变量：
 
 ```css
 [data-theme="dark"] {
@@ -2282,6 +2332,15 @@ document.documentElement.setAttribute('data-theme', 'dark')
   --wf-color-text: #e0e0e0;
   --wf-color-border: #2a2a4a;
 }
+
+/* 自定义系统自动暗色的变量（需与上面同步） */
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) {
+    --wf-color-bg: #1a1a2e;
+    --wf-color-text: #e0e0e0;
+    --wf-color-border: #2a2a4a;
+  }
+}
 ```
 
 ## 组件级覆盖

package/dist/client/app.d.ts

@@ -14,11 +14,11 @@
  *   并设置 childCtx.ui._selfId = 组件 ID
  *   render() 无参时从 this._selfId 取当前组件 ID
  */
-import type { WfuiContext, AppMiddleware } from './types.ts';
+import type { AppMiddleware } from './types.ts';
 import type { Component } from './vnode.ts';
-export declare function createApp(): {
-    readonly ctx: WfuiContext;
-    use(mw: AppMiddleware): /*elided*/ any;
-    mount(rootSelector: string, RootComponent: Component): Promise<void>;
-    destroy(): void;
-};
+/** 应用句柄：use() 链式累积中间件注入的 ctx 类型，mount() 时组件拿到完整注入 */
+export interface App<C extends object = {}> {
+    use<I extends object, O extends object>(mw: AppMiddleware<I, O>): App<C & O>;
+    mount(rootSelector: string, root: Component<any, C>): Promise<void>;
+}
+export declare function createApp<C extends object = {}>(): App<C>;

package/dist/client/i18n.d.ts

@@ -24,4 +24,8 @@ export interface I18nState {
     setLocale: (lang: string) => void;
     components: Record<string, Record<string, string>>;
 }
-export declare function i18n(opts?: I18nOptions): AppMiddleware;
+/** i18n 中间件注入到 ctx 的字段 */
+export interface I18nInjected {
+    i18n: I18nState;
+}
+export declare function i18n(opts?: I18nOptions): AppMiddleware<{}, I18nInjected>;

package/dist/client/index.d.ts

@@ -18,22 +18,25 @@
 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 type { App } from './app.ts';
 export { router, RouteView } from './router.ts';
+export type { RouteInjected } from './router.ts';
 export { ws } from './middleware/ws.ts';
+export type { WsClient, WsInjected } from './middleware/ws.ts';
 export { api } from './middleware/api.ts';
 export { auth } from './middleware/auth.ts';
-export type { ApiClient, ApiOptions, ApiRequestOptions } from './middleware/api.ts';
+export type { ApiClient, ApiOptions, ApiRequestOptions, ApiInjected } from './middleware/api.ts';
 export { ApiError } from './middleware/api.ts';
-export type { AuthClient, AuthOptions } from './middleware/auth.ts';
+export type { AuthClient, AuthOptions, AuthInjected } from './middleware/auth.ts';
 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 type { I18nOptions, I18nState, I18nInjected } from './i18n.ts';
 export { lockScroll, unlockScroll } from './scroll-lock.ts';
 export { trapFocus } from './focus-trap.ts';
-export { computeFixedPos } from './popup.ts';
+export { computeFixedPos, computeFixedPosRect } from './popup.ts';
 export type { FixedPos, Placement } from './popup.ts';
 export { zhCN } from './locale/zh_CN.ts';
 export { enUS } from './locale/en_US.ts';

package/dist/client/index.js

@@ -596,6 +596,15 @@ function cleanupPortalChildren(vnode) {
 function callRefCleanup(input) {
   if (input == null || typeof input !== "object") return;
   const vnode = input;
+  if (vnode._id) {
+    if (vnode._customId) idRegistry.delete(vnode._customId);
+    idRegistry.delete(vnode._id);
+    vnode._id = void 0;
+    vnode._customId = void 0;
+    vnode._render = void 0;
+    vnode._parentNode = void 0;
+    vnode._refNode = void 0;
+  }
   if (vnode._child != null) {
     if (Array.isArray(vnode._child)) {
       for (const child of vnode._child) {
@@ -1010,7 +1019,13 @@ function router(opts) {
         title: last?.title ?? ""
       };
     }
-    return { path, params: {}, query: {}, chain: [], title: "" };
+    return {
+      path,
+      params: {},
+      query: Object.fromEntries(new URLSearchParams(window.location.search)),
+      chain: opts.notFound ? [{ component: opts.notFound, title: "Not Found" }] : [],
+      title: ""
+    };
   }
   return (ctx) => {
     const resolved = resolve(getPath());
@@ -1582,6 +1597,7 @@ export {
   api,
   auth,
   computeFixedPos,
+  computeFixedPosRect,
   createApp,
   createPortal,
   enUS,

package/dist/client/middleware/api.d.ts

@@ -61,7 +61,11 @@ export interface ApiRequestOptions {
  * await ctx.api.delete('/users/1')
  * ```
  */
-export declare function api(options?: ApiOptions): AppMiddleware;
+/** api 中间件注入到 ctx 的字段 */
+export interface ApiInjected {
+    api: ApiClient;
+}
+export declare function api(options?: ApiOptions): AppMiddleware<{}, ApiInjected>;
 /**
  * API 错误 — 包含 HTTP 状态码和响应文本。
  *

package/dist/client/middleware/auth.d.ts

@@ -21,4 +21,8 @@ export interface AuthClient {
     setUser: (user: any) => void;
     refresh: () => Promise<boolean>;
 }
-export declare function auth(options?: AuthOptions): AppMiddleware;
+/** auth 中间件注入到 ctx 的字段 */
+export interface AuthInjected {
+    auth: AuthClient;
+}
+export declare function auth(options?: AuthOptions): AppMiddleware<{}, AuthInjected>;

package/dist/client/middleware/ws.d.ts

@@ -12,4 +12,14 @@ export interface WsOptions {
     pingInterval?: number;
     pingTimeout?: number;
 }
-export declare function ws(options?: WsOptions): AppMiddleware;
+/** ws 中间件注入到 ctx 的字段 */
+/** ws 中间件注入的客户端形状（与 WfuiContext.ws 一致） */
+export interface WsClient {
+    send: (msg: unknown) => void;
+    onMessage: (fn: (data: unknown) => void) => () => void;
+    isConnected: boolean;
+}
+export interface WsInjected {
+    ws: WsClient;
+}
+export declare function ws(options?: WsOptions): AppMiddleware<{}, WsInjected>;

package/dist/client/router.d.ts

@@ -9,5 +9,18 @@ export interface RouterOptions {
     routes: RouteDef[];
     notFound?: (props: any, ctx: WfuiContext) => any;
 }
-export declare function router(opts: RouterOptions): AppMiddleware;
+/** router 中间件注入到 ctx 的字段 */
+export interface RouteInjected {
+    route: {
+        path: string;
+        params: Record<string, string>;
+        query: Record<string, string>;
+        title?: string;
+    };
+    /** 编程式导航 */
+    app: {
+        navigate: (path: string) => void;
+    };
+}
+export declare function router(opts: RouterOptions): AppMiddleware<{}, RouteInjected>;
 export declare function RouteView(_props: {}, ctx: WfuiContext): () => any;

package/dist/client/type-flow.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 类型流测试（编译期验证）——组件 props 泛型 + ctx 注入链式累积。
+ *
+ * 运行方式：这些断言是类型层面的，由 tsc --noEmit 保证。
+ * 运行时测试仅验证 createApp().use() 链式调用不抛错。
+ */
+export {};

package/dist/client/types.d.ts

@@ -81,7 +81,12 @@ export interface WfuiContext {
     };
 }
 /** 中间件签名 */
-export type AppMiddleware = (ctx: WfuiContext) => WfuiContext;
+/**
+ * 前端中间件：输入 ctx 需要 I，输出 ctx 注入 O（链式累积，createApp().use() 类型自动合并）
+ *   api()   → AppMiddleware<{}, ApiInjected>   注入 ctx.api
+ *   router()→ AppMiddleware<{}, RouteInjected> 注入 ctx.route / ctx.app
+ */
+export type AppMiddleware<I extends object = {}, O extends object = I> = (ctx: WfuiContext & I) => (WfuiContext & O) | Promise<WfuiContext & O>;
 /** 路由定义 */
 export interface RouteDef {
     path: string;

package/dist/client/vnode.d.ts

@@ -23,6 +23,8 @@ export interface VNode {
     _render?: (props: any) => VNode | null;
     /** 组件实例 ID（如 '_wf_0'） */
     _id?: string;
+    /** 自定义组件 ID（ctx.ui.selfId() 注册，跨组件精准刷新） */
+    _customId?: string;
     /** 组件输出的 DOM 父节点 */
     _parentNode?: Node;
     /** 组件输出的第一个 DOM 节点 */
@@ -30,7 +32,11 @@ export interface VNode {
     /** 组件 mount/render 时的 ctx 版本号（供三态 skip 判定） */
     _ctxVersion?: number;
 }
-export type Component<P = {}> = (initProps: P, ctx: WfuiContext) => ((props: P) => VNode | null) | null;
+/**
+ * 两阶段组件：外层 = mount（一次），内层 = render（每次 dirty/props 变化）。
+ * P = props 类型（JSX 自动推断），C = 组件依赖的 ctx 注入（如 ApiInjected & RouteInjected）
+ */
+export type Component<P = {}, C extends object = {}> = (initProps: P, ctx: WfuiContext & C) => ((props: P) => VNode | null) | null;
 export declare const Fragment: unique symbol;
 /** Portal — 将子 VNode 渲染到 document.body 下的独立容器 */
 export declare const Portal: unique symbol;

package/dist/components/Table/Table.d.ts

@@ -22,5 +22,7 @@ export interface TableProps {
     onSort?: (key: string, order: 'asc' | 'desc') => void;
     /** 数据为空时显示的文本 */
     emptyText?: string;
+    /** 表格最小宽度（窄屏横向滚动，如 '720px'） */
+    minWidth?: string;
 }
 export declare const Table: Component<TableProps>;

package/dist/components/ThemeSwitch/ThemeSwitch.d.ts

@@ -0,0 +1,27 @@
+/**
+ * weifuwu/components — ThemeSwitch 主题切换器
+ *
+ * 三段式切换：auto（跟随系统偏好）/ light（强制亮色）/ dark（强制暗色）。
+ * 对应 layout 的暗色双段激活机制：
+ *   - auto  → 移除 data-theme，由 @media (prefers-color-scheme) 决定
+ *   - light → <html data-theme="light">（系统暗色也强制亮色）
+ *   - dark  → <html data-theme="dark">
+ *
+ * mount 时读取 localStorage 并立即应用（避免闪白）；
+ * 用户选择后持久化。
+ */
+import type { Component } from '../../client/vnode.ts';
+export type ThemeMode = 'auto' | 'light' | 'dark';
+export interface ThemeSwitchProps {
+    /** 初始模式（默认从 localStorage 读取，无记录时为 auto） */
+    mode?: ThemeMode;
+    /** 切换回调 */
+    onChange?: (mode: ThemeMode) => void;
+    /** localStorage 存储 key */
+    storageKey?: string;
+}
+/** 应用主题：auto 移除属性，light/dark 显式设置 */
+export declare function applyTheme(mode: ThemeMode): void;
+/** 读取当前生效主题（localStorage 优先，其次系统偏好） */
+export declare function getTheme(): ThemeMode;
+export declare const ThemeSwitch: Component<ThemeSwitchProps>;

package/dist/components/index.d.ts

@@ -89,3 +89,6 @@ export { Chart } from './Chart/Chart.ts';
 export type { ChartProps, ChartType, DataPoint, ChartOptions } from './Chart/Chart.ts';
 export { Editor } from './Editor/Editor.ts';
 export type { EditorProps, ToolbarItem } from './Editor/Editor.ts';
+export { ThemeSwitch } from './ThemeSwitch/ThemeSwitch.ts';
+export type { ThemeSwitchProps, ThemeMode } from './ThemeSwitch/ThemeSwitch.ts';
+export { applyTheme, getTheme } from './ThemeSwitch/ThemeSwitch.ts';

package/dist/components/index.js

@@ -296,6 +296,7 @@ var Table = (_init, _ctx) => (props) => {
     return h("th", {
       class: `wf-table-th${col.sortable ? " wf-table-th--sortable" : ""}${isSorted ? " wf-table-th--sorted" : ""}`,
       scope: "col",
+      tabindex: col.sortable ? 0 : void 0,
       style: col.width ? { width: col.width } : void 0,
       onClick: col.sortable && onSort ? () => onSort(col.key, isSorted && isAsc ? "desc" : "asc") : void 0
     }, label);
@@ -327,7 +328,11 @@ var Table = (_init, _ctx) => (props) => {
     });
   }
   const tbody = h("tbody", { class: "wf-table-tbody" }, bodyRows);
-  return h("table", { class: "wf-table" }, [thead, tbody]);
+  const table = h("table", {
+    class: "wf-table",
+    style: props.minWidth ? { minWidth: props.minWidth } : void 0
+  }, [thead, tbody]);
+  return h("div", { class: "wf-table-wrap" }, table);
 };
 
 // src/client/scroll-lock.ts
@@ -655,6 +660,15 @@ function cleanupPortalChildren(vnode) {
 function callRefCleanup(input) {
   if (input == null || typeof input !== "object") return;
   const vnode = input;
+  if (vnode._id) {
+    if (vnode._customId) idRegistry.delete(vnode._customId);
+    idRegistry.delete(vnode._id);
+    vnode._id = void 0;
+    vnode._customId = void 0;
+    vnode._render = void 0;
+    vnode._parentNode = void 0;
+    vnode._refNode = void 0;
+  }
   if (vnode._child != null) {
     if (Array.isArray(vnode._child)) {
       for (const child of vnode._child) {
@@ -2970,6 +2984,68 @@ var Editor = (_props, ctx) => {
     ]);
   };
 };
+
+// src/components/ThemeSwitch/ThemeSwitch.ts
+var DEFAULT_KEY = "wf_theme";
+function readStored(key) {
+  try {
+    const v = localStorage.getItem(key);
+    return v === "light" || v === "dark" || v === "auto" ? v : null;
+  } catch {
+    return null;
+  }
+}
+function writeStored(key, mode) {
+  try {
+    localStorage.setItem(key, mode);
+  } catch {
+  }
+}
+function applyTheme(mode) {
+  if (typeof document === "undefined") return;
+  if (mode === "auto") document.documentElement.removeAttribute("data-theme");
+  else document.documentElement.setAttribute("data-theme", mode);
+}
+function getTheme() {
+  const stored = readStored(DEFAULT_KEY);
+  if (stored) return stored;
+  return "auto";
+}
+var ThemeSwitch = (initProps, ctx) => {
+  const storageKey = initProps.storageKey ?? DEFAULT_KEY;
+  let mode = initProps.mode ?? readStored(storageKey) ?? "auto";
+  applyTheme(mode);
+  return (props) => {
+    const SL = ctx?.i18n?.components?.ThemeSwitch ?? {};
+    const modes = [
+      { value: "auto", label: SL.auto ?? "\u81EA\u52A8" },
+      { value: "light", label: SL.light ?? "\u4EAE\u8272" },
+      { value: "dark", label: SL.dark ?? "\u6697\u8272" }
+    ];
+    const segments = modes.map(
+      (m) => h("button", {
+        type: "button",
+        class: `wf-theme-seg${mode === m.value ? " wf-theme-seg--active" : ""}`,
+        role: "radio",
+        "aria-checked": String(mode === m.value),
+        "aria-label": m.label,
+        onClick: () => {
+          if (mode === m.value) return;
+          mode = m.value;
+          applyTheme(mode);
+          writeStored(storageKey, mode);
+          props.onChange?.(mode);
+          ctx.ui.render();
+        }
+      }, m.label)
+    );
+    return h("div", {
+      class: "wf-theme-switch",
+      role: "radiogroup",
+      "aria-label": SL.label ?? "\u4E3B\u9898\u5207\u6362"
+    }, segments);
+  };
+};
 export {
   Accordion,
   Alert,
@@ -3011,8 +3087,11 @@ export {
   Tabs,
   Tag,
   Textarea,
+  ThemeSwitch,
   Toast,
   Tooltip,
+  applyTheme,
   confirm,
+  getTheme,
   toast
 };