stoop 0.3.0 → 0.4.1

package/dist/core/compiler.js

@@ -1,198 +0,0 @@
-/**
- * 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.js

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

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

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

package/dist/create-stoop-server.js

@@ -1,130 +0,0 @@
-/**
- * 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 { createTheme as createThemeFactory } from "./api/create-theme";
-import { createCSSFunction } from "./api/css";
-import { createGlobalCSSFunction } from "./api/global-css";
-import { createKeyframesFunction } from "./api/keyframes";
-import { DEFAULT_THEME_MAP } from "./constants";
-import { compileCSS } from "./core/compiler";
-import { registerDefaultTheme, updateThemeVariables } from "./core/theme-manager";
-import { getCssText as getCssTextBase, registerTheme } from "./inject";
-import { getRootRegex, sanitizePrefix } from "./utils/string";
-import { generateCSSVariables } from "./utils/theme";
-import { validateTheme } from "./utils/theme-validation";
-/**
- * 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 function createStoop(config) {
-    const { media: configMedia, prefix = "stoop", theme, themeMap: userThemeMap, utils } = config;
-    const sanitizedPrefix = sanitizePrefix(prefix);
-    const validatedTheme = validateTheme(theme);
-    const media = validatedTheme.media || configMedia;
-    const mergedThemeMap = {
-        ...DEFAULT_THEME_MAP,
-        ...userThemeMap,
-    };
-    registerDefaultTheme(validatedTheme, sanitizedPrefix);
-    registerTheme(validatedTheme, sanitizedPrefix);
-    const css = createCSSFunction(validatedTheme, sanitizedPrefix, media, utils, mergedThemeMap);
-    const createTheme = createThemeFactory(validatedTheme);
-    const globalCss = createGlobalCSSFunction(validatedTheme, sanitizedPrefix, media, utils, mergedThemeMap);
-    const keyframes = createKeyframesFunction(sanitizedPrefix, validatedTheme, mergedThemeMap);
-    const themeObject = Object.freeze({ ...validatedTheme });
-    /**
-     * Pre-compiles CSS objects to warm the cache.
-     * Useful for eliminating FOUC by pre-compiling common styles.
-     *
-     * @param styles - Array of CSS objects to pre-compile
-     */
-    function warmCache(styles) {
-        for (const style of styles) {
-            try {
-                compileCSS(style, validatedTheme, sanitizedPrefix, media, utils, mergedThemeMap);
-            }
-            catch {
-                // Skip invalid styles
-            }
-        }
-    }
-    /**
-     * Preloads a theme by injecting its CSS variables before React renders.
-     * Useful for preventing FOUC when loading a non-default theme from localStorage.
-     *
-     * @param theme - Theme to preload (can be theme name string or Theme object)
-     */
-    function preloadTheme(theme) {
-        let themeToInject;
-        if (typeof theme === "string") {
-            if (config.themes && config.themes[theme]) {
-                themeToInject = config.themes[theme];
-            }
-            else {
-                if (typeof process !== "undefined" && process.env?.NODE_ENV !== "production") {
-                    // eslint-disable-next-line no-console
-                    console.warn(`[Stoop] Theme "${theme}" not found. Available themes: ${config.themes ? Object.keys(config.themes).join(", ") : "none"}`);
-                }
-                return;
-            }
-        }
-        else {
-            themeToInject = theme;
-        }
-        updateThemeVariables(themeToInject, sanitizedPrefix);
-    }
-    /**
-     * Gets all injected CSS text for server-side rendering.
-     * Always includes theme CSS variables.
-     *
-     * @param theme - Optional theme (name or object) to include vars for (defaults to default theme)
-     * @returns CSS text string with theme variables and component styles
-     */
-    function getCssText(theme) {
-        let themeToUse = validatedTheme;
-        if (theme) {
-            if (typeof theme === "string") {
-                if (config.themes && config.themes[theme]) {
-                    themeToUse = config.themes[theme];
-                }
-                else if (typeof process !== "undefined" && process.env?.NODE_ENV !== "production") {
-                    // eslint-disable-next-line no-console
-                    console.warn(`[Stoop] Theme "${theme}" not found. Using default theme. Available: ${config.themes ? Object.keys(config.themes).join(", ") : "none"}`);
-                }
-            }
-            else {
-                themeToUse = theme;
-            }
-        }
-        let result = "";
-        const themeVars = generateCSSVariables(themeToUse, sanitizedPrefix);
-        if (themeVars) {
-            result += themeVars + "\n";
-        }
-        const baseCss = getCssTextBase();
-        const rootRegex = getRootRegex(sanitizedPrefix);
-        const cssWithoutThemeVars = baseCss.replace(rootRegex, "").trim();
-        if (cssWithoutThemeVars) {
-            result += (result ? "\n" : "") + cssWithoutThemeVars;
-        }
-        return result;
-    }
-    return {
-        config: { ...config, prefix: sanitizedPrefix },
-        createTheme,
-        css,
-        getCssText,
-        globalCss,
-        keyframes,
-        preloadTheme,
-        theme: themeObject,
-        warmCache,
-    };
-}

package/dist/index.d.ts

@@ -1,6 +0,0 @@
-/**
- * Main entry point for Stoop CSS-in-JS library.
- * Exports the createStoop factory function and essential public types.
- */
-export { createStoop } from "./create-stoop";
-export type { CSS, StoopConfig, StoopInstance, StyledComponentProps, Theme, UtilityFunction, Variants, } from "./types";

package/dist/index.js

@@ -1,5 +0,0 @@
-/**
- * Main entry point for Stoop CSS-in-JS library.
- * Exports the createStoop factory function and essential public types.
- */
-export { createStoop } from "./create-stoop";

package/dist/inject/browser.d.ts

@@ -1,58 +0,0 @@
-/**
- * Browser-specific CSS injection.
- * Manages a single stylesheet element that gets updated with new CSS rules.
- * Handles theme variable injection, deduplication, and stylesheet lifecycle.
- */
-import type { Theme } from "../types";
-/**
- * Gets or creates the stylesheet element for CSS injection.
- * Reuses the SSR stylesheet if it exists to prevent FOUC.
- *
- * @param prefix - Optional prefix for stylesheet identification
- * @returns HTMLStyleElement
- * @throws Error if called in SSR context
- */
-export declare function getStylesheet(prefix?: string): HTMLStyleElement;
-/**
- * Injects theme CSS variables into the stylesheet.
- * Automatically ensures stylesheet exists before injection.
- *
- * @param cssVars - CSS variables string
- * @param theme - Theme object
- * @param prefix - Optional prefix for CSS variables
- */
-export declare function injectThemeVariables(cssVars: string, theme: Theme, prefix?: string): void;
-/**
- * Registers a theme for injection (browser-specific).
- * Automatically ensures stylesheet exists and injects theme variables.
- *
- * @param theme - Theme object to register
- * @param prefix - Optional prefix for CSS variables
- */
-export declare function registerTheme(theme: Theme, prefix?: string): void;
-/**
- * Updates the stylesheet with new CSS rules.
- *
- * @param css - CSS string to inject
- * @param ruleKey - Unique key for deduplication
- * @param prefix - Optional prefix for CSS rules
- */
-export declare function updateStylesheet(css: string, ruleKey: string, prefix?: string): void;
-/**
- * Injects CSS into the browser stylesheet with deduplication.
- *
- * @param css - CSS string to inject
- * @param ruleKey - Unique key for deduplication
- * @param prefix - Optional prefix for CSS rules
- */
-export declare function injectBrowserCSS(css: string, ruleKey: string, prefix?: string): void;
-/**
- * Gets the current stylesheet element.
- *
- * @returns HTMLStyleElement or null if not created
- */
-export declare function getStylesheetElement(): HTMLStyleElement | null;
-/**
- * Clears the stylesheet and all caches.
- */
-export declare function clearStylesheet(): void;