@flightdev/router 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Flight Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,488 @@
+# @flight-framework/router
+
+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, 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
+- Zero external dependencies
+
+---
+
+## 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 |
+| `'idle'` | Prefetch when browser is idle | Background preloading |
+
+### 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>
+
+// 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
+import {
+    prefetch,
+    prefetchAll,
+    prefetchWhenIdle,
+    isPrefetched,
+    clearPrefetchCache,
+} 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');
+}
+
+// Clear prefetch cache (useful for testing)
+clearPrefetchCache();
+```
+
+---
+
+## Prefetch Queue
+
+Control concurrent prefetch requests to avoid overwhelming the network:
+
+```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
+```
+
+---
+
+## 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();
+
+// 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 Component
+
+### 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 |
+
+### 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>
+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>
+    );
+}
+```
+
+---
+
+## Browser Support
+
+| Feature | Chrome | Firefox | Safari | Edge |
+|---------|--------|---------|--------|------|
+| 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

@@ -0,0 +1,95 @@
+import { L as LinkProps, R as RouteParams, S as SearchParams } from './prefetch-DRp54Q7z.js';
+export { g as LoaderContext, f as LoaderFunction, N as NavigateOptions, d as PrefetchOptions, k as PrefetchPageLinks, c as PrefetchPriority, P as PrefetchStrategy, e as RouteDefinition, h as RouteMatch, i as RouterContext, a as RouterContextValue, j as RouterProvider, b as RouterProviderProps, w as clearPrefetchCache, l as findRoute, o as generatePath, q as isActive, v as isPrefetched, m as matchRoute, n as navigate, x as observeForPrefetch, p as parseParams, s as prefetch, t as prefetchAll, z as prefetchPages, A as prefetchWhenIdle, r as redirect, y as setupIntentPrefetch, u as useRouter } from './prefetch-DRp54Q7z.js';
+
+/**
+ * @flightdev/router - Link Component
+ *
+ * Universal client-side navigation link with advanced prefetching support.
+ * Works with React, Vue, Svelte, Solid, and vanilla JavaScript.
+ *
+ * Features:
+ * - Multiple prefetch strategies (none, intent, render, viewport)
+ * - SSR-safe implementation
+ * - Accessibility compliant
+ * - Framework-agnostic core with React adapter
+ */
+
+/**
+ * @deprecated Use `prefetch` from '@flightdev/router' instead.
+ */
+declare function prefetchRoute(href: string): void;
+declare let Link: unknown;
+/**
+ * Create a link element with SPA navigation support (vanilla JS).
+ *
+ * For Vue, Svelte, Solid, and other frameworks, use this function
+ * or implement framework-specific wrappers.
+ *
+ * @example
+ * ```typescript
+ * const link = createLink({
+ *     href: '/docs',
+ *     children: 'Documentation',
+ *     prefetch: 'intent',
+ * });
+ * document.body.appendChild(link);
+ * ```
+ */
+declare function createLink(props: LinkProps): HTMLAnchorElement;
+/**
+ * Get link props for Vue template usage.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useLinkProps } from '@flightdev/router';
+ * const linkProps = useLinkProps('/docs', { prefetch: 'intent' });
+ * </script>
+ *
+ * <template>
+ *   <a v-bind="linkProps">Documentation</a>
+ * </template>
+ * ```
+ */
+declare function useLinkProps(href: string, options?: Partial<Omit<LinkProps, 'href' | 'children'>>): {
+    href: string;
+    onClick: (e: MouseEvent) => void;
+    onMouseenter?: () => void;
+    onFocus?: () => void;
+};
+
+/**
+ * Router Hooks
+ *
+ * React hooks for accessing router state.
+ * 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 '@flightdev/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;
+
+export { Link, LinkProps, RouteParams, SearchParams, createLink, createUsePathname, getPathnameServerSnapshot, getPathnameSnapshot, prefetchRoute, subscribeToPathname, useLinkProps, useParams, usePathname, useSearchParams };