@tachui/core 0.7.0-alpha1

package/src/css-classes/index.ts

@@ -0,0 +1,45 @@
+/**
+ * CSS Classes Enhancement - Public API
+ * 
+ * Exports the public API for CSS class integration system.
+ */
+
+// Types
+export type { 
+  CSSClassesProps,
+  CSSClassProcessor,
+  CSSClassConfig,
+  ClassProcessingResult
+} from './types'
+
+// Core Manager
+export { 
+  CSSClassManager,
+  cssClassManager,
+  configureCSSClasses,
+  getCSSClassConfig
+} from './css-class-manager'
+
+// Component Base
+export { ComponentWithCSSClasses } from './component-base'
+
+// Utilities
+export { createCSSClassUtilities } from './utilities'
+
+// DOM Integration
+export type { DOMNodeWithClasses, CSSClassDOMApplicator } from './dom-integration'
+export { 
+  DOMCSSClassApplicator,
+  domCSSClassApplicator,
+  createDOMNodeWithClasses,
+  extractCSSClasses
+} from './dom-integration'
+
+// Enhanced Renderer
+export type { CSSClassRendererMixin } from './enhanced-renderer'
+export {
+  cssClassRendererMixin,
+  enhanceRendererWithCSSClasses,
+  createCSSClassDOMNode,
+  hasCSSClassSupport
+} from './enhanced-renderer'

package/src/css-classes/types.ts

@@ -0,0 +1,73 @@
+/**
+ * CSS Classes Enhancement - Type Definitions
+ * 
+ * Core types for CSS class integration system that enables components
+ * to accept CSS classes from external frameworks (Tailwind, Bootstrap, etc.)
+ */
+
+import type { Signal } from '../reactive/types'
+
+/**
+ * CSS Classes property interface - extended by all component props
+ */
+export interface CSSClassesProps {
+  css?: string | string[] | Signal<string | string[]>
+}
+
+/**
+ * CSS Class processor interface
+ */
+export interface CSSClassProcessor {
+  /**
+   * Process and normalize CSS classes from various input formats
+   */
+  processClasses(input: string | string[] | Signal<string | string[]>): string[]
+  
+  /**
+   * Sanitize class names to be valid CSS identifiers
+   */
+  sanitizeClassName(className: string): string
+  
+  /**
+   * Deduplicate class arrays while preserving order
+   */
+  deduplicateClasses(classes: string[]): string[]
+  
+  /**
+   * Combine tachUI classes with user-provided CSS classes
+   */
+  combineClasses(tachuiClasses: string[], userClasses: string[]): string[]
+}
+
+/**
+ * Configuration for CSS class processing
+ */
+export interface CSSClassConfig {
+  // Enable/disable class sanitization
+  sanitizeClassNames: boolean
+  
+  // Custom sanitization rules
+  sanitizationRules?: {
+    allowNumbers: boolean
+    allowUnderscores: boolean
+    customReplacements: Record<string, string>
+  }
+  
+  // Performance options
+  enableCaching: boolean
+  maxCacheSize: number
+  
+  // Development warnings
+  warnDuplicateClasses: boolean
+  warnInvalidClasses: boolean
+}
+
+/**
+ * Processing result metadata
+ */
+export interface ClassProcessingResult {
+  classes: string[]
+  sanitized: string[]
+  duplicatesRemoved: number
+  invalidClasses: string[]
+}

package/src/css-classes/utilities.ts

@@ -0,0 +1,175 @@
+/**
+ * CSS Classes Enhancement - Utilities
+ * 
+ * Utility functions for CSS class processing and common patterns.
+ */
+
+import { cssClassManager } from './css-class-manager'
+import type { CSSClassesProps } from './types'
+
+/**
+ * Utility functions for CSS class operations
+ */
+export interface CSSClassUtilities {
+  /**
+   * Combine multiple class sources into a single class string
+   */
+  combineClasses(...sources: (string | string[] | undefined)[]): string
+
+  /**
+   * Create conditional classes based on boolean conditions
+   */
+  conditionalClasses(conditions: Record<string, boolean>): string[]
+
+  /**
+   * Merge CSS class props from multiple sources
+   */
+  mergeClassProps(...props: (CSSClassesProps | undefined)[]): CSSClassesProps
+
+  /**
+   * Extract unique classes from a class string
+   */
+  extractClasses(classString: string): string[]
+
+  /**
+   * Validate CSS class names
+   */
+  validateClassNames(classes: string[]): { valid: string[], invalid: string[] }
+}
+
+/**
+ * Create CSS class utilities instance
+ */
+export function createCSSClassUtilities(): CSSClassUtilities {
+  return {
+    combineClasses(...sources: (string | string[] | undefined)[]): string {
+      const allClasses: string[] = []
+      
+      sources.forEach(source => {
+        if (source) {
+          const processed = cssClassManager.processClasses(source)
+          allClasses.push(...processed)
+        }
+      })
+      
+      return cssClassManager.deduplicateClasses(allClasses).join(' ')
+    },
+
+    conditionalClasses(conditions: Record<string, boolean>): string[] {
+      return Object.entries(conditions)
+        .filter(([_, condition]) => condition)
+        .map(([className, _]) => className)
+    },
+
+    mergeClassProps(...props: (CSSClassesProps | undefined)[]): CSSClassesProps {
+      const allClasses: string[] = []
+      
+      props.forEach(prop => {
+        if (prop?.css) {
+          const processed = cssClassManager.processClasses(prop.css)
+          allClasses.push(...processed)
+        }
+      })
+      
+      if (allClasses.length === 0) {
+        return {}
+      }
+      
+      return {
+        css: cssClassManager.deduplicateClasses(allClasses)
+      }
+    },
+
+    extractClasses(classString: string): string[] {
+      return cssClassManager.processClasses(classString)
+    },
+
+    validateClassNames(classes: string[]): { valid: string[], invalid: string[] } {
+      const valid: string[] = []
+      const invalid: string[] = []
+      
+      classes.forEach(className => {
+        const sanitized = cssClassManager.sanitizeClassName(className)
+        if (sanitized === className.toLowerCase()) {
+          valid.push(className)
+        } else {
+          invalid.push(className)
+        }
+      })
+      
+      return { valid, invalid }
+    }
+  }
+}
+
+/**
+ * Default CSS class utilities instance
+ */
+export const cssClassUtils = createCSSClassUtilities()
+
+/**
+ * Common CSS class patterns for popular frameworks
+ */
+export const CSSPatterns = {
+  /**
+   * Tailwind CSS utility patterns
+   */
+  tailwind: {
+    flexCenter: 'flex items-center justify-center',
+    flexBetween: 'flex items-center justify-between',
+    absoluteCenter: 'absolute top-1/2 left-1/2 transform -translate-x-1/2 -translate-y-1/2',
+    srOnly: 'sr-only',
+    card: 'bg-white rounded-lg shadow-md p-6',
+    btn: {
+      primary: 'bg-blue-500 hover:bg-blue-600 text-white px-4 py-2 rounded transition-colors',
+      secondary: 'bg-gray-500 hover:bg-gray-600 text-white px-4 py-2 rounded transition-colors',
+      outline: 'border border-blue-500 text-blue-500 hover:bg-blue-50 px-4 py-2 rounded transition-colors'
+    }
+  },
+
+  /**
+   * Bootstrap component patterns
+   */
+  bootstrap: {
+    flexCenter: 'd-flex align-items-center justify-content-center',
+    flexBetween: 'd-flex align-items-center justify-content-between',
+    srOnly: 'visually-hidden',
+    card: 'card',
+    btn: {
+      primary: 'btn btn-primary',
+      secondary: 'btn btn-secondary',
+      outline: 'btn btn-outline-primary'
+    }
+  }
+}
+
+/**
+ * Framework-specific class builders
+ */
+export const FrameworkBuilders = {
+  /**
+   * Tailwind CSS class builder
+   */
+  tailwind: {
+    spacing: (value: number) => `p-${value}`,
+    margin: (value: number) => `m-${value}`,
+    textSize: (size: 'xs' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl' | '6xl') => `text-${size}`,
+    backgroundColor: (color: string) => `bg-${color}`,
+    textColor: (color: string) => `text-${color}`,
+    rounded: (size: 'none' | 'sm' | 'base' | 'md' | 'lg' | 'xl' | 'full' = 'base') => 
+      size === 'base' ? 'rounded' : `rounded-${size}`
+  },
+
+  /**
+   * Bootstrap class builder
+   */
+  bootstrap: {
+    spacing: (value: 1 | 2 | 3 | 4 | 5) => `p-${value}`,
+    margin: (value: 1 | 2 | 3 | 4 | 5) => `m-${value}`,
+    textSize: (size: 1 | 2 | 3 | 4 | 5 | 6) => `h${size}`,
+    backgroundColor: (color: string) => `bg-${color}`,
+    textColor: (color: string) => `text-${color}`,
+    rounded: (size: 0 | 1 | 2 | 3 | 'circle' | 'pill' = 1) => 
+      typeof size === 'number' ? `rounded-${size}` : `rounded-${size}`
+  }
+}

package/src/debug/index.ts

@@ -0,0 +1,267 @@
+/**
+ * TachUI Debug System
+ * 
+ * Provides visual debugging tools for component hierarchy and layout
+ */
+
+export interface DebugConfig {
+  enabled: boolean
+  showLabels: boolean
+  showBounds: boolean
+  logComponentTree: boolean
+}
+
+class DebugManager {
+  private config: DebugConfig = {
+    enabled: false,
+    showLabels: false,
+    showBounds: false,
+    logComponentTree: false
+  }
+
+  private componentTree: Array<{ label: string; type: string; depth: number }> = []
+
+  /**
+   * Enable debug mode with optional configuration
+   */
+  enable(options: Partial<DebugConfig> = {}): void {
+    this.config = {
+      enabled: true,
+      showLabels: true,
+      showBounds: true,
+      logComponentTree: true,
+      ...options
+    }
+
+    if (this.config.enabled) {
+      this.injectDebugStyles()
+      // Only log in development mode
+      if (typeof import.meta !== 'undefined' && (import.meta as any).env?.DEV) {
+        console.log('🔧 TachUI Debug Mode Enabled')
+      }
+    }
+  }
+
+  /**
+   * Disable debug mode
+   */
+  disable(): void {
+    this.config.enabled = false
+    this.removeDebugStyles()
+    if (typeof import.meta !== 'undefined' && (import.meta as any).env?.DEV) {
+      console.log('🔧 TachUI Debug Mode Disabled')
+    }
+  }
+
+  /**
+   * Check if debug mode is enabled
+   */
+  isEnabled(): boolean {
+    return this.config.enabled
+  }
+
+  /**
+   * Get current debug configuration
+   */
+  getConfig(): DebugConfig {
+    return { ...this.config }
+  }
+
+  /**
+   * Add debug attributes to DOM element
+   */
+  addDebugAttributes(element: HTMLElement, componentType: string, debugLabel?: string): void {
+    if (!this.config.enabled) return
+
+    element.setAttribute('data-tachui-component', componentType)
+    
+    if (debugLabel) {
+      element.setAttribute('data-tachui-label', debugLabel)
+    }
+
+    if (this.config.showLabels || this.config.showBounds) {
+      element.classList.add('tachui-debug')
+    }
+
+    if (this.config.showLabels && debugLabel) {
+      element.classList.add('tachui-debug-labeled')
+    }
+
+    if (this.config.showBounds) {
+      element.classList.add('tachui-debug-bounds')
+    }
+  }
+
+  /**
+   * Log component to tree (for hierarchical debugging)
+   */
+  logComponent(type: string, label?: string, depth: number = 0): void {
+    if (!this.config.enabled || !this.config.logComponentTree) return
+
+    this.componentTree.push({
+      label: label || `<${type}>`,
+      type,
+      depth
+    })
+  }
+
+  /**
+   * Print component tree to console
+   */
+  printComponentTree(): void {
+    if (!this.config.enabled || !this.config.logComponentTree) return
+
+    console.group('🌳 TachUI Component Tree:')
+    this.componentTree.forEach(({ label, type, depth }) => {
+      const indent = '  '.repeat(depth)
+      const icon = this.getComponentIcon(type)
+      console.log(`${indent}${icon} ${type}: "${label}"`)
+    })
+    console.groupEnd()
+    
+    // Clear tree for next render cycle
+    this.componentTree = []
+  }
+
+  /**
+   * Get icon for component type
+   */
+  private getComponentIcon(type: string): string {
+    const icons: Record<string, string> = {
+      VStack: '📚',
+      HStack: '➡️',
+      ZStack: '📑',
+      Button: '🔘',
+      Text: '📝',
+      Image: '🖼️',
+      ScrollView: '📜',
+      List: '📋',
+      Form: '📋',
+      Section: '📁',
+      default: '🧩'
+    }
+    return icons[type] || icons.default
+  }
+
+  /**
+   * Inject debug CSS styles
+   */
+  private injectDebugStyles(): void {
+    if (document.getElementById('tachui-debug-styles')) return
+
+    const styles = `
+      /* TachUI Debug Styles */
+      .tachui-debug {
+        position: relative;
+      }
+
+      .tachui-debug-bounds {
+        outline: 1px dashed rgba(255, 0, 0, 0.3) !important;
+        outline-offset: -1px;
+      }
+
+      .tachui-debug-labeled::before {
+        content: attr(data-tachui-label);
+        position: absolute;
+        top: -1px;
+        left: -1px;
+        background: rgba(255, 0, 0, 0.9);
+        color: white;
+        font-family: 'Monaco', 'Menlo', 'Consolas', monospace;
+        font-size: 10px;
+        font-weight: bold;
+        line-height: 1;
+        padding: 2px 4px;
+        border-radius: 2px;
+        z-index: 9999;
+        pointer-events: none;
+        white-space: nowrap;
+        max-width: 200px;
+        overflow: hidden;
+        text-overflow: ellipsis;
+      }
+
+      .tachui-debug-labeled:hover::before {
+        background: rgba(255, 0, 0, 1);
+        max-width: none;
+        white-space: normal;
+      }
+
+      /* Component type indicators */
+      [data-tachui-component="VStack"] {
+        border-left: 2px solid rgba(0, 255, 0, 0.5) !important;
+      }
+
+      [data-tachui-component="HStack"] {
+        border-top: 2px solid rgba(0, 0, 255, 0.5) !important;
+      }
+
+      [data-tachui-component="Button"] {
+        box-shadow: inset 0 0 0 1px rgba(255, 165, 0, 0.5) !important;
+      }
+    `
+
+    const styleElement = document.createElement('style')
+    styleElement.id = 'tachui-debug-styles'
+    styleElement.textContent = styles
+    document.head.appendChild(styleElement)
+  }
+
+  /**
+   * Remove debug CSS styles
+   */
+  private removeDebugStyles(): void {
+    const styleElement = document.getElementById('tachui-debug-styles')
+    if (styleElement) {
+      styleElement.remove()
+    }
+
+    // Remove debug classes from all elements
+    document.querySelectorAll('.tachui-debug').forEach(el => {
+      el.classList.remove('tachui-debug', 'tachui-debug-labeled', 'tachui-debug-bounds')
+    })
+  }
+}
+
+// Global debug instance
+export const debugManager = new DebugManager()
+
+// Convenience functions
+export const enableDebug = (options?: Partial<DebugConfig>) => debugManager.enable(options)
+export const disableDebug = () => debugManager.disable()
+export const isDebugEnabled = () => debugManager.isEnabled()
+
+// Auto-enable debug mode based on URL parameters
+if (typeof window !== 'undefined') {
+  const urlParams = new URLSearchParams(window.location.search)
+  const debugParam = urlParams.get('debug')
+  
+  if (debugParam === 'true' || debugParam === '1') {
+    // Enable full debug mode
+    debugManager.enable({
+      enabled: true,
+      showLabels: true,
+      showBounds: true,
+      logComponentTree: true
+    })
+    console.log('🔧 TachUI Debug Mode: Enabled via URL parameter (?debug=true)')
+  } else if (debugParam === 'labels') {
+    // Enable only labels
+    debugManager.enable({
+      enabled: true,
+      showLabels: true,
+      showBounds: false,
+      logComponentTree: false
+    })
+    console.log('🔧 TachUI Debug Mode: Labels only (?debug=labels)')
+  } else if (debugParam === 'bounds') {
+    // Enable only bounds
+    debugManager.enable({
+      enabled: true,
+      showLabels: false,
+      showBounds: true,
+      logComponentTree: false
+    })
+    console.log('🔧 TachUI Debug Mode: Bounds only (?debug=bounds)')
+  }
+}