@pithyjs/router 0.1.0-beta.0

package/dist/router/core/router.d.ts

@@ -0,0 +1,229 @@
+/** @codex
+{
+  "id": "pithy.router.core",
+  "title": "Router Core with Navigation Transaction State Machine",
+  "category": "runtime"
+}
+*/
+import { type Signal } from '@pithyjs/signals';
+import { type NavigationId, type RouteParams, type QueryParams, type RouterConfig, type RouteNode, type RouterState, type NavigationOptions } from './types';
+import { type ResourceState } from '../features/loaders';
+/** @codexApi {"parent":"pithy.router.core","name":"Router","stability":"stable","signature":"class Router","description":"Core router class with navigation transaction state machine"} */
+/**
+ * Core router class with navigation transaction state machine
+ * Implements enhanced architectural improvements for production-ready routing
+ */
+export declare class Router {
+    private config;
+    private routes;
+    private routePatterns;
+    private pipeline;
+    private historyManager;
+    private features;
+    private linkInterceptor;
+    private outletManager;
+    private previousSegmentChain;
+    private mountedElement;
+    private isMounted;
+    private popstateListener;
+    private hmrCleanup;
+    private _path;
+    private _params;
+    private _query;
+    private _loaderData;
+    private routerState;
+    private committed;
+    private outletSnapshot;
+    constructor(routes: RouteNode[], config?: RouterConfig);
+    /** @codexApi {"parent":"pithy.router.core","name":"state","stability":"stable","signature":"() => Signal<RouterState>","description":"Get current router state as a reactive signal"} */
+    /**
+     * Get current router state as reactive signal
+     */
+    state(): Signal<RouterState>;
+    /** @codexApi {"parent":"pithy.router.core","name":"path","stability":"stable","signature":"() => () => string","description":"Get current path as a computed reactive signal"} */
+    /**
+     * Get current path as reactive signal (memoized to avoid leaking effects)
+     */
+    path(): () => string;
+    /** @codexApi {"parent":"pithy.router.core","name":"params","stability":"stable","signature":"() => () => RouteParams","description":"Get current route params as a computed reactive signal"} */
+    /**
+     * Get current params as reactive signal (memoized to avoid leaking effects)
+     */
+    params(): () => RouteParams;
+    /** @codexApi {"parent":"pithy.router.core","name":"query","stability":"stable","signature":"() => () => QueryParams","description":"Get current query params as a computed reactive signal"} */
+    /**
+     * Get current query as reactive signal (memoized to avoid leaking effects)
+     */
+    query(): () => QueryParams;
+    /** @codexApi {"parent":"pithy.router.core","name":"loaderData","stability":"stable","signature":"() => () => ResourceState | null","description":"Get current loader data as a computed reactive signal"} */
+    /**
+     * Get current loader data as reactive signal (memoized to avoid leaking effects)
+     */
+    loaderData(): () => ResourceState | null;
+    /** @codexApi {"parent":"pithy.router.core","name":"navigate","stability":"stable","signature":"(path: string, options?: NavigationOptions) => Promise<boolean>","description":"Navigate to a path with two-phase commit via the pipeline"} */
+    /**
+     * Navigate to a new path with two-phase commit and transactional navigation
+     * Delegates to NavigationPipeline for orchestration
+     */
+    navigate(path: string, options?: NavigationOptions): Promise<boolean>;
+    /** @codexApi {"parent":"pithy.router.core","name":"back","stability":"stable","signature":"() => void","description":"Go back one entry in browser history"} */
+    /**
+     * Go back in history
+     */
+    back(): void;
+    /** @codexApi {"parent":"pithy.router.core","name":"forward","stability":"stable","signature":"() => void","description":"Go forward one entry in browser history"} */
+    /**
+     * Go forward in history
+     */
+    forward(): void;
+    /** @codexApi {"parent":"pithy.router.core","name":"mount","stability":"stable","signature":"(rootElement: HTMLElement) => void","description":"Mount router to a DOM element and activate outlet routing"} */
+    /**
+     * Mount router to DOM element with outlet management
+     * Automatically finds outlet element and sets up routing
+     *
+     * @param rootElement - Root element containing the router outlet
+     */
+    mount(rootElement: HTMLElement): void;
+    /** @codexApi {"parent":"pithy.router.core","name":"getActiveNavId","stability":"experimental","signature":"() => NavigationId","description":"Get the active navigation ID for outlet manager integration"} */
+    /**
+     * Get the active navigation ID for outlet manager integration
+     */
+    getActiveNavId(): NavigationId;
+    /** @codexApi {"parent":"pithy.router.core","name":"isNavActive","stability":"experimental","signature":"(navId: NavigationId) => boolean","description":"Check if a navigation ID is still active"} */
+    /**
+     * Check if a navigation ID is still active
+     */
+    isNavActive(navId: NavigationId): boolean;
+    /** @codexApi {"parent":"pithy.router.core","name":"prefetchRoute","stability":"experimental","signature":"(href: string, signal: AbortSignal) => Promise<void>","description":"Prefetch route components using shared module cache"} */
+    /**
+     * Prefetch route components (for PrefetchManager integration)
+     * Uses shared module cache from @pithyjs/core for deduplication
+     */
+    prefetchRoute(href: string, signal: AbortSignal): Promise<void>;
+    /** @codexApi {"parent":"pithy.router.core","name":"updateRoutes","stability":"stable","signature":"(newRoutes: RouteNode[], options?: { source?: string }) => Promise<void>","description":"Hot-update routes for HMR, preserving router state"} */
+    /**
+     * Update routes (for HMR support)
+     * Called by HMR manager when route modules are updated
+     * Preserves router state and only re-mounts outlets with new code
+     *
+     * @param newRoutes - Updated route tree from HMR
+     * @param options - Optional configuration
+     */
+    updateRoutes(newRoutes: RouteNode[], _options?: {
+        source?: string;
+    }): Promise<void>;
+    /** @codexApi {"parent":"pithy.router.core","name":"prefetchLoader","stability":"experimental","signature":"(href: string, signal: AbortSignal) => Promise<void>","description":"Prefetch route loader data with guard checks"} */
+    /**
+     * Prefetch route loader data (for PrefetchManager integration)
+     */
+    prefetchLoader(href: string, signal: AbortSignal): Promise<void>;
+    /** @codexApi {"parent":"pithy.router.core","name":"getRouteCacheTTL","stability":"experimental","signature":"(href: string) => Promise<number | undefined>","description":"Get the configured cache TTL for a specific route"} */
+    /**
+     * Get the cache TTL for a specific route (for PrefetchManager integration)
+     * Returns the route's configured cache TTL, or undefined if not configured
+     */
+    getRouteCacheTTL(href: string): Promise<number | undefined>;
+    /** @codexApi {"parent":"pithy.router.core","name":"dispose","stability":"stable","signature":"() => void","description":"Dispose router and clean up all listeners, outlets, and navigations"} */
+    /**
+     * Dispose of the router and clean up all resources
+     *
+     * This method should be called when unmounting the router or destroying the app.
+     * It cleans up:
+     * - Mounted components and their disposers
+     * - Event listeners (popstate, click)
+     * - HMR subscriptions
+     * - Active navigation transactions
+     *
+     * Note: In typical SPA usage, the router lives for the entire page lifetime,
+     * so dispose() is rarely needed. It's mainly useful for:
+     * - Testing (to prevent memory leaks between tests)
+     * - Multiple router instances
+     * - Micro-frontends
+     * - Server-side rendering cleanup
+     */
+    dispose(): void;
+    /**
+     * Save current scroll position to history.state before navigation
+     * Delegates to HistoryManager to avoid code duplication
+     */
+    private saveScrollToHistory;
+    /**
+     * Generate a stable selector for an element
+     */
+    private isNavigationActive;
+    private initializeFromCurrentLocation;
+    private setupHistoryListeners;
+    /**
+     * Set up HMR integration (thin layer pattern)
+     * Delegates to HMRManager which handles Vite HMR subscription
+     * Preserves router state and only re-mounts outlets
+     */
+    private setupHMR;
+    /**
+     * Set up global link interceptor - delegates to LinkInterceptor class
+     */
+    private setupLinkInterceptor;
+    private normalizePath;
+    private parseQueryParams;
+    private updateRouterState;
+    /**
+     * Show route loading in outlet using atomic swap (no overlay, no blank)
+     * Implements the core "replace" policy for forward navigations
+     * NOTE: No View Transition here - loading UI should be plain swap to avoid
+     * the spinner becoming the "transition target" and getting stuck
+     */
+    /**
+     * Snapshot committed DOM for safety belt
+     */
+    private snapshotCommittedOutlet;
+    /**
+     * Restore snapshot if outlet is empty (safety belt)
+     */
+    private restoreSnapshotIfEmpty;
+    /**
+     * Mount the current route using the outlet manager
+     */
+    private mountCurrentRoute;
+    /**
+     * Build segment chain for the current route
+     * @returns Segment chain or null if empty
+     */
+    private buildCurrentSegmentChain;
+    /**
+     * Handle successful route mount
+     * Updates state, snapshots DOM, and manages scroll/focus restoration
+     */
+    private handleMountSuccess;
+    /**
+     * Restore HMR scroll position after successful mount
+     * Uses HMRManager singleton to consume the scroll snapshot
+     */
+    private restoreHMRScrollIfNeeded;
+    /**
+     * Schedule focus management after route mount
+     */
+    private scheduleFocusManagement;
+    /**
+     * Handle failed route mount
+     * Clears loading UI but keeps old view
+     */
+    private handleMountFailure;
+    /**
+     * Create navigation context for pipeline
+     * @private
+     */
+    private createNavigationContext;
+}
+/** @codexApi {"parent":"pithy.router.core","name":"createRouter","stability":"stable","signature":"(routes: RouteNode[], config?: RouterConfig) => Router","description":"Create a router instance with HMR hot-singleton reuse"} */
+/**
+ * Create a new router instance with HMR hot-singleton pattern
+ *
+ * In development with HMR enabled, this function reuses the same router instance
+ * across module updates, preserving router state and avoiding duplicate instances.
+ *
+ * @param routes - Route tree from virtual:pithy/routes.gen
+ * @param config - Router configuration options
+ * @returns Router instance (may be existing instance if HMR is active)
+ */
+export declare function createRouter(routes: RouteNode[], config?: RouterConfig): Router;
+//# sourceMappingURL=router.d.ts.map

package/dist/router/core/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../../src/router/core/router.ts"],"names":[],"mappings":"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"}