stoop 0.6.1 → 0.6.2

package/dist/api/core-api.d.ts

@@ -1,6 +1,8 @@
 /**
  * Core API functions.
  * Consolidates theme creation, CSS class generation, and keyframes animation APIs.
+ *
+ * SERVER-SAFE: No React dependencies, can be used in server components and SSR.
  */
 import type { CSS, Theme, ThemeScale, UtilityFunction } from "../types";
 /**

package/dist/api/core-api.js

@@ -0,0 +1,171 @@
+/**
+ * Core API functions.
+ * Consolidates theme creation, CSS class generation, and keyframes animation APIs.
+ *
+ * SERVER-SAFE: No React dependencies, can be used in server components and SSR.
+ */
+import { LRUCache } from "../core/cache";
+import { compileCSS, cssObjectToString } from "../core/compiler";
+import { sanitizeCSSPropertyName } from "../core/stringify";
+import { mergeThemes } from "../core/theme-manager";
+import { injectCSS } from "../inject";
+import { applyUtilities, validateTheme } from "../utils/helpers";
+import { replaceThemeTokensWithVars } from "../utils/theme";
+import { hashObject, sanitizePrefix, validateKeyframeKey } from "../utils/theme-utils";
+// ============================================================================
+// Theme Creation API
+// ============================================================================
+/**
+ * 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);
+        return mergeThemes(baseTheme, validatedOverrides);
+    };
+}
+// ============================================================================
+// CSS Class Generation API
+// ============================================================================
+/**
+ * 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);
+    };
+}
+// ============================================================================
+// Keyframes Animation API
+// ============================================================================
+/**
+ * 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;
+}
+import { KEYFRAME_CACHE_LIMIT } from "../constants";
+/**
+ * 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;
+    };
+}
+// ============================================================================
+// Global CSS Injection API
+// ============================================================================
+/**
+ * Creates a global CSS injection function.
+ * Injects styles directly into the document with deduplication support.
+ * Supports media queries, nested selectors, and theme tokens.
+ *
+ * @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 Set();
+export function createGlobalCSSFunction(defaultTheme, prefix = "stoop", media, utils, themeMap) {
+    return function globalCss(styles) {
+        const cssKey = hashObject(styles);
+        if (globalInjectedStyles.has(cssKey)) {
+            return () => { };
+        }
+        globalInjectedStyles.add(cssKey);
+        const sanitizedPrefix = sanitizePrefix(prefix);
+        const stylesWithUtils = applyUtilities(styles, utils);
+        const themedStyles = replaceThemeTokensWithVars(stylesWithUtils, defaultTheme, themeMap);
+        // Empty selector for global CSS (no base selector needed)
+        const cssText = cssObjectToString(themedStyles, "", 0, media);
+        injectCSS(cssText, sanitizedPrefix, `__global_${cssKey}`);
+        return () => {
+            globalInjectedStyles.delete(cssKey);
+        };
+    };
+}

package/dist/api/styled.d.ts

@@ -2,6 +2,9 @@
  * Styled component API.
  * Creates polymorphic styled components with variant support, theme awareness,
  * and CSS prop merging. Supports component targeting via selector references.
+ *
+ * CLIENT-ONLY: This module uses React hooks (useMemo, useContext, forwardRef, createElement)
+ * and MUST have "use client" directive for Next.js App Router compatibility.
  */
 import { forwardRef, type Context } from "react";
 import type { CSS, StyledComponentProps, StyledComponentRef, StylableElement, Theme, ThemeContextValue, ThemeScale, UtilityFunction, Variants } from "../types";

package/dist/api/styled.js

@@ -0,0 +1,467 @@
+"use client";
+/**
+ * Styled component API.
+ * Creates polymorphic styled components with variant support, theme awareness,
+ * and CSS prop merging. Supports component targeting via selector references.
+ *
+ * CLIENT-ONLY: This module uses React hooks (useMemo, useContext, forwardRef, createElement)
+ * and MUST have "use client" directive for Next.js App Router compatibility.
+ */
+import { useMemo, forwardRef, createElement, useContext, createContext, } from "react";
+import { EMPTY_CSS, STOOP_COMPONENT_SYMBOL } from "../constants";
+import { compileCSS } from "../core/compiler";
+import { isStyledComponentRef } from "../utils/helpers";
+import { hash, sanitizeClassName } from "../utils/theme-utils";
+// ============================================================================
+// Variant Application Logic
+// ============================================================================
+/**
+ * Applies variant styles to base styles based on component props.
+ * Optimized to avoid unnecessary object spreads when no variants are applied.
+ *
+ * @param variants - Variant configuration object
+ * @param props - Component props containing variant values
+ * @param baseStyles - Base styles to merge with variant styles
+ * @returns Merged CSS object
+ */
+function applyVariants(variants, props, baseStyles) {
+    const appliedVariantStyles = [];
+    for (const variantName in variants) {
+        const propValue = props[variantName];
+        if (propValue === undefined) {
+            continue;
+        }
+        const variantOptions = variants[variantName];
+        const key = propValue === true ? "true" : propValue === false ? "false" : String(propValue);
+        if (variantOptions[key]) {
+            appliedVariantStyles.push(variantOptions[key]);
+        }
+    }
+    if (appliedVariantStyles.length === 0) {
+        return baseStyles;
+    }
+    // Optimize for single variant case
+    if (appliedVariantStyles.length === 1) {
+        return { ...baseStyles, ...appliedVariantStyles[0] };
+    }
+    // Merge multiple variant styles
+    const mergedVariants = { ...appliedVariantStyles[0] };
+    for (let i = 1; i < appliedVariantStyles.length; i++) {
+        Object.assign(mergedVariants, appliedVariantStyles[i]);
+    }
+    return { ...baseStyles, ...mergedVariants };
+}
+// ============================================================================
+// Styled Component API
+// ============================================================================
+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 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)) {
+            cssProps[key] = props[key];
+        }
+        else {
+            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, baseStyles) {
+        let actualBaseStyles = (baseStyles || EMPTY_CSS);
+        let actualVariants;
+        // Extract variants if embedded in baseStyles
+        if (baseStyles &&
+            "variants" in baseStyles &&
+            typeof baseStyles.variants === "object" &&
+            baseStyles.variants !== null &&
+            !Array.isArray(baseStyles.variants)) {
+            // Verify it's actually a Variants object (has string keys with CSS values)
+            const variantsObj = baseStyles.variants;
+            const hasValidVariants = Object.keys(variantsObj).length > 0 &&
+                Object.values(variantsObj).every((v) => typeof v === "object" && v !== null && !Array.isArray(v));
+            if (hasValidVariants) {
+                actualVariants = baseStyles.variants;
+                const { variants: _, ...rest } = baseStyles;
+                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);
+                }
+                if (Object.keys(cssProps).length > 0) {
+                    componentStyles = Object.assign({}, componentStyles, cssProps);
+                }
+                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

@@ -2,6 +2,9 @@
  * 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 { type ComponentType, type Context } from "react";
 import type { ProviderProps, Theme, ThemeContextValue, ThemeManagementContextValue } from "../types";