stoop 0.1.0 → 0.2.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+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,88 +1,179 @@
-# [stoop](https://github.com/dolmios/stoop)
+# Stoop
 
-> A lightweight, polymorphic React component library with intuitive design tokens and built-in theming system.
+CSS-in-JS library with type inference, theme creation, and variants support.
 
-![Stoop Kid Steps Off](https://nomeatballs.files.wordpress.com/2012/08/stoop-kid-steps-off.png)
+[![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)
 
-## Install
+> **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
 ```
 
-## Usage
-
-### Setup Provider
-
-Wrap your app with the `StoopProvider`:
+## Quick Start
 
 ```tsx
-import { StoopProvider } from "stoop";
-
-function App() {
-  return (
-    <StoopProvider theme="light">
-      {/* Your app content */}
-    </StoopProvider>
-  );
-}
+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>
 ```
 
-### Using Components
+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
-import { Stack, Text, Button } from "stoop";
-
-function MyComponent() {
-  return (
-    <Stack gap="medium">
-      <Text as="h1">Welcome</Text>
-      <Button>Click me</Button>
-    </Stack>
-  );
+{
+  color: "$primary",           // Shorthand (preferred)
+  padding: "$medium",          // Property-aware resolution
+  fontSize: "$fontSizes.small", // Explicit scale
 }
 ```
 
-### Theme Switching
+Tokens resolve to CSS variables (`var(--colors-primary)`), enabling instant theme switching without recompiling CSS.
+
+### Variants
+
+Variants create component variations via props:
 
 ```tsx
-import { useTheme, Button } from "stoop";
-
-function ThemeToggle() {
-  const { themeName, setTheme } = useTheme();
-  
-  return (
-    <Button onClick={() => setTheme(themeName === 'light' ? 'dark' : 'light')}>
-      Switch to {themeName === 'light' ? 'Dark' : 'Light'}
-    </Button>
-  );
-}
+const Button = styled("button", {}, {
+  variant: {
+    primary: { backgroundColor: "$primary" },
+    secondary: { backgroundColor: "$secondary" },
+  },
+  size: {
+    small: { padding: "$small" },
+    large: { padding: "$large" },
+  },
+});
+
+<Button variant="primary" size="small" />
 ```
 
-## Development
+## 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
 
-For local development:
+**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
-# Install dependencies
 bun install
-
-# Start development server
 bun run dev
-
-# Build the library
 bun run build
-
-# Lint and format
 bun run lint
-bun run prettier
 ```
 
 ## Contributing
 
-Feel free to get in touch with feedback, advice or suggestions. See [Conventional Commits](https://gist.github.com/dolmios/0e33c579a500d87fc6f44df6cde97259) for new contributors.
+Contributions welcome. See [ARCHITECTURE.md](./docs/ARCHITECTURE.md) for implementation details.
 
 ## License
 

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

@@ -0,0 +1,13 @@
+/**
+ * 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/css.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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/global-css.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Global CSS injection API.
+ * Creates a function that injects global styles into the document.
+ * Supports media queries, nested selectors, and theme tokens.
+ */
+import type { CSS, Theme, ThemeScale, UtilityFunction } from "../types";
+/**
+ * Creates a global CSS injection function.
+ * Injects styles directly into the document with deduplication support.
+ *
+ * @param defaultTheme - Default theme for token resolution
+ * @param prefix - Optional prefix for CSS rules
+ * @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 a cleanup function
+ */
+export declare function createGlobalCSSFunction(defaultTheme: Theme, prefix?: string, media?: Record<string, string>, utils?: Record<string, UtilityFunction>, themeMap?: Record<string, ThemeScale>): (styles: CSS) => () => void;

package/dist/api/keyframes.d.ts

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

@@ -0,0 +1,19 @@
+/**
+ * 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 ThemeContext - Stoop's theme context for styled components
+ * @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 and theme management context
+ */
+export declare function createProvider(ThemeContext: Context<ThemeContextValue | null>, themes: Record<string, Theme>, defaultTheme: Theme, prefix?: string): {
+    Provider: ComponentType<ProviderProps>;
+    ThemeManagementContext: Context<ThemeManagementContextValue | null>;
+};

package/dist/api/styled.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Styled component API.
+ * Creates polymorphic styled components with variant support, theme awareness,
+ * and CSS prop merging. Supports component targeting via selector references.
+ */
+import { forwardRef, type Context } from "react";
+import type { CSS, StyledComponentProps, StyledComponentRef, StylableElement, Theme, ThemeContextValue, ThemeScale, UtilityFunction, Variants } from "../types";
+/**
+ * Creates a styled component reference for selector targeting.
+ *
+ * @param className - Class name to reference
+ * @returns StyledComponentRef for use in CSS selectors
+ */
+export declare function createStyledComponentRef(className: string): StyledComponentRef;
+type CSSWithVariants = {
+    [K in keyof CSS]: CSS[K];
+} & {
+    variants: Variants;
+    compoundVariants?: unknown[];
+};
+/**
+ * Creates a styled component factory function.
+ * Supports polymorphic components, variants, theme awareness, and CSS prop merging.
+ *
+ * @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
+ * @param themeContext - React context for theme values (instance-specific)
+ * @returns Styled component factory function
+ */
+export declare function createStyledFunction(defaultTheme: Theme, prefix?: string, media?: Record<string, string>, utils?: Record<string, UtilityFunction>, themeMap?: Record<string, ThemeScale>, themeContext?: Context<ThemeContextValue | null>): {
+    <DefaultElement extends StylableElement, BaseStyles extends CSSWithVariants>(defaultElement: DefaultElement, baseStyles: BaseStyles): ReturnType<typeof forwardRef<unknown, StyledComponentProps<DefaultElement, BaseStyles["variants"]>>> & {
+        selector: StyledComponentRef;
+    };
+    <DefaultElement extends StylableElement, VariantsConfig extends Variants = {}>(defaultElement: DefaultElement, baseStyles?: CSS, variants?: VariantsConfig): ReturnType<typeof forwardRef<unknown, StyledComponentProps<DefaultElement, VariantsConfig>>> & {
+        selector: StyledComponentRef;
+    };
+};
+export {};

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

@@ -0,0 +1,13 @@
+/**
+ * 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/constants.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared constants used throughout the library.
+ * Includes cache size limits, nesting depth limits, and fallback context.
+ */
+import type { CSS, ThemeContextValue, ThemeScale } from "./types";
+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;
+export declare const FALLBACK_CONTEXT: import("react").Context<ThemeContextValue>;
+/**
+ * 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.
+ * Missing properties gracefully fallback to pattern-based auto-detection.
+ */
+export declare const DEFAULT_THEME_MAP: Record<string, ThemeScale>;
+export declare const STOOP_COMPONENT_SYMBOL: unique symbol;

package/dist/core/cache.d.ts

@@ -0,0 +1,39 @@
+/**
+ * CSS compilation caching system.
+ * Tracks compiled CSS strings and class names to prevent duplicate work.
+ * Implements LRU (Least Recently Used) eviction when cache size limits are exceeded.
+ */
+/**
+ * LRU Cache implementation for class names and CSS strings.
+ * Automatically evicts least recently used entries when size limit is exceeded.
+ */
+declare class LRUCache<K, V> extends Map<K, V> {
+    private readonly maxSize;
+    constructor(maxSize: number);
+    get(key: K): V | undefined;
+    set(key: K, value: V): this;
+}
+export declare const classNameCache: LRUCache<string, string>;
+export declare const cssStringCache: LRUCache<string, string>;
+/**
+ * Checks if a CSS string is cached.
+ *
+ * @param css - CSS string to check
+ * @returns True if CSS is cached
+ */
+export declare function isCachedStyle(css: string): boolean;
+/**
+ * Marks a CSS string as cached.
+ *
+ * @param css - CSS string to cache
+ */
+export declare function markStyleAsCached(css: string): void;
+/**
+ * Limits cache size by evicting least recently used entries.
+ */
+export declare function limitCacheSize(): void;
+/**
+ * Clears all cached styles.
+ */
+export declare function clearStyleCache(): void;
+export {};

package/dist/core/compiler.d.ts

@@ -0,0 +1,19 @@
+/**
+ * CSS compilation engine.
+ * Converts CSS objects to CSS strings and generates unique class names.
+ * Handles nested selectors, media queries, styled component targeting, and theme tokens.
+ */
+import type { CSS, Theme, ThemeScale, UtilityFunction } from "../types";
+/**
+ * Compiles CSS objects into CSS strings and generates unique class names.
+ * Handles nested selectors, media queries, styled component targeting, and theme tokens.
+ *
+ * @param styles - CSS object to compile
+ * @param currentTheme - 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 Generated class name
+ */
+export declare function compileCSS(styles: CSS, currentTheme: Theme, prefix?: string, media?: Record<string, string>, utils?: Record<string, UtilityFunction>, themeMap?: Record<string, ThemeScale>): string;

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

@@ -0,0 +1,30 @@
+/**
+ * Theme variable management.
+ * Updates CSS custom properties when theme changes.
+ * Ensures CSS variables are injected and kept in sync with theme updates.
+ * Automatically merges themes with the default theme when applied.
+ */
+import type { Theme } from "../types";
+/**
+ * Registers the default theme for a given prefix.
+ * Called automatically by createStoop.
+ *
+ * @param theme - Default theme from createStoop
+ * @param prefix - Optional prefix for theme scoping
+ */
+export declare function registerDefaultTheme(theme: Theme, prefix?: string): void;
+/**
+ * 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;
+/**
+ * Updates CSS custom properties when theme changes.
+ * Automatically merges the theme with the default theme to ensure all properties are present.
+ *
+ * @param theme - Theme object to generate CSS variables from
+ * @param prefix - Optional prefix for CSS variable names
+ */
+export declare function updateThemeVariables(theme: Theme, prefix?: string): void;

package/dist/core/variants.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Variant application logic.
+ * Merges variant styles with base styles based on component props.
+ * Optimized to avoid unnecessary object spreads when no variants are applied.
+ */
+import type { CSS, Variants, VariantProps } from "../types";
+/**
+ * Applies variant styles to base styles based on component props.
+ *
+ * @param variants - Variant configuration object
+ * @param props - Component props containing variant values
+ * @param baseStyles - Base styles to merge with variant styles
+ * @returns Merged CSS object
+ */
+export declare function applyVariants(variants: Variants, props: VariantProps, baseStyles: CSS): CSS;

package/dist/create-stoop.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Main factory function that creates a Stoop instance.
+ * Configures theme, media queries, utilities, and returns all API functions.
+ */
+import type { StoopConfig, StoopInstance } from "./types";
+/**
+ * Creates a Stoop instance with the provided configuration.
+ *
+ * @param config - Configuration object containing theme, media queries, utilities, and optional prefix/themeMap
+ * @returns StoopInstance with all API functions (styled, css, globalCss, keyframes, createTheme, etc.)
+ */
+export declare function createStoop(config: StoopConfig): StoopInstance;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export * from "./components/Provider";
-export * from "./styles";
-export * from "./hooks";
-export { Stack, Section, Text, Button, Badge, Card, Input, Textarea, Tabs, Menu, Select, Popover, Modal, StoopProvider, } from "./components";
-export { useTheme } from "./components/Provider";
-export type { StackProps, SectionProps, TextProps, TextElement, ButtonProps, BadgeProps, CardProps, InputProps, TextareaProps, TabsProps, TabItem, MenuProps, MenuOption, SelectProps, SelectOption, PopoverProps, ModalProps, } from "./components";
+/**
+ * Main entry point for Stoop CSS-in-JS library.
+ * Exports the createStoop factory function and essential public types.
+ */
+export { createStoop } from "./create-stoop";
+export type { CSS, StoopConfig, StoopInstance, StyledComponentProps, Theme, UtilityFunction, Variants, } from "./types";