@flight-framework/router 0.0.2 → 0.0.3

package/README.md

@@ -1,137 +1,273 @@
-# @flight-framework/router
-
-Client-side routing primitives for Flight Framework.
-
-## Installation
-
-```bash
-npm install @flight-framework/router
-```
-
-## Usage
-
-### With React
-
-```tsx
-import { RouterProvider, Link, useRouter } from '@flight-framework/router';
-
-// Wrap your app
-function App() {
-    return (
-        <RouterProvider initialPath={url}>
-            <Navigation />
-            <Content />
-        </RouterProvider>
-    );
-}
-
-// Use Link for navigation
-function Navigation() {
-    return (
-        <nav>
-            <Link href="/">Home</Link>
-            <Link href="/docs" prefetch>Docs</Link>
-            <Link href="/about">About</Link>
-        </nav>
-    );
-}
-
-// Use hooks to access router state
-function Content() {
-    const { path, navigate } = useRouter();
-    
-    return (
-        <main>
-            <p>Current path: {path}</p>
-            <button onClick={() => navigate('/dashboard')}>
-                Go to Dashboard
-            </button>
-        </main>
-    );
-}
-```
-
-### Hooks
-
-```tsx
-// Get current path and navigation functions
-const { path, searchParams, navigate, back, forward } = useRouter();
-
-// Get route parameters (from dynamic routes like [slug])
-const { slug } = useParams<{ slug: string }>();
-
-// Get and set search params
-const [searchParams, setSearchParams] = useSearchParams();
-
-// Get current pathname
-const pathname = usePathname();
-```
-
-### Programmatic Navigation
-
-```ts
-import { navigate, prefetch } from '@flight-framework/router';
-
-// Navigate to a path
-navigate('/docs');
-
-// Replace history instead of push
-navigate('/login', { replace: true });
-
-// Navigate without scrolling to top
-navigate('/next-page', { scroll: false });
-
-// Pass state data
-navigate('/dashboard', { state: { from: '/login' } });
-
-// Prefetch a route
-prefetch('/heavy-page');
-```
-
-### Route Matching
-
-```ts
-import { matchRoute, parseParams, generatePath } from '@flight-framework/router';
-
-// Check if a path matches a pattern
-const { matched, params } = matchRoute('/docs/routing', '/docs/:slug');
-// matched: true, params: { slug: 'routing' }
-
-// Parse params from a path
-const params = parseParams('/blog/2024/my-post', '/blog/:year/:slug');
-// { year: '2024', slug: 'my-post' }
-
-// Generate a path from pattern and params
-const path = generatePath('/docs/:slug', { slug: 'api-routes' });
-// '/docs/api-routes'
-```
-
-### Link Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `href` | `string` | required | Target URL path |
-| `prefetch` | `boolean` | `false` | Prefetch target on hover |
-| `replace` | `boolean` | `false` | Replace history entry |
-| `scroll` | `boolean` | `true` | Scroll to top on navigate |
-| `target` | `string` | - | Link target (_blank, etc) |
-| `className` | `string` | - | CSS class |
-
-## SSR Support
-
-The router is SSR-safe. Pass the initial path from your server:
-
-```tsx
-// entry-server.tsx
-export function render(url: string) {
-    return renderToString(
-        <RouterProvider initialPath={url}>
-            <App />
-        </RouterProvider>
-    );
-}
-```
-
-## License
-
-MIT
+# @flight-framework/router
+
+Universal client-side routing primitives for Flight Framework. Zero external dependencies. Works with any UI framework.
+
+## Features
+
+- Multiple prefetch strategies (none, intent, render, viewport)
+- SSR-safe implementation
+- Framework-agnostic with React adapters
+- TypeScript-first design
+- IntersectionObserver for viewport prefetching
+- Backwards compatible API
+
+## Installation
+
+```bash
+npm install @flight-framework/router
+```
+
+## Quick Start
+
+### With React
+
+```tsx
+import { RouterProvider, Link, useRouter } from '@flight-framework/router';
+
+function App() {
+    return (
+        <RouterProvider initialPath={url}>
+            <Navigation />
+            <Content />
+        </RouterProvider>
+    );
+}
+
+function Navigation() {
+    return (
+        <nav>
+            <Link href="/">Home</Link>
+            <Link href="/docs" prefetch="intent">Docs</Link>
+            <Link href="/about">About</Link>
+        </nav>
+    );
+}
+
+function Content() {
+    const { path, navigate } = useRouter();
+
+    return (
+        <main>
+            <p>Current path: {path}</p>
+            <button onClick={() => navigate('/dashboard')}>
+                Go to Dashboard
+            </button>
+        </main>
+    );
+}
+```
+
+## Prefetch Strategies
+
+Flight Router supports multiple prefetch strategies to optimize navigation performance:
+
+| Strategy | Behavior | Best For |
+|----------|----------|----------|
+| `'none'` | No prefetching (default) | Low-priority links |
+| `'intent'` | Prefetch on hover/focus | Most navigation links |
+| `'render'` | Prefetch immediately | Critical paths (checkout) |
+| `'viewport'` | Prefetch when visible | Mobile, infinite scroll |
+
+### Usage Examples
+
+```tsx
+// No prefetching (default)
+<Link href="/docs">Docs</Link>
+<Link href="/docs" prefetch="none">Docs</Link>
+
+// Prefetch on hover/focus (recommended for most cases)
+<Link href="/docs" prefetch="intent">Docs</Link>
+<Link href="/docs" prefetch>Docs</Link>  // boolean true = "intent"
+
+// Prefetch immediately when link renders
+<Link href="/checkout" prefetch="render">Checkout</Link>
+
+// Prefetch when link enters viewport (good for mobile)
+<Link href="/products" prefetch="viewport">Products</Link>
+```
+
+## Programmatic Prefetching
+
+```typescript
+import {
+    prefetch,
+    prefetchAll,
+    prefetchWhenIdle,
+    isPrefetched,
+} from '@flight-framework/router';
+
+// Basic prefetch
+prefetch('/docs');
+
+// High priority prefetch
+prefetch('/checkout', { priority: 'high' });
+
+// Prefetch with data loaders
+prefetch('/products', { includeData: true });
+
+// Prefetch multiple pages
+prefetchAll(['/page1', '/page2', '/page3']);
+
+// Prefetch when browser is idle
+prefetchWhenIdle('/dashboard');
+
+// Check if already prefetched
+if (!isPrefetched('/docs')) {
+    prefetch('/docs');
+}
+```
+
+## PrefetchPageLinks Component
+
+For proactive prefetching based on user behavior (search results, autocomplete):
+
+```tsx
+import { PrefetchPageLinks } from '@flight-framework/router';
+
+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>
+            ))}
+        </>
+    );
+}
+```
+
+## Hooks
+
+```tsx
+// Get current path and navigation functions
+const { path, searchParams, navigate, back, forward } = useRouter();
+
+// Get route parameters (from dynamic routes like [slug])
+const { slug } = useParams<{ slug: string }>();
+
+// Get and set search params
+const [searchParams, setSearchParams] = useSearchParams();
+
+// Get current pathname
+const pathname = usePathname();
+```
+
+## Programmatic Navigation
+
+```typescript
+import { navigate, prefetch } from '@flight-framework/router';
+
+// Navigate to a path
+navigate('/docs');
+
+// Replace history instead of push
+navigate('/login', { replace: true });
+
+// Navigate without scrolling to top
+navigate('/next-page', { scroll: false });
+
+// Pass state data
+navigate('/dashboard', { state: { from: '/login' } });
+```
+
+## Route Matching
+
+```typescript
+import { matchRoute, parseParams, generatePath } from '@flight-framework/router';
+
+// Check if a path matches a pattern
+const { matched, params } = matchRoute('/docs/routing', '/docs/:slug');
+// matched: true, params: { slug: 'routing' }
+
+// Parse params from a path
+const params = parseParams('/blog/2024/my-post', '/blog/:year/:slug');
+// { year: '2024', slug: 'my-post' }
+
+// Generate a path from pattern and params
+const path = generatePath('/docs/:slug', { slug: 'api-routes' });
+// '/docs/api-routes'
+```
+
+## Link Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `href` | `string` | required | Target URL path |
+| `prefetch` | `boolean \| PrefetchStrategy` | `'none'` | Prefetch strategy |
+| `replace` | `boolean` | `false` | Replace history entry |
+| `scroll` | `boolean` | `true` | Scroll to top on navigate |
+| `target` | `string` | - | Link target (_blank, etc) |
+| `className` | `string` | - | CSS class |
+| `aria-label` | `string` | - | Accessibility label |
+
+## Vue Integration
+
+```vue
+<script setup>
+import { useLinkProps } from '@flight-framework/router';
+
+const docsLink = useLinkProps('/docs', { prefetch: 'intent' });
+</script>
+
+<template>
+    <a v-bind="docsLink">Documentation</a>
+</template>
+```
+
+## Vanilla JavaScript
+
+```typescript
+import { createLink, prefetch } from '@flight-framework/router';
+
+const link = createLink({
+    href: '/docs',
+    children: 'Documentation',
+    prefetch: 'intent',
+});
+
+document.body.appendChild(link);
+```
+
+## SSR Support
+
+The router is SSR-safe. Pass the initial path from your server:
+
+```tsx
+// entry-server.tsx
+export function render(url: string) {
+    return renderToString(
+        <RouterProvider initialPath={url}>
+            <App />
+        </RouterProvider>
+    );
+}
+```
+
+## 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
+
+| Feature | Chrome | Firefox | Safari | Edge |
+|---------|--------|---------|--------|------|
+| Prefetch | All | All | All | All |
+| Viewport (IntersectionObserver) | 51+ | 55+ | 12.1+ | 15+ |
+| fetchPriority | 101+ | No | No | 101+ |
+
+## License
+
+MIT