weifuwu 0.33.5 → 0.33.6

package/README.md

@@ -66,7 +66,8 @@ app.mount('#root', AppShell)
 ```
 
 ```js
-// build.mjs — 可选，也可用 ctx.ui.js() 服务端动态编译
+// build.mjs — 传统构建方式（可选）
+// 推荐：使用 ctx.ui.js() 服务端动态编译，无需独立构建脚本
 esbuild.build({
   entryPoints: ['src/main.tsx'],
   jsx: 'automatic',
@@ -75,9 +76,10 @@ esbuild.build({
 })
 ```
 
-或用服务端动态编译（无需独立构建脚本）：
+或用服务端动态编译——一行代码，无需构建步骤、无需 watch 模式：
 ```ts
 app.get('/static/app.js', async (req, ctx) => ctx.ui.js('./src/main.tsx'))
+app.get('/static/style.css', async (req, ctx) => ctx.ui.css('./src/style.css'))
 ```
 
 ### Environment Variables
@@ -151,6 +153,10 @@ app.get('/static/app.js', async (req, ctx) => ctx.ui.js('./src/main.tsx'))
 | `LoginForm` | Login/register form component |
 | `Chat` | Real-time messaging component |
 | `domMount()` | Direct DOM mounting |
+| `wrap()` | Third-party library integration |
+| `useForm()` | Form state management (validation, submit, reset) |
+| `createPortal()` | Render outside parent DOM hierarchy |
+| `<ErrorBoundary>` | Catch render errors, show fallback |
 
 ### Utilities
 
@@ -229,6 +235,29 @@ ctx.route.path     // "/chat/123"
 ctx.route.params   // { id: "123" }
 ctx.route.query    // { tab: "settings" }
 
+#### Route Loader — 数据预取
+
+```tsx
+const routes: RouteDef[] = [
+  {
+    path: '/post/:id',
+    component: PostPage,
+    loader: async (ctx) => ({
+      post: await ctx.api.get(`/api/posts/${ctx.route.params.id}`),
+    }),
+  },
+]
+
+// In component:
+function PostPage(_, ctx) {
+  const post = ctx.route.data.post
+  if (!post) return <p class="text-gray-400">加载中...</p>
+  return <h1 class="text-2xl font-bold">{post.title}</h1>
+}
+```
+
+组件先渲染（显示 loading），loader 完成后自动重渲染。
+
 ### Middleware: api / auth / ws
 
 ```tsx
@@ -330,6 +359,79 @@ const PieChart = wrap('div', (el, props: { data: any[] }, ctx) => {
 </Dashboard>
 ```
 
+### useForm() — 表单状态管理
+
+```tsx
+import { useForm } from 'weifuwu/client'
+
+const form = useForm({
+  initial: { email: '', password: '' },
+  validate: {
+    email: (v) => !v.includes('@') && '请输入有效邮箱',
+    password: (v) => v.length < 6 && '至少 6 位',
+  },
+})
+
+// 绑定到 input：{...form.field('name')} 自动设置 value + onInput
+<input {...form.field('email')} placeholder="邮箱" />
+{form.errors.email && <span class="text-red-500">{form.errors.email}</span>}
+
+// 提交时自动验证所有字段
+<button onClick={() => form.submit((data) => ctx.login(data.email, data.password))}>
+  登录
+</button>
+
+// 重置
+<button onClick={form.reset}>重置</button>
+
+// 编程设置
+form.setValue('email', 'a@b.com')
+form.setValues({ email: 'a@b.com', password: '123' })
+```
+
+### createPortal() — 渲染到父容器外
+
+适用于 Modal、Dropdown、Tooltip 等需突破 `overflow: hidden` 或 z-index 层级的情况。
+
+```tsx
+import { createPortal, Show } from 'weifuwu/client'
+
+function Modal({ show, title, children }) {
+  return <Show when={show}>
+    {createPortal(
+      <div class="fixed inset-0 bg-black/50 flex items-center justify-center">
+        <div class="bg-white rounded-xl p-6 min-w-[400px]">
+          <h2 class="text-lg font-bold mb-4">{title}</h2>
+          {children}
+        </div>
+      </div>,
+      document.body
+    )}
+  </Show>
+}
+```
+
+### ErrorBoundary — 错误边界
+
+子组件渲染异常时捕获，显示 fallback 而非白屏。children 必须是 thunk（延迟执行）。
+
+```tsx
+import { ErrorBoundary } from 'weifuwu/client'
+
+function AppShell(_, ctx) {
+  return (
+    <div>
+      <nav>...</nav>
+      <main>
+        <ErrorBoundary fallback={(e) => <p>出错了: {e.message}</p>}>
+          {() => <RouteView />}
+        </ErrorBoundary>
+      </main>
+    </div>
+  )
+}
+```
+
 ### Show / For
 
 ```tsx
@@ -858,12 +960,14 @@ src/
 ├── hub.ts               ← WebSocket hub
 ├── ui/                  ← ctx.ui.html / ctx.ui.js / ctx.ui.css
 ├── client/              ← Frontend framework
-│   ├── index.ts         ← Entry (exports signal, wrap, createApp, ...)
+│   ├── index.ts         ← Entry (exports signal, useForm, wrap, createApp, ...)
 │   ├── signal.ts        ← Signal / effect / computed
-│   ├── jsx-runtime.ts   ← JSX → DOM / Show / For / wrap / onMount
+│   ├── jsx-runtime.ts   ← JSX → DOM / Show / For / wrap / ErrorBoundary / createPortal
 │   ├── app.ts           ← createApp / hydrate / middleware chain
-│   ├── router.ts        ← Route matching / RouteView
+│   ├── router.ts        ← Route matching / RouteView / loader
 │   ├── types.ts         ← WfuiContext / RouteDef
+│   ├── lib/
+│   │   └── form.ts     ← useForm
 │   ├── middleware/
 │   │   ├── api.ts       ← HTTP client
 │   │   ├── auth.ts      ← Login / logout / token

package/dist/client/index.d.ts

@@ -15,7 +15,7 @@
  */
 export { signal, computed, effect, isSignal } from './signal.ts';
 export type { Signal } from './signal.ts';
-export { jsx, jsxs, jsxDEV, Fragment, Show, For, domMount, wrap } from './jsx-runtime.ts';
+export { jsx, jsxs, jsxDEV, Fragment, Show, For, domMount, wrap, createPortal, ErrorBoundary } from './jsx-runtime.ts';
 export type { Component } from './jsx-runtime.ts';
 export type { WfuiContext, AppMiddleware, RouteDef } from './types.ts';
 export { createApp } from './app.ts';
@@ -24,5 +24,6 @@ export { api, ApiClient, ApiError } from './middleware/api.ts';
 export { auth } from './middleware/auth.ts';
 export type { UserRecord } from './middleware/auth.ts';
 export { ws } from './middleware/ws.ts';
+export { useForm } from './lib/form.ts';
 export { LoginForm } from './components/LoginForm.ts';
 export { Chat } from './components/Chat.ts';

package/dist/client/index.js

@@ -184,6 +184,17 @@ function domMount(root, app) {
   container.innerHTML = "";
   container.appendChild(app);
 }
+function ErrorBoundary({ fallback, children }, _ctx) {
+  try {
+    return children();
+  } catch (e) {
+    return fallback(e);
+  }
+}
+function createPortal(node, target) {
+  target.appendChild(node);
+  return document.createDocumentFragment();
+}
 function toNode(v) {
   if (v instanceof Node) return v;
   if (typeof v === "function") return toNode(v());
@@ -232,7 +243,8 @@ function createApp() {
       params: {},
       query: Object.fromEntries(new URLSearchParams(window.location.search)),
       hash: window.location.hash,
-      component: null
+      component: null,
+      data: {}
     },
     app: {
       navigate(path) {
@@ -308,56 +320,79 @@ function router(opts) {
     }).join("/") + "$";
     return { re: new RegExp(reStr), keys, route };
   });
-  function matchPath(path) {
-    for (const { re, keys, route } of matchers) {
-      const m = path.match(re);
-      if (m) {
-        const params = {};
-        keys.forEach((k, i) => {
-          params[k] = decodeURIComponent(m[i + 1]);
-        });
-        return { component: route.component, params, title: route.title, auth: route.auth };
-      }
+  function matchRoute(path) {
+    for (const m of matchers) {
+      const result = path.match(m.re);
+      if (!result) continue;
+      const params = {};
+      m.keys.forEach((k, i) => {
+        params[k] = decodeURIComponent(result[i + 1]);
+      });
+      return {
+        matched: { component: m.route.component, params, title: m.route.title, auth: m.route.auth },
+        routeDef: m.route
+      };
     }
     return null;
   }
   return (ctx) => {
-    function handleRoute() {
-      const raw = mode === "hash" ? window.location.hash.slice(1) || "/" : window.location.pathname + window.location.search;
-      const [path, qs] = raw.split("?");
+    function emit(path) {
+      window.dispatchEvent(new CustomEvent("wefu:route", { detail: { path } }));
+    }
+    function resolve(path) {
+      const raw = mode === "hash" ? path || "/" : path;
+      const [cleanPath, qs] = raw.split("?");
       ctx.route.query = Object.fromEntries(new URLSearchParams(qs ?? ""));
-      const matched = matchPath(path);
-      if (matched) {
-        ctx.route.path = path;
-        ctx.route.params = matched.params;
-        ctx.route.component = matched.component;
-        ctx.route.title = matched.title;
-        ctx.route.auth = matched.auth;
-        if (matched.title) document.title = matched.title;
-        if (matched.auth && !ctx.user) {
-          setTimeout(() => ctx.app.navigate("/login"), 0);
-          return;
-        }
-      } else {
+      ctx.route.path = cleanPath;
+      const r = matchRoute(cleanPath);
+      if (!r) {
         ctx.route.component = opts.notFound ?? null;
+        ctx.route.data = {};
+        return { component: null };
+      }
+      ctx.route.params = r.matched.params;
+      ctx.route.component = r.matched.component;
+      ctx.route.title = r.matched.title;
+      ctx.route.auth = r.matched.auth;
+      if (r.matched.title) document.title = r.matched.title;
+      return { component: r.matched.component, routeDef: r.routeDef };
+    }
+    function navigateAndLoad(path) {
+      const { routeDef } = resolve(path);
+      if (ctx.route.auth && !ctx.user) {
+        setTimeout(() => ctx.app.navigate("/login"), 0);
+        return;
+      }
+      emit(ctx.route.path);
+      if (routeDef?.loader) {
+        routeDef.loader(ctx).then((data) => {
+          ctx.route.data = data;
+          emit(ctx.route.path);
+        }).catch(() => {
+          ctx.route.data = {};
+          emit(ctx.route.path);
+        });
       }
-      window.dispatchEvent(new CustomEvent("wefu:route", { detail: { path } }));
     }
-    const origNavigate = ctx.app.navigate;
     ctx.app.navigate = (path) => {
       if (mode === "hash") {
         window.location.hash = "#" + path;
       } else {
         window.history.pushState({}, "", path);
-        handleRoute();
+        navigateAndLoad(path);
       }
     };
     if (mode === "hash") {
-      window.addEventListener("hashchange", handleRoute);
+      window.addEventListener("hashchange", () => {
+        navigateAndLoad(window.location.hash.slice(1) || "/");
+      });
     } else {
-      window.addEventListener("popstate", handleRoute);
+      window.addEventListener("popstate", () => {
+        navigateAndLoad(window.location.pathname + window.location.search);
+      });
     }
-    handleRoute();
+    const initialPath = mode === "hash" ? window.location.hash.slice(1) || "/" : window.location.pathname + window.location.search;
+    navigateAndLoad(initialPath);
     return ctx;
   };
 }
@@ -583,6 +618,112 @@ function ws(opts = {}) {
   };
 }
 
+// src/client/lib/form.ts
+function useForm(opts) {
+  const fields = /* @__PURE__ */ new Map();
+  const errors = {};
+  const touched = {};
+  for (const key of Object.keys(opts.initial)) {
+    fields.set(key, signal(opts.initial[key]));
+    errors[key] = null;
+    touched[key] = false;
+  }
+  const valid = signal(true);
+  const values = signal({ ...opts.initial });
+  function snapshot() {
+    const data = {};
+    for (const [key, sig] of fields) {
+      data[key] = sig.value;
+    }
+    values.value = data;
+  }
+  function validateField(name) {
+    if (!opts.validate) return null;
+    const rule = opts.validate[name];
+    if (!rule) return null;
+    const sig = fields.get(name);
+    const result = rule(sig.value, values.value);
+    const error = result && typeof result === "string" ? result : null;
+    errors[name] = error;
+    return error;
+  }
+  function validateAll() {
+    if (!opts.validate) return true;
+    let allValid = true;
+    for (const key of Object.keys(opts.initial)) {
+      const err = validateField(key);
+      if (err) allValid = false;
+    }
+    valid.value = allValid;
+    return allValid;
+  }
+  return {
+    field(name) {
+      let sig = fields.get(name);
+      if (!sig) {
+        sig = signal(opts.initial[name]);
+        fields.set(name, sig);
+      }
+      return {
+        value: sig,
+        onInput(e) {
+          const target = e.target;
+          touched[name] = true;
+          if (target.type === "checkbox") {
+            sig.value = target.checked;
+          } else {
+            sig.value = target.value;
+          }
+          snapshot();
+          validateField(name);
+        }
+      };
+    },
+    get errors() {
+      return errors;
+    },
+    get touched() {
+      return touched;
+    },
+    valid,
+    get values() {
+      return values;
+    },
+    async submit(handler) {
+      if (!validateAll()) return;
+      const data = {};
+      for (const [key, sig] of fields) {
+        data[key] = sig.value;
+      }
+      await handler(data);
+    },
+    reset() {
+      for (const key of Object.keys(opts.initial)) {
+        const sig = fields.get(key);
+        if (sig) sig.value = opts.initial[key];
+        errors[key] = null;
+        touched[key] = false;
+      }
+      valid.value = true;
+      snapshot();
+    },
+    setValue(name, value) {
+      const sig = fields.get(name);
+      if (sig) sig.value = value;
+      snapshot();
+      validateField(name);
+    },
+    setValues(partial) {
+      for (const [key, value] of Object.entries(partial)) {
+        const sig = fields.get(key);
+        if (sig) sig.value = value;
+      }
+      snapshot();
+      validateAll();
+    }
+  };
+}
+
 // src/client/components/LoginForm.ts
 var h = (tag, props, ...children) => jsx(tag, props ?? {}, ...children);
 function LoginForm(_props, ctx) {
@@ -739,6 +880,7 @@ export {
   ApiClient,
   ApiError,
   Chat,
+  ErrorBoundary,
   For,
   Fragment,
   LoginForm,
@@ -748,6 +890,7 @@ export {
   auth,
   computed,
   createApp,
+  createPortal,
   domMount,
   effect,
   isSignal,
@@ -756,6 +899,7 @@ export {
   jsxs,
   router,
   signal,
+  useForm,
   wrap,
   ws
 };

package/dist/client/jsx-runtime.d.ts

@@ -13,8 +13,306 @@ import type { WfuiContext } from './types.ts';
 declare global {
     namespace JSX {
         interface IntrinsicElements {
-            [tag: string]: any;
+            div: HtmlDiv;
+            span: HtmlSpan;
+            p: HtmlP;
+            h1: HtmlH1;
+            h2: HtmlH2;
+            h3: HtmlH3;
+            h4: HtmlH4;
+            h5: HtmlH5;
+            h6: HtmlH6;
+            header: HtmlHeader;
+            footer: HtmlFooter;
+            nav: HtmlNav;
+            main: HtmlMain;
+            section: HtmlSection;
+            article: HtmlArticle;
+            aside: HtmlAside;
+            pre: HtmlPre;
+            blockquote: HtmlBlockquote;
+            figure: HtmlFigure;
+            address: HtmlAddress;
+            ul: HtmlUl;
+            ol: HtmlOl;
+            li: HtmlLi;
+            dl: HtmlDl;
+            dt: HtmlDt;
+            dd: HtmlDd;
+            table: HtmlTable;
+            thead: HtmlThead;
+            tbody: HtmlTbody;
+            tr: HtmlTr;
+            th: HtmlTh;
+            td: HtmlTd;
+            form: HtmlForm;
+            input: HtmlInput;
+            button: HtmlButton;
+            select: HtmlSelect;
+            option: HtmlOption;
+            textarea: HtmlTextarea;
+            label: HtmlLabel;
+            fieldset: HtmlFieldset;
+            legend: HtmlLegend;
+            img: HtmlImg;
+            video: HtmlVideo;
+            audio: HtmlAudio;
+            canvas: HtmlCanvas;
+            svg: HtmlSvg;
+            a: HtmlA;
+            link: HtmlLink;
+            strong: HtmlStrong;
+            em: HtmlEm;
+            b: HtmlB;
+            i: HtmlI;
+            u: HtmlU;
+            s: HtmlS;
+            mark: HtmlMark;
+            code: HtmlCode;
+            small: HtmlSmall;
+            sub: HtmlSub;
+            sup: HtmlSup;
+            abbr: HtmlAbbr;
+            time: HtmlTime;
+            br: HtmlBr;
+            hr: HtmlHr;
+            wbr: HtmlWbr;
+            style: HtmlStyle;
+            script: HtmlScript;
+            template: HtmlTemplate;
+            slot: HtmlSlot;
+            details: HtmlDetails;
+            summary: HtmlSummary;
+            dialog: HtmlDialog;
+            iframe: HtmlIframe;
         }
+        interface WfuiAttributes<T> {
+            class?: string | Signal<string>;
+            className?: string | Signal<string>;
+            id?: string;
+            style?: Record<string, string | undefined>;
+            title?: string;
+            lang?: string;
+            dir?: string;
+            hidden?: boolean | Signal<boolean>;
+            tabindex?: number;
+            accesskey?: string;
+            draggable?: boolean;
+            contenteditable?: boolean;
+            slot?: string;
+            spellcheck?: boolean;
+            ref?: (el: T) => void;
+            onClick?: (e: MouseEvent) => void;
+            onDblClick?: (e: MouseEvent) => void;
+            onMouseDown?: (e: MouseEvent) => void;
+            onMouseUp?: (e: MouseEvent) => void;
+            onMouseMove?: (e: MouseEvent) => void;
+            onMouseEnter?: (e: MouseEvent) => void;
+            onMouseLeave?: (e: MouseEvent) => void;
+            onKeyDown?: (e: KeyboardEvent) => void;
+            onKeyUp?: (e: KeyboardEvent) => void;
+            onKeyPress?: (e: KeyboardEvent) => void;
+            onFocus?: (e: FocusEvent) => void;
+            onBlur?: (e: FocusEvent) => void;
+            onInput?: (e: Event) => void;
+            onChange?: (e: Event) => void;
+            onSubmit?: (e: Event) => void;
+            onScroll?: (e: Event) => void;
+            onWheel?: (e: WheelEvent) => void;
+            onTouchStart?: (e: TouchEvent) => void;
+            onTouchEnd?: (e: TouchEvent) => void;
+            onTouchMove?: (e: TouchEvent) => void;
+            onLoad?: (e: Event) => void;
+            onError?: (e: Event) => void;
+            onAnimationEnd?: (e: AnimationEvent) => void;
+            onTransitionEnd?: (e: TransitionEvent) => void;
+            [data: string]: unknown;
+        }
+        type HtmlDiv = WfuiAttributes<HTMLDivElement>;
+        type HtmlSpan = WfuiAttributes<HTMLSpanElement>;
+        type HtmlP = WfuiAttributes<HTMLParagraphElement>;
+        type HtmlH1 = WfuiAttributes<HTMLHeadingElement>;
+        type HtmlH2 = WfuiAttributes<HTMLHeadingElement>;
+        type HtmlH3 = WfuiAttributes<HTMLHeadingElement>;
+        type HtmlH4 = WfuiAttributes<HTMLHeadingElement>;
+        type HtmlH5 = WfuiAttributes<HTMLHeadingElement>;
+        type HtmlH6 = WfuiAttributes<HTMLHeadingElement>;
+        type HtmlHeader = WfuiAttributes<HTMLElement>;
+        type HtmlFooter = WfuiAttributes<HTMLElement>;
+        type HtmlNav = WfuiAttributes<HTMLElement>;
+        type HtmlMain = WfuiAttributes<HTMLElement>;
+        type HtmlSection = WfuiAttributes<HTMLElement>;
+        type HtmlArticle = WfuiAttributes<HTMLElement>;
+        type HtmlAside = WfuiAttributes<HTMLElement>;
+        type HtmlPre = WfuiAttributes<HTMLPreElement>;
+        type HtmlBlockquote = WfuiAttributes<HTMLQuoteElement>;
+        type HtmlFigure = WfuiAttributes<HTMLElement>;
+        type HtmlAddress = WfuiAttributes<HTMLElement>;
+        type HtmlUl = WfuiAttributes<HTMLUListElement>;
+        type HtmlOl = WfuiAttributes<HTMLOListElement>;
+        type HtmlLi = WfuiAttributes<HTMLLIElement>;
+        type HtmlDl = WfuiAttributes<HTMLDListElement>;
+        type HtmlDt = WfuiAttributes<HTMLElement>;
+        type HtmlDd = WfuiAttributes<HTMLElement>;
+        type HtmlTable = WfuiAttributes<HTMLTableElement>;
+        type HtmlThead = WfuiAttributes<HTMLTableSectionElement>;
+        type HtmlTbody = WfuiAttributes<HTMLTableSectionElement>;
+        type HtmlTr = WfuiAttributes<HTMLTableRowElement>;
+        type HtmlTh = WfuiAttributes<HTMLTableCellElement>;
+        type HtmlTd = WfuiAttributes<HTMLTableCellElement>;
+        interface HtmlForm extends WfuiAttributes<HTMLFormElement> {
+            action?: string;
+            method?: string;
+            enctype?: string;
+            novalidate?: boolean;
+            target?: string;
+        }
+        interface HtmlInput extends WfuiAttributes<HTMLInputElement> {
+            type?: string;
+            value?: string | Signal<string>;
+            placeholder?: string;
+            checked?: boolean | Signal<boolean>;
+            disabled?: boolean | Signal<boolean>;
+            readonly?: boolean;
+            required?: boolean;
+            autofocus?: boolean;
+            autocomplete?: string;
+            name?: string;
+            min?: string | number;
+            max?: string | number;
+            step?: number;
+            pattern?: string;
+            accept?: string;
+            multiple?: boolean;
+            src?: string;
+            alt?: string;
+        }
+        interface HtmlButton extends WfuiAttributes<HTMLButtonElement> {
+            type?: 'button' | 'submit' | 'reset';
+            disabled?: boolean | Signal<boolean>;
+            name?: string;
+            value?: string;
+        }
+        interface HtmlSelect extends WfuiAttributes<HTMLSelectElement> {
+            value?: string | Signal<string>;
+            disabled?: boolean;
+            name?: string;
+            required?: boolean;
+            multiple?: boolean;
+        }
+        interface HtmlOption extends WfuiAttributes<HTMLOptionElement> {
+            value?: string;
+            selected?: boolean;
+            disabled?: boolean;
+            label?: string;
+        }
+        interface HtmlTextarea extends WfuiAttributes<HTMLTextAreaElement> {
+            value?: string | Signal<string>;
+            placeholder?: string;
+            disabled?: boolean;
+            readonly?: boolean;
+            required?: boolean;
+            rows?: number;
+            cols?: number;
+            autofocus?: boolean;
+            name?: string;
+        }
+        interface HtmlLabel extends WfuiAttributes<HTMLLabelElement> {
+            htmlFor?: string;
+        }
+        interface HtmlFieldset extends WfuiAttributes<HTMLFieldSetElement> {
+            disabled?: boolean;
+            name?: string;
+        }
+        type HtmlLegend = WfuiAttributes<HTMLLegendElement>;
+        interface HtmlA extends WfuiAttributes<HTMLAnchorElement> {
+            href?: string;
+            target?: string;
+            rel?: string;
+            download?: string;
+        }
+        interface HtmlImg extends WfuiAttributes<HTMLImageElement> {
+            src?: string | Signal<string>;
+            alt?: string;
+            width?: number | string;
+            height?: number | string;
+            loading?: 'lazy' | 'eager';
+            srcset?: string;
+            sizes?: string;
+        }
+        interface HtmlVideo extends WfuiAttributes<HTMLVideoElement> {
+            src?: string;
+            controls?: boolean;
+            autoplay?: boolean;
+            loop?: boolean;
+            muted?: boolean;
+            poster?: string;
+            width?: number | string;
+            height?: number | string;
+        }
+        interface HtmlAudio extends WfuiAttributes<HTMLAudioElement> {
+            src?: string;
+            controls?: boolean;
+            autoplay?: boolean;
+            loop?: boolean;
+            muted?: boolean;
+        }
+        type HtmlCanvas = WfuiAttributes<HTMLCanvasElement> & {
+            width?: number;
+            height?: number;
+        };
+        type HtmlSvg = WfuiAttributes<SVGSVGElement> & {
+            viewBox?: string;
+            xmlns?: string;
+            fill?: string;
+            width?: string | number;
+            height?: string | number;
+        };
+        interface HtmlLink extends WfuiAttributes<HTMLLinkElement> {
+            rel?: string;
+            href?: string;
+            type?: string;
+            media?: string;
+        }
+        interface HtmlStyle extends WfuiAttributes<HTMLStyleElement> {
+            scoped?: boolean;
+            media?: string;
+        }
+        interface HtmlScript extends WfuiAttributes<HTMLScriptElement> {
+            src?: string;
+            type?: string;
+            async?: boolean;
+            defer?: boolean;
+        }
+        type HtmlStrong = WfuiAttributes<HTMLElement>;
+        type HtmlEm = WfuiAttributes<HTMLElement>;
+        type HtmlB = WfuiAttributes<HTMLElement>;
+        type HtmlI = WfuiAttributes<HTMLElement>;
+        type HtmlU = WfuiAttributes<HTMLElement>;
+        type HtmlS = WfuiAttributes<HTMLElement>;
+        type HtmlMark = WfuiAttributes<HTMLElement>;
+        type HtmlCode = WfuiAttributes<HTMLElement>;
+        type HtmlSmall = WfuiAttributes<HTMLElement>;
+        type HtmlSub = WfuiAttributes<HTMLElement>;
+        type HtmlSup = WfuiAttributes<HTMLElement>;
+        type HtmlAbbr = WfuiAttributes<HTMLElement>;
+        type HtmlTime = WfuiAttributes<HTMLElement> & {
+            datetime?: string;
+        };
+        type HtmlBr = WfuiAttributes<HTMLBRElement>;
+        type HtmlHr = WfuiAttributes<HTMLHRElement>;
+        type HtmlWbr = WfuiAttributes<HTMLElement>;
+        type HtmlTemplate = WfuiAttributes<HTMLTemplateElement>;
+        type HtmlSlot = WfuiAttributes<HTMLSlotElement>;
+        type HtmlDetails = WfuiAttributes<HTMLDetailsElement>;
+        type HtmlSummary = WfuiAttributes<HTMLElement>;
+        type HtmlDialog = WfuiAttributes<HTMLDialogElement>;
+        type HtmlIframe = WfuiAttributes<HTMLIFrameElement> & {
+            src?: string;
+            name?: string;
+            width?: string;
+            height?: string;
+        };
     }
 }
 export declare function setCtx(ctx: WfuiContext | null): void;
@@ -58,6 +356,42 @@ export declare function Fragment(props: Record<string, unknown> | null, ...child
  * 直接挂载 DOM（低层 API，一般用 createApp().mount()）
  */
 export declare function domMount(root: string | Element, app: Node): void;
+/**
+ * ErrorBoundary — 捕获子组件渲染时的异常。
+ *
+ * children 必须是 thunk（函数），延迟执行以便捕获错误。
+ *
+ * ```tsx
+ * <ErrorBoundary fallback={(e) => <p>出错了: {e.message}</p>}>
+ *   {() => <Dashboard />}
+ * </ErrorBoundary>
+ * ```
+ */
+export declare function ErrorBoundary({ fallback, children }: {
+    fallback: (error: Error) => Node;
+    children: () => Node;
+}, _ctx: WfuiContext): Node;
+/**
+ * Portal — 将组件渲染到父容器之外的 DOM 位置。
+ *
+ * 适用于 Modal、Dropdown、Tooltip 等需要突破 overflow / z-index 的场景。
+ *
+ * ```tsx
+ * import { createPortal } from 'weifuwu/client'
+ *
+ * function Modal({ show, children }) {
+ *   return <Show when={show}>
+ *     {createPortal(
+ *       <div class="fixed inset-0 bg-black/50 flex items-center justify-center">
+ *         {children}
+ *       </div>,
+ *       document.body
+ *     )}
+ *   </Show>
+ * }
+ * ```
+ */
+export declare function createPortal(node: Node, target: Element): Node;
 /**
  * 条件渲染 — when 为 Signal 时响应式切换
  *

package/dist/client/jsx-runtime.js

@@ -184,6 +184,17 @@ function domMount(root, app) {
   container.innerHTML = "";
   container.appendChild(app);
 }
+function ErrorBoundary({ fallback, children }, _ctx) {
+  try {
+    return children();
+  } catch (e) {
+    return fallback(e);
+  }
+}
+function createPortal(node, target) {
+  target.appendChild(node);
+  return document.createDocumentFragment();
+}
 function toNode(v) {
   if (v instanceof Node) return v;
   if (typeof v === "function") return toNode(v());
@@ -232,7 +243,8 @@ function createApp() {
       params: {},
       query: Object.fromEntries(new URLSearchParams(window.location.search)),
       hash: window.location.hash,
-      component: null
+      component: null,
+      data: {}
     },
     app: {
       navigate(path) {
@@ -308,56 +320,79 @@ function router(opts) {
     }).join("/") + "$";
     return { re: new RegExp(reStr), keys, route };
   });
-  function matchPath(path) {
-    for (const { re, keys, route } of matchers) {
-      const m = path.match(re);
-      if (m) {
-        const params = {};
-        keys.forEach((k, i) => {
-          params[k] = decodeURIComponent(m[i + 1]);
-        });
-        return { component: route.component, params, title: route.title, auth: route.auth };
-      }
+  function matchRoute(path) {
+    for (const m of matchers) {
+      const result = path.match(m.re);
+      if (!result) continue;
+      const params = {};
+      m.keys.forEach((k, i) => {
+        params[k] = decodeURIComponent(result[i + 1]);
+      });
+      return {
+        matched: { component: m.route.component, params, title: m.route.title, auth: m.route.auth },
+        routeDef: m.route
+      };
     }
     return null;
   }
   return (ctx) => {
-    function handleRoute() {
-      const raw = mode === "hash" ? window.location.hash.slice(1) || "/" : window.location.pathname + window.location.search;
-      const [path, qs] = raw.split("?");
+    function emit(path) {
+      window.dispatchEvent(new CustomEvent("wefu:route", { detail: { path } }));
+    }
+    function resolve(path) {
+      const raw = mode === "hash" ? path || "/" : path;
+      const [cleanPath, qs] = raw.split("?");
       ctx.route.query = Object.fromEntries(new URLSearchParams(qs ?? ""));
-      const matched = matchPath(path);
-      if (matched) {
-        ctx.route.path = path;
-        ctx.route.params = matched.params;
-        ctx.route.component = matched.component;
-        ctx.route.title = matched.title;
-        ctx.route.auth = matched.auth;
-        if (matched.title) document.title = matched.title;
-        if (matched.auth && !ctx.user) {
-          setTimeout(() => ctx.app.navigate("/login"), 0);
-          return;
-        }
-      } else {
+      ctx.route.path = cleanPath;
+      const r = matchRoute(cleanPath);
+      if (!r) {
         ctx.route.component = opts.notFound ?? null;
+        ctx.route.data = {};
+        return { component: null };
+      }
+      ctx.route.params = r.matched.params;
+      ctx.route.component = r.matched.component;
+      ctx.route.title = r.matched.title;
+      ctx.route.auth = r.matched.auth;
+      if (r.matched.title) document.title = r.matched.title;
+      return { component: r.matched.component, routeDef: r.routeDef };
+    }
+    function navigateAndLoad(path) {
+      const { routeDef } = resolve(path);
+      if (ctx.route.auth && !ctx.user) {
+        setTimeout(() => ctx.app.navigate("/login"), 0);
+        return;
+      }
+      emit(ctx.route.path);
+      if (routeDef?.loader) {
+        routeDef.loader(ctx).then((data) => {
+          ctx.route.data = data;
+          emit(ctx.route.path);
+        }).catch(() => {
+          ctx.route.data = {};
+          emit(ctx.route.path);
+        });
       }
-      window.dispatchEvent(new CustomEvent("wefu:route", { detail: { path } }));
     }
-    const origNavigate = ctx.app.navigate;
     ctx.app.navigate = (path) => {
       if (mode === "hash") {
         window.location.hash = "#" + path;
       } else {
         window.history.pushState({}, "", path);
-        handleRoute();
+        navigateAndLoad(path);
       }
     };
     if (mode === "hash") {
-      window.addEventListener("hashchange", handleRoute);
+      window.addEventListener("hashchange", () => {
+        navigateAndLoad(window.location.hash.slice(1) || "/");
+      });
     } else {
-      window.addEventListener("popstate", handleRoute);
+      window.addEventListener("popstate", () => {
+        navigateAndLoad(window.location.pathname + window.location.search);
+      });
     }
-    handleRoute();
+    const initialPath = mode === "hash" ? window.location.hash.slice(1) || "/" : window.location.pathname + window.location.search;
+    navigateAndLoad(initialPath);
     return ctx;
   };
 }
@@ -583,6 +618,112 @@ function ws(opts = {}) {
   };
 }
 
+// src/client/lib/form.ts
+function useForm(opts) {
+  const fields = /* @__PURE__ */ new Map();
+  const errors = {};
+  const touched = {};
+  for (const key of Object.keys(opts.initial)) {
+    fields.set(key, signal(opts.initial[key]));
+    errors[key] = null;
+    touched[key] = false;
+  }
+  const valid = signal(true);
+  const values = signal({ ...opts.initial });
+  function snapshot() {
+    const data = {};
+    for (const [key, sig] of fields) {
+      data[key] = sig.value;
+    }
+    values.value = data;
+  }
+  function validateField(name) {
+    if (!opts.validate) return null;
+    const rule = opts.validate[name];
+    if (!rule) return null;
+    const sig = fields.get(name);
+    const result = rule(sig.value, values.value);
+    const error = result && typeof result === "string" ? result : null;
+    errors[name] = error;
+    return error;
+  }
+  function validateAll() {
+    if (!opts.validate) return true;
+    let allValid = true;
+    for (const key of Object.keys(opts.initial)) {
+      const err = validateField(key);
+      if (err) allValid = false;
+    }
+    valid.value = allValid;
+    return allValid;
+  }
+  return {
+    field(name) {
+      let sig = fields.get(name);
+      if (!sig) {
+        sig = signal(opts.initial[name]);
+        fields.set(name, sig);
+      }
+      return {
+        value: sig,
+        onInput(e) {
+          const target = e.target;
+          touched[name] = true;
+          if (target.type === "checkbox") {
+            sig.value = target.checked;
+          } else {
+            sig.value = target.value;
+          }
+          snapshot();
+          validateField(name);
+        }
+      };
+    },
+    get errors() {
+      return errors;
+    },
+    get touched() {
+      return touched;
+    },
+    valid,
+    get values() {
+      return values;
+    },
+    async submit(handler) {
+      if (!validateAll()) return;
+      const data = {};
+      for (const [key, sig] of fields) {
+        data[key] = sig.value;
+      }
+      await handler(data);
+    },
+    reset() {
+      for (const key of Object.keys(opts.initial)) {
+        const sig = fields.get(key);
+        if (sig) sig.value = opts.initial[key];
+        errors[key] = null;
+        touched[key] = false;
+      }
+      valid.value = true;
+      snapshot();
+    },
+    setValue(name, value) {
+      const sig = fields.get(name);
+      if (sig) sig.value = value;
+      snapshot();
+      validateField(name);
+    },
+    setValues(partial) {
+      for (const [key, value] of Object.entries(partial)) {
+        const sig = fields.get(key);
+        if (sig) sig.value = value;
+      }
+      snapshot();
+      validateAll();
+    }
+  };
+}
+
 // src/client/components/LoginForm.ts
 var h = (tag, props, ...children) => jsx(tag, props ?? {}, ...children);
 function LoginForm(_props, ctx) {
@@ -739,6 +880,7 @@ export {
   ApiClient,
   ApiError,
   Chat,
+  ErrorBoundary,
   For,
   Fragment,
   LoginForm,
@@ -748,6 +890,7 @@ export {
   auth,
   computed,
   createApp,
+  createPortal,
   domMount,
   effect,
   isSignal,
@@ -756,6 +899,7 @@ export {
   jsxs,
   router,
   signal,
+  useForm,
   wrap,
   ws
 };

package/dist/client/lib/form.d.ts

@@ -0,0 +1,54 @@
+/**
+ * useForm — 表单状态管理
+ *
+ * 自动绑定字段信号、验证、提交。
+ *
+ * ```tsx
+ * const form = useForm({
+ *   initial: { email: '', password: '' },
+ *   validate: {
+ *     email: (v) => !v.includes('@') && '请输入有效邮箱',
+ *   },
+ * })
+ *
+ * // 在 JSX 中
+ * <input {...form.field('email')} placeholder="邮箱" />
+ * {form.errors.email && <span class="text-red-500">{form.errors.email}</span>}
+ *
+ * <button onClick={() => form.submit((data) => ctx.login(data.email, data.password))}>
+ *   登录
+ * </button>
+ * ```
+ */
+import { type Signal } from '../signal.ts';
+export type ValidationRule<T> = {
+    [K in keyof T]?: (value: T[K], values: T) => string | false | undefined | null;
+};
+export interface UseFormOptions<T extends Record<string, unknown>> {
+    initial: T;
+    validate?: ValidationRule<T>;
+}
+export interface UseFormResult<T extends Record<string, unknown>> {
+    /** 绑定到 input 的属性：value + onInput */
+    field: (name: keyof T) => {
+        value: Signal<T[keyof T]>;
+        onInput: (e: Event) => void;
+    };
+    /** 字段错误信息（空字符串表示无错误） */
+    errors: Record<keyof T, string | null>;
+    /** 字段是否已 touched（用户操作过） */
+    touched: Record<keyof T, boolean>;
+    /** 整个表单是否有效 */
+    valid: Signal<boolean>;
+    /** 表单数据快照（只读） */
+    values: Signal<T>;
+    /** 提交 — 先验证，验证通过后调用 handler */
+    submit: (handler: (data: T) => void | Promise<void>) => Promise<void>;
+    /** 重置到初始值 */
+    reset: () => void;
+    /** 设置单个字段值 */
+    setValue: <K extends keyof T>(name: K, value: T[K]) => void;
+    /** 批量设置字段值 */
+    setValues: (partial: Partial<T>) => void;
+}
+export declare function useForm<T extends Record<string, unknown>>(opts: UseFormOptions<T>): UseFormResult<T>;

package/dist/client/router.d.ts

@@ -1,51 +1,18 @@
 /**
  * weifuwu/client router — 路由中间件 + RouteView 组件
- *
- * ```tsx
- * import { createApp, router, RouteView } from 'weifuwu/client'
- *
- * const app = createApp()
- * app.use(router({
- *   routes: [
- *     { path: '/', component: HomePage },
- *     { path: '/chat/:id', component: ChatPage },
- *   ],
- * }))
- *
- * function AppShell(_, ctx) {
- *   return <div><Header /><RouteView /></div>
- * }
- * app.mount('#root', AppShell)
- * ```
  */
 import type { WfuiContext, AppMiddleware, RouteDef } from './types.ts';
 import type { Component } from './jsx-runtime.ts';
 export interface RouterOptions {
-    /** 路由模式，默认 'hash' */
     mode?: 'hash' | 'history';
-    /** 路由表 */
     routes: RouteDef[];
-    /** 404 组件 */
     notFound?: Component;
 }
 /**
- * 路由中间件 — 注入 ctx.route.component + 改写 ctx.app.navigate
+ * 路由中间件 — 注入 ctx.route + 改写 ctx.app.navigate
  */
 export declare function router(opts: RouterOptions): AppMiddleware;
 /**
  * RouteView — 渲染当前路由匹配的组件
- *
- * 放在布局组件中，URL 变化时自动切换内容。
- *
- * ```tsx
- * function AppShell(_, ctx) {
- *   return (
- *     <div class="app">
- *       <Header user={ctx.user} />
- *       <main><RouteView /></main>
- *     </div>
- *   )
- * }
- * ```
  */
 export declare function RouteView(_props: {}, ctx: WfuiContext): Node;

package/dist/client/types.d.ts

@@ -24,6 +24,8 @@ export interface WfuiContext {
         component: Component | null;
         title?: string;
         auth?: boolean;
+        /** 路由 loader 返回的数据 */
+        data: Record<string, unknown>;
     };
     app: {
         navigate: (path: string) => void;
@@ -72,4 +74,6 @@ export interface RouteDef {
     component: Component;
     auth?: boolean;
     title?: string;
+    /** 页面加载器 — 切换路由时自动调用，结果注入 ctx.route.data */
+    loader?: (ctx: WfuiContext) => Promise<Record<string, unknown>>;
 }

package/dist/index.js

@@ -1457,7 +1457,16 @@ function ui() {
             headers: { "Content-Type": "text/css; charset=utf-8" }
           });
         }
-        const code = await readFile2(absPath, "utf-8");
+        let code = await readFile2(absPath, "utf-8");
+        try {
+          const postcss = await import("postcss");
+          const tw = await import("@tailwindcss/postcss");
+          const plugin = tw.default || tw;
+          const instance = typeof plugin === "function" ? plugin() : plugin;
+          const result = await postcss.default([instance]).process(code, { from: absPath });
+          code = result.css;
+        } catch {
+        }
         cssCache.set(absPath, { code, mtime: stat.mtimeMs });
         return new Response(code, {
           headers: { "Content-Type": "text/css; charset=utf-8" }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "weifuwu",
   "type": "module",
-  "version": "0.33.5",
+  "version": "0.33.6",
   "description": "AI SaaS framework — (req, ctx) => Response",
   "exports": {
     ".": {
@@ -32,10 +32,13 @@
   },
   "dependencies": {
     "@graphql-tools/schema": "^10",
+    "@tailwindcss/postcss": "^4.3.3",
     "ai": "^7.0.14",
     "graphql": "^16",
     "ioredis": "^5.11.0",
+    "postcss": "^8.5.19",
     "postgres": "^3.4.9",
+    "tailwindcss": "^4.3.3",
     "ws": "^8"
   },
   "devDependencies": {