react-router 0.0.0-experimental-abd9fc79b → 0.0.0-experimental-479e73b7b

package/CHANGELOG.md

@@ -1,5 +1,95 @@
 # `react-router`
 
+## v8.3.0
+
+### Patch Changes
+
+- Encode path params in `href`/`generatePath` per RFC 3986 path-segment rules instead of `encodeURIComponent` ([#15310](https://github.com/remix-run/react-router/pull/15310))
+  - Characters that are valid literally in a path segment (`$ & + , ; = : @` — RFC 3986 `pchar`) are no longer percent-encoded, so values like a semver build `1.0.0+1` interpolate unchanged instead of becoming `1.0.0%2B1`
+  - Structural/unsafe characters (`/ ? # %`, whitespace, non-ASCII) are still escaped exactly as before
+- Use `crypto.randomUUID()` for `createMemorySessionStorage` session ids ([#15302](https://github.com/remix-run/react-router/pull/15302))
+  - `createMemorySessionStorage` is only intended for local development and testing - sessions are lost when the server restarts
+- Fix `NavLink` not applying its `pending` state when `to` has a trailing slash ([#15300](https://github.com/remix-run/react-router/pull/15300))
+- Preserve RSC route component metadata so routes with a `clientLoader` can skip unnecessary server requests once their components have rendered while still fetching missing server-rendered elements ([#15323](https://github.com/remix-run/react-router/pull/15323))
+- Harden RSC CSRF code paths ([#15311](https://github.com/remix-run/react-router/pull/15311))
+- Fix server crash (`TypeError: Invalid state: Unable to enqueue`) when a request is aborted while the RSC HTML stream has a pending flush ([#15286](https://github.com/remix-run/react-router/pull/15286))
+  - Handle cancellation of the `injectRSCPayload` readable side, clear the pending flush, and cancel the underlying RSC payload stream
+
+### Unstable Changes
+
+⚠️ _[Unstable features](https://reactrouter.com/community/api-development-strategy#unstable-flags) are not recommended for production use_
+
+- Detect stale RSC clients during lazy route discovery and reload the destination document ([#15318](https://github.com/remix-run/react-router/pull/15318))
+
+  #### Migration
+
+  Apps using the default RSC Framework entry do not need to make any changes. Apps with a custom `entry.rsc.tsx` should import the generated client version and pass it to `unstable_matchRSCServerRequest`:
+
+  ```tsx
+  import clientVersion from "virtual:react-router/unstable_rsc/client-version";
+
+  return unstable_matchRSCServerRequest({
+    // ...
+    clientVersion,
+  });
+  ```
+
+- Add CSP nonce support to RSC document rendering ([#15320](https://github.com/remix-run/react-router/pull/15320))
+  - Add `nonce` options to `unstable_routeRSCServerRequest` and `unstable_RSCStaticRouter`
+  - Forward the nonce to the HTML renderer and apply it to injected RSC payload scripts and nonce-aware framework components
+
+  To adopt nonce-based CSP, update your `entry.ssr.tsx` (run `react-router reveal entry.ssr` first in RSC Framework Mode) to generate a fresh nonce for each request. Pass it to `routeRSCServerRequest`, spread the `renderHTML` options into React's HTML renderer, pass `options.nonce` to `RSCStaticRouter`, and use the same nonce in the `Content-Security-Policy` response header:
+
+  ```tsx
+  const nonce = crypto.randomUUID();
+  const response = await routeRSCServerRequest({
+    request,
+    serverResponse,
+    createFromReadableStream,
+    nonce,
+    async renderHTML(getPayload, options) {
+      const payload = getPayload();
+      return renderHTMLToReadableStream(
+        <RSCStaticRouter getPayload={getPayload} nonce={options.nonce} />,
+        {
+          ...options,
+          bootstrapScriptContent,
+          formState: await payload.formState,
+          signal: request.signal,
+        },
+      );
+    },
+  });
+  response.headers.set(
+    "Content-Security-Policy",
+    `script-src 'self' 'nonce-${nonce}'`,
+  );
+  ```
+
+## v8.2.0
+
+### Patch Changes
+
+- Fix `href()` to properly stringify and URL-encode param values, matching `generatePath()` ([#15277](https://github.com/remix-run/react-router/pull/15277))
+  - splat params preserve path separators while encoding each segment individually
+- Fix dynamic param extraction for routes with optional static segments ([#15200](https://github.com/remix-run/react-router/pull/15200))
+  - When a route path contains optional static segments (e.g. `/school?/user/:id`), the internal regex's incorrectly shifted parameter indices resulting in incorrect parameter extraction
+  - Consecutive optional static segments (e.g. `/one?/two?`) were only partially handled
+- Preserve navigation blocker state through a revalidation ([#15246](https://github.com/remix-run/react-router/pull/15246))
+- Fix route ranking for dynamic parameters with static extension suffixes ([#15273](https://github.com/remix-run/react-router/pull/15273))
+  - These were not being detected as dynamic param segments and instead got incorrectly scored higher as a static segment
+  - This meant they could potentially tie truly static routes like `/sitemap.xml` and outrank them based on definition order
+  - These are now correctly identified as dynamic parameter segments and scored correctly
+- Use ReactFormState types instead of unknown ([#15263](https://github.com/remix-run/react-router/pull/15263))
+
+## v8.1.0
+
+### Minor Changes
+
+- Return route metadata from server request, client navigation, and client fetcher instrumentations ([#15235](https://github.com/remix-run/react-router/pull/15235))
+  - Adds result metadata after instrumented calls complete, including the URL, matched route pattern, and params
+  - Adds known HTTP status codes to server request handler instrumentation results
+
 ## v8.0.1
 
 ### Patch Changes

package/dist/development/dom-export.js

@@ -1,5 +1,5 @@
 /**
- * react-router v0.0.0-experimental-abd9fc79b
+ * react-router v0.0.0-experimental-479e73b7b
  *
  * Copyright (c) Remix Software Inc.
  *

package/dist/development/index-react-server-client.js

@@ -1,5 +1,5 @@
 /**
- * react-router v0.0.0-experimental-abd9fc79b
+ * react-router v0.0.0-experimental-479e73b7b
  *
  * Copyright (c) Remix Software Inc.
  *

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

@@ -2,6 +2,7 @@
 import * as React from "react";
 import { CookieParseOptions, CookieParseOptions as CookieParseOptions$1, CookieSerializeOptions, CookieSerializeOptions as CookieSerializeOptions$1 } from "cookie-es";
 import { 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 { ReactFormState } from "react-dom/client";
 
 //#region lib/router/history.d.ts
 /**
@@ -1009,6 +1010,19 @@ type ClientInstrumentation = {
 type InstrumentRequestHandlerFunction = (handler: InstrumentableRequestHandler) => void;
 type InstrumentRouterFunction = (router: InstrumentableRouter) => void;
 type InstrumentRouteFunction = (route: InstrumentableRoute) => void;
+/**
+ * Route metadata available after React Router has matched an instrumented
+ * request, navigation, or fetcher call.
+ */
+type InstrumentationResultMeta = {
+  url: LoaderFunctionArgs["url"];
+  pattern: string;
+  params: LoaderFunctionArgs["params"];
+};
+/**
+ * Result returned by route-level instrumented handler calls, such as
+ * instrumented loaders, actions, middleware, and lazy route functions.
+ */
 type InstrumentationHandlerResult = {
   status: "success";
   error: undefined;
@@ -1016,7 +1030,21 @@ type InstrumentationHandlerResult = {
   status: "error";
   error: Error;
 };
-type InstrumentFunction<T> = (handler: () => Promise<InstrumentationHandlerResult>, info: T) => Promise<void>;
+/**
+ * Result returned by client-side router instrumented navigation and fetcher
+ * calls.
+ */
+type InstrumentationClientRouterResult = InstrumentationHandlerResult & {
+  meta: InstrumentationResultMeta | undefined;
+};
+/**
+ * Result returned by server request handler instrumentation.
+ */
+type InstrumentationServerHandlerResult = InstrumentationHandlerResult & {
+  statusCode: number;
+  meta: InstrumentationResultMeta | undefined;
+};
+type InstrumentFunction<T, TInnerResult = InstrumentationHandlerResult> = (handler: () => Promise<TInnerResult>, info: T) => Promise<void>;
 type ReadonlyRequest = {
   method: string;
   url: string;
@@ -1039,18 +1067,16 @@ type RouteInstrumentations = {
   action?: InstrumentFunction<RouteHandlerInstrumentationInfo>;
 };
 type RouteLazyInstrumentationInfo = undefined;
-type RouteHandlerInstrumentationInfo = Readonly<{
+type RouteHandlerInstrumentationInfo = Readonly<Omit<LoaderFunctionArgs, "request" | "context"> & {
   request: ReadonlyRequest;
-  params: LoaderFunctionArgs["params"];
-  pattern: string;
   context: ReadonlyContext;
 }>;
 type InstrumentableRouter = {
   instrument(instrumentations: RouterInstrumentations): void;
 };
 type RouterInstrumentations = {
-  navigate?: InstrumentFunction<RouterNavigationInstrumentationInfo>;
-  fetch?: InstrumentFunction<RouterFetchInstrumentationInfo>;
+  navigate?: InstrumentFunction<RouterNavigationInstrumentationInfo, InstrumentationClientRouterResult>;
+  fetch?: InstrumentFunction<RouterFetchInstrumentationInfo, InstrumentationClientRouterResult>;
 };
 type RouterNavigationInstrumentationInfo = Readonly<{
   to: string | number;
@@ -1073,7 +1099,7 @@ type InstrumentableRequestHandler = {
   instrument(instrumentations: RequestHandlerInstrumentations): void;
 };
 type RequestHandlerInstrumentations = {
-  request?: InstrumentFunction<RequestHandlerInstrumentationInfo>;
+  request?: InstrumentFunction<RequestHandlerInstrumentationInfo, InstrumentationServerHandlerResult>;
 };
 type RequestHandlerInstrumentationInfo = Readonly<{
   request: ReadonlyRequest;
@@ -2292,14 +2318,14 @@ type RSCRenderPayload = {
   type: "render";
   actionData: Record<string, any> | null;
   basename: string | undefined;
+  clientVersion?: string;
   errors: Record<string, any> | null;
   loaderData: Record<string, any>;
   location: Location;
   routeDiscovery: RouteDiscovery;
   matches: RSCRouteMatch[];
   patches?: Promise<RSCRouteManifest[]>;
-  nonce?: string;
-  formState?: unknown;
+  formState?: ReactFormState;
 };
 type RSCManifestPayload = {
   type: "manifest";
@@ -2325,7 +2351,7 @@ type RSCMatch = {
   payload: RSCPayload;
 };
 type DecodeActionFunction = (formData: FormData) => Promise<() => Promise<unknown>>;
-type DecodeFormStateFunction = (result: unknown, formData: FormData) => unknown;
+type DecodeFormStateFunction = (result: unknown, formData: FormData) => Promise<ReactFormState | undefined>;
 type DecodeReplyFunction = (reply: FormData | string, options: {
   temporaryReferences: unknown;
 }) => Promise<unknown[]>;
@@ -2395,6 +2421,8 @@ type RouteDiscovery = {
  * encoding the {@link unstable_RSCPayload}.
  * @param opts.loadServerAction Your `react-server-dom-xyz/server`'s
  * `loadServerAction` function, used to load a server action by ID.
+ * @param opts.clientVersion A version derived from the client build output used
+ * to detect stale clients during lazy route discovery.
  * @param opts.onError An optional error handler that will be called with any
  * errors that occur during the request processing.
  * @param opts.request The [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request)
@@ -2418,6 +2446,7 @@ declare function matchRSCServerRequest({
   loadServerAction,
   decodeAction,
   decodeFormState,
+  clientVersion,
   onError,
   request,
   routes,
@@ -2431,6 +2460,7 @@ declare function matchRSCServerRequest({
   decodeFormState?: DecodeFormStateFunction;
   requestContext?: RouterContextProvider;
   loadServerAction?: LoadServerActionFunction;
+  clientVersion?: string;
   onError?: (error: unknown) => void;
   request: Request;
   routes: RSCRouteConfigEntry[];
@@ -2464,14 +2494,30 @@ type Pages = Register extends {
 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" })} />
-  ```
+ * Returns a resolved URL path for the specified route.
+ *
+ * Param values are percent-encoded for use in a path segment: characters that
+ * would change the URL structure (`/`, `?`, `#`, `%`, whitespace, non-ASCII)
+ * are escaped, while characters that RFC 3986 allows literally in a path
+ * segment (`$ & + , ; = : @`) are kept as-is. Note this differs from query-string
+ * encoding (`encodeURIComponent`/`URLSearchParams`), where those characters are
+ * delimiters and must be escaped. Splat (`*`) values are encoded per segment,
+ * preserving `/` separators.
+ *
+ * See [RFC 3986 §3.3](https://datatracker.ietf.org/doc/html/rfc3986#section-3.3)
+ *
+ * @example
+ * const h = href("/:lang?/about", { lang: "en" })
+ * // -> `/en/about`
+ *
+ * <Link to={href("/products/:id", { id: "abc123" })} />
+ *
+ * @public
+ * @category Utils
+ * @mode framework
+ * @param path The route path to resolve
+ * @param args The route params to use when resolving the path
+ * @returns The resolved URL path
  */
 declare function href<Path extends keyof Args>(path: Path, ...args: Args[Path]): string;
 //#endregion
@@ -2527,13 +2573,39 @@ interface Cookie {
 }
 /**
  * Creates a logical container for managing a browser cookie from the server.
+ *
+ * @public
+ * @category Utils
+ * @mode framework
+ * @mode data
+ * @param name The name of the cookie.
+ * @param cookieOptions Options for parsing and serializing the cookie.
+ * @returns A {@link Cookie} object for parsing and serializing the cookie.
  */
 declare const createCookie: (name: string, cookieOptions?: CookieOptions) => Cookie;
+/**
+ * A function that determines whether a value is a React Router {@link Cookie}
+ * object.
+ *
+ * @public
+ * @category Utils
+ * @mode framework
+ * @mode data
+ * @param object The value to check.
+ * @returns `true` if the value is a React Router {@link Cookie} object;
+ * otherwise, `false`.
+ */
 type IsCookieFunction = (object: any) => object is Cookie;
 /**
- * Returns true if an object is a Remix cookie container.
+ * Returns `true` if a value is a React Router {@link Cookie} object.
  *
- * @see https://remix.run/utils/cookies#iscookie
+ * @public
+ * @category Utils
+ * @mode framework
+ * @mode data
+ * @param object The value to check.
+ * @returns `true` if the value is a React Router {@link Cookie} object;
+ * otherwise, `false`.
  */
 declare const isCookie: IsCookieFunction;
 //#endregion
@@ -2595,13 +2667,37 @@ type CreateSessionFunction = <Data = SessionData, FlashData = Data>(initialData?
  *
  * Note: This function is typically not invoked directly by application code.
  * Instead, use a `SessionStorage` object's `getSession` method.
+ *
+ * @category Utils
+ * @param initialData The initial data for the session.
+ * @param id The identifier for the session. Defaults to an empty string for a
+ * new session.
+ * @returns A new {@link Session} object.
  */
 declare const createSession: CreateSessionFunction;
+/**
+ * A function that determines whether a value is a React Router {@link Session}
+ * object.
+ *
+ * @public
+ * @category Utils
+ * @mode framework
+ * @mode data
+ * @param object The value to check.
+ * @returns `true` if the value is a React Router {@link Session} object;
+ * otherwise, `false`.
+ */
 type IsSessionFunction = (object: any) => object is Session;
 /**
- * Returns true if an object is a React Router session.
+ * Returns `true` if a value is a React Router {@link Session} object.
  *
- * @see https://reactrouter.com/api/utils/isSession
+ * @public
+ * @category Utils
+ * @mode framework
+ * @mode data
+ * @param object The value to check.
+ * @returns `true` if the value is a React Router {@link Session} object;
+ * otherwise, `false`.
  */
 declare const isSession: IsSessionFunction;
 /**
@@ -2668,6 +2764,11 @@ interface SessionIdStorageStrategy<Data = SessionData, FlashData = Data> {
  *
  * Note: This is a low-level API that should only be used if none of the
  * existing session storage options meet your requirements.
+ *
+ * @category Utils
+ * @param strategy The strategy used to store session identifiers and data.
+ * @returns A {@link SessionStorage} object that persists session data using the
+ * provided strategy.
  */
 declare function createSessionStorage<Data = SessionData, FlashData = Data>({
   cookie: cookieArg,
@@ -2693,6 +2794,14 @@ interface CookieSessionStorageOptions {
  * needed, and can help to simplify some load-balanced scenarios. However, it
  * also has the limitation that serialized session data may not exceed the
  * browser's maximum cookie size. Trade-offs!
+ *
+ * @public
+ * @category Utils
+ * @mode framework
+ * @mode data
+ * @param options Options for creating the cookie-backed session storage.
+ * @returns A {@link SessionStorage} object that stores all session data in its
+ * cookie.
  */
 declare function createCookieSessionStorage<Data = SessionData, FlashData = Data>({
   cookie: cookieArg
@@ -2707,11 +2816,17 @@ interface MemorySessionStorageOptions {
   cookie?: SessionIdStorageStrategy["cookie"];
 }
 /**
- * Creates and returns a simple in-memory SessionStorage object, mostly useful
- * for testing and as a reference implementation.
+ * Creates and returns a simple in-memory SessionStorage object.
+ *
+ * Intended for local development and testing. It does not scale beyond a single
+ * process, and all session data is lost when the server process stops/restarts.
  *
- * Note: This storage does not scale beyond a single process, so it is not
- * suitable for most production scenarios.
+ * @public
+ * @category Utils
+ * @mode framework
+ * @mode data
+ * @param options Options for creating the in-memory session storage.
+ * @returns A {@link SessionStorage} object that stores session data in memory.
  */
 declare function createMemorySessionStorage<Data = SessionData, FlashData = Data>({
   cookie