@cube-dev/ui-kit 0.74.3 → 0.76.0

package/types/tasty/debug.d.ts

@@ -0,0 +1,163 @@
+/**
+ * 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 InspectResult {
+    element?: Element | null;
+    classes: string[];
+    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 GlobalBreakdown {
+    css: string;
+    totalRules: number;
+    totalCSSSize: number;
+    selectors: {
+        elements: string[];
+        classes: string[];
+        ids: string[];
+        pseudoClasses: string[];
+        mediaQueries: string[];
+        keyframes: string[];
+        other: string[];
+    };
+}
+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;
+    totalCSSSize: number;
+    activeCSS: string;
+    unusedCSS: string;
+    allCSS: string;
+    globalCSS: string;
+    globalCSSSize: number;
+    globalRuleCount: 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;
+        };
+    };
+}
+/**
+ * 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;
+    global(opts?: {
+        root?: Document | ShadowRoot;
+        log?: boolean;
+    }): GlobalBreakdown;
+    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/index.d.ts

@@ -11,6 +11,8 @@ export * from './providers/BreakpointsProvider';
 export * from './utils/mergeStyles';
 export * from './utils/warnings';
 export * from './utils/getDisplayName';
+export * from './injector';
+export * from './debug';
 export type { TastyProps, GlobalTastyProps, AllBasePropsWithMods, } from './tasty';
 export type { AllBaseProps, BaseProps, BaseStyleProps, DimensionStyleProps, ColorStyleProps, OuterStyleProps, PositionStyleProps, TextStyleProps, BlockStyleProps, ContainerStyleProps, BasePropsWithoutChildren, Props, FlowStyleProps, ShortGridStyles, GlobalStyledProps, TagName, } from './types';
 export type { StylesInterface, Styles, StylesWithoutSelectors, NoType, Selector, SuffixForSelector, NotSelector, } from './styles/types';

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

@@ -0,0 +1,87 @@
+import { StyleResult } from '../utils/renderStyles';
+import { StyleInjector } from './injector';
+import { GlobalInjectResult, InjectResult, StyleInjectorConfig } from './types';
+declare const GLOBAL_INJECTOR_KEY = "__TASTY_GLOBAL_INJECTOR__";
+declare global {
+    interface Window {
+        [GLOBAL_INJECTOR_KEY]?: StyleInjector;
+    }
+}
+/**
+ * Configure the global style injector
+ */
+export declare function configure(config?: Partial<StyleInjectorConfig>): void;
+/**
+ * Allocate a className for a cacheKey without injecting styles yet
+ */
+export declare function allocateClassName(cacheKey: string, options?: {
+    root?: Document | ShadowRoot;
+}): {
+    className: string;
+    isNewAllocation: boolean;
+};
+/**
+ * Inject styles and return className with dispose function
+ */
+export declare function inject(rules: StyleResult[], options?: {
+    root?: Document | ShadowRoot;
+    cacheKey?: string;
+}): InjectResult;
+/**
+ * Inject global rules that should not reserve tasty class names
+ */
+export declare function injectGlobal(rules: StyleResult[], options?: {
+    root?: Document | ShadowRoot;
+}): GlobalInjectResult;
+/**
+ * Inject keyframes and return object with toString() and dispose()
+ */
+export declare function keyframes(steps: import('./types').KeyframesSteps, nameOrOptions?: string | {
+    root?: Document | ShadowRoot;
+    name?: string;
+}): import('./types').KeyframesResult;
+/**
+ * Get CSS text from all sheets (for SSR)
+ */
+export declare function getCssText(options?: {
+    root?: Document | ShadowRoot;
+}): string;
+/**
+ * Collect only CSS used by a rendered subtree (like jest-styled-components).
+ * Pass the container returned by render(...).
+ */
+export declare function getCssTextForNode(node: ParentNode | Element | DocumentFragment, options?: {
+    root?: Document | ShadowRoot;
+}): string;
+/**
+ * Force cleanup of unused rules
+ */
+export declare function cleanup(root?: Document | ShadowRoot): void;
+/**
+ * Check if we're currently running in a test environment
+ */
+export declare function getIsTestEnvironment(): boolean;
+/**
+ * Get the global injector instance for debugging
+ */
+export declare const injector: {
+    readonly instance: StyleInjector;
+};
+/**
+ * Destroy all resources and clean up
+ */
+export declare function destroy(root?: Document | ShadowRoot): void;
+/**
+ * Create a new isolated injector instance
+ */
+export declare function createInjector(config?: Partial<StyleInjectorConfig>): StyleInjector;
+/**
+ * Create a global style component like styled-components createGlobalStyle
+ * Returns a React component that injects global styles when mounted and cleans up when unmounted
+ */
+export declare function createGlobalStyle<Props = {}>(strings: TemplateStringsArray, ...interpolations: Array<string | number | ((props: Props) => string | number)>): import('react').ComponentType<Props & {
+    root?: Document | ShadowRoot;
+}>;
+export type { StyleInjectorConfig, InjectResult, DisposeFunction, RuleInfo, SheetInfo, RootRegistry, StyleRule, KeyframesInfo, KeyframesResult, KeyframesSteps, KeyframesCacheEntry, CacheMetrics, } from './types';
+export { StyleInjector } from './injector';
+export { SheetManager } from './sheet-manager';

package/types/tasty/injector/injector.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Style injector that works with structured style objects
+ * Eliminates CSS string parsing for better performance
+ */
+import { StyleResult } from '../utils/renderStyles';
+import { GlobalInjectResult, InjectResult, KeyframesResult, KeyframesSteps, StyleInjectorConfig } from './types';
+import type { ComponentType } from 'react';
+export declare class StyleInjector {
+    private sheetManager;
+    private config;
+    private cleanupScheduled;
+    private globalRuleCounter;
+    constructor(config?: StyleInjectorConfig);
+    /**
+     * Allocate a className for a cacheKey without injecting styles yet.
+     * This allows separating className allocation (render phase) from style injection (insertion phase).
+     */
+    allocateClassName(cacheKey: string, options?: {
+        root?: Document | ShadowRoot;
+    }): {
+        className: string;
+        isNewAllocation: boolean;
+    };
+    /**
+     * Inject styles from StyleResult objects
+     */
+    inject(rules: StyleResult[], options?: {
+        root?: Document | ShadowRoot;
+        cacheKey?: string;
+    }): InjectResult;
+    /**
+     * Inject global styles (rules without a generated tasty class selector)
+     * This ensures we don't reserve a tasty class name (t{number}) for global rules,
+     * which could otherwise collide with element-level styles and break lookups.
+     */
+    injectGlobal(rules: StyleResult[], options?: {
+        root?: Document | ShadowRoot;
+    }): GlobalInjectResult;
+    /**
+     * Dispose of a className
+     */
+    private dispose;
+    /**
+     * Force bulk cleanup of unused styles
+     */
+    cleanup(root?: Document | ShadowRoot): void;
+    /**
+     * Get CSS text from all sheets (for SSR)
+     */
+    getCssText(options?: {
+        root?: Document | ShadowRoot;
+    }): string;
+    /**
+     * Get CSS only for the provided tasty classNames (e.g., ["t0","t3"])
+     */
+    getCssTextForClasses(classNames: Iterable<string>, options?: {
+        root?: Document | ShadowRoot;
+    }): string;
+    /**
+     * Get cache performance metrics
+     */
+    getMetrics(options?: {
+        root?: Document | ShadowRoot;
+    }): any;
+    /**
+     * Reset cache performance metrics
+     */
+    resetMetrics(options?: {
+        root?: Document | ShadowRoot;
+    }): void;
+    /**
+     * Define a CSS @property custom property
+     * Example:
+     * @property --rotation { syntax: "<angle>"; inherits: false; initial-value: 45deg; }
+     * Note: No caching or dispose — this defines a global property.
+     */
+    property(name: string, options?: {
+        syntax?: string;
+        inherits?: boolean;
+        initialValue?: string | number;
+        root?: Document | ShadowRoot;
+    }): void;
+    /**
+     * Check whether a given @property name was already injected by this injector
+     */
+    isPropertyDefined(name: string, options?: {
+        root?: Document | ShadowRoot;
+    }): boolean;
+    /**
+     * Inject keyframes and return object with toString() and dispose()
+     */
+    keyframes(steps: KeyframesSteps, nameOrOptions?: string | {
+        root?: Document | ShadowRoot;
+        name?: string;
+    }): KeyframesResult;
+    /**
+     * Dispose keyframes
+     */
+    private disposeKeyframes;
+    /**
+     * Destroy all resources for a root
+     */
+    destroy(root?: Document | ShadowRoot): void;
+    /**
+     * Create a global style component like styled-components createGlobalStyle
+     * Returns a React component that injects global styles when mounted and cleans up when unmounted
+     */
+    createGlobalStyle<Props = {}>(strings: TemplateStringsArray, ...interpolations: Array<string | number | ((props: Props) => string | number)>): ComponentType<Props & {
+        root?: Document | ShadowRoot;
+    }>;
+}

package/types/tasty/injector/sheet-manager.d.ts

@@ -0,0 +1,98 @@
+import { CacheMetrics, KeyframesInfo, KeyframesSteps, RootRegistry, RuleInfo, SheetInfo, StyleInjectorConfig, StyleRule } from './types';
+export declare class SheetManager {
+    private rootRegistries;
+    private config;
+    constructor(config: StyleInjectorConfig);
+    /**
+     * Get or create registry for a root (Document or ShadowRoot)
+     */
+    getRegistry(root: Document | ShadowRoot): RootRegistry;
+    /**
+     * Create a new stylesheet for the registry
+     */
+    createSheet(registry: RootRegistry, root: Document | ShadowRoot): SheetInfo;
+    /**
+     * Create a style element and append to document
+     */
+    private createStyleElement;
+    /**
+     * Insert CSS rules as a single block
+     */
+    insertRule(registry: RootRegistry, flattenedRules: StyleRule[], className: string, root: Document | ShadowRoot): RuleInfo | null;
+    /**
+     * Insert global CSS rules
+     */
+    insertGlobalRule(registry: RootRegistry, flattenedRules: StyleRule[], globalKey: string, root: Document | ShadowRoot): RuleInfo | null;
+    /**
+     * Delete a global CSS rule by key
+     */
+    deleteGlobalRule(registry: RootRegistry, globalKey: string): void;
+    /**
+     * Adjust rule indices after deletion to account for shifting
+     */
+    private adjustIndicesAfterDeletion;
+    /**
+     * Delete a CSS rule from the sheet
+     */
+    deleteRule(registry: RootRegistry, ruleInfo: RuleInfo): void;
+    /**
+     * Find a sheet with available space or return null
+     */
+    private findAvailableSheet;
+    /**
+     * Find an available rule index in the sheet
+     */
+    findAvailableRuleIndex(sheet: SheetInfo): number;
+    /**
+     * Schedule bulk cleanup of all unused styles (non-stacking)
+     */
+    private scheduleBulkCleanup;
+    /**
+     * Force cleanup of unused styles
+     */
+    forceCleanup(registry: RootRegistry): void;
+    /**
+     * Perform bulk cleanup of all unused styles
+     */
+    private performBulkCleanup;
+    /**
+     * Get total number of rules across all sheets
+     */
+    getTotalRuleCount(registry: RootRegistry): number;
+    /**
+     * Get CSS text from all sheets (for SSR)
+     */
+    getCssText(registry: RootRegistry): string;
+    /**
+     * Get cache performance metrics
+     */
+    getMetrics(registry: RootRegistry): CacheMetrics | null;
+    /**
+     * Reset cache performance metrics
+     */
+    resetMetrics(registry: RootRegistry): void;
+    /**
+     * Convert keyframes steps to CSS string
+     */
+    private stepsToCSS;
+    /**
+     * Insert keyframes rule
+     */
+    insertKeyframes(registry: RootRegistry, steps: KeyframesSteps, name: string, root: Document | ShadowRoot): KeyframesInfo | null;
+    /**
+     * Delete keyframes rule
+     */
+    deleteKeyframes(registry: RootRegistry, info: KeyframesInfo): void;
+    /**
+     * Schedule async cleanup check (non-stacking)
+     */
+    checkCleanupNeeded(registry: RootRegistry): void;
+    /**
+     * Perform the actual cleanup check (called asynchronously)
+     */
+    private performCleanupCheck;
+    /**
+     * Clean up resources for a root
+     */
+    cleanup(root: Document | ShadowRoot): void;
+}

package/types/tasty/injector/types.d.ts

@@ -0,0 +1,106 @@
+export interface InjectResult {
+    className: string;
+    dispose: () => void;
+}
+export interface GlobalInjectResult {
+    dispose: () => void;
+}
+export type DisposeFunction = () => void;
+export interface StyleInjectorConfig {
+    nonce?: string;
+    maxRulesPerSheet?: number;
+    unusedStylesThreshold?: number;
+    bulkCleanupDelay?: number;
+    idleCleanup?: boolean;
+    forceTextInjection?: boolean;
+    /** Enable development mode features: performance metrics and debug information storage */
+    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;
+}
+export interface RuleInfo {
+    className: string;
+    ruleIndex: number;
+    sheetIndex: number;
+    /** Dev-only: full CSS texts inserted for this class; omitted in production */
+    cssText?: string[];
+    /** Inclusive end index of the contiguous block of inserted rules for this className */
+    endRuleIndex?: number;
+    /** NEW: exact indices of all inserted rules for this className */
+    indices?: number[];
+}
+export interface SheetInfo {
+    sheet: HTMLStyleElement;
+    ruleCount: number;
+    holes: number[];
+}
+export interface CleanupStats {
+    timestamp: number;
+    classesDeleted: number;
+    cssSize: number;
+    rulesDeleted: number;
+}
+export interface CacheMetrics {
+    hits: number;
+    misses: number;
+    bulkCleanups: number;
+    totalInsertions: number;
+    totalUnused: number;
+    stylesCleanedUp: number;
+    cleanupHistory: CleanupStats[];
+    startTime: number;
+    unusedHits?: number;
+}
+export interface RootRegistry {
+    sheets: SheetInfo[];
+    refCounts: Map<string, number>;
+    rules: Map<string, RuleInfo>;
+    /** Cache key to className mapping to avoid dual storage of RuleInfo objects */
+    cacheKeyToClassName: Map<string, string>;
+    /** Deduplication set of fully materialized CSS rules inserted into sheets */
+    ruleTextSet: Set<string>;
+    /** Scheduled bulk cleanup timeout */
+    bulkCleanupTimeout: ReturnType<typeof requestIdleCallback> | ReturnType<typeof setTimeout> | null;
+    /** Scheduled cleanup check timeout */
+    cleanupCheckTimeout: ReturnType<typeof setTimeout> | null;
+    /** Performance metrics (optional) */
+    metrics?: CacheMetrics;
+    /** Counter for generating sequential class names like t0, t1, t2... */
+    classCounter: number;
+    /** Keyframes cache by JSON.stringify(steps) -> entry */
+    keyframesCache: Map<string, KeyframesCacheEntry>;
+    /** Counter for generating keyframes names like k0, k1, k2... */
+    keyframesCounter: number;
+    /** Set of injected @property names for tracking */
+    injectedProperties: Set<string>;
+    /** Global rules tracking for index adjustment */
+    globalRules: Map<string, RuleInfo>;
+}
+export type StyleRule = import('../utils/renderStyles').StyleResult;
+export interface KeyframesInfo {
+    name: string;
+    sheetIndex: number;
+    ruleIndex: number;
+    /** Dev-only: full CSS text of the @keyframes rule; omitted in production */
+    cssText?: string;
+}
+export type KeyframeStep = string | Record<string, string | number>;
+export type KeyframesSteps = Record<string, KeyframeStep>;
+export interface KeyframesResult {
+    toString(): string;
+    dispose: () => void;
+}
+export interface KeyframesCacheEntry {
+    name: string;
+    refCount: number;
+    info: KeyframesInfo;
+}

package/types/tasty/parser/lru.d.ts

@@ -3,9 +3,13 @@ export declare class Lru<K, V> {
     private map;
     private head;
     private tail;
-    constructor(limit?: number);
+    private onEvict?;
+    constructor(limit?: number, onEvict?: (key: K, value: V) => void);
+    setOnEvict(fn?: (key: K, value: V) => void): void;
     get(key: K): V | undefined;
     set(key: K, value: V): void;
+    delete(key: K): void;
+    keys(): IterableIterator<K>;
     private touch;
     private evict;
     clear(): void;

package/types/tasty/styles/color.d.ts

@@ -1,6 +1,8 @@
 export declare function colorStyle({ color }: {
     color: any;
-}): any[] | "";
+}): "" | {
+    color: any;
+};
 export declare namespace colorStyle {
     var __lookupStyles: string[];
 }

package/types/tasty/styles/reset.d.ts

@@ -1,7 +1,6 @@
-import { CSSMap } from '../utils/styles';
 export declare function resetStyle({ reset }: {
     reset: any;
-}): CSSMap[] | undefined;
+}): any[] | undefined;
 export declare namespace resetStyle {
     var __lookupStyles: string[];
 }

package/types/tasty/types.d.ts

@@ -32,8 +32,6 @@ export interface BasePropsWithoutChildren<K extends TagName = TagName> extends P
     isDisabled?: boolean;
     /** Plain css for the element */
     css?: string;
-    /** The element name for using in style overriding */
-    styleName?: string;
     /** The CSS style map */
     style?: CSSProperties | (CSSProperties & {
         [key: string]: string | number | null;

package/types/tasty/utils/getModCombinations.d.ts

@@ -1 +1,9 @@
-export declare function getModCombinations(array: string[], allowEmpty?: boolean): any;
+export type ConflictChecker = (combination: string[]) => boolean;
+/**
+ * Efficient iterative combination generator with early pruning
+ * Generates combinations one by one and prunes branches early when conflicts are detected
+ * @param array - Array of mod strings to generate combinations from
+ * @param allowEmpty - Whether to include empty combination
+ * @param conflictChecker - Function to detect conflicting combinations (required)
+ */
+export declare function getModCombinationsIterative(array: string[], allowEmpty?: boolean, conflictChecker?: ConflictChecker): string[][];

package/types/tasty/utils/isDevEnv.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Check if we're in a development environment at runtime
+ * Uses bracket notation to avoid bundler compilation
+ * Also checks for TASTY_DEBUG localStorage setting
+ */
+export declare function isDevEnv(): boolean;

package/types/tasty/utils/renderStyles.d.ts

@@ -1,10 +1,33 @@
+/**
+ * Style rendering that works with structured style objects
+ * Eliminates CSS string parsing for better performance
+ */
 import { Styles } from '../styles/types';
-export declare function isSelector(key: any): any;
+export interface StyleResult {
+    selector: string;
+    declarations: string;
+    atRules?: string[];
+    needsClassName?: boolean;
+}
+export interface RenderResult {
+    rules: StyleResult[];
+    className?: string;
+}
+/**
+ * Check if a key represents a CSS selector
+ */
+export declare function isSelector(key: string): boolean;
+/**
+ * Render styles to StyleResult[] format (recommended)
+ * Supports both component and global styling with advanced optimizations
+ */
+export declare function renderStyles(styles?: Styles, responsive?: number[], className?: string): RenderResult;
+/**
+ * Render styles without className for element styles (injector will add it)
+ */
+export declare function renderStyles(styles: Styles | undefined, responsive?: number[]): RenderResult;
 /**
- * Render style props to complete Styled Components CSS.
- * @param styles - Complete style props.
- * @param responsive - A list of responsive zones
- * @param {string} [suffix]
- * @return {string}
+ * Render styles for direct injection with a specific selector
+ * Bypasses CSS text generation and flattening by directly creating StyleResult[]
  */
-export declare function renderStyles(styles?: Styles, responsive?: number[], suffix?: string): any;
+export declare function renderStyles(styles: Styles | undefined, responsive: number[], selector: string): StyleResult[];

package/types/tasty/utils/responsive.d.ts

@@ -1,5 +1,4 @@
 import { ResponsiveStyleValue } from './styles';
-export declare function mediaWrapper(cssRules: any, points: any): any;
 export interface ResponsiveZone {
     max?: number;
     min?: number;