@rlabs-inc/tui 0.1.0 → 0.2.0

package/src/primitives/scope.ts

@@ -0,0 +1,215 @@
+/**
+ * TUI Framework - Component Scope
+ *
+ * Automatic cleanup collection for component functions.
+ * box/text/effect automatically register with the active scope.
+ *
+ * Usage:
+ * ```ts
+ * function MyComponent(props): Cleanup {
+ *   return scoped(() => {
+ *     // Everything inside auto-registers cleanup
+ *     box({ children: () => text({ content: 'Hello' }) })
+ *     effect(() => console.log(count.value))
+ *
+ *     // Manual cleanup for timers etc
+ *     const timer = setInterval(() => tick(), 1000)
+ *     onCleanup(() => clearInterval(timer))
+ *   })
+ * }
+ * ```
+ */
+
+import { effectScope, onScopeDispose } from '@rlabs-inc/signals'
+import type { EffectScope } from '@rlabs-inc/signals'
+
+export type Cleanup = () => void
+
+// =============================================================================
+// ACTIVE SCOPE TRACKING
+// =============================================================================
+
+interface ScopeContext {
+  cleanups: Cleanup[]
+  scope: EffectScope
+}
+
+let activeContext: ScopeContext | null = null
+
+/**
+ * Get the currently active scope context.
+ * Used by box/text to auto-register cleanups.
+ */
+export function getActiveScope(): ScopeContext | null {
+  return activeContext
+}
+
+/**
+ * Register a cleanup with the active scope.
+ * Called automatically by box/text when a scope is active.
+ * Can also be called manually for timers/subscriptions.
+ */
+export function onCleanup(cleanup: Cleanup): void {
+  if (activeContext) {
+    activeContext.cleanups.push(cleanup)
+  }
+}
+
+/**
+ * Register a cleanup and return it (for chaining).
+ * Useful when you need the cleanup function reference.
+ */
+export function trackCleanup<T extends Cleanup>(cleanup: T): T {
+  if (activeContext) {
+    activeContext.cleanups.push(cleanup)
+  }
+  return cleanup
+}
+
+// =============================================================================
+// SCOPED EXECUTION
+// =============================================================================
+
+/**
+ * Execute a function with automatic cleanup collection.
+ * box/text/effect calls inside automatically register their cleanups.
+ *
+ * @example Basic component
+ * ```ts
+ * function Counter(): Cleanup {
+ *   return scoped(() => {
+ *     const count = signal(0)
+ *
+ *     box({
+ *       children: () => {
+ *         text({ content: () => `Count: ${count.value}` })
+ *       }
+ *     })
+ *
+ *     effect(() => console.log('Count:', count.value))
+ *   })
+ * }
+ * ```
+ *
+ * @example With manual cleanups
+ * ```ts
+ * function Timer(): Cleanup {
+ *   return scoped(() => {
+ *     const elapsed = signal(0)
+ *
+ *     const interval = setInterval(() => elapsed.value++, 1000)
+ *     onCleanup(() => clearInterval(interval))
+ *
+ *     box({ children: () => text({ content: () => `${elapsed.value}s` }) })
+ *   })
+ * }
+ * ```
+ *
+ * @example Nested components work too
+ * ```ts
+ * function Parent(): Cleanup {
+ *   return scoped(() => {
+ *     box({
+ *       children: () => {
+ *         Child() // Child's cleanup is tracked by parent
+ *       }
+ *     })
+ *   })
+ * }
+ * ```
+ */
+export function scoped(fn: () => void): Cleanup {
+  const scope = effectScope()
+  const cleanups: Cleanup[] = []
+
+  const prevContext = activeContext
+  activeContext = { cleanups, scope }
+
+  try {
+    // Run the function within effect scope
+    // Effects created inside are tracked by the scope
+    scope.run(fn)
+  } finally {
+    activeContext = prevContext
+  }
+
+  // Return master cleanup
+  return () => {
+    // Stop effect scope (disposes effects)
+    scope.stop()
+
+    // Run all registered cleanups
+    for (const cleanup of cleanups) {
+      try {
+        cleanup()
+      } catch (e) {
+        // Cleanup errors logged but don't stop other cleanups
+        console.error('Cleanup error:', e)
+      }
+    }
+  }
+}
+
+// =============================================================================
+// LEGACY API (for backwards compatibility)
+// =============================================================================
+
+export interface ComponentScopeResult {
+  onCleanup: <T extends Cleanup>(cleanup: T) => T
+  cleanup: Cleanup
+  scope: EffectScope
+}
+
+/**
+ * Create a component scope for manual cleanup collection.
+ * @deprecated Use scoped() for automatic cleanup instead
+ */
+export function componentScope(): ComponentScopeResult {
+  const cleanups: Cleanup[] = []
+  const scope = effectScope()
+
+  return {
+    onCleanup: <T extends Cleanup>(cleanup: T): T => {
+      cleanups.push(cleanup)
+      return cleanup
+    },
+    cleanup: () => {
+      scope.stop()
+      for (const cleanup of cleanups) {
+        try {
+          cleanup()
+        } catch (e) {
+          console.error('Cleanup error:', e)
+        }
+      }
+    },
+    scope,
+  }
+}
+
+/**
+ * Create a simple cleanup collector.
+ * @deprecated Use scoped() for automatic cleanup instead
+ */
+export function cleanupCollector(): {
+  add: <T extends Cleanup>(cleanup: T) => T
+  cleanup: Cleanup
+} {
+  const cleanups: Cleanup[] = []
+
+  return {
+    add: <T extends Cleanup>(cleanup: T): T => {
+      cleanups.push(cleanup)
+      return cleanup
+    },
+    cleanup: () => {
+      for (const cleanup of cleanups) {
+        try {
+          cleanup()
+        } catch (e) {
+          console.error('Cleanup error:', e)
+        }
+      }
+    },
+  }
+}

package/src/primitives/show.ts

@@ -0,0 +1,77 @@
+/**
+ * TUI Framework - Show Primitive
+ *
+ * Conditional rendering. Shows or hides components based on a condition.
+ * When the condition changes, components are automatically created/destroyed.
+ *
+ * Usage:
+ * ```ts
+ * show(() => isVisible.value, () => {
+ *   text({ content: 'I am visible!' })
+ * })
+ * ```
+ */
+
+import { effect, effectScope, onScopeDispose } from '@rlabs-inc/signals'
+import { getCurrentParentIndex, pushParentContext, popParentContext } from '../engine/registry'
+import type { Cleanup } from './types'
+
+/**
+ * Conditionally render components.
+ *
+ * @param conditionGetter - Getter that returns boolean (creates dependency)
+ * @param renderFn - Function to render when condition is true (returns cleanup)
+ * @param elseFn - Optional function to render when condition is false
+ */
+export function show(
+  conditionGetter: () => boolean,
+  renderFn: () => Cleanup,
+  elseFn?: () => Cleanup
+): Cleanup {
+  let cleanup: Cleanup | null = null
+  let wasTrue: boolean | null = null
+  const parentIndex = getCurrentParentIndex()
+  const scope = effectScope()
+
+  const update = (condition: boolean) => {
+    if (condition === wasTrue) return
+    wasTrue = condition
+
+    if (cleanup) {
+      cleanup()
+      cleanup = null
+    }
+
+    pushParentContext(parentIndex)
+    try {
+      if (condition) {
+        cleanup = renderFn()
+      } else if (elseFn) {
+        cleanup = elseFn()
+      }
+    } finally {
+      popParentContext()
+    }
+  }
+
+  scope.run(() => {
+    // Initial render
+    update(conditionGetter())
+
+    // Effect for updates - skip first run
+    let initialized = false
+    effect(() => {
+      const condition = conditionGetter()
+      if (initialized) {
+        update(condition)
+      }
+      initialized = true
+    })
+
+    onScopeDispose(() => {
+      if (cleanup) cleanup()
+    })
+  })
+
+  return () => scope.stop()
+}

package/src/primitives/text.ts

@@ -23,11 +23,12 @@
  * ```
  */
 
-import { bind, BINDING_SYMBOL } from '@rlabs-inc/signals'
+// Using slotArray APIs - no direct signal imports needed
 import { ComponentType, Attr } from '../types'
 import { allocateIndex, releaseIndex, getCurrentParentIndex } from '../engine/registry'
 import { cleanupIndex as cleanupKeyboardListeners } from '../state/keyboard'
 import { getVariantStyle } from '../state/theme'
+import { getActiveScope } from './scope'
 
 // Import arrays
 import * as core from '../engine/arrays/core'
@@ -61,31 +62,33 @@ function wrapToNum(wrap: string | undefined): number {
     default: return 1 // wrap
   }
 }
+/** Override alignItems for this item: 0=auto, 1=stretch, 2=flex-start, 3=center, 4=flex-end */
+function alignSelfToNum(alignSelf: string | undefined): number {
+  switch (alignSelf) {
+    case 'auto': return 0
+    case 'stretch': return 1
+    case 'flex-start': return 2
+    case 'center': return 3
+    case 'flex-end': return 4
+    default: return 0
+  }
+}
+
+// bindEnumProp removed - using enumSource instead
 
 /**
- * Create a binding for enum props that converts at read time.
- * No derived needed - reads signal directly and converts inline.
- * This creates dependency directly on user's signal, no intermediate objects.
+ * Create a slot source for enum props - returns getter for reactive, value for static.
+ * For use with slotArray.setSource()
  */
-function bindEnumProp<T extends string>(
+function enumSource<T extends string>(
   prop: T | { value: T } | undefined,
   converter: (val: T | undefined) => number
-): ReturnType<typeof bind<number>> {
-  // If it's reactive (has .value), create binding that converts at read time
+): number | (() => number) {
   if (prop !== undefined && typeof prop === 'object' && prop !== null && 'value' in prop) {
     const reactiveSource = prop as { value: T }
-    return {
-      [BINDING_SYMBOL]: true,
-      get value(): number {
-        return converter(reactiveSource.value)
-      },
-      set value(_: number) {
-        // Enum props are read-only from number side
-      },
-    } as unknown as ReturnType<typeof bind<number>>
+    return () => converter(reactiveSource.value)
   }
-  // Static value - just convert
-  return bind(converter(prop as T | undefined))
+  return converter(prop as T | undefined)
 }
 
 // =============================================================================
@@ -110,55 +113,56 @@ export function text(props: TextProps): Cleanup {
   // CORE - Always needed
   // ==========================================================================
   core.componentType[index] = ComponentType.TEXT
-  core.parentIndex[index] = bind(getCurrentParentIndex())
+  core.parentIndex.setSource(index, getCurrentParentIndex())
 
   // Visible - only bind if passed
   if (props.visible !== undefined) {
-    core.visible[index] = bind(props.visible)
+    core.visible.setSource(index, props.visible)
   }
 
   // ==========================================================================
   // TEXT CONTENT - Always needed (this is a text component!)
+  // Uses setSource() for stable slot tracking (fixes bind() replacement bug)
   // ==========================================================================
-  textArrays.textContent[index] = bind(props.content)
+  textArrays.textContent.setSource(index, props.content)
 
-  // Text styling - only bind if passed
-  if (props.attrs !== undefined) textArrays.textAttrs[index] = bind(props.attrs)
-  if (props.align !== undefined) textArrays.textAlign[index] = bindEnumProp(props.align, alignToNum)
-  if (props.wrap !== undefined) textArrays.textWrap[index] = bindEnumProp(props.wrap, wrapToNum)
+  // Text styling - only set if passed
+  if (props.attrs !== undefined) textArrays.textAttrs.setSource(index, props.attrs)
+  if (props.align !== undefined) textArrays.textAlign.setSource(index, enumSource(props.align, alignToNum))
+  if (props.wrap !== undefined) textArrays.textWrap.setSource(index, enumSource(props.wrap, wrapToNum))
 
   // ==========================================================================
   // DIMENSIONS - Only bind what's passed (TITAN uses ?? 0 for undefined)
   // ==========================================================================
-  if (props.width !== undefined) dimensions.width[index] = bind(props.width)
-  if (props.height !== undefined) dimensions.height[index] = bind(props.height)
-  if (props.minWidth !== undefined) dimensions.minWidth[index] = bind(props.minWidth)
-  if (props.maxWidth !== undefined) dimensions.maxWidth[index] = bind(props.maxWidth)
-  if (props.minHeight !== undefined) dimensions.minHeight[index] = bind(props.minHeight)
-  if (props.maxHeight !== undefined) dimensions.maxHeight[index] = bind(props.maxHeight)
+  if (props.width !== undefined) dimensions.width.setSource(index, props.width)
+  if (props.height !== undefined) dimensions.height.setSource(index, props.height)
+  if (props.minWidth !== undefined) dimensions.minWidth.setSource(index, props.minWidth)
+  if (props.maxWidth !== undefined) dimensions.maxWidth.setSource(index, props.maxWidth)
+  if (props.minHeight !== undefined) dimensions.minHeight.setSource(index, props.minHeight)
+  if (props.maxHeight !== undefined) dimensions.maxHeight.setSource(index, props.maxHeight)
 
   // ==========================================================================
   // PADDING - Shorthand support
   // ==========================================================================
   if (props.padding !== undefined) {
-    spacing.paddingTop[index] = bind(props.paddingTop ?? props.padding)
-    spacing.paddingRight[index] = bind(props.paddingRight ?? props.padding)
-    spacing.paddingBottom[index] = bind(props.paddingBottom ?? props.padding)
-    spacing.paddingLeft[index] = bind(props.paddingLeft ?? props.padding)
+    spacing.paddingTop.setSource(index, props.paddingTop ?? props.padding)
+    spacing.paddingRight.setSource(index, props.paddingRight ?? props.padding)
+    spacing.paddingBottom.setSource(index, props.paddingBottom ?? props.padding)
+    spacing.paddingLeft.setSource(index, props.paddingLeft ?? props.padding)
   } else {
-    if (props.paddingTop !== undefined) spacing.paddingTop[index] = bind(props.paddingTop)
-    if (props.paddingRight !== undefined) spacing.paddingRight[index] = bind(props.paddingRight)
-    if (props.paddingBottom !== undefined) spacing.paddingBottom[index] = bind(props.paddingBottom)
-    if (props.paddingLeft !== undefined) spacing.paddingLeft[index] = bind(props.paddingLeft)
+    if (props.paddingTop !== undefined) spacing.paddingTop.setSource(index, props.paddingTop)
+    if (props.paddingRight !== undefined) spacing.paddingRight.setSource(index, props.paddingRight)
+    if (props.paddingBottom !== undefined) spacing.paddingBottom.setSource(index, props.paddingBottom)
+    if (props.paddingLeft !== undefined) spacing.paddingLeft.setSource(index, props.paddingLeft)
   }
 
   // ==========================================================================
   // FLEX ITEM - Only bind if passed (text can be a flex item)
   // ==========================================================================
-  if (props.grow !== undefined) layout.flexGrow[index] = bind(props.grow)
-  if (props.shrink !== undefined) layout.flexShrink[index] = bind(props.shrink)
-  if (props.flexBasis !== undefined) layout.flexBasis[index] = bind(props.flexBasis)
-  if (props.alignSelf !== undefined) layout.alignSelf[index] = bind(props.alignSelf)
+  if (props.grow !== undefined) layout.flexGrow.setSource(index, props.grow)
+  if (props.shrink !== undefined) layout.flexShrink.setSource(index, props.shrink)
+  if (props.flexBasis !== undefined) layout.flexBasis.setSource(index, props.flexBasis)
+  if (props.alignSelf !== undefined) layout.alignSelf.setSource(index, enumSource(props.alignSelf, alignSelfToNum))
 
   // ==========================================================================
   // VISUAL - Colors with variant support (only bind what's needed)
@@ -167,33 +171,33 @@ export function text(props: TextProps): Cleanup {
     // Variant colors - inline bindings that read theme at read time (no deriveds!)
     const variant = props.variant
     if (props.fg !== undefined) {
-      visual.fgColor[index] = bind(props.fg)
+      visual.fgColor.setSource(index, props.fg)
     } else {
-      visual.fgColor[index] = {
-        [BINDING_SYMBOL]: true,
-        get value() { return getVariantStyle(variant).fg },
-        set value(_) {},
-      } as any
+      visual.fgColor.setSource(index, () => getVariantStyle(variant).fg)
     }
     if (props.bg !== undefined) {
-      visual.bgColor[index] = bind(props.bg)
+      visual.bgColor.setSource(index, props.bg)
     } else {
-      visual.bgColor[index] = {
-        [BINDING_SYMBOL]: true,
-        get value() { return getVariantStyle(variant).bg },
-        set value(_) {},
-      } as any
+      visual.bgColor.setSource(index, () => getVariantStyle(variant).bg)
     }
   } else {
     // Direct colors - only bind if passed
-    if (props.fg !== undefined) visual.fgColor[index] = bind(props.fg)
-    if (props.bg !== undefined) visual.bgColor[index] = bind(props.bg)
+    if (props.fg !== undefined) visual.fgColor.setSource(index, props.fg)
+    if (props.bg !== undefined) visual.bgColor.setSource(index, props.bg)
   }
-  if (props.opacity !== undefined) visual.opacity[index] = bind(props.opacity)
+  if (props.opacity !== undefined) visual.opacity.setSource(index, props.opacity)
 
   // Cleanup function
-  return () => {
+  const cleanup = () => {
     cleanupKeyboardListeners(index)
     releaseIndex(index)
   }
+
+  // Auto-register with active scope if one exists
+  const scope = getActiveScope()
+  if (scope) {
+    scope.cleanups.push(cleanup)
+  }
+
+  return cleanup
 }

package/src/primitives/types.ts

@@ -137,7 +137,7 @@ export interface BoxProps extends StyleProps, BorderProps, DimensionProps, Spaci
 // TEXT PROPS
 // =============================================================================
 
-export interface TextProps extends StyleProps, DimensionProps, SpacingProps {
+export interface TextProps extends StyleProps, DimensionProps, SpacingProps, LayoutProps {
   /** Text content */
   content: Reactive<string>
   /** Text alignment: 'left' | 'center' | 'right' */

package/src/primitives/when.ts

@@ -0,0 +1,102 @@
+/**
+ * TUI Framework - When Primitive
+ *
+ * Async rendering. Shows loading/error/success states based on promise state.
+ * When the promise resolves or rejects, the appropriate components are shown.
+ *
+ * Usage:
+ * ```ts
+ * when(() => fetchData(), {
+ *   pending: () => text({ content: 'Loading...' }),
+ *   then: (data) => text({ content: `Got: ${data}` }),
+ *   catch: (err) => text({ content: `Error: ${err.message}` })
+ * })
+ * ```
+ */
+
+import { effect, effectScope, onScopeDispose } from '@rlabs-inc/signals'
+import { getCurrentParentIndex, pushParentContext, popParentContext } from '../engine/registry'
+import type { Cleanup } from './types'
+
+interface WhenOptions<T> {
+  pending?: () => Cleanup
+  then: (value: T) => Cleanup
+  catch?: (error: Error) => Cleanup
+}
+
+/**
+ * Render based on async promise state.
+ *
+ * @param promiseGetter - Getter that returns a promise (creates dependency)
+ * @param options - Handlers for pending, then, and catch states
+ */
+export function when<T>(
+  promiseGetter: () => Promise<T>,
+  options: WhenOptions<T>
+): Cleanup {
+  let cleanup: Cleanup | null = null
+  let currentPromise: Promise<T> | null = null
+  const parentIndex = getCurrentParentIndex()
+  const scope = effectScope()
+
+  const render = (fn: () => Cleanup) => {
+    if (cleanup) {
+      cleanup()
+      cleanup = null
+    }
+    pushParentContext(parentIndex)
+    try {
+      cleanup = fn()
+    } finally {
+      popParentContext()
+    }
+  }
+
+  const handlePromise = (promise: Promise<T>) => {
+    if (promise !== currentPromise) return
+
+    promise
+      .then((value) => {
+        if (promise !== currentPromise) return
+        render(() => options.then(value))
+      })
+      .catch((error) => {
+        if (promise !== currentPromise) return
+        if (options.catch) {
+          render(() => options.catch!(error))
+        }
+      })
+  }
+
+  scope.run(() => {
+    // Initial setup
+    const initialPromise = promiseGetter()
+    currentPromise = initialPromise
+    if (options.pending) {
+      render(options.pending)
+    }
+    handlePromise(initialPromise)
+
+    // Effect for updates - skip first run
+    let initialized = false
+    effect(() => {
+      const promise = promiseGetter()
+      if (initialized) {
+        if (promise === currentPromise) return
+        currentPromise = promise
+        if (options.pending) {
+          render(options.pending)
+        }
+        handlePromise(promise)
+      }
+      initialized = true
+    })
+
+    onScopeDispose(() => {
+      currentPromise = null
+      if (cleanup) cleanup()
+    })
+  })
+
+  return () => scope.stop()
+}