@csszyx/dynamic 0.6.2 → 0.8.0

package/dist/index.d.mts

@@ -0,0 +1,92 @@
+import { SzObject, ReadonlySzObject } from '@csszyx/compiler/browser';
+export { ReadonlySzObject, SzObject } from '@csszyx/compiler/browser';
+
+/**
+ *
+ */
+type Tier = 'base' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'max-2xl' | 'max-xl' | 'max-lg' | 'max-md' | 'max-sm' | '@sm' | '@md' | '@lg' | '@xl' | '@2xl' | '@max-2xl' | '@max-xl' | '@max-lg' | '@max-md' | '@max-sm';
+
+/**
+ * Manifest loading and caching.
+ *
+ * The manifest is a JSON file generated at build time by @csszyx/unplugin.
+ * It lists all original class names present in the built CSS so runtime
+ * dynamic() can skip injection for classes already covered.
+ *
+ * The manifest is fetched lazily on first dynamic() call (Qwik surgical pattern).
+ * Never inlined into HTML — each page only pays the cost if dynamic() is used.
+ */
+/**
+ *
+ */
+interface CSSManifest {
+    version: string;
+    buildId: string;
+    /** Original (non-mangled) class names present in built CSS. */
+    classes: string[];
+    /** Original → mangled map. Present only when production mangling is enabled. */
+    mangleMap?: Record<string, string>;
+}
+
+/**
+ * @csszyx/dynamic — Runtime CSS injection with delta check.
+ *
+ * Converts sz objects to Tailwind class strings at runtime, injecting CSS
+ * only for classes not already present in the pre-built stylesheet.
+ *
+ * Architecture:
+ *   Layer 1 (manifest):  Lazy-fetched JSON of all classes in built CSS.
+ *   Layer 2 (generator): Tailwind class → CSS rule using v4 CSS var patterns.
+ *   Layer 3 (injector):  21-tier CSSStyleSheet for correct breakpoint cascade.
+ *
+ * SSR-safe: on server, returns class names only — no CSSOM access.
+ *
+ * @example
+ * // Framework-agnostic usage
+ * import { dynamic, preloadManifest } from '@csszyx/dynamic';
+ *
+ * await preloadManifest('/csszyx-manifest.json'); // optional: eagerly load
+ * const cls = dynamic({ p: 4, bg: 'blue-500' }); // → "p-4 bg-blue-500"
+ */
+
+/**
+ * Transforms sz props at runtime and injects CSS only for classes not already
+ * in the pre-built stylesheet. Lazy-loads manifest on first call.
+ *
+ * SSR-safe: on server, returns class names without CSSOM access.
+ *
+ * @param szProps - sz object (e.g. { p: 4, bg: 'blue-500', hover: { bg: 'blue-600' } }). Accepts both mutable and `as const` objects.
+ * @returns space-separated class string (e.g. "p-4 bg-blue-500 hover:bg-blue-600")
+ *
+ * @example
+ * const cls = dynamic({ p: 4, bg: 'blue-500' });
+ * // → "p-4 bg-blue-500" (injects CSS for classes not in built stylesheet)
+ */
+declare function dynamic(szProps: SzObject | ReadonlySzObject): string;
+/**
+ * Eagerly preloads the CSS manifest.
+ * Without this, the manifest is lazy-loaded on the first dynamic() call.
+ * Call at app startup or on route enter for zero-latency first inject.
+ *
+ * @param url - manifest URL (default: '/csszyx-manifest.json')
+ * @returns promise that resolves when the manifest has been fetched and cached
+ * @example
+ * await preloadManifest('/csszyx-manifest.json');
+ */
+declare function preloadManifest(url?: string): Promise<void>;
+/**
+ * Releases all CSSStyleSheet tiers from adoptedStyleSheets, clears the
+ * injected class cache, and resets the manifest reference.
+ *
+ * Call on route unmount when the dynamic-styled component tree is destroyed.
+ * Next dynamic() call will re-fetch the manifest and re-init sheets.
+ *
+ * @example
+ * useEffect(() => {
+ *     return () => cleanup();
+ * }, []);
+ */
+declare function cleanup(): void;
+
+export { cleanup, dynamic, preloadManifest };
+export type { CSSManifest, Tier };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import '@csszyx/compiler/browser';
+export { a as cleanup, d as dynamic, b as preloadManifest } from './shared/dynamic.BLXLKBNg.mjs';

package/dist/react.d.mts

@@ -0,0 +1,86 @@
+import { SzObject } from '@csszyx/compiler/browser';
+import { ReactNode, ReactElement } from 'react';
+import { dynamic } from './index.mjs';
+
+/**
+ * React integration for @csszyx/dynamic.
+ *
+ * Provides:
+ * - sz: direct alias for dynamic() (cleaner import in React files)
+ * - useSz(): hook returning stable { sz } object with cleanup on unmount
+ * - CsszyxProvider: optional context for custom manifest URL
+ *
+ * @example
+ * // Simple usage
+ * import { sz } from '@csszyx/dynamic/react';
+ * const cls = sz({ p: 4, bg: 'blue-500' });
+ *
+ * @example
+ * // Hook usage (recommended — handles manifest + cleanup automatically)
+ * import { useSz } from '@csszyx/dynamic/react';
+ * function FormField({ schema }) {
+ *     const { sz } = useSz();
+ *     return <div className={sz(schema.style)}>{schema.label}</div>;
+ * }
+ *
+ * @example
+ * // Custom manifest URL
+ * import { CsszyxProvider } from '@csszyx/dynamic/react';
+ * <CsszyxProvider manifest="/assets/csszyx-manifest.json">
+ *     <App />
+ * </CsszyxProvider>
+ */
+
+/**
+ * Runtime alias for dynamic(). Use in React files for consistency with
+ * the build-time `sz` prop: `sz={{ p: 4 }}` at build, `sz({ p: 4 })` at runtime.
+ */
+declare const sz: typeof dynamic;
+/**
+ *
+ */
+interface UseSzReturn {
+    /**
+     * Converts sz props to a class string, injecting CSS for new classes.
+     * Stable reference — safe to pass as a prop without useMemo.
+     */
+    sz: (props: SzObject) => string;
+}
+/**
+ * React hook for runtime dynamic styling.
+ *
+ * Returns a stable `{ sz }` object. Preloads the manifest on mount.
+ * On unmount, releases CSSStyleSheet tiers and manifest cache — deferred
+ * to survive React 18 StrictMode's double-mount/unmount cycle.
+ *
+ * @returns stable object containing the sz function for converting sz props to class strings
+ * @example
+ * const { sz } = useSz();
+ * return <div className={sz(apiResponse.field.style)} />;
+ */
+declare function useSz(): UseSzReturn;
+/**
+ *
+ */
+interface CsszyxProviderProps {
+    /** Custom manifest URL (default: '/csszyx-manifest.json'). */
+    manifest: string;
+    children: ReactNode;
+}
+/**
+ * Optional React context for custom manifest path or non-root deployments.
+ * Without Provider, dynamic() defaults to fetching /csszyx-manifest.json.
+ *
+ * @param props - component props
+ * @param props.manifest - URL to the csszyx manifest JSON file
+ * @param props.children - child React nodes to render within the provider
+ * @returns React element wrapping children in a CsszyxContext.Provider
+ * @example
+ * <CsszyxProvider manifest="/api/assets/csszyx-manifest.json">
+ *     <App />
+ * </CsszyxProvider>
+ */
+declare function CsszyxProvider({ manifest, children }: CsszyxProviderProps): ReactElement;
+
+export { CsszyxProvider, sz, useSz };
+export type { UseSzReturn };

package/dist/react.mjs

@@ -0,0 +1,37 @@
+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.BLXLKBNg.mjs';
+import '@csszyx/compiler/browser';
+
+const CsszyxContext = createContext({
+  manifestUrl: "/csszyx-manifest.json"
+});
+const sz = dynamic;
+let _cleanupTimer = null;
+function useSz() {
+  const { manifestUrl } = useContext(CsszyxContext);
+  const stableSz = useCallback((props) => dynamic(props), []);
+  useEffect(() => {
+    if (_cleanupTimer !== null) {
+      clearTimeout(_cleanupTimer);
+      _cleanupTimer = null;
+    }
+    preloadManifest(manifestUrl);
+    return () => {
+      _cleanupTimer = setTimeout(() => {
+        cleanup();
+        resetManifest();
+        _cleanupTimer = null;
+      }, 0);
+    };
+  }, [manifestUrl]);
+  return { sz: stableSz };
+}
+function CsszyxProvider({ manifest, children }) {
+  useEffect(() => {
+    setManifestUrl(manifest);
+    preloadManifest(manifest);
+  }, [manifest]);
+  return createElement(CsszyxContext.Provider, { value: { manifestUrl: manifest } }, children);
+}
+
+export { CsszyxProvider, sz, useSz };