chaincss 2.1.39 → 2.3.0

package/src/compiler/responsive-inference.ts

@@ -0,0 +1,415 @@
+// src/compiler/responsive-inference.ts
+/**
+ * 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 { StyleIR, IRRule, IRDeclaration, IRPass } from './style-ir.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+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;
+}
+
+// ============================================================================
+// Detection Rules
+// ============================================================================
+
+const MOBILE_BREAKPOINT = 768;
+const TABLET_BREAKPOINT = 1024;
+const LARGE_FONT_THRESHOLD = 32; // px
+const LARGE_PADDING_THRESHOLD = 48; // px
+const LARGE_GAP_THRESHOLD = 32; // px
+const MAX_GRID_COLUMNS = 2; // warn if more than this
+
+/**
+ * Detect fixed pixel widths that will overflow mobile.
+ */
+function detectFixedWidth(rule: IRRule): ResponsiveIssue[] {
+  const issues: ResponsiveIssue[] = [];
+
+  for (const decl of rule.declarations) {
+    if ((decl.property === 'width' || decl.property === 'max-width') &&
+        typeof decl.value === 'string') {
+      const pxMatch = decl.value.match(/^(\d+(\.\d+)?)px$/);
+      if (pxMatch) {
+        const px = parseFloat(pxMatch[1]);
+        if (px > MOBILE_BREAKPOINT) {
+          issues.push({
+            ruleId: rule.id,
+            selector: rule.selector,
+            property: decl.property,
+            currentValue: decl.value,
+            severity: px > TABLET_BREAKPOINT ? 'error' : 'warning',
+            category: 'overflow',
+            message: 'Fixed ' + decl.property + ': ' + decl.value + ' will overflow on viewports < ' + px + 'px',
+            suggestedFix: decl.property + ': min(100%, ' + decl.value + ');',
+            autoFixAvailable: true,
+            affectedViewports: ['mobile', 'tablet'],
+          });
+        }
+      }
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Detect grid columns that won't fit on mobile.
+ */
+function detectGridColumns(rule: IRRule): ResponsiveIssue[] {
+  const issues: ResponsiveIssue[] = [];
+
+  for (const decl of rule.declarations) {
+    if ((decl.property === 'gridTemplateColumns' || decl.property === 'grid-template-columns') &&
+        typeof decl.value === 'string') {
+      // Count explicit columns: 1fr 1fr 1fr 1fr or 300px 300px 300px
+      const columns = decl.value.split(/\s+/).filter(c =>
+        c.includes('fr') || c.includes('px') || c.includes('%')
+      );
+      const explicitColumns = columns.length;
+
+      if (explicitColumns > MAX_GRID_COLUMNS) {
+        const isFixed = columns.every(c => c.includes('px'));
+        const suggestion = isFixed
+          ? 'repeat(auto-fit, minmax(' + columns[0] + ', 1fr))'
+          : 'repeat(auto-fit, minmax(250px, 1fr))';
+
+        issues.push({
+          ruleId: rule.id,
+          selector: rule.selector,
+          property: decl.property,
+          currentValue: decl.value,
+          severity: explicitColumns >= 4 ? 'error' : 'warning',
+          category: 'grid',
+          message: explicitColumns + ' columns will not fit on mobile screens (≤ ' + MOBILE_BREAKPOINT + 'px)',
+          suggestedFix: 'grid-template-columns: ' + suggestion + ';',
+          autoFixAvailable: true,
+          affectedViewports: ['mobile'],
+        });
+      }
+    }
+
+    // Detect auto-fit without minmax
+    if ((decl.property === 'gridTemplateColumns' || decl.property === 'grid-template-columns') &&
+        typeof decl.value === 'string' &&
+        decl.value.includes('auto-fit') &&
+        !decl.value.includes('minmax')) {
+      issues.push({
+        ruleId: rule.id,
+        selector: rule.selector,
+        property: decl.property,
+        currentValue: decl.value,
+        severity: 'info',
+        category: 'grid',
+        message: 'auto-fit without minmax() may collapse to 0 on empty containers. Consider: repeat(auto-fit, minmax(250px, 1fr))',
+        suggestedFix: 'grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));',
+        autoFixAvailable: true,
+        affectedViewports: ['all'],
+      });
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Detect large font sizes that need responsive scaling.
+ */
+function detectLargeTypography(rule: IRRule): ResponsiveIssue[] {
+  const issues: ResponsiveIssue[] = [];
+
+  for (const decl of rule.declarations) {
+    if ((decl.property === 'fontSize' || decl.property === 'font-size') &&
+        typeof decl.value === 'string') {
+      const pxMatch = decl.value.match(/^(\d+(\.\d+)?)px$/);
+      if (pxMatch) {
+        const px = parseFloat(pxMatch[1]);
+        if (px > LARGE_FONT_THRESHOLD) {
+          const minSize = Math.round(px * 0.5);
+          issues.push({
+            ruleId: rule.id,
+            selector: rule.selector,
+            property: decl.property,
+            currentValue: decl.value,
+            severity: 'warning',
+            category: 'typography',
+            message: 'font-size: ' + decl.value + ' may be too large on mobile. Consider responsive scaling.',
+            suggestedFix: 'font-size: clamp(' + minSize + 'px, ' + Math.round(px / TABLET_BREAKPOINT * 100) + 'vw, ' + px + 'px);',
+            autoFixAvailable: true,
+            affectedViewports: ['mobile', 'tablet'],
+          });
+        }
+      }
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Detect large padding on fixed elements.
+ */
+function detectLargeSpacing(rule: IRRule): ResponsiveIssue[] {
+  const issues: ResponsiveIssue[] = [];
+
+  for (const decl of rule.declarations) {
+    if ((decl.property === 'padding' || decl.property.startsWith('padding')) &&
+        typeof decl.value === 'string') {
+      const pxMatch = decl.value.match(/^(\d+(\.\d+)?)px$/);
+      if (pxMatch) {
+        const px = parseFloat(pxMatch[1]);
+        if (px > LARGE_PADDING_THRESHOLD) {
+          issues.push({
+            ruleId: rule.id,
+            selector: rule.selector,
+            property: decl.property,
+            currentValue: decl.value,
+            severity: 'info',
+            category: 'spacing',
+            message: decl.property + ': ' + decl.value + ' may be excessive on mobile. Consider reducing to ' + Math.round(px * 0.5) + 'px on small screens.',
+            suggestedFix: '@media (max-width: 768px) { ' + rule.selector + ' { ' + decl.property + ': ' + Math.round(px * 0.5) + 'px; } }',
+            autoFixAvailable: true,
+            affectedViewports: ['mobile'],
+          });
+        }
+      }
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Detect height: 100vh that should use dvh.
+ */
+function detectViewportUnits(rule: IRRule): ResponsiveIssue[] {
+  const issues: ResponsiveIssue[] = [];
+
+  for (const decl of rule.declarations) {
+    if ((decl.property === 'height' || decl.property === 'min-height') &&
+        typeof decl.value === 'string' &&
+        decl.value.includes('100vh')) {
+      issues.push({
+        ruleId: rule.id,
+        selector: rule.selector,
+        property: decl.property,
+        currentValue: decl.value,
+        severity: 'warning',
+        category: 'viewport',
+        message: '100vh can cause issues on mobile browsers with dynamic toolbars. Consider 100dvh instead.',
+        suggestedFix: decl.property + ': 100dvh;',
+        autoFixAvailable: true,
+        affectedViewports: ['mobile'],
+      });
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Detect large gaps.
+ */
+function detectLargeGaps(rule: IRRule): ResponsiveIssue[] {
+  const issues: ResponsiveIssue[] = [];
+
+  for (const decl of rule.declarations) {
+    if ((decl.property === 'gap' || decl.property === 'grid-gap') &&
+        typeof decl.value === 'string') {
+      const pxMatch = decl.value.match(/^(\d+(\.\d+)?)px$/);
+      if (pxMatch) {
+        const px = parseFloat(pxMatch[1]);
+        if (px > LARGE_GAP_THRESHOLD) {
+          issues.push({
+            ruleId: rule.id,
+            selector: rule.selector,
+            property: decl.property,
+            currentValue: decl.value,
+            severity: 'info',
+            category: 'spacing',
+            message: 'gap: ' + decl.value + ' may be too large on mobile. Consider reducing to ' + Math.round(px * 0.5) + 'px on small screens.',
+            suggestedFix: '@media (max-width: 768px) { ' + rule.selector + ' { gap: ' + Math.round(px * 0.5) + 'px; } }',
+            autoFixAvailable: true,
+            affectedViewports: ['mobile'],
+          });
+        }
+      }
+    }
+  }
+
+  return issues;
+}
+
+// ============================================================================
+// IR Pass
+// ============================================================================
+
+/**
+ * Responsive Inference IR pass.
+ * Detects responsive issues and adds diagnostics with suggested fixes.
+ */
+export const responsiveInferencePass: IRPass = (ir: StyleIR): StyleIR => {
+  const allIssues: ResponsiveIssue[] = [];
+
+  for (const rule of ir.rules) {
+    if (rule.isDead) continue;
+
+    allIssues.push(...detectFixedWidth(rule));
+    allIssues.push(...detectGridColumns(rule));
+    allIssues.push(...detectLargeTypography(rule));
+    allIssues.push(...detectLargeSpacing(rule));
+    allIssues.push(...detectViewportUnits(rule));
+    allIssues.push(...detectLargeGaps(rule));
+  }
+
+  // Convert issues to IR diagnostics
+  for (const issue of allIssues) {
+    ir.diagnostics.push({
+      id: 'responsive-' + issue.category + '-' + Date.now() + '-' + Math.random().toString(36).slice(2, 6),
+      nodeId: issue.ruleId,
+      severity: issue.severity,
+      message: issue.message,
+      suggestion: issue.suggestedFix,
+      pass: 'responsive-inference',
+    });
+  }
+
+  // Store for reporting
+  ir.meta = ir.meta || {};
+  (ir.meta as any).responsiveIssues = allIssues;
+
+  return ir;
+};
+
+// ============================================================================
+// Standalone API
+// ============================================================================
+
+/**
+ * Analyze declarations and return responsive issues.
+ */
+export function analyzeResponsive(
+  selector: string,
+  declarations: Record<string, string | number>
+): ResponsiveIssue[] {
+  const rule: IRRule = {
+    id: 'temp-responsive',
+    selector,
+    declarations: Object.entries(declarations).map(([prop, value]) => ({
+      id: 'temp-' + prop,
+      property: prop,
+      value,
+      history: [],
+      meta: {},
+    })),
+    pseudoClasses: [],
+    atRules: [],
+    nestedRules: [],
+    conditions: [],
+    isDead: false,
+    specificity: 0,
+    hash: '',
+    source: {},
+    history: [],
+    meta: {},
+  };
+
+  return [
+    ...detectFixedWidth(rule),
+    ...detectGridColumns(rule),
+    ...detectLargeTypography(rule),
+    ...detectLargeSpacing(rule),
+    ...detectViewportUnits(rule),
+    ...detectLargeGaps(rule),
+  ];
+}
+
+/**
+ * Generate a full responsive report.
+ */
+export function generateResponsiveReport(issues: ResponsiveIssue[]): ResponsiveReport {
+  const critical = issues.filter(i => i.severity === 'error');
+  const warnings = issues.filter(i => i.severity === 'warning');
+  const info = issues.filter(i => i.severity === 'info');
+
+  let summary: string;
+  if (issues.length === 0) {
+    summary = '✅ No responsive issues detected.';
+  } else if (critical.length > 0) {
+    summary = '❌ ' + critical.length + ' critical, ' + warnings.length + ' warnings, ' + info.length + ' suggestions.';
+  } else if (warnings.length > 0) {
+    summary = '⚠️ ' + warnings.length + ' warnings, ' + info.length + ' suggestions.';
+  } else {
+    summary = '💡 ' + info.length + ' responsive suggestions.';
+  }
+
+  return {
+    issues,
+    criticalCount: critical.length,
+    warningCount: warnings.length,
+    infoCount: info.length,
+    summary,
+  };
+}
+
+/**
+ * Auto-fix a single responsive issue.
+ */
+export function autoFixIssue(issue: ResponsiveIssue): string {
+  return issue.suggestedFix;
+}
+
+/**
+ * Auto-fix all auto-fixable issues.
+ */
+export function autoFixAll(issues: ResponsiveIssue[]): string[] {
+  return issues
+    .filter(i => i.autoFixAvailable)
+    .map(i => i.suggestedFix);
+}
+
+// ============================================================================
+// Quick API
+// ============================================================================
+
+export const responsiveInference = {
+  analyze: analyzeResponsive,
+  report: generateResponsiveReport,
+  autoFix: autoFixIssue,
+  autoFixAll,
+  pass: responsiveInferencePass,
+};
+
+export default responsiveInference;

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;