@rangojs/router 0.0.0-experimental.2

package/src/segment-system.tsx

@@ -0,0 +1,456 @@
+import { createElement, type ReactNode, type ComponentType } from "react";
+import { OutletProvider } from "./client.js";
+import { HrefProvider } from "./browser/react/use-href.js";
+import type {
+  ResolvedSegment,
+  LoaderDataResult,
+  RootLayoutProps,
+} from "./types.js";
+import { isLoaderDataResult } from "./types.js";
+import { invariant } from "./errors.js";
+import {
+  RouteContentWrapper,
+  LoaderBoundary,
+} from "./route-content-wrapper.js";
+import { RootErrorBoundary } from "./root-error-boundary.js";
+
+/**
+ * Resolve loader data from raw results, unwrapping LoaderDataResult wrappers
+ */
+function resolveLoaderData(
+  resolvedData: any[],
+  loaderIds: string[],
+): { loaderData: Record<string, any>; errorFallback: ReactNode } {
+  const loaderData: Record<string, any> = {};
+  let errorFallback: ReactNode = null;
+
+  for (let i = 0; i < loaderIds.length; i++) {
+    const id = loaderIds[i];
+    const result = resolvedData[i];
+
+    if (!isLoaderDataResult(result)) {
+      // Legacy format - direct data
+      loaderData[id] = result;
+      continue;
+    }
+
+    if (result.ok) {
+      loaderData[id] = result.data;
+      continue;
+    }
+
+    // Error case
+    if (result.fallback) {
+      errorFallback = result.fallback;
+    } else {
+      throw new Error(result.error.message);
+    }
+  }
+
+  return { loaderData, errorFallback };
+}
+
+/**
+ * Options for renderSegments
+ */
+export interface RenderSegmentsOptions {
+  /**
+   * If true, this render is for a server action response.
+   * In browser during actions, we await component promises to prevent
+   * UI flickering/suspense during optimistic updates.
+   */
+  isAction?: boolean;
+
+  /**
+   * If true, force awaiting all loaders instead of streaming with Suspense.
+   * Used for popstate (back/forward) navigation where we want instant rendering
+   * from cache without showing loading skeletons.
+   */
+  forceAwait?: boolean;
+
+  /**
+   * Intercept segments to inject into the tree.
+   * These are parallel segments from intercept routes that need to be
+   * associated with their parent layout's named outlet.
+   *
+   * Passed separately for explicit handling - makes the flow clearer
+   * and easier to debug than relying on ID pattern matching.
+   */
+  interceptSegments?: ResolvedSegment[];
+
+  /**
+   * Root layout component that wraps the entire application.
+   * When provided, wraps both route content and the error boundary,
+   * preventing the app shell from unmounting during errors (avoids FOUC).
+   */
+  rootLayout?: ComponentType<RootLayoutProps>;
+
+  /**
+   * Route map for useHref() during SSR.
+   * Maps route names to URL patterns.
+   */
+  routeMap?: Record<string, string>;
+
+  /**
+   * Current matched route name for useHref() during SSR.
+   * Used for local name resolution.
+   */
+  routeName?: string;
+}
+
+/**
+ * Render segments into a React tree with proper layout nesting
+ *
+ * Layouts nest using OutletProvider, while route + parallel + error + notFound segments
+ * render as siblings in a Fragment.
+ *
+ * Error segments are treated like route segments - they render their fallback
+ * component in place of the failed segment. When an error occurs in a handler,
+ * loader, or middleware, the router creates an error segment with the nearest
+ * error boundary's fallback component.
+ *
+ * NotFound segments are similar to error segments but are triggered by
+ * DataNotFoundError (thrown via notFound()). They render the nearest
+ * notFoundBoundary's fallback component.
+ *
+ * @param segments - Array of resolved segments to render
+ * @returns ReactNode representing the component tree
+ *
+ * @example
+ * ```typescript
+ * const segments = [
+ *   { id: 'L0.0', type: 'layout', component: <RootLayout /> },
+ *   { id: 'L1.0', type: 'layout', component: <BlogLayout /> },
+ *   { id: 'R2.0', type: 'route', component: <BlogPost /> },
+ *   { id: 'P3.0', type: 'parallel', component: <Sidebar />, slot: '@sidebar' }
+ * ];
+ *
+ * const tree = renderSegments(segments);
+ * // Results in:
+ * // <OutletProvider><RootLayout>
+ * //   <OutletProvider><BlogLayout>
+ * //     <><BlogPost /><Sidebar /></>
+ * //   </BlogLayout></OutletProvider>
+ * // </RootLayout></OutletProvider>
+ *
+ * // For server actions, pass isAction to await components:
+ * const tree = renderSegments(segments, { isAction: true });
+ * ```
+ */
+export async function renderSegments(
+  segments: ResolvedSegment[],
+  options?: RenderSegmentsOptions,
+): Promise<ReactNode> {
+  const {
+    isAction,
+    interceptSegments,
+    forceAwait,
+    rootLayout: RootLayout,
+    routeMap,
+    routeName,
+  } = options || {};
+  const temporalLazyRefs: Promise<any>[] = [];
+
+  /**
+   * Registers promises from lazy/async components for awaiting.
+   * Handles both direct promises and React lazy components (which store promise in _payload).
+   */
+  const registerLazyRef = <T,>(node: T): T => {
+    if (node instanceof Promise) {
+      temporalLazyRefs.push(node);
+    } else if (isLazyComponent(node)) {
+      temporalLazyRefs.push(node._payload);
+    }
+    return node;
+  };
+
+  // Type guard for React lazy component internals
+  function isLazyComponent(node: unknown): node is { _payload: Promise<any> } {
+    return (
+      node != null &&
+      typeof node === "object" &&
+      "_payload" in node &&
+      (node as any)._payload instanceof Promise
+    );
+  }
+  // Separate segments by type, passing intercept segments for explicit injection
+  const tree = segmentTreeWalk(segments, interceptSegments);
+  // Render content segments as siblings
+  let content: ReactNode = null;
+  for (const node of tree) {
+    invariant(
+      node.segment.type === "layout" ||
+        node.segment.type === "route" ||
+        node.segment.type === "error" ||
+        node.segment.type === "notFound",
+      `Expected layout, route, error, or notFound segment, got ${node.segment.type}`,
+    );
+    const { component, id, params, loading } = node.segment;
+
+    // Only include params in key for segments that belong to the route
+    // - Routes: always include params (they render param-specific content)
+    // - Error/notFound segments: always include params (they replace failed route content)
+    // - Route's layouts (orphans): include params (children of parameterized route)
+    // - Parent chain layouts: exclude params (shared across routes, param-agnostic)
+    // This prevents unnecessary unmounting when params change
+    const includeParams =
+      node.segment.type === "route" ||
+      node.segment.type === "error" ||
+      node.segment.type === "notFound" ||
+      (node.segment.type === "layout" && node.segment.belongsToRoute);
+
+    const paramStr =
+      includeParams && params && Object.keys(params).length > 0
+        ? Object.entries(params)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([k, v]) => `${k}=${v}`)
+            .join(",")
+        : "";
+    const key = `${paramStr ? `${id}-${paramStr}` : id}`;
+
+    // Get loader entries for this node
+    const loaderEntries = node.loaders.filter(
+      (loader) => loader.loaderId && loader.loaderData !== undefined,
+    );
+
+    // Determine the component content (with or without Suspense wrapper)
+    // Wrap when loading skeleton defined OR component is Promise (needs Suspense)
+    // During actions, await component Promise to prevent Suspense from triggering
+    // This keeps existing content visible instead of showing loading skeleton
+    let resolvedComponent = component;
+    if (isAction && component instanceof Promise) {
+      resolvedComponent = await component;
+    }
+    let nodeContent: ReactNode =
+      loading || loading === null || resolvedComponent instanceof Promise
+        ? createElement(RouteContentWrapper, {
+            key: `suspense-loading-${id}`,
+            content:
+              resolvedComponent instanceof Promise
+                ? resolvedComponent
+                : Promise.resolve(resolvedComponent),
+            fallback: loading,
+          })
+        : registerLazyRef(resolvedComponent);
+
+    // Common props for OutletProvider
+    const outletContent: ReactNode =
+      node.segment.type === "layout" ? content : null;
+
+    // Prepare loader data if there are loaders
+    const loaderIds = loaderEntries.map((loader) => loader.loaderId!);
+    const loaderDataPromise =
+      loaderEntries.length > 0
+        ? Promise.all(
+            loaderEntries.map((loader) =>
+              loader.loaderData instanceof Promise
+                ? loader.loaderData
+                : Promise.resolve(loader.loaderData),
+            ),
+          )
+        : Promise.resolve([]);
+
+    // Use LoaderBoundary when loading is defined to maintain consistent tree structure
+    // This ensures cached segments (which may not have loader segments) have the same
+    // tree structure as fresh segments, preventing React remounts
+    // If forceAwait or isAction is set, pre-resolve promises so LoaderBoundary won't suspend
+    if (loading !== undefined) {
+      content = createElement(LoaderBoundary, {
+        key: `loader-boundary-${key}`,
+        loaderDataPromise:
+          forceAwait || isAction ? await loaderDataPromise : loaderDataPromise,
+        loaderIds,
+        fallback: loading,
+        outletKey: key,
+        outletContent,
+        segment: node.segment,
+        parallel: node.parallel,
+        children: nodeContent,
+      });
+      continue;
+    }
+
+    // No loading skeleton defined - use OutletProvider directly
+    if (loaderEntries.length === 0) {
+      // No loaders, no loading - simple OutletProvider
+      content = createElement(OutletProvider, {
+        key,
+        content: outletContent,
+        segment: node.segment,
+        parallel: node.parallel,
+        children: nodeContent,
+      });
+      continue;
+    }
+
+    // Has loaders but no loading skeleton - await loaders and render directly
+    const resolvedData = await loaderDataPromise;
+    const { loaderData, errorFallback } = resolveLoaderData(
+      resolvedData,
+      loaderIds,
+    );
+
+    content = createElement(OutletProvider, {
+      key,
+      content: outletContent,
+      segment: node.segment,
+      parallel: node.parallel,
+      loaderData: Object.keys(loaderData).length > 0 ? loaderData : undefined,
+      children: errorFallback ?? nodeContent,
+    });
+  }
+
+  // Always wrap with root error boundary to prevent white screens
+  // This catches any unhandled errors that bubble up from the segment tree
+  const errorBoundaryWrapped = createElement(RootErrorBoundary, {
+    children: content,
+  });
+  await Promise.allSettled(temporalLazyRefs);
+
+  // Build the final result, optionally wrapped with root layout
+  let result: ReactNode = errorBoundaryWrapped;
+
+  // If rootLayout is provided, wrap the error boundary with it
+  // This ensures the app shell stays mounted even during errors (prevents FOUC)
+  if (RootLayout) {
+    result = createElement(RootLayout, {
+      children: errorBoundaryWrapped,
+    });
+  }
+
+  // Wrap with HrefProvider for useHref() to work during SSR
+  // This provides route info to client components during server rendering
+  if (routeMap) {
+    result = createElement(HrefProvider, {
+      routeMap,
+      routeName,
+      children: result,
+    });
+  }
+
+  return result;
+}
+
+/**
+ * Walk segments in bottom-to-top order for React nesting
+ *
+ * Segments from match() are in top-to-bottom order (root → leaf):
+ * Example: [L0, L0L0, L0R1L0.@sidebar, L0R1L0, L0R1]
+ *
+ * For proper React rendering, we need bottom-to-top (leaf → root):
+ * - Innermost content (route) wraps inside layouts
+ * - Each layer provides context via OutletProvider
+ * - Outer layouts receive inner content via <Outlet />
+ *
+ * Parallel segments must be matched to their parent by ID prefix:
+ * - "L0R1L0.@sidebar" belongs to "L0R1L0"
+ * - Pre-grouping prevents parallels from attaching to wrong parents
+ *   during the reversed iteration (which would cause "L0R1L0.@sidebar"
+ *   to incorrectly attach to "L0L0" instead of "L0R1L0")
+ *
+ * Loader segments are also grouped by parent:
+ * - "L0D0.cart" belongs to "L0"
+ * - Loaders don't render directly, their data is passed to context
+ *
+ * Intercept segments are passed separately for explicit handling:
+ * - They are injected into the correct parent's parallel array
+ * - This makes the flow clearer than relying on ID pattern matching
+ *
+ * @param segments - Main segments from the route tree
+ * @param interceptSegments - Optional intercept segments to inject
+ */
+function* segmentTreeWalk(
+  segments: ResolvedSegment[],
+  interceptSegments?: ResolvedSegment[],
+): Generator<{
+  segment: ResolvedSegment;
+  parallel: ResolvedSegment[];
+  loaders: ResolvedSegment[];
+}> {
+  // Pre-group parallel and loader segments by their parent ID using prefix matching
+  // This ensures each parallel/loader is associated with the correct parent segment
+  // regardless of the iteration order
+  const parallelsByParent = new Map<string, ResolvedSegment[]>();
+  const loadersByParent = new Map<string, ResolvedSegment[]>();
+  const nonParallels: ResolvedSegment[] = [];
+
+  for (const segment of segments) {
+    if (segment.type === "parallel") {
+      // Extract parent ID from parallel ID
+      // Example: "L0R1L0.@sidebar" → "L0R1L0"
+      const parentId = segment.id.split(".")[0];
+      if (!parallelsByParent.has(parentId)) {
+        parallelsByParent.set(parentId, []);
+      }
+      parallelsByParent.get(parentId)!.push(segment);
+    } else if (segment.type === "loader") {
+      // Extract parent ID from loader ID
+      // Example: "L0D0.cart" → "L0"
+      // Loader ID format: {parentShortCode}D{index}.{loaderId}
+      const parentId = segment.id.split("D")[0];
+      if (!loadersByParent.has(parentId)) {
+        loadersByParent.set(parentId, []);
+      }
+      loadersByParent.get(parentId)!.push(segment);
+    } else {
+      // Layout, route, error, and notFound segments are all rendered in the tree
+      // Error/notFound segments replace the failed segment with fallback UI
+      nonParallels.push(segment);
+    }
+  }
+
+  // INTERCEPT SEGMENTS: Explicitly inject into parent's parallel array
+  // Intercept segments are passed separately for explicit handling
+  if (interceptSegments && interceptSegments.length > 0) {
+    for (const intercept of interceptSegments) {
+      if (intercept.type === "parallel" && intercept.slot) {
+        // Extract parent ID from intercept ID (e.g., "M4L0L0L2.@modal" → "M4L0L0L2")
+        const parentId = intercept.id.split(".")[0];
+        if (!parallelsByParent.has(parentId)) {
+          parallelsByParent.set(parentId, []);
+        }
+        parallelsByParent.get(parentId)!.push(intercept);
+      } else if (intercept.type === "loader") {
+        // Intercept loaders - extract parent from loader ID
+        const parentId = intercept.id.split("D")[0];
+        if (!loadersByParent.has(parentId)) {
+          loadersByParent.set(parentId, []);
+        }
+        loadersByParent.get(parentId)!.push(intercept);
+      }
+    }
+  }
+
+  // Sort segments by ID to ensure consistent root-to-leaf ordering
+  // regardless of the order they arrive in the input array (which can differ
+  // between document requests and actions)
+  // Shorter IDs come first (closer to root), same length sorted lexicographically
+  nonParallels.sort((a, b) => {
+    if (a.id.length !== b.id.length) {
+      return a.id.length - b.id.length;
+    }
+    return a.id.localeCompare(b.id);
+  });
+
+  // Iterate bottom-to-top using reverse() to process leaf segments first
+  // This processes route/leaf layouts first, then parent layouts
+  // Note: We reverse the array to iterate from end to start (bottom-to-top)
+  for (let i = nonParallels.length - 1; i >= 0; i--) {
+    const segment = nonParallels[i];
+
+    // Lookup parallels and loaders that belong to this segment by ID prefix
+    const parallel = parallelsByParent.get(segment.id) || [];
+    const loaders = loadersByParent.get(segment.id) || [];
+
+    // Also include loaders from parallel segments (e.g., intercept loaders)
+    // These have parent IDs like "M9L0L1.@modal" which match the parallel segment ID
+    for (const p of parallel) {
+      const parallelLoaders = loadersByParent.get(p.id);
+      if (parallelLoaders) {
+        loaders.push(...parallelLoaders);
+      }
+    }
+
+    yield { segment, parallel, loaders };
+  }
+}

package/src/server/__tests__/request-context.test.ts

@@ -0,0 +1,171 @@
+/**
+ * Tests for RequestContext, specifically the onResponse callback API
+ */
+import { describe, it, expect, beforeEach } from "vitest";
+import {
+  createRequestContext,
+  runWithRequestContext,
+  getRequestContext,
+} from "../request-context.js";
+
+describe("RequestContext", () => {
+  describe("onResponse", () => {
+    it("should register callbacks", () => {
+      const ctx = createRequestContext({
+        env: {},
+        request: new Request("https://example.com"),
+        url: new URL("https://example.com"),
+        variables: {},
+      });
+
+      expect(ctx._onResponseCallbacks).toHaveLength(0);
+
+      ctx.onResponse((res) => res);
+      expect(ctx._onResponseCallbacks).toHaveLength(1);
+
+      ctx.onResponse((res) => res);
+      expect(ctx._onResponseCallbacks).toHaveLength(2);
+    });
+
+    it("should allow callbacks to inspect response status", () => {
+      const ctx = createRequestContext({
+        env: {},
+        request: new Request("https://example.com"),
+        url: new URL("https://example.com"),
+        variables: {},
+      });
+
+      let capturedStatus: number | undefined;
+
+      ctx.onResponse((res) => {
+        capturedStatus = res.status;
+        return res;
+      });
+
+      // Simulate calling the callback
+      const response = new Response("OK", { status: 200 });
+      for (const callback of ctx._onResponseCallbacks) {
+        callback(response);
+      }
+
+      expect(capturedStatus).toBe(200);
+    });
+
+    it("should allow callbacks to modify response", () => {
+      const ctx = createRequestContext({
+        env: {},
+        request: new Request("https://example.com"),
+        url: new URL("https://example.com"),
+        variables: {},
+      });
+
+      ctx.onResponse((res) => {
+        // Return a new response with added header
+        const newHeaders = new Headers(res.headers);
+        newHeaders.set("X-Modified", "true");
+        return new Response(res.body, {
+          status: res.status,
+          headers: newHeaders,
+        });
+      });
+
+      let response = new Response("OK", { status: 200 });
+      for (const callback of ctx._onResponseCallbacks) {
+        response = callback(response);
+      }
+
+      expect(response.headers.get("X-Modified")).toBe("true");
+    });
+
+    it("should run multiple callbacks in order", () => {
+      const ctx = createRequestContext({
+        env: {},
+        request: new Request("https://example.com"),
+        url: new URL("https://example.com"),
+        variables: {},
+      });
+
+      const order: number[] = [];
+
+      ctx.onResponse((res) => {
+        order.push(1);
+        return res;
+      });
+
+      ctx.onResponse((res) => {
+        order.push(2);
+        return res;
+      });
+
+      ctx.onResponse((res) => {
+        order.push(3);
+        return res;
+      });
+
+      let response = new Response("OK");
+      for (const callback of ctx._onResponseCallbacks) {
+        response = callback(response) ?? response;
+      }
+
+      expect(order).toEqual([1, 2, 3]);
+    });
+
+    it("should allow callbacks to chain modifications", () => {
+      const ctx = createRequestContext({
+        env: {},
+        request: new Request("https://example.com"),
+        url: new URL("https://example.com"),
+        variables: {},
+      });
+
+      ctx.onResponse((res) => {
+        const newHeaders = new Headers(res.headers);
+        newHeaders.set("X-First", "1");
+        return new Response(res.body, { status: res.status, headers: newHeaders });
+      });
+
+      ctx.onResponse((res) => {
+        const newHeaders = new Headers(res.headers);
+        newHeaders.set("X-Second", "2");
+        return new Response(res.body, { status: res.status, headers: newHeaders });
+      });
+
+      let response = new Response("OK");
+      for (const callback of ctx._onResponseCallbacks) {
+        response = callback(response) ?? response;
+      }
+
+      expect(response.headers.get("X-First")).toBe("1");
+      expect(response.headers.get("X-Second")).toBe("2");
+    });
+
+    it("should be accessible via getRequestContext", () => {
+      const ctx = createRequestContext({
+        env: {},
+        request: new Request("https://example.com"),
+        url: new URL("https://example.com"),
+        variables: {},
+      });
+
+      let callbackCalled = false;
+
+      runWithRequestContext(ctx, () => {
+        const currentCtx = getRequestContext();
+        currentCtx?.onResponse((res) => {
+          callbackCalled = true;
+          return res;
+        });
+      });
+
+      expect(ctx._onResponseCallbacks).toHaveLength(1);
+
+      // Trigger callback
+      const response = new Response("OK");
+      for (const callback of ctx._onResponseCallbacks) {
+        callback(response);
+      }
+
+      expect(callbackCalled).toBe(true);
+    });
+  });
+});