weifuwu 0.55.2 → 0.56.0

package/dist/client/vnode.d.ts

@@ -7,7 +7,7 @@
  *   --jsxImportSource=weifuwu/client
  */
 import type { WfuiContext } from './types.ts';
-export type VNodeType = string | Component | typeof Fragment | typeof Portal;
+export type VNodeType = string | Component | AsyncComponent | typeof Fragment | typeof Portal;
 export interface VNode {
     type: VNodeType;
     props: Record<string, any>;
@@ -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 节点 */
@@ -35,6 +37,35 @@ export interface VNode {
  * P = props 类型（JSX 自动推断），C = 组件依赖的 ctx 注入（如 ApiInjected & RouteInjected）
  */
 export type Component<P = {}, C extends object = {}> = (initProps: P, ctx: WfuiContext & C) => ((props: P) => VNode | null) | null;
+/**
+ * 异步组件工厂（形态 C）：async (ctx) => (initProps, ctx) => (props) => VNode
+ *
+ * 工厂层（async，只执行一次并缓存）：
+ *   - 数据声明：const data = await ctx.data.get(key, fetcher)
+ *   - 代码分割：const { default: def } = await import('./view.tsx')
+ *   - 异步初始化：模块加载、共享资源
+ *
+ * 返回标准的 Component——mount/render 保持同步，异步只发生在工厂边界。
+ * 服务端遍历器与客户端渲染器都 await 工厂；更新路径（_render 缓存）不碰工厂。
+ *
+ * 必须用 asyncComponent() 包装以标记（渲染器据此区分调用约定）：
+ *   Component       → Comp(initProps, ctx)
+ *   AsyncComponent  → await Comp(ctx) → Component
+ */
+export type AsyncComponent<C extends object = {}, P = {}> = (ctx: WfuiContext & C) => Promise<Component<P, C>>;
+/**
+ * 包装异步组件工厂。
+ *
+ * ```tsx
+ * const UserProfile = asyncComponent(async (ctx) => {
+ *   const user = await ctx.data.get(`/api/user/${ctx.params.id}`)
+ *   return (initProps, ctx) => (props) => h('div', {}, user.name)
+ * })
+ * ```
+ */
+export declare function asyncComponent<C extends object = {}, P = {}>(factory: AsyncComponent<C, P>): AsyncComponent<C, P>;
+/** 判定一个组件类型是否为 async 工厂（asyncComponent 包装过） */
+export declare function isAsyncComponent(type: any): type is AsyncComponent;
 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

@@ -1,4 +1,8 @@
 // src/client/vnode.ts
+var ASYNC_MARK = "__wfAsyncComponent";
+function isAsyncComponent(type) {
+  return typeof type === "function" && type?.[ASYNC_MARK] === true;
+}
 var Fragment = /* @__PURE__ */ Symbol("Fragment");
 var Portal = /* @__PURE__ */ Symbol("Portal");
 function h(type, props, ...children) {
@@ -296,6 +300,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 +332,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
@@ -462,10 +471,11 @@ function renderValue(v, ctx) {
   }
   if (vnode.type === Fragment) {
     const frag = document.createDocumentFragment();
-    forEach(vnode.props?.children, (child) => {
+    const children = vnode.props?.children == null ? [] : Array.isArray(vnode.props.children) ? vnode.props.children : [vnode.props.children];
+    for (const child of children) {
       const node = renderValue(child, ctx);
       if (node != null) frag.appendChild(node);
-    });
+    }
     return frag;
   }
   if (typeof vnode.type === "function") {
@@ -508,6 +518,54 @@ function renderValue(v, ctx) {
   if (typeof vnode.props?.ref === "function") vnode.props.ref(el);
   return el;
 }
+var asyncFactoryCache = /* @__PURE__ */ new WeakMap();
+function startAsyncFactory(Comp, ctx) {
+  const existing = asyncFactoryCache.get(Comp);
+  if (existing) return existing;
+  const entry = { promise: null };
+  entry.promise = Promise.resolve().then(() => Comp(ctx)).then((def) => {
+    if (typeof def !== "function") {
+      throw new Error(
+        `asyncComponent factory <${Comp.name || "anonymous"}> must return a Component (initProps, ctx) => (props) => VNode.`
+      );
+    }
+    entry.resolved = def;
+    return def;
+  });
+  asyncFactoryCache.set(Comp, entry);
+  return entry;
+}
+function resolveAsyncFactorySync(Comp) {
+  return asyncFactoryCache.get(Comp)?.resolved;
+}
+function scheduleFullReRender(ctx) {
+  const ui = ctx.ui;
+  if (ui && typeof ui.render === "function") ui.render(["_wf_root"]);
+}
+function mountComponent(Comp, props, vnode, ctx) {
+  let def;
+  if (isAsyncComponent(Comp)) {
+    def = resolveAsyncFactorySync(Comp);
+    if (!def) {
+      void startAsyncFactory(Comp, ctx).promise.then(
+        () => scheduleFullReRender(ctx),
+        () => {
+        }
+      );
+      return null;
+    }
+  } else {
+    def = Comp;
+  }
+  let childVNode = def(props, ctx);
+  if (typeof childVNode !== "function") {
+    throw new Error(
+      `Component ${Comp.name || "anonymous"} must return a render function. Use (init_props, ctx) => (props) => VNode pattern.`
+    );
+  }
+  vnode._render = childVNode;
+  return childVNode(props);
+}
 function renderComponent(Comp, props, vnode, ctx) {
   ;
   ctx.ui = ctx.ui ?? {};
@@ -522,14 +580,7 @@ function renderComponent(Comp, props, vnode, ctx) {
   vnode._ctxVersion = childCtx.ui._ctxVersion ?? 0;
   let childVNode;
   try {
-    childVNode = Comp(props, childCtx);
-    if (typeof childVNode !== "function") {
-      throw new Error(
-        `Component ${Comp.name || "anonymous"} must return a render function. Use (init_props, ctx) => (props) => VNode pattern.`
-      );
-    }
-    vnode._render = childVNode;
-    childVNode = childVNode(props);
+    childVNode = mountComponent(Comp, props, vnode, childCtx);
   } catch (e) {
     const errHandler = ctx.ui?._errorHandler;
     if (errHandler) {
@@ -586,14 +637,6 @@ function renderPortal(vnode, ctx) {
     if (node != null) sub.appendChild(node);
   }
 }
-function forEach(children, fn) {
-  if (children == null) return;
-  if (Array.isArray(children)) {
-    children.forEach(fn);
-    return;
-  }
-  fn(children);
-}
 function flattenChildren(children) {
   if (children == null) return [];
   if (!Array.isArray(children)) return [children];
@@ -655,6 +698,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 +3022,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 +3125,11 @@ export {
   Tabs,
   Tag,
   Textarea,
+  ThemeSwitch,
   Toast,
   Tooltip,
+  applyTheme,
   confirm,
+  getTheme,
   toast
 };