stoop 0.4.0 → 0.5.0

package/dist/create-stoop-internal.js

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

@@ -1,308 +0,0 @@
-/**
- * CSS injection implementation.
- * Consolidates browser-specific and SSR-specific CSS injection logic.
- * Handles stylesheet management, theme variable injection, deduplication, and SSR caching.
- */
-import { MAX_CSS_CACHE_SIZE } from "./constants";
-import { LRUCache, clearStyleCache } from "./core/cache";
-import { isBrowser } from "./utils/helpers";
-import { getRootRegex, sanitizePrefix } from "./utils/theme-utils";
-// ============================================================================
-// Internal Deduplication
-// ============================================================================
-const injectedRules = new Map();
-/**
- * Checks if a CSS rule has already been injected.
- *
- * @param key - Rule key to check
- * @returns True if rule is already injected
- */
-export function isInjectedRule(key) {
-    return injectedRules.has(key);
-}
-/**
- * Marks a CSS rule as injected.
- *
- * @param key - Rule key
- * @param css - CSS string
- */
-export function markRuleAsInjected(key, css) {
-    injectedRules.set(key, css);
-}
-// ============================================================================
-// SSR Cache Management
-// ============================================================================
-// Use LRUCache for reliable FIFO eviction (Map iteration order not guaranteed)
-const cssTextCache = new LRUCache(MAX_CSS_CACHE_SIZE);
-/**
- * Adds CSS to the SSR cache with LRU eviction.
- *
- * @param css - CSS string to cache
- */
-export function addToSSRCache(css) {
-    if (!cssTextCache.has(css)) {
-        cssTextCache.set(css, true);
-    }
-}
-/**
- * Gets all cached CSS text for SSR.
- *
- * @returns Joined CSS text string
- */
-export function getSSRCacheText() {
-    return Array.from(cssTextCache.keys()).join("\n");
-}
-/**
- * Clears the SSR cache.
- */
-export function clearSSRCache() {
-    cssTextCache.clear();
-}
-/**
- * Checks if CSS is already in the SSR cache.
- *
- * @param css - CSS string to check
- * @returns True if CSS is cached
- */
-export function isInSSRCache(css) {
-    return cssTextCache.has(css);
-}
-// ============================================================================
-// Browser-Specific Injection
-// ============================================================================
-// Map of prefix -> stylesheet element to support multiple Stoop instances
-const stylesheetElements = new Map();
-const lastInjectedThemes = new Map();
-const lastInjectedCSSVars = new Map();
-/**
- * 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 function getStylesheet(prefix = "stoop") {
-    if (!isBrowser()) {
-        throw new Error("Cannot access document in SSR context");
-    }
-    const sanitizedPrefix = sanitizePrefix(prefix);
-    let stylesheetElement = stylesheetElements.get(sanitizedPrefix);
-    if (!stylesheetElement || !stylesheetElement.parentNode) {
-        // Check if SSR stylesheet exists and matches this prefix
-        const ssrStylesheet = document.getElementById("stoop-ssr");
-        if (ssrStylesheet) {
-            const existingPrefix = ssrStylesheet.getAttribute("data-stoop");
-            // Only reuse if prefix matches or no prefix set yet
-            if (!existingPrefix || existingPrefix === sanitizedPrefix) {
-                stylesheetElement = ssrStylesheet;
-                stylesheetElement.setAttribute("data-stoop", sanitizedPrefix);
-                stylesheetElements.set(sanitizedPrefix, stylesheetElement);
-                return stylesheetElement;
-            }
-        }
-        // Create new stylesheet for this prefix
-        stylesheetElement = document.createElement("style");
-        stylesheetElement.setAttribute("data-stoop", sanitizedPrefix);
-        stylesheetElement.setAttribute("id", `stoop-${sanitizedPrefix}`);
-        document.head.appendChild(stylesheetElement);
-        stylesheetElements.set(sanitizedPrefix, stylesheetElement);
-    }
-    return stylesheetElement;
-}
-/**
- * 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 function removeThemeVariableBlocks(css) {
-    let result = css;
-    // Remove :root blocks using regex
-    const rootRegex = getRootRegex("");
-    result = result.replace(rootRegex, "").trim();
-    // Remove attribute selector blocks manually (handles nested braces)
-    let startIndex = result.indexOf("[data-theme=");
-    while (startIndex !== -1) {
-        const openBrace = result.indexOf("{", startIndex);
-        if (openBrace === -1) {
-            break;
-        }
-        let braceCount = 1;
-        let closeBrace = openBrace + 1;
-        while (closeBrace < result.length && braceCount > 0) {
-            if (result[closeBrace] === "{") {
-                braceCount++;
-            }
-            else if (result[closeBrace] === "}") {
-                braceCount--;
-            }
-            closeBrace++;
-        }
-        if (braceCount === 0) {
-            const before = result.substring(0, startIndex).trim();
-            const after = result.substring(closeBrace).trim();
-            result = (before + "\n" + after).trim();
-        }
-        else {
-            break;
-        }
-        startIndex = result.indexOf("[data-theme=");
-    }
-    return result.trim();
-}
-/**
- * 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 function injectAllThemeVariables(allThemeVars, prefix = "stoop") {
-    if (!allThemeVars) {
-        return;
-    }
-    const sanitizedPrefix = sanitizePrefix(prefix);
-    const key = `__all_theme_vars_${sanitizedPrefix}`;
-    const lastCSSVars = lastInjectedCSSVars.get(key) ?? null;
-    // Only skip if CSS vars string is exactly the same
-    if (lastCSSVars === allThemeVars) {
-        return;
-    }
-    lastInjectedCSSVars.set(key, allThemeVars);
-    if (!isBrowser()) {
-        addToSSRCache(allThemeVars);
-        return;
-    }
-    const sheet = getStylesheet(sanitizedPrefix);
-    const currentCSS = sheet.textContent || "";
-    // Check if theme variable blocks exist
-    const hasThemeBlocks = currentCSS.includes(":root") || currentCSS.includes("[data-theme=");
-    if (isInjectedRule(key) || hasThemeBlocks) {
-        // Remove all existing theme variable blocks
-        const withoutVars = removeThemeVariableBlocks(currentCSS);
-        // Update stylesheet synchronously - prepend all theme vars, then append rest
-        sheet.textContent = allThemeVars + (withoutVars ? "\n\n" + withoutVars : "");
-        markRuleAsInjected(key, allThemeVars);
-    }
-    else {
-        // First injection - no existing theme blocks
-        sheet.textContent = allThemeVars + (currentCSS ? "\n\n" + currentCSS : "");
-        markRuleAsInjected(key, allThemeVars);
-    }
-}
-/**
- * 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 function updateStylesheet(css, ruleKey, prefix = "stoop") {
-    if (!isBrowser()) {
-        return;
-    }
-    const sanitizedPrefix = sanitizePrefix(prefix);
-    if (isInjectedRule(ruleKey)) {
-        return;
-    }
-    const sheet = getStylesheet(sanitizedPrefix);
-    const currentCSS = sheet.textContent || "";
-    sheet.textContent = currentCSS + (currentCSS ? "\n" : "") + css;
-    markRuleAsInjected(ruleKey, css);
-}
-/**
- * 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 function injectBrowserCSS(css, ruleKey, prefix = "stoop") {
-    if (isInjectedRule(ruleKey)) {
-        return;
-    }
-    const sanitizedPrefix = sanitizePrefix(prefix);
-    updateStylesheet(css, ruleKey, sanitizedPrefix);
-}
-/**
- * Gets the current stylesheet element for a given prefix.
- *
- * @param prefix - Optional prefix for stylesheet identification
- * @returns HTMLStyleElement or null if not created
- */
-export function getStylesheetElement(prefix = "stoop") {
-    const sanitizedPrefix = sanitizePrefix(prefix);
-    return stylesheetElements.get(sanitizedPrefix) || null;
-}
-/**
- * Clears the stylesheet and all caches (internal).
- */
-function clearStylesheetInternal() {
-    // Remove all stylesheet elements
-    for (const [, element] of stylesheetElements.entries()) {
-        if (element && element.parentNode) {
-            element.parentNode.removeChild(element);
-        }
-    }
-    stylesheetElements.clear();
-    lastInjectedThemes.clear();
-    lastInjectedCSSVars.clear();
-    injectedRules.clear();
-}
-/**
- * Gets all injected rules (for internal use).
- */
-export function getAllInjectedRules() {
-    return new Map(injectedRules);
-}
-// ============================================================================
-// Public API Functions
-// ============================================================================
-/**
- * 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 function injectCSS(css, prefix = "stoop", ruleKey) {
-    const key = ruleKey || css;
-    if (!isBrowser()) {
-        if (!isInjectedRule(key)) {
-            markRuleAsInjected(key, css);
-        }
-        addToSSRCache(css);
-        return;
-    }
-    injectBrowserCSS(css, key, prefix);
-}
-/**
- * Gets all injected CSS text (browser or SSR).
- *
- * @returns CSS text string
- */
-export function getCssText(prefix = "stoop") {
-    if (isBrowser()) {
-        const sanitizedPrefix = sanitizePrefix(prefix);
-        const sheetElement = getStylesheetElement(sanitizedPrefix);
-        if (sheetElement && sheetElement.parentNode) {
-            const sheetCSS = sheetElement.textContent || "";
-            if (!sheetCSS && getAllInjectedRules().size > 0) {
-                return getSSRCacheText();
-            }
-            return sheetCSS;
-        }
-    }
-    return getSSRCacheText();
-}
-/**
- * Clears all injected CSS and caches.
- */
-export function clearStylesheet() {
-    clearStylesheetInternal();
-    clearSSRCache();
-    clearStyleCache();
-}

package/dist/types/index.js

@@ -1,5 +0,0 @@
-/**
- * Core TypeScript type definitions for Stoop.
- * Defines CSS objects, themes, variants, styled components, and instance types.
- */
-export {};

package/dist/utils/auto-preload.d.ts

@@ -1,45 +0,0 @@
-/**
- * Auto-preloading utilities for cache warming and theme preloading.
- * Helps eliminate FOUC (Flash of Unstyled Content) by pre-compiling styles and preloading themes.
- */
-import type { CSS, Theme, ThemeDetectionOptions, ThemeDetectionResult, AutoPreloadOptions, AutoPreloadResult } from "../types";
-/**
- * Common UI component styles that are frequently used.
- * These represent typical design system patterns.
- */
-export declare const COMMON_UI_STYLES: CSS[];
-/**
- * Automatically warms the cache with common styles.
- *
- * @param warmCacheFn - The warmCache function from Stoop instance
- * @param styles - Styles to warm (defaults to COMMON_UI_STYLES)
- * @returns Promise that resolves when warming is complete
- */
-export declare function autoWarmCache(warmCacheFn: (styles: CSS[]) => void, styles?: CSS[]): Promise<void>;
-/**
- * Automatically preloads a detected theme.
- *
- * @param preloadThemeFn - The preloadTheme function from Stoop instance
- * @param options - Theme detection options
- * @param ssr - Whether running in SSR context
- * @returns Promise that resolves when preloading is complete
- */
-export declare function autoPreloadTheme(preloadThemeFn: (theme: string | Theme) => void, options?: ThemeDetectionOptions, ssr?: boolean): Promise<ThemeDetectionResult>;
-/**
- * Performs automatic preloading operations based on configuration.
- *
- * @param warmCacheFn - The warmCache function from Stoop instance
- * @param preloadThemeFn - The preloadTheme function from Stoop instance
- * @param options - Auto-preload options
- * @returns Promise that resolves with preload results
- */
-export declare function autoPreload(warmCacheFn: (styles: CSS[]) => void, preloadThemeFn: (theme: string | Theme) => void, options?: AutoPreloadOptions): Promise<AutoPreloadResult>;
-/**
- * Creates an auto-preloader with pre-configured options.
- *
- * @param warmCacheFn - The warmCache function from Stoop instance
- * @param preloadThemeFn - The preloadTheme function from Stoop instance
- * @param defaultOptions - Default auto-preload options
- * @returns Auto-preloader function
- */
-export declare function createAutoPreloader(warmCacheFn: (styles: CSS[]) => void, preloadThemeFn: (theme: string | Theme) => void, defaultOptions?: AutoPreloadOptions): (options?: Partial<AutoPreloadOptions>) => Promise<AutoPreloadResult>;

package/dist/utils/auto-preload.js

@@ -1,167 +0,0 @@
-/* eslint-disable no-console */
-/**
- * Auto-preloading utilities for cache warming and theme preloading.
- * Helps eliminate FOUC (Flash of Unstyled Content) by pre-compiling styles and preloading themes.
- */
-import { detectTheme, detectThemeForSSR } from "./storage";
-/**
- * Common UI component styles that are frequently used.
- * These represent typical design system patterns.
- */
-export const COMMON_UI_STYLES = [
-    // Layout primitives
-    { alignItems: "center", display: "flex", justifyContent: "center" },
-    { display: "flex", flexDirection: "column" },
-    { position: "relative" },
-    // Spacing utilities
-    { padding: "$small" },
-    { padding: "$medium" },
-    { padding: "$large" },
-    { margin: "$small" },
-    { margin: "$medium" },
-    { margin: "$large" },
-    // Typography
-    { fontSize: "$small" },
-    { fontSize: "$medium" },
-    { fontSize: "$large" },
-    { fontWeight: "$normal" },
-    { fontWeight: "$bold" },
-    // Colors (using theme tokens)
-    { color: "$text" },
-    { color: "$textSecondary" },
-    { backgroundColor: "$surface" },
-    { backgroundColor: "$surfaceHover" },
-    { border: "1px solid $border" },
-    { borderColor: "$border" },
-    // Interactive states
-    { cursor: "pointer" },
-    { opacity: 0.5 },
-    { opacity: 0.7 },
-    // Positioning
-    { bottom: 0, left: 0, right: 0, top: 0 },
-    { height: "100%", width: "100%" },
-    // Borders and radii
-    { borderRadius: "$small" },
-    { borderRadius: "$medium" },
-    { borderRadius: "$large" },
-];
-/**
- * Automatically warms the cache with common styles.
- *
- * @param warmCacheFn - The warmCache function from Stoop instance
- * @param styles - Styles to warm (defaults to COMMON_UI_STYLES)
- * @returns Promise that resolves when warming is complete
- */
-export async function autoWarmCache(warmCacheFn, styles = COMMON_UI_STYLES) {
-    // Warm cache asynchronously to avoid blocking
-    return new Promise((resolve) => {
-        setTimeout(() => {
-            try {
-                warmCacheFn(styles);
-                resolve();
-            }
-            catch (error) {
-                // Silently fail - cache warming is not critical
-                console.warn("[Stoop] Cache warming failed:", error);
-                resolve();
-            }
-        }, 0);
-    });
-}
-/**
- * Automatically preloads a detected theme.
- *
- * @param preloadThemeFn - The preloadTheme function from Stoop instance
- * @param options - Theme detection options
- * @param ssr - Whether running in SSR context
- * @returns Promise that resolves when preloading is complete
- */
-export async function autoPreloadTheme(preloadThemeFn, options = {}, ssr = false) {
-    return new Promise((resolve) => {
-        setTimeout(() => {
-            try {
-                if (ssr) {
-                    const themeName = detectThemeForSSR(options);
-                    if (themeName && themeName !== options.default) {
-                        preloadThemeFn(themeName);
-                    }
-                    resolve({
-                        confidence: 0.3,
-                        source: "default",
-                        theme: themeName,
-                    });
-                }
-                else {
-                    const detection = detectTheme(options);
-                    if (detection.theme) {
-                        preloadThemeFn(detection.theme);
-                    }
-                    resolve(detection);
-                }
-            }
-            catch (error) {
-                console.warn("[Stoop] Theme preloading failed:", error);
-                resolve({
-                    confidence: 0.3,
-                    source: "default",
-                    theme: options.default || "light",
-                });
-            }
-        }, 0);
-    });
-}
-/**
- * Performs automatic preloading operations based on configuration.
- *
- * @param warmCacheFn - The warmCache function from Stoop instance
- * @param preloadThemeFn - The preloadTheme function from Stoop instance
- * @param options - Auto-preload options
- * @returns Promise that resolves with preload results
- */
-export async function autoPreload(warmCacheFn, preloadThemeFn, options = {}) {
-    const { commonStyles = COMMON_UI_STYLES, enableCacheWarm = true, enableThemePreload = true, ssr = false, themeDetection = {}, } = options;
-    const result = {
-        cacheWarmed: false,
-        errors: [],
-        themeDetection: { confidence: 0.3, source: "default", theme: "light" },
-        themePreloaded: false,
-    };
-    const operations = [];
-    // Auto-warm cache
-    if (enableCacheWarm && commonStyles.length > 0) {
-        operations.push(autoWarmCache(warmCacheFn, commonStyles)
-            .then(() => {
-            result.cacheWarmed = true;
-        })
-            .catch((error) => {
-            result.errors.push(`Cache warming failed: ${error instanceof Error ? error.message : String(error)}`);
-        }));
-    }
-    // Auto-preload theme
-    if (enableThemePreload) {
-        operations.push(autoPreloadTheme(preloadThemeFn, themeDetection, ssr)
-            .then((detection) => {
-            result.themeDetection = detection;
-            result.themePreloaded = true;
-        })
-            .catch((error) => {
-            result.errors.push(`Theme preloading failed: ${error instanceof Error ? error.message : String(error)}`);
-        }));
-    }
-    // Wait for all operations to complete
-    await Promise.allSettled(operations);
-    return result;
-}
-/**
- * Creates an auto-preloader with pre-configured options.
- *
- * @param warmCacheFn - The warmCache function from Stoop instance
- * @param preloadThemeFn - The preloadTheme function from Stoop instance
- * @param defaultOptions - Default auto-preload options
- * @returns Auto-preloader function
- */
-export function createAutoPreloader(warmCacheFn, preloadThemeFn, defaultOptions = {}) {
-    return (options = {}) => {
-        return autoPreload(warmCacheFn, preloadThemeFn, { ...defaultOptions, ...options });
-    };
-}