@cfdez11/vex 0.8.3 → 0.9.1

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

@@ -1,103 +0,0 @@
-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

@@ -1,8 +0,0 @@
-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

@@ -1,39 +0,0 @@
-/**
- * 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

@@ -1,23 +0,0 @@
-/**
- * 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

@@ -1,64 +0,0 @@
-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

@@ -1,43 +0,0 @@
-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

@@ -1,45 +0,0 @@
-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

@@ -1,157 +0,0 @@
-/**
- * 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;
-  }
-}

package/client/services/navigation/router.js

@@ -1,48 +0,0 @@
-import { routes } from "../_routes.js";
-
-/**
- * Converts a route path string with parameters (e.g., "/page/:city/:team")
- * into a RegExp for matching and extracts parameter keys.
- *
- * @param {string} routePath - The route path pattern.
- * @returns {{ regex: RegExp, keys: string[] }} An object containing the RegExp and parameter names.
- */
-function pathToRegex(routePath) {
-  const keys = [];
-  const regex = new RegExp(
-    "^" +
-      routePath.replace(/:([^/]+)/g, (_, key) => {
-        keys.push(key);
-        return "([^/]+)";
-      }) +
-      "$"
-  );
-  return { regex, keys };
-}
-
-/**
- * Finds the first route matching a given path and extracts route parameters.
- *
- * Supports both string-based paths with parameters and RegExp-based paths.
- *
- * @param {string} path - The URL path to match (e.g., "/page/madrid/barcelona").
- * @returns {{ route: import('../_routes.js').Route | null, params: Record<string, string> }}
- *          Returns the matched route and an object of extracted parameters.
- */
-export function findRouteWithParams(path) {
-  for (const r of routes) {
-    if (typeof r.path === "string") {
-      const { regex, keys } = pathToRegex(r.path);
-      const match = path.match(regex);
-      if (match) {
-        const params = {};
-        keys.forEach((k, i) => (params[k] = match[i + 1]));
-        return { route: r, params };
-      }
-    } else if (r.path instanceof RegExp && r.path.test(path)) {
-      return { route: r, params: {} };
-    }
-  }
-
-  return { route: null, params: {} };
-}