@rangojs/router 0.0.0-experimental.14 → 0.0.0-experimental.140

package/src/browser/react/use-navigation.ts

@@ -9,36 +9,10 @@ import {
   useRef,
 } from "react";
 import { NavigationStoreContext } from "./context.js";
-import type { PublicNavigationState, NavigateOptions } from "../types.js";
+import { shallowEqual } from "./shallow-equal.js";
+import type { PublicNavigationState } from "../types.js";
 import type { DerivedNavigationState } from "../event-controller.js";
 
-/**
- * Shallow equality check for selector results
- */
-function shallowEqual<T>(a: T, b: T): boolean {
-  if (Object.is(a, b)) return true;
-  if (
-    typeof a !== "object" ||
-    a === null ||
-    typeof b !== "object" ||
-    b === null
-  ) {
-    return false;
-  }
-  const keysA = Object.keys(a);
-  const keysB = Object.keys(b);
-  if (keysA.length !== keysB.length) return false;
-  for (const key of keysA) {
-    if (
-      !Object.hasOwn(b, key) ||
-      !Object.is((a as any)[key], (b as any)[key])
-    ) {
-      return false;
-    }
-  }
-  return true;
-}
-
 /**
  * Convert derived state to public version (strips inflightActions)
  */
@@ -47,64 +21,61 @@ function toPublicState(state: DerivedNavigationState): PublicNavigationState {
   return publicState;
 }
 
-
-/**
- * Navigation methods returned by useNavigation
- */
-export interface NavigationMethods {
-  navigate: (url: string, options?: NavigateOptions) => Promise<void>;
-  refresh: () => Promise<void>;
-}
-
 /**
- * Full value returned when no selector is provided
- */
-export type NavigationValue = PublicNavigationState & NavigationMethods;
-
-/**
- * Hook to access navigation state with optional selector for performance
+ * Hook to access reactive navigation state with optional selector for performance.
  *
- * Uses the event controller for reactive state management.
- * State is derived from source of truth (currentNavigation, inflightActions).
+ * Returns state only. For actions (push, replace, refresh, prefetch),
+ * use useRouter() instead.
  *
  * @example
  * ```tsx
- * const state = useNavigation(nav => nav.state);
+ * const { state, location } = useNavigation();
  * const isLoading = useNavigation(nav => nav.state === 'loading');
  * ```
  */
-export function useNavigation(): NavigationValue;
+export function useNavigation(): PublicNavigationState;
 export function useNavigation<T>(
   selector: (state: PublicNavigationState) => T,
 ): T;
 export function useNavigation<T>(
   selector?: (state: PublicNavigationState) => T,
-): T | NavigationValue {
+): T | PublicNavigationState {
   const ctx = useContext(NavigationStoreContext);
 
   if (!ctx) {
-    throw new Error(
-      "useNavigation must be used within NavigationStoreContext.Provider"
-    );
+    throw new Error("useNavigation must be used within NavigationProvider");
   }
 
-  // Base state for useOptimistic
   const [baseValue, setBaseValue] = useState<T | PublicNavigationState>(() => {
     const publicState = toPublicState(ctx.eventController.getState());
     return selector ? selector(publicState) : publicState;
   });
   const prevState = useRef(baseValue);
 
-  // useOptimistic allows immediate updates during transitions/actions
+  // Tracks whether the most recent setOptimisticValue call pinned the value
+  // to a non-idle state. Used to decide whether to emit a release update when
+  // returning to idle, so the optimistic store doesn't stay pinned if a
+  // parent transition (e.g. <Link> click) is still pending.
+  const optimisticPinnedRef = useRef(false);
+
   const [value, setOptimisticValue] = useOptimistic(baseValue);
 
+  // Store selector in a ref so the subscription callback always uses the
+  // latest selector without re-subscribing on every render (inline functions
+  // have a new identity each render). This is event-driven by design: the
+  // value updates when the store emits, not when the selector changes.
+  // Between events there is nothing new to select from.
+  const selectorRef = useRef(selector);
+  selectorRef.current = selector;
+
   // Subscribe to event controller state changes (only runs on client)
   useEffect(() => {
-    // Subscribe to updates from event controller
-    return ctx.eventController.subscribe(() => {
+    const update = () => {
       const currentState = ctx.eventController.getState();
       const publicState = toPublicState(currentState);
-      const nextSelected = selector ? selector(publicState) : publicState;
+      const nextSelected = selectorRef.current
+        ? selectorRef.current(publicState)
+        : publicState;
 
       // Check if selected value has changed
       if (!shallowEqual(nextSelected, prevState.current)) {
@@ -114,27 +85,40 @@ export function useNavigation<T>(
         const hasInflightActions =
           ctx.eventController.getInflightActions().size > 0;
 
-        if (hasInflightActions || publicState.state !== "idle") {
-          // Use optimistic update for immediate feedback during transitions
+        const shouldPin = hasInflightActions || publicState.state !== "idle";
+
+        if (shouldPin) {
+          // Pin the optimistic store so the loading value shows immediately
+          // even if a parent transition (e.g. <Link> click) defers the
+          // urgent setBaseValue commit.
           startTransition(() => {
             setOptimisticValue(nextSelected);
           });
+          optimisticPinnedRef.current = true;
+        } else if (optimisticPinnedRef.current) {
+          // Release a previously-pinned optimistic value. Without this,
+          // useOptimistic keeps returning the stale loading value while
+          // any parent transition is still pending, even after baseValue
+          // flipped to idle.
+          startTransition(() => {
+            setOptimisticValue(nextSelected);
+          });
+          optimisticPinnedRef.current = false;
         }
 
         // Always update base state so UI reflects current state
         setBaseValue(nextSelected);
       }
-    });
-  }, [selector]);
-
-  // If no selector, include navigation methods
-  if (!selector) {
-    return {
-      ...(value as PublicNavigationState),
-      navigate: ctx.navigate,
-      refresh: ctx.refresh,
     };
-  }
 
-  return value as T;
+    // Catch-up: re-read state synchronously on mount before subscribing, so a
+    // state change between the seeding render and this effect commit isn't
+    // dropped until the next (debounced) notify. Mirrors usePathname /
+    // useSearchParams.
+    update();
+
+    return ctx.eventController.subscribe(update);
+  }, []);
+
+  return value as T | PublicNavigationState;
 }

package/src/browser/react/use-params.ts

@@ -0,0 +1,75 @@
+"use client";
+
+import { useContext, useState, useEffect, useRef } from "react";
+import { NavigationStoreContext } from "./context.js";
+import { shallowEqual } from "./shallow-equal.js";
+
+const EMPTY_PARAMS: Record<string, string> = Object.freeze({});
+
+/**
+ * Hook to access the current route params.
+ *
+ * Returns the merged route params from the matched route.
+ * Updates when navigation completes, not during pending navigation.
+ *
+ * @example
+ * ```tsx
+ * // Route: /products/:productId
+ * const params = useParams();
+ * // { productId: "123" }
+ *
+ * // Annotate the expected shape via a generic
+ * const { productId } = useParams<{ productId: string }>();
+ *
+ * // With selector
+ * const productId = useParams(p => p.productId);
+ * ```
+ */
+// `T extends object` (not `Record<string, string | undefined>`) so that
+// interface shapes pass the constraint — interfaces lack an implicit
+// index signature and would otherwise be rejected. The generic is a
+// shape annotation, not a runtime check; the body always returns the
+// underlying params map unchanged. The default and selector input use
+// `string | undefined` because absent optional params are omitted from
+// the params record at runtime — the type must reflect that so callers
+// don't write `p.locale.length` and crash when the segment is absent.
+export function useParams<
+  T extends object = Record<string, string | undefined>,
+>(): Readonly<T>;
+export function useParams<T>(
+  selector: (params: Record<string, string | undefined>) => T,
+): T;
+export function useParams<T>(
+  selector?: (params: Record<string, string | undefined>) => T,
+): T | Record<string, string | undefined> {
+  const ctx = useContext(NavigationStoreContext);
+
+  const [value, setValue] = useState<T | Record<string, string>>(() => {
+    const params = ctx ? ctx.eventController.getParams() : EMPTY_PARAMS;
+    return selector ? selector(params) : params;
+  });
+
+  const prevValue = useRef(value);
+  const selectorRef = useRef(selector);
+  selectorRef.current = selector;
+
+  useEffect(() => {
+    if (!ctx) return;
+
+    const update = () => {
+      const params = ctx.eventController.getParams();
+      const next = selectorRef.current ? selectorRef.current(params) : params;
+
+      if (!shallowEqual(next, prevValue.current)) {
+        prevValue.current = next;
+        setValue(next);
+      }
+    };
+
+    update();
+
+    return ctx.eventController.subscribe(update);
+  }, []);
+
+  return value;
+}

package/src/browser/react/use-pathname.ts

@@ -0,0 +1,47 @@
+"use client";
+
+import { useContext, useState, useEffect, useRef } from "react";
+import { NavigationStoreContext } from "./context.js";
+
+/**
+ * Hook to access the current pathname.
+ *
+ * Returns the committed pathname string (excludes search params and hash).
+ * Updates when navigation completes, not during pending navigation.
+ *
+ * @example
+ * ```tsx
+ * const pathname = usePathname();
+ * // "/products/123"
+ * ```
+ */
+export function usePathname(): string {
+  const ctx = useContext(NavigationStoreContext);
+
+  const [pathname, setPathname] = useState<string>(() => {
+    if (!ctx) {
+      return "/";
+    }
+    return (ctx.eventController.getState().location as URL).pathname;
+  });
+
+  const prevPathname = useRef(pathname);
+
+  useEffect(() => {
+    if (!ctx) return;
+
+    const update = () => {
+      const next = (ctx.eventController.getState().location as URL).pathname;
+      if (next !== prevPathname.current) {
+        prevPathname.current = next;
+        setPathname(next);
+      }
+    };
+
+    update();
+
+    return ctx.eventController.subscribe(update);
+  }, []);
+
+  return pathname;
+}

package/src/browser/react/use-reverse.ts

@@ -0,0 +1,106 @@
+"use client";
+
+import { useCallback } from "react";
+import type { LocalReverseFunction } from "../../reverse.js";
+import { substitutePatternParams } from "../../router/substitute-pattern-params.js";
+import { serializeSearchParams } from "../../search-params.js";
+import { useMount } from "./use-mount.js";
+import { useParams } from "./use-params.js";
+
+type RouteEntry = string | { readonly path: string };
+type LocalRouteMap = Readonly<Record<string, RouteEntry>>;
+
+function getPattern(entry: RouteEntry | undefined): string | undefined {
+  if (entry === undefined) return undefined;
+  return typeof entry === "string" ? entry : entry.path;
+}
+
+/**
+ * Join an include mount prefix with a mount-relative pattern.
+ *
+ * `pattern === "/"` is the index of the local module — under a non-root
+ * mount it must collapse so `/` under `/blog` becomes `/blog`, not
+ * `/blog/`. This matches `ctx.reverse(".index")` on the server.
+ */
+function joinMount(mount: string, pattern: string): string {
+  if (pattern === "/") {
+    if (mount === "" || mount === "/") return "/";
+    return mount.endsWith("/") ? mount.slice(0, -1) : mount;
+  }
+  const normalizedMount = mount === "/" ? "" : mount.replace(/\/+$/, "");
+  return normalizedMount + pattern;
+}
+
+/**
+ * Mount-aware reverse function for a locally-imported `routes` map.
+ *
+ * The `routes` map you pass IS the scope: `reverse("name")` looks the name up
+ * in that map (verbatim), prefixes the result with the surrounding `include()`
+ * mount path via `useMount()`, and substitutes params — auto-filling from the
+ * current matched route's params, with explicit params overriding. A module's
+ * components can therefore reverse their own routes without knowing where the
+ * module is mounted: include it under any prefix and the URLs resolve correctly.
+ *
+ * The leading dot is optional and cosmetic: `reverse("post")` and
+ * `reverse(".post")` resolve identically. The dot exists only as a readability
+ * convention and for parity with `ctx.reverse(".name")` on the server; here the
+ * passed map is the scope, so there is no separate global namespace to
+ * disambiguate and the dot carries no meaning.
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { Link, useReverse } from "@rangojs/router/client";
+ * import { routes as blogRoutes } from "../urls/blog.gen.js";
+ *
+ * function BlogNav() {
+ *   const reverse = useReverse(blogRoutes);
+ *   return (
+ *     <>
+ *       <Link to={reverse("index")}>Blog</Link>
+ *       <Link to={reverse("post", { postId: "hello" })}>Post</Link>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function useReverse<const TRoutes extends LocalRouteMap>(
+  routes: TRoutes,
+): LocalReverseFunction<TRoutes> {
+  const mount = useMount();
+  const currentParams = useParams();
+
+  return useCallback(
+    ((
+      name: string,
+      explicitParams?: Record<string, string | undefined>,
+      search?: Record<string, unknown>,
+    ): string => {
+      // The leading dot is optional. The passed map IS the scope, so a dot to
+      // signal "local" is unnecessary — "detail" and ".detail" resolve the same.
+      // A dot is accepted (and stripped) for readability / ctx.reverse parity.
+      const lookupName = name.startsWith(".") ? name.slice(1) : name;
+      const entry = (routes as LocalRouteMap)[lookupName];
+      const pattern = getPattern(entry);
+      if (pattern === undefined) {
+        throw new Error(`Unknown route: "${name}"`);
+      }
+
+      const joined = joinMount(mount, pattern);
+
+      const mergedParams = explicitParams
+        ? { ...currentParams, ...explicitParams }
+        : currentParams;
+
+      const substituted = substitutePatternParams(joined, mergedParams, name);
+
+      if (search) {
+        const qs = serializeSearchParams(search);
+        if (qs) return `${substituted}?${qs}`;
+      }
+
+      return substituted;
+    }) as LocalReverseFunction<TRoutes>,
+    [routes, mount, currentParams],
+  );
+}

package/src/browser/react/use-router.ts

@@ -0,0 +1,98 @@
+"use client";
+
+import { useContext, useMemo } from "react";
+import { NavigationStoreContext } from "./context.js";
+import { prefetchDirect } from "../prefetch/fetch.js";
+import { getAppVersion } from "../app-version.js";
+import type { RouterInstance, RouterNavigateOptions } from "../types.js";
+
+/**
+ * Hook to access router actions (push, replace, refresh, prefetch, back, forward).
+ *
+ * Returns a STABLE reference that never changes, so components using
+ * useRouter() do not re-render on navigation state changes.
+ * For reactive navigation state, use useNavigation() instead.
+ *
+ * Methods read `basename` from the context on each call. It is set once from
+ * the initial payload and is stable within a session — a cross-app navigation
+ * is a full document load (X-RSC-Reload), so the target app mounts fresh with
+ * its own basename.
+ *
+ * @example
+ * ```tsx
+ * const router = useRouter();
+ * router.push("/products");
+ * router.replace("/login", { scroll: false });
+ * router.prefetch("/dashboard");
+ * router.back();
+ * ```
+ */
+export function useRouter(): RouterInstance {
+  const ctx = useContext(NavigationStoreContext);
+
+  if (!ctx) {
+    throw new Error("useRouter must be used within NavigationProvider");
+  }
+
+  // Stable reference: ctx itself is stable, and reads on each method call
+  // pick up live basename values from the context (backed by a live ref
+  // in NavigationProvider), so app-switch transitions are reflected without
+  // recreating this object.
+  return useMemo<RouterInstance>(() => {
+    /** Prefix a root-relative path with basename if not already prefixed. */
+    function withBasename(url: string): string {
+      const bn = ctx!.basename;
+      if (!bn || !url.startsWith("/") || url.startsWith(bn + "/") || url === bn)
+        return url;
+      return url === "/" ? bn : bn + url;
+    }
+
+    return {
+      push(url: string, options?: RouterNavigateOptions): Promise<void> {
+        return ctx.navigate(withBasename(url), { ...options, replace: false });
+      },
+
+      replace(url: string, options?: RouterNavigateOptions): Promise<void> {
+        return ctx.navigate(withBasename(url), { ...options, replace: true });
+      },
+
+      refresh(): Promise<void> {
+        return ctx.refresh();
+      },
+
+      prefetch(url: string, options?: { key?: ":source" }): void {
+        const segmentState = ctx.store?.getSegmentState();
+        if (segmentState) {
+          prefetchDirect(
+            withBasename(url),
+            segmentState.currentSegmentIds,
+            getAppVersion(),
+            ctx.store?.getRouterId?.(),
+            options?.key,
+          );
+        }
+      },
+
+      back(): void {
+        // Avoid escaping the host on the first entry of this session.
+        // Prefer the Navigation API; fall back to the router-stamped
+        // history.state.idx (set by pushHistoryWithIdx) for older browsers.
+        const nav = (window as { navigation?: { canGoBack: boolean } })
+          .navigation;
+        const canGoBack =
+          nav && typeof nav.canGoBack === "boolean"
+            ? nav.canGoBack
+            : ((window.history.state as { idx?: number } | null)?.idx ?? 0) > 0;
+        if (canGoBack) {
+          window.history.back();
+        } else {
+          ctx.navigate(withBasename("/"), { replace: true });
+        }
+      },
+
+      forward(): void {
+        window.history.forward();
+      },
+    };
+  }, []);
+}

package/src/browser/react/use-search-params.ts

@@ -0,0 +1,51 @@
+"use client";
+
+import { useContext, useState, useEffect, useRef } from "react";
+import { NavigationStoreContext } from "./context.js";
+import type { ReadonlyURLSearchParams } from "../types.js";
+
+/**
+ * Hook to access the current URL search params.
+ *
+ * Returns a read-only URLSearchParams object from the committed location.
+ * Updates when navigation completes, not during pending navigation.
+ *
+ * Note: During SSR the search params are not available (the server only sends
+ * the pathname). The hook returns empty params during SSR and syncs from
+ * the browser URL on mount.
+ *
+ * @example
+ * ```tsx
+ * const searchParams = useSearchParams();
+ * const query = searchParams.get("q"); // "react"
+ * const page = searchParams.get("page"); // "2"
+ * ```
+ */
+export function useSearchParams(): ReadonlyURLSearchParams {
+  const ctx = useContext(NavigationStoreContext);
+
+  const [searchParams, setSearchParams] = useState<ReadonlyURLSearchParams>(
+    () => new URLSearchParams(),
+  );
+
+  const prevSearch = useRef("");
+
+  useEffect(() => {
+    if (!ctx) return;
+
+    const update = () => {
+      const location = ctx.eventController.getState().location as URL;
+      const nextSearch = location.searchParams.toString();
+      if (nextSearch !== prevSearch.current) {
+        prevSearch.current = nextSearch;
+        setSearchParams(new URLSearchParams(nextSearch));
+      }
+    };
+
+    update();
+
+    return ctx.eventController.subscribe(update);
+  }, []);
+
+  return searchParams;
+}