stoop 0.3.0 → 0.4.1

package/dist/utils/theme.js

@@ -1,279 +0,0 @@
-/**
- * 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 { escapeCSSVariableValue, sanitizeCSSVariableName } from "./string";
-import { getScaleForProperty } from "./theme-map";
-import { isCSSObject, isThemeObject } from "./type-guards";
-const tokenIndexCache = new WeakMap();
-// 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.
- * Caches the result to avoid rebuilding on every token resolution.
- *
- * @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.
- *
- * @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 (typeof process !== "undefined" && process.env?.NODE_ENV !== "production") {
-                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 (typeof process !== "undefined" && process.env?.NODE_ENV !== "production") {
-                // 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
- * @returns CSS string with :root selector and CSS variables
- */
-export function generateCSSVariables(theme, prefix = "stoop") {
-    const rootSelector = ":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}`;
-}
-/**
- * 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 = {};
-    const keys = Object.keys(obj).sort();
-    for (const key of keys) {
-        const value = obj[key];
-        if (isCSSObject(value)) {
-            result[key] = replaceThemeTokensWithVars(value, theme, themeMap, undefined);
-        }
-        else if (typeof value === "string" && value.includes("$")) {
-            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;
-        }
-    }
-    return result;
-}

package/dist/utils/type-guards.d.ts

@@ -1,26 +0,0 @@
-/**
- * Type guard utilities.
- * Provides runtime type checking for CSS objects, themes, and styled component references.
- */
-import type { CSS, Theme } from "../types";
-/**
- * Type guard for CSS objects.
- *
- * @param value - Value to check
- * @returns True if value is a CSS object
- */
-export declare function isCSSObject(value: unknown): value is CSS;
-/**
- * Type guard for valid CSS objects (excludes styled component references).
- *
- * @param value - Value to check
- * @returns True if value is a valid CSS object
- */
-export declare function isValidCSSObject(value: unknown): value is CSS;
-/**
- * Type guard for theme objects.
- *
- * @param value - Value to check
- * @returns True if value is a theme object
- */
-export declare function isThemeObject(value: unknown): value is Theme;

package/dist/utils/type-guards.js

@@ -1,38 +0,0 @@
-/**
- * Type guard utilities.
- * Provides runtime type checking for CSS objects, themes, and styled component references.
- */
-/**
- * Type guard for CSS objects.
- *
- * @param value - Value to check
- * @returns True if value is a CSS object
- */
-export function isCSSObject(value) {
-    return typeof value === "object" && value !== null;
-}
-function isStyledComponentRef(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        "__isStoopStyled" in value &&
-        "__stoopClassName" in value &&
-        value.__isStoopStyled === true);
-}
-/**
- * Type guard for valid CSS objects (excludes styled component references).
- *
- * @param value - Value to check
- * @returns True if value is a valid CSS object
- */
-export function isValidCSSObject(value) {
-    return isCSSObject(value) && !isStyledComponentRef(value);
-}
-/**
- * Type guard for theme objects.
- *
- * @param value - Value to check
- * @returns True if value is a theme object
- */
-export function isThemeObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/dist/utils/utilities.d.ts

@@ -1,14 +0,0 @@
-/**
- * Utility function application.
- * Applies utility functions (e.g., px, py) to transform shorthand properties into CSS.
- * Recursively processes nested CSS objects.
- */
-import type { CSS, UtilityFunction } from "../types";
-/**
- * Applies utility functions to transform shorthand properties into CSS.
- *
- * @param styles - CSS object to process
- * @param utils - Optional utility functions object
- * @returns CSS object with utilities applied
- */
-export declare function applyUtilities(styles: CSS, utils?: Record<string, UtilityFunction>): CSS;

package/dist/utils/utilities.js

@@ -1,43 +0,0 @@
-/**
- * Utility function application.
- * Applies utility functions (e.g., px, py) to transform shorthand properties into CSS.
- * Recursively processes nested CSS objects.
- */
-import { isCSSObject } from "./type-guards";
-/**
- * Applies utility functions to transform shorthand properties into CSS.
- *
- * @param styles - CSS object to process
- * @param utils - Optional utility functions object
- * @returns CSS object with utilities applied
- */
-export function applyUtilities(styles, utils) {
-    if (!utils || !styles || typeof styles !== "object") {
-        return styles;
-    }
-    const result = {};
-    const utilityKeys = Object.keys(utils);
-    for (const key in styles) {
-        const value = styles[key];
-        if (utilityKeys.includes(key) && utils[key]) {
-            try {
-                const utilityResult = utils[key](value);
-                if (utilityResult && typeof utilityResult === "object") {
-                    for (const utilKey in utilityResult) {
-                        result[utilKey] = utilityResult[utilKey];
-                    }
-                }
-            }
-            catch {
-                result[key] = value;
-            }
-        }
-        else if (isCSSObject(value)) {
-            result[key] = applyUtilities(value, utils);
-        }
-        else {
-            result[key] = value;
-        }
-    }
-    return result;
-}