@furystack/shades/esm/components/nested-navigate.d.ts

A lightweight UI framework for FuryStack with JSX support

import type { Injector } from '@furystack/inject';
import type { ExtractRouteHash, ExtractRouteQuery, ExtractRoutePaths, RouteAt, TypedHashArg, TypedParamsArg, TypedQueryArg } from './nested-route-types.js';
import type { NestedRoute } from './nested-router.js';
/**
 * Untyped runtime arguments for a nested navigate call.
 * Used by the base {@link nestedNavigate} implementation; the typed variants
 * returned by {@link createNestedNavigate} narrow each field against the route
 * tree at compile time.
 */
export type NestedNavigateArgs = {
    path: string;
    params?: Record<string, string>;
    query?: Record<string, unknown>;
    hash?: string;
};
/**
 * Typed arguments for a nested navigate call, derived from the route tree and
 * the specific target path.
 *
 * - `params` is required when the path contains `:param` segments.
 * - `query` is required when the route's declared query shape has any required
 *   key, optional when all keys are optional, and forbidden when the route
 *   declares no `query` validator.
 * - `hash` is always optional and restricted to the route's declared literal
 *   tuple; forbidden when the route declares no `hash`.
 *
 * @typeParam TRoutes - The route tree
 * @typeParam TPath - A composed route path within `TRoutes`
 */
export type TypedNestedNavigateArgs<TRoutes extends Record<string, NestedRoute<any, any, any>>, TPath extends string> = {
    path: TPath;
} & TypedParamsArg<TPath> & TypedQueryArg<ExtractRouteQuery<RouteAt<TRoutes, TPath>>> & TypedHashArg<ExtractRouteHash<RouteAt<TRoutes, TPath>>>;
/**
 * Builds the resolved URL for a nested navigate call, including path parameters,
 * serialized query string and hash segment. Exported for callers that need the
 * URL without side effects (e.g. link rendering helpers).
 */
export declare const buildNestedNavigateUrl: (args: NestedNavigateArgs) => string;
/**
 * Navigates to a route using the LocationService resolved from the given injector.
 * Compiles parameterized routes (e.g. `/users/:id`), serializes the optional
 * `query` record with the default `@furystack/rest` serializer, and appends the
 * optional `hash` segment.
 *
 * @param injector - The injector instance to resolve LocationService from
 * @param args - The navigation arguments
 */
export declare const nestedNavigate: (injector: Injector, args: NestedNavigateArgs) => void;
/**
 * Creates a type-safe navigate function constrained to a specific route tree.
 * The returned function has the same runtime behavior as {@link nestedNavigate}
 * but narrows `path` to only accept valid route paths, requires `params` when
 * the route has parameters, and enforces the route's declared `query` and
 * `hash` schemas.
 *
 * Unlike {@link createNestedRouteLink}, the injector is passed at call time,
 * not at creation time.
 *
 * @typeParam TRoutes - The route tree type (use `typeof yourRoutes`)
 * @returns A type-safe navigate function
 *
 * @example
 * ```typescript
 * const appNavigate = createNestedNavigate<typeof appRoutes>()
 *
 * appNavigate(injector, { path: '/buttons' })
 * appNavigate(injector, { path: '/users/:id', params: { id: '123' } })
 * appNavigate(injector, {
 *   path: '/users/:id',
 *   params: { id: '123' },
 *   query: { tab: 'profile' },
 *   hash: 'settings',
 * })
 * ```
 */
export declare const createNestedNavigate: <TRoutes extends Record<string, NestedRoute<any, any, any>>>() => <TPath extends ExtractRoutePaths<TRoutes>>(injector: Injector, args: TypedNestedNavigateArgs<TRoutes, TPath>) => void;
//# sourceMappingURL=nested-navigate.d.ts.map