stoop 0.2.1 → 0.4.0

package/dist/utils/theme-utils.js

@@ -0,0 +1,353 @@
+/**
+ * Theme-related string utilities and property mapping.
+ * Provides hashing, CSS sanitization, and theme scale mapping for property-aware token resolution.
+ */
+import { DEFAULT_THEME_MAP, SANITIZE_CACHE_SIZE_LIMIT } from "../constants";
+// ============================================================================
+// String Utilities
+// ============================================================================
+import { LRUCache } from "../core/cache";
+let cachedRootRegex = null;
+const selectorCache = new LRUCache(SANITIZE_CACHE_SIZE_LIMIT);
+const propertyNameCache = new LRUCache(SANITIZE_CACHE_SIZE_LIMIT);
+const sanitizeClassNameCache = new LRUCache(SANITIZE_CACHE_SIZE_LIMIT);
+const variableNameCache = new LRUCache(SANITIZE_CACHE_SIZE_LIMIT);
+/**
+ * Generates a hash string from an input string using FNV-1a algorithm.
+ * Includes string length to reduce collision probability.
+ *
+ * @param str - String to hash
+ * @returns Hashed string
+ */
+export function hash(str) {
+    const FNV_OFFSET_BASIS = 2166136261;
+    const FNV_PRIME = 16777619;
+    let hash = FNV_OFFSET_BASIS;
+    for (let i = 0; i < str.length; i++) {
+        hash ^= str.charCodeAt(i);
+        hash = Math.imul(hash, FNV_PRIME);
+    }
+    hash ^= str.length;
+    return (hash >>> 0).toString(36);
+}
+/**
+ * Generates a hash string from an object by stringifying it.
+ *
+ * @param obj - Object to hash
+ * @returns Hashed string
+ */
+export function hashObject(obj) {
+    try {
+        return hash(JSON.stringify(obj));
+    }
+    catch {
+        return hash(String(obj));
+    }
+}
+/**
+ * Converts a camelCase string to kebab-case.
+ *
+ * @param str - String to convert
+ * @returns Kebab-case string
+ */
+export function toKebabCase(str) {
+    return str.replace(/([A-Z])/g, "-$1").toLowerCase();
+}
+/**
+ * Internal function to escape CSS values with optional brace escaping.
+ *
+ * @param value - Value to escape
+ * @param escapeBraces - Whether to escape curly braces
+ * @returns Escaped value string
+ */
+function escapeCSSValueInternal(value, escapeBraces = false) {
+    const str = String(value);
+    let result = str
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, '\\"')
+        .replace(/'/g, "\\'")
+        .replace(/;/g, "\\;")
+        .replace(/\n/g, "\\A ")
+        .replace(/\r/g, "")
+        .replace(/\f/g, "\\C ");
+    if (escapeBraces) {
+        result = result.replace(/\{/g, "\\7B ").replace(/\}/g, "\\7D ");
+    }
+    return result;
+}
+/**
+ * Escapes CSS property values to prevent injection attacks.
+ * Escapes quotes, semicolons, and other special characters.
+ *
+ * @param value - Value to escape
+ * @returns Escaped value string
+ */
+export function escapeCSSValue(value) {
+    return escapeCSSValueInternal(value, false);
+}
+/**
+ * Validates and sanitizes CSS selectors to prevent injection attacks.
+ * Only allows safe selector characters. Returns empty string for invalid selectors.
+ * Uses memoization for performance.
+ *
+ * @param selector - Selector to sanitize
+ * @returns Sanitized selector string or empty string if invalid
+ */
+export function sanitizeCSSSelector(selector) {
+    const cached = selectorCache.get(selector);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const sanitized = selector.replace(/[^a-zA-Z0-9\s\-_>+~:.#[\]&@()]/g, "");
+    const result = !sanitized.trim() || /^[>+~:.#[\]&@()\s]+$/.test(sanitized) ? "" : sanitized;
+    selectorCache.set(selector, result);
+    return result;
+}
+/**
+ * Validates and sanitizes CSS variable names to prevent injection attacks.
+ * CSS custom properties must start with -- and contain only valid characters.
+ * Uses memoization for performance.
+ *
+ * @param name - Variable name to sanitize
+ * @returns Sanitized variable name
+ */
+export function sanitizeCSSVariableName(name) {
+    const cached = variableNameCache.get(name);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const sanitized = name.replace(/[^a-zA-Z0-9-_]/g, "-");
+    const cleaned = sanitized.replace(/^[\d-]+/, "").replace(/^-+/, "");
+    const result = cleaned || "invalid";
+    variableNameCache.set(name, result);
+    return result;
+}
+/**
+ * Escapes CSS variable values to prevent injection attacks.
+ *
+ * @param value - Value to escape
+ * @returns Escaped value string
+ */
+export function escapeCSSVariableValue(value) {
+    return escapeCSSValueInternal(value, true);
+}
+/**
+ * Sanitizes prefix for use in CSS selectors and class names.
+ * Only allows alphanumeric characters, hyphens, and underscores.
+ * Defaults to "stoop" if prefix is empty or becomes empty after sanitization.
+ *
+ * @param prefix - Prefix to sanitize
+ * @returns Sanitized prefix string (never empty, defaults to "stoop")
+ */
+export function sanitizePrefix(prefix) {
+    if (!prefix) {
+        return "stoop";
+    }
+    const sanitized = prefix.replace(/[^a-zA-Z0-9-_]/g, "");
+    const cleaned = sanitized.replace(/^[\d-]+/, "").replace(/^-+/, "");
+    // Return "stoop" as default if sanitization results in empty string
+    return cleaned || "stoop";
+}
+/**
+ * Sanitizes media query strings to prevent injection attacks.
+ * Only allows safe characters for media queries.
+ *
+ * @param mediaQuery - Media query string to sanitize
+ * @returns Sanitized media query string or empty string if invalid
+ */
+export function sanitizeMediaQuery(mediaQuery) {
+    if (!mediaQuery || typeof mediaQuery !== "string") {
+        return "";
+    }
+    const sanitized = mediaQuery.replace(/[^a-zA-Z0-9\s():,<>=\-@]/g, "");
+    if (!sanitized.trim() || !/[a-zA-Z]/.test(sanitized)) {
+        return "";
+    }
+    return sanitized;
+}
+/**
+ * Sanitizes CSS class names to prevent injection attacks.
+ * Only allows valid CSS class name characters.
+ * Uses memoization for performance.
+ *
+ * @param className - Class name(s) to sanitize
+ * @returns Sanitized class name string
+ */
+export function sanitizeClassName(className) {
+    if (!className || typeof className !== "string") {
+        return "";
+    }
+    const cached = sanitizeClassNameCache.get(className);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const classes = className.trim().split(/\s+/);
+    const sanitizedClasses = [];
+    for (const cls of classes) {
+        if (!cls) {
+            continue;
+        }
+        const sanitized = cls.replace(/[^a-zA-Z0-9-_]/g, "");
+        const cleaned = sanitized.replace(/^\d+/, "");
+        if (cleaned && /^[a-zA-Z-_]/.test(cleaned)) {
+            sanitizedClasses.push(cleaned);
+        }
+    }
+    const result = sanitizedClasses.join(" ");
+    sanitizeClassNameCache.set(className, result);
+    return result;
+}
+/**
+ * Sanitizes CSS property names to prevent injection attacks.
+ * Uses memoization for performance.
+ *
+ * @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;
+    }
+    const kebab = toKebabCase(propertyName);
+    const sanitized = kebab.replace(/[^a-zA-Z0-9-]/g, "").replace(/^-+|-+$/g, "");
+    const result = sanitized.replace(/^\d+/, "") || "";
+    propertyNameCache.set(propertyName, result);
+    return result;
+}
+/**
+ * Validates keyframe percentage keys (e.g., "0%", "50%", "from", "to").
+ *
+ * @param key - Keyframe key to validate
+ * @returns True if key is valid
+ */
+export function validateKeyframeKey(key) {
+    if (!key || typeof key !== "string") {
+        return false;
+    }
+    if (key === "from" || key === "to") {
+        return true;
+    }
+    const percentageMatch = /^\d+(\.\d+)?%$/.test(key);
+    if (percentageMatch) {
+        const num = parseFloat(key);
+        return num >= 0 && num <= 100;
+    }
+    return false;
+}
+/**
+ * Gets a pre-compiled regex for matching :root CSS selector blocks.
+ * Uses caching for performance.
+ *
+ * @param prefix - Optional prefix (unused, kept for API compatibility)
+ * @returns RegExp for matching :root selector blocks
+ */
+export function getRootRegex(prefix = "") {
+    if (!cachedRootRegex) {
+        const rootSelector = ":root";
+        const escapedSelector = rootSelector.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        // Match :root block - use greedy match to handle nested braces (e.g., calc())
+        // Since theme vars should only have one :root block, greedy matching is safe
+        // Greedy matching ensures we capture the entire :root block, including nested functions
+        cachedRootRegex = new RegExp(`${escapedSelector}\\s*\\{[\\s\\S]*\\}`);
+    }
+    return cachedRootRegex;
+}
+// ============================================================================
+// Theme Map Utilities
+// ============================================================================
+/**
+ * Auto-detects theme scale from CSS property name using pattern matching.
+ * Used as fallback when property is not in DEFAULT_THEME_MAP.
+ *
+ * @param property - CSS property name
+ * @returns Theme scale name or undefined if no pattern matches
+ */
+export function autoDetectScale(property) {
+    // Color properties
+    if (property.includes("Color") ||
+        property === "fill" ||
+        property === "stroke" ||
+        property === "accentColor" ||
+        property === "caretColor" ||
+        property === "border" ||
+        property === "outline" ||
+        (property.includes("background") && !property.includes("Size") && !property.includes("Image"))) {
+        return "colors";
+    }
+    // Spacing properties
+    if (/^(margin|padding|gap|inset|top|right|bottom|left|rowGap|columnGap|gridGap|gridRowGap|gridColumnGap)/.test(property) ||
+        property.includes("Block") ||
+        property.includes("Inline")) {
+        return "space";
+    }
+    // Size properties
+    if (/(width|height|size|basis)$/i.test(property) ||
+        property.includes("BlockSize") ||
+        property.includes("InlineSize")) {
+        return "sizes";
+    }
+    // Typography: Font Size
+    if (property === "fontSize" || (property === "font" && !property.includes("Family"))) {
+        return "fontSizes";
+    }
+    // Typography: Font Family
+    if (property === "fontFamily" || property.includes("FontFamily")) {
+        return "fonts";
+    }
+    // Typography: Font Weight
+    if (property === "fontWeight" || property.includes("FontWeight")) {
+        return "fontWeights";
+    }
+    // Typography: Letter Spacing
+    if (property === "letterSpacing" || property.includes("LetterSpacing")) {
+        return "letterSpacings";
+    }
+    // Border Radius
+    if (property.includes("Radius") || property.includes("radius")) {
+        return "radii";
+    }
+    // Shadows
+    if (property.includes("Shadow") ||
+        property.includes("shadow") ||
+        property === "filter" ||
+        property === "backdropFilter") {
+        return "shadows";
+    }
+    // Z-Index
+    if (property === "zIndex" || property.includes("ZIndex") || property.includes("z-index")) {
+        return "zIndices";
+    }
+    // Opacity
+    if (property === "opacity" || property.includes("Opacity")) {
+        return "opacities";
+    }
+    // Transitions and animations
+    if (property.startsWith("transition") ||
+        property.startsWith("animation") ||
+        property.includes("Transition") ||
+        property.includes("Animation")) {
+        return "transitions";
+    }
+    return undefined;
+}
+/**
+ * Gets the theme scale for a CSS property.
+ * Checks user themeMap first, then default themeMap, then pattern matching.
+ *
+ * @param property - CSS property name
+ * @param userThemeMap - Optional user-provided themeMap override
+ * @returns Theme scale name or undefined if no mapping found
+ */
+export function getScaleForProperty(property, userThemeMap) {
+    if (userThemeMap && property in userThemeMap) {
+        return userThemeMap[property];
+    }
+    if (property in DEFAULT_THEME_MAP) {
+        return DEFAULT_THEME_MAP[property];
+    }
+    return autoDetectScale(property);
+}

package/dist/utils/theme.d.ts

@@ -5,12 +5,12 @@
  */
 import type { CSS, Theme, ThemeScale } from "../types";
 /**
- * Compares two themes for equality by structure and values.
- * Excludes 'media' property from comparison since it's not a CSS variable scale.
+ * Compares two themes for structural and value equality.
+ * Excludes 'media' property from comparison.
  *
  * @param theme1 - First theme to compare
  * @param theme2 - Second theme to compare
- * @returns True if themes are equal, false otherwise
+ * @returns True if themes are equal
  */
 export declare function themesAreEqual(theme1: Theme | null, theme2: Theme | null): boolean;
 /**
@@ -28,9 +28,21 @@ export declare function tokenToCSSVar(token: string, theme?: Theme, property?: s
  *
  * @param theme - Theme object to convert to CSS variables
  * @param prefix - Optional prefix for CSS variable names
- * @returns CSS string with :root selector and CSS variables
+ * @param attributeSelector - Optional attribute selector (e.g., '[data-theme="light"]'). Defaults to ':root'
+ * @returns CSS string with selector and CSS variables
  */
-export declare function generateCSSVariables(theme: Theme, prefix?: string): string;
+export declare function generateCSSVariables(theme: Theme, prefix?: string, attributeSelector?: string): string;
+/**
+ * Generates CSS custom properties 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 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')
+ * @returns CSS string with all theme CSS variables
+ */
+export declare function generateAllThemeVariables(themes: Record<string, Theme>, prefix?: string, attribute?: string): string;
 /**
  * Recursively replaces theme tokens with CSS variable references in a CSS object.
  *

package/dist/utils/theme.js

@@ -0,0 +1,304 @@
+/**
+ * Theme token resolution utilities.
+ * Converts theme tokens to CSS variables for runtime theme switching.
+ * Uses cached token index for efficient lookups and theme comparison.
+ */
+import { isCSSObject, isThemeObject, isProduction } from "./helpers";
+import { escapeCSSVariableValue, getScaleForProperty, sanitizeCSSVariableName, } from "./theme-utils";
+// Pre-compiled regex for token replacement (matches $primary, -$medium, $colors.primary, etc.)
+const TOKEN_REGEX = /(-?\$[a-zA-Z][a-zA-Z0-9]*(?:\$[a-zA-Z][a-zA-Z0-9]*)?(?:\.[a-zA-Z][a-zA-Z0-9]*)?)/g;
+/**
+ * Builds an index of all tokens in a theme for fast lookups.
+ *
+ * @param theme - Theme to index
+ * @returns Map of token names to their paths in the theme
+ */
+function buildTokenIndex(theme) {
+    const index = new Map();
+    function processThemeObject(obj, path = []) {
+        const keys = Object.keys(obj);
+        for (const key of keys) {
+            const value = obj[key];
+            const currentPath = [...path, key];
+            if (isThemeObject(value)) {
+                processThemeObject(value, currentPath);
+            }
+            else {
+                const existing = index.get(key);
+                if (existing) {
+                    existing.push(currentPath);
+                }
+                else {
+                    index.set(key, [currentPath]);
+                }
+            }
+        }
+    }
+    processThemeObject(theme);
+    for (const [, paths] of index.entries()) {
+        if (paths.length > 1) {
+            paths.sort((a, b) => {
+                const depthDiff = a.length - b.length;
+                if (depthDiff !== 0) {
+                    return depthDiff;
+                }
+                const pathA = a.join(".");
+                const pathB = b.join(".");
+                return pathA.localeCompare(pathB);
+            });
+        }
+    }
+    return index;
+}
+/**
+ * Checks if two themes have the same top-level keys (excluding 'media').
+ *
+ * @param theme1 - First theme
+ * @param theme2 - Second theme
+ * @returns True if themes have same keys
+ */
+function themesHaveSameKeys(theme1, theme2) {
+    const keys1 = Object.keys(theme1).filter((key) => key !== "media");
+    const keys2 = Object.keys(theme2).filter((key) => key !== "media");
+    if (keys1.length !== keys2.length) {
+        return false;
+    }
+    for (const key of keys1) {
+        if (!(key in theme2)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Compares two themes for structural and value equality.
+ * Excludes 'media' property from comparison.
+ *
+ * @param theme1 - First theme to compare
+ * @param theme2 - Second theme to compare
+ * @returns True if themes are equal
+ */
+export function themesAreEqual(theme1, theme2) {
+    if (theme1 === theme2) {
+        return true;
+    }
+    if (!theme1 || !theme2) {
+        return false;
+    }
+    if (!themesHaveSameKeys(theme1, theme2)) {
+        return false;
+    }
+    const theme1WithoutMedia = { ...theme1 };
+    const theme2WithoutMedia = { ...theme2 };
+    delete theme1WithoutMedia.media;
+    delete theme2WithoutMedia.media;
+    return JSON.stringify(theme1WithoutMedia) === JSON.stringify(theme2WithoutMedia);
+}
+/**
+ * Finds a token in the theme, optionally scoped to a specific scale.
+ *
+ * @param theme - Theme to search
+ * @param tokenName - Token name to find
+ * @param scale - Optional scale to search within first
+ * @returns Path to token or null if not found
+ */
+function findTokenInTheme(theme, tokenName, scale) {
+    if (scale && scale in theme) {
+        const scaleValue = theme[scale];
+        if (scaleValue &&
+            typeof scaleValue === "object" &&
+            !Array.isArray(scaleValue) &&
+            tokenName in scaleValue) {
+            return [scale, tokenName];
+        }
+    }
+    const index = buildTokenIndex(theme);
+    const paths = index.get(tokenName);
+    if (!paths || paths.length === 0) {
+        return null;
+    }
+    return paths[0];
+}
+/**
+ * Converts a theme token string to a CSS variable reference.
+ *
+ * @param token - Token string (e.g., "$primary" or "$colors$primary")
+ * @param theme - Optional theme for token resolution
+ * @param property - Optional CSS property name for scale detection
+ * @param themeMap - Optional theme scale mappings
+ * @returns CSS variable reference string
+ */
+export function tokenToCSSVar(token, theme, property, themeMap) {
+    if (!token.startsWith("$")) {
+        return token;
+    }
+    const tokenName = token.slice(1);
+    // Handle explicit scale: $colors$primary or $colors.primary
+    if (tokenName.includes("$") || tokenName.includes(".")) {
+        const parts = tokenName.includes("$") ? tokenName.split("$") : tokenName.split(".");
+        const sanitizedParts = parts.map((part) => sanitizeCSSVariableName(part));
+        const cssVarName = `--${sanitizedParts.join("-")}`;
+        return `var(${cssVarName})`;
+    }
+    // Handle shorthand token: $primary
+    if (theme && property) {
+        const scale = getScaleForProperty(property, themeMap);
+        if (scale) {
+            const foundPath = findTokenInTheme(theme, tokenName, scale);
+            if (foundPath) {
+                const sanitizedParts = foundPath.map((part) => sanitizeCSSVariableName(part));
+                const cssVarName = `--${sanitizedParts.join("-")}`;
+                return `var(${cssVarName})`;
+            }
+        }
+        const index = buildTokenIndex(theme);
+        const paths = index.get(tokenName);
+        if (paths && paths.length > 1) {
+            if (!isProduction()) {
+                const scaleInfo = scale
+                    ? `Property "${property}" maps to "${scale}" scale, but token not found there. `
+                    : `No scale mapping found for property "${property}". `;
+                // eslint-disable-next-line no-console
+                console.warn(`[Stoop] Ambiguous token "$${tokenName}" found in multiple categories: ${paths.map((p) => p.join(".")).join(", ")}. ` +
+                    `${scaleInfo}` +
+                    `Using "${paths[0].join(".")}" (deterministic: shorter paths first, then alphabetical). ` +
+                    `Use full path "$${paths[0].join(".")}" to be explicit.`);
+            }
+        }
+        const foundPath = findTokenInTheme(theme, tokenName);
+        if (foundPath) {
+            const sanitizedParts = foundPath.map((part) => sanitizeCSSVariableName(part));
+            const cssVarName = `--${sanitizedParts.join("-")}`;
+            return `var(${cssVarName})`;
+        }
+    }
+    else if (theme) {
+        const index = buildTokenIndex(theme);
+        const paths = index.get(tokenName);
+        if (paths && paths.length > 1) {
+            if (!isProduction()) {
+                // eslint-disable-next-line no-console
+                console.warn(`[Stoop] Ambiguous token "$${tokenName}" found in multiple categories: ${paths.map((p) => p.join(".")).join(", ")}. ` +
+                    `Using "${paths[0].join(".")}" (deterministic: shorter paths first, then alphabetical). ` +
+                    `Use full path "$${paths[0].join(".")}" to be explicit, or use with a CSS property for automatic resolution.`);
+            }
+        }
+        const foundPath = findTokenInTheme(theme, tokenName);
+        if (foundPath) {
+            const sanitizedParts = foundPath.map((part) => sanitizeCSSVariableName(part));
+            const cssVarName = `--${sanitizedParts.join("-")}`;
+            return `var(${cssVarName})`;
+        }
+    }
+    const sanitizedTokenName = sanitizeCSSVariableName(tokenName);
+    const cssVarName = `--${sanitizedTokenName}`;
+    return `var(${cssVarName})`;
+}
+/**
+ * Generates CSS custom properties from a theme object.
+ *
+ * @param theme - Theme object to convert to CSS variables
+ * @param prefix - Optional prefix for CSS variable names
+ * @param attributeSelector - Optional attribute selector (e.g., '[data-theme="light"]'). Defaults to ':root'
+ * @returns CSS string with selector and CSS variables
+ */
+export function generateCSSVariables(theme, prefix = "stoop", attributeSelector) {
+    const rootSelector = attributeSelector || ":root";
+    const variables = [];
+    function processThemeObject(obj, path = []) {
+        const keys = Object.keys(obj).sort();
+        for (const key of keys) {
+            // Media queries cannot be CSS variables
+            if (key === "media") {
+                continue;
+            }
+            const value = obj[key];
+            const currentPath = [...path, key];
+            if (isThemeObject(value)) {
+                processThemeObject(value, currentPath);
+            }
+            else {
+                const sanitizedParts = currentPath.map((part) => sanitizeCSSVariableName(part));
+                const varName = `--${sanitizedParts.join("-")}`;
+                const escapedValue = typeof value === "string" || typeof value === "number"
+                    ? escapeCSSVariableValue(value)
+                    : String(value);
+                variables.push(`  ${varName}: ${escapedValue};`);
+            }
+        }
+    }
+    processThemeObject(theme);
+    if (variables.length === 0) {
+        return "";
+    }
+    return `${rootSelector} {\n${variables.join("\n")}\n}`;
+}
+/**
+ * Generates CSS custom properties 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 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')
+ * @returns CSS string with all theme CSS variables
+ */
+export function generateAllThemeVariables(themes, prefix = "stoop", attribute = "data-theme") {
+    const themeBlocks = [];
+    for (const [themeName, theme] of Object.entries(themes)) {
+        const attributeSelector = `[${attribute}="${themeName}"]`;
+        const cssVars = generateCSSVariables(theme, prefix, attributeSelector);
+        if (cssVars) {
+            themeBlocks.push(cssVars);
+        }
+    }
+    return themeBlocks.join("\n\n");
+}
+/**
+ * Recursively replaces theme tokens with CSS variable references in a CSS object.
+ *
+ * @param obj - CSS object to process
+ * @param theme - Optional theme for token resolution
+ * @param themeMap - Optional theme scale mappings
+ * @param property - Optional CSS property name for scale detection
+ * @returns CSS object with tokens replaced by CSS variables
+ */
+export function replaceThemeTokensWithVars(obj, theme, themeMap, property) {
+    if (!obj || typeof obj !== "object") {
+        return obj;
+    }
+    const result = {};
+    let hasTokens = false;
+    const keys = Object.keys(obj).sort();
+    for (const key of keys) {
+        const value = obj[key];
+        if (isCSSObject(value)) {
+            const processed = replaceThemeTokensWithVars(value, theme, themeMap, undefined);
+            result[key] = processed;
+            // Check if processing changed anything (indicates tokens were found)
+            if (processed !== value) {
+                hasTokens = true;
+            }
+        }
+        else if (typeof value === "string" && value.includes("$")) {
+            hasTokens = true;
+            const cssProperty = property || key;
+            result[key] = value.replace(TOKEN_REGEX, (token) => {
+                if (token.startsWith("-$")) {
+                    const positiveToken = token.slice(1);
+                    const cssVar = tokenToCSSVar(positiveToken, theme, cssProperty, themeMap);
+                    return `calc(-1 * ${cssVar})`;
+                }
+                return tokenToCSSVar(token, theme, cssProperty, themeMap);
+            });
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    // Early exit: if no tokens were found, return original object to avoid unnecessary copying
+    if (!hasTokens) {
+        return obj;
+    }
+    return result;
+}