@rangojs/router 0.0.0-experimental.3 → 0.0.0-experimental.30

package/src/search-params.ts

@@ -0,0 +1,230 @@
+/**
+ * Search parameter schema types and runtime utilities.
+ *
+ * Provides a lightweight schema system for typed query parameters.
+ * When a route defines a `search` schema, ctx.search provides a typed
+ * object with parsed values. ctx.searchParams always remains a standard
+ * URLSearchParams instance.
+ */
+
+// ============================================================================
+// Schema Types
+// ============================================================================
+
+/** Supported scalar types for search params (append ? for optional). */
+export type SearchSchemaValue =
+  | "string"
+  | "number"
+  | "boolean"
+  | "string?"
+  | "number?"
+  | "boolean?";
+
+/** A search schema maps param names to their type descriptors. */
+export type SearchSchema = Record<string, SearchSchemaValue>;
+
+// ============================================================================
+// Type-Level Schema Resolution
+// ============================================================================
+
+/** Strip trailing `?` from a schema value to get the base type. */
+type BaseType<T extends string> = T extends `${infer B}?` ? B : T;
+
+/** Map a base type string to its TypeScript type. */
+type ResolveBaseType<T extends string> = T extends "string"
+  ? string
+  : T extends "number"
+    ? number
+    : T extends "boolean"
+      ? boolean
+      : never;
+
+/** Keys whose schema value does NOT end with `?`. */
+type RequiredKeys<T extends SearchSchema> = {
+  [K in keyof T]: T[K] extends `${string}?` ? never : K;
+}[keyof T];
+
+/** Keys whose schema value ends with `?`. */
+type OptionalKeys<T extends SearchSchema> = {
+  [K in keyof T]: T[K] extends `${string}?` ? K : never;
+}[keyof T];
+
+/** Flatten an intersection type into a single object type. */
+type Simplify<T> = { [K in keyof T]: T[K] };
+
+/**
+ * Resolve a SearchSchema to its typed object.
+ *
+ * Both required and optional params resolve to `T | undefined` at the handler
+ * level. The required/optional distinction is a consumer-facing contract
+ * (e.g., for href() and reverse() autocomplete) — it tells callers which
+ * params the route expects, but the handler must still check for undefined
+ * since the framework cannot trust the client to send all required params.
+ *
+ * @example
+ * type S = { q: "string"; page: "number?"; sort: "string?" };
+ * type R = ResolveSearchSchema<S>;
+ * // { q: string | undefined; page?: number; sort?: string }
+ */
+export type ResolveSearchSchema<T extends SearchSchema> = Simplify<
+  {
+    [K in RequiredKeys<T> & string]:
+      | ResolveBaseType<BaseType<T[K]>>
+      | undefined;
+  } & {
+    [K in OptionalKeys<T> & string]?: ResolveBaseType<BaseType<T[K]>>;
+  }
+>;
+
+// ============================================================================
+// Route-Level Type Extraction
+// ============================================================================
+
+/** Resolve the global route map from RegisteredRoutes or GeneratedRouteMap. */
+type GlobalRouteMap = keyof RSCRouter.RegisteredRoutes extends never
+  ? keyof RSCRouter.GeneratedRouteMap extends never
+    ? Record<string, string>
+    : RSCRouter.GeneratedRouteMap
+  : RSCRouter.RegisteredRoutes;
+
+/**
+ * Extract the resolved search params type for a named route.
+ * Looks up the search schema from the route map and resolves it.
+ *
+ * @example
+ * ```typescript
+ * // Given: path("/search", handler, { name: "search", search: { q: "string", page: "number?" } })
+ * type Params = RouteSearchParams<"search">;
+ * // { q: string; page?: number }
+ * ```
+ */
+export type RouteSearchParams<TName extends string, TRouteMap = never> = [
+  TRouteMap,
+] extends [never]
+  ? ExtractAndResolveSearch<GlobalRouteMap, TName>
+  : ExtractAndResolveSearch<TRouteMap, TName>;
+
+type ExtractAndResolveSearch<TRouteMap, TName> = TName extends keyof TRouteMap
+  ? TRouteMap[TName] extends { readonly search: infer S extends SearchSchema }
+    ? ResolveSearchSchema<S>
+    : {}
+  : {};
+
+/**
+ * Extract the route params type for a named route.
+ * Looks up the path pattern from the route map and extracts params.
+ *
+ * @example
+ * ```typescript
+ * // Given: path("/blog/:slug", handler, { name: "blogPost" })
+ * type Params = RouteParams<"blogPost">;
+ * // { slug: string }
+ * ```
+ */
+export type RouteParams<TName extends string, TRouteMap = never> = [
+  TRouteMap,
+] extends [never]
+  ? ExtractRouteParamsFromMap<GlobalRouteMap, TName>
+  : ExtractRouteParamsFromMap<TRouteMap, TName>;
+
+type ExtractRouteParamsFromMap<TRouteMap, TName> = TName extends keyof TRouteMap
+  ? TRouteMap[TName] extends string
+    ? ExtractParamsFromPattern<TRouteMap[TName]>
+    : TRouteMap[TName] extends { readonly path: infer P extends string }
+      ? ExtractParamsFromPattern<P>
+      : {}
+  : {};
+
+/** Parse "a|b|c" into "a" | "b" | "c" */
+type ParseConstraint<T extends string> =
+  T extends `${infer First}|${infer Rest}` ? First | ParseConstraint<Rest> : T;
+
+/** Minimal inline param extraction (avoids importing from types.ts to prevent circular deps). */
+type ExtractParamsFromPattern<T extends string> =
+  T extends `${string}:${infer Param}/${infer Rest}`
+    ? Param extends `${infer Name}(${infer C})?`
+      ? {
+          [K in Name]?: ParseConstraint<C>;
+        } & ExtractParamsFromPattern<`/${Rest}`>
+      : Param extends `${infer Name}(${infer C})`
+        ? {
+            [K in Name]: ParseConstraint<C>;
+          } & ExtractParamsFromPattern<`/${Rest}`>
+        : Param extends `${infer Name}?`
+          ? { [K in Name]?: string } & ExtractParamsFromPattern<`/${Rest}`>
+          : { [K in Param]: string } & ExtractParamsFromPattern<`/${Rest}`>
+    : T extends `${string}:${infer Param}`
+      ? Param extends `${infer Name}(${infer C})?`
+        ? { [K in Name]?: ParseConstraint<C> }
+        : Param extends `${infer Name}(${infer C})`
+          ? { [K in Name]: ParseConstraint<C> }
+          : Param extends `${infer Name}?`
+            ? { [K in Name]?: string }
+            : { [K in Param]: string }
+      : {};
+
+// ============================================================================
+// Runtime Parser
+// ============================================================================
+
+/**
+ * Parse URLSearchParams into a typed object using the given schema.
+ *
+ * - `"string"` / `"string?"` - kept as-is
+ * - `"number"` / `"number?"` - coerced via `Number()`; NaN treated as missing
+ * - `"boolean"` / `"boolean?"` - `"true"` / `"1"` -> true, `"false"` / `"0"` / `""` -> false
+ *
+ * Missing params (both required and optional) are omitted from the result
+ * (undefined). The required/optional distinction is a consumer-facing contract
+ * only — the handler must check for undefined.
+ */
+export function parseSearchParams<T extends SearchSchema>(
+  searchParams: URLSearchParams,
+  schema: T,
+): ResolveSearchSchema<T> {
+  const result: Record<string, unknown> = {};
+
+  for (const [key, descriptor] of Object.entries(schema)) {
+    const isOptional = descriptor.endsWith("?");
+    const baseType = isOptional ? descriptor.slice(0, -1) : descriptor;
+    const raw = searchParams.get(key);
+
+    if (raw === null) {
+      // Missing params are omitted (undefined) regardless of required/optional
+      continue;
+    }
+
+    if (baseType === "string") {
+      result[key] = raw;
+    } else if (baseType === "number") {
+      const num = Number(raw);
+      if (!Number.isNaN(num)) {
+        result[key] = num;
+      }
+      // NaN treated as missing (undefined)
+    } else if (baseType === "boolean") {
+      result[key] = raw === "true" || raw === "1";
+    }
+  }
+
+  return result as ResolveSearchSchema<T>;
+}
+
+// ============================================================================
+// Runtime Serializer
+// ============================================================================
+
+/**
+ * Serialize a typed search params object to a query string (without leading `?`).
+ * Skips `undefined` and `null` values.
+ */
+export function serializeSearchParams(params: Record<string, unknown>): string {
+  const parts: string[] = [];
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || value === null) continue;
+    parts.push(
+      `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`,
+    );
+  }
+  return parts.join("&");
+}

package/src/segment-system.tsx

@@ -1,6 +1,7 @@
+import * as React from "react";
 import { createElement, type ReactNode, type ComponentType } from "react";
 import { OutletProvider } from "./client.js";
-import { HrefProvider } from "./browser/react/use-href.js";
+import { MountContextProvider } from "./browser/react/mount-context.js";
 import type {
   ResolvedSegment,
   LoaderDataResult,
@@ -14,6 +15,11 @@ import {
 } from "./route-content-wrapper.js";
 import { RootErrorBoundary } from "./root-error-boundary.js";
 
+// ViewTransition is only available in React experimental.
+// Access via namespace import to avoid compile-time errors on stable React.
+const ReactViewTransition: any =
+  "ViewTransition" in React ? (React as any).ViewTransition : null;
+
 /**
  * Resolve loader data from raw results, unwrapping LoaderDataResult wrappers
  */
@@ -84,18 +90,6 @@ export interface RenderSegmentsOptions {
    * 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;
 }
 
 /**
@@ -146,9 +140,8 @@ export async function renderSegments(
     interceptSegments,
     forceAwait,
     rootLayout: RootLayout,
-    routeMap,
-    routeName,
   } = options || {};
+
   const temporalLazyRefs: Promise<any>[] = [];
 
   /**
@@ -221,8 +214,9 @@ export async function renderSegments(
     if (isAction && component instanceof Promise) {
       resolvedComponent = await component;
     }
+
     let nodeContent: ReactNode =
-      loading || loading === null || resolvedComponent instanceof Promise
+      loading !== null && loading !== undefined && loading !== false
         ? createElement(RouteContentWrapper, {
             key: `suspense-loading-${id}`,
             content:
@@ -230,9 +224,22 @@ export async function renderSegments(
                 ? resolvedComponent
                 : Promise.resolve(resolvedComponent),
             fallback: loading,
+            segmentId: id,
           })
         : registerLazyRef(resolvedComponent);
 
+    // Wrap with <ViewTransition> if transition config exists (React experimental only).
+    // An empty config ({}) creates a bare <ViewTransition> boundary that participates
+    // in transitions without adding custom animation classes. Named element-level
+    // <ViewTransition> components inside (with name/share props) morph independently
+    // from the parent's default cross-fade.
+    if (ReactViewTransition && node.segment.transition) {
+      nodeContent = createElement(ReactViewTransition, {
+        ...node.segment.transition,
+        children: nodeContent,
+      });
+    }
+
     // Common props for OutletProvider
     const outletContent: ReactNode =
       node.segment.type === "layout" ? content : null;
@@ -254,7 +261,7 @@ export async function renderSegments(
     // 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) {
+    if (loading !== undefined && loading !== null) {
       content = createElement(LoaderBoundary, {
         key: `loader-boundary-${key}`,
         loaderDataPromise:
@@ -267,11 +274,7 @@ export async function renderSegments(
         parallel: node.parallel,
         children: nodeContent,
       });
-      continue;
-    }
-
-    // No loading skeleton defined - use OutletProvider directly
-    if (loaderEntries.length === 0) {
+    } else if (loaderEntries.length === 0) {
       // No loaders, no loading - simple OutletProvider
       content = createElement(OutletProvider, {
         key,
@@ -280,24 +283,34 @@ export async function renderSegments(
         parallel: node.parallel,
         children: nodeContent,
       });
-      continue;
-    }
+    } else {
+      // Has loaders but no loading skeleton - await loaders and render directly
+      const resolvedData = await loaderDataPromise;
+      const { loaderData, errorFallback } = resolveLoaderData(
+        resolvedData,
+        loaderIds,
+      );
 
-    // 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,
+      });
+    }
 
-    content = createElement(OutletProvider, {
-      key,
-      content: outletContent,
-      segment: node.segment,
-      parallel: node.parallel,
-      loaderData: Object.keys(loaderData).length > 0 ? loaderData : undefined,
-      children: errorFallback ?? nodeContent,
-    });
+    // Wrap with MountContextProvider for include() scoped components.
+    // Must use MountContextProvider (a proper "use client" export) instead of
+    // MountContext.Provider directly, because .Provider is a property on the
+    // context object and resolves to undefined through RSC client reference proxies.
+    if (node.segment.mountPath) {
+      content = createElement(MountContextProvider, {
+        value: node.segment.mountPath,
+        children: content,
+      });
+    }
   }
 
   // Always wrap with root error boundary to prevent white screens
@@ -305,7 +318,7 @@ export async function renderSegments(
   const errorBoundaryWrapped = createElement(RootErrorBoundary, {
     children: content,
   });
-  if (typeof window === "object" || typeof document === "object") {
+  if (typeof window === "object") {
     await Promise.allSettled(temporalLazyRefs);
   }
 
@@ -320,16 +333,6 @@ export async function renderSegments(
     });
   }
 
-  // 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;
 }
 
@@ -423,20 +426,13 @@ function* segmentTreeWalk(
     }
   }
 
-  // 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
+  // Segments arrive in root-to-leaf order from the server (resolveSegment
+  // and resolveSegmentWithRevalidation push segments in this order).
+  // All consumers (reconcileSegments, cache) preserve this order.
+  // No sorting needed — iterate bottom-to-top 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];