@cube-dev/ui-kit 0.0.0-canary-4777472 → 0.0.0-canary-b26ec55

package/es/tasty/debug.js

@@ -1,13 +1,14 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.0.0-canary-4777472
+ * @cube-dev/ui-kit v0.0.0-canary-b26ec55
  * Released under the MIT license.
  */
 
 /**
  * Debug utilities for inspecting tasty-generated CSS at runtime
  */
+import { CHUNK_NAMES } from './chunks/definitions';
 import { getCssTextForNode, injector } from './injector';
 import { isDevEnv } from './utils/isDevEnv';
 /**
@@ -246,6 +247,95 @@ function getPageStats(options) {
     }
     return { cssSize, ruleCount, stylesheetCount, skippedStylesheets };
 }
+// ============================================================================
+// Chunk-aware helpers (for style chunking optimization)
+// ============================================================================
+/**
+ * Extract chunk name from a cache key.
+ *
+ * Cache keys have the format: "chunkName\0key:value\0key:value..."
+ * or "[states:...]\0chunkName\0..." for predefined states.
+ *
+ * @param cacheKey - The cache key to parse
+ * @returns The chunk name, or null if not found
+ */
+function extractChunkNameFromCacheKey(cacheKey) {
+    // Cache keys are separated by \0 (null character)
+    const parts = cacheKey.split('\0');
+    for (const part of parts) {
+        // Skip predefined states prefix
+        if (part.startsWith('[states:'))
+            continue;
+        // First non-states part that doesn't contain : is the chunk name
+        if (!part.includes(':') && part.length > 0) {
+            return part;
+        }
+    }
+    return null;
+}
+/**
+ * Get chunk info for a className by reverse-looking up its cache key.
+ *
+ * @param className - The tasty class name (e.g., "t0", "t123")
+ * @param root - The document or shadow root to search in
+ * @returns Object with chunk name and cache key, or nulls if not found
+ */
+function getChunkForClassName(className, root = document) {
+    const registry = injector.instance['sheetManager']?.getRegistry(root);
+    if (!registry) {
+        return { chunkName: null, cacheKey: null };
+    }
+    // Reverse lookup: find the cache key for this className
+    for (const [cacheKey, cn] of registry.cacheKeyToClassName) {
+        if (cn === className) {
+            return {
+                chunkName: extractChunkNameFromCacheKey(cacheKey),
+                cacheKey,
+            };
+        }
+    }
+    return { chunkName: null, cacheKey: null };
+}
+/**
+ * Get chunk breakdown statistics for all styles.
+ *
+ * @param root - The document or shadow root to search in
+ * @returns Object with breakdown by chunk type and totals
+ */
+function getChunkBreakdown(root = document) {
+    const registry = injector.instance['sheetManager']?.getRegistry(root);
+    if (!registry) {
+        return {
+            byChunk: {},
+            totalChunkTypes: 0,
+        };
+    }
+    const byChunk = {};
+    // Group classes by chunk
+    for (const [cacheKey, className] of registry.cacheKeyToClassName) {
+        const chunkName = extractChunkNameFromCacheKey(cacheKey) || 'unknown';
+        if (!byChunk[chunkName]) {
+            byChunk[chunkName] = { classes: [], cssSize: 0, ruleCount: 0 };
+        }
+        byChunk[chunkName].classes.push(className);
+        // Get CSS for this class
+        const css = injector.instance.getCssTextForClasses([className], { root });
+        byChunk[chunkName].cssSize += css.length;
+        byChunk[chunkName].ruleCount += (css.match(/\{[^}]*\}/g) || []).length;
+    }
+    // Sort classes within each chunk for consistency
+    for (const entry of Object.values(byChunk)) {
+        entry.classes.sort((a, b) => {
+            const aNum = parseInt(a.slice(1));
+            const bNum = parseInt(b.slice(1));
+            return aNum - bNum;
+        });
+    }
+    return {
+        byChunk,
+        totalChunkTypes: Object.keys(byChunk).length,
+    };
+}
 /**
  * Concise tastyDebug API for inspecting styles at runtime
  */
@@ -316,6 +406,7 @@ export const tastyDebug = {
             return {
                 element: null,
                 classes: [],
+                chunks: [],
                 css: '',
                 size: 0,
                 rules: 0,
@@ -325,12 +416,18 @@ export const tastyDebug = {
         const tastyClasses = classList
             .split(/\s+/)
             .filter((cls) => /^t\d+$/.test(cls));
+        // Get chunk info for each tasty class
+        const chunks = tastyClasses.map((className) => ({
+            className,
+            chunkName: getChunkForClassName(className, root).chunkName,
+        }));
         const css = getCssTextForNode(element, { root });
         const prettifiedCSS = prettifyCSS(css);
         const ruleCount = (css.match(/\{[^}]*\}/g) || []).length;
         return {
             element,
             classes: tastyClasses,
+            chunks,
             css: prettifiedCSS,
             size: css.length,
             rules: ruleCount,
@@ -370,7 +467,63 @@ export const tastyDebug = {
         const { root } = opts || {};
         injector.instance.resetMetrics({ root });
     },
-    // 5) Get CSS for specific global types
+    // 5) Chunk breakdown (style chunking optimization)
+    /**
+     * Get breakdown of styles by chunk type.
+     *
+     * With style chunking enabled, styles are split into logical chunks
+     * (appearance, font, dimension, container, etc.) for better caching
+     * and CSS reuse.
+     *
+     * @param opts - Options including root document/shadow root
+     * @returns Breakdown by chunk type with class counts and CSS sizes
+     */
+    chunks(opts) {
+        const { root = document, log = false } = opts || {};
+        const breakdown = getChunkBreakdown(root);
+        const totalClasses = Object.values(breakdown.byChunk).reduce((sum, entry) => sum + entry.classes.length, 0);
+        if (log) {
+            console.group('🧩 Style Chunk Breakdown');
+            // Define display order matching CHUNK_NAMES
+            const displayOrder = [
+                CHUNK_NAMES.COMBINED, // non-chunked styles (e.g., @starting-style)
+                CHUNK_NAMES.APPEARANCE,
+                CHUNK_NAMES.FONT,
+                CHUNK_NAMES.DIMENSION,
+                CHUNK_NAMES.CONTAINER,
+                CHUNK_NAMES.SCROLLBAR,
+                CHUNK_NAMES.POSITION,
+                CHUNK_NAMES.MISC,
+                CHUNK_NAMES.SUBCOMPONENTS,
+            ];
+            // Show chunks in order
+            for (const chunkName of displayOrder) {
+                const data = breakdown.byChunk[chunkName];
+                if (data) {
+                    const sizeStr = data.cssSize > 1024
+                        ? `${(data.cssSize / 1024).toFixed(1)}KB`
+                        : `${data.cssSize}B`;
+                    console.log(`  • ${chunkName}: ${data.classes.length} classes, ${sizeStr}, ${data.ruleCount} rules`);
+                }
+            }
+            // Show any unknown chunks
+            for (const [chunkName, data] of Object.entries(breakdown.byChunk)) {
+                if (!displayOrder.includes(chunkName)) {
+                    const sizeStr = data.cssSize > 1024
+                        ? `${(data.cssSize / 1024).toFixed(1)}KB`
+                        : `${data.cssSize}B`;
+                    console.log(`  • ${chunkName}: ${data.classes.length} classes, ${sizeStr}, ${data.ruleCount} rules`);
+                }
+            }
+            console.log(`📊 Total: ${totalClasses} classes across ${breakdown.totalChunkTypes} chunk types`);
+            console.groupEnd();
+        }
+        return {
+            ...breakdown,
+            totalClasses,
+        };
+    },
+    // 6) Get CSS for specific global types
     getGlobalTypeCSS(type, opts) {
         const { root = document } = opts || {};
         const registry = injector.instance['sheetManager']?.getRegistry(root);
@@ -565,6 +718,8 @@ export const tastyDebug = {
                 propertyCSSSize: Math.round(propertyData.size * scaleFactor),
             };
         }
+        // Get chunk breakdown
+        const chunkBreakdown = getChunkBreakdown(root);
         const summary = {
             activeClasses: cacheStatus.classes.active,
             unusedClasses: cacheStatus.classes.unused,
@@ -591,6 +746,7 @@ export const tastyDebug = {
             propertyCount: definitions.properties.length,
             keyframeCount: definitions.keyframes.length,
             cleanupSummary,
+            chunkBreakdown,
         };
         if (log) {
             console.group('🎨 Comprehensive Tasty Debug Summary');
@@ -602,7 +758,7 @@ export const tastyDebug = {
             console.log(`  • Active CSS: ${summary.activeCSSSize} characters`);
             console.log(`  • Unused CSS: ${summary.unusedCSSSize} characters`);
             console.log(`  • Global CSS (injectGlobal): ${summary.globalCSSSize} characters (${summary.globalRuleCount} rules)`);
-            console.log(`  • Raw CSS (createGlobalStyle): ${summary.rawCSSSize} characters (${summary.rawRuleCount} rules)`);
+            console.log(`  • Raw CSS (injectRawCSS/useRawCSS): ${summary.rawCSSSize} characters (${summary.rawRuleCount} rules)`);
             console.log(`  • Keyframes CSS: ${summary.keyframesCSSSize} characters (${summary.keyframesRuleCount} rules)`);
             console.log(`  • Property CSS: ${summary.propertyCSSSize} characters (${summary.propertyRuleCount} rules)`);
             // Show breakdown calculation
@@ -652,6 +808,30 @@ export const tastyDebug = {
                     : '0';
                 console.log(`  • Overall cache hit rate: ${hitRate}%`);
             }
+            // Show chunk breakdown
+            if (summary.chunkBreakdown.totalChunkTypes > 0) {
+                console.log('🧩 Style Chunk Breakdown:');
+                const displayOrder = [
+                    CHUNK_NAMES.COMBINED, // non-chunked styles (e.g., @starting-style)
+                    CHUNK_NAMES.APPEARANCE,
+                    CHUNK_NAMES.FONT,
+                    CHUNK_NAMES.DIMENSION,
+                    CHUNK_NAMES.CONTAINER,
+                    CHUNK_NAMES.SCROLLBAR,
+                    CHUNK_NAMES.POSITION,
+                    CHUNK_NAMES.MISC,
+                    CHUNK_NAMES.SUBCOMPONENTS,
+                ];
+                for (const chunkName of displayOrder) {
+                    const data = summary.chunkBreakdown.byChunk[chunkName];
+                    if (data) {
+                        const sizeStr = data.cssSize > 1024
+                            ? `${(data.cssSize / 1024).toFixed(1)}KB`
+                            : `${data.cssSize}B`;
+                        console.log(`  • ${chunkName}: ${data.classes.length} classes, ${sizeStr}, ${data.ruleCount} rules`);
+                    }
+                }
+            }
             console.log('🔍 Details:');
             console.log('  • Active classes:', summary.activeClasses);
             console.log('  • Unused classes:', summary.unusedClasses);
@@ -735,15 +915,15 @@ export const tastyDebug = {
         console.groupEnd();
         console.groupEnd();
     },
-    // 11) Show help and usage examples
+    // 12) Show help and usage examples
     help() {
         console.group('🎨 tastyDebug - Quick Start Guide');
         console.log('💡 Essential commands:');
         console.log('  • tastyDebug.summary({ log: true }) - comprehensive overview');
+        console.log('  • tastyDebug.chunks({ log: true }) - style chunk breakdown');
         console.log('  • tastyDebug.log("active") - beautiful CSS display');
         console.log('  • tastyDebug.css("active") - get active CSS');
-        console.log('  • tastyDebug.inspect(".my-element") - detailed element inspection');
-        console.log('  • tastyDebug.global({ log: true }) - global CSS analysis');
+        console.log('  • tastyDebug.inspect(".my-element") - element inspection with chunk info');
         console.log('  • tastyDebug.cache() - cache status');
         console.log('  • tastyDebug.defs() - defined properties & keyframes');
         console.log('  • tastyDebug.pageCSS({ log: true }) - all page CSS');
@@ -752,7 +932,7 @@ export const tastyDebug = {
         console.log('  • "all" - all tasty CSS + global CSS');
         console.log('  • "active" - CSS for classes in DOM');
         console.log('  • "unused" - CSS for classes with refCount = 0');
-        console.log('  • "global" - only global CSS (createGlobalStyle)');
+        console.log('  • "global" - only global CSS (injectGlobal)');
         console.log('  • "page" - ALL page CSS (including non-tasty)');
         console.log('  • "t123" - specific tasty class');
         console.log('  • [".my-selector"] - CSS selector');
@@ -762,6 +942,12 @@ export const tastyDebug = {
         console.log('  • { title: "Custom" } - custom title for log()');
         console.log('  • { root: shadowRoot } - target Shadow DOM');
         console.log('  • { prettify: false } - skip CSS formatting');
+        console.log('');
+        console.log('🧩 Style Chunking:');
+        console.log('  Elements have multiple classes (one per chunk: appearance, font, dimension, etc.)');
+        console.log('  • tastyDebug.chunks({ log: true }) - breakdown by chunk type');
+        console.log('  • tastyDebug.inspect() - shows which chunk each class belongs to');
+        console.log('  Chunk types: combined (non-chunked), appearance, font, dimension, container, scrollbar, position, misc, subcomponents');
         console.groupEnd();
     },
 };

package/es/tasty/hooks/index.js

@@ -0,0 +1,12 @@
+/**
+ * @license MIT
+ * author: Cube Dev Team
+ * @cube-dev/ui-kit v0.0.0-canary-b26ec55
+ * Released under the MIT license.
+ */
+
+export { useStyles } from './useStyles';
+export { useGlobalStyles } from './useGlobalStyles';
+export { useRawCSS } from './useRawCSS';
+
+        

package/es/tasty/hooks/useGlobalStyles.js

@@ -0,0 +1,67 @@
+/**
+ * @license MIT
+ * author: Cube Dev Team
+ * @cube-dev/ui-kit v0.0.0-canary-b26ec55
+ * Released under the MIT license.
+ */
+
+import { useInsertionEffect, useMemo, useRef } from 'react';
+import { injectGlobal } from '../injector';
+import { renderStyles } from '../pipeline';
+/**
+ * Hook to inject global styles for a given selector.
+ * Useful for styling elements by selector without generating classNames.
+ *
+ * @param selector - CSS selector to apply styles to (e.g., '.my-class', ':root', 'body')
+ * @param styles - Tasty styles object
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   useGlobalStyles('.card', {
+ *     padding: '2x',
+ *     radius: '1r',
+ *     fill: '#white',
+ *   });
+ *
+ *   return <div className="card">Content</div>;
+ * }
+ * ```
+ */
+export function useGlobalStyles(selector, styles) {
+    const disposeRef = useRef(null);
+    // Render styles with the provided selector
+    // Note: renderStyles overload with selector string returns StyleResult[] directly
+    const styleResults = useMemo(() => {
+        if (!styles)
+            return [];
+        // Validate selector - empty string would cause renderStyles to return RenderResult instead of StyleResult[]
+        if (!selector) {
+            if (process.env.NODE_ENV !== 'production') {
+                console.warn('[Tasty] useGlobalStyles: selector is required and cannot be empty. ' +
+                    'Styles will not be injected.');
+            }
+            return [];
+        }
+        const result = renderStyles(styles, selector);
+        // When a non-empty selector is provided, renderStyles returns StyleResult[]
+        return result;
+    }, [styles, selector]);
+    // Inject as global styles
+    useInsertionEffect(() => {
+        disposeRef.current?.();
+        if (styleResults.length > 0) {
+            const { dispose } = injectGlobal(styleResults);
+            disposeRef.current = dispose;
+        }
+        else {
+            disposeRef.current = null;
+        }
+        return () => {
+            disposeRef.current?.();
+            disposeRef.current = null;
+        };
+    }, [styleResults]);
+}
+
+        

package/es/tasty/hooks/useRawCSS.js

@@ -0,0 +1,40 @@
+/**
+ * @license MIT
+ * author: Cube Dev Team
+ * @cube-dev/ui-kit v0.0.0-canary-b26ec55
+ * Released under the MIT license.
+ */
+
+import { useInsertionEffect, useMemo, useRef } from 'react';
+import { injectRawCSS } from '../injector';
+// 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,146 @@
+/**
+ * @license MIT
+ * author: Cube Dev Team
+ * @cube-dev/ui-kit v0.0.0-canary-b26ec55
+ * Released under the MIT license.
+ */
+
+import { useInsertionEffect, useMemo, useRef } from 'react';
+import { categorizeStyleKeys, CHUNK_NAMES, generateChunkCacheKey, renderStylesForChunk, } from '../chunks';
+import { allocateClassName, inject } from '../injector';
+import { renderStyles } from '../pipeline';
+import { stringifyStyles } from '../utils/styles';
+/**
+ * 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');
+}
+/**
+ * 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({
+ *     styles: {
+ *       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 chunk disposals
+        disposeRef.current.forEach((dispose) => dispose?.());
+        disposeRef.current = [];
+        // Inject each chunk and collect dispose functions
+        for (const chunk of processedChunks) {
+            if (chunk.renderResult.rules.length > 0) {
+                const { dispose } = inject(chunk.renderResult.rules, {
+                    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,24 +1,38 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.0.0-canary-4777472
+ * @cube-dev/ui-kit v0.0.0-canary-b26ec55
  * Released under the MIT license.
  */
 
+// Register built-in plugins at module load time
+import { configure } from './config';
+import { okhslPlugin } from './plugins';
 export { tasty, Element } from './tasty';
+export { useStyles, useGlobalStyles, useRawCSS } from './hooks';
+// Configuration API
+export { configure, getConfig, isConfigLocked, hasStylesGenerated, resetConfig, isTestEnvironment, } from './config';
+// Plugins
+export { okhslPlugin, okhslFunc } from './plugins';
+configure({
+    plugins: [okhslPlugin()],
+});
+// Chunk utilities for advanced use cases
+export { CHUNK_NAMES, STYLE_TO_CHUNK, categorizeStyleKeys } from './chunks';
+// Advanced state mapping utilities
+export { getGlobalPredefinedStates, setGlobalPredefinedStates } from './states';
 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 { renderStyles, isSelector } from './pipeline';
 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 './utils/typography';
 export * from './injector';
 export * from './debug';