@cube-dev/ui-kit 0.98.8 → 0.99.0

package/es/stories/playground/examples.js

@@ -0,0 +1,158 @@
+/**
+ * @license MIT
+ * author: Cube Dev Team
+ * @cube-dev/ui-kit v0.99.0
+ * Released under the MIT license.
+ */
+
+import { DEFAULT_OUTLINE_STYLES, DEFAULT_PRIMARY_STYLES, } from '../../data/item-themes.js';
+// Common button layout styles
+const BUTTON_BASE_STYLES = {
+    display: 'inline-flex',
+    placeItems: 'center',
+    gap: '1x',
+    padding: '(1.25x - 1bw) (2x - 1bw)',
+    radius: '1r',
+    preset: 't3',
+    cursor: {
+        '': 'pointer',
+        disabled: 'not-allowed',
+    },
+    transition: 'theme',
+};
+export const PLAYGROUND_EXAMPLES = [
+    {
+        name: 'Raw (No preview)',
+        component: 'raw',
+        styles: {
+            display: 'flex',
+            flow: 'column',
+            gap: '2x',
+            padding: '3x',
+            fill: '#white',
+            radius: '2r',
+            border: true,
+        },
+    },
+    {
+        name: 'Card - Basic',
+        component: 'card',
+        styles: {
+            display: 'flex',
+            flow: 'column',
+            gap: '2x',
+            padding: '3x',
+            fill: '#white',
+            radius: '2r',
+            border: true,
+            shadow: '0 2px 8px #dark.10',
+        },
+    },
+    {
+        name: 'Card - Purple',
+        component: 'card',
+        styles: {
+            display: 'flex',
+            flow: 'column',
+            gap: '2x',
+            padding: '4x',
+            fill: '#purple',
+            color: '#white',
+            radius: '2r',
+        },
+    },
+    {
+        name: 'Card - Responsive',
+        component: 'card',
+        styles: {
+            display: 'flex',
+            flow: 'column',
+            gap: '2x',
+            padding: {
+                '': '4x',
+                '@(w < 768px)': '2x',
+            },
+            fill: '#white',
+            radius: '2r',
+            border: true,
+            width: {
+                '': '400px',
+                '@(w < 768px)': '100%',
+            },
+        },
+    },
+    {
+        name: 'Button - Primary',
+        component: 'button',
+        styles: {
+            ...BUTTON_BASE_STYLES,
+            ...DEFAULT_PRIMARY_STYLES,
+        },
+    },
+    {
+        name: 'Button - Outline',
+        component: 'button',
+        styles: {
+            ...BUTTON_BASE_STYLES,
+            ...DEFAULT_OUTLINE_STYLES,
+        },
+    },
+    {
+        name: 'Scroll Progress (@supports)',
+        component: 'scroll-progress',
+        styles: {
+            // Container styles
+            display: 'flex',
+            flow: 'column',
+            width: '300px',
+            height: '200px',
+            radius: '2r',
+            border: true,
+            overflow: 'auto',
+            fill: '#white',
+            // Predefined state for @supports(animation-timeline: scroll())
+            '@supports-timeline': '@supports(animation-timeline: scroll())',
+            // Define keyframes for the progress animation
+            '@keyframes': {
+                'grow-progress': {
+                    from: 'scale: 0 1',
+                    to: 'scale: 1 1',
+                },
+            },
+            // Progress bar element
+            ProgressBar: {
+                position: 'sticky',
+                top: 0,
+                left: 0,
+                zIndex: 1,
+                height: 'min .5x',
+                margin: '-.5x bottom',
+                fill: '#purple',
+                radius: 'round',
+                transformOrigin: 'left center',
+                // Fallback for browsers without animation-timeline
+                scale: {
+                    '': '1 1',
+                    // When animation-timeline is supported, use scale: 0 1 as starting point
+                    '@supports-timeline': '0 1',
+                },
+                // Animation properties only when supported
+                animation: {
+                    '': 'none',
+                    '@supports-timeline': 'grow-progress linear both',
+                },
+                animationTimeline: {
+                    '': 'auto',
+                    '@supports-timeline': 'scroll(nearest block)',
+                },
+            },
+            // Scrollable content area
+            Content: {
+                display: 'block',
+                padding: '2x',
+            },
+        },
+    },
+];
+
+        

package/es/tasty/chunks/cacheKey.js

@@ -0,0 +1,98 @@
+/**
+ * @license MIT
+ * author: Cube Dev Team
+ * @cube-dev/ui-kit v0.99.0
+ * Released under the MIT license.
+ */
+
+/**
+ * Chunk-specific cache key generation.
+ *
+ * Generates cache keys that only include styles relevant to a specific chunk,
+ * enabling more granular caching and reuse.
+ *
+ * Enhanced to support predefined states:
+ * - Global predefined states don't affect cache keys (constant across app)
+ * - Local predefined states only affect cache keys if referenced in the chunk
+ */
+import { extractLocalPredefinedStates, extractPredefinedStateRefs, } from '../states/index.js';
+/**
+ * Recursively serialize a value with sorted keys for stable output.
+ * This ensures that {a: 1, b: 2} and {b: 2, a: 1} produce the same string.
+ */
+function stableStringify(value) {
+    if (value === null) {
+        return 'null';
+    }
+    if (value === undefined) {
+        return 'undefined';
+    }
+    if (typeof value !== 'object') {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return '[' + value.map(stableStringify).join(',') + ']';
+    }
+    // Object: sort keys for stable order
+    const obj = value;
+    const sortedKeys = Object.keys(obj).sort();
+    const parts = [];
+    for (const key of sortedKeys) {
+        if (obj[key] !== undefined) {
+            parts.push(`${JSON.stringify(key)}:${stableStringify(obj[key])}`);
+        }
+    }
+    return '{' + parts.join(',') + '}';
+}
+/**
+ * Generate a cache key for a specific chunk.
+ *
+ * Only includes the styles that belong to this chunk, allowing
+ * chunks to be cached independently.
+ *
+ * Also includes relevant local predefined states that are referenced
+ * by this chunk's styles.
+ *
+ * @param styles - The full styles object
+ * @param chunkName - Name of the chunk
+ * @param styleKeys - Keys of styles belonging to this chunk
+ * @returns A stable cache key string
+ */
+export function generateChunkCacheKey(styles, chunkName, styleKeys) {
+    // Start with chunk name for namespace separation
+    const parts = [chunkName];
+    // Sort keys for stable ordering
+    const sortedKeys = styleKeys.slice().sort();
+    // Build the chunk-specific styles string for predefined state detection
+    let chunkStylesStr = '';
+    for (const key of sortedKeys) {
+        const value = styles[key];
+        if (value !== undefined) {
+            // Use stable stringify for consistent serialization regardless of key order
+            const serialized = stableStringify(value);
+            parts.push(`${key}:${serialized}`);
+            chunkStylesStr += serialized;
+        }
+    }
+    // Extract local predefined states from the full styles object
+    const localStates = extractLocalPredefinedStates(styles);
+    // Only include local predefined states that are actually referenced in this chunk
+    if (Object.keys(localStates).length > 0) {
+        const referencedStates = extractPredefinedStateRefs(chunkStylesStr);
+        const relevantLocalStates = [];
+        for (const stateName of referencedStates) {
+            if (localStates[stateName]) {
+                relevantLocalStates.push(`${stateName}=${localStates[stateName]}`);
+            }
+        }
+        // Add relevant local states to the cache key (sorted for stability)
+        if (relevantLocalStates.length > 0) {
+            relevantLocalStates.sort();
+            parts.unshift(`[states:${relevantLocalStates.join('|')}]`);
+        }
+    }
+    // Use null character as separator (safe, not in JSON output)
+    return parts.join('\0');
+}
+
+        

package/es/tasty/chunks/definitions.js

@@ -0,0 +1,281 @@
+/**
+ * @license MIT
+ * author: Cube Dev Team
+ * @cube-dev/ui-kit v0.99.0
+ * Released under the MIT license.
+ */
+
+/**
+ * Style chunk definitions for CSS chunking optimization.
+ *
+ * Styles are grouped into chunks based on:
+ * 1. Handler dependencies - styles that share a handler MUST be in the same chunk
+ * 2. Logical grouping - related styles grouped for better cache reuse
+ *
+ * See STYLE_CHUNKING_SPEC.md for detailed rationale.
+ */
+import { isSelector } from '../pipeline/index.js';
+// ============================================================================
+// Chunk Style Lists
+// ============================================================================
+/**
+ * Appearance chunk - visual styling with independent handlers
+ */
+export const APPEARANCE_CHUNK_STYLES = [
+    'fill', // fillStyle (independent)
+    'color', // colorStyle (independent)
+    'opacity', // independent
+    'border', // borderStyle (independent)
+    'radius', // radiusStyle (independent)
+    'outline', // outlineStyle (independent)
+    'outlineOffset', // independent (used with outline)
+    'shadow', // shadowStyle (independent)
+    'fade', // fadeStyle (independent)
+];
+/**
+ * Font chunk - typography styles
+ * ⚠️ presetStyle handler requires: preset, fontSize, lineHeight, letterSpacing,
+ *    textTransform, fontWeight, fontStyle, font - all MUST stay together
+ */
+export const FONT_CHUNK_STYLES = [
+    // All from presetStyle handler - MUST stay together
+    'preset',
+    'font',
+    'fontWeight',
+    'fontStyle',
+    'fontSize',
+    'lineHeight',
+    'letterSpacing',
+    'textTransform',
+    // Independent text styles grouped for cohesion
+    'fontFamily', // independent alias (logical grouping with font styles)
+    'textAlign',
+    'whiteSpace',
+    'textDecoration',
+    'textOverflow',
+    'wordBreak',
+    'wordWrap',
+    'boldFontWeight',
+];
+/**
+ * Dimension chunk - sizing and spacing
+ * ⚠️ paddingStyle handler requires all padding variants together
+ * ⚠️ marginStyle handler requires all margin variants together
+ */
+export const DIMENSION_CHUNK_STYLES = [
+    // All from paddingStyle handler - MUST stay together
+    'padding',
+    'paddingTop',
+    'paddingRight',
+    'paddingBottom',
+    'paddingLeft',
+    'paddingBlock',
+    'paddingInline',
+    // All from marginStyle handler - MUST stay together
+    'margin',
+    'marginTop',
+    'marginRight',
+    'marginBottom',
+    'marginLeft',
+    'marginBlock',
+    'marginInline',
+    // Independent sizing styles
+    'width', // widthStyle (independent)
+    'height', // heightStyle (independent)
+    'minWidth',
+    'maxWidth',
+    'minHeight',
+    'maxHeight',
+    'flexBasis',
+    'flexGrow',
+    'flexShrink',
+    'flex',
+];
+/**
+ * Container chunk - display, flow, and grid layout
+ * ⚠️ FORCED TOGETHER by transitive handler dependencies:
+ *    displayStyle(display,hide) + flowStyle(display,flow) +
+ *    gapStyle(display,flow,gap) + groupRadiusAttr(groupRadius,flow)
+ */
+export const CONTAINER_CHUNK_STYLES = [
+    // Forced together by handler dependencies
+    'display', // displayStyle: display ↔ hide
+    'hide', // displayStyle: display ↔ hide
+    'flow', // flowStyle: display ↔ flow
+    'gap', // gapStyle: display ↔ flow ↔ gap
+    'groupRadius', // groupRadiusAttr: groupRadius ↔ flow
+    // Related container styles (independent but logically grouped)
+    'placeItems',
+    'placeContent',
+    'alignItems',
+    'alignContent',
+    'justifyItems',
+    'justifyContent',
+    'align', // alignStyle (independent)
+    'justify', // justifyStyle (independent)
+    'place', // placeStyle (independent)
+    'columnGap',
+    'rowGap',
+    'gridColumns',
+    'gridRows',
+    'gridTemplate',
+    'gridAreas',
+    'gridAutoFlow',
+    'gridAutoColumns',
+    'gridAutoRows',
+];
+/**
+ * Scrollbar chunk - scrollbar and overflow
+ * ⚠️ scrollbarStyle handler requires scrollbar ↔ overflow together
+ */
+export const SCROLLBAR_CHUNK_STYLES = [
+    'scrollbar', // scrollbarStyle: scrollbar ↔ overflow
+    'overflow', // scrollbarStyle: scrollbar ↔ overflow
+    'styledScrollbar', // styledScrollbarStyle (independent, deprecated)
+];
+/**
+ * Position chunk - element positioning (all independent handlers)
+ */
+export const POSITION_CHUNK_STYLES = [
+    'position',
+    'inset', // insetStyle (independent)
+    'top',
+    'right',
+    'bottom',
+    'left',
+    'zIndex',
+    'gridArea',
+    'gridColumn',
+    'gridRow',
+    'order',
+    'placeSelf',
+    'alignSelf',
+    'justifySelf',
+    'transform',
+    'transition',
+    'animation',
+];
+// ============================================================================
+// Chunk Names
+// ============================================================================
+export const CHUNK_NAMES = {
+    /** Special chunk for styles that cannot be split (e.g., @starting-style) */
+    COMBINED: 'combined',
+    SUBCOMPONENTS: 'subcomponents',
+    APPEARANCE: 'appearance',
+    FONT: 'font',
+    DIMENSION: 'dimension',
+    CONTAINER: 'container',
+    SCROLLBAR: 'scrollbar',
+    POSITION: 'position',
+    MISC: 'misc',
+};
+// ============================================================================
+// Style-to-Chunk Lookup Map (O(1) categorization)
+// ============================================================================
+/**
+ * Pre-computed map for O(1) style-to-chunk lookup.
+ * Built once at module load time.
+ */
+export const STYLE_TO_CHUNK = new Map();
+// Populate the lookup map
+function populateStyleToChunkMap() {
+    for (const style of APPEARANCE_CHUNK_STYLES) {
+        STYLE_TO_CHUNK.set(style, CHUNK_NAMES.APPEARANCE);
+    }
+    for (const style of FONT_CHUNK_STYLES) {
+        STYLE_TO_CHUNK.set(style, CHUNK_NAMES.FONT);
+    }
+    for (const style of DIMENSION_CHUNK_STYLES) {
+        STYLE_TO_CHUNK.set(style, CHUNK_NAMES.DIMENSION);
+    }
+    for (const style of CONTAINER_CHUNK_STYLES) {
+        STYLE_TO_CHUNK.set(style, CHUNK_NAMES.CONTAINER);
+    }
+    for (const style of SCROLLBAR_CHUNK_STYLES) {
+        STYLE_TO_CHUNK.set(style, CHUNK_NAMES.SCROLLBAR);
+    }
+    for (const style of POSITION_CHUNK_STYLES) {
+        STYLE_TO_CHUNK.set(style, CHUNK_NAMES.POSITION);
+    }
+}
+// Initialize at module load
+populateStyleToChunkMap();
+// ============================================================================
+// Chunk Priority Order
+// ============================================================================
+/**
+ * Chunk processing order. This ensures deterministic className allocation
+ * regardless of style key order in the input.
+ */
+const CHUNK_ORDER = [
+    CHUNK_NAMES.APPEARANCE,
+    CHUNK_NAMES.FONT,
+    CHUNK_NAMES.DIMENSION,
+    CHUNK_NAMES.CONTAINER,
+    CHUNK_NAMES.SCROLLBAR,
+    CHUNK_NAMES.POSITION,
+    CHUNK_NAMES.MISC,
+    CHUNK_NAMES.SUBCOMPONENTS,
+];
+/**
+ * Map from chunk name to its priority index for sorting.
+ */
+const CHUNK_PRIORITY = new Map(CHUNK_ORDER.map((name, index) => [name, index]));
+// ============================================================================
+// Style Categorization
+// ============================================================================
+/**
+ * Categorize style keys into chunks.
+ *
+ * Returns chunks in a deterministic order (by CHUNK_ORDER) regardless
+ * of the order of keys in the input styles object.
+ *
+ * @param styles - The styles object to categorize
+ * @returns Map of chunk name to array of style keys in that chunk (in priority order)
+ */
+export function categorizeStyleKeys(styles) {
+    // First pass: collect keys into chunks (unordered)
+    const chunkData = {};
+    const keys = Object.keys(styles);
+    for (const key of keys) {
+        // Skip the $ helper key (used for selector combinators)
+        // Skip @keyframes (processed separately in useStyles)
+        if (key === '$' || key === '@keyframes') {
+            continue;
+        }
+        if (isSelector(key)) {
+            // All selectors go into the subcomponents chunk
+            if (!chunkData[CHUNK_NAMES.SUBCOMPONENTS]) {
+                chunkData[CHUNK_NAMES.SUBCOMPONENTS] = [];
+            }
+            chunkData[CHUNK_NAMES.SUBCOMPONENTS].push(key);
+        }
+        else {
+            // Look up the chunk for this style, default to misc
+            const chunkName = STYLE_TO_CHUNK.get(key) ?? CHUNK_NAMES.MISC;
+            if (!chunkData[chunkName]) {
+                chunkData[chunkName] = [];
+            }
+            chunkData[chunkName].push(key);
+        }
+    }
+    // Second pass: build ordered Map based on CHUNK_ORDER
+    const orderedChunks = new Map();
+    // Add chunks in priority order
+    for (const chunkName of CHUNK_ORDER) {
+        if (chunkData[chunkName] && chunkData[chunkName].length > 0) {
+            // Sort keys within chunk for consistent cache key generation
+            orderedChunks.set(chunkName, chunkData[chunkName].sort());
+        }
+    }
+    // Handle any unknown chunks (shouldn't happen, but be defensive)
+    for (const chunkName of Object.keys(chunkData)) {
+        if (!orderedChunks.has(chunkName)) {
+            orderedChunks.set(chunkName, chunkData[chunkName].sort());
+        }
+    }
+    return orderedChunks;
+}
+
+        

package/es/tasty/chunks/index.js

@@ -0,0 +1,12 @@
+/**
+ * @license MIT
+ * author: Cube Dev Team
+ * @cube-dev/ui-kit v0.99.0
+ * Released under the MIT license.
+ */
+
+export { APPEARANCE_CHUNK_STYLES, FONT_CHUNK_STYLES, DIMENSION_CHUNK_STYLES, CONTAINER_CHUNK_STYLES, SCROLLBAR_CHUNK_STYLES, POSITION_CHUNK_STYLES, CHUNK_NAMES, STYLE_TO_CHUNK, categorizeStyleKeys, } from './definitions.js';
+export { generateChunkCacheKey } from './cacheKey.js';
+export { renderStylesForChunk } from './renderChunk.js';
+
+        

package/es/tasty/chunks/renderChunk.js

@@ -0,0 +1,97 @@
+/**
+ * @license MIT
+ * author: Cube Dev Team
+ * @cube-dev/ui-kit v0.99.0
+ * Released under the MIT license.
+ */
+
+/**
+ * Chunk-specific style rendering.
+ *
+ * Renders styles for a specific chunk by filtering the styles object
+ * to only include relevant keys before passing to renderStyles.
+ */
+import { renderStyles } from '../pipeline/index.js';
+import { extractLocalPredefinedStates } from '../states/index.js';
+import { CHUNK_NAMES } from './definitions.js';
+/**
+ * Render styles for a specific chunk.
+ *
+ * Creates a filtered styles object containing only the keys for this chunk,
+ * then delegates to the existing renderStyles function.
+ *
+ * IMPORTANT: Local predefined states (e.g., '@mobile': '@media(w < 600px)')
+ * are always included in the filtered styles, regardless of which chunk is
+ * being rendered. This ensures that state references like '@mobile' in any
+ * chunk can be properly resolved by the pipeline.
+ *
+ * @param styles - The full styles object
+ * @param chunkName - Name of the chunk being rendered
+ * @param styleKeys - Keys of styles belonging to this chunk
+ * @returns RenderResult with rules for this chunk
+ */
+export function renderStylesForChunk(styles, chunkName, styleKeys) {
+    // Empty chunk - return empty result
+    if (styleKeys.length === 0) {
+        return { rules: [], className: '' };
+    }
+    // For subcomponents, we need to preserve the nested structure
+    if (chunkName === CHUNK_NAMES.SUBCOMPONENTS) {
+        return renderSubcomponentsChunk(styles, styleKeys);
+    }
+    // Extract local predefined states from the full styles object
+    // These must be included for state resolution to work across chunks
+    const localPredefinedStates = extractLocalPredefinedStates(styles);
+    // For regular chunks, create a filtered styles object
+    // This is memory-efficient: we only create a shallow copy with filtered keys
+    const filteredStyles = {};
+    // First, add local predefined states so they're available for resolution
+    for (const [key, value] of Object.entries(localPredefinedStates)) {
+        filteredStyles[key] = value;
+    }
+    // Then add the chunk's style keys
+    for (const key of styleKeys) {
+        const value = styles[key];
+        if (value !== undefined) {
+            filteredStyles[key] = value;
+        }
+    }
+    // Delegate to existing renderStyles
+    return renderStyles(filteredStyles);
+}
+/**
+ * Render the subcomponents chunk.
+ *
+ * Subcomponents (selectors like Label, &::before, etc.) contain nested
+ * style objects that need to be preserved in their entirety.
+ *
+ * @param styles - The full styles object
+ * @param selectorKeys - Keys of selectors in this chunk
+ * @returns RenderResult with rules for all subcomponents
+ */
+function renderSubcomponentsChunk(styles, selectorKeys) {
+    // Extract local predefined states from the full styles object
+    // These must be included for state resolution to work in nested styles
+    const localPredefinedStates = extractLocalPredefinedStates(styles);
+    // Create a styles object containing only the selector keys
+    const filteredStyles = {};
+    // First, add local predefined states so they're available for resolution
+    for (const [key, value] of Object.entries(localPredefinedStates)) {
+        filteredStyles[key] = value;
+    }
+    // Then add the selector keys
+    for (const key of selectorKeys) {
+        const value = styles[key];
+        if (value !== undefined) {
+            filteredStyles[key] = value;
+        }
+    }
+    // Also copy the $ helper if present (used for selector combinators)
+    if (styles.$ !== undefined) {
+        filteredStyles.$ = styles.$;
+    }
+    // Delegate to existing renderStyles
+    return renderStyles(filteredStyles);
+}
+
+