@tachui/core 0.7.0-alpha1

package/src/modifiers/responsive/responsive-modifier.ts

@@ -0,0 +1,410 @@
+/**
+ * Responsive Modifier Implementation
+ * 
+ * Core responsive modifier that integrates with the existing tachUI modifier system.
+ * Provides CSS-native media query generation with backward compatibility.
+ */
+
+import { BaseModifier } from '../base'
+import type { ModifierContext } from '../types'
+import type { DOMNode } from '../../runtime/types'
+import {
+  ResponsiveValue,
+  ResponsiveStyleConfig,
+  ResponsiveModifierResult,
+  isResponsiveValue,
+  BreakpointKey
+} from './types'
+import { ResponsiveCSSGenerator, CSSInjector } from './css-generator'
+import { ResponsivePerformanceMonitor } from './performance'
+import { createEffect, isSignal, isComputed } from '../../reactive'
+import { getThemeSignal } from '../../reactive/theme'
+
+/**
+ * Responsive modifier priority (between appearance and interaction)
+ */
+export const RESPONSIVE_MODIFIER_PRIORITY = 250
+
+/**
+ * Core responsive modifier class
+ */
+export class ResponsiveModifier extends BaseModifier<ResponsiveStyleConfig> {
+  readonly type = 'responsive'
+  readonly priority = RESPONSIVE_MODIFIER_PRIORITY
+  private generatedCSS: ResponsiveModifierResult | null = null
+  private elementSelector: string = ''
+  private _config: ResponsiveStyleConfig
+  
+  constructor(config: ResponsiveStyleConfig) {
+    super(config)
+    this._config = config
+  }
+  
+  get config(): ResponsiveStyleConfig {
+    return this._config
+  }
+  
+  /**
+   * Apply responsive styles to the element
+   */
+  apply(node: DOMNode, _context: ModifierContext): DOMNode | undefined {
+    const element = node.element
+    
+    if (!element || !(element instanceof HTMLElement)) {
+      return undefined
+    }
+    
+    // Generate unique selector for this element
+    this.elementSelector = this.generateUniqueSelector(element)
+    element.classList.add(this.getClassFromSelector(this.elementSelector))
+    
+    // Generate responsive CSS
+    this.generateAndInjectCSS()
+    
+    // Set up reactive updates for dynamic responsive values
+    this.setupReactiveUpdates()
+    
+    return undefined // No DOM modifications needed
+  }
+  
+  /**
+   * Generate and inject responsive CSS
+   */
+  private generateAndInjectCSS(): void {
+    const endMeasurement = ResponsivePerformanceMonitor.startMeasurement('css-generation')
+    
+    try {
+      // Always use immediate CSS generation for responsive modifiers
+      // Batching can cause FOUC and layout issues when components need responsive styles immediately
+      const generator = new ResponsiveCSSGenerator({
+        selector: this.elementSelector,
+        generateMinified: process.env.NODE_ENV === 'production',
+        includeComments: process.env.NODE_ENV !== 'production',
+        optimizeOutput: true
+      })
+      
+      this.generatedCSS = generator.generateResponsiveCSS(this.config)
+      
+      // Inject CSS rules into the document immediately
+      if (this.generatedCSS.cssRules.length > 0) {
+        CSSInjector.injectCSS(this.generatedCSS.cssRules)
+      }
+    } finally {
+      endMeasurement()
+    }
+  }
+  
+  /**
+   * Set up reactive updates for dynamic responsive values
+   */
+  private setupReactiveUpdates(): void {
+    // Check if any values are reactive signals
+    const hasReactiveValues = this.hasReactiveValues(this.config)
+    
+    if (hasReactiveValues) {
+      // Create reactive effect to regenerate CSS when values change
+      createEffect(() => {
+        // Track all reactive dependencies by accessing them
+        this.trackReactiveDependencies(this.config)
+        
+        // Re-evaluate config with current signal values
+        const currentConfig = this.resolveReactiveConfig(this.config)
+        
+        // Update CSS if config changed
+        this.updateConfig(currentConfig)
+      })
+    }
+  }
+  
+  /**
+   * Track reactive dependencies by accessing all reactive values
+   */
+  private trackReactiveDependencies(config: ResponsiveStyleConfig): void {
+    // Track theme signal for any Assets that might be present
+    let hasAssets = false
+    
+    for (const [_key, value] of Object.entries(config)) {
+      if (this.isReactiveValue(value)) {
+        if (isSignal(value) || isComputed(value)) {
+          value() // Access to establish dependency tracking
+        } else if (this.isAsset(value)) {
+          hasAssets = true
+          value.resolve() // Access to establish theme dependency tracking
+        }
+      } else if (isResponsiveValue(value)) {
+        for (const [_breakpoint, breakpointValue] of Object.entries(value)) {
+          if (this.isReactiveValue(breakpointValue)) {
+            if (isSignal(breakpointValue) || isComputed(breakpointValue)) {
+              breakpointValue() // Access to establish dependency tracking
+            } else if (this.isAsset(breakpointValue)) {
+              hasAssets = true
+              breakpointValue.resolve() // Access to establish theme dependency tracking
+            }
+          }
+        }
+      }
+    }
+    
+    // If we have Assets, explicitly track the theme signal to ensure theme changes trigger updates
+    if (hasAssets) {
+      const themeSignal = getThemeSignal()
+      themeSignal() // Access theme signal to establish dependency
+    }
+  }
+  
+  /**
+   * Update configuration and regenerate CSS
+   */
+  private updateConfig(newConfig: ResponsiveStyleConfig): void {
+    this._config = newConfig
+    
+    // Clear old CSS rules (if we had a way to track them individually)
+    // For now, we'll rely on CSS override behavior
+    
+    // Generate new CSS
+    this.generateAndInjectCSS()
+  }
+  
+  /**
+   * Generate unique CSS selector for this element
+   */
+  private generateUniqueSelector(_element: HTMLElement): string {
+    const uniqueId = this.generateUniqueId()
+    const className = `tachui-responsive-${uniqueId}`
+    return `.${className}`
+  }
+  
+  /**
+   * Extract class name from CSS selector
+   */
+  private getClassFromSelector(selector: string): string {
+    return selector.replace(/^\./, '') // Remove leading dot
+  }
+  
+  /**
+   * Generate unique ID for CSS class names
+   */
+  private generateUniqueId(): string {
+    return Math.random().toString(36).substr(2, 9)
+  }
+  
+  /**
+   * Check if configuration contains reactive values (signals)
+   */
+  private hasReactiveValues(config: ResponsiveStyleConfig): boolean {
+    for (const value of Object.values(config)) {
+      if (this.isReactiveValue(value)) {
+        return true
+      }
+      
+      if (isResponsiveValue(value)) {
+        for (const breakpointValue of Object.values(value)) {
+          if (this.isReactiveValue(breakpointValue)) {
+            return true
+          }
+        }
+      }
+    }
+    
+    return false
+  }
+  
+  /**
+   * Check if a value is a reactive signal, computed, or Asset
+   */
+  private isReactiveValue(value: any): boolean {
+    // Check for TachUI signals and computed values
+    if (isSignal(value) || isComputed(value)) {
+      return true
+    }
+    
+    // Check for Assets (have a resolve method and are theme-reactive)
+    if (this.isAsset(value)) {
+      return true
+    }
+    
+    return false
+  }
+  
+  /**
+   * Check if a value is an Asset object
+   */
+  private isAsset(value: any): boolean {
+    return (
+      value !== null &&
+      value !== undefined &&
+      typeof value === 'object' &&
+      'resolve' in value &&
+      typeof value.resolve === 'function'
+    )
+  }
+  
+  /**
+   * Resolve configuration with current signal values
+   */
+  private resolveReactiveConfig(config: ResponsiveStyleConfig): ResponsiveStyleConfig {
+    const resolved: ResponsiveStyleConfig = {}
+    
+    for (const [key, value] of Object.entries(config)) {
+      if (this.isReactiveValue(value)) {
+        // Handle different types of reactive values
+        if (isSignal(value) || isComputed(value)) {
+          resolved[key] = value() // Call signal/computed to get current value
+        } else if (this.isAsset(value)) {
+          resolved[key] = value.resolve() // Resolve Asset to current theme value
+        }
+      } else if (isResponsiveValue(value)) {
+        const resolvedBreakpoints: Partial<Record<BreakpointKey, any>> = {}
+        
+        for (const [breakpoint, breakpointValue] of Object.entries(value)) {
+          if (this.isReactiveValue(breakpointValue)) {
+            // Handle different types of reactive values at breakpoint level
+            if (isSignal(breakpointValue) || isComputed(breakpointValue)) {
+              resolvedBreakpoints[breakpoint as BreakpointKey] = breakpointValue()
+            } else if (this.isAsset(breakpointValue)) {
+              resolvedBreakpoints[breakpoint as BreakpointKey] = breakpointValue.resolve()
+            }
+          } else {
+            resolvedBreakpoints[breakpoint as BreakpointKey] = breakpointValue
+          }
+        }
+        
+        resolved[key] = resolvedBreakpoints
+      } else {
+        resolved[key] = value
+      }
+    }
+    
+    return resolved
+  }
+  
+  /**
+   * Get generated CSS information (for debugging)
+   */
+  getGeneratedCSS(): ResponsiveModifierResult | null {
+    return this.generatedCSS
+  }
+  
+  /**
+   * Get configuration (for debugging)
+   */
+  getConfig(): ResponsiveStyleConfig {
+    return this.config
+  }
+}
+
+/**
+ * Factory function to create responsive modifiers
+ */
+export function createResponsiveModifier(config: ResponsiveStyleConfig): ResponsiveModifier {
+  return new ResponsiveModifier(config)
+}
+
+/**
+ * Media query modifier for custom media queries
+ */
+export class MediaQueryModifier extends BaseModifier<{ query: string; styles: Record<string, any> }> {
+  readonly type = 'media-query'
+  readonly priority = RESPONSIVE_MODIFIER_PRIORITY + 1 // Slightly higher than responsive
+  private elementSelector: string = ''
+  
+  constructor(query: string, styles: Record<string, any>) {
+    super({ query, styles })
+  }
+  
+  get query(): string {
+    return this.properties.query
+  }
+  
+  get styles(): Record<string, any> {
+    return this.properties.styles
+  }
+  
+  apply(node: DOMNode, _context: ModifierContext): DOMNode | undefined {
+    const element = node.element
+    
+    if (!element || !(element instanceof HTMLElement)) {
+      return undefined
+    }
+    
+    // Generate unique selector
+    this.elementSelector = this.generateUniqueSelector(element)
+    element.classList.add(this.getClassFromSelector(this.elementSelector))
+    
+    // Generate and inject media query CSS
+    this.generateMediaQueryCSS()
+    
+    return undefined
+  }
+  
+  private generateMediaQueryCSS(): void {
+    const { generateMinified = process.env.NODE_ENV === 'production' } = {}
+    const indent = generateMinified ? '' : '  '
+    const doubleIndent = generateMinified ? '' : '    '
+    const newline = generateMinified ? '' : '\n'
+    const space = generateMinified ? '' : ' '
+    
+    let rule = `@media ${this.query}${space}{${newline}`
+    rule += `${indent}${this.elementSelector}${space}{${newline}`
+    
+    for (const [property, value] of Object.entries(this.styles)) {
+      const cssProperty = property.replace(/[A-Z]/g, match => `-${match.toLowerCase()}`)
+      const cssValue = typeof value === 'number' ? `${value}px` : value.toString()
+      rule += `${doubleIndent}${cssProperty}:${space}${cssValue};${newline}`
+    }
+    
+    rule += `${indent}}${newline}`
+    rule += `}${newline}`
+    
+    CSSInjector.injectCSS([rule])
+  }
+  
+  private generateUniqueSelector(_element: HTMLElement): string {
+    const uniqueId = Math.random().toString(36).substr(2, 9)
+    const className = `tachui-mq-${uniqueId}`
+    return `.${className}`
+  }
+  
+  private getClassFromSelector(selector: string): string {
+    return selector.replace(/^\./, '')
+  }
+}
+
+/**
+ * Factory function to create media query modifiers
+ */
+export function createMediaQueryModifier(query: string, styles: Record<string, any>): MediaQueryModifier {
+  return new MediaQueryModifier(query, styles)
+}
+
+/**
+ * Utility to create responsive property modifier
+ */
+export function createResponsivePropertyModifier<T>(
+  property: string, 
+  value: ResponsiveValue<T>
+): ResponsiveModifier {
+  const config = { [property]: value } as ResponsiveStyleConfig
+  return new ResponsiveModifier(config)
+}
+
+/**
+ * Create a responsive layout modifier
+ */
+export function createResponsiveLayoutModifier(config: {
+  direction?: ResponsiveValue<'row' | 'column' | 'row-reverse' | 'column-reverse'>
+  wrap?: ResponsiveValue<'nowrap' | 'wrap' | 'wrap-reverse'>
+  justify?: ResponsiveValue<'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly'>
+  align?: ResponsiveValue<'flex-start' | 'flex-end' | 'center' | 'stretch' | 'baseline'>
+  gap?: ResponsiveValue<number | string>
+}): ResponsiveModifier {
+  const styleConfig: ResponsiveStyleConfig = {}
+  
+  if (config.direction) styleConfig.flexDirection = config.direction
+  if (config.wrap) styleConfig.flexWrap = config.wrap
+  if (config.justify) styleConfig.justifyContent = config.justify
+  if (config.align) styleConfig.alignItems = config.align
+  if (config.gap) styleConfig.gap = config.gap
+  
+  return new ResponsiveModifier(styleConfig)
+}

package/src/modifiers/responsive/types.ts

@@ -0,0 +1,226 @@
+/**
+ * Responsive Design System Types
+ * 
+ * CSS-Native media query and responsive design type definitions for tachUI.
+ * Provides comprehensive type safety for responsive modifiers while maintaining
+ * backward compatibility with existing modifier system.
+ */
+
+/**
+ * Standard breakpoint identifiers following Tailwind conventions
+ */
+export type BreakpointKey = 'base' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'
+
+/**
+ * Breakpoint configuration mapping breakpoint keys to CSS values
+ */
+export interface BreakpointConfig {
+  base?: string    // Mobile-first base (no media query)
+  sm?: string      // 640px+ (small tablets and large phones)
+  md?: string      // 768px+ (tablets)
+  lg?: string      // 1024px+ (laptops and small desktops)
+  xl?: string      // 1280px+ (large desktops)
+  '2xl'?: string   // 1536px+ (extra large screens)
+}
+
+/**
+ * Default breakpoint values (Tailwind-inspired)
+ */
+export const DEFAULT_BREAKPOINTS: Required<BreakpointConfig> = {
+  base: '0px',      // Mobile-first base
+  sm: '640px',      // Small tablets and large phones
+  md: '768px',      // Tablets
+  lg: '1024px',     // Laptops and small desktops
+  xl: '1280px',     // Large desktops
+  '2xl': '1536px'   // Extra large screens
+} as const
+
+/**
+ * Responsive value type that accepts either a single value or breakpoint-specific values
+ */
+export type ResponsiveValue<T> = T | Partial<Record<BreakpointKey, T>>
+
+/**
+ * CSS property values that can be responsive
+ */
+export type ResponsiveCSSValue = ResponsiveValue<string | number>
+
+/**
+ * Advanced media query configuration for custom responsive behavior
+ */
+export interface MediaQueryConfig {
+  query: string                    // Raw CSS media query
+  styles: Record<string, string | number>  // CSS properties to apply
+}
+
+/**
+ * Responsive modifier configuration combining breakpoints and custom media queries
+ */
+export interface ResponsiveModifierConfig<T = any> {
+  breakpoints?: Partial<Record<BreakpointKey, T>>
+  mediaQueries?: MediaQueryConfig[]
+  fallback?: T  // Fallback value if no conditions match
+}
+
+/**
+ * Responsive layout configuration for common responsive patterns
+ */
+export interface ResponsiveLayoutConfig {
+  direction?: ResponsiveValue<'row' | 'column' | 'row-reverse' | 'column-reverse'>
+  wrap?: ResponsiveValue<'nowrap' | 'wrap' | 'wrap-reverse'>
+  justify?: ResponsiveValue<'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly'>
+  align?: ResponsiveValue<'flex-start' | 'flex-end' | 'center' | 'stretch' | 'baseline'>
+  gap?: ResponsiveValue<number | string>
+}
+
+/**
+ * Responsive typography configuration
+ */
+export interface ResponsiveTypographyConfig {
+  fontSize?: ResponsiveValue<number | string>
+  lineHeight?: ResponsiveValue<number | string>
+  letterSpacing?: ResponsiveValue<number | string>
+  fontWeight?: ResponsiveValue<number | string>
+  textAlign?: ResponsiveValue<'left' | 'center' | 'right' | 'justify'>
+  textTransform?: ResponsiveValue<'none' | 'uppercase' | 'lowercase' | 'capitalize'>
+}
+
+/**
+ * Responsive spacing configuration
+ */
+export interface ResponsiveSpacingConfig {
+  top?: ResponsiveValue<number | string>
+  right?: ResponsiveValue<number | string>
+  bottom?: ResponsiveValue<number | string>
+  left?: ResponsiveValue<number | string>
+  horizontal?: ResponsiveValue<number | string>  // left + right
+  vertical?: ResponsiveValue<number | string>    // top + bottom
+  all?: ResponsiveValue<number | string>         // all sides
+}
+
+/**
+ * Responsive dimension configuration
+ */
+export interface ResponsiveDimensionConfig {
+  width?: ResponsiveValue<number | string>
+  height?: ResponsiveValue<number | string>
+  minWidth?: ResponsiveValue<number | string>
+  maxWidth?: ResponsiveValue<number | string>
+  minHeight?: ResponsiveValue<number | string>
+  maxHeight?: ResponsiveValue<number | string>
+}
+
+/**
+ * Responsive visibility configuration
+ */
+export interface ResponsiveVisibilityConfig {
+  display?: ResponsiveValue<'none' | 'block' | 'inline' | 'inline-block' | 'flex' | 'inline-flex' | 'grid' | 'inline-grid'>
+  visibility?: ResponsiveValue<'visible' | 'hidden' | 'collapse'>
+  opacity?: ResponsiveValue<number>
+}
+
+/**
+ * Comprehensive responsive style configuration
+ */
+export interface ResponsiveStyleConfig extends 
+  ResponsiveLayoutConfig,
+  ResponsiveTypographyConfig,
+  ResponsiveDimensionConfig,
+  ResponsiveVisibilityConfig {
+  
+  // Additional CSS properties that can be responsive
+  backgroundColor?: ResponsiveValue<string>
+  color?: ResponsiveValue<string>
+  border?: ResponsiveValue<string>
+  borderRadius?: ResponsiveValue<number | string>
+  boxShadow?: ResponsiveValue<string>
+  transform?: ResponsiveValue<string>
+  transition?: ResponsiveValue<string>
+  
+  // Spacing
+  padding?: ResponsiveSpacingConfig | ResponsiveValue<number | string>
+  margin?: ResponsiveSpacingConfig | ResponsiveValue<number | string>
+  
+  // Custom CSS properties
+  [key: string]: any
+}
+
+/**
+ * Breakpoint context information for responsive utilities
+ */
+export interface BreakpointContext {
+  current: BreakpointKey
+  width: number
+  height: number
+  isAbove: (breakpoint: BreakpointKey) => boolean
+  isBelow: (breakpoint: BreakpointKey) => boolean
+  isBetween: (min: BreakpointKey, max: BreakpointKey) => boolean
+  matches: (query: string) => boolean
+}
+
+/**
+ * Responsive modifier factory configuration
+ */
+export interface ResponsiveModifierFactoryConfig {
+  breakpoints?: BreakpointConfig
+  generateCSS?: boolean          // Generate CSS media queries vs JavaScript
+  fallbackToJS?: boolean         // Fallback to JavaScript if CSS not supported
+  optimizeOutput?: boolean       // Optimize generated CSS
+  debugMode?: boolean           // Enable responsive debugging
+}
+
+/**
+ * CSS media query generation result
+ */
+export interface GeneratedMediaQuery {
+  breakpoint: BreakpointKey
+  query: string                 // CSS media query string
+  styles: Record<string, string | number>  // CSS properties
+  selector: string              // CSS selector
+}
+
+/**
+ * Responsive modifier application result
+ */
+export interface ResponsiveModifierResult {
+  cssRules: string[]            // Generated CSS rules
+  mediaQueries: GeneratedMediaQuery[]  // Generated media queries
+  fallbackStyles: Record<string, string | number>  // Fallback styles for base
+  hasResponsiveStyles: boolean  // Whether responsive styles were applied
+}
+
+/**
+ * Type guard to check if a value is responsive
+ */
+export function isResponsiveValue<T>(value: ResponsiveValue<T>): value is Partial<Record<BreakpointKey, T>> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value) && 
+         Object.keys(value).some(key => ['base', 'sm', 'md', 'lg', 'xl', '2xl'].includes(key))
+}
+
+/**
+ * Type guard to check if a breakpoint key is valid
+ */
+export function isValidBreakpointKey(key: string): key is BreakpointKey {
+  return ['base', 'sm', 'md', 'lg', 'xl', '2xl'].includes(key)
+}
+
+/**
+ * Utility type to make any property responsive
+ */
+export type MakeResponsive<T> = {
+  [K in keyof T]: ResponsiveValue<T[K]>
+}
+
+/**
+ * Extract responsive properties from a configuration object
+ */
+export type ResponsiveProperties<T> = {
+  [K in keyof T as T[K] extends ResponsiveValue<any> ? K : never]: T[K]
+}
+
+/**
+ * Extract non-responsive properties from a configuration object
+ */
+export type NonResponsiveProperties<T> = {
+  [K in keyof T as T[K] extends ResponsiveValue<any> ? never : K]: T[K]
+}