pulse-js-framework 1.10.0 → 1.10.3

package/runtime/router/guards.js

@@ -0,0 +1,90 @@
+/**
+ * Pulse Router - Guards and Middleware
+ *
+ * Navigation guards and middleware system for route protection
+ *
+ * @module pulse-js-framework/runtime/router/guards
+ */
+
+import { loggers } from '../logger.js';
+
+const log = loggers.router;
+
+/**
+ * Middleware context passed to each middleware function
+ * @typedef {Object} MiddlewareContext
+ * @property {NavigationTarget} to - Target route
+ * @property {NavigationTarget} from - Source route
+ * @property {Object} meta - Shared metadata between middlewares
+ * @property {function} redirect - Redirect to another path
+ * @property {function} abort - Abort navigation
+ */
+
+/**
+ * Create a middleware runner for the router
+ * Middlewares are executed in order, each can modify context or abort navigation
+ *
+ * @param {Array<function>} middlewares - Array of middleware functions
+ * @returns {function} Runner function
+ *
+ * @example
+ * const authMiddleware = async (ctx, next) => {
+ *   if (ctx.to.meta.requiresAuth && !isAuthenticated()) {
+ *     return ctx.redirect('/login');
+ *   }
+ *   await next();
+ * };
+ *
+ * const loggerMiddleware = async (ctx, next) => {
+ *   console.log('Navigating to:', ctx.to.path);
+ *   const start = Date.now();
+ *   await next();
+ *   console.log('Navigation took:', Date.now() - start, 'ms');
+ * };
+ *
+ * const router = createRouter({
+ *   routes,
+ *   middleware: [loggerMiddleware, authMiddleware]
+ * });
+ */
+export function createMiddlewareRunner(middlewares) {
+  return async function runMiddleware(context) {
+    let index = 0;
+    let aborted = false;
+    let redirectPath = null;
+
+    // Create enhanced context with redirect and abort
+    const ctx = {
+      ...context,
+      meta: {},
+      redirect: (path) => {
+        redirectPath = path;
+      },
+      abort: () => {
+        aborted = true;
+      }
+    };
+
+    async function next() {
+      if (aborted || redirectPath) return;
+      if (index >= middlewares.length) return;
+
+      const middlewareIndex = index;
+      const middleware = middlewares[index++];
+      try {
+        await middleware(ctx, next);
+      } catch (error) {
+        log.error(`Middleware error at index ${middlewareIndex}:`, error);
+        throw error; // Re-throw to halt navigation
+      }
+    }
+
+    await next();
+
+    return {
+      aborted,
+      redirectPath,
+      meta: ctx.meta
+    };
+  };
+}

package/runtime/router/history.js

@@ -0,0 +1,204 @@
+/**
+ * Pulse Router - History and Scroll Management
+ *
+ * Browser history integration, scroll position restoration, and persistence
+ *
+ * @module pulse-js-framework/runtime/router/history
+ */
+
+import { LRUCache } from '../lru-cache.js';
+import { loggers } from '../logger.js';
+
+const log = loggers.router;
+
+/**
+ * Create scroll position manager with persistence
+ * @param {Object} options - Configuration
+ * @param {boolean} options.persist - Enable sessionStorage persistence
+ * @param {string} options.persistKey - Storage key name
+ * @returns {Object} Scroll position manager
+ */
+export function createScrollManager(options = {}) {
+  const { persist = false, persistKey = 'pulse-router-scroll' } = options;
+
+  // Scroll positions for history (LRU cache to prevent memory leaks)
+  // Keeps last 100 scroll positions - enough for typical navigation patterns
+  const scrollPositions = new LRUCache(100);
+
+  // Restore scroll positions from sessionStorage if persistence is enabled
+  if (persist && typeof sessionStorage !== 'undefined') {
+    try {
+      const stored = sessionStorage.getItem(persistKey);
+      if (stored) {
+        const parsed = JSON.parse(stored);
+        // Restore up to 100 most recent positions
+        const entries = Object.entries(parsed).slice(-100);
+        for (const [path, pos] of entries) {
+          if (pos && typeof pos.x === 'number' && typeof pos.y === 'number') {
+            scrollPositions.set(path, pos);
+          }
+        }
+        log.debug(`Restored ${entries.length} scroll positions from sessionStorage`);
+      }
+    } catch (err) {
+      log.warn('Failed to restore scroll positions from sessionStorage:', err.message);
+    }
+  }
+
+  /**
+   * Persist scroll positions to sessionStorage
+   */
+  function persistScrollPositions() {
+    if (!persist || typeof sessionStorage === 'undefined') return;
+
+    try {
+      const data = {};
+      for (const [path, pos] of scrollPositions.entries()) {
+        data[path] = pos;
+      }
+      sessionStorage.setItem(persistKey, JSON.stringify(data));
+    } catch (err) {
+      // SessionStorage may be full or disabled
+      log.warn('Failed to persist scroll positions:', err.message);
+    }
+  }
+
+  /**
+   * Save current scroll position for a path
+   */
+  function saveScrollPosition(path) {
+    if (!path) return;
+    scrollPositions.set(path, {
+      x: window.scrollX,
+      y: window.scrollY
+    });
+    persistScrollPositions();
+  }
+
+  /**
+   * Get saved scroll position for a path
+   */
+  function getScrollPosition(path) {
+    return scrollPositions.get(path);
+  }
+
+  return {
+    saveScrollPosition,
+    getScrollPosition,
+    persistScrollPositions
+  };
+}
+
+/**
+ * Handle scroll behavior after navigation
+ */
+export function handleScroll(to, from, savedPosition, scrollBehavior = null) {
+  if (scrollBehavior) {
+    let position;
+    try {
+      position = scrollBehavior(to, from, savedPosition);
+    } catch (err) {
+      log.warn(`scrollBehavior threw an error: ${err.message}`);
+      // Fall back to default behavior
+      window.scrollTo(0, 0);
+      return;
+    }
+
+    // Validate position is a valid object
+    if (position && typeof position === 'object') {
+      if (typeof position.selector === 'string' && position.selector) {
+        // Scroll to element
+        try {
+          const el = document.querySelector(position.selector);
+          if (el) {
+            const behavior = position.behavior === 'smooth' || position.behavior === 'auto'
+              ? position.behavior
+              : 'auto';
+            el.scrollIntoView({ behavior });
+          }
+        } catch (err) {
+          log.warn(`Invalid selector in scrollBehavior: ${position.selector}`);
+        }
+      } else if (typeof position.x === 'number' || typeof position.y === 'number') {
+        const x = typeof position.x === 'number' && isFinite(position.x) ? position.x : 0;
+        const y = typeof position.y === 'number' && isFinite(position.y) ? position.y : 0;
+        const behavior = position.behavior === 'smooth' || position.behavior === 'auto'
+          ? position.behavior
+          : 'auto';
+        window.scrollTo({ left: x, top: y, behavior });
+      }
+      // If position is object but no valid selector/x/y, do nothing (intentional no-scroll)
+    }
+    // If position is falsy (null/undefined/false), do nothing (intentional no-scroll)
+  } else if (savedPosition) {
+    // Default: restore saved position
+    const x = typeof savedPosition.x === 'number' && isFinite(savedPosition.x) ? savedPosition.x : 0;
+    const y = typeof savedPosition.y === 'number' && isFinite(savedPosition.y) ? savedPosition.y : 0;
+    window.scrollTo(x, y);
+  } else {
+    // Default: scroll to top
+    window.scrollTo(0, 0);
+  }
+}
+
+/**
+ * Save current scroll and wait for popstate to fire
+ * Used by back(), forward(), and go() to integrate with scroll restoration
+ * @returns {Promise} Resolves after popstate fires or timeout
+ */
+export function saveScrollAndWaitForPopState() {
+  // Return a Promise that resolves on the next popstate (with 100ms fallback)
+  return new Promise(resolve => {
+    let resolved = false;
+    const done = () => {
+      if (resolved) return;
+      resolved = true;
+      window.removeEventListener('popstate', listener);
+      resolve();
+    };
+    const listener = () => done();
+    window.addEventListener('popstate', listener);
+    setTimeout(done, 100);
+  });
+}
+
+/**
+ * Navigate back in browser history
+ * Saves scroll position before navigating
+ * @returns {Promise} Resolves after navigation completes
+ * @example
+ * await router.back(); // Go to previous page
+ */
+export function back() {
+  const promise = saveScrollAndWaitForPopState();
+  window.history.back();
+  return promise;
+}
+
+/**
+ * Navigate forward in browser history
+ * Saves scroll position before navigating
+ * @returns {Promise} Resolves after navigation completes
+ * @example
+ * await router.forward(); // Go to next page (if available)
+ */
+export function forward() {
+  const promise = saveScrollAndWaitForPopState();
+  window.history.forward();
+  return promise;
+}
+
+/**
+ * Navigate to a specific position in browser history
+ * Saves scroll position before navigating
+ * @param {number} delta - Number of entries to move (negative = back, positive = forward)
+ * @returns {Promise} Resolves after navigation completes
+ * @example
+ * await router.go(-2); // Go back 2 pages
+ * await router.go(1);  // Go forward 1 page
+ */
+export function go(delta) {
+  const promise = saveScrollAndWaitForPopState();
+  window.history.go(delta);
+  return promise;
+}

package/runtime/router/index.js

@@ -0,0 +1,36 @@
+/**
+ * Pulse Router - Main Entry Point
+ *
+ * Barrel export for all router modules
+ *
+ * @module pulse-js-framework/runtime/router
+ */
+
+// Export all from sub-modules
+export * from './core.js';
+export * from './lazy.js';
+export * from './guards.js';
+export * from './history.js';
+export * from './utils.js';
+
+// Default export for backward compatibility
+import {
+  createRouter,
+  simpleRouter,
+  onBeforeLeave,
+  onAfterEnter
+} from './core.js';
+import { lazy, preload } from './lazy.js';
+import { matchRoute, parseQuery, buildQueryString } from './utils.js';
+
+export default {
+  createRouter,
+  simpleRouter,
+  lazy,
+  preload,
+  matchRoute,
+  parseQuery,
+  buildQueryString,
+  onBeforeLeave,
+  onAfterEnter
+};

package/runtime/router/lazy.js

@@ -0,0 +1,180 @@
+/**
+ * Pulse Router - Lazy Loading
+ *
+ * Lazy loading utilities for code-split route components
+ *
+ * @module pulse-js-framework/runtime/router/lazy
+ */
+
+import { el } from '../dom.js';
+import { loggers } from '../logger.js';
+import { createVersionedAsync } from '../async.js';
+import { Errors } from '../errors.js';
+
+const log = loggers.router;
+
+/**
+ * Lazy load helper for route components
+ * Wraps a dynamic import to provide loading states and error handling
+ *
+ * MEMORY SAFETY: Uses load version tracking to prevent stale promise callbacks
+ * from updating containers that are no longer in the DOM (e.g., after navigation).
+ *
+ * @param {function} importFn - Dynamic import function () => import('./Component.js')
+ * @param {Object} options - Lazy loading options
+ * @param {function} options.loading - Loading component function
+ * @param {function} options.error - Error component function
+ * @param {number} options.timeout - Timeout in ms (default: 10000)
+ * @param {number} options.delay - Delay before showing loading (default: 200)
+ * @returns {function} Lazy route handler
+ *
+ * @example
+ * const routes = {
+ *   '/dashboard': lazy(() => import('./Dashboard.js')),
+ *   '/settings': lazy(() => import('./Settings.js'), {
+ *     loading: () => el('div.spinner', 'Loading...'),
+ *     error: (err) => el('div.error', `Failed to load: ${err.message}`),
+ *     timeout: 5000
+ *   })
+ * };
+ */
+export function lazy(importFn, options = {}) {
+  const {
+    loading: LoadingComponent = null,
+    error: ErrorComponent = null,
+    timeout = 10000,
+    delay = 200
+  } = options;
+
+  // Cache for loaded component
+  let cachedComponent = null;
+  let loadPromise = null;
+
+  // Use centralized versioned async for race condition handling
+  const versionController = createVersionedAsync();
+
+  return function lazyHandler(ctx) {
+    // Return cached component if already loaded
+    if (cachedComponent) {
+      return typeof cachedComponent === 'function'
+        ? cachedComponent(ctx)
+        : cachedComponent.default
+          ? cachedComponent.default(ctx)
+          : cachedComponent.render
+            ? cachedComponent.render(ctx)
+            : cachedComponent;
+    }
+
+    // Create container for async loading
+    const container = el('div.lazy-route');
+
+    // Start a new versioned load operation
+    const loadCtx = versionController.begin();
+
+    // Attach abort method to container for cleanup on navigation
+    container._pulseAbortLazyLoad = () => versionController.abort();
+
+    // Start loading if not already
+    if (!loadPromise) {
+      loadPromise = importFn();
+    }
+
+    // Delay showing loading state to avoid flash (uses versioned timer)
+    if (LoadingComponent && delay > 0) {
+      loadCtx.setTimeout(() => {
+        if (!cachedComponent && loadCtx.isCurrent()) {
+          container.replaceChildren(LoadingComponent());
+        }
+      }, delay);
+    } else if (LoadingComponent) {
+      container.replaceChildren(LoadingComponent());
+    }
+
+    // Set timeout for loading (uses versioned timer)
+    let timeoutPromise = null;
+    if (timeout > 0) {
+      timeoutPromise = new Promise((_, reject) => {
+        loadCtx.setTimeout(() => {
+          reject(Errors.lazyTimeout(timeout));
+        }, timeout);
+      });
+    }
+
+    // Race between load and timeout
+    const loadWithTimeout = timeoutPromise
+      ? Promise.race([loadPromise, timeoutPromise])
+      : loadPromise;
+
+    loadWithTimeout
+      .then(module => {
+        // Always cache the component, even if navigation occurred
+        // This prevents re-showing loading state on future navigations
+        cachedComponent = module;
+
+        // Skip DOM updates if this load attempt is stale (navigation occurred)
+        if (loadCtx.isStale()) {
+          return;
+        }
+
+        // Get the component from module
+        const Component = module.default || module;
+        const result = typeof Component === 'function'
+          ? Component(ctx)
+          : Component.render
+            ? Component.render(ctx)
+            : Component;
+
+        // Replace loading with actual component
+        loadCtx.ifCurrent(() => {
+          if (result instanceof Node) {
+            container.replaceChildren(result);
+          }
+        });
+      })
+      .catch(err => {
+        loadPromise = null; // Allow retry
+
+        // Ignore if this load attempt is stale
+        if (loadCtx.isStale()) {
+          return;
+        }
+
+        if (ErrorComponent) {
+          container.replaceChildren(ErrorComponent(err));
+        } else {
+          log.error('Lazy load error:', err);
+          container.replaceChildren(
+            el('div.lazy-error', `Failed to load component: ${err.message}`)
+          );
+        }
+      });
+
+    return container;
+  };
+}
+
+/**
+ * Preload a lazy component without rendering
+ * Useful for prefetching on hover or when likely to navigate
+ *
+ * @param {function} lazyHandler - Lazy handler created with lazy()
+ * @returns {Promise} Resolves when component is loaded
+ *
+ * @example
+ * const DashboardLazy = lazy(() => import('./Dashboard.js'));
+ * // Preload on link hover
+ * link.addEventListener('mouseenter', () => preload(DashboardLazy));
+ */
+export function preload(lazyHandler) {
+  // Trigger the lazy handler with a dummy context to start loading
+  // The result is discarded, but the component will be cached
+  return new Promise(resolve => {
+    const result = lazyHandler({});
+    if (result instanceof Promise) {
+      result.then(resolve);
+    } else {
+      // Already loaded
+      resolve(result);
+    }
+  });
+}