stoop 0.3.0 → 0.4.0

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,9 +1,40 @@
-import type { StoopConfig, StoopInstance } from "./types";
+/**
+ * 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 { 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
  */
+export type { CSS, Theme, StoopConfig, StoopInstance, UtilityFunction, ThemeScale, DefaultTheme, } from "./types";
 export declare function createStoop(config: StoopConfig): StoopInstance;

package/dist/create-stoop.js

@@ -1,27 +1,26 @@
-"use client";
-import { createTheme as createThemeFactory } from "./api/create-theme";
-import { createCSSFunction } from "./api/css";
+/**
+ * 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 { createKeyframesFunction } from "./api/keyframes";
-import { createProvider } from "./api/provider";
 import { createStyledFunction } from "./api/styled";
-import { createUseThemeHook } from "./api/use-theme";
+import { createProvider, createUseThemeHook } from "./api/theme-provider";
 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";
+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";
 /**
- * Creates a Stoop instance with the provided configuration.
- * Includes all APIs: styled, Provider, useTheme, etc.
- *
- * @param config - Configuration object containing theme, media queries, utilities, and optional prefix/themeMap
- * @returns StoopInstance with all API functions
+ * 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 createStoop(config) {
-    const { media: configMedia, prefix = "stoop", theme, themeMap: userThemeMap, utils } = config;
+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;
@@ -30,7 +29,6 @@ export function createStoop(config) {
         ...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);
@@ -55,64 +53,75 @@ export function createStoop(config) {
     /**
      * 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) {
-        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;
-            }
+        if (!config.themes || Object.keys(config.themes).length === 0) {
+            return;
         }
-        else {
-            themeToInject = theme;
-        }
-        updateThemeVariables(themeToInject, sanitizedPrefix);
+        // 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 theme CSS variables.
+     * Always includes all theme CSS variables using attribute selectors.
      *
-     * @param theme - Optional theme (name or object) to include vars for (defaults to default theme)
+     * @param theme - Deprecated parameter, kept for backward compatibility but ignored
      * @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"}`);
-                }
+        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);
             }
-            else {
-                themeToUse = theme;
+            const allThemeVars = generateAllThemeVariables(mergedThemes, sanitizedPrefix, "data-theme");
+            if (allThemeVars) {
+                result += allThemeVars + "\n";
             }
         }
-        let result = "";
-        const themeVars = generateCSSVariables(themeToUse, sanitizedPrefix);
-        if (themeVars) {
-            result += themeVars + "\n";
+        else {
+            // No themes configured, just use default theme
+            const themeVars = generateCSSVariables(validatedTheme, 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;
+        // 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;
@@ -120,28 +129,28 @@ export function createStoop(config) {
     if (config.themes) {
         const mergedThemesForProvider = {};
         for (const [themeName, themeOverride] of Object.entries(config.themes)) {
-            mergedThemesForProvider[themeName] = createTheme(themeOverride);
+            mergedThemesForProvider[themeName] = base.createTheme(themeOverride);
         }
-        const { Provider: ProviderComponent, ThemeContext, ThemeManagementContext, } = createProvider(mergedThemesForProvider, validatedTheme, sanitizedPrefix);
+        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(validatedTheme, sanitizedPrefix, media, utils, mergedThemeMap, themeContext);
+    const styled = createStyledFunction(base.validatedTheme, base.sanitizedPrefix, base.media, base.utils, base.mergedThemeMap, themeContext);
     // Return instance with all APIs
     return {
-        config: { ...config, prefix: sanitizedPrefix },
-        createTheme,
-        css,
-        getCssText,
-        globalCss,
-        keyframes,
-        preloadTheme,
+        config: base.config,
+        createTheme: base.createTheme,
+        css: base.css,
+        getCssText: base.getCssText,
+        globalCss: base.globalCss,
+        keyframes: base.keyframes,
+        preloadTheme: base.preloadTheme,
         Provider,
         styled,
-        theme: themeObject,
+        theme: base.theme,
         useTheme,
-        warmCache,
+        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;