npm - @rangojs/router - Versions diffs - 0.0.0-experimental.2 - Mend

@rangojs/router 0.0.0-experimental.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (155) hide show

package/CLAUDE.md +7 -0
package/README.md +19 -0
package/dist/vite/index.js +1298 -0
package/package.json +140 -0
package/skills/caching/SKILL.md +319 -0
package/skills/document-cache/SKILL.md +152 -0
package/skills/hooks/SKILL.md +359 -0
package/skills/intercept/SKILL.md +292 -0
package/skills/layout/SKILL.md +216 -0
package/skills/loader/SKILL.md +365 -0
package/skills/middleware/SKILL.md +442 -0
package/skills/parallel/SKILL.md +255 -0
package/skills/route/SKILL.md +141 -0
package/skills/router-setup/SKILL.md +403 -0
package/skills/theme/SKILL.md +54 -0
package/skills/typesafety/SKILL.md +352 -0
package/src/__mocks__/version.ts +6 -0
package/src/__tests__/component-utils.test.ts +76 -0
package/src/__tests__/route-definition.test.ts +63 -0
package/src/__tests__/urls.test.tsx +436 -0
package/src/browser/event-controller.ts +876 -0
package/src/browser/index.ts +18 -0
package/src/browser/link-interceptor.ts +121 -0
package/src/browser/lru-cache.ts +69 -0
package/src/browser/merge-segment-loaders.ts +126 -0
package/src/browser/navigation-bridge.ts +893 -0
package/src/browser/navigation-client.ts +162 -0
package/src/browser/navigation-store.ts +823 -0
package/src/browser/partial-update.ts +559 -0
package/src/browser/react/Link.tsx +248 -0
package/src/browser/react/NavigationProvider.tsx +275 -0
package/src/browser/react/ScrollRestoration.tsx +94 -0
package/src/browser/react/context.ts +53 -0
package/src/browser/react/index.ts +52 -0
package/src/browser/react/location-state-shared.ts +120 -0
package/src/browser/react/location-state.ts +62 -0
package/src/browser/react/use-action.ts +240 -0
package/src/browser/react/use-client-cache.ts +56 -0
package/src/browser/react/use-handle.ts +178 -0
package/src/browser/react/use-href.tsx +208 -0
package/src/browser/react/use-link-status.ts +134 -0
package/src/browser/react/use-navigation.ts +150 -0
package/src/browser/react/use-segments.ts +188 -0
package/src/browser/request-controller.ts +164 -0
package/src/browser/rsc-router.tsx +353 -0
package/src/browser/scroll-restoration.ts +324 -0
package/src/browser/server-action-bridge.ts +747 -0
package/src/browser/shallow.ts +35 -0
package/src/browser/types.ts +464 -0
package/src/cache/__tests__/document-cache.test.ts +522 -0
package/src/cache/__tests__/memory-segment-store.test.ts +487 -0
package/src/cache/__tests__/memory-store.test.ts +484 -0
package/src/cache/cache-scope.ts +565 -0
package/src/cache/cf/__tests__/cf-cache-store.test.ts +428 -0
package/src/cache/cf/cf-cache-store.ts +428 -0
package/src/cache/cf/index.ts +19 -0
package/src/cache/document-cache.ts +340 -0
package/src/cache/index.ts +58 -0
package/src/cache/memory-segment-store.ts +150 -0
package/src/cache/memory-store.ts +253 -0
package/src/cache/types.ts +387 -0
package/src/client.rsc.tsx +88 -0
package/src/client.tsx +621 -0
package/src/component-utils.ts +76 -0
package/src/components/DefaultDocument.tsx +23 -0
package/src/default-error-boundary.tsx +88 -0
package/src/deps/browser.ts +8 -0
package/src/deps/html-stream-client.ts +2 -0
package/src/deps/html-stream-server.ts +2 -0
package/src/deps/rsc.ts +10 -0
package/src/deps/ssr.ts +2 -0
package/src/errors.ts +259 -0
package/src/handle.ts +120 -0
package/src/handles/MetaTags.tsx +193 -0
package/src/handles/index.ts +6 -0
package/src/handles/meta.ts +247 -0
package/src/href-client.ts +128 -0
package/src/href-context.ts +33 -0
package/src/href.ts +177 -0
package/src/index.rsc.ts +79 -0
package/src/index.ts +87 -0
package/src/loader.rsc.ts +204 -0
package/src/loader.ts +47 -0
package/src/network-error-thrower.tsx +21 -0
package/src/outlet-context.ts +15 -0
package/src/root-error-boundary.tsx +277 -0
package/src/route-content-wrapper.tsx +198 -0
package/src/route-definition.ts +1371 -0
package/src/route-map-builder.ts +146 -0
package/src/route-types.ts +198 -0
package/src/route-utils.ts +89 -0
package/src/router/__tests__/match-context.test.ts +104 -0
package/src/router/__tests__/match-pipelines.test.ts +537 -0
package/src/router/__tests__/match-result.test.ts +566 -0
package/src/router/__tests__/on-error.test.ts +935 -0
package/src/router/__tests__/pattern-matching.test.ts +577 -0
package/src/router/error-handling.ts +287 -0
package/src/router/handler-context.ts +158 -0
package/src/router/loader-resolution.ts +326 -0
package/src/router/manifest.ts +138 -0
package/src/router/match-context.ts +264 -0
package/src/router/match-middleware/background-revalidation.ts +236 -0
package/src/router/match-middleware/cache-lookup.ts +261 -0
package/src/router/match-middleware/cache-store.ts +266 -0
package/src/router/match-middleware/index.ts +81 -0
package/src/router/match-middleware/intercept-resolution.ts +268 -0
package/src/router/match-middleware/segment-resolution.ts +174 -0
package/src/router/match-pipelines.ts +214 -0
package/src/router/match-result.ts +214 -0
package/src/router/metrics.ts +62 -0
package/src/router/middleware.test.ts +1355 -0
package/src/router/middleware.ts +748 -0
package/src/router/pattern-matching.ts +272 -0
package/src/router/revalidation.ts +190 -0
package/src/router/router-context.ts +299 -0
package/src/router/types.ts +96 -0
package/src/router.ts +3876 -0
package/src/rsc/__tests__/helpers.test.ts +175 -0
package/src/rsc/handler.ts +1060 -0
package/src/rsc/helpers.ts +64 -0
package/src/rsc/index.ts +56 -0
package/src/rsc/nonce.ts +18 -0
package/src/rsc/types.ts +237 -0
package/src/segment-system.tsx +456 -0
package/src/server/__tests__/request-context.test.ts +171 -0
package/src/server/context.ts +417 -0
package/src/server/handle-store.ts +230 -0
package/src/server/loader-registry.ts +174 -0
package/src/server/request-context.ts +554 -0
package/src/server/root-layout.tsx +10 -0
package/src/server/tsconfig.json +14 -0
package/src/server.ts +146 -0
package/src/ssr/__tests__/ssr-handler.test.tsx +188 -0
package/src/ssr/index.tsx +234 -0
package/src/theme/ThemeProvider.tsx +291 -0
package/src/theme/ThemeScript.tsx +61 -0
package/src/theme/__tests__/theme.test.ts +120 -0
package/src/theme/constants.ts +55 -0
package/src/theme/index.ts +58 -0
package/src/theme/theme-context.ts +70 -0
package/src/theme/theme-script.ts +152 -0
package/src/theme/types.ts +182 -0
package/src/theme/use-theme.ts +44 -0
package/src/types.ts +1561 -0
package/src/urls.ts +726 -0
package/src/use-loader.tsx +346 -0
package/src/vite/__tests__/expose-loader-id.test.ts +117 -0
package/src/vite/expose-action-id.ts +344 -0
package/src/vite/expose-handle-id.ts +209 -0
package/src/vite/expose-loader-id.ts +357 -0
package/src/vite/expose-location-state-id.ts +177 -0
package/src/vite/index.ts +787 -0
package/src/vite/package-resolution.ts +125 -0
package/src/vite/version.d.ts +12 -0
package/src/vite/virtual-entries.ts +109 -0

package/src/theme/theme-script.ts ADDED Viewed

@@ -0,0 +1,152 @@
+/**
+ * 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) {
+        return decodeURIComponent(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}"` : "";
+}

package/src/theme/types.ts ADDED Viewed

@@ -0,0 +1,182 @@
+/**
+ * Theme type definitions for rsc-router theme system.
+ *
+ * The theme system provides:
+ * - Opt-in via router config
+ * - FOUC prevention via inline script
+ * - Server-side theme access via ctx.theme/ctx.setTheme
+ * - Client-side theme access via useTheme hook
+ */
+/**
+ * Theme value - stored in cookies/localStorage
+ */
+export type Theme = "light" | "dark" | "system";
+/**
+ * Resolved theme - actual visual appearance (system preference resolved)
+ */
+export type ResolvedTheme = "light" | "dark";
+/**
+ * Attribute used to apply theme to HTML element
+ * - "class": Adds theme value as CSS class (e.g., <html class="dark">)
+ * - "data-*": Sets data attribute (e.g., <html data-theme="dark">)
+ */
+export type ThemeAttribute = "class" | `data-${string}`;
+/**
+ * Theme configuration for router
+ *
+ * @example
+ * ```typescript
+ * const router = createRSCRouter<Env>({
+ *   theme: {
+ *     defaultTheme: "system",
+ *     themes: ["light", "dark"],
+ *     attribute: "class",
+ *     storageKey: "theme",
+ *   }
+ * });
+ * ```
+ */
+export interface ThemeConfig {
+  /**
+   * Default theme when no preference is stored
+   * @default "system"
+   */
+  defaultTheme?: Theme;
+  /**
+   * Available theme options
+   * @default ["light", "dark"]
+   */
+  themes?: string[];
+  /**
+   * Attribute to apply to HTML element
+   * @default "class"
+   */
+  attribute?: ThemeAttribute;
+  /**
+   * Key for cookie and localStorage
+   * @default "theme"
+   */
+  storageKey?: string;
+  /**
+   * Enable system preference detection
+   * When true, "system" theme will resolve based on prefers-color-scheme
+   * @default true
+   */
+  enableSystem?: boolean;
+  /**
+   * Set CSS color-scheme property on HTML element
+   * This enables native dark mode for form controls, scrollbars, etc.
+   * @default true
+   */
+  enableColorScheme?: boolean;
+  /**
+   * Custom mapping of theme names to attribute values
+   * Useful when theme names don't match desired attribute values
+   *
+   * @example
+   * ```typescript
+   * value: {
+   *   light: "light-mode",
+   *   dark: "dark-mode",
+   * }
+   * ```
+   */
+  value?: Record<string, string>;
+}
+/**
+ * Resolved theme configuration with defaults applied
+ */
+export interface ResolvedThemeConfig {
+  defaultTheme: Theme;
+  themes: string[];
+  attribute: ThemeAttribute;
+  storageKey: string;
+  enableSystem: boolean;
+  enableColorScheme: boolean;
+  value: Record<string, string>;
+}
+/**
+ * Return type from useTheme hook
+ *
+ * @example
+ * ```tsx
+ * function ThemeToggle() {
+ *   const { theme, setTheme, resolvedTheme, themes } = useTheme();
+ *
+ *   return (
+ *     <select value={theme} onChange={e => setTheme(e.target.value as Theme)}>
+ *       {themes.map(t => <option key={t}>{t}</option>)}
+ *     </select>
+ *   );
+ * }
+ * ```
+ */
+export interface UseThemeReturn {
+  /**
+   * Current theme setting ("light" | "dark" | "system")
+   */
+  theme: Theme;
+  /**
+   * Set the theme
+   */
+  setTheme: (theme: Theme) => void;
+  /**
+   * Resolved theme based on system preference
+   * When theme is "system", this reflects the actual appearance
+   */
+  resolvedTheme: ResolvedTheme;
+  /**
+   * Current system preference ("light" | "dark")
+   */
+  systemTheme: ResolvedTheme;
+  /**
+   * Available theme options (includes "system" if enableSystem is true)
+   */
+  themes: string[];
+}
+/**
+ * Props for ThemeProvider component
+ */
+export interface ThemeProviderProps {
+  /**
+   * Theme configuration
+   */
+  config: ResolvedThemeConfig;
+  /**
+   * Initial theme from server (from cookie)
+   */
+  initialTheme?: Theme;
+  /**
+   * Children to render
+   */
+  children: React.ReactNode;
+}
+/**
+ * Context value for ThemeContext
+ */
+export interface ThemeContextValue extends UseThemeReturn {
+  /**
+   * Full theme configuration
+   */
+  config: ResolvedThemeConfig;
+}

package/src/theme/use-theme.ts ADDED Viewed

@@ -0,0 +1,44 @@
+"use client";
+/**
+ * useTheme - Hook for accessing theme state in client components.
+ *
+ * @example
+ * ```tsx
+ * import { useTheme } from "@rangojs/router/theme";
+ *
+ * function ThemeToggle() {
+ *   const { theme, setTheme, resolvedTheme, themes } = useTheme();
+ *
+ *   return (
+ *     <select value={theme} onChange={e => setTheme(e.target.value)}>
+ *       {themes.map(t => <option key={t}>{t}</option>)}
+ *     </select>
+ *   );
+ * }
+ * ```
+ */
+import { requireThemeContext } from "./theme-context.js";
+import type { UseThemeReturn } from "./types.js";
+/**
+ * Hook to access theme state and methods.
+ *
+ * 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();
+  return {
+    theme: ctx.theme,
+    setTheme: ctx.setTheme,
+    resolvedTheme: ctx.resolvedTheme,
+    systemTheme: ctx.systemTheme,
+    themes: ctx.themes,
+  };
+}