stoop 0.2.1 → 0.4.0

package/dist/utils/storage.js

@@ -0,0 +1,396 @@
+/**
+ * Storage and theme detection utilities.
+ * Provides simplified localStorage and cookie management, plus automatic theme selection.
+ * Supports SSR compatibility and error handling.
+ */
+import { DEFAULT_COOKIE_MAX_AGE, DEFAULT_COOKIE_PATH } from "../constants";
+import { isBrowser } from "./helpers";
+// ============================================================================
+// Storage Utilities
+// ============================================================================
+/**
+ * Parses a JSON value safely.
+ *
+ * @param value - String value to parse
+ * @param fallback - Fallback value if parsing fails
+ * @returns Parsed value or fallback
+ */
+function safeJsonParse(value, fallback) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return fallback;
+    }
+}
+/**
+ * Safely gets a value from localStorage.
+ *
+ * @param key - Storage key
+ * @returns Storage result
+ */
+export function getFromStorage(key) {
+    if (!isBrowser()) {
+        return { error: "Not in browser environment", success: false, value: null };
+    }
+    try {
+        const value = localStorage.getItem(key);
+        return { source: "localStorage", success: true, value };
+    }
+    catch (error) {
+        return {
+            error: error instanceof Error ? error.message : "localStorage access failed",
+            success: false,
+            value: null,
+        };
+    }
+}
+/**
+ * Safely sets a value in localStorage.
+ *
+ * @param key - Storage key
+ * @param value - Value to store
+ * @returns Storage result
+ */
+export function setInStorage(key, value) {
+    if (!isBrowser()) {
+        return { error: "Not in browser environment", success: false, value: undefined };
+    }
+    try {
+        localStorage.setItem(key, value);
+        return { success: true, value: undefined };
+    }
+    catch (error) {
+        return {
+            error: error instanceof Error ? error.message : "localStorage write failed",
+            success: false,
+            value: undefined,
+        };
+    }
+}
+/**
+ * Safely removes a value from localStorage.
+ *
+ * @param key - Storage key
+ * @returns Storage result
+ */
+export function removeFromStorage(key) {
+    if (!isBrowser()) {
+        return { error: "Not in browser environment", success: false, value: undefined };
+    }
+    try {
+        localStorage.removeItem(key);
+        return { success: true, value: undefined };
+    }
+    catch (error) {
+        return {
+            error: error instanceof Error ? error.message : "localStorage remove failed",
+            success: false,
+            value: undefined,
+        };
+    }
+}
+/**
+ * Gets a cookie value.
+ *
+ * @param name - Cookie name
+ * @returns Cookie value or null if not found
+ */
+export function getCookie(name) {
+    if (!isBrowser())
+        return null;
+    const value = `; ${document.cookie}`;
+    const parts = value.split(`; ${name}=`);
+    if (parts.length === 2) {
+        return parts.pop()?.split(";").shift() || null;
+    }
+    return null;
+}
+/**
+ * Sets a cookie value.
+ *
+ * @param name - Cookie name
+ * @param value - Cookie value
+ * @param options - Cookie options
+ * @returns Success status
+ */
+export function setCookie(name, value, options = {}) {
+    if (!isBrowser())
+        return false;
+    const { maxAge = DEFAULT_COOKIE_MAX_AGE, path = DEFAULT_COOKIE_PATH, secure = false } = options;
+    try {
+        document.cookie = `${name}=${value}; path=${path}; max-age=${maxAge}${secure ? "; secure" : ""}`;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Removes a cookie by setting it to expire.
+ *
+ * @param name - Cookie name
+ * @param path - Cookie path
+ * @returns Success status
+ */
+export function removeCookie(name, path = "/") {
+    if (!isBrowser())
+        return false;
+    try {
+        document.cookie = `${name}=; path=${path}; max-age=0`;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Unified storage API that works with both localStorage and cookies.
+ *
+ * @param key - Storage key
+ * @param options - Storage options
+ * @returns Storage result
+ */
+export function getStorage(key, options = {}) {
+    const { type = "localStorage" } = options;
+    if (type === "cookie") {
+        const value = getCookie(key);
+        return {
+            source: "cookie",
+            success: value !== null,
+            value,
+        };
+    }
+    return getFromStorage(key);
+}
+/**
+ * Unified storage API that works with both localStorage and cookies.
+ *
+ * @param key - Storage key
+ * @param value - Value to store
+ * @param options - Storage options
+ * @returns Storage result
+ */
+export function setStorage(key, value, options = {}) {
+    const { type = "localStorage" } = options;
+    if (type === "cookie") {
+        const success = setCookie(key, value, options);
+        return {
+            error: success ? undefined : "Cookie write failed",
+            success,
+            value: undefined,
+        };
+    }
+    return setInStorage(key, value);
+}
+/**
+ * Unified storage API that works with both localStorage and cookies.
+ *
+ * @param key - Storage key
+ * @param options - Storage options
+ * @returns Storage result
+ */
+export function removeStorage(key, options = {}) {
+    const { type = "localStorage" } = options;
+    if (type === "cookie") {
+        const success = removeCookie(key, options.path);
+        return {
+            error: success ? undefined : "Cookie remove failed",
+            success,
+            value: undefined,
+        };
+    }
+    return removeFromStorage(key);
+}
+/**
+ * Gets a JSON value from storage with automatic parsing.
+ *
+ * @param key - Storage key
+ * @param fallback - Fallback value if parsing fails or key not found
+ * @param options - Storage options
+ * @returns Parsed JSON value or fallback
+ */
+export function getJsonFromStorage(key, fallback, options = {}) {
+    const result = getStorage(key, options);
+    if (!result.success || result.value === null) {
+        return { ...result, value: fallback };
+    }
+    const parsed = safeJsonParse(result.value, fallback);
+    return { ...result, value: parsed };
+}
+/**
+ * Sets a JSON value in storage with automatic serialization.
+ *
+ * @param key - Storage key
+ * @param value - Value to serialize and store
+ * @param options - Storage options
+ * @returns Storage result
+ */
+export function setJsonInStorage(key, value, options = {}) {
+    try {
+        const serialized = JSON.stringify(value);
+        return setStorage(key, serialized, options);
+    }
+    catch (error) {
+        return {
+            error: error instanceof Error ? error.message : "JSON serialization failed",
+            success: false,
+            value: undefined,
+        };
+    }
+}
+/**
+ * Creates a typed storage interface for a specific key.
+ *
+ * @param key - Storage key
+ * @param options - Storage options
+ * @returns Typed storage interface
+ */
+export function createStorage(key, options = {}) {
+    return {
+        get: () => getStorage(key, options),
+        getJson: (fallback) => getJsonFromStorage(key, fallback, options),
+        remove: () => removeStorage(key, options),
+        set: (value) => setStorage(key, value, options),
+        setJson: (value) => setJsonInStorage(key, value, options),
+    };
+}
+// ============================================================================
+// Theme Detection Utilities
+// ============================================================================
+/**
+ * Gets localStorage value safely (internal helper for theme detection).
+ * Uses getFromStorage for consistency.
+ *
+ * @param key - Storage key
+ * @returns Stored value or null if not found or access failed
+ */
+function getLocalStorage(key) {
+    const result = getFromStorage(key);
+    return result.success ? result.value : null;
+}
+/**
+ * Detects system color scheme preference.
+ *
+ * @returns 'dark' or 'light' based on system preference
+ */
+function getSystemPreference() {
+    if (!isBrowser())
+        return null;
+    try {
+        return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Validates if a theme name exists in available themes.
+ *
+ * @param themeName - Theme name to validate
+ * @param themes - Available themes map
+ * @returns True if theme is valid
+ */
+function isValidTheme(themeName, themes) {
+    return !themes || !!themes[themeName];
+}
+/**
+ * Detects the best theme to use based on multiple sources with priority.
+ *
+ * Priority order (highest to lowest):
+ * 1. Explicit localStorage preference
+ * 2. Cookie preference (for SSR compatibility)
+ * 3. System color scheme preference
+ * 4. Default theme
+ *
+ * @param options - Theme detection options
+ * @returns Theme detection result
+ */
+export function detectTheme(options = {}) {
+    const { cookie: cookieKey, default: defaultTheme = "light", localStorage: storageKey, systemPreference = true, themes, } = options;
+    // 1. Check localStorage (highest priority - explicit user choice)
+    if (storageKey) {
+        const stored = getLocalStorage(storageKey);
+        if (stored && isValidTheme(stored, themes)) {
+            return {
+                confidence: 0.9, // High confidence - explicit user choice
+                source: "localStorage",
+                theme: stored,
+            };
+        }
+    }
+    // 2. Check cookie (for SSR compatibility)
+    if (cookieKey) {
+        const cookieValue = getCookie(cookieKey);
+        if (cookieValue && isValidTheme(cookieValue, themes)) {
+            return {
+                confidence: 0.8, // High confidence - persisted preference
+                source: "cookie",
+                theme: cookieValue,
+            };
+        }
+    }
+    // 3. Check system preference
+    if (systemPreference) {
+        const system = getSystemPreference();
+        if (system && isValidTheme(system, themes)) {
+            return {
+                confidence: 0.6, // Medium confidence - system default
+                source: "system",
+                theme: system,
+            };
+        }
+    }
+    // 4. Fall back to default
+    return {
+        confidence: 0.3, // Low confidence - fallback only
+        source: "default",
+        theme: defaultTheme,
+    };
+}
+/**
+ * Creates a theme detector function with pre-configured options.
+ *
+ * @param options - Theme detection options
+ * @returns Theme detection function
+ */
+export function createThemeDetector(options) {
+    return () => detectTheme(options);
+}
+/**
+ * Auto-detects theme for SSR contexts (server-side or during hydration).
+ * Uses only cookie and default sources since localStorage isn't available.
+ *
+ * @param options - Theme detection options
+ * @returns Theme name
+ */
+export function detectThemeForSSR(options = {}) {
+    const { cookie: cookieKey, default: defaultTheme = "light", themes } = options;
+    // Only check cookie in SSR context
+    if (cookieKey) {
+        const cookieValue = getCookie(cookieKey);
+        if (cookieValue && isValidTheme(cookieValue, themes)) {
+            return cookieValue;
+        }
+    }
+    return defaultTheme;
+}
+/**
+ * Listens for system theme changes and calls callback when changed.
+ *
+ * @param callback - Function to call when system theme changes
+ * @returns Cleanup function
+ */
+export function onSystemThemeChange(callback) {
+    if (!isBrowser()) {
+        return () => { }; // No-op in SSR
+    }
+    const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
+    const handleChange = (e) => {
+        callback(e.matches ? "dark" : "light");
+    };
+    mediaQuery.addEventListener("change", handleChange);
+    return () => {
+        mediaQuery.removeEventListener("change", handleChange);
+    };
+}

package/dist/utils/{string.d.ts → theme-utils.d.ts}

@@ -1,10 +1,11 @@
 /**
- * String utility functions.
- * Provides hashing for class name generation, camelCase to kebab-case conversion,
- * and CSS sanitization utilities for security.
+ * Theme-related string utilities and property mapping.
+ * Provides hashing, CSS sanitization, and theme scale mapping for property-aware token resolution.
  */
+import type { ThemeScale } from "../types";
 /**
- * Generates a hash string from an input string.
+ * Generates a hash string from an input string using FNV-1a algorithm.
+ * Includes string length to reduce collision probability.
  *
  * @param str - String to hash
  * @returns Hashed string
@@ -35,6 +36,7 @@ export declare function escapeCSSValue(value: string | number): string;
 /**
  * Validates and sanitizes CSS selectors to prevent injection attacks.
  * Only allows safe selector characters. Returns empty string for invalid selectors.
+ * Uses memoization for performance.
  *
  * @param selector - Selector to sanitize
  * @returns Sanitized selector string or empty string if invalid
@@ -43,6 +45,7 @@ export declare function sanitizeCSSSelector(selector: string): string;
 /**
  * Validates and sanitizes CSS variable names to prevent injection attacks.
  * CSS custom properties must start with -- and contain only valid characters.
+ * Uses memoization for performance.
  *
  * @param name - Variable name to sanitize
  * @returns Sanitized variable name
@@ -58,18 +61,12 @@ export declare function escapeCSSVariableValue(value: string | number): string;
 /**
  * Sanitizes prefix for use in CSS selectors and class names.
  * Only allows alphanumeric characters, hyphens, and underscores.
+ * Defaults to "stoop" if prefix is empty or becomes empty after sanitization.
  *
  * @param prefix - Prefix to sanitize
- * @returns Sanitized prefix string
+ * @returns Sanitized prefix string (never empty, defaults to "stoop")
  */
 export declare function sanitizePrefix(prefix: string): string;
-/**
- * Escapes prefix for use in CSS attribute selectors.
- *
- * @param prefix - Prefix to escape
- * @returns Escaped prefix string
- */
-export declare function escapePrefixForSelector(prefix: string): string;
 /**
  * Sanitizes media query strings to prevent injection attacks.
  * Only allows safe characters for media queries.
@@ -81,6 +78,7 @@ export declare function sanitizeMediaQuery(mediaQuery: string): string;
 /**
  * Sanitizes CSS class names to prevent injection attacks.
  * Only allows valid CSS class name characters.
+ * Uses memoization for performance.
  *
  * @param className - Class name(s) to sanitize
  * @returns Sanitized class name string
@@ -88,6 +86,7 @@ export declare function sanitizeMediaQuery(mediaQuery: string): string;
 export declare function sanitizeClassName(className: string): string;
 /**
  * Sanitizes CSS property names to prevent injection attacks.
+ * Uses memoization for performance.
  *
  * @param propertyName - Property name to sanitize
  * @returns Sanitized property name
@@ -100,3 +99,28 @@ export declare function sanitizeCSSPropertyName(propertyName: string): string;
  * @returns True if key is valid
  */
 export declare function validateKeyframeKey(key: string): boolean;
+/**
+ * Gets a pre-compiled regex for matching :root CSS selector blocks.
+ * Uses caching for performance.
+ *
+ * @param prefix - Optional prefix (unused, kept for API compatibility)
+ * @returns RegExp for matching :root selector blocks
+ */
+export declare function getRootRegex(prefix?: string): RegExp;
+/**
+ * Auto-detects theme scale from CSS property name using pattern matching.
+ * Used as fallback when property is not in DEFAULT_THEME_MAP.
+ *
+ * @param property - CSS property name
+ * @returns Theme scale name or undefined if no pattern matches
+ */
+export declare function autoDetectScale(property: string): ThemeScale | undefined;
+/**
+ * Gets the theme scale for a CSS property.
+ * Checks user themeMap first, then default themeMap, then pattern matching.
+ *
+ * @param property - CSS property name
+ * @param userThemeMap - Optional user-provided themeMap override
+ * @returns Theme scale name or undefined if no mapping found
+ */
+export declare function getScaleForProperty(property: string, userThemeMap?: Record<string, ThemeScale>): ThemeScale | undefined;