@csszyx/dynamic 0.7.0 → 0.9.0

package/src/index.ts

@@ -1,122 +0,0 @@
-/**
- * @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"
- */
-
-// Import only the browser-safe (pure JS, no WASM) transform sub-path.
-// The main '@csszyx/compiler' entry bundles @csszyx/core (WASM) which cannot
-// run in browsers without a dedicated WASM loader.
-import type { ReadonlySzObject, SzObject } from '@csszyx/compiler/browser';
-import { transform } from '@csszyx/compiler/browser';
-
-import { generateCSSRule } from './css-generator.js';
-import { cleanup as injectorCleanup, injectRule, resolveTier } from './injector.js';
-import { ensureManifest, lookupManifest, preloadManifest as manifestPreload, resetManifest } from './manifest.js';
-import { isServer } from './ssr.js';
-
-export type { Tier } from './css-generator.js';
-export type { CSSManifest } from './manifest.js';
-export type { ReadonlySzObject, SzObject } from '@csszyx/compiler/browser';
-
-/**
- * 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)
- */
-export function dynamic(szProps: SzObject | ReadonlySzObject): string {
-    const { className } = transform(szProps as SzObject);
-    if (!className) {return '';}
-
-    if (isServer) {
-        // SSR: apply the mangle map if the Vite plugin exposed it via globalThis.
-        // The plugin sets __csszyx_ssr_mangle_map in buildEnd(), which runs before
-        // SSG rendering (Astro, Next.js) in the same Node.js process. Without this,
-        // dynamic() returns unmangled names (e.g. "p-4") while built CSS only has
-        // mangled selectors (e.g. ".q0"), so styles silently don't apply in SSR HTML.
-        const ssrMangleMap = (globalThis as Record<string, unknown>).__csszyx_ssr_mangle_map as Record<string, string> | undefined;
-        if (ssrMangleMap) {
-            return className.split(' ').filter(Boolean)
-                .map(c => ssrMangleMap[c] ?? c)
-                .join(' ');
-        }
-        return className;
-    }
-
-    // Trigger manifest lazy-load (non-blocking — first render uses whatever is loaded)
-    ensureManifest();
-
-    const classes = className.split(' ').filter(Boolean);
-    const outputClasses: string[] = [];
-
-    for (const cls of classes) {
-        const manifestResult = lookupManifest(cls);
-
-        if (manifestResult !== null) {
-            // Class is in built CSS. Use the resolved name (mangled in production).
-            outputClasses.push(manifestResult);
-        } else {
-            // Class is not in built CSS — inject CSS rule.
-            const tier = resolveTier(cls);
-            const rule = generateCSSRule(cls);
-            injectRule(cls, rule, tier);
-            outputClasses.push(cls);
-        }
-    }
-
-    return outputClasses.join(' ');
-}
-
-/**
- * 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');
- */
-export async function preloadManifest(url?: string): Promise<void> {
-    return manifestPreload(url);
-}
-
-/**
- * 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();
- * }, []);
- */
-export function cleanup(): void {
-    injectorCleanup();
-    resetManifest();
-}

package/src/injector.ts

@@ -1,226 +0,0 @@
-/**
- * CSSOM Injection with 21-tier CSSStyleSheet architecture.
- *
- * WHY 21 SHEETS:
- * Injecting all rules into a single sheet breaks cascade order.
- * If a linter sorts object keys alphabetically (lg, md, sm),
- * sm:p-4 could end up injected AFTER lg:p-8 — at 640px both @media
- * rules match and the later-injected sm rule incorrectly wins.
- *
- * Fix: One CSSStyleSheet per breakpoint tier. The `adoptedStyleSheets`
- * array ORDER determines cascade — not insertion time. Sheets are created
- * once in the correct ascending order and never reordered.
- *
- * CSS @layer collision note:
- * Tailwind v4 utilities are in `@layer utilities`. Rules injected via
- * CSSStyleSheet.insertRule() are unlayered — unlayered beats ALL layered
- * styles at equal specificity (CSS Cascade Level 5). This is intentional:
- * - Classes in manifest → delta check skips injection → no conflict
- * - Truly new classes → not in built CSS → no conflict
- * - Stale manifest → injected rule overrides built rule (same CSS value)
- */
-
-import { BREAKPOINTS, type Tier } from './css-generator.js';
-
-// ── Tier ordering ─────────────────────────────────────────────────────────────
-
-/**
- * 21 tiers in cascade order (index = priority, higher = wins).
- *
- * max-* tiers are DESCENDING by breakpoint size (opposite of min-*).
- * At a small viewport (e.g. 400px), ALL max-* variants match.
- * The most restrictive (max-sm = ≤640px) must win → must appear LAST.
- * Example at 400px: max-2xl, max-xl, max-lg, max-md, max-sm all match.
- * max-sm should win → index(max-sm) > index(max-md) > ... > index(max-2xl).
- */
-export const TIER_ORDER: readonly Tier[] = [
-    'base',
-    // viewport min-width (ascending — sm wins over base, lg wins over md)
-    'sm', 'md', 'lg', 'xl', '2xl',
-    // viewport max-width (descending size — max-sm is most restrictive, must win)
-    'max-2xl', 'max-xl', 'max-lg', 'max-md', 'max-sm',
-    // container query min (ascending)
-    '@sm', '@md', '@lg', '@xl', '@2xl',
-    // container query max (descending)
-    '@max-2xl', '@max-xl', '@max-lg', '@max-md', '@max-sm',
-] as const;
-
-const TIER_SET = new Set<string>(TIER_ORDER);
-
-/**
- * Returns true if constructable stylesheets are available in the current environment.
- *
- * @returns true when CSSStyleSheet and adoptedStyleSheets are both supported
- */
-function supportsConstructableSheets(): boolean {
-    return typeof document !== 'undefined' &&
-        typeof CSSStyleSheet !== 'undefined' &&
-        'adoptedStyleSheets' in document;
-}
-
-// ── Module state ──────────────────────────────────────────────────────────────
-
-let sheets: Map<Tier, CSSStyleSheet> | null = null;
-
-/** StyleElement fallback for environments without constructable stylesheets. */
-let fallbackStyle: HTMLStyleElement | null = null;
-
-/** Set of all class names injected this session (prevents double inject). */
-const injected = new Set<string>();
-
-// ── Sheet initialisation ──────────────────────────────────────────────────────
-
-/**
- * Wraps a CSS rule in the appropriate @media or @container query for non-base tiers.
- * Base sheet holds all rules directly (no wrapper).
- *
- * @param cssRule - raw CSS rule string to wrap (e.g. ".p-4 { padding: 1rem }")
- * @param tier - breakpoint tier that determines the wrapping query type
- * @returns wrapped CSS string (e.g. "@media (min-width: 40rem) { .p-4 { padding: 1rem } }")
- */
-function wrapForTier(cssRule: string, tier: Tier): string {
-    if (tier === 'base') {return cssRule;}
-
-    // Container query tiers: @sm, @md, @lg, @xl, @2xl, @max-*
-    if (tier.startsWith('@')) {
-        const bp = tier.slice(1); // '@sm' → 'sm', '@max-sm' → 'max-sm'
-        const bpValue = BREAKPOINTS[bp];
-        if (!bpValue) {return cssRule;}
-        const query = bp.startsWith('max-')
-            ? `(width <= ${bpValue})`
-            : `(width >= ${bpValue})`;
-        return `@container ${query} { ${cssRule} }`;
-    }
-
-    // Viewport tiers: sm, md, lg, xl, 2xl, max-sm, max-md, ...
-    const bpValue = BREAKPOINTS[tier];
-    if (!bpValue) {return cssRule;}
-
-    const query = tier.startsWith('max-')
-        ? `(max-width: ${bpValue})`
-        : `(min-width: ${bpValue})`;
-    return `@media ${query} { ${cssRule} }`;
-}
-
-/**
- * Initialises one CSSStyleSheet per tier and appends them to adoptedStyleSheets in cascade order.
- *
- * @returns map from each Tier to its dedicated CSSStyleSheet
- */
-function initSheets(): Map<Tier, CSSStyleSheet> {
-    const map = new Map<Tier, CSSStyleSheet>();
-    const adopted: CSSStyleSheet[] = [];
-
-    for (const tier of TIER_ORDER) {
-        const sheet = new CSSStyleSheet();
-        map.set(tier, sheet);
-        adopted.push(sheet);
-    }
-
-    // Append to end — does NOT replace existing adoptedStyleSheets.
-    document.adoptedStyleSheets = [...document.adoptedStyleSheets, ...adopted];
-    return map;
-}
-
-/**
- * Creates and appends a fallback <style> element for environments without constructable stylesheets.
- *
- * @returns the newly created and appended HTMLStyleElement
- */
-function initFallbackStyle(): HTMLStyleElement {
-    const el = document.createElement('style');
-    el.id = '__csszyx_dynamic__';
-    document.head.appendChild(el);
-    return el;
-}
-
-// ── Tier resolution ───────────────────────────────────────────────────────────
-
-/**
- * Resolves which tier a class name belongs to based on its first variant segment.
- * Stacked variants: sm:hover:bg-blue → first segment = 'sm' → tier = sm.
- * dark:sm:bg-blue is invalid (dark is not a breakpoint) → tier = base.
- *
- * @param className - full Tailwind class name (e.g. "sm:hover:bg-blue-500")
- * @returns the breakpoint tier for this class, or 'base' if no breakpoint prefix is found
- */
-export function resolveTier(className: string): Tier {
-    const colonIdx = className.indexOf(':');
-    if (colonIdx === -1) {return 'base';}
-
-    const prefix = className.slice(0, colonIdx);
-    // Container query variants start with @
-    const normalizedPrefix = prefix.startsWith('@') ? prefix : prefix;
-
-    if (TIER_SET.has(normalizedPrefix)) {
-        return normalizedPrefix as Tier;
-    }
-    return 'base';
-}
-
-// ── Public API ────────────────────────────────────────────────────────────────
-
-/**
- * Injects a CSS rule if the class has not already been injected this session.
- * No-op if the class is already known (delta check must be done by caller via manifest).
- *
- * @param className - original Tailwind class name (used as cache key)
- * @param cssRule   - CSS rule string returned by generateCSSRule()
- * @param tier      - which tier sheet to inject into
- */
-export function injectRule(className: string, cssRule: string, tier: Tier = 'base'): void {
-    if (injected.has(className)) {return;}
-    injected.add(className);
-
-    if (!cssRule) {return;} // unknown class — still mark as "seen" to avoid repeat lookups
-
-    if (supportsConstructableSheets()) {
-        if (!sheets) {sheets = initSheets();}
-        const resolved = sheets.get(tier) ?? sheets.get('base');
-        if (!resolved) {return;}
-        const sheet = resolved;
-        const rule = wrapForTier(cssRule, tier);
-        try {
-            sheet.insertRule(rule, sheet.cssRules.length);
-        } catch {
-            // Malformed rule — silently ignore; class is still marked injected.
-        }
-    } else {
-        // Fallback: append to a <style> element
-        if (!fallbackStyle) {fallbackStyle = initFallbackStyle();}
-        const rule = wrapForTier(cssRule, tier);
-        fallbackStyle.sheet?.insertRule(rule, fallbackStyle.sheet.cssRules.length);
-    }
-}
-
-/**
- * Checks whether a class name has already been injected this session.
- * Used to skip repeated calls for the same class within a render cycle.
- *
- * @param className - original Tailwind class name to check (e.g. "p-4")
- * @returns true if the class has already been injected in the current session
- */
-export function isInjected(className: string): boolean {
-    return injected.has(className);
-}
-
-/**
- * Releases all tier sheets and clears injected state.
- * Call on route unmount / component cleanup.
- */
-export function cleanup(): void {
-    if (sheets) {
-        const tierSheets = new Set(sheets.values());
-        document.adoptedStyleSheets = document.adoptedStyleSheets.filter(
-            s => !tierSheets.has(s),
-        );
-        sheets = null;
-    }
-
-    if (fallbackStyle) {
-        fallbackStyle.remove();
-        fallbackStyle = null;
-    }
-
-    injected.clear();
-}

package/src/manifest.ts

@@ -1,119 +0,0 @@
-/**
- * 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.
- */
-
-/**
- *
- */
-export 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>;
-}
-
-// Module-level state (lazy, reset by cleanup())
-let manifestClasses: Set<string> | null = null;
-let mangleMap: Record<string, string> | null = null;
-let manifestUrl = '/csszyx-manifest.json';
-let fetchPromise: Promise<void> | null = null;
-
-/**
- * Override the manifest URL (called by CsszyxProvider).
- *
- * @param url - absolute or relative URL to the csszyx manifest JSON file
- */
-export function setManifestUrl(url: string): void {
-    manifestUrl = url;
-}
-
-/**
- * Returns true if the manifest has been loaded.
- *
- * @returns true once the manifest fetch has completed (even on failure)
- */
-export function isManifestLoaded(): boolean {
-    return manifestClasses !== null;
-}
-
-/**
- * Lazily fetches and caches the manifest.
- * Returns the in-flight promise so concurrent calls coalesce.
- *
- * @returns promise that resolves when the manifest is loaded (or silently fails)
- */
-export function ensureManifest(): Promise<void> {
-    if (manifestClasses !== null) {return Promise.resolve();}
-    if (fetchPromise) {return fetchPromise;}
-
-    fetchPromise = fetch(manifestUrl)
-        .then(r => {
-            if (!r.ok) {throw new Error(`csszyx: manifest fetch failed ${r.status}`);}
-            return r.json() as Promise<CSSManifest>;
-        })
-        .then((data: CSSManifest) => {
-            manifestClasses = new Set(data.classes);
-            mangleMap = data.mangleMap ?? null;
-        })
-        .catch(() => {
-            // Non-blocking: if manifest unavailable, all classes are treated as new.
-            manifestClasses = new Set();
-            mangleMap = null;
-            fetchPromise = null; // allow retry
-        });
-
-    return fetchPromise;
-}
-
-/**
- * Eagerly preloads the manifest. Call at app startup for zero-latency first inject.
- * Without this, the first dynamic() call triggers a lazy fetch.
- *
- * @param url - optional manifest URL override (default: '/csszyx-manifest.json')
- * @returns promise that resolves when the manifest has been fetched and cached
- */
-export async function preloadManifest(url?: string): Promise<void> {
-    if (url) {setManifestUrl(url);}
-    return ensureManifest();
-}
-
-/**
- * Returns the CSS class name to use for a given original class name.
- *
- * - If manifest says the class is pre-built AND mangle map exists: returns mangled name.
- * - If manifest says the class is pre-built, no mangle map: returns original name.
- * - If class is NOT in manifest (or manifest not yet loaded): returns null (inject needed).
- *
- * @param originalClass - the original (non-mangled) Tailwind class name to look up
- * @returns the class name to use in the DOM (mangled or original), or null if injection is needed
- */
-export function lookupManifest(originalClass: string): string | null {
-    if (manifestClasses === null) {return null;} // not loaded yet
-    if (!manifestClasses.has(originalClass)) {return null;} // not in built CSS
-
-    // Class is in built CSS
-    if (mangleMap && originalClass in mangleMap) {
-        return mangleMap[originalClass]; // return mangled name
-    }
-    return originalClass; // non-mangled build
-}
-
-/**
- * Releases all manifest state. Called by cleanup().
- * Next dynamic() call will re-fetch the manifest.
- */
-export function resetManifest(): void {
-    manifestClasses = null;
-    mangleMap = null;
-    fetchPromise = null;
-    manifestUrl = '/csszyx-manifest.json';
-}

package/src/react.ts

@@ -1,166 +0,0 @@
-/**
- * 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>
- */
-
-import type { SzObject } from '@csszyx/compiler/browser';
-import {
-    createContext,
-    createElement,
-    type ReactElement,
-    type ReactNode,
-    useCallback,
-    useContext,
-    useEffect,
-} from 'react';
-
-import { dynamic } from './index.js';
-import { cleanup as injectorCleanup } from './injector.js';
-import { preloadManifest, resetManifest, setManifestUrl } from './manifest.js';
-
-// ── Context ───────────────────────────────────────────────────────────────────
-
-/**
- *
- */
-interface CsszyxContextValue {
-    manifestUrl: string;
-}
-
-const CsszyxContext = createContext<CsszyxContextValue>({
-    manifestUrl: '/csszyx-manifest.json',
-});
-
-// ── sz alias ──────────────────────────────────────────────────────────────────
-
-/**
- * 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.
- */
-export const sz = dynamic;
-
-// ── useSz hook ────────────────────────────────────────────────────────────────
-
-/**
- *
- */
-export 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;
-}
-
-/**
- * Deferred cleanup timer — shared across all useSz instances.
- *
- * WHY DEFERRED: React 18 StrictMode fires useEffect cleanup immediately after
- * the initial mount (simulating unmount → remount to catch side-effect bugs).
- * Without deferral, the first mount injects CSS → StrictMode cleanup fires →
- * CSS is wiped → no re-render → component renders with no styles.
- *
- * With setTimeout(0): StrictMode's cleanup schedules removal, then StrictMode's
- * remount runs synchronously and cancels the timer before it fires. On a true
- * navigation away, no remount happens, so the timer fires and cleans up.
- */
-let _cleanupTimer: ReturnType<typeof setTimeout> | null = null;
-
-/**
- * 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)} />;
- */
-export function useSz(): UseSzReturn {
-    const { manifestUrl } = useContext(CsszyxContext);
-    const stableSz = useCallback((props: SzObject) => dynamic(props), []);
-
-    useEffect(() => {
-        // Cancel any pending cleanup from a previous unmount (handles StrictMode remount).
-        if (_cleanupTimer !== null) {
-            clearTimeout(_cleanupTimer);
-            _cleanupTimer = null;
-        }
-        // Pre-fetch manifest (non-blocking)
-        preloadManifest(manifestUrl);
-
-        return () => {
-            // Defer cleanup so a StrictMode remount can cancel it before it fires.
-            _cleanupTimer = setTimeout(() => {
-                injectorCleanup();
-                resetManifest();
-                _cleanupTimer = null;
-            }, 0);
-        };
-    }, [manifestUrl]);
-
-    return { sz: stableSz };
-}
-
-// ── CsszyxProvider ────────────────────────────────────────────────────────────
-
-/**
- *
- */
-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>
- */
-export function CsszyxProvider({ manifest, children }: CsszyxProviderProps): ReactElement {
-    useEffect(() => {
-        setManifestUrl(manifest);
-        preloadManifest(manifest);
-    }, [manifest]);
-
-    return createElement(
-        CsszyxContext.Provider,
-        { value: { manifestUrl: manifest } },
-        children,
-    );
-}

package/src/ssr.ts

@@ -1,5 +0,0 @@
-/**
- * SSR detection helper.
- * Used to guard CSSOM operations that are unavailable in Node.js.
- */
-export const isServer = typeof document === 'undefined';