@cube-dev/ui-kit 0.98.9 → 0.99.0

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

@@ -0,0 +1,67 @@
+/**
+ * Tasty Style Rendering Pipeline
+ *
+ * This is the main entrypoint for the new pipeline implementation.
+ * It implements the complete flow from style objects to CSS rules.
+ *
+ * Pipeline stages:
+ * 1. PARSE CONDITIONS - Parse state keys into ConditionNode trees
+ * 2. BUILD EXCLUSIVE CONDITIONS - AND with negation of higher-priority conditions
+ * 3. SIMPLIFY CONDITIONS - Apply boolean algebra, detect contradictions
+ * 4. GROUP BY HANDLER - Collect styles per handler, compute combinations
+ * 5. COMPUTE CSS VALUES - Call handlers to get CSS declarations
+ * 6. MERGE BY VALUE - Merge rules with identical CSS output
+ * 7. MATERIALIZE CSS - Convert conditions to CSS selectors + at-rules
+ */
+import { Styles } from '../styles/types';
+import { CSSRule } from './materialize';
+/**
+ * Matches the old StyleResult interface for backward compatibility
+ */
+export interface StyleResult {
+    selector: string;
+    declarations: string;
+    atRules?: string[];
+    needsClassName?: boolean;
+    rootPrefix?: string;
+}
+/**
+ * Matches the old RenderResult interface for backward compatibility
+ */
+export interface RenderResult {
+    rules: StyleResult[];
+    className?: string;
+}
+export interface PipelineResult {
+    rules: CSSRule[];
+    className?: string;
+}
+/**
+ * Render styles using the new pipeline.
+ *
+ * This is the main entrypoint that implements the complete flow.
+ */
+export declare function renderStylesPipeline(styles?: Styles, className?: string): PipelineResult;
+/**
+ * Clear the pipeline cache (for testing)
+ */
+export declare function clearPipelineCache(): void;
+/**
+ * Check if a key is a CSS selector
+ */
+export declare function isSelector(key: string): boolean;
+/**
+ * Render styles to CSS rules.
+ *
+ * When called without classNameOrSelector, returns RenderResult with needsClassName=true.
+ * When called with a selector/className string, returns StyleResult[] for direct injection.
+ */
+export declare function renderStyles(styles?: Styles): RenderResult;
+export declare function renderStyles(styles: Styles | undefined, classNameOrSelector: string): StyleResult[];
+export type { ConditionNode } from './conditions';
+export { and, or, not, trueCondition, falseCondition } from './conditions';
+export { parseStateKey } from './parseStateKey';
+export { simplifyCondition } from './simplify';
+export { buildExclusiveConditions } from './exclusive';
+export { conditionToCSS } from './materialize';
+export type { CSSRule } from './materialize';

package/types/tasty/pipeline/materialize.d.ts

@@ -0,0 +1,162 @@
+/**
+ * CSS Materialization
+ *
+ * Converts condition trees into CSS selectors and at-rules.
+ * This is the final stage that produces actual CSS output.
+ */
+import { ConditionNode } from './conditions';
+/**
+ * Parsed media condition for structured analysis and combination
+ */
+export interface ParsedMediaCondition {
+    /** Subtype for structured analysis */
+    subtype: 'dimension' | 'feature' | 'type';
+    /** Whether this is a negated condition */
+    negated: boolean;
+    /** The condition part for CSS output (e.g., "(width < 600px)", "print") */
+    condition: string;
+    /** For dimension queries: dimension name */
+    dimension?: 'width' | 'height' | 'inline-size' | 'block-size';
+    /** For dimension queries: lower bound value */
+    lowerBound?: {
+        value: string;
+        valueNumeric: number | null;
+        inclusive: boolean;
+    };
+    /** For dimension queries: upper bound value */
+    upperBound?: {
+        value: string;
+        valueNumeric: number | null;
+        inclusive: boolean;
+    };
+    /** For feature queries: feature name */
+    feature?: string;
+    /** For feature queries: feature value */
+    featureValue?: string;
+    /** For type queries: media type */
+    mediaType?: 'print' | 'screen' | 'all' | 'speech';
+}
+/**
+ * Parsed container condition for structured analysis and combination
+ */
+export interface ParsedContainerCondition {
+    /** Container name (undefined = unnamed/nearest container) */
+    name?: string;
+    /** The condition part (e.g., "(width < 600px)" or "style(--variant: danger)") */
+    condition: string;
+    /** Whether this is a negated condition */
+    negated: boolean;
+    /** Subtype for structured analysis */
+    subtype: 'dimension' | 'style';
+    /** For style queries: property name (without --) */
+    property?: string;
+    /** For style queries: property value (undefined = existence check) */
+    propertyValue?: string;
+}
+/**
+ * Parsed supports condition for structured analysis and combination
+ */
+export interface ParsedSupportsCondition {
+    /** Subtype: 'feature' for property support, 'selector' for selector() support */
+    subtype: 'feature' | 'selector';
+    /** The condition string (e.g., "display: grid" or ":has(*)") */
+    condition: string;
+    /** Whether this is a negated condition */
+    negated: boolean;
+}
+/**
+ * Parsed modifier condition for structured analysis
+ */
+export interface ParsedModifierCondition {
+    /** Attribute name (e.g., 'data-hovered', 'data-size') */
+    attribute: string;
+    /** Value if present (e.g., 'large', 'danger') */
+    value?: string;
+    /** Operator for value matching (default '=') */
+    operator?: '=' | '^=' | '$=' | '*=';
+    /** Whether this is negated (:not(...)) */
+    negated: boolean;
+}
+/**
+ * Parsed pseudo-class condition for structured analysis
+ */
+export interface ParsedPseudoCondition {
+    /** The pseudo-class (e.g., ':hover', ':focus-visible', ':has(> Icon)') */
+    pseudo: string;
+    /** Whether this is negated (:not(...)) */
+    negated: boolean;
+}
+/**
+ * Parsed root condition for structured analysis
+ */
+export interface ParsedRootCondition {
+    /** The selector part (e.g., '[data-theme="dark"]') */
+    selector: string;
+    /** Whether this is negated (:root:not(...)) */
+    negated: boolean;
+}
+/**
+ * A single selector variant (one term in a DNF expression)
+ */
+export interface SelectorVariant {
+    /** Structured modifier conditions */
+    modifierConditions: ParsedModifierCondition[];
+    /** Structured pseudo conditions */
+    pseudoConditions: ParsedPseudoCondition[];
+    /** Structured own conditions (for sub-element states) */
+    ownConditions: (ParsedModifierCondition | ParsedPseudoCondition)[];
+    /** Parsed media conditions for structured combination */
+    mediaConditions: ParsedMediaCondition[];
+    /** Parsed container conditions for structured combination */
+    containerConditions: ParsedContainerCondition[];
+    /** Parsed supports conditions for @supports at-rules */
+    supportsConditions: ParsedSupportsCondition[];
+    /** Structured root conditions */
+    rootConditions: ParsedRootCondition[];
+    /** Whether to wrap in @starting-style */
+    startingStyle: boolean;
+}
+/**
+ * CSS output components extracted from a condition
+ * Supports multiple variants for OR conditions (DNF form)
+ */
+export interface CSSComponents {
+    /** Selector variants - OR means multiple variants, AND means single variant with combined selectors */
+    variants: SelectorVariant[];
+    /** Whether condition is impossible (should skip) */
+    isImpossible: boolean;
+}
+/**
+ * Final CSS rule output
+ */
+export interface CSSRule {
+    /** Single selector or array of selector fragments (for OR conditions) */
+    selector: string | string[];
+    declarations: string;
+    atRules?: string[];
+    rootPrefix?: string;
+}
+/**
+ * Convert a condition tree to CSS components
+ */
+export declare function conditionToCSS(node: ConditionNode): CSSComponents;
+/**
+ * Clear the condition cache (for testing)
+ */
+export declare function clearConditionCache(): void;
+/**
+ * Convert parsed modifier to CSS selector string (for final output)
+ */
+export declare function modifierToCSS(mod: ParsedModifierCondition): string;
+/**
+ * Convert parsed pseudo to CSS selector string (for final output)
+ */
+export declare function pseudoToCSS(pseudo: ParsedPseudoCondition): string;
+/**
+ * Convert parsed root conditions to CSS selector prefix (for final output)
+ */
+export declare function rootConditionsToCSS(roots: ParsedRootCondition[]): string | undefined;
+/**
+ * Build at-rules array from a variant
+ */
+export declare function buildAtRulesFromVariant(variant: SelectorVariant): string[];

package/types/tasty/pipeline/parseStateKey.d.ts

@@ -0,0 +1,20 @@
+/**
+ * State Key Parser
+ *
+ * Parses state notation strings (like 'hovered & !disabled', '@media(w < 768px)')
+ * into ConditionNode trees for processing in the pipeline.
+ */
+import { StateParserContext } from '../states';
+import { ConditionNode } from './conditions';
+export interface ParseStateKeyOptions {
+    context?: StateParserContext;
+    isSubElement?: boolean;
+}
+/**
+ * Parse a state key string into a ConditionNode
+ */
+export declare function parseStateKey(stateKey: string, options?: ParseStateKeyOptions): ConditionNode;
+/**
+ * Clear the parse cache (for testing)
+ */
+export declare function clearParseCache(): void;

package/types/tasty/pipeline/simplify.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Condition Simplification Engine
+ *
+ * Simplifies condition trees by applying boolean algebra rules,
+ * detecting contradictions, merging ranges, and deduplicating terms.
+ *
+ * This is critical for:
+ * 1. Detecting invalid combinations (A & !A → FALSE)
+ * 2. Reducing CSS output size
+ * 3. Producing cleaner selectors
+ */
+import { ConditionNode } from './conditions';
+/**
+ * Simplify a condition tree aggressively.
+ *
+ * This applies all possible simplification rules:
+ * - Boolean algebra (identity, annihilator, idempotent, absorption)
+ * - Contradiction detection (A & !A → FALSE)
+ * - Tautology detection (A | !A → TRUE)
+ * - Range intersection for numeric queries
+ * - Attribute value conflict detection
+ * - Deduplication and sorting
+ */
+export declare function simplifyCondition(node: ConditionNode): ConditionNode;
+/**
+ * Clear the simplify cache (for testing)
+ */
+export declare function clearSimplifyCache(): void;

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

@@ -0,0 +1,17 @@
+/**
+ * Tasty Plugins
+ *
+ * This module exports official tasty plugins that extend the style system.
+ *
+ * @example
+ * ```ts
+ * import { configure } from '@cube-dev/ui-kit';
+ * import { okhslPlugin } from '@cube-dev/ui-kit/tasty/plugins';
+ *
+ * configure({
+ *   plugins: [okhslPlugin()],
+ * });
+ * ```
+ */
+export type { TastyPlugin, TastyPluginFactory } from './types';
+export { okhslPlugin, okhslFunc } from './okhsl-plugin';

package/types/tasty/plugins/okhsl-plugin.d.ts

@@ -0,0 +1,45 @@
+/**
+ * OKHSL Plugin for Tasty
+ *
+ * Converts OKHSL color syntax to RGB notation.
+ * Supports angle units: deg, turn, rad, or unitless (degrees).
+ *
+ * Examples:
+ *   okhsl(240.5 50% 50%)
+ *   okhsl(240.5deg 50% 50%)
+ *   okhsl(0.25turn 50% 50%)
+ *   okhsl(1.57rad 50% 50%)
+ *
+ * Conversion math inlined from @texel/color to avoid external dependencies.
+ */
+import type { StyleDetails } from '../parser/types';
+import type { TastyPluginFactory } from './types';
+/**
+ * The okhsl function handler for tasty parser.
+ * Receives parsed style groups and returns an RGB color string.
+ */
+declare const okhslFunc: (groups: StyleDetails[]) => string;
+/**
+ * OKHSL Plugin for Tasty.
+ *
+ * Adds support for the `okhsl()` color function in tasty styles.
+ *
+ * @example
+ * ```ts
+ * import { configure } from '@cube-dev/ui-kit';
+ * import { okhslPlugin } from '@cube-dev/ui-kit/tasty/plugins';
+ *
+ * configure({
+ *   plugins: [okhslPlugin()],
+ * });
+ *
+ * // Now you can use okhsl in styles:
+ * const Box = tasty({
+ *   styles: {
+ *     fill: 'okhsl(240 50% 50%)',
+ *   },
+ * });
+ * ```
+ */
+export declare const okhslPlugin: TastyPluginFactory;
+export { okhslFunc };

package/types/tasty/plugins/types.d.ts

@@ -0,0 +1,34 @@
+import type { StyleDetails, UnitHandler } from '../parser/types';
+/**
+ * A tasty plugin that extends the style system with custom functions, units, or states.
+ */
+export interface TastyPlugin {
+    /** Unique name for the plugin (used for debugging and conflict detection) */
+    name: string;
+    /** Custom functions that transform parsed style groups into CSS values */
+    funcs?: Record<string, (groups: StyleDetails[]) => string>;
+    /** Custom units that transform numeric values (e.g., `2x` → `calc(2 * var(--gap))`) */
+    units?: Record<string, string | UnitHandler>;
+    /** Custom state aliases (e.g., `'@mobile': '@media(w < 768px)'`) */
+    states?: Record<string, string>;
+}
+/**
+ * A factory function that creates a TastyPlugin.
+ * Can optionally accept configuration options.
+ *
+ * @example
+ * ```ts
+ * // Plugin without options
+ * const okhslPlugin: TastyPluginFactory = () => ({
+ *   name: 'okhsl',
+ *   funcs: { okhsl: okhslFunc },
+ * });
+ *
+ * // Plugin with options
+ * const debugPlugin: TastyPluginFactory<{ verbose: boolean }> = (options) => ({
+ *   name: 'debug',
+ *   funcs: { debug: createDebugFunc(options.verbose) },
+ * });
+ * ```
+ */
+export type TastyPluginFactory<TOptions = void> = TOptions extends void ? () => TastyPlugin : (options: TOptions) => TastyPlugin;

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

@@ -0,0 +1,101 @@
+/**
+ * Advanced State Mapping - Predefined States Management
+ *
+ * This module handles global and local predefined states for the Tasty styling system.
+ * See ADVANCED_STATE_MAPPING.md for full specification.
+ */
+import { Styles } from '../styles/types';
+/**
+ * Parsed advanced state information
+ */
+export interface ParsedAdvancedState {
+    type: 'media' | 'container' | 'root' | 'own' | 'starting' | 'predefined' | 'modifier';
+    condition: string;
+    containerName?: string;
+    raw: string;
+    mediaType?: string;
+}
+/**
+ * Context for state parsing operations
+ */
+export interface StateParserContext {
+    localPredefinedStates: Record<string, string>;
+    globalPredefinedStates: Record<string, string>;
+    isSubElement?: boolean;
+}
+/**
+ * At-rule context for CSS generation
+ */
+export interface AtRuleContext {
+    media?: string[];
+    container?: {
+        name?: string;
+        condition: string;
+    }[];
+    startingStyle?: boolean;
+    rootStates?: string[];
+    negatedRootStates?: string[];
+}
+/**
+ * Configure global predefined states
+ */
+export declare function setGlobalPredefinedStates(states: Record<string, string>): void;
+/**
+ * Get global predefined states
+ */
+export declare function getGlobalPredefinedStates(): Record<string, string>;
+/**
+ * Clear global predefined states (for testing only)
+ */
+export declare function clearGlobalPredefinedStates(): void;
+/**
+ * Extract predefined state references from a string
+ */
+export declare function extractPredefinedStateRefs(value: string): string[];
+/**
+ * Check if a state key is a predefined state reference
+ */
+export declare function isPredefinedStateRef(stateKey: string): boolean;
+/**
+ * Extract local predefined states from a styles object
+ * Local predefined states are top-level keys starting with @ that have string values
+ * and are valid predefined state names (not built-in like @media, @root, etc.)
+ */
+export declare function extractLocalPredefinedStates(styles: Styles): Record<string, string>;
+/**
+ * Create a state parser context from styles
+ */
+export declare function createStateParserContext(styles?: Styles, isSubElement?: boolean): StateParserContext;
+/**
+ * Resolve a predefined state reference to its value
+ * Returns the resolved value or null if not found
+ */
+export declare function resolvePredefinedState(stateKey: string, ctx: StateParserContext): string | null;
+/**
+ * Normalize state key by trimming whitespace and removing trailing/leading operators
+ */
+export declare function normalizeStateKey(stateKey: string): {
+    key: string;
+    warnings: string[];
+};
+/**
+ * Expand dimension shorthands in a condition string
+ * w -> width, h -> height, is -> inline-size, bs -> block-size
+ */
+export declare function expandDimensionShorthands(condition: string): string;
+/**
+ * Convert tasty units in a string (e.g., 40x -> calc(var(--gap) * 40))
+ */
+export declare function expandTastyUnits(value: string): string;
+/**
+ * Parse an advanced state key and return its type and components
+ */
+export declare function parseAdvancedState(stateKey: string, ctx: StateParserContext): ParsedAdvancedState;
+/**
+ * Check if a state key is an advanced state (starts with @)
+ */
+export declare function isAdvancedState(stateKey: string): boolean;
+/**
+ * Detect the type of advanced state from a raw state key
+ */
+export declare function detectAdvancedStateType(stateKey: string): ParsedAdvancedState['type'];

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;

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

@@ -1,6 +1,16 @@
 export declare function fillStyle({ fill }: {
     fill: any;
-}): any[] | "";
+}): "" | {
+    'background-color': any;
+};
 export declare namespace fillStyle {
     var __lookupStyles: string[];
 }
+export declare function svgFillStyle({ svgFill }: {
+    svgFill: any;
+}): "" | {
+    fill: any;
+};
+export declare namespace svgFillStyle {
+    var __lookupStyles: string[];
+}

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

@@ -7,7 +7,9 @@ export declare function marginStyle({ margin, marginBlock, marginInline, marginT
     marginBottom?: string | number | boolean;
     marginLeft?: string | number | boolean;
 }): {
-    [key: string]: string;
+    margin?: undefined;
+} | {
+    margin: string;
 };
 export declare namespace marginStyle {
     var __lookupStyles: string[];

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

@@ -7,7 +7,9 @@ export declare function paddingStyle({ padding, paddingBlock, paddingInline, pad
     paddingBottom?: string | number | boolean;
     paddingLeft?: string | number | boolean;
 }): {
-    [key: string]: string;
+    padding?: undefined;
+} | {
+    padding: string;
 };
 export declare namespace paddingStyle {
     var __lookupStyles: string[];

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

@@ -1,16 +1,8 @@
 export declare function radiusStyle({ radius }: {
     radius: any;
-}): "" | ({
-    '--local-radius': string;
+}): "" | {
     'border-radius': string;
-    $?: undefined;
-    '--context-radius'?: undefined;
-} | {
-    $: string;
-    '--context-radius': string;
-    '--local-radius'?: undefined;
-    'border-radius'?: undefined;
-})[];
+};
 export declare namespace radiusStyle {
     var __lookupStyles: string[];
 }