@rlabs-inc/tui 0.1.0 → 0.2.1

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()
+}

package/src/renderer/append-region.ts

@@ -0,0 +1,159 @@
+/**
+ * TUI Framework - Append Mode Renderer
+ *
+ * Simple renderer for append mode:
+ * - Clears active region (eraseDown from cursor)
+ * - Renders active content
+ *
+ * History content is handled separately via renderToHistory().
+ * The app controls what goes to history vs active area.
+ *
+ * This renderer is essentially inline mode with cursor at the
+ * boundary between frozen history and active content.
+ */
+
+import type { FrameBuffer, RGBA, CellAttrs } from '../types'
+import { Attr } from '../types'
+import { rgbaEqual } from '../types/color'
+import * as ansi from './ansi'
+
+// =============================================================================
+// APPEND MODE RENDERER
+// =============================================================================
+
+/**
+ * Simple append mode renderer.
+ * Erases previous active content and renders fresh.
+ *
+ * Like InlineRenderer but only erases the active area (preserves history).
+ */
+export class AppendRegionRenderer {
+  // Cell rendering state (for ANSI optimization)
+  private lastFg: RGBA | null = null
+  private lastBg: RGBA | null = null
+  private lastAttrs: CellAttrs = Attr.NONE
+
+  // Track previous height to know how many lines to erase
+  private previousHeight = 0
+
+  /**
+   * Render frame buffer as active content.
+   * Erases exactly the previous content, then writes fresh.
+   */
+  render(buffer: FrameBuffer): void {
+    const output = this.buildOutput(buffer)
+
+    // Erase previous active content (move up and clear each line)
+    if (this.previousHeight > 0) {
+      process.stdout.write(ansi.eraseLines(this.previousHeight))
+    }
+
+    // Render active content
+    process.stdout.write(output)
+
+    // Track height for next render
+    // +1 because buildOutput adds trailing newline which moves cursor down one line
+    this.previousHeight = buffer.height + 1
+  }
+
+  /**
+   * Erase the current active area.
+   * Call this BEFORE writing to history so we clear the screen first.
+   */
+  eraseActive(): void {
+    if (this.previousHeight > 0) {
+      process.stdout.write(ansi.eraseLines(this.previousHeight))
+      this.previousHeight = 0
+    }
+  }
+
+  /**
+   * Call this after writing to history.
+   * Resets height tracking so next render doesn't try to erase history.
+   */
+  invalidate(): void {
+    this.previousHeight = 0
+  }
+
+  /**
+   * Build output string for the buffer.
+   */
+  private buildOutput(buffer: FrameBuffer): string {
+    if (buffer.height === 0) return ''
+
+    const chunks: string[] = []
+
+    // Reset rendering state
+    this.lastFg = null
+    this.lastBg = null
+    this.lastAttrs = Attr.NONE
+
+    for (let y = 0; y < buffer.height; y++) {
+      if (y > 0) {
+        chunks.push('\n')
+      }
+
+      for (let x = 0; x < buffer.width; x++) {
+        const cell = buffer.cells[y]![x]
+        this.renderCell(chunks, cell!)
+      }
+    }
+
+    chunks.push(ansi.reset)
+    chunks.push('\n')
+
+    return chunks.join('')
+  }
+
+  /**
+   * Render a single cell with ANSI optimization.
+   */
+  private renderCell(chunks: string[], cell: { char: number; fg: RGBA; bg: RGBA; attrs: CellAttrs }): void {
+    // Attributes changed - reset first
+    if (cell.attrs !== this.lastAttrs) {
+      chunks.push(ansi.reset)
+      if (cell.attrs !== Attr.NONE) {
+        chunks.push(ansi.attrs(cell.attrs))
+      }
+      this.lastFg = null
+      this.lastBg = null
+      this.lastAttrs = cell.attrs
+    }
+
+    // Foreground color changed
+    if (!this.lastFg || !rgbaEqual(cell.fg, this.lastFg)) {
+      chunks.push(ansi.fg(cell.fg))
+      this.lastFg = cell.fg
+    }
+
+    // Background color changed
+    if (!this.lastBg || !rgbaEqual(cell.bg, this.lastBg)) {
+      chunks.push(ansi.bg(cell.bg))
+      this.lastBg = cell.bg
+    }
+
+    // Output character
+    if (cell.char === 0) {
+      chunks.push(' ')
+    } else {
+      chunks.push(String.fromCodePoint(cell.char))
+    }
+  }
+
+  /**
+   * Reset renderer state.
+   */
+  reset(): void {
+    this.previousHeight = 0
+    this.lastFg = null
+    this.lastBg = null
+    this.lastAttrs = Attr.NONE
+  }
+
+  /**
+   * Cleanup (no-op for simplified renderer).
+   */
+  cleanup(): void {
+    // Nothing to cleanup - we don't own the FileSink
+  }
+}

package/src/renderer/index.ts

@@ -36,5 +36,7 @@ export {
   finalizeAppendMode,
 } from './output'
 
-// Input parsing
-export { InputBuffer, type ParsedInput } from './input'
+// Two-region append renderer
+export { AppendRegionRenderer } from './append-region'
+
+// Input parsing moved to src/state/input.ts

package/src/renderer/output.ts

@@ -312,12 +312,11 @@ export function finalizeAppendMode(output: OutputBuffer, height: number): void {
 // =============================================================================
 
 /**
- * Inline renderer matching Ink's log-update approach.
- * Uses our own ansi.ts (zero dependencies).
+ * Inline renderer for non-fullscreen mode.
+ * Uses clearTerminal for reliable rendering without ghost lines.
  */
 export class InlineRenderer {
   private output = new OutputBuffer()
-  private previousLineCount = 0
   private previousOutput = ''
 
   // Cell rendering state (for ANSI optimization)
@@ -327,18 +326,14 @@ export class InlineRenderer {
 
   /**
    * Render a frame buffer for inline mode.
-   * Follows log-update's algorithm:
-   * 1. Build output with trailing newline
-   * 2. eraseLines(previousLineCount) + output
-   * 3. Track new line count
    *
-   * KEY INSIGHT FROM INK:
-   * When content height >= terminal rows, eraseLines can't reach content
-   * that scrolled off the top into scrollback. In this case, use clearTerminal
-   * to wipe everything including scrollback, then redraw.
+   * Uses clearTerminal (clears screen + scrollback) before each render.
+   * This is simpler and more reliable than tracking line counts:
+   * - No ghost lines from eraseLines edge cases
+   * - Once content exceeds terminal height, scrollback is cleared anyway
+   * - The slight overhead of clearing is negligible with fast renders
    */
   render(buffer: FrameBuffer): void {
-    // Build the output string
     const output = this.buildOutput(buffer)
 
     // Skip if output unchanged
@@ -346,26 +341,11 @@ export class InlineRenderer {
       return
     }
 
-    // Get terminal viewport height
-    const terminalRows = process.stdout.rows || 24
-
-    // When content height >= terminal rows, eraseLines can't reach content
-    // that scrolled off into scrollback. Use clearTerminal instead.
-    if (this.previousLineCount >= terminalRows) {
-      this.output.write(ansi.clearTerminal + output)
-    } else {
-      this.output.write(ansi.eraseLines(this.previousLineCount) + output)
-    }
+    // Clear everything and render fresh
+    this.output.write(ansi.clearTerminal + output)
     this.output.flushSync()
 
-    // Track for next render
     this.previousOutput = output
-    // buffer.height + 1 because:
-    // - We output buffer.height lines of content
-    // - Plus a trailing newline that puts cursor on the next line
-    // - eraseLines works from cursor position upward, so we need to erase
-    //   buffer.height lines PLUS the empty line we're currently on
-    this.previousLineCount = buffer.height + 1
   }
 
   /**
@@ -431,10 +411,8 @@ export class InlineRenderer {
    * Clear all rendered content and reset state.
    */
   clear(): void {
-    if (this.previousLineCount > 0) {
-      this.output.write(ansi.eraseLines(this.previousLineCount))
-      this.output.flushSync()
-    }
+    this.output.write(ansi.clearTerminal)
+    this.output.flushSync()
     this.reset()
   }
 
@@ -442,7 +420,6 @@ export class InlineRenderer {
    * Reset the renderer state.
    */
   reset(): void {
-    this.previousLineCount = 0
     this.previousOutput = ''
     this.lastFg = null
     this.lastBg = null

package/src/state/focus.ts

@@ -65,7 +65,10 @@ export function restoreFocusFromHistory(): boolean {
   while (focusHistory.length > 0) {
     const index = focusHistory.pop()!
     // Check if component is still valid and focusable
-    if (unwrap(focusable[index]) && unwrap(visible[index])) {
+    // Match TITAN's logic: undefined means visible, only 0/false means hidden
+    const isVisible = unwrap(visible[index])
+    const isActuallyVisible = isVisible !== 0 && isVisible !== false
+    if (unwrap(focusable[index]) && isActuallyVisible) {
       focusedIndex.value = index
       return true
     }
@@ -83,7 +86,11 @@ export function getFocusableIndices(): number[] {
   const result: number[] = []
 
   for (const i of indices) {
-    if (unwrap(focusable[i]) && unwrap(visible[i])) {
+    const isFocusable = unwrap(focusable[i])
+    const isVisible = unwrap(visible[i])
+    // Match TITAN's logic: undefined means visible, only 0/false means hidden
+    const isActuallyVisible = isVisible !== 0 && isVisible !== false
+    if (isFocusable && isActuallyVisible) {
       result.push(i)
     }
   }
@@ -141,8 +148,9 @@ function findNextFocusable(fromIndex: number, direction: 1 | -1): number {
 
 /** Move focus to next focusable component */
 export function focusNext(): boolean {
-  const next = findNextFocusable(focusedIndex.value, 1)
-  if (next !== -1 && next !== focusedIndex.value) {
+  const current = focusedIndex.value
+  const next = findNextFocusable(current, 1)
+  if (next !== -1 && next !== current) {
     saveFocusToHistory()
     focusedIndex.value = next
     return true
@@ -163,7 +171,10 @@ export function focusPrevious(): boolean {
 
 /** Focus a specific component by index */
 export function focus(index: number): boolean {
-  if (unwrap(focusable[index]) && unwrap(visible[index])) {
+  // Match TITAN's logic: undefined means visible, only 0/false means hidden
+  const isVisible = unwrap(visible[index])
+  const isActuallyVisible = isVisible !== 0 && isVisible !== false
+  if (unwrap(focusable[index]) && isActuallyVisible) {
     if (focusedIndex.value !== index) {
       saveFocusToHistory()
       focusedIndex.value = index