@ivogt/rsc-router 0.0.0-experimental.1

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;
+}

package/src/browser/request-controller.ts

@@ -0,0 +1,149 @@
+import type { RequestController, DisposableAbortController } from "./types.js";
+
+// Polyfill Symbol.dispose for Safari and older browsers
+if (typeof Symbol.dispose === "undefined") {
+  (Symbol as any).dispose = Symbol("Symbol.dispose");
+}
+
+/**
+ * Create a request controller for managing concurrent abort controllers
+ *
+ * This utility helps manage concurrent navigation requests by providing
+ * a way to abort all pending requests when a new navigation starts.
+ *
+ * @returns RequestController instance
+ *
+ * @example
+ * ```typescript
+ * const controller = createRequestController();
+ *
+ * // Start a new request
+ * const abortController = controller.create();
+ * fetch(url, { signal: abortController.signal });
+ *
+ * // Abort all pending requests (e.g., when starting new navigation)
+ * controller.abortAll();
+ *
+ * // Clean up completed request
+ * controller.remove(abortController);
+ * ```
+ */
+export function createRequestController(): RequestController {
+  // Navigation controllers - aborted on new navigation
+  const controllers: AbortController[] = [];
+  // Action controllers - NOT aborted by navigation, only by errors
+  const actionControllers: AbortController[] = [];
+
+  return {
+    /**
+     * Create a new abort controller and track it for navigation
+     *
+     * @returns A new AbortController
+     */
+    create(): AbortController {
+      const controller = new AbortController();
+      controllers.push(controller);
+      console.log(
+        `[Browser] Created abort controller, total: ${controllers.length}`
+      );
+      return controller;
+    },
+
+    /**
+     * Create a disposable abort controller for navigation use with `using` keyword
+     *
+     * The controller will be automatically removed from tracking when
+     * it goes out of scope, regardless of how the scope is exited.
+     *
+     * @returns A DisposableAbortController
+     *
+     * @example
+     * ```typescript
+     * async function handleNavigation() {
+     *   requestController.abortAll();
+     *   using { controller } = requestController.createDisposable();
+     *   // ... use controller.signal ...
+     *   // controller is automatically removed on scope exit
+     * }
+     * ```
+     */
+    createDisposable(): DisposableAbortController {
+      const controller = this.create();
+      return {
+        controller,
+        [Symbol.dispose]: () => {
+          this.remove(controller);
+        },
+      };
+    },
+
+    /**
+     * Create a disposable abort controller for actions
+     *
+     * Action controllers are NOT aborted by navigation - they complete
+     * independently. Only aborted by abortAllActions() on error.
+     *
+     * @returns A DisposableAbortController
+     */
+    createActionDisposable(): DisposableAbortController {
+      const controller = new AbortController();
+      actionControllers.push(controller);
+      console.log(
+        `[Browser] Created action controller, total: ${actionControllers.length}`
+      );
+      return {
+        controller,
+        [Symbol.dispose]: () => {
+          const index = actionControllers.indexOf(controller);
+          if (index !== -1) {
+            actionControllers.splice(index, 1);
+            console.log(
+              `[Browser] Removed action controller, remaining: ${actionControllers.length}`
+            );
+          }
+        },
+      };
+    },
+
+    /**
+     * Abort all navigation controllers (NOT actions)
+     *
+     * Called when starting new navigation. Actions continue
+     * to complete in the background.
+     */
+    abortAll(): void {
+      controllers.forEach((controller) => controller.abort());
+      controllers.length = 0;
+      console.log(`[Browser] Aborted all navigation controllers`);
+    },
+
+    /**
+     * Abort all action controllers
+     *
+     * Called when an action error occurs - prevents other actions
+     * from completing and overwriting the error UI.
+     */
+    abortAllActions(): void {
+      actionControllers.forEach((controller) => controller.abort());
+      actionControllers.length = 0;
+      console.log(`[Browser] Aborted all action controllers`);
+    },
+
+    /**
+     * Remove a specific controller from tracking
+     *
+     * Call this when a request completes successfully.
+     *
+     * @param controller - The controller to remove
+     */
+    remove(controller: AbortController): void {
+      const index = controllers.indexOf(controller);
+      if (index !== -1) {
+        controllers.splice(index, 1);
+        console.log(
+          `[Browser] Removed abort controller, remaining: ${controllers.length}`
+        );
+      }
+    },
+  };
+}