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

package/src/theme/ThemeProvider.tsx

@@ -28,9 +28,6 @@ import type {
 } from "./types.js";
 import { THEME_COOKIE } from "./constants.js";
 
-/**
- * Get system preference for color scheme
- */
 function getSystemTheme(): ResolvedTheme {
   if (typeof window !== "undefined" && window.matchMedia) {
     return window.matchMedia("(prefers-color-scheme: dark)").matches
@@ -40,9 +37,6 @@ function getSystemTheme(): ResolvedTheme {
   return "light";
 }
 
-/**
- * Read theme from cookie
- */
 function readThemeFromCookie(storageKey: string): string | null {
   if (typeof document === "undefined") return null;
 
@@ -61,9 +55,6 @@ function readThemeFromCookie(storageKey: string): string | null {
   return null;
 }
 
-/**
- * Read theme from localStorage
- */
 function readThemeFromStorage(storageKey: string): string | null {
   if (typeof localStorage === "undefined") return null;
 
@@ -74,9 +65,6 @@ function readThemeFromStorage(storageKey: string): string | null {
   }
 }
 
-/**
- * Write theme to cookie
- */
 function writeThemeToCookie(storageKey: string, theme: Theme): void {
   if (typeof document === "undefined") return;
 
@@ -85,9 +73,6 @@ function writeThemeToCookie(storageKey: string, theme: Theme): void {
   document.cookie = cookie;
 }
 
-/**
- * Write theme to localStorage
- */
 function writeThemeToStorage(storageKey: string, theme: Theme): void {
   if (typeof localStorage === "undefined") return;
 
@@ -98,9 +83,6 @@ function writeThemeToStorage(storageKey: string, theme: Theme): void {
   }
 }
 
-/**
- * Apply theme to HTML element
- */
 function applyThemeToDocument(theme: Theme, config: ResolvedThemeConfig): void {
   if (typeof document === "undefined") return;
 
@@ -112,40 +94,30 @@ function applyThemeToDocument(theme: Theme, config: ResolvedThemeConfig): void {
   const value = config.value[resolved] || resolved;
   const el = document.documentElement;
 
-  // Apply attribute
   if (config.attribute === "class") {
-    // Remove all theme classes
     for (const t of config.themes) {
       const v = config.value[t] || t;
       el.classList.remove(v);
     }
-    // Add current theme class
     el.classList.add(value);
   } else {
     el.setAttribute(config.attribute, value);
   }
 
-  // Set color-scheme for native dark mode support
   if (config.enableColorScheme) {
     el.style.colorScheme = resolved;
   }
 }
 
-/**
- * Get the resolved stored theme (validated against available themes)
- */
 function getStoredTheme(config: ResolvedThemeConfig): Theme {
   const { storageKey, themes, defaultTheme, enableSystem } = config;
 
-  // Try cookie first (for SSR consistency)
   let stored = readThemeFromCookie(storageKey);
 
-  // Fall back to localStorage
   if (!stored) {
     stored = readThemeFromStorage(storageKey);
   }
 
-  // Validate stored value
   if (stored) {
     if (stored === "system" && enableSystem) {
       return "system";
@@ -158,38 +130,26 @@ function getStoredTheme(config: ResolvedThemeConfig): Theme {
   return defaultTheme;
 }
 
-/**
- * ThemeProvider component
- *
- * Provides theme state to the component tree via context.
- * Handles theme persistence, system preference detection, and cross-tab sync.
- */
 export function ThemeProvider({
   config,
   initialTheme,
   children,
 }: ThemeProviderProps): React.ReactNode {
-  // Track mount state to avoid hydration mismatches
-  // During SSR and initial hydration, mounted is false
   const [mounted, setMounted] = useState(false);
 
-  // Initialize theme from prop, storage, or default
   const [theme, setThemeState] = useState<Theme>(() => {
     if (initialTheme) return initialTheme;
     if (typeof window === "undefined") return config.defaultTheme;
     return getStoredTheme(config);
   });
 
-  // Track system preference - use stable default during SSR
   const [systemTheme, setSystemTheme] = useState<ResolvedTheme>("light");
 
-  // Set mounted after hydration and detect actual system theme
   useEffect(() => {
     setMounted(true);
     setSystemTheme(getSystemTheme());
   }, []);
 
-  // Set theme and persist to storage
   const setTheme = useCallback(
     (newTheme: Theme) => {
       setThemeState(newTheme);
@@ -200,7 +160,6 @@ export function ThemeProvider({
     [config],
   );
 
-  // Listen for system preference changes
   useEffect(() => {
     if (!config.enableSystem) return;
     if (typeof window === "undefined" || !window.matchMedia) return;
@@ -211,13 +170,11 @@ export function ThemeProvider({
       const newSystemTheme = e.matches ? "dark" : "light";
       setSystemTheme(newSystemTheme);
 
-      // If current theme is "system", re-apply to update document
       if (theme === "system") {
         applyThemeToDocument("system", config);
       }
     };
 
-    // Modern browsers
     mediaQuery.addEventListener("change", handleChange);
 
     return () => {
@@ -225,7 +182,6 @@ export function ThemeProvider({
     };
   }, [config, theme]);
 
-  // Cross-tab synchronization via localStorage storage event
   useEffect(() => {
     if (typeof window === "undefined") return;
 
@@ -249,12 +205,8 @@ export function ThemeProvider({
     };
   }, [config]);
 
-  // Compute resolved theme
-  // During SSR (not mounted), use the initial theme or default to avoid hydration mismatch
   const resolvedTheme: ResolvedTheme = useMemo(() => {
     if (!mounted) {
-      // During SSR, return the initial theme if it's not "system", otherwise "light"
-      // The inline script will apply the correct class before hydration
       if (initialTheme && initialTheme !== "system") {
         return initialTheme as ResolvedTheme;
       }
@@ -266,7 +218,6 @@ export function ThemeProvider({
     return theme as ResolvedTheme;
   }, [theme, systemTheme, config.enableSystem, mounted, initialTheme]);
 
-  // Build themes list (include "system" if enabled)
   const themes = useMemo(() => {
     if (config.enableSystem) {
       return ["system", ...config.themes.filter((t) => t !== "system")];
@@ -274,14 +225,11 @@ export function ThemeProvider({
     return config.themes;
   }, [config.themes, config.enableSystem]);
 
-  // Context value
-  // During SSR (not mounted), return stable values to avoid hydration mismatch
   const contextValue: ThemeContextValue = useMemo(
     () => ({
       theme,
       setTheme,
       resolvedTheme,
-      // Return stable "light" for systemTheme during SSR - actual value updates after mount
       systemTheme: mounted ? systemTheme : "light",
       themes,
       config,

package/src/theme/ThemeScript.tsx

@@ -43,12 +43,6 @@ export interface ThemeScriptProps {
   nonce?: string;
 }
 
-/**
- * Server component that renders the theme initialization script.
- *
- * This renders a synchronous inline script that applies the theme
- * to the HTML element before React hydration, preventing FOUC.
- */
 export function ThemeScript({
   config,
   nonce,

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 {}
   }
 }