@zenithbuild/router 0.7.3 → 0.7.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zenith Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,4 +1,4 @@
-# @zenith/router
+# @zenithbuild/router
 
 > Internal Zenith package. The generated router runtime is the authoritative surface here, not a general SPA framework API.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenithbuild/router",
-  "version": "0.7.3",
+  "version": "0.7.4",
   "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 : "/"
 );

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,184 @@
+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 resolveFormEnctype(form, submitter) {
+  return String(
+    readSubmitOverride(submitter, "formenctype", "formEnctype") ||
+    form.getAttribute("enctype") ||
+    form.enctype ||
+    "application/x-www-form-urlencoded"
+  ).toLowerCase();
+}
+
+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;
+  if (resolveFormEnctype(form, submitter).includes("multipart/form-data")) 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);
+      }
+    });
+  });
+}`;
+}

package/template-navigation.js

@@ -1,53 +1,8 @@
 export function renderRouterNavigationSource() {
-    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 {};
+    return `async function requestRouteCheck(context, resolved, targetUrl, signal) {
+  if (!__ZENITH_ROUTE_CHECK_ENABLED__) {
+    return { kind: "allow" };
   }
-}
-
-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 || ""
-  };
-}
-
-async function requestRouteCheck(context, resolved, targetUrl, signal) {
   if (!requiresServerReload(resolved.route)) {
     return { kind: "allow" };
   }
@@ -147,6 +102,109 @@ function dispatchNavigationFallback(context, detail) {
   emitNavigationAbort(context, detail);
 }
 
+async function commitNavigationDocument(context, resolved, targetUrl, historyMode, popstateState, payload, response) {
+  const documentDetail = createDocumentDetail(payload, response);
+  let historyCommitted = false;
+
+  context.stage = "data-ready";
+  emitNavigationEvent(context, "navigation:data-ready", {
+    document: documentDetail
+  }, false);
+
+  dispatchScrollEvent("before", {
+    navigationType: historyMode,
+    to: targetUrl.href,
+    from: context.fromUrl ? context.fromUrl.href : window.location.href
+  }, false);
+
+  context.stage = "before-leave";
+  await emitNavigationEvent(context, "navigation:before-leave", {
+    document: documentDetail
+  }, true);
+  if (!ensureCurrentNavigation(context)) return { committed: false, documentDetail, historyCommitted };
+
+  context.stage = "leave-complete";
+  emitNavigationEvent(context, "navigation:leave-complete", {
+    document: documentDetail
+  }, false);
+
+  context.stage = "before-swap";
+  await emitNavigationEvent(context, "navigation:before-swap", {
+    document: documentDetail
+  }, true);
+  if (!ensureCurrentNavigation(context)) return { committed: false, documentDetail, historyCommitted };
+
+  if (historyMode === "push") {
+    rememberScrollForKey(currentHistoryKey);
+    pushHistoryEntry(targetUrl);
+    historyCommitted = true;
+  } else if (historyMode === "pop") {
+    syncHistoryEntry(popstateState);
+    historyCommitted = true;
+  }
+  currentUrl = new URL(targetUrl.href);
+
+  if (payload.title) {
+    document.title = payload.title;
+  }
+
+  const mounted = await mountRoute(resolved.route, resolved.params, context.token, payload);
+  if (!mounted || !ensureCurrentNavigation(context)) {
+    return { committed: false, documentDetail, historyCommitted };
+  }
+
+  context.stage = "content-swapped";
+  emitNavigationEvent(context, "navigation:content-swapped", {
+    document: documentDetail,
+    historyCommitted
+  }, false);
+
+  await nextFrame();
+  if (!ensureCurrentNavigation(context)) return { committed: false, documentDetail, historyCommitted };
+
+  const scrollTarget = resolveScrollTarget(targetUrl, historyMode, popstateState);
+  const scrollDetail = createScrollDetail(targetUrl, scrollTarget);
+  const defaultScrollAllowed = dispatchScrollEvent("apply", {
+    navigationType: historyMode,
+    mode: scrollDetail.mode,
+    x: scrollDetail.x,
+    y: scrollDetail.y,
+    hash: scrollDetail.hash
+  }, true);
+  if (defaultScrollAllowed) {
+    applyNativeScroll(scrollTarget);
+  }
+
+  focusAfterNavigation(scrollTarget);
+  rememberScrollForKey(currentHistoryKey, { x: scrollTarget.x, y: scrollTarget.y });
+
+  context.stage = "before-enter";
+  await emitNavigationEvent(context, "navigation:before-enter", {
+    document: documentDetail,
+    scroll: scrollDetail
+  }, true);
+  if (!ensureCurrentNavigation(context)) return { committed: false, documentDetail, historyCommitted };
+
+  dispatchScrollEvent("after", {
+    navigationType: historyMode,
+    mode: scrollDetail.mode,
+    x: scrollDetail.x,
+    y: scrollDetail.y,
+    hash: scrollDetail.hash
+  }, false);
+
+  await nextFrame();
+  if (!ensureCurrentNavigation(context)) return { committed: false, documentDetail, historyCommitted };
+
+  context.stage = "enter-complete";
+  emitNavigationEvent(context, "navigation:enter-complete", {
+    document: documentDetail,
+    scroll: scrollDetail
+  }, false);
+
+  return { committed: true, documentDetail, historyCommitted };
+}
+
 async function performNavigation(targetUrl, historyMode, popstateState) {
   const resolved = resolveRoute(targetUrl.pathname);
   if (!resolved) {
@@ -232,102 +290,18 @@ async function performNavigation(targetUrl, historyMode, popstateState) {
       navigateViaBrowser(targetUrl, historyMode === "pop");
       return true;
     }
-
-    documentDetail = createDocumentDetail(payload, response);
-
-    context.stage = "data-ready";
-    emitNavigationEvent(context, "navigation:data-ready", {
-      document: documentDetail
-    }, false);
-
-    dispatchScrollEvent("before", {
-      navigationType: historyMode,
-      to: targetUrl.href,
-      from: context.fromUrl ? context.fromUrl.href : window.location.href
-    }, false);
-
-    context.stage = "before-leave";
-    await emitNavigationEvent(context, "navigation:before-leave", {
-      document: documentDetail
-    }, true);
-    if (!ensureCurrentNavigation(context)) return false;
-
-    context.stage = "leave-complete";
-    emitNavigationEvent(context, "navigation:leave-complete", {
-      document: documentDetail
-    }, false);
-
-    context.stage = "before-swap";
-    await emitNavigationEvent(context, "navigation:before-swap", {
-      document: documentDetail
-    }, true);
-    if (!ensureCurrentNavigation(context)) return false;
-
-    if (historyMode === "push") {
-      rememberScrollForKey(currentHistoryKey);
-      pushHistoryEntry(targetUrl);
-      historyCommitted = true;
-    } else if (historyMode === "pop") {
-      syncHistoryEntry(popstateState);
-      historyCommitted = true;
-    }
-    currentUrl = new URL(targetUrl.href);
-
-    if (payload.title) {
-      document.title = payload.title;
-    }
-
-    const mounted = await mountRoute(resolved.route, resolved.params, context.token, payload);
-    if (!mounted || !ensureCurrentNavigation(context)) return false;
-
-    context.stage = "content-swapped";
-    emitNavigationEvent(context, "navigation:content-swapped", {
-      document: documentDetail,
-      historyCommitted
-    }, false);
-
-    await nextFrame();
-    if (!ensureCurrentNavigation(context)) return false;
-
-    const scrollTarget = resolveScrollTarget(targetUrl, historyMode, popstateState);
-    const scrollDetail = createScrollDetail(targetUrl, scrollTarget);
-    const defaultScrollAllowed = dispatchScrollEvent("apply", {
-      navigationType: historyMode,
-      mode: scrollDetail.mode,
-      x: scrollDetail.x,
-      y: scrollDetail.y,
-      hash: scrollDetail.hash
-    }, true);
-    if (defaultScrollAllowed) {
-      applyNativeScroll(scrollTarget);
-    }
-
-    focusAfterNavigation(scrollTarget);
-    rememberScrollForKey(currentHistoryKey, { x: scrollTarget.x, y: scrollTarget.y });
-
-    context.stage = "before-enter";
-    await emitNavigationEvent(context, "navigation:before-enter", {
-      document: documentDetail,
-      scroll: scrollDetail
-    }, true);
-    if (!ensureCurrentNavigation(context)) return false;
-
-    dispatchScrollEvent("after", {
-      navigationType: historyMode,
-      mode: scrollDetail.mode,
-      x: scrollDetail.x,
-      y: scrollDetail.y,
-      hash: scrollDetail.hash
-    }, false);
-
-    await nextFrame();
-    if (!ensureCurrentNavigation(context)) return false;
-
-    context.stage = "enter-complete";
-    emitNavigationEvent(context, "navigation:enter-complete", {
-      document: documentDetail,
-      scroll: scrollDetail
-    }, false);
+    const committed = await commitNavigationDocument(
+      context,
+      resolved,
+      targetUrl,
+      historyMode,
+      popstateState,
+      payload,
+      response
+    );
+    documentDetail = committed.documentDetail;
+    historyCommitted = committed.historyCommitted;
+    if (!committed.committed) return false;
 
     return true;
   } catch (error) {
@@ -387,6 +361,7 @@ function start() {
     currentUrl = new URL(window.location.href);
     queueScrollSnapshot();
   });
+  installEnhancedFormHandling();
 
   document.addEventListener("click", function(event) {
     if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;

package/template.js

@@ -1,4 +1,6 @@
 import { renderRouterCoreSource } from './template-core.js';
+import { renderRouterDocumentSource } from './template-document.js';
+import { renderRouterFormSource } from './template-form.js';
 import { renderRouterLifecycleSource } from './template-lifecycle.js';
 import { renderRouterNavigationSource } from './template-navigation.js';
 
@@ -19,7 +21,7 @@ export function renderRouterModule(opts) {
         throw new Error('renderRouterModule(opts) requires an options object');
     }
 
-    const { manifestJson, runtimeImport, coreImport } = opts;
+    const { manifestJson, runtimeImport, coreImport, routeCheck = false } = opts;
     if (typeof manifestJson !== 'string' || manifestJson.length === 0) {
         throw new Error('renderRouterModule(opts) requires opts.manifestJson string');
     }
@@ -34,5 +36,5 @@ export function renderRouterModule(opts) {
     const runtimeSpec = sanitizeImportSpecifier(runtimeImport);
     const coreSpec = sanitizeImportSpecifier(coreImport);
 
-    return `${renderRouterCoreSource({ manifest, runtimeSpec, coreSpec })}\n\n${renderRouterLifecycleSource()}\n\n${renderRouterNavigationSource()}\n`;
+    return `${renderRouterCoreSource({ manifest, runtimeSpec, coreSpec, routeCheck })}\n\n${renderRouterDocumentSource()}\n\n${renderRouterLifecycleSource()}\n\n${renderRouterNavigationSource()}\n\n${renderRouterFormSource()}\n`;
 }