chaincss 2.2.0 → 2.3.1

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/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/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;

package/dist/compiler/pattern-learner.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Style Pattern Learner
+ *
+ * Observes all styles across a codebase and:
+ *   1. DETECTS repeated patterns by content-hashing style blocks
+ *   2. RANKS by frequency × property count
+ *   3. SUGGESTS extraction as chain.recipe() or intent macros
+ *   4. REPORTS savings (lines eliminated, bundle size reduction)
+ *
+ * This is compiler-assisted design system extraction.
+ */
+import type { IRRule, IRPass } from './style-ir.js';
+export interface StyleFingerprint {
+    /** Content hash of the property set */
+    hash: string;
+    /** Human-readable signature */
+    signature: string;
+    /** Properties and their values */
+    properties: Record<string, string | number>;
+    /** Number of properties */
+    propertyCount: number;
+}
+export interface PatternCluster {
+    /** The fingerprint that defines this cluster */
+    fingerprint: StyleFingerprint;
+    /** All rules that match this pattern */
+    occurrences: Array<{
+        ruleId: string;
+        selector: string;
+        sourceFile?: string;
+        component?: string;
+    }>;
+    /** How many times it appears */
+    frequency: number;
+    /** Across how many files */
+    fileCount: number;
+    /** Importance score (frequency × propertyCount) */
+    score: number;
+    /** Suggested recipe name */
+    suggestedName: string;
+    /** Suggested extraction as recipe */
+    suggestedRecipe: string;
+    /** Estimated savings */
+    savings: {
+        declarations: number;
+        linesEliminated: number;
+        bundleReduction: string;
+    };
+}
+export interface LearningReport {
+    clusters: PatternCluster[];
+    totalPatterns: number;
+    highValuePatterns: PatternCluster[];
+    totalSavings: {
+        declarations: number;
+        estimatedBytes: number;
+    };
+    summary: string;
+}
+/**
+ * Create a content hash from a set of declarations.
+ * Ignores selectors, focuses on the actual style properties.
+ */
+declare function fingerprintDeclarations(declarations: Array<{
+    property: string;
+    value: string | number;
+}>): StyleFingerprint;
+/**
+ * Cluster rules by their style fingerprint.
+ * Only considers rules with a minimum number of declarations.
+ */
+declare function clusterPatterns(rules: IRRule[], options?: {
+    minProperties?: number;
+    minFrequency?: number;
+}): PatternCluster[];
+/**
+ * Generate a full learning report from clustered patterns.
+ */
+declare function generateReport(clusters: PatternCluster[]): LearningReport;
+/**
+ * Pattern Learning IR pass.
+ * Analyzes rules, clusters patterns, and adds diagnostics.
+ */
+export declare const patternLearningPass: IRPass;
+/**
+ * Learn patterns from a set of style rules.
+ */
+export declare function learnPatterns(rules: Array<{
+    selector: string;
+    declarations: Record<string, string | number>;
+    sourceFile?: string;
+}>, options?: {
+    minProperties?: number;
+    minFrequency?: number;
+}): LearningReport;
+/**
+ * Get the top patterns worth extracting.
+ */
+export declare function getExtractionCandidates(rules: Array<{
+    selector: string;
+    declarations: Record<string, string | number>;
+    sourceFile?: string;
+}>, minScore?: number): PatternCluster[];
+export declare const patternLearner: {
+    learn: typeof learnPatterns;
+    extract: typeof getExtractionCandidates;
+    fingerprint: typeof fingerprintDeclarations;
+    cluster: typeof clusterPatterns;
+    report: typeof generateReport;
+    pass: IRPass;
+};
+export default patternLearner;

package/dist/compiler/responsive-inference.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Automatic Responsive Inference Engine
+ *
+ * Detects layout patterns that will break on mobile and suggests fixes.
+ * Positions ChainCSS as a layout advisor, not just a compiler.
+ *
+ * Detection rules:
+ *   - Fixed widths > 768px → suggest min(100%, width)
+ *   - Grid columns > 2 → suggest auto-fit
+ *   - Large font sizes → suggest clamp()
+ *   - Fixed height: 100vh → suggest 100dvh
+ *   - Large padding/gap → suggest responsive reduction
+ *   - Multiple fixed-width columns → suggest auto-fit grid
+ */
+import type { IRPass } from './style-ir.js';
+export interface ResponsiveIssue {
+    ruleId: string;
+    selector: string;
+    property: string;
+    currentValue: string;
+    severity: 'error' | 'warning' | 'info';
+    category: 'overflow' | 'grid' | 'typography' | 'spacing' | 'viewport' | 'columns';
+    message: string;
+    suggestedFix: string;
+    autoFixAvailable: boolean;
+    affectedViewports: string[];
+}
+export interface ResponsiveReport {
+    issues: ResponsiveIssue[];
+    criticalCount: number;
+    warningCount: number;
+    infoCount: number;
+    summary: string;
+}
+/**
+ * Responsive Inference IR pass.
+ * Detects responsive issues and adds diagnostics with suggested fixes.
+ */
+export declare const responsiveInferencePass: IRPass;
+/**
+ * Analyze declarations and return responsive issues.
+ */
+export declare function analyzeResponsive(selector: string, declarations: Record<string, string | number>): ResponsiveIssue[];
+/**
+ * Generate a full responsive report.
+ */
+export declare function generateResponsiveReport(issues: ResponsiveIssue[]): ResponsiveReport;
+/**
+ * Auto-fix a single responsive issue.
+ */
+export declare function autoFixIssue(issue: ResponsiveIssue): string;
+/**
+ * Auto-fix all auto-fixable issues.
+ */
+export declare function autoFixAll(issues: ResponsiveIssue[]): string[];
+export declare const responsiveInference: {
+    analyze: typeof analyzeResponsive;
+    report: typeof generateResponsiveReport;
+    autoFix: typeof autoFixIssue;
+    autoFixAll: typeof autoFixAll;
+    pass: IRPass;
+};
+export default responsiveInference;

package/dist/compiler/semantic-tokens.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Semantic Token System
+ *
+ * Intent-based styling that maps semantic concepts to design tokens.
+ * Wraps the existing token system — both coexist.
+ *
+ * @example
+ *   chain.surface('interactive')  // → maps to background, color, border-radius
+ *   chain.text('primary')         // → maps to color, font-weight
+ *   chain.elevation('floating')   // → maps to box-shadow, z-index
+ *   chain.state('hover')          // → maps to hover pseudo-class
+ *   chain.spacing('comfortable')  // → maps to padding
+ */
+import type { IRPass } from './style-ir.js';
+export type SurfaceIntent = 'interactive' | 'container' | 'overlay' | 'sheet' | 'tooltip' | 'input';
+export type TextIntent = 'primary' | 'secondary' | 'muted' | 'link' | 'inverse' | 'code';
+export type ElevationIntent = 'flat' | 'raised' | 'floating' | 'sticky' | 'overlay' | 'modal';
+export type StateIntent = 'hover' | 'active' | 'focus' | 'disabled' | 'loading' | 'selected';
+export type SpacingIntent = 'none' | 'tight' | 'compact' | 'comfortable' | 'spacious' | 'generous';
+export interface SemanticMapping {
+    properties: Record<string, string | number>;
+    pseudoClass?: string;
+    description: string;
+}
+export interface ThemeContext {
+    mode: 'light' | 'dark' | 'high-contrast';
+    brand?: Record<string, string>;
+    containerContext?: 'light' | 'dark';
+}
+/**
+ * Resolve a semantic intent to concrete CSS properties.
+ * Applies theme overrides based on context.
+ */
+export declare function resolveSemantic(category: 'surface' | 'text' | 'elevation' | 'state' | 'spacing', intent: string, themeContext?: ThemeContext): SemanticMapping | null;
+/**
+ * Get all available intents for a category.
+ */
+export declare function getSemanticIntents(category: 'surface' | 'text' | 'elevation' | 'state' | 'spacing'): string[];
+/**
+ * Get the description of a semantic intent.
+ */
+export declare function getSemanticDescription(category: 'surface' | 'text' | 'elevation' | 'state' | 'spacing', intent: string): string | null;
+/**
+ * Semantic Token IR pass.
+ * Resolves any _semantic metadata on rules into concrete declarations.
+ */
+export declare const semanticTokensPass: IRPass;
+export declare const semanticTokens: {
+    resolve: typeof resolveSemantic;
+    getIntents: typeof getSemanticIntents;
+    getDescription: typeof getSemanticDescription;
+    pass: IRPass;
+    theme: Record<string, Record<string, SemanticMapping>>;
+    darkOverrides: Record<string, Record<string, Partial<Record<string, string | number>>>>;
+    highContrastOverrides: Record<string, Record<string, Partial<Record<string, string | number>>>>;
+};
+export default semanticTokens;