@rangojs/router 0.33.1 → 0.34.0

package/src/types/loader-types.ts

@@ -11,6 +11,7 @@ import type {
   DefaultVars,
 } from "./global-namespace.js";
 import type { RequestScope } from "./request-scope.js";
+import type { PrefetchOption } from "../prefetch-markers.js";
 
 /**
  * Context passed to loader functions during execution
@@ -207,13 +208,14 @@ export type LoaderFn<
 export type LoaderOptions = {
   ssr?: boolean;
   /**
-   * `prefetch: false` keeps this loader out of speculative prefetches. A
-   * viewport or render `<Link>` prefetch (a partial request with
-   * `X-Rango-Prefetch: 1`) does not execute it; the payload marks it
-   * deferred. A hover prefetch and `useRouter().prefetch()`
-   * (`X-Rango-Prefetch: intent`) count as intent to click and run it, so a
-   * click after a hover needs no follow-up request. A document request and a
-   * navigation with no prefetch to adopt run it as usual.
+   * `prefetch: false` keeps this loader out of every `<Link>` prefetch: a
+   * prefetch (a partial request with `X-Rango-Prefetch`) does not execute
+   * it; the payload marks it deferred. `prefetch: "intent"` keeps it out of
+   * speculative prefetches only: a viewport or render prefetch
+   * (`X-Rango-Prefetch: 1`) defers it, and a hover prefetch or
+   * `useRouter().prefetch()` (`X-Rango-Prefetch: intent`) runs it, so a click
+   * after a hover needs no follow-up request for it. A document request and
+   * a navigation with no prefetch to adopt run it as usual.
    *
    * A deferred loader never blocks the navigation that adopts the prefetch:
    * it behaves like a loader that is still streaming. Its own `<Suspense>`
@@ -238,7 +240,7 @@ export type LoaderOptions = {
    * request only deferred work and middleware run, so values a held handler
    * would have set with `ctx.set()` are not visible.
    */
-  prefetch?: boolean;
+  prefetch?: PrefetchOption;
 };
 
 /**

package/src/urls/path-helper-types.ts

@@ -58,6 +58,7 @@ import type {
 } from "./pattern-types.js";
 import type { ExtractRoutes, ExtractResponses } from "./type-extraction.js";
 import type { ClientUrlPatterns } from "../client-urls/types.js";
+import type { PrefetchOption } from "../prefetch-markers.js";
 
 /**
  * Base path function signature for defining routes with URL patterns.
@@ -364,10 +365,10 @@ export type PathHelpers<TEnv> = {
    * freezes into the shell (nested promises stay live holes) — the pre-flush
    * promise applied to the prelude.
    *
-   * Pass `{ prefetch: false }` to keep the loader out of speculative
-   * prefetches (viewport, render): such a prefetch skips it and the click
-   * that adopts it fetches it in one follow-up request; a hover prefetch runs
-   * it (see {@link LoaderOptions}). Only on a segment the
+   * Pass `{ prefetch: false }` to keep the loader out of prefetches: a
+   * prefetch skips it and the click that adopts it fetches it in one
+   * follow-up request. `{ prefetch: "intent" }` defers it in viewport and
+   * render prefetches only (see {@link LoaderOptions}). Only on a segment the
    * client does not have yet: a loader the client already holds runs in the
    * prefetch when it revalidates.
    */
@@ -381,9 +382,9 @@ export type PathHelpers<TEnv> = {
    * Attach a loading component to the current route/layout.
    *
    * `{ ssr: false }` skips the fallback on document requests. `{ prefetch:
-   * false }` keeps what the fallback covers out of viewport and render
-   * prefetches (a hover prefetch runs it), when this entry's segment is new
-   * to the client: the entry's handler, its loaders,
+   * false }` keeps what the fallback covers out of prefetches (`"intent"`:
+   * viewport and render prefetches only, see {@link LoaderOptions}), when this
+   * entry's segment is new to the client: the entry's handler, its loaders,
    * its orphan layouts and parallel slots and, for a layout, every deeper
    * entry. The click that adopts the prefetch shows the fallback and fetches
    * them in one follow-up request, which reads cache() and "use cache" as
@@ -397,7 +398,7 @@ export type PathHelpers<TEnv> = {
    */
   loading: (
     component: ReactNode | (() => ReactNode),
-    options?: { ssr?: boolean; prefetch?: boolean },
+    options?: { ssr?: boolean; prefetch?: PrefetchOption },
   ) => LoadingItem;
 
   /**

package/src/use-loader.tsx

@@ -270,10 +270,15 @@ function useLoaderInternal<T>(
   const loaders: LoaderStore | undefined = useContext(NavigationStoreContext)
     ?.store?.loaders;
 
+  // Committed route data (updated by the reset effect below), read by the
+  // store when a refresh begins: the snapshot it produces belongs to it.
+  const prevContextDataRef = useRef(contextData);
+  const routeDataOf = useCallback(() => prevContextDataRef.current, []);
+
   const groupRefetch = useCallback(async (): Promise<void> => {
     if (!loaderId || !loaders) return;
     const requestId = loaders.reserveRequestId(bucketKey);
-    loaders.beginRequest(bucketKey, requestId);
+    loaders.beginRequest(bucketKey, requestId, routeDataOf);
     try {
       const url = new URL(window.location.href);
       url.searchParams.set("_rsc_loader", loaderId);
@@ -316,6 +321,15 @@ function useLoaderInternal<T>(
     sharedState.bucketKey === bucketKey
       ? sharedState.snapshot
       : EMPTY_LOADER_SNAPSHOT;
+  // A route reader shows a refresh only when it was requested for this
+  // reader's route data: never another page's, nor one a navigation replaced
+  // (the rule the reset effect below applies when a mounted reader's data
+  // changes, here also for a reader that mounts).
+  const sharedValue =
+    sharedSnapshot.hasValue &&
+    (!hasContextData || sharedSnapshot.valueFor.has(contextData));
+  const sharedRequest =
+    !hasContextData || sharedSnapshot.requestFor.has(contextData);
   useEffect(() => {
     if (!loaders) return;
     const initial = loaders.getSnapshot(bucketKey);
@@ -343,6 +357,7 @@ function useLoaderInternal<T>(
         onStreamPending: hasContextData
           ? () => startTransition(() => setStreamPending(true))
           : undefined,
+        routeData: hasContextData ? routeDataOf : undefined,
       },
     );
     // eslint-disable-next-line react-hooks/exhaustive-deps -- intentional:
@@ -388,7 +403,6 @@ function useLoaderInternal<T>(
   // any pre-navigation load() promise that resolves later fails its gate
   // and is dropped — fixes the race where a stale fetch overwrites the
   // new route's context.
-  const prevContextDataRef = useRef(contextData);
   useEffect(() => {
     if (prevContextDataRef.current !== contextData) {
       setLocalFetchedData({ has: false, value: undefined });
@@ -407,11 +421,14 @@ function useLoaderInternal<T>(
   // `has`/`hasValue` gate each level so a committed falsy value is not skipped.
   const data = localFetchedData.has
     ? localFetchedData.value
-    : sharedSnapshot.hasValue
+    : sharedValue
       ? (sharedSnapshot.value as T | undefined)
       : contextData;
-  const isLoading = localIsLoading || sharedSnapshot.isLoading || streamPending;
-  const error = localError ?? sharedSnapshot.error;
+  const isLoading =
+    localIsLoading ||
+    (sharedRequest && sharedSnapshot.isLoading) ||
+    streamPending;
+  const error = localError ?? (sharedRequest ? sharedSnapshot.error : null);
 
   const throwOnError = options?.throwOnError ?? true;
 
@@ -446,7 +463,11 @@ function useLoaderInternal<T>(
       if (shared) {
         sharedRequestId = loaders.reserveRequestId(bucket);
         lastSharedRequestIdRef.current = sharedRequestId;
-        loaders.beginRequest(bucket, sharedRequestId);
+        loaders.beginRequest(
+          bucket,
+          sharedRequestId,
+          hasContextDataRef.current ? routeDataOf : undefined,
+        );
       } else {
         localRequestId = ++localRequestIdRef.current;
         setLocalIsLoading(true);
@@ -559,12 +580,13 @@ function useLoaderInternal<T>(
         }
       }
     },
-    [throwOnError, loaders],
+    [throwOnError, loaders, routeDataOf],
   );
 
   if (throwOnError) {
     if (localError) throw localError;
     if (
+      sharedRequest &&
       sharedSnapshot.error &&
       lastSharedRequestIdRef.current !== null &&
       sharedSnapshot.requestId === lastSharedRequestIdRef.current