stoop 0.6.1 → 0.6.2

package/dist/api/theme-provider.js

@@ -0,0 +1,199 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Theme Provider component and hook.
+ * Manages theme state, localStorage persistence, cookie sync, and centralized theme variable updates.
+ * Includes the useTheme hook for accessing theme management context.
+ *
+ * CLIENT-ONLY: This module uses React hooks (useState, useLayoutEffect, useCallback, useMemo)
+ * and MUST have "use client" directive for Next.js App Router compatibility.
+ */
+import { createContext, useCallback, useContext, useLayoutEffect, useMemo, useRef, useState, } from "react";
+import { injectAllThemes } from "../core/theme-manager";
+import { isBrowser, isProduction } from "../utils/helpers";
+import { getCookie, setCookie, getFromStorage, setInStorage } from "../utils/storage";
+/**
+ * Syncs a theme value between cookie and localStorage.
+ *
+ * @param value - Theme value to sync
+ * @param cookieKey - Cookie key (if undefined, cookie sync is skipped)
+ * @param storageKey - LocalStorage key
+ */
+function syncThemeStorage(value, cookieKey, storageKey) {
+    if (!isBrowser()) {
+        return;
+    }
+    const cookieValue = cookieKey ? getCookie(cookieKey) : null;
+    const localStorageResult = getFromStorage(storageKey);
+    const localStorageValue = localStorageResult.success ? localStorageResult.value : null;
+    if (cookieValue === value && localStorageValue !== value) {
+        setInStorage(storageKey, value);
+    }
+    if (localStorageValue === value && cookieKey && cookieValue !== value) {
+        setCookie(cookieKey, value);
+    }
+}
+/**
+ * Reads theme from cookie or localStorage, preferring cookie if available.
+ *
+ * @param cookieKey - Cookie key (if undefined, cookie is not checked)
+ * @param storageKey - LocalStorage key
+ * @param themes - Available themes map for validation
+ * @returns Theme name or null if not found or invalid
+ */
+function readThemeFromStorage(cookieKey, storageKey, themes) {
+    if (!isBrowser()) {
+        return null;
+    }
+    if (cookieKey !== undefined) {
+        const cookieValue = getCookie(cookieKey);
+        if (cookieValue && themes[cookieValue]) {
+            return cookieValue;
+        }
+    }
+    const storageResult = getFromStorage(storageKey);
+    const stored = storageResult.success ? storageResult.value : null;
+    if (stored && themes[stored]) {
+        return stored;
+    }
+    return null;
+}
+/**
+ * Creates a Provider component for theme management.
+ *
+ * @param themes - Map of theme names to theme objects
+ * @param defaultTheme - Default theme object
+ * @param prefix - Optional prefix for CSS variable scoping
+ * @param globalCss - Optional global CSS object from config
+ * @param globalCssFunction - Optional globalCss function from createStoop
+ * @returns Provider component, theme context, and theme management context
+ *
+ * @remarks
+ * To prevent FOUC (Flash of Unstyled Content) when a user has a non-default theme stored,
+ * call `preloadTheme()` from your stoop instance in a script tag before React hydrates.
+ * Note: `preloadTheme()` takes no parameters and always preloads all configured themes.
+ *
+ * ```html
+ * <script>
+ *   // Preload all themes before React renders
+ *   stoopInstance.preloadTheme();
+ * </script>
+ * ```
+ */
+export function createProvider(themes, defaultTheme, prefix = "stoop", globalCss, globalCssFunction) {
+    const ThemeContext = createContext(null);
+    const ThemeManagementContext = createContext(null);
+    const availableThemeNames = Object.keys(themes);
+    const firstThemeName = availableThemeNames[0] || "default";
+    const configGlobalStyles = globalCss && globalCssFunction ? globalCssFunction(globalCss) : undefined;
+    function Provider({ attribute = "data-theme", children, cookieKey, defaultTheme: defaultThemeProp, storageKey = "stoop-theme", }) {
+        const [themeName, setThemeNameState] = useState(defaultThemeProp || firstThemeName);
+        const hasHydratedRef = useRef(false);
+        useLayoutEffect(() => {
+            if (!isBrowser() || hasHydratedRef.current) {
+                return;
+            }
+            const stored = readThemeFromStorage(cookieKey, storageKey, themes);
+            if (stored) {
+                syncThemeStorage(stored, cookieKey, storageKey);
+                if (stored !== themeName) {
+                    setThemeNameState(stored);
+                }
+            }
+            hasHydratedRef.current = true;
+        }, [cookieKey, storageKey, themes]);
+        useLayoutEffect(() => {
+            if (!isBrowser()) {
+                return;
+            }
+            const handleStorageChange = (e) => {
+                if (e.key === storageKey && e.newValue && themes[e.newValue] && e.newValue !== themeName) {
+                    setThemeNameState(e.newValue);
+                    syncThemeStorage(e.newValue, cookieKey, storageKey);
+                }
+            };
+            window.addEventListener("storage", handleStorageChange);
+            return () => {
+                window.removeEventListener("storage", handleStorageChange);
+            };
+        }, [storageKey, cookieKey, themeName, themes]);
+        const currentTheme = useMemo(() => {
+            return themes[themeName] || themes[defaultThemeProp || firstThemeName] || defaultTheme;
+        }, [themeName, defaultThemeProp, firstThemeName, themes, defaultTheme]);
+        const themesInjectedRef = useRef(false);
+        const globalStylesInjectedRef = useRef(false);
+        useLayoutEffect(() => {
+            if (!isBrowser() || themesInjectedRef.current) {
+                return;
+            }
+            injectAllThemes(themes, prefix, attribute);
+            themesInjectedRef.current = true;
+        }, [themes, prefix, attribute]);
+        useLayoutEffect(() => {
+            if (!isBrowser() || globalStylesInjectedRef.current) {
+                return;
+            }
+            if (configGlobalStyles) {
+                configGlobalStyles();
+                globalStylesInjectedRef.current = true;
+            }
+        }, [configGlobalStyles]);
+        useLayoutEffect(() => {
+            if (!isBrowser()) {
+                return;
+            }
+            if (attribute) {
+                document.documentElement.setAttribute(attribute, themeName);
+            }
+        }, [themeName, attribute]);
+        const setTheme = useCallback((newThemeName) => {
+            if (themes[newThemeName]) {
+                setThemeNameState(newThemeName);
+                setInStorage(storageKey, newThemeName);
+                syncThemeStorage(newThemeName, cookieKey, storageKey);
+            }
+            else if (!isProduction()) {
+                // eslint-disable-next-line no-console
+                console.warn(`[Stoop] Theme "${newThemeName}" not found. Available themes: ${availableThemeNames.join(", ")}`);
+            }
+        }, [storageKey, cookieKey, themes, availableThemeNames, themeName]);
+        const themeContextValue = useMemo(() => ({
+            theme: currentTheme,
+            themeName,
+        }), [currentTheme, themeName]);
+        const toggleTheme = useCallback(() => {
+            const currentIndex = availableThemeNames.indexOf(themeName);
+            const nextIndex = (currentIndex + 1) % availableThemeNames.length;
+            const newTheme = availableThemeNames[nextIndex];
+            setTheme(newTheme);
+        }, [themeName, setTheme, availableThemeNames]);
+        const managementContextValue = useMemo(() => ({
+            availableThemes: availableThemeNames,
+            setTheme,
+            theme: currentTheme,
+            themeName,
+            toggleTheme,
+        }), [currentTheme, themeName, setTheme, toggleTheme]);
+        return (_jsx(ThemeContext.Provider, { value: themeContextValue, children: _jsx(ThemeManagementContext.Provider, { value: managementContextValue, children: children }) }));
+    }
+    return {
+        Provider,
+        ThemeContext,
+        ThemeManagementContext,
+    };
+}
+/**
+ * Creates a useTheme hook for a specific theme management context.
+ *
+ * @param ThemeManagementContext - React context for theme management
+ * @returns Hook function that returns theme management context value
+ */
+export function createUseThemeHook(ThemeManagementContext) {
+    return function useTheme() {
+        const context = useContext(ThemeManagementContext);
+        if (!context) {
+            throw new Error("useTheme must be used within a Provider");
+        }
+        return context;
+    };
+}

package/dist/constants.js

@@ -0,0 +1,154 @@
+/**
+ * Shared constants used throughout the library.
+ * Includes cache size limits and nesting depth limits.
+ */
+export const EMPTY_CSS = Object.freeze({});
+export const MAX_CSS_CACHE_SIZE = 10000;
+export const MAX_CLASS_NAME_CACHE_SIZE = 5000;
+export const MAX_CSS_NESTING_DEPTH = 10;
+/**
+ * Cache size limits for various LRU caches.
+ */
+export const KEYFRAME_CACHE_LIMIT = 500;
+export const SANITIZE_CACHE_SIZE_LIMIT = 1000;
+/**
+ * Cookie defaults.
+ */
+export const DEFAULT_COOKIE_MAX_AGE = 31536000; // 1 year in seconds
+export const DEFAULT_COOKIE_PATH = "/";
+/**
+ * Approved theme scales - only these scales are allowed in theme objects.
+ */
+export const APPROVED_THEME_SCALES = [
+    "colors",
+    "opacities",
+    "space",
+    "radii",
+    "sizes",
+    "fonts",
+    "fontWeights",
+    "fontSizes",
+    "lineHeights",
+    "letterSpacings",
+    "shadows",
+    "zIndices",
+    "transitions",
+];
+/**
+ * Default themeMap mapping CSS properties to theme scales.
+ * Covers common CSS properties for zero-config experience.
+ * Missing properties gracefully fallback to pattern-based auto-detection.
+ */
+export const DEFAULT_THEME_MAP = {
+    accentColor: "colors",
+    animation: "transitions",
+    animationDelay: "transitions",
+    animationDuration: "transitions",
+    animationTimingFunction: "transitions",
+    backdropFilter: "shadows",
+    background: "colors",
+    backgroundColor: "colors",
+    blockSize: "sizes",
+    border: "colors",
+    borderBlockColor: "colors",
+    borderBlockEndColor: "colors",
+    borderBlockStartColor: "colors",
+    borderBottomColor: "colors",
+    borderBottomLeftRadius: "radii",
+    borderBottomRightRadius: "radii",
+    borderColor: "colors",
+    borderEndEndRadius: "radii",
+    borderEndStartRadius: "radii",
+    borderInlineColor: "colors",
+    borderInlineEndColor: "colors",
+    borderInlineStartColor: "colors",
+    borderLeftColor: "colors",
+    borderRadius: "radii",
+    borderRightColor: "colors",
+    borderStartEndRadius: "radii",
+    borderStartStartRadius: "radii",
+    borderTopColor: "colors",
+    borderTopLeftRadius: "radii",
+    borderTopRightRadius: "radii",
+    bottom: "space",
+    boxShadow: "shadows",
+    caretColor: "colors",
+    color: "colors",
+    columnGap: "space",
+    columnRuleColor: "colors",
+    fill: "colors",
+    filter: "shadows",
+    flexBasis: "sizes",
+    floodColor: "colors",
+    font: "fontSizes",
+    fontFamily: "fonts",
+    fontSize: "fontSizes",
+    fontWeight: "fontWeights",
+    gap: "space",
+    gridColumnGap: "space",
+    gridGap: "space",
+    gridRowGap: "space",
+    height: "sizes",
+    inlineSize: "sizes",
+    inset: "space",
+    insetBlock: "space",
+    insetBlockEnd: "space",
+    insetBlockStart: "space",
+    insetInline: "space",
+    insetInlineEnd: "space",
+    insetInlineStart: "space",
+    left: "space",
+    letterSpacing: "letterSpacings",
+    lightingColor: "colors",
+    lineHeight: "lineHeights",
+    margin: "space",
+    marginBlock: "space",
+    marginBlockEnd: "space",
+    marginBlockStart: "space",
+    marginBottom: "space",
+    marginInline: "space",
+    marginInlineEnd: "space",
+    marginInlineStart: "space",
+    marginLeft: "space",
+    marginRight: "space",
+    marginTop: "space",
+    maxBlockSize: "sizes",
+    maxHeight: "sizes",
+    maxInlineSize: "sizes",
+    maxWidth: "sizes",
+    minBlockSize: "sizes",
+    minHeight: "sizes",
+    minInlineSize: "sizes",
+    minWidth: "sizes",
+    opacity: "opacities",
+    outline: "colors",
+    outlineColor: "colors",
+    padding: "space",
+    paddingBlock: "space",
+    paddingBlockEnd: "space",
+    paddingBlockStart: "space",
+    paddingBottom: "space",
+    paddingInline: "space",
+    paddingInlineEnd: "space",
+    paddingInlineStart: "space",
+    paddingLeft: "space",
+    paddingRight: "space",
+    paddingTop: "space",
+    right: "space",
+    rowGap: "space",
+    size: "sizes",
+    stopColor: "colors",
+    stroke: "colors",
+    textDecorationColor: "colors",
+    textEmphasisColor: "colors",
+    textShadow: "shadows",
+    top: "space",
+    transition: "transitions",
+    transitionDelay: "transitions",
+    transitionDuration: "transitions",
+    transitionProperty: "transitions",
+    transitionTimingFunction: "transitions",
+    width: "sizes",
+    zIndex: "zIndices",
+};
+export const STOOP_COMPONENT_SYMBOL = Symbol.for("stoop.component");

package/dist/core/cache.js

@@ -0,0 +1,66 @@
+/**
+ * CSS compilation caching system.
+ * Tracks compiled CSS strings and class names to prevent duplicate work.
+ * Implements LRU (Least Recently Used) eviction when cache size limits are exceeded.
+ */
+import { MAX_CLASS_NAME_CACHE_SIZE, MAX_CSS_CACHE_SIZE } from "../constants";
+/**
+ * LRU Cache implementation for class names and CSS strings.
+ * Automatically evicts least recently used entries when size limit is exceeded.
+ */
+export class LRUCache extends Map {
+    maxSize;
+    constructor(maxSize) {
+        super();
+        this.maxSize = maxSize;
+    }
+    get(key) {
+        const value = super.get(key);
+        if (value !== undefined) {
+            super.delete(key);
+            super.set(key, value);
+        }
+        return value;
+    }
+    set(key, value) {
+        if (super.has(key)) {
+            super.delete(key);
+        }
+        else if (this.size >= this.maxSize) {
+            const firstKey = this.keys().next().value;
+            if (firstKey !== undefined) {
+                super.delete(firstKey);
+            }
+        }
+        super.set(key, value);
+        return this;
+    }
+}
+export const classNameCache = new LRUCache(MAX_CLASS_NAME_CACHE_SIZE);
+export const cssStringCache = new LRUCache(MAX_CSS_CACHE_SIZE);
+const injectedStylesCache = new Set();
+/**
+ * Checks if a CSS string has been injected.
+ *
+ * @param css - CSS string to check
+ * @returns True if CSS has been injected
+ */
+export function isCachedStyle(css) {
+    return injectedStylesCache.has(css);
+}
+/**
+ * Marks a CSS string as injected.
+ *
+ * @param css - CSS string to cache
+ */
+export function markStyleAsCached(css) {
+    injectedStylesCache.add(css);
+}
+/**
+ * Clears all cached styles.
+ */
+export function clearStyleCache() {
+    classNameCache.clear();
+    cssStringCache.clear();
+    injectedStylesCache.clear();
+}