stoop 0.4.0 → 0.5.0

package/dist/types/index.d.ts

@@ -26,6 +26,17 @@ export type StylableElement = HTMLElements | ElementType;
 export interface StyledBaseProps {
     css?: CSS;
 }
+/**
+ * CSS object that includes variants configuration.
+ * Used for styled component definitions that combine base styles with variants.
+ * This type explicitly requires the `variants` property to be present and of type Variants.
+ * We exclude variants from the CSS index signature to make it distinct.
+ */
+export type CSSWithVariants = {
+    [K in keyof CSS as K extends "variants" ? never : K]: CSS[K];
+} & {
+    variants: Variants;
+};
 export type UtilityFunction = (value: CSSPropertyValue | CSS | undefined) => CSS;
 /**
  * Theme scale type - represents valid keys from DefaultTheme.
@@ -95,10 +106,10 @@ export interface StoopServerInstance {
     };
     createTheme: (themeOverride: Partial<Theme>) => Theme;
     css: (styles: CSS) => string;
-    getCssText: (theme?: string | Theme) => string;
+    getCssText: () => string;
     globalCss: (...args: CSS[]) => () => void;
     keyframes: (definition: Record<string, CSS>) => string;
-    preloadTheme: (theme: string | Theme) => void;
+    preloadTheme: () => void;
     theme: Theme;
     warmCache: (styles: CSS[]) => void;
 }
@@ -194,9 +205,11 @@ export type StyledComponent<DefaultElement extends ElementType, VariantsConfig e
 };
 /**
  * Styled function type - the main styled() function signature
+ * Variants must be embedded in the baseStyles object, matching Stitches API.
  */
 export interface StyledFunction {
-    <DefaultElement extends StylableElement, VariantsConfig extends Variants = {}>(defaultElement: DefaultElement, baseStyles?: CSS, variants?: VariantsConfig): StyledComponent<DefaultElement, VariantsConfig>;
+    <DefaultElement extends StylableElement, BaseStyles extends CSSWithVariants>(defaultElement: DefaultElement, baseStyles: BaseStyles): StyledComponent<DefaultElement, BaseStyles["variants"]>;
+    <DefaultElement extends StylableElement>(defaultElement: DefaultElement, baseStyles?: CSS): StyledComponent<DefaultElement, {}>;
 }
 export interface GetCssTextOptions {
     theme?: Theme;
@@ -248,10 +261,9 @@ export interface StoopInstance {
      * Gets all generated CSS text for server-side rendering.
      * Always includes theme CSS variables.
      *
-     * @param theme - Deprecated parameter, kept for backward compatibility but ignored
      * @returns CSS text string with theme variables and component styles
      */
-    getCssText: (theme?: string | Theme) => string;
+    getCssText: () => string;
     config: StoopConfig;
     /**
      * Pre-compiles CSS objects to warm the cache.
@@ -261,12 +273,11 @@ export interface StoopInstance {
      */
     warmCache: (styles: CSS[]) => void;
     /**
-     * Preloads a theme by injecting its CSS variables before React renders.
+     * Preloads themes by injecting CSS variables before React renders.
      * Useful for preventing FOUC when loading a non-default theme from localStorage.
-     *
-     * @param theme - Theme to preload (theme name string or Theme object)
+     * Always injects all configured themes.
      */
-    preloadTheme: (theme: string | Theme) => void;
+    preloadTheme: () => void;
     /**
      * Provider component for managing theme state and updates.
      * Available when themes are provided in createStoop config.

package/dist/utils/helpers.d.ts

@@ -11,7 +11,6 @@ import type { CSS, DefaultTheme, StyledComponentRef, Theme, UtilityFunction } fr
 export declare function isBrowser(): boolean;
 /**
  * Checks if running in production mode.
- * Extracted to helper function for consistency.
  *
  * @returns True if running in production mode
  */
@@ -25,7 +24,6 @@ export declare function isProduction(): boolean;
 export declare function isCSSObject(value: unknown): value is CSS;
 /**
  * Checks if a value is a styled component reference.
- * Consolidated function used across the codebase.
  *
  * @param value - Value to check
  * @returns True if value is a styled component reference
@@ -47,7 +45,6 @@ export declare function isValidCSSObject(value: unknown): value is CSS;
 export declare function isThemeObject(value: unknown): value is Theme;
 /**
  * Validates that a theme object only contains approved scales.
- * In production, skips all validation for performance.
  *
  * @param theme - Theme object to validate
  * @returns Validated theme as DefaultTheme

package/dist/utils/storage.d.ts

@@ -1,9 +1,8 @@
 /**
  * Storage and theme detection utilities.
- * Provides simplified localStorage and cookie management, plus automatic theme selection.
- * Supports SSR compatibility and error handling.
+ * Provides simplified localStorage and cookie management with SSR compatibility and error handling.
  */
-import type { ThemeDetectionOptions, ThemeDetectionResult, StorageOptions, StorageResult } from "../types";
+import type { StorageOptions, StorageResult } from "../types";
 /**
  * Safely gets a value from localStorage.
  *
@@ -54,95 +53,3 @@ export declare function setCookie(name: string, value: string, options?: Omit<St
  * @returns Success status
  */
 export declare function removeCookie(name: string, path?: string): boolean;
-/**
- * Unified storage API that works with both localStorage and cookies.
- *
- * @param key - Storage key
- * @param options - Storage options
- * @returns Storage result
- */
-export declare function getStorage(key: string, options?: StorageOptions): StorageResult<string | null>;
-/**
- * Unified storage API that works with both localStorage and cookies.
- *
- * @param key - Storage key
- * @param value - Value to store
- * @param options - Storage options
- * @returns Storage result
- */
-export declare function setStorage(key: string, value: string, options?: StorageOptions): StorageResult<void>;
-/**
- * Unified storage API that works with both localStorage and cookies.
- *
- * @param key - Storage key
- * @param options - Storage options
- * @returns Storage result
- */
-export declare function removeStorage(key: string, options?: StorageOptions): StorageResult<void>;
-/**
- * Gets a JSON value from storage with automatic parsing.
- *
- * @param key - Storage key
- * @param fallback - Fallback value if parsing fails or key not found
- * @param options - Storage options
- * @returns Parsed JSON value or fallback
- */
-export declare function getJsonFromStorage<T>(key: string, fallback: T, options?: StorageOptions): StorageResult<T>;
-/**
- * Sets a JSON value in storage with automatic serialization.
- *
- * @param key - Storage key
- * @param value - Value to serialize and store
- * @param options - Storage options
- * @returns Storage result
- */
-export declare function setJsonInStorage<T>(key: string, value: T, options?: StorageOptions): StorageResult<void>;
-/**
- * Creates a typed storage interface for a specific key.
- *
- * @param key - Storage key
- * @param options - Storage options
- * @returns Typed storage interface
- */
-export declare function createStorage<T = string>(key: string, options?: StorageOptions): {
-    get: () => StorageResult<string | null>;
-    getJson: (fallback: T) => StorageResult<T>;
-    remove: () => StorageResult<void>;
-    set: (value: string) => StorageResult<void>;
-    setJson: (value: T) => StorageResult<void>;
-};
-/**
- * Detects the best theme to use based on multiple sources with priority.
- *
- * Priority order (highest to lowest):
- * 1. Explicit localStorage preference
- * 2. Cookie preference (for SSR compatibility)
- * 3. System color scheme preference
- * 4. Default theme
- *
- * @param options - Theme detection options
- * @returns Theme detection result
- */
-export declare function detectTheme(options?: ThemeDetectionOptions): ThemeDetectionResult;
-/**
- * Creates a theme detector function with pre-configured options.
- *
- * @param options - Theme detection options
- * @returns Theme detection function
- */
-export declare function createThemeDetector(options: ThemeDetectionOptions): () => ThemeDetectionResult;
-/**
- * Auto-detects theme for SSR contexts (server-side or during hydration).
- * Uses only cookie and default sources since localStorage isn't available.
- *
- * @param options - Theme detection options
- * @returns Theme name
- */
-export declare function detectThemeForSSR(options?: ThemeDetectionOptions): string;
-/**
- * Listens for system theme changes and calls callback when changed.
- *
- * @param callback - Function to call when system theme changes
- * @returns Cleanup function
- */
-export declare function onSystemThemeChange(callback: (theme: "dark" | "light") => void): () => void;

package/dist/utils/theme-utils.d.ts

@@ -36,7 +36,6 @@ export declare function escapeCSSValue(value: string | number): string;
 /**
  * Validates and sanitizes CSS selectors to prevent injection attacks.
  * Only allows safe selector characters. Returns empty string for invalid selectors.
- * Uses memoization for performance.
  *
  * @param selector - Selector to sanitize
  * @returns Sanitized selector string or empty string if invalid
@@ -45,7 +44,6 @@ export declare function sanitizeCSSSelector(selector: string): string;
 /**
  * Validates and sanitizes CSS variable names to prevent injection attacks.
  * CSS custom properties must start with -- and contain only valid characters.
- * Uses memoization for performance.
  *
  * @param name - Variable name to sanitize
  * @returns Sanitized variable name
@@ -78,20 +76,11 @@ export declare function sanitizeMediaQuery(mediaQuery: string): string;
 /**
  * Sanitizes CSS class names to prevent injection attacks.
  * Only allows valid CSS class name characters.
- * Uses memoization for performance.
  *
  * @param className - Class name(s) to sanitize
  * @returns Sanitized class name string
  */
 export declare function sanitizeClassName(className: string): string;
-/**
- * Sanitizes CSS property names to prevent injection attacks.
- * Uses memoization for performance.
- *
- * @param propertyName - Property name to sanitize
- * @returns Sanitized property name
- */
-export declare function sanitizeCSSPropertyName(propertyName: string): string;
 /**
  * Validates keyframe percentage keys (e.g., "0%", "50%", "from", "to").
  *
@@ -101,7 +90,6 @@ export declare function sanitizeCSSPropertyName(propertyName: string): string;
 export declare function validateKeyframeKey(key: string): boolean;
 /**
  * Gets a pre-compiled regex for matching :root CSS selector blocks.
- * Uses caching for performance.
  *
  * @param prefix - Optional prefix (unused, kept for API compatibility)
  * @returns RegExp for matching :root selector blocks
@@ -109,7 +97,6 @@ export declare function validateKeyframeKey(key: string): boolean;
 export declare function getRootRegex(prefix?: string): RegExp;
 /**
  * Auto-detects theme scale from CSS property name using pattern matching.
- * Used as fallback when property is not in DEFAULT_THEME_MAP.
  *
  * @param property - CSS property name
  * @returns Theme scale name or undefined if no pattern matches

package/dist/utils/theme.d.ts

@@ -1,7 +1,6 @@
 /**
  * Theme token resolution utilities.
  * Converts theme tokens to CSS variables for runtime theme switching.
- * Uses cached token index for efficient lookups and theme comparison.
  */
 import type { CSS, Theme, ThemeScale } from "../types";
 /**
@@ -34,8 +33,7 @@ export declare function tokenToCSSVar(token: string, theme?: Theme, property?: s
 export declare function generateCSSVariables(theme: Theme, prefix?: string, attributeSelector?: string): string;
 /**
  * Generates CSS custom properties for all themes using attribute selectors.
- * This allows all themes to be available simultaneously, with theme switching
- * handled by changing the data-theme attribute.
+ * All themes are available simultaneously, with theme switching handled by changing the data-theme attribute.
  *
  * @param themes - Map of theme names to theme objects
  * @param prefix - Optional prefix for CSS variable names

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "stoop",
   "description": "CSS-in-JS library with type inference, theme creation, and variants support.",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "author": "Jackson Dolman <mail@dolmios.com>",
   "main": "./dist/create-stoop.js",
   "types": "./dist/create-stoop.d.ts",
@@ -17,10 +17,13 @@
     "react-polymorphic-types": "^2.0.0"
   },
   "devDependencies": {
+    "@stitches/stringify": "^1.2.8",
     "@types/node": "^25.0.3",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
     "bun-types": "^1.3.5",
+    "style-object-to-css-string": "^1.1.3",
+    "to-css": "^1.2.1",
     "typescript": "^5.9.3"
   },
   "exports": {
@@ -36,12 +39,6 @@
       "require": "./dist/utils/storage.js",
       "default": "./dist/utils/storage.js"
     },
-    "./utils/auto-preload": {
-      "types": "./dist/utils/auto-preload.d.ts",
-      "import": "./dist/utils/auto-preload.js",
-      "require": "./dist/utils/auto-preload.js",
-      "default": "./dist/utils/auto-preload.js"
-    },
     "./types": {
       "types": "./dist/types/index.d.ts",
       "import": "./dist/types/index.js",
@@ -96,18 +93,19 @@
     "react": ">=16.8.0",
     "react-dom": ">=16.8.0"
   },
-  "sideEffects": false,
-  "type": "module",
   "scripts": {
     "build": "bun run build:clean && bun run build:js && bun run build:js:ssr && bun run build:types",
     "build:clean": "rm -rf dist",
     "build:copy-declarations": "mkdir -p dist/types && cp src/types/react-polymorphic-types.d.ts dist/types/react-polymorphic-types.d.ts 2>/dev/null || :",
-    "build:js": "NODE_ENV=production bun build ./src/create-stoop.ts --outdir ./dist --target node --minify --jsx=automatic --splitting --external react --external react-dom --external react/jsx-runtime --define process.env.NODE_ENV='\"production\"'",
-    "build:js:ssr": "NODE_ENV=production bun build ./src/create-stoop-ssr.ts --outdir ./dist --target node --minify --jsx=automatic --external react --external react-dom --external react/jsx-runtime --define process.env.NODE_ENV='\"production\"'",
+    "build:js": "NODE_ENV=production bun build ./src/create-stoop.ts --outfile ./dist/create-stoop.js --target browser --format esm --minify --jsx=automatic --external react --external react-dom --external react/jsx-runtime --define process.env.NODE_ENV='\"production\"'",
+    "build:js:ssr": "NODE_ENV=production bun build ./src/create-stoop-ssr.ts --outfile ./dist/create-stoop-ssr.js --target browser --format esm --minify --jsx=automatic --external react --external react-dom --external react/jsx-runtime --define process.env.NODE_ENV='\"production\"'",
     "build:types": "bunx tsc --project tsconfig.build.json && bun run build:copy-declarations",
     "lint": "eslint src --fix",
+    "prepare": "bun run build",
     "test": "bun test",
     "test:coverage": "bun test --coverage",
     "test:watch": "bun test --watch"
-  }
-}
+  },
+  "sideEffects": false,
+  "type": "module"
+}

package/dist/api/core-api.js

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

@@ -1,7 +0,0 @@
-/**
- * Global CSS injection API.
- * Creates a function that injects global styles into the document.
- * Supports media queries, nested selectors, and theme tokens.
- */
-import type { CSS, Theme, ThemeScale, UtilityFunction } from "../types";
-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

@@ -1,42 +0,0 @@
-/**
- * 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);
-        };
-    };
-}