@rangojs/router 0.20.0 → 0.22.0

package/src/testing/render-route.tsx

@@ -35,11 +35,19 @@
  *     useRouter().replace kind "replace", refresh() kind "revalidate".
  *     Back/forward, action and optimistic clientUrls() swap decisions are
  *     e2e territory.
+ *   - Location state reaches readers the way it does in production:
+ *     NavigationProvider holds the committed entry's state next to the
+ *     payload, so a navigation whose loader the test holds keeps the entry
+ *     being left on screen with its own state. A `popstate` event is a
+ *     back/forward onto the entry history.state holds; the tree has one
+ *     location, so no page is restored with it. A server action's state, a
+ *     redirect's and an intercept's are e2e territory.
  * What it DOES cover: client hooks that read NavigationProvider /
  * OutletContext — useParams, useReverse, useHref, useMount, useNavigation,
  * useRouter, usePathname, useSearchParams, Outlet/useOutlet nesting and seeded
  * descendant pending state, useLoader/useFetchLoader (seeded data),
- * useLocationState (seeded), and useHandle (seeded).
+ * useLocationState (seeded, or written by a navigation), and useHandle
+ * (seeded).
  * Basename-mounted apps: pass the `basename` option so useRouter().basename,
  * <Link> prefixing, and useMount/useHref resolve against the mount prefix
  * (without it they resolve at the root "/"). For an include("/shop", ...)
@@ -48,7 +56,12 @@
  */
 
 import { decideTransitionGatedOff } from "../browser/transition-when.js";
-import { useEffect, type ReactNode, type ComponentType } from "react";
+import {
+  StrictMode,
+  useEffect,
+  type ReactNode,
+  type ComponentType,
+} from "react";
 import type { RenderResult } from "@testing-library/react";
 import { renderSegments } from "../segment-system.js";
 import {
@@ -62,6 +75,7 @@ import {
   shouldStartViewTransition,
 } from "../browser/partial-update.js";
 import type {
+  NavigateOptions,
   NavigateOptionsInternal,
   NavigationStore,
   NavigationBridge,
@@ -80,10 +94,13 @@ import type {
   TransitionConfig,
   TransitionWhenKind,
 } from "../types.js";
-import type { LocationStateDefinition } from "../browser/react/location-state-shared.js";
+import {
+  setLocationStateVersion,
+  type LocationStateDefinition,
+} from "../browser/react/location-state-shared.js";
 import {
   buildHistoryState,
-  hasLocationState,
+  clearLocationStateOnDocumentLoad,
   pushHistoryWithIdx,
   resolveNavigationState,
 } from "../browser/history-state.js";
@@ -93,9 +110,9 @@ import type { ThemeConfig } from "../theme/types.js";
 import { resolveThemeConfig } from "../theme/constants.js";
 import { isUnderTestRunner } from "../runtime-env.js";
 import { setupNavigationBridgeDelegatedPrefetch } from "../browser/navigation-bridge.js";
-import { resetAdaptiveStrategyForTesting } from "../browser/prefetch/default-strategy.js";
 import { resetPrefetchObserverForTesting } from "../browser/prefetch/observer.js";
 import type { PrefetchStrategy } from "../router/prefetch-default.js";
+import { auditTreeCause } from "../suspense-audit.js";
 
 const TEST_ORIGIN = "http://localhost";
 let activePrefetchRegistrations = 0;
@@ -230,6 +247,8 @@ export interface RenderRouteOptions {
    * `useLocationState(StateDef)`. Like loaders, a real `createLocationState()`
    * handle has an empty injected key in a bare test, so pass `[def, value]`
    * pairs; renderRoute assigns a synthetic key and writes it to `history.state`.
+   * With `hydrate: true` a `clearOnReload` definition's seed is removed before
+   * hydration, as on a document load.
    *
    * @example
    * renderRoute([{ path: "/", Component: FlashBanner }], {
@@ -265,6 +284,24 @@ export interface RenderRouteOptions {
    * computes the segment id for you). Merged with `handles`.
    */
   handle?: HandleDataSeed;
+  /**
+   * Handle values a document delivers after hydration, as a loader's push
+   * that is not in the document's handle snapshot is (a push made after the
+   * handler output settled, or any loader push on a PPR shell HIT). Each
+   * entry is `[handle, values]`: the handle's values after the update, which
+   * replace its `handles` seed once the root has hydrated (or mounted). With
+   * `hydrate: true` the server HTML is rendered from `handles`, and a reader
+   * inside a `<Suspense>` boundary hydrates after the update was applied, as
+   * a boundary that hydrates after the root does in production.
+   *
+   * @example
+   * const { serverHtml, recoverableErrors } = await renderRoute(routes, {
+   *   hydrate: true,
+   *   handles: [[Notes, ["from-handler"]]],
+   *   lateHandles: [[Notes, ["from-handler", "from-loader"]]],
+   * });
+   */
+  lateHandles?: ReadonlyArray<readonly [Handle<any, any>, unknown[]]>;
   /**
    * Route name -> pattern map. Informational for parity with the server test
    * context; client useReverse takes its map directly as an argument, so this
@@ -326,6 +363,25 @@ export interface RenderRouteOptions {
    * not override a `"none"` default.
    */
   defaultPrefetch?: PrefetchStrategy;
+  /**
+   * Hydrate instead of mounting fresh: the same element is rendered to HTML
+   * (react-dom/server `renderToString`), placed in the container and hydrated.
+   * The result gains `serverHtml` and `recoverableErrors`
+   * (RenderRouteHydrateResult). `data-hydrated` is set on `<html>` after
+   * hydration, as production's root does, and removed on unmount.
+   *
+   * Limits:
+   * - The server pass runs without `window` and `document`, and only those. A
+   *   hook that reads a global that stays defined there (`history`,
+   *   `localStorage`, `navigator`) outside a server snapshot renders the same
+   *   in both passes here and can still mismatch in real SSR.
+   * - Content that suspends in the server pass (`lazy`, a pending or untracked
+   *   `use()` promise) is emitted as its fallback and client-rendered, not
+   *   hydrated; React reports the boundary in `recoverableErrors`. Outside any
+   *   `<Suspense>` it rejects.
+   * - Needs @testing-library/react >= 16.2.0; throws on older versions.
+   */
+  hydrate?: boolean;
 }
 
 /**
@@ -356,10 +412,20 @@ export interface TestRouterHandle {
    * `options.transition: false` is the per-navigation opt-out
    * (`router.push(url, { transition: false })`, `<Link transition={false}>`):
    * the commit is urgent and no transition({ when }) predicate is called.
+   *
+   * `options.state` and `options.replace: true` write the history entry the
+   * way `useRouter().push(url, { state })` and `.replace(url, { state })` do,
+   * so a test can carry location state on a navigation whose loader it
+   * holds: `state` pushes an entry with it, `replace: true` replaces the
+   * current entry (with `state`, or with none, which drops the entry's
+   * location state as a production replace does). With neither, history is
+   * left alone and readers keep the state they have: `navigate(url)` and
+   * `navigate(url, { replace: false })` are the same call.
    */
   navigate(
     url: string,
-    options?: Pick<RenderRouteOptions, "loaders"> & { transition?: boolean },
+    options?: Pick<RenderRouteOptions, "loaders"> &
+      Pick<NavigateOptions, "state" | "replace" | "transition">,
   ): Promise<void>;
   /**
    * Re-render the current location, as router.refresh() does: a spec's
@@ -379,6 +445,21 @@ export interface TestRouterHandle {
 /** Result of renderRoute: RTL's render result plus the router handle. */
 export type RenderRouteResult = RenderResult & { router: TestRouterHandle };
 
+/** Result of renderRoute with `hydrate: true`. */
+export type RenderRouteHydrateResult = RenderRouteResult & {
+  /** The HTML the server pass produced, as placed in the container. */
+  serverHtml: string;
+  /**
+   * Messages of the errors React recovered from (`onRecoverableError`): a
+   * hydration mismatch that made it re-render on the client, or a boundary the
+   * server pass could not finish. Empty means the tree hydrated as rendered.
+   * Live: React appends for as long as the root is mounted. An attribute-only
+   * mismatch is NOT here — React keeps the server attribute and only logs it
+   * with `console.error` in development.
+   */
+  recoverableErrors: string[];
+};
+
 interface ResolvedMatch {
   params: Record<string, string>;
   pathname: string;
@@ -410,7 +491,6 @@ function DelegatedPrefetchRegistration({
             }
             pendingPrefetchReset = undefined;
             resetPrefetchObserverForTesting();
-            resetAdaptiveStrategyForTesting();
           });
         }
       }
@@ -419,6 +499,46 @@ function DelegatedPrefetchRegistration({
   return null;
 }
 
+/**
+ * initBrowserApp calls the bridge's registerLinkInterception, which is where
+ * production listens for `popstate` (navigation-bridge.ts); a rendered tree
+ * has no initBrowserApp.
+ */
+function LinkInterceptionRegistration({
+  bridge,
+}: {
+  bridge: NavigationBridge;
+}): null {
+  useEffect(() => bridge.registerLinkInterception(), [bridge]);
+  return null;
+}
+
+/**
+ * The marker production's root sets from its effect after hydration
+ * (browser/rsc-router.tsx Rango), so a boundary that hydrates in a later pass
+ * finds it set, as in production. Removed on unmount: a test unmounts its
+ * root, production never does.
+ */
+function HydratedMarker(): null {
+  useEffect(() => {
+    document.documentElement.dataset.hydrated = "";
+    return () => document.documentElement.removeAttribute("data-hydrated");
+  }, []);
+  return null;
+}
+
+/**
+ * Runs `run` from an effect after the tree's. That is where production's late
+ * handle channel writes a push that arrives after the root hydrated (the store
+ * holds it while the hydration window is open, EventController.lockHydration),
+ * and where the document has been revealed (browser/rsc-router.tsx
+ * documentRevealed).
+ */
+function AfterTree({ run }: { run: () => void }): null {
+  useEffect(run, [run]);
+  return null;
+}
+
 function matchLeaf(
   pattern: string,
   pathname: string,
@@ -504,6 +624,14 @@ function buildSegments(
   return segments;
 }
 
+export function renderRoute(
+  routes: RenderRouteSpec[],
+  options: RenderRouteOptions & { hydrate: true },
+): Promise<RenderRouteHydrateResult>;
+export function renderRoute(
+  routes: RenderRouteSpec[],
+  options?: RenderRouteOptions,
+): Promise<RenderRouteResult>;
 export async function renderRoute(
   routes: RenderRouteSpec[],
   options: RenderRouteOptions = {},
@@ -539,11 +667,17 @@ export async function renderRoute(
   const loaderData = seedLoaders(options.loaderData ?? {}, options.loaders);
 
   if (typeof window !== "undefined") {
+    // The tree has no app version (its bridge reports none), so a seed needs
+    // none either. Reset what an initBrowserApp in the same file may have left.
+    setLocationStateVersion(undefined);
     const stateObj: Record<string, unknown> = {};
     for (const [def, value] of options.locationState ?? []) {
       stateObj[withLocationStateKey(def).__rsc_ls_key] = value;
     }
     window.history.replaceState(stateObj, "");
+    // Hydrate mode is a document load of the seeded entry: run start-up's
+    // step (initBrowserApp), not a copy of it.
+    if (options.hydrate) clearLocationStateOnDocumentLoad();
   }
 
   const resolve = (pathname: string): ResolvedMatch => {
@@ -609,14 +743,40 @@ export async function renderRoute(
 
   const eventController = createEventController({ initialLocation: url });
   eventController.setParams(initialMatch.params);
+  // The seeded entry, as initBrowserApp commits the document's.
+  eventController.commitLocationState(window.history.state);
   // Resolve-by-default: resolve any deferred (Promise) seeded handle values
   // before applying, so the seeded handles reach collect/useHandle resolved —
   // matching what the server/client do in a real app.
   const resolvedSeed = await resolveDeferredHandleValues(handleSeed);
-  eventController.setHandleData(
-    resolvedSeed,
-    initialSegments.map((s) => s.id),
-  );
+  const initialSegmentIds = initialSegments.map((s) => s.id);
+  eventController.setHandleData(resolvedSeed, initialSegmentIds);
+  // As initBrowserApp before hydrateRoot: until the provider's barrier commit,
+  // handle reads return this state and later writes wait.
+  if (options.hydrate) eventController.lockHydration();
+  let resolveDocumentRevealed: (() => void) | undefined;
+  const documentRevealed = options.hydrate
+    ? new Promise<void>((resolve) => {
+        resolveDocumentRevealed = resolve;
+      })
+    : undefined;
+  // A late update carries the full state: the seed with these handles' values
+  // replaced, resolved as the browser resolves a late yield before applying.
+  let applyLateHandles: (() => void) | undefined;
+  if (options.lateHandles && leafRouteSegmentId !== undefined) {
+    const lateSeed = cloneHandleSeed(resolvedSeed);
+    for (const [handle, values] of options.lateHandles) {
+      const id = (handle as unknown as { $$id: string }).$$id;
+      (lateSeed[id] ??= {})[leafRouteSegmentId] = values;
+    }
+    const lateState = await resolveDeferredHandleValues(lateSeed);
+    // Flushed, not left to the notify timer: renderRoute's act() has
+    // returned by then.
+    applyLateHandles = () => {
+      eventController.setHandleData(lateState, initialSegmentIds);
+      eventController.flushRouteState();
+    };
+  }
 
   let warnedNavLifecycle = false;
   const navigate = async (
@@ -633,10 +793,11 @@ export async function renderRoute(
     // A useRouter().push/replace or <Link> navigation (`history`) writes its
     // entry the way production does (navigation-bridge.ts navigate ->
     // navigation-transaction.ts commit): the dev state check, typed entries
-    // spread onto history.state, the idx stamp, and the __rsc_locationstate
-    // event when the old or new entry carries location state. The URL stays
-    // put: renderRoute tracks location on the event controller, not
-    // window.location. router.navigate() and refresh() leave history alone.
+    // spread onto history.state, the idx stamp, and the entry state committed
+    // on the event controller, which the provider takes with the payload.
+    // The URL stays put: renderRoute tracks location on the event
+    // controller, not window.location. router.navigate() without `state` or
+    // `replace: true`, and refresh(), leave history alone.
     const history = navOptions?.history;
     const historyState = history
       ? buildHistoryState(
@@ -702,30 +863,28 @@ export async function renderRoute(
     eventController.setParams(match.params);
     store.setCurrentUrl(nextUrl.href);
     store.setSegmentIds(segments.map((s) => s.id));
-    let notifyLocationState = false;
     if (history) {
-      notifyLocationState =
-        hasLocationState(window.history.state) ||
-        hasLocationState(historyState);
       pushHistoryWithIdx(
         historyState ?? null,
         window.location.href,
         history.replace ?? false,
       );
+      eventController.commitLocationState(historyState);
     }
     const emit: UpdateSubscriber = (update) => store.emitUpdate(update);
     await act(async () => {
+      // As production's emitters name their cause (suspense-audit.ts I6).
+      auditTreeCause("navigation");
       // Production's transition() lane (browser/partial-update.ts). Its
       // same-structure / fully-prefetched / optimistic hold lanes are not
       // modeled: without transition() the commit stays urgent.
       if (shouldStartViewTransition(segments, gatedOff)) {
-        commitInTransition(emit, segments, { root, metadata }, ["navigation"]);
+        commitInTransition(store.loaders, emit, segments, { root, metadata }, [
+          "navigation",
+        ]);
       } else {
         emit({ root, metadata });
       }
-      if (notifyLocationState) {
-        window.dispatchEvent(new Event("__rsc_locationstate"));
-      }
     });
   };
 
@@ -739,8 +898,20 @@ export async function renderRoute(
     navigate: (target, navigateOptions) =>
       navigate(target, { history: navigateOptions ?? {} }),
     refresh: () => refresh(),
-    handlePopstate: async () => {},
-    registerLinkInterception: () => () => {},
+    // Back/forward onto the entry history.state holds. The tree has one
+    // location, so nothing is restored: a treeless commit of that entry, as
+    // production's traversal that keeps every segment
+    // (navigation-transaction.ts commit). Flushed, not left to the notify
+    // timer: the dispatching test's act() has returned by then.
+    handlePopstate: async () => {
+      eventController.commitLocationState(window.history.state, true);
+      eventController.flushRouteState();
+    },
+    registerLinkInterception: () => {
+      const onPopstate = (): void => void bridge.handlePopstate();
+      window.addEventListener("popstate", onPopstate);
+      return () => window.removeEventListener("popstate", onPopstate);
+    },
     registerDelegatedPrefetch: () =>
       setupNavigationBridgeDelegatedPrefetch(
         store,
@@ -764,6 +935,54 @@ export async function renderRoute(
     outletPending: options.outletPending,
   });
 
+  // The marker sits after the provider so its effect runs after the tree's,
+  // like the effect of production's root component.
+  const ui = (
+    <>
+      <NavigationProvider
+        store={store}
+        eventController={eventController}
+        initialPayload={{ root: initialTree, metadata: initialMetadata }}
+        bridge={bridge}
+        basename={basename}
+        themeConfig={
+          options.theme === undefined ? null : resolveThemeConfig(options.theme)
+        }
+        nonce={options.nonce}
+        hydration={documentRevealed ? { settled: documentRevealed } : undefined}
+      />
+      <DelegatedPrefetchRegistration bridge={bridge} />
+      <LinkInterceptionRegistration bridge={bridge} />
+      {options.hydrate && <HydratedMarker />}
+      {applyLateHandles && <AfterTree run={applyLateHandles} />}
+      {resolveDocumentRevealed && <AfterTree run={resolveDocumentRevealed} />}
+    </>
+  );
+
+  let serverHtml: string | undefined;
+  const recoverableErrors: string[] = [];
+  if (options.hydrate) {
+    // RTL forwards onRecoverableError to hydrateRoot from 16.2.0. 16.0-16.1
+    // are inside the peer range and drop it (their render() never names the
+    // option), which would leave `recoverableErrors` empty on a real mismatch.
+    if (!String(render).includes("onRecoverableError")) {
+      throw new Error(
+        "renderRoute: `hydrate` needs @testing-library/react >= 16.2.0. Older " +
+          "versions do not pass onRecoverableError to hydrateRoot, so a " +
+          "hydration mismatch would go unreported.",
+      );
+    }
+    const { getConfig } = await import("@testing-library/react");
+    const { renderToString } = await import("react-dom/server");
+    // RTL wraps the hydrated element the same way.
+    const serverUi = getConfig().reactStrictMode ? (
+      <StrictMode>{ui}</StrictMode>
+    ) : (
+      ui
+    );
+    serverHtml = withoutBrowserGlobals(() => renderToString(serverUi));
+  }
+
   // Wrap render in an awaited async act so a tree that suspends (async loaders,
   // loading states, deferred handle entries that arrive as a Promise) settles its
   // Suspense within act — otherwise React orphans the resolution ("a component
@@ -772,30 +991,32 @@ export async function renderRoute(
   let result!: Awaited<ReturnType<typeof render>>;
   const container = document.body.appendChild(document.createElement("div"));
   prefetchRoot = container;
+  if (serverHtml !== undefined) container.innerHTML = serverHtml;
   await act(async () => {
-    result = render(
-      <>
-        <NavigationProvider
-          store={store}
-          eventController={eventController}
-          initialPayload={{ root: initialTree, metadata: initialMetadata }}
-          bridge={bridge}
-          basename={basename}
-          themeConfig={
-            options.theme === undefined
-              ? null
-              : resolveThemeConfig(options.theme)
-          }
-          nonce={options.nonce}
-        />
-        <DelegatedPrefetchRegistration bridge={bridge} />
-      </>,
-      { baseElement: document.body, container },
-    );
+    result = render(ui, {
+      baseElement: document.body,
+      container,
+      ...(serverHtml !== undefined && {
+        hydrate: true,
+        onRecoverableError: (error: unknown) => {
+          recoverableErrors.push(
+            error instanceof Error ? error.message : String(error),
+          );
+        },
+      }),
+    });
   });
 
   const router: TestRouterHandle = {
-    navigate,
+    navigate: (target, navOptions) =>
+      navigate(target, {
+        loaders: navOptions?.loaders,
+        transition: navOptions?.transition,
+        history:
+          navOptions?.state !== undefined || navOptions?.replace
+            ? navOptions
+            : undefined,
+      }),
     refresh,
     pathname: () => new URL(eventController.getLocation().href).pathname,
     params: () => eventController.getParams(),
@@ -803,7 +1024,33 @@ export async function renderRoute(
     eventController,
   };
 
-  return Object.assign(result, { router });
+  if (serverHtml === undefined) return Object.assign(result, { router });
+  return Object.assign(result, { router, serverHtml, recoverableErrors });
+}
+
+/**
+ * Runs the server pass without `window` and `document`, the two globals
+ * SSR-aware code probes. A DOM test environment defines both, so with them in
+ * place a `typeof window` branch takes its client side, renders the client
+ * HTML, and the mismatch it causes in production hydrates clean. `fn` must be
+ * synchronous (renderToString, not a streaming entry): nothing else may run
+ * while they are gone.
+ */
+function withoutBrowserGlobals<T>(fn: () => T): T {
+  const scope = globalThis as { window?: unknown; document?: unknown };
+  const windowDescriptor = Object.getOwnPropertyDescriptor(scope, "window")!;
+  const documentDescriptor = Object.getOwnPropertyDescriptor(
+    scope,
+    "document",
+  )!;
+  try {
+    delete scope.window;
+    delete scope.document;
+    return fn();
+  } finally {
+    Object.defineProperty(scope, "window", windowDescriptor);
+    Object.defineProperty(scope, "document", documentDescriptor);
+  }
 }
 
 function makeMetadata(