@fictjs/router 0.2.2 → 0.3.0

package/dist/index.d.cts

@@ -1,3 +1,1137 @@
-declare const Router: () => void;
+import { Component, FictNode, JSX, StyleProp } from '@fictjs/runtime';
 
-export { Router };
+/**
+ * @fileoverview Core type definitions for @fictjs/router
+ *
+ * This module defines the fundamental types used throughout the router.
+ * Designed to integrate seamlessly with Fict's reactive system.
+ */
+
+/**
+ * Represents a location in the router.
+ * Similar to window.location but with reactive support.
+ */
+interface Location {
+    /** The pathname portion of the URL (e.g., "/users/123") */
+    pathname: string;
+    /** The search/query portion of the URL (e.g., "?page=1") */
+    search: string;
+    /** The hash portion of the URL (e.g., "#section") */
+    hash: string;
+    /** State associated with this location */
+    state: unknown;
+    /** Unique key for this location entry */
+    key: string;
+}
+/**
+ * Target for navigation - can be a string path or a partial location object
+ */
+type To = string | Partial<Location>;
+/**
+ * Navigation intent type
+ */
+type NavigationIntent = 'initial' | 'navigate' | 'native' | 'preload';
+/**
+ * Route parameters extracted from the URL
+ */
+type Params<Key extends string = string> = Readonly<Record<Key, string | undefined>>;
+/**
+ * Search parameters from the query string
+ */
+type SearchParams = URLSearchParams;
+/**
+ * Match filter for validating route parameters
+ */
+type MatchFilter<T = string> = RegExp | readonly T[] | ((value: string) => boolean);
+/**
+ * Match filters for route parameters
+ */
+type MatchFilters<P extends string = string> = Partial<Record<P, MatchFilter>>;
+/**
+ * Props passed to route components
+ */
+interface RouteComponentProps<P extends string = string> {
+    /** Route parameters */
+    params: Params<P>;
+    /** Current location */
+    location: Location;
+    /** Preloaded data (if preload function is defined) */
+    data?: unknown;
+    /** Children routes rendered via <Outlet /> */
+    children?: FictNode;
+    /** Allow additional properties for component extensibility */
+    [key: string]: unknown;
+}
+/**
+ * Preload function arguments
+ */
+interface PreloadArgs<P extends string = string> {
+    /** Route parameters */
+    params: Params<P>;
+    /** Current location */
+    location: Location;
+    /** Navigation intent */
+    intent: NavigationIntent;
+}
+/**
+ * Preload function type
+ */
+type PreloadFunction<T = unknown, P extends string = string> = (args: PreloadArgs<P>) => T | Promise<T>;
+/**
+ * Route definition - user-facing configuration
+ */
+interface RouteDefinition<P extends string = string> {
+    /** Path pattern (e.g., "/users/:id", "/items/:id?") */
+    path?: string;
+    /** Component to render for this route */
+    component?: Component<RouteComponentProps<P>>;
+    /** Element to render (alternative to component) */
+    element?: FictNode;
+    /** Preload function for data loading */
+    preload?: PreloadFunction<unknown, P>;
+    /** Nested child routes */
+    children?: RouteDefinition[];
+    /** Parameter validation filters */
+    matchFilters?: MatchFilters<P>;
+    /** Whether this is an index route */
+    index?: boolean;
+    /** Route key for caching/optimization */
+    key?: string;
+    /** Catch-all error boundary element */
+    errorElement?: FictNode;
+    /** Loading fallback element */
+    loadingElement?: FictNode;
+}
+/**
+ * Props for the Route component (JSX-based definition)
+ */
+interface RouteProps<P extends string = string> extends Omit<RouteDefinition<P>, 'children'> {
+    /** JSX children (nested Route components) */
+    children?: FictNode;
+}
+/**
+ * Result of matching a route against a location
+ */
+interface RouteMatch<P extends string = string> {
+    /** The matched route definition */
+    route: RouteDefinition<P>;
+    /** The matched portion of the pathname */
+    pathname: string;
+    /** Extracted parameters */
+    params: Params<P>;
+    /** The pattern that matched */
+    pattern: string;
+}
+/**
+ * Internal compiled route with matcher function
+ */
+interface CompiledRoute {
+    /** Original route definition */
+    route: RouteDefinition;
+    /** Normalized path pattern */
+    pattern: string;
+    /** Matcher function */
+    matcher: (pathname: string) => RouteMatch | null;
+    /** Route score for ranking */
+    score: number;
+    /** Child compiled routes */
+    children?: CompiledRoute[];
+    /** Unique key for this route */
+    key: string;
+}
+/**
+ * Branch of routes (for nested route matching)
+ */
+interface RouteBranch {
+    /** Routes in this branch from root to leaf */
+    routes: CompiledRoute[];
+    /** Combined score for the branch */
+    score: number;
+    /** Matcher for the entire branch */
+    matcher: (pathname: string) => RouteMatch[] | null;
+}
+/**
+ * Options for navigation
+ */
+interface NavigateOptions {
+    /** Replace current history entry instead of pushing */
+    replace?: boolean | undefined;
+    /** State to pass with the navigation */
+    state?: unknown;
+    /** Scroll to top after navigation */
+    scroll?: boolean | undefined;
+    /** Resolve path relative to current route */
+    relative?: 'route' | 'path' | undefined;
+}
+/**
+ * Navigation function type
+ */
+interface NavigateFunction {
+    (to: To, options?: NavigateOptions): void;
+    (delta: number): void;
+}
+/**
+ * Navigation state during transitions
+ */
+interface Navigation {
+    /** Current navigation state */
+    state: 'idle' | 'loading' | 'submitting';
+    /** Target location (if loading) */
+    location?: Location;
+    /** Form data (if submitting) */
+    formData?: FormData;
+    /** Form action (if submitting) */
+    formAction?: string;
+    /** Form method (if submitting) */
+    formMethod?: string;
+}
+/**
+ * Router context value
+ */
+interface RouterContextValue {
+    /** Current location (reactive) */
+    location: () => Location;
+    /** Route parameters (reactive) */
+    params: () => Params;
+    /** Current matches (reactive) */
+    matches: () => RouteMatch[];
+    /** Navigate function */
+    navigate: NavigateFunction;
+    /** Whether currently routing */
+    isRouting: () => boolean;
+    /** Pending navigation target (if routing) */
+    pendingLocation: () => Location | null;
+    /** Base path for the router */
+    base: string;
+    /** Resolve a path relative to the current route */
+    resolvePath: (to: To) => string;
+}
+/**
+ * Route context value (for nested routes)
+ */
+interface RouteContextValue {
+    /** The current route match */
+    match: () => RouteMatch | undefined;
+    /** Preloaded data */
+    data: () => unknown;
+    /** Route error (if any) */
+    error?: () => unknown;
+    /** Outlet function to render child route */
+    outlet: () => FictNode;
+    /** Parent route context */
+    parent?: RouteContextValue;
+    /** Resolve path relative to this route */
+    resolvePath: (to: To) => string;
+}
+/**
+ * History action type
+ */
+type HistoryAction = 'POP' | 'PUSH' | 'REPLACE';
+/**
+ * History listener callback
+ */
+type HistoryListener = (update: {
+    action: HistoryAction;
+    location: Location;
+}) => void;
+/**
+ * History interface (browser, hash, or memory)
+ */
+interface History {
+    /** Current action */
+    readonly action: HistoryAction;
+    /** Current location */
+    readonly location: Location;
+    /** Push a new entry */
+    push(to: To, state?: unknown): void;
+    /** Replace the current entry */
+    replace(to: To, state?: unknown): void;
+    /** Go forward or backward */
+    go(delta: number): void;
+    /** Go back one entry */
+    back(): void;
+    /** Go forward one entry */
+    forward(): void;
+    /** Listen for location changes */
+    listen(listener: HistoryListener): () => void;
+    /** Create an href from a To value */
+    createHref(to: To): string;
+    /** Block navigation */
+    block(blocker: Blocker): () => void;
+}
+/**
+ * Blocker function for preventing navigation
+ */
+type Blocker = (tx: {
+    action: HistoryAction;
+    location: Location;
+    retry: () => void;
+}) => void;
+/**
+ * Arguments passed to beforeLeave handlers
+ */
+interface BeforeLeaveEventArgs {
+    /** Target location */
+    to: Location;
+    /** Current location */
+    from: Location;
+    /** Whether this was prevented */
+    defaultPrevented: boolean;
+    /** Prevent the navigation */
+    preventDefault: () => void;
+    /** Retry the navigation */
+    retry: (force?: boolean) => void;
+}
+/**
+ * BeforeLeave handler function
+ */
+type BeforeLeaveHandler = (e: BeforeLeaveEventArgs) => void | Promise<void>;
+/**
+ * Submission state
+ */
+interface Submission<T = unknown> {
+    /** Unique submission key */
+    key: string;
+    /** Form data being submitted */
+    formData: FormData;
+    /** Submission state */
+    state: 'submitting' | 'loading' | 'idle';
+    /** Result data */
+    result?: T;
+    /** Error if submission failed */
+    error?: unknown;
+    /** Clear the submission */
+    clear: () => void;
+    /** Retry the submission */
+    retry: () => void;
+}
+/**
+ * Action function type
+ */
+type ActionFunction<T = unknown> = (formData: FormData, args: {
+    params: Params;
+    request: Request;
+}) => T | Promise<T>;
+/**
+ * Action object returned by createAction
+ */
+interface Action<T = unknown> {
+    /** Action URL */
+    url: string;
+    /** Submit the action */
+    submit: (formData: FormData) => Promise<T>;
+    /** Action name */
+    name?: string;
+}
+/**
+ * Query function type
+ */
+type QueryFunction<T = unknown, Args extends unknown[] = unknown[]> = (...args: Args) => T | Promise<T>;
+/**
+ * Query cache entry
+ */
+interface QueryCacheEntry<T = unknown> {
+    /** Timestamp when cached */
+    timestamp: number;
+    /** Cached promise */
+    promise: Promise<T>;
+    /** Resolved result */
+    result?: T;
+    /** Intent when fetched */
+    intent: NavigationIntent;
+}
+/**
+ * Router configuration options
+ */
+interface RouterOptions {
+    /** Base path for the router */
+    base?: string;
+    /** Initial location (for SSR) */
+    url?: string;
+    /** History implementation to use */
+    history?: History;
+    /** Data preloaded on server */
+    hydrationData?: {
+        loaderData?: Record<string, unknown>;
+        actionData?: Record<string, unknown>;
+    };
+}
+/**
+ * Memory router options
+ */
+interface MemoryRouterOptions extends RouterOptions {
+    /** Initial entries in the history stack */
+    initialEntries?: string[];
+    /** Initial index in the history stack */
+    initialIndex?: number;
+}
+/**
+ * Hash router options
+ */
+interface HashRouterOptions extends RouterOptions {
+    /** Hash type: "slash" for /#/path, "noslash" for /#path */
+    hashType?: 'slash' | 'noslash';
+}
+
+/**
+ * @fileoverview Router components for @fictjs/router
+ *
+ * This module provides the main Router, Routes, Route, and Outlet components.
+ * These integrate with Fict's reactive system for fine-grained updates.
+ */
+
+interface BaseRouterProps {
+    children?: FictNode;
+    base?: string;
+}
+interface BrowserRouterProps extends BaseRouterProps, RouterOptions {
+}
+interface HashRouterProps extends BaseRouterProps, HashRouterOptions {
+}
+interface MemoryRouterProps extends BaseRouterProps, MemoryRouterOptions {
+}
+interface StaticRouterProps extends BaseRouterProps {
+    url: string;
+}
+/**
+ * Browser Router - uses the History API
+ */
+declare function Router(props: BrowserRouterProps & {
+    children?: FictNode;
+}): FictNode;
+/**
+ * Hash Router - uses the URL hash
+ */
+declare function HashRouter(props: HashRouterProps & {
+    children?: FictNode;
+}): FictNode;
+/**
+ * Memory Router - keeps history in memory (for testing/SSR)
+ */
+declare function MemoryRouter(props: MemoryRouterProps & {
+    children?: FictNode;
+}): FictNode;
+/**
+ * Static Router - for server-side rendering
+ */
+declare function StaticRouter(props: StaticRouterProps & {
+    children?: FictNode;
+}): FictNode;
+interface RoutesProps {
+    children?: FictNode;
+}
+/**
+ * Routes component - renders the matched route
+ */
+declare function Routes(props: RoutesProps): FictNode;
+interface RouteJSXProps {
+    path?: string | undefined;
+    component?: Component<any> | undefined;
+    element?: FictNode;
+    children?: FictNode;
+    index?: boolean | undefined;
+    key?: string | undefined;
+    preload?: ((args: {
+        params: Params;
+        location: Location;
+        intent: 'initial' | 'navigate' | 'native' | 'preload';
+    }) => unknown | Promise<unknown>) | undefined;
+    errorElement?: FictNode;
+    loadingElement?: FictNode;
+}
+/**
+ * Route component - defines a route
+ * This is a configuration component, it doesn't render anything directly.
+ */
+declare function Route(_props: RouteJSXProps): FictNode;
+/**
+ * Outlet component - renders the child route
+ */
+declare function Outlet(): FictNode;
+interface NavigateComponentProps {
+    to: To;
+    replace?: boolean;
+    state?: unknown;
+}
+/**
+ * Navigate component - declarative navigation
+ * Navigates immediately when rendered.
+ */
+declare function Navigate(props: NavigateComponentProps): FictNode;
+interface RedirectProps {
+    /** Target path to redirect to */
+    to: To;
+    /** Path pattern that triggers this redirect (optional, for declarative redirects) */
+    from?: string;
+    /** State to pass with the redirect */
+    state?: unknown;
+    /** Whether to replace or push to history (default: true) */
+    push?: boolean;
+}
+/**
+ * Redirect component - declarative redirect
+ *
+ * Unlike Navigate, Redirect is specifically for redirect scenarios:
+ * - Always replaces by default (unless push=true)
+ * - Can be used in route definitions with a `from` pattern
+ * - Semantically indicates a redirect rather than navigation
+ *
+ * @example
+ * ```tsx
+ * // Basic redirect (replaces current entry)
+ * <Redirect to="/login" />
+ *
+ * // Redirect with state
+ * <Redirect to="/login" state={{ from: location.pathname }} />
+ *
+ * // Push instead of replace
+ * <Redirect to="/new-page" push />
+ *
+ * // In route definitions (redirect old paths)
+ * <Route path="/old-path" element={<Redirect to="/new-path" />} />
+ * ```
+ */
+declare function Redirect(props: RedirectProps): FictNode;
+/**
+ * Create routes from a configuration array (alternative to JSX)
+ */
+declare function createRoutes(routes: RouteDefinition[]): RouteDefinition[];
+/**
+ * Create a router with programmatic routes
+ */
+declare function createRouter(routes: RouteDefinition[], options?: RouterOptions): {
+    Router: Component<{
+        children?: FictNode;
+    }>;
+};
+
+/**
+ * @fileoverview Link components for @fictjs/router
+ *
+ * This module provides Link and NavLink components for declarative navigation.
+ * Integrates with Fict's reactive system for active state tracking.
+ */
+
+type CSSProperties = StyleProp;
+interface LinkProps extends Omit<JSX.IntrinsicElements['a'], 'href'> {
+    /** Navigation target */
+    to: To;
+    /** Replace history entry instead of pushing */
+    replace?: boolean;
+    /** State to pass with navigation */
+    state?: unknown;
+    /** Scroll to top after navigation */
+    scroll?: boolean;
+    /** Relative path resolution mode */
+    relative?: 'route' | 'path';
+    /** Force full page reload */
+    reloadDocument?: boolean;
+    /** Preload behavior */
+    prefetch?: 'none' | 'intent' | 'render';
+    /** Prevent navigation (render as text) */
+    disabled?: boolean;
+    /** Custom click handler (called before navigation) */
+    onClick?: (event: MouseEvent) => void;
+    children?: FictNode;
+}
+/**
+ * Link component for navigation
+ *
+ * @example
+ * ```tsx
+ * <Link to="/about">About</Link>
+ * <Link to="/users/123" replace>View User</Link>
+ * <Link to={{ pathname: "/search", search: "?q=test" }}>Search</Link>
+ * ```
+ */
+declare function Link(props: LinkProps): FictNode;
+interface NavLinkRenderProps {
+    /** Whether the link is active */
+    isActive: boolean;
+    /** Whether a navigation to this link is pending */
+    isPending: boolean;
+    /** Whether a view transition is in progress */
+    isTransitioning: boolean;
+}
+interface NavLinkProps extends Omit<LinkProps, 'className' | 'style' | 'children'> {
+    /** Class name - can be a function that receives render props */
+    className?: string | ((props: NavLinkRenderProps) => string | undefined);
+    /** Style - can be a function that receives render props */
+    style?: CSSProperties | ((props: NavLinkRenderProps) => CSSProperties | undefined);
+    /** Children - can be a function that receives render props */
+    children?: FictNode | ((props: NavLinkRenderProps) => FictNode);
+    /** Only match if path is exactly equal (not a prefix) */
+    end?: boolean;
+    /** Case-sensitive matching */
+    caseSensitive?: boolean;
+    /** Custom active class name */
+    activeClassName?: string;
+    /** Custom pending class name */
+    pendingClassName?: string;
+    /** Custom active style */
+    activeStyle?: CSSProperties;
+    /** Custom pending style */
+    pendingStyle?: CSSProperties;
+    /** aria-current value when active */
+    'aria-current'?: 'page' | 'step' | 'location' | 'date' | 'time' | 'true' | 'false';
+}
+/**
+ * NavLink component for navigation with active state
+ *
+ * @example
+ * ```tsx
+ * <NavLink to="/about" activeClassName="active">About</NavLink>
+ *
+ * <NavLink to="/users" end>
+ *   {({ isActive }) => (
+ *     <span className={isActive ? 'active' : ''}>Users</span>
+ *   )}
+ * </NavLink>
+ *
+ * <NavLink
+ *   to="/dashboard"
+ *   className={({ isActive }) => isActive ? 'nav-active' : 'nav-link'}
+ * >
+ *   Dashboard
+ * </NavLink>
+ * ```
+ */
+declare function NavLink(props: NavLinkProps): FictNode;
+interface FormProps extends Omit<JSX.IntrinsicElements['form'], 'action' | 'method'> {
+    /** Form action URL */
+    action?: string;
+    /** HTTP method */
+    method?: 'get' | 'post' | 'put' | 'patch' | 'delete';
+    /** Replace history entry */
+    replace?: boolean;
+    /** Relative path resolution */
+    relative?: 'route' | 'path';
+    /** Prevent navigation */
+    preventScrollReset?: boolean;
+    /** Navigate on submit */
+    navigate?: boolean;
+    /** Fetch mode */
+    fetcherKey?: string;
+    children?: FictNode;
+    onSubmit?: (event: SubmitEvent) => void;
+}
+/**
+ * Form component for action submissions
+ *
+ * @example
+ * ```tsx
+ * <Form action="/api/submit" method="post">
+ *   <input name="email" type="email" />
+ *   <button type="submit">Submit</button>
+ * </Form>
+ * ```
+ */
+declare function Form(props: FormProps): FictNode;
+
+/**
+ * Use the router context
+ */
+declare function useRouter(): RouterContextValue;
+/**
+ * Use the route context
+ */
+declare function useRoute(): RouteContextValue;
+/**
+ * Get the navigate function
+ */
+declare function useNavigate(): NavigateFunction;
+/**
+ * Get the current location
+ */
+declare function useLocation(): () => Location;
+/**
+ * Get the current route parameters
+ */
+declare function useParams<P extends string = string>(): () => Params<P>;
+/**
+ * Get the current search parameters
+ */
+declare function useSearchParams(): [
+    () => URLSearchParams,
+    (params: URLSearchParams | Record<string, string>, options?: {
+        replace?: boolean;
+    }) => void
+];
+/**
+ * Get the current route matches
+ */
+declare function useMatches(): () => RouteMatch[];
+/**
+ * Check if currently routing (loading new route)
+ */
+declare function useIsRouting(): () => boolean;
+/**
+ * Get the pending navigation location (if any)
+ */
+declare function usePendingLocation(): () => Location | null;
+/**
+ * Get the preloaded data for the current route
+ */
+declare function useRouteData<T = unknown>(): () => T | undefined;
+/**
+ * Get route error (for use in errorElement components)
+ * This hook is used within an error boundary to access the caught error.
+ * It returns errors from both preload phase (via route context) and
+ * render phase (via ErrorBoundary context).
+ *
+ * @example
+ * ```tsx
+ * function RouteErrorPage() {
+ *   const error = useRouteError()
+ *   return (
+ *     <div>
+ *       <h1>Error</h1>
+ *       <p>{error?.message || 'Unknown error'}</p>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+declare function useRouteError(): unknown;
+/**
+ * Resolve a path relative to the current route
+ */
+declare function useResolvedPath(to: To | (() => To)): () => string;
+/**
+ * Check if a path matches the current location
+ */
+declare function useMatch(path: string | (() => string)): () => RouteMatch | null;
+/**
+ * Get the href for a given path (useful for SSR)
+ */
+declare function useHref(to: To | (() => To)): () => string;
+/**
+ * Check if a path is active (matches current location)
+ */
+declare function useIsActive(to: To | (() => To), options?: {
+    end?: boolean | undefined;
+}): () => boolean;
+/**
+ * Register a beforeLeave handler for the current route
+ */
+declare function useBeforeLeave(handler: BeforeLeaveHandler): void;
+
+/**
+ * @fileoverview History implementations for @fictjs/router
+ *
+ * Provides browser history, hash history, and memory history implementations.
+ * These handle the low-level navigation state management.
+ */
+
+/**
+ * Create a browser history instance that uses the History API.
+ * This is the standard history for most web applications.
+ *
+ * @throws Error if called in a non-browser environment (SSR)
+ */
+declare function createBrowserHistory(): History;
+/**
+ * Create a hash history instance that uses the URL hash.
+ * Useful for static file hosting or when you can't configure server-side routing.
+ *
+ * @throws Error if called in a non-browser environment (SSR)
+ */
+declare function createHashHistory(options?: {
+    hashType?: 'slash' | 'noslash';
+}): History;
+/**
+ * Create a memory history instance that keeps history in memory.
+ * Useful for testing and server-side rendering.
+ */
+declare function createMemoryHistory(options?: {
+    initialEntries?: string[];
+    initialIndex?: number;
+}): History;
+/**
+ * Create a static history for server-side rendering.
+ * This history doesn't support navigation and always returns the initial location.
+ */
+declare function createStaticHistory(url: string): History;
+
+/**
+ * @fileoverview Data loading utilities for @fictjs/router
+ *
+ * This module provides utilities for loading data in routes,
+ * including query caching, actions, and preloading.
+ */
+
+/**
+ * Create a cached query function
+ *
+ * @example
+ * ```tsx
+ * const getUser = query(
+ *   async (id: string) => {
+ *     const response = await fetch(`/api/users/${id}`)
+ *     return response.json()
+ *   },
+ *   'getUser'
+ * )
+ *
+ * // In a component
+ * function UserProfile({ id }) {
+ *   const user = getUser(id)
+ *   return <div>{user()?.name}</div>
+ * }
+ * ```
+ */
+declare function query<T, Args extends unknown[]>(fn: QueryFunction<T, Args>, name: string): (...args: Args) => () => T | undefined;
+/**
+ * Invalidate cached queries by key pattern
+ */
+declare function revalidate(keys?: string | string[] | RegExp): void;
+/**
+ * Create an action for form submissions
+ *
+ * @example
+ * ```tsx
+ * const createUser = action(
+ *   async (formData, { params }) => {
+ *     const response = await fetch('/api/users', {
+ *       method: 'POST',
+ *       body: formData,
+ *     })
+ *     return response.json()
+ *   },
+ *   'createUser'
+ * )
+ *
+ * // In a component
+ * <Form action={createUser}>
+ *   <input name="name" />
+ *   <button type="submit">Create</button>
+ * </Form>
+ * ```
+ */
+declare function action<T>(fn: ActionFunction<T>, name?: string): Action<T>;
+/**
+ * Get a registered action by URL
+ */
+declare function getAction(url: string): ActionFunction<unknown> | undefined;
+/**
+ * Use submission state for an action
+ */
+declare function useSubmission<T>(actionOrUrl: Action<T> | string): () => Submission<T> | undefined;
+/**
+ * Use all active submissions
+ */
+declare function useSubmissions(): () => Submission<unknown>[];
+/**
+ * Submit an action and track the submission
+ */
+declare function submitAction<T>(action: Action<T>, formData: FormData, params?: Params): Promise<T>;
+/**
+ * Preload a query for faster navigation
+ */
+declare function preloadQuery<T, Args extends unknown[]>(queryFn: (...args: Args) => () => T | undefined, ...args: Args): void;
+/**
+ * Create a preload function for a route
+ */
+declare function createPreload<T>(fn: (args: {
+    params: Params;
+    intent: NavigationIntent;
+}) => T | Promise<T>): (args: {
+    params: Params;
+    intent: NavigationIntent;
+}) => Promise<T>;
+/**
+ * Resource state
+ */
+interface Resource<T> {
+    /** Get current data (undefined during loading or on error) */
+    (): T | undefined;
+    /** Whether the resource is currently loading */
+    loading: () => boolean;
+    /** Error if the fetch failed, undefined otherwise */
+    error: () => unknown;
+    /** Latest successfully loaded value (persists during reloads) */
+    latest: () => T | undefined;
+    /** Trigger a refetch, returns the result or undefined on error */
+    refetch: () => Promise<T | undefined>;
+}
+/**
+ * Create a resource for async data loading
+ * Integrates with Suspense for loading states
+ *
+ * @example
+ * ```tsx
+ * const userResource = createResource(
+ *   () => userId,
+ *   async (id) => fetch(`/api/users/${id}`).then(r => r.json())
+ * )
+ *
+ * function UserProfile() {
+ *   const user = userResource()
+ *   return <div>{user?.name}</div>
+ * }
+ * ```
+ */
+declare function createResource<T, S = unknown>(source: () => S, fetcher: (source: S) => T | Promise<T>): Resource<T>;
+/**
+ * Clean up router data utilities
+ */
+declare function cleanupDataUtilities(): void;
+
+/**
+ * @fileoverview Path matching and utility functions for @fictjs/router
+ *
+ * This module provides path parsing, matching, and scoring utilities.
+ * Based on patterns from Solid Router with optimizations for Fict.
+ */
+
+/**
+ * Normalize a path by removing trailing slashes and ensuring leading slash
+ */
+declare function normalizePath(path: string): string;
+/**
+ * Join path segments together
+ */
+declare function joinPaths(...paths: (string | undefined)[]): string;
+/**
+ * Resolve a relative path against a base path
+ */
+declare function resolvePath(base: string, to: To): string;
+/**
+ * Create a Location object from a To value
+ */
+declare function createLocation(to: To, state?: unknown, key?: string): Location;
+/**
+ * Parse a URL string into its components
+ */
+declare function parseURL(url: string): {
+    pathname: string;
+    search: string;
+    hash: string;
+};
+/**
+ * Create a URL string from a Location object
+ */
+declare function createURL(location: Partial<Location>): string;
+/**
+ * Calculate the score for a route pattern.
+ * Higher score = more specific route.
+ *
+ * Scoring:
+ * - Static segment: 3 points
+ * - Dynamic segment: 2 points
+ * - Optional segment: 1 point
+ * - Splat segment: 0.5 points
+ * - Index route bonus: 0.5 points
+ */
+declare function scoreRoute(pattern: string, isIndex?: boolean): number;
+/**
+ * Compile a route definition into a CompiledRoute
+ */
+declare function compileRoute(route: RouteDefinition, parentPattern?: string): CompiledRoute;
+/**
+ * Create branches from compiled routes for efficient matching.
+ * A branch represents a complete path from root to leaf.
+ */
+declare function createBranches(routes: CompiledRoute[]): RouteBranch[];
+/**
+ * Match a pathname against route branches
+ */
+declare function matchRoutes(branches: RouteBranch[], pathname: string): RouteMatch[] | null;
+/**
+ * Parse search params from a search string
+ */
+declare function parseSearchParams(search: string): URLSearchParams;
+/**
+ * Stringify search params to a search string
+ */
+declare function stringifySearchParams(params: URLSearchParams | Record<string, string>): string;
+/**
+ * Check if two locations are equal
+ */
+declare function locationsAreEqual(a: Location, b: Location): boolean;
+/**
+ * Strip the base path from a pathname
+ */
+declare function stripBasePath(pathname: string, basePath: string): string;
+/**
+ * Prepend the base path to a pathname
+ */
+declare function prependBasePath(pathname: string, basePath: string): string;
+/**
+ * Check if code is running on the server
+ */
+declare function isServer(): boolean;
+/**
+ * Check if code is running in the browser
+ */
+declare function isBrowser(): boolean;
+
+/**
+ * @fileoverview Scroll restoration utilities for @fictjs/router
+ *
+ * This module provides scroll position management including:
+ * - Saving scroll positions per location key
+ * - Restoring scroll on back/forward navigation
+ * - Scrolling to top on new navigation
+ * - Hash scrolling support (#section)
+ */
+
+/**
+ * Save the current scroll position for a location
+ */
+declare function saveScrollPosition(key: string): void;
+/**
+ * Clear saved scroll position for a location
+ */
+declare function clearScrollPosition(key: string): void;
+/**
+ * Clear all saved scroll positions
+ */
+declare function clearAllScrollPositions(): void;
+/**
+ * Scroll to top of the page
+ */
+declare function scrollToTop(behavior?: ScrollBehavior): void;
+/**
+ * Scroll to an element by ID (hash navigation)
+ */
+declare function scrollToHash(hash: string, behavior?: ScrollBehavior): boolean;
+/**
+ * Restore scroll position for a location
+ * Returns true if position was restored
+ */
+declare function restoreScrollPosition(key: string): boolean;
+interface ScrollRestorationOptions {
+    /** Whether scroll restoration is enabled */
+    enabled?: boolean;
+    /** Whether to restore scroll on back/forward navigation */
+    restoreOnPop?: boolean;
+    /** Whether to scroll to top on push navigation */
+    scrollToTopOnPush?: boolean;
+    /** Default scroll behavior */
+    behavior?: ScrollBehavior;
+}
+/**
+ * Create a scroll restoration manager
+ */
+declare function createScrollRestoration(options?: ScrollRestorationOptions): {
+    handleNavigation: (from: Location | null, to: Location, action: "PUSH" | "REPLACE" | "POP") => void;
+    saveScrollPosition: typeof saveScrollPosition;
+    restoreScrollPosition: typeof restoreScrollPosition;
+    scrollToTop: () => void;
+    scrollToHash: (hash: string) => boolean;
+    reset: () => void;
+    config: {
+        enabled: boolean;
+        restoreOnPop: boolean;
+        scrollToTopOnPush: boolean;
+        behavior: ScrollBehavior;
+    };
+};
+/**
+ * Get or create the default scroll restoration instance
+ */
+declare function getScrollRestoration(): ReturnType<typeof createScrollRestoration>;
+/**
+ * Configure the default scroll restoration
+ */
+declare function configureScrollRestoration(options: ScrollRestorationOptions): void;
+
+/**
+ * @fileoverview Lazy loading utilities for @fictjs/router
+ *
+ * This module provides code splitting support via lazy loading of route components.
+ * Works with Fict's Suspense for loading states.
+ */
+
+/**
+ * Create a lazy-loaded component
+ *
+ * @example
+ * ```tsx
+ * // Create a lazy component
+ * const LazyUserProfile = lazy(() => import('./pages/UserProfile'))
+ *
+ * // Use in routes
+ * <Route path="/users/:id" component={LazyUserProfile} />
+ *
+ * // Or with Suspense fallback
+ * <Suspense fallback={<Loading />}>
+ *   <LazyUserProfile />
+ * </Suspense>
+ * ```
+ */
+declare function lazy<T extends Component<any>>(loader: () => Promise<{
+    default: T;
+} | T>): Component<any>;
+/**
+ * Preload a lazy component
+ * Useful for preloading on hover/focus
+ */
+declare function preloadLazy(component: Component<any>): Promise<void>;
+/**
+ * Check if a component is a lazy component
+ */
+declare function isLazyComponent(component: unknown): boolean;
+/**
+ * Create a lazy route definition
+ *
+ * @example
+ * ```tsx
+ * const routes = [
+ *   lazyRoute({
+ *     path: '/users/:id',
+ *     component: () => import('./pages/UserProfile'),
+ *   }),
+ *   lazyRoute({
+ *     path: '/settings',
+ *     component: () => import('./pages/Settings'),
+ *     loadingElement: <Loading />,
+ *     errorElement: <Error />,
+ *   }),
+ * ]
+ * ```
+ */
+declare function lazyRoute<P extends string = string>(config: {
+    path?: string;
+    component: () => Promise<{
+        default: Component<RouteComponentProps<P>>;
+    } | Component<RouteComponentProps<P>>>;
+    loadingElement?: FictNode;
+    errorElement?: FictNode;
+    preload?: RouteDefinition<P>['preload'];
+    children?: RouteDefinition[];
+    index?: boolean;
+    key?: string;
+}): RouteDefinition<P>;
+/**
+ * Create multiple lazy routes from a glob import pattern
+ * Useful for file-system based routing
+ *
+ * @example
+ * ```tsx
+ * // In a Vite project
+ * const pages = import.meta.glob('./pages/*.tsx')
+ *
+ * const routes = createLazyRoutes(pages, {
+ *   // Map file path to route path
+ *   pathTransform: (filePath) => {
+ *     // ./pages/UserProfile.tsx -> /user-profile
+ *     return filePath
+ *       .replace('./pages/', '/')
+ *       .replace('.tsx', '')
+ *       .toLowerCase()
+ *       .replace(/([A-Z])/g, '-$1')
+ *   },
+ * })
+ * ```
+ */
+declare function createLazyRoutes(modules: Record<string, () => Promise<{
+    default: Component<any>;
+}>>, options?: {
+    pathTransform?: (filePath: string) => string;
+    loadingElement?: FictNode;
+    errorElement?: FictNode;
+}): RouteDefinition[];
+
+export { type Action, type ActionFunction, type BeforeLeaveEventArgs, type BeforeLeaveHandler, type Blocker, type CompiledRoute, Form, type FormProps, HashRouter, type HashRouterOptions, type History, type HistoryAction, type HistoryListener, Link, type LinkProps, type Location, type MatchFilter, type MatchFilters, MemoryRouter, type MemoryRouterOptions, NavLink, type NavLinkProps, type NavLinkRenderProps, Navigate, type NavigateFunction, type NavigateOptions, type Navigation, type NavigationIntent, Outlet, type Params, type PreloadArgs, type PreloadFunction, type QueryCacheEntry, type QueryFunction, Redirect, type Resource, Route, type RouteBranch, type RouteComponentProps, type RouteContextValue, type RouteDefinition, type RouteMatch, type RouteProps, Router, type RouterContextValue, type RouterOptions, Routes, type ScrollRestorationOptions, type SearchParams, StaticRouter, type Submission, type To, action, cleanupDataUtilities, clearAllScrollPositions, clearScrollPosition, compileRoute, configureScrollRestoration, createBranches, createBrowserHistory, createHashHistory, createLazyRoutes, createLocation, createMemoryHistory, createPreload, createResource, createRouter, createRoutes, createScrollRestoration, createStaticHistory, createURL, getAction, getScrollRestoration, isBrowser, isLazyComponent, isServer, joinPaths, lazy, lazyRoute, locationsAreEqual, matchRoutes, normalizePath, parseSearchParams, parseURL, preloadLazy, preloadQuery, prependBasePath, query, resolvePath, restoreScrollPosition, revalidate, saveScrollPosition, scoreRoute, scrollToHash, scrollToTop, stringifySearchParams, stripBasePath, submitAction, useBeforeLeave, useHref, useIsActive, useIsRouting, useLocation, useMatch, useMatches, useNavigate, useParams, usePendingLocation, useResolvedPath, useRoute, useRouteData, useRouteError, useRouter, useSearchParams, useSubmission, useSubmissions };