tailwind-to-style 3.3.0 → 4.0.1

package/llms.txt

@@ -0,0 +1,481 @@
+# tailwind-to-style
+
+> Zero-build runtime Tailwind CSS engine. Convert utility classes to real CSS at runtime — with variants, slots, design tokens, and React bindings.
+
+## Installation
+
+```
+npm install tailwind-to-style
+```
+
+## Overview
+
+tailwind-to-style replaces the Tailwind CSS build step entirely. You write Tailwind utility classes as strings, and the library generates and injects real CSS into the DOM at runtime. It supports responsive breakpoints (md:, lg:), pseudo-classes (hover:, focus:), arbitrary values, variants, slots, design tokens, and SSR.
+
+---
+
+## API Reference
+
+### `tw()` — The main function (4 modes)
+
+#### Mode 1: Atomic classes
+Pass a string of Tailwind utilities. Returns auto-generated class names. CSS is injected into the DOM automatically, including @media queries and pseudo-class rules.
+
+```js
+import { tw } from 'tailwind-to-style';
+
+tw('flex items-center gap-4 hover:bg-gray-100 md:hidden')
+// Returns: "tw-flex tw-items-center tw-gap-4 tw-hover-bg-gray-100 tw-md-hidden"
+```
+
+Use with `className={}` in React. Supports all responsive prefixes (sm:, md:, lg:, xl:, 2xl:) and pseudo-classes (hover:, focus:, active:, disabled:, focus-within:, etc.).
+
+#### Mode 2: Named class (preferred for static styles)
+Two string arguments: name + Tailwind classes. Returns the name as the class. This is the preferred shorthand for defining reusable static styles.
+
+```js
+tw('sidebar', 'w-64 h-screen bg-white border-r border-gray-200')
+// Returns: "sidebar"
+// Injects: .sidebar { width: 16rem; height: 100vh; background: #fff; ... }
+```
+
+#### Mode 3: Variants (returns a selector function)
+Object config with `name`, `base`, `variants`, optional `compoundVariants` and `defaultVariants`. Returns a function you call with variant selections.
+
+```js
+const button = tw({
+  name: 'btn',
+  base: 'px-4 py-2 rounded-lg font-medium transition-all cursor-pointer',
+  variants: {
+    color: {
+      primary: 'bg-blue-600 text-white hover:bg-blue-700',
+      secondary: 'bg-gray-200 text-gray-900 hover:bg-gray-300',
+      danger: 'bg-red-600 text-white hover:bg-red-700',
+      ghost: 'bg-transparent text-gray-700 hover:bg-gray-100',
+    },
+    size: {
+      sm: 'text-sm px-3 py-1.5',
+      md: 'text-base px-4 py-2',
+      lg: 'text-lg px-6 py-3',
+    },
+    fullWidth: {
+      true: 'w-full',
+    },
+  },
+  compoundVariants: [
+    { color: 'primary', size: 'lg', class: 'shadow-lg shadow-blue-500/25' },
+    { color: 'danger', size: 'lg', class: 'shadow-lg shadow-red-500/25' },
+  ],
+  defaultVariants: { color: 'primary', size: 'md' },
+})
+
+button({ color: 'danger', size: 'lg' })
+// Returns: "btn btn--color-danger btn--size-lg"
+```
+
+#### Mode 4: Slots (multi-part components)
+Object config with `name`, `slots`, and `variants` where each variant value is an object mapping slot names to classes.
+
+```js
+const card = tw({
+  name: 'card',
+  slots: {
+    root: 'bg-white rounded-xl border overflow-hidden',
+    header: 'border-b flex items-center justify-between',
+    title: 'font-semibold text-gray-900',
+    body: 'text-gray-700',
+    footer: 'border-t bg-gray-50',
+  },
+  variants: {
+    variant: {
+      default: {
+        root: 'border-gray-200 shadow-sm',
+        header: 'border-gray-100',
+        footer: 'border-gray-100',
+      },
+      elevated: {
+        root: 'border-gray-200 shadow-lg hover:shadow-xl',
+        header: 'border-gray-100',
+        footer: 'border-gray-100',
+      },
+    },
+    size: {
+      sm: { header: 'px-4 py-3', title: 'text-sm', body: 'px-4 py-3 text-sm', footer: 'px-4 py-3' },
+      md: { header: 'px-6 py-4', title: 'text-base', body: 'px-6 py-4', footer: 'px-6 py-4' },
+      lg: { header: 'px-8 py-5', title: 'text-lg', body: 'px-8 py-5', footer: 'px-8 py-5' },
+    },
+  },
+  defaultVariants: { variant: 'default', size: 'md' },
+})
+
+const slots = card({ variant: 'elevated', size: 'lg' })
+// Returns: { root: "card__root card__root--variant-elevated card__root--size-lg", ... }
+// Use: <div className={slots.root}> ... <h3 className={slots.title}> ...
+```
+
+---
+
+### `tws()` — Inline style converter
+
+Converts Tailwind classes to CSS string or JS style object. Does NOT support responsive or pseudo-class variants (those require `tw()`).
+
+```js
+import { tws } from 'tailwind-to-style';
+
+// CSS string
+tws('bg-blue-500 text-white p-4 rounded-lg')
+// → "background-color: rgb(59,130,246); color: #fff; padding: 1rem; border-radius: 0.5rem;"
+
+// JS object (pass true as second arg)
+tws('flex items-center gap-4', true)
+// → { display: 'flex', alignItems: 'center', gap: '1rem' }
+```
+
+---
+
+### `cx()` — Conditional class merging
+
+```js
+import { cx } from 'tailwind-to-style';
+
+cx('base-class', isActive && 'ring-2 ring-blue-500', { 'opacity-50': disabled })
+cx(button({ color: 'primary' }), disabled && tw('opacity-50 pointer-events-none'), className)
+```
+
+---
+
+### Design Tokens
+
+```js
+import { createTheme, activateTheme, token, tokenRegistry } from 'tailwind-to-style/tokens';
+
+createTheme({
+  colors: { primary: '#2563eb', surface: '#ffffff', text: '#0f172a', border: '#e2e8f0' },
+}, { name: 'light' });
+
+createTheme({
+  colors: { primary: '#60a5fa', surface: '#1e293b', text: '#f1f5f9', border: '#334155' },
+}, { name: 'dark' });
+
+// Reference in tw() via arbitrary value syntax
+tw('themed-btn', `bg-[${token('colors.primary')}] text-white px-4 py-2 rounded-lg`)
+// token('colors.primary') → "var(--tws-colors-primary)"
+
+// Switch themes at runtime
+activateTheme('dark')
+
+// Programmatic access
+tokenRegistry.get('colors.primary')
+tokenRegistry.set('colors.primary', '#1d4ed8')
+tokenRegistry.subscribe((tokens) => { /* react to changes */ })
+tokenRegistry.toCSS() // → ":root { --tws-colors-primary: ...; }"
+```
+
+---
+
+### React Bindings
+
+```jsx
+import { ThemeProvider, useTheme, styled } from 'tailwind-to-style/react';
+
+<ThemeProvider theme={lightTheme} name="light">
+  <App />
+</ThemeProvider>
+
+// Inside components:
+const { tokens, setTheme } = useTheme();
+
+// styled() — creates React components with variant props
+const Button = styled('button', {
+  name: 'btn',
+  base: 'px-4 py-2 rounded-lg font-medium',
+  variants: {
+    color: { primary: 'bg-blue-600 text-white', secondary: 'bg-gray-200 text-gray-800' },
+  },
+  defaultVariants: { color: 'primary' },
+})
+
+<Button color="primary" onClick={handleClick}>Click</Button>
+```
+
+---
+
+### Animations
+
+```js
+import { animate, defineAnimation } from 'tailwind-to-style/animations';
+
+element.className = animate('fadeIn', { duration: '300ms', delay: '100ms' });
+// Built-in: fadeIn, fadeOut, slideInUp, slideInDown, slideInLeft, slideInRight,
+//           scaleIn, scaleOut, bounce, shake, pulse, spin, ping
+
+defineAnimation('wiggle', {
+  keyframes: [
+    { transform: 'rotate(0deg)' },
+    { transform: 'rotate(-3deg)' },
+    { transform: 'rotate(3deg)' },
+    { transform: 'rotate(0deg)' },
+  ],
+  duration: '300ms',
+  easing: 'ease-in-out',
+});
+```
+
+---
+
+### SSR (Server-Side Rendering)
+
+```js
+import { tw, createSSRCollector } from 'tailwind-to-style';
+
+const collector = createSSRCollector();
+const html = renderToString(<App />);
+const css = collector.extract();
+// Inject css into <style> in <head> of server-rendered HTML
+```
+
+---
+
+## Import Paths
+
+| Path | Exports |
+|------|---------|
+| `tailwind-to-style` | `tw`, `tws`, `cx` |
+| `tailwind-to-style/react` | `ThemeProvider`, `useTheme`, `styled`, `useTws` |
+| `tailwind-to-style/tokens` | `createTheme`, `activateTheme`, `token`, `tokenRegistry` |
+| `tailwind-to-style/animations` | `animate`, `defineAnimation`, `getAnimationNames` |
+| `tailwind-to-style/cx` | `cx` (standalone, ~300B) |
+| `tailwind-to-style/tws` | `tws` (standalone subset) |
+
+---
+
+## Real-World Component Patterns
+
+These patterns are extracted from the library's production demo app.
+
+### Pattern: Simple component with Mode 2 static classes
+
+```jsx
+import { tw, cx } from 'tailwind-to-style';
+
+const accordionRoot = tw('accordion', 'rounded-lg border border-gray-200 overflow-hidden divide-y divide-gray-200');
+const accordionItem = tw('accordion-item', 'bg-white');
+const accordionTrigger = tw('accordion-trigger', 'flex items-center justify-between w-full px-4 py-3 text-left text-sm font-medium text-gray-900 cursor-pointer select-none hover:bg-gray-50 transition-colors');
+const accordionContent = tw('accordion-content', 'px-4 pb-3 text-sm text-gray-600');
+
+export function Accordion({ items, className }) {
+  return (
+    <div className={cx(accordionRoot, className)}>
+      {items.map((item, i) => (
+        <div className={accordionItem}>
+          <button className={accordionTrigger}>{item.title}</button>
+          <div className={accordionContent}>{item.content}</div>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Pattern: Component with variants
+
+```jsx
+const inputField = tw({
+  name: 'input',
+  base: 'block w-full rounded-lg border bg-white text-gray-900 transition-all duration-200 focus:outline-none focus:ring-2',
+  variants: {
+    size: {
+      sm: 'text-sm px-3 py-1.5',
+      md: 'text-base px-3.5 py-2.5',
+      lg: 'text-lg px-4 py-3',
+    },
+    state: {
+      default: 'border-gray-300 focus:border-blue-500 focus:ring-blue-500/20',
+      error: 'border-red-400 focus:border-red-500 focus:ring-red-500/20',
+      success: 'border-emerald-400 focus:border-emerald-500 focus:ring-emerald-500/20',
+    },
+    disabled: {
+      true: 'opacity-50 cursor-not-allowed bg-gray-50',
+    },
+  },
+  defaultVariants: { size: 'md', state: 'default' },
+});
+
+// Usage — filter undefined props before passing:
+const variantProps = { state: error ? 'error' : 'default' };
+if (size !== undefined) variantProps.size = size;
+if (disabled) variantProps.disabled = true;
+
+<input className={inputField(variantProps)} />
+```
+
+### Pattern: Component with compoundVariants
+
+```jsx
+const tab = tw({
+  name: 'tab',
+  base: 'inline-flex items-center justify-center font-medium cursor-pointer transition-all duration-200',
+  variants: {
+    variant: {
+      underline: 'px-4 py-2.5 text-sm border-b-2 -mb-px',
+      pills: 'px-3 py-1.5 text-sm rounded-md',
+    },
+    active: { true: '', false: '' },
+  },
+  compoundVariants: [
+    { variant: 'underline', active: true, class: 'border-blue-500 text-blue-600' },
+    { variant: 'underline', active: false, class: 'border-transparent text-gray-500 hover:text-gray-700' },
+    { variant: 'pills', active: true, class: 'bg-white text-gray-900 shadow-sm' },
+    { variant: 'pills', active: false, class: 'text-gray-500 hover:text-gray-700' },
+  ],
+  defaultVariants: { variant: 'underline', active: false },
+});
+
+tab({ variant: 'pills', active: true })
+```
+
+### Pattern: Multi-part component with slots
+
+```jsx
+const dialog = tw({
+  name: 'dialog',
+  slots: {
+    overlay: 'fixed inset-0 z-50 flex items-center justify-center p-4',
+    backdrop: 'absolute inset-0 bg-black/50',
+    content: 'relative bg-white rounded-xl shadow-xl w-full max-h-[85vh] overflow-y-auto',
+    header: 'border-b border-gray-100 flex items-center justify-between',
+    title: 'font-semibold text-gray-900',
+    body: '',
+    footer: 'border-t border-gray-100 flex justify-end gap-2',
+  },
+  variants: {
+    size: {
+      sm: { content: 'max-w-sm', header: 'px-4 py-3', body: 'px-4 py-3', footer: 'px-4 py-3' },
+      md: { content: 'max-w-md', header: 'px-6 py-4', body: 'px-6 py-4', footer: 'px-6 py-4' },
+      lg: { content: 'max-w-2xl', header: 'px-8 py-5', body: 'px-8 py-5', footer: 'px-8 py-5' },
+    },
+  },
+  defaultVariants: { size: 'md' },
+});
+
+// Usage:
+const slots = dialog({ size: 'lg' });
+<div className={slots.overlay}>
+  <div className={slots.backdrop} onClick={onClose} />
+  <div className={slots.content}>
+    <div className={slots.header}><h2 className={slots.title}>{title}</h2></div>
+    <div className={slots.body}>{children}</div>
+    <div className={slots.footer}>{footer}</div>
+  </div>
+</div>
+```
+
+### Pattern: Toggle with color maps (combining tw() and inline styles)
+
+When a component has many possible colors (not fixed variants), use a color map with inline styles for the dynamic color, and tw() for structural styling:
+
+```jsx
+const track = tw({
+  name: 'toggle-track',
+  base: 'relative inline-flex shrink-0 cursor-pointer rounded-full border-2 border-transparent transition-colors duration-200',
+  variants: {
+    size: { sm: 'w-8 h-4', md: 'w-11 h-6', lg: 'w-14 h-7' },
+    checked: { true: '', false: 'bg-gray-200' },
+    disabled: { true: 'opacity-50 cursor-not-allowed' },
+  },
+  defaultVariants: { size: 'md', checked: false },
+});
+
+const checkedColors = {
+  blue: '#3b82f6', green: '#10b981', red: '#ef4444', purple: '#8b5cf6',
+};
+
+// Usage: tw() handles layout/structure, inline style handles dynamic color
+<button
+  className={track({ size, checked, disabled })}
+  style={checked ? { backgroundColor: checkedColors[color] } : undefined}
+/>
+```
+
+### Pattern: Table with structural tw() + value maps for density/variant
+
+For data-driven variations where utilities don't cleanly map (padding values, complex conditional styles), define value maps as plain objects and apply via inline style:
+
+```jsx
+const wrapperCls = tw('tbl-wrapper', 'overflow-x-auto rounded-lg');
+const tableCls = tw('tbl-table', 'w-full text-sm text-left');
+const thBaseCls = tw('tbl-th', 'text-xs font-semibold text-gray-600 uppercase tracking-wider');
+const tdBaseCls = tw('tbl-td', 'text-gray-700 border-b border-gray-100');
+
+const DENSITY_PADDING = {
+  compact: { padding: '4px 12px' },
+  default: { padding: '12px 16px' },
+  comfortable: { padding: '20px 24px' },
+};
+
+// Usage:
+<th className={thBaseCls} style={DENSITY_PADDING[density]}>{col.label}</th>
+```
+
+### Pattern: Responsive layout using tw()
+
+```jsx
+const layout = tw('app-layout', 'flex h-screen overflow-hidden bg-gray-50');
+const sidebar = tw('app-sidebar', 'hidden md:flex w-56 shrink-0 flex-col bg-white border-r border-gray-200 h-full overflow-y-auto');
+const hamburger = tw('app-hamburger', 'flex md:hidden items-center p-1 rounded-md text-gray-700 hover:bg-gray-100 bg-transparent border-none cursor-pointer');
+const content = tw('app-content', 'flex-1 overflow-y-auto overflow-x-hidden p-4 md:p-8 min-w-0');
+
+// Sidebar hidden on mobile, shown on md+. Hamburger visible on mobile only.
+```
+
+### Pattern: Design tokens with live theme switching
+
+```jsx
+import { createTheme, token } from 'tailwind-to-style/tokens';
+import { ThemeProvider, useTheme } from 'tailwind-to-style/react';
+
+const THEMES = {
+  blue: { colors: { primary: '#2563eb', primaryLight: '#dbeafe', surface: '#ffffff' } },
+  emerald: { colors: { primary: '#059669', primaryLight: '#d1fae5', surface: '#f0fdf4' } },
+};
+
+// Apply theme
+createTheme(structuredClone(THEMES.blue), { name: 'blue' });
+
+// Reference in component styles (uses CSS variables — updates automatically when theme changes)
+const themedBtn = tw({
+  name: 'theme-btn',
+  base: 'px-4 py-2 rounded-lg font-medium transition-all cursor-pointer',
+  variants: {
+    intent: {
+      primary: `bg-[${token('colors.primary')}] text-white hover:opacity-90`,
+      surface: `bg-[${token('colors.surface')}] text-[${token('colors.text')}] border border-[${token('colors.border')}]`,
+    },
+  },
+  defaultVariants: { intent: 'primary' },
+});
+```
+
+---
+
+## Best Practices
+
+1. **Use `tw('name', 'classes')` for static styles.** It's the shortest, cleanest form.
+2. **Use Mode 3 (object with base + variants) only when you need runtime variant selection.**
+3. **Use `className={tw(...)}` for all responsive and interactive styles.** Never `style={tws('md:...')}` — responsive/pseudo-class does not work in inline styles.
+4. **Use `cx()` to merge conditional classes.** Not string concatenation.
+5. **Filter undefined variant props** before passing to a variant function — pass only defined keys so defaultVariants apply correctly.
+6. **For dynamic colors not in a fixed variant set**, use a color map + inline style for the color, and tw() for everything structural.
+7. **This library replaces Tailwind CSS entirely.** Do not install both.
+8. **Always clone theme objects** when passing to `createTheme()` in React effects (use `structuredClone()`).
+9. **Arbitrary values work:** `tw('box', 'w-[200px] h-[50vh] bg-[#ff6600] text-[1.2rem]')`
+10. **All Tailwind v3 utilities are supported.** Most v4 utilities also supported.
+
+---
+
+## Links
+
+- npm: https://www.npmjs.com/package/tailwind-to-style
+- GitHub: https://github.com/Bigetion/tailwind-to-style
+- Live Demo: https://n86xr8.csb.app/
+- License: MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tailwind-to-style",
-  "version": "3.3.0",
-  "description": "Runtime Tailwind CSS to inline styles converter. Zero build step, SSR support, tree-shakeable. Works with React, Vue, Svelte, vanilla JS.",
+  "version": "4.0.1",
+  "description": "Zero-build runtime Tailwind CSS engine. Convert utility classes to real CSS with variants, slots, tokens, and React bindings. SSR-ready, tree-shakeable.",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.esm.js",
@@ -15,26 +15,26 @@
       "import": "./dist/index.esm.js",
       "require": "./dist/index.cjs"
     },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.esm.js",
+      "require": "./dist/react/index.cjs"
+    },
+    "./tokens": {
+      "types": "./dist/tokens/index.d.ts",
+      "import": "./dist/tokens/index.esm.js",
+      "require": "./dist/tokens/index.cjs"
+    },
+    "./animations": {
+      "types": "./dist/animations/index.d.ts",
+      "import": "./dist/animations/index.esm.js",
+      "require": "./dist/animations/index.cjs"
+    },
     "./tws": {
       "types": "./dist/core/tws.d.ts",
       "import": "./dist/core/tws.esm.js",
       "require": "./dist/core/tws.cjs"
     },
-    "./twsx": {
-      "types": "./dist/core/twsx.d.ts",
-      "import": "./dist/core/twsx.esm.js",
-      "require": "./dist/core/twsx.cjs"
-    },
-    "./twsx-variants": {
-      "types": "./dist/core/twsxVariants.d.ts",
-      "import": "./dist/core/twsxVariants.esm.js",
-      "require": "./dist/core/twsxVariants.cjs"
-    },
-    "./utils": {
-      "types": "./dist/utils/index.d.ts",
-      "import": "./dist/utils/index.esm.js",
-      "require": "./dist/utils/index.cjs"
-    },
     "./cx": {
       "types": "./dist/cx.d.ts",
       "import": "./dist/cx.esm.js",
@@ -48,11 +48,16 @@
     "./preflight.css": "./preflight.css",
     "./package.json": "./package.json"
   },
-  "sideEffects": false,
+  "sideEffects": [
+    "*.css",
+    "dist/*.js",
+    "dist/**/*.js"
+  ],
   "files": [
     "dist",
     "types",
     "preflight.css",
+    "llms.txt",
     "README.md",
     "LICENSE"
   ],
@@ -82,19 +87,20 @@
     "tailwind",
     "tailwindcss",
     "css",
-    "stylesheet",
-    "inline-styles",
-    "runtime-css",
     "css-in-js",
+    "runtime-css",
     "zero-build",
+    "variants",
+    "slots",
+    "design-tokens",
+    "styled-components",
     "ssr",
     "server-side-rendering",
     "tree-shakeable",
-    "variants",
-    "style-converter",
     "react",
     "vue",
-    "svelte"
+    "svelte",
+    "vanilla-js"
   ],
   "author": "Bigetion",
   "license": "MIT",
@@ -106,6 +112,14 @@
     "url": "https://github.com/Bigetion/tailwind-to-style/issues"
   },
   "homepage": "https://github.com/Bigetion/tailwind-to-style#readme",
+  "peerDependencies": {
+    "react": ">=17.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@babel/core": "^7.27.4",
     "@babel/plugin-proposal-optional-chaining": "^7.21.0",

package/types/animations/index.d.ts

@@ -0,0 +1,58 @@
+// Type definitions for tailwind-to-style/animations
+
+export type AnimationPresetName =
+  | 'fadeIn' | 'fadeOut'
+  | 'slideInUp' | 'slideInDown' | 'slideInLeft' | 'slideInRight'
+  | 'scaleIn' | 'scaleOut'
+  | 'bounce' | 'shake' | 'pulse' | 'spin' | 'ping';
+
+export interface AnimationKeyframe {
+  [property: string]: string;
+}
+
+export interface AnimationConfig {
+  keyframes: AnimationKeyframe[];
+  duration?: string;
+  easing?: string;
+  delay?: string;
+  iterations?: string | number;
+  fillMode?: string;
+}
+
+export interface AnimateOptions {
+  duration?: string;
+  easing?: string;
+  delay?: string;
+  iterations?: string | number;
+  fillMode?: string;
+}
+
+/**
+ * Apply a named animation, returning a className with the animation injected.
+ */
+export declare function animate(name: AnimationPresetName | string, options?: AnimateOptions): string;
+
+/**
+ * Define a custom animation preset.
+ */
+export declare function defineAnimation(name: string, config: AnimationConfig): void;
+
+/**
+ * Get all available animation names (built-in + custom).
+ */
+export declare function getAnimationNames(): string[];
+
+/**
+ * Get an animation preset config by name.
+ */
+export declare function getPreset(name: string): AnimationConfig | undefined;
+
+/**
+ * Clear all injected keyframes and custom animations.
+ */
+export declare function clearAnimations(): void;
+
+/**
+ * Built-in animation presets.
+ */
+export declare const ANIMATION_PRESETS: Record<AnimationPresetName, AnimationConfig>;

package/types/index.d.ts

@@ -1,7 +1,10 @@
-// Type definitions for tailwind-to-style
+// Type definitions for tailwind-to-style v4
 // Project: https://github.com/Bigetion/tailwind-to-style
 // Definitions by: Bigetion
 
+// v4 unified API re-exports
+export { tw, tws, cx, createSSRCollector } from './v4';
+
 // ============================================================================
 // Environment Detection
 // ============================================================================