@flight-framework/router 0.0.2 → 0.0.4

package/dist/index.d.ts

@@ -27,6 +27,30 @@ interface RouterProviderProps {
     /** Base path for the router (e.g., '/app') */
     basePath?: string;
 }
+/**
+ * Prefetch strategy for Link component
+ *
+ * - 'none': No prefetching (default)
+ * - 'intent': Prefetch on hover or focus (recommended for most cases)
+ * - 'render': Prefetch immediately when link renders
+ * - 'viewport': Prefetch when link enters the viewport (good for mobile)
+ */
+type PrefetchStrategy = 'none' | 'intent' | 'render' | 'viewport';
+/**
+ * Priority level for prefetch requests
+ */
+type PrefetchPriority = 'high' | 'low' | 'auto';
+/**
+ * Options for programmatic prefetching
+ */
+interface PrefetchOptions {
+    /** Priority of the prefetch request */
+    priority?: PrefetchPriority;
+    /** Include data prefetch (loaders) */
+    includeData?: boolean;
+    /** Include module prefetch (JS chunks) */
+    includeModules?: boolean;
+}
 /**
  * Props for Link component
  */
@@ -41,8 +65,17 @@ interface LinkProps {
     target?: string;
     /** Link relationship */
     rel?: string;
-    /** Prefetch the target page */
-    prefetch?: boolean;
+    /**
+     * Prefetch strategy for the target page.
+     *
+     * - `true` or `'intent'`: Prefetch on hover/focus
+     * - `'render'`: Prefetch when link renders
+     * - `'viewport'`: Prefetch when link enters viewport
+     * - `false` or `'none'`: No prefetching (default)
+     *
+     * @default 'none'
+     */
+    prefetch?: boolean | PrefetchStrategy;
     /** Replace current history entry instead of pushing */
     replace?: boolean;
     /** Scroll to top after navigation */
@@ -71,6 +104,51 @@ type RouteParams<T extends string = string> = Record<T, string>;
  * Search params as key-value pairs
  */
 type SearchParams = Record<string, string | string[]>;
+/**
+ * Route definition for automatic route generation
+ */
+interface RouteDefinition {
+    /** Route path pattern (e.g., '/docs/:slug') */
+    path: string;
+    /** Dynamic import for component */
+    component: () => Promise<{
+        default: unknown;
+    }>;
+    /** Dynamic imports for layouts (in order, root first) */
+    layouts?: Array<() => Promise<{
+        default: unknown;
+    }>>;
+    /** Dynamic import for loader function */
+    loader?: () => Promise<{
+        loader: LoaderFunction;
+    }>;
+}
+/**
+ * Loader function signature
+ */
+type LoaderFunction = (context: LoaderContext) => Promise<unknown> | unknown;
+/**
+ * Context passed to loader functions
+ */
+interface LoaderContext {
+    /** Route parameters */
+    params: RouteParams;
+    /** Request object (available on server) */
+    request?: Request;
+    /** URL search params */
+    searchParams: URLSearchParams;
+}
+/**
+ * Route match result
+ */
+interface RouteMatch {
+    /** Matched route definition */
+    route: RouteDefinition;
+    /** Extracted parameters */
+    params: RouteParams;
+    /** Matched path */
+    pathname: string;
+}
 
 /**
  * Router Context and Provider
@@ -88,13 +166,101 @@ declare let RouterProvider: unknown;
 declare let useRouter: () => RouterContextValue;
 
 /**
- * Link Component
+ * @flight-framework/router - Link Component
+ *
+ * Universal client-side navigation link with advanced prefetching support.
+ * Works with React, Vue, Svelte, Solid, and vanilla JavaScript.
  *
- * Client-side navigation link with prefetching support.
- * Works with React or as a vanilla function.
+ * Features:
+ * - Multiple prefetch strategies (none, intent, render, viewport)
+ * - SSR-safe implementation
+ * - Accessibility compliant
+ * - Framework-agnostic core with React adapter
  */
 
+/**
+ * @deprecated Use `prefetch` from '@flight-framework/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 '@flight-framework/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;
+};
+
+/**
+ * @flight-framework/router - PrefetchPageLinks Component
+ *
+ * Renders prefetch link tags for a page. Useful for proactively
+ * prefetching pages based on user behavior (e.g., search results).
+ *
+ * This is the Flight equivalent of React Router's PrefetchPageLinks.
+ */
+
+declare let PrefetchPageLinks: unknown;
+/**
+ * Prefetch multiple pages at once.
+ *
+ * Useful for prefetching a list of search results or related pages.
+ *
+ * @example
+ * ```typescript
+ * // Prefetch top 5 search results
+ * prefetchPages([
+ *     '/products/1',
+ *     '/products/2',
+ *     '/products/3',
+ * ]);
+ * ```
+ */
+declare function prefetchPages(pages: string[], options?: PrefetchOptions): void;
+/**
+ * Prefetch a page when idle.
+ *
+ * Uses requestIdleCallback if available, otherwise falls back
+ * to setTimeout.
+ *
+ * @example
+ * ```typescript
+ * // Prefetch after initial render settles
+ * prefetchWhenIdle('/dashboard');
+ * ```
+ */
+declare function prefetchWhenIdle(page: string, options?: PrefetchOptions): void;
 
 /**
  * Router Hooks
@@ -124,16 +290,6 @@ declare let usePathname: () => string;
  * ```
  */
 declare function navigate(to: string, options?: NavigateOptions): void;
-/**
- * Prefetch a route's assets
- * Creates a prefetch link for the target URL
- *
- * @example
- * ```ts
- * prefetch('/docs'); // Prefetch when user hovers
- * ```
- */
-declare function prefetch(href: string): void;
 /**
  * Match a pathname against a route pattern
  *
@@ -157,5 +313,100 @@ declare function matchRoute(pathname: string, pattern: string): {
  * ```
  */
 declare function parseParams(pathname: string, pattern: string): RouteParams;
+/**
+ * Find the best matching route from a list of route definitions
+ */
+declare function findRoute(pathname: string, routes: RouteDefinition[]): RouteMatch | null;
+/**
+ * Generate a URL from a route pattern and params
+ *
+ * @example
+ * ```ts
+ * generatePath('/docs/:slug', { slug: 'routing' });
+ * // Returns: '/docs/routing'
+ * ```
+ */
+declare function generatePath(pattern: string, params?: RouteParams): string;
+/**
+ * Check if current path matches a pattern
+ */
+declare function isActive(pattern: string): boolean;
+/**
+ * Redirect to a new URL (full page navigation)
+ * Use this for external redirects or when you need to break out of SPA
+ */
+declare function redirect(url: string): never;
+
+/**
+ * @flight-framework/router - Prefetch Utilities
+ *
+ * Universal prefetch system for Flight Framework.
+ * Works across all UI frameworks and runtimes.
+ *
+ * Features:
+ * - Multiple prefetch strategies (intent, render, viewport)
+ * - Priority-based prefetching
+ * - Module and data prefetching
+ * - IntersectionObserver for viewport detection
+ * - SSR-safe implementation
+ */
+
+/**
+ * Prefetch a URL with the specified options.
+ *
+ * This is the main programmatic prefetch API for Flight Framework.
+ * It creates appropriate link elements for prefetching resources.
+ *
+ * @param href - The URL to prefetch
+ * @param options - Prefetch configuration options
+ *
+ * @example
+ * ```typescript
+ * // Basic prefetch
+ * prefetch('/docs');
+ *
+ * // High priority prefetch (for critical navigation paths)
+ * prefetch('/checkout', { priority: 'high' });
+ *
+ * // Prefetch with data loaders
+ * prefetch('/products', { includeData: true });
+ * ```
+ */
+declare function prefetch(href: string, options?: PrefetchOptions): void;
+/**
+ * Prefetch multiple URLs at once.
+ *
+ * @param hrefs - Array of URLs to prefetch
+ * @param options - Prefetch configuration options
+ */
+declare function prefetchAll(hrefs: string[], options?: PrefetchOptions): void;
+/**
+ * Check if a URL has been prefetched.
+ *
+ * @param href - The URL to check
+ * @returns True if the URL has been prefetched
+ */
+declare function isPrefetched(href: string): boolean;
+/**
+ * Clear all prefetch state (useful for testing or memory management).
+ */
+declare function clearPrefetchCache(): void;
+/**
+ * Observe an element for viewport entry and trigger prefetch.
+ *
+ * @param element - The link element to observe
+ * @param href - The URL to prefetch when visible
+ * @returns Cleanup function to stop observing
+ */
+declare function observeForPrefetch(element: Element, href: string): () => void;
+/**
+ * Setup intent-based prefetching for an element.
+ * Prefetches on mouseenter or focus.
+ *
+ * @param element - The link element
+ * @param href - The URL to prefetch
+ * @returns Cleanup function to remove listeners
+ */
+declare function setupIntentPrefetch(element: HTMLElement, href: string): () => void;
 
-export { Link, type LinkProps, type NavigateOptions, type RouteParams, RouterContext, type RouterContextValue, RouterProvider, type RouterProviderProps, type SearchParams, matchRoute, navigate, parseParams, prefetch, 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, findRoute, generatePath, isActive, isPrefetched, matchRoute, navigate, observeForPrefetch, parseParams, prefetch, prefetchAll, prefetchPages, prefetchRoute, prefetchWhenIdle, redirect, setupIntentPrefetch, useLinkProps, useParams, usePathname, useRouter, useSearchParams };