@cube-dev/ui-kit 0.98.9 → 0.99.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);
+}
+
+        

package/es/tasty/config.js

@@ -0,0 +1,280 @@
+/**
+ * @license MIT
+ * author: Cube Dev Team
+ * @cube-dev/ui-kit v0.99.0
+ * Released under the MIT license.
+ */
+
+/**
+ * Tasty Configuration Module
+ *
+ * Centralizes all tasty configuration, including:
+ * - Style injector settings (nonce, cleanup thresholds, etc.)
+ * - Global predefined states for advanced state mapping
+ * - stylesGenerated flag that locks configuration after first style generation
+ *
+ * Configuration must be done BEFORE any styles are generated.
+ * After the first `inject()` call, configuration is locked and attempts to
+ * reconfigure will emit a warning and be ignored.
+ */
+import { StyleInjector } from './injector/injector.js';
+import { setGlobalPredefinedStates } from './states/index.js';
+import { isDevEnv } from './utils/isDevEnv.js';
+import { CUSTOM_UNITS, getGlobalFuncs, getGlobalParser } from './utils/styles.js';
+// Warnings tracking to avoid duplicates
+const emittedWarnings = new Set();
+const devMode = isDevEnv();
+/**
+ * Emit a warning only once
+ */
+function warnOnce(key, message) {
+    if (devMode && !emittedWarnings.has(key)) {
+        emittedWarnings.add(key);
+        console.warn(message);
+    }
+}
+// ============================================================================
+// Configuration State
+// ============================================================================
+// Track whether styles have been generated (locks configuration)
+let stylesGenerated = false;
+// Current configuration (null until first configure() or auto-configured on first use)
+let currentConfig = null;
+// Global keyframes storage (null = no keyframes configured, empty object checked via hasGlobalKeyframes)
+let globalKeyframes = null;
+// Global injector instance key
+const GLOBAL_INJECTOR_KEY = '__TASTY_GLOBAL_INJECTOR__';
+/**
+ * Detect if we're running in a test environment
+ */
+export 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,
+        unusedStylesThreshold: 500,
+        bulkCleanupDelay: 5000,
+        idleCleanup: true,
+        forceTextInjection: isTest ?? false,
+        devMode: isDevEnv(),
+        bulkCleanupBatchRatio: 0.5,
+        unusedStylesMinAgeMs: 10000,
+    };
+}
+// ============================================================================
+// stylesGenerated Flag Management
+// ============================================================================
+/**
+ * Mark that styles have been generated (called by injector on first inject)
+ * This locks the configuration - no further changes allowed.
+ */
+export function markStylesGenerated() {
+    stylesGenerated = true;
+}
+/**
+ * Check if styles have been generated (configuration is locked)
+ */
+export function hasStylesGenerated() {
+    return stylesGenerated;
+}
+/**
+ * Reset styles generated flag (for testing only)
+ */
+export function resetStylesGenerated() {
+    stylesGenerated = false;
+    emittedWarnings.clear();
+}
+// ============================================================================
+// Global Keyframes Management
+// ============================================================================
+/**
+ * Check if any global keyframes are configured.
+ * Fast path: returns false if no keyframes were ever set.
+ */
+export function hasGlobalKeyframes() {
+    return globalKeyframes !== null && Object.keys(globalKeyframes).length > 0;
+}
+/**
+ * Get global keyframes configuration.
+ * Returns null if no keyframes configured (fast path for zero-overhead).
+ */
+export function getGlobalKeyframes() {
+    return globalKeyframes;
+}
+/**
+ * Set global keyframes (called from configure).
+ * Internal use only.
+ */
+function setGlobalKeyframes(keyframes) {
+    if (stylesGenerated) {
+        warnOnce('keyframes-after-styles', `[Tasty] Cannot update keyframes after styles have been generated.\n` +
+            `The new keyframes will be ignored.`);
+        return;
+    }
+    globalKeyframes = keyframes;
+}
+/**
+ * Check if configuration is locked (styles have been generated)
+ */
+export function isConfigLocked() {
+    return stylesGenerated;
+}
+// ============================================================================
+// Configuration API
+// ============================================================================
+/**
+ * Configure the Tasty style system.
+ *
+ * Must be called BEFORE any styles are generated (before first render that uses tasty).
+ * After styles are generated, configuration is locked and calls to configure() will
+ * emit a warning and be ignored.
+ *
+ * @example
+ * ```ts
+ * import { configure } from '@cube-dev/ui-kit';
+ *
+ * // Configure before app renders
+ * configure({
+ *   nonce: 'abc123',
+ *   states: {
+ *     '@mobile': '@media(w < 768px)',
+ *     '@dark': '@root(theme=dark)',
+ *   },
+ * });
+ * ```
+ */
+export function configure(config = {}) {
+    if (stylesGenerated) {
+        warnOnce('configure-after-styles', `[Tasty] Cannot call configure() after styles have been generated.\n` +
+            `Configuration must be done before the first render. The configuration will be ignored.`);
+        return;
+    }
+    // Collect merged values from plugins first, then override with direct config
+    let mergedStates = {};
+    let mergedUnits = {};
+    let mergedFuncs = {};
+    // Process plugins in order
+    if (config.plugins) {
+        for (const plugin of config.plugins) {
+            if (plugin.states) {
+                mergedStates = { ...mergedStates, ...plugin.states };
+            }
+            if (plugin.units) {
+                mergedUnits = { ...mergedUnits, ...plugin.units };
+            }
+            if (plugin.funcs) {
+                mergedFuncs = { ...mergedFuncs, ...plugin.funcs };
+            }
+        }
+    }
+    // Direct config overrides plugins
+    if (config.states) {
+        mergedStates = { ...mergedStates, ...config.states };
+    }
+    if (config.units) {
+        mergedUnits = { ...mergedUnits, ...config.units };
+    }
+    if (config.funcs) {
+        mergedFuncs = { ...mergedFuncs, ...config.funcs };
+    }
+    // Handle predefined states
+    if (Object.keys(mergedStates).length > 0) {
+        setGlobalPredefinedStates(mergedStates);
+    }
+    // Handle parser configuration (merge semantics - extend, not replace)
+    const parser = getGlobalParser();
+    if (config.parserCacheSize !== undefined) {
+        parser.updateOptions({ cacheSize: config.parserCacheSize });
+    }
+    if (Object.keys(mergedUnits).length > 0) {
+        // Merge with existing units
+        const currentUnits = parser.getUnits() ?? CUSTOM_UNITS;
+        parser.setUnits({ ...currentUnits, ...mergedUnits });
+    }
+    if (Object.keys(mergedFuncs).length > 0) {
+        // Merge with existing funcs
+        const currentFuncs = getGlobalFuncs();
+        const finalFuncs = { ...currentFuncs, ...mergedFuncs };
+        parser.setFuncs(finalFuncs);
+        // Also update the global registry so customFunc() continues to work
+        Object.assign(currentFuncs, mergedFuncs);
+    }
+    // Handle keyframes
+    if (config.keyframes) {
+        setGlobalKeyframes(config.keyframes);
+    }
+    // Create config without states, parser options, plugins, and keyframes (handled separately)
+    const { states: _states, parserCacheSize: _parserCacheSize, units: _units, funcs: _funcs, plugins: _plugins, keyframes: _keyframes, ...injectorConfig } = config;
+    const fullConfig = {
+        ...createDefaultConfig(),
+        ...currentConfig,
+        ...injectorConfig,
+    };
+    // Store the config
+    currentConfig = fullConfig;
+    // Create/replace the global injector
+    const storage = typeof window !== 'undefined' ? window : globalThis;
+    storage[GLOBAL_INJECTOR_KEY] = new StyleInjector(fullConfig);
+}
+/**
+ * Get the current configuration.
+ * If not configured, returns default configuration.
+ */
+export function getConfig() {
+    if (!currentConfig) {
+        currentConfig = createDefaultConfig(isTestEnvironment());
+    }
+    return currentConfig;
+}
+/**
+ * Get the global injector instance.
+ * Auto-configures with defaults if not already configured.
+ */
+export function getGlobalInjector() {
+    const storage = typeof window !== 'undefined' ? window : globalThis;
+    if (!storage[GLOBAL_INJECTOR_KEY]) {
+        configure();
+    }
+    return storage[GLOBAL_INJECTOR_KEY];
+}
+/**
+ * Reset configuration (for testing only).
+ * Clears the global injector and allows reconfiguration.
+ */
+export function resetConfig() {
+    stylesGenerated = false;
+    currentConfig = null;
+    globalKeyframes = null;
+    emittedWarnings.clear();
+    const storage = typeof window !== 'undefined' ? window : globalThis;
+    delete storage[GLOBAL_INJECTOR_KEY];
+}
+
+