@tachui/core 0.7.0-alpha1

package/src/developer-experience/enhanced-types.ts

@@ -0,0 +1,427 @@
+/**
+ * Enhanced TypeScript Type Definitions (Phase Maroon Week 2)
+ *
+ * Provides stronger type safety, better intellisense, and improved
+ * developer experience through enhanced TypeScript definitions.
+ */
+
+import type { Asset } from '../assets/Asset'
+import type { Signal } from '../reactive/types'
+import type { ComponentInstance } from '../runtime/types'
+
+// =============================================================================
+// ENHANCED COMPONENT TYPES
+// =============================================================================
+
+/**
+ * Strict component props with validation
+ */
+export type StrictComponentProps<T = {}> = {
+  readonly [K in keyof T]: T[K]
+} & {
+  readonly children?: ComponentChildren
+  readonly key?: string | number
+  readonly ref?: ComponentRef<any>
+}
+
+/**
+ * Component children with strict typing
+ */
+export type ComponentChildren =
+  | ComponentInstance
+  | ComponentInstance[]
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | Signal<any>
+  | (() => any)
+
+/**
+ * Component ref with type safety
+ */
+export interface ComponentRef<T = HTMLElement> {
+  readonly current: T | null
+}
+
+/**
+ * Enhanced component factory with strict typing
+ */
+export type StrictComponentFactory<T extends StrictComponentProps = StrictComponentProps> = (
+  props: T
+) => ComponentInstance & {
+  readonly props: T
+  readonly type: string
+  readonly modifiers: readonly any[]
+}
+
+// =============================================================================
+// ENHANCED MODIFIER TYPES
+// =============================================================================
+
+/**
+ * Reactive-aware CSS value types
+ */
+export type CSSValue<T = string | number> = T | Signal<T>
+
+/**
+ * Enhanced color types with asset support
+ */
+export type ColorValue =
+  | string // hex, rgb, named colors
+  | Asset // theme-aware color asset
+  | Signal<string | Asset>
+
+/**
+ * Enhanced size types
+ */
+export type SizeValue =
+  | number // pixels
+  | string // CSS units (px, %, em, rem, vw, vh, etc.)
+  | 'auto'
+  | 'min-content'
+  | 'max-content'
+  | 'fit-content'
+  | Signal<number | string>
+
+/**
+ * Enhanced spacing types with semantic values
+ */
+export type SpacingValue =
+  | number
+  | 'xs' // 4px
+  | 'sm' // 8px
+  | 'md' // 12px
+  | 'lg' // 16px
+  | 'xl' // 24px
+  | 'xxl' // 32px
+  | Signal<number | string>
+
+/**
+ * Enhanced border types
+ */
+export interface EnhancedBorderProps {
+  width?: CSSValue<number>
+  style?: CSSValue<
+    'solid' | 'dashed' | 'dotted' | 'double' | 'groove' | 'ridge' | 'inset' | 'outset' | 'none'
+  >
+  color?: ColorValue
+  radius?: CSSValue<number>
+}
+
+/**
+ * Enhanced shadow types
+ */
+export interface EnhancedShadowProps {
+  x?: CSSValue<number>
+  y?: CSSValue<number>
+  blur?: CSSValue<number>
+  spread?: CSSValue<number>
+  color?: ColorValue
+  inset?: CSSValue<boolean>
+}
+
+/**
+ * Enhanced typography types with system font support
+ */
+export interface EnhancedTypographyProps {
+  size?: CSSValue<number | string>
+  weight?: CSSValue<
+    | '100'
+    | '200'
+    | '300'
+    | '400'
+    | '500'
+    | '600'
+    | '700'
+    | '800'
+    | '900'
+    | 'normal'
+    | 'bold'
+    | 'bolder'
+    | 'lighter'
+  >
+  family?: CSSValue<string | 'system' | 'serif' | 'sans-serif' | 'monospace'>
+  style?: CSSValue<'normal' | 'italic' | 'oblique'>
+  variant?: CSSValue<'normal' | 'small-caps'>
+  decoration?: CSSValue<'none' | 'underline' | 'overline' | 'line-through'>
+  align?: CSSValue<'left' | 'center' | 'right' | 'justify' | 'start' | 'end'>
+  transform?: CSSValue<'none' | 'uppercase' | 'lowercase' | 'capitalize'>
+  lineHeight?: CSSValue<number | string>
+  letterSpacing?: CSSValue<number | string>
+}
+
+// =============================================================================
+// ENHANCED MODIFIER BUILDER TYPES
+// =============================================================================
+
+/**
+ * Enhanced modifier builder with strict return types
+ */
+export interface EnhancedModifierBuilder<T extends ComponentInstance> {
+  // Layout modifiers with enhanced types
+  frame(width: SizeValue, height: SizeValue): EnhancedModifierBuilder<T>
+  frame(options: {
+    width?: SizeValue
+    height?: SizeValue
+    minWidth?: SizeValue
+    maxWidth?: SizeValue
+    minHeight?: SizeValue
+    maxHeight?: SizeValue
+  }): EnhancedModifierBuilder<T>
+
+  // Enhanced size modifiers
+  size(options: {
+    width?: SizeValue
+    height?: SizeValue
+    minWidth?: SizeValue
+    maxWidth?: SizeValue
+    minHeight?: SizeValue
+    maxHeight?: SizeValue
+  }): EnhancedModifierBuilder<T>
+  width(value: SizeValue): EnhancedModifierBuilder<T>
+  height(value: SizeValue): EnhancedModifierBuilder<T>
+  minWidth(value: SizeValue): EnhancedModifierBuilder<T>
+  maxWidth(value: SizeValue): EnhancedModifierBuilder<T>
+  minHeight(value: SizeValue): EnhancedModifierBuilder<T>
+  maxHeight(value: SizeValue): EnhancedModifierBuilder<T>
+
+  // Enhanced padding with all SwiftUI functions
+  padding(value: SpacingValue): EnhancedModifierBuilder<T>
+  padding(options: {
+    all?: SpacingValue
+    horizontal?: SpacingValue
+    vertical?: SpacingValue
+    top?: SpacingValue
+    right?: SpacingValue
+    bottom?: SpacingValue
+    left?: SpacingValue
+    leading?: SpacingValue // SwiftUI-style
+    trailing?: SpacingValue // SwiftUI-style
+  }): EnhancedModifierBuilder<T>
+  paddingTop(value: SpacingValue): EnhancedModifierBuilder<T>
+  paddingBottom(value: SpacingValue): EnhancedModifierBuilder<T>
+  paddingLeft(value: SpacingValue): EnhancedModifierBuilder<T>
+  paddingRight(value: SpacingValue): EnhancedModifierBuilder<T>
+  paddingLeading(value: SpacingValue): EnhancedModifierBuilder<T>
+  paddingTrailing(value: SpacingValue): EnhancedModifierBuilder<T>
+  paddingHorizontal(value: SpacingValue): EnhancedModifierBuilder<T>
+  paddingVertical(value: SpacingValue): EnhancedModifierBuilder<T>
+
+  // Enhanced appearance modifiers
+  foregroundColor(color: ColorValue): EnhancedModifierBuilder<T>
+  backgroundColor(color: ColorValue): EnhancedModifierBuilder<T>
+  opacity(value: CSSValue<number>): EnhancedModifierBuilder<T>
+  cornerRadius(value: CSSValue<number>): EnhancedModifierBuilder<T>
+
+  // Enhanced typography
+  font(props: EnhancedTypographyProps): EnhancedModifierBuilder<T>
+  fontSize(value: CSSValue<number | string>): EnhancedModifierBuilder<T>
+  fontWeight(value: EnhancedTypographyProps['weight']): EnhancedModifierBuilder<T>
+  fontFamily(value: EnhancedTypographyProps['family']): EnhancedModifierBuilder<T>
+  textAlign(value: EnhancedTypographyProps['align']): EnhancedModifierBuilder<T>
+
+  // Enhanced borders and shadows
+  border(props: EnhancedBorderProps): EnhancedModifierBuilder<T>
+  border(
+    width: number,
+    color?: ColorValue,
+    style?: EnhancedBorderProps['style']
+  ): EnhancedModifierBuilder<T>
+  shadow(props: EnhancedShadowProps): EnhancedModifierBuilder<T>
+  dropShadow(x?: number, y?: number, blur?: number, color?: ColorValue): EnhancedModifierBuilder<T>
+
+  // Enhanced interaction
+  onTap<E extends Event = MouseEvent>(handler: (event: E) => void): EnhancedModifierBuilder<T>
+  onHover(handler: (isHovered: boolean, event: MouseEvent) => void): EnhancedModifierBuilder<T>
+  onFocus(handler: (isFocused: boolean, event: FocusEvent) => void): EnhancedModifierBuilder<T>
+  disabled(value?: CSSValue<boolean>): EnhancedModifierBuilder<T>
+
+  // Enhanced animation
+  transition(
+    property?: string,
+    duration?: number,
+    easing?: string,
+    delay?: number
+  ): EnhancedModifierBuilder<T>
+  animation(
+    keyframes: Record<string, Record<string, string>>,
+    duration?: number,
+    easing?: string
+  ): EnhancedModifierBuilder<T>
+
+  // Build with strict return type
+  build(): T & {
+    readonly modifiers: readonly any[]
+  }
+}
+
+// =============================================================================
+// ENHANCED REACTIVE TYPES
+// =============================================================================
+
+/**
+ * Enhanced signal with better type inference
+ */
+export interface EnhancedSignal<T> extends Signal<T> {
+  (): T
+  readonly value: T // Read-only access without calling
+  readonly name?: string // Debug name
+  readonly version: number // Change tracking
+}
+
+/**
+ * Enhanced signal factory
+ */
+export interface EnhancedSignalFactory {
+  <T>(initialValue: T, name?: string): [EnhancedSignal<T>, (value: T | ((prev: T) => T)) => void]
+  <T = undefined>(
+    name?: string
+  ): [EnhancedSignal<T | undefined>, (value: T | ((prev: T | undefined) => T)) => void]
+}
+
+/**
+ * Enhanced computed with dependency tracking
+ */
+export interface EnhancedComputed<T> {
+  (): T
+  readonly value: T
+  readonly dependencies: readonly EnhancedSignal<any>[]
+  readonly name?: string
+}
+
+/**
+ * Type-safe effect with cleanup
+ */
+export interface TypedEffect {
+  <T extends readonly EnhancedSignal<any>[]>(
+    dependencies: T,
+    effect: (
+      ...values: { [K in keyof T]: T[K] extends EnhancedSignal<infer U> ? U : never }
+    ) => undefined | (() => void)
+  ): () => void
+
+  (effect: () => undefined | (() => void)): () => void
+}
+
+// =============================================================================
+// ENHANCED COMPONENT-SPECIFIC TYPES
+// =============================================================================
+
+/**
+ * Enhanced Text component props
+ */
+export interface EnhancedTextProps extends StrictComponentProps {
+  readonly children: string | Signal<string> | (() => string)
+  readonly numberOfLines?: number
+  readonly truncate?: boolean | 'start' | 'middle' | 'end'
+  readonly selectable?: boolean
+}
+
+/**
+ * Enhanced Button component props
+ */
+export interface EnhancedButtonProps extends StrictComponentProps {
+  readonly children: ComponentChildren
+  readonly variant?: 'filled' | 'outlined' | 'text' | 'destructive'
+  readonly size?: 'small' | 'medium' | 'large'
+  readonly loading?: boolean | Signal<boolean>
+  readonly disabled?: boolean | Signal<boolean>
+  readonly onPress?: (event: MouseEvent) => void | Promise<void>
+  readonly onLongPress?: (event: MouseEvent) => void
+  readonly hapticFeedback?: boolean
+}
+
+/**
+ * Enhanced layout component props
+ */
+export interface EnhancedLayoutProps extends StrictComponentProps {
+  readonly children: ComponentChildren
+  readonly spacing?: SpacingValue
+  readonly alignment?: 'start' | 'center' | 'end' | 'stretch'
+  readonly distribution?:
+    | 'start'
+    | 'center'
+    | 'end'
+    | 'space-between'
+    | 'space-around'
+    | 'space-evenly'
+}
+
+// =============================================================================
+// UTILITY TYPES FOR BETTER INTELLISENSE
+// =============================================================================
+
+/**
+ * Extract component props from factory
+ */
+export type ComponentProps<T> = T extends StrictComponentFactory<infer P> ? P : never
+
+/**
+ * Make all properties reactive-aware
+ */
+export type Reactive<T> = {
+  [K in keyof T]: T[K] | Signal<T[K]>
+}
+
+/**
+ * Deep readonly for immutable props
+ */
+export type DeepReadonly<T> = {
+  readonly [K in keyof T]: T[K] extends object ? DeepReadonly<T[K]> : T[K]
+}
+
+/**
+ * Type-safe event handlers
+ */
+export type EventHandler<T extends Event> = (event: T) => void | Promise<void>
+
+/**
+ * Component instance with enhanced type information
+ */
+export interface EnhancedComponentInstance extends ComponentInstance {
+  readonly displayName?: string
+  readonly debugInfo?: {
+    readonly createdAt: number
+    readonly renderCount: number
+    readonly lastRenderTime: number
+  }
+}
+
+// =============================================================================
+// DEVELOPMENT MODE TYPES
+// =============================================================================
+
+/**
+ * Development mode configuration
+ */
+export interface DevelopmentConfig {
+  readonly enableWarnings: boolean
+  readonly enablePerformanceTracking: boolean
+  readonly enableComponentTree: boolean
+  readonly enableHotReload: boolean
+  readonly strictMode: boolean
+}
+
+/**
+ * Component development metadata
+ */
+export interface ComponentDevMetadata {
+  readonly name: string
+  readonly file?: string
+  readonly line?: number
+  readonly props: Record<string, any>
+  readonly state: Record<string, any>
+  readonly renderTime?: number
+  readonly updateCount: number
+}
+
+// =============================================================================
+// EXPORTS FOR PUBLIC API
+// =============================================================================
+
+/**
+ * Main enhanced types export (simplified for build compatibility)
+ */
+export type TachUIEnhancedTypes = {}

package/src/developer-experience/index.ts

@@ -0,0 +1,220 @@
+/**
+ * Developer Experience Enhancement Package (Phase Maroon Week 2)
+ *
+ * Provides enhanced error messages, better TypeScript types, and improved
+ * developer experience for the TachUI framework.
+ */
+
+// Enhanced error system
+import { DeveloperErrorFactory } from './enhanced-errors'
+
+export type { EnhancedTachUIError } from './enhanced-errors'
+export {
+  DeveloperErrorFactory,
+  DeveloperWarnings,
+  TypeValidation,
+} from './enhanced-errors'
+
+// Enhanced TypeScript types
+export type {
+  // Enhanced modifier types
+  ColorValue,
+  ComponentChildren,
+  ComponentDevMetadata,
+  // Utility types
+  ComponentProps,
+  ComponentRef,
+  CSSValue,
+  DeepReadonly,
+  // Development types
+  DevelopmentConfig,
+  EnhancedBorderProps,
+  EnhancedButtonProps,
+  EnhancedComponentInstance,
+  EnhancedComputed,
+  EnhancedLayoutProps,
+  EnhancedModifierBuilder,
+  EnhancedShadowProps,
+  // Enhanced reactive types
+  EnhancedSignal,
+  EnhancedSignalFactory,
+  // Enhanced component-specific types
+  EnhancedTextProps,
+  EnhancedTypographyProps,
+  EventHandler,
+  Reactive,
+  SizeValue,
+  SpacingValue,
+  StrictComponentFactory,
+  // Component types
+  StrictComponentProps,
+  TachUIEnhancedTypes,
+  TypedEffect,
+} from './enhanced-types'
+
+/**
+ * Initialize enhanced developer experience
+ */
+export function initializeDeveloperExperience(
+  options: {
+    enhancedErrors?: boolean
+    performanceWarnings?: boolean
+    accessibilityWarnings?: boolean
+    deprecationWarnings?: boolean
+  } = {}
+) {
+  const {
+    enhancedErrors = true,
+    performanceWarnings = true,
+    accessibilityWarnings = true,
+    deprecationWarnings = true,
+  } = options
+
+  if (process.env.NODE_ENV === 'development') {
+    if (enhancedErrors) {
+      // Enhanced errors would be enabled here
+      console.log('🛠️ TachUI: Enhanced error reporting enabled')
+    }
+
+    if (performanceWarnings) {
+      console.log('⚡ TachUI: Performance warnings enabled')
+    }
+
+    if (accessibilityWarnings) {
+      console.log('♿ TachUI: Accessibility warnings enabled')
+    }
+
+    if (deprecationWarnings) {
+      console.log('🟡 TachUI: Deprecation warnings enabled')
+    }
+
+    console.log('✨ TachUI Developer Experience initialized')
+  }
+}
+
+/**
+ * Development mode utilities for easier debugging
+ */
+export const devUtils = {
+  /**
+   * Log component information
+   */
+  inspectComponent(component: any): void {
+    console.group(`🔍 Component Inspector: ${component.type}`)
+    console.log('Props:', component.props)
+    console.log('Modifiers:', component.modifiers?.length || 0)
+
+    if (component.debugInfo) {
+      console.log('Debug Info:', component.debugInfo)
+    }
+
+    if (component.modifiers && component.modifiers.length > 0) {
+      console.group('Applied Modifiers:')
+      component.modifiers.forEach((modifier: any, index: number) => {
+        console.log(`${index + 1}. ${modifier.type}:`, modifier.properties)
+      })
+      console.groupEnd()
+    }
+
+    console.groupEnd()
+  },
+
+  /**
+   * Measure component render time
+   */
+  measureRender<T>(componentFactory: () => T, label = 'Component'): T {
+    const startTime = performance.now()
+    const result = componentFactory()
+    const endTime = performance.now()
+
+    console.log(`⏱️ ${label} render time: ${(endTime - startTime).toFixed(2)}ms`)
+    return result
+  },
+
+  /**
+   * Log reactive signal changes
+   */
+  watchSignal(signal: any, label?: string): () => void {
+    const signalName = label || signal.name || 'Signal'
+    const lastValue = signal.value
+
+    const unwatch = () => {
+      // This would need integration with the reactive system
+      console.log(`👁️ Stopped watching ${signalName}`)
+    }
+
+    console.log(`👁️ Watching ${signalName}, current value:`, lastValue)
+
+    // In a real implementation, this would set up a reactive effect
+    // createEffect(() => {
+    //   const newValue = signal()
+    //   if (newValue !== lastValue) {
+    //     console.log(`🔄 ${signalName} changed:`, lastValue, '→', newValue)
+    //     lastValue = newValue
+    //   }
+    // })
+
+    return unwatch
+  },
+}
+
+/**
+ * Type-safe component factory helper
+ */
+export function createTypedComponent<T extends Record<string, any>>(
+  name: string,
+  factory: (props: T) => any
+): any {
+  const typedFactory = (props: T) => {
+    const component = factory(props)
+
+    // Add development metadata
+    if (process.env.NODE_ENV === 'development') {
+      const enhancedComponent = component as any
+      enhancedComponent.displayName = name
+      enhancedComponent.debugInfo = {
+        createdAt: Date.now(),
+        renderCount: 1,
+        lastRenderTime: performance.now(),
+      }
+    }
+
+    return component
+  }
+
+  // Add display name for debugging
+  Object.defineProperty(typedFactory, 'name', { value: name })
+
+  return typedFactory
+}
+
+/**
+ * Validation helper for component props
+ */
+export function validateProps<T extends Record<string, any>>(
+  componentName: string,
+  props: T,
+  validator: (props: T) => boolean | string
+): void {
+  const result = validator(props)
+
+  if (typeof result === 'string') {
+    const error = DeveloperErrorFactory.componentValidationError(
+      componentName,
+      'props',
+      'valid props object',
+      props
+    )
+    error.suggestion = result
+    throw error
+  }
+
+  if (result === false) {
+    throw DeveloperErrorFactory.componentValidationError(
+      componentName,
+      'props',
+      'valid props object',
+      props
+    )
+  }
+}

package/src/globals.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Global type definitions for TachUI core
+ */
+
+declare global {
+  /**
+   * Development mode flag
+   */
+  const __DEV__: boolean
+
+  /**
+   * WeakRef support (ES2021+)
+   */
+  interface WeakRef<T extends object> {
+    readonly [Symbol.toStringTag]: 'WeakRef'
+    deref(): T | undefined
+  }
+
+  interface WeakRefConstructor {
+    readonly prototype: WeakRef<any>
+    new <T extends object>(target: T): WeakRef<T>
+  }
+
+  var WeakRef: WeakRefConstructor
+
+  /**
+   * FinalizationRegistry support (ES2021+)
+   */
+  interface FinalizationRegistry<T> {
+    readonly [Symbol.toStringTag]: 'FinalizationRegistry'
+    register(target: object, heldValue: T, unregisterToken?: object): void
+    unregister(unregisterToken: object): boolean
+  }
+
+  interface FinalizationRegistryConstructor {
+    readonly prototype: FinalizationRegistry<any>
+    new <T>(cleanupCallback: (heldValue: T) => void): FinalizationRegistry<T>
+  }
+
+  var FinalizationRegistry: FinalizationRegistryConstructor
+}
+
+export {}