@rangojs/router 0.0.0-experimental.10

package/src/browser/react/Link.tsx

@@ -0,0 +1,248 @@
+"use client";
+
+import React, { forwardRef, useCallback, useContext, useRef, type ForwardRefExoticComponent, type RefAttributes } from "react";
+import { NavigationStoreContext } from "./context.js";
+import { LinkContext } from "./use-link-status.js";
+import type { NavigateOptions } from "../types.js";
+import {
+  type LocationStateEntry,
+  isLocationStateEntry,
+  resolveLocationStateEntries,
+} from "./location-state.js";
+
+/**
+ * State value or getter function for just-in-time state resolution (legacy)
+ */
+export type StateOrGetter<T = unknown> = T | (() => T);
+
+/**
+ * State prop type for Link component
+ * - LocationStateEntry[]: Type-safe state entries (always lazy)
+ * - StateOrGetter: Legacy format for backwards compatibility
+ */
+export type LinkState = LocationStateEntry[] | StateOrGetter;
+
+// Track prefetched URLs to avoid duplicate <link> elements
+const prefetchedUrls = new Set<string>();
+
+/**
+ * Inject a <link rel="prefetch"> element into the document head
+ * for the given URL with RSC partial request parameters.
+ */
+function prefetchUrl(url: string, segmentIds: string[]): void {
+  if (prefetchedUrls.has(url)) return;
+  prefetchedUrls.add(url);
+
+  // Build RSC partial URL with segment IDs
+  const targetUrl = new URL(url, window.location.origin);
+  targetUrl.searchParams.set("_rsc_partial", "true");
+  if (segmentIds.length > 0) {
+    targetUrl.searchParams.set("_rsc_segments", segmentIds.join(","));
+  }
+
+  // Inject <link rel="prefetch"> into head
+  const link = document.createElement("link");
+  link.rel = "prefetch";
+  link.href = targetUrl.toString();
+  link.as = "fetch";
+  document.head.appendChild(link);
+}
+
+/**
+ * Prefetch strategy for the Link component
+ * - "hover": Prefetch on mouse enter (uses native <link rel="prefetch">)
+ * - "viewport": Prefetch when link enters viewport (not yet implemented)
+ * - "hybrid": Hover on desktop, viewport on mobile (not yet implemented)
+ * - "none": No prefetching (default)
+ */
+export type PrefetchStrategy = "hover" | "viewport" | "hybrid" | "none";
+
+/**
+ * Link component props
+ */
+export interface LinkProps
+  extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
+  /**
+   * The URL to navigate to (typically from router.reverse())
+   */
+  to: string;
+  /**
+   * Replace current history entry instead of pushing
+   */
+  replace?: boolean;
+  /**
+   * Scroll to top after navigation (default: true)
+   */
+  scroll?: boolean;
+  /**
+   * Force full document navigation instead of SPA
+   */
+  reloadDocument?: boolean;
+  /**
+   * Prefetch strategy for the link destination
+   * @default "none"
+   */
+  prefetch?: PrefetchStrategy;
+  /**
+   * State to pass to history.pushState/replaceState.
+   * Accessible via useLocationState() hook.
+   *
+   * @example
+   * ```tsx
+   * // Type-safe state with createLocationState (recommended)
+   * const ProductState = createLocationState((p: Product) => ({ name: p.name }));
+   * <Link to="/product" state={[ProductState(product)]}>View</Link>
+   *
+   * // Multiple typed states
+   * <Link to="/checkout" state={[ProductState(p), CartState(c)]}>Checkout</Link>
+   *
+   * // Legacy: static state
+   * <Link to="/product" state={{ from: "list" }}>View</Link>
+   *
+   * // Legacy: dynamic state (called at click time)
+   * <Link to="/product" state={() => ({ scrollY: window.scrollY })}>View</Link>
+   * ```
+   */
+  state?: LinkState;
+  children: React.ReactNode;
+}
+
+/**
+ * Check if URL is external (different origin)
+ */
+function isExternalUrl(href: string): boolean {
+  // Protocol-relative URLs
+  if (href.startsWith("//")) return true;
+
+  // Absolute URLs
+  if (href.startsWith("http://") || href.startsWith("https://")) {
+    try {
+      return new URL(href).origin !== window.location.origin;
+    } catch {
+      return false;
+    }
+  }
+
+  // Special protocols (mailto, tel, etc.)
+  if (/^[a-z][a-z0-9+.-]*:/i.test(href)) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Type-safe Link component for SPA navigation
+ *
+ * Works with router.reverse() for type-safe URLs:
+ * ```tsx
+ * <Link to={router.reverse("shop.products.detail", { slug: "my-product" })}>
+ *   View Product
+ * </Link>
+ * ```
+ *
+ * Also supports regular URLs:
+ * ```tsx
+ * <Link to="/about">About</Link>
+ * <Link to="https://example.com">External</Link>
+ * ```
+ */
+export const Link: ForwardRefExoticComponent<LinkProps & RefAttributes<HTMLAnchorElement>> = forwardRef<HTMLAnchorElement, LinkProps>(function Link(
+  {
+    to,
+    replace = false,
+    scroll = true,
+    reloadDocument = false,
+    prefetch = "none",
+    state,
+    children,
+    onClick,
+    ...props
+  },
+  ref
+) {
+  const ctx = useContext(NavigationStoreContext);
+  const isExternal = isExternalUrl(to);
+
+  // Use ref to always get the latest state/getter without adding to useCallback deps
+  // This enables just-in-time state resolution without causing re-renders
+  const stateRef = useRef(state);
+  stateRef.current = state;
+
+  const handleClick = useCallback(
+    (e: React.MouseEvent<HTMLAnchorElement>) => {
+      // Call user's onClick handler first
+      onClick?.(e);
+
+      // If user prevented default, respect that
+      if (e.defaultPrevented) return;
+
+      // External links - let browser handle normally
+      if (isExternal) return;
+
+      // Force document navigation if requested
+      if (reloadDocument) return;
+
+      // Allow modifier keys for opening in new tab/window
+      if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+
+      // Check for download attribute
+      if ((e.currentTarget as HTMLAnchorElement).hasAttribute("download"))
+        return;
+
+      // Check for target attribute
+      const target = (e.currentTarget as HTMLAnchorElement).target;
+      if (target && target !== "_self") return;
+
+      // Prevent default and use SPA navigation
+      e.preventDefault();
+      // Stop propagation to prevent link-interceptor from also handling this
+      e.stopPropagation();
+
+      if (ctx?.navigate) {
+        // Resolve state just-in-time based on format
+        let resolvedState: unknown;
+        const currentState = stateRef.current;
+
+        if (Array.isArray(currentState) && currentState.length > 0 && isLocationStateEntry(currentState[0])) {
+          // Type-safe LocationStateEntry[] - resolve each entry into keyed object
+          resolvedState = resolveLocationStateEntries(currentState as LocationStateEntry[]);
+        } else if (typeof currentState === "function") {
+          // Legacy getter function
+          resolvedState = currentState();
+        } else {
+          // Legacy static value
+          resolvedState = currentState;
+        }
+
+        ctx.navigate(to, { replace, scroll, state: resolvedState });
+      }
+    },
+    [to, isExternal, reloadDocument, replace, scroll, ctx, onClick]
+  );
+
+  const handleMouseEnter = useCallback(() => {
+    if (prefetch === "hover" && !isExternal && ctx?.store) {
+      const segmentState = ctx.store.getSegmentState();
+      prefetchUrl(to, segmentState.currentSegmentIds);
+    }
+  }, [prefetch, to, isExternal, ctx]);
+
+  return (
+    <a
+      ref={ref}
+      href={to}
+      onClick={handleClick}
+      onMouseEnter={handleMouseEnter}
+      data-link-component
+      data-external={isExternal ? "" : undefined}
+      data-scroll={scroll === false ? "false" : undefined}
+      data-replace={replace ? "true" : undefined}
+      {...props}
+    >
+      <LinkContext.Provider value={to}>
+        {children}
+      </LinkContext.Provider>
+    </a>
+  );
+});

package/src/browser/react/NavigationProvider.tsx

@@ -0,0 +1,346 @@
+"use client";
+
+import React, {
+  useState,
+  useEffect,
+  useCallback,
+  useMemo,
+  use,
+  type ReactNode,
+} from "react";
+import {
+  NavigationStoreContext,
+  type NavigationStoreContextValue,
+} from "./context.js";
+import type {
+  NavigationStore,
+  RscPayload,
+  NavigateOptions,
+  NavigationBridge,
+} from "../types.js";
+import type { EventController } from "../event-controller.js";
+import { RootErrorBoundary } from "../../root-error-boundary.js";
+import type { HandleData } from "../types.js";
+import { ThemeProvider } from "../../theme/ThemeProvider.js";
+import type { ResolvedThemeConfig, Theme } from "../../theme/types.js";
+
+/**
+ * Process handles from an async generator, updating the event controller
+ * and cache as data streams in.
+ *
+ * This handles:
+ * 1. Consuming the async generator and calling setHandleData on each yield
+ * 2. Stopping early if user navigates away (historyKey changes)
+ * 3. Cleaning up stale data when generator yields nothing
+ * 4. Updating the cache after processing completes (if still on same page)
+ */
+async function processHandles(
+  handlesGenerator: AsyncGenerator<HandleData>,
+  opts: {
+    eventController: EventController;
+    store: NavigationStore;
+    matched?: string[];
+    isPartial?: boolean;
+    historyKey: string;
+  }
+): Promise<void> {
+  const { eventController, store, matched, isPartial, historyKey } = opts;
+
+  let yieldCount = 0;
+  for await (const handleData of handlesGenerator) {
+    // Check if user navigated away before each update.
+    // This prevents handle data from cancelled navigations polluting
+    // the current route's breadcrumbs (e.g., quick popstate after clicking a link).
+    if (historyKey !== store.getHistoryKey()) {
+      console.log(
+        "[NavigationProvider] Stopping handle processing - user navigated away"
+      );
+      return;
+    }
+
+    yieldCount++;
+    eventController.setHandleData(handleData, matched, isPartial);
+  }
+
+  // Check again before final updates
+  if (historyKey !== store.getHistoryKey()) {
+    return;
+  }
+
+  // For partial updates where the generator yielded nothing (cached handlers),
+  // we still need to update the segment order to clean up stale handle data.
+  // This happens when navigating away from a route - the handlers for the new
+  // route might not push any breadcrumbs, but we still need to remove the old ones.
+  if (yieldCount === 0 && matched) {
+    eventController.setHandleData({}, matched, true);
+  }
+
+  // After handles processing completes, update the cache's handleData.
+  // This fixes a race condition where commit() caches stale handleData before
+  // the async handles processing completes.
+  // Only update if we're still on the same page (historyKey matches).
+  if (historyKey === store.getHistoryKey()) {
+    const finalHandleData = eventController.getHandleState().data;
+    store.updateCacheHandleData(historyKey, finalHandleData);
+  }
+}
+
+/**
+ * Props for NavigationProvider
+ */
+export interface NavigationProviderProps {
+  /**
+   * Navigation store instance (for cache/segment management)
+   */
+  store: NavigationStore;
+
+  /**
+   * Event controller instance (for navigation/action state)
+   */
+  eventController: EventController;
+
+  /**
+   * Initial RSC payload from server
+   */
+  initialPayload: RscPayload;
+
+  /**
+   * Navigation bridge for handling navigation
+   */
+  bridge: NavigationBridge;
+
+  /**
+   * Theme configuration (null if theme not enabled)
+   * When provided, wraps content in ThemeProvider
+   */
+  themeConfig?: ResolvedThemeConfig | null;
+
+  /**
+   * Initial theme from server (from cookie)
+   * Only used when themeConfig is provided
+   */
+  initialTheme?: Theme;
+
+  /**
+   * Whether connection warmup is enabled.
+   * When true, keeps TLS alive by sending HEAD requests after idle periods.
+   */
+  warmupEnabled?: boolean;
+}
+
+/**
+ * Navigation provider component
+ *
+ * Provides navigation context to the component tree and handles:
+ * - Providing stable store and event controller references (never re-renders consumers)
+ * - Subscribing to UI updates to re-render the tree
+ * - Providing navigate/refresh methods (delegated to bridge)
+ *
+ * State subscriptions happen via useNavigation hook (via event controller), not via context.
+ * This means context consumers don't re-render on state changes.
+ *
+ * @example
+ * ```tsx
+ * <NavigationProvider
+ *   store={store}
+ *   eventController={eventController}
+ *   initialPayload={payload}
+ *   bridge={navigationBridge}
+ * />
+ * ```
+ */
+export function NavigationProvider({
+  store,
+  eventController,
+  initialPayload,
+  bridge,
+  themeConfig,
+  initialTheme,
+  warmupEnabled,
+}: NavigationProviderProps): ReactNode {
+  // Track current payload for rendering (this triggers re-renders)
+  const [payload, setPayload] = useState(initialPayload);
+
+  /**
+   * Navigate to a URL (delegates to bridge)
+   */
+  const navigate = useCallback(
+    async (url: string, options?: NavigateOptions): Promise<void> => {
+      await bridge.navigate(url, options);
+    },
+    []
+  );
+
+  /**
+   * Refresh current route (delegates to bridge)
+   */
+  const refresh = useCallback(async (): Promise<void> => {
+    await bridge.refresh();
+  }, []);
+
+  // Context value is stable (store, eventController, navigate, refresh never change)
+  const contextValue = useMemo<NavigationStoreContextValue>(
+    () => ({
+      store,
+      eventController,
+      navigate,
+      refresh,
+    }),
+    []
+  );
+
+  // Connection warmup: keep TLS alive after idle periods.
+  // After 60s of no user interaction, marks connection as "cold".
+  // On next interaction or visibility change, sends a HEAD request to warm TLS
+  // before the user actually clicks a link.
+  useEffect(() => {
+    if (!warmupEnabled) return;
+
+    const IDLE_TIMEOUT = 60_000;
+    const DEBOUNCE_DELAY = 150;
+
+    let idleTimer: ReturnType<typeof setTimeout> | undefined;
+    let debounceTimer: ReturnType<typeof setTimeout> | undefined;
+    let isCold = false;
+    let warmupListenersAttached = false;
+
+    function sendWarmup() {
+      isCold = false;
+      fetch("/?_rsc_warmup", { method: "HEAD" }).catch(() => {});
+    }
+
+    function triggerWarmup() {
+      if (!isCold) return;
+      clearTimeout(debounceTimer);
+      debounceTimer = setTimeout(() => {
+        sendWarmup();
+        detachWarmupListeners();
+        resetIdleTimer();
+      }, DEBOUNCE_DELAY);
+    }
+
+    function onVisibilityChange() {
+      if (document.visibilityState === "visible" && isCold) {
+        triggerWarmup();
+      }
+    }
+
+    function attachWarmupListeners() {
+      if (warmupListenersAttached) return;
+      warmupListenersAttached = true;
+      document.addEventListener("visibilitychange", onVisibilityChange);
+      document.addEventListener("mousemove", triggerWarmup, { once: true });
+      document.addEventListener("touchstart", triggerWarmup, { once: true });
+    }
+
+    function detachWarmupListeners() {
+      warmupListenersAttached = false;
+      document.removeEventListener("visibilitychange", onVisibilityChange);
+      document.removeEventListener("mousemove", triggerWarmup);
+      document.removeEventListener("touchstart", triggerWarmup);
+    }
+
+    function markCold() {
+      isCold = true;
+      attachWarmupListeners();
+    }
+
+    function resetIdleTimer() {
+      clearTimeout(idleTimer);
+      isCold = false;
+      idleTimer = setTimeout(markCold, IDLE_TIMEOUT);
+    }
+
+    // Activity events that reset the idle timer
+    const activityEvents = ["mousemove", "keydown", "touchstart", "scroll"] as const;
+    const activityOptions: AddEventListenerOptions = { passive: true };
+
+    for (const event of activityEvents) {
+      document.addEventListener(event, resetIdleTimer, activityOptions);
+    }
+
+    resetIdleTimer();
+
+    return () => {
+      clearTimeout(idleTimer);
+      clearTimeout(debounceTimer);
+      detachWarmupListeners();
+      for (const event of activityEvents) {
+        document.removeEventListener(event, resetIdleTimer);
+      }
+    };
+  }, [warmupEnabled]);
+
+  // Subscribe to UI updates (for re-rendering the tree)
+  useEffect(() => {
+    const unsubscribe = store.onUpdate((update) => {
+      setPayload({
+        root: update.root,
+        metadata: update.metadata,
+      });
+
+      // Update handle data progressively as it streams in
+      if (update.metadata.handles) {
+        // Capture historyKey now - by the time async processing completes,
+        // the user might have navigated elsewhere
+        const historyKey = store.getHistoryKey();
+
+        processHandles(update.metadata.handles, {
+          eventController,
+          store,
+          matched: update.metadata.matched,
+          isPartial: update.metadata.isPartial,
+          historyKey,
+        }).catch((err) =>
+          console.error("[NavigationProvider] Error consuming handles:", err)
+        );
+      } else if (update.metadata.cachedHandleData) {
+        // For back/forward navigation from cache, restore the cached handleData
+        // This restores breadcrumbs to the exact state they were when the page was cached
+        eventController.setHandleData(
+          update.metadata.cachedHandleData,
+          update.metadata.matched,
+          false // full replace - restore entire cached state
+        );
+      } else if (update.metadata.matched) {
+        // For cached navigations without handleData, update segmentOrder to clean up stale data
+        eventController.setHandleData(
+          {}, // Empty data - all existing data not in matched will be cleaned up
+          update.metadata.matched,
+          true // partial update - will clean up segments not in matched
+        );
+      }
+    });
+
+    return unsubscribe;
+  }, []);
+
+  // Handle promise case - use() will suspend until resolved
+  const root =
+    payload.root instanceof Promise ? use(payload.root) : payload.root;
+
+  // Wrap content in RootErrorBoundary to catch:
+  // 1. Errors from NetworkErrorThrower (rendered during network failures)
+  // 2. Client component errors that occur before/outside the segment tree's error boundary
+  // 3. Errors during promise resolution or navigation state updates
+  // This acts as a safety net - the segment tree has its own RootErrorBoundary that
+  // catches most errors, but this outer boundary catches anything that slips through.
+
+  // Build the content tree
+  let content = <RootErrorBoundary>{root}</RootErrorBoundary>;
+
+  // Wrap with ThemeProvider when theme is enabled
+  if (themeConfig) {
+    content = (
+      <ThemeProvider config={themeConfig} initialTheme={initialTheme}>
+        {content}
+      </ThemeProvider>
+    );
+  }
+
+  return (
+    <NavigationStoreContext.Provider value={contextValue}>
+      {content}
+    </NavigationStoreContext.Provider>
+  );
+}

package/src/browser/react/ScrollRestoration.tsx

@@ -0,0 +1,94 @@
+"use client";
+
+import { useEffect } from "react";
+import { initScrollRestoration } from "../scroll-restoration.js";
+
+/**
+ * Props for ScrollRestoration component
+ */
+export interface ScrollRestorationProps {
+  /**
+   * Custom function to determine the scroll restoration key.
+   * By default, uses a unique key per history entry (location.key).
+   *
+   * Return location.pathname to restore scroll based on path
+   * (useful for keeping scroll position on the same page).
+   *
+   * @example
+   * ```tsx
+   * // Restore based on pathname (same URL = same scroll)
+   * <ScrollRestoration
+   *   getKey={(location) => location.pathname}
+   * />
+   *
+   * // Restore based on unique history entry (default)
+   * <ScrollRestoration
+   *   getKey={(location) => location.key}
+   * />
+   * ```
+   */
+  getKey?: (location: {
+    pathname: string;
+    search: string;
+    hash: string;
+    key: string;
+  }) => string;
+}
+
+/**
+ * ScrollRestoration component
+ *
+ * Enables scroll position restoration across navigations:
+ * - Saves scroll positions to sessionStorage
+ * - Restores scroll on back/forward navigation
+ * - Scrolls to top on new navigation
+ * - Supports hash link scrolling
+ *
+ * Should be rendered once in your app, typically in the root layout.
+ *
+ * @example
+ * ```tsx
+ * // In your root layout
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html>
+ *       <body>
+ *         <ScrollRestoration />
+ *         {children}
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+export function ScrollRestoration({ getKey }: ScrollRestorationProps) {
+  useEffect(() => {
+    const cleanup = initScrollRestoration({ getKey });
+    return cleanup;
+  }, [getKey]);
+
+  // This component doesn't render anything
+  return null;
+}
+
+/**
+ * Hook to initialize scroll restoration
+ *
+ * Alternative to the ScrollRestoration component for more control.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   useScrollRestoration();
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+export function useScrollRestoration(options?: {
+  getKey?: ScrollRestorationProps["getKey"];
+}): void {
+  useEffect(() => {
+    const cleanup = initScrollRestoration({ getKey: options?.getKey });
+    return cleanup;
+  }, [options?.getKey]);
+}