@tachui/core 0.7.0-alpha1

package/src/state/state-manager.ts

@@ -0,0 +1,366 @@
+/**
+ * State Manager Implementation
+ *
+ * Manages the lifecycle of all property wrappers (@State, @Binding, @ObservedObject, @EnvironmentObject)
+ * within a component context. Handles registration, cleanup, and debugging utilities.
+ */
+
+import type { ComponentContext } from '../runtime/types'
+import type {
+  Binding,
+  BindingOptions,
+  EnvironmentObject,
+  EnvironmentObjectOptions,
+  ObservableObject,
+  ObservableObjectOptions,
+  ObservedObject,
+  PropertyWrapperMetadata,
+  PropertyWrapperRegistry,
+  State,
+  StateManager,
+  StateWrapperOptions,
+} from './types'
+
+/**
+ * Internal state manager implementation
+ */
+export class StateManagerImpl implements StateManager {
+  private states = new Map<string, State<any>>()
+  private bindings = new Map<string, Binding<any>>()
+  private observedObjects = new Map<string, ObservedObject<any>>()
+  private environmentObjects = new Map<string, EnvironmentObject<any>>()
+  private registry: PropertyWrapperRegistry
+
+  constructor(public readonly componentContext: ComponentContext) {
+    this.registry = new PropertyWrapperRegistryImpl()
+  }
+
+  /**
+   * Register a @State property wrapper
+   */
+  registerState<T>(state: State<T>, _options: StateWrapperOptions = {}): void {
+    const metadata = (state as any).metadata as PropertyWrapperMetadata
+    if (metadata) {
+      const key = `${metadata.componentId}_${metadata.propertyName}`
+      this.states.set(key, state)
+      this.registry.register(metadata)
+
+      // Set up debugging if in development mode
+      if (process.env.NODE_ENV === 'development') {
+        this.setupStateDebugging(state, metadata)
+      }
+    }
+  }
+
+  /**
+   * Register a @Binding property wrapper
+   */
+  registerBinding<T>(binding: Binding<T>, options: BindingOptions<T> = {}): void {
+    const key = `${this.componentContext.id}_${options.name || 'binding'}_${Date.now()}`
+    this.bindings.set(key, binding)
+
+    const metadata: PropertyWrapperMetadata = {
+      type: 'Binding',
+      propertyName: options.name || 'binding',
+      componentId: this.componentContext.id,
+      options,
+    }
+    this.registry.register(metadata)
+  }
+
+  /**
+   * Register an @ObservedObject property wrapper
+   */
+  registerObservedObject<T extends ObservableObject>(
+    observedObject: ObservedObject<T>,
+    _options: ObservableObjectOptions = {}
+  ): void {
+    const metadata = (observedObject as any).metadata as PropertyWrapperMetadata
+    if (metadata) {
+      const key = `${metadata.componentId}_${metadata.propertyName}`
+      this.observedObjects.set(key, observedObject)
+      this.registry.register(metadata)
+
+      // Set up debugging if in development mode
+      if (process.env.NODE_ENV === 'development') {
+        this.setupObservedObjectDebugging(observedObject, metadata)
+      }
+    }
+  }
+
+  /**
+   * Register an @EnvironmentObject property wrapper
+   */
+  registerEnvironmentObject<T>(
+    environmentObject: EnvironmentObject<T>,
+    _options: EnvironmentObjectOptions<T>
+  ): void {
+    const metadata = (environmentObject as any).metadata as PropertyWrapperMetadata
+    if (metadata) {
+      const key = `${metadata.componentId}_${metadata.propertyName}`
+      this.environmentObjects.set(key, environmentObject)
+      this.registry.register(metadata)
+    }
+  }
+
+  /**
+   * Clean up all property wrappers for this component
+   */
+  cleanup(): void {
+    // Clear all registered property wrappers
+    this.states.clear()
+    this.bindings.clear()
+    this.observedObjects.clear()
+    this.environmentObjects.clear()
+
+    // Clean up registry
+    this.registry.cleanup(this.componentContext.id)
+  }
+
+  /**
+   * Get all registered states (for debugging)
+   */
+  getStates(): Map<string, State<any>> {
+    return new Map(this.states)
+  }
+
+  /**
+   * Get all registered bindings (for debugging)
+   */
+  getBindings(): Map<string, Binding<any>> {
+    return new Map(this.bindings)
+  }
+
+  /**
+   * Get all registered observed objects (for debugging)
+   */
+  getObservedObjects(): Map<string, ObservedObject<any>> {
+    return new Map(this.observedObjects)
+  }
+
+  /**
+   * Get all registered environment objects (for debugging)
+   */
+  getEnvironmentObjects(): Map<string, EnvironmentObject<any>> {
+    return new Map(this.environmentObjects)
+  }
+
+  /**
+   * Get property wrapper registry
+   */
+  getRegistry(): PropertyWrapperRegistry {
+    return this.registry
+  }
+
+  /**
+   * Set up debugging for @State property wrappers
+   */
+  private setupStateDebugging<T>(state: State<T>, metadata: PropertyWrapperMetadata): void {
+    if (typeof window !== 'undefined') {
+      // Add to global debug object
+      const globalDebug = (window as any).__TACHUI_DEBUG__ || {}
+      if (!globalDebug.states) globalDebug.states = {}
+
+      globalDebug.states[`${metadata.componentId}_${metadata.propertyName}`] = {
+        state,
+        metadata,
+        getValue: () => state.wrappedValue,
+        setValue: (value: T) => {
+          state.projectedValue.set(value)
+        },
+        getBinding: () => state.projectedValue,
+      }
+
+      ;(window as any).__TACHUI_DEBUG__ = globalDebug
+    }
+  }
+
+  /**
+   * Set up debugging for @ObservedObject property wrappers
+   */
+  private setupObservedObjectDebugging<T extends ObservableObject>(
+    observedObject: ObservedObject<T>,
+    metadata: PropertyWrapperMetadata
+  ): void {
+    if (typeof window !== 'undefined') {
+      // Add to global debug object
+      const globalDebug = (window as any).__TACHUI_DEBUG__ || {}
+      if (!globalDebug.observedObjects) globalDebug.observedObjects = {}
+
+      globalDebug.observedObjects[`${metadata.componentId}_${metadata.propertyName}`] = {
+        observedObject,
+        metadata,
+        getObject: () => observedObject.wrappedValue,
+        getNotificationCount: () => (observedObject.wrappedValue as any).notificationCount || 0,
+        triggerChange: () => observedObject.wrappedValue.notifyChange(),
+      }
+
+      ;(window as any).__TACHUI_DEBUG__ = globalDebug
+    }
+  }
+}
+
+/**
+ * Property wrapper registry implementation
+ */
+class PropertyWrapperRegistryImpl implements PropertyWrapperRegistry {
+  private metadata = new Map<string, PropertyWrapperMetadata[]>()
+
+  /**
+   * Register property wrapper metadata
+   */
+  register(metadata: PropertyWrapperMetadata): void {
+    const key = metadata.componentId
+    const existing = this.metadata.get(key) || []
+    existing.push(metadata)
+    this.metadata.set(key, existing)
+  }
+
+  /**
+   * Unregister a specific property wrapper
+   */
+  unregister(componentId: string, propertyName: string): void {
+    const existing = this.metadata.get(componentId) || []
+    const filtered = existing.filter((m) => m.propertyName !== propertyName)
+
+    if (filtered.length > 0) {
+      this.metadata.set(componentId, filtered)
+    } else {
+      this.metadata.delete(componentId)
+    }
+  }
+
+  /**
+   * Clean up all metadata for a component
+   */
+  cleanup(componentId: string): void {
+    this.metadata.delete(componentId)
+  }
+
+  /**
+   * Get all metadata for a component
+   */
+  getMetadata(componentId: string): PropertyWrapperMetadata[] {
+    return this.metadata.get(componentId) || []
+  }
+
+  /**
+   * Get all registered metadata (for debugging)
+   */
+  getAllMetadata(): Map<string, PropertyWrapperMetadata[]> {
+    return new Map(this.metadata)
+  }
+}
+
+/**
+ * Create a state manager for a component
+ */
+export function createStateManager(componentContext: ComponentContext): StateManager {
+  return new StateManagerImpl(componentContext)
+}
+
+/**
+ * Global state manager registry for debugging and introspection
+ */
+class GlobalStateManagerRegistry {
+  private static instance: GlobalStateManagerRegistry
+  private managers = new Map<string, StateManager>()
+
+  static getInstance(): GlobalStateManagerRegistry {
+    if (!GlobalStateManagerRegistry.instance) {
+      GlobalStateManagerRegistry.instance = new GlobalStateManagerRegistry()
+    }
+    return GlobalStateManagerRegistry.instance
+  }
+
+  register(componentId: string, manager: StateManager): void {
+    this.managers.set(componentId, manager)
+  }
+
+  unregister(componentId: string): void {
+    this.managers.delete(componentId)
+  }
+
+  getManager(componentId: string): StateManager | undefined {
+    return this.managers.get(componentId)
+  }
+
+  getAllManagers(): Map<string, StateManager> {
+    return new Map(this.managers)
+  }
+
+  /**
+   * Get debugging information for all components
+   */
+  getDebugInfo(): any {
+    const info: any = {}
+
+    for (const [componentId, manager] of this.managers) {
+      info[componentId] = {
+        states: (manager as StateManagerImpl).getStates().size,
+        bindings: (manager as StateManagerImpl).getBindings().size,
+        observedObjects: (manager as StateManagerImpl).getObservedObjects().size,
+        environmentObjects: (manager as StateManagerImpl).getEnvironmentObjects().size,
+        metadata: (manager as StateManagerImpl).getRegistry().getMetadata(componentId),
+      }
+    }
+
+    return info
+  }
+}
+
+/**
+ * Register a state manager globally
+ */
+export function registerStateManager(componentId: string, manager: StateManager): void {
+  GlobalStateManagerRegistry.getInstance().register(componentId, manager)
+}
+
+/**
+ * Unregister a state manager globally
+ */
+export function unregisterStateManager(componentId: string): void {
+  GlobalStateManagerRegistry.getInstance().unregister(componentId)
+}
+
+/**
+ * Get a state manager by component ID
+ */
+export function getStateManager(componentId: string): StateManager | undefined {
+  return GlobalStateManagerRegistry.getInstance().getManager(componentId)
+}
+
+/**
+ * Get all state managers (for debugging)
+ */
+export function getAllStateManagers(): Map<string, StateManager> {
+  return GlobalStateManagerRegistry.getInstance().getAllManagers()
+}
+
+/**
+ * Get debugging information for all state managers
+ */
+export function getStateManagerDebugInfo(): any {
+  return GlobalStateManagerRegistry.getInstance().getDebugInfo()
+}
+
+/**
+ * Initialize global debugging utilities
+ */
+export function initializeStateDebugging(): void {
+  if (typeof window !== 'undefined' && process.env.NODE_ENV === 'development') {
+    const globalDebug = (window as any).__TACHUI_DEBUG__ || {}
+
+    globalDebug.stateManagers = {
+      getAll: getAllStateManagers,
+      getDebugInfo: getStateManagerDebugInfo,
+      getManager: getStateManager,
+    }
+
+    ;(window as any).__TACHUI_DEBUG__ = globalDebug
+
+    console.log(
+      'TachUI State Management debugging enabled. Use window.__TACHUI_DEBUG__.stateManagers'
+    )
+  }
+}

package/src/state/state.ts

@@ -0,0 +1,339 @@
+/**
+ * @State Property Wrapper Implementation
+ *
+ * Implements SwiftUI's @State property wrapper for local component state management.
+ * Provides reactive state with automatic component re-rendering on changes.
+ */
+
+import { getCurrentOwner } from '../reactive/context'
+import { createEffect } from '../reactive/effect'
+import { createSignal } from '../reactive/signal'
+import type { Accessor, Setter } from '../reactive/types'
+import { getCurrentComponentContext } from '../runtime/component-context'
+import type { ComponentContext } from '../runtime/types'
+import type * as Types from './types'
+import type { Binding, PropertyWrapperMetadata, StateFactory, StateWrapperOptions } from './types'
+
+/**
+ * Internal state wrapper implementation
+ */
+class StateImpl<T> implements Types.State<T> {
+  private _accessor: Accessor<T>
+  private _setter: Setter<T>
+  private _binding: Binding<T>
+  private _metadata: PropertyWrapperMetadata
+
+  constructor(
+    initialValue: T,
+    componentContext: ComponentContext,
+    propertyName: string,
+    options: StateWrapperOptions = {}
+  ) {
+    // Create the underlying reactive signal
+    const [accessor, setter] = createSignal(initialValue)
+    this._accessor = accessor
+    this._setter = setter
+
+    // Create the projected binding
+    this._binding = createBinding(accessor, setter, {
+      name: options.name || `${propertyName}Binding`,
+    })
+
+    // Store metadata for introspection
+    this._metadata = {
+      type: 'State',
+      propertyName,
+      componentId: componentContext.id,
+      options,
+    }
+
+    // Register with component context for lifecycle management
+    componentContext.setState(propertyName, initialValue)
+
+    // Set up cleanup on component unmount
+    const owner = getCurrentOwner()
+    if (owner) {
+      owner.cleanups.push(() => {
+        // Cleanup any resources if needed
+        this.cleanup()
+      })
+    }
+
+    // Handle reset on mount if configured
+    if (options.resetOnMount) {
+      this.resetToInitialValue(initialValue)
+    }
+
+    // Set up persistence if configured
+    if (options.persist && typeof window !== 'undefined') {
+      this.setupPersistence(propertyName, initialValue)
+    }
+  }
+
+  get wrappedValue(): T {
+    return this._accessor()
+  }
+
+  set wrappedValue(value: T) {
+    this._setter(value)
+  }
+
+  get projectedValue(): Binding<T> {
+    return this._binding
+  }
+
+  /**
+   * Get the underlying signal accessor (for advanced usage)
+   */
+  get accessor(): Accessor<T> {
+    return this._accessor
+  }
+
+  /**
+   * Get the underlying signal setter (for advanced usage)
+   */
+  get setter(): Setter<T> {
+    return this._setter
+  }
+
+  /**
+   * Get property wrapper metadata
+   */
+  get metadata(): PropertyWrapperMetadata {
+    return this._metadata
+  }
+
+  /**
+   * Reset to initial value
+   */
+  private resetToInitialValue(initialValue: T): void {
+    this._setter(initialValue)
+  }
+
+  /**
+   * Set up local storage persistence
+   */
+  private setupPersistence(propertyName: string, _initialValue: T): void {
+    const storageKey = `tachui_state_${this._metadata.componentId}_${propertyName}`
+
+    // Try to load persisted value
+    try {
+      const stored = localStorage.getItem(storageKey)
+      if (stored !== null && stored !== undefined && stored !== 'undefined') {
+        const parsedValue = JSON.parse(stored)
+        this._setter(parsedValue)
+      }
+    } catch (error) {
+      console.warn(`Failed to load persisted state for ${propertyName}:`, error)
+    }
+
+    // Set up automatic persistence on changes
+    createEffect(() => {
+      const currentValue = this._accessor()
+      try {
+        localStorage.setItem(storageKey, JSON.stringify(currentValue))
+      } catch (error) {
+        console.warn(`Failed to persist state for ${propertyName}:`, error)
+      }
+    })
+  }
+
+  /**
+   * Cleanup resources
+   */
+  private cleanup(): void {
+    // Any cleanup logic would go here
+    // Currently no cleanup needed for basic state
+  }
+}
+
+/**
+ * Create a binding from getter and setter functions
+ */
+function createBinding<T>(
+  get: Accessor<T>,
+  set: Setter<T>,
+  options: { name?: string } = {}
+): Binding<T> {
+  return new BindingImpl(get, set, options)
+}
+
+/**
+ * Internal binding implementation
+ */
+class BindingImpl<T> implements Binding<T> {
+  constructor(
+    private _get: Accessor<T>,
+    private _set: Setter<T>,
+    private _options: { name?: string } = {}
+  ) {}
+
+  get wrappedValue(): T {
+    return this._get()
+  }
+
+  set wrappedValue(value: T) {
+    this._set(value)
+  }
+
+  get projectedValue(): Binding<T> {
+    return this
+  }
+
+  get(): T {
+    return this._get()
+  }
+
+  set(value: T | ((prev: T) => T)): void {
+    this._set(value)
+  }
+
+  /**
+   * Create a derived binding with transformation
+   */
+  map<U>(getter: (value: T) => U, setter: (newValue: U, oldValue: T) => T): Binding<U> {
+    const mappedGet = () => getter(this._get())
+    const mappedSet = (value: U | ((prev: U) => U)) => {
+      const currentValue = this._get()
+      const currentMapped = getter(currentValue)
+      const newMapped =
+        typeof value === 'function' ? (value as (prev: U) => U)(currentMapped) : value
+      const newOriginal = setter(newMapped, currentValue)
+      this._set(newOriginal)
+    }
+
+    return createBinding(mappedGet, mappedSet as Setter<U>, {
+      name: `${this._options.name || 'binding'}_mapped`,
+    })
+  }
+
+  /**
+   * Create a constant binding (read-only)
+   */
+  constant(): Binding<T> {
+    return createBinding(
+      this._get,
+      () => {
+        console.warn('Attempted to set value on constant binding')
+        return this._get()
+      },
+      { name: `${this._options.name || 'binding'}_constant` }
+    )
+  }
+}
+
+/**
+ * @State property wrapper factory
+ *
+ * Creates a @State property wrapper for local component state.
+ *
+ * @param initialValue - The initial value for the state
+ * @param options - Configuration options for the state wrapper
+ * @returns A State property wrapper
+ *
+ * @example
+ * ```typescript
+ * class MyComponent {
+ *   @State(0)
+ *   private count: number
+ *
+ *   @State('Hello')
+ *   private message: string
+ *
+ *   render() {
+ *     return Text(`${this.message}: ${this.count}`)
+ *       .modifier
+ *       .onTap(() => this.count++)
+ *       .build()
+ *   }
+ * }
+ * ```
+ */
+export const State: StateFactory = <T>(
+  initialValue: T,
+  options: StateWrapperOptions = {}
+): Types.State<T> => {
+  // This will be replaced by the decorator transformer during compilation
+  // For runtime usage, we need component context
+  const componentContext = getCurrentComponentContext()
+  const propertyName = getCallerPropertyName() || 'state'
+
+  return new StateImpl(initialValue, componentContext, propertyName, options)
+}
+
+/**
+ * Create a binding from external getter/setter functions
+ *
+ * @param get - Function to get current value
+ * @param set - Function to set new value
+ * @param options - Configuration options
+ * @returns A Binding property wrapper
+ *
+ * @example
+ * ```typescript
+ * const binding = createBinding(
+ *   () => externalValue,
+ *   (value) => { externalValue = value },
+ *   { name: 'externalBinding' }
+ * )
+ * ```
+ */
+export const createStateBinding = createBinding
+
+// getCurrentComponentContext is now imported from component-context module
+
+/**
+ * Helper to get the property name of the caller (used for metadata)
+ */
+function getCallerPropertyName(): string | null {
+  // This would be replaced by the compiler with actual property name
+  // For runtime debugging, we can try to infer from call stack
+  try {
+    const stack = new Error().stack
+    if (stack) {
+      // Parse stack to get property name - this is a fallback for debugging
+      const match = stack.match(/at (\w+)\./)?.[1]
+      return match || null
+    }
+  } catch {
+    // Ignore errors in stack parsing
+  }
+  return null
+}
+
+// ComponentContextSymbol is now imported from component-context module
+
+/**
+ * Export binding factory for external use
+ */
+export { createBinding }
+
+/**
+ * Type guard for State property wrappers
+ */
+export function isState<T>(value: any): value is Types.State<T> {
+  return value && typeof value === 'object' && 'wrappedValue' in value && 'projectedValue' in value
+}
+
+/**
+ * Type guard for Binding property wrappers
+ */
+export function isBinding<T>(value: any): value is Binding<T> {
+  return (
+    value &&
+    typeof value === 'object' &&
+    'get' in value &&
+    'set' in value &&
+    'wrappedValue' in value
+  )
+}
+
+/**
+ * Utility to extract the raw value from State or Binding
+ */
+export function unwrapValue<T>(wrapper: Types.State<T> | Binding<T> | T): T {
+  if (isState(wrapper) || isBinding(wrapper)) {
+    return (wrapper as Types.State<T> | Binding<T>).wrappedValue
+  }
+  return wrapper as T
+}