react-router 7.15.1 → 8.3.0

package/dist/development/lib/dom/ssr/routeModules.d.ts

@@ -0,0 +1,206 @@
+
+import { Location } from "../../router/history.js";
+import { ActionFunction, ActionFunctionArgs, DataRouteMatch, DataStrategyResult, LoaderFunction, LoaderFunctionArgs, MiddlewareFunction, Params, ShouldRevalidateFunction } from "../../router/utils.js";
+import { LinkDescriptor } from "../../router/links.js";
+import { SerializeFrom } from "../../types/route-data.js";
+import { ComponentType, ReactElement } from "react";
+
+//#region lib/dom/ssr/routeModules.d.ts
+interface RouteModules {
+  [routeId: string]: RouteModule | undefined;
+}
+/**
+ * The shape of a route module shipped to the client
+ */
+interface RouteModule {
+  clientAction?: ClientActionFunction;
+  clientLoader?: ClientLoaderFunction;
+  clientMiddleware?: MiddlewareFunction<Record<string, DataStrategyResult>>[];
+  ErrorBoundary?: ErrorBoundaryComponent;
+  HydrateFallback?: HydrateFallbackComponent;
+  Layout?: LayoutComponent;
+  default: RouteComponent;
+  handle?: RouteHandle;
+  links?: LinksFunction;
+  meta?: MetaFunction;
+  shouldRevalidate?: ShouldRevalidateFunction;
+}
+/**
+ * The shape of a route module on the server
+ */
+interface ServerRouteModule extends RouteModule {
+  action?: ActionFunction;
+  headers?: HeadersFunction | {
+    [name: string]: string;
+  };
+  loader?: LoaderFunction;
+  middleware?: MiddlewareFunction<Response>[];
+}
+/**
+ * A function that handles data mutations for a route on the client
+ */
+type ClientActionFunction = (args: ClientActionFunctionArgs) => ReturnType<ActionFunction>;
+/**
+ * Arguments passed to a route `clientAction` function
+ */
+type ClientActionFunctionArgs = ActionFunctionArgs & {
+  serverAction: <T = unknown>() => Promise<SerializeFrom<T>>;
+};
+/**
+ * A function that loads data for a route on the client
+ */
+type ClientLoaderFunction = ((args: ClientLoaderFunctionArgs) => ReturnType<LoaderFunction>) & {
+  hydrate?: boolean;
+};
+/**
+ * Arguments passed to a route `clientLoader` function
+ */
+type ClientLoaderFunctionArgs = LoaderFunctionArgs & {
+  serverLoader: <T = unknown>() => Promise<SerializeFrom<T>>;
+};
+/**
+ * ErrorBoundary to display for this route
+ */
+type ErrorBoundaryComponent = ComponentType;
+type HeadersArgs = {
+  loaderHeaders: Headers;
+  parentHeaders: Headers;
+  actionHeaders: Headers;
+  errorHeaders: Headers | undefined;
+};
+/**
+ * A function that returns HTTP headers to be used for a route. These headers
+ * will be merged with (and take precedence over) headers from parent routes.
+ */
+interface HeadersFunction {
+  (args: HeadersArgs): Headers | HeadersInit;
+}
+/**
+ * `<Route HydrateFallback>` component to render on initial loads
+ * when client loaders are present
+ */
+type HydrateFallbackComponent = ComponentType;
+/**
+ * Optional, root-only `<Route Layout>` component to wrap the root content in.
+ * Useful for defining the <html>/<head>/<body> document shell shared by the
+ * Component, HydrateFallback, and ErrorBoundary
+ */
+type LayoutComponent = ComponentType<{
+  children: ReactElement<unknown, ErrorBoundaryComponent | HydrateFallbackComponent | RouteComponent>;
+}>;
+/**
+ * A function that defines `<link>` tags to be inserted into the `<head>` of
+ * the document on route transitions.
+ *
+ * @see https://reactrouter.com/start/framework/route-module#meta
+ */
+interface LinksFunction {
+  (): LinkDescriptor[];
+}
+interface MetaMatch<RouteId extends string = string, Loader extends LoaderFunction | ClientLoaderFunction | unknown = unknown> {
+  id: RouteId;
+  pathname: DataRouteMatch["pathname"];
+  loaderData: Loader extends LoaderFunction | ClientLoaderFunction ? SerializeFrom<Loader> : unknown;
+  handle?: RouteHandle;
+  params: DataRouteMatch["params"];
+  meta: MetaDescriptor[];
+  error?: unknown;
+}
+type MetaMatches<MatchLoaders extends Record<string, LoaderFunction | ClientLoaderFunction | unknown> = Record<string, unknown>> = Array<{ [K in keyof MatchLoaders]: MetaMatch<Exclude<K, number | symbol>, MatchLoaders[K]> }[keyof MatchLoaders]>;
+interface MetaArgs<Loader extends LoaderFunction | ClientLoaderFunction | unknown = unknown, MatchLoaders extends Record<string, LoaderFunction | ClientLoaderFunction | unknown> = Record<string, unknown>> {
+  loaderData: (Loader extends LoaderFunction | ClientLoaderFunction ? SerializeFrom<Loader> : unknown) | undefined;
+  params: Params;
+  location: Location;
+  matches: MetaMatches<MatchLoaders>;
+  error?: unknown;
+}
+/**
+ * A function that returns an array of data objects to use for rendering
+ * metadata HTML tags in a route. These tags are not rendered on descendant
+ * routes in the route hierarchy. In other words, they will only be rendered on
+ * the route in which they are exported.
+ *
+ * @param Loader - The type of the current route's loader function
+ * @param MatchLoaders - Mapping from a parent route's filepath to its loader
+ * function type
+ *
+ * Note that parent route filepaths are relative to the `app/` directory.
+ *
+ * For example, if this meta function is for `/sales/customers/$customerId`:
+ *
+ * ```ts
+ * // app/root.tsx
+ * const loader = () => ({ hello: "world" })
+ * export type Loader = typeof loader
+ *
+ * // app/routes/sales.tsx
+ * const loader = () => ({ salesCount: 1074 })
+ * export type Loader = typeof loader
+ *
+ * // app/routes/sales/customers.tsx
+ * const loader = () => ({ customerCount: 74 })
+ * export type Loader = typeof loader
+ *
+ * // app/routes/sales/customers/$customersId.tsx
+ * import type { Loader as RootLoader } from "../../../root"
+ * import type { Loader as SalesLoader } from "../../sales"
+ * import type { Loader as CustomersLoader } from "../../sales/customers"
+ *
+ * const loader = () => ({ name: "Customer name" })
+ *
+ * const meta: MetaFunction<typeof loader, {
+ *  "root": RootLoader,
+ *  "routes/sales": SalesLoader,
+ *  "routes/sales/customers": CustomersLoader,
+ * }> = ({ loaderData, matches }) => {
+ *   const { name } = loaderData
+ *   //      ^? string
+ *   const { customerCount } = matches.find((match) => match.id === "routes/sales/customers").loaderData
+ *   //      ^? number
+ *   const { salesCount } = matches.find((match) => match.id === "routes/sales").loaderData
+ *   //      ^? number
+ *   const { hello } = matches.find((match) => match.id === "root").loaderData
+ *   //      ^? "world"
+ * }
+ * ```
+ */
+interface MetaFunction<Loader extends LoaderFunction | ClientLoaderFunction | unknown = unknown, MatchLoaders extends Record<string, LoaderFunction | ClientLoaderFunction | unknown> = Record<string, unknown>> {
+  (args: MetaArgs<Loader, MatchLoaders>): MetaDescriptor[] | undefined;
+}
+type MetaDescriptor = {
+  charSet: "utf-8";
+} | {
+  title: string;
+} | {
+  name: string;
+  content: string;
+} | {
+  property: string;
+  content: string;
+} | {
+  httpEquiv: string;
+  content: string;
+} | {
+  "script:ld+json": LdJsonObject | LdJsonObject[];
+} | {
+  tagName: "meta" | "link";
+  [name: string]: string;
+} | {
+  [name: string]: unknown;
+};
+type LdJsonObject = { [Key in string]: LdJsonValue } & { [Key in string]?: LdJsonValue | undefined };
+type LdJsonArray = LdJsonValue[] | readonly LdJsonValue[];
+type LdJsonPrimitive = string | number | boolean | null;
+type LdJsonValue = LdJsonPrimitive | LdJsonObject | LdJsonArray;
+/**
+ * A React component that is rendered for a route.
+ */
+type RouteComponent = ComponentType<{}>;
+/**
+ * An arbitrary object that is associated with a route.
+ *
+ * @see https://reactrouter.com/how-to/using-handle
+ */
+type RouteHandle = unknown;
+//#endregion
+export { ClientActionFunction, ClientActionFunctionArgs, ClientLoaderFunction, ClientLoaderFunctionArgs, HeadersArgs, HeadersFunction, LinksFunction, MetaArgs, MetaDescriptor, MetaFunction, RouteModules, ServerRouteModule };

package/dist/development/lib/dom/ssr/routeModules.js

@@ -0,0 +1,31 @@
+/**
+ * react-router v8.3.0
+ *
+ * Copyright (c) Remix Software Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE.md file in the root directory of this source tree.
+ *
+ * @license MIT
+ */
+//#region lib/dom/ssr/routeModules.ts
+async function loadRouteModule(route, routeModulesCache) {
+	if (route.id in routeModulesCache) return routeModulesCache[route.id];
+	try {
+		let routeModule = await import(
+			/* @vite-ignore */
+			/* webpackIgnore: true */
+			route.module
+);
+		routeModulesCache[route.id] = routeModule;
+		return routeModule;
+	} catch (error) {
+		console.error(`Error loading route module \`${route.module}\`, reloading page...`);
+		console.error(error);
+		if (window.__reactRouterContext && window.__reactRouterContext.isSpaMode && import.meta.hot) throw error;
+		window.location.reload();
+		return new Promise(() => {});
+	}
+}
+//#endregion
+export { loadRouteModule };

package/dist/development/lib/dom/ssr/routes-test-stub.d.ts

@@ -0,0 +1,75 @@
+
+import { InitialEntry } from "../../router/history.js";
+import { ActionFunction, IndexRouteObject, LoaderFunction, NonIndexRouteObject, RouterContextProvider } from "../../router/utils.js";
+import { HydrationState } from "../../router/router.js";
+import { LinksFunction, MetaFunction } from "./routeModules.js";
+import { FutureConfig } from "./entry.js";
+import * as React$1 from "react";
+
+//#region lib/dom/ssr/routes-test-stub.d.ts
+interface StubRouteExtensions {
+  Component?: React$1.ComponentType<any>;
+  HydrateFallback?: React$1.ComponentType<any>;
+  ErrorBoundary?: React$1.ComponentType<any>;
+  loader?: LoaderFunction;
+  action?: ActionFunction;
+  children?: StubRouteObject[];
+  meta?: MetaFunction;
+  links?: LinksFunction;
+}
+interface StubIndexRouteObject extends Omit<IndexRouteObject, "Component" | "HydrateFallback" | "ErrorBoundary" | "loader" | "action" | "element" | "errorElement" | "children">, StubRouteExtensions {}
+interface StubNonIndexRouteObject extends Omit<NonIndexRouteObject, "Component" | "HydrateFallback" | "ErrorBoundary" | "loader" | "action" | "element" | "errorElement" | "children">, StubRouteExtensions {}
+type StubRouteObject = StubIndexRouteObject | StubNonIndexRouteObject;
+interface RoutesTestStubProps {
+  /**
+   *  The initial entries in the history stack. This allows you to start a test with
+   *  multiple locations already in the history stack (for testing a back navigation, etc.)
+   *  The test will default to the last entry in initialEntries if no initialIndex is provided.
+   *  e.g. initialEntries={["/home", "/about", "/contact"]}
+   */
+  initialEntries?: InitialEntry[];
+  /**
+   * The initial index in the history stack to render. This allows you to start a test at a specific entry.
+   * It defaults to the last entry in initialEntries.
+   * e.g.
+   *   initialEntries: ["/", "/events/123"]
+   *   initialIndex: 1 // start at "/events/123"
+   */
+  initialIndex?: number;
+  /**
+   *  Used to set the route's initial loader and action data.
+   *  e.g. hydrationData={{
+   *   loaderData: { "/contact": { locale: "en-US" } },
+   *   actionData: { "/login": { errors: { email: "invalid email" } }}
+   *  }}
+   */
+  hydrationData?: HydrationState;
+  /**
+   * Future flags mimicking the settings in react-router.config.ts
+   */
+  future?: Partial<FutureConfig>;
+}
+/**
+ * Creates a React component that renders the provided routes in a test-friendly
+ * React Router context.
+ *
+ * Use this to unit test components that rely on router context, such as
+ * `loaderData`, `actionData`, and route matches.
+ *
+ * @public
+ * @category Utils
+ * @mode framework
+ * @mode data
+ * @param routes The route objects to render in the test router.
+ * @param _context An optional {@link RouterContextProvider} for supplying
+ * application context values to route middleware, loaders, and actions.
+ * @returns A React component that renders the test router.
+ */
+declare function createRoutesStub(routes: StubRouteObject[], _context?: RouterContextProvider): ({
+  initialEntries,
+  initialIndex,
+  hydrationData,
+  future
+}: RoutesTestStubProps) => React$1.JSX.Element;
+//#endregion
+export { RoutesTestStubProps, createRoutesStub };

package/dist/development/lib/dom/ssr/routes-test-stub.js

@@ -0,0 +1,121 @@
+/**
+ * react-router v8.3.0
+ *
+ * Copyright (c) Remix Software Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE.md file in the root directory of this source tree.
+ *
+ * @license MIT
+ */
+import { RouterContextProvider, convertRoutesToDataRoutes } from "../../router/utils.js";
+import { Outlet, RouterProvider, createMemoryRouter, withComponentProps, withErrorBoundaryProps, withHydrateFallbackProps } from "../../components.js";
+import { FrameworkContext } from "./components.js";
+import * as React$1 from "react";
+//#region lib/dom/ssr/routes-test-stub.tsx
+/**
+* Creates a React component that renders the provided routes in a test-friendly
+* React Router context.
+*
+* Use this to unit test components that rely on router context, such as
+* `loaderData`, `actionData`, and route matches.
+*
+* @public
+* @category Utils
+* @mode framework
+* @mode data
+* @param routes The route objects to render in the test router.
+* @param _context An optional {@link RouterContextProvider} for supplying
+* application context values to route middleware, loaders, and actions.
+* @returns A React component that renders the test router.
+*/
+function createRoutesStub(routes, _context) {
+	return function RoutesTestStub({ initialEntries, initialIndex, hydrationData, future }) {
+		let routerRef = React$1.useRef(null);
+		let frameworkContextRef = React$1.useRef(null);
+		if (routerRef.current == null || frameworkContextRef.current == null) {
+			frameworkContextRef.current = {
+				future: {},
+				manifest: {
+					routes: {},
+					entry: {
+						imports: [],
+						module: ""
+					},
+					url: "",
+					version: ""
+				},
+				routeModules: {},
+				ssr: false,
+				isSpaMode: false,
+				routeDiscovery: {
+					mode: "lazy",
+					manifestPath: "/__manifest"
+				}
+			};
+			routerRef.current = createMemoryRouter(processRoutes(convertRoutesToDataRoutes(routes, (r) => r), _context ?? new RouterContextProvider(), frameworkContextRef.current.manifest, frameworkContextRef.current.routeModules), {
+				initialEntries,
+				initialIndex,
+				hydrationData
+			});
+		}
+		return /* @__PURE__ */ React$1.createElement(FrameworkContext.Provider, { value: frameworkContextRef.current }, /* @__PURE__ */ React$1.createElement(RouterProvider, { router: routerRef.current }));
+	};
+}
+function processRoutes(routes, context, manifest, routeModules, parentId) {
+	return routes.map((route) => {
+		if (!route.id) throw new Error("Expected a route.id in react-router processRoutes() function");
+		let newRoute = {
+			id: route.id,
+			path: route.path,
+			index: route.index,
+			Component: route.Component ? withComponentProps(route.Component) : void 0,
+			HydrateFallback: route.HydrateFallback ? withHydrateFallbackProps(route.HydrateFallback) : void 0,
+			ErrorBoundary: route.ErrorBoundary ? withErrorBoundaryProps(route.ErrorBoundary) : void 0,
+			action: route.action ? (args) => route.action({
+				...args,
+				context
+			}) : void 0,
+			loader: route.loader ? (args) => route.loader({
+				...args,
+				context
+			}) : void 0,
+			middleware: route.middleware ? route.middleware.map((mw) => (...args) => mw({
+				...args[0],
+				context
+			}, args[1])) : void 0,
+			handle: route.handle,
+			shouldRevalidate: route.shouldRevalidate
+		};
+		let entryRoute = {
+			id: route.id,
+			path: route.path,
+			index: route.index,
+			parentId,
+			hasAction: route.action != null,
+			hasLoader: route.loader != null,
+			hasClientAction: false,
+			hasClientLoader: false,
+			hasClientMiddleware: false,
+			hasErrorBoundary: route.ErrorBoundary != null,
+			module: "build/stub-path-to-module.js",
+			clientActionModule: void 0,
+			clientLoaderModule: void 0,
+			clientMiddlewareModule: void 0,
+			hydrateFallbackModule: void 0
+		};
+		manifest.routes[newRoute.id] = entryRoute;
+		routeModules[route.id] = {
+			default: newRoute.Component || Outlet,
+			ErrorBoundary: newRoute.ErrorBoundary || void 0,
+			handle: route.handle,
+			links: route.links,
+			meta: route.meta,
+			shouldRevalidate: route.shouldRevalidate
+		};
+		if (route.children) newRoute.children = processRoutes(route.children, context, manifest, routeModules, newRoute.id);
+		return newRoute;
+	});
+}
+//#endregion
+export { createRoutesStub };

package/dist/development/lib/dom/ssr/routes.d.ts

@@ -0,0 +1,33 @@
+
+import { DataRouteObject, RouteManifest } from "../../router/utils.js";
+import { HydrationState } from "../../router/router.js";
+import { ClientLoaderFunction, RouteModules } from "./routeModules.js";
+//#region lib/dom/ssr/routes.d.ts
+interface Route {
+  index?: boolean;
+  caseSensitive?: boolean;
+  id: string;
+  parentId?: string;
+  path?: string;
+}
+interface EntryRoute extends Route {
+  hasAction: boolean;
+  hasLoader: boolean;
+  hasClientAction: boolean;
+  hasClientLoader: boolean;
+  hasClientMiddleware: boolean;
+  hasErrorBoundary: boolean;
+  imports?: string[];
+  css?: string[];
+  module: string;
+  clientActionModule: string | undefined;
+  clientLoaderModule: string | undefined;
+  clientMiddlewareModule: string | undefined;
+  hydrateFallbackModule: string | undefined;
+  parentId?: string;
+}
+declare function createClientRoutesWithHMRRevalidationOptOut(needsRevalidation: Set<string>, manifest: RouteManifest<EntryRoute>, routeModulesCache: RouteModules, initialState: HydrationState, ssr: boolean, isSpaMode: boolean): DataRouteObject[];
+declare function createClientRoutes(manifest: RouteManifest<EntryRoute>, routeModulesCache: RouteModules, initialState: HydrationState | null, ssr: boolean, isSpaMode: boolean, parentId?: string, routesByParentId?: Record<string, Omit<EntryRoute, "children">[]>, needsRevalidation?: Set<string>): DataRouteObject[];
+declare function shouldHydrateRouteLoader(routeId: string, clientLoader: ClientLoaderFunction | undefined, hasLoader: boolean, isSpaMode: boolean): boolean;
+//#endregion
+export { EntryRoute, Route, createClientRoutes, createClientRoutesWithHMRRevalidationOptOut, shouldHydrateRouteLoader };