@rangojs/router 0.18.0 → 0.19.1

package/src/browser/server-action-bridge.ts

@@ -2,6 +2,7 @@ import type {
   ServerActionBridge,
   ServerActionBridgeConfig,
   RscPayload,
+  ResolvedSegment,
 } from "./types.js";
 import { createPartialUpdater } from "./partial-update.js";
 import { enterActionFence, exitActionFence } from "./action-fence.js";
@@ -38,6 +39,11 @@ import { mergeLocationState } from "./history-state.js";
 import { classifyActionOutcome } from "./action-coordinator.js";
 import { getAppVersion } from "./app-version.js";
 import { collectClientRevalidationDecisions } from "../client-urls/navigation.js";
+import {
+  decideCommitGatedOff,
+  findActionFormData,
+  type TransitionWhenActionInput,
+} from "./transition-when.js";
 import { CLIENT_REVALIDATION_HEADER } from "../client-urls/revalidation-protocol.js";
 
 // Polyfill Symbol.dispose/asyncDispose for Safari and older browsers
@@ -137,6 +143,20 @@ export function createServerActionBridge(
     getVersion: getAppVersion,
   });
 
+  /**
+   * transition({ when }) for an action commit: the location on screen,
+   * refreshed by the response's params and route name when it carries them.
+   */
+  const decideActionGatedOff = (
+    segments: readonly ResolvedSegment[],
+    metadata: RscPayload["metadata"] | undefined,
+    action: TransitionWhenActionInput,
+  ): boolean =>
+    decideCommitGatedOff(store, segments, "action", {
+      from: metadata,
+      action,
+    });
+
   /**
    * Refetch current route via a navigation transaction.
    * Encapsulates the repeated pattern of creating a navTx + fetchPartialUpdate
@@ -146,6 +166,8 @@ export function createServerActionBridge(
     segments?: string[];
     interceptSourceUrl?: string | null;
     actionId?: string;
+    /** transition({ when }) `action` fields for the refetch commit. */
+    action?: TransitionWhenActionInput;
   }): Promise<void> {
     const src = opts?.interceptSourceUrl ?? null;
     const navTx = createNavigationTransaction(
@@ -169,6 +191,7 @@ export function createServerActionBridge(
           type: "action" as const,
           ...(src ? { interceptSourceUrl: src } : {}),
           ...(opts?.actionId !== undefined ? { actionId: opts.actionId } : {}),
+          ...(opts?.action ? { action: opts.action } : {}),
         },
       );
     } finally {
@@ -560,8 +583,22 @@ export function createServerActionBridge(
         // Reconcile error segments with cached tree
         const errorResult = reconcileErrorSegments(cachedSegments, segments);
 
+        // transition({ when }) decides the error-boundary commit too, with
+        // `action.error` set.
+        const errorGatedOff = decideActionGatedOff(
+          errorResult.segments,
+          metadata,
+          {
+            id,
+            formData: findActionFormData(args),
+            error:
+              returnValue && !returnValue.ok ? returnValue.data : undefined,
+          },
+        );
+
         // Render the full tree with error segment merged with parent layouts
         const errorTree = await renderSegments(errorResult.mainSegments, {
+          transitionGatedOff: errorGatedOff,
           isAction: true,
           interceptSegments:
             errorResult.interceptSegments.length > 0
@@ -605,11 +642,13 @@ export function createServerActionBridge(
           errorResult.segments,
           currentHandleData,
         );
+        store.rememberDisplayedEntry();
 
-        // Update UI with error boundary
-        startTransition(() => {
-          onUpdate({ root: errorTree, metadata: metadata! });
-        });
+        // Update UI with error boundary: urgent when transition({ when })
+        // gated it off, like every gated-off commit.
+        const errorUpdate = { root: errorTree, metadata: metadata! };
+        if (errorGatedOff) onUpdate(errorUpdate);
+        else startTransition(() => onUpdate(errorUpdate));
 
         // Throw the error so the action promise rejects
         if (returnValue && !returnValue.ok) {
@@ -697,6 +736,13 @@ export function createServerActionBridge(
       if (scenario.type !== "navigated-away") {
         applyActionLocationState(handle, metadata?.locationState);
       }
+      // transition({ when }) `action` for this action's commit, whichever
+      // lane applies it (normal, or a refetch below).
+      const whenAction: TransitionWhenActionInput = {
+        id,
+        formData: findActionFormData(args),
+        result: returnData,
+      };
 
       switch (scenario.type) {
         case "navigated-away": {
@@ -712,13 +758,15 @@ export function createServerActionBridge(
             // Invalidation is deferred to finalizeAction(); here we only trigger
             // the revalidation refetch of the new route (suppressed on keep).
             if (!scenario.onInterceptRoute && !keepCache) {
-              refetchRoute({ actionId: id }).catch((error) => {
-                if (isBackgroundSuppressible(error)) return;
-                console.error(
-                  "[Browser] Background revalidation failed:",
-                  error,
-                );
-              });
+              refetchRoute({ actionId: id, action: whenAction }).catch(
+                (error) => {
+                  if (isBackgroundSuppressible(error)) return;
+                  console.error(
+                    "[Browser] Background revalidation failed:",
+                    error,
+                  );
+                },
+              );
             }
             break;
           }
@@ -730,6 +778,7 @@ export function createServerActionBridge(
             await refetchRoute({
               interceptSourceUrl: store.getInterceptSourceUrl(),
               actionId: id,
+              action: whenAction,
             });
           }
           break;
@@ -743,7 +792,11 @@ export function createServerActionBridge(
           // resolving last must discharge a directive-free sibling's repair.
           // See the keep row in docs/design/rango-state-cookie.md (the all-keep
           // edge, and the benign re-mark-stale-after-refetch end-state delta).
-          await refetchRoute({ interceptSourceUrl, actionId: id });
+          await refetchRoute({
+            interceptSourceUrl,
+            actionId: id,
+            action: whenAction,
+          });
           break;
         }
 
@@ -766,6 +819,7 @@ export function createServerActionBridge(
             segments: segmentsToSend,
             interceptSourceUrl,
             actionId: id,
+            action: whenAction,
           });
           break;
         }
@@ -791,8 +845,22 @@ export function createServerActionBridge(
         }
 
         case "normal": {
+          // transition({ when }) for the action commit (kind "action"): the
+          // page does not move, so `to` is `from`. False commits urgently (a
+          // re-suspending segment streams its loading()) and switches every
+          // <ViewTransition> class to "none"; true keeps the startTransition.
+          // This commit runs after awaits, outside the transition React opens
+          // for a form action / useActionState call, so React does not force
+          // a transition on it. The tree shape never changes, so
+          // useActionState and other client state survive (#995).
+          const gatedOff = decideActionGatedOff(
+            fullSegments,
+            metadata,
+            whenAction,
+          );
           // Prepare new tree (await loader data resolution)
           const newTree = await renderSegments(reconciled.mainSegments, {
+            transitionGatedOff: gatedOff,
             isAction: true,
             interceptSegments:
               reconciled.interceptSegments.length > 0
@@ -832,10 +900,11 @@ export function createServerActionBridge(
             fullSegments,
             currentHandleData,
           );
+          store.rememberDisplayedEntry(metadata?.routeName);
 
-          startTransition(() => {
-            onUpdate({ root: newTree, metadata: metadata! });
-          });
+          const actionUpdate = { root: newTree, metadata: metadata! };
+          if (gatedOff) onUpdate(actionUpdate);
+          else startTransition(() => onUpdate(actionUpdate));
           // Invalidation deferred to finalizeAction() (runs after this caches
           // the fresh segments), suppressed when the action called
           // keepClientCache().

package/src/browser/transition-when.ts

@@ -0,0 +1,205 @@
+/**
+ * Browser-side transition({ when }) decisions.
+ *
+ * A navigation is decided ONCE, at the first commit that presents its
+ * destination: the canonical commit for a server route, the optimistic swap
+ * for a clientUrls() cross-route navigation (the canonical commit then reuses
+ * the decision carried on its transaction), the history-cache restore or
+ * refetch commit for back/forward, the action commit (error lane included).
+ *
+ * The decision is navigation-wide: every distinct predicate (by function
+ * identity) declared by a committed segment, kept or re-sent (#989), runs, and
+ * any false gates the whole navigation off. It never changes the rendered
+ * tree's shape: every segment keeps its key and its <ViewTransition> element
+ * (segment-system.tsx renders each class "none"), and the commit is urgent
+ * instead of held (partial-update.ts). That is what keeps component state
+ * across when true -> false -> true (#995). A response carries no decision,
+ * so a reused prefetch is decided against the real source.
+ */
+
+import type {
+  ResolvedSegment,
+  RouteLocation,
+  TransitionWhenContext,
+  TransitionWhenFn,
+  TransitionWhenKind,
+} from "../types/segments.js";
+import { resolveTransitionWhen } from "../transition-when-ref.js";
+import { makeIsAction } from "../router/is-action.js";
+import { isInterceptSegment } from "./intercept-utils.js";
+import type { NavigationStore } from "./types.js";
+
+/** One side of the navigation before it is frozen into a RouteLocation. */
+export interface RouteLocationInput {
+  url: string | URL;
+  params?: Readonly<Record<string, string>>;
+  routeName?: string;
+  state?: unknown;
+}
+
+/** The action fields of a `kind: "action"` context. */
+export interface TransitionWhenActionInput {
+  id?: string;
+  formData?: FormData;
+  result?: unknown;
+  error?: unknown;
+}
+
+export interface TransitionDecisionInput {
+  kind: TransitionWhenKind;
+  from: RouteLocationInput;
+  /** The destination; ignored for "action" and "revalidate" (`to` is `from`). */
+  to?: RouteLocationInput;
+  action?: TransitionWhenActionInput;
+}
+
+const EMPTY_PARAMS: Readonly<Record<string, string>> = Object.freeze({});
+
+function createRouteLocation(input: RouteLocationInput): RouteLocation {
+  return Object.freeze({
+    // A fresh URL: a predicate may not mutate the store's or the caller's.
+    url: new URL(
+      String(input.url),
+      typeof window !== "undefined"
+        ? window.location.href
+        : "http://localhost/",
+    ),
+    params: input.params ? Object.freeze({ ...input.params }) : EMPTY_PARAMS,
+    routeName: input.routeName,
+    state: input.state,
+  });
+}
+
+export function createTransitionWhenContext(
+  input: TransitionDecisionInput,
+): TransitionWhenContext {
+  const from = createRouteLocation(input.from);
+  const inAction = input.kind === "action";
+  const { id, formData, result, error } = input.action ?? {};
+  return Object.freeze({
+    kind: input.kind,
+    from,
+    to:
+      inAction || input.kind === "revalidate" || !input.to
+        ? from
+        : createRouteLocation(input.to),
+    isAction: makeIsAction(id, inAction),
+    ...(inAction && { action: Object.freeze({ id, formData, result, error }) }),
+  });
+}
+
+/**
+ * Run one predicate. A throw counts as false (the navigation does not hold)
+ * and is logged; it never fails the navigation.
+ */
+export function evaluateTransitionWhen(
+  fn: TransitionWhenFn,
+  ctx: TransitionWhenContext,
+): boolean {
+  try {
+    return fn(ctx) !== false;
+  } catch (error) {
+    console.error(
+      "[rango] transition({ when }) threw; the navigation does not hold.",
+      error,
+    );
+    return false;
+  }
+}
+
+/** Distinct predicates of the segments that declare one, in segment order. */
+export function collectTransitionWhens(
+  segments: readonly ResolvedSegment[],
+): Set<TransitionWhenFn> {
+  const fns = new Set<TransitionWhenFn>();
+  for (const segment of segments) {
+    const fn = resolveTransitionWhen(segment.transition?.when);
+    if (fn) fns.add(fn);
+  }
+  return fns;
+}
+
+/**
+ * Decide a commit: true when the navigation is gated off (some predicate
+ * returned false or threw). The context is built only when a predicate runs.
+ * An intercept commit is not evaluated: it never holds or animates
+ * (partial-update.ts shouldStartViewTransition). `extra` is a predicate not on
+ * a segment yet (the optimistic clientUrls() destination).
+ */
+export function decideTransitionGatedOff(
+  segments: readonly ResolvedSegment[],
+  input: () => TransitionDecisionInput,
+  extra?: TransitionWhenFn,
+): boolean {
+  if (segments.some(isInterceptSegment)) return false;
+  const fns = collectTransitionWhens(segments);
+  if (extra) fns.add(extra);
+  if (fns.size === 0) return false;
+  const ctx = createTransitionWhenContext(input());
+  for (const fn of fns) if (!evaluateTransitionWhen(fn, ctx)) return true;
+  return false;
+}
+
+/** Merge route params the way popstate restores them (per-segment params). */
+export function mergeSegmentParams(
+  segments: readonly ResolvedSegment[],
+): Record<string, string> {
+  const params: Record<string, string> = {};
+  for (const s of segments) if (s.params) Object.assign(params, s.params);
+  return params;
+}
+
+export interface CommitDecision {
+  /** Newer params / route name for the committed location (an action response's). */
+  from?: { params?: Record<string, string>; routeName?: string };
+  /** The destination, from the committed location; omit for "action" / "revalidate". */
+  to?: (from: RouteLocationInput) => RouteLocationInput;
+  action?: TransitionWhenActionInput;
+  extra?: TransitionWhenFn;
+}
+
+/**
+ * decideTransitionGatedOff with `from` read from the store: call it before
+ * the commit moves the store. `state` is the live history.state, except for
+ * back/forward: at popstate history.state already belongs to the destination,
+ * so the entry being left comes from the store's per-entry memory (undefined
+ * after a reload, never guessed).
+ */
+export function decideCommitGatedOff(
+  store: NavigationStore,
+  segments: readonly ResolvedSegment[],
+  kind: TransitionWhenKind,
+  decision: CommitDecision = {},
+): boolean {
+  return decideTransitionGatedOff(
+    segments,
+    () => {
+      const memory = store.getHistoryEntryMemory();
+      const from: RouteLocationInput = {
+        url: store.getSegmentState().currentUrl || window.location.href,
+        params:
+          decision.from?.params ??
+          mergeSegmentParams(
+            store.getCachedSegments(store.getHistoryKey())?.segments ?? [],
+          ),
+        routeName: decision.from?.routeName ?? memory?.routeName,
+        state: kind === "pop" ? memory?.state : window.history.state,
+      };
+      return {
+        kind,
+        from,
+        to: decision.to?.(from),
+        action: decision.action,
+      };
+    },
+    decision.extra,
+  );
+}
+
+/** The FormData argument a server action was called with, if any. */
+export function findActionFormData(
+  args: readonly unknown[],
+): FormData | undefined {
+  if (typeof FormData === "undefined") return undefined;
+  return args.find((arg): arg is FormData => arg instanceof FormData);
+}

package/src/browser/types.ts

@@ -48,6 +48,12 @@ export interface RscMetadata {
   resolvedIds?: string[];
   /** Merged route params from the matched route */
   params?: Record<string, string>;
+  /**
+   * The matched route's name (include name prefix applied), when the route is
+   * named. The browser keeps it per history entry for transition({ when })'s
+   * `from.routeName` / `to.routeName` (browser/transition-when.ts).
+   */
+  routeName?: string;
   /**
    * State of named slots for this route match
    * Key is slot name (e.g., "@modal"), value is slot state
@@ -276,6 +282,18 @@ export interface SegmentState {
   currentSegmentIds: string[];
 }
 
+/**
+ * What the router remembers about one history entry for transition({ when })
+ * (NavigationStore.rememberDisplayedEntry).
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface HistoryEntryMemory {
+  readonly routeName: string | undefined;
+  /** The entry's `history.state` as last recorded. */
+  readonly state: unknown;
+}
+
 /**
  * Navigation update emitted when UI should re-render
  *
@@ -296,13 +314,67 @@ export interface NavigationUpdate {
 }
 
 /**
- * State value for navigate/Link
- * - LocationStateEntry[]: Type-safe state entries (recommended)
- * - unknown: Plain state format (object or getter function)
+ * Plain object accepted as {@link PlainHistoryState}. The `any` string index
+ * admits interface-typed values (an `unknown` index would reject interfaces,
+ * which carry no implicit index signature). The `never` members reject:
+ * - a single typed entry (`GridState(value)` without the array) — its
+ *   `__rsc_ls_*` fields would be spread onto history.state and
+ *   `useLocationState(GridState)` would read `undefined`;
+ * - functions, including a location-state definition passed uncalled
+ *   (`Symbol.hasInstance` comes from `Function.prototype`), which throw
+ *   `DataCloneError`;
+ * - arrays and other iterables (`Symbol.iterator`), so an array must match the
+ *   typed-entry or plain-array member instead;
+ * - built-ins tagged with `Symbol.toStringTag` (`Promise`, `WeakMap`,
+ *   `WeakSet`), which throw `DataCloneError`. The cloneable tagged ones
+ *   (`Map`, `Set`, `ArrayBuffer`, typed arrays) have their own members.
+ *
+ * Members are not checked: a function, symbol, or React element inside a
+ * plain object still compiles, as does a top-level `ReactElement` or DOM node
+ * (an object with none of the keys above).
+ */
+export interface PlainHistoryObject {
+  readonly [key: string]: any;
+  readonly __rsc_ls_key?: never;
+  readonly __rsc_ls_value?: never;
+  readonly __rsc_ls_lazy?: never;
+  readonly [Symbol.iterator]?: never;
+  readonly [Symbol.hasInstance]?: never;
+  readonly [Symbol.toStringTag]?: never;
+}
+
+/**
+ * Plain (untyped) navigation state, stored under `history.state.state` and
+ * read with `useLocationState<T>()`. A structured-clone-safe value: primitives,
+ * arrays, `Map`/`Set`, `ArrayBuffer`, typed arrays, and plain objects. Excludes
+ * functions, symbols, `Promise`/`WeakMap`/`WeakSet`, and objects carrying
+ * `__rsc_ls_*` keys (a typed entry passed without its array). Arrays, `Map`,
+ * and `Set` are checked element by element; plain object members are not
+ * checked (see {@link PlainHistoryObject}).
+ */
+export type PlainHistoryState =
+  | string
+  | number
+  | boolean
+  | bigint
+  | null
+  | undefined
+  | readonly PlainHistoryState[]
+  | ReadonlyMap<PlainHistoryState, PlainHistoryState>
+  | ReadonlySet<PlainHistoryState>
+  | ArrayBuffer
+  | ArrayBufferView
+  | PlainHistoryObject;
+
+/**
+ * State value for `router.push()` / `router.replace()` / `<Link state>`.
+ * - `readonly LocationStateEntry[]`: typed entries from `createLocationState()`
+ *   definitions, e.g. `[GridState({ count: 3 })]` (recommended)
+ * - {@link PlainHistoryState}: plain structured-clone-safe state
  */
 export type HistoryState =
-  | import("./react/location-state-shared.js").LocationStateEntry[]
-  | unknown;
+  | readonly import("./react/location-state-shared.js").LocationStateEntry[]
+  | PlainHistoryState;
 
 /**
  * Options for navigation operations
@@ -329,6 +401,22 @@ export interface NavigateOptions {
    * ```
    */
   revalidate?: boolean;
+  /**
+   * Set to `false` to present this navigation without a transition: the
+   * commit is urgent and every `<ViewTransition>` class resolves to `"none"`,
+   * the same result as a `transition({ when })` predicate returning `false`.
+   * No `when` predicate is called. Back/forward, action and revalidation
+   * commits are unaffected (they are not started by this call).
+   *
+   * @default true (the route's transition config applies)
+   *
+   * @example
+   * ```tsx
+   * router.push("/photos/2", { transition: false });
+   * <Link to="/photos/2" transition={false}>Next</Link>
+   * ```
+   */
+  transition?: boolean;
   /**
    * State to pass to history.pushState/replaceState
    * Accessible via useLocationState() hook.
@@ -350,15 +438,25 @@ export interface NavigateOptions {
    * // Plain static state
    * navigate("/product", { state: { from: "list" } });
    *
-   * // Plain just-in-time state
-   * navigate("/product", { state: () => ({ from: window.location.pathname }) });
+   * // Compile errors (and a dev-mode runtime error for untyped callers):
+   * navigate("/product", { state: ProductState(p) }); // entry without the array
+   * navigate("/product", { state: [ProductState] }); // definition not called
    * ```
    */
   state?: HistoryState;
 }
 
-/** @internal Extended options used only within the navigation bridge */
-export interface NavigateOptionsInternal extends NavigateOptions {
+/**
+ * @internal Extended options used only within the navigation bridge. `state`
+ * is widened to `unknown`: the redirect lanes pass state already resolved to
+ * a flat `history.state` record, and in dev Link passes an uncalled
+ * definition through to resolveNavigationState's check.
+ */
+export interface NavigateOptionsInternal extends Omit<
+  NavigateOptions,
+  "state"
+> {
+  state?: unknown;
   /** Skip segment cache (used by redirect-with-state to force re-render) */
   _skipCache?: boolean;
 }
@@ -465,6 +563,22 @@ export interface NavigationStore {
   // History-based segment cache (for back/forward navigation and partial merging)
   getHistoryKey(): string;
   setHistoryKey(key: string): void;
+
+  /**
+   * Per-history-entry memory for transition({ when }) sources: record the
+   * entry on screen (keyed by its `history.state.key`) with its current
+   * `history.state` and, when given, its route name (kept from the last
+   * record otherwise; every push/replace creates a new key, so a stale name
+   * never carries to another entry). Called after every commit, restore and
+   * state merge.
+   */
+  rememberDisplayedEntry(routeName?: string): void;
+  /**
+   * The memory of the entry on screen, or of `entryKey`. At popstate
+   * history.state already belongs to the destination, so back/forward reads
+   * the entry being LEFT from here. In-memory only: empty after a reload.
+   */
+  getHistoryEntryMemory(entryKey?: string): HistoryEntryMemory | undefined;
   /** Monotonic token of the most recently committed navigation. */
   getNavInstance(): number;
   cacheSegmentsForHistory(
@@ -631,7 +745,7 @@ export interface ServerActionBridgeConfig {
  * Navigation bridge for handling client-side navigation
  */
 export interface NavigationBridge {
-  navigate(url: string, options?: NavigateOptions): Promise<void>;
+  navigate(url: string, options?: NavigateOptionsInternal): Promise<void>;
   refresh(): Promise<void>;
   handlePopstate(): Promise<void>;
   registerLinkInterception(): () => void;