tailwind-to-style 4.0.0 → 4.0.2

package/README.md

@@ -64,6 +64,30 @@ const classes = cx('base', isActive && 'ring-2', { 'opacity-50': disabled });
 
 ---
 
+## Examples
+
+Want to try the library with real demos?
+
+- `examples/basic/` — runtime `tws()` examples for inline conversion and custom values.
+- `examples/react-demo/` — full React showcase with components, variants, tokens, and theme switching.
+- `examples/twsx-classname-app/` — Vite-based runtime `tw()` v4 demo with variant and slots components.
+
+Run the demos by opening `examples/README.md` or using the commands below:
+
+```bash
+cd examples/react-demo
+npm install
+npm run dev
+```
+
+```bash
+cd examples/twsx-classname-app
+npm install
+npm run dev
+```
+
+---
+
 ## API Reference
 
 ### `tw()` — The Main Function
@@ -259,7 +283,7 @@ createTheme({
   },
   spacing: { sm: '0.5rem', md: '1rem', lg: '1.5rem' },
   radius: { sm: '0.25rem', md: '0.5rem', lg: '1rem' },
-});
+}, { selector: ':root' });
 // Injects CSS variables on :root:
 // --tws-colors-primary: #3b82f6;
 // --tws-colors-secondary: #8b5cf6;
@@ -361,11 +385,10 @@ Import only what you need for minimal bundle size:
 
 Works with any framework or vanilla JS:
 
-- **React** — Full bindings via `tailwind-to-style/react`
-- **Vue** — Use `tw()` in computed properties or `tws()` in `:style`
-- **Svelte** — Use `tw()` in `class:` or `tws()` in `style:`
-- **Vanilla JS** — Direct DOM manipulation
-- **Node.js / SSR** — `tws()` for inline + `createSSRCollector()` for classes
+- **React** — Full bindings via `tailwind-to-style/react` (example available in `examples/react-demo`)
+- **Vanilla JS** — Direct DOM usage with `tw()` and `tws()`
+- **Node.js / SSR** — `tws()` for inline styles + `createSSRCollector()` for CSS extraction
+- **Vue / Svelte** — supported in runtime with `tw()` / `tws()`, examples can be added in future releases
 
 ---
 

package/dist/animations/index.cjs

@@ -1,5 +1,5 @@
 /**
- * tailwind-to-style v4.0.0
+ * tailwind-to-style v4.0.2
  * Zero-build runtime Tailwind CSS engine
  * 
  * @author Bigetion
@@ -2049,6 +2049,106 @@ function generateCssString$1() {
   return cssString;
 }
 
+/**
+ * SSR (Server-Side Rendering) Collector
+ * 
+ * Simplified API for collecting CSS during server-side rendering.
+ * Replaces the imperative startSSR/stopSSR/getSSRStyles with a context-based approach.
+ * 
+ * Features:
+ * - Instance-based state (safe for concurrent requests)
+ * - CSS deduplication
+ * - Critical CSS extraction
+ * - Minification support
+ * - Nonce support for CSP
+ * 
+ * @module ssr
+ */
+
+let _globalIsCollecting = false;
+
+// Fallback "active collector" used when AsyncLocalStorage isn't available
+// (browsers, edge runtimes without async_hooks) or before it has finished
+// loading. Safe for the common single-request-at-a-time case, but multiple
+// concurrent requests on the same Node process can interleave and see each
+// other's CSS — use `collector.run(fn)` below to avoid that.
+let _activeCollector = null;
+
+// ============================================================================
+// Async-context isolation (Node only)
+// ============================================================================
+// AsyncLocalStorage lets each concurrent request keep its own "active
+// collector" even though CSS is collected deep inside tw()/twsx() calls that
+// have no direct reference to the collector. It only exists in Node, and
+// this module is also bundled for browsers (via styled()/index.js), so the
+// Node builtin must never be statically imported — that would break the
+// browser/CDN build. It's loaded lazily via a dynamic import instead, and
+// every call site below falls back gracefully when it isn't available.
+const IS_NODE = typeof process !== "undefined" && !!process.versions && !!process.versions.node;
+let _als = null;
+let _alsLoadPromise = null;
+function loadAsyncLocalStorage() {
+  if (!IS_NODE) return Promise.resolve(null);
+  if (!_alsLoadPromise) {
+    const specifier = "node:async_hooks";
+    _alsLoadPromise = import(/* @vite-ignore */specifier).then(mod => new mod.AsyncLocalStorage()).catch(() => null);
+  }
+  return _alsLoadPromise;
+}
+if (IS_NODE) {
+  // Kick off loading immediately so it's ready before the first request in
+  // the common case. There's an unavoidable brief window right at process
+  // startup where this hasn't resolved yet; the singleton fallback above
+  // covers that window for single-request-at-a-time usage.
+  loadAsyncLocalStorage().then(als => {
+    _als = als;
+  });
+}
+
+// ============================================================================
+// Internal Helpers (used by twsx/tws)
+// ============================================================================
+
+/**
+ * Check if SSR collecting is active
+ * @internal
+ */
+function isSSRCollecting() {
+  const active = getActiveCollector();
+  return !!(active && active.isCollecting) || _globalIsCollecting;
+}
+
+/**
+ * Add CSS to SSR collection (prefers active collector if available)
+ * @internal
+ */
+function collectSSRCSS(css) {
+  if (!css) return;
+
+  // Use active collector if available (modern API) — prefers the
+  // AsyncLocalStorage-scoped collector for the current request when present.
+  const active = getActiveCollector();
+  if (active && active.isCollecting) {
+    active._collect(css);
+    return;
+  }
+}
+
+/**
+ * Get active collector (for advanced usage)
+ * Prefers the AsyncLocalStorage-scoped collector for the current async
+ * context (set via `collector.run(fn)`) and falls back to the shared
+ * singleton otherwise.
+ * @internal
+ */
+function getActiveCollector() {
+  if (_als) {
+    const store = _als.getStore();
+    if (store) return store;
+  }
+  return _activeCollector;
+}
+
 /**
  * Proper LRU (Least Recently Used) Cache implementation
  * Efficiently manages memory by removing least recently used items
@@ -5926,10 +6026,6 @@ cx.with = function () {
 // Detect environment once at module load for zero-cost runtime checks
 // ============================================================================
 const IS_BROWSER$1 = typeof window !== "undefined" && typeof document !== "undefined";
-
-// SSR CSS collector - accumulates CSS strings during server rendering
-let _ssrCollectedCss = [];
-let _ssrCollecting = false;
 const MAX_CACHE_SIZE$1 = 5000;
 const MAX_SET_SIZE = 10000;
 
@@ -7304,7 +7400,7 @@ function twsx(obj) {
     const cached = _twsxInputCache.get(cacheKey);
 
     // Re-inject with registryKey so the slot stays registered (no-op when unchanged).
-    if (inject && (IS_BROWSER$1 || _ssrCollecting)) {
+    if (inject && (IS_BROWSER$1 || isSSRCollecting())) {
       autoInjectCss(cached, registryKey);
     }
     return cached;
@@ -7318,7 +7414,7 @@ function twsx(obj) {
   _twsxInputCache.set(cacheKey, result);
   // LRUCache handles eviction automatically
 
-  if (inject && (IS_BROWSER$1 || _ssrCollecting)) {
+  if (inject && (IS_BROWSER$1 || isSSRCollecting())) {
     autoInjectCss(result, registryKey);
   }
   return result;
@@ -7363,8 +7459,15 @@ function autoInjectCss(cssString) {
   let sourceKey = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : null;
   const marker = performanceMonitor.start("css:inject");
   try {
-    // SSR mode: collect CSS strings instead of DOM injection
-    if (_ssrCollecting) ;
+    // SSR mode: collect CSS strings instead of DOM injection. Delegates to
+    // the shared collector in ./utils/ssr.js so both the legacy
+    // startSSR()/stopSSR() pair and the modern createSSRCollector() actually
+    // receive the CSS generated by tw()/twsx().
+    if (isSSRCollecting()) {
+      collectSSRCSS(cssString);
+      performanceMonitor.end(marker);
+      return;
+    }
     if (IS_BROWSER$1) {
       if (sourceKey) {
         // Slot-based update: each unique twsx(obj) call owns its own CSS block.
@@ -7834,6 +7937,11 @@ function injectCSS(className, css) {
     // Batch CSS injection with requestAnimationFrame
     pendingCSS.push(css);
     scheduleStyleUpdate();
+  } else if (isSSRCollecting()) {
+    // Server-side rendering: forward to the shared SSR collector. Previously
+    // this branch didn't exist, so tw()/styled() produced no usable CSS
+    // output at all during SSR (only the browser path injected anything).
+    collectSSRCSS(css);
   }
 }
 function scheduleStyleUpdate() {

package/dist/animations/index.esm.js

@@ -1,5 +1,5 @@
 /**
- * tailwind-to-style v4.0.0
+ * tailwind-to-style v4.0.2
  * Zero-build runtime Tailwind CSS engine
  * 
  * @author Bigetion
@@ -2047,6 +2047,106 @@ function generateCssString$1() {
   return cssString;
 }
 
+/**
+ * SSR (Server-Side Rendering) Collector
+ * 
+ * Simplified API for collecting CSS during server-side rendering.
+ * Replaces the imperative startSSR/stopSSR/getSSRStyles with a context-based approach.
+ * 
+ * Features:
+ * - Instance-based state (safe for concurrent requests)
+ * - CSS deduplication
+ * - Critical CSS extraction
+ * - Minification support
+ * - Nonce support for CSP
+ * 
+ * @module ssr
+ */
+
+let _globalIsCollecting = false;
+
+// Fallback "active collector" used when AsyncLocalStorage isn't available
+// (browsers, edge runtimes without async_hooks) or before it has finished
+// loading. Safe for the common single-request-at-a-time case, but multiple
+// concurrent requests on the same Node process can interleave and see each
+// other's CSS — use `collector.run(fn)` below to avoid that.
+let _activeCollector = null;
+
+// ============================================================================
+// Async-context isolation (Node only)
+// ============================================================================
+// AsyncLocalStorage lets each concurrent request keep its own "active
+// collector" even though CSS is collected deep inside tw()/twsx() calls that
+// have no direct reference to the collector. It only exists in Node, and
+// this module is also bundled for browsers (via styled()/index.js), so the
+// Node builtin must never be statically imported — that would break the
+// browser/CDN build. It's loaded lazily via a dynamic import instead, and
+// every call site below falls back gracefully when it isn't available.
+const IS_NODE = typeof process !== "undefined" && !!process.versions && !!process.versions.node;
+let _als = null;
+let _alsLoadPromise = null;
+function loadAsyncLocalStorage() {
+  if (!IS_NODE) return Promise.resolve(null);
+  if (!_alsLoadPromise) {
+    const specifier = "node:async_hooks";
+    _alsLoadPromise = import(/* @vite-ignore */specifier).then(mod => new mod.AsyncLocalStorage()).catch(() => null);
+  }
+  return _alsLoadPromise;
+}
+if (IS_NODE) {
+  // Kick off loading immediately so it's ready before the first request in
+  // the common case. There's an unavoidable brief window right at process
+  // startup where this hasn't resolved yet; the singleton fallback above
+  // covers that window for single-request-at-a-time usage.
+  loadAsyncLocalStorage().then(als => {
+    _als = als;
+  });
+}
+
+// ============================================================================
+// Internal Helpers (used by twsx/tws)
+// ============================================================================
+
+/**
+ * Check if SSR collecting is active
+ * @internal
+ */
+function isSSRCollecting() {
+  const active = getActiveCollector();
+  return !!(active && active.isCollecting) || _globalIsCollecting;
+}
+
+/**
+ * Add CSS to SSR collection (prefers active collector if available)
+ * @internal
+ */
+function collectSSRCSS(css) {
+  if (!css) return;
+
+  // Use active collector if available (modern API) — prefers the
+  // AsyncLocalStorage-scoped collector for the current request when present.
+  const active = getActiveCollector();
+  if (active && active.isCollecting) {
+    active._collect(css);
+    return;
+  }
+}
+
+/**
+ * Get active collector (for advanced usage)
+ * Prefers the AsyncLocalStorage-scoped collector for the current async
+ * context (set via `collector.run(fn)`) and falls back to the shared
+ * singleton otherwise.
+ * @internal
+ */
+function getActiveCollector() {
+  if (_als) {
+    const store = _als.getStore();
+    if (store) return store;
+  }
+  return _activeCollector;
+}
+
 /**
  * Proper LRU (Least Recently Used) Cache implementation
  * Efficiently manages memory by removing least recently used items
@@ -5924,10 +6024,6 @@ cx.with = function () {
 // Detect environment once at module load for zero-cost runtime checks
 // ============================================================================
 const IS_BROWSER$1 = typeof window !== "undefined" && typeof document !== "undefined";
-
-// SSR CSS collector - accumulates CSS strings during server rendering
-let _ssrCollectedCss = [];
-let _ssrCollecting = false;
 const MAX_CACHE_SIZE$1 = 5000;
 const MAX_SET_SIZE = 10000;
 
@@ -7302,7 +7398,7 @@ function twsx(obj) {
     const cached = _twsxInputCache.get(cacheKey);
 
     // Re-inject with registryKey so the slot stays registered (no-op when unchanged).
-    if (inject && (IS_BROWSER$1 || _ssrCollecting)) {
+    if (inject && (IS_BROWSER$1 || isSSRCollecting())) {
       autoInjectCss(cached, registryKey);
     }
     return cached;
@@ -7316,7 +7412,7 @@ function twsx(obj) {
   _twsxInputCache.set(cacheKey, result);
   // LRUCache handles eviction automatically
 
-  if (inject && (IS_BROWSER$1 || _ssrCollecting)) {
+  if (inject && (IS_BROWSER$1 || isSSRCollecting())) {
     autoInjectCss(result, registryKey);
   }
   return result;
@@ -7361,8 +7457,15 @@ function autoInjectCss(cssString) {
   let sourceKey = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : null;
   const marker = performanceMonitor.start("css:inject");
   try {
-    // SSR mode: collect CSS strings instead of DOM injection
-    if (_ssrCollecting) ;
+    // SSR mode: collect CSS strings instead of DOM injection. Delegates to
+    // the shared collector in ./utils/ssr.js so both the legacy
+    // startSSR()/stopSSR() pair and the modern createSSRCollector() actually
+    // receive the CSS generated by tw()/twsx().
+    if (isSSRCollecting()) {
+      collectSSRCSS(cssString);
+      performanceMonitor.end(marker);
+      return;
+    }
     if (IS_BROWSER$1) {
       if (sourceKey) {
         // Slot-based update: each unique twsx(obj) call owns its own CSS block.
@@ -7832,6 +7935,11 @@ function injectCSS(className, css) {
     // Batch CSS injection with requestAnimationFrame
     pendingCSS.push(css);
     scheduleStyleUpdate();
+  } else if (isSSRCollecting()) {
+    // Server-side rendering: forward to the shared SSR collector. Previously
+    // this branch didn't exist, so tw()/styled() produced no usable CSS
+    // output at all during SSR (only the browser path injected anything).
+    collectSSRCSS(css);
   }
 }
 function scheduleStyleUpdate() {