@cube-dev/ui-kit 0.98.8 → 0.99.0

package/es/tasty/hooks/useRawCSS.js

@@ -0,0 +1,40 @@
+/**
+ * @license MIT
+ * author: Cube Dev Team
+ * @cube-dev/ui-kit v0.99.0
+ * Released under the MIT license.
+ */
+
+import { useInsertionEffect, useMemo, useRef } from 'react';
+import { injectRawCSS } from '../injector/index.js';
+// Implementation
+export function useRawCSS(cssOrFactory, depsOrOptions, options) {
+    // Detect which overload is being used
+    const isFactory = typeof cssOrFactory === 'function';
+    // Parse arguments based on overload
+    const deps = isFactory && Array.isArray(depsOrOptions) ? depsOrOptions : undefined;
+    const opts = isFactory
+        ? options
+        : depsOrOptions;
+    // Memoize CSS - for factory functions, use provided deps; for strings, use the string itself
+    const css = useMemo(() => isFactory ? cssOrFactory() : cssOrFactory, isFactory ? deps ?? [] : [cssOrFactory]);
+    const disposeRef = useRef(null);
+    useInsertionEffect(() => {
+        // Dispose previous injection if any
+        disposeRef.current?.();
+        if (!css.trim()) {
+            disposeRef.current = null;
+            return;
+        }
+        // Inject new CSS
+        const { dispose } = injectRawCSS(css, opts);
+        disposeRef.current = dispose;
+        // Cleanup on unmount or when css changes
+        return () => {
+            disposeRef.current?.();
+            disposeRef.current = null;
+        };
+    }, [css, opts?.root]);
+}
+
+        

package/es/tasty/hooks/useStyles.js

@@ -0,0 +1,206 @@
+/**
+ * @license MIT
+ * author: Cube Dev Team
+ * @cube-dev/ui-kit v0.99.0
+ * Released under the MIT license.
+ */
+
+import { useInsertionEffect, useMemo, useRef } from 'react';
+import { categorizeStyleKeys, CHUNK_NAMES, generateChunkCacheKey, renderStylesForChunk, } from '../chunks/index.js';
+import { getGlobalKeyframes, hasGlobalKeyframes } from '../config.js';
+import { allocateClassName, inject, keyframes } from '../injector/index.js';
+import { extractAnimationNamesFromStyles, extractLocalKeyframes, filterUsedKeyframes, hasLocalKeyframes, mergeKeyframes, replaceAnimationNames, } from '../keyframes/index.js';
+import { renderStyles } from '../pipeline/index.js';
+import { stringifyStyles } from '../utils/styles.js';
+/**
+ * Check if styles contain @starting-style rules.
+ *
+ * @starting-style CSS cannot be applied via multiple class names because
+ * of cascade - later rules override earlier ones. When @starting is detected,
+ * we disable chunking and use a single class name for all styles.
+ */
+function containsStartingStyle(styleKey) {
+    return styleKey.includes('@starting');
+}
+/**
+ * Get keyframes that are actually used in styles.
+ * Returns null if no keyframes are used (fast path for zero overhead).
+ *
+ * Optimization order:
+ * 1. Check if any keyframes are defined (local or global) - if not, return null
+ * 2. Extract animation names from styles - if none, return null
+ * 3. Merge and filter keyframes to only used ones
+ */
+function getUsedKeyframes(styles) {
+    // Fast path: no keyframes defined anywhere
+    const hasLocal = hasLocalKeyframes(styles);
+    const hasGlobal = hasGlobalKeyframes();
+    if (!hasLocal && !hasGlobal)
+        return null;
+    // Extract animation names from styles (not from rendered CSS - faster)
+    const usedNames = extractAnimationNamesFromStyles(styles);
+    if (usedNames.size === 0)
+        return null;
+    // Merge local and global keyframes
+    const local = hasLocal ? extractLocalKeyframes(styles) : null;
+    const global = hasGlobal ? getGlobalKeyframes() : null;
+    const allKeyframes = mergeKeyframes(local, global);
+    // Filter to only used keyframes
+    return filterUsedKeyframes(allKeyframes, usedNames);
+}
+/**
+ * Hook to generate CSS classes from Tasty styles.
+ * Handles style rendering, className allocation, and CSS injection.
+ *
+ * Uses chunking to split styles into logical groups for better caching
+ * and CSS reuse across components.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { className } = useStyles({
+ *     padding: '2x',
+ *     fill: '#purple',
+ *     radius: '1r',
+ *   });
+ *
+ *   return <div className={className}>Styled content</div>;
+ * }
+ * ```
+ */
+export function useStyles(styles) {
+    // Array of dispose functions for each chunk
+    const disposeRef = useRef([]);
+    // Store styles by their stringified key to avoid recomputing when only reference changes
+    const stylesRef = useRef({
+        key: '',
+        styles: undefined,
+    });
+    // Compute style key - this is a primitive string that captures style content
+    const styleKey = useMemo(() => {
+        if (!styles || Object.keys(styles).length === 0) {
+            return '';
+        }
+        return stringifyStyles(styles);
+    }, [styles]);
+    // Update ref when styleKey changes (content actually changed)
+    if (stylesRef.current.key !== styleKey) {
+        stylesRef.current = { key: styleKey, styles };
+    }
+    // Process chunks: categorize, generate cache keys, render, and allocate classNames
+    // Only depends on styleKey (primitive), not styles object reference
+    const processedChunks = useMemo(() => {
+        const currentStyles = stylesRef.current.styles;
+        if (!styleKey || !currentStyles) {
+            return [];
+        }
+        // Disable chunking for styles containing @starting-style rules.
+        // @starting-style CSS cannot work with multiple class names due to cascade -
+        // the rules would override each other instead of combining properly.
+        if (containsStartingStyle(styleKey)) {
+            const renderResult = renderStyles(currentStyles);
+            if (renderResult.rules.length === 0) {
+                return [];
+            }
+            const { className } = allocateClassName(styleKey);
+            return [
+                {
+                    name: CHUNK_NAMES.COMBINED,
+                    styleKeys: Object.keys(currentStyles),
+                    cacheKey: styleKey,
+                    renderResult,
+                    className,
+                },
+            ];
+        }
+        // Categorize style keys into chunks
+        const chunkMap = categorizeStyleKeys(currentStyles);
+        const chunks = [];
+        for (const [chunkName, chunkStyleKeys] of chunkMap) {
+            // Skip empty chunks
+            if (chunkStyleKeys.length === 0) {
+                continue;
+            }
+            // Generate cache key for this chunk
+            const cacheKey = generateChunkCacheKey(currentStyles, chunkName, chunkStyleKeys);
+            // Render styles for this chunk
+            const renderResult = renderStylesForChunk(currentStyles, chunkName, chunkStyleKeys);
+            // Skip chunks with no rules
+            if (renderResult.rules.length === 0) {
+                continue;
+            }
+            // Allocate className for this chunk (safe in render phase)
+            const { className } = allocateClassName(cacheKey);
+            chunks.push({
+                name: chunkName,
+                styleKeys: chunkStyleKeys,
+                cacheKey,
+                renderResult,
+                className,
+            });
+        }
+        return chunks;
+    }, [styleKey]);
+    // Inject styles in insertion effect (avoids render phase side effects)
+    useInsertionEffect(() => {
+        // Cleanup all previous disposals
+        disposeRef.current.forEach((dispose) => dispose?.());
+        disposeRef.current = [];
+        // Fast path: no chunks to inject
+        if (processedChunks.length === 0) {
+            return;
+        }
+        const currentStyles = stylesRef.current.styles;
+        // Get keyframes that are actually used (returns null if none - zero overhead)
+        const usedKeyframes = currentStyles
+            ? getUsedKeyframes(currentStyles)
+            : null;
+        // Inject keyframes and build name map (only if we have keyframes)
+        let nameMap = null;
+        if (usedKeyframes) {
+            nameMap = new Map();
+            for (const [name, steps] of Object.entries(usedKeyframes)) {
+                const result = keyframes(steps, { name });
+                const injectedName = result.toString();
+                // Only add to map if name differs (optimization for replacement check)
+                if (injectedName !== name) {
+                    nameMap.set(name, injectedName);
+                }
+                disposeRef.current.push(result.dispose);
+            }
+            // Clear map if no replacements needed
+            if (nameMap.size === 0) {
+                nameMap = null;
+            }
+        }
+        // Inject each chunk
+        for (const chunk of processedChunks) {
+            if (chunk.renderResult.rules.length > 0) {
+                // Replace animation names only if needed
+                const rulesToInject = nameMap
+                    ? chunk.renderResult.rules.map((rule) => ({
+                        ...rule,
+                        declarations: replaceAnimationNames(rule.declarations, nameMap),
+                    }))
+                    : chunk.renderResult.rules;
+                const { dispose } = inject(rulesToInject, {
+                    cacheKey: chunk.cacheKey,
+                });
+                disposeRef.current.push(dispose);
+            }
+        }
+        return () => {
+            disposeRef.current.forEach((dispose) => dispose?.());
+            disposeRef.current = [];
+        };
+    }, [processedChunks]);
+    // Combine all chunk classNames
+    const className = useMemo(() => {
+        return processedChunks.map((chunk) => chunk.className).join(' ');
+    }, [processedChunks]);
+    return {
+        className,
+    };
+}
+
+        

package/es/tasty/index.js

@@ -1,25 +1,39 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.98.8
+ * @cube-dev/ui-kit v0.99.0
  * Released under the MIT license.
  */
 
-export { tasty, Element } from './tasty';
-export * from './utils/filterBaseProps';
-export * from './utils/colors';
-export * from './utils/styles';
-export * from './utils/modAttrs';
-export * from './utils/responsive';
-export * from './utils/renderStyles';
-export * from './utils/dotize';
-export * from './styles/list';
-export * from './providers/BreakpointsProvider';
-export * from './utils/mergeStyles';
-export * from './utils/warnings';
-export * from './utils/getDisplayName';
-export * from './utils/processTokens';
-export * from './injector';
-export * from './debug';
+// Register built-in plugins at module load time
+import { configure } from './config.js';
+import { okhslPlugin } from './plugins/index.js';
+export { tasty, Element } from './tasty.js';
+export { useStyles, useGlobalStyles, useRawCSS } from './hooks/index.js';
+// Configuration API
+export { configure, getConfig, isConfigLocked, hasStylesGenerated, resetConfig, isTestEnvironment, hasGlobalKeyframes, getGlobalKeyframes, } from './config.js';
+// Plugins
+export { okhslPlugin, okhslFunc } from './plugins/index.js';
+configure({
+    plugins: [okhslPlugin()],
+});
+// Chunk utilities for advanced use cases
+export { CHUNK_NAMES, STYLE_TO_CHUNK, categorizeStyleKeys } from './chunks/index.js';
+// Advanced state mapping utilities
+export { getGlobalPredefinedStates, setGlobalPredefinedStates } from './states/index.js';
+export * from './utils/filterBaseProps.js';
+export * from './utils/colors.js';
+export * from './utils/styles.js';
+export * from './utils/modAttrs.js';
+export { renderStyles, isSelector } from './pipeline/index.js';
+export * from './utils/dotize.js';
+export * from './styles/list.js';
+export * from './utils/mergeStyles.js';
+export * from './utils/warnings.js';
+export * from './utils/getDisplayName.js';
+export * from './utils/processTokens.js';
+export * from './utils/typography.js';
+export * from './injector/index.js';
+export * from './debug.js';
 
         

package/es/tasty/injector/index.js

@@ -1,85 +1,12 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.98.8
+ * @cube-dev/ui-kit v0.99.0
  * Released under the MIT license.
  */
 
-import { isDevEnv } from '../utils/isDevEnv';
-import { StyleInjector } from './injector';
-// Use a more robust global singleton that survives React Strict Mode
-const GLOBAL_INJECTOR_KEY = '__TASTY_GLOBAL_INJECTOR__';
-/**
- * Detect if we're running in a test environment
- */
-function isTestEnvironment() {
-    // Check Node.js environment
-    if (typeof process !== 'undefined' && process.env?.NODE_ENV === 'test') {
-        return true;
-    }
-    // Check for Jest globals (safely)
-    if (typeof global !== 'undefined') {
-        const g = global;
-        if (g.jest || g.expect || g.describe || g.it) {
-            return true;
-        }
-    }
-    // Check for jsdom environment (common in tests)
-    if (typeof window !== 'undefined' &&
-        window.navigator?.userAgent?.includes('jsdom')) {
-        return true;
-    }
-    // Check for other test runners
-    if (typeof globalThis !== 'undefined') {
-        const gt = globalThis;
-        if (gt.vitest || gt.mocha) {
-            return true;
-        }
-    }
-    return false;
-}
-/**
- * Create default configuration with optional test environment detection
- */
-function createDefaultConfig(isTest) {
-    return {
-        maxRulesPerSheet: 8192, // safer default cap per sheet
-        unusedStylesThreshold: 500, // default threshold for bulk cleanup of unused styles
-        bulkCleanupDelay: 5000, // default delay before bulk cleanup (ignored if idleCleanup is true)
-        idleCleanup: true, // default to using requestIdleCallback instead of setTimeout
-        forceTextInjection: isTest ?? false, // auto-enable for test environments
-        devMode: isDevEnv(), // enable dev features: performance tracking and debug info
-        bulkCleanupBatchRatio: 0.5,
-        unusedStylesMinAgeMs: 10000,
-    };
-}
-/**
- * Configure the global style injector
- */
-export function configure(config = {}) {
-    const fullConfig = {
-        ...createDefaultConfig(),
-        ...config,
-    };
-    // Store on window to survive React Strict Mode resets
-    if (typeof window !== 'undefined') {
-        window[GLOBAL_INJECTOR_KEY] = new StyleInjector(fullConfig);
-    }
-    else {
-        // Fallback for SSR
-        globalThis[GLOBAL_INJECTOR_KEY] = new StyleInjector(fullConfig);
-    }
-}
-/**
- * Get or create the global injector instance
- */
-function getGlobalInjector() {
-    const storage = typeof window !== 'undefined' ? window : globalThis;
-    if (!storage[GLOBAL_INJECTOR_KEY]) {
-        configure();
-    }
-    return storage[GLOBAL_INJECTOR_KEY];
-}
+import { getConfig, getGlobalInjector, isTestEnvironment, markStylesGenerated, } from '../config.js';
+import { StyleInjector } from './injector.js';
 /**
  * Allocate a className for a cacheKey without injecting styles yet
  */
@@ -90,6 +17,8 @@ export function allocateClassName(cacheKey, options) {
  * Inject styles and return className with dispose function
  */
 export function inject(rules, options) {
+    // Mark that styles have been generated (prevents configuration changes)
+    markStylesGenerated();
     return getGlobalInjector().inject(rules, options);
 }
 /**
@@ -99,10 +28,30 @@ export function injectGlobal(rules, options) {
     return getGlobalInjector().injectGlobal(rules, options);
 }
 /**
- * Internal method for createGlobalStyle - not exported publicly
+ * Inject raw CSS text directly without parsing
+ * This is a low-overhead method for injecting raw CSS that doesn't need tasty processing.
+ * The CSS is inserted into a separate style element to avoid conflicts with tasty's chunking.
+ *
+ * @example
+ * ```tsx
+ * // Inject raw CSS
+ * const { dispose } = injectRawCSS(`
+ *   body { margin: 0; padding: 0; }
+ *   .my-class { color: red; }
+ * `);
+ *
+ * // Later, remove the injected CSS
+ * dispose();
+ * ```
+ */
+export function injectRawCSS(css, options) {
+    return getGlobalInjector().injectRawCSS(css, options);
+}
+/**
+ * Get raw CSS text for SSR
  */
-function injectCreateGlobalStyle(rules, options) {
-    return getGlobalInjector().injectCreateGlobalStyle(rules, options);
+export function getRawCSSText(options) {
+    return getGlobalInjector().getRawCSSText(options);
 }
 /**
  * Inject keyframes and return object with toString() and dispose()
@@ -173,21 +122,16 @@ export function destroy(root) {
  * Create a new isolated injector instance
  */
 export function createInjector(config = {}) {
-    const isTest = isTestEnvironment();
+    const defaultConfig = getConfig();
     const fullConfig = {
-        ...createDefaultConfig(isTest),
+        ...defaultConfig,
+        // Auto-enable forceTextInjection in test environments
+        forceTextInjection: config.forceTextInjection ?? isTestEnvironment(),
         ...config,
     };
     return new StyleInjector(fullConfig);
 }
-/**
- * Create a global style component like styled-components createGlobalStyle
- * Returns a React component that injects global styles when mounted and cleans up when unmounted
- */
-export function createGlobalStyle(strings, ...interpolations) {
-    return getGlobalInjector().createGlobalStyle(strings, ...interpolations);
-}
-export { StyleInjector } from './injector';
-export { SheetManager } from './sheet-manager';
+export { StyleInjector } from './injector.js';
+export { SheetManager } from './sheet-manager.js';