stoop 0.3.0 → 0.4.1

package/README.md

@@ -0,0 +1,125 @@
+# stoop
+
+A lightweight, type-safe CSS-in-JS library for React with theme support, variants, and SSR capabilities.
+
+## Installation
+
+```sh
+npm install stoop
+# or
+bun add stoop
+# or
+yarn add stoop
+```
+
+## Quick Start
+
+```tsx
+import { createStoop } from "stoop";
+
+const { styled, css, Provider, useTheme } = createStoop({
+  theme: {
+    colors: {
+      primary: "#0070f3",
+      background: "#ffffff",
+      text: "#000000",
+    },
+    space: {
+      small: "8px",
+      medium: "16px",
+      large: "24px",
+    },
+  },
+  themes: {
+    light: {
+      /* ... */
+    },
+    dark: {
+      /* ... */
+    },
+  },
+});
+
+const Button = styled("button", {
+  padding: "$medium",
+  backgroundColor: "$primary",
+  color: "$text",
+});
+
+<Button>Click me</Button>;
+```
+
+## Features
+
+- **Type-safe theming** with TypeScript inference
+- **CSS variables** for instant theme switching
+- **Variant system** for component variations
+- **SSR support** via `getCssText()`
+- **Multiple themes** with built-in Provider
+- **Utility functions** for custom CSS transformations
+- **Zero runtime overhead** for theme switching
+
+## 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
+- **[TESTING.md](./docs/TESTING.md)** - Testing guide and test suite documentation
+
+## API Overview
+
+### `createStoop(config)`
+
+Creates a Stoop instance. Returns: `styled`, `css`, `createTheme`, `globalCss`, `keyframes`, `getCssText`, `warmCache`, `preloadTheme`, `theme`, `config`. If `themes` config is provided, also returns `Provider` and `useTheme`.
+
+### Theme Tokens
+
+Use `$` prefix for theme tokens. Shorthand `$token` uses property-aware resolution (preferred); explicit `$scale.token` specifies the scale.
+
+```tsx
+{
+  color: "$primary",           // Shorthand (preferred, property-aware)
+  padding: "$medium",         // Property-aware → space scale
+  fontSize: "$fontSizes.small", // Explicit scale
+}
+```
+
+### 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" />;
+```
+
+## Development
+
+```sh
+# Build
+bun run build
+
+# Test
+bun run test
+
+# Watch mode
+bun run test:watch
+```
+
+## License
+
+MIT

package/dist/api/core-api.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Core API functions.
+ * Consolidates theme creation, CSS class generation, and keyframes animation APIs.
+ */
+import type { CSS, Theme, ThemeScale, UtilityFunction } 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;
+/**
+ * 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;
+/**
+ * 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/styled.d.ts

@@ -16,7 +16,6 @@ type CSSWithVariants = {
     [K in keyof CSS]: CSS[K];
 } & {
     variants: Variants;
-    compoundVariants?: unknown[];
 };
 /**
  * Creates a styled component factory function.

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

@@ -0,0 +1,41 @@
+/**
+ * Theme Provider component and hook.
+ * Manages theme state, localStorage persistence, cookie sync, and centralized theme variable updates.
+ * Includes the useTheme hook for accessing theme management context.
+ */
+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
+ * @param globalCss - Optional global CSS object from config
+ * @param globalCssFunction - Optional globalCss function from createStoop
+ * @returns Provider component, theme context, and theme management context
+ *
+ * @remarks
+ * To prevent FOUC (Flash of Unstyled Content) when a user has a non-default theme stored,
+ * call `preloadTheme()` from your stoop instance in a script tag before React hydrates:
+ *
+ * ```html
+ * <script>
+ *   // Read theme from storage and preload before React renders
+ *   const storedTheme = localStorage.getItem('stoop-theme') || 'light';
+ *   stoopInstance.preloadTheme(storedTheme);
+ * </script>
+ * ```
+ */
+export declare function createProvider(themes: Record<string, Theme>, defaultTheme: Theme, prefix?: string, globalCss?: import("../types").CSS, globalCssFunction?: import("../types").GlobalCSSFunction): {
+    Provider: ComponentType<ProviderProps>;
+    ThemeContext: Context<ThemeContextValue | null>;
+    ThemeManagementContext: Context<ThemeManagementContextValue | null>;
+};
+/**
+ * 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/constants.d.ts

@@ -7,13 +7,23 @@ export declare const EMPTY_CSS: CSS;
 export declare const MAX_CSS_CACHE_SIZE = 10000;
 export declare const MAX_CLASS_NAME_CACHE_SIZE = 5000;
 export declare const MAX_CSS_NESTING_DEPTH = 10;
+/**
+ * Cache size limits for various LRU caches.
+ */
+export declare const KEYFRAME_CACHE_LIMIT = 500;
+export declare const SANITIZE_CACHE_SIZE_LIMIT = 1000;
+/**
+ * Cookie defaults.
+ */
+export declare const DEFAULT_COOKIE_MAX_AGE = 31536000;
+export declare const DEFAULT_COOKIE_PATH = "/";
 /**
  * Approved theme scales - only these scales are allowed in theme objects.
  */
 export declare const APPROVED_THEME_SCALES: ReadonlyArray<ThemeScale>;
 /**
  * Default themeMap mapping CSS properties to theme scales.
- * Covers 150+ common CSS properties for zero-config experience.
+ * Covers common CSS properties for zero-config experience.
  * Missing properties gracefully fallback to pattern-based auto-detection.
  */
 export declare const DEFAULT_THEME_MAP: Record<string, ThemeScale>;

package/dist/core/compiler.d.ts

@@ -4,6 +4,17 @@
  * Handles nested selectors, media queries, styled component targeting, and theme tokens.
  */
 import type { CSS, Theme, ThemeScale, UtilityFunction } from "../types";
+/**
+ * Converts a CSS object to a CSS string with proper nesting and selectors.
+ * Handles pseudo-selectors, media queries, combinators, and styled component targeting.
+ *
+ * @param obj - CSS object to convert
+ * @param selector - Current selector context
+ * @param depth - Current nesting depth
+ * @param media - Media query breakpoints
+ * @returns CSS string
+ */
+export declare function cssObjectToString(obj: CSS, selector?: string, depth?: number, media?: Record<string, string>): string;
 /**
  * Compiles CSS objects into CSS strings and generates unique class names.
  * Handles nested selectors, media queries, styled component targeting, and theme tokens.

package/dist/core/theme-manager.d.ts

@@ -14,9 +14,40 @@ import type { Theme } from "../types";
  */
 export declare function registerDefaultTheme(theme: Theme, prefix?: string): void;
 /**
- * Updates CSS custom properties when theme changes.
+ * Gets the default theme for a given prefix.
+ *
+ * @param prefix - Optional prefix for theme scoping
+ * @returns Default theme or null if not registered
+ */
+export declare function getDefaultTheme(prefix?: string): Theme | null;
+/**
+ * Core theme merging logic.
+ * Merges source theme into target theme, handling nested objects.
+ * Shared implementation used by both mergeWithDefaultTheme and createTheme.
+ *
+ * @param target - Target theme to merge into
+ * @param source - Source theme to merge from
+ * @returns Merged theme
+ */
+export declare function mergeThemes(target: Theme, source: Theme | Partial<Theme>): Theme;
+/**
+ * Merges a theme with the default theme if it's not already the default theme.
+ * This ensures all themes extend the default theme, keeping all original properties.
+ * Uses caching to avoid repeated merging of the same theme objects.
+ *
+ * @param theme - Theme to merge
+ * @param prefix - Optional prefix for theme scoping
+ * @returns Merged theme (or original if it's the default theme)
+ */
+export declare function mergeWithDefaultTheme(theme: Theme, prefix?: string): Theme;
+/**
+ * Injects CSS variables for all themes using attribute selectors.
+ * This allows all themes to be available simultaneously, with theme switching
+ * handled by changing the data-theme attribute. This prevents layout shifts
+ * and eliminates the need to replace CSS variables on theme change.
  *
- * @param theme - Theme object to generate CSS variables from
+ * @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')
  */
-export declare function updateThemeVariables(theme: Theme, prefix?: string): void;
+export declare function injectAllThemes(themes: Record<string, Theme>, prefix?: string, attribute?: string): void;

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

@@ -0,0 +1,30 @@
+/**
+ * Internal implementation for creating Stoop instances.
+ * This file is used by the SSR entry point and does NOT import React types at module level.
+ * React types are only imported conditionally when creating client instances.
+ */
+import type { CSS, StoopConfig, Theme, ThemeScale } from "./types";
+import { createCSSFunction, createKeyframesFunction } from "./api/core-api";
+import { createGlobalCSSFunction } from "./api/global-css";
+/**
+ * Shared implementation for creating Stoop instances.
+ * Handles common setup logic for both client and server instances.
+ * Exported for use in SSR entry point.
+ */
+export declare function createStoopBase(config: StoopConfig): {
+    config: StoopConfig;
+    createTheme: (overrides?: Partial<Theme>) => Theme;
+    css: ReturnType<typeof createCSSFunction>;
+    getCssText: (theme?: string | Theme) => string;
+    globalCss: ReturnType<typeof createGlobalCSSFunction>;
+    globalCssConfig: StoopConfig["globalCss"];
+    keyframes: ReturnType<typeof createKeyframesFunction>;
+    media: StoopConfig["media"];
+    mergedThemeMap: Record<string, ThemeScale>;
+    preloadTheme: (theme: string | Theme) => void;
+    sanitizedPrefix: string;
+    theme: Theme;
+    utils: StoopConfig["utils"];
+    validatedTheme: Theme;
+    warmCache: (styles: CSS[]) => void;
+};

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

@@ -0,0 +1,10 @@
+/**
+ * SSR-safe entry point for Stoop.
+ * Exports only server-safe APIs that don't require React.
+ * Use this import in Server Components: import { createStoop } from "stoop/ssr"
+ *
+ * This file does NOT import React types or create React components.
+ */
+import type { StoopConfig, StoopServerInstance } from "./types";
+export type { CSS, Theme, StoopConfig, StoopServerInstance, UtilityFunction, ThemeScale, DefaultTheme, } from "./types";
+export declare function createStoop(config: StoopConfig): StoopServerInstance;

package/dist/create-stoop-ssr.js

@@ -0,0 +1,16 @@
+var J0=Object.freeze({}),j=1e4,GJ=5000,QJ=10,FJ=500,P=1000;var c=["colors","opacities","space","radii","sizes","fonts","fontWeights","fontSizes","lineHeights","letterSpacings","shadows","zIndices","transitions"],N={accentColor:"colors",animation:"transitions",animationDelay:"transitions",animationDuration:"transitions",animationTimingFunction:"transitions",backdropFilter:"shadows",background:"colors",backgroundColor:"colors",blockSize:"sizes",border:"colors",borderBlockColor:"colors",borderBlockEndColor:"colors",borderBlockStartColor:"colors",borderBottomColor:"colors",borderBottomLeftRadius:"radii",borderBottomRightRadius:"radii",borderColor:"colors",borderEndEndRadius:"radii",borderEndStartRadius:"radii",borderInlineColor:"colors",borderInlineEndColor:"colors",borderInlineStartColor:"colors",borderLeftColor:"colors",borderRadius:"radii",borderRightColor:"colors",borderStartEndRadius:"radii",borderStartStartRadius:"radii",borderTopColor:"colors",borderTopLeftRadius:"radii",borderTopRightRadius:"radii",bottom:"space",boxShadow:"shadows",caretColor:"colors",color:"colors",columnGap:"space",columnRuleColor:"colors",fill:"colors",filter:"shadows",flexBasis:"sizes",floodColor:"colors",font:"fontSizes",fontFamily:"fonts",fontSize:"fontSizes",fontWeight:"fontWeights",gap:"space",gridColumnGap:"space",gridGap:"space",gridRowGap:"space",height:"sizes",inlineSize:"sizes",inset:"space",insetBlock:"space",insetBlockEnd:"space",insetBlockStart:"space",insetInline:"space",insetInlineEnd:"space",insetInlineStart:"space",left:"space",letterSpacing:"letterSpacings",lightingColor:"colors",lineHeight:"lineHeights",margin:"space",marginBlock:"space",marginBlockEnd:"space",marginBlockStart:"space",marginBottom:"space",marginInline:"space",marginInlineEnd:"space",marginInlineStart:"space",marginLeft:"space",marginRight:"space",marginTop:"space",maxBlockSize:"sizes",maxHeight:"sizes",maxInlineSize:"sizes",maxWidth:"sizes",minBlockSize:"sizes",minHeight:"sizes",minInlineSize:"sizes",minWidth:"sizes",opacity:"opacities",outline:"colors",outlineColor:"colors",padding:"space",paddingBlock:"space",paddingBlockEnd:"space",paddingBlockStart:"space",paddingBottom:"space",paddingInline:"space",paddingInlineEnd:"space",paddingInlineStart:"space",paddingLeft:"space",paddingRight:"space",paddingTop:"space",right:"space",rowGap:"space",size:"sizes",stopColor:"colors",stroke:"colors",textDecorationColor:"colors",textEmphasisColor:"colors",textShadow:"shadows",top:"space",transition:"transitions",transitionDelay:"transitions",transitionDuration:"transitions",transitionProperty:"transitions",transitionTimingFunction:"transitions",width:"sizes",zIndex:"zIndices"},ZJ=Symbol.for("stoop.component");class L extends Map{maxSize;constructor(J){super();this.maxSize=J}get(J){let $=super.get(J);if($!==void 0)super.delete(J),super.set(J,$);return $}set(J,$){if(super.has(J))super.delete(J);else if(this.size>=this.maxSize){let Y=this.keys().next().value;if(Y!==void 0)super.delete(Y)}return super.set(J,$),this}}var WJ=new L(GJ),n=new L(j);function K(){return typeof window!=="undefined"&&typeof document!=="undefined"&&typeof window.document==="object"&&typeof document.createElement==="function"}function g(){return typeof process!=="undefined"&&process.env?.NODE_ENV==="production"}function v(J){return typeof J==="object"&&J!==null}function p(J){return typeof J==="object"&&J!==null&&"__isStoopStyled"in J&&"__stoopClassName"in J&&J.__isStoopStyled===!0}function m(J){return v(J)&&!p(J)}function o(J){return typeof J==="object"&&J!==null&&!Array.isArray(J)}function x(J){if(!J||typeof J!=="object"||Array.isArray(J))throw new Error("[Stoop] Theme must be a non-null object");if(g())return J;let $=J,Y=[];for(let q in $){if(q==="media")continue;if(!c.includes(q))Y.push(q)}if(Y.length>0){let q=`[Stoop] Theme contains invalid scales: ${Y.join(", ")}. Only these scales are allowed: ${c.join(", ")}`;throw new Error(q)}return J}function z(J,$){if(!$||!J||typeof J!=="object")return J;let Y={},q=Object.keys($);for(let X in J){let F=J[X];if(q.includes(X)&&$[X])try{let Q=$[X](F);if(Q&&typeof Q==="object")for(let Z in Q)Y[Z]=Q[Z]}catch{Y[X]=F}else if(v(F))Y[X]=z(F,$);else Y[X]=F}return Y}var l=null,DJ=new L(P),wJ=new L(P),Z0=new L(P),HJ=new L(P);function b(J){let q=2166136261;for(let X=0;X<J.length;X++)q^=J.charCodeAt(X),q=Math.imul(q,16777619);return q^=J.length,(q>>>0).toString(36)}function T(J){try{return b(JSON.stringify(J))}catch{return b(String(J))}}function cJ(J){return J.replace(/([A-Z])/g,"-$1").toLowerCase()}function UJ(J,$=!1){let q=String(J).replace(/\\/g,"\\\\").replace(/"/g,"\\\"").replace(/'/g,"\\'").replace(/;/g,"\\;").replace(/\n/g,"\\A ").replace(/\r/g,"").replace(/\f/g,"\\C ");if($)q=q.replace(/\{/g,"\\7B ").replace(/\}/g,"\\7D ");return q}function BJ(J){return UJ(J,!1)}function I(J){let $=DJ.get(J);if($!==void 0)return $;let Y=J.replace(/[^a-zA-Z0-9\s\-_>+~:.#[\]&@()]/g,""),q=!Y.trim()||/^[>+~:.#[\]&@()\s]+$/.test(Y)?"":Y;return DJ.set(J,q),q}function R(J){let $=HJ.get(J);if($!==void 0)return $;let X=J.replace(/[^a-zA-Z0-9-_]/g,"-").replace(/^[\d-]+/,"").replace(/^-+/,"")||"invalid";return HJ.set(J,X),X}function LJ(J){return UJ(J,!0)}function B(J){if(!J)return"stoop";return J.replace(/[^a-zA-Z0-9-_]/g,"").replace(/^[\d-]+/,"").replace(/^-+/,"")||"stoop"}function _J(J){if(!J||typeof J!=="string")return"";let $=J.replace(/[^a-zA-Z0-9\s():,<>=\-@]/g,"");if(!$.trim()||!/[a-zA-Z]/.test($))return"";return $}function C(J){if(!J||typeof J!=="string")return"";let $=wJ.get(J);if($!==void 0)return $;let X=cJ(J).replace(/[^a-zA-Z0-9-]/g,"").replace(/^-+|-+$/g,"").replace(/^\d+/,"")||"";return wJ.set(J,X),X}function AJ(J){if(!J||typeof J!=="string")return!1;if(J==="from"||J==="to")return!0;if(/^\d+(\.\d+)?%$/.test(J)){let Y=parseFloat(J);return Y>=0&&Y<=100}return!1}function KJ(J=""){if(!l){let Y=":root".replace(/[.*+?^${}()|[\]\\]/g,"\\$&");l=new RegExp(`${Y}\\s*\\{[\\s\\S]*\\}`)}return l}function nJ(J){if(J.includes("Color")||J==="fill"||J==="stroke"||J==="accentColor"||J==="caretColor"||J==="border"||J==="outline"||J.includes("background")&&!J.includes("Size")&&!J.includes("Image"))return"colors";if(/^(margin|padding|gap|inset|top|right|bottom|left|rowGap|columnGap|gridGap|gridRowGap|gridColumnGap)/.test(J)||J.includes("Block")||J.includes("Inline"))return"space";if(/(width|height|size|basis)$/i.test(J)||J.includes("BlockSize")||J.includes("InlineSize"))return"sizes";if(J==="fontSize"||J==="font"&&!J.includes("Family"))return"fontSizes";if(J==="fontFamily"||J.includes("FontFamily"))return"fonts";if(J==="fontWeight"||J.includes("FontWeight"))return"fontWeights";if(J==="letterSpacing"||J.includes("LetterSpacing"))return"letterSpacings";if(J.includes("Radius")||J.includes("radius"))return"radii";if(J.includes("Shadow")||J.includes("shadow")||J==="filter"||J==="backdropFilter")return"shadows";if(J==="zIndex"||J.includes("ZIndex")||J.includes("z-index"))return"zIndices";if(J==="opacity"||J.includes("Opacity"))return"opacities";if(J.startsWith("transition")||J.startsWith("animation")||J.includes("Transition")||J.includes("Animation"))return"transitions";return}function OJ(J,$){if($&&J in $)return $[J];if(J in N)return N[J];return nJ(J)}var r=new Map;function S(J){return r.has(J)}function f(J,$){r.set(J,$)}var i=new L(j);function MJ(J){if(!i.has(J))i.set(J,!0)}function IJ(){return Array.from(i.keys()).join(`
+`)}var k=new Map;var RJ=new Map;function EJ(J="stoop"){if(!K())throw new Error("Cannot access document in SSR context");let $=B(J),Y=k.get($);if(!Y||!Y.parentNode){let q=document.getElementById("stoop-ssr");if(q){let X=q.getAttribute("data-stoop");if(!X||X===$)return Y=q,Y.setAttribute("data-stoop",$),k.set($,Y),Y}Y=document.createElement("style"),Y.setAttribute("data-stoop",$),Y.setAttribute("id",`stoop-${$}`),document.head.appendChild(Y),k.set($,Y)}return Y}function a(J){let $=J,Y=KJ("");$=$.replace(Y,"").trim();let q=$.indexOf("[data-theme=");while(q!==-1){let X=$.indexOf("{",q);if(X===-1)break;let F=1,Q=X+1;while(Q<$.length&&F>0){if($[Q]==="{")F++;else if($[Q]==="}")F--;Q++}if(F===0){let Z=$.substring(0,q).trim(),G=$.substring(Q).trim();$=(Z+`
+`+G).trim()}else break;q=$.indexOf("[data-theme=")}return $.trim()}function VJ(J,$="stoop"){if(!J)return;let Y=B($),q=`__all_theme_vars_${Y}`;if((RJ.get(q)??null)===J)return;if(RJ.set(q,J),!K()){MJ(J);return}let F=EJ(Y),Q=F.textContent||"",Z=Q.includes(":root")||Q.includes("[data-theme=");if(S(q)||Z){let G=a(Q);F.textContent=J+(G?`
+
+`+G:""),f(q,J)}else F.textContent=J+(Q?`
+
+`+Q:""),f(q,J)}function pJ(J,$,Y="stoop"){if(!K())return;let q=B(Y);if(S($))return;let X=EJ(q),F=X.textContent||"";X.textContent=F+(F?`
+`:"")+J,f($,J)}function mJ(J,$,Y="stoop"){if(S($))return;let q=B(Y);pJ(J,$,q)}function oJ(J="stoop"){let $=B(J);return k.get($)||null}function lJ(){return new Map(r)}function M(J,$="stoop",Y){let q=Y||J;if(!K()){if(!S(q))f(q,J);MJ(J);return}mJ(J,q,$)}function PJ(J="stoop"){if(K()){let $=B(J),Y=oJ($);if(Y&&Y.parentNode){let q=Y.textContent||"";if(!q&&lJ().size>0)return IJ();return q}}return IJ()}var iJ=/(-?\$[a-zA-Z][a-zA-Z0-9]*(?:\$[a-zA-Z][a-zA-Z0-9]*)?(?:\.[a-zA-Z][a-zA-Z0-9]*)?)/g;function t(J){let $=new Map;function Y(q,X=[]){let F=Object.keys(q);for(let Q of F){let Z=q[Q],G=[...X,Q];if(o(Z))Y(Z,G);else{let D=$.get(Q);if(D)D.push(G);else $.set(Q,[G])}}}Y(J);for(let[,q]of $.entries())if(q.length>1)q.sort((X,F)=>{let Q=X.length-F.length;if(Q!==0)return Q;let Z=X.join("."),G=F.join(".");return Z.localeCompare(G)});return $}function rJ(J,$){let Y=Object.keys(J).filter((X)=>X!=="media"),q=Object.keys($).filter((X)=>X!=="media");if(Y.length!==q.length)return!1;for(let X of Y)if(!(X in $))return!1;return!0}function zJ(J,$){if(J===$)return!0;if(!J||!$)return!1;if(!rJ(J,$))return!1;let Y={...J},q={...$};return delete Y.media,delete q.media,JSON.stringify(Y)===JSON.stringify(q)}function s(J,$,Y){if(Y&&Y in J){let F=J[Y];if(F&&typeof F==="object"&&!Array.isArray(F)&&$ in F)return[Y,$]}let X=t(J).get($);if(!X||X.length===0)return null;return X[0]}function NJ(J,$,Y,q){if(!J.startsWith("$"))return J;let X=J.slice(1);if(X.includes("$")||X.includes("."))return`var(${`--${(X.includes("$")?X.split("$"):X.split(".")).map((W)=>R(W)).join("-")}`})`;if($&&Y){let Z=OJ(Y,q);if(Z){let w=s($,X,Z);if(w)return`var(${`--${w.map((A)=>R(A)).join("-")}`})`}let D=t($).get(X);if(D&&D.length>1){if(!g()){let w=Z?`Property "${Y}" maps to "${Z}" scale, but token not found there. `:`No scale mapping found for property "${Y}". `;console.warn(`[Stoop] Ambiguous token "$${X}" found in multiple categories: ${D.map((H)=>H.join(".")).join(", ")}. ${w}Using "${D[0].join(".")}" (deterministic: shorter paths first, then alphabetical). Use full path "$${D[0].join(".")}" to be explicit.`)}}let W=s($,X);if(W)return`var(${`--${W.map((U)=>R(U)).join("-")}`})`}else if($){let G=t($).get(X);if(G&&G.length>1){if(!g())console.warn(`[Stoop] Ambiguous token "$${X}" found in multiple categories: ${G.map((W)=>W.join(".")).join(", ")}. Using "${G[0].join(".")}" (deterministic: shorter paths first, then alphabetical). Use full path "$${G[0].join(".")}" to be explicit, or use with a CSS property for automatic resolution.`)}let D=s($,X);if(D)return`var(${`--${D.map((H)=>R(H)).join("-")}`})`}return`var(${`--${R(X)}`})`}function e(J,$="stoop",Y){let q=Y||":root",X=[];function F(Q,Z=[]){let G=Object.keys(Q).sort();for(let D of G){if(D==="media")continue;let W=Q[D],w=[...Z,D];if(o(W))F(W,w);else{let U=`--${w.map((y)=>R(y)).join("-")}`,A=typeof W==="string"||typeof W==="number"?LJ(W):String(W);X.push(`  ${U}: ${A};`)}}}if(F(J),X.length===0)return"";return`${q} {
+${X.join(`
+`)}
+}`}function d(J,$="stoop",Y="data-theme"){let q=[];for(let[X,F]of Object.entries(J)){let Q=`[${Y}="${X}"]`,Z=e(F,$,Q);if(Z)q.push(Z)}return q.join(`
+
+`)}function E(J,$,Y,q){if(!J||typeof J!=="object")return J;let X={},F=!1,Q=Object.keys(J).sort();for(let Z of Q){let G=J[Z];if(v(G)){let D=E(G,$,Y,void 0);if(X[Z]=D,D!==G)F=!0}else if(typeof G==="string"&&G.includes("$")){F=!0;let D=q||Z;X[Z]=G.replace(iJ,(W)=>{if(W.startsWith("-$")){let w=W.slice(1);return`calc(-1 * ${NJ(w,$,D,Y)})`}return NJ(W,$,D,Y)})}else X[Z]=G}if(!F)return J;return X}function aJ(J,$){if(typeof J==="symbol"&&J===ZJ)return!0;if(p($))return!0;if(typeof J==="string"&&J.startsWith("__STOOP_COMPONENT_"))return!0;return!1}function sJ(J,$){if(typeof $==="object"&&$!==null&&"__stoopClassName"in $&&typeof $.__stoopClassName==="string")return $.__stoopClassName;if(typeof J==="string"&&J.startsWith("__STOOP_COMPONENT_"))return J.replace("__STOOP_COMPONENT_","");return""}function _(J,$="",Y=0,q){if(!J||typeof J!=="object")return"";if(Y>QJ)return"";let X=[],F=[],Q=Object.keys(J).sort();for(let G of Q){let D=J[G];if(aJ(G,D)){let W=sJ(G,D);if(!W)continue;let w=I(W);if(!w)continue;let H=$?`${$} .${w}`:`.${w}`,U=m(D)?_(D,H,Y+1,q):"";if(U)F.push(U);continue}if(m(D))if(q&&G in q){let W=_J(q[G]);if(W){let w=_(D,$,Y+1,q);if(w)F.push(`${W} { ${w} }`)}}else if(G.startsWith("@")){let W=I(G);if(W){let w=_(D,$,Y+1,q);if(w)F.push(`${W} { ${w} }`)}}else if(G.includes("&")){let W=I(G);if(W){let H=W.split("&").join($),U=_(D,H,Y+1,q);if(U)F.push(U)}}else if(G.startsWith(":")){let W=I(G);if(W){let w=`${$}${W}`,H=_(D,w,Y+1,q);if(H)F.push(H)}}else if(G.includes(" ")||G.includes(">")||G.includes("+")||G.includes("~")){let W=I(G);if(W){let H=/^[\s>+~]/.test(W.trim())?`${$}${W}`:`${$} ${W}`,U=_(D,H,Y+1,q);if(U)F.push(U)}}else{let W=I(G);if(W){let w=$?`${$} ${W}`:W,H=_(D,w,Y+1,q);if(H)F.push(H)}}else if(D!==void 0){let W=C(G);if(W&&(typeof D==="string"||typeof D==="number")){let w=BJ(D);X.push(`${W}: ${w};`)}}}let Z=[];if(X.length>0)Z.push(`${$} { ${X.join(" ")} }`);return Z.push(...F),Z.join("")}function u(J,$,Y="stoop",q,X,F){let Q=B(Y),Z=z(J,X),G=E(Z,$,F),D=_(G,"",0,q),W=b(D),w=Q?`${Q}-${W}`:`css-${W}`,H=`${Q}:${w}`,U=n.get(H);if(U)return M(U,Q,H),w;let A=_(G,`.${w}`,0,q);return n.set(H,A),WJ.set(H,w),M(A,Q,H),w}var jJ=new Map;function gJ(J,$="stoop"){let Y=$||"";jJ.set(Y,J)}function tJ(J="stoop"){let $=J||"";return jJ.get($)||null}function JJ(J,$){let Y={...J},q=Object.keys($);for(let X of q){if(X==="media")continue;let F=$[X],Q=J[X];if(F&&typeof F==="object"&&!Array.isArray(F)&&Q&&typeof Q==="object"&&!Array.isArray(Q))Y[X]={...Q,...F};else if(F!==void 0)Y[X]=F}return Y}function $J(J,$="stoop"){let Y=tJ($);if(!Y)return J;if(zJ(J,Y))return J;return JJ(Y,J)}function vJ(J,$="stoop",Y="data-theme"){if(!K())return;let q={};for(let[F,Q]of Object.entries(J))q[F]=$J(Q,$);let X=d(q,$,Y);VJ(X,$)}function xJ(J){return function $(Y={}){let q=x(Y);return JJ(J,q)}}function bJ(J,$="stoop",Y,q,X){return function F(Q){return u(Q,J,$,Y,q,X)}}function eJ(J,$,Y,q){let X=`@keyframes ${$} {`,F=Object.keys(J).sort((Q,Z)=>{let G=parseFloat(Q.replace("%","")),D=parseFloat(Z.replace("%",""));if(Q==="from")return-1;if(Z==="from")return 1;if(Q==="to")return 1;if(Z==="to")return-1;return G-D});for(let Q of F){if(!AJ(Q))continue;let Z=J[Q];if(!Z||typeof Z!=="object")continue;X+=` ${Q} {`;let G=E(Z,Y,q),D=Object.keys(G).sort();for(let W of D){let w=G[W];if(w!==void 0&&(typeof w==="string"||typeof w==="number")){let H=C(W);if(H){let U=String(w);X+=` ${H}: ${U};`}}}X+=" }"}return X+=" }",X}function TJ(J="stoop",$,Y){let q=B(J),X=new L(FJ);return function F(Q){let Z=T(Q),G=X.get(Z);if(G)return G;let D=Z.slice(0,8),W=q?`${q}-${D}`:`stoop-${D}`,w=eJ(Q,W,$,Y),H=`__keyframes_${W}`;return M(w,q,H),X.set(Z,W),W}}var YJ=new Set;function CJ(J,$="stoop",Y,q,X){return function F(Q){let Z=T(Q);if(YJ.has(Z))return()=>{};YJ.add(Z);let G=B($),D=z(Q,q),W=E(D,J,X),w=_(W,"",0,Y);return M(w,G,`__global_${Z}`),()=>{YJ.delete(Z)}}}function kJ(J){let{globalCss:$,media:Y,prefix:q="stoop",theme:X,themeMap:F,utils:Q}=J,Z=B(q),G=x(X),D=G.media||Y,W={...N,...F};gJ(G,Z);let w=bJ(G,Z,D,Q,W),H=xJ(G),U=CJ(G,Z,D,Q,W),A=TJ(Z,G,W),y=Object.freeze({...G});function fJ(h){for(let O of h)try{u(O,G,Z,D,Q,W)}catch{}}function SJ(h){if(!J.themes||Object.keys(J.themes).length===0)return;vJ(J.themes,Z)}function dJ(h){let O="";if(J.themes&&Object.keys(J.themes).length>0){let V={};for(let[yJ,hJ]of Object.entries(J.themes))V[yJ]=$J(hJ,Z);let XJ=d(V,Z,"data-theme");if(XJ)O+=XJ+`
+`}else{let V=e(G,Z);if(V)O+=V+`
+`}let uJ=PJ(),qJ=a(uJ).trim();if(qJ)O+=(O?`
+`:"")+qJ;return O}return{config:{...J,prefix:Z},createTheme:H,css:w,getCssText:dJ,globalCss:U,globalCssConfig:$,keyframes:A,media:D,mergedThemeMap:W,preloadTheme:SJ,sanitizedPrefix:Z,theme:y,utils:Q,validatedTheme:G,warmCache:fJ}}function Y1(J){let $=kJ(J);return{config:{...$.config,prefix:$.sanitizedPrefix},createTheme:$.createTheme,css:$.css,getCssText:$.getCssText,globalCss:$.globalCss,keyframes:$.keyframes,preloadTheme:$.preloadTheme,theme:$.theme,warmCache:$.warmCache}}export{Y1 as createStoop};

package/dist/create-stoop.d.ts

@@ -1,9 +1,40 @@
-import type { StoopConfig, StoopInstance } from "./types";
+/**
+ * Factory function that creates a Stoop instance.
+ * Supports both client-side (with React APIs) and server-side (without React) usage.
+ * Automatically detects environment and includes appropriate APIs.
+ */
+import type { CSS, StoopConfig, StoopInstance, Theme, ThemeScale } from "./types";
+import { createCSSFunction, createKeyframesFunction } from "./api/core-api";
+import { createGlobalCSSFunction } from "./api/global-css";
+/**
+ * Shared implementation for creating Stoop instances.
+ * Handles common setup logic for both client and server instances.
+ * Exported for use in SSR entry point.
+ */
+export declare function createStoopBase(config: StoopConfig): {
+    config: StoopConfig;
+    createTheme: (overrides?: Partial<Theme>) => Theme;
+    css: ReturnType<typeof createCSSFunction>;
+    getCssText: (theme?: string | Theme) => string;
+    globalCss: ReturnType<typeof createGlobalCSSFunction>;
+    globalCssConfig: StoopConfig["globalCss"];
+    keyframes: ReturnType<typeof createKeyframesFunction>;
+    media: StoopConfig["media"];
+    mergedThemeMap: Record<string, ThemeScale>;
+    preloadTheme: (theme: string | Theme) => void;
+    sanitizedPrefix: string;
+    theme: Theme;
+    utils: StoopConfig["utils"];
+    validatedTheme: Theme;
+    warmCache: (styles: CSS[]) => void;
+};
 /**
  * Creates a Stoop instance with the provided configuration.
  * Includes all APIs: styled, Provider, useTheme, etc.
+ * In server contexts without React, React APIs will be undefined.
  *
  * @param config - Configuration object containing theme, media queries, utilities, and optional prefix/themeMap
  * @returns StoopInstance with all API functions
  */
+export type { CSS, Theme, StoopConfig, StoopInstance, UtilityFunction, ThemeScale, DefaultTheme, } from "./types";
 export declare function createStoop(config: StoopConfig): StoopInstance;