UNPKG

react-router/dist/development/lib/router/router.d.ts

Version:
20.4 kB TypeScript View Raw
1
2import { Action, History, Location, Path, To } from "./history.js";
3import { DataRouteMatch, DataRouteObject, DataStrategyFunction, FormEncType, HTMLFormMethod, MapRoutePropertiesFunction, MaybePromise, PatchRoutesOnNavigationFunction, RouteBranch, RouteData, RouteManifest, RouteObject, RouterContextProvider, Submission, UIMatch } from "./utils.js";
4import { ClientInstrumentation, ServerInstrumentation } from "./instrumentation.js";
5
6//#region lib/router/router.d.ts
7/**
* A Router instance manages all navigation and data loading/mutations
*/
10interface Router {
/**
 * @private
 * PRIVATE - DO NOT USE
 *
 * Return the basename for the router
 */
get basename(): RouterInit["basename"];
/**
 * @private
 * PRIVATE - DO NOT USE
 *
 * Return the future config for the router
 */
get future(): FutureConfig;
/**
 * @private
 * PRIVATE - DO NOT USE
 *
 * Return the current state of the router
 */
get state(): RouterState;
/**
 * @private
 * PRIVATE - DO NOT USE
 *
 * Return the routes for this router instance
 */
get routes(): DataRouteObject[];
/**
 * @private
 * PRIVATE - DO NOT USE
 *
 * Return the route branches for this router instance
 */
get branches(): RouteBranch<DataRouteObject>[] | undefined;
/**
 * @private
 * PRIVATE - DO NOT USE
 *
 * Return the manifest for this router instance
 */
get manifest(): RouteManifest;
/**
 * @private
 * PRIVATE - DO NOT USE
 *
 * Return the window associated with the router
 */
get window(): RouterInit["window"];
/**
 * @private
 * PRIVATE - DO NOT USE
 *
 * Initialize the router, including adding history listeners and kicking off
 * initial data fetches.  Returns a function to cleanup listeners and abort
 * any in-progress loads
 */
initialize(): Router;
/**
 * @private
 * PRIVATE - DO NOT USE
 *
 * Subscribe to router.state updates
 *
 * @param fn function to call with the new state
 */
subscribe(fn: RouterSubscriber): () => void;
/**
 * @private
 * PRIVATE - DO NOT USE
 *
 * Enable scroll restoration behavior in the router
 *
 * @param savedScrollPositions Object that will manage positions, in case
 *                             it's being restored from sessionStorage
 * @param getScrollPosition    Function to get the active Y scroll position
 * @param getKey               Function to get the key to use for restoration
 */
enableScrollRestoration(savedScrollPositions: Record<string, number>, getScrollPosition: GetScrollPositionFunction, getKey?: GetScrollRestorationKeyFunction): () => void;
/**
 * @private
 * PRIVATE - DO NOT USE
 *
 * Navigate forward/backward in the history stack
 * @param to Delta to move in the history stack
 */
navigate(to: number): Promise<void>;
/**
 * Navigate to the given path
 * @param to Path to navigate to
 * @param opts Navigation options (method, submission, etc.)
 */
navigate(to: To | null, opts?: RouterNavigateOptions): Promise<void>;
/**
 * @private
 * PRIVATE - DO NOT USE
 *
 * Trigger a fetcher load/submission
 *
 * @param key     Fetcher key
 * @param routeId Route that owns the fetcher
 * @param href    href to fetch
 * @param opts    Fetcher options, (method, submission, etc.)
 */
fetch(key: string, routeId: string, href: string | null, opts?: RouterFetchOptions): Promise<void>;
/**
 * @private
 * PRIVATE - DO NOT USE
 *
 * Trigger a revalidation of all current route loaders and fetcher loads
 */
revalidate(): Promise<void>;
/**
 * @private
 * PRIVATE - DO NOT USE
 *
 * Utility function to create an href for the given location
 * @param location
 */
createHref(location: Location | URL): string;
/**
 * @private
 * PRIVATE - DO NOT USE
 *
 * Utility function to create a URL for the given location
 * @param location
 */
createURL?(to: To): URL;
/**
 * @private
 * PRIVATE - DO NOT USE
 *
 * Utility function to URL encode a destination path according to the internal
 * history implementation
 * @param to
 */
encodeLocation(to: To): Path;
/**
 * @private
 * PRIVATE - DO NOT USE
 *
 * Get/create a fetcher for the given key
 * @param key
 */
getFetcher<TData = any>(key: string): Fetcher<TData>;
/**
 * @internal
 * PRIVATE - DO NOT USE
 *
 * Reset the fetcher for a given key
 * @param key
 */
resetFetcher(key: string, opts?: {
  reason?: unknown;
}): void;
/**
 * @private
 * PRIVATE - DO NOT USE
 *
 * Delete the fetcher for a given key
 * @param key
 */
deleteFetcher(key: string): void;
/**
 * @private
 * PRIVATE - DO NOT USE
 *
 * Cleanup listeners and abort any in-progress loads
 */
dispose(): void;
/**
 * @private
 * PRIVATE - DO NOT USE
 *
 * Get a navigation blocker
 * @param key The identifier for the blocker
 * @param fn The blocker function implementation
 */
getBlocker(key: string, fn: BlockerFunction): Blocker;
/**
 * @private
 * PRIVATE - DO NOT USE
 *
 * Delete a navigation blocker
 * @param key The identifier for the blocker
 */
deleteBlocker(key: string): void;
/**
 * @private
 * PRIVATE DO NOT USE
 *
 * Patch additional children routes into an existing parent route
 * @param routeId The parent route id or a callback function accepting `patch`
 *                to perform batch patching
 * @param children The additional children routes
 * @param unstable_allowElementMutations Allow mutation or route elements on
 *                                       existing routes. Intended for RSC-usage
 *                                       only.
 */
patchRoutes(routeId: string | null, children: RouteObject[], unstable_allowElementMutations?: boolean): void;
/**
 * @private
 * PRIVATE - DO NOT USE
 *
 * HMR needs to pass in-flight route updates to React Router
 * TODO: Replace this with granular route update APIs (addRoute, updateRoute, deleteRoute)
 */
_internalSetRoutes(routes: RouteObject[]): void;
/**
 * @private
 * PRIVATE - DO NOT USE
 *
 * Cause subscribers to re-render.  This is used to force a re-render.
 */
_internalSetStateDoNotUseOrYouWillBreakYourApp(state: Partial<RouterState>): void;
/**
 * @private
 * PRIVATE - DO NOT USE
 *
 * Internal fetch AbortControllers accessed by unit tests
 */
_internalFetchControllers: Map<string, AbortController>;
233}
234/**
* State maintained internally by the router.  During a navigation, all states
* reflect the "old" location unless otherwise noted.
*/
238interface RouterState {
/**
 * The action of the most recent navigation
 */
historyAction: Action;
/**
 * The current location reflected by the router
 */
location: Location;
/**
 * The current set of route matches
 */
matches: DataRouteMatch[];
/**
 * Tracks whether we've completed our initial data load
 */
initialized: boolean;
/**
 * Tracks whether we should be rendering a HydrateFallback during hydration
 */
renderFallback: boolean;
/**
 * Current scroll position we should start at for a new view
 *  - number -> scroll position to restore to
 *  - false -> do not restore scroll at all (used during submissions/revalidations)
 *  - null -> don't have a saved position, scroll to hash or top of page
 */
restoreScrollPosition: number | false | null;
/**
 * Indicate whether this navigation should skip resetting the scroll position
 * if we are unable to restore the scroll position
 */
preventScrollReset: boolean;
/**
 * Tracks the state of the current navigation
 */
navigation: Navigation;
/**
 * Tracks any in-progress revalidations
 */
revalidation: RevalidationState;
/**
 * Data from the loaders for the current matches
 */
loaderData: RouteData;
/**
 * Data from the action for the current matches
 */
actionData: RouteData | null;
/**
 * Errors caught from loaders for the current matches
 */
errors: RouteData | null;
/**
 * Map of current fetchers
 */
fetchers: Map<string, Fetcher>;
/**
 * Map of current blockers
 */
blockers: Map<string, Blocker>;
299}
300/**
* Data that can be passed into hydrate a Router from SSR
*/
303type HydrationState = Partial<Pick<RouterState, "loaderData" | "actionData" | "errors">>;
304/**
* Future flags to toggle new feature behavior
*/
307interface FutureConfig {}
308/**
* Initialization options for createRouter
*/
311interface RouterInit {
routes: RouteObject[];
history: History;
basename?: string;
getContext?: () => MaybePromise<RouterContextProvider>;
instrumentations?: ClientInstrumentation[];
mapRouteProperties?: MapRoutePropertiesFunction;
future?: Partial<FutureConfig>;
hydrationRouteProperties?: string[];
hydrationData?: HydrationState;
window?: Window;
dataStrategy?: DataStrategyFunction;
patchRoutesOnNavigation?: PatchRoutesOnNavigationFunction;
324}
325/**
* State returned from a server-side query() call
*/
328interface StaticHandlerContext {
basename: Router["basename"];
location: RouterState["location"];
matches: RouterState["matches"];
loaderData: RouterState["loaderData"];
actionData: RouterState["actionData"];
errors: RouterState["errors"];
statusCode: number;
loaderHeaders: Record<string, Headers>;
actionHeaders: Record<string, Headers>;
_deepestRenderedBoundaryId?: string | null;
339}
340/**
* A StaticHandler instance manages a singular SSR navigation/fetch event
*/
343interface StaticHandler {
/**
 * The set of data routes managed by this handler
 */
dataRoutes: DataRouteObject[];
/**
 * @private
 * PRIVATE - DO NOT USE
 *
 * The route branches derived from the data routes, used for internal route
 * matching in Framework Mode
 */
_internalRouteBranches: RouteBranch<DataRouteObject>[];
/**
 * Perform a query for a given request - executing all matched route
 * loaders/actions.  Used for document requests.
 *
 * @param request The request to query
 * @param opts Optional query options
 * @param opts.dataStrategy Alternate dataStrategy implementation
 * @param opts.filterMatchesToLoad Predicate function to filter which matches should be loaded
 * @param opts.generateMiddlewareResponse To enable middleware, provide a function
 * to generate a response to bubble back up the middleware chain
 * @param opts.requestContext Context object to pass to loaders/actions
 * @param opts.skipLoaderErrorBubbling Skip loader error bubbling
 * @param opts.skipRevalidation Skip revalidation after action submission
 * @param opts.normalizePath Normalize the request path
 */
query(request: Request, opts?: {
  requestContext?: unknown;
  filterMatchesToLoad?: (match: DataRouteMatch) => boolean;
  skipLoaderErrorBubbling?: boolean;
  skipRevalidation?: boolean;
  dataStrategy?: DataStrategyFunction<unknown>;
  generateMiddlewareResponse?: (query: (r: Request, args?: {
    filterMatchesToLoad?: (match: DataRouteMatch) => boolean;
  }) => Promise<StaticHandlerContext | Response>) => MaybePromise<Response>;
  normalizePath?: (request: Request) => Path;
}): Promise<StaticHandlerContext | Response>;
/**
 * Perform a query for a specific route.  Used for resource requests.
 *
 * @param request The request to query
 * @param opts Optional queryRoute options
 * @param opts.dataStrategy Alternate dataStrategy implementation
 * @param opts.generateMiddlewareResponse To enable middleware, provide a function
 * to generate a response to bubble back up the middleware chain
 * @param opts.requestContext Context object to pass to loaders/actions
 * @param opts.routeId The ID of the route to query
 * @param opts.normalizePath Normalize the request path
    */
queryRoute(request: Request, opts?: {
  routeId?: string;
  requestContext?: unknown;
  dataStrategy?: DataStrategyFunction<unknown>;
  generateMiddlewareResponse?: (queryRoute: (r: Request) => Promise<Response>) => MaybePromise<Response>;
  normalizePath?: (request: Request) => Path;
}): Promise<any>;
401}
402type ViewTransitionOpts = {
currentLocation: Location;
nextLocation: Location;
405};
406/**
* Subscriber function signature for changes to router state
*/
409interface RouterSubscriber {
(state: RouterState, opts: {
  deletedFetchers: string[];
  newErrors: RouteData | null;
  viewTransitionOpts?: ViewTransitionOpts;
  flushSync: boolean;
}): void;
416}
417/**
* Function signature for determining the key to be used in scroll restoration
* for a given location
*/
421interface GetScrollRestorationKeyFunction {
(location: Location, matches: UIMatch[]): string | null;
423}
424/**
* Function signature for determining the current scroll position
*/
427interface GetScrollPositionFunction {
(): number;
429}
430/**
* - "route": relative to the route hierarchy so `..` means remove all segments
* of the current route even if it has many. For example, a `route("posts/:id")`
* would have both `:id` and `posts` removed from the url.
* - "path": relative to the pathname so `..` means remove one segment of the
* pathname. For example, a `route("posts/:id")` would have only `:id` removed
* from the url.
*/
438type RelativeRoutingType = "route" | "path";
439type BaseNavigateOrFetchOptions = {
preventScrollReset?: boolean;
relative?: RelativeRoutingType;
flushSync?: boolean;
defaultShouldRevalidate?: boolean;
444};
445type BaseNavigateOptions = BaseNavigateOrFetchOptions & {
replace?: boolean;
state?: any;
fromRouteId?: string;
viewTransition?: boolean;
mask?: To;
451};
452type BaseSubmissionOptions = {
formMethod?: HTMLFormMethod;
formEncType?: FormEncType;
455} & ({
formData: FormData;
body?: undefined;
458} | {
formData?: undefined;
body: any;
461});
462/**
* Options for a navigate() call for a normal (non-submission) navigation
*/
465type LinkNavigateOptions = BaseNavigateOptions;
466/**
* Options for a navigate() call for a submission navigation
*/
469type SubmissionNavigateOptions = BaseNavigateOptions & BaseSubmissionOptions;
470/**
* Options to pass to navigate() for a navigation
*/
473type RouterNavigateOptions = LinkNavigateOptions | SubmissionNavigateOptions;
474/**
* Options for a fetch() load
*/
477type LoadFetchOptions = BaseNavigateOrFetchOptions;
478/**
* Options for a fetch() submission
*/
481type SubmitFetchOptions = BaseNavigateOrFetchOptions & BaseSubmissionOptions;
482/**
* Options to pass to fetch()
*/
485type RouterFetchOptions = LoadFetchOptions | SubmitFetchOptions;
486/**
* Potential states for state.navigation
*/
489type NavigationStates = {
Idle: {
  state: "idle";
  location: undefined;
  matches: undefined;
  historyAction: undefined;
  formMethod: undefined;
  formAction: undefined;
  formEncType: undefined;
  formData: undefined;
  json: undefined;
  text: undefined;
};
Loading: {
  state: "loading";
  location: Location;
  matches: DataRouteMatch[];
  historyAction: Action;
  formMethod: Submission["formMethod"] | undefined;
  formAction: Submission["formAction"] | undefined;
  formEncType: Submission["formEncType"] | undefined;
  formData: Submission["formData"] | undefined;
  json: Submission["json"] | undefined;
  text: Submission["text"] | undefined;
};
Submitting: {
  state: "submitting";
  location: Location;
  matches: DataRouteMatch[];
  historyAction: Action;
  formMethod: Submission["formMethod"];
  formAction: Submission["formAction"];
  formEncType: Submission["formEncType"];
  formData: Submission["formData"];
  json: Submission["json"];
  text: Submission["text"];
};
526};
527type Navigation = NavigationStates[keyof NavigationStates];
528type RevalidationState = "idle" | "loading";
529/**
* Potential states for fetchers
*/
532type FetcherStates<TData = any> = {
/**
 * The fetcher is not calling a loader or action
 *
 * ```tsx
 * fetcher.state === "idle"
 * ```
 */
Idle: {
  state: "idle";
  formMethod: undefined;
  formAction: undefined;
  formEncType: undefined;
  text: undefined;
  formData: undefined;
  json: undefined;
  /**
   * If the fetcher has never been called, this will be undefined.
   */
  data: TData | undefined;
};
/**
 * The fetcher is loading data from a {@link LoaderFunction | loader} from a
 * call to {@link FetcherWithComponents.load | `fetcher.load`}.
 *
 * ```tsx
 * // somewhere
 * <button onClick={() => fetcher.load("/some/route") }>Load</button>
 *
 * // the state will update
 * fetcher.state === "loading"
 * ```
 */
Loading: {
  state: "loading";
  formMethod: Submission["formMethod"] | undefined;
  formAction: Submission["formAction"] | undefined;
  formEncType: Submission["formEncType"] | undefined;
  text: Submission["text"] | undefined;
  formData: Submission["formData"] | undefined;
  json: Submission["json"] | undefined;
  data: TData | undefined;
};
/**
  The fetcher is submitting to a {@link LoaderFunction} (GET) or {@link ActionFunction} (POST) from a {@link FetcherWithComponents.Form | `fetcher.Form`} or {@link FetcherWithComponents.submit | `fetcher.submit`}.
     ```tsx
  // somewhere
  <input
    onChange={e => {
      fetcher.submit(event.currentTarget.form, { method: "post" });
    }}
  />
     // the state will update
  fetcher.state === "submitting"
     // and formData will be available
  fetcher.formData
  ```
 */
Submitting: {
  state: "submitting";
  formMethod: Submission["formMethod"];
  formAction: Submission["formAction"];
  formEncType: Submission["formEncType"];
  text: Submission["text"];
  formData: Submission["formData"];
  json: Submission["json"];
  data: TData | undefined;
};
600};
601type Fetcher<TData = any> = FetcherStates<TData>[keyof FetcherStates<TData>];
602interface BlockerBlocked {
state: "blocked";
reset: () => void;
proceed: () => void;
location: Location;
607}
608interface BlockerUnblocked {
state: "unblocked";
reset: undefined;
proceed: undefined;
location: undefined;
613}
614interface BlockerProceeding {
state: "proceeding";
reset: undefined;
proceed: undefined;
location: Location;
619}
620type Blocker = BlockerUnblocked | BlockerBlocked | BlockerProceeding;
621type BlockerFunction = (args: {
currentLocation: Location;
nextLocation: Location;
historyAction: Action;
625}) => boolean;
626declare const IDLE_NAVIGATION: NavigationStates["Idle"];
627declare const IDLE_FETCHER: FetcherStates["Idle"];
628declare const IDLE_BLOCKER: BlockerUnblocked;
629/**
* Create a router and listen to history POP navigations
*/
632declare function createRouter(init: RouterInit): Router;
633interface CreateStaticHandlerOptions {
basename?: string;
mapRouteProperties?: MapRoutePropertiesFunction;
instrumentations?: Pick<ServerInstrumentation, "route">[];
future?: Partial<FutureConfig>;
638}
639/**
* Create a static handler to perform server-side data loading
*
* @example
* export async function handleRequest(request: Request) {
*   let { query, dataRoutes } = createStaticHandler(routes);
*   let context = await query(request);
*
*   if (context instanceof Response) {
*     return context;
*   }
*
*   let router = createStaticRouter(dataRoutes, context);
*   return new Response(
*     ReactDOMServer.renderToString(<StaticRouterProvider ... />),
*     { headers: { "Content-Type": "text/html" } }
*   );
* }
*
* @public
* @category Data Routers
* @mode data
* @param routes The {@link RouteObject | route objects} to create a static
* handler for
* @param opts Options
* @param opts.basename The base URL for the static handler (default: `/`)
* @param opts.future Future flags for the static handler
* @returns A static handler that can be used to query data for the provided
* routes
*/
669declare function createStaticHandler(routes: RouteObject[], opts?: CreateStaticHandlerOptions): StaticHandler;
670//#endregion
671export { Blocker, BlockerFunction, Fetcher, FutureConfig, GetScrollPositionFunction, GetScrollRestorationKeyFunction, HydrationState, IDLE_BLOCKER, IDLE_FETCHER, IDLE_NAVIGATION, Navigation, NavigationStates, RelativeRoutingType, RevalidationState, Router, RouterFetchOptions, RouterInit, RouterNavigateOptions, RouterState, RouterSubscriber, StaticHandler, StaticHandlerContext, createRouter, createStaticHandler };
\No newline at end of file
1
2	`import { Action, History, Location, Path, To } from "./history.js";`
3	`import { DataRouteMatch, DataRouteObject, DataStrategyFunction, FormEncType, HTMLFormMethod, MapRoutePropertiesFunction, MaybePromise, PatchRoutesOnNavigationFunction, RouteBranch, RouteData, RouteManifest, RouteObject, RouterContextProvider, Submission, UIMatch } from "./utils.js";`
4	`import { ClientInstrumentation, ServerInstrumentation } from "./instrumentation.js";`
5
6	`//#region lib/router/router.d.ts`
7	`/**`
8	`* A Router instance manages all navigation and data loading/mutations`
9	`*/`
10	`interface Router {`
11	`/**`
12	`* @private`
13	`* PRIVATE - DO NOT USE`
14	`*`
15	`* Return the basename for the router`
16	`*/`
17	`get basename(): RouterInit["basename"];`
18	`/**`
19	`* @private`
20	`* PRIVATE - DO NOT USE`
21	`*`
22	`* Return the future config for the router`
23	`*/`
24	`get future(): FutureConfig;`
25	`/**`
26	`* @private`
27	`* PRIVATE - DO NOT USE`
28	`*`
29	`* Return the current state of the router`
30	`*/`
31	`get state(): RouterState;`
32	`/**`
33	`* @private`
34	`* PRIVATE - DO NOT USE`
35	`*`
36	`* Return the routes for this router instance`
37	`*/`
38	`get routes(): DataRouteObject[];`
39	`/**`
40	`* @private`