stoop 0.2.0 → 0.3.0

package/dist/utils/theme.js

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

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

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "stoop",
   "description": "CSS-in-JS library with type inference, theme creation, and variants support.",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "author": "Jackson Dolman <mail@dolmios.com>",
   "main": "./dist/index.js",
   "repository": {
@@ -16,22 +16,24 @@
     "react-polymorphic-types": "^2.0.0"
   },
   "devDependencies": {
-    "@types/node": "^22.17.0",
-    "@types/react": "^19.1.9",
-    "@types/react-dom": "^19.1.7",
-    "bun-types": "^1.2.19",
-    "eslint": "^9.32.0",
-    "eslint-config-dolmios": "^2.0.10",
-    "prettier": "^3.6.2",
-    "react": "^19.1.1",
-    "react-dom": "^19.1.1",
-    "typescript": "^5.9.2"
+    "@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"
   },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "require": "./dist/index.js"
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./ssr": {
+      "types": "./dist/ssr.d.ts",
+      "import": "./dist/ssr.js",
+      "require": "./dist/ssr.js",
+      "default": "./dist/ssr.js"
     }
   },
   "files": [
@@ -66,24 +68,21 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "react": ">=19.0.0",
-    "react-dom": ">=19.0.0"
+    "react": ">=16.8.0",
+    "react-dom": ">=16.8.0"
   },
-  "prettier": "eslint-config-dolmios/configs/prettier",
-  "sideEffects": false,
-  "type": "module",
   "scripts": {
-    "build": "bun run build:clean && bun run build:js && bun run build:types && bun run build:copy-declarations",
+    "build": "bun run build:clean && 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 || true",
-    "build:js": "bun build ./src/index.ts --outdir ./dist --target browser --minify --jsx=react --splitting --external react --external react-dom",
-    "build:types": "bunx tsc src/index.ts src/**/*.ts --declaration --emitDeclarationOnly --outDir dist --skipLibCheck --jsx react-jsx --module ESNext --moduleResolution bundler --target ES2022 --lib dom,dom.iterable,esnext --rootDir src",
-    "dev": "bun run build && bun --bun preview/index.html",
-    "format": "prettier --write src preview",
-    "kill": "lsof -ti:3000,420 | xargs kill -9 2>/dev/null || true",
-    "lint": "eslint . --ext .ts,.tsx --fix",
+    "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:types": "bunx tsc --project tsconfig.build.json && bun run build:copy-declarations",
+    "prepare": "bun run build",
     "test": "bun test",
     "test:coverage": "bun test --coverage",
     "test:watch": "bun test --watch"
-  }
-}
+  },
+  "sideEffects": false,
+  "type": "module"
+}
+

package/LICENSE.md

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Jackson Dolman
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/README.md

@@ -1,180 +0,0 @@
-# Stoop
-
-CSS-in-JS library with type inference, theme creation, and variants support.
-
-[![npm version](https://img.shields.io/npm/v/stoop)](https://www.npmjs.com/package/stoop)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-> **Warning: Not Production Ready**
-> Stoop is currently in active development and is not recommended for production use. The API may change, and there may be bugs or missing features. Use at your own risk.
-
-## About
-
-Stoop is a CSS-in-JS library—a TypeScript-first approach to styling that provides type-safe CSS objects with full type inference. Similar to [Stitches](https://stitches.dev) and [Vanilla Extract](https://vanilla-extract.style), Stoop focuses on type safety and developer experience.
-
-Stoop is a minimalist implementation of Stitches' high-level features. It provides a similar API for `styled`, `css`, and variants, but omits several Stitches features.
-
-**What's missing compared to Stitches:**
-- Compound variants
-- Build-time CSS extraction (runtime-only)
-- Advanced utility functions (basic support only)
-- Additional Stitches APIs
-
-If you need these features, consider [Vanilla Extract](https://vanilla-extract.style) or [styled-components](https://styled-components.com).
-
-## Features
-
-- Type-safe theming with TypeScript inference
-- CSS variables for theme tokens
-- Variant system for component variations
-- Utility functions for custom CSS transformations
-- Multiple themes with `createTheme()`
-- SSR support via `getCssText()`
-- React 19+ required (Next.js Pages & App Router supported)
-
-## Installation
-
-```sh
-npm install stoop
-# or
-bun add stoop
-# or
-yarn add stoop
-```
-
-## Quick Start
-
-```tsx
-import { createStoop } from "stoop";
-
-const { styled, css, createTheme, globalCss, keyframes, ThemeContext } = createStoop({
-  theme: {
-    colors: {
-      primary: "#0070f3",
-      background: "#ffffff",
-      text: "#000000",
-    },
-    space: {
-      small: "8px",
-      medium: "16px",
-      large: "24px",
-    },
-  },
-});
-
-const Button = styled("button", {
-  padding: "$medium",
-  backgroundColor: "$primary",
-}, {
-  variant: {
-    primary: { backgroundColor: "$primary" },
-    secondary: { backgroundColor: "$secondary" },
-  },
-});
-
-<Button variant="primary">Click me</Button>
-```
-
-See [GUIDE.md](./docs/GUIDE.md) for complete setup instructions.
-
-## Documentation
-
-- **[GUIDE.md](./docs/GUIDE.md)** - Step-by-step setup and usage guide
-- **[API.md](./docs/API.md)** - Complete API reference
-- **[ARCHITECTURE.md](./docs/ARCHITECTURE.md)** - Internal implementation details
-
-## API Overview
-
-### `createStoop(config)`
-
-Creates a Stoop instance. Returns: `styled`, `css`, `createTheme`, `globalCss`, `keyframes`, `getCssText`, `warmCache`, `ThemeContext`, `theme`, `config`.
-
-See [API.md](./docs/API.md) for complete API documentation.
-
-### Theme Tokens
-
-Use `$` prefix for theme tokens. Shorthand `$token` searches all scales; explicit `$scale.token` specifies the scale.
-
-```tsx
-{
-  color: "$primary",           // Shorthand (preferred)
-  padding: "$medium",          // Property-aware resolution
-  fontSize: "$fontSizes.small", // Explicit scale
-}
-```
-
-Tokens resolve to CSS variables (`var(--colors-primary)`), enabling instant theme switching without recompiling CSS.
-
-### Variants
-
-Variants create component variations via props:
-
-```tsx
-const Button = styled("button", {}, {
-  variant: {
-    primary: { backgroundColor: "$primary" },
-    secondary: { backgroundColor: "$secondary" },
-  },
-  size: {
-    small: { padding: "$small" },
-    large: { padding: "$large" },
-  },
-});
-
-<Button variant="primary" size="small" />
-```
-
-## Migration from Stitches
-
-Stoop provides a similar API for the features it implements. Key differences:
-- CSS variables for theme tokens
-- Simple theme system with `createTheme()`
-- Full TypeScript inference
-
-See [GUIDE.md](./docs/GUIDE.md) for migration examples.
-
-## Related Projects
-
-**CSS-in-JS Libraries:**
-- [Stitches](https://stitches.dev) - Original library Stoop is based on (no longer maintained)
-- [Stitches](https://stitches.dev) - CSS-in-JS library (original inspiration)
-- [Vanilla Extract](https://vanilla-extract.style) - Zero-runtime CSS-in-JS
-- [styled-components](https://styled-components.com) - CSS-in-JS library
-- [Emotion](https://emotion.sh) - CSS-in-JS library
-- [Goober](https://goober.rocks) - Lightweight CSS-in-JS library
-- [JSS](https://cssinjs.org) - Framework-agnostic CSS-in-JS
-- [Compiled](https://compiledcssinjs.com) - Compile-time CSS-in-JS
-- [Stylex](https://stylexjs.com) - Facebook's build-time CSS-in-JS
-- [Panda CSS](https://panda-css.com) - CSS-in-JS with build-time generation
-- [Linaria](https://linaria.dev) - Zero-runtime CSS-in-JS
-- [Treat](https://seek-oss.github.io/treat) - Themeable CSS-in-JS
-
-**Variant Systems:**
-- [CVA](https://cva.style) - Class Variance Authority for component variants
-- [clsx](https://github.com/lukeed/clsx) - Tiny utility for constructing className strings
-
-**Utility-First:**
-- [Tailwind CSS](https://tailwindcss.com) - Utility-first CSS framework
-- [UnoCSS](https://unocss.dev) - Instant atomic CSS engine
-
-**Component Libraries:**
-- [Radix UI](https://www.radix-ui.com) - Unstyled, accessible component primitives
-- [Chakra UI](https://chakra-ui.com) - Component library built on Emotion
-- [Mantine](https://mantine.dev) - React components library with Emotion
-
-## Development
-
-```sh
-bun install
-bun run dev
-bun run build
-bun run lint
-```
-
-## Contributing
-
-Contributions welcome. See [ARCHITECTURE.md](./docs/ARCHITECTURE.md) for implementation details.
-
-## License
-
-MIT © [Jackson Dolman](https://github.com/dolmios)