@ivogt/rsc-router 0.0.0-experimental.1

package/src/browser/react/location-state-shared.ts

@@ -0,0 +1,120 @@
+/**
+ * Shared location state utilities - works in both RSC and client contexts
+ * No "use client" directive so it can be imported from RSC
+ */
+
+/**
+ * Internal entry representing a state value with its unique key
+ */
+export interface LocationStateEntry {
+  readonly __rsc_ls_key: string;
+  readonly __rsc_ls_value: unknown;
+}
+
+/**
+ * Type-safe location state definition
+ *
+ * Created via createLocationState(), used with Link's state prop
+ * and useLocationState() hook.
+ */
+export interface LocationStateDefinition<TArgs extends unknown[], TState> {
+  (...args: TArgs): LocationStateEntry;
+  readonly __rsc_ls_key: string;
+}
+
+// Track used keys to detect duplicates in development
+const usedKeys = new Set<string>();
+
+/**
+ * Create a type-safe location state definition
+ *
+ * The key is auto-generated by the Vite exposeLocationStateId plugin based on
+ * file path and export name. No manual key required.
+ *
+ * @param key Auto-injected by Vite plugin, do not provide manually
+ * @returns A typed state definition for use with Link and useLocationState
+ *
+ * @example
+ * ```typescript
+ * // Define typed state (key auto-generated from file + export)
+ * export const ProductState = createLocationState<{ name: string; price: number }>();
+ *
+ * // Use in Link - state is captured at click time
+ * <Link to="/product/123" state={[ProductState({ name: product.name, price: product.price })]}>
+ *   View Product
+ * </Link>
+ *
+ * // Multiple states
+ * <Link to="/checkout" state={[ProductState(productData), CartState(cartData)]}>
+ *   Checkout
+ * </Link>
+ *
+ * // For lazy evaluation (click-time), pass a getter
+ * <Link to="/product" state={[ProductState(() => ({ name: product.name }))]}>
+ *
+ * // Read with type safety
+ * const productState = useLocationState(ProductState);
+ * // productState: { name: string; price: number } | undefined
+ * ```
+ */
+export function createLocationState<TState>(
+  key?: string
+): LocationStateDefinition<[TState | (() => TState)], TState> {
+  if (!key && process.env.NODE_ENV !== "production") {
+    console.warn(
+      "[rsc-router] createLocationState is missing a key. " +
+        "Make sure the exposeLocationStateId Vite plugin is enabled and " +
+        "the state is exported with: export const MyState = createLocationState(...)"
+    );
+  }
+  const fullKey = `__rsc_ls_${key}`;
+
+  // Warn about duplicate keys in development
+  if (process.env.NODE_ENV !== "production" && usedKeys.has(fullKey)) {
+    console.warn(
+      `[rsc-router] Duplicate location state key "${key}". ` +
+        `Each createLocationState call should have a unique key.`
+    );
+  }
+  usedKeys.add(fullKey);
+
+  const definition = Object.assign(
+    (stateOrGetter: TState | (() => TState)): LocationStateEntry => ({
+      __rsc_ls_key: fullKey,
+      // Resolve getter immediately - lazy evaluation happens via Link's stateRef pattern
+      __rsc_ls_value:
+        typeof stateOrGetter === "function"
+          ? (stateOrGetter as () => TState)()
+          : stateOrGetter,
+    }),
+    { __rsc_ls_key: fullKey }
+  );
+
+  return definition as LocationStateDefinition<[TState | (() => TState)], TState>;
+}
+
+/**
+ * Check if a value is a LocationStateEntry
+ */
+export function isLocationStateEntry(value: unknown): value is LocationStateEntry {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    "__rsc_ls_key" in value &&
+    "__rsc_ls_value" in value &&
+    typeof (value as LocationStateEntry).__rsc_ls_key === "string"
+  );
+}
+
+/**
+ * Resolve state entries into a flat object for history.state
+ */
+export function resolveLocationStateEntries(
+  entries: LocationStateEntry[]
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const entry of entries) {
+    result[entry.__rsc_ls_key] = entry.__rsc_ls_value;
+  }
+  return result;
+}

package/src/browser/react/location-state.ts

@@ -0,0 +1,62 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import type { LocationStateDefinition } from "./location-state-shared.js";
+
+// Re-export shared utilities and types
+export {
+  createLocationState,
+  isLocationStateEntry,
+  resolveLocationStateEntries,
+  type LocationStateEntry,
+  type LocationStateDefinition,
+} from "./location-state-shared.js";
+
+/**
+ * Hook to read location state from history.state
+ *
+ * Overloaded:
+ * - With definition: Returns typed state from the specific key
+ * - With type param only: Returns legacy state from history.state.state (backwards compat)
+ *
+ * @example
+ * ```typescript
+ * // Typed access with definition (recommended)
+ * const ProductState = createLocationState<{ name: string }>("product");
+ * const state = useLocationState(ProductState);
+ * // state: { name: string } | undefined
+ *
+ * // Legacy typed access (backwards compatible)
+ * const legacyState = useLocationState<{ from?: string }>();
+ * ```
+ */
+export function useLocationState<TArgs extends unknown[], TState>(
+  definition: LocationStateDefinition<TArgs, TState>
+): TState | undefined;
+export function useLocationState<T = unknown>(): T | undefined;
+export function useLocationState<TArgs extends unknown[], TState>(
+  definition?: LocationStateDefinition<TArgs, TState>
+): TState | undefined {
+  const [state, setState] = useState<TState | undefined>(() => {
+    if (typeof window === "undefined") return undefined;
+    if (definition) {
+      return window.history.state?.[definition.__rsc_ls_key] as TState | undefined;
+    }
+    // Legacy: return history.state.state for backwards compatibility
+    return window.history.state?.state as TState | undefined;
+  });
+
+  useEffect(() => {
+    const handlePopstate = () => {
+      if (definition) {
+        setState(window.history.state?.[definition.__rsc_ls_key] as TState | undefined);
+      } else {
+        setState(window.history.state?.state as TState | undefined);
+      }
+    };
+    window.addEventListener("popstate", handlePopstate);
+    return () => window.removeEventListener("popstate", handlePopstate);
+  }, [definition]);
+
+  return state;
+}

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

@@ -0,0 +1,240 @@
+"use client";
+
+import {
+  useContext,
+  useState,
+  useEffect,
+  useRef,
+  useOptimistic,
+  startTransition,
+} from "react";
+import { NavigationStoreContext } from "./context.js";
+import type { TrackedActionState, ActionLifecycleState } from "../types.js";
+import { invariant } from "../../errors.js";
+
+/**
+ * Default action state (idle with no payload)
+ */
+const DEFAULT_ACTION_STATE: TrackedActionState = {
+  state: "idle",
+  actionId: null,
+  payload: null,
+  error: null,
+  result: null,
+};
+
+/**
+ * Normalize action ID - returns the ID as-is
+ *
+ * Server actions have IDs like "hash#actionName" or "src/actions.ts#actionName".
+ * When using function references, we use the full ID for exact matching.
+ * When using strings, the event controller supports suffix matching
+ * (e.g., "addToCart" matches "hash#addToCart").
+ */
+function normalizeActionId(actionId: string): string {
+  return actionId;
+}
+
+/**
+ * Extract action ID from a server action function or string.
+ *
+ * Actions passed as props from server components lose their metadata
+ * during RSC serialization - use a string action name instead.
+ */
+export function getActionId(action: ServerActionFunction | string): string {
+  invariant(
+    typeof action === "function" || typeof action === "string",
+    `useAction: action must be a function or string, got ${typeof action}`
+  );
+  const actionId = (action as any)?.$$id;
+  if (actionId) {
+    return normalizeActionId(actionId);
+  }
+
+  // If action is a string, use it directly
+  if (typeof action === "string") {
+    return action;
+  }
+
+  // If we get here, this is likely an action passed as prop from a server component
+  // These lose their metadata during RSC serialization
+  throw new Error(
+    `useAction: Cannot extract action ID from function reference.
+
+This typically happens when an action is passed as a prop from a server component.
+Actions passed through RSC lose their metadata during serialization.
+
+Solutions:
+1. Import the action directly in your client component:
+   import { myAction } from './actions';
+   const state = useAction(myAction);
+
+2. Use the action name as a string:
+   const state = useAction("myAction");
+
+The string must match the exported function name from your "use server" file.`
+  );
+}
+
+/**
+ * Server action function type
+ * Server actions have a $$id property added by the RSC compiler
+ */
+export type ServerActionFunction = ((...args: any[]) => Promise<any>) & {
+  $$id?: string;
+};
+
+/**
+ * Hook to track the lifecycle of a specific server action
+ *
+ * Unlike useNavigation which tracks global navigation state, useAction
+ * tracks the state of individual server action invocations.
+ *
+ * Uses the event controller for reactive state management.
+ * State is derived from the inflight actions tracked by the controller.
+ *
+ * Features:
+ * - Tracks action lifecycle: idle → loading → streaming → idle
+ * - Captures result/error locally (React handles cleanup)
+ * - If multiple actions fire, tracks only the last one
+ * - Supports selector pattern like useNavigation
+ *
+ * Matching behavior:
+ * - **Function reference**: Uses full $$id for exact matching. This is precise
+ *   and distinguishes between actions with the same name in different files.
+ * - **String**: Matches by suffix (action name after #). This is convenient
+ *   but may be ambiguous if multiple files export the same action name.
+ *
+ * @param action - Either a server action function or a string action name.
+ *   - **Function**: Must be directly imported in the client component.
+ *     Actions passed as props from server components will throw an error.
+ *   - **String**: The exported function name from your "use server" file.
+ *     Matches any action ending with "#actionName" (suffix match).
+ *
+ * @example
+ * ```tsx
+ * // Option 1: Direct import (precise matching)
+ * import { addToCart } from './actions';
+ * const actionState = useAction(addToCart);
+ *
+ * // Option 2: String-based (suffix matching)
+ * // Matches "hash#addToCart" or "src/actions.ts#addToCart"
+ * const actionState = useAction('addToCart');
+ *
+ * // With selector for specific values
+ * const isLoading = useAction(addToCart, state => state.state === 'loading');
+ * const error = useAction(addToCart, state => state.error);
+ * ```
+ *
+ * @note Actions passed as props from server components lose their metadata
+ * during RSC serialization. Use a string action name or import directly.
+ */
+export function useAction(
+  action: ServerActionFunction | string
+): TrackedActionState;
+export function useAction<T>(
+  action: ServerActionFunction | string,
+  selector: (state: TrackedActionState) => T
+): T;
+export function useAction<T>(
+  action: ServerActionFunction | string,
+  selector?: (state: TrackedActionState) => T
+): T | TrackedActionState {
+  const ctx = useContext(NavigationStoreContext);
+  const actionId =
+    typeof window !== "undefined" && typeof document !== "undefined"
+      ? getActionId(action)
+      : "";
+
+  // Base state for useOptimistic
+  const [baseState, setBaseState] = useState<T | TrackedActionState>(() => {
+    if (!ctx) {
+      return selector ? selector(DEFAULT_ACTION_STATE) : DEFAULT_ACTION_STATE;
+    }
+    const state = ctx.eventController.getActionState(actionId);
+    return selector ? selector(state) : state;
+  });
+  const prevSelected = useRef(baseState);
+  prevSelected.current = baseState;
+  // useOptimistic allows immediate updates during transitions/actions
+  const [optimisticState, setOptimisticState] = useOptimistic<
+    T | TrackedActionState
+  >(null!);
+
+  // Memoize the selector to avoid unnecessary re-subscriptions
+  const selectorRef = useRef(selector);
+  selectorRef.current = selector;
+
+  // Subscribe to action state changes from event controller
+  useEffect(() => {
+    if (!ctx) return;
+
+    // Subscribe to action-specific updates
+    const unsubscribe = ctx.eventController.subscribeToAction(
+      actionId,
+      (state) => {
+        const selectedState = selectorRef.current
+          ? selectorRef.current(state)
+          : state;
+
+        if (!isShallowEqual(selectedState, prevSelected.current)) {
+          prevSelected.current = selectedState;
+          setBaseState(selectedState);
+          startTransition(() => {
+            setOptimisticState(selectedState);
+          });
+        }
+      }
+    );
+
+    return () => {
+      unsubscribe();
+    };
+  }, [actionId]);
+
+  return (optimisticState ?? baseState) as T | TrackedActionState;
+}
+
+function isShallowEqual<T, U>(selectedState: T, baseState: U): boolean {
+  // If references are equal, they're shallow equal
+  //@ts-expect-error -- TS doesn't like comparing generics
+  if (selectedState === baseState) {
+    return true;
+  }
+
+  // If either is null/undefined and they're not equal, they're not shallow equal
+  if (selectedState == null || baseState == null) {
+    return false;
+  }
+
+  // If types are different, they're not shallow equal
+  if (typeof selectedState !== typeof baseState) {
+    return false;
+  }
+
+  // For primitives, === comparison is sufficient (already checked above)
+  if (typeof selectedState !== "object") {
+    return false;
+  }
+
+  // For objects, compare keys and values shallowly
+  const keysA = Object.keys(selectedState as object);
+  const keysB = Object.keys(baseState as object);
+
+  if (keysA.length !== keysB.length) {
+    return false;
+  }
+
+  for (const key of keysA) {
+    if (
+      !Object.prototype.hasOwnProperty.call(baseState, key) ||
+      (selectedState as any)[key] !== (baseState as any)[key]
+    ) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+export type { TrackedActionState };

package/src/browser/react/use-client-cache.ts

@@ -0,0 +1,56 @@
+"use client";
+
+import { useContext, useCallback } from "react";
+import { NavigationStoreContext } from "./context.js";
+
+/**
+ * Return type for useClientCache hook
+ */
+export interface ClientCacheControls {
+  /**
+   * Clear the client-side navigation cache.
+   * Call this after data changes that happen outside of server actions
+   * (e.g., REST API calls, WebSocket updates, etc.)
+   *
+   * This will also broadcast to other tabs to clear their caches.
+   */
+  clear: () => void;
+}
+
+/**
+ * Hook to access client-side cache controls
+ *
+ * Use this when you need to manually invalidate the navigation cache
+ * after data changes that happen outside of server actions.
+ *
+ * Server actions automatically clear the cache, so you only need this for:
+ * - REST API mutations
+ * - WebSocket-driven updates
+ * - Other non-RSC data changes
+ *
+ * @example
+ * ```tsx
+ * function DataEditor() {
+ *   const { clear } = useClientCache();
+ *
+ *   async function handleSave() {
+ *     await fetch('/api/data', { method: 'POST', body: JSON.stringify(data) });
+ *     // Clear cache so back/forward navigation shows fresh data
+ *     clear();
+ *   }
+ *
+ *   return <button onClick={handleSave}>Save</button>;
+ * }
+ * ```
+ */
+export function useClientCache(): ClientCacheControls {
+  const ctx = useContext(NavigationStoreContext);
+
+  const clear = useCallback(() => {
+    if (ctx?.store) {
+      ctx.store.clearHistoryCache();
+    }
+  }, [ctx]);
+
+  return { clear };
+}

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

@@ -0,0 +1,178 @@
+"use client";
+
+import {
+  useContext,
+  useState,
+  useEffect,
+  useRef,
+  useOptimistic,
+  startTransition,
+} from "react";
+import type { Handle } 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;
+  });
+}
+
+/**
+ * Collect handle data from segments and transform to final value.
+ */
+function collectHandle<T, A>(
+  handle: Handle<T, A>,
+  data: HandleData,
+  segmentOrder: string[]
+): A {
+  const segmentData = data[handle.$$id];
+
+  if (!segmentData) {
+    return handle.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 handle.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;
+}