named-react-router/dist/index.d.ts

A lightweight extension to React Router for named routes

import { createBrowserRouter, Location, NavigateOptions, RouteObject, To } from 'react-router-dom';
/**
 * An object that represents a named route navigation intent.
 */
type NamedTo = {
    /**
     * The unique name of the route.
     */
    name: string;
    /**
     * A map of path parameters. Each key should match a dynamic segment (e.g. :id).
     */
    params?: {
        [key: string]: string;
    };
    /**
     * A map of query parameters that will be appended to the URL.
     */
    query?: {
        [key: string]: string;
    };
};
/**
 * Extension of `RouteObject` that includes optional `name`, `absolutePath`,
 * fields for named-route functionality.
 */
export type NamedRouteObject = {
    /**
     * Optional name to identify this route. Must be unique if provided.
     */
    name?: string;
    /**
     * Nested children in the route hierarchy.
     */
    children?: NamedRouteObject[];
    /**
     * The absolute path resolved by combining parent paths.
     * This is an internal property, automatically populated by `collectRouteNames`.
     * Not intended for external modification.
     */
    __absolutePath?: string;
} & RouteObject;
export type JunctionTo = To | NamedTo;
declare const namedRoutesMap: Map<string, NamedRouteObject>;
/**
 * Recursively collects and validates named routes, setting absolute paths.
 *
 * @param routes - An array of NamedRouteObject to collect.
 * @param parentPath - The path of the parent route, defaults to "/".
 * @param accId - Accumulated ID for child route indexing.
 * @throws Error if a duplicate route name is encountered.
 */
declare function collectRouteNames(routes: NamedRouteObject[], parentPath?: string, accId?: string): void;
/**
 * Creates a React Router browser router with named-route capabilities.
 *
 * Accepts an array of `NamedRouteObject` entries (each optionally containing a `name`,
 * `path`, `element`, and nested `children`) and returns a router instance that supports
 * named navigation.
 *
 * @example
 * ```ts
 * enum RouteNames { home = "home", about = "about", team = "team" }
 *
 * const router = createNamedBrowserRouter([
 *   {
 *     path: "",
 *     name: RouteNames.home,
 *     element: <HomePage />,
 *     children: [
 *       {
 *         path: "about",
 *         name: RouteNames.about,
 *         element: <AboutPage />,
 *         children: [
 *           { path: "team/:id", name: RouteNames.team, element: <TeamPage /> },
 *         ],
 *       },
 *     ],
 *   },
 * ]);
 * ```
 *
 * @param routes - An array of `NamedRouteObject`.
 * @param opts - Optional router configuration.
 * @returns A browser router instance with named route support.
 */
declare function createNamedBrowserRouter(routes: NamedRouteObject[], opts?: Parameters<typeof createBrowserRouter>[1]): import('react-router-dom').DataRouter;
/**
 * Returns a navigation function that supports both standard `To`
 * and named-route (`NamedTo`) navigation.
 *
 * @example
 * ```tsx
 * import { useNamedNavigate } from "named-react-router";
 *
 * function MyComponent() {
 *   const navigate = useNamedNavigate();
 *
 *   function handleClick() {
 *     navigate({
 *       name: "profile",
 *       params: { id: "123" },
 *       query: { tab: "posts" }
 *     });
 *   }
 *
 *   return <button onClick={handleClick}>Go to Profile</button>;
 * }
 * ```
 *
 * @returns A function that can navigate by name (with params & queries) or by path/string.
 */
declare function useNamedNavigate(): (to: JunctionTo, options?: NavigateOptions) => void;
/**
 * A hook that returns the current location, enhanced with the named route (if available).
 *
 * @example
 * ```tsx
 * import { useNamedLocation } from "named-react-router";
 *
 * function Breadcrumb() {
 *   const location = useNamedLocation();
 *   // location.name might be "about", "profile", etc.
 *   return <span>Current Page: {location.name || "Unnamed"}</span>;
 * }
 * ```
 *
 * @returns The standard react-router location object with an optional `name` property.
 */
declare function useNamedLocation(): Location & {
    name?: string;
};
export declare function __namedToFilledPath(to: JunctionTo): To;
export { namedRoutesMap, createNamedBrowserRouter, useNamedNavigate, useNamedLocation, collectRouteNames, };
export { NamedRoute } from './components/NamedRoute';
export { NamedRoutes } from './components/NamedRoutes';
export { NamedNavLink } from './components/NamedNavLink';