@cfdez11/vex 0.1.0

package/client/services/navigation/create-layouts.js

@@ -0,0 +1,172 @@
+/**
+ * @typedef {Object} Layout
+ * @property {string} name - Layout name.
+ * @property {string} importPath - Path to the module.
+ */
+
+/**
+ * @typedef {Object} RenderedLayout
+ * @property {string} name - Layout name.
+ * @property {Node} children - Original children node.
+ * @property {Node} node - Rendered layout node.
+ */
+
+/**
+ * @typedef {Object} GenerateParams
+ * @property {Layout[]} [routeLayouts] - Layouts to render for this route.
+ * @property {Node} pageNode - The page node to wrap.
+ * @property {any} metadata - Metadata for the page/layout.
+ */
+
+/**
+ * @typedef {Object} GenerateResult
+ * @property {string | null} layoutId - ID of the nearest rendered layout.
+ * @property {Node} node - The root node after layout wrapping.
+ * @property {any} metadata - Metadata after merging layouts.
+ */
+
+/**
+ * Creates a layout renderer responsible for dynamically loading,
+ * rendering, caching, and patching route-based layouts.
+ *
+ * The renderer keeps track of already rendered layouts to avoid
+ * unnecessary re-renders and supports incremental layout updates.
+ *
+ * @returns {{
+ *   generate: (params: GenerateParams) => Promise<GenerateResult>,
+ *   patch: (layoutId: string, node: Node) => void,
+ *   reset: () => void
+ * }}
+ */
+export function createLayoutRenderer() {
+  /** @type {Map<string, RenderedLayout>} */
+  const renderedLayouts = new Map();
+
+  /**
+   * Removes cached layouts that are no longer part of the current route.
+   * @param {Layout[]} routeLayouts
+   */
+  function cleanNotNeeded(routeLayouts) {
+    for (const name of renderedLayouts.keys()) {
+      const exists = routeLayouts.some((l) => l.name === name);
+      if (!exists) {
+        renderedLayouts.delete(name);
+      }
+    }
+  }
+
+  /**
+   * Finds the nearest already-rendered layout in the route hierarchy.
+   * @param {Layout[]} routeLayouts
+   * @returns {RenderedLayout | null}
+   */
+  function getNearestRendered(routeLayouts) {
+    const reversed = routeLayouts.toReversed();
+
+    for (const layout of reversed) {
+      if (renderedLayouts.has(layout.name)) {
+        return renderedLayouts.get(layout.name);
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Determines which layouts need to be rendered based on
+   * the nearest cached layout.
+   * @param {Layout[]} routeLayouts
+   * @param {RenderedLayout | null} nearestRendered
+   * @returns {Layout[]}
+   */
+  function getLayoutsToRender(routeLayouts, nearestRendered) {
+    if (!nearestRendered) return routeLayouts;
+
+    const reversed = routeLayouts.toReversed();
+    const idx = reversed.findIndex((l) => l.name === nearestRendered.name);
+
+    return idx === -1 ? routeLayouts : reversed.slice(0, idx);
+  }
+
+  /**
+   * Dynamically imports layout modules.
+   * @param {Layout[]} layouts
+   * @returns {Promise<any[]>}
+   */
+  async function loadLayoutModules(layouts) {
+    return Promise.all(layouts.map((layout) => import(layout.importPath)));
+  }
+
+  /**
+   * Generates the layout tree wrapping the provided page node.
+   * @param {GenerateParams} params
+   * @returns {Promise<GenerateResult>}
+   */
+  async function generate({ routeLayouts = [], pageNode, metadata }) {
+    if (!pageNode || routeLayouts.length === 0) {
+      return {
+        layoutId: null,
+        node: pageNode,
+        metadata,
+      };
+    }
+
+    cleanNotNeeded(routeLayouts);
+
+    const nearestRendered = getNearestRendered(routeLayouts);
+    const layoutsToRender = getLayoutsToRender(routeLayouts, nearestRendered);
+
+    const modules = await loadLayoutModules(layoutsToRender);
+
+    let htmlContainerNode = pageNode;
+    let deepestMetadata = metadata;
+
+    for (let i = modules.length - 1; i >= 0; i--) {
+      const layout = layoutsToRender[i];
+      const mod = modules[i];
+
+      const children = htmlContainerNode;
+      const marker = document.createElement("template");
+
+      htmlContainerNode = mod.hydrateClientComponent(marker, { children });
+
+      if (!deepestMetadata && mod.metadata) {
+        deepestMetadata = mod.metadata;
+      }
+
+      renderedLayouts.set(layout.name, {
+        name: layout.name,
+        children,
+        node: htmlContainerNode,
+      });
+    }
+
+    return {
+      layoutId: nearestRendered?.name ?? null,
+      node: htmlContainerNode,
+      metadata: deepestMetadata,
+    };
+  }
+
+  /**
+   * Patches an already-rendered layout by replacing its children node.
+   * @param {string} layoutId
+   * @param {Node} node
+   */
+  function patch(layoutId, node) {
+    const record = renderedLayouts.get(layoutId);
+    if (!record) return;
+
+    record.children.replaceWith(node);
+    record.children = node;
+  }
+
+  /**
+   * Clears all cached rendered layouts.
+   */
+  function reset() {
+    renderedLayouts.clear();
+  }
+
+  return { generate, patch, reset };
+}

package/client/services/navigation/create-navigation.js

@@ -0,0 +1,103 @@
+import { setupLinkInterceptor } from "./link-interceptor.js";
+import { setupPrefetchObserver } from "./prefetch.js";
+import { navigateInternal } from "./navigate.js";
+import { findRouteWithParams } from "./router.js";
+import { createLayoutRenderer } from "./create-layouts.js";
+
+/**
+ * Creates a new SPA navigation runtime with encapsulated state.
+ *
+ * This factory returns a navigation runtime that manages:
+ * - Current navigation controller (for aborting in-progress navigations)
+ * - Layout rendering via `layoutRenderer`
+ * - Link interception for SPA navigation
+ * - Prefetch observer setup
+ * - Popstate handling for back/forward browser navigation
+ *
+ * Each instance is isolated and maintains its own state, making it safe
+ * to use multiple runtimes or for testing purposes.
+ *
+ * @returns {Object} The navigation runtime API.
+ * @property {(path: string, addToHistory?: boolean) => Promise<void>} navigate - Programmatically navigate to a given path.
+ * @property {() => void} initialize - Initializes the SPA router and sets up link interception, prefetching, and initial navigation.
+ */
+export function createNavigationRuntime() {
+  /** @type {AbortController | null} - Controller for the current navigation request */
+  let currentNavigationController = null;
+
+  /** Layout renderer instance for wrapping pages with layouts */
+  const layoutRenderer = createLayoutRenderer();
+
+  /**
+   * Aborts the currently active navigation, if any.
+   * @private
+   */
+  function abortPrevious() {
+    if (currentNavigationController) {
+      currentNavigationController.abort();
+    }
+  }
+
+  /**
+   * Performs SPA navigation to the specified path.
+   *
+   * Aborts any in-progress navigation, manages history state, and renders
+   * the target route. Handles SSR routes and layout rendering internally.
+   *
+   * @param {string} path - The URL path to navigate to.
+   * @param {boolean} [addToHistory=true] - Whether to push this navigation to the browser history.
+   * @returns {Promise<void>} Resolves when navigation is complete.
+   */
+  async function navigate(path, addToHistory = true) {
+    abortPrevious();
+
+    const controller = new AbortController();
+    currentNavigationController = controller;
+
+    try {
+      await navigateInternal({
+        path,
+        addToHistory,
+        controller,
+        layoutRenderer,
+        onFinish: () => {
+          if (currentNavigationController === controller) {
+            currentNavigationController = null;
+          }
+        },
+      });
+    } catch (e) {
+      if (e.name !== "AbortError") {
+        console.error("Navigation error:", e);
+      }
+    }
+  }
+
+  /**
+   * Initializes the SPA router.
+   *
+   * Sets up:
+   * - Popstate listener for browser back/forward navigation
+   * - Link interception for SPA navigation
+   * - Prefetch observer for internal links
+   * - Initial navigation if the current route is not SSR
+   *
+   * Must be called after DOMContentLoaded.
+   */
+  function initialize() {
+    window.addEventListener("popstate", () => {
+      navigate(location.pathname, false);
+    });
+
+    setupLinkInterceptor(navigate);
+    setupPrefetchObserver();
+    layoutRenderer.reset();
+
+    const { route } = findRouteWithParams(location.pathname);
+    if (!route?.meta?.ssr) {
+      navigate(location.pathname, false);
+    }
+  }
+
+  return { navigate, initialize };
+}

package/client/services/navigation/index.js

@@ -0,0 +1,8 @@
+import { createNavigationRuntime } from "./create-navigation.js";
+
+const navigation = createNavigationRuntime();
+
+export const initializeRouter = navigation.initialize;
+export const navigate = navigation.navigate;
+export { useRouteParams } from "./use-route-params.js";
+export { useQueryParams } from "./use-query-params.js";

package/client/services/navigation/link-interceptor.js

@@ -0,0 +1,39 @@
+/**
+ * Sets up a global click listener to intercept internal link clicks
+ * and enable SPA-style navigation without full page reloads.
+ *
+ * This function ignores links that:
+ * - Are external (different origin)
+ * - Have `target="_blank"` or `rel="external"`
+ * - Have a `data-reload` attribute
+ * - Are hash links (start with "#")
+ *
+ * When a valid internal link is clicked, it prevents the default browser behavior
+ * and invokes the provided `navigate` function with the link's path.
+ *
+ * @param {(path: string) => void} navigate - A function to handle navigation
+ *   to the given path (e.g., your SPA router's `navigate` method).
+ */
+export function setupLinkInterceptor(navigate) {
+  document.addEventListener("click", (event) => {
+    const link = event.target.closest("a");
+    if (!link) return;
+
+    const href = link.getAttribute("href");
+    if (!href || href.startsWith("#")) return;
+
+    const url = new URL(href, window.location.origin);
+
+    if (
+      url.origin !== window.location.origin ||
+      link.dataset.reload !== undefined ||
+      link.target === "_blank" ||
+      link.rel === "external"
+    ) {
+      return;
+    }
+
+    event.preventDefault();
+    navigate(url.pathname);
+  });
+}

package/client/services/navigation/metadata.js

@@ -0,0 +1,23 @@
+/**
+ * Updates the document's `<title>` and `<meta name="description">` tags
+ * based on the provided metadata.
+ *
+ * If a `<meta name="description">` tag does not exist, it will be created.
+ *
+ * @param {Object} metadata - Page metadata to apply.
+ * @param {string} [metadata.title] - Title to set for the document.
+ * @param {string} [metadata.description] - Description to set in the meta tag.
+ */
+export function addMetadata(metadata) {
+  if (metadata.title) document.title = metadata.title;
+
+  if (metadata.description) {
+    let meta = document.querySelector('meta[name="description"]');
+    if (!meta) {
+      meta = document.createElement("meta");
+      meta.name = "description";
+      document.head.appendChild(meta);
+    }
+    meta.content = metadata.description;
+  }
+}

package/client/services/navigation/navigate.js

@@ -0,0 +1,64 @@
+import { findRouteWithParams } from "./router.js";
+import { updateRouteParams } from "./use-route-params.js";
+import { renderPage } from "./render-page.js";
+import { renderSSRPage } from "./render-ssr.js";
+
+/**
+ * Handles the internal SPA navigation logic.
+ *
+ * This function performs the following tasks:
+ * - Updates the route parameters store.
+ * - Updates browser history (if `addToHistory` is true).
+ * - Resolves the target route using the router.
+ * - Handles SSR routes by fetching and rendering via streaming.
+ * - Checks authentication and access restrictions, redirecting if necessary.
+ * - Renders the target page component and its layouts.
+ * - Calls `onFinish` when navigation is complete, regardless of success or error.
+ *
+ * @param {Object} options - Navigation options.
+ * @param {string} options.path - The target URL path for navigation.
+ * @param {boolean} options.addToHistory - Whether to push this navigation to browser history.
+ * @param {AbortController} options.controller - The controller used to cancel the navigation if needed.
+ * @param {import('./create-layouts.js').LayoutRenderer} options.layoutRenderer - Instance responsible for rendering layouts.
+ * @param {() => void} options.onFinish - Callback invoked when navigation completes or is aborted.
+ *
+ * @returns {Promise<void>} Resolves when navigation is complete.
+ */
+export async function navigateInternal({
+  path,
+  addToHistory,
+  controller,
+  layoutRenderer,
+  onFinish,
+}) {
+  updateRouteParams(path);
+
+  const routePath = path.split("?")[0];
+  const { route } = findRouteWithParams(routePath);
+
+  if (addToHistory) {
+    history.pushState({}, "", path);
+  }
+
+  try {
+    if (route?.meta?.ssr) {
+      layoutRenderer.reset();
+      await renderSSRPage(path, controller.signal);
+      return;
+    }
+
+    if (route?.meta?.requiresAuth && !app.Store?.loggedIn) {
+      location.href = "/account/login";
+      return;
+    }
+
+    if (route?.meta?.guestOnly && app.Store?.loggedIn) {
+      location.href = "/account";
+      return;
+    }
+
+    await renderPage({ route, layoutRenderer });
+  } finally {
+    onFinish();
+  }
+}

package/client/services/navigation/prefetch.js

@@ -0,0 +1,43 @@
+import { routes } from "../_routes.js";
+import { prefetchRouteComponent } from "../cache.js";
+
+/**
+ * Sets up an IntersectionObserver to prefetch route components for links
+ * with the `data-prefetch` attribute when they enter the viewport.
+ *
+ * Prefetched components are loaded in advance to improve SPA navigation performance.
+ *
+ * Links are only observed once, and the observer is disconnected for each link
+ * after prefetching to avoid unnecessary observations.
+ */
+export function setupPrefetchObserver() {
+  /** @type {IntersectionObserver} */
+  const observer = new IntersectionObserver(
+    (entries) => {
+      entries.forEach((entry) => {
+        if (!entry.isIntersecting) return;
+
+        /** @type {HTMLAnchorElement} */
+        const link = entry.target;
+        if (!link.hasAttribute("data-prefetch")) return;
+
+        const url = new URL(link.href, location.origin);
+        const route = routes.find((r) => r.path === url.pathname);
+
+        if (route?.component) {
+          prefetchRouteComponent(route.path, route.component);
+          observer.unobserve(link);
+        }
+      });
+    },
+    { rootMargin: "200px" }
+  );
+
+  // Observe all links with data-prefetch attribute that haven't been observed yet
+  document.querySelectorAll("a[data-prefetch]").forEach((link) => {
+    if (!link.__prefetchObserved) {
+      link.__prefetchObserved = true;
+      observer.observe(link);
+    }
+  });
+}

package/client/services/navigation/render-page.js

@@ -0,0 +1,45 @@
+import { addMetadata } from "./metadata.js";
+
+/**
+ * Renders a client-side page component into the DOM, wrapping it with layouts if defined.
+ *
+ * This function performs the following steps:
+ * - Dynamically imports the route component.
+ * - Hydrates the component into a DOM node.
+ * - Wraps the page node with layouts using the provided `layoutRenderer`.
+ * - Patches the layout if it already exists, or replaces the root content.
+ * - Updates page metadata (title, description).
+ * - Hydrates any client-side components within the page.
+ *
+ * @param {Object} options - The rendering options.
+ * @param {import('../_routes.js').Route} options.route - The route object containing the component and layout info.
+ * @param {import('./create-layouts.js').LayoutRenderer} options.layoutRenderer - The layout renderer instance responsible for wrapping layouts.
+ *
+ * @returns {Promise<void>} Resolves when the page has been rendered and layouts patched.
+ */
+export async function renderPage({ route, layoutRenderer }) {
+  if (!route?.component) return;
+
+  const mod = await route.component();
+  if (!mod.hydrateClientComponent) return;
+
+  const root = document.getElementById("app-root") || document.body;
+  const marker = document.createElement("template");
+  const pageNode = mod.hydrateClientComponent(marker);
+
+  const { node, layoutId, metadata } = await layoutRenderer.generate({
+    routeLayouts: route.layouts,
+    pageNode,
+    metadata: mod.metadata,
+  });
+
+  if (layoutId) {
+    layoutRenderer.patch(layoutId, node);
+  } else {
+    root.innerHTML = "";
+    root.appendChild(node);
+  }
+
+  if (metadata) addMetadata(metadata);
+  hydrateComponents();
+}

package/client/services/navigation/render-ssr.js

@@ -0,0 +1,157 @@
+/**
+ * Streams and renders a server-side rendered (SSR) page into the DOM.
+ *
+ * This function progressively updates the `<main>` element, `<template>` elements,
+ * `<script>` tags, and metadata while reading the response stream.
+ *
+ * @param {string} path - The URL or path of the SSR page to fetch.
+ * @param {AbortSignal} signal - AbortSignal to cancel the fetch if needed.
+ * @throws {Error} If the response body is not readable.
+ */
+export async function renderSSRPage(path, signal) {
+  const res = await fetch(path, { signal });
+  if (!res.body) throw new Error("Invalid SSR response");
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  const parser = new DOMParser();
+
+  let buffer = "";
+  const main = document.querySelector("main");
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+
+    buffer += decoder.decode(value, { stream: true });
+
+    buffer = processSSRMain(buffer, parser, main);
+    buffer = processSSRTemplates(buffer, parser);
+    buffer = processSSRScripts(buffer, parser);
+    updateSSRMetadata(buffer, parser);
+
+    hydrateComponents(); // global hydration function
+  }
+}
+
+/**
+ * Extracts and renders the `<main>` element from an HTML buffer.
+ *
+ * @param {string} buffer - The HTML buffer.
+ * @param {DOMParser} parser - DOMParser instance.
+ * @param {HTMLElement|null} mainEl - Existing <main> element in the DOM.
+ * @returns {string} The remaining buffer after processing the <main> tag.
+ */
+function processSSRMain(buffer, parser, mainEl) {
+  const match = buffer.match(/<main[\s\S]*?<\/main>/i);
+  if (!match) return buffer;
+
+  const doc = parser.parseFromString(match[0], "text/html");
+  const newMain = doc.querySelector("main");
+
+  if (newMain && mainEl) {
+    mainEl.innerHTML = newMain.innerHTML;
+  }
+
+  return buffer.slice(match.index + match[0].length);
+}
+
+/**
+ * Extracts `<template id="...">` elements from the stream buffer and appends
+ * them to the document so the Suspense hydration script can find them by ID.
+ *
+ * When a Suspense boundary resolves the server streams:
+ *   <template id="suspense-X-content">…real content…</template>
+ *   <script src="hydrate.js" data-target="suspense-X" data-source="suspense-X-content"></script>
+ *
+ * `hydrate.js` looks up the template by ID and swaps the fallback placeholder
+ * with its content. The template must be in the DOM before the script runs —
+ * this function is called before `processSSRScripts`, guaranteeing that order.
+ *
+ * @param {string} buffer - The HTML buffer.
+ * @param {DOMParser} parser - DOMParser instance.
+ * @returns {string} Remaining buffer after extracting all complete <template> tags.
+ */
+function processSSRTemplates(buffer, parser) {
+  const regex = /<template\b[^>]*>[\s\S]*?<\/template>/gi;
+  let match;
+  let lastIndex = -1;
+
+  while ((match = regex.exec(buffer)) !== null) {
+    const doc = parser.parseFromString(match[0], "text/html");
+    const template = doc.querySelector("template");
+    // Only insert templates with an id — those are Suspense replacement payloads.
+    // Regular <template> tags inside <main> are already handled by processSSRMain.
+    if (template?.id) {
+      document.body.appendChild(template);
+    }
+    lastIndex = match.index + match[0].length;
+  }
+
+  return lastIndex !== -1 ? buffer.slice(lastIndex) : buffer;
+}
+
+/**
+ * Processes <script> elements from an HTML buffer, executes inline scripts,
+ * and injects external scripts into the DOM if they don't exist yet.
+ *
+ * @param {string} buffer - The HTML buffer.
+ * @param {DOMParser} parser - DOMParser instance.
+ * @returns {string} Remaining buffer after processing <script> tags.
+ */
+function processSSRScripts(buffer, parser) {
+  const regex = /<script[\s\S]*?<\/script>/gi;
+  let match;
+
+  while ((match = regex.exec(buffer))) {
+    const script = parser
+      .parseFromString(match[0], "text/html")
+      .querySelector("script");
+
+    if (!script) continue;
+
+    if (script.src) {
+      const exists = [...document.scripts].some((s) => s.src === script.src);
+      if (!exists) {
+        const s = document.createElement("script");
+        s.src = script.src;
+        s.async = true;
+        document.head.appendChild(s);
+      }
+    } else {
+      try {
+        new Function(script.textContent)();
+      } catch (e) {
+        console.error("Error executing inline SSR script:", e);
+      }
+    }
+  }
+
+  const end = buffer.lastIndexOf("</script>");
+  return end !== -1 ? buffer.slice(end + 9) : buffer;
+}
+
+/**
+ * Updates the document `<title>` and `<meta name="description">` based on
+ * content found in the HTML buffer.
+ *
+ * @param {string} buffer - The HTML buffer.
+ * @param {DOMParser} parser - DOMParser instance.
+ */
+function updateSSRMetadata(buffer, parser) {
+  const doc = parser.parseFromString(buffer, "text/html");
+
+  const title = doc.querySelector("title");
+  if (title) document.title = title.textContent;
+
+  const desc = doc.querySelector('meta[name="description"]');
+  if (desc) {
+    let meta = document.querySelector('meta[name="description"]');
+    if (!meta) {
+      meta = document.createElement("meta");
+      meta.name = "description";
+      document.head.appendChild(meta);
+    }
+    meta.content = desc.content;
+  }
+}