stoop 0.3.0 → 0.4.0

package/README.md

@@ -0,0 +1,125 @@
+# stoop
+
+A lightweight, type-safe CSS-in-JS library for React with theme support, variants, and SSR capabilities.
+
+## Installation
+
+```sh
+npm install stoop
+# or
+bun add stoop
+# or
+yarn add stoop
+```
+
+## Quick Start
+
+```tsx
+import { createStoop } from "stoop";
+
+const { styled, css, Provider, useTheme } = createStoop({
+  theme: {
+    colors: {
+      primary: "#0070f3",
+      background: "#ffffff",
+      text: "#000000",
+    },
+    space: {
+      small: "8px",
+      medium: "16px",
+      large: "24px",
+    },
+  },
+  themes: {
+    light: {
+      /* ... */
+    },
+    dark: {
+      /* ... */
+    },
+  },
+});
+
+const Button = styled("button", {
+  padding: "$medium",
+  backgroundColor: "$primary",
+  color: "$text",
+});
+
+<Button>Click me</Button>;
+```
+
+## Features
+
+- **Type-safe theming** with TypeScript inference
+- **CSS variables** for instant theme switching
+- **Variant system** for component variations
+- **SSR support** via `getCssText()`
+- **Multiple themes** with built-in Provider
+- **Utility functions** for custom CSS transformations
+- **Zero runtime overhead** for theme switching
+
+## Documentation
+
+- **[GUIDE.md](./docs/GUIDE.md)** - Step-by-step setup and usage guide
+- **[API.md](./docs/API.md)** - Complete API reference
+- **[ARCHITECTURE.md](./docs/ARCHITECTURE.md)** - Internal implementation details
+- **[TESTING.md](./docs/TESTING.md)** - Testing guide and test suite documentation
+
+## API Overview
+
+### `createStoop(config)`
+
+Creates a Stoop instance. Returns: `styled`, `css`, `createTheme`, `globalCss`, `keyframes`, `getCssText`, `warmCache`, `preloadTheme`, `theme`, `config`. If `themes` config is provided, also returns `Provider` and `useTheme`.
+
+### Theme Tokens
+
+Use `$` prefix for theme tokens. Shorthand `$token` uses property-aware resolution (preferred); explicit `$scale.token` specifies the scale.
+
+```tsx
+{
+  color: "$primary",           // Shorthand (preferred, property-aware)
+  padding: "$medium",         // Property-aware → space scale
+  fontSize: "$fontSizes.small", // Explicit scale
+}
+```
+
+### Variants
+
+Variants create component variations via props:
+
+```tsx
+const Button = styled(
+  "button",
+  {},
+  {
+    variant: {
+      primary: { backgroundColor: "$primary" },
+      secondary: { backgroundColor: "$secondary" },
+    },
+    size: {
+      small: { padding: "$small" },
+      large: { padding: "$large" },
+    },
+  },
+);
+
+<Button variant="primary" size="small" />;
+```
+
+## Development
+
+```sh
+# Build
+bun run build
+
+# Test
+bun run test
+
+# Watch mode
+bun run test:watch
+```
+
+## License
+
+MIT

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

@@ -0,0 +1,34 @@
+/**
+ * Core API functions.
+ * Consolidates theme creation, CSS class generation, and keyframes animation APIs.
+ */
+import type { CSS, Theme, ThemeScale, UtilityFunction } from "../types";
+/**
+ * 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 declare function createTheme(baseTheme: Theme): (themeOverrides?: Partial<Theme>) => Theme;
+/**
+ * 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 declare function createCSSFunction(defaultTheme: Theme, prefix?: string, media?: Record<string, string>, utils?: Record<string, UtilityFunction>, themeMap?: Record<string, ThemeScale>): (styles: CSS) => string;
+/**
+ * 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 declare function createKeyframesFunction(prefix?: string, theme?: Theme, themeMap?: Record<string, ThemeScale>): (keyframes: Record<string, CSS>) => string;

package/dist/api/{keyframes.js → core-api.js}

@@ -1,12 +1,52 @@
 /**
- * CSS keyframes animation API.
- * Creates a function that generates and injects @keyframes rules.
- * Caches animations by content hash to prevent duplicates.
+ * Core API functions.
+ * Consolidates theme creation, CSS class generation, and keyframes animation APIs.
  */
 import { LRUCache } from "../core/cache";
+import { compileCSS } from "../core/compiler";
+import { mergeThemes } from "../core/theme-manager";
 import { injectCSS } from "../inject";
-import { hashObject, sanitizeCSSPropertyName, sanitizePrefix, validateKeyframeKey, } from "../utils/string";
+import { validateTheme } from "../utils/helpers";
 import { replaceThemeTokensWithVars } from "../utils/theme";
+import { hashObject, sanitizeCSSPropertyName, 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);
+        // Use shared mergeThemes function instead of duplicate deepMerge
+        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.
  *
@@ -63,7 +103,7 @@ function keyframesToCSS(keyframesObj, animationName, theme, themeMap) {
     css += " }";
     return css;
 }
-const KEYFRAME_CACHE_LIMIT = 500;
+import { KEYFRAME_CACHE_LIMIT } from "../constants";
 /**
  * Creates a keyframes animation function.
  * Generates and injects @keyframes rules with caching to prevent duplicates.

package/dist/api/global-css.js

@@ -3,12 +3,11 @@
  * 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 { cssObjectToString } from "../core/compiler";
 import { injectCSS } from "../inject";
-import { escapeCSSValue, hashObject, sanitizeCSSPropertyName, sanitizeCSSSelector, sanitizeMediaQuery, sanitizePrefix, } from "../utils/string";
+import { applyUtilities } from "../utils/helpers";
 import { replaceThemeTokensWithVars } from "../utils/theme";
-import { isCSSObject } from "../utils/type-guards";
-import { applyUtilities } from "../utils/utilities";
+import { hashObject, sanitizePrefix } from "../utils/theme-utils";
 /**
  * Creates a global CSS injection function.
  * Injects styles directly into the document with deduplication support.
@@ -20,70 +19,24 @@ import { applyUtilities } from "../utils/utilities";
  * @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;
-}
+// Use CSS hash as key instead of theme object reference for better deduplication
+const globalInjectedStyles = new 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)) {
+        if (globalInjectedStyles.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;
-        }
+        globalInjectedStyles.add(cssKey);
         const sanitizedPrefix = sanitizePrefix(prefix);
         const stylesWithUtils = applyUtilities(styles, utils);
         const themedStyles = replaceThemeTokensWithVars(stylesWithUtils, defaultTheme, themeMap);
-        const cssText = generateGlobalCSS(themedStyles);
+        // Use cssObjectToString from compiler.ts instead of duplicate generateGlobalCSS
+        // Empty selector for global CSS (no base selector needed)
+        const cssText = cssObjectToString(themedStyles, "", 0, media);
         injectCSS(cssText, sanitizedPrefix, `__global_${cssKey}`);
         return () => {
-            injected.delete(cssKey);
+            globalInjectedStyles.delete(cssKey);
         };
     };
 }

package/dist/api/styled.d.ts

@@ -16,7 +16,6 @@ type CSSWithVariants = {
     [K in keyof CSS]: CSS[K];
 } & {
     variants: Variants;
-    compoundVariants?: unknown[];
 };
 /**
  * Creates a styled component factory function.

package/dist/api/styled.js

@@ -8,7 +8,8 @@ import { useMemo, forwardRef, createElement, useContext, createContext, } from "
 import { EMPTY_CSS, STOOP_COMPONENT_SYMBOL } from "../constants";
 import { compileCSS } from "../core/compiler";
 import { applyVariants } from "../core/variants";
-import { hash, sanitizeClassName } from "../utils/string";
+import { isStyledComponentRef } from "../utils/helpers";
+import { hash, sanitizeClassName } from "../utils/theme-utils";
 let defaultThemeContext = null;
 function getDefaultThemeContext() {
     if (!defaultThemeContext) {
@@ -33,40 +34,283 @@ export function createStyledComponentRef(className) {
 }
 /**
  * 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 (typeof value === "object" &&
-        value !== null &&
-        "__isStoopStyled" in value &&
-        value.__isStoopStyled === true);
+    return isStyledComponentRef(value);
 }
 /**
- * Separates component props into variant props and element props.
- * Variant props are used for style variants, element props are passed to the DOM element.
+ * 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 and variantProps
+ * @returns Object with separated elementProps, variantProps, and cssProps
  */
 function extractVariantProps(props, variants) {
-    if (!variants) {
-        return { elementProps: props, variantProps: {} };
-    }
-    const variantKeys = new Set(Object.keys(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 { elementProps, variantProps };
+    return { cssProps, elementProps, variantProps };
 }
 /**
  * Creates a styled component factory function.
@@ -88,7 +332,7 @@ export function createStyledFunction(defaultTheme, prefix = "stoop", media, util
             "variants" in baseStylesOrVariants &&
             typeof baseStylesOrVariants.variants === "object") {
             actualVariants = baseStylesOrVariants.variants;
-            const { compoundVariants: __, variants: _, ...rest } = baseStylesOrVariants;
+            const { variants: _, ...rest } = baseStylesOrVariants;
             actualBaseStyles = rest;
         }
         let baseElementClassName;
@@ -101,7 +345,7 @@ export function createStyledFunction(defaultTheme, prefix = "stoop", media, util
             const cssObject = useMemo(() => cssStyles && typeof cssStyles === "object" && cssStyles !== null
                 ? cssStyles
                 : EMPTY_CSS, [cssStyles]);
-            const { elementProps, variantProps } = extractVariantProps(restProps, actualVariants);
+            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;
@@ -123,11 +367,16 @@ export function createStyledFunction(defaultTheme, prefix = "stoop", media, util
                 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, actualBaseStyles, actualVariants, variantProps]);
+            }, [variantKey, cssObject, cssProps, actualBaseStyles, actualVariants, variantProps]);
             const finalClassName = useMemo(() => {
                 const classNames = [];
                 if (baseElementClassName) {