stoop 0.2.1 → 0.3.0

package/dist/constants.js

@@ -0,0 +1,144 @@
+/**
+ * Shared constants used throughout the library.
+ * Includes cache size limits and nesting depth limits.
+ */
+export const EMPTY_CSS = Object.freeze({});
+export const MAX_CSS_CACHE_SIZE = 10000;
+export const MAX_CLASS_NAME_CACHE_SIZE = 5000;
+export const MAX_CSS_NESTING_DEPTH = 10;
+/**
+ * Approved theme scales - only these scales are allowed in theme objects.
+ */
+export const APPROVED_THEME_SCALES = [
+    "colors",
+    "opacities",
+    "space",
+    "radii",
+    "sizes",
+    "fonts",
+    "fontWeights",
+    "fontSizes",
+    "lineHeights",
+    "letterSpacings",
+    "shadows",
+    "zIndices",
+    "transitions",
+];
+/**
+ * Default themeMap mapping CSS properties to theme scales.
+ * Covers 150+ common CSS properties for zero-config experience.
+ * Missing properties gracefully fallback to pattern-based auto-detection.
+ */
+export const DEFAULT_THEME_MAP = {
+    accentColor: "colors",
+    animation: "transitions",
+    animationDelay: "transitions",
+    animationDuration: "transitions",
+    animationTimingFunction: "transitions",
+    backdropFilter: "shadows",
+    background: "colors",
+    backgroundColor: "colors",
+    blockSize: "sizes",
+    border: "colors",
+    borderBlockColor: "colors",
+    borderBlockEndColor: "colors",
+    borderBlockStartColor: "colors",
+    borderBottomColor: "colors",
+    borderBottomLeftRadius: "radii",
+    borderBottomRightRadius: "radii",
+    borderColor: "colors",
+    borderEndEndRadius: "radii",
+    borderEndStartRadius: "radii",
+    borderInlineColor: "colors",
+    borderInlineEndColor: "colors",
+    borderInlineStartColor: "colors",
+    borderLeftColor: "colors",
+    borderRadius: "radii",
+    borderRightColor: "colors",
+    borderStartEndRadius: "radii",
+    borderStartStartRadius: "radii",
+    borderTopColor: "colors",
+    borderTopLeftRadius: "radii",
+    borderTopRightRadius: "radii",
+    bottom: "space",
+    boxShadow: "shadows",
+    caretColor: "colors",
+    color: "colors",
+    columnGap: "space",
+    columnRuleColor: "colors",
+    fill: "colors",
+    filter: "shadows",
+    flexBasis: "sizes",
+    floodColor: "colors",
+    font: "fontSizes",
+    fontFamily: "fonts",
+    fontSize: "fontSizes",
+    fontWeight: "fontWeights",
+    gap: "space",
+    gridColumnGap: "space",
+    gridGap: "space",
+    gridRowGap: "space",
+    height: "sizes",
+    inlineSize: "sizes",
+    inset: "space",
+    insetBlock: "space",
+    insetBlockEnd: "space",
+    insetBlockStart: "space",
+    insetInline: "space",
+    insetInlineEnd: "space",
+    insetInlineStart: "space",
+    left: "space",
+    letterSpacing: "letterSpacings",
+    lightingColor: "colors",
+    lineHeight: "lineHeights",
+    margin: "space",
+    marginBlock: "space",
+    marginBlockEnd: "space",
+    marginBlockStart: "space",
+    marginBottom: "space",
+    marginInline: "space",
+    marginInlineEnd: "space",
+    marginInlineStart: "space",
+    marginLeft: "space",
+    marginRight: "space",
+    marginTop: "space",
+    maxBlockSize: "sizes",
+    maxHeight: "sizes",
+    maxInlineSize: "sizes",
+    maxWidth: "sizes",
+    minBlockSize: "sizes",
+    minHeight: "sizes",
+    minInlineSize: "sizes",
+    minWidth: "sizes",
+    opacity: "opacities",
+    outline: "colors",
+    outlineColor: "colors",
+    padding: "space",
+    paddingBlock: "space",
+    paddingBlockEnd: "space",
+    paddingBlockStart: "space",
+    paddingBottom: "space",
+    paddingInline: "space",
+    paddingInlineEnd: "space",
+    paddingInlineStart: "space",
+    paddingLeft: "space",
+    paddingRight: "space",
+    paddingTop: "space",
+    right: "space",
+    rowGap: "space",
+    size: "sizes",
+    stopColor: "colors",
+    stroke: "colors",
+    textDecorationColor: "colors",
+    textEmphasisColor: "colors",
+    textShadow: "shadows",
+    top: "space",
+    transition: "transitions",
+    transitionDelay: "transitions",
+    transitionDuration: "transitions",
+    transitionProperty: "transitions",
+    transitionTimingFunction: "transitions",
+    width: "sizes",
+    zIndex: "zIndices",
+};
+export const STOOP_COMPONENT_SYMBOL = Symbol.for("stoop.component");

package/dist/core/cache.d.ts

@@ -7,7 +7,7 @@
  * LRU Cache implementation for class names and CSS strings.
  * Automatically evicts least recently used entries when size limit is exceeded.
  */
-declare class LRUCache<K, V> extends Map<K, V> {
+export declare class LRUCache<K, V> extends Map<K, V> {
     private readonly maxSize;
     constructor(maxSize: number);
     get(key: K): V | undefined;
@@ -16,24 +16,20 @@ declare class LRUCache<K, V> extends Map<K, V> {
 export declare const classNameCache: LRUCache<string, string>;
 export declare const cssStringCache: LRUCache<string, string>;
 /**
- * Checks if a CSS string is cached.
+ * Checks if a CSS string has been injected.
+ * Uses a Set for O(1) lookup.
  *
  * @param css - CSS string to check
- * @returns True if CSS is cached
+ * @returns True if CSS has been injected
  */
 export declare function isCachedStyle(css: string): boolean;
 /**
- * Marks a CSS string as cached.
+ * Marks a CSS string as injected.
  *
  * @param css - CSS string to cache
  */
 export declare function markStyleAsCached(css: string): void;
-/**
- * Limits cache size by evicting least recently used entries.
- */
-export declare function limitCacheSize(): void;
 /**
  * Clears all cached styles.
  */
 export declare function clearStyleCache(): void;
-export {};

package/dist/core/cache.js

@@ -0,0 +1,68 @@
+/**
+ * CSS compilation caching system.
+ * Tracks compiled CSS strings and class names to prevent duplicate work.
+ * Implements LRU (Least Recently Used) eviction when cache size limits are exceeded.
+ */
+import { MAX_CLASS_NAME_CACHE_SIZE, MAX_CSS_CACHE_SIZE } from "../constants";
+/**
+ * LRU Cache implementation for class names and CSS strings.
+ * Automatically evicts least recently used entries when size limit is exceeded.
+ */
+export class LRUCache extends Map {
+    maxSize;
+    constructor(maxSize) {
+        super();
+        this.maxSize = maxSize;
+    }
+    get(key) {
+        const value = super.get(key);
+        if (value !== undefined) {
+            super.delete(key);
+            super.set(key, value);
+        }
+        return value;
+    }
+    set(key, value) {
+        if (super.has(key)) {
+            super.delete(key);
+        }
+        else if (this.size >= this.maxSize) {
+            const firstKey = this.keys().next().value;
+            if (firstKey !== undefined) {
+                super.delete(firstKey);
+            }
+        }
+        super.set(key, value);
+        return this;
+    }
+}
+export const classNameCache = new LRUCache(MAX_CLASS_NAME_CACHE_SIZE);
+export const cssStringCache = new LRUCache(MAX_CSS_CACHE_SIZE);
+// Separate cache for tracking injected CSS strings (used by browser injection)
+const injectedStylesCache = new Set();
+/**
+ * Checks if a CSS string has been injected.
+ * Uses a Set for O(1) lookup.
+ *
+ * @param css - CSS string to check
+ * @returns True if CSS has been injected
+ */
+export function isCachedStyle(css) {
+    return injectedStylesCache.has(css);
+}
+/**
+ * Marks a CSS string as injected.
+ *
+ * @param css - CSS string to cache
+ */
+export function markStyleAsCached(css) {
+    injectedStylesCache.add(css);
+}
+/**
+ * Clears all cached styles.
+ */
+export function clearStyleCache() {
+    classNameCache.clear();
+    cssStringCache.clear();
+    injectedStylesCache.clear();
+}

package/dist/core/compiler.js

@@ -0,0 +1,198 @@
+/**
+ * CSS compilation engine.
+ * Converts CSS objects to CSS strings and generates unique class names.
+ * Handles nested selectors, media queries, styled component targeting, and theme tokens.
+ */
+import { MAX_CSS_NESTING_DEPTH, STOOP_COMPONENT_SYMBOL } from "../constants";
+import { injectCSS } from "../inject";
+import { escapeCSSValue, hash, sanitizeCSSPropertyName, sanitizeCSSSelector, sanitizeMediaQuery, sanitizePrefix, } from "../utils/string";
+import { replaceThemeTokensWithVars } from "../utils/theme";
+import { isValidCSSObject } from "../utils/type-guards";
+import { applyUtilities } from "../utils/utilities";
+import { classNameCache, cssStringCache } from "./cache";
+/**
+ * Checks if a key/value pair represents a styled component reference.
+ *
+ * @param key - Property key to check
+ * @param value - Property value to check
+ * @returns True if key/value represents a styled component reference
+ */
+function isStyledComponentKey(key, value) {
+    if (typeof key === "symbol" && key === STOOP_COMPONENT_SYMBOL) {
+        return true;
+    }
+    if (typeof value === "object" && value !== null && STOOP_COMPONENT_SYMBOL in value) {
+        return true;
+    }
+    if (typeof key === "string" && key.startsWith("__STOOP_COMPONENT_")) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Extracts the class name from a styled component reference.
+ *
+ * @param key - Property key
+ * @param value - Property value
+ * @returns Extracted class name or empty string
+ */
+function getClassNameFromKeyOrValue(key, value) {
+    if (typeof value === "object" &&
+        value !== null &&
+        "__stoopClassName" in value &&
+        typeof value.__stoopClassName === "string") {
+        return value.__stoopClassName;
+    }
+    if (typeof key === "string" && key.startsWith("__STOOP_COMPONENT_")) {
+        return key.replace("__STOOP_COMPONENT_", "");
+    }
+    return "";
+}
+/**
+ * Converts a CSS object to a CSS string with proper nesting and selectors.
+ * Handles pseudo-selectors, media queries, combinators, and styled component targeting.
+ *
+ * @param obj - CSS object to convert
+ * @param selector - Current selector context
+ * @param depth - Current nesting depth
+ * @param media - Media query breakpoints
+ * @returns CSS string
+ */
+function cssObjectToString(obj, selector = "", depth = 0, media) {
+    if (!obj || typeof obj !== "object") {
+        return "";
+    }
+    if (depth > MAX_CSS_NESTING_DEPTH) {
+        return "";
+    }
+    const cssProperties = [];
+    const nestedRulesList = [];
+    const keys = Object.keys(obj).sort();
+    for (const key of keys) {
+        const value = obj[key];
+        if (isStyledComponentKey(key, value)) {
+            const componentClassName = getClassNameFromKeyOrValue(key, value);
+            if (!componentClassName) {
+                continue;
+            }
+            const sanitizedClassName = sanitizeCSSSelector(componentClassName);
+            if (!sanitizedClassName) {
+                continue;
+            }
+            const componentSelector = selector
+                ? `${selector} .${sanitizedClassName}`
+                : `.${sanitizedClassName}`;
+            const nestedCss = isValidCSSObject(value)
+                ? cssObjectToString(value, componentSelector, depth + 1, media)
+                : "";
+            if (nestedCss) {
+                nestedRulesList.push(nestedCss);
+            }
+            continue;
+        }
+        if (isValidCSSObject(value)) {
+            if (media && key in media) {
+                const mediaQuery = sanitizeMediaQuery(media[key]);
+                if (mediaQuery) {
+                    const nestedCss = cssObjectToString(value, selector, depth + 1, media);
+                    if (nestedCss) {
+                        nestedRulesList.push(`${mediaQuery} { ${nestedCss} }`);
+                    }
+                }
+            }
+            else if (key.startsWith("@")) {
+                const sanitizedKey = sanitizeCSSSelector(key);
+                if (sanitizedKey) {
+                    const nestedCss = cssObjectToString(value, selector, depth + 1, media);
+                    if (nestedCss) {
+                        nestedRulesList.push(`${sanitizedKey} { ${nestedCss} }`);
+                    }
+                }
+            }
+            else if (key.includes("&")) {
+                const sanitizedKey = sanitizeCSSSelector(key);
+                if (sanitizedKey) {
+                    const parts = sanitizedKey.split("&");
+                    const nestedSelector = parts.join(selector);
+                    const nestedCss = cssObjectToString(value, nestedSelector, depth + 1, media);
+                    if (nestedCss) {
+                        nestedRulesList.push(nestedCss);
+                    }
+                }
+            }
+            else if (key.startsWith(":")) {
+                const sanitizedKey = sanitizeCSSSelector(key);
+                if (sanitizedKey) {
+                    const nestedSelector = `${selector}${sanitizedKey}`;
+                    const nestedCss = cssObjectToString(value, nestedSelector, depth + 1, media);
+                    if (nestedCss) {
+                        nestedRulesList.push(nestedCss);
+                    }
+                }
+            }
+            else if (key.includes(" ") || key.includes(">") || key.includes("+") || key.includes("~")) {
+                const sanitizedKey = sanitizeCSSSelector(key);
+                if (sanitizedKey) {
+                    const startsWithCombinator = /^[\s>+~]/.test(sanitizedKey.trim());
+                    const nestedSelector = startsWithCombinator
+                        ? `${selector}${sanitizedKey}`
+                        : `${selector} ${sanitizedKey}`;
+                    const nestedCss = cssObjectToString(value, nestedSelector, depth + 1, media);
+                    if (nestedCss) {
+                        nestedRulesList.push(nestedCss);
+                    }
+                }
+            }
+            else {
+                const sanitizedKey = sanitizeCSSSelector(key);
+                if (sanitizedKey) {
+                    const nestedSelector = selector ? `${selector} ${sanitizedKey}` : sanitizedKey;
+                    const nestedCss = cssObjectToString(value, nestedSelector, depth + 1, media);
+                    if (nestedCss) {
+                        nestedRulesList.push(nestedCss);
+                    }
+                }
+            }
+        }
+        else if (value !== undefined) {
+            const property = sanitizeCSSPropertyName(key);
+            if (property && (typeof value === "string" || typeof value === "number")) {
+                const escapedValue = escapeCSSValue(value);
+                cssProperties.push(`${property}: ${escapedValue};`);
+            }
+        }
+    }
+    const rule = cssProperties.length > 0 ? `${selector} { ${cssProperties.join(" ")} }` : "";
+    return rule + nestedRulesList.join("");
+}
+/**
+ * Compiles CSS objects into CSS strings and generates unique class names.
+ * Handles nested selectors, media queries, styled component targeting, and theme tokens.
+ *
+ * @param styles - CSS object to compile
+ * @param currentTheme - 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 Generated class name
+ */
+export function compileCSS(styles, currentTheme, prefix = "stoop", media, utils, themeMap) {
+    const sanitizedPrefix = sanitizePrefix(prefix);
+    const stylesWithUtils = applyUtilities(styles, utils);
+    const themedStyles = replaceThemeTokensWithVars(stylesWithUtils, currentTheme, themeMap);
+    const cssString = cssObjectToString(themedStyles, "", 0, media);
+    const stylesHash = hash(cssString);
+    const className = sanitizedPrefix ? `${sanitizedPrefix}-${stylesHash}` : `css-${stylesHash}`;
+    const cacheKey = `${sanitizedPrefix}:${className}`;
+    const cachedCSS = cssStringCache.get(cacheKey);
+    if (cachedCSS) {
+        injectCSS(cachedCSS, sanitizedPrefix, cacheKey);
+        return className;
+    }
+    const fullCSS = cssObjectToString(themedStyles, `.${className}`, 0, media);
+    cssStringCache.set(cacheKey, fullCSS);
+    classNameCache.set(cacheKey, className);
+    injectCSS(fullCSS, sanitizedPrefix, cacheKey);
+    return className;
+}

package/dist/core/theme-manager.d.ts

@@ -13,16 +13,8 @@ import type { Theme } from "../types";
  * @param prefix - Optional prefix for theme scoping
  */
 export declare function registerDefaultTheme(theme: Theme, prefix?: string): void;
-/**
- * Gets the default theme for a given prefix.
- *
- * @param prefix - Optional prefix for theme scoping
- * @returns Default theme or null if not registered
- */
-export declare function getDefaultTheme(prefix?: string): Theme | null;
 /**
  * Updates CSS custom properties when theme changes.
- * Automatically merges the theme with the default theme to ensure all properties are present.
  *
  * @param theme - Theme object to generate CSS variables from
  * @param prefix - Optional prefix for CSS variable names

package/dist/core/theme-manager.js

@@ -0,0 +1,97 @@
+/**
+ * Theme variable management.
+ * Updates CSS custom properties when theme changes.
+ * Ensures CSS variables are injected and kept in sync with theme updates.
+ * Automatically merges themes with the default theme when applied.
+ */
+import { injectThemeVariables } from "../inject";
+import { isBrowser } from "../utils/environment";
+import { generateCSSVariables, themesAreEqual } from "../utils/theme";
+const defaultThemes = new Map();
+const mergedThemeCache = new WeakMap();
+/**
+ * Registers the default theme for a given prefix.
+ * Called automatically by createStoop.
+ *
+ * @param theme - Default theme from createStoop
+ * @param prefix - Optional prefix for theme scoping
+ */
+export function registerDefaultTheme(theme, prefix = "stoop") {
+    const sanitizedPrefix = prefix || "";
+    defaultThemes.set(sanitizedPrefix, theme);
+}
+/**
+ * Gets the default theme for a given prefix.
+ *
+ * @param prefix - Optional prefix for theme scoping
+ * @returns Default theme or null if not registered
+ */
+function getDefaultTheme(prefix = "stoop") {
+    const sanitizedPrefix = prefix || "";
+    return defaultThemes.get(sanitizedPrefix) || null;
+}
+/**
+ * Merges a theme with the default theme if it's not already the default theme.
+ * This ensures all themes extend the default theme, keeping all original properties.
+ * Uses caching to avoid repeated merging of the same theme objects.
+ *
+ * @param theme - Theme to merge
+ * @param prefix - Optional prefix for theme scoping
+ * @returns Merged theme (or original if it's the default theme)
+ */
+function mergeWithDefaultTheme(theme, prefix = "stoop") {
+    const defaultTheme = getDefaultTheme(prefix);
+    if (!defaultTheme) {
+        return theme;
+    }
+    if (themesAreEqual(theme, defaultTheme)) {
+        return theme;
+    }
+    let prefixCache = mergedThemeCache.get(theme);
+    if (!prefixCache) {
+        prefixCache = new Map();
+        mergedThemeCache.set(theme, prefixCache);
+    }
+    const cached = prefixCache.get(prefix);
+    if (cached) {
+        return cached;
+    }
+    const merged = { ...defaultTheme };
+    const allThemeKeys = Object.keys(theme);
+    for (const key of allThemeKeys) {
+        if (key === "media") {
+            continue;
+        }
+        const themeValue = theme[key];
+        const defaultValue = defaultTheme[key];
+        if (themeValue &&
+            typeof themeValue === "object" &&
+            !Array.isArray(themeValue) &&
+            defaultValue &&
+            typeof defaultValue === "object" &&
+            !Array.isArray(defaultValue)) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            merged[key] = { ...defaultValue, ...themeValue };
+        }
+        else if (themeValue !== undefined) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            merged[key] = themeValue;
+        }
+    }
+    prefixCache.set(prefix, merged);
+    return merged;
+}
+/**
+ * Updates CSS custom properties when theme changes.
+ *
+ * @param theme - Theme object to generate CSS variables from
+ * @param prefix - Optional prefix for CSS variable names
+ */
+export function updateThemeVariables(theme, prefix = "stoop") {
+    if (!isBrowser()) {
+        return;
+    }
+    const mergedTheme = mergeWithDefaultTheme(theme, prefix);
+    const cssVars = generateCSSVariables(mergedTheme, prefix);
+    injectThemeVariables(cssVars, mergedTheme, prefix);
+}

package/dist/core/variants.js

@@ -0,0 +1,32 @@
+/**
+ * Variant application logic.
+ * Merges variant styles with base styles based on component props.
+ * Optimized to avoid unnecessary object spreads when no variants are applied.
+ */
+/**
+ * Applies variant styles to base styles based on component props.
+ *
+ * @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
+ */
+export function applyVariants(variants, props, baseStyles) {
+    let hasVariants = false;
+    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]);
+            hasVariants = true;
+        }
+    }
+    return hasVariants
+        ? { ...baseStyles, ...appliedVariantStyles.reduce((acc, style) => ({ ...acc, ...style }), {}) }
+        : baseStyles;
+}

package/dist/create-stoop-server.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Server-safe factory function that creates a Stoop instance.
+ * Only includes APIs that work without React: css, globalCss, keyframes, getCssText, etc.
+ * Does NOT include: styled, Provider, useTheme
+ *
+ * This is the entry point for Server Components in Next.js App Router.
+ */
+import type { CSS, StoopConfig, Theme } from "./types";
+/**
+ * Server-safe Stoop instance interface.
+ * Only includes APIs that work without React dependencies.
+ */
+export interface StoopServerInstance {
+    config: StoopConfig & {
+        prefix: string;
+    };
+    createTheme: (themeOverride: Partial<Theme>) => Theme;
+    css: (styles: CSS) => string;
+    getCssText: (theme?: string | Theme) => string;
+    globalCss: (...args: CSS[]) => () => void;
+    keyframes: (definition: Record<string, CSS>) => string;
+    preloadTheme: (theme: string | Theme) => void;
+    theme: Theme;
+    warmCache: (styles: CSS[]) => void;
+}
+/**
+ * Creates a server-safe Stoop instance with the provided configuration.
+ * Only includes APIs that work without React: css, globalCss, keyframes, getCssText, etc.
+ *
+ * @param config - Configuration object containing theme, media queries, utilities, and optional prefix/themeMap
+ * @returns StoopServerInstance with server-safe API functions
+ */
+export declare function createStoop(config: StoopConfig): StoopServerInstance;