stoop 0.2.0 → 0.3.0

package/dist/inject/ssr.js

@@ -0,0 +1,46 @@
+/**
+ * SSR cache management for CSS injection.
+ * Maintains a cache of CSS text for server-side rendering.
+ */
+import { MAX_CSS_CACHE_SIZE } from "../constants";
+const cssTextCache = new Map();
+/**
+ * Adds CSS to the SSR cache with FIFO eviction.
+ *
+ * @param css - CSS string to cache
+ */
+export function addToSSRCache(css) {
+    if (cssTextCache.has(css)) {
+        return;
+    }
+    if (cssTextCache.size >= MAX_CSS_CACHE_SIZE) {
+        const firstKey = cssTextCache.keys().next().value;
+        if (firstKey !== undefined) {
+            cssTextCache.delete(firstKey);
+        }
+    }
+    cssTextCache.set(css, true);
+}
+/**
+ * Gets all cached CSS text for SSR.
+ *
+ * @returns Joined CSS text string
+ */
+export function getSSRCacheText() {
+    return Array.from(cssTextCache.keys()).join("\n");
+}
+/**
+ * Clears the SSR cache.
+ */
+export function clearSSRCache() {
+    cssTextCache.clear();
+}
+/**
+ * Checks if CSS is already in the SSR cache.
+ *
+ * @param css - CSS string to check
+ * @returns True if CSS is cached
+ */
+export function isInSSRCache(css) {
+    return cssTextCache.has(css);
+}

package/dist/ssr.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Server-safe entry point for Stoop.
+ * Exports only functions that work in Server Components.
+ * NO React dependencies, NO "use client" directive.
+ *
+ * Use this entry point when importing Stoop in Next.js Server Components.
+ *
+ * @example
+ * ```typescript
+ * // In a Server Component (layout.tsx)
+ * import { createStoop } from 'stoop/ssr';
+ *
+ * const { getCssText } = createStoop(config);
+ * const cssText = getCssText();
+ * ```
+ */
+export { createStoop } from "./create-stoop-server";
+export type { StoopServerInstance } from "./create-stoop-server";
+export { getCssText, clearStylesheet } from "./inject";
+export { generateCSSVariables } from "./utils/theme";
+export type { Theme, CSS, StoopConfig, UtilityFunction, Variants } from "./types";

package/dist/ssr.js

@@ -0,0 +1,19 @@
+/**
+ * Server-safe entry point for Stoop.
+ * Exports only functions that work in Server Components.
+ * NO React dependencies, NO "use client" directive.
+ *
+ * Use this entry point when importing Stoop in Next.js Server Components.
+ *
+ * @example
+ * ```typescript
+ * // In a Server Component (layout.tsx)
+ * import { createStoop } from 'stoop/ssr';
+ *
+ * const { getCssText } = createStoop(config);
+ * const cssText = getCssText();
+ * ```
+ */
+export { createStoop } from "./create-stoop-server";
+export { getCssText, clearStylesheet } from "./inject";
+export { generateCSSVariables } from "./utils/theme";

package/dist/types/index.d.ts

@@ -38,7 +38,7 @@ export type UtilityFunction = (value: CSSPropertyValue | CSS | undefined) => CSS
  */
 export type ThemeScale = keyof DefaultTheme;
 /**
- * Theme interface - strictly enforces only these 12 approved scales.
+ * Theme interface - strictly enforces only these 13 approved scales.
  * Custom theme scales are NOT allowed.
  * Media queries are also supported as part of the theme.
  */
@@ -51,6 +51,7 @@ export interface DefaultTheme {
     fonts?: Record<string, string>;
     fontWeights?: Record<string, string | number>;
     fontSizes?: Record<string, string>;
+    lineHeights?: Record<string, string | number>;
     letterSpacings?: Record<string, string>;
     shadows?: Record<string, string>;
     zIndices?: Record<string, string | number>;
@@ -97,6 +98,10 @@ export interface ProviderProps {
     storageKey?: string;
     attribute?: string;
 }
+/**
+ * Stoop instance.
+ * Includes all APIs: styled, Provider, useTheme, css, globalCss, keyframes, etc.
+ */
 export interface StoopInstance {
     styled: ReturnType<typeof createStyledFunction>;
     css: ReturnType<typeof createCSSFunction>;
@@ -129,13 +134,13 @@ export interface StoopInstance {
     preloadTheme: (theme: string | Theme) => void;
     /**
      * Provider component for managing theme state and updates.
-     * Only available if themes were provided in createStoop config.
+     * Available when themes are provided in createStoop config.
      */
-    Provider?: ComponentType<ProviderProps>;
+    Provider: ComponentType<ProviderProps>;
     /**
      * Hook to access theme management context.
-     * Only available if themes were provided in createStoop config.
+     * Available when themes are provided in createStoop config.
      */
-    useTheme?: () => ThemeManagementContextValue;
+    useTheme: () => ThemeManagementContextValue;
 }
 export {};

package/dist/types/index.js

@@ -0,0 +1,5 @@
+/**
+ * Core TypeScript type definitions for Stoop.
+ * Defines CSS objects, themes, variants, styled components, and instance types.
+ */
+export {};

package/dist/types/react-polymorphic-types.d.ts

@@ -5,13 +5,9 @@
 declare module "react-polymorphic-types" {
   import type { ElementType, ComponentPropsWithRef, ComponentPropsWithoutRef } from "react";
 
-  export type PolymorphicPropsWithRef<
-    OwnProps,
-    DefaultElement extends ElementType,
-  > = OwnProps & ComponentPropsWithRef<DefaultElement>;
+  export type PolymorphicPropsWithRef<OwnProps, DefaultElement extends ElementType> = OwnProps &
+    ComponentPropsWithRef<DefaultElement>;
 
-  export type PolymorphicPropsWithoutRef<
-    OwnProps,
-    DefaultElement extends ElementType,
-  > = OwnProps & ComponentPropsWithoutRef<DefaultElement>;
+  export type PolymorphicPropsWithoutRef<OwnProps, DefaultElement extends ElementType> = OwnProps &
+    ComponentPropsWithoutRef<DefaultElement>;
 }

package/dist/utils/environment.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Checks if code is running in a browser environment.
+ *
+ * @returns True if running in browser, false if in SSR/Node environment
+ */
+export declare function isBrowser(): boolean;

package/dist/utils/environment.js

@@ -0,0 +1,12 @@
+/**
+ * Checks if code is running in a browser environment.
+ *
+ * @returns True if running in browser, false if in SSR/Node environment
+ */
+export function isBrowser() {
+    return (typeof window !== "undefined" &&
+        typeof document !== "undefined" &&
+        typeof window.document === "object" &&
+        // Ensure we're not in React Server Component or SSR context
+        typeof window.requestAnimationFrame === "function");
+}

package/dist/utils/string.d.ts

@@ -4,7 +4,8 @@
  * and CSS sanitization utilities for security.
  */
 /**
- * Generates a hash string from an input string.
+ * 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
@@ -35,6 +36,7 @@ export declare function escapeCSSValue(value: string | number): string;
 /**
  * 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
@@ -43,6 +45,7 @@ export declare function sanitizeCSSSelector(selector: string): string;
 /**
  * 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
@@ -58,18 +61,12 @@ export declare function escapeCSSVariableValue(value: string | number): string;
 /**
  * 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
+ * @returns Sanitized prefix string (never empty, defaults to "stoop")
  */
 export declare function sanitizePrefix(prefix: string): string;
-/**
- * Escapes prefix for use in CSS attribute selectors.
- *
- * @param prefix - Prefix to escape
- * @returns Escaped prefix string
- */
-export declare function escapePrefixForSelector(prefix: string): string;
 /**
  * Sanitizes media query strings to prevent injection attacks.
  * Only allows safe characters for media queries.
@@ -81,6 +78,7 @@ export declare function sanitizeMediaQuery(mediaQuery: string): string;
 /**
  * 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
@@ -88,6 +86,7 @@ export declare function sanitizeMediaQuery(mediaQuery: string): string;
 export declare function sanitizeClassName(className: string): string;
 /**
  * Sanitizes CSS property names to prevent injection attacks.
+ * Uses memoization for performance.
  *
  * @param propertyName - Property name to sanitize
  * @returns Sanitized property name
@@ -100,3 +99,11 @@ export declare function sanitizeCSSPropertyName(propertyName: string): string;
  * @returns True if key is valid
  */
 export declare function validateKeyframeKey(key: string): boolean;
+/**
+ * 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 declare function getRootRegex(prefix?: string): RegExp;

package/dist/utils/string.js

@@ -0,0 +1,253 @@
+/**
+ * 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

@@ -3,9 +3,6 @@
  * Maps CSS properties to theme scales for deterministic token resolution.
  */
 import type { ThemeScale } from "../types";
-import { APPROVED_THEME_SCALES, DEFAULT_THEME_MAP } from "../constants";
-export { APPROVED_THEME_SCALES, DEFAULT_THEME_MAP };
-export type { ThemeScale };
 /**
  * Auto-detects theme scale from CSS property name using pattern matching.
  * Used as fallback when property is not in DEFAULT_THEME_MAP.

package/dist/utils/theme-map.js

@@ -0,0 +1,97 @@
+/**
+ * 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.js

@@ -0,0 +1,36 @@
+/**
+ * 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;
+}

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;
 /**