stoop 0.2.1 → 0.3.0

package/dist/api/create-theme.js

@@ -0,0 +1,43 @@
+/**
+ * Theme extension API.
+ * Creates a function that deep merges theme overrides with a base theme.
+ */
+import { validateTheme } from "../utils/theme-validation";
+import { isThemeObject } from "../utils/type-guards";
+/**
+ * Creates a function that extends a base theme with overrides.
+ * The returned function deep merges theme overrides with the base theme.
+ *
+ * @param baseTheme - Base theme to extend
+ * @returns Function that accepts theme overrides and returns a merged theme
+ */
+export function createTheme(baseTheme) {
+    return function createTheme(themeOverrides) {
+        const validatedOverrides = validateTheme(themeOverrides);
+        function deepMerge(target, source) {
+            const result = { ...target };
+            const sourceKeys = Object.keys(source);
+            for (const key of sourceKeys) {
+                const sourceValue = source[key];
+                const targetValue = target[key];
+                if (isThemeObject(sourceValue) && isThemeObject(targetValue)) {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    result[key] = { ...targetValue, ...sourceValue };
+                }
+                else if (sourceValue !== undefined) {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    result[key] = sourceValue;
+                }
+            }
+            const targetKeys = Object.keys(target);
+            for (const key of targetKeys) {
+                if (!(key in result)) {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    result[key] = target[key];
+                }
+            }
+            return result;
+        }
+        return deepMerge(baseTheme, validatedOverrides);
+    };
+}

package/dist/api/css.js

@@ -0,0 +1,20 @@
+/**
+ * CSS class generation API.
+ * Creates a function that compiles CSS objects into class names.
+ */
+import { compileCSS } from "../core/compiler";
+/**
+ * Creates a CSS function that compiles CSS objects into class names.
+ *
+ * @param defaultTheme - Default theme for token resolution
+ * @param prefix - Optional prefix for generated class names
+ * @param media - Optional media query breakpoints
+ * @param utils - Optional utility functions
+ * @param themeMap - Optional theme scale mappings
+ * @returns Function that accepts CSS objects and returns class names
+ */
+export function createCSSFunction(defaultTheme, prefix = "stoop", media, utils, themeMap) {
+    return function css(styles) {
+        return compileCSS(styles, defaultTheme, prefix, media, utils, themeMap);
+    };
+}

package/dist/api/global-css.d.ts

@@ -4,15 +4,4 @@
  * Supports media queries, nested selectors, and theme tokens.
  */
 import type { CSS, Theme, ThemeScale, UtilityFunction } from "../types";
-/**
- * Creates a global CSS injection function.
- * Injects styles directly into the document with deduplication support.
- *
- * @param defaultTheme - Default theme for token resolution
- * @param prefix - Optional prefix for CSS rules
- * @param media - Optional media query breakpoints
- * @param utils - Optional utility functions
- * @param themeMap - Optional theme scale mappings
- * @returns Function that accepts CSS objects and returns a cleanup function
- */
 export declare function createGlobalCSSFunction(defaultTheme: Theme, prefix?: string, media?: Record<string, string>, utils?: Record<string, UtilityFunction>, themeMap?: Record<string, ThemeScale>): (styles: CSS) => () => void;

package/dist/api/global-css.js

@@ -0,0 +1,89 @@
+/**
+ * Global CSS injection API.
+ * Creates a function that injects global styles into the document.
+ * Supports media queries, nested selectors, and theme tokens.
+ */
+import { MAX_CSS_NESTING_DEPTH } from "../constants";
+import { injectCSS } from "../inject";
+import { escapeCSSValue, hashObject, sanitizeCSSPropertyName, sanitizeCSSSelector, sanitizeMediaQuery, sanitizePrefix, } from "../utils/string";
+import { replaceThemeTokensWithVars } from "../utils/theme";
+import { isCSSObject } from "../utils/type-guards";
+import { applyUtilities } from "../utils/utilities";
+/**
+ * Creates a global CSS injection function.
+ * Injects styles directly into the document with deduplication support.
+ *
+ * @param defaultTheme - Default theme for token resolution
+ * @param prefix - Optional prefix for CSS rules
+ * @param media - Optional media query breakpoints
+ * @param utils - Optional utility functions
+ * @param themeMap - Optional theme scale mappings
+ * @returns Function that accepts CSS objects and returns a cleanup function
+ */
+const globalInjectedStyles = new WeakMap();
+function getInjectedSet(theme) {
+    let set = globalInjectedStyles.get(theme);
+    if (!set) {
+        set = new Set();
+        globalInjectedStyles.set(theme, set);
+    }
+    return set;
+}
+export function createGlobalCSSFunction(defaultTheme, prefix = "stoop", media, utils, themeMap) {
+    return function globalCss(styles) {
+        const injected = getInjectedSet(defaultTheme);
+        const cssKey = hashObject(styles);
+        if (injected.has(cssKey)) {
+            return () => { };
+        }
+        injected.add(cssKey);
+        function generateGlobalCSS(obj, depth = 0) {
+            if (depth > MAX_CSS_NESTING_DEPTH) {
+                return "";
+            }
+            let result = "";
+            const sortedEntries = Object.entries(obj).sort(([a], [b]) => a.localeCompare(b));
+            sortedEntries.forEach(([key, value]) => {
+                if (isCSSObject(value)) {
+                    if (media && key in media) {
+                        const mediaQuery = sanitizeMediaQuery(media[key]);
+                        if (mediaQuery) {
+                            const nestedCss = generateGlobalCSS(value, depth + 1);
+                            result += `${mediaQuery} { ${nestedCss} }`;
+                        }
+                    }
+                    else if (key.startsWith("@")) {
+                        const sanitizedKey = sanitizeCSSSelector(key);
+                        if (sanitizedKey) {
+                            const nestedCss = generateGlobalCSS(value, depth + 1);
+                            result += `${sanitizedKey} { ${nestedCss} }`;
+                        }
+                    }
+                    else {
+                        const sanitizedKey = sanitizeCSSSelector(key);
+                        if (sanitizedKey) {
+                            const nestedCss = generateGlobalCSS(value, depth + 1);
+                            result += `${sanitizedKey} { ${nestedCss} }`;
+                        }
+                    }
+                }
+                else if (value !== undefined) {
+                    const property = sanitizeCSSPropertyName(key);
+                    if (property && (typeof value === "string" || typeof value === "number")) {
+                        const escapedValue = escapeCSSValue(value);
+                        result += `${property}: ${escapedValue}; `;
+                    }
+                }
+            });
+            return result;
+        }
+        const sanitizedPrefix = sanitizePrefix(prefix);
+        const stylesWithUtils = applyUtilities(styles, utils);
+        const themedStyles = replaceThemeTokensWithVars(stylesWithUtils, defaultTheme, themeMap);
+        const cssText = generateGlobalCSS(themedStyles);
+        injectCSS(cssText, sanitizedPrefix, `__global_${cssKey}`);
+        return () => {
+            injected.delete(cssKey);
+        };
+    };
+}

package/dist/api/keyframes.js

@@ -0,0 +1,95 @@
+/**
+ * CSS keyframes animation API.
+ * Creates a function that generates and injects @keyframes rules.
+ * Caches animations by content hash to prevent duplicates.
+ */
+import { LRUCache } from "../core/cache";
+import { injectCSS } from "../inject";
+import { hashObject, sanitizeCSSPropertyName, sanitizePrefix, validateKeyframeKey, } from "../utils/string";
+import { replaceThemeTokensWithVars } from "../utils/theme";
+/**
+ * Converts a keyframes object to a CSS @keyframes rule string.
+ *
+ * @param keyframesObj - Keyframes object with percentage/from/to keys
+ * @param animationName - Name for the animation
+ * @param theme - Optional theme for token resolution
+ * @param themeMap - Optional theme scale mappings
+ * @returns CSS @keyframes rule string
+ */
+function keyframesToCSS(keyframesObj, animationName, theme, themeMap) {
+    let css = `@keyframes ${animationName} {`;
+    const sortedKeys = Object.keys(keyframesObj).sort((a, b) => {
+        const aNum = parseFloat(a.replace("%", ""));
+        const bNum = parseFloat(b.replace("%", ""));
+        if (a === "from") {
+            return -1;
+        }
+        if (b === "from") {
+            return 1;
+        }
+        if (a === "to") {
+            return 1;
+        }
+        if (b === "to") {
+            return -1;
+        }
+        return aNum - bNum;
+    });
+    for (const key of sortedKeys) {
+        if (!validateKeyframeKey(key)) {
+            continue;
+        }
+        const styles = keyframesObj[key];
+        if (!styles || typeof styles !== "object") {
+            continue;
+        }
+        css += ` ${key} {`;
+        const themedStyles = replaceThemeTokensWithVars(styles, theme, themeMap);
+        // Sort properties for deterministic CSS generation
+        const sortedProps = Object.keys(themedStyles).sort();
+        for (const prop of sortedProps) {
+            const value = themedStyles[prop];
+            if (value !== undefined && (typeof value === "string" || typeof value === "number")) {
+                const sanitizedProp = sanitizeCSSPropertyName(prop);
+                if (sanitizedProp) {
+                    // Don't escape keyframe values - escaping breaks complex CSS functions
+                    const cssValue = String(value);
+                    css += ` ${sanitizedProp}: ${cssValue};`;
+                }
+            }
+        }
+        css += " }";
+    }
+    css += " }";
+    return css;
+}
+const KEYFRAME_CACHE_LIMIT = 500;
+/**
+ * Creates a keyframes animation function.
+ * Generates and injects @keyframes rules with caching to prevent duplicates.
+ *
+ * @param prefix - Optional prefix for animation names
+ * @param theme - Optional theme for token resolution
+ * @param themeMap - Optional theme scale mappings
+ * @returns Function that accepts keyframes objects and returns animation names
+ */
+export function createKeyframesFunction(prefix = "stoop", theme, themeMap) {
+    const sanitizedPrefix = sanitizePrefix(prefix);
+    const animationCache = new LRUCache(KEYFRAME_CACHE_LIMIT);
+    return function keyframes(keyframesObj) {
+        const keyframesKey = hashObject(keyframesObj);
+        const cachedName = animationCache.get(keyframesKey);
+        if (cachedName) {
+            return cachedName;
+        }
+        const hashValue = keyframesKey.slice(0, 8);
+        const animationName = sanitizedPrefix
+            ? `${sanitizedPrefix}-${hashValue}`
+            : `stoop-${hashValue}`;
+        const css = keyframesToCSS(keyframesObj, animationName, theme, themeMap);
+        const ruleKey = `__keyframes_${animationName}`;
+        injectCSS(css, sanitizedPrefix, ruleKey);
+        animationCache.set(keyframesKey, animationName);
+        return animationName;
+    };
+}

package/dist/api/provider.d.ts

@@ -7,13 +7,13 @@ import type { ProviderProps, Theme, ThemeContextValue, ThemeManagementContextVal
 /**
  * Creates a Provider component for theme management.
  *
- * @param ThemeContext - Stoop's theme context for styled components
  * @param themes - Map of theme names to theme objects
  * @param defaultTheme - Default theme object
  * @param prefix - Optional prefix for CSS variable scoping
- * @returns Provider component and theme management context
+ * @returns Provider component, theme context, and theme management context
  */
-export declare function createProvider(ThemeContext: Context<ThemeContextValue | null>, themes: Record<string, Theme>, defaultTheme: Theme, prefix?: string): {
+export declare function createProvider(themes: Record<string, Theme>, defaultTheme: Theme, prefix?: string): {
     Provider: ComponentType<ProviderProps>;
+    ThemeContext: Context<ThemeContextValue | null>;
     ThemeManagementContext: Context<ThemeManagementContextValue | null>;
 };

package/dist/api/provider.js

@@ -0,0 +1,109 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Theme Provider component.
+ * Manages theme state, localStorage persistence, and centralized theme variable updates.
+ */
+import { createContext, useCallback, useLayoutEffect, useMemo, useState, } from "react";
+import { updateThemeVariables } from "../core/theme-manager";
+import { isBrowser } from "../utils/environment";
+/**
+ * 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
+ * @returns Provider component, theme context, and theme management context
+ */
+export function createProvider(themes, defaultTheme, prefix = "stoop") {
+    const ThemeContext = createContext(null);
+    const ThemeManagementContext = createContext(null);
+    const availableThemeNames = Object.keys(themes);
+    const firstThemeName = availableThemeNames[0] || "default";
+    function Provider({ attribute = "data-theme", children, defaultTheme: defaultThemeProp, storageKey = "stoop-theme", }) {
+        // SSR-safe initialization: always start with default, then hydrate from localStorage
+        const [themeName, setThemeNameState] = useState(() => {
+            // During SSR, always return the default theme
+            if (!isBrowser()) {
+                return defaultThemeProp || firstThemeName;
+            }
+            // On client, try to read from localStorage
+            try {
+                const stored = localStorage.getItem(storageKey);
+                if (stored && themes[stored]) {
+                    return stored;
+                }
+            }
+            catch {
+                // localStorage access failed (e.g., in private browsing mode)
+            }
+            return defaultThemeProp || firstThemeName;
+        });
+        // Hydrate from localStorage after mount to prevent hydration mismatch
+        useLayoutEffect(() => {
+            if (!isBrowser()) {
+                return;
+            }
+            try {
+                const stored = localStorage.getItem(storageKey);
+                if (stored && themes[stored] && stored !== themeName) {
+                    setThemeNameState(stored);
+                }
+            }
+            catch {
+                // localStorage access failed
+            }
+        }, [storageKey, themeName]);
+        const currentTheme = useMemo(() => {
+            return themes[themeName] || themes[defaultThemeProp || firstThemeName] || defaultTheme;
+        }, [themeName, defaultThemeProp, firstThemeName, themes]);
+        useLayoutEffect(() => {
+            if (currentTheme) {
+                updateThemeVariables(currentTheme, prefix);
+            }
+        }, [currentTheme, prefix]);
+        useLayoutEffect(() => {
+            if (isBrowser() && attribute) {
+                document.documentElement.setAttribute(attribute, themeName);
+            }
+        }, [themeName, attribute]);
+        const setTheme = useCallback((newThemeName) => {
+            if (themes[newThemeName]) {
+                setThemeNameState(newThemeName);
+                try {
+                    localStorage.setItem(storageKey, newThemeName);
+                }
+                catch {
+                    // localStorage access failed (e.g., in private browsing mode)
+                }
+            }
+            else if (typeof process !== "undefined" && process.env?.NODE_ENV !== "production") {
+                // eslint-disable-next-line no-console
+                console.warn(`[Stoop] Theme "${newThemeName}" not found. Available themes: ${availableThemeNames.join(", ")}`);
+            }
+        }, [storageKey, themes, availableThemeNames]);
+        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]);
+        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,
+    };
+}

package/dist/api/styled.js

@@ -0,0 +1,170 @@
+"use client";
+/**
+ * Styled component API.
+ * Creates polymorphic styled components with variant support, theme awareness,
+ * and CSS prop merging. Supports component targeting via selector references.
+ */
+import { useMemo, forwardRef, createElement, useContext, createContext, } from "react";
+import { EMPTY_CSS, STOOP_COMPONENT_SYMBOL } from "../constants";
+import { compileCSS } from "../core/compiler";
+import { applyVariants } from "../core/variants";
+import { hash, sanitizeClassName } from "../utils/string";
+let defaultThemeContext = null;
+function getDefaultThemeContext() {
+    if (!defaultThemeContext) {
+        defaultThemeContext = createContext(null);
+    }
+    return defaultThemeContext;
+}
+/**
+ * Creates a styled component reference for selector targeting.
+ *
+ * @param className - Class name to reference
+ * @returns StyledComponentRef for use in CSS selectors
+ */
+export function createStyledComponentRef(className) {
+    const ref = {
+        __isStoopStyled: true,
+        __stoopClassName: className,
+        [STOOP_COMPONENT_SYMBOL]: className,
+        toString: () => `__STOOP_COMPONENT_${className}`,
+    };
+    return ref;
+}
+/**
+ * Type guard for styled component references.
+ *
+ * @param value - Value to check
+ * @returns True if value is a styled component reference
+ */
+function isStyledComponent(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "__isStoopStyled" in value &&
+        value.__isStoopStyled === true);
+}
+/**
+ * Separates component props into variant props and element props.
+ * Variant props are used for style variants, element props are passed to the DOM element.
+ *
+ * @param props - All component props
+ * @param variants - Variant configuration
+ * @returns Object with separated elementProps and variantProps
+ */
+function extractVariantProps(props, variants) {
+    if (!variants) {
+        return { elementProps: props, variantProps: {} };
+    }
+    const variantKeys = new Set(Object.keys(variants));
+    const variantProps = {};
+    const elementProps = {};
+    for (const key in props) {
+        if (variantKeys.has(key)) {
+            variantProps[key] = props[key];
+        }
+        else {
+            elementProps[key] = props[key];
+        }
+    }
+    return { elementProps, variantProps };
+}
+/**
+ * Creates a styled component factory function.
+ * Supports polymorphic components, variants, theme awareness, and CSS prop merging.
+ *
+ * @param defaultTheme - Default theme for token resolution
+ * @param prefix - Optional prefix for generated class names
+ * @param media - Optional media query breakpoints
+ * @param utils - Optional utility functions
+ * @param themeMap - Optional theme scale mappings
+ * @param themeContext - React context for theme values (instance-specific)
+ * @returns Styled component factory function
+ */
+export function createStyledFunction(defaultTheme, prefix = "stoop", media, utils, themeMap, themeContext) {
+    return function styled(defaultElement, baseStylesOrVariants, variantsParam) {
+        let actualBaseStyles = (baseStylesOrVariants || EMPTY_CSS);
+        let actualVariants = variantsParam;
+        if (baseStylesOrVariants &&
+            "variants" in baseStylesOrVariants &&
+            typeof baseStylesOrVariants.variants === "object") {
+            actualVariants = baseStylesOrVariants.variants;
+            const { compoundVariants: __, variants: _, ...rest } = baseStylesOrVariants;
+            actualBaseStyles = rest;
+        }
+        let baseElementClassName;
+        if (typeof defaultElement !== "string" && isStyledComponent(defaultElement)) {
+            baseElementClassName = defaultElement.__stoopClassName;
+        }
+        const StyledComponent = forwardRef(function StyledComponent(propsWithBase, ref) {
+            const { as, className, css: cssStyles, ...restProps } = propsWithBase;
+            const element = (as || defaultElement);
+            const cssObject = useMemo(() => cssStyles && typeof cssStyles === "object" && cssStyles !== null
+                ? cssStyles
+                : EMPTY_CSS, [cssStyles]);
+            const { elementProps, variantProps } = extractVariantProps(restProps, actualVariants);
+            const contextValue = useContext(themeContext || getDefaultThemeContext());
+            const currentTheme = contextValue?.theme || defaultTheme;
+            const currentMedia = currentTheme.media ? { ...media, ...currentTheme.media } : media;
+            const variantKey = useMemo(() => {
+                if (!actualVariants) {
+                    return "";
+                }
+                const variantEntries = Object.entries(variantProps);
+                if (variantEntries.length === 0) {
+                    return "";
+                }
+                return variantEntries
+                    .sort(([a], [b]) => a.localeCompare(b))
+                    .map(([key, value]) => `${key}:${String(value)}`)
+                    .join("|");
+            }, [variantProps]);
+            const finalStyles = useMemo(() => {
+                let componentStyles = actualBaseStyles;
+                if (actualVariants && variantKey) {
+                    componentStyles = applyVariants(actualVariants, variantProps, actualBaseStyles);
+                }
+                if (cssObject !== EMPTY_CSS) {
+                    componentStyles = Object.assign({}, componentStyles, cssObject);
+                }
+                return componentStyles;
+            }, [variantKey, cssObject, actualBaseStyles, actualVariants, variantProps]);
+            const finalClassName = useMemo(() => {
+                const classNames = [];
+                if (baseElementClassName) {
+                    classNames.push(baseElementClassName);
+                }
+                const mergedClass = compileCSS(finalStyles, currentTheme, prefix, currentMedia, utils, themeMap);
+                if (mergedClass) {
+                    classNames.push(mergedClass);
+                }
+                if (className) {
+                    const classNameStr = typeof className === "string" ? className : String(className);
+                    const sanitizedClassName = sanitizeClassName(classNameStr);
+                    if (sanitizedClassName) {
+                        classNames.push(sanitizedClassName);
+                    }
+                }
+                return classNames.length > 0 ? classNames.join(" ") : undefined;
+            }, [
+                finalStyles,
+                className,
+                baseElementClassName,
+                currentTheme,
+                prefix,
+                currentMedia,
+                utils,
+                themeMap,
+            ]);
+            return createElement(element, {
+                ...elementProps,
+                className: finalClassName,
+                ref,
+            });
+        });
+        const selectorHash = hash(JSON.stringify(actualBaseStyles));
+        const selectorClassName = `${prefix}-${selectorHash}`;
+        const componentWithSelector = StyledComponent;
+        componentWithSelector.selector = createStyledComponentRef(selectorClassName);
+        return componentWithSelector;
+    };
+}

package/dist/api/use-theme.js

@@ -0,0 +1,21 @@
+"use client";
+/**
+ * Theme management hook.
+ * Provides access to theme state and theme switching functions.
+ */
+import { useContext } from "react";
+/**
+ * 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.d.ts

@@ -1,13 +1,12 @@
 /**
  * Shared constants used throughout the library.
- * Includes cache size limits, nesting depth limits, and fallback context.
+ * Includes cache size limits and nesting depth limits.
  */
-import type { CSS, ThemeContextValue, ThemeScale } from "./types";
+import type { CSS, ThemeScale } from "./types";
 export declare const EMPTY_CSS: CSS;
 export declare const MAX_CSS_CACHE_SIZE = 10000;
 export declare const MAX_CLASS_NAME_CACHE_SIZE = 5000;
 export declare const MAX_CSS_NESTING_DEPTH = 10;
-export declare const FALLBACK_CONTEXT: import("react").Context<ThemeContextValue>;
 /**
  * Approved theme scales - only these scales are allowed in theme objects.
  */