@flight-framework/router 0.0.3 → 0.0.5

package/README.md

@@ -2,14 +2,40 @@
 
 Universal client-side routing primitives for Flight Framework. Zero external dependencies. Works with any UI framework.
 
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Prefetch Strategies](#prefetch-strategies)
+- [Smart Prefetching](#smart-prefetching)
+- [Intercepting Routes](#intercepting-routes)
+- [Programmatic Prefetching](#programmatic-prefetching)
+- [Prefetch Queue](#prefetch-queue)
+- [React Hooks](#react-hooks)
+- [Programmatic Navigation](#programmatic-navigation)
+- [Route Matching](#route-matching)
+- [Link Component](#link-component)
+- [Framework Integration](#framework-integration)
+- [SSR Support](#ssr-support)
+- [Browser Support](#browser-support)
+- [License](#license)
+
+---
+
 ## Features
 
-- Multiple prefetch strategies (none, intent, render, viewport)
+- Multiple prefetch strategies (none, intent, render, viewport, idle)
+- Network-aware smart prefetching (respects Save-Data and connection speed)
+- Intercepting routes with modal support
+- Prefetch queue with concurrency control
 - SSR-safe implementation
 - Framework-agnostic with React adapters
 - TypeScript-first design
 - IntersectionObserver for viewport prefetching
-- Backwards compatible API
+- Zero external dependencies
+
+---
 
 ## Installation
 
@@ -17,6 +43,8 @@ Universal client-side routing primitives for Flight Framework. Zero external dep
 npm install @flight-framework/router
 ```
 
+---
+
 ## Quick Start
 
 ### With React
@@ -57,6 +85,8 @@ function Content() {
 }
 ```
 
+---
+
 ## Prefetch Strategies
 
 Flight Router supports multiple prefetch strategies to optimize navigation performance:
@@ -67,6 +97,7 @@ Flight Router supports multiple prefetch strategies to optimize navigation perfo
 | `'intent'` | Prefetch on hover/focus | Most navigation links |
 | `'render'` | Prefetch immediately | Critical paths (checkout) |
 | `'viewport'` | Prefetch when visible | Mobile, infinite scroll |
+| `'idle'` | Prefetch when browser is idle | Background preloading |
 
 ### Usage Examples
 
@@ -84,8 +115,129 @@ Flight Router supports multiple prefetch strategies to optimize navigation perfo
 
 // Prefetch when link enters viewport (good for mobile)
 <Link href="/products" prefetch="viewport">Products</Link>
+
+// Prefetch when browser is idle
+<Link href="/settings" prefetch="idle">Settings</Link>
 ```
 
+---
+
+## Smart Prefetching
+
+Network-aware prefetching that respects user preferences and connection quality.
+
+### Features
+
+- Respects `Save-Data` header (users on limited data plans)
+- Detects connection type (2G, 3G, 4G)
+- Configurable minimum network requirements
+- Automatic throttling on slow connections
+
+### API
+
+```typescript
+import {
+    smartPrefetch,
+    shouldSkipPrefetch,
+    canPrefetchOnNetwork,
+} from '@flight-framework/router';
+
+// Respects network conditions automatically
+smartPrefetch('/dashboard');
+
+// Check if prefetching should be skipped
+if (shouldSkipPrefetch()) {
+    console.log('Skipping due to network conditions');
+}
+
+// Custom network requirements
+const canPrefetch = canPrefetchOnNetwork({
+    respectSaveData: true,      // Skip if Save-Data enabled
+    respectSlowNetwork: true,   // Skip on 2G/slow-2G
+    minEffectiveType: '3g',     // Minimum 3G required
+});
+```
+
+### Configuration
+
+```typescript
+smartPrefetch('/page', {
+    respectSaveData: true,      // Default: true
+    respectSlowNetwork: true,   // Default: true
+    minEffectiveType: '3g',     // Default: '3g'
+    priority: 'high',           // Optional priority override
+});
+```
+
+---
+
+## Intercepting Routes
+
+Render routes in modals while preserving URL state. Perfect for photo galleries, user profiles, and detail views.
+
+### React Integration
+
+```tsx
+import {
+    InterceptedRouteProvider,
+    useInterceptedRoute,
+} from '@flight-framework/router';
+
+// Wrap your layout
+function RootLayout({ children }) {
+    return (
+        <InterceptedRouteProvider>
+            {children}
+            <ModalRenderer />
+        </InterceptedRouteProvider>
+    );
+}
+
+// Render intercepted content in a modal
+function ModalRenderer() {
+    const intercepted = useInterceptedRoute();
+
+    if (!intercepted) return null;
+
+    return (
+        <Dialog open onClose={intercepted.dismiss}>
+            <intercepted.Component />
+            <button onClick={intercepted.navigateToPage}>
+                View Full Page
+            </button>
+        </Dialog>
+    );
+}
+```
+
+### Intercepted Route State
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `Component` | `() => unknown` | The component to render |
+| `pathname` | `string` | The intercepted URL path |
+| `params` | `Record<string, string>` | Route parameters |
+| `dismiss()` | `() => void` | Go back (close modal) |
+| `navigateToPage()` | `() => void` | Navigate to actual page |
+
+### Additional Hooks
+
+```typescript
+import {
+    useInterceptedRoute,
+    useSetInterceptedRoute,
+    useIsIntercepting,
+} from '@flight-framework/router';
+
+// Check if currently intercepting
+const isIntercepting = useIsIntercepting();
+
+// Programmatically set intercepted state (for router integration)
+const setIntercepted = useSetInterceptedRoute();
+```
+
+---
+
 ## Programmatic Prefetching
 
 ```typescript
@@ -94,6 +246,7 @@ import {
     prefetchAll,
     prefetchWhenIdle,
     isPrefetched,
+    clearPrefetchCache,
 } from '@flight-framework/router';
 
 // Basic prefetch
@@ -115,33 +268,50 @@ prefetchWhenIdle('/dashboard');
 if (!isPrefetched('/docs')) {
     prefetch('/docs');
 }
+
+// Clear prefetch cache (useful for testing)
+clearPrefetchCache();
 ```
 
-## PrefetchPageLinks Component
+---
 
-For proactive prefetching based on user behavior (search results, autocomplete):
+## Prefetch Queue
 
-```tsx
-import { PrefetchPageLinks } from '@flight-framework/router';
+Control concurrent prefetch requests to avoid overwhelming the network:
 
-function SearchResults({ results }) {
-    return (
-        <>
-            {results.map(result => (
-                <div key={result.id}>
-                    {/* Prefetch as soon as result renders */}
-                    <PrefetchPageLinks page={result.url} />
-                    <Link href={result.url}>{result.title}</Link>
-                </div>
-            ))}
-        </>
-    );
-}
+```typescript
+import { PrefetchQueue } from '@flight-framework/router';
+
+// Create queue with max 3 concurrent prefetches
+const queue = new PrefetchQueue(3);
+
+// Add URLs to queue
+queue.add('/page1');
+queue.add('/page2', { priority: 'high' });
+queue.addAll(['/page3', '/page4', '/page5']);
+
+// Control queue
+queue.pause();   // Stop processing
+queue.resume();  // Continue processing
+queue.clear();   // Remove pending items
+
+// Check state
+console.log(queue.pending);     // Items waiting
+console.log(queue.activeCount); // Currently prefetching
 ```
 
-## Hooks
+---
+
+## React Hooks
 
 ```tsx
+import {
+    useRouter,
+    useParams,
+    useSearchParams,
+    usePathname,
+} from '@flight-framework/router';
+
 // Get current path and navigation functions
 const { path, searchParams, navigate, back, forward } = useRouter();
 
@@ -155,6 +325,8 @@ const [searchParams, setSearchParams] = useSearchParams();
 const pathname = usePathname();
 ```
 
+---
+
 ## Programmatic Navigation
 
 ```typescript
@@ -173,6 +345,8 @@ navigate('/next-page', { scroll: false });
 navigate('/dashboard', { state: { from: '/login' } });
 ```
 
+---
+
 ## Route Matching
 
 ```typescript
@@ -191,7 +365,11 @@ const path = generatePath('/docs/:slug', { slug: 'api-routes' });
 // '/docs/api-routes'
 ```
 
-## Link Props
+---
+
+## Link Component
+
+### Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -203,7 +381,32 @@ const path = generatePath('/docs/:slug', { slug: 'api-routes' });
 | `className` | `string` | - | CSS class |
 | `aria-label` | `string` | - | Accessibility label |
 
-## Vue Integration
+### PrefetchPageLinks Component
+
+For proactive prefetching based on user behavior:
+
+```tsx
+import { PrefetchPageLinks } from '@flight-framework/router';
+
+function SearchResults({ results }) {
+    return (
+        <>
+            {results.map(result => (
+                <div key={result.id}>
+                    <PrefetchPageLinks page={result.url} />
+                    <Link href={result.url}>{result.title}</Link>
+                </div>
+            ))}
+        </>
+    );
+}
+```
+
+---
+
+## Framework Integration
+
+### Vue
 
 ```vue
 <script setup>
@@ -217,7 +420,7 @@ const docsLink = useLinkProps('/docs', { prefetch: 'intent' });
 </template>
 ```
 
-## Vanilla JavaScript
+### Vanilla JavaScript
 
 ```typescript
 import { createLink, prefetch } from '@flight-framework/router';
@@ -231,6 +434,8 @@ const link = createLink({
 document.body.appendChild(link);
 ```
 
+---
+
 ## SSR Support
 
 The router is SSR-safe. Pass the initial path from your server:
@@ -246,19 +451,7 @@ export function render(url: string) {
 }
 ```
 
-## Build Integration
-
-For optimal prefetching, Flight generates a route manifest during build that maps routes to their JS modules. This enables `prefetch` to preload the correct chunks.
-
-```typescript
-// flight.config.ts
-export default defineConfig({
-    router: {
-        // Generates __FLIGHT_MANIFEST__ at build time
-        generateManifest: true,
-    },
-});
-```
+---
 
 ## Browser Support
 
@@ -266,8 +459,30 @@ export default defineConfig({
 |---------|--------|---------|--------|------|
 | Prefetch | All | All | All | All |
 | Viewport (IntersectionObserver) | 51+ | 55+ | 12.1+ | 15+ |
+| Network Information API | 61+ | No | No | 79+ |
+| requestIdleCallback | 47+ | 55+ | No | 79+ |
 | fetchPriority | 101+ | No | No | 101+ |
 
+Features gracefully degrade when APIs are unavailable.
+
+---
+
+## TypeScript
+
+Full TypeScript support with exported types:
+
+```typescript
+import type {
+    PrefetchStrategy,
+    PrefetchOptions,
+    SmartPrefetchOptions,
+    InterceptedRouteState,
+    InterceptedRouteContextValue,
+} from '@flight-framework/router';
+```
+
+---
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -266,9 +266,32 @@ declare function prefetchWhenIdle(page: string, options?: PrefetchOptions): void
  * Router Hooks
  *
  * React hooks for accessing router state.
- * These require React to be available.
+ * Uses useSyncExternalStore for concurrent-safe external state (2026 best practice).
  */
 
+/**
+ * Subscribe to pathname changes - for useSyncExternalStore
+ */
+declare function subscribeToPathname(callback: () => void): () => void;
+/**
+ * Get current pathname snapshot - for useSyncExternalStore
+ */
+declare function getPathnameSnapshot(): string;
+/**
+ * Get server snapshot - for useSyncExternalStore SSR
+ */
+declare function getPathnameServerSnapshot(): string;
+/**
+ * Create usePathname hook with provided React instance
+ * This pattern ensures proper bundler support for React hooks
+ *
+ * @example
+ * import { useSyncExternalStore } from 'react';
+ * import { createUsePathname } from '@flight-framework/router';
+ *
+ * const usePathname = createUsePathname(useSyncExternalStore);
+ */
+declare function createUsePathname(useSyncExternalStore: <T>(subscribe: (onStoreChange: () => void) => () => void, getSnapshot: () => T, getServerSnapshot?: () => T) => T): () => string;
 declare let useParams: <T extends RouteParams = RouteParams>() => T;
 declare let useSearchParams: () => [URLSearchParams, (params: SearchParams | URLSearchParams) => void];
 declare let usePathname: () => string;
@@ -409,4 +432,4 @@ declare function observeForPrefetch(element: Element, href: string): () => void;
  */
 declare function setupIntentPrefetch(element: HTMLElement, href: string): () => void;
 
-export { Link, type LinkProps, type LoaderContext, type LoaderFunction, type NavigateOptions, type PrefetchOptions, PrefetchPageLinks, type PrefetchPriority, type PrefetchStrategy, type RouteDefinition, type RouteMatch, type RouteParams, RouterContext, type RouterContextValue, RouterProvider, type RouterProviderProps, type SearchParams, clearPrefetchCache, createLink, findRoute, generatePath, isActive, isPrefetched, matchRoute, navigate, observeForPrefetch, parseParams, prefetch, prefetchAll, prefetchPages, prefetchRoute, prefetchWhenIdle, redirect, setupIntentPrefetch, useLinkProps, useParams, usePathname, useRouter, useSearchParams };
+export { Link, type LinkProps, type LoaderContext, type LoaderFunction, type NavigateOptions, type PrefetchOptions, PrefetchPageLinks, type PrefetchPriority, type PrefetchStrategy, type RouteDefinition, type RouteMatch, type RouteParams, RouterContext, type RouterContextValue, RouterProvider, type RouterProviderProps, type SearchParams, clearPrefetchCache, createLink, createUsePathname, findRoute, generatePath, getPathnameServerSnapshot, getPathnameSnapshot, isActive, isPrefetched, matchRoute, navigate, observeForPrefetch, parseParams, prefetch, prefetchAll, prefetchPages, prefetchRoute, prefetchWhenIdle, redirect, setupIntentPrefetch, subscribeToPathname, useLinkProps, useParams, usePathname, useRouter, useSearchParams };

package/dist/index.js

@@ -39,6 +39,63 @@ function navigateTo(to, options = {}) {
     window.scrollTo({ top: 0, left: 0, behavior: "instant" });
   }
 }
+function initRouter(options = {}) {
+  const { initialPath, basePath = "" } = options;
+  let path;
+  let searchParams;
+  if (isBrowser) {
+    path = window.location.pathname;
+    searchParams = new URLSearchParams(window.location.search);
+  } else {
+    path = initialPath || "/";
+    searchParams = new URLSearchParams();
+  }
+  if (basePath && path.startsWith(basePath)) {
+    path = path.slice(basePath.length) || "/";
+  }
+  currentContext = {
+    path,
+    searchParams,
+    navigate: navigateTo,
+    back: () => isBrowser && window.history.back(),
+    forward: () => isBrowser && window.history.forward()
+  };
+  if (isBrowser) {
+    window.addEventListener("popstate", () => {
+      updateContext({
+        path: window.location.pathname,
+        searchParams: new URLSearchParams(window.location.search)
+      });
+    });
+    const originalPushState = history.pushState.bind(history);
+    const originalReplaceState = history.replaceState.bind(history);
+    history.pushState = function(state, unused, url) {
+      originalPushState(state, unused, url);
+      if (url) {
+        const newUrl = new URL(url.toString(), window.location.origin);
+        updateContext({
+          path: newUrl.pathname,
+          searchParams: newUrl.searchParams
+        });
+      }
+    };
+    history.replaceState = function(state, unused, url) {
+      originalReplaceState(state, unused, url);
+      if (url) {
+        const newUrl = new URL(url.toString(), window.location.origin);
+        updateContext({
+          path: newUrl.pathname,
+          searchParams: newUrl.searchParams
+        });
+      }
+    };
+  }
+}
+var initialized = false;
+if (isBrowser && !initialized) {
+  initialized = true;
+  initRouter();
+}
 var RouterContext = null;
 var RouterProvider = null;
 var useRouter = getRouterContext;
@@ -493,15 +550,65 @@ function prefetchWhenIdle(page, options = {}) {
 
 // src/hooks.ts
 var isBrowser5 = typeof window !== "undefined";
+var pathSubscribers = /* @__PURE__ */ new Set();
+function notifyPathChange() {
+  pathSubscribers.forEach((fn) => fn());
+}
+var historyIntercepted = false;
+function interceptHistory() {
+  if (!isBrowser5 || historyIntercepted) return;
+  historyIntercepted = true;
+  const originalPushState = history.pushState.bind(history);
+  const originalReplaceState = history.replaceState.bind(history);
+  history.pushState = function(state, unused, url) {
+    originalPushState(state, unused, url);
+    notifyPathChange();
+  };
+  history.replaceState = function(state, unused, url) {
+    originalReplaceState(state, unused, url);
+    notifyPathChange();
+  };
+  window.addEventListener("popstate", notifyPathChange);
+}
+if (isBrowser5) {
+  interceptHistory();
+}
+function subscribeToPathname(callback) {
+  pathSubscribers.add(callback);
+  return () => pathSubscribers.delete(callback);
+}
+function getPathnameSnapshot() {
+  return isBrowser5 ? window.location.pathname : "/";
+}
+function getPathnameServerSnapshot() {
+  return "/";
+}
+function createUsePathname(useSyncExternalStore) {
+  return function usePathname2() {
+    return useSyncExternalStore(
+      subscribeToPathname,
+      getPathnameSnapshot,
+      getPathnameServerSnapshot
+    );
+  };
+}
 var useParams = () => ({});
 var useSearchParams = () => [new URLSearchParams(), () => {
 }];
-var usePathname = () => "/";
+var usePathname = () => {
+  if (isBrowser5) {
+    return window.location.pathname;
+  }
+  return "/";
+};
 if (typeof globalThis !== "undefined") {
   try {
     const React = globalThis.React;
+    if (React?.useSyncExternalStore) {
+      usePathname = createUsePathname(React.useSyncExternalStore);
+    }
     if (React?.useState) {
-      const { useState, useEffect, useCallback, useMemo } = React;
+      const { useState, useEffect, useCallback } = React;
       useParams = function useFlightParams() {
         const [params, setParams] = useState({});
         useEffect(() => {
@@ -545,19 +652,6 @@ if (typeof globalThis !== "undefined") {
         }, []);
         return [searchParams, setSearchParams];
       };
-      usePathname = function useFlightPathname() {
-        const { path } = getRouterContext();
-        const [pathname, setPathname] = useState(path);
-        useEffect(() => {
-          if (!isBrowser5) return;
-          const handleChange = () => {
-            setPathname(window.location.pathname);
-          };
-          window.addEventListener("popstate", handleChange);
-          return () => window.removeEventListener("popstate", handleChange);
-        }, []);
-        return pathname;
-      };
     }
   } catch {
   }
@@ -644,8 +738,11 @@ export {
   RouterProvider,
   clearPrefetchCache,
   createLink,
+  createUsePathname,
   findRoute,
   generatePath,
+  getPathnameServerSnapshot,
+  getPathnameSnapshot,
   isActive,
   isPrefetched,
   matchRoute,
@@ -659,6 +756,7 @@ export {
   prefetchWhenIdle,
   redirect,
   setupIntentPrefetch,
+  subscribeToPathname,
   useLinkProps,
   useParams,
   usePathname,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@flight-framework/router",
-    "version": "0.0.3",
+    "version": "0.0.5",
     "description": "Agnostic client-side routing primitives for Flight Framework",
     "type": "module",
     "main": "./dist/index.js",
@@ -45,4 +45,4 @@
             "optional": true
         }
     }
-}
+}