stoop 0.2.1 → 0.4.0

package/README.md

@@ -1,36 +1,6 @@
-# Stoop
+# stoop
 
-CSS-in-JS library with type inference, theme creation, and variants support.
-
-[![npm version](https://img.shields.io/npm/v/stoop)](https://www.npmjs.com/package/stoop)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-> **Warning: Not Production Ready**
-> Stoop is currently in active development and is not recommended for production use. The API may change, and there may be bugs or missing features. Use at your own risk.
-
-## About
-
-Stoop is a CSS-in-JS library—a TypeScript-first approach to styling that provides type-safe CSS objects with full type inference. Similar to [Stitches](https://stitches.dev) and [Vanilla Extract](https://vanilla-extract.style), Stoop focuses on type safety and developer experience.
-
-Stoop is a minimalist implementation of Stitches' high-level features. It provides a similar API for `styled`, `css`, and variants, but omits several Stitches features.
-
-**What's missing compared to Stitches:**
-- Compound variants
-- Build-time CSS extraction (runtime-only)
-- Advanced utility functions (basic support only)
-- Additional Stitches APIs
-
-If you need these features, consider [Vanilla Extract](https://vanilla-extract.style) or [styled-components](https://styled-components.com).
-
-## Features
-
-- Type-safe theming with TypeScript inference
-- CSS variables for theme tokens
-- Variant system for component variations
-- Utility functions for custom CSS transformations
-- Multiple themes with `createTheme()`
-- SSR support via `getCssText()`
-- React 19+ required (Next.js Pages & App Router supported)
+A lightweight, type-safe CSS-in-JS library for React with theme support, variants, and SSR capabilities.
 
 ## Installation
 
@@ -47,7 +17,7 @@ yarn add stoop
 ```tsx
 import { createStoop } from "stoop";
 
-const { styled, css, createTheme, globalCss, keyframes, ThemeContext } = createStoop({
+const { styled, css, Provider, useTheme } = createStoop({
   theme: {
     colors: {
       primary: "#0070f3",
@@ -60,121 +30,96 @@ const { styled, css, createTheme, globalCss, keyframes, ThemeContext } = createS
       large: "24px",
     },
   },
+  themes: {
+    light: {
+      /* ... */
+    },
+    dark: {
+      /* ... */
+    },
+  },
 });
 
 const Button = styled("button", {
   padding: "$medium",
   backgroundColor: "$primary",
-}, {
-  variant: {
-    primary: { backgroundColor: "$primary" },
-    secondary: { backgroundColor: "$secondary" },
-  },
+  color: "$text",
 });
 
-<Button variant="primary">Click me</Button>
+<Button>Click me</Button>;
 ```
 
-See [GUIDE.md](./docs/GUIDE.md) for complete setup instructions.
+## 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`, `ThemeContext`, `theme`, `config`.
-
-See [API.md](./docs/API.md) for complete API documentation.
+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` searches all scales; explicit `$scale.token` specifies the scale.
+Use `$` prefix for theme tokens. Shorthand `$token` uses property-aware resolution (preferred); explicit `$scale.token` specifies the scale.
 
 ```tsx
 {
-  color: "$primary",           // Shorthand (preferred)
-  padding: "$medium",          // Property-aware resolution
+  color: "$primary",           // Shorthand (preferred, property-aware)
+  padding: "$medium",         // Property-aware → space scale
   fontSize: "$fontSizes.small", // Explicit scale
 }
 ```
 
-Tokens resolve to CSS variables (`var(--colors-primary)`), enabling instant theme switching without recompiling CSS.
-
 ### 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" },
+const Button = styled(
+  "button",
+  {},
+  {
+    variant: {
+      primary: { backgroundColor: "$primary" },
+      secondary: { backgroundColor: "$secondary" },
+    },
+    size: {
+      small: { padding: "$small" },
+      large: { padding: "$large" },
+    },
   },
-});
+);
 
-<Button variant="primary" size="small" />
+<Button variant="primary" size="small" />;
 ```
 
-## Migration from Stitches
-
-Stoop provides a similar API for the features it implements. Key differences:
-- CSS variables for theme tokens
-- Simple theme system with `createTheme()`
-- Full TypeScript inference
-
-See [GUIDE.md](./docs/GUIDE.md) for migration examples.
-
-## Related Projects
-
-**CSS-in-JS Libraries:**
-- [Stitches](https://stitches.dev) - Original library Stoop is based on (no longer maintained)
-- [Stitches](https://stitches.dev) - CSS-in-JS library (original inspiration)
-- [Vanilla Extract](https://vanilla-extract.style) - Zero-runtime CSS-in-JS
-- [styled-components](https://styled-components.com) - CSS-in-JS library
-- [Emotion](https://emotion.sh) - CSS-in-JS library
-- [Goober](https://goober.rocks) - Lightweight CSS-in-JS library
-- [JSS](https://cssinjs.org) - Framework-agnostic CSS-in-JS
-- [Compiled](https://compiledcssinjs.com) - Compile-time CSS-in-JS
-- [Stylex](https://stylexjs.com) - Facebook's build-time CSS-in-JS
-- [Panda CSS](https://panda-css.com) - CSS-in-JS with build-time generation
-- [Linaria](https://linaria.dev) - Zero-runtime CSS-in-JS
-- [Treat](https://seek-oss.github.io/treat) - Themeable CSS-in-JS
-
-**Variant Systems:**
-- [CVA](https://cva.style) - Class Variance Authority for component variants
-- [clsx](https://github.com/lukeed/clsx) - Tiny utility for constructing className strings
-
-**Utility-First:**
-- [Tailwind CSS](https://tailwindcss.com) - Utility-first CSS framework
-- [UnoCSS](https://unocss.dev) - Instant atomic CSS engine
-
-**Component Libraries:**
-- [Radix UI](https://www.radix-ui.com) - Unstyled, accessible component primitives
-- [Chakra UI](https://chakra-ui.com) - Component library built on Emotion
-- [Mantine](https://mantine.dev) - React components library with Emotion
-
 ## Development
 
 ```sh
-bun install
-bun run dev
+# Build
 bun run build
-bun run lint
-```
 
-## Contributing
+# Test
+bun run test
 
-Contributions welcome. See [ARCHITECTURE.md](./docs/ARCHITECTURE.md) for implementation details.
+# Watch mode
+bun run test:watch
+```
 
 ## License
 
-MIT © [Jackson Dolman](https://github.com/dolmios)
+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/core-api.js

@@ -0,0 +1,135 @@
+/**
+ * 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 { 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.
+ *
+ * @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;
+    };
+}

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,42 @@
+/**
+ * Global CSS injection API.
+ * Creates a function that injects global styles into the document.
+ * Supports media queries, nested selectors, and theme tokens.
+ */
+import { cssObjectToString } from "../core/compiler";
+import { injectCSS } from "../inject";
+import { applyUtilities } from "../utils/helpers";
+import { replaceThemeTokensWithVars } from "../utils/theme";
+import { hashObject, sanitizePrefix } from "../utils/theme-utils";
+/**
+ * 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
+ */
+// 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 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);
+        // 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 () => {
+            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.