chaincss 2.1.39 → 2.3.0

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

@@ -0,0 +1,57 @@
+/**
+ * Accessibility Intelligence Engine
+ *
+ * Build-time WCAG 2.2 compliance checking. Auto-fixes where possible.
+ * Runs only in build-time and hybrid-static modes. Zero runtime cost.
+ *
+ * Detectors:
+ *   - Contrast ratio (extends design-orchestrator)
+ *   - Minimum font size (12px)
+ *   - Touch target size (44×44px)
+ *   - Missing focus indicators
+ *   - prefers-reduced-motion
+ *   - Hover-only interactions
+ */
+import type { IRRule, IRPass } from './style-ir.js';
+export interface AccessibilityIssue {
+    ruleId: string;
+    selector: string;
+    category: 'contrast' | 'font-size' | 'touch-target' | 'focus' | 'motion' | 'hover-only' | 'color-only';
+    severity: 'error' | 'warning';
+    wcagCriterion: string;
+    message: string;
+    suggestion: string;
+    autoFixable: boolean;
+}
+export interface AccessibilityReport {
+    issues: AccessibilityIssue[];
+    errorCount: number;
+    warningCount: number;
+    passedCount: number;
+    summary: string;
+}
+export declare const accessibilityPass: IRPass;
+export declare function auditAccessibility(rules: IRRule[]): AccessibilityReport;
+export declare function checkRule(rule: IRRule): AccessibilityIssue[];
+export declare const accessibilityEngine: {
+    audit: typeof auditAccessibility;
+    checkRule: typeof checkRule;
+    pass: IRPass;
+    wcag: {
+        MIN_CONTRAST_AA: number;
+        MIN_CONTRAST_AA_LARGE: number;
+        MIN_CONTRAST_AAA: number;
+        MIN_FONT_SIZE: number;
+        MIN_TOUCH_TARGET: number;
+        CRITERIA: {
+            contrast: string;
+            fontSize: string;
+            touchTarget: string;
+            focus: string;
+            motion: string;
+            hoverOnly: string;
+            colorOnly: string;
+        };
+    };
+};
+export default accessibilityEngine;

package/dist/compiler/constraint-solver.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Constraint-Based Styling Engine
+ *
+ * Declare relationships, not values. The solver resolves them to CSS.
+ *
+ * @example
+ *   .constrain('width', '< parent')
+ *   .constrain('height', '= width * 0.5')
+ *   .constrain('sidebar', 'sticky until footer')
+ *   .constrain('columns', '>= 3 when > 768px')
+ */
+import type { IRPass } from './style-ir.js';
+export type ConstraintOperator = '<' | '>' | '<=' | '>=' | '=' | '!=' | '≈';
+export type ConstraintTarget = 'parent' | 'viewport' | 'sibling' | 'self' | string;
+export interface Constraint {
+    property: string;
+    operator: ConstraintOperator;
+    expression: string;
+    target?: ConstraintTarget;
+    condition?: string;
+}
+export interface ResolvedConstraint {
+    constraint: Constraint;
+    cssProperty: string;
+    cssValue: string;
+    method: 'direct' | 'calc' | 'aspect-ratio' | 'container-query' | 'sticky' | 'clamp' | 'custom-property' | 'color-mix';
+    explanation: string;
+}
+/**
+ * Parse a constraint expression into structured form.
+ */
+declare function parseExpression(expr: string): {
+    left: string;
+    operator: string;
+    right: string;
+    isFunction: boolean;
+    functionName?: string;
+    functionArgs?: string[];
+};
+declare function resolveReference(ref: string): string;
+/**
+ * Resolve a single constraint into a CSS property+value.
+ */
+export declare function resolveConstraint(constraint: Constraint, context?: Record<string, string>): ResolvedConstraint;
+/**
+ * Resolve sticky-until constraint.
+ * "sticky until footer" → position: sticky + scroll-driven animation
+ */
+export declare function resolveStickyUntil(selector: string, untilSelector: string): ResolvedConstraint;
+/**
+ * Resolve ">= N when > Xpx" constraints to container queries.
+ */
+export declare function resolveContainerQuery(property: string, operator: string, value: string, condition: string): {
+    atRule: {
+        type: string;
+        query: string;
+        declarations: Array<{
+            property: string;
+            value: string;
+        }>;
+    };
+    explanation: string;
+};
+/**
+ * IR Pass: resolve all constraints in the IR to concrete CSS.
+ */
+export declare const constraintSolverPass: IRPass;
+/**
+ * Parse a chain-style constraint call into the Constraint format.
+ *
+ * @example
+ *   parseConstraint('width', '< parent')
+ *   // => { property: 'width', operator: '<', expression: 'parent' }
+ */
+export declare function parseConstraint(property: string, expression: string): Constraint;
+export declare const constraintSolver: {
+    resolve: typeof resolveConstraint;
+    resolveStickyUntil: typeof resolveStickyUntil;
+    resolveContainerQuery: typeof resolveContainerQuery;
+    parseConstraint: typeof parseConstraint;
+    parseExpression: typeof parseExpression;
+    resolveReference: typeof resolveReference;
+    pass: IRPass;
+};
+export default constraintSolver;

package/dist/compiler/css-if-transpiler.d.ts

@@ -0,0 +1,33 @@
+/**
+ * CSS if() Transpiler
+ * Detects conditional style patterns and emits:
+ *   1. Native CSS if() — Chrome 137+
+ *   2. @supports fallback — Firefox, Safari
+ */
+export interface IfCondition {
+    property: string;
+    variable: string;
+    conditions: Record<string, string | number>;
+    defaultValue: string | number;
+}
+export interface DetectedCondition {
+    property: string;
+    variable: string;
+    conditions: Record<string, string | number>;
+    defaultValue: string | number;
+}
+/**
+ * Detect conditional patterns from _conditions metadata.
+ * When chain.when() branches set the same property to different values,
+ * those can be compiled to CSS if().
+ */
+export declare function detectIfPatterns(styles: Record<string, any>): DetectedCondition[];
+/**
+ * Generate CSS if() output for detected conditions.
+ */
+export declare function emitCSSIf(selector: string, detectedConditions: DetectedCondition[], baseProperties?: Record<string, string | number>): string;
+declare const _default: {
+    detectIfPatterns: typeof detectIfPatterns;
+    emitCSSIf: typeof emitCSSIf;
+};
+export default _default;

package/dist/compiler/design-orchestrator.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Design System Orchestrator
+ *
+ * 1. WCAG Contrast Ratio Checker — validates text/background combos at build time
+ * 2. Contextual Tokens — tokens that auto-flip based on container context
+ * 3. Token Relationship Validator — ensures design tokens are consistent
+ */
+export interface ContrastResult {
+    foreground: string;
+    background: string;
+    ratio: number;
+    passes: {
+        AA: boolean;
+        AALarge: boolean;
+        AAA: boolean;
+        AAALarge: boolean;
+    };
+    suggestion?: string;
+}
+export interface ContrastReport {
+    checks: ContrastResult[];
+    failures: ContrastResult[];
+    warnings: ContrastResult[];
+    passCount: number;
+    failCount: number;
+    summary: string;
+}
+export interface ContextualToken {
+    name: string;
+    default: string;
+    contexts: Record<string, string>;
+}
+export interface TokenContext {
+    name: string;
+    parentSelector?: string;
+    tokens: Record<string, any>;
+}
+/**
+ * Parse CSS color to RGBA components.
+ * Supports: hex, rgb(), rgba(), named colors
+ */
+declare function parseColor(color: string): {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+} | null;
+/**
+ * Calculate WCAG contrast ratio between two colors.
+ * Returns value between 1 (no contrast) and 21 (max contrast).
+ */
+export declare function contrastRatio(foreground: string, background: string): number;
+/**
+ * Check WCAG compliance levels.
+ * AA: 4.5:1 normal, 3:1 large text
+ * AAA: 7:1 normal, 4.5:1 large text
+ */
+export declare function checkContrast(foreground: string, background: string): ContrastResult;
+/**
+ * Run contrast checks across a set of style definitions.
+ */
+export declare function auditContrast(styles: Array<{
+    selector: string;
+    color: string;
+    backgroundColor: string;
+}>): ContrastReport;
+/**
+ * Contextual tokens that auto-resolve based on parent container.
+ *
+ * @example
+ *   const buttonText = contextualToken({
+ *     default: '#1a1a1a',
+ *     contexts: {
+ *       '.dark-section': '#ffffff',
+ *       '.hero': '#ffffff',
+ *     },
+ *   });
+ *
+ *   resolveContextual(buttonText, '.dark-section .my-button')
+ *   // => '#ffffff'
+ */
+export declare function createContextualToken(defaultValue: string, contexts?: Record<string, string>): ContextualToken;
+/**
+ * Resolve a contextual token based on the current selector path.
+ * Matches the most specific context that applies.
+ */
+export declare function resolveContextual(token: ContextualToken, selectorPath: string): string;
+/**
+ * Generate CSS custom property fallback for contextual tokens.
+ *
+ * @example
+ *   generateContextualCSS('button-text', contextualToken)
+ *   // => "
+ *   //   .my-button { --button-text: #1a1a1a; }
+ *   //   .dark-section .my-button { --button-text: #ffffff; }
+ *   // "
+ */
+export declare function generateContextualCSS(propertyName: string, token: ContextualToken, baseSelector: string): string;
+/**
+ * Validate that token references are consistent.
+ * E.g., "primary" should have both foreground and background variants
+ * that contrast well with each other.
+ */
+export declare function validateTokenRelationships(tokens: Record<string, any>, pairs: Array<{
+    foreground: string;
+    background: string;
+    label: string;
+}>): ContrastReport;
+export declare const orchestrator: {
+    contrastRatio: typeof contrastRatio;
+    checkContrast: typeof checkContrast;
+    auditContrast: typeof auditContrast;
+    createContextualToken: typeof createContextualToken;
+    resolveContextual: typeof resolveContextual;
+    generateContextualCSS: typeof generateContextualCSS;
+    validateTokenRelationships: typeof validateTokenRelationships;
+    parseColor: typeof parseColor;
+};
+export default orchestrator;

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

@@ -0,0 +1,73 @@
+/**
+ * Intent-Based API
+ *
+ * The highest-level API — developers declare WHAT they want,
+ * the compiler resolves HOW using all available modules.
+ *
+ * @example
+ *   chain.intent('card')          // → full card component
+ *   chain.intent('center-content') // → flex/grid centering
+ *   chain.intent('button-primary') // → accessible blue button
+ */
+import type { IRPass } from './style-ir.js';
+interface IntentDefinition {
+    /** Human-readable name */
+    name: string;
+    /** Category for organization */
+    category: 'layout' | 'component' | 'semantic' | 'interaction';
+    /** Description */
+    description: string;
+    /** Semantic tokens to apply */
+    semantics?: Array<{
+        category: string;
+        intent: string;
+    }>;
+    /** Direct properties (for simple intents) */
+    properties?: Record<string, string | number>;
+    /** Pseudo-classes */
+    states?: Record<string, Record<string, string | number>>;
+    /** Responsive overrides */
+    responsive?: Record<string, Record<string, string | number>>;
+    /** Accessibility requirements */
+    a11y?: string[];
+}
+/**
+ * Resolve an intent into all its constituent parts.
+ * Calls semantic tokens, properties, states, responsive overrides.
+ */
+export declare function resolveIntent(intentName: string, options?: {
+    theme?: 'light' | 'dark' | 'high-contrast';
+    viewport?: string;
+}): {
+    properties: Record<string, string | number>;
+    states: Record<string, Record<string, string | number>>;
+    responsive: Record<string, Record<string, string | number>>;
+    a11y: string[];
+    description: string;
+} | null;
+/**
+ * Get all available intents.
+ */
+export declare function getAvailableIntents(): string[];
+/**
+ * Get intents by category.
+ */
+export declare function getIntentsByCategory(category: IntentDefinition['category']): string[];
+/**
+ * Get a description of an intent.
+ */
+export declare function getIntentDescription(intentName: string): string | null;
+/**
+ * Intent API IR pass.
+ * Resolves _intent metadata on rules into full component definitions.
+ */
+export declare const intentAPIPass: IRPass;
+export declare const intentAPI: {
+    resolve: typeof resolveIntent;
+    list: typeof getAvailableIntents;
+    byCategory: typeof getIntentsByCategory;
+    description: typeof getIntentDescription;
+    catalog: Record<string, IntentDefinition>;
+    pass: IRPass;
+};
+export default intentAPI;

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

@@ -1,4 +1,5 @@
 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;
@@ -15,11 +16,24 @@ export declare const intent: {
     };
     getCorrections(property: string): ValueCorrection[];
     explain(correction: CorrectionResult): string;
-    getKnownProperties(): 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;
@@ -28,4 +42,8 @@ export declare const validate: (property: string, value: string) => {
     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/layout-intelligence.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Layout Intelligence Engine
+ *
+ * Bidirectional pattern recognition:
+ *   1. EXPAND: Human shorthand → full CSS (via existing macros)
+ *   2. RECOGNIZE: Full CSS → detected pattern (NEW — this module)
+ *   3. COMPRESS: Duplicate patterns → shared intent suggestion
+ *   4. SUGGEST: Diagnostic when verbose CSS could be a macro
+ */
+import type { IRPass } from './style-ir.js';
+export interface LayoutPattern {
+    /** Unique name of the pattern */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** The macro call that generates this pattern */
+    macro: string;
+    /** Example usage */
+    example: string;
+    /** Properties that must match exactly */
+    required: Record<string, string | number>;
+    /** Properties that should be present but can have any value */
+    optional?: string[];
+    /** Minimum number of required matches to trigger recognition */
+    minMatches?: number;
+}
+export interface PatternMatch {
+    pattern: LayoutPattern;
+    ruleId: string;
+    selector: string;
+    matchedProperties: string[];
+    confidence: number;
+}
+export interface PatternReport {
+    matches: PatternMatch[];
+    duplicates: Array<{
+        pattern: string;
+        selectors: string[];
+        count: number;
+    }>;
+    suggestions: Array<{
+        selector: string;
+        suggestion: string;
+        savings: number;
+    }>;
+}
+/**
+ * Layout Intelligence IR pass.
+ * Scans all rules for known layout patterns, generates diagnostics and suggestions.
+ */
+export declare const layoutIntelligencePass: IRPass;
+/**
+ * Analyze a set of declarations and return matching patterns.
+ */
+export declare function recognizeLayout(declarations: Record<string, string | number>): PatternMatch[];
+/**
+ * Get the best macro for a set of declarations.
+ */
+export declare function suggestMacro(declarations: Record<string, string | number>): string | null;
+/**
+ * Get all known layout patterns.
+ */
+export declare function getLayoutPatterns(): LayoutPattern[];
+export declare const layoutIntelligence: {
+    recognize: typeof recognizeLayout;
+    suggestMacro: typeof suggestMacro;
+    getPatterns: typeof getLayoutPatterns;
+    pass: IRPass;
+    patterns: LayoutPattern[];
+};
+export default layoutIntelligence;

package/dist/compiler/pass-manager.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Multi-Pass Optimization Pipeline
+ *
+ * Coordinates all compiler passes in a defined, deterministic order.
+ * Each pass is a pure function: StyleIR → StyleIR.
+ *
+ * Architecture inspired by: LLVM, Babel, SWC, Rust compiler
+ *
+ * Pipeline order (optimized for maximum information gain per pass):
+ *   1. Intent Recovery      — fix typos, add defaults
+ *   2. Unit Resolution       — resolve units, constant fold
+ *   3. Validation            — contrast checks, conflict detection
+ *   4. Specificity Sorting   — order rules by specificity
+ *   5. Dead Elimination      — remove unused selectors
+ *   6. Atomic Extraction     — extract shared properties
+ *   7. Media Query Packing   — group same-query rules
+ *   8. CSS if() Transpiling  — emit native if() + fallback
+ *   9. CSS Compression       — minify output
+ *  10. Diagnostics Export    — collect all pass diagnostics
+ */
+import type { StyleIR, IRPass } from './style-ir.js';
+export type PassName = 'intent-recovery' | 'unit-resolution' | 'validation' | 'specificity-sort' | 'dead-elimination' | 'atomic-extraction' | 'media-query-packing' | 'css-if-transpile' | 'css-compression' | 'diagnostics-export';
+export type PassPriority = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10;
+export interface PassDefinition {
+    name: PassName;
+    priority: PassPriority;
+    description: string;
+    /** The actual transform function */
+    pass: IRPass;
+    /** Dependencies — these passes must run first */
+    requires: PassName[];
+    /** Whether this pass is enabled */
+    enabled: boolean;
+}
+export interface PassResult {
+    name: PassName;
+    duration: number;
+    nodesBefore: number;
+    nodesAfter: number;
+    changes: number;
+    errors: string[];
+}
+export interface PipelineResult {
+    ir: StyleIR;
+    css: string;
+    results: PassResult[];
+    totalDuration: number;
+    summary: string;
+}
+/**
+ * Pass 1: Intent Recovery
+ * Corrects typos, adds defaults for common patterns.
+ * Runs FIRST so all downstream passes see clean data.
+ */
+export declare const intentRecoveryPass: IRPass;
+/**
+ * Pass 2: Unit Resolution
+ * Resolves math expressions, converts units where possible.
+ * Runs early so later passes see resolved values.
+ */
+export declare const unitResolutionPass: IRPass;
+/**
+ * Pass 3: Validation
+ * Runs contrast checks, detects conflicts.
+ */
+export declare const validationPass: IRPass;
+/**
+ * Pass 4: Specificity Sorting
+ * Orders rules by specificity so the cascade is predictable.
+ */
+export declare const specificitySortPass: IRPass;
+/**
+ * Pass 5: Dead Elimination
+ * Removes rules marked as dead.
+ */
+export declare const deadEliminationPass: IRPass;
+/**
+ * Pass 6: Atomic Extraction
+ * Identifies identical declarations across rules and marks them for atomic CSS.
+ */
+export declare const atomicExtractionPass: IRPass;
+/**
+ * Pass 7: Media Query Packing
+ * Groups rules with the same media query together.
+ */
+export declare const mediaQueryPackingPass: IRPass;
+/**
+ * Pass 8: CSS if() Transpile
+ * Detects conditional patterns and emits native CSS if().
+ */
+export declare const cssIfTranspilePass: IRPass;
+/**
+ * Pass 9: CSS Compression
+ * Minifies the IR — shortens values, removes unnecessary data.
+ */
+export declare const cssCompressionPass: IRPass;
+/**
+ * Pass 10: Diagnostics Export
+ * Collects all diagnostics from passes for reporting.
+ */
+export declare const diagnosticsExportPass: IRPass;
+/**
+ * The default pass pipeline — runs all passes in optimal order.
+ */
+export declare const DEFAULT_PIPELINE: PassDefinition[];
+export declare class PassManager {
+    private passes;
+    private results;
+    constructor(passes?: PassDefinition[]);
+    /**
+     * Validate that all pass dependencies are satisfied.
+     */
+    private validateDependencies;
+    /**
+     * Topological sort passes by dependencies.
+     * Passes with no dependencies run first.
+     */
+    private sortByDependencies;
+    /**
+     * Run the full pipeline on an IR.
+     */
+    run(ir: StyleIR): PipelineResult;
+    /**
+     * Get results from the last run.
+     */
+    getResults(): PassResult[];
+    /**
+     * Print a human-readable report of pass results.
+     */
+    report(): string;
+    /**
+     * Add a custom pass to the pipeline.
+     */
+    addPass(pass: PassDefinition): this;
+    /**
+     * Remove a pass by name.
+     */
+    removePass(name: PassName): this;
+    /**
+     * Enable/disable a pass.
+     */
+    setPassEnabled(name: PassName, enabled: boolean): this;
+    /**
+     * Get the list of pass names in execution order.
+     */
+    getPassOrder(): PassName[];
+}
+/**
+ * Run the default pipeline on an IR.
+ */
+export declare function runDefaultPipeline(ir: StyleIR): PipelineResult;
+export declare const passManager: {
+    PassManager: typeof PassManager;
+    runDefaultPipeline: typeof runDefaultPipeline;
+    DEFAULT_PIPELINE: PassDefinition[];
+};
+export default passManager;