chaincss 2.1.38 → 2.2.0

package/dist/compiler/intent-engine.d.ts

@@ -0,0 +1,49 @@
+import type { CorrectionResult, HealMode, HealResult, IntentContext } from '../core/types.js';
+import { detectIfPatterns, emitCSSIf } from './css-if-transpiler.js';
+export type { CorrectionResult, HealMode, HealResult, IntentContext };
+interface ValueCorrection {
+    wrong: string;
+    correct: string;
+    confidence: number;
+}
+export declare const intent: {
+    correct(property: string, value: string, context?: IntentContext): CorrectionResult | null;
+    heal(styles: Record<string, any>, mode?: HealMode, context?: IntentContext): HealResult;
+    getIntent(value: string, ctx?: IntentContext): string | null;
+    validate(property: string, value: string): {
+        valid: boolean;
+        suggestion?: string;
+    };
+    getCorrections(property: string): ValueCorrection[];
+    explain(correction: CorrectionResult): string;
+    cssIf: {
+        detect: typeof detectIfPatterns;
+        emit: typeof emitCSSIf;
+    };
+    getIntents(): {
+        pattern: string;
+        description: string;
+    }[];
+    getKnownProperties(): string[];
+    macro(name: string): Record<string, any> | null;
+    getMacros(): string[];
+    getMacroDescription(name: string): string | null;
+    hasMacro(name: string): boolean;
+    /**
+     * Apply a layout macro to an existing styles object.
+     * Merges macro properties with user overrides.
+     */
+    applyMacro(name: string, overrides?: Record<string, any>): Record<string, any> | null;
+};
+export declare const correct: (property: string, value: string, context?: IntentContext) => CorrectionResult | null;
+export declare const heal: (styles: Record<string, any>, mode?: HealMode, context?: IntentContext) => HealResult;
+export declare const validate: (property: string, value: string) => {
+    valid: boolean;
+    suggestion?: string;
+};
+export declare const getIntent: (value: string, ctx?: IntentContext) => string | null;
+export declare const macro: (name: string) => Record<string, any> | null;
+export declare const applyMacro: (name: string, overrides?: Record<string, any>) => Record<string, any> | null;
+export declare const getMacros: () => string[];
+export declare const hasMacro: (name: string) => boolean;
+export default intent;

package/dist/compiler/math-engine.d.ts

@@ -0,0 +1,89 @@
+import type { CSSUnit, CSSMathValue, MathContext, MathResult, FluidTypeConfig } from '../core/types.js';
+export type { CSSUnit, CSSMathValue, MathContext, MathResult, FluidTypeConfig };
+export type MathOp = 'add' | 'subtract' | 'multiply' | 'divide';
+export declare const math: {
+    /**
+     * Add two CSS values with unit resolution.
+     *
+     * @example
+     * math.add('10px', '2rem')                    // → '42px' (with default context)
+     * math.add('10px', '2rem', { rootFontSize: 16 }) // → '42px'
+     * math.add('10px', '2vw')                     // → 'calc(10px + 2vw)'
+     */
+    add(a: string | number, b: string | number, context?: MathContext): MathResult;
+    /**
+     * Subtract two CSS values with unit resolution.
+     */
+    subtract(a: string | number, b: string | number, context?: MathContext): MathResult;
+    /**
+     * Multiply two CSS values with unit resolution.
+     */
+    multiply(a: string | number, b: string | number, context?: MathContext): MathResult;
+    /**
+     * Divide two CSS values with unit resolution.
+     */
+    divide(a: string | number, b: string | number, context?: MathContext): MathResult;
+    /**
+     * Sum multiple CSS values.
+     */
+    sum(...values: (string | number)[]): MathResult;
+    /**
+     * Resolve a CSS value to pixels.
+     */
+    toPx(value: string | number, context?: MathContext): number;
+    /**
+     * Convert between CSS units.
+     */
+    convert(value: string | number, toUnit: CSSUnit, context?: MathContext): MathResult;
+    /**
+     * Create a fluid typography clamp() expression.
+     *
+     * @example
+     * math.fluidType({ minSize: 14, maxSize: 20 })
+     *   // → 'clamp(14px, 0.625vw + 12px, 20px)'
+     * math.fluidType({ minSize: 14, maxSize: 20, unit: 'rem', rootFontSize: 16 })
+     *   // → 'clamp(0.875rem, 0.625vw + 0.75rem, 1.25rem)'
+     */
+    fluidType(config: FluidTypeConfig): MathResult;
+    /**
+     * Scale a value by a factor with unit preservation.
+     */
+    scale(value: string | number, factor: number): MathResult;
+    /**
+     * Clamp a CSS value between min and max.
+     */
+    clampValue(value: string | number, min: string | number, max: string | number, context?: MathContext): MathResult;
+    /**
+     * Parse a CSS value into its numeric and unit parts.
+     */
+    parse(value: string | number): CSSMathValue;
+    /**
+     * Check if two values have compatible units for direct operations.
+     */
+    compatible(a: string | number, b: string | number): boolean;
+    /**
+     * Get the category of a CSS unit.
+     */
+    unitCategory(unit: CSSUnit): string;
+    /**
+     * Create a CSS min() expression.
+     */
+    cssMin(...values: (string | number)[]): string;
+    /**
+     * Create a CSS max() expression.
+     */
+    cssMax(...values: (string | number)[]): string;
+    /**
+     * Format a number with specified precision.
+     */
+    precision(value: number, decimals?: number): string;
+};
+export declare const add: (a: string | number, b: string | number, context?: MathContext) => MathResult;
+export declare const subtract: (a: string | number, b: string | number, context?: MathContext) => MathResult;
+export declare const multiply: (a: string | number, b: string | number, context?: MathContext) => MathResult;
+export declare const divide: (a: string | number, b: string | number, context?: MathContext) => MathResult;
+export declare const fluidType: (config: FluidTypeConfig) => MathResult;
+export declare const convert: (value: string | number, toUnit: CSSUnit, context?: MathContext) => MathResult;
+export declare const toPx: (value: string | number, context?: MathContext) => number;
+export declare const scale: (value: string | number, factor: number) => MathResult;
+export default math;

package/dist/compiler/scroll-timeline.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Scroll-Driven Animations Engine
+ *
+ * Compiles timeline-based animation descriptions into:
+ *   1. Native CSS scroll-timeline / view-timeline (Chromium 115+)
+ *   2. @supports fallback with JavaScript polyfill hint
+ *
+ * API inspiration: GSAP's ScrollTrigger, but compiles to 0kb JS.
+ */
+export interface ScrollTimelineConfig {
+    /** Name of the timeline */
+    name: string;
+    /** What drives the timeline */
+    source: 'scroll' | 'view';
+    /** The scrollable element (default: nearest scrollable ancestor) */
+    scroller?: 'nearest' | 'root' | 'self' | string;
+    /** Scroll axis */
+    axis?: 'block' | 'inline' | 'x' | 'y';
+    /** For view timelines: when does the element enter/exit */
+    inset?: string | {
+        start: string;
+        end: string;
+    };
+    /** Timeline range (for view timelines) */
+    range?: 'cover' | 'contain' | 'entry' | 'exit' | 'entry-crossing' | 'exit-crossing' | string;
+}
+export interface KeyframeStep {
+    /** Percentage or keyword (e.g., '0%', 'from', 'to') */
+    offset: string;
+    /** CSS properties at this keyframe */
+    properties: Record<string, string | number>;
+    /** Easing for this segment */
+    easing?: string;
+}
+export interface ScrollAnimation {
+    /** Selector to animate */
+    selector: string;
+    /** Timeline configuration */
+    timeline: ScrollTimelineConfig;
+    /** Keyframes */
+    keyframes: KeyframeStep[];
+    /** Animation duration (maps to timeline range) */
+    duration?: string;
+    /** Fill mode */
+    fill?: 'none' | 'forwards' | 'backwards' | 'both';
+    /** Iteration count */
+    iterations?: number | 'infinite';
+    /** Delay before starting */
+    delay?: string;
+}
+export interface ScrollTimelineResult {
+    /** Native CSS for scroll-driven animation */
+    css: string;
+    /** The @keyframes name generated */
+    animationName: string;
+    /** The timeline name generated */
+    timelineName: string;
+    /** Fallback CSS for browsers without scroll-timeline */
+    fallback: string;
+}
+export declare const SCROLL_PRESETS: Record<string, ScrollAnimation>;
+/**
+ * Compile a scroll animation into CSS.
+ *
+ * Output includes:
+ *   - @keyframes definition
+ *   - animation-timeline property
+ *   - animation-range (for view timelines)
+ *   - @supports fallback for older browsers
+ */
+export declare function compileScrollAnimation(animation: ScrollAnimation): ScrollTimelineResult;
+/**
+ * Compile multiple scroll animations for a page.
+ */
+export declare function compileScrollAnimations(animations: ScrollAnimation[]): string;
+/**
+ * Create a scroll animation from a preset.
+ */
+export declare function createScrollAnimation(preset: keyof typeof SCROLL_PRESETS, selector: string, overrides?: Partial<ScrollAnimation>): ScrollAnimation;
+/**
+ * Get available scroll animation presets.
+ */
+export declare function getScrollPresets(): string[];
+export declare const scrollTimeline: {
+    compile: typeof compileScrollAnimation;
+    compileAll: typeof compileScrollAnimations;
+    create: typeof createScrollAnimation;
+    presets: Record<string, ScrollAnimation>;
+    getPresets: typeof getScrollPresets;
+};
+export default scrollTimeline;

package/dist/compiler/style-graph.d.ts

@@ -0,0 +1,30 @@
+import type { StyleDefinition, StyleGraph, StyleGraphNode, StyleGraphEdge, GraphCompileOptions, GraphCompileResult } from '../core/types.js';
+export type { StyleGraph, StyleGraphNode, StyleGraphEdge, GraphCompileOptions, GraphCompileResult };
+export declare class StyleGraphCompiler {
+    private options;
+    constructor(options?: GraphCompileOptions);
+    /**
+     * Compile a set of style definitions through the graph compiler.
+     */
+    compile(styles: Record<string, StyleDefinition>): GraphCompileResult;
+    /**
+     * Analyze a style graph without generating CSS.
+     */
+    analyze(styles: Record<string, StyleDefinition>): StyleGraph;
+    /**
+     * Get optimization statistics for a graph.
+     */
+    getStats(graph: StyleGraph): {
+        totalNodes: number;
+        deadNodes: number;
+        mergedGroups: number;
+        averageSpecificity: number;
+        deepestDependencyChain: number;
+    };
+    /**
+     * Update options.
+     */
+    configure(options: Partial<GraphCompileOptions>): void;
+}
+export declare function compileGraph(styles: Record<string, StyleDefinition>, options?: GraphCompileOptions): GraphCompileResult;
+export default StyleGraphCompiler;

package/dist/core/compiler.d.ts

@@ -1,5 +1,6 @@
 import type { ChainCSSConfig, CompileResult, StyleDefinition } from './types.js';
 import { AtomicOptimizer } from '../compiler/atomic-optimizer.js';
+import type { GraphCompileOptions } from '../compiler/style-graph.js';
 export declare class ChainCSSCompiler {
     private config;
     private prefixer;
@@ -18,6 +19,17 @@ export declare class ChainCSSCompiler {
     private compileQueue;
     private lruList;
     constructor(config: ChainCSSConfig);
+    /**
+   * Compile using the style graph compiler for advanced optimizations.
+   *
+   * @example
+   * const result = compiler.compileWithGraph(styles, {
+   *   eliminateDead: true,
+   *   knownSelectors: ['.header', '.footer'],
+   *   mergeIdentical: true
+   * });
+   */
+    compileWithGraph(styles: Record<string, import('./types.js').StyleDefinition>, options?: GraphCompileOptions): import('./types.js').GraphCompileResult;
     hasStyles(): boolean;
     private processStyleObject;
     private addToCache;

package/dist/core/types.d.ts

@@ -199,3 +199,148 @@ export declare function isStyleDefinition(value: any): value is StyleDefinition;
 export declare function isAtRule(value: any): value is AtRule;
 export declare function isAtomicClass(value: any): value is AtomicClass;
 export declare function isCompileResult(value: any): value is CompileResult;
+export type CSSUnit = 'px' | 'rem' | 'em' | '%' | 'vw' | 'vh' | 'vmin' | 'vmax' | 'ch' | 'ex' | 'cm' | 'mm' | 'in' | 'pt' | 'pc' | 'deg' | 'rad' | 'turn' | 'grad' | 's' | 'ms' | 'dpi' | 'dpcm' | 'dppx';
+export interface CSSMathValue {
+    value: number;
+    unit: CSSUnit;
+}
+export interface MathContext {
+    rootFontSize?: number;
+    viewportWidth?: number;
+    viewportHeight?: number;
+    parentFontSize?: number;
+    dpi?: number;
+    elementWidth?: number;
+    elementHeight?: number;
+}
+export interface MathResult {
+    value: number;
+    unit: CSSUnit | 'calc' | 'mixed';
+    expression: string;
+    resolved: CSSMathValue | null;
+    explanations: string[];
+    toString(): string;
+    toCalc(): string;
+}
+export interface FluidTypeConfig {
+    minSize: number;
+    maxSize: number;
+    minWidth?: number;
+    maxWidth?: number;
+    unit?: 'px' | 'rem';
+    rootFontSize?: number;
+}
+export interface IntentRule {
+    input: string | RegExp;
+    output: string | ((match: RegExpMatchArray) => string);
+    defaults?: Record<string, string | number>;
+    confidence: number;
+    description: string;
+}
+export interface CorrectionResult {
+    original: string;
+    property: string;
+    corrected: string;
+    defaults: Record<string, string | number>;
+    confidence: number;
+    intent: string;
+    explanation: string;
+}
+export interface IntentContext {
+    property?: string;
+    value?: string;
+    selector?: string;
+    parentStyles?: Record<string, any>;
+    mediaContext?: string;
+    themeContext?: string;
+}
+export type HealMode = 'strict' | 'dev' | 'smart';
+export interface HealResult {
+    fixed: Record<string, any>;
+    corrections: CorrectionResult[];
+    warnings: string[];
+    mode: HealMode;
+}
+export interface StyleGraphNode {
+    id: string;
+    selector: string;
+    properties: Record<string, string | number>;
+    specificity: number;
+    dependencies: string[];
+    dependents: string[];
+    mediaQuery?: string;
+    isDead: boolean;
+    hash: string;
+    sourceComponent?: string;
+}
+export interface StyleGraphEdge {
+    from: string;
+    to: string;
+    type: 'extends' | 'overrides' | 'references';
+}
+export interface StyleGraph {
+    nodes: Map<string, StyleGraphNode>;
+    edges: StyleGraphEdge[];
+    rootNodes: string[];
+    leafNodes: string[];
+}
+export interface GraphCompileOptions {
+    eliminateDead?: boolean;
+    knownSelectors?: string[];
+    mergeIdentical?: boolean;
+    mergeThreshold?: number;
+    sortOutput?: 'specificity' | 'source-order' | 'topological';
+    verbose?: boolean;
+}
+export interface GraphCompileResult extends CompileResult {
+    graph: StyleGraph;
+    eliminatedDead: number;
+    mergedRules: number;
+    optimizationTime: number;
+    preOptimizationSize: number;
+    postOptimizationSize: number;
+}
+export type DiagnosticSeverity = 'error' | 'warning' | 'info' | 'hint';
+export interface StyleDiagnostic {
+    property: string;
+    value?: string;
+    selector?: string;
+    severity: DiagnosticSeverity;
+    message: string;
+    suggestion?: string;
+    code?: string;
+    source?: string;
+    range?: {
+        startLine: number;
+        startColumn: number;
+        endLine: number;
+        endColumn: number;
+    };
+}
+export interface StyleAnalysis {
+    diagnostics: StyleDiagnostic[];
+    conflicts: StyleDiagnostic[];
+    breakpoints: BreakpointConfig[];
+    unusedSelectors: string[];
+    deadStyles: string[];
+    duplicationWarnings: StyleDiagnostic[];
+    optimizationSuggestions: StyleDiagnostic[];
+    stats: {
+        totalProperties: number;
+        totalSelectors: number;
+        shorthandOpportunities: number;
+        animationSuggestions: number;
+        responsiveIssues: number;
+    };
+}
+export interface BreakpointInference {
+    selector: string;
+    property: string;
+    currentValue: string;
+    suggestedBreakpoint: string;
+    suggestedValue: string;
+    reason: string;
+}
+export declare function isMathResult(value: any): value is MathResult;
+export declare function isCorrectionResult(value: any): value is CorrectionResult;
+export declare function isGraphCompileResult(value: any): value is GraphCompileResult;

package/dist/index.d.ts

@@ -40,6 +40,10 @@ export type { Chain } from './compiler/Chain.js';
 export type { AnimationConfig, KeyframeDefinition } from './compiler/animations.js';
 export type { BreakpointsMap, ResponsiveStyle } from './compiler/breakpoints.js';
 export declare const VERSION = "3.0.0";
+export { orchestrator, contrastRatio, checkContrast, auditContrast, createContextualToken, resolveContextual, generateContextualCSS, validateTokenRelationships, } from './compiler/design-orchestrator.js';
+export type { ContrastResult, ContrastReport, ContextualToken, TokenContext } from './compiler/design-orchestrator.js';
+export { scrollTimeline, compileScrollAnimation, compileScrollAnimations, createScrollAnimation, getScrollPresets, SCROLL_PRESETS, } from './compiler/scroll-timeline.js';
+export type { ScrollTimelineConfig, ScrollAnimation, ScrollTimelineResult, KeyframeStep } from './compiler/scroll-timeline.js';
 import { chain } from './compiler/Chain.js';
 export default chain;
 export type { Properties as CSSProperties } from 'csstype';
@@ -55,3 +59,11 @@ export type ResponsiveValue<T> = T | {
 };
 export type StyleWithTokens<T = any> = T | ((tokens: DesignTokens) => T);
 import { DesignTokens } from './compiler/tokens.js';
+export { math, add, subtract, multiply, divide, fluidType, convert, toPx, scale } from './compiler/math-engine.js';
+export type { CSSUnit, CSSMathValue, MathContext, MathResult, FluidTypeConfig } from './compiler/math-engine.js';
+export { intent, correct, heal, validate as validateValue, getIntent } from './compiler/intent-engine.js';
+export type { CorrectionResult, HealMode, HealResult, IntentContext } from './compiler/intent-engine.js';
+export { StyleGraphCompiler, compileGraph } from './compiler/style-graph.js';
+export type { StyleGraph, StyleGraphNode, StyleGraphEdge, GraphCompileOptions, GraphCompileResult } from './compiler/style-graph.js';
+export { StyleAnalyzer, analyze as analyzeStyle } from './compiler/analyzer.js';
+export type { StyleDiagnostic, StyleAnalysis, BreakpointInference, DiagnosticSeverity } from './compiler/analyzer.js';