@adukiorg/anza 0.2.0

package/src/core/router/intercept.js

@@ -0,0 +1,376 @@
+/**
+ * src/core/router/intercept.js
+ *
+ * Core navigation interceptor loop.
+ * Attaches listeners to the Navigation API 'navigate' event, evaluates security
+ * guards, manages loading indicators, and performs updates wrapped in view transitions.
+ *
+ * Source: doc 09 — Routing §2, §5, §9, §13
+ */
+
+import { match } from './match.js';
+import { transitions } from './transitions.js';
+import { getContainer } from './container.js';
+import { isCallback, runCallback } from './handler.js';
+
+let guards = [];
+let notFoundHandler = null;
+let ready = false;
+
+// Navigation API listener references for teardown
+let navListener = null;
+let successListener = null;
+let errorListener = null;
+
+const listeners = {
+  found: new Set(),
+  notfound: new Set(),
+  error: new Set()
+};
+
+/**
+ * Registers an event listener on the router.
+ * Supported events: 'found', 'notfound', 'error'.
+ * Returns a disposer. Supports auto-cleanup via AbortSignal.
+ */
+export function on(type, callback, signal) {
+  if (!listeners[type]) return () => {};
+
+  listeners[type].add(callback);
+
+  const dispose = () => {
+    listeners[type].delete(callback);
+    signal?.removeEventListener('abort', dispose);
+  };
+
+  if (signal) {
+    signal.addEventListener('abort', dispose, { once: true });
+  }
+
+  return dispose;
+}
+
+/**
+ * Emits an event to registered router listeners.
+ */
+export function emit(type, detail) {
+  if (!listeners[type]) return;
+  for (const callback of Array.from(listeners[type])) {
+    try {
+      callback(detail);
+    } catch (err) {
+      console.error(`Error in router event listener for "${type}":`, err);
+    }
+  }
+}
+
+/**
+ * Registers a global navigation guard. Returns a disposer.
+ * Guards receive (destination, controller) and return a redirect URL if blocked,
+ * or null/undefined to allow.
+ */
+export function addGuard(guardFn) {
+  guards.push(guardFn);
+  return () => {
+    const idx = guards.indexOf(guardFn);
+    if (idx !== -1) guards.splice(idx, 1);
+  };
+}
+
+/** Grouped guard API. */
+export const guardsApi = {
+  add: addGuard,
+  clear() { guards = []; }
+};
+
+/**
+ * Sets the default handler for unmatched routes (404 page). Returns a disposer.
+ */
+export function setNotFound(handler) {
+  notFoundHandler = handler;
+  return () => {
+    if (notFoundHandler === handler) notFoundHandler = null;
+  };
+}
+
+/** Grouped miss API. */
+export const missApi = {
+  set: setNotFound,
+  clear() { notFoundHandler = null; }
+};
+
+/**
+ * Attaches the global window.navigation navigate listener.
+ * Idempotent — safe to call multiple times.
+ */
+export function setup() {
+  if (ready) return;
+  if (typeof window === 'undefined' || !window.navigation) return;
+  ready = true;
+
+  navListener = (event) => {
+    // Skip cross-origin navigations, file downloads, or same-document hash scrolls
+    if (!event.canIntercept || event.hashChange || event.downloadRequest) {
+      return;
+    }
+
+    const url = event.destination.url;
+    let precommitted = false; // Scoped precommitted guard state (RT-02)
+
+    event.intercept({
+      /**
+       * Runs guards before URL changes.
+       * Supports atomic redirection before URL commit (Chrome & Firefox).
+       */
+      async precommitHandler(controller) {
+        precommitted = true;
+        const destination = event.destination;
+        for (const guardFn of guards) {
+          const redirectUrl = await guardFn(destination, controller);
+          if (redirectUrl) {
+            controller.redirect(redirectUrl);
+            return;
+          }
+        }
+      },
+
+      /**
+       * Executes DOM mutations, layout changes, and provides fallbacks for Safari.
+       */
+      async handler() {
+        const destination = event.destination;
+        let routeMatch = null;
+        try {
+          routeMatch = await match(destination.url);
+        } catch (err) {
+          emit('error', { error: err, url: destination.url, route: null, phase: 'match' });
+          return;
+        }
+
+        // Strict Layout Resolution Guard: prevent blind mounts if required container is inactive
+        if (routeMatch?.route?.meta?.container) {
+          const containerName = routeMatch.route.meta.container;
+          if (!getContainer(containerName)) {
+            const err = new Error(`RouteError: Required layout container '${containerName}' is not active in the DOM.`);
+            emit('error', { error: err, url: destination.url, route: routeMatch.route, phase: 'container' });
+            throw err;
+          }
+        }
+
+        // Graceful Safari Fallback: Evaluate guards inside post-commit handler if precommit is ignored.
+        if (!precommitted) {
+          for (const guardFn of guards) {
+            let redirectUrl;
+            try {
+              redirectUrl = await guardFn(destination, null);
+            } catch (err) {
+              emit('error', { error: err, url: destination.url, route: routeMatch?.route ?? null, phase: 'guard' });
+              return;
+            }
+            if (redirectUrl) {
+              window.navigation.navigate(redirectUrl, { history: 'replace' });
+              return;
+            }
+          }
+        }
+
+        await transitions.run(async () => {
+          if (routeMatch) {
+            // Run callback handlers exactly once, here (never during match()).
+            if (isCallback(routeMatch.route.handler)) {
+              try {
+                await runCallback(routeMatch.route.handler, routeMatch.params, event);
+              } catch (err) {
+                emit('error', { error: err, url: destination.url, route: routeMatch.route, phase: 'handler' });
+                return;
+              }
+            }
+
+            emit('found', {
+              tag: routeMatch.tag,
+              params: routeMatch.params,
+              query: routeMatch.query,
+              hash: routeMatch.hash,
+              chain: routeMatch.chain,
+              url: destination.url,
+              direction: event.navigationType
+            });
+          } else {
+            emit('notfound', { url: destination.url });
+
+            if (notFoundHandler) {
+              await notFoundHandler(event);
+            } else {
+              console.error(`Route matching failed and no not-found boundary handler was configured: ${destination.url}`);
+            }
+          }
+        });
+      }
+    });
+  };
+
+  successListener = () => {
+    const url = window.navigation.currentEntry?.url;
+    if (url) {
+      import('./sync/index.js').then(({ coordinateConnections }) => {
+        coordinateConnections(url);
+      }).catch(() => {});
+    }
+  };
+
+  errorListener = (event) => {
+    const error = event.error;
+
+    // Silence aborted/superseded navigation actions
+    if (error && (error.name === 'AbortError' || error.message?.includes('aborted'))) {
+      return;
+    }
+
+    console.error('Navigation error caught globally:', error);
+    emit('error', { error, url: window.navigation.currentEntry?.url ?? null, route: null, phase: 'navigation' });
+
+    import('../events/index.js').then(({ events }) => {
+      events.emit('core:error', {
+        code: 'NAVIGATION_FAILED',
+        message: error?.message || 'Navigation failed',
+        cause: error,
+        context: { url: window.navigation.currentEntry?.url },
+        recoverable: true
+      });
+    }).catch(() => {});
+  };
+
+  window.navigation.addEventListener('navigate', navListener);
+  window.navigation.addEventListener('navigatesuccess', successListener);
+  window.navigation.addEventListener('navigateerror', errorListener);
+
+  // Trigger initial on-boot matching and emit initial events once setup is completed
+  Promise.resolve().then(async () => {
+    const url = window.navigation.currentEntry?.url || window.location.href;
+    const routeMatch = await match(url);
+    if (routeMatch) {
+      emit('found', {
+        tag: routeMatch.tag,
+        params: routeMatch.params,
+        query: routeMatch.query,
+        hash: routeMatch.hash,
+        chain: routeMatch.chain,
+        url,
+        direction: 'load'
+      });
+    } else {
+      emit('notfound', { url });
+    }
+  });
+}
+
+/**
+ * Tears down all navigation listeners and resets router state.
+ * Useful for test isolation and SSR teardown.
+ */
+export function destroy() {
+  if (!ready) return;
+  ready = false;
+
+  if (typeof window !== 'undefined' && window.navigation) {
+    if (navListener) window.navigation.removeEventListener('navigate', navListener);
+    if (successListener) window.navigation.removeEventListener('navigatesuccess', successListener);
+    if (errorListener) window.navigation.removeEventListener('navigateerror', errorListener);
+  }
+
+  navListener = null;
+  successListener = null;
+  errorListener = null;
+
+  guards = [];
+  notFoundHandler = null;
+
+  for (const set of Object.values(listeners)) {
+    set.clear();
+  }
+
+  // Close sync channel via dynamic import (avoids circular dep at module load)
+  import('./sync/tab.js').then(m => m.close?.()).catch(() => {});
+}
+
+class TransitionController {
+  constructor(url, navigationPromise) {
+    this.url = url;
+    this.promise = navigationPromise;
+    this.listeners = {
+      found: [],
+      notfound: [],
+      error: []
+    };
+
+    const getPath = (u) => {
+      try { return new URL(u, window.location.href).pathname; } catch (_) { return u; }
+    };
+
+    // Coordinate with Navigation events using standard on() mechanism (RT-01)
+    const disposeFound = on('found', (detail) => {
+      if (getPath(detail.url) === getPath(this.url)) {
+        cleanup();
+        this._dispatch('found', detail);
+      }
+    });
+
+    const disposeNotFound = on('notfound', (detail) => {
+      if (getPath(detail.url) === getPath(this.url)) {
+        cleanup();
+        this._dispatch('notfound', detail);
+      }
+    });
+
+    const disposeError = on('error', (detail) => {
+      cleanup();
+      this._dispatch('error', detail.error);
+    });
+
+    const cleanup = () => {
+      disposeFound();
+      disposeNotFound();
+      disposeError();
+    };
+
+    this.promise.catch((err) => {
+      cleanup();
+      this._dispatch('error', err);
+    });
+  }
+
+  on(event, callback) {
+    if (this.listeners[event]) {
+      this.listeners[event].push(callback);
+    }
+    return this;
+  }
+
+  _dispatch(event, payload) {
+    for (const cb of this.listeners[event]) {
+      try {
+        cb(payload);
+      } catch (err) {
+        console.error(`Error inside fluent navigation "${event}" handler:`, err);
+      }
+    }
+  }
+}
+
+let navigateCallback = null;
+
+export function registerNavigator(cb) {
+  navigateCallback = cb;
+}
+
+export const nav = {
+  to(url, options) {
+    if (!navigateCallback) {
+      console.warn('[Router] Navigator is not registered yet. Falling back to dynamic import.');
+      return new TransitionController(url, import('./history.js').then(m => m.navigate(url, options)));
+    }
+    const result = navigateCallback(url, options);
+    const p = result instanceof Promise ? result : Promise.resolve(result);
+    return new TransitionController(url, p);
+  }
+};

package/src/core/router/match.js

@@ -0,0 +1,145 @@
+/**
+ * src/core/router/match.js
+ *
+ * Route table registration and URLPattern matcher.
+ * Compiles patterns lazily and extracts named capture group parameters on success.
+ *
+ * Source: doc 09 — Routing §3, §4
+ */
+
+import { guard } from '../platform/index.js';
+import { resolveTag } from './handler.js';
+
+const routes = [];
+// Resolve Pattern class at module load if available natively (RT-03)
+let Pattern = typeof URLPattern !== 'undefined' ? URLPattern : null;
+
+// Pre-resolve polyfill in background if not native
+if (!Pattern) {
+  guard.urlPattern().then(cls => {
+    Pattern = cls;
+  }).catch(() => {});
+}
+
+async function getURLPattern() {
+  if (!Pattern) {
+    Pattern = await guard.urlPattern();
+  }
+  return Pattern;
+}
+
+function getSpecificity(patternStr) {
+  if (patternStr === '*') return 0;
+  const hasWildcard = patternStr.includes('*');
+  const hasParam = patternStr.includes(':');
+  
+  if (!hasWildcard && !hasParam) return 3; // Static: highest
+  if (!hasWildcard && hasParam) return 2;  // Params: medium
+  return 1;                                // Wildcard: low
+}
+
+/**
+ * Registers a route mapping.
+ */
+export function register(patternStr, handler, meta = {}) {
+  routes.push({
+    patternStr,
+    handler,
+    meta,
+    pattern: null
+  });
+
+  // Sort routes by specificity (descending) and length (longer first) at registration time (RT-04)
+  routes.sort((a, b) => {
+    const specA = getSpecificity(a.patternStr);
+    const specB = getSpecificity(b.patternStr);
+    if (specA !== specB) return specB - specA;
+    return b.patternStr.length - a.patternStr.length;
+  });
+}
+
+/**
+ * Matches a URL against the registered routes.
+ */
+export async function match(url) {
+  // Use pre-resolved Pattern class synchronously on hot path (RT-03)
+  const P = Pattern || (await getURLPattern());
+  const targetUrl = new URL(url, globalThis.location?.href || 'http://localhost');
+
+  for (const route of routes) {
+    if (!route.pattern) {
+      if (route.patternStr.startsWith('http://') || route.patternStr.startsWith('https://')) {
+        route.pattern = new P(route.patternStr);
+      } else {
+        route.pattern = new P({ pathname: route.patternStr });
+      }
+    }
+
+    const result = route.pattern.exec(targetUrl.href);
+    if (result) {
+      // Resolve to a tag without ever invoking callback handlers (see handler.js).
+      const tag = await resolveTag(route.handler);
+
+      const query = Object.fromEntries(targetUrl.searchParams.entries());
+      const hash = targetUrl.hash;
+
+      const chain = [];
+      let currentRoute = route;
+      while (currentRoute) {
+        const currentTag = await resolveTag(currentRoute.handler);
+        chain.unshift({
+          route: currentRoute,
+          tag: currentTag,
+          params: result.pathname.groups || {}
+        });
+
+        const parentPattern = currentRoute.meta?.parent;
+        if (parentPattern) {
+          const parentRoute = routes.find(r => r.patternStr === parentPattern);
+          currentRoute = parentRoute;
+        } else {
+          currentRoute = null;
+        }
+      }
+
+      return {
+        route,
+        tag,
+        params: result.pathname.groups || {},
+        query,
+        hash,
+        chain,
+        result
+      };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Clears the route registry.
+ */
+export function clear() {
+  routes.length = 0;
+}
+
+/**
+ * Returns all currently registered routes.
+ */
+export function getRoutes() {
+  return routes;
+}
+
+/**
+ * Bulk registers routes from a JSON array or object.
+ * Accepts an array of { pattern, handler, meta } objects.
+ */
+export function load(routesData) {
+  const routesArray = Array.isArray(routesData) ? routesData : [routesData];
+  for (const { pattern, handler, meta } of routesArray) {
+    if (pattern && handler) {
+      register(pattern, handler, meta || {});
+    }
+  }
+}