@rangojs/router 0.0.0-experimental.10

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

@@ -0,0 +1,203 @@
+"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";
+
+/**
+ * SSR module-level state.
+ * Populated by initHandleDataSync before React renders.
+ * Used by useState initializer during SSR.
+ */
+let ssrHandleData: HandleData = {};
+let ssrSegmentOrder: string[] = [];
+
+/**
+ * Filter segment IDs to only include routes and layouts.
+ * Excludes parallels (contain .@) and loaders (contain D followed by digit).
+ */
+function filterSegmentOrder(matched: string[]): string[] {
+  return matched.filter((id) => {
+    if (id.includes(".@")) return false;
+    if (/D\d+\./.test(id)) return false;
+    return true;
+  });
+}
+
+/**
+ * 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);
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Initialize handle data synchronously for SSR.
+ * Called before rendering to populate state for useState initializer.
+ *
+ * @param data - Handle data from RSC payload
+ * @param matched - Segment order for reduction
+ */
+export function initHandleDataSync(data: HandleData, matched?: string[]): void {
+  ssrHandleData = data;
+  ssrSegmentOrder = filterSegmentOrder(matched ?? []);
+}
+
+/**
+ * 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 SSR module state or event controller
+  const [value, setValue] = useState<A | S>(() => {
+    // During SSR, use module-level state
+    if (typeof document === "undefined" || !ctx) {
+      const collected = collectHandle(handle, ssrHandleData, ssrSegmentOrder);
+      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;
+
+  // Memoize selector ref
+  const selectorRef = useRef(selector);
+  selectorRef.current = selector;
+
+  // Subscribe to handle data changes (client only)
+  useEffect(() => {
+    if (!ctx) return;
+
+    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,134 @@
+"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,140 @@
+"use client";
+
+import {
+  useContext,
+  useState,
+  useEffect,
+  useOptimistic,
+  startTransition,
+  useRef,
+} from "react";
+import { NavigationStoreContext } from "./context.js";
+import type { PublicNavigationState, NavigateOptions } 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)
+ */
+function toPublicState(state: DerivedNavigationState): PublicNavigationState {
+  const { inflightActions: _, ...publicState } = state;
+  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
+ *
+ * Uses the event controller for reactive state management.
+ * State is derived from source of truth (currentNavigation, inflightActions).
+ *
+ * @example
+ * ```tsx
+ * const state = useNavigation(nav => nav.state);
+ * const isLoading = useNavigation(nav => nav.state === 'loading');
+ * ```
+ */
+export function useNavigation(): NavigationValue;
+export function useNavigation<T>(
+  selector: (state: PublicNavigationState) => T,
+): T;
+export function useNavigation<T>(
+  selector?: (state: PublicNavigationState) => T,
+): T | NavigationValue {
+  const ctx = useContext(NavigationStoreContext);
+
+  if (!ctx) {
+    throw new Error(
+      "useNavigation must be used within NavigationStoreContext.Provider"
+    );
+  }
+
+  // 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);
+
+  // 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 = selector ? selector(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);
+      }
+    });
+  }, [selector]);
+
+  // If no selector, include navigation methods
+  if (!selector) {
+    return {
+      ...(value as PublicNavigationState),
+      navigate: ctx.navigate,
+      refresh: ctx.refresh,
+    };
+  }
+
+  return value as T;
+}