@flight-framework/router 0.0.3 → 0.0.4

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/package.json

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