stoop 0.6.0 → 0.6.2

package/dist/inject.js

@@ -0,0 +1,293 @@
+/**
+ * CSS injection implementation.
+ * Consolidates browser-specific and SSR-specific CSS injection logic.
+ * Handles stylesheet management, theme variable injection, deduplication, and SSR caching.
+ */
+import { MAX_CSS_CACHE_SIZE } from "./constants";
+import { LRUCache, clearStyleCache } from "./core/cache";
+import { isBrowser } from "./utils/helpers";
+import { getRootRegex, sanitizePrefix } from "./utils/theme-utils";
+// ============================================================================
+// Internal Deduplication
+// ============================================================================
+const injectedRules = new Map();
+/**
+ * Checks if a CSS rule has already been injected.
+ *
+ * @param key - Rule key to check
+ * @returns True if rule is already injected
+ */
+export function isInjectedRule(key) {
+    return injectedRules.has(key);
+}
+/**
+ * Marks a CSS rule as injected.
+ *
+ * @param key - Rule key
+ * @param css - CSS string
+ */
+export function markRuleAsInjected(key, css) {
+    injectedRules.set(key, css);
+}
+// ============================================================================
+// SSR Cache Management
+// ============================================================================
+const cssTextCache = new LRUCache(MAX_CSS_CACHE_SIZE);
+/**
+ * Adds CSS to the SSR cache with LRU eviction.
+ *
+ * @param css - CSS string to cache
+ */
+export function addToSSRCache(css) {
+    if (!cssTextCache.has(css)) {
+        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);
+}
+// ============================================================================
+// Browser-Specific Injection
+// ============================================================================
+const stylesheetElements = new Map();
+const lastInjectedThemes = new Map();
+const lastInjectedCSSVars = new Map();
+/**
+ * Gets or creates the stylesheet element for CSS injection.
+ * Reuses the SSR stylesheet if it exists to prevent FOUC.
+ *
+ * @param prefix - Optional prefix for stylesheet identification
+ * @returns HTMLStyleElement
+ * @throws Error if called in SSR context
+ */
+export function getStylesheet(prefix = "stoop") {
+    if (!isBrowser()) {
+        throw new Error("Cannot access document in SSR context");
+    }
+    const sanitizedPrefix = sanitizePrefix(prefix);
+    let stylesheetElement = stylesheetElements.get(sanitizedPrefix);
+    if (!stylesheetElement || !stylesheetElement.parentNode) {
+        const ssrStylesheet = document.getElementById("stoop-ssr");
+        if (ssrStylesheet) {
+            const existingPrefix = ssrStylesheet.getAttribute("data-stoop");
+            if (!existingPrefix || existingPrefix === sanitizedPrefix) {
+                stylesheetElement = ssrStylesheet;
+                stylesheetElement.setAttribute("data-stoop", sanitizedPrefix);
+                stylesheetElements.set(sanitizedPrefix, stylesheetElement);
+                return stylesheetElement;
+            }
+        }
+        stylesheetElement = document.createElement("style");
+        stylesheetElement.setAttribute("data-stoop", sanitizedPrefix);
+        stylesheetElement.setAttribute("id", `stoop-${sanitizedPrefix}`);
+        document.head.appendChild(stylesheetElement);
+        stylesheetElements.set(sanitizedPrefix, stylesheetElement);
+    }
+    return stylesheetElement;
+}
+/**
+ * Removes all theme variable blocks (both :root and attribute selectors) from CSS.
+ *
+ * @param css - CSS string to clean
+ * @returns CSS string without theme variable blocks
+ */
+export function removeThemeVariableBlocks(css) {
+    let result = css;
+    const rootRegex = getRootRegex("");
+    result = result.replace(rootRegex, "").trim();
+    let startIndex = result.indexOf("[data-theme=");
+    while (startIndex !== -1) {
+        const openBrace = result.indexOf("{", startIndex);
+        if (openBrace === -1) {
+            break;
+        }
+        let braceCount = 1;
+        let closeBrace = openBrace + 1;
+        while (closeBrace < result.length && braceCount > 0) {
+            if (result[closeBrace] === "{") {
+                braceCount++;
+            }
+            else if (result[closeBrace] === "}") {
+                braceCount--;
+            }
+            closeBrace++;
+        }
+        if (braceCount === 0) {
+            const before = result.substring(0, startIndex).trim();
+            const after = result.substring(closeBrace).trim();
+            result = (before + "\n" + after).trim();
+        }
+        else {
+            break;
+        }
+        startIndex = result.indexOf("[data-theme=");
+    }
+    return result.trim();
+}
+/**
+ * Injects CSS variables for all themes using attribute selectors.
+ * All themes are available simultaneously, with theme switching handled by changing the data-theme attribute.
+ *
+ * @param allThemeVars - CSS string containing all theme CSS variables
+ * @param prefix - Optional prefix for CSS variables
+ */
+export function injectAllThemeVariables(allThemeVars, prefix = "stoop") {
+    if (!allThemeVars) {
+        return;
+    }
+    const sanitizedPrefix = sanitizePrefix(prefix);
+    const key = `__all_theme_vars_${sanitizedPrefix}`;
+    const lastCSSVars = lastInjectedCSSVars.get(key) ?? null;
+    if (lastCSSVars === allThemeVars) {
+        return;
+    }
+    lastInjectedCSSVars.set(key, allThemeVars);
+    if (!isBrowser()) {
+        addToSSRCache(allThemeVars);
+        return;
+    }
+    const sheet = getStylesheet(sanitizedPrefix);
+    const currentCSS = sheet.textContent || "";
+    const hasThemeBlocks = currentCSS.includes(":root") || currentCSS.includes("[data-theme=");
+    if (isInjectedRule(key) || hasThemeBlocks) {
+        const withoutVars = removeThemeVariableBlocks(currentCSS);
+        sheet.textContent = allThemeVars + (withoutVars ? "\n\n" + withoutVars : "");
+        markRuleAsInjected(key, allThemeVars);
+    }
+    else {
+        sheet.textContent = allThemeVars + (currentCSS ? "\n\n" + currentCSS : "");
+        markRuleAsInjected(key, allThemeVars);
+    }
+}
+/**
+ * Updates the stylesheet with new CSS rules.
+ *
+ * @param css - CSS string to inject
+ * @param ruleKey - Unique key for deduplication
+ * @param prefix - Optional prefix for CSS rules
+ */
+export function updateStylesheet(css, ruleKey, prefix = "stoop") {
+    if (!isBrowser()) {
+        return;
+    }
+    const sanitizedPrefix = sanitizePrefix(prefix);
+    if (isInjectedRule(ruleKey)) {
+        return;
+    }
+    const sheet = getStylesheet(sanitizedPrefix);
+    const currentCSS = sheet.textContent || "";
+    sheet.textContent = currentCSS + (currentCSS ? "\n" : "") + css;
+    markRuleAsInjected(ruleKey, css);
+}
+/**
+ * Injects CSS into the browser stylesheet with deduplication.
+ *
+ * @param css - CSS string to inject
+ * @param ruleKey - Unique key for deduplication
+ * @param prefix - Optional prefix for CSS rules
+ */
+export function injectBrowserCSS(css, ruleKey, prefix = "stoop") {
+    if (isInjectedRule(ruleKey)) {
+        return;
+    }
+    const sanitizedPrefix = sanitizePrefix(prefix);
+    updateStylesheet(css, ruleKey, sanitizedPrefix);
+}
+/**
+ * Gets the current stylesheet element for a given prefix.
+ *
+ * @param prefix - Optional prefix for stylesheet identification
+ * @returns HTMLStyleElement or null if not created
+ */
+export function getStylesheetElement(prefix = "stoop") {
+    const sanitizedPrefix = sanitizePrefix(prefix);
+    return stylesheetElements.get(sanitizedPrefix) || null;
+}
+/**
+ * Clears the stylesheet and all caches.
+ */
+function clearStylesheetInternal() {
+    for (const [, element] of stylesheetElements.entries()) {
+        if (element && element.parentNode) {
+            element.parentNode.removeChild(element);
+        }
+    }
+    stylesheetElements.clear();
+    lastInjectedThemes.clear();
+    lastInjectedCSSVars.clear();
+    injectedRules.clear();
+}
+/**
+ * Gets all injected rules.
+ */
+export function getAllInjectedRules() {
+    return new Map(injectedRules);
+}
+// ============================================================================
+// Public API Functions
+// ============================================================================
+/**
+ * Injects CSS into the document with automatic SSR support.
+ *
+ * @param css - CSS string to inject
+ * @param prefix - Optional prefix for CSS rules
+ * @param ruleKey - Optional unique key for deduplication
+ */
+export function injectCSS(css, prefix = "stoop", ruleKey) {
+    const key = ruleKey || css;
+    if (!isBrowser()) {
+        if (!isInjectedRule(key)) {
+            markRuleAsInjected(key, css);
+        }
+        addToSSRCache(css);
+        return;
+    }
+    injectBrowserCSS(css, key, prefix);
+}
+/**
+ * Gets all injected CSS text (browser or SSR).
+ *
+ * @returns CSS text string
+ */
+export function getCssText(prefix = "stoop") {
+    if (isBrowser()) {
+        const sanitizedPrefix = sanitizePrefix(prefix);
+        const sheetElement = getStylesheetElement(sanitizedPrefix);
+        if (sheetElement && sheetElement.parentNode) {
+            const sheetCSS = sheetElement.textContent || "";
+            if (!sheetCSS && getAllInjectedRules().size > 0) {
+                return getSSRCacheText();
+            }
+            return sheetCSS;
+        }
+    }
+    return getSSRCacheText();
+}
+/**
+ * Clears all injected CSS and caches.
+ */
+export function clearStylesheet() {
+    clearStylesheetInternal();
+    clearSSRCache();
+    clearStyleCache();
+}

package/dist/types/index.d.ts

@@ -265,7 +265,7 @@ type Merge<T, U> = Omit<T, keyof U> & U;
  * Props for a styled component without the `as` prop polymorphism.
  * Just the base element props + our styled props.
  */
-export type StyledComponentProps<DefaultElement extends ElementType, VariantsConfig extends Variants = {}> = Merge<DefaultElement extends keyof JSX.IntrinsicElements | ComponentType<any> ? ComponentPropsWithRef<DefaultElement> : {}, StyledOwnProps<VariantsConfig>>;
+export type StyledComponentProps<DefaultElement extends ElementType, VariantsConfig extends Variants = {}> = Merge<DefaultElement extends keyof JSX.IntrinsicElements | ComponentType<unknown> ? ComponentPropsWithRef<DefaultElement> : {}, StyledOwnProps<VariantsConfig>>;
 export interface ThemeContextValue {
     theme: Theme;
     themeName?: string;
@@ -521,7 +521,7 @@ export interface StoopInstance {
  * type ButtonProps = ComponentProps<typeof Button>;
  * ```
  */
-export type ComponentProps<Component> = Component extends (...args: any[]) => any ? Parameters<Component>[0] : never;
+export type ComponentProps<Component> = Component extends (...args: unknown[]) => unknown ? Parameters<Component>[0] : never;
 /**
  * Returns a type that extracts only the variant props from a styled component.
  *
@@ -535,6 +535,6 @@ export type ComponentProps<Component> = Component extends (...args: any[]) => an
  * ```
  */
 export type VariantProps<Component extends {
-    selector: any;
-}> = Component extends StyledComponent<any, infer V> ? VariantPropsFromConfig<V> : never;
+    selector: StyledComponentRef;
+}> = Component extends StyledComponent<ElementType, infer V> ? VariantPropsFromConfig<V> : never;
 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/utils/helpers.js

@@ -0,0 +1,157 @@
+/**
+ * Helper utilities for Stoop.
+ * Consolidates environment detection, type guards, theme validation, and utility function application.
+ */
+import { APPROVED_THEME_SCALES } from "../constants";
+// ============================================================================
+// Environment Detection
+// ============================================================================
+/**
+ * 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" &&
+        typeof document.createElement === "function");
+}
+/**
+ * Checks if running in production mode.
+ *
+ * @returns True if running in production mode
+ */
+export function isProduction() {
+    return typeof process !== "undefined" && process.env?.NODE_ENV === "production";
+}
+// ============================================================================
+// Type Guards
+// ============================================================================
+/**
+ * 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;
+}
+/**
+ * Checks if a value is a styled component reference.
+ *
+ * @param value - Value to check
+ * @returns True if value is a styled component reference
+ */
+export 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);
+}
+// ============================================================================
+// Theme Validation
+// ============================================================================
+/**
+ * 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 (development only)
+ */
+export function validateTheme(theme) {
+    if (!theme || typeof theme !== "object" || Array.isArray(theme)) {
+        throw new Error("[Stoop] Theme must be a non-null object");
+    }
+    // Skip all validation in production for performance
+    if (isProduction()) {
+        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;
+}
+// ============================================================================
+// Utility Function Application
+// ============================================================================
+/**
+ * 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 utilityKeys = Object.keys(utils);
+    // Fast path: check if any utility keys are present before creating new object
+    let hasUtilities = false;
+    for (const key in styles) {
+        if (utilityKeys.includes(key)) {
+            hasUtilities = true;
+            break;
+        }
+    }
+    // If no utility keys found, return original object
+    if (!hasUtilities) {
+        return styles;
+    }
+    const result = {};
+    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;
+}

package/dist/utils/storage.js

@@ -0,0 +1,130 @@
+/**
+ * Storage and theme detection utilities.
+ * Provides simplified localStorage and cookie management with SSR compatibility and error handling.
+ */
+import { DEFAULT_COOKIE_MAX_AGE, DEFAULT_COOKIE_PATH } from "../constants";
+import { isBrowser } from "./helpers";
+// ============================================================================
+// Storage Utilities
+// ============================================================================
+/**
+ * Safely gets a value from localStorage.
+ *
+ * @param key - Storage key
+ * @returns Storage result
+ */
+export function getFromStorage(key) {
+    if (!isBrowser()) {
+        return { error: "Not in browser environment", success: false, value: null };
+    }
+    try {
+        const value = localStorage.getItem(key);
+        return { source: "localStorage", success: true, value };
+    }
+    catch (error) {
+        return {
+            error: error instanceof Error ? error.message : "localStorage access failed",
+            success: false,
+            value: null,
+        };
+    }
+}
+/**
+ * Safely sets a value in localStorage.
+ *
+ * @param key - Storage key
+ * @param value - Value to store
+ * @returns Storage result
+ */
+export function setInStorage(key, value) {
+    if (!isBrowser()) {
+        return { error: "Not in browser environment", success: false, value: undefined };
+    }
+    try {
+        localStorage.setItem(key, value);
+        return { success: true, value: undefined };
+    }
+    catch (error) {
+        return {
+            error: error instanceof Error ? error.message : "localStorage write failed",
+            success: false,
+            value: undefined,
+        };
+    }
+}
+/**
+ * Safely removes a value from localStorage.
+ *
+ * @param key - Storage key
+ * @returns Storage result
+ */
+export function removeFromStorage(key) {
+    if (!isBrowser()) {
+        return { error: "Not in browser environment", success: false, value: undefined };
+    }
+    try {
+        localStorage.removeItem(key);
+        return { success: true, value: undefined };
+    }
+    catch (error) {
+        return {
+            error: error instanceof Error ? error.message : "localStorage remove failed",
+            success: false,
+            value: undefined,
+        };
+    }
+}
+/**
+ * Gets a cookie value.
+ *
+ * @param name - Cookie name
+ * @returns Cookie value or null if not found
+ */
+export function getCookie(name) {
+    if (!isBrowser())
+        return null;
+    const value = `; ${document.cookie}`;
+    const parts = value.split(`; ${name}=`);
+    if (parts.length === 2) {
+        return parts.pop()?.split(";").shift() || null;
+    }
+    return null;
+}
+/**
+ * Sets a cookie value.
+ *
+ * @param name - Cookie name
+ * @param value - Cookie value
+ * @param options - Cookie options
+ * @returns Success status
+ */
+export function setCookie(name, value, options = {}) {
+    if (!isBrowser())
+        return false;
+    const { maxAge = DEFAULT_COOKIE_MAX_AGE, path = DEFAULT_COOKIE_PATH, secure = false } = options;
+    try {
+        document.cookie = `${name}=${value}; path=${path}; max-age=${maxAge}${secure ? "; secure" : ""}`;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Removes a cookie by setting it to expire.
+ *
+ * @param name - Cookie name
+ * @param path - Cookie path
+ * @returns Success status
+ */
+export function removeCookie(name, path = "/") {
+    if (!isBrowser())
+        return false;
+    try {
+        document.cookie = `${name}=; path=${path}; max-age=0`;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}