@rangojs/router 0.0.0-experimental.0f44aca1

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

@@ -0,0 +1,162 @@
+"use client";
+
+import {
+  useContext,
+  useState,
+  useEffect,
+  useRef,
+  useOptimistic,
+  startTransition,
+} from "react";
+import type { Handle } from "../../handle.js";
+import { getCollectFn } from "../../handle.js";
+import type { HandleData } from "../types.js";
+import { NavigationStoreContext } from "./context.js";
+import { shallowEqual } from "./shallow-equal.js";
+
+/**
+ * Resolve the collect function for a handle.
+ * Handle objects are plain { __brand, $$id } - collect is stored in the registry
+ * (populated when createHandle runs on the client).
+ */
+function resolveCollect<T, A>(handle: Handle<T, A>): (segments: T[][]) => A {
+  // Look up collect from the registry (populated when the handle module is imported).
+  const registered = getCollectFn(handle.$$id);
+  if (registered) {
+    return registered as (segments: T[][]) => A;
+  }
+
+  // Fall back to default flat collect with a dev warning.
+  if (process.env.NODE_ENV !== "production") {
+    console.warn(
+      `[rsc-router] Handle "${handle.$$id}" was passed as a prop but its collect ` +
+        `function could not be resolved. Falling back to flat array. ` +
+        `Import the handle module in a client component to register its collect function.`,
+    );
+  }
+  return ((segments: unknown[][]) => segments.flat()) as unknown as (
+    segments: T[][],
+  ) => A;
+}
+
+/**
+ * Collect handle data from segments and transform to final value.
+ */
+function collectHandle<T, A>(
+  handle: Handle<T, A>,
+  data: HandleData,
+  segmentOrder: string[],
+): A {
+  const collect = resolveCollect(handle);
+  const segmentData = data[handle.$$id];
+
+  if (!segmentData) {
+    return collect([]);
+  }
+
+  // Build array of segment arrays in parent -> child order
+  const segmentArrays: T[][] = [];
+  for (const segmentId of segmentOrder) {
+    const entries = segmentData[segmentId];
+    if (entries && entries.length > 0) {
+      segmentArrays.push(entries as T[]);
+    }
+  }
+
+  // Call collect once with all segment data
+  return collect(segmentArrays);
+}
+
+/**
+ * Hook to access collected handle data.
+ *
+ * Returns the collected value from all route segments that pushed to this handle.
+ * Re-renders when handle data changes (navigation, actions).
+ *
+ * @param handle - The handle to read
+ * @param selector - Optional selector for performance (only re-render when selected value changes)
+ *
+ * @example
+ * ```tsx
+ * // Get all breadcrumbs
+ * const breadcrumbs = useHandle(Breadcrumbs);
+ *
+ * // With selector - only re-render when last crumb changes
+ * const lastCrumb = useHandle(Breadcrumbs, (data) => data.at(-1));
+ * ```
+ */
+export function useHandle<T, A>(handle: Handle<T, A>): A;
+export function useHandle<T, A, S>(
+  handle: Handle<T, A>,
+  selector: (data: A) => S,
+): S;
+export function useHandle<T, A, S>(
+  handle: Handle<T, A>,
+  selector?: (data: A) => S,
+): A | S {
+  const ctx = useContext(NavigationStoreContext);
+
+  // Initial state from context event controller, or empty fallback without provider.
+  const [value, setValue] = useState<A | S>(() => {
+    if (!ctx) {
+      const collected = collectHandle(handle, {}, []);
+      return selector ? selector(collected) : collected;
+    }
+
+    // On client, use event controller state
+    const state = ctx.eventController.getHandleState();
+    const collected = collectHandle(handle, state.data, state.segmentOrder);
+    return selector ? selector(collected) : collected;
+  });
+  const [optimisticValue, setOptimisticValue] = useOptimistic(value);
+
+  // Track previous value for shallow comparison
+  const prevValueRef = useRef(value);
+  prevValueRef.current = value;
+
+  // Ref keeps the latest selector without re-subscribing on every render.
+  const selectorRef = useRef(selector);
+  selectorRef.current = selector;
+
+  // Subscribe to handle data changes (client only)
+  useEffect(() => {
+    if (!ctx) return;
+
+    // Sync current state for the (possibly new) handle so that switching
+    // handles on an idle page doesn't leave stale data from the old handle.
+    const currentHandleState = ctx.eventController.getHandleState();
+    const currentCollected = collectHandle(
+      handle,
+      currentHandleState.data,
+      currentHandleState.segmentOrder,
+    );
+    const currentValue = selectorRef.current
+      ? selectorRef.current(currentCollected)
+      : currentCollected;
+    if (!shallowEqual(currentValue, prevValueRef.current)) {
+      prevValueRef.current = currentValue;
+      setValue(currentValue);
+    }
+
+    return ctx.eventController.subscribeToHandles(() => {
+      const state = ctx.eventController.getHandleState();
+      const isAction =
+        ctx.eventController.getState().inflightActions.length > 0;
+      const collected = collectHandle(handle, state.data, state.segmentOrder);
+      const nextValue = selectorRef.current
+        ? selectorRef.current(collected)
+        : collected;
+
+      if (!shallowEqual(nextValue, prevValueRef.current)) {
+        prevValueRef.current = nextValue;
+        startTransition(() => {
+          // Skip optimistic update during actions to prevent Suspense fallback
+          if (!isAction) setOptimisticValue(nextValue);
+          setValue(nextValue);
+        });
+      }
+    });
+  }, [handle]);
+
+  return optimisticValue;
+}

package/src/browser/react/use-href.tsx

@@ -0,0 +1,40 @@
+"use client";
+
+import { href, type ValidPaths } from "../../href-client.js";
+import { useMount } from "./use-mount.js";
+
+/**
+ * Client-side hook for mount-aware URL resolution.
+ *
+ * Returns an href function that automatically prepends the current
+ * include() mount prefix. Inside an include("/shop", ...) scope,
+ * the returned function resolves local paths relative to /shop.
+ *
+ * For absolute paths (outside the current mount), use the bare
+ * href() function directly instead.
+ *
+ * @returns A function that prepends the mount prefix to paths
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { useHref, href } from "@rangojs/router/client";
+ *
+ * // Inside include("/shop", shopPatterns)
+ * function ShopNav() {
+ *   const href = useHref();
+ *
+ *   return (
+ *     <>
+ *       {// Local paths - auto-prefixed with /shop}
+ *       <Link to={href("/cart")}>Cart</Link>
+ *       <Link to={href("/product/widget")}>Widget</Link>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function useHref(): (path: `/${string}`) => string {
+  const mount = useMount();
+  return (path: `/${string}`) => href(path as ValidPaths, mount);
+}

package/src/browser/react/use-link-status.ts

@@ -0,0 +1,135 @@
+"use client";
+
+import {
+  createContext,
+  useContext,
+  useState,
+  useEffect,
+  useRef,
+  useOptimistic,
+  startTransition,
+  type Context,
+} from "react";
+import { NavigationStoreContext } from "./context.js";
+
+/**
+ * Context for Link component to provide its destination URL
+ * Used by useLinkStatus to determine if this specific link is pending
+ */
+export const LinkContext: Context<string | null> = createContext<string | null>(
+  null,
+);
+
+/**
+ * Link status returned by useLinkStatus hook
+ */
+export interface LinkStatus {
+  /** Whether navigation to this link's destination is in progress */
+  pending: boolean;
+}
+
+/**
+ * Normalize URL for comparison
+ * Handles relative URLs and ensures consistent format
+ */
+function normalizeUrl(url: string, origin: string): string {
+  try {
+    const parsed = new URL(url, origin);
+    // Return pathname + search + hash for comparison
+    return parsed.pathname + parsed.search + parsed.hash;
+  } catch {
+    return url;
+  }
+}
+
+/**
+ * Check if this link's destination matches the pending navigation URL
+ */
+function isPendingFor(
+  linkTo: string | null,
+  pendingUrl: string | null,
+  origin: string,
+): boolean {
+  if (linkTo === null || pendingUrl === null) {
+    return false;
+  }
+  return normalizeUrl(pendingUrl, origin) === normalizeUrl(linkTo, origin);
+}
+
+/**
+ * Hook to track the pending state of a Link component
+ *
+ * Must be used inside a Link component. Returns `{ pending: true }`
+ * when navigation to this link's destination is in progress.
+ *
+ * Useful for showing inline loading indicators on individual links.
+ *
+ * @example
+ * ```tsx
+ * function LoadingIndicator() {
+ *   const { pending } = useLinkStatus();
+ *   return pending ? <Spinner /> : null;
+ * }
+ *
+ * // In your component:
+ * <Link to="/dashboard">
+ *   Dashboard
+ *   <LoadingIndicator />
+ * </Link>
+ * ```
+ */
+export function useLinkStatus(): LinkStatus {
+  const linkTo = useContext(LinkContext);
+  const ctx = useContext(NavigationStoreContext);
+
+  // Get origin for URL normalization (stable across renders)
+  const origin =
+    typeof window !== "undefined" ? window.location.origin : "http://localhost";
+
+  // Base state for useOptimistic
+  const [basePending, setBasePending] = useState<boolean>(() => {
+    if (!ctx || linkTo === null) {
+      return false;
+    }
+    const state = ctx.eventController.getState();
+    return isPendingFor(linkTo, state.pendingUrl, origin);
+  });
+
+  const prevPending = useRef(basePending);
+
+  // useOptimistic allows immediate updates during transitions
+  const [pending, setOptimisticPending] = useOptimistic(basePending);
+
+  useEffect(() => {
+    if (!ctx || linkTo === null) {
+      return;
+    }
+
+    // Subscribe to navigation state changes
+    return ctx.eventController.subscribe(() => {
+      const state = ctx.eventController.getState();
+      const isPending = isPendingFor(linkTo, state.pendingUrl, origin);
+
+      if (isPending !== prevPending.current) {
+        prevPending.current = isPending;
+
+        // Use optimistic update for immediate feedback during navigation
+        if (state.state !== "idle") {
+          startTransition(() => {
+            setOptimisticPending(isPending);
+          });
+        }
+
+        // Always update base state
+        setBasePending(isPending);
+      }
+    });
+  }, [linkTo, origin]);
+
+  // If not inside a Link, return not pending
+  if (linkTo === null) {
+    return { pending: false };
+  }
+
+  return { pending };
+}

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

@@ -0,0 +1,31 @@
+"use client";
+
+import { useContext } from "react";
+import { MountContext } from "./mount-context.js";
+
+/**
+ * Returns the current include() mount path.
+ *
+ * Inside `include("/articles", blogPatterns)`, returns "/articles".
+ * For nested includes, returns the nearest mount path.
+ * At root level (no include), returns "/".
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { useMount, href } from "@rangojs/router/client";
+ *
+ * function BlogNav({ slug }: { slug: string }) {
+ *   const mount = useMount(); // "/articles"
+ *   return (
+ *     <>
+ *       <Link to={href("/", mount)}>Blog Home</Link>
+ *       <Link to={href(`/${slug}`, mount)}>Post</Link>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function useMount(): string {
+  return useContext(MountContext);
+}

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

@@ -0,0 +1,99 @@
+"use client";
+
+import {
+  useContext,
+  useState,
+  useEffect,
+  useOptimistic,
+  startTransition,
+  useRef,
+} from "react";
+import { NavigationStoreContext } from "./context.js";
+import { shallowEqual } from "./shallow-equal.js";
+import type { PublicNavigationState } from "../types.js";
+import type { DerivedNavigationState } from "../event-controller.js";
+
+/**
+ * Convert derived state to public version (strips inflightActions)
+ */
+function toPublicState(state: DerivedNavigationState): PublicNavigationState {
+  const { inflightActions: _, ...publicState } = state;
+  return publicState;
+}
+
+/**
+ * Hook to access reactive navigation state with optional selector for performance.
+ *
+ * Returns state only. For actions (push, replace, refresh, prefetch),
+ * use useRouter() instead.
+ *
+ * @example
+ * ```tsx
+ * const { state, location } = useNavigation();
+ * const isLoading = useNavigation(nav => nav.state === 'loading');
+ * ```
+ */
+export function useNavigation(): PublicNavigationState;
+export function useNavigation<T>(
+  selector: (state: PublicNavigationState) => T,
+): T;
+export function useNavigation<T>(
+  selector?: (state: PublicNavigationState) => T,
+): T | PublicNavigationState {
+  const ctx = useContext(NavigationStoreContext);
+
+  if (!ctx) {
+    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
+  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 currentState = ctx.eventController.getState();
+      const publicState = toPublicState(currentState);
+      const nextSelected = selectorRef.current
+        ? selectorRef.current(publicState)
+        : publicState;
+
+      // Check if selected value has changed
+      if (!shallowEqual(nextSelected, prevState.current)) {
+        prevState.current = nextSelected;
+
+        // Check if any actions are in progress for optimistic updates
+        const hasInflightActions =
+          ctx.eventController.getInflightActions().size > 0;
+
+        if (hasInflightActions || publicState.state !== "idle") {
+          // Use optimistic update for immediate feedback during transitions
+          startTransition(() => {
+            setOptimisticValue(nextSelected);
+          });
+        }
+
+        // Always update base state so UI reflects current state
+        setBaseValue(nextSelected);
+      }
+    });
+  }, []);
+
+  return value as T | PublicNavigationState;
+}

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

@@ -0,0 +1,65 @@
+"use client";
+
+import { useContext, useState, useEffect, useRef } from "react";
+import { NavigationStoreContext } from "./context.js";
+import { shallowEqual } from "./shallow-equal.js";
+
+/**
+ * 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" }
+ *
+ * // With selector
+ * const productId = useParams(p => p.productId);
+ * ```
+ */
+export function useParams(): Record<string, string>;
+export function useParams<T>(
+  selector: (params: Record<string, string>) => T,
+): T;
+export function useParams<T>(
+  selector?: (params: Record<string, string>) => T,
+): T | Record<string, string> {
+  const ctx = useContext(NavigationStoreContext);
+
+  const [value, setValue] = useState<T | Record<string, string>>(() => {
+    if (!ctx) {
+      return selector ? selector({}) : {};
+    }
+    const params = ctx.eventController.getParams();
+    return selector ? selector(params) : params;
+  });
+
+  const prevValue = useRef(value);
+  // Ref keeps the latest selector without re-subscribing. Event-driven by
+  // design: value updates on store events, not on selector identity change.
+  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-router.ts

@@ -0,0 +1,63 @@
+"use client";
+
+import { useContext, useMemo } from "react";
+import { NavigationStoreContext } from "./context.js";
+import { prefetchDirect } from "../prefetch/fetch.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.
+ *
+ * @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 is itself stable (NavigationProvider memoizes with [])
+  return useMemo<RouterInstance>(
+    () => ({
+      push(url: string, options?: RouterNavigateOptions): Promise<void> {
+        return ctx.navigate(url, { ...options, replace: false });
+      },
+
+      replace(url: string, options?: RouterNavigateOptions): Promise<void> {
+        return ctx.navigate(url, { ...options, replace: true });
+      },
+
+      refresh(): Promise<void> {
+        return ctx.refresh();
+      },
+
+      prefetch(url: string): void {
+        const segmentState = ctx.store?.getSegmentState();
+        if (segmentState) {
+          prefetchDirect(url, segmentState.currentSegmentIds, ctx.version);
+        }
+      },
+
+      back(): void {
+        window.history.back();
+      },
+
+      forward(): void {
+        window.history.forward();
+      },
+    }),
+    [],
+  );
+}

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

@@ -0,0 +1,56 @@
+"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);
+
+  // Always initialize with empty URLSearchParams to match SSR output
+  // and avoid hydration mismatch. The useEffect below syncs from
+  // the real URL after hydration.
+  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;
+        // Create a snapshot so callers cannot mutate the source URLSearchParams
+        setSearchParams(new URLSearchParams(nextSearch));
+      }
+    };
+
+    // Sync on mount (picks up search params from browser URL)
+    update();
+
+    return ctx.eventController.subscribe(update);
+  }, []);
+
+  return searchParams;
+}