@csszyx/dynamic 0.10.10 → 0.10.12

package/README.md

@@ -0,0 +1,93 @@
+# @csszyx/dynamic
+
+Runtime CSS injection for [CSSzyx](https://github.com/nguyennhutien/csszyx) —
+turn sz objects into class strings **at runtime**, injecting CSS only for
+classes not already in your pre-built stylesheet.
+
+Static styles belong in the build (`sz` prop / `szv` — zero runtime cost).
+`dynamic()` is the escape hatch for values that genuinely cannot be known at
+build time: styling driven by a CMS, an API response, or user configuration.
+
+```tsx
+import { dynamic } from "@csszyx/dynamic";
+
+const cls = dynamic(apiResponse.field.style); // e.g. { p: 4, bg: 'blue-500' }
+<div className={cls} />;
+```
+
+## How it works
+
+1. **Manifest delta check** — a build-generated manifest lists every class in
+   the built CSS. Classes already covered are returned as-is (mangled in
+   production), with no injection.
+2. **CSS generation** — classes NOT in the manifest get a CSS rule generated in
+   the browser using Tailwind v4 variable patterns.
+3. **21-tier injection** — rules insert into per-breakpoint
+   `CSSStyleSheet`s whose order matches the Tailwind cascade, so
+   `sm:`/`md:`/`max-*`/container-query variants win in the right order
+   regardless of injection timing.
+
+SSR-safe: on the server, `dynamic()` returns class names without touching the
+CSSOM (and applies the build's mangle map during SSG so classes match the
+mangled CSS).
+
+## Installation
+
+```bash
+pnpm add @csszyx/dynamic
+```
+
+## API
+
+```ts
+import { dynamic, preloadManifest, cleanup, purifySz } from "@csszyx/dynamic";
+
+// Optional: eagerly fetch the manifest at startup for zero-latency first inject
+await preloadManifest("/csszyx-manifest.json");
+
+// Untrusted input (JSON from a CMS)? Sanitize before injecting:
+const cls = dynamic(purifySz(untrustedSzObject));
+
+// Release injected sheets + manifest cache (e.g. on route teardown)
+cleanup();
+```
+
+## React
+
+```tsx
+import { useSz, CsszyxProvider } from "@csszyx/dynamic/react";
+
+function FormField({ schema }) {
+  const { sz } = useSz(); // stable reference; manages manifest + cleanup
+  return <div className={sz(schema.style)}>{schema.label}</div>;
+}
+
+// Custom manifest URL (non-root deployments):
+<CsszyxProvider manifest="/assets/csszyx-manifest.json">
+  <App />
+</CsszyxProvider>;
+```
+
+`useSz` handles manifest preloading on mount and releases the shared
+stylesheets when the **last** consumer unmounts (StrictMode-safe).
+
+## When NOT to use this
+
+- A finite set of styles selected by a prop → use `szv` (build-time, typed).
+- Literal styles → use the `sz` prop.
+- A runtime **value** inside an otherwise static rule (`bg-(--user-color)`) →
+  consider [`@csszyx/vars`](https://www.npmjs.com/package/@csszyx/vars) + a CSS
+  variable instead of generating rules per value.
+
+Injected rules live for the session and are not individually removed — apps
+that feed continuously varying values (a new arbitrary width per animation
+frame) will grow the CSSOM. In development, a one-time warning fires if a
+session crosses a large number of unique injected classes.
+
+## Documentation
+
+<https://csszyx.com/docs/dynamic/>
+
+## License
+
+MIT

package/dist/index.mjs

@@ -1,2 +1,2 @@
 import '@csszyx/compiler/browser';
-export { a as cleanup, d as dynamic, b as preloadManifest, e as purifySz } from './shared/dynamic.2EVb-qef.mjs';
+export { a as cleanup, d as dynamic, b as preloadManifest, e as purifySz } from './shared/dynamic.BWQj5dWI.mjs';

package/dist/react.d.mts

@@ -46,6 +46,12 @@ interface UseSzReturn {
      */
     sz: (props: SzObject) => string;
 }
+/**
+ * Reset the shared consumer counter and pending timer — test-only. Module
+ * state persists across tests in one suite, so suites that simulate
+ * mount/unmount cycles must start from a known-empty lifecycle.
+ */
+declare function _resetUseSzLifecycle(): void;
 /**
  * React hook for runtime dynamic styling.
  *
@@ -82,5 +88,5 @@ interface CsszyxProviderProps {
  */
 declare function CsszyxProvider({ manifest, children }: CsszyxProviderProps): ReactElement;
 
-export { CsszyxProvider, sz, useSz };
+export { CsszyxProvider, _resetUseSzLifecycle, sz, useSz };
 export type { UseSzReturn };

package/dist/react.mjs

@@ -1,5 +1,5 @@
 import { createContext, useEffect, createElement, useContext, useCallback } from 'react';
-import { d as dynamic, p as preloadManifest, c as cleanup, r as resetManifest, s as setManifestUrl } from './shared/dynamic.2EVb-qef.mjs';
+import { d as dynamic, p as preloadManifest, c as cleanup, r as resetManifest, s as setManifestUrl } from './shared/dynamic.BWQj5dWI.mjs';
 import '@csszyx/compiler/browser';
 
 const CsszyxContext = createContext({
@@ -7,16 +7,30 @@ const CsszyxContext = createContext({
 });
 const sz = dynamic;
 let _cleanupTimer = null;
+let _mountedConsumers = 0;
+function cancelPendingCleanup() {
+  if (_cleanupTimer !== null) {
+    clearTimeout(_cleanupTimer);
+    _cleanupTimer = null;
+  }
+}
+function _resetUseSzLifecycle() {
+  cancelPendingCleanup();
+  _mountedConsumers = 0;
+}
 function useSz() {
   const { manifestUrl } = useContext(CsszyxContext);
   const stableSz = useCallback((props) => dynamic(props), []);
   useEffect(() => {
-    if (_cleanupTimer !== null) {
-      clearTimeout(_cleanupTimer);
-      _cleanupTimer = null;
-    }
+    _mountedConsumers++;
+    cancelPendingCleanup();
     preloadManifest(manifestUrl);
     return () => {
+      _mountedConsumers--;
+      if (_mountedConsumers > 0) {
+        return;
+      }
+      cancelPendingCleanup();
       _cleanupTimer = setTimeout(() => {
         cleanup();
         resetManifest();
@@ -34,4 +48,4 @@ function CsszyxProvider({ manifest, children }) {
   return createElement(CsszyxContext.Provider, { value: { manifestUrl: manifest } }, children);
 }
 
-export { CsszyxProvider, sz, useSz };
+export { CsszyxProvider, _resetUseSzLifecycle, sz, useSz };

package/dist/shared/{dynamic.2EVb-qef.mjs → dynamic.BWQj5dWI.mjs}

@@ -1044,6 +1044,8 @@ function supportsConstructableSheets() {
 let sheets = null;
 let fallbackStyle = null;
 const injected = /* @__PURE__ */ new Set();
+const INJECTED_GROWTH_WARN_THRESHOLD = 5e3;
+let warnedInjectedGrowth = false;
 function wrapForTier(cssRule, tier) {
   if (tier === "base") {
     return cssRule;
@@ -1097,6 +1099,12 @@ function injectRule(className, cssRule, tier = "base") {
     return;
   }
   injected.add(className);
+  if (process.env.NODE_ENV !== "production" && !warnedInjectedGrowth && injected.size >= INJECTED_GROWTH_WARN_THRESHOLD) {
+    warnedInjectedGrowth = true;
+    console.warn(
+      `[csszyx] dynamic() has injected ${INJECTED_GROWTH_WARN_THRESHOLD}+ unique classes this session. Injected CSS rules are never removed, so continuously varying values (e.g. w-[\`\${x}px\`] per animation frame) grow the CSSOM and slow style recalc. Drive continuously changing values through a CSS variable instead.`
+    );
+  }
   if (!cssRule) {
     return;
   }
@@ -1133,6 +1141,7 @@ function cleanup$1() {
     fallbackStyle = null;
   }
   injected.clear();
+  warnedInjectedGrowth = false;
 }
 
 let manifestClasses = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@csszyx/dynamic",
-  "version": "0.10.10",
+  "version": "0.10.12",
   "description": "Runtime CSS injection engine for @csszyx — injects only CSS not already in the pre-built stylesheet",
   "type": "module",
   "repository": {
@@ -38,7 +38,7 @@
     "node": ">=22.12.0"
   },
   "dependencies": {
-    "@csszyx/compiler": "0.10.10"
+    "@csszyx/compiler": "0.10.12"
   },
   "peerDependencies": {
     "react": ">=17.0.0"