@flight-framework/router 0.0.6 → 0.0.7

package/dist/prefetch-CMmeei6-.d.ts

@@ -0,0 +1,359 @@
+/**
+ * Type definitions for @flight-framework/router
+ */
+/**
+ * Router context value provided to all components
+ */
+interface RouterContextValue {
+    /** Current pathname (e.g., '/docs/routing') */
+    path: string;
+    /** URL search params as object */
+    searchParams: URLSearchParams;
+    /** Navigate to a new path */
+    navigate: (to: string, options?: NavigateOptions) => void;
+    /** Go back in history */
+    back: () => void;
+    /** Go forward in history */
+    forward: () => void;
+}
+/**
+ * Props for RouterProvider component
+ */
+interface RouterProviderProps {
+    /** Child components */
+    children: unknown;
+    /** Initial path for SSR (server passes request URL) */
+    initialPath?: string;
+    /** 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
+ */
+interface LinkProps {
+    /** Target URL path */
+    href: string;
+    /** Child content */
+    children: unknown;
+    /** CSS class name */
+    className?: string;
+    /** Open in new tab */
+    target?: string;
+    /** Link relationship */
+    rel?: string;
+    /**
+     * 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 */
+    scroll?: boolean;
+    /** Aria label for accessibility */
+    'aria-label'?: string;
+    /** Click handler */
+    onClick?: (event: MouseEvent) => void;
+}
+/**
+ * Options for programmatic navigation
+ */
+interface NavigateOptions {
+    /** Replace current history entry instead of pushing */
+    replace?: boolean;
+    /** Scroll to top after navigation */
+    scroll?: boolean;
+    /** State data to pass to the new route */
+    state?: unknown;
+}
+/**
+ * Dynamic route parameters extracted from URL
+ */
+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
+ *
+ * Provides routing state to the component tree.
+ * SSR-safe: works on both server and client.
+ */
+
+/**
+ * Subscribe to router context changes
+ */
+declare function subscribe(callback: (ctx: RouterContextValue) => void): () => void;
+/**
+ * Get current router context value
+ */
+declare function getRouterContext(): RouterContextValue;
+/**
+ * Initialize router (call once at app start)
+ */
+declare function initRouter(options?: {
+    initialPath?: string;
+    basePath?: string;
+}): void;
+/**
+ * React Context for router
+ * Only used if React is available
+ */
+declare let RouterContext: unknown;
+declare let RouterProvider: unknown;
+declare let useRouter: () => RouterContextValue;
+
+/**
+ * @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;
+
+/**
+ * Navigation Utilities
+ *
+ * Programmatic navigation and route matching utilities.
+ */
+
+/**
+ * Navigate programmatically to a new path
+ *
+ * @example
+ * ```ts
+ * navigate('/docs');
+ * navigate('/login', { replace: true });
+ * navigate('/dashboard', { scroll: false, state: { from: '/home' } });
+ * ```
+ */
+declare function navigate(to: string, options?: NavigateOptions): void;
+/**
+ * Match a pathname against a route pattern
+ *
+ * @example
+ * ```ts
+ * matchRoute('/docs/routing', '/docs/:slug');
+ * // Returns: { params: { slug: 'routing' }, matched: true }
+ * ```
+ */
+declare function matchRoute(pathname: string, pattern: string): {
+    matched: boolean;
+    params: RouteParams;
+};
+/**
+ * Parse parameters from a matched route
+ *
+ * @example
+ * ```ts
+ * parseParams('/blog/2024/my-post', '/blog/:year/:slug');
+ * // Returns: { year: '2024', slug: 'my-post' }
+ * ```
+ */
+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 { prefetchWhenIdle as A, getRouterContext as B, subscribe as C, initRouter as D, type LinkProps as L, type NavigateOptions as N, type PrefetchStrategy as P, type RouteParams as R, type SearchParams as S, type RouterContextValue as a, type RouterProviderProps as b, type PrefetchPriority as c, type PrefetchOptions as d, type RouteDefinition as e, type LoaderFunction as f, type LoaderContext as g, type RouteMatch as h, RouterContext as i, RouterProvider as j, PrefetchPageLinks as k, findRoute as l, matchRoute as m, navigate as n, generatePath as o, parseParams as p, isActive as q, redirect as r, prefetch as s, prefetchAll as t, useRouter as u, isPrefetched as v, clearPrefetchCache as w, observeForPrefetch as x, setupIntentPrefetch as y, prefetchPages as z };

package/dist/react/index.d.ts

@@ -0,0 +1,113 @@
+import { L as LinkProps, b as RouterProviderProps, a as RouterContextValue, R as RouteParams } from '../prefetch-CMmeei6-.js';
+export { g as LoaderContext, f as LoaderFunction, N as NavigateOptions, d as PrefetchOptions, c as PrefetchPriority, P as PrefetchStrategy, e as RouteDefinition, h as RouteMatch, S as SearchParams, w as clearPrefetchCache, l as findRoute, o as generatePath, B as getRouterContext, D as initRouter, 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, C as subscribe } from '../prefetch-CMmeei6-.js';
+import React from 'react';
+
+/**
+ * React Link Component
+ *
+ * Provides client-side navigation with prefetching support.
+ * Properly imports React for SSR compatibility.
+ */
+
+/**
+ * Flight Link Component for React
+ *
+ * A drop-in replacement for `<a>` that enables SPA navigation
+ * with optional prefetching strategies.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <Link href="/docs">Documentation</Link>
+ *
+ * // With prefetch on hover/focus (recommended)
+ * <Link href="/docs" prefetch="intent">Docs</Link>
+ *
+ * // 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>
+ * ```
+ */
+declare function Link({ href, children, className, target, rel, prefetch: prefetchProp, replace, scroll, onClick, 'aria-label': ariaLabel, ...props }: LinkProps): React.ReactElement;
+
+/**
+ * React Router Provider
+ *
+ * Provides routing context to React component tree.
+ * Properly imports React for SSR compatibility.
+ */
+
+/**
+ * React Context for router
+ */
+declare const RouterContext: React.Context<RouterContextValue>;
+/**
+ * Hook to access router context
+ */
+declare function useRouter(): RouterContextValue;
+/**
+ * React Router Provider
+ *
+ * Wraps your app to provide routing context.
+ *
+ * @example
+ * ```tsx
+ * import { RouterProvider } from '@flight-framework/router/react';
+ *
+ * function App() {
+ *     return (
+ *         <RouterProvider initialPath="/">
+ *             <YourApp />
+ *         </RouterProvider>
+ *     );
+ * }
+ * ```
+ */
+declare function RouterProvider({ children, initialPath, basePath }: RouterProviderProps): React.ReactElement;
+
+/**
+ * Hook to get current pathname
+ *
+ * Uses React 18+ useSyncExternalStore for optimal performance.
+ *
+ * @example
+ * ```tsx
+ * function Component() {
+ *     const pathname = usePathname();
+ *     return <div>Current path: {pathname}</div>;
+ * }
+ * ```
+ */
+declare function usePathname(): string;
+/**
+ * Hook to get current search params
+ *
+ * @example
+ * ```tsx
+ * function Component() {
+ *     const searchParams = useSearchParams();
+ *     const page = searchParams.get('page') || '1';
+ *     return <div>Page: {page}</div>;
+ * }
+ * ```
+ */
+declare function useSearchParams(): URLSearchParams;
+/**
+ * Hook to get route params
+ *
+ * Note: For dynamic routes like /blog/[slug], the params
+ * must be extracted from the pathname using pattern matching.
+ *
+ * @example
+ * ```tsx
+ * function BlogPost() {
+ *     const params = useParams();
+ *     return <div>Post: {params.slug}</div>;
+ * }
+ * ```
+ */
+declare function useParams(): RouteParams;
+
+export { Link, LinkProps, RouteParams, RouterContext, RouterContextValue, RouterProvider, RouterProviderProps, useParams, usePathname, useRouter, useSearchParams };

package/dist/react/index.js

@@ -0,0 +1,245 @@
+import {
+  clearPrefetchCache,
+  findRoute,
+  generatePath,
+  getRouterContext,
+  initRouter,
+  isActive,
+  isPrefetched,
+  matchRoute,
+  navigate,
+  observeForPrefetch,
+  parseParams,
+  prefetch,
+  prefetchAll,
+  prefetchPages,
+  prefetchWhenIdle,
+  redirect,
+  setupIntentPrefetch,
+  subscribe
+} from "../chunk-MO2HMSZH.js";
+
+// src/react/Link.tsx
+import { useCallback, useEffect, useRef } from "react";
+import { jsx } from "react/jsx-runtime";
+var isBrowser = typeof window !== "undefined";
+function isExternalUrl(href) {
+  if (!href) return false;
+  return href.startsWith("http://") || href.startsWith("https://") || href.startsWith("//") || href.startsWith("mailto:") || href.startsWith("tel:") || href.startsWith("javascript:") || href.startsWith("#");
+}
+function normalizePrefetchStrategy(prefetchProp) {
+  if (prefetchProp === true) return "intent";
+  if (prefetchProp === false || prefetchProp === void 0) return "none";
+  return prefetchProp;
+}
+function handleLinkClick(href, options, event) {
+  if (event && (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)) {
+    return;
+  }
+  if (event && event.button !== 0) {
+    return;
+  }
+  event?.preventDefault();
+  const { navigate: navigate2 } = getRouterContext();
+  navigate2(href, options);
+}
+function Link({
+  href,
+  children,
+  className,
+  target,
+  rel,
+  prefetch: prefetchProp = "none",
+  replace = false,
+  scroll = true,
+  onClick,
+  "aria-label": ariaLabel,
+  ...props
+}) {
+  const linkRef = useRef(null);
+  const isExternal = isExternalUrl(href);
+  const prefetchStrategy = normalizePrefetchStrategy(prefetchProp);
+  const handleClick = useCallback(
+    (e) => {
+      if (onClick) {
+        onClick(e);
+        if (e.defaultPrevented) return;
+      }
+      if (isExternal || target === "_blank") return;
+      handleLinkClick(href, { replace, scroll }, e);
+    },
+    [href, isExternal, target, replace, scroll, onClick]
+  );
+  useEffect(() => {
+    if (isExternal || !isBrowser || prefetchStrategy === "none") {
+      return;
+    }
+    const link = linkRef.current;
+    if (!link) return;
+    switch (prefetchStrategy) {
+      case "render":
+        prefetch(href, { priority: "low" });
+        break;
+      case "viewport":
+        return observeForPrefetch(link, href);
+      case "intent":
+      default:
+        return setupIntentPrefetch(link, href);
+    }
+  }, [href, prefetchStrategy, isExternal]);
+  const computedRel = isExternal && target === "_blank" ? rel || "noopener noreferrer" : rel;
+  return /* @__PURE__ */ jsx(
+    "a",
+    {
+      ref: linkRef,
+      href,
+      className,
+      target,
+      rel: computedRel,
+      "aria-label": ariaLabel,
+      onClick: handleClick,
+      ...props,
+      children
+    }
+  );
+}
+
+// src/react/RouterProvider.tsx
+import { createContext, useContext, useState, useEffect as useEffect2 } from "react";
+import { jsx as jsx2 } from "react/jsx-runtime";
+var isBrowser2 = typeof window !== "undefined";
+function navigateTo(to, options = {}) {
+  if (!isBrowser2) return;
+  const { replace = false, scroll = true, state } = options;
+  if (replace) {
+    window.history.replaceState(state ?? null, "", to);
+  } else {
+    window.history.pushState(state ?? null, "", to);
+  }
+  if (scroll) {
+    window.scrollTo({ top: 0, left: 0, behavior: "instant" });
+  }
+}
+var defaultContext = {
+  path: "/",
+  searchParams: new URLSearchParams(),
+  navigate: navigateTo,
+  back: () => isBrowser2 && window.history.back(),
+  forward: () => isBrowser2 && window.history.forward()
+};
+var RouterContext = createContext(defaultContext);
+function useRouter() {
+  return useContext(RouterContext);
+}
+function RouterProvider({
+  children,
+  initialPath,
+  basePath = ""
+}) {
+  const [routerState, setRouterState] = useState(() => {
+    const path = isBrowser2 ? window.location.pathname : initialPath || "/";
+    const searchParams = isBrowser2 ? new URLSearchParams(window.location.search) : new URLSearchParams();
+    let normalizedPath = path;
+    if (basePath && path.startsWith(basePath)) {
+      normalizedPath = path.slice(basePath.length) || "/";
+    }
+    return {
+      path: normalizedPath,
+      searchParams,
+      navigate: navigateTo,
+      back: () => isBrowser2 && window.history.back(),
+      forward: () => isBrowser2 && window.history.forward()
+    };
+  });
+  useEffect2(() => {
+    if (!isBrowser2) return;
+    const handlePopState = () => {
+      let path = window.location.pathname;
+      if (basePath && path.startsWith(basePath)) {
+        path = path.slice(basePath.length) || "/";
+      }
+      setRouterState((prev) => ({
+        ...prev,
+        path,
+        searchParams: new URLSearchParams(window.location.search)
+      }));
+    };
+    window.addEventListener("popstate", handlePopState);
+    return () => window.removeEventListener("popstate", handlePopState);
+  }, [basePath]);
+  useEffect2(() => {
+    return subscribe((ctx) => {
+      let path = ctx.path;
+      if (basePath && path.startsWith(basePath)) {
+        path = path.slice(basePath.length) || "/";
+      }
+      setRouterState((prev) => ({
+        ...prev,
+        path,
+        searchParams: ctx.searchParams
+      }));
+    });
+  }, [basePath]);
+  return /* @__PURE__ */ jsx2(RouterContext.Provider, { value: routerState, children });
+}
+
+// src/react/hooks.ts
+import { useContext as useContext2, useSyncExternalStore } from "react";
+var isBrowser3 = typeof window !== "undefined";
+function getPathnameSnapshot() {
+  return isBrowser3 ? window.location.pathname : "/";
+}
+function getPathnameServerSnapshot() {
+  return "/";
+}
+function subscribeToPathname(callback) {
+  if (!isBrowser3) return () => {
+  };
+  window.addEventListener("popstate", callback);
+  const unsubscribe = subscribe(callback);
+  return () => {
+    window.removeEventListener("popstate", callback);
+    unsubscribe();
+  };
+}
+function usePathname() {
+  return useSyncExternalStore(
+    subscribeToPathname,
+    getPathnameSnapshot,
+    getPathnameServerSnapshot
+  );
+}
+function useSearchParams() {
+  const { searchParams } = useContext2(RouterContext);
+  return searchParams;
+}
+function useParams() {
+  return {};
+}
+export {
+  Link,
+  RouterContext,
+  RouterProvider,
+  clearPrefetchCache,
+  findRoute,
+  generatePath,
+  getRouterContext,
+  initRouter,
+  isActive,
+  isPrefetched,
+  matchRoute,
+  navigate,
+  observeForPrefetch,
+  parseParams,
+  prefetch,
+  prefetchAll,
+  prefetchPages,
+  prefetchWhenIdle,
+  redirect,
+  setupIntentPrefetch,
+  subscribe,
+  useParams,
+  usePathname,
+  useRouter,
+  useSearchParams
+};