weifuwu 0.55.1 → 0.55.2

package/README.md

@@ -991,6 +991,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` |

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,19 +18,22 @@
 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';

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

@@ -30,7 +30,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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "weifuwu",
   "type": "module",
-  "version": "0.55.1",
+  "version": "0.55.2",
   "description": "AI SaaS framework — (req, ctx) => Response",
   "exports": {
     ".": {