@cube-dev/ui-kit 0.113.1 → 0.115.0

package/types/tasty/chunks/renderChunk.d.ts

@@ -1,25 +0,0 @@
-/**
- * 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 { RenderResult } from '../pipeline';
-import { Styles } from '../styles/types';
-/**
- * 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 declare function renderStylesForChunk(styles: Styles, chunkName: string, styleKeys: string[]): RenderResult;

package/types/tasty/config.d.ts

@@ -1,320 +0,0 @@
-/**
- * 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 type { KeyframesSteps, PropertyDefinition } from './injector/types';
-import type { StyleDetails, UnitHandler } from './parser/types';
-import type { TastyPlugin } from './plugins/types';
-import type { RecipeStyles } from './styles/types';
-import type { StyleHandlerDefinition } from './utils/styles';
-/**
- * Configuration options for the Tasty style system
- */
-export interface TastyConfig {
-    /** CSP nonce for style elements */
-    nonce?: string;
-    /** Maximum rules per stylesheet (default: 8192) */
-    maxRulesPerSheet?: number;
-    /** Threshold for bulk cleanup of unused styles (default: 500) */
-    unusedStylesThreshold?: number;
-    /** Delay before bulk cleanup in ms, ignored if idleCleanup is true (default: 5000) */
-    bulkCleanupDelay?: number;
-    /** Use requestIdleCallback for cleanup when available (default: true) */
-    idleCleanup?: boolean;
-    /** Force text injection mode, auto-detected in test environments (default: auto) */
-    forceTextInjection?: boolean;
-    /** Enable development mode features: performance metrics and debug info (default: auto) */
-    devMode?: boolean;
-    /**
-     * Ratio of unused styles to delete per bulk cleanup run (0..1).
-     * Defaults to 0.5 (oldest half) to reduce risk of removing styles
-     * that may be restored shortly after being marked unused.
-     */
-    bulkCleanupBatchRatio?: number;
-    /**
-     * Minimum age (in ms) a style must remain unused before eligible for deletion.
-     * Helps avoid races during rapid mount/unmount cycles. Default: 10000ms.
-     */
-    unusedStylesMinAgeMs?: number;
-    /**
-     * Global predefined states for advanced state mapping.
-     * These are state aliases that can be used in any component.
-     * Example: { '@mobile': '@media(w < 920px)', '@dark': '@root(theme=dark)' }
-     */
-    states?: Record<string, string>;
-    /**
-     * Parser LRU cache size (default: 1000).
-     * Larger values improve performance for apps with many unique style values.
-     */
-    parserCacheSize?: number;
-    /**
-     * Custom units for the style parser (merged with built-in units).
-     * Units transform numeric values like `2x` → `calc(2 * var(--gap))`.
-     * @example { em: 'em', vw: 'vw', custom: (n) => `${n * 10}px` }
-     */
-    units?: Record<string, string | UnitHandler>;
-    /**
-     * Custom functions for the style parser (merged with existing).
-     * Functions process parsed style groups and return CSS values.
-     * @example { myFunc: (groups) => groups.map(g => g.output).join(' ') }
-     */
-    funcs?: Record<string, (groups: StyleDetails[]) => string>;
-    /**
-     * Plugins that extend tasty with custom functions, units, or states.
-     * Plugins are processed in order, with later plugins overriding earlier ones.
-     * @example
-     * ```ts
-     * import { okhslPlugin } from '@cube-dev/ui-kit/tasty/plugins';
-     *
-     * configure({
-     *   plugins: [okhslPlugin()],
-     * });
-     * ```
-     */
-    plugins?: TastyPlugin[];
-    /**
-     * Global keyframes definitions that can be referenced by animation names in styles.
-     * Keys are animation names, values are keyframes step definitions.
-     * Keyframes are only injected when actually used in styles.
-     * @example
-     * ```ts
-     * configure({
-     *   keyframes: {
-     *     fadeIn: { from: { opacity: 0 }, to: { opacity: 1 } },
-     *     pulse: { '0%, 100%': { transform: 'scale(1)' }, '50%': { transform: 'scale(1.05)' } },
-     *   },
-     * });
-     * ```
-     */
-    keyframes?: Record<string, KeyframesSteps>;
-    /**
-     * Global CSS @property definitions for custom properties.
-     * Keys use tasty token syntax ($name for properties, #name for colors).
-     * Properties are only injected when the component using them is rendered.
-     *
-     * For color tokens (#name), `syntax: '<color>'` is auto-set and
-     * `initialValue` defaults to `'transparent'` if not specified.
-     *
-     * @example
-     * ```ts
-     * configure({
-     *   properties: {
-     *     '$rotation': { syntax: '<angle>', initialValue: '0deg' },
-     *     '$scale': { syntax: '<number>', inherits: false, initialValue: 1 },
-     *     '#accent': { initialValue: 'purple' }, // syntax: '<color>' auto-set
-     *   },
-     * });
-     *
-     * // Now use in styles - properties are registered when component renders:
-     * const Spinner = tasty({
-     *   styles: {
-     *     transform: 'rotate($rotation)',
-     *     transition: '$$rotation 0.3s', // outputs: --rotation 0.3s
-     *   },
-     * });
-     * ```
-     */
-    properties?: Record<string, PropertyDefinition>;
-    /**
-     * Custom style handlers that transform style properties into CSS declarations.
-     * Handlers replace built-in handlers for the same style name.
-     * @example
-     * ```ts
-     * import { styleHandlers } from '@cube-dev/ui-kit';
-     *
-     * configure({
-     *   handlers: {
-     *     // Override fill with custom behavior
-     *     fill: ({ fill }) => {
-     *       if (fill?.startsWith('gradient:')) {
-     *         return { background: fill.slice(9) };
-     *       }
-     *       return styleHandlers.fill({ fill });
-     *     },
-     *     // Add new custom style
-     *     elevation: ({ elevation }) => {
-     *       const level = parseInt(elevation) || 1;
-     *       return {
-     *         'box-shadow': `0 ${level * 2}px ${level * 4}px rgba(0,0,0,0.1)`,
-     *         'z-index': String(level * 100),
-     *       };
-     *     },
-     *   },
-     * });
-     * ```
-     */
-    handlers?: Record<string, StyleHandlerDefinition>;
-    /**
-     * Predefined tokens that are replaced during style parsing.
-     * Token values are processed through the parser (like component tokens).
-     * Use `$name` for custom properties and `#name` for color tokens.
-     *
-     * For color tokens (#name), boolean `true` is converted to `transparent`.
-     *
-     * @example
-     * ```ts
-     * configure({
-     *   tokens: {
-     *     $spacing: '2x',
-     *     '$card-padding': '4x',
-     *     '#accent': '#purple',
-     *     '#surface': '#white',
-     *     '#overlay': true, // → transparent
-     *   },
-     * });
-     *
-     * // Now use in styles - tokens are replaced at parse time:
-     * const Card = tasty({
-     *   styles: {
-     *     padding: '$card-padding',  // → calc(4 * var(--gap))
-     *     fill: '#surface',          // → var(--white-color)
-     *   },
-     * });
-     * ```
-     */
-    tokens?: {
-        [key: `$${string}`]: string | number | boolean;
-    } & {
-        [key: `#${string}`]: string | number | boolean;
-    };
-    /**
-     * Predefined style recipes -- named style bundles that can be applied via `recipe` style property.
-     * Recipe values are flat tasty styles (no sub-element keys). They may contain base styles,
-     * tokens (`$name`/`#name` definitions), local states, `@keyframes`, and `@properties`.
-     *
-     * Components reference recipes via: `recipe: 'name1, name2'` in their styles.
-     * Recipes are resolved before the style pipeline by merging in order:
-     * `recipe_1 → recipe_2 → ... → component styles`.
-     *
-     * Recipes cannot reference other recipes.
-     *
-     * @example
-     * ```ts
-     * configure({
-     *   recipes: {
-     *     card: { padding: '4x', fill: '#surface', radius: '1r', border: true },
-     *     elevated: { shadow: '2x 2x 4x #shadow' },
-     *   },
-     * });
-     *
-     * // Usage in styles:
-     * const Card = tasty({
-     *   styles: {
-     *     recipe: 'card, elevated',
-     *     color: '#text', // Overrides recipe values
-     *   },
-     * });
-     * ```
-     */
-    recipes?: Record<string, RecipeStyles>;
-}
-/**
- * Internal properties required by tasty core features.
- * These are always injected when styles are first generated.
- * Keys use tasty token syntax (#name for colors, $name for other properties).
- */
-export declare const INTERNAL_PROPERTIES: Record<string, PropertyDefinition>;
-declare const GLOBAL_INJECTOR_KEY = "__TASTY_GLOBAL_INJECTOR__";
-declare global {
-    interface Window {
-        [GLOBAL_INJECTOR_KEY]?: import('./injector/injector').StyleInjector;
-    }
-}
-/**
- * Detect if we're running in a test environment
- */
-export declare function isTestEnvironment(): boolean;
-/**
- * Mark that styles have been generated (called by injector on first inject)
- * This locks the configuration - no further changes allowed.
- * Also injects internal and global properties.
- */
-export declare function markStylesGenerated(): void;
-/**
- * Check if styles have been generated (configuration is locked)
- */
-export declare function hasStylesGenerated(): boolean;
-/**
- * Reset styles generated flag (for testing only)
- */
-export declare function resetStylesGenerated(): void;
-/**
- * Check if any global keyframes are configured.
- * Fast path: returns false if no keyframes were ever set.
- */
-export declare function hasGlobalKeyframes(): boolean;
-/**
- * Get global keyframes configuration.
- * Returns null if no keyframes configured (fast path for zero-overhead).
- */
-export declare function getGlobalKeyframes(): Record<string, KeyframesSteps> | null;
-/**
- * Check if any global properties are configured.
- * Fast path: returns false if no properties were ever set.
- */
-export declare function hasGlobalProperties(): boolean;
-/**
- * Get global properties configuration.
- * Returns null if no properties configured (fast path for zero-overhead).
- */
-export declare function getGlobalProperties(): Record<string, PropertyDefinition> | null;
-/**
- * Check if any global recipes are configured.
- * Fast path: returns false if no recipes were ever set.
- */
-export declare function hasGlobalRecipes(): boolean;
-/**
- * Get global recipes configuration.
- * Returns null if no recipes configured (fast path for zero-overhead).
- */
-export declare function getGlobalRecipes(): Record<string, RecipeStyles> | null;
-/**
- * Check if configuration is locked (styles have been generated)
- */
-export declare function isConfigLocked(): boolean;
-/**
- * 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 declare function configure(config?: Partial<TastyConfig>): void;
-/**
- * Get the current configuration.
- * If not configured, returns default configuration.
- */
-export declare function getConfig(): TastyConfig;
-/**
- * Get the global injector instance.
- * Auto-configures with defaults if not already configured.
- */
-export declare function getGlobalInjector(): import('./injector/injector').StyleInjector;
-/**
- * Reset configuration (for testing only).
- * Clears the global injector and allows reconfiguration.
- */
-export declare function resetConfig(): void;
-export type { TastyConfig as StyleInjectorConfig };

package/types/tasty/debug.d.ts

@@ -1,196 +0,0 @@
-/**
- * Debug utilities for inspecting tasty-generated CSS at runtime
- */
-type CSSTarget = 'all' | 'global' | 'active' | 'unused' | 'page' | string | string[] | Element;
-interface CssOptions {
-    root?: Document | ShadowRoot;
-    prettify?: boolean;
-    log?: boolean;
-}
-interface ChunkInfo {
-    className: string;
-    chunkName: string | null;
-}
-interface InspectResult {
-    element?: Element | null;
-    classes: string[];
-    chunks: ChunkInfo[];
-    css: string;
-    size: number;
-    rules: number;
-}
-interface CacheMetrics {
-    hits: number;
-    misses: number;
-    bulkCleanups: number;
-    totalInsertions: number;
-    totalUnused: number;
-    stylesCleanedUp: number;
-    cleanupHistory: Array<{
-        timestamp: number;
-        classesDeleted: number;
-        cssSize: number;
-        rulesDeleted: number;
-    }>;
-    startTime: number;
-    unusedHits?: number;
-}
-interface CacheStatus {
-    classes: {
-        active: string[];
-        unused: string[];
-        all: string[];
-    };
-    metrics: CacheMetrics | null;
-}
-interface Definitions {
-    properties: string[];
-    keyframes: Array<{
-        name: string;
-        refCount: number;
-    }>;
-}
-interface SummaryOptions {
-    root?: Document | ShadowRoot;
-    log?: boolean;
-    includePageCSS?: false | true | 'all';
-}
-interface Summary {
-    activeClasses: string[];
-    unusedClasses: string[];
-    totalStyledClasses: string[];
-    activeCSSSize: number;
-    unusedCSSSize: number;
-    globalCSSSize: number;
-    rawCSSSize: number;
-    keyframesCSSSize: number;
-    propertyCSSSize: number;
-    totalCSSSize: number;
-    activeCSS: string;
-    unusedCSS: string;
-    globalCSS: string;
-    rawCSS: string;
-    keyframesCSS: string;
-    propertyCSS: string;
-    allCSS: string;
-    globalRuleCount: number;
-    rawRuleCount: number;
-    keyframesRuleCount: number;
-    propertyRuleCount: number;
-    page?: {
-        css?: string;
-        cssSize: number;
-        ruleCount: number;
-        stylesheetCount: number;
-        skippedStylesheets: number;
-    };
-    metrics: CacheMetrics | null;
-    definedProperties: string[];
-    definedKeyframes: Array<{
-        name: string;
-        refCount: number;
-    }>;
-    propertyCount: number;
-    keyframeCount: number;
-    cleanupSummary: {
-        enabled: boolean;
-        totalCleanups: number;
-        totalClassesDeleted: number;
-        totalCssDeleted: number;
-        totalRulesDeleted: number;
-        averageClassesPerCleanup: number;
-        averageCssPerCleanup: number;
-        averageRulesPerCleanup: number;
-        lastCleanup?: {
-            timestamp: number;
-            date: string;
-            classesDeleted: number;
-            cssSize: number;
-            rulesDeleted: number;
-        };
-    };
-    chunkBreakdown: {
-        byChunk: Record<string, {
-            classes: string[];
-            cssSize: number;
-            ruleCount: number;
-        }>;
-        totalChunkTypes: number;
-    };
-}
-/**
- * Concise tastyDebug API for inspecting styles at runtime
- */
-export declare const tastyDebug: {
-    css(target: CSSTarget, opts?: CssOptions): string;
-    inspect(target: string | Element, opts?: {
-        root?: Document | ShadowRoot;
-    }): InspectResult;
-    cache(opts?: {
-        root?: Document | ShadowRoot;
-        includeHistory?: boolean;
-    }): CacheStatus;
-    cleanup(opts?: {
-        root?: Document | ShadowRoot;
-    }): void;
-    metrics(opts?: {
-        root?: Document | ShadowRoot;
-    }): CacheMetrics | null;
-    resetMetrics(opts?: {
-        root?: Document | ShadowRoot;
-    }): void;
-    /**
-     * 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?: {
-        root?: Document | ShadowRoot;
-        log?: boolean;
-    }): {
-        byChunk: Record<string, {
-            classes: string[];
-            cssSize: number;
-            ruleCount: number;
-        }>;
-        totalChunkTypes: number;
-        totalClasses: number;
-    };
-    getGlobalTypeCSS(type: "global" | "raw" | "keyframes" | "property", opts?: {
-        root?: Document | ShadowRoot;
-    }): {
-        css: string;
-        ruleCount: number;
-        size: number;
-    };
-    defs(opts?: {
-        root?: Document | ShadowRoot;
-    }): Definitions;
-    summary(opts?: SummaryOptions): Summary;
-    pageCSS(opts?: {
-        root?: Document | ShadowRoot;
-        prettify?: boolean;
-        log?: boolean;
-        includeCrossOrigin?: boolean;
-    }): string;
-    pageStats(opts?: {
-        root?: Document | ShadowRoot;
-        includeCrossOrigin?: boolean;
-    }): {
-        cssSize: number;
-        ruleCount: number;
-        stylesheetCount: number;
-        skippedStylesheets: number;
-    };
-    install(): void;
-    log(target: CSSTarget, opts?: CssOptions & {
-        title?: string;
-    }): void;
-    help(): void;
-};
-export {};

package/types/tasty/hooks/index.d.ts

@@ -1,7 +0,0 @@
-export { useStyles } from './useStyles';
-export type { UseStylesOptions, UseStylesResult } from './useStyles';
-export { useGlobalStyles } from './useGlobalStyles';
-export { useRawCSS } from './useRawCSS';
-export { useKeyframes } from './useKeyframes';
-export { useProperty } from './useProperty';
-export type { UsePropertyOptions } from './useProperty';

package/types/tasty/hooks/useGlobalStyles.d.ts

@@ -1,22 +0,0 @@
-import { Styles } from '../styles/types';
-/**
- * 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 declare function useGlobalStyles(selector: string, styles?: Styles): void;

package/types/tasty/hooks/useKeyframes.d.ts

@@ -1,52 +0,0 @@
-import { KeyframesSteps } from '../injector/types';
-type UseKeyframesOptions = {
-    name?: string;
-    root?: Document | ShadowRoot;
-};
-/**
- * Hook to inject CSS @keyframes and return the generated animation name.
- * Handles keyframes injection with proper cleanup on unmount or dependency changes.
- *
- * @example Basic usage - steps object is the dependency
- * ```tsx
- * function MyComponent() {
- *   const bounce = useKeyframes({
- *     '0%': { transform: 'scale(1)' },
- *     '50%': { transform: 'scale(1.1)' },
- *     '100%': { transform: 'scale(1)' },
- *   });
- *
- *   return <div style={{ animation: `${bounce} 1s infinite` }}>Bouncing</div>;
- * }
- * ```
- *
- * @example With custom name
- * ```tsx
- * function MyComponent() {
- *   const fadeIn = useKeyframes(
- *     { from: { opacity: 0 }, to: { opacity: 1 } },
- *     { name: 'fadeIn' }
- *   );
- *
- *   return <div style={{ animation: `${fadeIn} 0.3s ease-out` }}>Fading in</div>;
- * }
- * ```
- *
- * @example Factory function with dependencies
- * ```tsx
- * function MyComponent({ scale }: { scale: number }) {
- *   const pulse = useKeyframes(
- *     () => ({
- *       '0%': { transform: 'scale(1)' },
- *       '100%': { transform: `scale(${scale})` },
- *     }),
- *     [scale]
- *   );
- *
- *   return <div style={{ animation: `${pulse} 1s infinite` }}>Pulsing</div>;
- * }
- * ```
- */
-export declare function useKeyframes(steps: KeyframesSteps, options?: UseKeyframesOptions): string;
-export declare function useKeyframes(factory: () => KeyframesSteps, deps: readonly unknown[], options?: UseKeyframesOptions): string;
-export {};

package/types/tasty/hooks/useProperty.d.ts

@@ -1,75 +0,0 @@
-export interface UsePropertyOptions {
-    /**
-     * CSS syntax string for the property (e.g., '<color>', '<length>', '<angle>').
-     * For color tokens (#name), this is auto-set to '<color>' and cannot be overridden.
-     * @see https://developer.mozilla.org/en-US/docs/Web/CSS/@property/syntax
-     */
-    syntax?: string;
-    /**
-     * Whether the property inherits from parent elements
-     * @default true
-     */
-    inherits?: boolean;
-    /**
-     * Initial value for the property.
-     * For color tokens (#name), this defaults to 'transparent' if not specified.
-     */
-    initialValue?: string | number;
-    /**
-     * Shadow root or document to inject into
-     */
-    root?: Document | ShadowRoot;
-}
-/**
- * Hook to register a CSS @property custom property.
- * This enables advanced features like animating custom properties.
- *
- * Note: @property rules are global and persistent once defined.
- * The hook ensures the property is only registered once per root.
- *
- * Accepts tasty token syntax for the property name:
- * - `$name` → defines `--name`
- * - `#name` → defines `--name-color` (auto-sets syntax: '<color>', defaults initialValue: 'transparent')
- * - `--name` → defines `--name` (legacy format)
- *
- * @param name - The property token ($name, #name) or CSS property name (--name)
- * @param options - Property configuration
- *
- * @example Basic property with token syntax
- * ```tsx
- * function Spinner() {
- *   useProperty('$rotation', {
- *     syntax: '<angle>',
- *     inherits: false,
- *     initialValue: '0deg',
- *   });
- *
- *   return <div className="spinner" />;
- * }
- * ```
- *
- * @example Color property with token syntax (auto-sets syntax)
- * ```tsx
- * function MyComponent() {
- *   useProperty('#theme', {
- *     initialValue: 'red', // syntax: '<color>' is auto-set
- *   });
- *
- *   // Now --theme-color can be animated with CSS transitions
- *   return <div style={{ '--theme-color': 'blue' } as React.CSSProperties}>Colored</div>;
- * }
- * ```
- *
- * @example Legacy format (still supported)
- * ```tsx
- * function ResizableBox() {
- *   useProperty('--box-size', {
- *     syntax: '<length>',
- *     initialValue: '100px',
- *   });
- *
- *   return <div style={{ width: 'var(--box-size)' }} />;
- * }
- * ```
- */
-export declare function useProperty(name: string, options?: UsePropertyOptions): void;