@finesoft/front 0.1.37 → 0.1.39

package/README.md

@@ -50,6 +50,9 @@ $$
 -   `HttpClient`
 -   `LruMap`
 -   `buildUrl`
+-   `next` / `redirect` / `rewrite` / `deny`
+-   `createBrowserContext` / `createServerContext`
+-   `BeforeLoadGuard` / `AfterLoadGuard`
 
 ### Browser
 
@@ -275,6 +278,73 @@ export function bootstrap(framework: Framework): void {
 export { routes };
 ```
 
+### 3.1 可选：注册导航守卫
+
+框架提供两阶段守卫：
+
+-   `beforeLoad`：路由匹配后、数据加载前执行。适合认证、权限校验、提前重定向。
+-   `afterLoad`：数据加载后、渲染前执行。适合基于页面数据做 URL 规范化、二次校验。**这个阶段可以直接拿到 `ctx.page`。**
+
+既支持**全局守卫**，也支持**路由级守卫**。
+
+```ts
+import {
+	Framework,
+	defineRoutes,
+	next,
+	redirect,
+	rewrite,
+	type AfterLoadGuard,
+	type BeforeLoadGuard,
+	type RouteDefinition,
+} from "@finesoft/front";
+
+const requireLogin: BeforeLoadGuard = (ctx) => {
+	if (!ctx.getCookie("session")) {
+		return redirect("/login");
+	}
+	return next();
+};
+
+const canonicalizeProductUrl: AfterLoadGuard = (ctx) => {
+	const slug = ctx.page.title.toLowerCase().replace(/\s+/g, "-");
+	const expected = `/product/${slug}/${ctx.page.id}`;
+
+	return ctx.path === expected ? next() : rewrite(expected);
+};
+
+const routes: RouteDefinition[] = [
+	{
+		path: "/account",
+		intentId: "account-page",
+		controller: new AccountController(),
+		beforeLoad: [requireLogin],
+	},
+	{
+		path: "/product/:id",
+		intentId: "product-page",
+		controller: new ProductController(),
+		afterLoad: [canonicalizeProductUrl],
+	},
+];
+
+export function bootstrap(framework: Framework): void {
+	framework.beforeLoad((ctx) => {
+		console.log("global beforeLoad:", ctx.path);
+		return next();
+	});
+
+	framework.afterLoad((ctx) => {
+		console.log("global afterLoad page:", ctx.page.pageType);
+		return next();
+	});
+
+	defineRoutes(framework, routes);
+}
+```
+
+执行顺序为：**全局守卫 → 路由级守卫**。按注册顺序依次执行，遇到第一个非 `next()` 结果会立即短路。
+
 #### 为什么 `static` 模式建议导出 `routes`
 
 `staticAdapter()` 会在构建期读取你的路由定义，并自动预渲染无参数路由。

package/dist/app-XEMPAI6H.js

@@ -0,0 +1,10 @@
+import {
+  createSSRApp
+} from "./chunk-OYTIGVEG.js";
+import "./chunk-XQ3UWZOS.js";
+import "./chunk-SDPWQT2T.js";
+import "./chunk-PSPVIVC2.js";
+export {
+  createSSRApp
+};
+//# sourceMappingURL=app-XEMPAI6H.js.map

package/dist/browser.cjs

@@ -39,8 +39,11 @@ __export(browser_exports, {
   PrefetchedIntents: () => PrefetchedIntents,
   Router: () => Router,
   buildUrl: () => buildUrl,
+  createBrowserContext: () => createBrowserContext,
   createPrefetchedIntentsFromDom: () => createPrefetchedIntentsFromDom,
+  createServerContext: () => createServerContext,
   defineRoutes: () => defineRoutes,
+  deny: () => deny,
   deserializeServerData: () => deserializeServerData,
   generateUuid: () => generateUuid,
   getBaseUrl: () => getBaseUrl,
@@ -53,8 +56,10 @@ __export(browser_exports, {
   makeExternalUrlAction: () => makeExternalUrlAction,
   makeFlowAction: () => makeFlowAction,
   mapEach: () => mapEach,
+  next: () => next,
   pipe: () => pipe,
   pipeAsync: () => pipeAsync,
+  redirect: () => redirect,
   registerActionHandlers: () => registerActionHandlers,
   registerExternalUrlHandler: () => registerExternalUrlHandler,
   registerFlowActionHandler: () => registerFlowActionHandler,
@@ -62,6 +67,9 @@ __export(browser_exports, {
   removeQueryParams: () => removeQueryParams,
   removeScheme: () => removeScheme,
   resetFilterCache: () => resetFilterCache,
+  rewrite: () => rewrite,
+  runAfterLoadGuards: () => runAfterLoadGuards,
+  runBeforeLoadGuards: () => runBeforeLoadGuards,
   shouldLog: () => shouldLog,
   stableStringify: () => stableStringify,
   startBrowserApp: () => startBrowserApp,
@@ -379,7 +387,8 @@ function makeDependencies(container, options = {}) {
 var Router = class {
   routes = [];
   /** 添加路由规则 */
-  add(pattern, intentId, renderMode) {
+  add(pattern, intentId, renderModeOrOptions) {
+    const opts = typeof renderModeOrOptions === "string" ? { renderMode: renderModeOrOptions } : renderModeOrOptions ?? {};
     const paramNames = [];
     const regexStr = pattern.split(/(\/:[\w]+\??)/).map((segment) => {
       const paramMatch = segment.match(/^\/:(\w+)(\?)?$/);
@@ -394,7 +403,9 @@ var Router = class {
       intentId,
       regex: new RegExp(`^${regexStr}/?$`),
       paramNames,
-      renderMode
+      renderMode: opts.renderMode,
+      beforeGuards: opts.beforeGuards,
+      afterGuards: opts.afterGuards
     });
     return this;
   }
@@ -416,7 +427,9 @@ var Router = class {
         return {
           intent: { id: route.intentId, params },
           action: makeFlowAction(urlOrPath),
-          renderMode: route.renderMode
+          renderMode: route.renderMode,
+          beforeGuards: route.beforeGuards,
+          afterGuards: route.afterGuards
         };
       }
     }
@@ -483,6 +496,22 @@ var CompositeLogger = class {
   }
 };
 
+// ../core/src/middleware/pipeline.ts
+async function runBeforeLoadGuards(guards, ctx) {
+  for (const guard of guards) {
+    const result = await guard(ctx);
+    if (result.kind !== "next") return result;
+  }
+  return { kind: "next" };
+}
+async function runAfterLoadGuards(guards, ctx) {
+  for (const guard of guards) {
+    const result = await guard(ctx);
+    if (result.kind !== "next") return result;
+  }
+  return { kind: "next" };
+}
+
 // ../core/src/prefetched-intents/stable-stringify.ts
 function stableStringify(obj, _seen) {
   if (obj === null || obj === void 0) return String(obj);
@@ -551,6 +580,8 @@ var Framework = class _Framework {
   actionDispatcher;
   router;
   prefetchedIntents;
+  beforeGuards = [];
+  afterGuards = [];
   constructor(container, prefetchedIntents) {
     this.container = container;
     this.intentDispatcher = new IntentDispatcher();
@@ -614,6 +645,25 @@ var Framework = class _Framework {
   registerIntent(controller) {
     this.intentDispatcher.register(controller);
   }
+  // ===== Navigation Middleware =====
+  /** 注册 beforeLoad 守卫（路由匹配后、数据加载前） */
+  beforeLoad(guard) {
+    this.beforeGuards.push(guard);
+  }
+  /** 注册 afterLoad 守卫（数据加载后、渲染前） */
+  afterLoad(guard) {
+    this.afterGuards.push(guard);
+  }
+  /** 执行所有 beforeLoad 守卫（全局 → 路由级） */
+  runBeforeLoad(ctx, routeGuards) {
+    const guards = routeGuards?.length ? [...this.beforeGuards, ...routeGuards] : this.beforeGuards;
+    return runBeforeLoadGuards(guards, ctx);
+  }
+  /** 执行所有 afterLoad 守卫（全局 → 路由级） */
+  runAfterLoad(ctx, routeGuards) {
+    const guards = routeGuards?.length ? [...this.afterGuards, ...routeGuards] : this.afterGuards;
+    return runAfterLoadGuards(guards, ctx);
+  }
   /** 销毁 Framework 实例 */
   dispose() {
     this.container.dispose();
@@ -758,7 +808,11 @@ function defineRoutes(framework, definitions) {
       framework.registerIntent(def.controller);
       registeredIntents.add(def.intentId);
     }
-    framework.router.add(def.path, def.intentId, def.renderMode);
+    framework.router.add(def.path, def.intentId, {
+      renderMode: def.renderMode,
+      beforeGuards: def.beforeLoad,
+      afterGuards: def.afterLoad
+    });
   }
 }
 
@@ -852,6 +906,64 @@ function generateUuid() {
   });
 }
 
+// ../core/src/middleware/context.ts
+function parseCookieString(str) {
+  const map = /* @__PURE__ */ new Map();
+  if (!str) return map;
+  for (const pair of str.split(";")) {
+    const idx = pair.indexOf("=");
+    if (idx === -1) continue;
+    const key = pair.slice(0, idx).trim();
+    const val = pair.slice(idx + 1).trim();
+    if (key) map.set(key, val);
+  }
+  return map;
+}
+function createServerContext(options) {
+  const { url, intent, container, request } = options;
+  const parsed = new URL(url, "http://localhost");
+  const cookieHeader = request?.headers.get("cookie") ?? "";
+  const cookies = parseCookieString(cookieHeader);
+  return {
+    url,
+    path: parsed.pathname,
+    params: intent.params ?? {},
+    intent,
+    isServer: true,
+    container,
+    getCookie: (name) => cookies.get(name),
+    getHeader: (name) => request?.headers.get(name) ?? void 0
+  };
+}
+function createBrowserContext(options) {
+  const { url, intent, container } = options;
+  const parsed = new URL(url, window.location.origin);
+  return {
+    url,
+    path: parsed.pathname,
+    params: intent.params ?? {},
+    intent,
+    isServer: false,
+    container,
+    getCookie: (name) => parseCookieString(document.cookie).get(name),
+    getHeader: () => void 0
+  };
+}
+
+// ../core/src/middleware/types.ts
+function next() {
+  return { kind: "next" };
+}
+function redirect(url, status = 302) {
+  return { kind: "redirect", url, status };
+}
+function rewrite(url) {
+  return { kind: "rewrite", url };
+}
+function deny(status = 403, message = "Forbidden") {
+  return { kind: "deny", status, message };
+}
+
 // ../browser/src/action-handlers/external-url-action.ts
 function registerExternalUrlHandler(deps) {
   const { framework, log } = deps;
@@ -967,6 +1079,22 @@ var History = class {
       tryScroll(this.log, () => this.getScrollablePageElement(), scrollY);
     });
   }
+  /** 仅推入 URL，不缓存页面状态（用于页面加载失败场景） */
+  pushUrl(url) {
+    const id = generateUuid();
+    window.history.pushState({ id }, "", url);
+    this.currentStateId = id;
+    this.scrollTop = 0;
+    this.log.info("pushUrl (no state)", url, id);
+  }
+  /** 仅替换 URL，不缓存页面状态（用于页面加载失败场景） */
+  replaceUrl(url) {
+    const id = generateUuid();
+    window.history.replaceState({ id }, "", url);
+    this.currentStateId = id;
+    this.scrollTop = 0;
+    this.log.info("replaceUrl (no state)", url, id);
+  }
   updateState(update) {
     if (!this.currentStateId) {
       this.log.warn(
@@ -998,31 +1126,49 @@ function registerFlowActionHandler(deps) {
   const { framework, log, callbacks, updateApp } = deps;
   let isFirstPage = true;
   let navigationId = 0;
+  const MAX_REDIRECTS = 5;
   const defaultGetScrollable = () => document.getElementById("scrollable-page-override") || document.getElementById("scrollable-page") || document.documentElement;
   const history = new History(log, {
     getScrollablePageElement: deps.getScrollablePageElement ?? defaultGetScrollable
   });
-  framework.onAction(ACTION_KINDS.FLOW, async (action) => {
-    const flowAction = action;
-    const url = flowAction.url;
-    log.debug(`FlowAction \u2192 ${url}`);
-    if (flowAction.presentationContext === "modal") {
-      const match2 = framework.routeUrl(url);
-      if (match2) {
-        const page = await framework.dispatch(
-          match2.intent
-        );
-        callbacks.onModal(page);
-      }
+  async function navigateTo(url, redirectCount, thisNav) {
+    if (redirectCount >= MAX_REDIRECTS) {
+      log.error(
+        `Navigation redirect loop detected (${MAX_REDIRECTS} redirects), stopping at: ${url}`
+      );
       return;
     }
-    const thisNav = ++navigationId;
-    const shouldReplace = isFirstPage;
+    const shouldReplace = isFirstPage || url === window.location.pathname + window.location.search;
     const match = framework.routeUrl(url);
     if (!match) {
       log.warn(`FlowAction: no route for ${url}`);
       return;
     }
+    const navCtx = createBrowserContext({
+      url,
+      intent: match.intent,
+      container: framework.container
+    });
+    const beforeResult = await framework.runBeforeLoad(
+      navCtx,
+      match.beforeGuards
+    );
+    if (beforeResult.kind === "redirect") {
+      log.debug(`beforeLoad \u2192 redirect to ${beforeResult.url}`);
+      await navigateTo(beforeResult.url, redirectCount + 1, thisNav);
+      return;
+    }
+    if (beforeResult.kind === "deny") {
+      log.warn(
+        `beforeLoad \u2192 denied (${beforeResult.status}): ${beforeResult.message}`
+      );
+      return;
+    }
+    if (beforeResult.kind === "rewrite") {
+      log.debug(`beforeLoad \u2192 rewrite to ${beforeResult.url}`);
+      await navigateTo(beforeResult.url, redirectCount + 1, thisNav);
+      return;
+    }
     const pagePromise = framework.dispatch(
       match.intent
     );
@@ -1037,26 +1183,80 @@ function registerFlowActionHandler(deps) {
     }
     history.beforeTransition();
     updateApp({
-      page: pagePromise.then((page) => {
-        if (thisNav !== navigationId) {
-          log.info("FlowAction commit superseded", url);
+      page: pagePromise.then(
+        async (page) => {
+          if (thisNav !== navigationId) {
+            log.info("FlowAction commit superseded", url);
+            return page;
+          }
+          const postCtx = {
+            ...navCtx,
+            page
+          };
+          const afterResult = await framework.runAfterLoad(
+            postCtx,
+            match.afterGuards
+          );
+          if (afterResult.kind === "redirect") {
+            log.debug(`afterLoad \u2192 redirect to ${afterResult.url}`);
+            navigateTo(afterResult.url, redirectCount + 1, thisNav);
+            return page;
+          }
+          let canonicalURL = url;
+          if (afterResult.kind === "rewrite") {
+            canonicalURL = afterResult.url;
+            log.debug(`afterLoad \u2192 rewrite URL to ${canonicalURL}`);
+          }
+          if (afterResult.kind === "deny") {
+            log.warn(`afterLoad \u2192 denied (${afterResult.status})`);
+            return page;
+          }
+          if (shouldReplace) {
+            history.replaceState({ page }, canonicalURL);
+          } else {
+            history.pushState({ page }, canonicalURL);
+          }
+          callbacks.onNavigate(
+            new URL(canonicalURL, window.location.origin).pathname
+          );
+          didEnterPage(page);
           return page;
+        },
+        (error) => {
+          if (thisNav === navigationId) {
+            const canonicalURL = url;
+            if (shouldReplace) {
+              history.replaceUrl(canonicalURL);
+            } else {
+              history.pushUrl(canonicalURL);
+            }
+            callbacks.onNavigate(
+              new URL(canonicalURL, window.location.origin).pathname
+            );
+          }
+          throw error;
         }
-        const canonicalURL = url;
-        if (shouldReplace) {
-          history.replaceState({ page }, canonicalURL);
-        } else {
-          history.pushState({ page }, canonicalURL);
-        }
-        callbacks.onNavigate(
-          new URL(canonicalURL, window.location.origin).pathname
-        );
-        didEnterPage(page);
-        return page;
-      }),
+      ),
       isFirstPage
     });
     isFirstPage = false;
+  }
+  framework.onAction(ACTION_KINDS.FLOW, async (action) => {
+    const flowAction = action;
+    const url = flowAction.url;
+    log.debug(`FlowAction \u2192 ${url}`);
+    if (flowAction.presentationContext === "modal") {
+      const match = framework.routeUrl(url);
+      if (match) {
+        const page = await framework.dispatch(
+          match.intent
+        );
+        callbacks.onModal(page);
+      }
+      return;
+    }
+    const thisNav = ++navigationId;
+    await navigateTo(url, 0, thisNav);
   });
   history.onPopState(async (url, cachedState) => {
     log.debug(`popstate \u2192 ${url}, cached=${!!cachedState}`);
@@ -1081,6 +1281,30 @@ function registerFlowActionHandler(deps) {
       });
       return;
     }
+    const navCtx = createBrowserContext({
+      url: parsed.pathname + parsed.search,
+      intent: routeMatch.intent,
+      container: framework.container
+    });
+    const beforeResult = await framework.runBeforeLoad(
+      navCtx,
+      routeMatch.beforeGuards
+    );
+    if (beforeResult.kind === "redirect") {
+      log.debug(`popstate beforeLoad \u2192 redirect to ${beforeResult.url}`);
+      const thisNav = ++navigationId;
+      await navigateTo(beforeResult.url, 0, thisNav);
+      return;
+    }
+    if (beforeResult.kind === "deny" || beforeResult.kind === "rewrite") {
+      if (beforeResult.kind === "deny") {
+        log.warn(`popstate beforeLoad \u2192 denied`);
+      } else {
+        const thisNav = ++navigationId;
+        await navigateTo(beforeResult.url, 0, thisNav);
+      }
+      return;
+    }
     const pagePromise = framework.dispatch(
       routeMatch.intent
     );
@@ -1202,8 +1426,11 @@ async function startBrowserApp(config) {
   PrefetchedIntents,
   Router,
   buildUrl,
+  createBrowserContext,
   createPrefetchedIntentsFromDom,
+  createServerContext,
   defineRoutes,
+  deny,
   deserializeServerData,
   generateUuid,
   getBaseUrl,
@@ -1216,8 +1443,10 @@ async function startBrowserApp(config) {
   makeExternalUrlAction,
   makeFlowAction,
   mapEach,
+  next,
   pipe,
   pipeAsync,
+  redirect,
   registerActionHandlers,
   registerExternalUrlHandler,
   registerFlowActionHandler,
@@ -1225,6 +1454,9 @@ async function startBrowserApp(config) {
   removeQueryParams,
   removeScheme,
   resetFilterCache,
+  rewrite,
+  runAfterLoadGuards,
+  runBeforeLoadGuards,
   shouldLog,
   stableStringify,
   startBrowserApp,