@rangojs/router 0.18.0 → 0.19.0

package/src/client-urls/navigation.ts

@@ -8,6 +8,7 @@ import {
 } from "./revalidate-chain.js";
 import { encodeClientRevalidationDecisions } from "./revalidation-protocol.js";
 import type { ClientUrlPatterns } from "./types.js";
+import type { TransitionWhenFn } from "../types/segments.js";
 
 export interface ClientUrlNavigationIntent {
   readonly routeId: string;
@@ -16,6 +17,26 @@ export interface ClientUrlNavigationIntent {
   /** Absolute destination pathname (mount included) and search ("?..." or ""). */
   readonly pathname: string;
   readonly search: string;
+  /**
+   * transition({ when }) gated this navigation off at the swap: the
+   * destination presents urgently instead of in a transition lane.
+   */
+  readonly transitionGatedOff?: boolean;
+}
+
+/** What the bridge needs to decide transition({ when }) at the swap. */
+export interface ClientUrlDestination {
+  /** Definition-local params of the destination match. */
+  readonly params: Readonly<Record<string, string>>;
+  /** Canonical route name (include prefix applied); undefined when unnamed. */
+  readonly routeName: string | undefined;
+  /** The destination route's own `when`, from its "use client" definition. */
+  readonly when: TransitionWhenFn | undefined;
+  /**
+   * Param names the ORIGIN route matched inside the group: the committed
+   * params minus these are the mount's (include prefix) params.
+   */
+  readonly originLocalParamNames: readonly string[];
 }
 
 interface ActiveClientUrlGroup {
@@ -24,6 +45,8 @@ interface ActiveClientUrlGroup {
   readonly mount: string;
   /** include() route-name prefix ("" at root) for canonical name composition. */
   readonly namePrefix: string;
+  /** The group route on screen (ClientUrlsRoot's committed routeId). */
+  readonly routeId: string | undefined;
   readonly setIntent: (intent: ClientUrlNavigationIntent | null) => void;
   intent: ClientUrlNavigationIntent | null;
 }
@@ -48,6 +71,12 @@ export function setActiveInterceptTargets(
 
 export interface ClientUrlNavigationPresentation {
   readonly routeId: string;
+  /**
+   * The transition({ when }) decision made at the optimistic swap (true =
+   * gated off), or undefined when nothing was swapped (a same-route
+   * navigation decides at the canonical commit).
+   */
+  readonly transitionGatedOff: boolean | undefined;
   clear(): void;
 }
 
@@ -75,11 +104,13 @@ export function registerClientUrlGroup(
   mount: string,
   namePrefix: string,
   setIntent: (intent: ClientUrlNavigationIntent | null) => void,
+  routeId?: string,
 ): () => void {
   const group: ActiveClientUrlGroup = {
     definition,
     mount,
     namePrefix,
+    routeId,
     setIntent,
     intent: null,
   };
@@ -93,6 +124,7 @@ export function registerClientUrlGroup(
 export function beginClientUrlNavigation(
   targetUrl: URL,
   signal: AbortSignal,
+  decideTransition?: (destination: ClientUrlDestination) => boolean,
 ): ClientUrlNavigationPresentation | null {
   const group = activeGroup;
   if (!group) return null;
@@ -110,11 +142,28 @@ export function beginClientUrlNavigation(
   const record = group.definition.routes.find(
     (candidate) => candidate.id === match.routeKey,
   );
-  if (record?.name) {
-    const canonicalName = group.namePrefix
+  const canonicalName = record?.name
+    ? group.namePrefix
       ? `${group.namePrefix}.${record.name}`
-      : record.name;
-    if (activeInterceptTargets.has(canonicalName)) return null;
+      : record.name
+    : undefined;
+  if (canonicalName && activeInterceptTargets.has(canonicalName)) return null;
+
+  // A same-route intent never swaps (ClientUrlsRoot), so transition({ when })
+  // decides at the canonical commit; a cross-route one decides here, at the
+  // navigation's first presentation.
+  let transitionGatedOff: boolean | undefined;
+  if (decideTransition && match.routeKey !== group.routeId) {
+    const originLocal = stripMountPrefix(window.location.pathname, group.mount);
+    const originMatch =
+      originLocal === null ? null : group.definition.match(originLocal);
+    const when = record?.transition?.when;
+    transitionGatedOff = decideTransition({
+      params: match.params,
+      routeName: canonicalName,
+      when: typeof when === "function" ? when : undefined,
+      originLocalParamNames: Object.keys(originMatch?.params ?? {}),
+    });
   }
 
   const intent: ClientUrlNavigationIntent = {
@@ -122,6 +171,7 @@ export function beginClientUrlNavigation(
     params: match.params,
     pathname: targetUrl.pathname,
     search: targetUrl.search,
+    transitionGatedOff,
   };
   group.intent = intent;
   group.setIntent(intent);
@@ -142,6 +192,7 @@ export function beginClientUrlNavigation(
 
   return {
     routeId: match.routeKey,
+    transitionGatedOff,
     clear() {
       signal.removeEventListener("abort", clear);
       clear();

package/src/client-urls/server-projection.ts

@@ -1,3 +1,4 @@
+import { requestHeaders } from "../server/request-headers.js";
 import * as React from "react";
 import type { SearchSchemaValue } from "../search-params.js";
 import { getLoaderLazy } from "../server/loader-registry.js";
@@ -27,6 +28,7 @@ import {
   ClientUrlsLoading,
   ClientUrlsRoot,
 } from "./client-root.js";
+import { createClientUrlsWhenRef } from "../transition-when-ref.js";
 import type {
   ClientTransitionConfig,
   ClientUrlInterceptRecord,
@@ -94,9 +96,12 @@ export interface ClientUrlProjectionRoute {
    *  document renders await them before first flush. Absent (= none) in
    *  projections serialized before the option existed. */
   readonly awaitedLoaderIndices?: readonly number[];
-  /** Data-only transition config (no `when` — server-tree only); absent in
-   *  projections serialized before transition support. */
+  /** Data-only transition config (never `when`); absent in projections
+   *  serialized before transition support. */
   readonly transition?: Readonly<ClientTransitionConfig>;
+  /** The route's transition() declares a browser-run `when`. Materialization
+   *  attaches a clientUrls when reference (definition + route id). */
+  readonly transitionWhen?: true;
 }
 
 export interface ClientUrlProjectionIntercept {
@@ -249,11 +254,12 @@ function serializeTransition(
 ): Readonly<ClientTransitionConfig> | undefined {
   const source = route.transition;
   if (!source) return undefined;
-  // The DSL already validated shape and rejected `when`; re-copy defensively
-  // so the projection is a plain JSON value (class maps included).
+  // The DSL already validated shape; re-copy defensively so the projection is
+  // a plain JSON value (class maps included). `when` is a function: the
+  // projection records only that it exists (transitionWhen).
   const config: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(source)) {
-    if (value === undefined) continue;
+    if (value === undefined || key === "when") continue;
     config[key] =
       typeof value === "object" && value !== null
         ? Object.freeze({ ...(value as Record<string, string>) })
@@ -289,6 +295,9 @@ function serializeRoute(route: ClientUrlRouteRecord): ClientUrlProjectionRoute {
       ? { awaitedLoaderIndices: Object.freeze(awaitedLoaderIndices) }
       : {}),
     ...(transition ? { transition } : {}),
+    ...(typeof route.transition?.when === "function"
+      ? { transitionWhen: true as const }
+      : {}),
   });
 }
 
@@ -433,7 +442,7 @@ function clientDecisionsFor(
     return decisionsByRequest.get(request) ?? null;
   }
   const decoded = decodeClientRevalidationDecisions(
-    request.headers.get(CLIENT_REVALIDATION_HEADER),
+    requestHeaders(request).get(CLIENT_REVALIDATION_HEADER),
   );
   decisionsByRequest.set(request, decoded);
   return decoded;
@@ -561,9 +570,20 @@ function materializeRouteItems(
                   ),
                 ]
               : []),
-            // Data-only per-route transition config: same child position as a
-            // hand-written server transition(config) — no `when`.
-            ...(route.transition ? [transition({ ...route.transition })] : []),
+            // Per-route transition config: same child position as a
+            // hand-written server transition(config). A declared `when` rides
+            // as a reference to the definition + route id; the browser calls
+            // the function the "use client" module declares.
+            ...(route.transition
+              ? [
+                  transition({
+                    ...route.transition,
+                    ...(route.transitionWhen
+                      ? { when: createClientUrlsWhenRef(reference, route.id) }
+                      : {}),
+                  }),
+                ]
+              : []),
           ],
         ) as AllUseItems,
     );
@@ -596,7 +616,8 @@ function materializeRouteItems(
   const isInGroupOrigin = ({ from }: InterceptSelectorContext): boolean =>
     mount === "/"
       ? true
-      : from.pathname === mount || from.pathname.startsWith(`${mount}/`);
+      : from.url.pathname === mount ||
+        from.url.pathname.startsWith(`${mount}/`);
   const slotNames = [...new Set(intercepts.map((record) => record.slotName))];
   const buildInterceptItems = (): AllUseItems[] =>
     intercepts.map(

package/src/client-urls/types.ts

@@ -123,14 +123,21 @@ export interface ClientUrlLoaderRecord {
 }
 
 /**
- * The data-only subset of TransitionConfig a clientUrls() route may declare:
- * ViewTransition classes/name plus the boundary opt-out. The `when` gate is a
- * server-executed predicate and stays in the server tree — it cannot cross the
- * "use client" projection boundary.
+ * The TransitionConfig subset a clientUrls() route may declare: ViewTransition
+ * classes/name, the boundary opt-out, and the browser-run `when` gate. The
+ * projection carries only a "has when" marker; the browser calls the function
+ * this module declares (transition-when-ref.ts resolveTransitionWhen).
  */
 export type ClientTransitionConfig = Pick<
   TransitionConfig,
-  "enter" | "exit" | "update" | "share" | "default" | "name" | "viewTransition"
+  | "enter"
+  | "exit"
+  | "update"
+  | "share"
+  | "default"
+  | "name"
+  | "viewTransition"
+  | "when"
 >;
 
 export interface ClientUrlRouteRecord {

package/src/client.tsx

@@ -396,6 +396,8 @@ export { useNonce } from "./browser/react/nonce-context.js";
 export type {
   RouterInstance,
   RouterNavigateOptions,
+  HistoryState,
+  PlainHistoryState,
   ReadonlyURLSearchParams,
   ActionState,
   ActionLifecycleState,

package/src/host/cookie-handler.ts

@@ -1,3 +1,4 @@
+import { requestHeaders } from "../server/request-headers.js";
 import type { HostOverrideConfig } from "./types.js";
 import type { RouterRequestInput } from "../router/router-interfaces.js";
 import { matchPattern, parseRequest } from "./pattern-matcher.js";
@@ -9,7 +10,7 @@ import {
 import { parseCookiesFromHeader } from "../server/cookie-parse.js";
 
 export function parseCookies(request: Request): Record<string, string> {
-  return parseCookiesFromHeader(request.headers.get("cookie"));
+  return parseCookiesFromHeader(requestHeaders(request).get("cookie"));
 }
 
 export function getCookie(request: Request, name: string): string | undefined {

package/src/index.rsc.ts

@@ -72,6 +72,9 @@ export type {
   TransitionConfig,
   TransitionWhenFn,
   TransitionWhenContext,
+  TransitionWhenKind,
+  RouteLocation,
+  ServerRouteLocation,
   ViewTransitionClass,
 } from "./types.js";
 

package/src/index.ts

@@ -94,6 +94,9 @@ export type {
   TransitionConfig,
   TransitionWhenFn,
   TransitionWhenContext,
+  TransitionWhenKind,
+  RouteLocation,
+  ServerRouteLocation,
   ViewTransitionClass,
 } from "./types.js";
 

package/src/loader-redirect.tsx

@@ -1,7 +1,10 @@
 "use client";
 import type { ReactNode } from "react";
 import { useEffect } from "react";
-import type { NavigateOptionsInternal } from "./browser/types.js";
+import type {
+  NavigateOptionsInternal,
+  RouterNavigateOptions,
+} from "./browser/types.js";
 import { useRouter } from "./browser/react/use-router.js";
 import { validateExternalRedirect } from "./browser/validate-redirect-origin.js";
 import { resolveSameOriginRedirect } from "./redirect-origin.js";
@@ -48,8 +51,9 @@ export function LoaderRedirect({
     // so it must not log a "blocked" error on its way to the branch below.
     const sameOrigin = resolveSameOriginRedirect(to, origin);
     if (sameOrigin) {
-      const options: Omit<NavigateOptionsInternal, "replace"> | undefined =
-        state ? { state, _skipCache: true } : undefined;
+      const options:
+        | (RouterNavigateOptions & Pick<NavigateOptionsInternal, "_skipCache">)
+        | undefined = state ? { state, _skipCache: true } : undefined;
       void router.replace(sameOrigin, options);
       return;
     }