@cube-dev/ui-kit 0.75.0 → 0.76.0

package/types/tasty/debug.d.ts

@@ -1,173 +1,98 @@
 /**
  * Debug utilities for inspecting tasty-generated CSS at runtime
  */
-/**
- * Debug utilities for inspecting tasty styles in runtime applications
- */
-export declare const tastyDebug: {
-    /**
-     * Get CSS for a specific tasty class (e.g., 't24')
-     */
-    getCSSForClass(className: string): string;
-    /**
-     * Get CSS for multiple tasty classes
-     */
-    getCSSForClasses(classNames: string[]): string;
-    /**
-     * Log CSS for a specific tasty class (e.g., 't24') to console
-     */
-    logCSSForClass(className: string): void;
-    /**
-     * Log CSS for multiple tasty classes to console
-     */
-    logCSSForClasses(classNames: string[]): void;
-    /**
-     * Inspect an element by CSS selector and get its tasty CSS
-     */
-    inspectElement(selector: string): string;
-    /**
-     * Inspect a DOM element directly and get its tasty CSS
-     */
-    inspectDOMElement(element: Element): string;
-    /**
-     * Get all tasty CSS currently injected into the page
-     */
-    getAllCSS(): string;
-    /**
-     * Find all tasty classes used in the page (in DOM)
-     */
-    findAllTastyClasses(): string[];
-    /**
-     * Find all tasty classes that have styles in the stylesheet (used + unused)
-     */
-    findAllStyledClasses(): string[];
-    /**
-     * Get active vs cached class breakdown
-     */
-    getClassUsage(): {
-        activeClasses: string[];
-        cachedClasses: string[];
-        totalStyledClasses: string[];
+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[];
     };
-    /**
-     * Get a comprehensive summary of all tasty styles
-     */
-    getSummary(): {
-        activeClasses: string[];
-        cachedClasses: string[];
-        totalStyledClasses: string[];
-        activeCSSSize: number;
-        cachedCSSSize: number;
-        totalCSSSize: number;
-        activeCSS: string;
-        cachedCSS: string;
-        allCSS: string;
-        globalCSS: string;
-        globalCSSSize: number;
-        globalRuleCount: number;
-        metrics: any;
-        definedProperties: string[];
-        definedKeyframes: {
-            name: string;
-            refCount: number;
-            cssText?: string;
-        }[];
-        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;
-            };
-        };
+    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[];
     };
-    /**
-     * Helper to log CSS in a readable format
-     */
-    logCSS(css: string, title?: string): void;
-    /**
-     * Advanced inspection with detailed breakdown and statistics
-     */
-    inspect(target: string | Element): {
-        element: Element | null;
-        tastyClasses: string[];
-        css: 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;
-        breakdown: {
-            [className: string]: {
-                css: string;
-                cssSize: number;
-                ruleCount: number;
-            };
-        };
-        stats: {
-            totalClasses: number;
-            totalRules: number;
-            totalCSSSize: number;
-            averageRulesPerClass: number;
-            averageCSSPerClass: number;
-        };
+        stylesheetCount: number;
+        skippedStylesheets: number;
     };
-    /**
-     * Get CSS for active classes only
-     */
-    getActiveCSS(): string;
-    /**
-     * Get CSS for cached classes only
-     */
-    getCachedCSS(): string;
-    /**
-     * Get all defined @property custom properties
-     */
-    getDefinedProperties(): string[];
-    /**
-     * Get all defined keyframes
-     */
-    getDefinedKeyframes(): {
+    metrics: CacheMetrics | null;
+    definedProperties: string[];
+    definedKeyframes: Array<{
         name: string;
         refCount: number;
-        cssText?: string;
-    }[];
-    /**
-     * Check if a specific @property is defined
-     */
-    isPropertyDefined(propertyName: string): boolean;
-    /**
-     * Check if a specific keyframe is defined
-     */
-    isKeyframeDefined(keyframeName: string): boolean;
-    /**
-     * Get detailed cleanup statistics history
-     */
-    getCleanupHistory(): {
-        totalCleanups: number;
-        totalClassesDeleted: number;
-        totalCssDeleted: number;
-        totalRulesDeleted: number;
-        cleanupHistory: Array<{
-            timestamp: number;
-            date: string;
-            classesDeleted: number;
-            cssSize: number;
-            rulesDeleted: number;
-        }>;
-    };
-    /**
-     * Get cleanup statistics summary
-     */
-    getCleanupSummary(): {
+    }>;
+    propertyCount: number;
+    keyframeCount: number;
+    cleanupSummary: {
         enabled: boolean;
         totalCleanups: number;
         totalClassesDeleted: number;
@@ -184,67 +109,55 @@ export declare const tastyDebug: {
             rulesDeleted: number;
         };
     };
-    /**
-     * Log cleanup history to console in a readable format
-     */
-    logCleanupHistory(): void;
-    /**
-     * Get all global CSS rules (non-tasty class selectors)
-     */
-    getGlobalCSS(): string;
-    /**
-     * Log global CSS to console
-     */
-    logGlobalCSS(): void;
-    /**
-     * Get global CSS rules breakdown with detailed analysis
-     */
-    getGlobalCSSBreakdown(): {
-        globalRules: Array<{
-            selector: string;
-            declarations: string;
-            ruleCount: number;
-        }>;
-        totalRules: number;
-        totalCSSSize: number;
-        css: string;
-        selectors: {
-            elements: string[];
-            classes: string[];
-            ids: string[];
-            pseudoClasses: string[];
-            mediaQueries: string[];
-            keyframes: string[];
-            other: string[];
-        };
-    };
-    /**
-     * Log detailed global CSS breakdown
-     */
-    logGlobalCSSBreakdown(): void;
-    /**
-     * Helper to extract CSS rules from raw CSS text
-     */
-    extractCSSRules(css: string): Array<{
-        selector: string;
-        declarations: string;
-    }>;
-    /**
-     * Safe CSS parser that handles nested rules properly
-     */
-    parseCSSSafe(css: string, rules: Array<{
-        selector: string;
-        declarations: string;
-    }>): void;
-    /**
-     * Debug method to see raw CSS content and rule parsing
-     */
-    debugRawCSS(): void;
-};
+}
 /**
- * Install tastyDebug on window object for easy access in browser console
- * Only in non-production environments
+ * Concise tastyDebug API for inspecting styles at runtime
  */
-export declare function installGlobalDebug(options?: {
-    force?: boolean;
-}): void;
+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/injector/index.d.ts

@@ -1,6 +1,6 @@
 import { StyleResult } from '../utils/renderStyles';
 import { StyleInjector } from './injector';
-import { InjectResult, StyleInjectorConfig } from './types';
+import { GlobalInjectResult, InjectResult, StyleInjectorConfig } from './types';
 declare const GLOBAL_INJECTOR_KEY = "__TASTY_GLOBAL_INJECTOR__";
 declare global {
     interface Window {
@@ -11,12 +11,28 @@ declare global {
  * 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()
  */
@@ -66,6 +82,6 @@ export declare function createInjector(config?: Partial<StyleInjectorConfig>): S
 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, UnusedRuleInfo, CacheMetrics, } from './types';
+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

@@ -3,39 +3,47 @@
  * Eliminates CSS string parsing for better performance
  */
 import { StyleResult } from '../utils/renderStyles';
-import { InjectResult, KeyframesResult, KeyframesSteps, StyleInjectorConfig } from './types';
+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;
     /**
-     * Extract className from rules (assumes first rule contains the base className)
+     * 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.
      */
-    private extractClassName;
-    /**
-     * Generate cache key from style rules with optimized deduplication
-     */
-    private generateCacheKey;
+    injectGlobal(rules: StyleResult[], options?: {
+        root?: Document | ShadowRoot;
+    }): GlobalInjectResult;
     /**
      * Dispose of a className
      */
     private dispose;
-    /**
-     * Cleanup unused rules
-     */
-    cleanup(root?: Document | ShadowRoot): void;
     /**
      * Force bulk cleanup of unused styles
      */
-    forceBulkCleanup(root?: Document | ShadowRoot): void;
+    cleanup(root?: Document | ShadowRoot): void;
     /**
      * Get CSS text from all sheets (for SSR)
      */
@@ -60,12 +68,6 @@ export declare class StyleInjector {
     resetMetrics(options?: {
         root?: Document | ShadowRoot;
     }): void;
-    /**
-     * Force cleanup of unused styles (useful for memory pressure)
-     */
-    forceCleanupUnused(options?: {
-        root?: Document | ShadowRoot;
-    }): void;
     /**
      * Define a CSS @property custom property
      * Example:

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

@@ -22,7 +22,15 @@ export declare class SheetManager {
     /**
      * Insert global CSS rules
      */
-    insertGlobalRule(registry: RootRegistry, flattenedRules: StyleRule[], className: string, root: Document | ShadowRoot): RuleInfo | null;
+    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
      */
@@ -36,25 +44,17 @@ export declare class SheetManager {
      */
     findAvailableRuleIndex(sheet: SheetInfo): number;
     /**
-     * Mark a ruleset as unused but keep it in the stylesheet
-     */
-    markAsUnused(registry: RootRegistry, className: string): void;
-    /**
-     * Restore a ruleset from unused styles
+     * Schedule bulk cleanup of all unused styles (non-stacking)
      */
-    restoreFromUnused(registry: RootRegistry, className: string): RuleInfo | null;
+    private scheduleBulkCleanup;
     /**
-     * Schedule bulk cleanup of all unused styles
+     * Force cleanup of unused styles
      */
-    private scheduleBulkCleanup;
+    forceCleanup(registry: RootRegistry): void;
     /**
      * Perform bulk cleanup of all unused styles
      */
     private performBulkCleanup;
-    /**
-     * Process the deletion queue for cleanup
-     */
-    processCleanupQueue(registry: RootRegistry): void;
     /**
      * Get total number of rules across all sheets
      */
@@ -84,9 +84,13 @@ export declare class SheetManager {
      */
     deleteKeyframes(registry: RootRegistry, info: KeyframesInfo): void;
     /**
-     * Mark keyframes as unused
+     * Schedule async cleanup check (non-stacking)
+     */
+    checkCleanupNeeded(registry: RootRegistry): void;
+    /**
+     * Perform the actual cleanup check (called asynchronously)
      */
-    markKeyframesAsUnused(registry: RootRegistry, name: string): void;
+    private performCleanupCheck;
     /**
      * Clean up resources for a root
      */

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

@@ -2,6 +2,9 @@ export interface InjectResult {
     className: string;
     dispose: () => void;
 }
+export interface GlobalInjectResult {
+    dispose: () => void;
+}
 export type DisposeFunction = () => void;
 export interface StyleInjectorConfig {
     nonce?: string;
@@ -9,28 +12,37 @@ export interface StyleInjectorConfig {
     unusedStylesThreshold?: number;
     bulkCleanupDelay?: number;
     idleCleanup?: boolean;
-    collectMetrics?: boolean;
     forceTextInjection?: boolean;
-    /** When false, avoid storing full cssText for each rule block to reduce memory. */
-    debugMode?: 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;
-    cssText: string[];
+    /** 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 UnusedRuleInfo {
-    ruleInfo: RuleInfo;
-    markedUnusedAt: number;
-}
 export interface CleanupStats {
     timestamp: number;
     classesDeleted: number;
@@ -40,42 +52,46 @@ export interface CleanupStats {
 export interface CacheMetrics {
     hits: number;
     misses: number;
-    unusedHits: 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>;
-    unusedRules: Map<string, UnusedRuleInfo>;
+    /** 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>;
-    /** Unused keyframes for cleanup */
-    unusedKeyframes: Map<string, UnusedRuleInfo>;
     /** 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;
-    cssText: string;
+    /** 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>;

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;