@cube-dev/ui-kit 0.0.0-canary-9e3bcfc → 0.0.0-canary-eaff7d7

package/types/stories/components/StyledButton.d.ts

@@ -3,5 +3,5 @@ export declare const StyledButton: import("react").ComponentType<{
     [x: number]: any;
     [x: symbol]: any;
 } & {}>;
-export declare const GlobalStyledHeading: any;
+export declare function GlobalStyledHeading(): null;
 export declare function Block(): import("react/jsx-runtime").JSX.Element;

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

@@ -40,6 +40,8 @@ export declare const SCROLLBAR_CHUNK_STYLES: readonly ["scrollbar", "overflow",
  */
 export declare const POSITION_CHUNK_STYLES: readonly ["position", "inset", "top", "right", "bottom", "left", "zIndex", "gridArea", "gridColumn", "gridRow", "order", "placeSelf", "alignSelf", "justifySelf", "transform", "transition", "animation"];
 export declare const CHUNK_NAMES: {
+    /** Special chunk for styles that cannot be split (e.g., @starting-style) */
+    readonly COMBINED: "combined";
     readonly SUBCOMPONENTS: "subcomponents";
     readonly APPEARANCE: "appearance";
     readonly FONT: "font";

package/types/tasty/config.d.ts

@@ -0,0 +1,113 @@
+/**
+ * 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.
+ */
+/**
+ * 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>;
+}
+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.
+ */
+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 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

@@ -7,9 +7,14 @@ interface CssOptions {
     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;
@@ -104,6 +109,14 @@ interface Summary {
             rulesDeleted: number;
         };
     };
+    chunkBreakdown: {
+        byChunk: Record<string, {
+            classes: string[];
+            cssSize: number;
+            ruleCount: number;
+        }>;
+        totalChunkTypes: number;
+    };
 }
 /**
  * Concise tastyDebug API for inspecting styles at runtime
@@ -126,6 +139,28 @@ export declare const tastyDebug: {
     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;
     }): {

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

@@ -1,4 +1,4 @@
 export { useStyles } from './useStyles';
 export type { UseStylesOptions, UseStylesResult } from './useStyles';
 export { useGlobalStyles } from './useGlobalStyles';
-export type { UseGlobalStylesOptions } from './useGlobalStyles';
+export { useRawCSS } from './useRawCSS';

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

@@ -1,32 +1,22 @@
 import { Styles } from '../styles/types';
-export interface UseGlobalStylesOptions {
-    /**
-     * CSS selector to apply styles to (e.g., '.my-class', ':root', 'body')
-     */
-    selector: string;
-    /**
-     * Tasty styles object
-     */
-    styles?: Styles;
-}
 /**
  * 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({
- *     selector: '.card',
- *     styles: {
- *       padding: '2x',
- *       radius: '1r',
- *       fill: '#white',
- *     }
+ *   useGlobalStyles('.card', {
+ *     padding: '2x',
+ *     radius: '1r',
+ *     fill: '#white',
  *   });
  *
  *   return <div className="card">Content</div>;
  * }
  * ```
  */
-export declare function useGlobalStyles({ selector, styles, }: UseGlobalStylesOptions): void;
+export declare function useGlobalStyles(selector: string, styles?: Styles): void;

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

@@ -0,0 +1,50 @@
+type UseRawCSSOptions = {
+    root?: Document | ShadowRoot;
+};
+/**
+ * Hook to inject raw CSS text directly without parsing.
+ * This is a low-overhead alternative for injecting global CSS that doesn't need tasty processing.
+ *
+ * The CSS is inserted into a separate style element (data-tasty-raw) to avoid conflicts
+ * with tasty's chunked style sheets.
+ *
+ * @example Static CSS string
+ * ```tsx
+ * function GlobalStyles() {
+ *   useRawCSS(`
+ *     body {
+ *       margin: 0;
+ *       padding: 0;
+ *       font-family: sans-serif;
+ *     }
+ *   `);
+ *
+ *   return null;
+ * }
+ * ```
+ *
+ * @example Factory function with dependencies (like useMemo)
+ * ```tsx
+ * function ThemeStyles({ theme }: { theme: 'light' | 'dark' }) {
+ *   useRawCSS(() => `
+ *     :root {
+ *       --bg-color: ${theme === 'dark' ? '#1a1a1a' : '#ffffff'};
+ *       --text-color: ${theme === 'dark' ? '#ffffff' : '#1a1a1a'};
+ *     }
+ *   `, [theme]);
+ *
+ *   return null;
+ * }
+ * ```
+ *
+ * @example With options
+ * ```tsx
+ * function ShadowStyles({ shadowRoot }) {
+ *   useRawCSS(() => `.scoped { color: red; }`, [], { root: shadowRoot });
+ *   return null;
+ * }
+ * ```
+ */
+export declare function useRawCSS(css: string, options?: UseRawCSSOptions): void;
+export declare function useRawCSS(factory: () => string, deps: readonly unknown[], options?: UseRawCSSOptions): void;
+export {};

package/types/tasty/index.d.ts

@@ -1,6 +1,8 @@
 export { tasty, Element } from './tasty';
-export { useStyles, useGlobalStyles } from './hooks';
-export type { UseStylesOptions, UseStylesResult, UseGlobalStylesOptions, } from './hooks';
+export { useStyles, useGlobalStyles, useRawCSS } from './hooks';
+export type { UseStylesOptions, UseStylesResult } from './hooks';
+export { configure, getConfig, isConfigLocked, hasStylesGenerated, resetConfig, isTestEnvironment, } from './config';
+export type { TastyConfig } from './config';
 export { CHUNK_NAMES, STYLE_TO_CHUNK, categorizeStyleKeys } from './chunks';
 export type { ChunkName, ChunkInfo } from './chunks';
 export { getGlobalPredefinedStates, setGlobalPredefinedStates } from './states';

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

@@ -1,16 +1,6 @@
 import { StyleResult } from '../pipeline';
 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
  */
@@ -33,6 +23,34 @@ export declare function inject(rules: StyleResult[], options?: {
 export declare function injectGlobal(rules: StyleResult[], options?: {
     root?: Document | ShadowRoot;
 }): GlobalInjectResult;
+/**
+ * Inject raw CSS text directly without parsing
+ * This is a low-overhead method for injecting raw CSS that doesn't need tasty processing.
+ * The CSS is inserted into a separate style element to avoid conflicts with tasty's chunking.
+ *
+ * @example
+ * ```tsx
+ * // Inject raw CSS
+ * const { dispose } = injectRawCSS(`
+ *   body { margin: 0; padding: 0; }
+ *   .my-class { color: red; }
+ * `);
+ *
+ * // Later, remove the injected CSS
+ * dispose();
+ * ```
+ */
+export declare function injectRawCSS(css: string, options?: {
+    root?: Document | ShadowRoot;
+}): {
+    dispose: () => void;
+};
+/**
+ * Get raw CSS text for SSR
+ */
+export declare function getRawCSSText(options?: {
+    root?: Document | ShadowRoot;
+}): string;
 /**
  * Inject keyframes and return object with toString() and dispose()
  */
@@ -75,13 +93,6 @@ 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 type { StyleInjectorConfig, InjectResult, DisposeFunction, RuleInfo, SheetInfo, RootRegistry, StyleRule, KeyframesInfo, KeyframesResult, KeyframesSteps, KeyframesCacheEntry, CacheMetrics, RawCSSResult, } from './types';
 export { StyleInjector } from './injector';
 export { SheetManager } from './sheet-manager';

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

@@ -3,8 +3,7 @@
  * Eliminates CSS string parsing for better performance
  */
 import { StyleResult } from '../pipeline';
-import { GlobalInjectResult, InjectResult, KeyframesResult, KeyframesSteps, StyleInjectorConfig } from './types';
-import type { ComponentType } from 'react';
+import { GlobalInjectResult, InjectResult, KeyframesResult, KeyframesSteps, RawCSSResult, StyleInjectorConfig } from './types';
 export declare class StyleInjector {
     private sheetManager;
     private config;
@@ -37,11 +36,19 @@ export declare class StyleInjector {
         root?: Document | ShadowRoot;
     }): GlobalInjectResult;
     /**
-     * Inject styles from createGlobalStyle (separate from injectGlobal for tracking)
+     * Inject raw CSS text directly without parsing
+     * This is a low-overhead alternative to createGlobalStyle for raw CSS
+     * The CSS is inserted into a separate style element to avoid conflicts with tasty's chunking
      */
-    injectCreateGlobalStyle(rules: StyleResult[], options?: {
+    injectRawCSS(css: string, options?: {
         root?: Document | ShadowRoot;
-    }): GlobalInjectResult;
+    }): RawCSSResult;
+    /**
+     * Get raw CSS text for SSR
+     */
+    getRawCSSText(options?: {
+        root?: Document | ShadowRoot;
+    }): string;
     /**
      * Dispose of a className
      */
@@ -107,11 +114,4 @@ export declare class StyleInjector {
      * 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

@@ -1,7 +1,13 @@
-import { CacheMetrics, KeyframesInfo, KeyframesSteps, RootRegistry, RuleInfo, SheetInfo, StyleInjectorConfig, StyleRule } from './types';
+import { CacheMetrics, KeyframesInfo, KeyframesSteps, RawCSSResult, RootRegistry, RuleInfo, SheetInfo, StyleInjectorConfig, StyleRule } from './types';
 export declare class SheetManager {
     private rootRegistries;
     private config;
+    /** Dedicated style elements for raw CSS per root */
+    private rawStyleElements;
+    /** Tracking for raw CSS blocks per root */
+    private rawCSSBlocks;
+    /** Counter for generating unique raw CSS IDs */
+    private rawCSSCounter;
     constructor(config: StyleInjectorConfig);
     /**
      * Get or create registry for a root (Document or ShadowRoot)
@@ -95,4 +101,22 @@ export declare class SheetManager {
      * Clean up resources for a root
      */
     cleanup(root: Document | ShadowRoot): void;
+    /**
+     * Get or create a dedicated style element for raw CSS
+     * Raw CSS is kept separate from tasty-managed sheets to avoid index conflicts
+     */
+    private getOrCreateRawStyleElement;
+    /**
+     * Inject raw CSS text directly without parsing
+     * Returns a dispose function to remove the injected CSS
+     */
+    injectRawCSS(css: string, root: Document | ShadowRoot): RawCSSResult;
+    /**
+     * Remove a raw CSS block by ID
+     */
+    private disposeRawCSS;
+    /**
+     * Get the raw CSS content for SSR
+     */
+    getRawCSSText(root: Document | ShadowRoot): string;
 }

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

@@ -110,3 +110,16 @@ export interface KeyframesCacheEntry {
     refCount: number;
     info: KeyframesInfo;
 }
+export interface RawCSSInfo {
+    /** Unique identifier for this raw CSS block */
+    id: string;
+    /** The raw CSS text */
+    css: string;
+    /** Start offset in the style element's textContent */
+    startOffset: number;
+    /** End offset in the style element's textContent */
+    endOffset: number;
+}
+export interface RawCSSResult {
+    dispose: () => void;
+}

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

@@ -36,18 +36,6 @@ export interface AtRuleContext {
     rootStates?: string[];
     negatedRootStates?: string[];
 }
-/**
- * Mark that styles have been generated (called by injector on first inject)
- */
-export declare function markStylesGenerated(): void;
-/**
- * Check if styles have been generated
- */
-export declare function hasStylesGenerated(): boolean;
-/**
- * Reset styles generated flag (for testing only)
- */
-export declare function resetStylesGenerated(): void;
 /**
  * Configure global predefined states
  */

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

@@ -0,0 +1,39 @@
+/**
+ * Build-time only module for zero-runtime static site generation.
+ *
+ * Usage:
+ * ```typescript
+ * import { tastyStatic } from '@cube-dev/ui-kit/tasty/static';
+ *
+ * // Returns StaticStyle object (className + styles + toString)
+ * const button = tastyStatic({
+ *   fill: '#blue',
+ *   padding: '2x',
+ * });
+ *
+ * // Extend existing styles
+ * const primaryButton = tastyStatic(button, {
+ *   fill: '#purple',
+ * });
+ *
+ * // Global styles (removed at build time)
+ * tastyStatic('.heading', { preset: 'h1' });
+ *
+ * // Usage in JSX
+ * <div className={button} />           // toString() coercion
+ * <div className={button.className} /> // Explicit
+ * ```
+ *
+ * Requires the Babel plugin to be configured:
+ * ```javascript
+ * // babel.config.js
+ * plugins: [
+ *   ['@cube-dev/ui-kit/tasty/zero/babel', { output: 'public/tasty.css' }]
+ * ]
+ * ```
+ */
+export { tastyStatic } from './tastyStatic';
+export { createStaticStyle, isStaticStyle } from './types';
+export type { StaticStyle } from './types';
+export type { Styles } from '../styles/types';
+export { mergeStyles } from '../utils/mergeStyles';

package/types/tasty/static/tastyStatic.d.ts

@@ -0,0 +1,41 @@
+import { Styles } from '../styles/types';
+import { StaticStyle } from './types';
+/**
+ * Generate styles and return a StaticStyle object.
+ * The object has `className`, `styles`, and `toString()`.
+ *
+ * @example
+ * ```typescript
+ * const button = tastyStatic({
+ *   fill: '#blue',
+ *   padding: '2x',
+ * });
+ * // After build: { className: 'ts3f2a1b', styles: {...}, toString() }
+ *
+ * <div className={button} />  // Works via toString()
+ * ```
+ */
+export declare function tastyStatic(styles: Styles): StaticStyle;
+/**
+ * Extend an existing StaticStyle with additional styles.
+ * Uses mergeStyles() internally for proper nested selector handling.
+ *
+ * @example
+ * ```typescript
+ * const button = tastyStatic({ fill: '#blue' });
+ * const primary = tastyStatic(button, { fill: '#purple' });
+ * // After build: { className: 'ts8c4d2e', styles: {...merged...}, toString() }
+ * ```
+ */
+export declare function tastyStatic(base: StaticStyle, styles: Styles): StaticStyle;
+/**
+ * Generate styles for a specific CSS selector.
+ * The call is completely removed after build transformation.
+ *
+ * @example
+ * ```typescript
+ * tastyStatic('.heading', { preset: 'h1', color: '#primary' });
+ * // After build: (removed)
+ * ```
+ */
+export declare function tastyStatic(selector: string, styles: Styles): void;

package/types/tasty/static/types.d.ts

@@ -0,0 +1,44 @@
+import { Styles } from '../styles/types';
+/**
+ * Static style definition returned by tastyStatic().
+ *
+ * Supports both explicit className access and implicit string coercion via toString().
+ *
+ * @example
+ * ```typescript
+ * const button = tastyStatic({ fill: '#blue' });
+ *
+ * // Both work in JSX:
+ * <div className={button} />           // Uses toString()
+ * <div className={button.className} /> // Explicit
+ *
+ * // Extension:
+ * const primary = tastyStatic(button, { fill: '#purple' });
+ * ```
+ */
+export interface StaticStyle {
+    /**
+     * Generated className(s) for use in JSX.
+     * May contain multiple space-separated class names due to chunking.
+     */
+    className: string;
+    /**
+     * The original (or merged) styles object.
+     * Available for extension via tastyStatic(base, overrides).
+     */
+    styles: Styles;
+    /**
+     * Returns className for implicit string coercion.
+     * Enables `<div className={button} />` syntax.
+     */
+    toString(): string;
+}
+/**
+ * Create a StaticStyle object.
+ * Used internally by the Babel plugin to generate output.
+ */
+export declare function createStaticStyle(className: string, styles: Styles): StaticStyle;
+/**
+ * Type guard to check if a value is a StaticStyle object.
+ */
+export declare function isStaticStyle(value: unknown): value is StaticStyle;