react-router 7.8.2 → 7.9.0-pre.1

package/dist/development/index-react-server.d.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-export { Await, BrowserRouter, Form, HashRouter, Link, Links, MemoryRouter, Meta, NavLink, Navigate, Outlet, Route, Router, RouterProvider, Routes, ScrollRestoration, StaticRouter, StaticRouterProvider, unstable_HistoryRouter } from 'react-router/internal/react-server-client';
+export { BrowserRouter, Form, HashRouter, Link, Links, MemoryRouter, Meta, NavLink, Navigate, Outlet, Route, Router, RouterProvider, Routes, ScrollRestoration, StaticRouter, StaticRouterProvider, unstable_HistoryRouter } from 'react-router/internal/react-server-client';
 import { ParseOptions, SerializeOptions } from 'cookie';
 export { ParseOptions as CookieParseOptions, SerializeOptions as CookieSerializeOptions } from 'cookie';
 
@@ -169,7 +169,7 @@ interface History {
 interface Future {
 }
 type MiddlewareEnabled = Future extends {
-    unstable_middleware: infer T extends boolean;
+    middleware: infer T extends boolean;
 } ? T : false;
 
 type MaybePromise<T> = T | Promise<T>;
@@ -229,14 +229,14 @@ type Submission = {
 };
 /**
  * A context instance used as the key for the `get`/`set` methods of a
- * {@link unstable_RouterContextProvider}. Accepts an optional default
+ * {@link RouterContextProvider}. Accepts an optional default
  * value to be returned if no value has been set.
  */
-interface unstable_RouterContext<T = unknown> {
+interface RouterContext<T = unknown> {
     defaultValue?: T;
 }
 /**
- * Creates a type-safe {@link unstable_RouterContext} object that can be used to
+ * Creates a type-safe {@link RouterContext} object that can be used to
  * store and retrieve arbitrary values in [`action`](../../start/framework/route-module#action)s,
  * [`loader`](../../start/framework/route-module#loader)s, and [middleware](../../how-to/middleware).
  * Similar to React's [`createContext`](https://react.dev/reference/react/createContext),
@@ -247,11 +247,11 @@ interface unstable_RouterContext<T = unknown> {
  * when no value has been set will throw an error.
  *
  * ```tsx filename=app/context.ts
- * import { unstable_createContext } from "react-router";
+ * import { createContext } from "react-router";
  *
  * // Create a context for user data
  * export const userContext =
- *   unstable_createContext<User | null>(null);
+ *   createContext<User | null>(null);
  * ```
  *
  * ```tsx filename=app/middleware/auth.ts
@@ -289,23 +289,23 @@ interface unstable_RouterContext<T = unknown> {
  * @mode data
  * @param defaultValue An optional default value for the context. This value
  * will be returned if no value has been set for this context.
- * @returns A {@link unstable_RouterContext} object that can be used with
+ * @returns A {@link RouterContext} object that can be used with
  * `context.get()` and `context.set()` in [`action`](../../start/framework/route-module#action)s,
  * [`loader`](../../start/framework/route-module#loader)s, and [middleware](../../how-to/middleware).
  */
-declare function unstable_createContext<T>(defaultValue?: T): unstable_RouterContext<T>;
+declare function createContext<T>(defaultValue?: T): RouterContext<T>;
 /**
  * Provides methods for writing/reading values in application context in a
  * type-safe way. Primarily for usage with [middleware](../../how-to/middleware).
  *
  * @example
  * import {
- *   unstable_createContext,
- *   unstable_RouterContextProvider
+ *   createContext,
+ *   RouterContextProvider
  * } from "react-router";
  *
- * const userContext = unstable_createContext<User | null>(null);
- * const contextProvider = new unstable_RouterContextProvider();
+ * const userContext = createContext<User | null>(null);
+ * const contextProvider = new RouterContextProvider();
  * contextProvider.set(userContext, getUser());
  * //                               ^ Type-safe
  * const user = contextProvider.get(userContext);
@@ -316,13 +316,13 @@ declare function unstable_createContext<T>(defaultValue?: T): unstable_RouterCon
  * @mode framework
  * @mode data
  */
-declare class unstable_RouterContextProvider {
+declare class RouterContextProvider {
     #private;
     /**
-     * Create a new `unstable_RouterContextProvider` instance
+     * Create a new `RouterContextProvider` instance
      * @param init An optional initial context map to populate the provider with
      */
-    constructor(init?: Map<unstable_RouterContext, unknown>);
+    constructor(init?: Map<RouterContext, unknown>);
     /**
      * Access a value from the context. If no value has been set for the context,
      * it will return the context's `defaultValue` if provided, or throw an error
@@ -331,7 +331,7 @@ declare class unstable_RouterContextProvider {
      * @returns The value for the context, or the context's `defaultValue` if no
      * value was set
      */
-    get<T>(context: unstable_RouterContext<T>): T;
+    get<T>(context: RouterContext<T>): T;
     /**
      * Set a value for the context. If the context already has a value set, this
      * will overwrite it.
@@ -340,9 +340,9 @@ declare class unstable_RouterContextProvider {
      * @param value The value to set for the context
      * @returns {void}
      */
-    set<C extends unstable_RouterContext>(context: C, value: C extends unstable_RouterContext<infer T> ? T : never): void;
+    set<C extends RouterContext>(context: C, value: C extends RouterContext<infer T> ? T : never): void;
 }
-type DefaultContext = MiddlewareEnabled extends true ? Readonly<unstable_RouterContextProvider> : any;
+type DefaultContext = MiddlewareEnabled extends true ? Readonly<RouterContextProvider> : any;
 /**
  * @private
  * Arguments passed to route loader/action functions.  Same for now but we keep
@@ -377,7 +377,7 @@ interface DataFunctionArgs<Context> {
  * Route middleware `next` function to call downstream handlers and then complete
  * middlewares from the bottom-up
  */
-interface unstable_MiddlewareNextFunction<Result = unknown> {
+interface MiddlewareNextFunction<Result = unknown> {
     (): Promise<Result>;
 }
 /**
@@ -386,7 +386,7 @@ interface unstable_MiddlewareNextFunction<Result = unknown> {
  * a `next` function as the second parameter which will call downstream handlers
  * and then complete middlewares from the bottom-up
  */
-type unstable_MiddlewareFunction<Result = unknown> = (args: DataFunctionArgs<Readonly<unstable_RouterContextProvider>>, next: unstable_MiddlewareNextFunction<Result>) => MaybePromise<Result | void>;
+type MiddlewareFunction<Result = unknown> = (args: DataFunctionArgs<Readonly<RouterContextProvider>>, next: MiddlewareNextFunction<Result>) => MaybePromise<Result | void>;
 /**
  * Arguments passed to loader functions
  */
@@ -541,7 +541,7 @@ interface DataStrategyFunctionArgs<Context = DefaultContext> extends DataFunctio
      * Matches for this route extended with Data strategy APIs
      */
     matches: DataStrategyMatch[];
-    unstable_runClientMiddleware: (cb: DataStrategyFunction<Context>) => Promise<Record<string, DataStrategyResult>>;
+    runClientMiddleware: (cb: DataStrategyFunction<Context>) => Promise<Record<string, DataStrategyResult>>;
     /**
      * The key of the fetcher we are calling `dataStrategy` for, otherwise `null`
      * for navigational executions
@@ -586,7 +586,7 @@ type UnsupportedLazyRouteObjectKey = "lazy" | "caseSensitive" | "path" | "id" |
  * onto the route. Either they're meaningful to the router, or they'll get
  * ignored.
  */
-type UnsupportedLazyRouteFunctionKey = UnsupportedLazyRouteObjectKey | "unstable_middleware";
+type UnsupportedLazyRouteFunctionKey = UnsupportedLazyRouteObjectKey | "middleware";
 /**
  * lazy object to load route properties, which can add non-matching
  * related properties to a route
@@ -609,7 +609,7 @@ type AgnosticBaseRouteObject = {
     caseSensitive?: boolean;
     path?: string;
     id?: string;
-    unstable_middleware?: unstable_MiddlewareFunction[];
+    middleware?: MiddlewareFunction[];
     loader?: LoaderFunction | boolean;
     action?: ActionFunction | boolean;
     hasErrorBoundary?: boolean;
@@ -1160,7 +1160,7 @@ interface RouterInit {
     routes: AgnosticRouteObject[];
     history: History;
     basename?: string;
-    unstable_getContext?: () => MaybePromise<unstable_RouterContextProvider>;
+    getContext?: () => MaybePromise<RouterContextProvider>;
     mapRouteProperties?: MapRoutePropertiesFunction;
     future?: Partial<FutureConfig>;
     hydrationRouteProperties?: string[];
@@ -1195,7 +1195,7 @@ interface StaticHandler {
         skipLoaderErrorBubbling?: boolean;
         skipRevalidation?: boolean;
         dataStrategy?: DataStrategyFunction<unknown>;
-        unstable_generateMiddlewareResponse?: (query: (r: Request, args?: {
+        generateMiddlewareResponse?: (query: (r: Request, args?: {
             filterMatchesToLoad?: (match: AgnosticDataRouteMatch) => boolean;
         }) => Promise<StaticHandlerContext | Response>) => MaybePromise<Response>;
     }): Promise<StaticHandlerContext | Response>;
@@ -1203,7 +1203,7 @@ interface StaticHandler {
         routeId?: string;
         requestContext?: unknown;
         dataStrategy?: DataStrategyFunction<unknown>;
-        unstable_generateMiddlewareResponse?: (queryRoute: (r: Request) => Promise<Response>) => MaybePromise<Response>;
+        generateMiddlewareResponse?: (queryRoute: (r: Request) => Promise<Response>) => MaybePromise<Response>;
     }): Promise<any>;
 }
 type ViewTransitionOpts = {
@@ -1431,11 +1431,168 @@ interface CreateStaticHandlerOptions {
 }
 declare function createStaticHandler(routes: AgnosticRouteObject[], opts?: CreateStaticHandlerOptions): StaticHandler;
 
+interface AwaitResolveRenderFunction<Resolve = any> {
+    (data: Awaited<Resolve>): React.ReactNode;
+}
+/**
+ * @category Types
+ */
+interface AwaitProps<Resolve> {
+    /**
+     * When using a function, the resolved value is provided as the parameter.
+     *
+     * ```tsx [2]
+     * <Await resolve={reviewsPromise}>
+     *   {(resolvedReviews) => <Reviews items={resolvedReviews} />}
+     * </Await>
+     * ```
+     *
+     * When using React elements, {@link useAsyncValue} will provide the
+     * resolved value:
+     *
+     * ```tsx [2]
+     * <Await resolve={reviewsPromise}>
+     *   <Reviews />
+     * </Await>
+     *
+     * function Reviews() {
+     *   const resolvedReviews = useAsyncValue();
+     *   return <div>...</div>;
+     * }
+     * ```
+     */
+    children: React.ReactNode | AwaitResolveRenderFunction<Resolve>;
+    /**
+     * The error element renders instead of the `children` when the [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
+     * rejects.
+     *
+     * ```tsx
+     * <Await
+     *   errorElement={<div>Oops</div>}
+     *   resolve={reviewsPromise}
+     * >
+     *   <Reviews />
+     * </Await>
+     * ```
+     *
+     * To provide a more contextual error, you can use the {@link useAsyncError} in a
+     * child component
+     *
+     * ```tsx
+     * <Await
+     *   errorElement={<ReviewsError />}
+     *   resolve={reviewsPromise}
+     * >
+     *   <Reviews />
+     * </Await>
+     *
+     * function ReviewsError() {
+     *   const error = useAsyncError();
+     *   return <div>Error loading reviews: {error.message}</div>;
+     * }
+     * ```
+     *
+     * If you do not provide an `errorElement`, the rejected value will bubble up
+     * to the nearest route-level [`ErrorBoundary`](../../start/framework/route-module#errorboundary)
+     * and be accessible via the {@link useRouteError} hook.
+     */
+    errorElement?: React.ReactNode;
+    /**
+     * Takes a [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
+     * returned from a [`loader`](../../start/framework/route-module#loader) to be
+     * resolved and rendered.
+     *
+     * ```tsx
+     * import { Await, useLoaderData } from "react-router";
+     *
+     * export async function loader() {
+     *   let reviews = getReviews(); // not awaited
+     *   let book = await getBook();
+     *   return {
+     *     book,
+     *     reviews, // this is a promise
+     *   };
+     * }
+     *
+     * export default function Book() {
+     *   const {
+     *     book,
+     *     reviews, // this is the same promise
+     *   } = useLoaderData();
+     *
+     *   return (
+     *     <div>
+     *       <h1>{book.title}</h1>
+     *       <p>{book.description}</p>
+     *       <React.Suspense fallback={<ReviewsSkeleton />}>
+     *         <Await
+     *           // and is the promise we pass to Await
+     *           resolve={reviews}
+     *         >
+     *           <Reviews />
+     *         </Await>
+     *       </React.Suspense>
+     *     </div>
+     *   );
+     * }
+     * ```
+     */
+    resolve: Resolve;
+}
+/**
+ * Used to render promise values with automatic error handling.
+ *
+ * **Note:** `<Await>` expects to be rendered inside a [`<React.Suspense>`](https://react.dev/reference/react/Suspense)
+ *
+ * @example
+ * import { Await, useLoaderData } from "react-router";
+ *
+ * export async function loader() {
+ *   // not awaited
+ *   const reviews = getReviews();
+ *   // awaited (blocks the transition)
+ *   const book = await fetch("/api/book").then((res) => res.json());
+ *   return { book, reviews };
+ * }
+ *
+ * function Book() {
+ *   const { book, reviews } = useLoaderData();
+ *   return (
+ *     <div>
+ *       <h1>{book.title}</h1>
+ *       <p>{book.description}</p>
+ *       <React.Suspense fallback={<ReviewsSkeleton />}>
+ *         <Await
+ *           resolve={reviews}
+ *           errorElement={
+ *             <div>Could not load reviews 😬</div>
+ *           }
+ *           children={(resolvedReviews) => (
+ *             <Reviews items={resolvedReviews} />
+ *           )}
+ *         />
+ *       </React.Suspense>
+ *     </div>
+ *   );
+ * }
+ *
+ * @public
+ * @category Components
+ * @mode framework
+ * @mode data
+ * @param props Props
+ * @param {AwaitProps.children} props.children n/a
+ * @param {AwaitProps.errorElement} props.errorElement n/a
+ * @param {AwaitProps.resolve} props.resolve n/a
+ * @returns React element for the rendered awaited value
+ */
+declare function Await$1<Resolve>({ children, errorElement, resolve, }: AwaitProps<Resolve>): React.JSX.Element;
+
 interface IndexRouteObject {
     caseSensitive?: AgnosticIndexRouteObject["caseSensitive"];
     path?: AgnosticIndexRouteObject["path"];
     id?: AgnosticIndexRouteObject["id"];
-    unstable_middleware?: AgnosticIndexRouteObject["unstable_middleware"];
+    middleware?: AgnosticIndexRouteObject["middleware"];
     loader?: AgnosticIndexRouteObject["loader"];
     action?: AgnosticIndexRouteObject["action"];
     hasErrorBoundary?: AgnosticIndexRouteObject["hasErrorBoundary"];
@@ -1455,7 +1612,7 @@ interface NonIndexRouteObject {
     caseSensitive?: AgnosticNonIndexRouteObject["caseSensitive"];
     path?: AgnosticNonIndexRouteObject["path"];
     id?: AgnosticNonIndexRouteObject["id"];
-    unstable_middleware?: AgnosticNonIndexRouteObject["unstable_middleware"];
+    middleware?: AgnosticNonIndexRouteObject["middleware"];
     loader?: AgnosticNonIndexRouteObject["loader"];
     action?: AgnosticNonIndexRouteObject["action"];
     hasErrorBoundary?: AgnosticNonIndexRouteObject["hasErrorBoundary"];
@@ -1641,14 +1798,14 @@ type ClientDataFunctionArgs<Params> = {
      **/
     params: Params;
     /**
-     * When `future.unstable_middleware` is not enabled, this is undefined.
+     * When `future.v8_middleware` is not enabled, this is undefined.
      *
-     * When `future.unstable_middleware` is enabled, this is an instance of
-     * `unstable_RouterContextProvider` and can be used to access context values
+     * When `future.v8_middleware` is enabled, this is an instance of
+     * `RouterContextProvider` and can be used to access context values
      * from your route middlewares.  You may pass in initial context values in your
-     * `<HydratedRouter unstable_getContext>` prop
+     * `<HydratedRouter getContext>` prop
      */
-    context: Readonly<unstable_RouterContextProvider>;
+    context: Readonly<RouterContextProvider>;
 };
 type SerializeFrom<T> = T extends (...args: infer Args) => unknown ? Args extends [
     ClientLoaderFunctionArgs | ClientActionFunctionArgs | ClientDataFunctionArgs<unknown>
@@ -1813,6 +1970,7 @@ type RouteHandle = unknown;
 declare const redirect: typeof redirect$1;
 declare const redirectDocument: typeof redirectDocument$1;
 declare const replace: typeof replace$1;
+declare const Await: typeof Await$1;
 type RSCRouteConfigEntryBase = {
     action?: ActionFunction;
     clientAction?: ClientActionFunction;
@@ -1971,7 +2129,7 @@ type LoadServerActionFunction = (id: string) => Promise<Function>;
  * errors that occur during the request processing.
  * @param opts.request The [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request)
  * to match against.
- * @param opts.requestContext An instance of {@link unstable_RouterContextProvider}
+ * @param opts.requestContext An instance of {@link RouterContextProvider}
  * that should be created per request, to be passed to [`action`](../../start/data/route-object#action)s,
  * [`loader`](../../start/data/route-object#loader)s and [middleware](../../how-to/middleware).
  * @param opts.routes Your {@link unstable_RSCRouteConfigEntry | route definitions}.
@@ -1985,7 +2143,7 @@ declare function matchRSCServerRequest({ createTemporaryReferenceSet, basename,
     decodeReply?: DecodeReplyFunction;
     decodeAction?: DecodeActionFunction;
     decodeFormState?: DecodeFormStateFunction;
-    requestContext?: unstable_RouterContextProvider;
+    requestContext?: RouterContextProvider;
     loadServerAction?: LoadServerActionFunction;
     onError?: (error: unknown) => void;
     request: Request;
@@ -1995,6 +2153,40 @@ declare function matchRSCServerRequest({ createTemporaryReferenceSet, basename,
     }) => Response;
 }): Promise<Response>;
 
+/**
+ * Apps can use this interface to "register" app-wide types for React Router via interface declaration merging and module augmentation.
+ * React Router should handle this for you via type generation.
+ *
+ * For more on declaration merging and module augmentation, see https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation .
+ */
+interface Register {
+}
+type AnyParams = Record<string, string | undefined>;
+type AnyPages = Record<string, {
+    params: AnyParams;
+}>;
+type Pages = Register extends {
+    pages: infer Registered extends AnyPages;
+} ? Registered : AnyPages;
+
+type Args = {
+    [K in keyof Pages]: ToArgs<Pages[K]["params"]>;
+};
+type ToArgs<Params extends Record<string, string | undefined>> = Equal<Params, {}> extends true ? [] : Partial<Params> extends Params ? [Params] | [] : [
+    Params
+];
+/**
+  Returns a resolved URL path for the specified route.
+
+  ```tsx
+  const h = href("/:lang?/about", { lang: "en" })
+  // -> `/en/about`
+
+  <Link to={href("/products/:id", { id: "abc123" })} />
+  ```
+ */
+declare function href<Path extends keyof Args>(path: Path, ...args: Args[Path]): string;
+
 interface CookieSignatureOptions {
     /**
      * An array of secrets that may be used to sign/unsign the value of a cookie.
@@ -2225,4 +2417,4 @@ interface MemorySessionStorageOptions {
  */
 declare function createMemorySessionStorage<Data = SessionData, FlashData = Data>({ cookie }?: MemorySessionStorageOptions): SessionStorage<Data, FlashData>;
 
-export { type Cookie, type CookieOptions, type CookieSignatureOptions, type FlashSessionData, type IsCookieFunction, type IsSessionFunction, type Session, type SessionData, type SessionIdStorageStrategy, type SessionStorage, createCookie, createCookieSessionStorage, createMemorySessionStorage, createSession, createSessionStorage, createStaticHandler, data, isCookie, isRouteErrorResponse, isSession, matchRoutes, redirect, redirectDocument, replace, type DecodeActionFunction as unstable_DecodeActionFunction, type DecodeFormStateFunction as unstable_DecodeFormStateFunction, type DecodeReplyFunction as unstable_DecodeReplyFunction, type LoadServerActionFunction as unstable_LoadServerActionFunction, type unstable_MiddlewareFunction, type unstable_MiddlewareNextFunction, type RSCManifestPayload as unstable_RSCManifestPayload, type RSCMatch as unstable_RSCMatch, type RSCPayload as unstable_RSCPayload, type RSCRenderPayload as unstable_RSCRenderPayload, type RSCRouteConfig as unstable_RSCRouteConfig, type RSCRouteConfigEntry as unstable_RSCRouteConfigEntry, type RSCRouteManifest as unstable_RSCRouteManifest, type RSCRouteMatch as unstable_RSCRouteMatch, type unstable_RouterContext, unstable_RouterContextProvider, unstable_createContext, matchRSCServerRequest as unstable_matchRSCServerRequest };
+export { Await, type Cookie, type CookieOptions, type CookieSignatureOptions, type FlashSessionData, type IsCookieFunction, type IsSessionFunction, type MiddlewareFunction, type MiddlewareNextFunction, type RouterContext, RouterContextProvider, type Session, type SessionData, type SessionIdStorageStrategy, type SessionStorage, createContext, createCookie, createCookieSessionStorage, createMemorySessionStorage, createSession, createSessionStorage, createStaticHandler, data, href, isCookie, isRouteErrorResponse, isSession, matchRoutes, redirect, redirectDocument, replace, type DecodeActionFunction as unstable_DecodeActionFunction, type DecodeFormStateFunction as unstable_DecodeFormStateFunction, type DecodeReplyFunction as unstable_DecodeReplyFunction, type LoadServerActionFunction as unstable_LoadServerActionFunction, type RSCManifestPayload as unstable_RSCManifestPayload, type RSCMatch as unstable_RSCMatch, type RSCPayload as unstable_RSCPayload, type RSCRenderPayload as unstable_RSCRenderPayload, type RSCRouteConfig as unstable_RSCRouteConfig, type RSCRouteConfigEntry as unstable_RSCRouteConfigEntry, type RSCRouteManifest as unstable_RSCRouteManifest, type RSCRouteMatch as unstable_RSCRouteMatch, matchRSCServerRequest as unstable_matchRSCServerRequest };