stoop 0.2.1 → 0.4.0

package/dist/api/styled.js

@@ -0,0 +1,419 @@
+"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 { isStyledComponentRef } from "../utils/helpers";
+import { hash, sanitizeClassName } from "../utils/theme-utils";
+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.
+ * Uses shared isStyledComponentRef helper for consistency.
+ *
+ * @param value - Value to check
+ * @returns True if value is a styled component reference
+ */
+function isStyledComponent(value) {
+    return isStyledComponentRef(value);
+}
+/**
+ * Set of common CSS properties that should not be passed to DOM elements.
+ * These are camelCase CSS properties that React doesn't recognize as valid DOM attributes.
+ */
+const CSS_PROPERTIES = new Set([
+    "alignContent",
+    "alignItems",
+    "alignSelf",
+    "animation",
+    "animationDelay",
+    "animationDirection",
+    "animationDuration",
+    "animationFillMode",
+    "animationIterationCount",
+    "animationName",
+    "animationPlayState",
+    "animationTimingFunction",
+    "aspectRatio",
+    "backdropFilter",
+    "backfaceVisibility",
+    "background",
+    "backgroundAttachment",
+    "backgroundBlendMode",
+    "backgroundClip",
+    "backgroundColor",
+    "backgroundImage",
+    "backgroundOrigin",
+    "backgroundPosition",
+    "backgroundRepeat",
+    "backgroundSize",
+    "border",
+    "borderBottom",
+    "borderBottomColor",
+    "borderBottomLeftRadius",
+    "borderBottomRightRadius",
+    "borderBottomStyle",
+    "borderBottomWidth",
+    "borderCollapse",
+    "borderColor",
+    "borderImage",
+    "borderImageOutset",
+    "borderImageRepeat",
+    "borderImageSlice",
+    "borderImageSource",
+    "borderImageWidth",
+    "borderLeft",
+    "borderLeftColor",
+    "borderLeftStyle",
+    "borderLeftWidth",
+    "borderRadius",
+    "borderRight",
+    "borderRightColor",
+    "borderRightStyle",
+    "borderRightWidth",
+    "borderSpacing",
+    "borderStyle",
+    "borderTop",
+    "borderTopColor",
+    "borderTopLeftRadius",
+    "borderTopRightRadius",
+    "borderTopStyle",
+    "borderTopWidth",
+    "borderWidth",
+    "bottom",
+    "boxShadow",
+    "boxSizing",
+    "captionSide",
+    "caretColor",
+    "clear",
+    "clip",
+    "clipPath",
+    "color",
+    "columnCount",
+    "columnFill",
+    "columnGap",
+    "columnRule",
+    "columnRuleColor",
+    "columnRuleStyle",
+    "columnRuleWidth",
+    "columnSpan",
+    "columnWidth",
+    "columns",
+    "content",
+    "counterIncrement",
+    "counterReset",
+    "cursor",
+    "direction",
+    "display",
+    "emptyCells",
+    "filter",
+    "flex",
+    "flexBasis",
+    "flexDirection",
+    "flexFlow",
+    "flexGrow",
+    "flexShrink",
+    "flexWrap",
+    "float",
+    "font",
+    "fontFamily",
+    "fontFeatureSettings",
+    "fontKerning",
+    "fontLanguageOverride",
+    "fontSize",
+    "fontSizeAdjust",
+    "fontStretch",
+    "fontStyle",
+    "fontSynthesis",
+    "fontVariant",
+    "fontVariantAlternates",
+    "fontVariantCaps",
+    "fontVariantEastAsian",
+    "fontVariantLigatures",
+    "fontVariantNumeric",
+    "fontVariantPosition",
+    "fontWeight",
+    "gap",
+    "grid",
+    "gridArea",
+    "gridAutoColumns",
+    "gridAutoFlow",
+    "gridAutoRows",
+    "gridColumn",
+    "gridColumnEnd",
+    "gridColumnGap",
+    "gridColumnStart",
+    "gridGap",
+    "gridRow",
+    "gridRowEnd",
+    "gridRowGap",
+    "gridRowStart",
+    "gridTemplate",
+    "gridTemplateAreas",
+    "gridTemplateColumns",
+    "gridTemplateRows",
+    "height",
+    "hyphens",
+    "imageOrientation",
+    "imageRendering",
+    "imageResolution",
+    "imeMode",
+    "inlineSize",
+    "isolation",
+    "justifyContent",
+    "justifyItems",
+    "justifySelf",
+    "left",
+    "letterSpacing",
+    "lineHeight",
+    "listStyle",
+    "listStyleImage",
+    "listStylePosition",
+    "listStyleType",
+    "margin",
+    "marginBottom",
+    "marginLeft",
+    "marginRight",
+    "marginTop",
+    "maxHeight",
+    "maxWidth",
+    "minHeight",
+    "minWidth",
+    "objectFit",
+    "objectPosition",
+    "opacity",
+    "order",
+    "orphans",
+    "outline",
+    "outlineColor",
+    "outlineOffset",
+    "outlineStyle",
+    "outlineWidth",
+    "overflow",
+    "overflowWrap",
+    "overflowX",
+    "overflowY",
+    "padding",
+    "paddingBottom",
+    "paddingLeft",
+    "paddingRight",
+    "paddingTop",
+    "pageBreakAfter",
+    "pageBreakBefore",
+    "pageBreakInside",
+    "perspective",
+    "perspectiveOrigin",
+    "placeContent",
+    "placeItems",
+    "placeSelf",
+    "pointerEvents",
+    "position",
+    "quotes",
+    "resize",
+    "right",
+    "rowGap",
+    "scrollBehavior",
+    "tabSize",
+    "tableLayout",
+    "textAlign",
+    "textAlignLast",
+    "textDecoration",
+    "textDecorationColor",
+    "textDecorationLine",
+    "textDecorationStyle",
+    "textIndent",
+    "textJustify",
+    "textOverflow",
+    "textShadow",
+    "textTransform",
+    "textUnderlinePosition",
+    "top",
+    "transform",
+    "transformOrigin",
+    "transformStyle",
+    "transition",
+    "transitionDelay",
+    "transitionDuration",
+    "transitionProperty",
+    "transitionTimingFunction",
+    "unicodeBidi",
+    "userSelect",
+    "verticalAlign",
+    "visibility",
+    "whiteSpace",
+    "width",
+    "wordBreak",
+    "wordSpacing",
+    "wordWrap",
+    "writingMode",
+    "zIndex",
+]);
+/**
+ * Checks if a prop name is a CSS property that should be converted to CSS styles.
+ *
+ * @param propName - The prop name to check
+ * @returns True if the prop is a CSS property
+ */
+function isCSSProperty(propName) {
+    return CSS_PROPERTIES.has(propName);
+}
+/**
+ * Separates component props into variant props, CSS props, and element props.
+ * Variant props are used for style variants.
+ * CSS props are converted to CSS styles.
+ * Element props are passed to the DOM element.
+ *
+ * @param props - All component props
+ * @param variants - Variant configuration
+ * @returns Object with separated elementProps, variantProps, and cssProps
+ */
+function extractVariantProps(props, variants) {
+    const variantKeys = variants ? new Set(Object.keys(variants)) : new Set();
+    const variantProps = {};
+    const cssProps = {};
+    const elementProps = {};
+    for (const key in props) {
+        if (variantKeys.has(key)) {
+            variantProps[key] = props[key];
+        }
+        else if (isCSSProperty(key)) {
+            // Convert CSS properties to CSS styles
+            cssProps[key] = props[key];
+        }
+        else {
+            // Only include non-CSS, non-variant properties in elementProps
+            elementProps[key] = props[key];
+        }
+    }
+    return { cssProps, 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 { 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 { cssProps, 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);
+                }
+                // Merge CSS props (CSS properties passed as props) into styles
+                if (Object.keys(cssProps).length > 0) {
+                    componentStyles = Object.assign({}, componentStyles, cssProps);
+                }
+                // Merge explicit css prop into styles
+                if (cssObject !== EMPTY_CSS) {
+                    componentStyles = Object.assign({}, componentStyles, cssObject);
+                }
+                return componentStyles;
+            }, [variantKey, cssObject, cssProps, 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/theme-provider.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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.
+ */
+import { type ComponentType, type Context } from "react";
+import type { ProviderProps, Theme, ThemeContextValue, ThemeManagementContextValue } from "../types";
+/**
+ * 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:
+ *
+ * ```html
+ * <script>
+ *   // Read theme from storage and preload before React renders
+ *   const storedTheme = localStorage.getItem('stoop-theme') || 'light';
+ *   stoopInstance.preloadTheme(storedTheme);
+ * </script>
+ * ```
+ */
+export declare function createProvider(themes: Record<string, Theme>, defaultTheme: Theme, prefix?: string, globalCss?: import("../types").CSS, globalCssFunction?: import("../types").GlobalCSSFunction): {
+    Provider: ComponentType<ProviderProps>;
+    ThemeContext: Context<ThemeContextValue | null>;
+    ThemeManagementContext: Context<ThemeManagementContextValue | null>;
+};
+/**
+ * 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 declare function createUseThemeHook(ThemeManagementContext: Context<ThemeManagementContextValue | null>): () => ThemeManagementContextValue;

package/dist/api/theme-provider.js

@@ -0,0 +1,223 @@
+"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.
+ */
+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.
+ * If cookie exists, syncs to localStorage. If localStorage exists, syncs to cookie.
+ *
+ * @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;
+    // Sync cookie -> localStorage
+    if (cookieValue === value && localStorageValue !== value) {
+        setInStorage(storageKey, value);
+    }
+    // Sync localStorage -> cookie
+    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;
+    }
+    // Try cookie first if cookieKey is provided
+    if (cookieKey !== undefined) {
+        const cookieValue = getCookie(cookieKey);
+        if (cookieValue && themes[cookieValue]) {
+            return cookieValue;
+        }
+    }
+    // Fall back to localStorage
+    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:
+ *
+ * ```html
+ * <script>
+ *   // Read theme from storage and preload before React renders
+ *   const storedTheme = localStorage.getItem('stoop-theme') || 'light';
+ *   stoopInstance.preloadTheme(storedTheme);
+ * </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";
+    // Create global styles function from config if provided
+    const configGlobalStyles = globalCss && globalCssFunction ? globalCssFunction(globalCss) : undefined;
+    function Provider({ attribute = "data-theme", children, cookieKey, defaultTheme: defaultThemeProp, storageKey = "stoop-theme", }) {
+        // SSR-safe initialization: always start with default theme to match SSR
+        // This prevents hydration mismatch - server always renders with default theme
+        // Hydration will happen in useLayoutEffect to update to stored theme
+        const [themeName, setThemeNameState] = useState(defaultThemeProp || firstThemeName);
+        // Track if hydration has occurred to prevent re-running hydration effect
+        const hasHydratedRef = useRef(false);
+        // Hydrate from cookie/localStorage after mount to prevent hydration mismatch
+        // Only run once on mount - storage changes are handled by the storage event listener
+        useLayoutEffect(() => {
+            if (!isBrowser() || hasHydratedRef.current) {
+                return;
+            }
+            const stored = readThemeFromStorage(cookieKey, storageKey, themes);
+            if (stored) {
+                // Sync between cookie and localStorage
+                syncThemeStorage(stored, cookieKey, storageKey);
+                // Only update if different from initial state to avoid unnecessary re-render
+                if (stored !== themeName) {
+                    setThemeNameState(stored);
+                }
+            }
+            hasHydratedRef.current = true;
+        }, [cookieKey, storageKey, themes]); // Removed themeName from deps - only run once on mount
+        // Listen for storage changes from other tabs/windows
+        useLayoutEffect(() => {
+            if (!isBrowser()) {
+                return;
+            }
+            const handleStorageChange = (e) => {
+                if (e.key === storageKey && e.newValue && themes[e.newValue] && e.newValue !== themeName) {
+                    setThemeNameState(e.newValue);
+                    // Sync to cookie if cookieKey is provided
+                    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]);
+        // Track if themes and global styles have been injected
+        const themesInjectedRef = useRef(false);
+        const globalStylesInjectedRef = useRef(false);
+        // Inject all theme CSS variables once on mount (before global styles and theme switching)
+        // This ensures all themes are available simultaneously via attribute selectors
+        useLayoutEffect(() => {
+            if (!isBrowser() || themesInjectedRef.current) {
+                return;
+            }
+            // Inject all themes using attribute selectors
+            // This allows instant theme switching by only changing the data-theme attribute
+            injectAllThemes(themes, prefix, attribute);
+            themesInjectedRef.current = true;
+        }, [themes, prefix, attribute]);
+        // Inject global styles once on mount (after themes are injected)
+        useLayoutEffect(() => {
+            if (!isBrowser() || globalStylesInjectedRef.current) {
+                return;
+            }
+            // Inject global styles from config
+            // These use CSS variables, so they'll automatically work with all themes
+            if (configGlobalStyles) {
+                configGlobalStyles();
+                globalStylesInjectedRef.current = true;
+            }
+        }, [configGlobalStyles]);
+        // Update data-theme attribute when theme changes
+        // No need to update CSS variables since all themes are already injected
+        useLayoutEffect(() => {
+            if (!isBrowser()) {
+                return;
+            }
+            // Simply update the data-theme attribute - CSS variables are already available
+            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;
+    };
+}