chaincss 2.1.39 → 2.2.0

package/src/compiler/intent-engine.ts

@@ -1,5 +1,7 @@
 // src/compiler/intent-engine.ts
+
 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; }
@@ -13,6 +15,262 @@ const SEMANTIC_INTENTS: Array<{pattern: RegExp; handler: Function; description:
   { pattern: /^(rounded|round)$/i, handler: (v: string, ctx: any) => ({ original: v, property: ctx.property||'border-radius', corrected: '9999px', defaults: { borderRadius: '9999px' }, confidence: 0.8, intent: 'rounded-pill', explanation: '"rounded" -> border-radius: 9999px (pill)' }), description: 'rounded -> pill' },
 ];
 
+
+// ============================================================================
+// Layout Macros — High-level semantic intents
+// These compile complex multi-property layouts from simple intent names
+// ============================================================================
+
+interface LayoutMacro {
+  name: string;
+  description: string;
+  properties: Record<string, string | number>;
+  defaults?: Record<string, string | number>;
+  mediaQueries?: Record<string, Record<string, any>>;
+}
+
+const LAYOUT_MACROS: Record<string, LayoutMacro> = {
+  stickyHeader: {
+    name: 'stickyHeader',
+    description: 'Sticky header with scroll shadow and entrance animation',
+    properties: {
+      position: 'sticky',
+      top: '0',
+      zIndex: '50',
+      backgroundColor: 'var(--header-bg, white)',
+      backdropFilter: 'blur(8px)',
+      borderBottom: '1px solid transparent',
+    },
+    defaults: {
+      '--header-bg': 'white',
+      '--header-shadow': '0 4px 12px rgba(0,0,0,0.1)',
+    },
+    mediaQueries: {
+      '(max-width: 768px)': {
+        padding: '12px 16px',
+      },
+      '(min-width: 769px)': {
+        padding: '16px 32px',
+      },
+    },
+  },
+
+  card: {
+    name: 'card',
+    description: 'Standard card container with hover lift effect',
+    properties: {
+      display: 'flex',
+      flexDirection: 'column',
+      borderRadius: '12px',
+      backgroundColor: 'var(--card-bg, white)',
+      boxShadow: '0 1px 3px rgba(0,0,0,0.12), 0 1px 2px rgba(0,0,0,0.08)',
+      transition: 'box-shadow 0.2s ease, transform 0.2s ease',
+      overflow: 'hidden',
+    },
+    defaults: {
+      '--card-bg': 'white',
+      '--card-hover-shadow': '0 10px 30px rgba(0,0,0,0.15)',
+    },
+    mediaQueries: {
+      '(hover: hover)': {
+        '&:hover': {
+          boxShadow: 'var(--card-hover-shadow)',
+          transform: 'translateY(-2px)',
+        },
+      },
+    },
+  },
+
+  hero: {
+    name: 'hero',
+    description: 'Full-width hero section with centered content',
+    properties: {
+      display: 'flex',
+      flexDirection: 'column',
+      justifyContent: 'center',
+      alignItems: 'center',
+      width: '100%',
+      minHeight: '60vh',
+      padding: '48px 24px',
+      textAlign: 'center',
+    },
+    defaults: {},
+    mediaQueries: {
+      '(max-width: 768px)': {
+        minHeight: '40vh',
+        padding: '32px 16px',
+      },
+    },
+  },
+
+  container: {
+    name: 'container',
+    description: 'Responsive centered container with max-width',
+    properties: {
+      width: '100%',
+      maxWidth: '1200px',
+      marginLeft: 'auto',
+      marginRight: 'auto',
+      paddingLeft: '16px',
+      paddingRight: '16px',
+    },
+    defaults: {},
+    mediaQueries: {
+      '(min-width: 768px)': {
+        paddingLeft: '24px',
+        paddingRight: '24px',
+      },
+      '(min-width: 1024px)': {
+        paddingLeft: '32px',
+        paddingRight: '32px',
+      },
+    },
+  },
+
+  center: {
+    name: 'center',
+    description: 'Absolute centering using flexbox',
+    properties: {
+      display: 'flex',
+      justifyContent: 'center',
+      alignItems: 'center',
+    },
+    defaults: {},
+  },
+
+  gridList: {
+    name: 'gridList',
+    description: 'Responsive grid list with auto-fit columns',
+    properties: {
+      display: 'grid',
+      gridTemplateColumns: 'repeat(auto-fit, minmax(280px, 1fr))',
+      gap: '24px',
+    },
+    defaults: {},
+    mediaQueries: {
+      '(max-width: 640px)': {
+        gridTemplateColumns: '1fr',
+        gap: '16px',
+      },
+    },
+  },
+
+  sidebar: {
+    name: 'sidebar',
+    description: 'Two-column layout: sidebar + main content',
+    properties: {
+      display: 'grid',
+      gridTemplateColumns: '280px 1fr',
+      gap: '32px',
+      minHeight: '100vh',
+    },
+    defaults: {},
+    mediaQueries: {
+      '(max-width: 1024px)': {
+        gridTemplateColumns: '1fr',
+        gap: '24px',
+      },
+    },
+  },
+
+  pill: {
+    name: 'pill',
+    description: 'Pill-shaped element (fully rounded)',
+    properties: {
+      borderRadius: '9999px',
+      padding: '8px 20px',
+      display: 'inline-flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+    },
+    defaults: {},
+  },
+
+  glass: {
+    name: 'glass',
+    description: 'Frosted glass morphism effect',
+    properties: {
+      backgroundColor: 'rgba(255, 255, 255, 0.1)',
+      backdropFilter: 'blur(16px)',
+      border: '1px solid rgba(255, 255, 255, 0.2)',
+      borderRadius: '16px',
+    },
+    defaults: {},
+  },
+
+  truncate: {
+    name: 'truncate',
+    description: 'Single-line text truncation with ellipsis',
+    properties: {
+      overflow: 'hidden',
+      textOverflow: 'ellipsis',
+      whiteSpace: 'nowrap',
+    },
+    defaults: {},
+  },
+
+  srOnly: {
+    name: 'srOnly',
+    description: 'Screen-reader only (visually hidden but accessible)',
+    properties: {
+      position: 'absolute',
+      width: '1px',
+      height: '1px',
+      padding: '0',
+      margin: '-1px',
+      overflow: 'hidden',
+      clip: 'rect(0, 0, 0, 0)',
+      whiteSpace: 'nowrap',
+      borderWidth: '0',
+    },
+    defaults: {},
+  },
+};
+
+// ============================================================================
+// Layout Macro Resolver
+// ============================================================================
+
+function resolveLayoutMacro(name: string): LayoutMacro | null {
+  return LAYOUT_MACROS[name] || null;
+}
+
+function expandLayoutMacro(name: string): Record<string, any> | null {
+  const macro = resolveLayoutMacro(name);
+  if (!macro) return null;
+
+  // Start with properties
+  const result: Record<string, any> = { ...macro.properties };
+  
+  // Merge defaults (CSS custom properties) into the result
+  if (macro.defaults) {
+    Object.assign(result, macro.defaults);
+  }
+
+  // Apply media queries as nested atRules
+  if (macro.mediaQueries) {
+    result.atRules = result.atRules || [];
+    for (const [query, props] of Object.entries(macro.mediaQueries)) {
+      result.atRules.push({
+        type: 'media',
+        query,
+        styles: props,
+      });
+    }
+  }
+
+  return result;
+}
+
+function getAvailableMacros(): string[] {
+  return Object.keys(LAYOUT_MACROS);
+}
+
+function getMacroDescription(name: string): string | null {
+  const macro = resolveLayoutMacro(name);
+  return macro?.description || null;
+}
+
 const VALUE_CORRECTIONS: Record<string, ValueCorrection[]> = {
   'display': [{wrong:'flexbox',correct:'flex',confidence:0.95},{wrong:'inline-flexbox',correct:'inline-flex',confidence:0.95}],
   'position': [{wrong:'abs',correct:'absolute',confidence:0.9},{wrong:'rel',correct:'relative',confidence:0.9}],
@@ -101,12 +359,44 @@ export const intent = {
   },
   getCorrections(property: string): ValueCorrection[] { return VALUE_CORRECTIONS[property] || []; },
   explain(correction: CorrectionResult): string { return correction.explanation; },
-  getKnownProperties(): string[] { return [...KNOWN_PROPERTIES]; },
+  cssIf: { detect: detectIfPatterns, emit: emitCSSIf },
   getIntents() { return SEMANTIC_INTENTS.map(r => ({ pattern: r.pattern.toString(), description: r.description })); },
+  getKnownProperties(): string[] { return [...KNOWN_PROPERTIES]; },
+
+  // Layout Macros
+  macro(name: string): Record<string, any> | null { return expandLayoutMacro(name); },
+  getMacros(): string[] { return getAvailableMacros(); },
+  getMacroDescription(name: string): string | null { return getMacroDescription(name); },
+  hasMacro(name: string): boolean { return name in LAYOUT_MACROS; },
+  /**
+   * 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 {
+    const macro = expandLayoutMacro(name);
+    if (!macro) return null;
+    if (!overrides) return macro;
+    // Deep merge: user overrides win
+    const merged = { ...macro };
+    for (const [key, value] of Object.entries(overrides)) {
+      if (key === 'atRules' && Array.isArray(value) && Array.isArray(merged.atRules)) {
+        merged.atRules = [...merged.atRules, ...value];
+      } else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        merged[key] = { ...(merged[key] || {}), ...value };
+      } else {
+        merged[key] = value;
+      }
+    }
+    return merged;
+  },
 };
 
 export const correct = intent.correct.bind(intent);
 export const heal = intent.heal.bind(intent);
 export const validate = intent.validate.bind(intent);
 export const getIntent = intent.getIntent.bind(intent);
+export const macro = intent.macro.bind(intent);
+export const applyMacro = intent.applyMacro.bind(intent);
+export const getMacros = intent.getMacros.bind(intent);
+export const hasMacro = intent.hasMacro.bind(intent);
 export default intent;

package/src/compiler/scroll-timeline.ts

@@ -0,0 +1,284 @@
+// src/compiler/scroll-timeline.ts
+/**
+ * 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.
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+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;
+}
+
+// ============================================================================
+// Presets — common scroll animations
+// ============================================================================
+
+export const SCROLL_PRESETS: Record<string, ScrollAnimation> = {
+  fadeIn: {
+    selector: '',
+    timeline: { name: 'fade-in', source: 'view', range: 'entry' },
+    keyframes: [
+      { offset: '0%', properties: { opacity: '0', transform: 'translateY(20px)' } },
+      { offset: '100%', properties: { opacity: '1', transform: 'translateY(0)' } },
+    ],
+  },
+  fadeOut: {
+    selector: '',
+    timeline: { name: 'fade-out', source: 'view', range: 'exit' },
+    keyframes: [
+      { offset: '0%', properties: { opacity: '1' } },
+      { offset: '100%', properties: { opacity: '0' } },
+    ],
+  },
+  scaleIn: {
+    selector: '',
+    timeline: { name: 'scale-in', source: 'view', range: 'entry' },
+    keyframes: [
+      { offset: '0%', properties: { opacity: '0', transform: 'scale(0.8)' } },
+      { offset: '100%', properties: { opacity: '1', transform: 'scale(1)' } },
+    ],
+  },
+  slideLeft: {
+    selector: '',
+    timeline: { name: 'slide-left', source: 'view', range: 'entry' },
+    keyframes: [
+      { offset: '0%', properties: { opacity: '0', transform: 'translateX(-40px)' } },
+      { offset: '100%', properties: { opacity: '1', transform: 'translateX(0)' } },
+    ],
+  },
+  slideRight: {
+    selector: '',
+    timeline: { name: 'slide-right', source: 'view', range: 'entry' },
+    keyframes: [
+      { offset: '0%', properties: { opacity: '0', transform: 'translateX(40px)' } },
+      { offset: '100%', properties: { opacity: '1', transform: 'translateX(0)' } },
+    ],
+  },
+  parallax: {
+    selector: '',
+    timeline: { name: 'parallax', source: 'scroll', scroller: 'root' },
+    keyframes: [
+      { offset: '0%', properties: { transform: 'translateY(0)' } },
+      { offset: '100%', properties: { transform: 'translateY(-20%)' } },
+    ],
+  },
+  stickyReveal: {
+    selector: '',
+    timeline: { name: 'sticky-reveal', source: 'view', range: 'contain' },
+    keyframes: [
+      { offset: '0%', properties: { opacity: '0', clipPath: 'inset(0 0 100% 0)' } },
+      { offset: '50%', properties: { opacity: '1', clipPath: 'inset(0 0 0% 0)' } },
+      { offset: '100%', properties: { opacity: '1', clipPath: 'inset(0 0 0% 0)' } },
+    ],
+  },
+};
+
+// ============================================================================
+// Core Compiler
+// ============================================================================
+
+let animCounter = 0;
+
+function generateName(prefix: string): string {
+  return prefix + '-' + (animCounter++).toString(36);
+}
+
+/**
+ * Compile a scroll animation into CSS.
+ * 
+ * Output includes:
+ *   - @keyframes definition
+ *   - animation-timeline property
+ *   - animation-range (for view timelines)
+ *   - @supports fallback for older browsers
+ */
+export function compileScrollAnimation(animation: ScrollAnimation): ScrollTimelineResult {
+  const animName = animation.timeline.name || generateName('scroll-anim');
+  const timelineName = '--' + animName + '-tl';
+
+  let css = '';
+
+  // 1. Define the scroll timeline
+  css += '/* Scroll Timeline: ' + animName + ' */\n';
+  
+  if (animation.timeline.source === 'view') {
+    // view-timeline
+    const range = animation.timeline.range || 'entry';
+    css += animation.selector + ' {\n';
+    css += '  view-timeline-name: ' + timelineName + ';\n';
+    css += '  view-timeline-axis: ' + (animation.timeline.axis || 'block') + ';\n';
+    if (animation.timeline.inset) {
+      const inset = typeof animation.timeline.inset === 'string'
+        ? animation.timeline.inset
+        : animation.timeline.inset.start + ' ' + animation.timeline.inset.end;
+      css += '  view-timeline-inset: ' + inset + ';\n';
+    }
+    css += '}\n\n';
+  } else {
+    // scroll-timeline
+    const scroller = animation.timeline.scroller === 'root' ? 'root' 
+      : animation.timeline.scroller === 'self' ? 'self'
+      : animation.timeline.scroller || 'nearest';
+    css += animation.selector + ' {\n';
+    if (scroller === 'root' || scroller === 'self' || scroller === 'nearest') {
+      css += '  scroll-timeline-name: ' + timelineName + ';\n';
+      css += '  scroll-timeline-axis: ' + (animation.timeline.axis || 'block') + ';\n';
+    }
+    css += '}\n\n';
+  }
+
+  // 2. Define @keyframes
+  css += '@keyframes ' + animName + ' {\n';
+  for (const step of animation.keyframes) {
+    css += '  ' + step.offset + ' {\n';
+    for (const [prop, value] of Object.entries(step.properties)) {
+      const kebabProp = prop.replace(/([A-Z])/g, '-$1').toLowerCase();
+      css += '    ' + kebabProp + ': ' + value + ';\n';
+    }
+    css += '  }\n';
+  }
+  css += '}\n\n';
+
+  // 3. Apply animation to target
+  const targetSelector = animation.selector + ' > *' || animation.selector;
+  css += '/* Apply animation to children */\n';
+  css += targetSelector + ' {\n';
+  css += '  animation: ' + animName + ' linear both;\n';
+  css += '  animation-timeline: ' + timelineName + ';\n';
+  if (animation.timeline.source === 'view') {
+    const range = animation.timeline.range || 'entry';
+    css += '  animation-range: ' + range + ';\n';
+  }
+  if (animation.delay) css += '  animation-delay: ' + animation.delay + ';\n';
+  css += '}\n\n';
+
+  // 4. @supports fallback
+  css += '/* Fallback for browsers without scroll-timeline */\n';
+  css += '@supports not (animation-timeline: scroll()) {\n';
+  css += '  ' + targetSelector + ' {\n';
+  css += '    /* Use JS polyfill: https://github.com/flackr/scroll-timeline */\n';
+  css += '    animation: ' + animName + ' 1s ease both;\n';
+  css += '  }\n';
+  css += '}\n';
+
+  return {
+    css,
+    animationName: animName,
+    timelineName,
+    fallback: '',
+  };
+}
+
+/**
+ * Compile multiple scroll animations for a page.
+ */
+export function compileScrollAnimations(animations: ScrollAnimation[]): string {
+  let css = '/* ============================================================\n';
+  css += '   ChainCSS Scroll-Driven Animations\n';
+  css += '   Generated: ' + new Date().toISOString() + '\n';
+  css += '   ============================================================ */\n\n';
+
+  for (const animation of animations) {
+    const result = compileScrollAnimation(animation);
+    css += result.css;
+  }
+
+  return css;
+}
+
+/**
+ * Create a scroll animation from a preset.
+ */
+export function createScrollAnimation(
+  preset: keyof typeof SCROLL_PRESETS,
+  selector: string,
+  overrides?: Partial<ScrollAnimation>
+): ScrollAnimation {
+  const base = SCROLL_PRESETS[preset];
+  if (!base) throw new Error('Unknown scroll preset: ' + preset);
+
+  return {
+    ...base,
+    selector,
+    timeline: { ...base.timeline, ...overrides?.timeline },
+    keyframes: overrides?.keyframes || base.keyframes,
+    ...overrides,
+  };
+}
+
+/**
+ * Get available scroll animation presets.
+ */
+export function getScrollPresets(): string[] {
+  return Object.keys(SCROLL_PRESETS);
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export const scrollTimeline = {
+  compile: compileScrollAnimation,
+  compileAll: compileScrollAnimations,
+  create: createScrollAnimation,
+  presets: SCROLL_PRESETS,
+  getPresets: getScrollPresets,
+};
+
+export default scrollTimeline;

package/src/index.ts

@@ -162,6 +162,40 @@ export type { BreakpointsMap, ResponsiveStyle } from './compiler/breakpoints.js'
 // ============================================================================
 export const VERSION = '3.0.0';
 
+// ============================================================================
+// Default Export - Keep original chain for backward compatibility
+// ============================================================================
+// ============================================================================
+// 🆕 Design System Orchestrator (v2.3)
+// ============================================================================
+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';
+
+// ============================================================================
+// Default Export - Keep original chain for backward compatibility
+// ============================================================================
+// ============================================================================
+// 🆕 Scroll Timeline Engine (v2.3)
+// ============================================================================
+export {
+  scrollTimeline,
+  compileScrollAnimation,
+  compileScrollAnimations,
+  createScrollAnimation,
+  getScrollPresets,
+  SCROLL_PRESETS,
+} from './compiler/scroll-timeline.js';
+export type { ScrollTimelineConfig, ScrollAnimation, ScrollTimelineResult, KeyframeStep } from './compiler/scroll-timeline.js';
+
 // ============================================================================
 // Default Export - Keep original chain for backward compatibility
 // ============================================================================