stoop 0.6.0 → 0.6.2

package/dist/core/compiler.js

@@ -0,0 +1,408 @@
+/**
+ * CSS compilation engine.
+ * Converts CSS objects to CSS strings and generates unique class names.
+ * Handles nested selectors, media queries, styled component targeting, and theme tokens.
+ */
+import { MAX_CSS_NESTING_DEPTH, STOOP_COMPONENT_SYMBOL } from "../constants";
+import { injectCSS } from "../inject";
+import { isValidCSSObject, applyUtilities, isStyledComponentRef } from "../utils/helpers";
+import { replaceThemeTokensWithVars } from "../utils/theme";
+import { escapeCSSValue, hash, sanitizeCSSSelector, sanitizeMediaQuery, sanitizePrefix, } from "../utils/theme-utils";
+import { classNameCache, cssStringCache } from "./cache";
+import { sanitizeCSSPropertyName } from "./stringify";
+/**
+ * Set of CSS properties that require length units for numeric values.
+ * These properties should have 'px' automatically appended to unitless numbers.
+ */
+const DIMENSIONAL_PROPERTIES = new Set([
+    "width",
+    "height",
+    "min-width",
+    "min-height",
+    "max-width",
+    "max-height",
+    "top",
+    "right",
+    "bottom",
+    "left",
+    "margin",
+    "margin-top",
+    "margin-right",
+    "margin-bottom",
+    "margin-left",
+    "padding",
+    "padding-top",
+    "padding-right",
+    "padding-bottom",
+    "padding-left",
+    "border-width",
+    "border-top-width",
+    "border-right-width",
+    "border-bottom-width",
+    "border-left-width",
+    "border-radius",
+    "border-top-left-radius",
+    "border-top-right-radius",
+    "border-bottom-left-radius",
+    "border-bottom-right-radius",
+    "font-size",
+    "letter-spacing",
+    "word-spacing",
+    "text-indent",
+    "flex-basis",
+    "gap",
+    "row-gap",
+    "column-gap",
+    "grid-template-rows",
+    "grid-template-columns",
+    "grid-auto-rows",
+    "grid-auto-columns",
+    "perspective",
+    "outline-width",
+    "outline-offset",
+    "clip",
+    "vertical-align",
+    "object-position",
+    "background-position",
+    "background-size",
+    "mask-position",
+    "mask-size",
+    "scroll-margin",
+    "scroll-padding",
+    "shape-margin",
+]);
+/**
+ * Checks if a CSS property requires length units for numeric values.
+ *
+ * @param property - CSS property name (in kebab-case)
+ * @returns True if the property requires units
+ */
+function requiresUnit(property) {
+    return DIMENSIONAL_PROPERTIES.has(property);
+}
+/**
+ * Normalizes a CSS value by adding 'px' unit to unitless numeric values
+ * for properties that require units.
+ *
+ * @param property - CSS property name (in kebab-case)
+ * @param value - CSS value (string or number)
+ * @returns Normalized value string
+ */
+function normalizeCSSValue(property, value) {
+    if (typeof value === "string") {
+        // If it's already a string, check if it's a unitless number
+        // Only add px if it's a pure number and the property requires units
+        if (requiresUnit(property) && /^-?\d+\.?\d*$/.test(value.trim())) {
+            return `${value}px`;
+        }
+        return value;
+    }
+    // For numeric values, add px if the property requires units
+    if (typeof value === "number" && requiresUnit(property)) {
+        return `${value}px`;
+    }
+    return String(value);
+}
+/**
+ * Checks if a key/value pair represents a styled component reference.
+ *
+ * @param key - Property key to check
+ * @param value - Property value to check
+ * @returns True if key/value represents a styled component reference
+ */
+function isStyledComponentKey(key, value) {
+    if (typeof key === "symbol" && key === STOOP_COMPONENT_SYMBOL) {
+        return true;
+    }
+    if (isStyledComponentRef(value)) {
+        return true;
+    }
+    if (typeof key === "string" && key.startsWith("__STOOP_COMPONENT_")) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Extracts the class name from a styled component reference.
+ *
+ * @param key - Property key
+ * @param value - Property value
+ * @returns Extracted class name or empty string
+ */
+function getClassNameFromKeyOrValue(key, value) {
+    if (typeof value === "object" &&
+        value !== null &&
+        "__stoopClassName" in value &&
+        typeof value.__stoopClassName === "string") {
+        return value.__stoopClassName;
+    }
+    if (typeof key === "string" && key.startsWith("__STOOP_COMPONENT_")) {
+        return key.replace("__STOOP_COMPONENT_", "");
+    }
+    return "";
+}
+/**
+ * Converts a CSS object to a CSS string with proper nesting and selectors.
+ * Handles pseudo-selectors, media queries, combinators, and styled component targeting.
+ *
+ * @param obj - CSS object to convert
+ * @param selector - Current selector context
+ * @param depth - Current nesting depth
+ * @param media - Media query breakpoints
+ * @returns CSS string
+ */
+export function cssObjectToString(obj, selector = "", depth = 0, media) {
+    if (!obj || typeof obj !== "object") {
+        return "";
+    }
+    if (depth > MAX_CSS_NESTING_DEPTH) {
+        return "";
+    }
+    const cssProperties = [];
+    const nestedRulesList = [];
+    // Only sort keys when selector is empty (for hashing/deterministic output)
+    // When selector is provided, we don't need deterministic ordering for performance
+    const keys = selector === "" ? Object.keys(obj).sort() : Object.keys(obj);
+    for (const key of keys) {
+        const value = obj[key];
+        if (isStyledComponentKey(key, value)) {
+            const componentClassName = getClassNameFromKeyOrValue(key, value);
+            if (!componentClassName) {
+                continue;
+            }
+            const sanitizedClassName = sanitizeCSSSelector(componentClassName);
+            if (!sanitizedClassName) {
+                continue;
+            }
+            const componentSelector = selector
+                ? `${selector} .${sanitizedClassName}`
+                : `.${sanitizedClassName}`;
+            const nestedCss = isValidCSSObject(value)
+                ? cssObjectToString(value, componentSelector, depth + 1, media)
+                : "";
+            if (nestedCss) {
+                nestedRulesList.push(nestedCss);
+            }
+            continue;
+        }
+        if (isValidCSSObject(value)) {
+            if (media && key in media) {
+                const mediaQuery = sanitizeMediaQuery(media[key]);
+                if (mediaQuery) {
+                    const nestedCss = cssObjectToString(value, selector, depth + 1, media);
+                    if (nestedCss) {
+                        nestedRulesList.push(`${mediaQuery} { ${nestedCss} }`);
+                    }
+                }
+            }
+            else if (key.startsWith("@")) {
+                const sanitizedKey = sanitizeCSSSelector(key);
+                if (sanitizedKey) {
+                    const nestedCss = cssObjectToString(value, selector, depth + 1, media);
+                    if (nestedCss) {
+                        nestedRulesList.push(`${sanitizedKey} { ${nestedCss} }`);
+                    }
+                }
+            }
+            else if (key.includes("&")) {
+                const sanitizedKey = sanitizeCSSSelector(key);
+                if (sanitizedKey) {
+                    const parts = sanitizedKey.split("&");
+                    // Handle comma-separated selectors: split by comma, apply & replacement to each part, then rejoin
+                    if (selector.includes(",")) {
+                        const selectorParts = selector.split(",").map((s) => s.trim());
+                        const nestedSelectors = selectorParts.map((sel) => parts.join(sel));
+                        const nestedSelector = nestedSelectors.join(", ");
+                        const nestedCss = cssObjectToString(value, nestedSelector, depth + 1, media);
+                        if (nestedCss) {
+                            nestedRulesList.push(nestedCss);
+                        }
+                    }
+                    else {
+                        // Single selector: simple & replacement
+                        const nestedSelector = parts.join(selector);
+                        const nestedCss = cssObjectToString(value, nestedSelector, depth + 1, media);
+                        if (nestedCss) {
+                            nestedRulesList.push(nestedCss);
+                        }
+                    }
+                }
+            }
+            else if (key.startsWith(":")) {
+                const sanitizedKey = sanitizeCSSSelector(key);
+                if (sanitizedKey) {
+                    const nestedSelector = `${selector}${sanitizedKey}`;
+                    const nestedCss = cssObjectToString(value, nestedSelector, depth + 1, media);
+                    if (nestedCss) {
+                        nestedRulesList.push(nestedCss);
+                    }
+                }
+            }
+            else if (key.includes(",")) {
+                // Handle comma-separated selectors (e.g., "a, a:visited")
+                // Split by comma, sanitize each part, then rejoin
+                // This must come before the space/combinator check since comma-separated selectors can contain spaces
+                const parts = key.split(",").map((part) => part.trim());
+                const sanitizedParts = parts
+                    .map((part) => sanitizeCSSSelector(part))
+                    .filter((part) => part);
+                if (sanitizedParts.length > 0) {
+                    const nestedSelector = sanitizedParts.join(", ");
+                    const nestedCss = cssObjectToString(value, nestedSelector, depth + 1, media);
+                    if (nestedCss) {
+                        nestedRulesList.push(nestedCss);
+                    }
+                }
+            }
+            else if (key.includes(" ") || key.includes(">") || key.includes("+") || key.includes("~")) {
+                const sanitizedKey = sanitizeCSSSelector(key);
+                if (sanitizedKey) {
+                    const startsWithCombinator = /^[\s>+~]/.test(sanitizedKey.trim());
+                    const nestedSelector = startsWithCombinator
+                        ? `${selector}${sanitizedKey}`
+                        : `${selector} ${sanitizedKey}`;
+                    const nestedCss = cssObjectToString(value, nestedSelector, depth + 1, media);
+                    if (nestedCss) {
+                        nestedRulesList.push(nestedCss);
+                    }
+                }
+            }
+            else {
+                const sanitizedKey = sanitizeCSSSelector(key);
+                if (sanitizedKey) {
+                    const nestedSelector = selector ? `${selector} ${sanitizedKey}` : sanitizedKey;
+                    const nestedCss = cssObjectToString(value, nestedSelector, depth + 1, media);
+                    if (nestedCss) {
+                        nestedRulesList.push(nestedCss);
+                    }
+                }
+            }
+        }
+        else if (value !== undefined) {
+            const property = sanitizeCSSPropertyName(key);
+            if (property && (typeof value === "string" || typeof value === "number")) {
+                const normalizedValue = normalizeCSSValue(property, value);
+                // Special handling for content property with empty string
+                // CSS requires content: ""; not content: ;
+                if (property === "content" && normalizedValue === "") {
+                    cssProperties.push(`${property}: "";`);
+                }
+                else {
+                    const escapedValue = escapeCSSValue(normalizedValue);
+                    cssProperties.push(`${property}: ${escapedValue};`);
+                }
+            }
+        }
+    }
+    const parts = [];
+    if (cssProperties.length > 0) {
+        parts.push(`${selector} { ${cssProperties.join(" ")} }`);
+    }
+    parts.push(...nestedRulesList);
+    return parts.join("");
+}
+/**
+ * Extracts CSS properties string from a CSS object for hashing.
+ * Only processes top-level properties (no nested rules, media queries, etc.).
+ * This is optimized for simple CSS objects without nesting.
+ *
+ * @param obj - CSS object to process
+ * @param media - Optional media query breakpoints
+ * @returns CSS properties string without selector wrapper, or empty string if complex
+ */
+function extractCSSPropertiesForHash(obj, media) {
+    if (!obj || typeof obj !== "object") {
+        return "";
+    }
+    const cssProperties = [];
+    const keys = Object.keys(obj).sort(); // Sort for deterministic hashing
+    for (const key of keys) {
+        const value = obj[key];
+        // Check for nested rules - if found, we need full stringification
+        if (isValidCSSObject(value)) {
+            return ""; // Complex CSS, use full stringification
+        }
+        // Check for media queries
+        if (media && key in media) {
+            return ""; // Has media queries, use full stringification
+        }
+        // Check for pseudo-selectors, combinators, etc.
+        if (key.startsWith("@") ||
+            key.includes("&") ||
+            key.startsWith(":") ||
+            key.includes(" ") ||
+            key.includes(">") ||
+            key.includes("+") ||
+            key.includes("~")) {
+            return ""; // Complex selector, use full stringification
+        }
+        if (value !== undefined && !isStyledComponentKey(key, value)) {
+            const property = sanitizeCSSPropertyName(key);
+            if (property && (typeof value === "string" || typeof value === "number")) {
+                const normalizedValue = normalizeCSSValue(property, value);
+                // Special handling for content property with empty string
+                // CSS requires content: ""; not content: ;
+                if (property === "content" && normalizedValue === "") {
+                    cssProperties.push(`${property}: "";`);
+                }
+                else {
+                    const escapedValue = escapeCSSValue(normalizedValue);
+                    cssProperties.push(`${property}: ${escapedValue};`);
+                }
+            }
+        }
+    }
+    return cssProperties.join(" ");
+}
+/**
+ * Compiles CSS objects into CSS strings and generates unique class names.
+ * Handles nested selectors, media queries, styled component targeting, and theme tokens.
+ *
+ * @param styles - CSS object to compile
+ * @param currentTheme - Theme for token resolution
+ * @param prefix - Optional prefix for generated class names
+ * @param media - Optional media query breakpoints
+ * @param utils - Optional utility functions
+ * @param themeMap - Optional theme scale mappings
+ * @returns Generated class name
+ */
+export function compileCSS(styles, currentTheme, prefix = "stoop", media, utils, themeMap) {
+    const sanitizedPrefix = sanitizePrefix(prefix);
+    const stylesWithUtils = applyUtilities(styles, utils);
+    const themedStyles = replaceThemeTokensWithVars(stylesWithUtils, currentTheme, themeMap);
+    // Optimize: Try to extract properties for hash first (fast path for simple CSS)
+    const propertiesString = extractCSSPropertiesForHash(themedStyles, media);
+    let cssString;
+    let stylesHash;
+    if (propertiesString) {
+        // Fast path: simple CSS without nested rules - use properties string for hash
+        cssString = propertiesString;
+        stylesHash = hash(cssString);
+    }
+    else {
+        // Fallback: complex CSS with nested rules - need full stringification
+        cssString = cssObjectToString(themedStyles, "", 0, media);
+        stylesHash = hash(cssString);
+    }
+    const className = sanitizedPrefix ? `${sanitizedPrefix}-${stylesHash}` : `css-${stylesHash}`;
+    const cacheKey = `${sanitizedPrefix}:${className}`;
+    const cachedCSS = cssStringCache.get(cacheKey);
+    if (cachedCSS) {
+        injectCSS(cachedCSS, sanitizedPrefix, cacheKey);
+        return className;
+    }
+    // Generate final CSS with className selector
+    let fullCSS;
+    if (propertiesString) {
+        // Fast path: wrap properties with selector
+        fullCSS = `.${className} { ${propertiesString} }`;
+    }
+    else {
+        // Fallback: full stringification with selector
+        fullCSS = cssObjectToString(themedStyles, `.${className}`, 0, media);
+    }
+    cssStringCache.set(cacheKey, fullCSS);
+    classNameCache.set(cacheKey, className);
+    injectCSS(fullCSS, sanitizedPrefix, cacheKey);
+    return className;
+}

package/dist/core/stringify.js

@@ -0,0 +1,150 @@
+/**
+ * CSS property name stringification utilities.
+ * Handles conversion of camelCase CSS property names to kebab-case,
+ * including proper vendor prefix detection and normalization.
+ */
+import { SANITIZE_CACHE_SIZE_LIMIT } from "../constants";
+import { LRUCache } from "./cache";
+const propertyNameCache = new LRUCache(SANITIZE_CACHE_SIZE_LIMIT);
+/**
+ * Converts a camelCase string to kebab-case.
+ *
+ * @param str - String to convert
+ * @returns Kebab-case string
+ */
+function toKebabCase(str) {
+    return str.replace(/([A-Z])/g, "-$1").toLowerCase();
+}
+/**
+ * Normalizes a property name for vendor prefix detection.
+ * Handles all-caps and mixed-case scenarios.
+ *
+ * @param property - Property name to normalize
+ * @returns Normalized property name
+ */
+function normalizePropertyName(property) {
+    if (property === property.toUpperCase() && property.length > 1) {
+        return property.charAt(0) + property.slice(1).toLowerCase();
+    }
+    return property;
+}
+/**
+ * Converts the rest of a property name (after vendor prefix) to kebab-case.
+ * Ensures the first character is lowercase before conversion to avoid double dashes.
+ *
+ * @param rest - The property name part after the vendor prefix
+ * @returns Kebab-case string
+ */
+function restToKebabCase(rest) {
+    if (!rest) {
+        return "";
+    }
+    return (rest.charAt(0).toLowerCase() +
+        rest
+            .slice(1)
+            .replace(/([A-Z])/g, "-$1")
+            .toLowerCase());
+}
+/**
+ * Sanitizes CSS property names to prevent injection attacks.
+ * Handles vendor prefixes, camelCase conversion, and edge cases.
+ *
+ * Vendor prefix patterns handled:
+ * - Moz* → -moz-*
+ * - Webkit* → -webkit-*
+ * - ms* → -ms-*
+ * - O* → -o-*
+ *
+ * @param propertyName - Property name to sanitize
+ * @returns Sanitized property name
+ */
+export function sanitizeCSSPropertyName(propertyName) {
+    if (!propertyName || typeof propertyName !== "string") {
+        return "";
+    }
+    const cached = propertyNameCache.get(propertyName);
+    if (cached !== undefined) {
+        return cached;
+    }
+    if (/^-[a-z]+-/.test(propertyName)) {
+        propertyNameCache.set(propertyName, propertyName);
+        return propertyName;
+    }
+    const normalized = normalizePropertyName(propertyName);
+    // Mozilla prefix (case-insensitive): Moz*, moz*, MOZ* → -moz-*
+    if (/^[Mm]oz/i.test(normalized)) {
+        if (normalized.length === 3 || normalized.toLowerCase() === "moz") {
+            const result = "-moz";
+            propertyNameCache.set(propertyName, result);
+            return result;
+        }
+        const match = normalized.match(/^[Mm]oz(.+)$/i);
+        if (match && match[1]) {
+            const [, rest] = match;
+            const kebab = restToKebabCase(rest);
+            if (kebab) {
+                const result = `-moz-${kebab}`;
+                propertyNameCache.set(propertyName, result);
+                return result;
+            }
+        }
+    }
+    // WebKit prefix (case-insensitive): Webkit*, webkit*, WEBKIT* → -webkit-*
+    if (/^[Ww]ebkit/i.test(normalized)) {
+        if (normalized.length === 6 || normalized.toLowerCase() === "webkit") {
+            const result = "-webkit";
+            propertyNameCache.set(propertyName, result);
+            return result;
+        }
+        const match = normalized.match(/^[Ww]ebkit(.+)$/i);
+        if (match && match[1]) {
+            const [, rest] = match;
+            const kebab = restToKebabCase(rest);
+            if (kebab) {
+                const result = `-webkit-${kebab}`;
+                propertyNameCache.set(propertyName, result);
+                return result;
+            }
+        }
+    }
+    // Microsoft prefix (case-insensitive): ms*, Ms*, MS* → -ms-*
+    if (/^[Mm]s/i.test(normalized)) {
+        if (normalized.length === 2 || normalized.toLowerCase() === "ms") {
+            const result = "-ms";
+            propertyNameCache.set(propertyName, result);
+            return result;
+        }
+        const match = normalized.match(/^[Mm]s(.+)$/i);
+        if (match && match[1]) {
+            const [, rest] = match;
+            const kebab = restToKebabCase(rest);
+            if (kebab) {
+                const result = `-ms-${kebab}`;
+                propertyNameCache.set(propertyName, result);
+                return result;
+            }
+        }
+    }
+    // Opera prefix (single uppercase O): O* → -o-* or just O → -o
+    if (/^O/i.test(normalized)) {
+        if (normalized.length === 1 || normalized.toLowerCase() === "o") {
+            const result = "-o";
+            propertyNameCache.set(propertyName, result);
+            return result;
+        }
+        if (/^O[A-Z]/.test(normalized)) {
+            const rest = normalized.substring(1);
+            const kebab = restToKebabCase(rest);
+            if (kebab) {
+                const result = `-o-${kebab}`;
+                propertyNameCache.set(propertyName, result);
+                return result;
+            }
+        }
+    }
+    const kebab = toKebabCase(normalized);
+    const sanitized = kebab.replace(/[^a-zA-Z0-9-]/g, "").replace(/^-+|-+$/g, "");
+    const result = sanitized.replace(/^\d+/, "") || "";
+    propertyNameCache.set(propertyName, result);
+    return result;
+}

package/dist/core/theme-manager.js

@@ -0,0 +1,97 @@
+/**
+ * Theme variable management.
+ * Updates CSS custom properties when theme changes and merges themes with the default theme.
+ */
+import { injectAllThemeVariables } from "../inject";
+import { isBrowser } from "../utils/helpers";
+import { generateAllThemeVariables, themesAreEqual } from "../utils/theme";
+const defaultThemes = new Map();
+/**
+ * Registers the default theme for a given prefix.
+ * Called automatically by createStoop.
+ *
+ * @param theme - Default theme from createStoop
+ * @param prefix - Optional prefix for theme scoping
+ */
+export function registerDefaultTheme(theme, prefix = "stoop") {
+    const sanitizedPrefix = prefix || "";
+    defaultThemes.set(sanitizedPrefix, theme);
+}
+/**
+ * Gets the default theme for a given prefix.
+ *
+ * @param prefix - Optional prefix for theme scoping
+ * @returns Default theme or null if not registered
+ */
+export function getDefaultTheme(prefix = "stoop") {
+    const sanitizedPrefix = prefix || "";
+    return defaultThemes.get(sanitizedPrefix) || null;
+}
+/**
+ * Merges source theme into target theme, handling nested objects.
+ *
+ * @param target - Target theme to merge into
+ * @param source - Source theme to merge from
+ * @returns Merged theme
+ */
+export function mergeThemes(target, source) {
+    const merged = { ...target };
+    const sourceKeys = Object.keys(source);
+    for (const key of sourceKeys) {
+        if (key === "media") {
+            continue;
+        }
+        const sourceValue = source[key];
+        const targetValue = target[key];
+        if (sourceValue &&
+            typeof sourceValue === "object" &&
+            !Array.isArray(sourceValue) &&
+            targetValue &&
+            typeof targetValue === "object" &&
+            !Array.isArray(targetValue)) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            merged[key] = { ...targetValue, ...sourceValue };
+        }
+        else if (sourceValue !== undefined) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            merged[key] = sourceValue;
+        }
+    }
+    return merged;
+}
+/**
+ * Merges a theme with the default theme, ensuring all themes extend the default theme.
+ *
+ * @param theme - Theme to merge
+ * @param prefix - Optional prefix for theme scoping
+ * @returns Merged theme (or original if it's the default theme)
+ */
+export function mergeWithDefaultTheme(theme, prefix = "stoop") {
+    const defaultTheme = getDefaultTheme(prefix);
+    if (!defaultTheme) {
+        return theme;
+    }
+    if (themesAreEqual(theme, defaultTheme)) {
+        return theme;
+    }
+    return mergeThemes(defaultTheme, theme);
+}
+/**
+ * Injects CSS variables for all themes using attribute selectors.
+ * All themes are available simultaneously, with theme switching handled by changing the data-theme attribute.
+ *
+ * @param themes - Map of theme names to theme objects
+ * @param prefix - Optional prefix for CSS variable names
+ * @param attribute - Attribute name for theme selection (defaults to 'data-theme')
+ */
+export function injectAllThemes(themes, prefix = "stoop", attribute = "data-theme") {
+    if (!isBrowser()) {
+        return;
+    }
+    const mergedThemes = {};
+    for (const [themeName, theme] of Object.entries(themes)) {
+        mergedThemes[themeName] = mergeWithDefaultTheme(theme, prefix);
+    }
+    const allThemeVars = generateAllThemeVariables(mergedThemes, prefix, attribute);
+    injectAllThemeVariables(allThemeVars, prefix);
+}

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

@@ -1,7 +1,7 @@
 /**
  * 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.
+ * SERVER-SAFE: No "use client" dependencies, no React imports.
+ * This file is used by both client (create-stoop.ts) and server (create-stoop-ssr.ts) entry points.
  */
 import type { CSS, StoopConfig, Theme, ThemeScale } from "./types";
 import { createCSSFunction, createKeyframesFunction, createGlobalCSSFunction } from "./api/core-api";