@rangojs/router 0.17.0 → 0.19.0

package/src/testing/render-route.tsx

@@ -30,6 +30,11 @@
  *     model is the held-navigation useLoader().isLoading: a `transition` spec
  *     plus a pending Promise seeded via navigate(url, { loaders }) commits
  *     through production's commitInTransition (browser/partial-update.ts).
+ *   - A spec's transition({ when }) decides every commit with production's
+ *     browser decision: navigate() and useRouter().push model kind "push",
+ *     useRouter().replace kind "replace", refresh() kind "revalidate".
+ *     Back/forward, action and optimistic clientUrls() swap decisions 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
@@ -42,6 +47,7 @@
  * (the segment chain is wrapped in a MountContext exactly as in production).
  */
 
+import { decideTransitionGatedOff } from "../browser/transition-when.js";
 import { useEffect, type ReactNode, type ComponentType } from "react";
 import type { RenderResult } from "@testing-library/react";
 import { renderSegments } from "../segment-system.js";
@@ -56,6 +62,7 @@ import {
   shouldStartViewTransition,
 } from "../browser/partial-update.js";
 import type {
+  NavigateOptionsInternal,
   NavigationStore,
   NavigationBridge,
   UpdateSubscriber,
@@ -68,8 +75,19 @@ import {
   buildParamsFromMatch,
 } from "../router/pattern-matching.js";
 import { normalizeBasename } from "../router/basename.js";
-import type { LoaderDefinition, TransitionConfig } from "../types.js";
+import type {
+  LoaderDefinition,
+  TransitionConfig,
+  TransitionWhenKind,
+} from "../types.js";
 import type { LocationStateDefinition } from "../browser/react/location-state-shared.js";
+import {
+  buildHistoryState,
+  hasLocationState,
+  pushHistoryWithIdx,
+  resolveNavigationState,
+} from "../browser/history-state.js";
+import { withLocationStateKey } from "./location-state-key.js";
 import type { Handle } from "../handle.js";
 import type { ThemeConfig } from "../theme/types.js";
 import { resolveThemeConfig } from "../theme/constants.js";
@@ -93,18 +111,15 @@ export type HandleDataSeed = Record<string, Record<string, unknown[]>>;
 const syntheticIds = new WeakMap<object, string>();
 let syntheticIdCounter = 0;
 
-function ensureSyntheticId(
-  handle: object,
-  field: "$$id" | "__rsc_ls_key",
-): string {
-  const existing = (handle as Record<string, string>)[field];
+function ensureSyntheticId(loader: object): string {
+  const existing = (loader as { $$id?: string }).$$id;
   if (existing) return existing;
-  let id = syntheticIds.get(handle);
+  let id = syntheticIds.get(loader);
   if (!id) {
     id = `__rango_test_id_${syntheticIdCounter++}`;
-    syntheticIds.set(handle, id);
+    syntheticIds.set(loader, id);
   }
-  (handle as Record<string, string>)[field] = id;
+  (loader as { $$id?: string }).$$id = id;
   return id;
 }
 
@@ -337,11 +352,20 @@ export interface TestRouterHandle {
    * // reader: isLoading true, old data
    * await act(async () => resolve({ name: "Product 2" }));
    * // reader: isLoading false, new data
+   *
+   * `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.
    */
   navigate(
     url: string,
-    options?: Pick<RenderRouteOptions, "loaders">,
+    options?: Pick<RenderRouteOptions, "loaders"> & { transition?: boolean },
   ): Promise<void>;
+  /**
+   * Re-render the current location, as router.refresh() does: a spec's
+   * transition({ when }) decides it with kind "revalidate" (`to` is `from`).
+   */
+  refresh(): Promise<void>;
   /** The current committed pathname. */
   pathname(): string;
   /** The current committed params. */
@@ -508,7 +532,7 @@ export async function renderRoute(
   ): Record<string, unknown> => {
     const out = { ...base };
     for (const [loader, data] of loaders ?? []) {
-      out[ensureSyntheticId(loader as object, "$$id")] = data;
+      out[ensureSyntheticId(loader)] = data;
     }
     return out;
   };
@@ -517,7 +541,7 @@ export async function renderRoute(
   if (typeof window !== "undefined") {
     const stateObj: Record<string, unknown> = {};
     for (const [def, value] of options.locationState ?? []) {
-      stateObj[ensureSyntheticId(def as object, "__rsc_ls_key")] = value;
+      stateObj[withLocationStateKey(def).__rsc_ls_key] = value;
     }
     window.history.replaceState(stateObj, "");
   }
@@ -597,8 +621,30 @@ export async function renderRoute(
   let warnedNavLifecycle = false;
   const navigate = async (
     target: string,
-    navOptions?: Pick<RenderRouteOptions, "loaders">,
+    navOptions?: Pick<RenderRouteOptions, "loaders"> & {
+      history?: Pick<
+        NavigateOptionsInternal,
+        "state" | "replace" | "transition"
+      >;
+      kind?: TransitionWhenKind;
+      transition?: boolean;
+    },
   ): Promise<void> => {
+    // 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.
+    const history = navOptions?.history;
+    const historyState = history
+      ? buildHistoryState(
+          history.state !== undefined
+            ? resolveNavigationState(history.state)
+            : undefined,
+        )
+      : undefined;
     // No server fetch, so the navigation lifecycle never starts: the state
     // useNavigation()/useLinkStatus()/useAction() read stays "idle" — asserting
     // a pending/loading/submitting state here proves nothing. Warn once (per
@@ -623,30 +669,76 @@ export async function renderRoute(
       mount,
     );
     const metadata = makeMetadata(nextUrl.pathname, segments, match.params);
+    // Production's browser-run transition({ when }) decision
+    // (browser/partial-update.ts): the committed location is the source.
+    const kind: TransitionWhenKind =
+      navOptions?.kind ?? (history?.replace ? "replace" : "push");
+    // `transition: false` gates off without calling a predicate
+    // (navigation-bridge.ts navigate).
+    const transitionOptOut =
+      (navOptions?.transition ?? history?.transition) === false;
+    const gatedOff =
+      transitionOptOut ||
+      decideTransitionGatedOff(segments, () => ({
+        kind,
+        from: {
+          url: eventController.getLocation().href,
+          params: eventController.getParams(),
+          routeName: leaf.name,
+          state: window.history.state,
+        },
+        to: {
+          url: nextUrl,
+          params: match.params,
+          routeName: leaf.name,
+          state: historyState ?? null,
+        },
+      }));
     const root = await renderSegments(segments, {
       outletPending: options.outletPending,
+      transitionGatedOff: gatedOff,
     });
     eventController.setLocation(nextUrl);
     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,
+      );
+    }
     const emit: UpdateSubscriber = (update) => store.emitUpdate(update);
     await act(async () => {
       // 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)) {
+      if (shouldStartViewTransition(segments, gatedOff)) {
         commitInTransition(emit, segments, { root, metadata }, ["navigation"]);
       } else {
         emit({ root, metadata });
       }
+      if (notifyLocationState) {
+        window.dispatchEvent(new Event("__rsc_locationstate"));
+      }
     });
   };
 
+  const refresh = (): Promise<void> => {
+    const current = new URL(eventController.getLocation().href);
+    return navigate(current.pathname + current.search, { kind: "revalidate" });
+  };
+
   let prefetchRoot: HTMLElement | undefined;
   const bridge: NavigationBridge = {
-    navigate: (target) => navigate(target),
-    refresh: () => navigate(url.pathname + url.search),
+    navigate: (target, navigateOptions) =>
+      navigate(target, { history: navigateOptions ?? {} }),
+    refresh: () => refresh(),
     handlePopstate: async () => {},
     registerLinkInterception: () => () => {},
     registerDelegatedPrefetch: () =>
@@ -704,6 +796,7 @@ export async function renderRoute(
 
   const router: TestRouterHandle = {
     navigate,
+    refresh,
     pathname: () => new URL(eventController.getLocation().href).pathname,
     params: () => eventController.getParams(),
     store,

package/src/testing/run-client-revalidate.ts

@@ -10,7 +10,8 @@
  * Synchronous: client revalidate functions must be sync.
  */
 
-import { makeIsAction, resolveActionRefId } from "../router/is-action.js";
+import { makeIsAction } from "../router/is-action.js";
+import { resolveTestActionId } from "./internal/action-id.js";
 import {
   lockedClientDefault,
   runClientRevalidateChain,
@@ -23,23 +24,6 @@ import type {
 
 const DEFAULT_URL = "http://localhost/";
 
-function resolveActionId(
-  action: ((...args: never[]) => unknown) | string | undefined,
-): string | undefined {
-  if (action === undefined) return undefined;
-  if (typeof action === "string") return action;
-  const id = resolveActionRefId(action);
-  if (id === undefined) {
-    throw new Error(
-      "runClientRevalidate: `action` must be a single imported server action " +
-        "(carrying its build-injected id) or an actionId string. The passed " +
-        "function has no $id/$$id — outside a built app, pass the id string " +
-        'your predicate should match (e.g. "src/actions/cart.ts#addToCart").',
-    );
-  }
-  return id;
-}
-
 /**
  * Options for {@link runClientRevalidate}. Defaults model a same-URL
  * navigation with no action (locked default `false`).
@@ -80,7 +64,7 @@ export function runClientRevalidate(
   const currentParams = opts.currentParams ?? {};
   const nextParams = opts.nextParams ?? currentParams;
   const inAction = opts.action !== undefined;
-  const actionId = resolveActionId(opts.action);
+  const actionId = resolveTestActionId(opts.action, "runClientRevalidate");
   const defaultShouldRevalidate = lockedClientDefault({
     actionRequest: opts.actionRequest ?? inAction,
     currentParams,

package/src/testing/run-loader.ts

@@ -48,6 +48,10 @@ import { collectHandle } from "./collect-handle.js";
 import type { ThemeConfig } from "../theme/types.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import type { CacheProfile } from "../cache/profile-registry.js";
+import type { PartialCacheOptions } from "../types/cache-types.js";
+import type { HandlerContext } from "../types/handler-context.js";
+import { resolveLoaderData } from "../router/segment-resolution/loader-cache.js";
+import { armLoaderTagSets } from "../cache/cache-tag.js";
 import {
   createTestRequestContext,
   buildRunSnapshot,
@@ -111,9 +115,11 @@ export interface RunLoaderOptions<TEnv = any> {
   basename?: string;
   /**
    * Theme config in the same shape `createRouter({ theme })` takes (e.g. `true`
-   * or `{ themes: [...] }`). Seeds the request's theme config so nested handler
-   * or cache contexts created from this loader observe it. Loaders themselves do
-   * not expose `ctx.theme`/`ctx.setTheme` (those are handler/middleware-only).
+   * or `{ themes: [...] }`). Seeds the request's theme config, so the loader
+   * body reads the visitor's theme (the Cookie on `request`, or the default)
+   * with `getRequestContext().theme`. That read is guarded like `cookies()`: it
+   * throws inside a `"use cache"` function (#971). The loader ctx has no
+   * `theme`/`setTheme` (those are handler/middleware-only).
    */
   theme?: ThemeConfig | true;
   /** Environment bindings surfaced as `ctx.env`. */
@@ -151,6 +157,18 @@ export interface RunLoaderOptions<TEnv = any> {
   cacheStore?: SegmentCacheStore;
   /** Cache profiles (the `createRouter({ cacheProfiles })` shape). */
   cacheProfiles?: Record<string, CacheProfile>;
+  /**
+   * Run the loader through the `cache()` a route binds it with — the options
+   * `loader(Loader, () => [cache({...})])` takes — using the production
+   * read-through against `cache.store`, else `cacheStore`. A HIT returns the
+   * stored value without running the body and records the tags the body
+   * recorded when the entry was written, so `updateTag()` of any of them drops
+   * the entry. The write is a background task the call does not await (spy
+   * on the store's `setItem` to wait for it). A raw loader body is keyed by
+   * its function reference. `handlePushes` lists the body's pushes, so a HIT
+   * reports none: the replay into the page's handle store is not modeled.
+   */
+  cache?: PartialCacheOptions;
   /**
    * Customize the rango state cookie a loader that calls
    * `invalidateClientCache()` rotates (the name is always seeded — default
@@ -352,6 +370,50 @@ function runWithLoaderContext<R>(
   });
 }
 
+const rawLoaderIds = new WeakMap<object, string>();
+let rawLoaderSeq = 0;
+
+function cacheLoaderId(loader: RunnableLoader<unknown>): string {
+  if (typeof loader !== "function") return loader.$$id;
+  let id = rawLoaderIds.get(loader);
+  if (id === undefined) {
+    id = `runLoader#${++rawLoaderSeq}`;
+    rawLoaderIds.set(loader, id);
+  }
+  return id;
+}
+
+/**
+ * Call the loader: directly, or through its `cache()` binding (the funnel a
+ * route's DSL loaders take, loader-cache.ts resolveLoaderData), whose MISS
+ * reads the binding through the handler ctx's use(). A binding arms the
+ * per-execution loader tag sets first, as a match that resolves one does
+ * (match-api.ts, bindsLoaderCache).
+ */
+function invokeLoader<T>(
+  loader: RunnableLoader<T>,
+  loaderFn: (ctx: TestLoaderContext) => Promise<T> | T,
+  opts: RunLoaderOptions,
+  loaderCtx: TestLoaderContext,
+): Promise<T> {
+  const run = () => Promise.resolve(loaderFn(loaderCtx));
+  if (!opts.cache) return run();
+  armLoaderTagSets();
+  const handlerCtx = {
+    params: loaderCtx.params,
+    use: run,
+  } as unknown as HandlerContext<any, any>;
+  return resolveLoaderData(
+    {
+      loader: { __brand: "loader", $$id: cacheLoaderId(loader) },
+      revalidate: [],
+      cache: { options: opts.cache },
+    },
+    handlerCtx,
+    loaderCtx.pathname,
+  );
+}
+
 export async function runLoader<T>(
   loader: RunnableLoader<T>,
   opts: RunLoaderOptions = {},
@@ -359,7 +421,7 @@ export async function runLoader<T>(
   const loaderFn = resolveLoaderFn(loader);
   const { ctx } = createTestRequestContext(buildLoaderCtxOpts(opts));
   return runWithLoaderContext(ctx as RequestContext<any>, opts, (loaderCtx) =>
-    Promise.resolve(loaderFn(loaderCtx)),
+    invokeLoader(loader, loaderFn, opts, loaderCtx),
   );
 }
 
@@ -413,7 +475,7 @@ export async function runLoaderResult<T>(
     result = await runWithLoaderContext(
       reqCtx,
       opts,
-      (loaderCtx) => Promise.resolve(loaderFn(loaderCtx)),
+      (loaderCtx) => invokeLoader(loader, loaderFn, opts, loaderCtx),
       handlePushes,
     );
   } catch (error) {