stoop 0.2.1 → 0.4.0

package/dist/core/variants.js

@@ -0,0 +1,38 @@
+/**
+ * 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;
+        }
+    }
+    if (!hasVariants) {
+        return baseStyles;
+    }
+    // Merge all variant styles into a single object using spread for consistency
+    const mergedVariants = { ...appliedVariantStyles[0] };
+    for (let i = 1; i < appliedVariantStyles.length; i++) {
+        Object.assign(mergedVariants, appliedVariantStyles[i]);
+    }
+    return { ...baseStyles, ...mergedVariants };
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Internal implementation for creating Stoop instances.
+ * This file is used by the SSR entry point and does NOT import React types at module level.
+ * React types are only imported conditionally when creating client instances.
+ */
+import type { CSS, StoopConfig, Theme, ThemeScale } from "./types";
+import { createCSSFunction, createKeyframesFunction } from "./api/core-api";
+import { createGlobalCSSFunction } from "./api/global-css";
+/**
+ * Shared implementation for creating Stoop instances.
+ * Handles common setup logic for both client and server instances.
+ * Exported for use in SSR entry point.
+ */
+export declare function createStoopBase(config: StoopConfig): {
+    config: StoopConfig;
+    createTheme: (overrides?: Partial<Theme>) => Theme;
+    css: ReturnType<typeof createCSSFunction>;
+    getCssText: (theme?: string | Theme) => string;
+    globalCss: ReturnType<typeof createGlobalCSSFunction>;
+    globalCssConfig: StoopConfig["globalCss"];
+    keyframes: ReturnType<typeof createKeyframesFunction>;
+    media: StoopConfig["media"];
+    mergedThemeMap: Record<string, ThemeScale>;
+    preloadTheme: (theme: string | Theme) => void;
+    sanitizedPrefix: string;
+    theme: Theme;
+    utils: StoopConfig["utils"];
+    validatedTheme: Theme;
+    warmCache: (styles: CSS[]) => void;
+};

package/dist/create-stoop-internal.js

@@ -0,0 +1,123 @@
+/**
+ * Internal implementation for creating Stoop instances.
+ * This file is used by the SSR entry point and does NOT import React types at module level.
+ * React types are only imported conditionally when creating client instances.
+ */
+import { createTheme as createThemeFactory, createCSSFunction, createKeyframesFunction, } from "./api/core-api";
+import { createGlobalCSSFunction } from "./api/global-css";
+// Note: React APIs (styled, Provider) are NOT imported here for SSR safety
+import { DEFAULT_THEME_MAP } from "./constants";
+import { compileCSS } from "./core/compiler";
+import { mergeWithDefaultTheme, registerDefaultTheme, injectAllThemes } from "./core/theme-manager";
+import { getCssText as getCssTextBase, removeThemeVariableBlocks } from "./inject";
+import { validateTheme } from "./utils/helpers";
+import { generateAllThemeVariables, generateCSSVariables } from "./utils/theme";
+import { sanitizePrefix } from "./utils/theme-utils";
+/**
+ * Shared implementation for creating Stoop instances.
+ * Handles common setup logic for both client and server instances.
+ * Exported for use in SSR entry point.
+ */
+export function createStoopBase(config) {
+    const { globalCss: globalCssConfig, 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);
+    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.
+     * Uses injectAllThemes to ensure all themes are available.
+     *
+     * @param theme - Theme to preload (can be theme name string or Theme object)
+     */
+    function preloadTheme(theme) {
+        if (!config.themes || Object.keys(config.themes).length === 0) {
+            return;
+        }
+        // Always inject all themes for consistency and to prevent FOUC
+        injectAllThemes(config.themes, sanitizedPrefix);
+    }
+    /**
+     * Gets all injected CSS text for server-side rendering.
+     * Always includes all theme CSS variables using attribute selectors.
+     *
+     * @param theme - Deprecated parameter, kept for backward compatibility but ignored
+     * @returns CSS text string with theme variables and component styles
+     */
+    function getCssText(theme) {
+        let result = "";
+        // Always include all themes using attribute selectors for consistency
+        if (config.themes && Object.keys(config.themes).length > 0) {
+            // Merge all themes with default theme for consistency with client-side behavior
+            const mergedThemes = {};
+            for (const [themeName, theme] of Object.entries(config.themes)) {
+                mergedThemes[themeName] = mergeWithDefaultTheme(theme, sanitizedPrefix);
+            }
+            const allThemeVars = generateAllThemeVariables(mergedThemes, sanitizedPrefix, "data-theme");
+            if (allThemeVars) {
+                result += allThemeVars + "\n";
+            }
+        }
+        else {
+            // No themes configured, just use default theme
+            const themeVars = generateCSSVariables(validatedTheme, sanitizedPrefix);
+            if (themeVars) {
+                result += themeVars + "\n";
+            }
+        }
+        const baseCss = getCssTextBase();
+        // Remove any existing theme variable blocks (they're already included above)
+        const cleanedCss = removeThemeVariableBlocks(baseCss).trim();
+        if (cleanedCss) {
+            result += (result ? "\n" : "") + cleanedCss;
+        }
+        return result;
+    }
+    return {
+        config: { ...config, prefix: sanitizedPrefix },
+        createTheme,
+        css,
+        getCssText,
+        globalCss,
+        globalCssConfig,
+        keyframes,
+        media,
+        mergedThemeMap,
+        preloadTheme,
+        sanitizedPrefix,
+        theme: themeObject,
+        utils,
+        // Internal values for React API creation
+        validatedTheme,
+        warmCache,
+    };
+}
+// Export createStoopBase for use in SSR entry point
+// Note: This file does NOT export createStoop() - that's in create-stoop.ts
+// This separation allows SSR entry point to avoid bundling React code

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

@@ -0,0 +1,10 @@
+/**
+ * SSR-safe entry point for Stoop.
+ * Exports only server-safe APIs that don't require React.
+ * Use this import in Server Components: import { createStoop } from "stoop/ssr"
+ *
+ * This file does NOT import React types or create React components.
+ */
+import type { StoopConfig, StoopServerInstance } from "./types";
+export type { CSS, Theme, StoopConfig, StoopServerInstance, UtilityFunction, ThemeScale, DefaultTheme, } from "./types";
+export declare function createStoop(config: StoopConfig): StoopServerInstance;

package/dist/create-stoop-ssr.js

@@ -0,0 +1,26 @@
+/**
+ * SSR-safe entry point for Stoop.
+ * Exports only server-safe APIs that don't require React.
+ * Use this import in Server Components: import { createStoop } from "stoop/ssr"
+ *
+ * This file does NOT import React types or create React components.
+ */
+// Import createStoopBase from create-stoop-internal to avoid React type imports
+// create-stoop-internal.ts is a copy of create-stoop.ts without React imports at module level
+import { createStoopBase } from "./create-stoop-internal";
+export function createStoop(config) {
+    const base = createStoopBase(config);
+    // Return only server-safe APIs (no React components)
+    // Ensure config.prefix is always a string (not undefined) for type compatibility
+    return {
+        config: { ...base.config, prefix: base.sanitizedPrefix },
+        createTheme: base.createTheme,
+        css: base.css,
+        getCssText: base.getCssText,
+        globalCss: base.globalCss,
+        keyframes: base.keyframes,
+        preloadTheme: base.preloadTheme,
+        theme: base.theme,
+        warmCache: base.warmCache,
+    };
+}

package/dist/create-stoop.d.ts

@@ -1,12 +1,40 @@
 /**
- * Main factory function that creates a Stoop instance.
- * Configures theme, media queries, utilities, and returns all API functions.
+ * Factory function that creates a Stoop instance.
+ * Supports both client-side (with React APIs) and server-side (without React) usage.
+ * Automatically detects environment and includes appropriate APIs.
  */
-import type { StoopConfig, StoopInstance } from "./types";
+import type { CSS, StoopConfig, StoopInstance, Theme, ThemeScale } from "./types";
+import { createCSSFunction, createKeyframesFunction } from "./api/core-api";
+import { createGlobalCSSFunction } from "./api/global-css";
+/**
+ * Shared implementation for creating Stoop instances.
+ * Handles common setup logic for both client and server instances.
+ * Exported for use in SSR entry point.
+ */
+export declare function createStoopBase(config: StoopConfig): {
+    config: StoopConfig;
+    createTheme: (overrides?: Partial<Theme>) => Theme;
+    css: ReturnType<typeof createCSSFunction>;
+    getCssText: (theme?: string | Theme) => string;
+    globalCss: ReturnType<typeof createGlobalCSSFunction>;
+    globalCssConfig: StoopConfig["globalCss"];
+    keyframes: ReturnType<typeof createKeyframesFunction>;
+    media: StoopConfig["media"];
+    mergedThemeMap: Record<string, ThemeScale>;
+    preloadTheme: (theme: string | Theme) => void;
+    sanitizedPrefix: string;
+    theme: Theme;
+    utils: StoopConfig["utils"];
+    validatedTheme: Theme;
+    warmCache: (styles: CSS[]) => void;
+};
 /**
  * Creates a Stoop instance with the provided configuration.
+ * Includes all APIs: styled, Provider, useTheme, etc.
+ * In server contexts without React, React APIs will be undefined.
  *
  * @param config - Configuration object containing theme, media queries, utilities, and optional prefix/themeMap
- * @returns StoopInstance with all API functions (styled, css, globalCss, keyframes, createTheme, etc.)
+ * @returns StoopInstance with all API functions
  */
+export type { CSS, Theme, StoopConfig, StoopInstance, UtilityFunction, ThemeScale, DefaultTheme, } from "./types";
 export declare function createStoop(config: StoopConfig): StoopInstance;

package/dist/create-stoop.js

@@ -0,0 +1,156 @@
+/**
+ * Factory function that creates a Stoop instance.
+ * Supports both client-side (with React APIs) and server-side (without React) usage.
+ * Automatically detects environment and includes appropriate APIs.
+ */
+import { createTheme as createThemeFactory, createCSSFunction, createKeyframesFunction, } from "./api/core-api";
+import { createGlobalCSSFunction } from "./api/global-css";
+import { createStyledFunction } from "./api/styled";
+import { createProvider, createUseThemeHook } from "./api/theme-provider";
+import { DEFAULT_THEME_MAP } from "./constants";
+import { compileCSS } from "./core/compiler";
+import { mergeWithDefaultTheme, registerDefaultTheme, injectAllThemes } from "./core/theme-manager";
+import { getCssText as getCssTextBase, removeThemeVariableBlocks } from "./inject";
+import { validateTheme } from "./utils/helpers";
+import { generateAllThemeVariables, generateCSSVariables } from "./utils/theme";
+import { sanitizePrefix } from "./utils/theme-utils";
+/**
+ * Shared implementation for creating Stoop instances.
+ * Handles common setup logic for both client and server instances.
+ * Exported for use in SSR entry point.
+ */
+export function createStoopBase(config) {
+    const { globalCss: globalCssConfig, 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);
+    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.
+     * Uses injectAllThemes to ensure all themes are available.
+     *
+     * @param theme - Theme to preload (can be theme name string or Theme object)
+     */
+    function preloadTheme(theme) {
+        if (!config.themes || Object.keys(config.themes).length === 0) {
+            return;
+        }
+        // Always inject all themes for consistency and to prevent FOUC
+        injectAllThemes(config.themes, sanitizedPrefix);
+    }
+    /**
+     * Gets all injected CSS text for server-side rendering.
+     * Always includes all theme CSS variables using attribute selectors.
+     *
+     * @param theme - Deprecated parameter, kept for backward compatibility but ignored
+     * @returns CSS text string with theme variables and component styles
+     */
+    function getCssText(theme) {
+        let result = "";
+        // Always include all themes using attribute selectors for consistency
+        if (config.themes && Object.keys(config.themes).length > 0) {
+            // Merge all themes with default theme for consistency with client-side behavior
+            const mergedThemes = {};
+            for (const [themeName, theme] of Object.entries(config.themes)) {
+                mergedThemes[themeName] = mergeWithDefaultTheme(theme, sanitizedPrefix);
+            }
+            const allThemeVars = generateAllThemeVariables(mergedThemes, sanitizedPrefix, "data-theme");
+            if (allThemeVars) {
+                result += allThemeVars + "\n";
+            }
+        }
+        else {
+            // No themes configured, just use default theme
+            const themeVars = generateCSSVariables(validatedTheme, sanitizedPrefix);
+            if (themeVars) {
+                result += themeVars + "\n";
+            }
+        }
+        const baseCss = getCssTextBase();
+        // Remove any existing theme variable blocks (they're already included above)
+        const cleanedCss = removeThemeVariableBlocks(baseCss).trim();
+        if (cleanedCss) {
+            result += (result ? "\n" : "") + cleanedCss;
+        }
+        return result;
+    }
+    return {
+        config: { ...config, prefix: sanitizedPrefix },
+        createTheme,
+        css,
+        getCssText,
+        globalCss,
+        globalCssConfig,
+        keyframes,
+        media,
+        mergedThemeMap,
+        preloadTheme,
+        sanitizedPrefix,
+        theme: themeObject,
+        utils,
+        // Internal values for React API creation
+        validatedTheme,
+        warmCache,
+    };
+}
+export function createStoop(config) {
+    const base = createStoopBase(config);
+    // Create full client instance (React APIs may be undefined in SSR contexts)
+    // Create Provider and useTheme if themes are configured
+    let Provider;
+    let useTheme;
+    let themeContext;
+    if (config.themes) {
+        const mergedThemesForProvider = {};
+        for (const [themeName, themeOverride] of Object.entries(config.themes)) {
+            mergedThemesForProvider[themeName] = base.createTheme(themeOverride);
+        }
+        const { Provider: ProviderComponent, ThemeContext, ThemeManagementContext, } = createProvider(mergedThemesForProvider, base.validatedTheme, base.sanitizedPrefix, base.globalCssConfig, base.globalCss);
+        themeContext = ThemeContext;
+        Provider = ProviderComponent;
+        useTheme = createUseThemeHook(ThemeManagementContext);
+    }
+    // Create styled function
+    const styled = createStyledFunction(base.validatedTheme, base.sanitizedPrefix, base.media, base.utils, base.mergedThemeMap, themeContext);
+    // Return instance with all APIs
+    return {
+        config: base.config,
+        createTheme: base.createTheme,
+        css: base.css,
+        getCssText: base.getCssText,
+        globalCss: base.globalCss,
+        keyframes: base.keyframes,
+        preloadTheme: base.preloadTheme,
+        Provider,
+        styled,
+        theme: base.theme,
+        useTheme,
+        warmCache: base.warmCache,
+    };
+}

package/dist/inject.d.ts

@@ -0,0 +1,113 @@
+/**
+ * CSS injection implementation.
+ * Consolidates browser-specific and SSR-specific CSS injection logic.
+ * Handles stylesheet management, theme variable injection, deduplication, and SSR caching.
+ */
+/**
+ * Checks if a CSS rule has already been injected.
+ *
+ * @param key - Rule key to check
+ * @returns True if rule is already injected
+ */
+export declare function isInjectedRule(key: string): boolean;
+/**
+ * Marks a CSS rule as injected.
+ *
+ * @param key - Rule key
+ * @param css - CSS string
+ */
+export declare function markRuleAsInjected(key: string, css: string): void;
+/**
+ * Adds CSS to the SSR cache with LRU eviction.
+ *
+ * @param css - CSS string to cache
+ */
+export declare function addToSSRCache(css: string): void;
+/**
+ * Gets all cached CSS text for SSR.
+ *
+ * @returns Joined CSS text string
+ */
+export declare function getSSRCacheText(): string;
+/**
+ * Clears the SSR cache.
+ */
+export declare function clearSSRCache(): void;
+/**
+ * Checks if CSS is already in the SSR cache.
+ *
+ * @param css - CSS string to check
+ * @returns True if CSS is cached
+ */
+export declare function isInSSRCache(css: string): boolean;
+/**
+ * Gets or creates the stylesheet element for CSS injection.
+ * Reuses the SSR stylesheet if it exists to prevent FOUC.
+ * Supports multiple Stoop instances with different prefixes.
+ *
+ * @param prefix - Optional prefix for stylesheet identification
+ * @returns HTMLStyleElement
+ * @throws Error if called in SSR context
+ */
+export declare function getStylesheet(prefix?: string): HTMLStyleElement;
+/**
+ * Removes all theme variable blocks (both :root and attribute selectors) from CSS.
+ *
+ * @param css - CSS string to clean
+ * @returns CSS string without theme variable blocks
+ */
+export declare function removeThemeVariableBlocks(css: string): string;
+/**
+ * Injects CSS variables for all themes using attribute selectors.
+ * This allows all themes to be available simultaneously, with theme switching
+ * handled by changing the data-theme attribute.
+ *
+ * @param allThemeVars - CSS string containing all theme CSS variables
+ * @param prefix - Optional prefix for CSS variables
+ */
+export declare function injectAllThemeVariables(allThemeVars: string, 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 for a given prefix.
+ *
+ * @param prefix - Optional prefix for stylesheet identification
+ * @returns HTMLStyleElement or null if not created
+ */
+export declare function getStylesheetElement(prefix?: string): HTMLStyleElement | null;
+/**
+ * Gets all injected rules (for internal use).
+ */
+export declare function getAllInjectedRules(): Map<string, string>;
+/**
+ * Injects CSS into the document with automatic SSR support.
+ *
+ * @param css - CSS string to inject
+ * @param prefix - Optional prefix for CSS rules
+ * @param ruleKey - Optional unique key for deduplication
+ */
+export declare function injectCSS(css: string, prefix?: string, ruleKey?: string): void;
+/**
+ * Gets all injected CSS text (browser or SSR).
+ *
+ * @returns CSS text string
+ */
+export declare function getCssText(prefix?: string): string;
+/**
+ * Clears all injected CSS and caches.
+ */
+export declare function clearStylesheet(): void;