@rangojs/router 0.0.0-experimental.2

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

@@ -0,0 +1,208 @@
+"use client";
+
+import { useContext } from "react";
+import { createHref, type ScopedHrefFunction } from "../../href.js";
+import type { UrlPatterns } from "../../urls.js";
+import { HrefContext, type HrefContextValue } from "../../href-context.js";
+
+// Re-export for backwards compatibility
+export { HrefContext, type HrefContextValue } from "../../href-context.js";
+
+/**
+ * Resolution priority for href:
+ * 1. Path-based (/blog/:slug) → Use directly
+ * 2. Absolute name (shop.cart) → Global lookup (has dot separator)
+ * 3. Local name (index) → Prepend current name prefix, then lookup
+ */
+function resolveRouteName(
+  name: string,
+  routeMap: Record<string, string>,
+  currentRoutePrefix?: string
+): string | undefined {
+  // 1. Path-based - starts with /
+  if (name.startsWith("/")) {
+    return name;
+  }
+
+  // 2. Absolute name - already has a dot (e.g., "shop.cart")
+  if (name.includes(".")) {
+    return routeMap[name];
+  }
+
+  // 3. Local name - try with current prefix first, then fall back to direct lookup
+  if (currentRoutePrefix) {
+    // Extract the prefix from current route name
+    // e.g., "blog.posts.detail" → prefix is "blog.posts"
+    const lastDot = currentRoutePrefix.lastIndexOf(".");
+    const prefix = lastDot > 0 ? currentRoutePrefix.substring(0, lastDot) : currentRoutePrefix;
+
+    // Try prefixed name
+    const prefixedName = `${prefix}.${name}`;
+    if (routeMap[prefixedName] !== undefined) {
+      return routeMap[prefixedName];
+    }
+
+    // If current route is a nested include, try parent prefixes
+    // e.g., for "blog.posts.detail", try "blog.posts.index", then "blog.index"
+    let currentPrefix = prefix;
+    while (currentPrefix.includes(".")) {
+      const parentDot = currentPrefix.lastIndexOf(".");
+      currentPrefix = currentPrefix.substring(0, parentDot);
+      const parentPrefixedName = `${currentPrefix}.${name}`;
+      if (routeMap[parentPrefixedName] !== undefined) {
+        return routeMap[parentPrefixedName];
+      }
+    }
+  }
+
+  // Fall back to direct lookup (route without prefix)
+  return routeMap[name];
+}
+
+/**
+ * Type for href function returned by useHref
+ */
+export type HrefFn = {
+  /**
+   * Generate a URL from a route name
+   *
+   * @param name - Route name (local or absolute) or path-based URL
+   * @param params - Optional params for dynamic segments
+   * @returns The resolved URL
+   *
+   * @example
+   * ```tsx
+   * const href = useHref();
+   *
+   * // Local name (resolved with current prefix)
+   * href("index")         // → "/blog" (if inside blog patterns)
+   * href("post", { slug: "hello" }) // → "/blog/hello"
+   *
+   * // Absolute name (direct lookup)
+   * href("shop.cart")     // → "/shop/cart"
+   *
+   * // Path-based (used directly)
+   * href("/about")        // → "/about"
+   * ```
+   */
+  (name: string, params?: Record<string, string>): string;
+};
+
+/**
+ * Client-side hook for resolving route names with current name prefix.
+ *
+ * Resolution priority:
+ * 1. Path-based (`/blog/:slug`) → Use directly
+ * 2. Absolute name (`shop.cart`) → Global lookup (contains dot)
+ * 3. Local name (`index`) → Prepend current name prefix, then lookup
+ *
+ * @typeParam TPatterns - Optional patterns type for type-safe local route names
+ * @returns A function to generate URLs from route names
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { useHref } from "@rangojs/router/client";
+ * import { blogPatterns } from "../urls/blog";
+ *
+ * function BlogNav() {
+ *   // Type-safe: knows "index" | "post" are valid local names
+ *   const href = useHref<typeof blogPatterns>();
+ *
+ *   return (
+ *     <>
+ *       {/* Local names - type-safe, resolved with current name prefix *\/}
+ *       <Link href={href("index")}>Blog Home</Link>
+ *       <Link href={href("post", { slug: "hello" })}>Post</Link>
+ *
+ *       {/* Absolute names - explicit prefix *\/}
+ *       <Link href={href("shop.cart")}>Cart</Link>
+ *
+ *       {/* Path-based - always works *\/}
+ *       <Link href={href("/about")}>About</Link>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function useHref<
+  TPatterns extends UrlPatterns<any, any> = UrlPatterns<any, Record<string, string>>
+>(): TPatterns extends UrlPatterns<any, infer TRoutes>
+  ? ScopedHrefFunction<TRoutes>
+  : HrefFn {
+  const context = useContext(HrefContext);
+
+  if (!context) {
+    // Return a function that warns and returns the name as-is
+    return ((name: string, _params?: Record<string, string>) => {
+      if (process.env.NODE_ENV !== "production") {
+        console.warn(
+          "[useHref] HrefContext not found. Make sure HrefProvider is mounted. Returning name as-is."
+        );
+      }
+      return name;
+    }) as any;
+  }
+
+  const { routeMap, routeName } = context;
+
+  return ((name: string, params?: Record<string, string>) => {
+    // Path-based - return directly (optionally with param substitution)
+    if (name.startsWith("/")) {
+      if (params) {
+        // Substitute params in path-based URL
+        return name.replace(/:([^/]+)/g, (_, key) => {
+          const value = params[key];
+          if (value === undefined) {
+            throw new Error(`Missing param "${key}" for path "${name}"`);
+          }
+          return encodeURIComponent(value);
+        });
+      }
+      return name;
+    }
+
+    // Resolve route name
+    const pattern = resolveRouteName(name, routeMap, routeName);
+
+    if (pattern === undefined) {
+      throw new Error(
+        `Unknown route: "${name}"${routeName ? ` (current route: ${routeName})` : ""}`
+      );
+    }
+
+    // If no params, return pattern directly
+    if (!params) {
+      return pattern;
+    }
+
+    // Substitute params
+    return pattern.replace(/:([^/]+)/g, (_, key) => {
+      const value = params[key];
+      if (value === undefined) {
+        throw new Error(`Missing param "${key}" for route "${name}"`);
+      }
+      return encodeURIComponent(value);
+    });
+  }) as any;
+}
+
+/**
+ * Provider component for href context
+ * Used internally by NavigationProvider to pass route map from RSC metadata
+ */
+export function HrefProvider({
+  routeMap,
+  routeName,
+  children,
+}: {
+  routeMap: Record<string, string>;
+  routeName?: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <HrefContext.Provider value={{ routeMap, routeName }}>
+      {children}
+    </HrefContext.Provider>
+  );
+}

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-navigation.ts

@@ -0,0 +1,150 @@
+"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;
+}
+
+// SSR-safe default state (public version without internal properties)
+const SSR_DEFAULT_STATE: PublicNavigationState = {
+  state: "idle",
+  isStreaming: false,
+  location: new URL("/", "http://localhost"),
+  pendingUrl: null,
+};
+
+/**
+ * Convert derived state to public version (strips inflightActions)
+ */
+function toPublicState(state: DerivedNavigationState): PublicNavigationState {
+  const { inflightActions: _, ...publicState } = state;
+  return publicState;
+}
+
+// No-op functions for SSR
+const noopNavigate = async () => {};
+const noopRefresh = async () => {};
+
+/**
+ * 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);
+
+  // Base state for useOptimistic
+  const [baseValue, setBaseValue] = useState<T | PublicNavigationState>(() => {
+    if (typeof document === "undefined" || !ctx) {
+      return selector ? selector(SSR_DEFAULT_STATE) : SSR_DEFAULT_STATE;
+    }
+    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(() => {
+    if (!ctx) return;
+
+    // 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 ?? noopNavigate,
+      refresh: ctx?.refresh ?? noopRefresh,
+    };
+  }
+
+  return value as T;
+}

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

@@ -0,0 +1,188 @@
+"use client";
+
+import { useContext, useState, useEffect, useRef } from "react";
+import { NavigationStoreContext } from "./context.js";
+
+/**
+ * Segments state returned by useSegments hook
+ */
+export interface SegmentsState {
+  /** URL path segments (e.g., /shop/products/123 → ["shop", "products", "123"]) */
+  path: readonly string[];
+  /** Matched segment IDs in order (layouts and routes only, e.g., ["L0", "L0L1", "L0L1R0"]) */
+  segmentIds: readonly string[];
+  /** Current URL location */
+  location: URL;
+}
+
+/**
+ * SSR module-level state.
+ * Populated by initSegmentsSync before React renders.
+ * Used by useState initializer during SSR.
+ */
+let ssrSegmentOrder: string[] = [];
+let ssrPathname: 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;
+  });
+}
+
+/**
+ * Initialize segments data synchronously for SSR.
+ * Called before rendering to populate state for useState initializer.
+ *
+ * @param matched - Segment order from RSC metadata
+ * @param pathname - Current pathname
+ */
+export function initSegmentsSync(matched?: string[], pathname?: string): void {
+  ssrSegmentOrder = filterSegmentOrder(matched ?? []);
+  ssrPathname = pathname ?? "/";
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Parse pathname into path segments
+ * /shop/products/123 → ["shop", "products", "123"]
+ */
+function parsePathname(pathname: string): string[] {
+  return pathname.split("/").filter(Boolean);
+}
+
+/**
+ * Build segments state from event controller
+ */
+function buildSegmentsState(
+  location: URL,
+  segmentOrder: string[]
+): SegmentsState {
+  return {
+    path: parsePathname(location.pathname),
+    segmentIds: segmentOrder,
+    location,
+  };
+}
+
+/**
+ * Build SSR state from module-level variables
+ */
+function buildSsrState(): SegmentsState {
+  const location = new URL(ssrPathname, "http://localhost");
+  return {
+    path: parsePathname(ssrPathname),
+    segmentIds: ssrSegmentOrder,
+    location,
+  };
+}
+
+/**
+ * Hook to access current route segments with optional selector for performance
+ *
+ * Provides information about the current URL path and matched route segments.
+ * Uses the event controller for reactive state management.
+ *
+ * @example
+ * ```tsx
+ * // Get full segments state
+ * const { path, segmentIds, location } = useSegments();
+ *
+ * // Use selector for specific values (better performance)
+ * const path = useSegments(s => s.path);
+ * const isShopRoute = useSegments(s => s.path[0] === "shop");
+ * ```
+ */
+export function useSegments(): SegmentsState;
+export function useSegments<T>(selector: (state: SegmentsState) => T): T;
+export function useSegments<T>(
+  selector?: (state: SegmentsState) => T
+): T | SegmentsState {
+  const ctx = useContext(NavigationStoreContext);
+
+  // Build initial state from SSR module state or event controller
+  const [state, setState] = useState<T | SegmentsState>(() => {
+    // During SSR or when no context, use module-level SSR state
+    if (typeof document === "undefined" || !ctx) {
+      const ssrState = buildSsrState();
+      return selector ? selector(ssrState) : ssrState;
+    }
+    // On client with context, use event controller state
+    const navState = ctx.eventController.getState();
+    const handleState = ctx.eventController.getHandleState();
+    const segmentsState = buildSegmentsState(
+      navState.location as URL,
+      handleState.segmentOrder
+    );
+    return selector ? selector(segmentsState) : segmentsState;
+  });
+
+  const prevState = useRef(state);
+
+  // Subscribe to both navigation state and handle state changes
+  useEffect(() => {
+    if (!ctx) {
+      return;
+    }
+
+    const updateState = () => {
+      const navState = ctx.eventController.getState();
+      const handleState = ctx.eventController.getHandleState();
+      const segmentsState = buildSegmentsState(
+        navState.location as URL,
+        handleState.segmentOrder
+      );
+      const nextSelected = selector ? selector(segmentsState) : segmentsState;
+
+      if (!shallowEqual(nextSelected, prevState.current)) {
+        prevState.current = nextSelected;
+        setState(nextSelected);
+      }
+    };
+
+    // Initial update in case SSR state differs from client state
+    updateState();
+
+    // Subscribe to both state sources
+    const unsubscribeNav = ctx.eventController.subscribe(updateState);
+    const unsubscribeHandles = ctx.eventController.subscribeToHandles(updateState);
+
+    return () => {
+      unsubscribeNav();
+      unsubscribeHandles();
+    };
+  }, [selector]);
+
+  return state as T | SegmentsState;
+}