@zenithbuild/router 0.7.3 → 0.7.5

package/index.d.ts

@@ -1,11 +1,26 @@
+export type RouteDownloadBody = string | Uint8Array | ArrayBuffer;
+
+export interface RouteDownloadOptions {
+    filename: string;
+    contentType?: string;
+}
+
 export type RouteResult =
     | { kind: "allow" }
     | { kind: "redirect"; location: string; status?: number }
     | { kind: "deny"; status: 401 | 403 | 404; message?: string }
-    | { kind: "data"; data: any };
+    | { kind: "data"; data: any }
+    | { kind: "invalid"; data: any; status: 400 | 422 }
+    | { kind: "json"; data: any; status?: number }
+    | { kind: "text"; body: string; status?: number }
+    | { kind: "download"; filename: string; contentType: string; status?: 200 };
 
 export type GuardResult = Extract<RouteResult, { kind: "allow" | "redirect" | "deny" }>;
 export type LoadResult = Extract<RouteResult, { kind: "data" | "redirect" | "deny" }>;
+export type RouteSession = Record<string, unknown>;
+export type RequireSessionOptions =
+    | { redirectTo: string; status?: 302 | 303 | 307 }
+    | { deny: 401 | 403 | 404; message?: string };
 
 export interface RouteContext {
     params: Record<string, string>;
@@ -17,17 +32,24 @@ export interface RouteContext {
     route: { id: string; pattern: string; file: string };
     env: Record<string, string>;
     auth: {
-        getSession(ctx: RouteContext): Promise<any>;
-        requireSession(ctx: RouteContext): Promise<void>;
+        getSession(): Promise<RouteSession | null>;
+        requireSession(options: RequireSessionOptions): Promise<RouteSession>;
+        signIn(sessionObject: RouteSession): Promise<void>;
+        signOut(): Promise<void>;
     };
     allow(): { kind: "allow" };
     redirect(location: string, status?: number): { kind: "redirect"; location: string; status: number };
     deny(status: 401 | 403 | 404, message?: string): { kind: "deny"; status: 401 | 403 | 404; message?: string };
     data(payload: any): { kind: "data"; data: any };
+    invalid(payload: any, status?: 400 | 422): { kind: "invalid"; data: any; status: 400 | 422 };
+    json(payload: any, status?: number): { kind: "json"; data: any; status: number };
+    text(body: string, status?: number): { kind: "text"; body: string; status: number };
+    download(body: RouteDownloadBody, options: RouteDownloadOptions): { kind: "download"; filename: string; contentType: string; status: 200 };
 }
 
 export declare function createRouter(config: { routes: any[]; container: HTMLElement }): { start: () => Promise<void>; destroy: () => void; };
 export declare function navigate(path: string): Promise<void>;
+export declare function refreshCurrentRoute(): Promise<void>;
 export declare function back(): void;
 export declare function forward(): void;
 export declare function getCurrentPath(): string;
@@ -41,7 +63,26 @@ export interface RouteProtectionPolicy {
     forbiddenPath?: string;
 }
 
-export type NavigationType = "push" | "pop";
+export type NavigationType = "push" | "pop" | "refresh";
+export type NavigationShellPhase = "idle" | "leaving" | "swapping" | "entering";
+
+export interface NavigationShellState {
+    phase: NavigationShellPhase;
+    navigationId: number | null;
+    navigationType: NavigationType | null;
+}
+
+export interface NavigationShellOptions {
+    timeoutMs?: number;
+    onStateChange?: (state: NavigationShellState, context: { previousState: NavigationShellState }) => void;
+}
+
+export interface NavigationShellController {
+    mount(): () => void;
+    destroy(): void;
+    getPhase(): NavigationShellPhase;
+    getState(): NavigationShellState;
+}
 
 export interface NavigationLifecyclePayload {
     navigationId: number;
@@ -95,3 +136,4 @@ export type RouteEventName =
 export declare function setRouteProtectionPolicy(policy: RouteProtectionPolicy): void;
 export declare function on(eventName: RouteEventName, handler: RouteEventHandler): void;
 export declare function off(eventName: RouteEventName, handler: RouteEventHandler): void;
+export declare function zenNavigationShell(ref: { current?: Element | null }, options?: NavigationShellOptions | null): NavigationShellController;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenithbuild/router",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "description": "File-based SPA router for Zenith framework with deterministic, compile-time route resolution",
   "license": "MIT",
   "type": "module",
@@ -9,9 +9,10 @@
     "dist",
     "template.js",
     "template-core.js",
+    "template-document.js",
+    "template-form.js",
     "template-lifecycle.js",
     "template-navigation.js",
-    "index.js",
     "index.d.ts",
     "README.md",
     "dist/**",

package/template-core.js

@@ -1,4 +1,4 @@
-export function renderRouterCoreSource({ manifest, runtimeSpec, coreSpec }) {
+export function renderRouterCoreSource({ manifest, runtimeSpec, coreSpec, routeCheck = false }) {
     return `import { hydrate as __zenithHydrate } from '${runtimeSpec}';
 import { zenOnMount as __zenithOnMount } from '${coreSpec}';
 
@@ -6,6 +6,7 @@ void __zenithHydrate;
 void __zenithOnMount;
 
 const __ZENITH_MANIFEST__ = ${manifest};
+const __ZENITH_ROUTE_CHECK_ENABLED__ = ${routeCheck ? 'true' : 'false'};
 const __ZENITH_BASE_PATH__ = normalizeBasePath(
   typeof __ZENITH_MANIFEST__.base_path === "string" ? __ZENITH_MANIFEST__.base_path : "/"
 );
@@ -436,6 +437,14 @@ function resolveScrollTarget(targetUrl, historyMode, popstateState) {
     const saved = readStoredScroll(popstateState);
     return { mode: "restore", x: saved.x, y: saved.y, focusTarget: null };
   }
+  if (historyMode === "refresh") {
+    return {
+      mode: "restore",
+      x: window.scrollX || window.pageXOffset || 0,
+      y: window.scrollY || window.pageYOffset || 0,
+      focusTarget: null
+    };
+  }
   return { mode: "top", x: 0, y: 0, focusTarget: null };
 }
 

package/template-document.js

@@ -0,0 +1,49 @@
+export function renderRouterDocumentSource() {
+    return `function extractSsrData(parsed) {
+  if (!parsed || typeof parsed.getElementById !== "function") return {};
+  const ssrScript = parsed.getElementById("zenith-ssr-data");
+  if (!ssrScript) return {};
+  const source = typeof ssrScript.textContent === "string" ? ssrScript.textContent : "";
+  const marker = "window.__zenith_ssr_data =";
+  const markerIndex = source.indexOf(marker);
+  if (markerIndex === -1) return {};
+  const jsonText = source.slice(markerIndex + marker.length).trim().replace(/;$/, "");
+  try {
+    return JSON.parse(jsonText);
+  } catch {
+    return {};
+  }
+}
+
+function parseDocumentPayload(html) {
+  if (typeof DOMParser === "undefined") return null;
+  const parsed = new DOMParser().parseFromString(html, "text/html");
+  return {
+    html,
+    title: parsed.title || "",
+    ssrData: extractSsrData(parsed)
+  };
+}
+
+function isHtmlResponse(response) {
+  const contentType = String(response.headers.get("content-type") || "");
+  return /text\\/html|application\\/xhtml\\+xml/i.test(contentType);
+}
+
+function createDocumentDetail(payload, response) {
+  return {
+    title: payload && typeof payload.title === "string" ? payload.title : "",
+    hasSsrData: !!(payload && payload.ssrData && typeof payload.ssrData === "object"),
+    status: response && typeof response.status === "number" ? response.status : 200
+  };
+}
+
+function createScrollDetail(targetUrl, scrollTarget) {
+  return {
+    mode: scrollTarget.mode,
+    x: scrollTarget.x,
+    y: scrollTarget.y,
+    hash: targetUrl.hash || ""
+  };
+}`;
+}

package/template-form.js

@@ -0,0 +1,174 @@
+export function renderRouterFormSource() {
+    return `function normalizeFormMethod(method) {
+  const value = typeof method === "string" ? method.trim().toUpperCase() : "";
+  return value || "GET";
+}
+
+function readSubmitOverride(submitter, attributeName, propertyName) {
+  if (!submitter) return "";
+  if (typeof submitter.getAttribute === "function") {
+    const attrValue = submitter.getAttribute(attributeName);
+    if (typeof attrValue === "string" && attrValue.length > 0) {
+      return attrValue;
+    }
+  }
+  const propertyValue = submitter[propertyName];
+  return typeof propertyValue === "string" ? propertyValue : "";
+}
+
+function resolveFormTargetUrl(form, submitter) {
+  const action =
+    readSubmitOverride(submitter, "formaction", "formAction") ||
+    form.getAttribute("action") ||
+    form.action ||
+    window.location.href;
+  return new URL(action, window.location.href);
+}
+
+function resolveFormTargetValue(form, submitter) {
+  const target = readSubmitOverride(submitter, "formtarget", "formTarget") || form.target || "";
+  return String(target || "").trim();
+}
+
+function resolveFormMethod(form, submitter) {
+  return normalizeFormMethod(
+    readSubmitOverride(submitter, "formmethod", "formMethod") || form.getAttribute("method") || form.method || "GET"
+  );
+}
+
+function createFormSubmissionPayload(form, submitter) {
+  try {
+    return submitter ? new FormData(form, submitter) : new FormData(form);
+  } catch {
+    const formData = new FormData(form);
+    if (submitter && submitter.name) {
+      formData.append(submitter.name, submitter.value || "");
+    }
+    return formData;
+  }
+}
+
+function shouldEnhanceForm(form, submitter) {
+  if (!form || typeof form.getAttribute !== "function") return false;
+  if (!form.hasAttribute("data-zen-form")) return false;
+  const target = resolveFormTargetValue(form, submitter);
+  if (target && target !== "_self") return false;
+  if (resolveFormMethod(form, submitter) !== "POST") return false;
+
+  const targetUrl = resolveFormTargetUrl(form, submitter);
+  if (targetUrl.origin !== window.location.origin) return false;
+  const resolved = resolveRoute(targetUrl.pathname);
+  return !!resolved && requiresServerReload(resolved.route);
+}
+
+async function performEnhancedFormSubmission(form, submitter) {
+  const targetUrl = resolveFormTargetUrl(form, submitter);
+  const resolved = resolveRoute(targetUrl.pathname);
+  if (!resolved) {
+    navigateViaBrowser(targetUrl, false);
+    return true;
+  }
+
+  const context = beginNavigation(targetUrl, resolved, "push");
+  let historyCommitted = false;
+  let documentDetail = null;
+  try {
+    dispatchRouteEvent("navigation:request", buildNavigationPayload(context));
+    context.stage = "fetch";
+    const response = await fetch(targetUrl.href, {
+      method: "POST",
+      body: createFormSubmissionPayload(form, submitter),
+      credentials: "include",
+      headers: { Accept: "text/html,application/xhtml+xml" },
+      redirect: "manual",
+      signal: context.signal
+    });
+    if (!ensureCurrentNavigation(context)) return false;
+
+    if (response.type === "opaqueredirect" || (response.status >= 300 && response.status < 400)) {
+      const redirectUrl = resolveRedirectUrl(response.headers.get("location"), targetUrl);
+      dispatchNavigationFallback(context, {
+        reason: "server-redirect",
+        location: redirectUrl.href,
+        status: response.status
+      });
+      navigateViaBrowser(redirectUrl, false);
+      return true;
+    }
+
+    if (!isHtmlResponse(response) || (response.status !== 200 && response.status !== 400 && response.status !== 422)) {
+      dispatchNavigationFallback(context, {
+        reason: "http-status",
+        status: response.status
+      });
+      navigateViaBrowser(targetUrl, false);
+      return true;
+    }
+
+    const html = await response.text();
+    if (!ensureCurrentNavigation(context)) return false;
+    const payload = parseDocumentPayload(html);
+    if (!payload) {
+      dispatchNavigationFallback(context, {
+        reason: "document-parse"
+      });
+      navigateViaBrowser(targetUrl, false);
+      return true;
+    }
+
+    const committed = await commitNavigationDocument(
+      context,
+      resolved,
+      targetUrl,
+      "push",
+      null,
+      payload,
+      response
+    );
+    documentDetail = committed.documentDetail;
+    historyCommitted = committed.historyCommitted;
+    if (!committed.committed) return false;
+    return true;
+  } catch (error) {
+    if (!isAbortError(error)) {
+      emitNavigationError(context, {
+        reason: "runtime-failure",
+        error,
+        historyCommitted,
+        document: documentDetail
+      });
+      console.error("[Zenith Router] form submission failed", error);
+      dispatchNavigationFallback(context, {
+        reason: "runtime-failure",
+        historyCommitted
+      });
+      navigateViaBrowser(targetUrl, false);
+      return true;
+    }
+    dispatchNavigationFallback(context, context.abortReason || {
+      reason: "superseded",
+      abortedStage: context.stage
+    });
+    return false;
+  } finally {
+    completeNavigation(context);
+  }
+}
+
+function installEnhancedFormHandling() {
+  document.addEventListener("submit", function(event) {
+    if (event.defaultPrevented) return;
+    const form = event.target;
+    const submitter = event.submitter || null;
+    if (!shouldEnhanceForm(form, submitter)) return;
+
+    event.preventDefault();
+    performEnhancedFormSubmission(form, submitter).catch(function(error) {
+      if (!isAbortError(error)) {
+        console.error("[Zenith Router] enhanced form submission failed", error);
+        navigateViaBrowser(resolveFormTargetUrl(form, submitter), false);
+      }
+    });
+  });
+}`;
+}