@rangojs/router 0.0.0-experimental.124 → 0.0.0-experimental.125

package/src/theme/constants.ts

@@ -4,9 +4,6 @@
 
 import type { ResolvedThemeConfig, ThemeConfig } from "./types.js";
 
-/**
- * Default theme configuration values
- */
 export const THEME_DEFAULTS = {
   defaultTheme: "system",
   themes: ["light", "dark"],
@@ -16,9 +13,6 @@ export const THEME_DEFAULTS = {
   enableColorScheme: true,
 } as const;
 
-/**
- * Cookie configuration for theme persistence
- */
 export const THEME_COOKIE: {
   readonly maxAge: number;
   readonly path: string;
@@ -29,21 +23,15 @@ export const THEME_COOKIE: {
   sameSite: "lax",
 };
 
-/**
- * Resolve theme config by applying defaults.
- * Accepts `true` to enable with all defaults, or a config object.
- */
 export function resolveThemeConfig(
   config: ThemeConfig | true,
 ): ResolvedThemeConfig {
-  // Handle `theme: true` shorthand
   if (config === true) {
     config = {};
   }
 
   const themes = config.themes ?? [...THEME_DEFAULTS.themes];
 
-  // Build value mapping - default to identity mapping
   const value: Record<string, string> = {};
   for (const theme of themes) {
     value[theme] = config.value?.[theme] ?? theme;

package/src/theme/index.ts

@@ -23,16 +23,10 @@
  * ```
  */
 
-// Main hook for accessing theme
 export { useTheme } from "./use-theme.js";
-
-// Provider (typically auto-included via NavigationProvider when theme is enabled)
 export { ThemeProvider } from "./ThemeProvider.js";
-
-// Script component for FOUC prevention (use in document head)
 export { ThemeScript, type ThemeScriptProps } from "./ThemeScript.js";
 
-// Types
 export type {
   Theme,
   ResolvedTheme,
@@ -44,5 +38,4 @@ export type {
   ThemeContextValue,
 } from "./types.js";
 
-// Constants
 export { THEME_DEFAULTS, THEME_COOKIE } from "./constants.js";

package/src/theme/theme-context.ts

@@ -19,17 +19,13 @@ import type { ThemeContextValue } from "./types.js";
 export const ThemeContext: Context<ThemeContextValue | null> =
   createContext<ThemeContextValue | null>(null);
 
-/**
- * Get theme context (internal use)
- * Returns null if theme is not enabled
- */
 export function useThemeContext(): ThemeContextValue | null {
   return useContext(ThemeContext);
 }
 
 /**
  * Get theme context, throwing if not available
- * Use this in useTheme hook
+ * Used by useTheme hook
  */
 export function requireThemeContext(): ThemeContextValue {
   const ctx = useContext(ThemeContext);

package/src/theme/theme-script.ts

@@ -22,7 +22,6 @@ import type { ResolvedThemeConfig } from "./types.js";
  * - Handle all edge cases (no localStorage, no cookie, etc.)
  */
 export function generateThemeScript(config: ResolvedThemeConfig): string {
-  // Build the script as a string, then minify
   const script = `
 (function() {
   var storageKey = ${JSON.stringify(config.storageKey)};
@@ -33,9 +32,7 @@ export function generateThemeScript(config: ResolvedThemeConfig): string {
   var valueMap = ${JSON.stringify(config.value)};
   var themes = ${JSON.stringify(config.themes)};
 
-  // Read theme from cookie or localStorage
   function getStoredTheme() {
-    // Try cookie first (for SSR consistency)
     var cookies = document.cookie.split(';');
     for (var i = 0; i < cookies.length; i++) {
       var cookie = cookies[i].trim();
@@ -44,7 +41,6 @@ export function generateThemeScript(config: ResolvedThemeConfig): string {
         catch (e) { return cookie.substring(storageKey.length + 1); }
       }
     }
-    // Fall back to localStorage
     try {
       return localStorage.getItem(storageKey);
     } catch (e) {
@@ -52,7 +48,6 @@ export function generateThemeScript(config: ResolvedThemeConfig): string {
     }
   }
 
-  // Get system preference
   function getSystemTheme() {
     if (typeof window !== 'undefined' && window.matchMedia) {
       return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
@@ -60,7 +55,6 @@ export function generateThemeScript(config: ResolvedThemeConfig): string {
     return 'light';
   }
 
-  // Resolve "system" to actual theme
   function resolveTheme(theme) {
     if (theme === 'system' && enableSystem) {
       return getSystemTheme();
@@ -68,15 +62,12 @@ export function generateThemeScript(config: ResolvedThemeConfig): string {
     return theme;
   }
 
-  // Apply theme to HTML element
   function applyTheme(theme) {
     var resolved = resolveTheme(theme);
     var value = valueMap[resolved] || resolved;
     var el = document.documentElement;
 
-    // Apply attribute
     if (attribute === 'class') {
-      // Remove all theme classes, then add current
       for (var i = 0; i < themes.length; i++) {
         var v = valueMap[themes[i]] || themes[i];
         el.classList.remove(v);
@@ -86,22 +77,18 @@ export function generateThemeScript(config: ResolvedThemeConfig): string {
       el.setAttribute(attribute, value);
     }
 
-    // Set color-scheme for native dark mode support
     if (enableColorScheme) {
       el.style.colorScheme = resolved;
     }
   }
 
-  // Get stored theme or use default
   var stored = getStoredTheme();
   var theme = stored && (stored === 'system' || themes.indexOf(stored) !== -1)
     ? stored
     : defaultTheme;
 
-  // Apply immediately
   applyTheme(theme);
 
-  // Listen for system preference changes (for "system" theme)
   if (enableSystem && typeof window !== 'undefined' && window.matchMedia) {
     try {
       window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', function() {
@@ -117,7 +104,6 @@ export function generateThemeScript(config: ResolvedThemeConfig): string {
 })();
 `;
 
-  // Minify by removing comments, extra whitespace, and newlines
   return minifyScript(script);
 }
 

package/src/theme/use-theme.ts

@@ -27,9 +27,6 @@ import type { UseThemeReturn } from "./types.js";
  *
  * Must be used within a ThemeProvider (which is automatically included
  * in NavigationProvider when theme is enabled in router config).
- *
- * @returns Theme state and methods
- * @throws Error if used outside ThemeProvider
  */
 export function useTheme(): UseThemeReturn {
   const ctx = requireThemeContext();

package/src/types/boundaries.ts

@@ -1,22 +1,12 @@
 import type { ReactNode } from "react";
 
-/**
- * Error information passed to error boundary fallback components
- */
 export interface ErrorInfo {
-  /** Error message (always available) */
   message: string;
-  /** Error name/type (e.g., "RouteNotFoundError", "MiddlewareError") */
   name: string;
-  /** Optional error code for programmatic handling */
   code?: string;
-  /** Stack trace (only in development) */
   stack?: string;
-  /** Original error cause if available */
   cause?: unknown;
-  /** Segment ID where the error occurred */
   segmentId: string;
-  /** Segment type where the error occurred */
   segmentType:
     | "layout"
     | "route"
@@ -46,13 +36,9 @@ export interface ErrorInfo {
  * ```
  */
 export interface ErrorBoundaryFallbackProps {
-  /** Error information */
   error: ErrorInfo;
 }
 
-/**
- * Error boundary handler - receives error info and returns fallback UI
- */
 export type ErrorBoundaryHandler = (
   props: ErrorBoundaryFallbackProps,
 ) => ReactNode;
@@ -77,17 +63,10 @@ export type ErrorBoundaryHandler = (
  * ```
  */
 export interface ClientErrorBoundaryFallbackProps {
-  /** Error information */
   error: ErrorInfo;
-  /** Function to reset error state and retry rendering */
   reset: () => void;
 }
 
-/**
- * Wrapped loader data result for deferred resolution with error handling.
- * When loaders are deferred to client-side resolution, errors need to be
- * wrapped so the client can handle them appropriately.
- */
 export type LoaderDataResult<T = unknown> =
   | { __loaderResult: true; ok: true; data: T }
   | {
@@ -97,9 +76,6 @@ export type LoaderDataResult<T = unknown> =
       fallback: ReactNode | null;
     };
 
-/**
- * Type guard to check if a value is a wrapped loader result
- */
 export function isLoaderDataResult(value: unknown): value is LoaderDataResult {
   return (
     typeof value === "object" &&
@@ -109,15 +85,9 @@ export function isLoaderDataResult(value: unknown): value is LoaderDataResult {
   );
 }
 
-/**
- * Not found information passed to notFound boundary fallback components
- */
 export interface NotFoundInfo {
-  /** Not found message */
   message: string;
-  /** Segment ID where notFound was thrown */
   segmentId: string;
-  /** Segment type where notFound was thrown */
   segmentType:
     | "layout"
     | "route"
@@ -125,7 +95,6 @@ export interface NotFoundInfo {
     | "loader"
     | "middleware"
     | "cache";
-  /** The pathname that triggered the not found */
   pathname?: string;
 }
 
@@ -146,13 +115,9 @@ export interface NotFoundInfo {
  * ```
  */
 export interface NotFoundBoundaryFallbackProps {
-  /** Not found information */
   notFound: NotFoundInfo;
 }
 
-/**
- * NotFound boundary handler - receives not found info and returns fallback UI
- */
 export type NotFoundBoundaryHandler = (
   props: NotFoundBoundaryFallbackProps,
 ) => ReactNode;

package/src/types/error-types.ts

@@ -14,19 +14,19 @@
  * - "unknown": Fallback for unclassified errors (not currently invoked)
  */
 export type ErrorPhase =
-  | "routing" // During route matching
-  | "manifest" // During manifest loading (reserved, not currently invoked)
-  | "middleware" // During middleware execution (errors propagate to handler phase)
-  | "loader" // During loader execution
-  | "handler" // During route/layout handler execution
-  | "rendering" // During RSC/SSR rendering (SSR handler uses separate callback)
-  | "action" // During server action execution
-  | "revalidation" // During revalidation evaluation
-  | "cache" // During "use cache" background operations (stale revalidation, async cache writes)
-  | "prerender" // During build-time pre-rendering (Vite closeBundle)
-  | "static" // During build-time static handler rendering (Vite closeBundle)
-  | "origin" // During cross-origin request validation (CSRF protection)
-  | "unknown"; // Fallback for unclassified errors
+  | "routing"
+  | "manifest"
+  | "middleware"
+  | "loader"
+  | "handler"
+  | "rendering"
+  | "action"
+  | "revalidation"
+  | "cache"
+  | "prerender"
+  | "static"
+  | "origin"
+  | "unknown";
 
 /**
  * Comprehensive context passed to onError callback
@@ -59,99 +59,35 @@ export type ErrorPhase =
  * ```
  */
 export interface OnErrorContext<TEnv = any> {
-  /**
-   * The error that occurred
-   */
   error: Error;
-
-  /**
-   * Phase where the error occurred
-   */
   phase: ErrorPhase;
-
-  /**
-   * The original request
-   */
   request: Request;
-
-  /**
-   * Parsed URL from the request
-   */
   url: URL;
-
-  /**
-   * Request pathname
-   */
   pathname: string;
-
-  /**
-   * HTTP method
-   */
   method: string;
-
-  /**
-   * Matched route key (if available)
-   * e.g., "shop.products.detail"
-   */
+  /** Matched route key (if available) e.g., "shop.products.detail" */
   routeKey?: string;
-
-  /**
-   * Route params (if available)
-   * e.g., { slug: "headphones" }
-   */
+  /** Route params (if available) e.g., { slug: "headphones" } */
   params?: Record<string, string>;
-
-  /**
-   * Segment ID where error occurred (if available)
-   * e.g., "M1L0" for a layout, "M1R0" for a route
-   */
+  /** Segment ID where error occurred (if available) e.g., "M1L0" for a layout, "M1R0" for a route */
   segmentId?: string;
-
-  /**
-   * Segment type where error occurred (if available)
-   */
+  /** Segment type where error occurred (if available) */
   segmentType?: "layout" | "route" | "parallel" | "loader" | "middleware";
-
-  /**
-   * Loader name (if error occurred in a loader)
-   */
+  /** Loader name (if error occurred in a loader) */
   loaderName?: string;
-
-  /**
-   * Middleware name/id (if error occurred in middleware)
-   */
+  /** Middleware name/id (if error occurred in middleware) */
   middlewareId?: string;
-
-  /**
-   * Action ID (if error occurred during server action)
-   * e.g., "src/actions.ts#addToCart"
-   */
+  /** Action ID (if error occurred during server action) e.g., "src/actions.ts#addToCart" */
   actionId?: string;
-
-  /**
-   * Environment/bindings (platform context)
-   */
+  /** Environment/bindings (platform context) */
   env?: TEnv;
-
-  /**
-   * Duration from request start to error (milliseconds)
-   */
+  /** Duration from request start to error (milliseconds) */
   duration?: number;
-
-  /**
-   * Whether this is a partial/navigation request
-   */
+  /** Whether this is a partial/navigation request */
   isPartial?: boolean;
-
-  /**
-   * Whether an error boundary caught the error
-   * If true, the error was handled and a fallback UI was rendered
-   */
+  /** Whether an error boundary caught the error */
   handledByBoundary?: boolean;
-
-  /**
-   * Stack trace (if available)
-   */
+  /** Stack trace (if available) */
   stack?: string;
 
   /**

package/src/types/global-namespace.ts

@@ -20,26 +20,16 @@
 declare global {
   namespace Rango {
     // eslint-disable-next-line @typescript-eslint/no-empty-interface
-    interface Env {
-      // Empty by default - users augment with their bindings (e.g., { DB: D1Database })
-    }
+    interface Env {}
 
     // eslint-disable-next-line @typescript-eslint/no-empty-interface
-    interface Vars {
-      // Empty by default - users augment with their variables (e.g., { user?: User })
-    }
+    interface Vars {}
 
     // eslint-disable-next-line @typescript-eslint/no-empty-interface
-    interface RegisteredRoutes {
-      // Empty by default - users augment with their merged route maps for type-safe href()
-      // Values are string (pattern) for RSC routes, or { path: string; response: T } for response routes
-    }
+    interface RegisteredRoutes {}
 
     // eslint-disable-next-line @typescript-eslint/no-empty-interface
-    interface GeneratedRouteMap {
-      // Empty by default - populated by generated named-routes.gen.ts
-      // Maps route names to URL pattern strings for Handler<"routeName"> support
-    }
+    interface GeneratedRouteMap {}
   }
 }
 

package/src/types/handler-context.ts

@@ -107,14 +107,6 @@ type StrictLocalParamsWithExtras<TEntry> =
     ? Record<string, string>
     : ExtractParamsFromEntry<TEntry, {}> & Record<string, string>;
 
-// HandlerContext.reverse is the only reverse surface with runtime param autofill
-// from the current matched request. Middleware/loaders/request context do not
-// have the same local-route guarantees, so they keep plain ScopedReverseFunction.
-//
-// When a handler has an explicit local route map, enforce that local route
-// params declared by that map are present while still allowing extra mount
-// params to be passed through. Global names remain autofill-friendly because
-// parent include() params are often unknown at the module definition site.
 type StrictLocalAutofillGlobalReverseFunction<TLocalRoutes, TGlobalRoutes> =
   ScopedReverseFunction<TLocalRoutes, TGlobalRoutes> & {
     <TName extends keyof TGlobalRoutes & string>(

package/src/types/index.ts

@@ -1,14 +1,11 @@
-// Global namespace (must be imported for side effects: `declare global`)
 export type {
   GetRegisteredRoutes,
   DefaultHandlerRouteMap,
   DefaultReverseRouteMap,
   DefaultEnv,
 } from "./global-namespace.js";
-// Ensure the global namespace declaration is evaluated
 import "./global-namespace.js";
 
-// Route configuration
 export type {
   DocumentProps,
   ExtractParams,
@@ -19,7 +16,6 @@ export type {
   ResolvedRouteMap,
 } from "./route-config.js";
 
-// Boundaries (error/notFound)
 export type {
   ErrorInfo,
   ErrorBoundaryFallbackProps,
@@ -32,7 +28,6 @@ export type {
 } from "./boundaries.js";
 export { isLoaderDataResult } from "./boundaries.js";
 
-// Handler context and related types
 export type {
   MiddlewareFn,
   ScopedRouteMap,
@@ -50,7 +45,6 @@ export type {
   Middleware,
 } from "./handler-context.js";
 
-// Segments
 export type {
   ViewTransitionClass,
   TransitionConfig,
@@ -61,10 +55,8 @@ export type {
   MatchResult,
 } from "./segments.js";
 
-// Route entries
 export type { LazyIncludeContext, RouteEntry } from "./route-entry.js";
 
-// Loader types
 export type {
   LoaderContext,
   LoaderFn,
@@ -73,7 +65,6 @@ export type {
   LoaderDefinition,
 } from "./loader-types.js";
 
-// Cache types
 export type {
   CacheContext,
   CacheOptions,
@@ -81,7 +72,6 @@ export type {
   EntryCacheConfig,
 } from "./cache-types.js";
 
-// Error handling types
 export type {
   ErrorPhase,
   OnErrorContext,

package/src/types/request-scope.ts

@@ -1,22 +1,3 @@
-/**
- * RequestScope: the fields every user-facing context shares.
- *
- * A handler, middleware, loader, response handler, and the ALS-bound
- * RequestContext are all different phases of the same request, and they
- * all carry the same set of request-scoped capabilities: the raw Request,
- * the parsed URL pair (`url` is cleaned of internal `_rsc*` params,
- * `originalUrl` retains them), pathname/searchParams, platform bindings
- * (`env`), and two escape hatches for work that outlives the response
- * (`waitUntil`) or needs the raw Cloudflare runtime object
- * (`executionContext`).
- *
- * Each public context type intersects `RequestScope<TEnv>` with its own
- * phase-specific fields (e.g. `params`/`reverse` on HandlerContext,
- * `headers`/`header()` on MiddlewareContext). That keeps platform surface
- * in one place and lets the next runtime escape hatch we need land in
- * one file instead of four.
- */
-
 import type { DefaultEnv } from "./global-namespace.js";
 
 /**

package/src/types/route-config.ts

@@ -7,47 +7,24 @@ export type DocumentProps = {
   children: ReactNode;
 };
 
-/**
- * Parse constraint values into a union type
- * "a|b|c" -> "a" | "b" | "c"
- */
 type ParseConstraint<T extends string> =
   T extends `${infer First}|${infer Rest}` ? First | ParseConstraint<Rest> : T;
 
-/**
- * Extract param info from a param segment
- *
- * Handles:
- * - :param -> { name: "param", optional: false, type: string }
- * - :param? -> { name: "param", optional: true, type: string }
- * - :param(a|b) -> { name: "param", optional: false, type: "a" | "b" }
- * - :param(a|b)? -> { name: "param", optional: true, type: "a" | "b" }
- */
 type ExtractParamInfo<T extends string> =
-  // Optional + constrained (with optional suffix): :param(a|b)?suffix
   T extends `${infer Name}(${infer Constraint})?${string}`
     ? { name: Name; optional: true; type: ParseConstraint<Constraint> }
-    : // Constrained (with optional suffix): :param(a|b)suffix
-      T extends `${infer Name}(${infer Constraint})${string}`
+    : T extends `${infer Name}(${infer Constraint})${string}`
       ? { name: Name; optional: false; type: ParseConstraint<Constraint> }
-      : // Optional (with optional suffix): :param?suffix
-        T extends `${infer Name}?${string}`
+      : T extends `${infer Name}?${string}`
         ? { name: Name; optional: true; type: string }
-        : // Param with dot-suffix: :param.html
-          T extends `${infer Name}.${string}`
+        : T extends `${infer Name}.${string}`
           ? { name: Name; optional: false; type: string }
-          : // Param with dash-suffix: :param-slug
-            T extends `${infer Name}-${string}`
+          : T extends `${infer Name}-${string}`
             ? { name: Name; optional: false; type: string }
-            : // Param with tilde-suffix: :param~v2
-              T extends `${infer Name}~${string}`
+            : T extends `${infer Name}~${string}`
               ? { name: Name; optional: false; type: string }
-              : // Required: :param (no suffix)
-                { name: T; optional: false; type: string };
+              : { name: T; optional: false; type: string };
 
-/**
- * Build param object from info
- */
 type ParamFromInfo<Info> = Info extends {
   name: infer N extends string;
   optional: true;
@@ -62,10 +39,6 @@ type ParamFromInfo<Info> = Info extends {
     ? { [K in N]: V }
     : never;
 
-/**
- * Merge two param objects preserving optionality
- * Uses Pick to preserve the modifiers from source types
- */
 type MergeParams<A, B> = Pick<A, keyof A> & Pick<B, keyof B> extends infer O
   ? { [K in keyof O]: O[K] }
   : never;
@@ -109,17 +82,11 @@ export type ExtractParams<
  */
 export type TrailingSlashMode = "never" | "always" | "ignore";
 
-/**
- * Route configuration object (alternative to string path)
- */
 export type RouteConfig = {
   path: string;
   trailingSlash?: TrailingSlashMode;
 };
 
-/**
- * Route definition options (global defaults)
- */
 export type RouteDefinitionOptions = {
   trailingSlash?: TrailingSlashMode;
 };
@@ -128,11 +95,6 @@ export type RouteDefinition = {
   [key: string]: string | RouteConfig | RouteDefinition;
 };
 
-/**
- * Recursively flatten nested routes with depth limit to prevent infinite recursion
- * Transforms: { products: { detail: "/product/:slug" } } => { "products.detail": "/product/:slug" }
- * Also handles RouteConfig objects: { api: { path: "/api" } } => { "api": "/api" }
- */
 type FlattenRoutes<
   T extends RouteDefinition,
   Prefix extends string = "",
@@ -153,18 +115,12 @@ type FlattenRoutes<
             : never;
     }[keyof T];
 
-/**
- * Union to intersection helper
- */
 type UnionToIntersection<U> = (
   U extends unknown ? (k: U) => void : never
 ) extends (k: infer I) => void
   ? I
   : never;
 
-/**
- * Resolved route map - flattened route definitions with full paths
- */
 export type ResolvedRouteMap<T extends RouteDefinition> = UnionToIntersection<
   FlattenRoutes<T>
 >;