@rangojs/router 0.0.0-experimental.0b82333f

package/src/theme/ThemeProvider.tsx

@@ -0,0 +1,297 @@
+"use client";
+
+/**
+ * ThemeProvider - Client component that provides theme state and management.
+ *
+ * Features:
+ * - Syncs theme to cookie/localStorage
+ * - Detects system preference changes
+ * - Cross-tab synchronization via storage events
+ * - Updates HTML element attribute when theme changes
+ * - Handles SSR hydration by deferring system theme detection
+ */
+
+import React, {
+  useCallback,
+  useEffect,
+  useMemo,
+  useState,
+  useRef,
+} from "react";
+import { ThemeContext } from "./theme-context.js";
+import type {
+  ResolvedTheme,
+  ResolvedThemeConfig,
+  Theme,
+  ThemeContextValue,
+  ThemeProviderProps,
+} 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
+      ? "dark"
+      : "light";
+  }
+  return "light";
+}
+
+/**
+ * Read theme from cookie
+ */
+function readThemeFromCookie(storageKey: string): string | null {
+  if (typeof document === "undefined") return null;
+
+  const cookies = document.cookie.split(";");
+  for (const cookie of cookies) {
+    const [name, ...rest] = cookie.trim().split("=");
+    if (name === storageKey) {
+      const raw = rest.join("=");
+      try {
+        return decodeURIComponent(raw);
+      } catch {
+        return raw;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Read theme from localStorage
+ */
+function readThemeFromStorage(storageKey: string): string | null {
+  if (typeof localStorage === "undefined") return null;
+
+  try {
+    return localStorage.getItem(storageKey);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write theme to cookie
+ */
+function writeThemeToCookie(storageKey: string, theme: Theme): void {
+  if (typeof document === "undefined") return;
+
+  const value = encodeURIComponent(theme);
+  const cookie = `${storageKey}=${value}; Path=${THEME_COOKIE.path}; Max-Age=${THEME_COOKIE.maxAge}; SameSite=${THEME_COOKIE.sameSite}`;
+  document.cookie = cookie;
+}
+
+/**
+ * Write theme to localStorage
+ */
+function writeThemeToStorage(storageKey: string, theme: Theme): void {
+  if (typeof localStorage === "undefined") return;
+
+  try {
+    localStorage.setItem(storageKey, theme);
+  } catch {
+    // localStorage might be disabled or full
+  }
+}
+
+/**
+ * Apply theme to HTML element
+ */
+function applyThemeToDocument(theme: Theme, config: ResolvedThemeConfig): void {
+  if (typeof document === "undefined") return;
+
+  const resolved =
+    theme === "system" && config.enableSystem
+      ? getSystemTheme()
+      : (theme as ResolvedTheme);
+
+  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";
+    }
+    if (themes.includes(stored)) {
+      return stored as 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);
+      writeThemeToCookie(config.storageKey, newTheme);
+      writeThemeToStorage(config.storageKey, newTheme);
+      applyThemeToDocument(newTheme, config);
+    },
+    [config],
+  );
+
+  // Listen for system preference changes
+  useEffect(() => {
+    if (!config.enableSystem) return;
+    if (typeof window === "undefined" || !window.matchMedia) return;
+
+    const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
+
+    const handleChange = (e: MediaQueryListEvent) => {
+      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 () => {
+      mediaQuery.removeEventListener("change", handleChange);
+    };
+  }, [config, theme]);
+
+  // Cross-tab synchronization via localStorage storage event
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+
+    const handleStorageChange = (e: StorageEvent) => {
+      if (e.key !== config.storageKey) return;
+
+      const newTheme = e.newValue;
+      if (!newTheme) return;
+
+      // Validate and apply
+      if (newTheme === "system" || config.themes.includes(newTheme)) {
+        setThemeState(newTheme as Theme);
+        applyThemeToDocument(newTheme as Theme, config);
+      }
+    };
+
+    window.addEventListener("storage", handleStorageChange);
+
+    return () => {
+      window.removeEventListener("storage", handleStorageChange);
+    };
+  }, [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;
+      }
+      return "light";
+    }
+    if (theme === "system" && config.enableSystem) {
+      return systemTheme;
+    }
+    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")];
+    }
+    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,
+    }),
+    [theme, setTheme, resolvedTheme, systemTheme, themes, config, mounted],
+  );
+
+  return (
+    <ThemeContext.Provider value={contextValue}>
+      {children}
+    </ThemeContext.Provider>
+  );
+}

package/src/theme/ThemeScript.tsx

@@ -0,0 +1,61 @@
+/**
+ * ThemeScript - Server component that renders an inline script for FOUC prevention.
+ *
+ * This component renders a blocking inline script that:
+ * 1. Reads theme from cookie/localStorage before paint
+ * 2. Applies the theme to the HTML element immediately
+ * 3. Prevents flash of unstyled content (FOUC)
+ *
+ * Must be placed in the <head> element of your document, before any stylesheets.
+ *
+ * @example
+ * ```tsx
+ * // In your document component
+ * import { ThemeScript } from "@rangojs/router/theme";
+ *
+ * export function Document({ children }) {
+ *   return (
+ *     <html lang="en" suppressHydrationWarning>
+ *       <head>
+ *         <ThemeScript />
+ *         <MetaTags />
+ *       </head>
+ *       <body>{children}</body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+
+import React from "react";
+import { generateThemeScript } from "./theme-script.js";
+import type { ResolvedThemeConfig } from "./types.js";
+
+export interface ThemeScriptProps {
+  /**
+   * Theme configuration - passed from router.themeConfig
+   */
+  config: ResolvedThemeConfig;
+
+  /**
+   * Optional nonce for CSP
+   */
+  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,
+}: ThemeScriptProps): React.ReactNode {
+  const scriptContent = generateThemeScript(config);
+
+  return (
+    <script nonce={nonce} dangerouslySetInnerHTML={{ __html: scriptContent }} />
+  );
+}

package/src/theme/constants.ts

@@ -0,0 +1,62 @@
+/**
+ * Default values for theme configuration
+ */
+
+import type { ResolvedThemeConfig, ThemeConfig } from "./types.js";
+
+/**
+ * Default theme configuration values
+ */
+export const THEME_DEFAULTS = {
+  defaultTheme: "system",
+  themes: ["light", "dark"],
+  attribute: "class",
+  storageKey: "theme",
+  enableSystem: true,
+  enableColorScheme: true,
+} as const;
+
+/**
+ * Cookie configuration for theme persistence
+ */
+export const THEME_COOKIE: {
+  readonly maxAge: number;
+  readonly path: string;
+  readonly sameSite: "lax";
+} = {
+  maxAge: 60 * 60 * 24 * 365, // 1 year
+  path: "/",
+  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;
+  }
+
+  return {
+    defaultTheme: config.defaultTheme ?? THEME_DEFAULTS.defaultTheme,
+    themes,
+    attribute: config.attribute ?? THEME_DEFAULTS.attribute,
+    storageKey: config.storageKey ?? THEME_DEFAULTS.storageKey,
+    enableSystem: config.enableSystem ?? THEME_DEFAULTS.enableSystem,
+    enableColorScheme:
+      config.enableColorScheme ?? THEME_DEFAULTS.enableColorScheme,
+    value,
+  };
+}

package/src/theme/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Theme module exports for @rangojs/router/theme
+ *
+ * This module provides the public theme API:
+ * - useTheme: Hook for accessing theme state in client components
+ * - ThemeProvider: Component for manual theme provider setup (typically not needed)
+ * - ThemeScript: FOUC-prevention script component for document/head usage
+ * - Types for theme configuration
+ *
+ * @example
+ * ```tsx
+ * // In a client component
+ * import { useTheme } from "@rangojs/router/theme";
+ *
+ * function ThemeToggle() {
+ *   const { theme, setTheme, themes } = useTheme();
+ *   return (
+ *     <select value={theme} onChange={e => setTheme(e.target.value)}>
+ *       {themes.map(t => <option key={t}>{t}</option>)}
+ *     </select>
+ *   );
+ * }
+ * ```
+ */
+
+// 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,
+  ThemeAttribute,
+  ThemeConfig,
+  ResolvedThemeConfig,
+  UseThemeReturn,
+  ThemeProviderProps,
+  ThemeContextValue,
+} from "./types.js";
+
+// Constants
+export { THEME_DEFAULTS, THEME_COOKIE } from "./constants.js";

package/src/theme/theme-context.ts

@@ -0,0 +1,44 @@
+"use client";
+
+/**
+ * Theme context for sharing theme state and configuration.
+ *
+ * Used by:
+ * - ThemeProvider to provide theme state
+ * - useTheme hook to access theme state
+ * - MetaTags to check if theme is enabled and render script
+ */
+
+import { createContext, useContext, type Context } from "react";
+import type { ThemeContextValue } from "./types.js";
+
+/**
+ * React context for theme state
+ * null when theme is not enabled in router config
+ */
+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
+ */
+export function requireThemeContext(): ThemeContextValue {
+  const ctx = useContext(ThemeContext);
+  if (!ctx) {
+    throw new Error(
+      "useTheme must be used within a ThemeProvider. " +
+        "Make sure theme is enabled in your router config: " +
+        "createRouter({ theme: { ... } })",
+    );
+  }
+  return ctx;
+}

package/src/theme/theme-script.ts

@@ -0,0 +1,155 @@
+/**
+ * Generates an inline script for FOUC prevention.
+ *
+ * This script runs synchronously before page paint to:
+ * 1. Read theme from cookie or localStorage
+ * 2. Detect system preference if theme is "system"
+ * 3. Apply theme to HTML element via class or data attribute
+ * 4. Optionally set color-scheme CSS property
+ *
+ * The script is minified and inlined in <head> before any other content.
+ */
+
+import type { ResolvedThemeConfig } from "./types.js";
+
+/**
+ * Generate the inline script for theme initialization
+ *
+ * The script is designed to:
+ * - Run synchronously before paint (blocking)
+ * - Be as small as possible to minimize blocking time
+ * - Work without any external dependencies
+ * - 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)};
+  var defaultTheme = ${JSON.stringify(config.defaultTheme)};
+  var attribute = ${JSON.stringify(config.attribute)};
+  var enableSystem = ${config.enableSystem};
+  var enableColorScheme = ${config.enableColorScheme};
+  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();
+      if (cookie.indexOf(storageKey + '=') === 0) {
+        try { return decodeURIComponent(cookie.substring(storageKey.length + 1)); }
+        catch (e) { return cookie.substring(storageKey.length + 1); }
+      }
+    }
+    // Fall back to localStorage
+    try {
+      return localStorage.getItem(storageKey);
+    } catch (e) {
+      return null;
+    }
+  }
+
+  // Get system preference
+  function getSystemTheme() {
+    if (typeof window !== 'undefined' && window.matchMedia) {
+      return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+    }
+    return 'light';
+  }
+
+  // Resolve "system" to actual theme
+  function resolveTheme(theme) {
+    if (theme === 'system' && enableSystem) {
+      return getSystemTheme();
+    }
+    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);
+      }
+      el.classList.add(value);
+    } else {
+      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() {
+        var current = getStoredTheme() || defaultTheme;
+        if (current === 'system') {
+          applyTheme('system');
+        }
+      });
+    } catch (e) {
+      // Older browsers may not support addEventListener on MediaQueryList
+    }
+  }
+})();
+`;
+
+  // Minify by removing comments, extra whitespace, and newlines
+  return minifyScript(script);
+}
+
+/**
+ * Basic script minification
+ * Removes comments, extra whitespace, and unnecessary newlines
+ */
+function minifyScript(script: string): string {
+  return (
+    script
+      // Remove single-line comments
+      .replace(/\/\/.*$/gm, "")
+      // Remove multi-line comments
+      .replace(/\/\*[\s\S]*?\*\//g, "")
+      // Remove leading/trailing whitespace from lines
+      .split("\n")
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0)
+      .join("")
+      // Collapse multiple spaces to single space
+      .replace(/\s+/g, " ")
+      // Remove spaces around operators and punctuation
+      .replace(/\s*([{};,=!<>()[\]+\-*/&|?:])\s*/g, "$1")
+      // Add back necessary spaces (e.g., "var x")
+      .replace(/(var|function|return|if|for|try|catch|typeof|else)\(/g, "$1 (")
+      .replace(/\)([a-zA-Z])/g, ") $1")
+  );
+}
+
+/**
+ * Generate nonce attribute string if nonce is provided
+ */
+export function getNonceAttribute(nonce?: string): string {
+  return nonce ? ` nonce="${nonce}"` : "";
+}