stoop 0.6.0 → 0.6.2

package/dist/utils/theme.js

@@ -0,0 +1,430 @@
+/**
+ * Theme token resolution utilities.
+ * Converts theme tokens to CSS variables for runtime theme switching.
+ */
+import { isCSSObject, isThemeObject, isProduction } from "./helpers";
+import { escapeCSSVariableValue, getScaleForProperty, sanitizeCSSVariableName, } from "./theme-utils";
+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;
+// Cache token indices per theme to avoid rebuilding them
+const tokenIndexCache = new WeakMap();
+/**
+ * Builds an index of all tokens in a theme for fast lookups.
+ * Results are cached per theme instance to avoid rebuilding.
+ *
+ * @param theme - Theme to index
+ * @returns Map of token names to their paths in the theme
+ */
+function buildTokenIndex(theme) {
+    const cached = tokenIndexCache.get(theme);
+    if (cached) {
+        return cached;
+    }
+    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);
+            });
+        }
+    }
+    tokenIndexCache.set(theme, index);
+    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.
+ * Uses cached token index for performance.
+ *
+ * @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) {
+    // Fast path: check specific scale first if provided
+    if (scale && scale in theme) {
+        const scaleValue = theme[scale];
+        if (scaleValue &&
+            typeof scaleValue === "object" &&
+            !Array.isArray(scaleValue) &&
+            tokenName in scaleValue) {
+            return [scale, tokenName];
+        }
+    }
+    // Use cached index (buildTokenIndex uses WeakMap cache)
+    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);
+    // Fast path: explicit token paths (e.g., "$colors.background", "$space$medium")
+    // These don't need theme lookup - convert directly to CSS variable
+    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})`;
+    }
+    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})`;
+            }
+        }
+        // Reuse the index from findTokenInTheme if available, otherwise build it once
+        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.`);
+            }
+        }
+        // Use the already-built index instead of calling findTokenInTheme again
+        if (paths && paths.length > 0) {
+            const [foundPath] = paths;
+            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.`);
+            }
+        }
+        // Use the already-built index instead of calling findTokenInTheme again
+        if (paths && paths.length > 0) {
+            const [foundPath] = paths;
+            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) {
+            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.
+ * 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')
+ * @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;
+    }
+    // Fast pre-check: scan for tokens before creating new object
+    const keys = Object.keys(obj);
+    let hasAnyTokens = false;
+    // Quick scan to see if we need to process (only check top-level strings)
+    for (const key of keys) {
+        const value = obj[key];
+        if (typeof value === "string" && value.includes("$")) {
+            hasAnyTokens = true;
+            break;
+        }
+    }
+    // If no tokens found and no theme needed, return original
+    if (!hasAnyTokens && !theme) {
+        return obj;
+    }
+    const result = {};
+    let hasTokens = false;
+    for (const key of keys) {
+        const value = obj[key];
+        if (isCSSObject(value)) {
+            const processed = replaceThemeTokensWithVars(value, theme, themeMap, undefined);
+            result[key] = processed;
+            if (processed !== value) {
+                hasTokens = true;
+            }
+        }
+        else if (typeof value === "string" && value.includes("$")) {
+            hasTokens = true;
+            const cssProperty = property || key;
+            // Fast path: if value is exactly a single token (most common case), skip regex
+            // Check if it's a single token by ensuring it starts with $ and has no spaces or calc()
+            // This covers cases like "$colors.background", "$primary", "-$space.small"
+            const isSingleToken = value.startsWith("$") &&
+                !value.includes(" ") &&
+                !value.includes("calc(") &&
+                value === value.trim(); // No leading/trailing whitespace
+            if (isSingleToken) {
+                // Ultra-fast path for explicit tokens (e.g., "$colors.background")
+                // Convert directly to CSS variable without function call overhead
+                if (value.startsWith("-$")) {
+                    const positiveToken = value.slice(1);
+                    // Check if it's an explicit token path (contains . or $)
+                    if (positiveToken.includes(".") || positiveToken.includes("$")) {
+                        const parts = positiveToken.includes("$")
+                            ? positiveToken.split("$")
+                            : positiveToken.split(".");
+                        // Fast inline conversion - most theme scale names are already valid
+                        // Only sanitize if needed (contains invalid chars) - use fast char check
+                        let needsSanitization = false;
+                        for (let i = 0; i < parts.length; i++) {
+                            const part = parts[i];
+                            for (let j = 0; j < part.length; j++) {
+                                const char = part.charCodeAt(j);
+                                // Check if char is not alphanumeric, dash, or underscore
+                                if (!((char >= 48 && char <= 57) || // 0-9
+                                    (char >= 65 && char <= 90) || // A-Z
+                                    (char >= 97 && char <= 122) || // a-z
+                                    char === 45 ||
+                                    char === 95)) {
+                                    // - or _
+                                    needsSanitization = true;
+                                    break;
+                                }
+                            }
+                            if (needsSanitization)
+                                break;
+                        }
+                        if (needsSanitization) {
+                            // Fall back to sanitized version for edge cases
+                            const sanitizedParts = parts.map((part) => sanitizeCSSVariableName(part));
+                            const cssVarName = `--${sanitizedParts.join("-")}`;
+                            result[key] = `calc(-1 * var(${cssVarName}))`;
+                        }
+                        else {
+                            // Fast path: no sanitization needed
+                            const cssVarName = `--${parts.join("-")}`;
+                            result[key] = `calc(-1 * var(${cssVarName}))`;
+                        }
+                    }
+                    else {
+                        // Simple token - use existing function
+                        const cssVar = tokenToCSSVar(positiveToken, theme, cssProperty, themeMap);
+                        result[key] = `calc(-1 * ${cssVar})`;
+                    }
+                }
+                else {
+                    // Check if it's an explicit token path (contains . or $ after the $)
+                    const tokenName = value.slice(1);
+                    if (tokenName.includes(".") || tokenName.includes("$")) {
+                        const parts = tokenName.includes("$") ? tokenName.split("$") : tokenName.split(".");
+                        // Fast inline conversion - most theme scale names are already valid
+                        // Only sanitize if needed (contains invalid chars) - use fast char check
+                        let needsSanitization = false;
+                        for (let i = 0; i < parts.length; i++) {
+                            const part = parts[i];
+                            for (let j = 0; j < part.length; j++) {
+                                const char = part.charCodeAt(j);
+                                // Check if char is not alphanumeric, dash, or underscore
+                                if (!((char >= 48 && char <= 57) || // 0-9
+                                    (char >= 65 && char <= 90) || // A-Z
+                                    (char >= 97 && char <= 122) || // a-z
+                                    char === 45 ||
+                                    char === 95)) {
+                                    // - or _
+                                    needsSanitization = true;
+                                    break;
+                                }
+                            }
+                            if (needsSanitization)
+                                break;
+                        }
+                        if (needsSanitization) {
+                            // Fall back to sanitized version for edge cases
+                            const sanitizedParts = parts.map((part) => sanitizeCSSVariableName(part));
+                            const cssVarName = `--${sanitizedParts.join("-")}`;
+                            result[key] = `var(${cssVarName})`;
+                        }
+                        else {
+                            // Fast path: no sanitization needed
+                            const cssVarName = `--${parts.join("-")}`;
+                            result[key] = `var(${cssVarName})`;
+                        }
+                    }
+                    else {
+                        // Simple token - use existing function
+                        result[key] = tokenToCSSVar(value, theme, cssProperty, themeMap);
+                    }
+                }
+            }
+            else {
+                // Complex case: multiple tokens or tokens in expressions - use regex
+                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;
+        }
+    }
+    // Return original object if no tokens were found (avoid unnecessary object creation)
+    if (!hasTokens) {
+        return obj;
+    }
+    return result;
+}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "stoop",
   "description": "CSS-in-JS library with type inference, theme creation, and variants support.",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "author": "Jackson Dolman <mail@dolmios.com>",
-  "main": "./dist/create-stoop.js",
-  "types": "./dist/create-stoop.d.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "repository": {
     "type": "git",
     "url": "https://github.com/dolmios/stoop.git"
@@ -22,34 +22,20 @@
   },
   "exports": {
     ".": {
-      "types": "./dist/create-stoop.d.ts",
-      "import": "./dist/create-stoop.js",
-      "require": "./dist/create-stoop.js",
-      "default": "./dist/create-stoop.js"
-    },
-    "./utils/storage": {
-      "types": "./dist/utils/storage.d.ts",
-      "import": "./dist/utils/storage.js",
-      "require": "./dist/utils/storage.js",
-      "default": "./dist/utils/storage.js"
-    },
-    "./types": {
-      "types": "./dist/types/index.d.ts",
-      "import": "./dist/types/index.js",
-      "require": "./dist/types/index.js",
-      "default": "./dist/types/index.js"
-    },
-    "./inject": {
-      "types": "./dist/inject.d.ts",
-      "import": "./dist/inject.js",
-      "require": "./dist/inject.js",
-      "default": "./dist/inject.js"
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     },
     "./ssr": {
       "types": "./dist/create-stoop-ssr.d.ts",
-      "import": "./dist/create-stoop-ssr.js",
-      "require": "./dist/create-stoop-ssr.js",
       "default": "./dist/create-stoop-ssr.js"
+    },
+    "./styled": {
+      "types": "./dist/api/styled.d.ts",
+      "default": "./dist/api/styled.js"
+    },
+    "./theme-provider": {
+      "types": "./dist/api/theme-provider.d.ts",
+      "default": "./dist/api/theme-provider.js"
     }
   },
   "files": [
@@ -87,7 +73,7 @@
     "react": ">=16.8.0"
   },
   "scripts": {
-    "build": "bun run build.ts",
+    "build": "bunx tsc --project tsconfig.build.json",
     "lint": "eslint src --fix",
     "prepare": "bun run build",
     "test": "bun test",