react-router 0.0.0-experimental-2a6c7bc → 0.0.0-experimental-e89ad3012

package/dist/production/index.mjs

@@ -1,5 +1,5 @@
 /**
- * react-router v0.0.0-experimental-2a6c7bc
+ * react-router v0.0.0-experimental-e89ad3012
  *
  * Copyright (c) Remix Software Inc.
  *
@@ -31,7 +31,7 @@ import {
   isSession,
   routeRSCServerRequest,
   setDevServerHooks
-} from "./chunk-ATNMTWNA.mjs";
+} from "./chunk-J6PLTU3O.mjs";
 import {
   Action,
   Await,
@@ -140,7 +140,7 @@ import {
   withComponentProps,
   withErrorBoundaryProps,
   withHydrateFallbackProps
-} from "./chunk-P2JVUBYL.mjs";
+} from "./chunk-QI3NR5VQ.mjs";
 export {
   Await,
   BrowserRouter,

package/dist/production/lib/types/internal.d.mts

@@ -1,5 +1,5 @@
-import { R as RouteModule, L as LinkDescriptor, P as Pretty, M as MetaDescriptor, G as GetLoaderData, S as ServerDataFunctionArgs, C as ClientDataFunctionArgs, a as ServerDataFrom, N as Normalize, b as GetActionData } from '../../route-data-BnrIwdAP.mjs';
-import { c as Location, u as unstable_MiddlewareNextFunction } from '../../context-AvZz33Zq.mjs';
+import { R as RouteModule, L as LinkDescriptor, P as Pretty, M as MetaDescriptor, G as GetLoaderData, S as ServerDataFunctionArgs, C as ClientDataFunctionArgs, a as ServerDataFrom, N as Normalize, b as GetActionData } from '../../route-data-DJXZgnJq.mjs';
+import { c as Location, u as unstable_MiddlewareNextFunction } from '../../context-CphUWOpx.mjs';
 import { R as RouteFiles, P as Pages } from '../../register-DiOIlEq5.mjs';
 import 'react';
 

package/dist/production/lib/types/internal.d.ts

@@ -1,4 +1,4 @@
-import { R as RouteModule, L as LinkDescriptor, a as Location, P as Pretty, M as MetaDescriptor, G as GetLoaderData, S as ServerDataFunctionArgs, u as unstable_MiddlewareNextFunction, C as ClientDataFunctionArgs, b as ServerDataFrom, N as Normalize, c as GetActionData } from '../../routeModules-BbH0xTnc.js';
+import { R as RouteModule, L as LinkDescriptor, a as Location, P as Pretty, M as MetaDescriptor, G as GetLoaderData, S as ServerDataFunctionArgs, u as unstable_MiddlewareNextFunction, C as ClientDataFunctionArgs, b as ServerDataFrom, N as Normalize, c as GetActionData } from '../../routeModules-DH3xUx4Z.js';
 import { R as RouteFiles, P as Pages } from '../../register-DiOIlEq5.js';
 import 'react';
 

package/dist/production/lib/types/internal.js

@@ -1,5 +1,5 @@
 "use strict";/**
- * react-router v0.0.0-experimental-2a6c7bc
+ * react-router v0.0.0-experimental-e89ad3012
  *
  * Copyright (c) Remix Software Inc.
  *

package/dist/production/lib/types/internal.mjs

@@ -1,5 +1,5 @@
 /**
- * react-router v0.0.0-experimental-2a6c7bc
+ * react-router v0.0.0-experimental-e89ad3012
  *
  * Copyright (c) Remix Software Inc.
  *

package/dist/production/{route-data-BnrIwdAP.d.mts → route-data-DJXZgnJq.d.mts}

@@ -1,5 +1,5 @@
 import { ComponentType, ReactElement } from 'react';
-import { i as ActionFunctionArgs, j as LoaderFunctionArgs, k as ActionFunction, l as LoaderFunction, h as Params, c as Location, m as DataRouteMatch, n as unstable_MiddlewareFunction, S as ShouldRevalidateFunction, o as unstable_RouterContextProvider, p as DataWithResponseInit, M as MiddlewareEnabled } from './context-AvZz33Zq.mjs';
+import { i as ActionFunctionArgs, j as LoaderFunctionArgs, k as ActionFunction, l as LoaderFunction, h as Params, c as Location, m as DataRouteMatch, n as unstable_MiddlewareFunction, S as ShouldRevalidateFunction, o as unstable_RouterContextProvider, p as DataWithResponseInit, M as MiddlewareEnabled } from './context-CphUWOpx.mjs';
 
 /**
  * An object of unknown type for route loaders and actions provided by the

package/dist/production/{routeModules-BbH0xTnc.d.ts → routeModules-DH3xUx4Z.d.ts}

@@ -271,27 +271,117 @@ type Submission = {
     json: undefined;
     text: string;
 };
+/**
+ * A context instance used as the key for the `get`/`set` methods of a
+ * {@link unstable_RouterContextProvider}. Accepts an optional default
+ * value to be returned if no value has been set.
+ */
 interface unstable_RouterContext<T = unknown> {
     defaultValue?: T;
 }
 /**
- * Creates a context object that may be used to store and retrieve arbitrary values.
+ * Creates a type-safe context object that can be used to store and retrieve
+ * values in middleware, [loaders](../../start/framework/route-module#loader),
+ * and [actions](../../start/framework/route-module#action). Similar to React's
+ * [`createContext`](https://react.dev/reference/react/createContext), but
+ * designed for React Router's request/response lifecycle.
+ *
+ * If a `defaultValue` is provided, it will be returned from `context.get()` when
+ * no value has been set for the context. Otherwise reading this context when no
+ * value has been set will throw an error.
+ *
+ * ```tsx filename=app/context.ts
+ * import { unstable_createContext } from "react-router";
  *
- * If a `defaultValue` is provided, it will be returned from `context.get()` when no value has been
- * set for the context. Otherwise reading this context when no value has been set will throw an
- * error.
+ * // Create a context for user data
+ * export const userContext =
+ *   unstable_createContext<User | null>(null);
+ * ```
+ *
+ * ```tsx filename=app/middleware/auth.ts
+ * import { userContext } from "~/context";
+ * import { getUserFromSession } from "~/auth.server";
+ *
+ * export const authMiddleware = async ({
+ *   request,
+ *   context,
+ * }) => {
+ *   const user = await getUserFromSession(request);
+ *   context.set(userContext, user);
+ * };
+ * ```
  *
- * @param defaultValue The default value for the context
- * @returns A context object
+ * ```tsx filename=app/routes/profile.tsx
+ * import { userContext } from "~/context";
+ *
+ * export async function loader({
+ *   context,
+ * }: Route.LoaderArgs) {
+ *   const user = context.get(userContext);
+ *
+ *   if (!user) {
+ *     throw new Response("Unauthorized", { status: 401 });
+ *   }
+ *
+ *   return { user };
+ * }
+ * ```
+ *
+ * @public
+ * @category Utils
+ * @mode framework
+ * @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
+ * `context.get()` and `context.set()` in middleware, loaders, and actions.
  */
 declare function unstable_createContext<T>(defaultValue?: T): unstable_RouterContext<T>;
 /**
- * Provides methods for writing/reading values in application context in a typesafe way.
+ * 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
+ * } from "react-router";
+ *
+ * const userContext = unstable_createContext<User | null>(null);
+ * const contextProvider = new unstable_RouterContextProvider();
+ * contextProvider.set(userContext, getUser());
+ * const user = contextProvider.get(userContext);
+ * //    ^ User
+ *
+ * @public
+ * @category Utils
+ * @mode framework
+ * @mode data
  */
 declare class unstable_RouterContextProvider {
     #private;
+    /**
+     * Create a new `unstable_RouterContextProvider` instance
+     * @param init An optional initial context map to populate the provider with
+     */
     constructor(init?: Map<unstable_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 if no `defaultValue` was set.
+     * @param context The context to get the value for
+     * @returns The value for the context, or the contexts `defaultValue` if no
+     * value was set
+     */
     get<T>(context: unstable_RouterContext<T>): T;
+    /**
+     * Set a value for the context. If the context already has a value set,
+     * this will overwrite it.
+     *
+     * @param context The context to set the value for
+     * @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;
 }
 type DefaultContext = MiddlewareEnabled extends true ? Readonly<unstable_RouterContextProvider> : any;
@@ -316,7 +406,7 @@ interface DataFunctionArgs<Context> {
      *   params.teamId;
      *   //        ^ string
      * }
-     **/
+     */
     params: Params;
     /**
      * This is the context passed in to your server adapter's getLoadContext() function.
@@ -643,7 +733,27 @@ interface AgnosticDataRouteMatch extends AgnosticRouteMatch<string, AgnosticData
 /**
  * Matches the given routes to a location and returns the match data.
  *
+ * @example
+ * import { matchRoutes } from "react-router";
+ *
+ * let routes = [{
+ *   path: "/",
+ *   Component: Root,
+ *   children: [{
+ *     path: "dashboard",
+ *     Component: Dashboard,
+ *   }]
+ * }];
+ *
+ * matchRoutes(routes, "/dashboard"); // [rootMatch, dashboardMatch]
+ *
+ * @public
  * @category Utils
+ * @param routes The array of route objects to match against.
+ * @param locationArg The location to match against, either a string path or a
+ * partial {@link Location} object
+ * @param basename Optional base path to strip from the location before matching.
+ * @returns An array of matched routes, or `null` if no matches were found.
  */
 declare function matchRoutes<RouteObjectType extends AgnosticRouteObject = AgnosticRouteObject>(routes: RouteObjectType[], locationArg: Partial<Location> | string, basename?: string): AgnosticRouteMatch<string, RouteObjectType>[] | null;
 interface UIMatch<Data = unknown, Handle = unknown> {
@@ -651,7 +761,7 @@ interface UIMatch<Data = unknown, Handle = unknown> {
     pathname: string;
     /**
      * {@link https://reactrouter.com/start/framework/routing#dynamic-segments Dynamic route params} for the matched route.
-     **/
+     */
     params: AgnosticRouteMatch["params"];
     /**
      * The return value from the matched route's loader or clientLoader
@@ -667,7 +777,16 @@ interface UIMatch<Data = unknown, Handle = unknown> {
 /**
  * Returns a path with params interpolated.
  *
+ * @example
+ * import { generatePath } from "react-router";
+ *
+ * generatePath("/users/:id", { id: "123" }); // "/users/123"
+ *
+ * @public
  * @category Utils
+ * @param originalPath The original path to generate.
+ * @param params The parameters to interpolate into the path.
+ * @returns The generated path with parameters interpolated.
  */
 declare function generatePath<Path extends string>(originalPath: Path, params?: {
     [key in PathParam<Path>]: string | null;
@@ -717,13 +836,25 @@ interface PathMatch<ParamKey extends string = string> {
  * Performs pattern matching on a URL pathname and returns information about
  * the match.
  *
+ * @public
  * @category Utils
+ * @param pattern The pattern to match against the URL pathname. This can be a
+ * string or a {@link PathPattern} object. If a string is provided, it will
+ * be treated as a pattern with `caseSensitive` set to `false` and `end
+ * set to `true`.
+ * @param pathname The URL pathname to match against the pattern.
+ * @returns A path match object if the pattern matches the pathname,
+ * or `null` if it does not match.
  */
 declare function matchPath<ParamKey extends ParamParseKey<Path>, Path extends string>(pattern: PathPattern<Path> | Path, pathname: string): PathMatch<ParamKey> | null;
 /**
  * Returns a resolved path object relative to the given pathname.
  *
+ * @public
  * @category Utils
+ * @param to The path to resolve, either a string or a partial {@link Path} object.
+ * @param fromPathname The pathname to resolve the path from. Defaults to `/`.
+ * @returns A {@link Path} object with the resolved pathname, search, and hash.
  */
 declare function resolvePath(to: To, fromPathname?: string): Path;
 declare class DataWithResponseInit<D> {
@@ -734,9 +865,29 @@ declare class DataWithResponseInit<D> {
 }
 /**
  * Create "responses" that contain `status`/`headers` without forcing
- * serialization into an actual `Response` - used by Remix single fetch
+ * serialization into an actual `Response`
+ *
+ * @example
+ * import { data } from "react-router";
  *
+ * export async function action({ request }) {
+ *   let formData = await request.formData();
+ *   let item = await createItem(formData);
+ *   return data(item, {
+ *     status: 201,
+ *     headers: { "X-Custom-Header": "value" }
+ *   });
+ * }
+ *
+ * @public
  * @category Utils
+ * @mode framework
+ * @mode data
+ * @param data The data to be included in the response.
+ * @param init The status code or a `ResponseInit` object to be included in the
+ * response.
+ * @returns A `DataWithResponseInit` instance containing the data and response
+ * init.
  */
 declare function data<D>(data: D, init?: number | ResponseInit): DataWithResponseInit<D>;
 type RedirectFunction = (url: string, init?: number | ResponseInit) => Response;
@@ -744,7 +895,25 @@ type RedirectFunction = (url: string, init?: number | ResponseInit) => Response;
  * A redirect response. Sets the status code and the `Location` header.
  * Defaults to "302 Found".
  *
+ * @example
+ * import { redirect } from "react-router";
+ *
+ * export function loader({ request }) {
+ *   if (!isLoggedIn(request))
+ *     throw redirect("/login");
+ *   }
+ *
+ *   // ...
+ * }
+ *
+ * @public
  * @category Utils
+ * @mode framework
+ * @mode data
+ * @param url The URL to redirect to.
+ * @param init The status code or a `ResponseInit` object to be included in the
+ * response.
+ * @returns A `Response` object with the redirect status and `Location` header.
  */
 declare const redirect: RedirectFunction;
 /**
@@ -752,7 +921,26 @@ declare const redirect: RedirectFunction;
  * Sets the status code and the `Location` header.
  * Defaults to "302 Found".
  *
+ * @example
+ * // routes/logout.tsx
+ * import { redirectDocument } from "react-router";
+ * import { destroySession } from "../sessions.server";
+ *
+ * export async function action({ request }) {
+ *   let session = await getSession(request.headers.get("Cookie"));
+ *   return redirectDocument("/", {
+ *     headers: { "Set-Cookie": await destroySession(session) }
+ *   });
+ * }
+ *
+ * @public
  * @category Utils
+ * @mode framework
+ * @mode data
+ * @param url The URL to redirect to.
+ * @param init The status code or a `ResponseInit` object to be included in the
+ * response.
+ * @returns A `Response` object with the redirect status and `Location` header.
  */
 declare const redirectDocument: RedirectFunction;
 /**
@@ -761,7 +949,21 @@ declare const redirectDocument: RedirectFunction;
  * Sets the status code and the `Location` header.
  * Defaults to "302 Found".
  *
+ * @example
+ * import { replace } from "react-router";
+ *
+ * export function loader() {
+ *   return replace("/new-location");
+ * }
+ *
+ * @public
  * @category Utils
+ * @mode framework
+ * @mode data
+ * @param url The URL to redirect to.
+ * @param init The status code or a `ResponseInit` object to be included in the
+ * response.
+ * @returns A `Response` object with the redirect status and `Location` header.
  */
 declare const replace: RedirectFunction;
 type ErrorResponse = {
@@ -769,14 +971,6 @@ type ErrorResponse = {
     statusText: string;
     data: any;
 };
-/**
- * @private
- * Utility class we use to hold auto-unwrapped 4xx/5xx Response bodies
- *
- * We don't export the class for public use since it's an implementation
- * detail, but we export the interface above so folks can build their own
- * abstractions around instances via isRouteErrorResponse()
- */
 declare class ErrorResponseImpl implements ErrorResponse {
     status: number;
     statusText: string;
@@ -789,7 +983,31 @@ declare class ErrorResponseImpl implements ErrorResponse {
  * Check if the given error is an ErrorResponse generated from a 4xx/5xx
  * Response thrown from an action/loader
  *
+ * @example
+ * import { isRouteErrorResponse } from "react-router";
+ *
+ * export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) {
+ *   if (isRouteErrorResponse(error)) {
+ *     return (
+ *       <>
+ *         <p>Error: {{error.status}: {error.statusText}}</p>
+ *         <p>{error.data}</p>
+ *       </>
+ *     );
+ *   }
+ *
+ *   return (
+ *     <p>Error: {error instanceof Error ? error.message : "Unknown Error"}</p>
+ *   );
+ * }
+ *
+ * @public
  * @category Utils
+ * @mode framework
+ * @mode data
+ * @param error The error to check.
+ * @returns `true` if the error is an `ErrorResponse`, `false` otherwise.
+ *
  */
 declare function isRouteErrorResponse(error: any): error is ErrorResponse;
 
@@ -1102,15 +1320,13 @@ interface StaticHandler {
         skipLoaderErrorBubbling?: boolean;
         skipRevalidation?: boolean;
         dataStrategy?: DataStrategyFunction<unknown>;
-        unstable_respond?: (staticContext: StaticHandlerContext) => MaybePromise<Response>;
-        unstable_stream?: (context: unstable_RouterContextProvider, query: (r: Request) => Promise<StaticHandlerContext | Response>) => MaybePromise<Response>;
+        unstable_generateMiddlewareResponse?: (query: (r: Request) => Promise<StaticHandlerContext | Response>) => MaybePromise<Response>;
     }): Promise<StaticHandlerContext | Response>;
     queryRoute(request: Request, opts?: {
         routeId?: string;
         requestContext?: unknown;
         dataStrategy?: DataStrategyFunction<unknown>;
-        unstable_respond?: (res: Response) => MaybePromise<Response>;
-        unstable_stream?: (context: unstable_RouterContextProvider, queryRoute: (r: Request) => Promise<Response>) => MaybePromise<Response>;
+        unstable_generateMiddlewareResponse?: (queryRoute: (r: Request) => Promise<Response>) => MaybePromise<Response>;
     }): Promise<any>;
 }
 type ViewTransitionOpts = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-router",
-  "version": "0.0.0-experimental-2a6c7bc",
+  "version": "0.0.0-experimental-e89ad3012",
   "description": "Declarative routing for React",
   "keywords": [
     "react",