stoop 0.3.0 → 0.4.0

package/dist/utils/auto-preload.js

@@ -0,0 +1,167 @@
+/* eslint-disable no-console */
+/**
+ * Auto-preloading utilities for cache warming and theme preloading.
+ * Helps eliminate FOUC (Flash of Unstyled Content) by pre-compiling styles and preloading themes.
+ */
+import { detectTheme, detectThemeForSSR } from "./storage";
+/**
+ * Common UI component styles that are frequently used.
+ * These represent typical design system patterns.
+ */
+export const COMMON_UI_STYLES = [
+    // Layout primitives
+    { alignItems: "center", display: "flex", justifyContent: "center" },
+    { display: "flex", flexDirection: "column" },
+    { position: "relative" },
+    // Spacing utilities
+    { padding: "$small" },
+    { padding: "$medium" },
+    { padding: "$large" },
+    { margin: "$small" },
+    { margin: "$medium" },
+    { margin: "$large" },
+    // Typography
+    { fontSize: "$small" },
+    { fontSize: "$medium" },
+    { fontSize: "$large" },
+    { fontWeight: "$normal" },
+    { fontWeight: "$bold" },
+    // Colors (using theme tokens)
+    { color: "$text" },
+    { color: "$textSecondary" },
+    { backgroundColor: "$surface" },
+    { backgroundColor: "$surfaceHover" },
+    { border: "1px solid $border" },
+    { borderColor: "$border" },
+    // Interactive states
+    { cursor: "pointer" },
+    { opacity: 0.5 },
+    { opacity: 0.7 },
+    // Positioning
+    { bottom: 0, left: 0, right: 0, top: 0 },
+    { height: "100%", width: "100%" },
+    // Borders and radii
+    { borderRadius: "$small" },
+    { borderRadius: "$medium" },
+    { borderRadius: "$large" },
+];
+/**
+ * Automatically warms the cache with common styles.
+ *
+ * @param warmCacheFn - The warmCache function from Stoop instance
+ * @param styles - Styles to warm (defaults to COMMON_UI_STYLES)
+ * @returns Promise that resolves when warming is complete
+ */
+export async function autoWarmCache(warmCacheFn, styles = COMMON_UI_STYLES) {
+    // Warm cache asynchronously to avoid blocking
+    return new Promise((resolve) => {
+        setTimeout(() => {
+            try {
+                warmCacheFn(styles);
+                resolve();
+            }
+            catch (error) {
+                // Silently fail - cache warming is not critical
+                console.warn("[Stoop] Cache warming failed:", error);
+                resolve();
+            }
+        }, 0);
+    });
+}
+/**
+ * Automatically preloads a detected theme.
+ *
+ * @param preloadThemeFn - The preloadTheme function from Stoop instance
+ * @param options - Theme detection options
+ * @param ssr - Whether running in SSR context
+ * @returns Promise that resolves when preloading is complete
+ */
+export async function autoPreloadTheme(preloadThemeFn, options = {}, ssr = false) {
+    return new Promise((resolve) => {
+        setTimeout(() => {
+            try {
+                if (ssr) {
+                    const themeName = detectThemeForSSR(options);
+                    if (themeName && themeName !== options.default) {
+                        preloadThemeFn(themeName);
+                    }
+                    resolve({
+                        confidence: 0.3,
+                        source: "default",
+                        theme: themeName,
+                    });
+                }
+                else {
+                    const detection = detectTheme(options);
+                    if (detection.theme) {
+                        preloadThemeFn(detection.theme);
+                    }
+                    resolve(detection);
+                }
+            }
+            catch (error) {
+                console.warn("[Stoop] Theme preloading failed:", error);
+                resolve({
+                    confidence: 0.3,
+                    source: "default",
+                    theme: options.default || "light",
+                });
+            }
+        }, 0);
+    });
+}
+/**
+ * Performs automatic preloading operations based on configuration.
+ *
+ * @param warmCacheFn - The warmCache function from Stoop instance
+ * @param preloadThemeFn - The preloadTheme function from Stoop instance
+ * @param options - Auto-preload options
+ * @returns Promise that resolves with preload results
+ */
+export async function autoPreload(warmCacheFn, preloadThemeFn, options = {}) {
+    const { commonStyles = COMMON_UI_STYLES, enableCacheWarm = true, enableThemePreload = true, ssr = false, themeDetection = {}, } = options;
+    const result = {
+        cacheWarmed: false,
+        errors: [],
+        themeDetection: { confidence: 0.3, source: "default", theme: "light" },
+        themePreloaded: false,
+    };
+    const operations = [];
+    // Auto-warm cache
+    if (enableCacheWarm && commonStyles.length > 0) {
+        operations.push(autoWarmCache(warmCacheFn, commonStyles)
+            .then(() => {
+            result.cacheWarmed = true;
+        })
+            .catch((error) => {
+            result.errors.push(`Cache warming failed: ${error instanceof Error ? error.message : String(error)}`);
+        }));
+    }
+    // Auto-preload theme
+    if (enableThemePreload) {
+        operations.push(autoPreloadTheme(preloadThemeFn, themeDetection, ssr)
+            .then((detection) => {
+            result.themeDetection = detection;
+            result.themePreloaded = true;
+        })
+            .catch((error) => {
+            result.errors.push(`Theme preloading failed: ${error instanceof Error ? error.message : String(error)}`);
+        }));
+    }
+    // Wait for all operations to complete
+    await Promise.allSettled(operations);
+    return result;
+}
+/**
+ * Creates an auto-preloader with pre-configured options.
+ *
+ * @param warmCacheFn - The warmCache function from Stoop instance
+ * @param preloadThemeFn - The preloadTheme function from Stoop instance
+ * @param defaultOptions - Default auto-preload options
+ * @returns Auto-preloader function
+ */
+export function createAutoPreloader(warmCacheFn, preloadThemeFn, defaultOptions = {}) {
+    return (options = {}) => {
+        return autoPreload(warmCacheFn, preloadThemeFn, { ...defaultOptions, ...options });
+    };
+}

package/dist/utils/helpers.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Helper utilities for Stoop.
+ * Consolidates environment detection, type guards, theme validation, and utility function application.
+ */
+import type { CSS, DefaultTheme, StyledComponentRef, Theme, UtilityFunction } from "../types";
+/**
+ * Checks if code is running in a browser environment.
+ *
+ * @returns True if running in browser, false if in SSR/Node environment
+ */
+export declare function isBrowser(): boolean;
+/**
+ * Checks if running in production mode.
+ * Extracted to helper function for consistency.
+ *
+ * @returns True if running in production mode
+ */
+export declare function isProduction(): boolean;
+/**
+ * Type guard for CSS objects.
+ *
+ * @param value - Value to check
+ * @returns True if value is a CSS object
+ */
+export declare function isCSSObject(value: unknown): value is CSS;
+/**
+ * Checks if a value is a styled component reference.
+ * Consolidated function used across the codebase.
+ *
+ * @param value - Value to check
+ * @returns True if value is a styled component reference
+ */
+export declare function isStyledComponentRef(value: unknown): value is StyledComponentRef;
+/**
+ * Type guard for valid CSS objects (excludes styled component references).
+ *
+ * @param value - Value to check
+ * @returns True if value is a valid CSS object
+ */
+export declare function isValidCSSObject(value: unknown): value is CSS;
+/**
+ * Type guard for theme objects.
+ *
+ * @param value - Value to check
+ * @returns True if value is a theme object
+ */
+export declare function isThemeObject(value: unknown): value is Theme;
+/**
+ * Validates that a theme object only contains approved scales.
+ * In production, skips all validation for performance.
+ *
+ * @param theme - Theme object to validate
+ * @returns Validated theme as DefaultTheme
+ * @throws Error if theme contains invalid scales (development only)
+ */
+export declare function validateTheme(theme: unknown): DefaultTheme;
+/**
+ * Applies utility functions to transform shorthand properties into CSS.
+ *
+ * @param styles - CSS object to process
+ * @param utils - Optional utility functions object
+ * @returns CSS object with utilities applied
+ */
+export declare function applyUtilities(styles: CSS, utils?: Record<string, UtilityFunction>): CSS;

package/dist/utils/helpers.js

@@ -0,0 +1,150 @@
+/**
+ * Helper utilities for Stoop.
+ * Consolidates environment detection, type guards, theme validation, and utility function application.
+ */
+import { APPROVED_THEME_SCALES } from "../constants";
+// ============================================================================
+// Environment Detection
+// ============================================================================
+/**
+ * Checks if code is running in a browser environment.
+ *
+ * @returns True if running in browser, false if in SSR/Node environment
+ */
+export function isBrowser() {
+    return (typeof window !== "undefined" &&
+        typeof document !== "undefined" &&
+        typeof window.document === "object" &&
+        // Use document.createElement instead of requestAnimationFrame for better compatibility
+        // requestAnimationFrame may not exist in test environments (jsdom)
+        typeof document.createElement === "function");
+}
+/**
+ * Checks if running in production mode.
+ * Extracted to helper function for consistency.
+ *
+ * @returns True if running in production mode
+ */
+export function isProduction() {
+    return typeof process !== "undefined" && process.env?.NODE_ENV === "production";
+}
+// ============================================================================
+// Type Guards
+// ============================================================================
+/**
+ * Type guard for CSS objects.
+ *
+ * @param value - Value to check
+ * @returns True if value is a CSS object
+ */
+export function isCSSObject(value) {
+    return typeof value === "object" && value !== null;
+}
+/**
+ * Checks if a value is a styled component reference.
+ * Consolidated function used across the codebase.
+ *
+ * @param value - Value to check
+ * @returns True if value is a styled component reference
+ */
+export function isStyledComponentRef(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "__isStoopStyled" in value &&
+        "__stoopClassName" in value &&
+        value.__isStoopStyled === true);
+}
+/**
+ * Type guard for valid CSS objects (excludes styled component references).
+ *
+ * @param value - Value to check
+ * @returns True if value is a valid CSS object
+ */
+export function isValidCSSObject(value) {
+    return isCSSObject(value) && !isStyledComponentRef(value);
+}
+/**
+ * Type guard for theme objects.
+ *
+ * @param value - Value to check
+ * @returns True if value is a theme object
+ */
+export function isThemeObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// ============================================================================
+// Theme Validation
+// ============================================================================
+/**
+ * Validates that a theme object only contains approved scales.
+ * In production, skips all validation for performance.
+ *
+ * @param theme - Theme object to validate
+ * @returns Validated theme as DefaultTheme
+ * @throws Error if theme contains invalid scales (development only)
+ */
+export function validateTheme(theme) {
+    if (!theme || typeof theme !== "object" || Array.isArray(theme)) {
+        throw new Error("[Stoop] Theme must be a non-null object");
+    }
+    // Skip all validation in production for performance
+    if (isProduction()) {
+        return theme;
+    }
+    const themeObj = theme;
+    const invalidScales = [];
+    for (const key in themeObj) {
+        if (key === "media") {
+            continue;
+        }
+        if (!APPROVED_THEME_SCALES.includes(key)) {
+            invalidScales.push(key);
+        }
+    }
+    if (invalidScales.length > 0) {
+        const errorMessage = `[Stoop] Theme contains invalid scales: ${invalidScales.join(", ")}. ` +
+            `Only these scales are allowed: ${APPROVED_THEME_SCALES.join(", ")}`;
+        throw new Error(errorMessage);
+    }
+    return theme;
+}
+// ============================================================================
+// Utility Function Application
+// ============================================================================
+/**
+ * Applies utility functions to transform shorthand properties into CSS.
+ *
+ * @param styles - CSS object to process
+ * @param utils - Optional utility functions object
+ * @returns CSS object with utilities applied
+ */
+export function applyUtilities(styles, utils) {
+    if (!utils || !styles || typeof styles !== "object") {
+        return styles;
+    }
+    const result = {};
+    const utilityKeys = Object.keys(utils);
+    for (const key in styles) {
+        const value = styles[key];
+        if (utilityKeys.includes(key) && utils[key]) {
+            try {
+                const utilityResult = utils[key](value);
+                if (utilityResult && typeof utilityResult === "object") {
+                    for (const utilKey in utilityResult) {
+                        result[utilKey] = utilityResult[utilKey];
+                    }
+                }
+            }
+            catch {
+                result[key] = value;
+            }
+        }
+        else if (isCSSObject(value)) {
+            result[key] = applyUtilities(value, utils);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}

package/dist/utils/storage.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Storage and theme detection utilities.
+ * Provides simplified localStorage and cookie management, plus automatic theme selection.
+ * Supports SSR compatibility and error handling.
+ */
+import type { ThemeDetectionOptions, ThemeDetectionResult, StorageOptions, StorageResult } from "../types";
+/**
+ * Safely gets a value from localStorage.
+ *
+ * @param key - Storage key
+ * @returns Storage result
+ */
+export declare function getFromStorage(key: string): StorageResult<string | null>;
+/**
+ * Safely sets a value in localStorage.
+ *
+ * @param key - Storage key
+ * @param value - Value to store
+ * @returns Storage result
+ */
+export declare function setInStorage(key: string, value: string): StorageResult<void>;
+/**
+ * Safely removes a value from localStorage.
+ *
+ * @param key - Storage key
+ * @returns Storage result
+ */
+export declare function removeFromStorage(key: string): StorageResult<void>;
+/**
+ * Gets a cookie value.
+ *
+ * @param name - Cookie name
+ * @returns Cookie value or null if not found
+ */
+export declare function getCookie(name: string): string | null;
+/**
+ * Sets a cookie value.
+ *
+ * @param name - Cookie name
+ * @param value - Cookie value
+ * @param options - Cookie options
+ * @returns Success status
+ */
+export declare function setCookie(name: string, value: string, options?: Omit<StorageOptions, "type"> & {
+    maxAge?: number;
+    path?: string;
+    secure?: boolean;
+}): boolean;
+/**
+ * Removes a cookie by setting it to expire.
+ *
+ * @param name - Cookie name
+ * @param path - Cookie path
+ * @returns Success status
+ */
+export declare function removeCookie(name: string, path?: string): boolean;
+/**
+ * Unified storage API that works with both localStorage and cookies.
+ *
+ * @param key - Storage key
+ * @param options - Storage options
+ * @returns Storage result
+ */
+export declare function getStorage(key: string, options?: StorageOptions): StorageResult<string | null>;
+/**
+ * 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 declare function setStorage(key: string, value: string, options?: StorageOptions): StorageResult<void>;
+/**
+ * Unified storage API that works with both localStorage and cookies.
+ *
+ * @param key - Storage key
+ * @param options - Storage options
+ * @returns Storage result
+ */
+export declare function removeStorage(key: string, options?: StorageOptions): StorageResult<void>;
+/**
+ * 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 declare function getJsonFromStorage<T>(key: string, fallback: T, options?: StorageOptions): StorageResult<T>;
+/**
+ * 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 declare function setJsonInStorage<T>(key: string, value: T, options?: StorageOptions): StorageResult<void>;
+/**
+ * Creates a typed storage interface for a specific key.
+ *
+ * @param key - Storage key
+ * @param options - Storage options
+ * @returns Typed storage interface
+ */
+export declare function createStorage<T = string>(key: string, options?: StorageOptions): {
+    get: () => StorageResult<string | null>;
+    getJson: (fallback: T) => StorageResult<T>;
+    remove: () => StorageResult<void>;
+    set: (value: string) => StorageResult<void>;
+    setJson: (value: T) => StorageResult<void>;
+};
+/**
+ * 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 declare function detectTheme(options?: ThemeDetectionOptions): ThemeDetectionResult;
+/**
+ * Creates a theme detector function with pre-configured options.
+ *
+ * @param options - Theme detection options
+ * @returns Theme detection function
+ */
+export declare function createThemeDetector(options: ThemeDetectionOptions): () => ThemeDetectionResult;
+/**
+ * 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 declare function detectThemeForSSR(options?: ThemeDetectionOptions): string;
+/**
+ * Listens for system theme changes and calls callback when changed.
+ *
+ * @param callback - Function to call when system theme changes
+ * @returns Cleanup function
+ */
+export declare function onSystemThemeChange(callback: (theme: "dark" | "light") => void): () => void;