stoop 0.3.0 → 0.4.0

package/dist/inject.js

@@ -0,0 +1,308 @@
+/**
+ * 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.d.ts

@@ -4,11 +4,6 @@
  */
 import type { ComponentType, ElementType, JSX, ReactNode } from "react";
 import type { PolymorphicPropsWithRef } from "react-polymorphic-types";
-import type { createTheme } from "../api/create-theme";
-import type { createCSSFunction } from "../api/css";
-import type { createGlobalCSSFunction } from "../api/global-css";
-import type { createKeyframesFunction } from "../api/keyframes";
-import type { createStyledFunction } from "../api/styled";
 export type CSSPropertyValue = string | number;
 export interface StyledComponentRef {
     readonly __stoopClassName: string;
@@ -70,10 +65,12 @@ export interface StoopConfig {
     utils?: Record<string, UtilityFunction>;
     prefix?: string;
     themeMap?: Record<string, ThemeScale>;
+    globalCss?: CSS;
 }
 export type VariantKeys<T extends Variants> = keyof T;
+type ExtractVariantKeys<T> = T extends Record<infer K, CSS> ? K extends string | number | boolean ? K : T extends Record<string, CSS> ? string : never : T extends Record<string, CSS> ? keyof T : never;
 export type VariantPropsFromConfig<T extends Variants> = {
-    [K in VariantKeys<T>]?: keyof T[K] | boolean | number;
+    [K in VariantKeys<T>]?: ExtractVariantKeys<T[K]>;
 };
 type StyledOwnProps<VariantsConfig extends Variants> = StyledBaseProps & (VariantsConfig extends Record<string, never> ? {} : VariantPropsFromConfig<VariantsConfig>);
 export type StyledComponentProps<DefaultElement extends ElementType, VariantsConfig extends Variants = {}> = PolymorphicPropsWithRef<StyledOwnProps<VariantsConfig>, DefaultElement>;
@@ -88,6 +85,119 @@ export interface ThemeManagementContextValue {
     toggleTheme: () => void;
     availableThemes: readonly string[];
 }
+/**
+ * Server-side Stoop instance.
+ * 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;
+}
+/**
+ * Theme detection options for automatic theme selection.
+ */
+export interface ThemeDetectionOptions {
+    /** localStorage key to check for stored theme preference */
+    localStorage?: string;
+    /** Cookie name to check for stored theme preference */
+    cookie?: string;
+    /** Whether to check system color scheme preference */
+    systemPreference?: boolean;
+    /** Default theme name to fall back to */
+    default?: string;
+    /** Available themes map for validation */
+    themes?: Record<string, Theme>;
+}
+/**
+ * Result of theme detection.
+ */
+export interface ThemeDetectionResult {
+    /** Detected theme name */
+    theme: string;
+    /** Source of the theme detection */
+    source: "cookie" | "localStorage" | "system" | "default";
+    /** Confidence level (0-1) of the detection */
+    confidence: number;
+}
+/**
+ * Storage type enumeration.
+ */
+export type StorageType = "localStorage" | "cookie";
+/**
+ * Options for storage operations.
+ */
+export interface StorageOptions {
+    /** Storage type */
+    type?: StorageType;
+    /** Cookie max age in seconds (only for cookies) */
+    maxAge?: number;
+    /** Cookie path (only for cookies) */
+    path?: string;
+    /** Whether to use secure cookies (only for cookies) */
+    secure?: boolean;
+}
+/**
+ * Storage result with metadata.
+ */
+export interface StorageResult<T = string> {
+    /** The stored value */
+    value: T;
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Error message if operation failed */
+    error?: string;
+    /** Source of the value */
+    source?: StorageType;
+}
+/**
+ * Options for auto-preloading.
+ */
+export interface AutoPreloadOptions {
+    /** Theme detection options */
+    themeDetection?: ThemeDetectionOptions;
+    /** Common styles to warm the cache with */
+    commonStyles?: CSS[];
+    /** Whether to enable automatic theme preloading */
+    enableThemePreload?: boolean;
+    /** Whether to enable automatic cache warming */
+    enableCacheWarm?: boolean;
+    /** Whether to run in SSR context (limits available APIs) */
+    ssr?: boolean;
+}
+/**
+ * Result of auto-preloading operations.
+ */
+export interface AutoPreloadResult {
+    /** Detected theme information */
+    themeDetection: ThemeDetectionResult;
+    /** Whether cache was warmed */
+    cacheWarmed: boolean;
+    /** Whether theme was preloaded */
+    themePreloaded: boolean;
+    /** Any errors that occurred */
+    errors: string[];
+}
+/**
+ * Styled component type - the return type of styled()
+ */
+export type StyledComponent<DefaultElement extends ElementType, VariantsConfig extends Variants = {}> = ComponentType<StyledComponentProps<DefaultElement, VariantsConfig>> & {
+    selector: StyledComponentRef;
+};
+/**
+ * Styled function type - the main styled() function signature
+ */
+export interface StyledFunction {
+    <DefaultElement extends StylableElement, VariantsConfig extends Variants = {}>(defaultElement: DefaultElement, baseStyles?: CSS, variants?: VariantsConfig): StyledComponent<DefaultElement, VariantsConfig>;
+}
 export interface GetCssTextOptions {
     theme?: Theme;
     includeThemeVars?: boolean;
@@ -96,24 +206,49 @@ export interface ProviderProps {
     children: ReactNode;
     defaultTheme?: string;
     storageKey?: string;
+    cookieKey?: string;
     attribute?: string;
 }
+/**
+ * CSS function type
+ */
+export interface CSSFunction {
+    (styles: CSS): string;
+}
+/**
+ * Global CSS function type
+ */
+export interface GlobalCSSFunction {
+    (styles: CSS): () => void;
+}
+/**
+ * Keyframes function type
+ */
+export interface KeyframesFunction {
+    (keyframes: Record<string, CSS>): string;
+}
+/**
+ * Create theme function type
+ */
+export interface CreateThemeFunction {
+    (theme: Partial<DefaultTheme>): DefaultTheme;
+}
 /**
  * Stoop instance.
  * Includes all APIs: styled, Provider, useTheme, css, globalCss, keyframes, etc.
  */
 export interface StoopInstance {
-    styled: ReturnType<typeof createStyledFunction>;
-    css: ReturnType<typeof createCSSFunction>;
-    createTheme: ReturnType<typeof createTheme>;
-    globalCss: ReturnType<typeof createGlobalCSSFunction>;
-    keyframes: ReturnType<typeof createKeyframesFunction>;
+    styled: StyledFunction;
+    css: CSSFunction;
+    createTheme: CreateThemeFunction;
+    globalCss: GlobalCSSFunction;
+    keyframes: KeyframesFunction;
     theme: DefaultTheme;
     /**
      * Gets all generated 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)
+     * @param theme - Deprecated parameter, kept for backward compatibility but ignored
      * @returns CSS text string with theme variables and component styles
      */
     getCssText: (theme?: string | Theme) => string;

package/dist/types/react-polymorphic-types.d.ts

@@ -1,13 +1,24 @@
 /**
  * Type declaration for react-polymorphic-types to work around package.json exports issue.
+ * Properly extends native element props while preserving custom variant props.
  */
 
 declare module "react-polymorphic-types" {
   import type { ElementType, ComponentPropsWithRef, ComponentPropsWithoutRef } from "react";
 
+  /**
+   * Polymorphic props with ref support.
+   * Extends native element props while preserving custom props (like variants).
+   * Variant props take precedence over native props with the same name.
+   */
   export type PolymorphicPropsWithRef<OwnProps, DefaultElement extends ElementType> = OwnProps &
-    ComponentPropsWithRef<DefaultElement>;
+    Omit<ComponentPropsWithRef<DefaultElement>, keyof OwnProps>;
 
+  /**
+   * Polymorphic props without ref support.
+   * Extends native element props while preserving custom props (like variants).
+   * Variant props take precedence over native props with the same name.
+   */
   export type PolymorphicPropsWithoutRef<OwnProps, DefaultElement extends ElementType> = OwnProps &
-    ComponentPropsWithoutRef<DefaultElement>;
+    Omit<ComponentPropsWithoutRef<DefaultElement>, keyof OwnProps>;
 }

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

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