stoop 0.3.0 → 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,8 +1,8 @@
 /**
- * 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 using FNV-1a algorithm.
  * Includes string length to reduce collision probability.
@@ -107,3 +107,20 @@ export declare function validateKeyframeKey(key: string): boolean;
  * @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;

package/dist/utils/{string.js → theme-utils.js}

@@ -1,15 +1,17 @@
 /**
- * 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 { DEFAULT_THEME_MAP, SANITIZE_CACHE_SIZE_LIMIT } from "../constants";
+// ============================================================================
+// String Utilities
+// ============================================================================
 import { LRUCache } from "../core/cache";
-const sanitizeCacheSizeLimit = 1000;
 let cachedRootRegex = null;
-const selectorCache = new LRUCache(sanitizeCacheSizeLimit);
-const propertyNameCache = new LRUCache(sanitizeCacheSizeLimit);
-const sanitizeClassNameCache = new LRUCache(sanitizeCacheSizeLimit);
-const variableNameCache = new LRUCache(sanitizeCacheSizeLimit);
+const selectorCache = new LRUCache(SANITIZE_CACHE_SIZE_LIMIT);
+const propertyNameCache = new LRUCache(SANITIZE_CACHE_SIZE_LIMIT);
+const sanitizeClassNameCache = new LRUCache(SANITIZE_CACHE_SIZE_LIMIT);
+const variableNameCache = new LRUCache(SANITIZE_CACHE_SIZE_LIMIT);
 /**
  * Generates a hash string from an input string using FNV-1a algorithm.
  * Includes string length to reduce collision probability.
@@ -247,7 +249,105 @@ export function getRootRegex(prefix = "") {
     if (!cachedRootRegex) {
         const rootSelector = ":root";
         const escapedSelector = rootSelector.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-        cachedRootRegex = new RegExp(`${escapedSelector}\\s*\\{[\\s\\S]*?\\}`, "g");
+        // Match :root block - use greedy match to handle nested braces (e.g., calc())
+        // Since theme vars should only have one :root block, greedy matching is safe
+        // Greedy matching ensures we capture the entire :root block, including nested functions
+        cachedRootRegex = new RegExp(`${escapedSelector}\\s*\\{[\\s\\S]*\\}`);
     }
     return cachedRootRegex;
 }
+// ============================================================================
+// Theme Map Utilities
+// ============================================================================
+/**
+ * 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 function autoDetectScale(property) {
+    // Color properties
+    if (property.includes("Color") ||
+        property === "fill" ||
+        property === "stroke" ||
+        property === "accentColor" ||
+        property === "caretColor" ||
+        property === "border" ||
+        property === "outline" ||
+        (property.includes("background") && !property.includes("Size") && !property.includes("Image"))) {
+        return "colors";
+    }
+    // Spacing properties
+    if (/^(margin|padding|gap|inset|top|right|bottom|left|rowGap|columnGap|gridGap|gridRowGap|gridColumnGap)/.test(property) ||
+        property.includes("Block") ||
+        property.includes("Inline")) {
+        return "space";
+    }
+    // Size properties
+    if (/(width|height|size|basis)$/i.test(property) ||
+        property.includes("BlockSize") ||
+        property.includes("InlineSize")) {
+        return "sizes";
+    }
+    // Typography: Font Size
+    if (property === "fontSize" || (property === "font" && !property.includes("Family"))) {
+        return "fontSizes";
+    }
+    // Typography: Font Family
+    if (property === "fontFamily" || property.includes("FontFamily")) {
+        return "fonts";
+    }
+    // Typography: Font Weight
+    if (property === "fontWeight" || property.includes("FontWeight")) {
+        return "fontWeights";
+    }
+    // Typography: Letter Spacing
+    if (property === "letterSpacing" || property.includes("LetterSpacing")) {
+        return "letterSpacings";
+    }
+    // Border Radius
+    if (property.includes("Radius") || property.includes("radius")) {
+        return "radii";
+    }
+    // Shadows
+    if (property.includes("Shadow") ||
+        property.includes("shadow") ||
+        property === "filter" ||
+        property === "backdropFilter") {
+        return "shadows";
+    }
+    // Z-Index
+    if (property === "zIndex" || property.includes("ZIndex") || property.includes("z-index")) {
+        return "zIndices";
+    }
+    // Opacity
+    if (property === "opacity" || property.includes("Opacity")) {
+        return "opacities";
+    }
+    // Transitions and animations
+    if (property.startsWith("transition") ||
+        property.startsWith("animation") ||
+        property.includes("Transition") ||
+        property.includes("Animation")) {
+        return "transitions";
+    }
+    return 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 function getScaleForProperty(property, userThemeMap) {
+    if (userThemeMap && property in userThemeMap) {
+        return userThemeMap[property];
+    }
+    if (property in DEFAULT_THEME_MAP) {
+        return DEFAULT_THEME_MAP[property];
+    }
+    return autoDetectScale(property);
+}

package/dist/utils/theme.d.ts

@@ -28,9 +28,21 @@ export declare function tokenToCSSVar(token: string, theme?: Theme, property?: s
  *
  * @param theme - Theme object to convert to CSS variables
  * @param prefix - Optional prefix for CSS variable names
- * @returns CSS string with :root selector and CSS variables
+ * @param attributeSelector - Optional attribute selector (e.g., '[data-theme="light"]'). Defaults to ':root'
+ * @returns CSS string with selector and CSS variables
  */
-export declare function generateCSSVariables(theme: Theme, prefix?: string): string;
+export declare function generateCSSVariables(theme: Theme, prefix?: string, attributeSelector?: string): string;
+/**
+ * Generates CSS custom properties for all themes using attribute selectors.
+ * This allows all themes to be available simultaneously, with theme switching
+ * handled by changing the data-theme attribute.
+ *
+ * @param themes - Map of theme names to theme objects
+ * @param prefix - Optional prefix for CSS variable names
+ * @param attribute - Attribute name for theme selection (defaults to 'data-theme')
+ * @returns CSS string with all theme CSS variables
+ */
+export declare function generateAllThemeVariables(themes: Record<string, Theme>, prefix?: string, attribute?: string): string;
 /**
  * Recursively replaces theme tokens with CSS variable references in a CSS object.
  *