@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.20dbba0c

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

@@ -1,208 +1,40 @@
 "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];
-}
+import { href, type ValidPaths } from "../../href-client.js";
+import { useMount } from "./use-mount.js";
 
 /**
- * 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.
+ * 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.
  *
- * 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
+ * For absolute paths (outside the current mount), use the bare
+ * href() function directly instead.
  *
- * @typeParam TPatterns - Optional patterns type for type-safe local route names
- * @returns A function to generate URLs from route names
+ * @returns A function that prepends the mount prefix to paths
  *
  * @example
  * ```tsx
  * "use client";
- * import { useHref } from "@rangojs/router/client";
- * import { blogPatterns } from "../urls/blog";
+ * import { useHref, href } from "@rangojs/router/client";
  *
- * function BlogNav() {
- *   // Type-safe: knows "index" | "post" are valid local names
- *   const href = useHref<typeof blogPatterns>();
+ * // Inside include("/shop", shopPatterns)
+ * function ShopNav() {
+ *   const href = useHref();
  *
  *   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>
+ *       {// Local paths - auto-prefixed with /shop}
+ *       <Link to={href("/cart")}>Cart</Link>
+ *       <Link to={href("/product/widget")}>Widget</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>
-  );
+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

@@ -16,7 +16,9 @@ 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);
+export const LinkContext: Context<string | null> = createContext<string | null>(
+  null,
+);
 
 /**
  * Link status returned by useLinkStatus hook
@@ -46,7 +48,7 @@ function normalizeUrl(url: string, origin: string): string {
 function isPendingFor(
   linkTo: string | null,
   pendingUrl: string | null,
-  origin: string
+  origin: string,
 ): boolean {
   if (linkTo === null || pendingUrl === null) {
     return false;
@@ -81,9 +83,8 @@ export function useLinkStatus(): LinkStatus {
   const ctx = useContext(NavigationStoreContext);
 
   // Get origin for URL normalization (stable across renders)
-  const origin = typeof window !== "undefined"
-    ? window.location.origin
-    : "http://localhost";
+  const origin =
+    typeof window !== "undefined" ? window.location.origin : "http://localhost";
 
   // Base state for useOptimistic
   const [basePending, setBasePending] = useState<boolean>(() => {

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

@@ -9,44 +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;
-}
-
-// 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)
  */
@@ -55,66 +21,64 @@ function toPublicState(state: DerivedNavigationState): PublicNavigationState {
   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
+ * 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
+  selector: (state: PublicNavigationState) => T,
 ): T;
 export function useNavigation<T>(
-  selector?: (state: PublicNavigationState) => T
-): T | NavigationValue {
+  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>(() => {
-    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);
 
+  // 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);
+
   // 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(() => {
-    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;
+      const nextSelected = selectorRef.current
+        ? selectorRef.current(publicState)
+        : publicState;
 
       // Check if selected value has changed
       if (!shallowEqual(nextSelected, prevState.current)) {
@@ -124,27 +88,32 @@ 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 ?? noopNavigate,
-      refresh: ctx?.refresh ?? noopRefresh,
-    };
-  }
+  }, []);
 
-  return value as T;
+  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";
+
+/**
+ * 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.
+export function useParams<
+  T extends object = Record<string, string>,
+>(): Readonly<T>;
+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,83 @@
+"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 live context on each call so that
+ * cross-app navigation (app-switch) sees the current app's basename
+ * rather than the one captured at mount time.
+ *
+ * @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): void {
+        const segmentState = ctx.store?.getSegmentState();
+        if (segmentState) {
+          prefetchDirect(
+            withBasename(url),
+            segmentState.currentSegmentIds,
+            getAppVersion(),
+            ctx.store?.getRouterId?.(),
+          );
+        }
+      },
+
+      back(): void {
+        window.history.back();
+      },
+
+      forward(): void {
+        window.history.forward();
+      },
+    };
+  }, []);
+}