stoop 0.3.0 → 0.4.1

package/dist/utils/string.js

@@ -1,253 +0,0 @@
-/**
- * String utility functions.
- * Provides hashing for class name generation, camelCase to kebab-case conversion,
- * and CSS sanitization utilities for security.
- */
-import { LRUCache } from "../core/cache";
-const sanitizeCacheSizeLimit = 1000;
-let cachedRootRegex = null;
-const selectorCache = new LRUCache(sanitizeCacheSizeLimit);
-const propertyNameCache = new LRUCache(sanitizeCacheSizeLimit);
-const sanitizeClassNameCache = new LRUCache(sanitizeCacheSizeLimit);
-const variableNameCache = new LRUCache(sanitizeCacheSizeLimit);
-/**
- * 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, "\\$&");
-        cachedRootRegex = new RegExp(`${escapedSelector}\\s*\\{[\\s\\S]*?\\}`, "g");
-    }
-    return cachedRootRegex;
-}

package/dist/utils/theme-map.d.ts

@@ -1,22 +0,0 @@
-/**
- * ThemeMap utilities for property-aware token resolution.
- * Maps CSS properties to theme scales for deterministic token resolution.
- */
-import type { ThemeScale } from "../types";
-/**
- * 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 declare function autoDetectScale(property: string): ThemeScale | 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 declare function getScaleForProperty(property: string, userThemeMap?: Record<string, ThemeScale>): ThemeScale | undefined;

package/dist/utils/theme-map.js

@@ -1,97 +0,0 @@
-/**
- * ThemeMap utilities for property-aware token resolution.
- * Maps CSS properties to theme scales for deterministic token resolution.
- */
-import { DEFAULT_THEME_MAP } from "../constants";
-/**
- * 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-validation.d.ts

@@ -1,13 +0,0 @@
-/**
- * Theme validation utilities.
- * Ensures theme objects only contain approved scales.
- */
-import type { DefaultTheme } from "../types";
-/**
- * Validates that a theme object only contains approved scales.
- *
- * @param theme - Theme object to validate
- * @returns Validated theme as DefaultTheme
- * @throws Error if theme contains invalid scales (in development)
- */
-export declare function validateTheme(theme: unknown): DefaultTheme;

package/dist/utils/theme-validation.js

@@ -1,36 +0,0 @@
-/**
- * Theme validation utilities.
- * Ensures theme objects only contain approved scales.
- */
-import { APPROVED_THEME_SCALES } from "../constants";
-/**
- * Validates that a theme object only contains approved scales.
- *
- * @param theme - Theme object to validate
- * @returns Validated theme as DefaultTheme
- * @throws Error if theme contains invalid scales (in development)
- */
-export function validateTheme(theme) {
-    if (!theme || typeof theme !== "object" || Array.isArray(theme)) {
-        throw new Error("[Stoop] Theme must be a non-null object");
-    }
-    if (typeof process !== "undefined" && process.env?.NODE_ENV === "production") {
-        return theme;
-    }
-    const themeObj = theme;
-    const invalidScales = [];
-    for (const key in themeObj) {
-        if (key === "media") {
-            continue;
-        }
-        if (!APPROVED_THEME_SCALES.includes(key)) {
-            invalidScales.push(key);
-        }
-    }
-    if (invalidScales.length > 0) {
-        const errorMessage = `[Stoop] Theme contains invalid scales: ${invalidScales.join(", ")}. ` +
-            `Only these scales are allowed: ${APPROVED_THEME_SCALES.join(", ")}`;
-        throw new Error(errorMessage);
-    }
-    return theme;
-}