stoop 0.3.0 → 0.4.0

package/dist/utils/theme.js

@@ -3,24 +3,17 @@
  * 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();
+import { isCSSObject, isThemeObject, isProduction } from "./helpers";
+import { escapeCSSVariableValue, getScaleForProperty, sanitizeCSSVariableName, } from "./theme-utils";
 // 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);
@@ -55,7 +48,6 @@ function buildTokenIndex(theme) {
             });
         }
     }
-    tokenIndexCache.set(theme, index);
     return index;
 }
 /**
@@ -162,7 +154,7 @@ export function tokenToCSSVar(token, theme, property, themeMap) {
         const index = buildTokenIndex(theme);
         const paths = index.get(tokenName);
         if (paths && paths.length > 1) {
-            if (typeof process !== "undefined" && process.env?.NODE_ENV !== "production") {
+            if (!isProduction()) {
                 const scaleInfo = scale
                     ? `Property "${property}" maps to "${scale}" scale, but token not found there. `
                     : `No scale mapping found for property "${property}". `;
@@ -184,7 +176,7 @@ export function tokenToCSSVar(token, theme, property, themeMap) {
         const index = buildTokenIndex(theme);
         const paths = index.get(tokenName);
         if (paths && paths.length > 1) {
-            if (typeof process !== "undefined" && process.env?.NODE_ENV !== "production") {
+            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). ` +
@@ -207,10 +199,11 @@ export function tokenToCSSVar(token, theme, property, themeMap) {
  *
  * @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
+ * @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") {
-    const rootSelector = ":root";
+export function generateCSSVariables(theme, prefix = "stoop", attributeSelector) {
+    const rootSelector = attributeSelector || ":root";
     const variables = [];
     function processThemeObject(obj, path = []) {
         const keys = Object.keys(obj).sort();
@@ -240,6 +233,27 @@ export function generateCSSVariables(theme, prefix = "stoop") {
     }
     return `${rootSelector} {\n${variables.join("\n")}\n}`;
 }
+/**
+ * Generates CSS custom properties for all themes using attribute selectors.
+ * This allows all themes to be 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.
  *
@@ -254,13 +268,20 @@ export function replaceThemeTokensWithVars(obj, theme, themeMap, property) {
         return obj;
     }
     const result = {};
+    let hasTokens = false;
     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);
+            const processed = replaceThemeTokensWithVars(value, theme, themeMap, undefined);
+            result[key] = processed;
+            // Check if processing changed anything (indicates tokens were found)
+            if (processed !== value) {
+                hasTokens = true;
+            }
         }
         else if (typeof value === "string" && value.includes("$")) {
+            hasTokens = true;
             const cssProperty = property || key;
             result[key] = value.replace(TOKEN_REGEX, (token) => {
                 if (token.startsWith("-$")) {
@@ -275,5 +296,9 @@ export function replaceThemeTokensWithVars(obj, theme, themeMap, property) {
             result[key] = value;
         }
     }
+    // Early exit: if no tokens were found, return original object to avoid unnecessary copying
+    if (!hasTokens) {
+        return obj;
+    }
     return result;
 }

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "stoop",
   "description": "CSS-in-JS library with type inference, theme creation, and variants support.",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "author": "Jackson Dolman <mail@dolmios.com>",
-  "main": "./dist/index.js",
+  "main": "./dist/create-stoop.js",
+  "types": "./dist/create-stoop.d.ts",
   "repository": {
     "type": "git",
     "url": "https://github.com/dolmios/stoop.git"
@@ -16,24 +17,48 @@
     "react-polymorphic-types": "^2.0.0"
   },
   "devDependencies": {
-    "@types/node": "^22.10.5",
-    "@types/react": "^19.0.6",
-    "@types/react-dom": "^19.0.2",
-    "bun-types": "^1.2.6",
-    "typescript": "^5.7.2"
+    "@types/node": "^25.0.3",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "bun-types": "^1.3.5",
+    "typescript": "^5.9.3"
   },
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.js",
-      "default": "./dist/index.js"
+      "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"
+    },
+    "./utils/auto-preload": {
+      "types": "./dist/utils/auto-preload.d.ts",
+      "import": "./dist/utils/auto-preload.js",
+      "require": "./dist/utils/auto-preload.js",
+      "default": "./dist/utils/auto-preload.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"
     },
     "./ssr": {
-      "types": "./dist/ssr.d.ts",
-      "import": "./dist/ssr.js",
-      "require": "./dist/ssr.js",
-      "default": "./dist/ssr.js"
+      "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"
     }
   },
   "files": [
@@ -71,18 +96,18 @@
     "react": ">=16.8.0",
     "react-dom": ">=16.8.0"
   },
+  "sideEffects": false,
+  "type": "module",
   "scripts": {
-    "build": "bun run build:clean && bun run build:types",
+    "build": "bun run build:clean && bun run build:js && bun run build:js:ssr && bun run build:types",
     "build:clean": "rm -rf dist",
     "build:copy-declarations": "mkdir -p dist/types && cp src/types/react-polymorphic-types.d.ts dist/types/react-polymorphic-types.d.ts 2>/dev/null || :",
-    "build:js": "NODE_ENV=production bun build ./src/index.ts --outdir ./dist --target node --minify --jsx=automatic --splitting --external react --external react-dom --external react/jsx-runtime --define process.env.NODE_ENV='\"production\"'",
+    "build:js": "NODE_ENV=production bun build ./src/create-stoop.ts --outdir ./dist --target node --minify --jsx=automatic --splitting --external react --external react-dom --external react/jsx-runtime --define process.env.NODE_ENV='\"production\"'",
+    "build:js:ssr": "NODE_ENV=production bun build ./src/create-stoop-ssr.ts --outdir ./dist --target node --minify --jsx=automatic --external react --external react-dom --external react/jsx-runtime --define process.env.NODE_ENV='\"production\"'",
     "build:types": "bunx tsc --project tsconfig.build.json && bun run build:copy-declarations",
-    "prepare": "bun run build",
+    "lint": "eslint src --fix",
     "test": "bun test",
     "test:coverage": "bun test --coverage",
     "test:watch": "bun test --watch"
-  },
-  "sideEffects": false,
-  "type": "module"
-}
-
+  }
+}

package/dist/api/create-theme.d.ts

@@ -1,13 +0,0 @@
-/**
- * Theme extension API.
- * Creates a function that deep merges theme overrides with a base theme.
- */
-import type { Theme } from "../types";
-/**
- * Creates a function that extends a base theme with overrides.
- * The returned function deep merges theme overrides with the base theme.
- *
- * @param baseTheme - Base theme to extend
- * @returns Function that accepts theme overrides and returns a merged theme
- */
-export declare function createTheme(baseTheme: Theme): (themeOverrides: Partial<Theme>) => Theme;

package/dist/api/create-theme.js

@@ -1,43 +0,0 @@
-/**
- * Theme extension API.
- * Creates a function that deep merges theme overrides with a base theme.
- */
-import { validateTheme } from "../utils/theme-validation";
-import { isThemeObject } from "../utils/type-guards";
-/**
- * Creates a function that extends a base theme with overrides.
- * The returned function deep merges theme overrides with the base theme.
- *
- * @param baseTheme - Base theme to extend
- * @returns Function that accepts theme overrides and returns a merged theme
- */
-export function createTheme(baseTheme) {
-    return function createTheme(themeOverrides) {
-        const validatedOverrides = validateTheme(themeOverrides);
-        function deepMerge(target, source) {
-            const result = { ...target };
-            const sourceKeys = Object.keys(source);
-            for (const key of sourceKeys) {
-                const sourceValue = source[key];
-                const targetValue = target[key];
-                if (isThemeObject(sourceValue) && isThemeObject(targetValue)) {
-                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                    result[key] = { ...targetValue, ...sourceValue };
-                }
-                else if (sourceValue !== undefined) {
-                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                    result[key] = sourceValue;
-                }
-            }
-            const targetKeys = Object.keys(target);
-            for (const key of targetKeys) {
-                if (!(key in result)) {
-                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                    result[key] = target[key];
-                }
-            }
-            return result;
-        }
-        return deepMerge(baseTheme, validatedOverrides);
-    };
-}

package/dist/api/css.d.ts

@@ -1,16 +0,0 @@
-/**
- * CSS class generation API.
- * Creates a function that compiles CSS objects into class names.
- */
-import type { CSS, Theme, ThemeScale, UtilityFunction } from "../types";
-/**
- * Creates a CSS function that compiles CSS objects into class names.
- *
- * @param defaultTheme - Default theme for token resolution
- * @param prefix - Optional prefix for generated class names
- * @param media - Optional media query breakpoints
- * @param utils - Optional utility functions
- * @param themeMap - Optional theme scale mappings
- * @returns Function that accepts CSS objects and returns class names
- */
-export declare function createCSSFunction(defaultTheme: Theme, prefix?: string, media?: Record<string, string>, utils?: Record<string, UtilityFunction>, themeMap?: Record<string, ThemeScale>): (styles: CSS) => string;

package/dist/api/css.js

@@ -1,20 +0,0 @@
-/**
- * CSS class generation API.
- * Creates a function that compiles CSS objects into class names.
- */
-import { compileCSS } from "../core/compiler";
-/**
- * Creates a CSS function that compiles CSS objects into class names.
- *
- * @param defaultTheme - Default theme for token resolution
- * @param prefix - Optional prefix for generated class names
- * @param media - Optional media query breakpoints
- * @param utils - Optional utility functions
- * @param themeMap - Optional theme scale mappings
- * @returns Function that accepts CSS objects and returns class names
- */
-export function createCSSFunction(defaultTheme, prefix = "stoop", media, utils, themeMap) {
-    return function css(styles) {
-        return compileCSS(styles, defaultTheme, prefix, media, utils, themeMap);
-    };
-}

package/dist/api/keyframes.d.ts

@@ -1,16 +0,0 @@
-/**
- * CSS keyframes animation API.
- * Creates a function that generates and injects @keyframes rules.
- * Caches animations by content hash to prevent duplicates.
- */
-import type { CSS, Theme, ThemeScale } from "../types";
-/**
- * Creates a keyframes animation function.
- * Generates and injects @keyframes rules with caching to prevent duplicates.
- *
- * @param prefix - Optional prefix for animation names
- * @param theme - Optional theme for token resolution
- * @param themeMap - Optional theme scale mappings
- * @returns Function that accepts keyframes objects and returns animation names
- */
-export declare function createKeyframesFunction(prefix?: string, theme?: Theme, themeMap?: Record<string, ThemeScale>): (keyframes: Record<string, CSS>) => string;

package/dist/api/provider.d.ts

@@ -1,19 +0,0 @@
-/**
- * Theme Provider component.
- * Manages theme state, localStorage persistence, and centralized theme variable updates.
- */
-import { type ComponentType, type Context } from "react";
-import type { ProviderProps, Theme, ThemeContextValue, ThemeManagementContextValue } from "../types";
-/**
- * Creates a Provider component for theme management.
- *
- * @param themes - Map of theme names to theme objects
- * @param defaultTheme - Default theme object
- * @param prefix - Optional prefix for CSS variable scoping
- * @returns Provider component, theme context, and theme management context
- */
-export declare function createProvider(themes: Record<string, Theme>, defaultTheme: Theme, prefix?: string): {
-    Provider: ComponentType<ProviderProps>;
-    ThemeContext: Context<ThemeContextValue | null>;
-    ThemeManagementContext: Context<ThemeManagementContextValue | null>;
-};

package/dist/api/provider.js

@@ -1,109 +0,0 @@
-"use client";
-import { jsx as _jsx } from "react/jsx-runtime";
-/**
- * Theme Provider component.
- * Manages theme state, localStorage persistence, and centralized theme variable updates.
- */
-import { createContext, useCallback, useLayoutEffect, useMemo, useState, } from "react";
-import { updateThemeVariables } from "../core/theme-manager";
-import { isBrowser } from "../utils/environment";
-/**
- * Creates a Provider component for theme management.
- *
- * @param themes - Map of theme names to theme objects
- * @param defaultTheme - Default theme object
- * @param prefix - Optional prefix for CSS variable scoping
- * @returns Provider component, theme context, and theme management context
- */
-export function createProvider(themes, defaultTheme, prefix = "stoop") {
-    const ThemeContext = createContext(null);
-    const ThemeManagementContext = createContext(null);
-    const availableThemeNames = Object.keys(themes);
-    const firstThemeName = availableThemeNames[0] || "default";
-    function Provider({ attribute = "data-theme", children, defaultTheme: defaultThemeProp, storageKey = "stoop-theme", }) {
-        // SSR-safe initialization: always start with default, then hydrate from localStorage
-        const [themeName, setThemeNameState] = useState(() => {
-            // During SSR, always return the default theme
-            if (!isBrowser()) {
-                return defaultThemeProp || firstThemeName;
-            }
-            // On client, try to read from localStorage
-            try {
-                const stored = localStorage.getItem(storageKey);
-                if (stored && themes[stored]) {
-                    return stored;
-                }
-            }
-            catch {
-                // localStorage access failed (e.g., in private browsing mode)
-            }
-            return defaultThemeProp || firstThemeName;
-        });
-        // Hydrate from localStorage after mount to prevent hydration mismatch
-        useLayoutEffect(() => {
-            if (!isBrowser()) {
-                return;
-            }
-            try {
-                const stored = localStorage.getItem(storageKey);
-                if (stored && themes[stored] && stored !== themeName) {
-                    setThemeNameState(stored);
-                }
-            }
-            catch {
-                // localStorage access failed
-            }
-        }, [storageKey, themeName]);
-        const currentTheme = useMemo(() => {
-            return themes[themeName] || themes[defaultThemeProp || firstThemeName] || defaultTheme;
-        }, [themeName, defaultThemeProp, firstThemeName, themes]);
-        useLayoutEffect(() => {
-            if (currentTheme) {
-                updateThemeVariables(currentTheme, prefix);
-            }
-        }, [currentTheme, prefix]);
-        useLayoutEffect(() => {
-            if (isBrowser() && attribute) {
-                document.documentElement.setAttribute(attribute, themeName);
-            }
-        }, [themeName, attribute]);
-        const setTheme = useCallback((newThemeName) => {
-            if (themes[newThemeName]) {
-                setThemeNameState(newThemeName);
-                try {
-                    localStorage.setItem(storageKey, newThemeName);
-                }
-                catch {
-                    // localStorage access failed (e.g., in private browsing mode)
-                }
-            }
-            else if (typeof process !== "undefined" && process.env?.NODE_ENV !== "production") {
-                // eslint-disable-next-line no-console
-                console.warn(`[Stoop] Theme "${newThemeName}" not found. Available themes: ${availableThemeNames.join(", ")}`);
-            }
-        }, [storageKey, themes, availableThemeNames]);
-        const themeContextValue = useMemo(() => ({
-            theme: currentTheme,
-            themeName,
-        }), [currentTheme, themeName]);
-        const toggleTheme = useCallback(() => {
-            const currentIndex = availableThemeNames.indexOf(themeName);
-            const nextIndex = (currentIndex + 1) % availableThemeNames.length;
-            const newTheme = availableThemeNames[nextIndex];
-            setTheme(newTheme);
-        }, [themeName, setTheme]);
-        const managementContextValue = useMemo(() => ({
-            availableThemes: availableThemeNames,
-            setTheme,
-            theme: currentTheme,
-            themeName,
-            toggleTheme,
-        }), [currentTheme, themeName, setTheme, toggleTheme]);
-        return (_jsx(ThemeContext.Provider, { value: themeContextValue, children: _jsx(ThemeManagementContext.Provider, { value: managementContextValue, children: children }) }));
-    }
-    return {
-        Provider,
-        ThemeContext,
-        ThemeManagementContext,
-    };
-}

package/dist/api/use-theme.d.ts

@@ -1,13 +0,0 @@
-/**
- * Theme management hook.
- * Provides access to theme state and theme switching functions.
- */
-import { type Context } from "react";
-import type { ThemeManagementContextValue } from "../types";
-/**
- * Creates a useTheme hook for a specific theme management context.
- *
- * @param ThemeManagementContext - React context for theme management
- * @returns Hook function that returns theme management context value
- */
-export declare function createUseThemeHook(ThemeManagementContext: Context<ThemeManagementContextValue | null>): () => ThemeManagementContextValue;

package/dist/api/use-theme.js

@@ -1,21 +0,0 @@
-"use client";
-/**
- * Theme management hook.
- * Provides access to theme state and theme switching functions.
- */
-import { useContext } from "react";
-/**
- * Creates a useTheme hook for a specific theme management context.
- *
- * @param ThemeManagementContext - React context for theme management
- * @returns Hook function that returns theme management context value
- */
-export function createUseThemeHook(ThemeManagementContext) {
-    return function useTheme() {
-        const context = useContext(ThemeManagementContext);
-        if (!context) {
-            throw new Error("useTheme must be used within a Provider");
-        }
-        return context;
-    };
-}

package/dist/create-stoop-server.d.ts

@@ -1,33 +0,0 @@
-/**
- * Server-safe factory function that creates a Stoop instance.
- * Only includes APIs that work without React: css, globalCss, keyframes, getCssText, etc.
- * Does NOT include: styled, Provider, useTheme
- *
- * This is the entry point for Server Components in Next.js App Router.
- */
-import type { CSS, StoopConfig, Theme } from "./types";
-/**
- * Server-safe Stoop instance interface.
- * Only includes APIs that work without React dependencies.
- */
-export interface StoopServerInstance {
-    config: StoopConfig & {
-        prefix: string;
-    };
-    createTheme: (themeOverride: Partial<Theme>) => Theme;
-    css: (styles: CSS) => string;
-    getCssText: (theme?: string | Theme) => string;
-    globalCss: (...args: CSS[]) => () => void;
-    keyframes: (definition: Record<string, CSS>) => string;
-    preloadTheme: (theme: string | Theme) => void;
-    theme: Theme;
-    warmCache: (styles: CSS[]) => void;
-}
-/**
- * Creates a server-safe Stoop instance with the provided configuration.
- * Only includes APIs that work without React: css, globalCss, keyframes, getCssText, etc.
- *
- * @param config - Configuration object containing theme, media queries, utilities, and optional prefix/themeMap
- * @returns StoopServerInstance with server-safe API functions
- */
-export declare function createStoop(config: StoopConfig): StoopServerInstance;