@rangojs/router 0.0.0-experimental.2

package/src/theme/ThemeProvider.tsx

@@ -0,0 +1,291 @@
+"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) {
+      return decodeURIComponent(rest.join("="));
+    }
+  }
+  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/__tests__/theme.test.ts

@@ -0,0 +1,120 @@
+import { describe, it, expect } from "vitest";
+import { resolveThemeConfig, THEME_DEFAULTS, THEME_COOKIE } from "../constants.js";
+import { generateThemeScript } from "../theme-script.js";
+import type { ThemeConfig, ResolvedThemeConfig } from "../types.js";
+
+describe("Theme Configuration", () => {
+  describe("resolveThemeConfig", () => {
+    it("should apply defaults when no config provided", () => {
+      const config: ThemeConfig = {};
+      const resolved = resolveThemeConfig(config);
+
+      expect(resolved.defaultTheme).toBe(THEME_DEFAULTS.defaultTheme);
+      expect(resolved.themes).toEqual(THEME_DEFAULTS.themes);
+      expect(resolved.attribute).toBe(THEME_DEFAULTS.attribute);
+      expect(resolved.storageKey).toBe(THEME_DEFAULTS.storageKey);
+      expect(resolved.enableSystem).toBe(THEME_DEFAULTS.enableSystem);
+      expect(resolved.enableColorScheme).toBe(THEME_DEFAULTS.enableColorScheme);
+    });
+
+    it("should preserve custom config values", () => {
+      const config: ThemeConfig = {
+        defaultTheme: "dark",
+        themes: ["light", "dark", "sepia"],
+        attribute: "data-theme",
+        storageKey: "app-theme",
+        enableSystem: false,
+        enableColorScheme: false,
+      };
+      const resolved = resolveThemeConfig(config);
+
+      expect(resolved.defaultTheme).toBe("dark");
+      expect(resolved.themes).toEqual(["light", "dark", "sepia"]);
+      expect(resolved.attribute).toBe("data-theme");
+      expect(resolved.storageKey).toBe("app-theme");
+      expect(resolved.enableSystem).toBe(false);
+      expect(resolved.enableColorScheme).toBe(false);
+    });
+
+    it("should generate value mapping for themes", () => {
+      const config: ThemeConfig = {
+        themes: ["light", "dark"],
+      };
+      const resolved = resolveThemeConfig(config);
+
+      expect(resolved.value).toEqual({
+        light: "light",
+        dark: "dark",
+      });
+    });
+
+    it("should use custom value mapping when provided", () => {
+      const config: ThemeConfig = {
+        themes: ["light", "dark"],
+        value: {
+          light: "light-mode",
+          dark: "dark-mode",
+        },
+      };
+      const resolved = resolveThemeConfig(config);
+
+      expect(resolved.value).toEqual({
+        light: "light-mode",
+        dark: "dark-mode",
+      });
+    });
+  });
+
+  describe("THEME_COOKIE", () => {
+    it("should have correct defaults", () => {
+      expect(THEME_COOKIE.maxAge).toBe(60 * 60 * 24 * 365);
+      expect(THEME_COOKIE.path).toBe("/");
+      expect(THEME_COOKIE.sameSite).toBe("lax");
+    });
+  });
+});
+
+describe("Theme Script", () => {
+  describe("generateThemeScript", () => {
+    it("should generate a minified script", () => {
+      const config: ResolvedThemeConfig = {
+        defaultTheme: "system",
+        themes: ["light", "dark"],
+        attribute: "class",
+        storageKey: "theme",
+        enableSystem: true,
+        enableColorScheme: true,
+        value: { light: "light", dark: "dark" },
+      };
+
+      const script = generateThemeScript(config);
+
+      // Should be a string
+      expect(typeof script).toBe("string");
+
+      // Should not have multi-line formatting (minified)
+      expect(script.includes("\n  ")).toBe(false);
+
+      // Should contain key configuration values
+      expect(script.includes('"theme"')).toBe(true);
+      expect(script.includes('"system"')).toBe(true);
+      expect(script.includes('"class"')).toBe(true);
+    });
+
+    it("should handle data-* attributes", () => {
+      const config: ResolvedThemeConfig = {
+        defaultTheme: "light",
+        themes: ["light", "dark"],
+        attribute: "data-theme",
+        storageKey: "theme",
+        enableSystem: true,
+        enableColorScheme: true,
+        value: { light: "light", dark: "dark" },
+      };
+
+      const script = generateThemeScript(config);
+
+      expect(script.includes('"data-theme"')).toBe(true);
+    });
+  });
+});

package/src/theme/constants.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 = {
+  maxAge: 60 * 60 * 24 * 365, // 1 year
+  path: "/",
+  sameSite: "lax",
+} as const;
+
+/**
+ * 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,58 @@
+/**
+ * Theme module exports for @rangojs/router/theme
+ *
+ * This module provides theme management for rsc-router:
+ * - useTheme: Hook for accessing theme state in client components
+ * - ThemeProvider: Component for manual theme provider setup (typically not needed)
+ * - 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 (for advanced use cases)
+export { THEME_DEFAULTS, THEME_COOKIE, resolveThemeConfig } from "./constants.js";
+
+// Script generation (for advanced SSR use cases)
+export { generateThemeScript, getNonceAttribute } from "./theme-script.js";
+
+// Context (for advanced use cases)
+export {
+  ThemeContext,
+  useThemeContext,
+  initThemeConfigSync,
+  getSSRThemeConfig,
+} from "./theme-context.js";

package/src/theme/theme-context.ts

@@ -0,0 +1,70 @@
+"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 } from "react";
+import type { ResolvedThemeConfig, ThemeContextValue } from "./types.js";
+
+/**
+ * React context for theme state
+ * null when theme is not enabled in router config
+ */
+export const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+/**
+ * SSR module-level state for theme config.
+ * Populated by initThemeConfigSync before React renders.
+ * Used by MetaTags during SSR to render the theme script.
+ */
+let ssrThemeConfig: ResolvedThemeConfig | null = null;
+
+/**
+ * Initialize theme config synchronously for SSR.
+ * Called before rendering to populate state for MetaTags.
+ *
+ * @param config - Theme config from router, or null if theme is disabled
+ */
+export function initThemeConfigSync(config: ResolvedThemeConfig | null): void {
+  ssrThemeConfig = config;
+}
+
+/**
+ * Get theme config for SSR/hydration.
+ * Used by MetaTags to render the theme script.
+ *
+ * @returns Theme config if available, null otherwise
+ */
+export function getSSRThemeConfig(): ResolvedThemeConfig | null {
+  return ssrThemeConfig;
+}
+
+/**
+ * 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: " +
+        "createRSCRouter({ theme: { ... } })"
+    );
+  }
+  return ctx;
+}