@rlabs-inc/tui 0.1.0 → 0.2.0

package/README.md

@@ -57,17 +57,6 @@ setInterval(() => count.value++, 1000)
 - Bindings for prop connections
 - Zero reconciliation - reactivity IS the update mechanism
 
-### Svelte-like .tui Files (Compiler)
-```html
-<script>
-  const name = signal('World')
-</script>
-
-<box width={40} height={3}>
-  <text content={`Hello, ${name.value}!`} />
-</box>
-```
-
 ### State Modules
 - **keyboard** - Key events, shortcuts, input buffering
 - **mouse** - Click, hover, drag, wheel events
@@ -110,6 +99,8 @@ bun run examples/tests/03-layout-flex.ts
 
 ## Primitives
 
+### UI Primitives
+
 | Primitive | Status | Description |
 |-----------|--------|-------------|
 | `box` | Complete | Container with flexbox layout |
@@ -118,13 +109,135 @@ bun run examples/tests/03-layout-flex.ts
 | `select` | Planned | Dropdown selection |
 | `progress` | Planned | Progress bar |
 
+### Template Primitives
+
+Reactive control flow for dynamic UIs - no manual effects needed!
+
+| Primitive | Purpose | Description |
+|-----------|---------|-------------|
+| `each()` | Lists | Reactive list rendering with keyed reconciliation |
+| `show()` | Conditionals | Show/hide components based on condition |
+| `when()` | Async | Suspense-like pending/success/error states |
+
+#### `each()` - Reactive Lists
+
+Renders a list of components that automatically updates when the array changes.
+
+```typescript
+import { each, box, text, signal } from '@rlabs-inc/tui'
+
+const todos = signal([
+  { id: '1', text: 'Learn TUI', done: false },
+  { id: '2', text: 'Build app', done: false },
+])
+
+box({
+  children: () => {
+    each(
+      () => todos.value,                    // Reactive array getter
+      (todo) => box({                       // Render function per item
+        id: `todo-${todo.id}`,              // Stable ID for reconciliation
+        children: () => {
+          text({ content: () => todo.text })  // Props can be reactive too!
+        }
+      }),
+      { key: (todo) => todo.id }            // Key function for efficient updates
+    )
+  }
+})
+
+// Add item - UI updates automatically
+todos.value = [...todos.value, { id: '3', text: 'Deploy', done: false }]
+
+// Remove item - component is cleaned up automatically
+todos.value = todos.value.filter(t => t.id !== '1')
+```
+
+#### `show()` - Conditional Rendering
+
+Shows or hides components based on a reactive condition.
+
+```typescript
+import { show, box, text, signal } from '@rlabs-inc/tui'
+
+const isLoggedIn = signal(false)
+
+box({
+  children: () => {
+    show(
+      () => isLoggedIn.value,               // Condition getter
+      () => box({                           // Render when true
+        children: () => {
+          text({ content: 'Welcome back!' })
+        }
+      }),
+      () => text({ content: 'Please log in' })  // Optional: render when false
+    )
+  }
+})
+
+// Toggle - UI switches automatically
+isLoggedIn.value = true
+```
+
+#### `when()` - Async/Suspense
+
+Handles async operations with loading, success, and error states.
+
+```typescript
+import { when, box, text, signal } from '@rlabs-inc/tui'
+
+const userId = signal('123')
+
+// Fetch function that returns a promise
+const fetchUser = (id: string) =>
+  fetch(`/api/users/${id}`).then(r => r.json())
+
+box({
+  children: () => {
+    when(
+      () => fetchUser(userId.value),        // Promise getter (re-runs on userId change)
+      {
+        pending: () => text({ content: 'Loading...' }),
+        then: (user) => box({
+          children: () => {
+            text({ content: `Name: ${user.name}` })
+            text({ content: `Email: ${user.email}` })
+          }
+        }),
+        catch: (error) => text({
+          content: `Error: ${error.message}`,
+          fg: 'red'
+        })
+      }
+    )
+  }
+})
+
+// Change userId - triggers new fetch, shows loading, then result
+userId.value = '456'
+```
+
+### How Template Primitives Work
+
+All template primitives follow the same elegant pattern:
+
+1. **Capture parent context** at creation time
+2. **Initial render synchronously** (correct parent hierarchy)
+3. **Internal effect** tracks reactive dependencies
+4. **Reconcile on change** (create new, cleanup removed)
+
+This means:
+- User code stays clean - no manual effects
+- Props inside templates are fully reactive
+- Cleanup is automatic
+- Performance is optimal (only affected components update)
+
 ## Test Coverage
 
-- **130 tests** passing
 - TITAN layout engine: 48 tests
 - Parallel arrays: 17 tests
 - Focus manager: 29 tests
-- Compiler: 36 tests (unit + integration)
 
 ## Requirements
 

package/index.ts

@@ -9,21 +9,24 @@
 export { mount } from './src/api'
 
 // Primitives - UI building blocks
-export { box, text } from './src/primitives'
-export type { BoxProps, TextProps, Cleanup } from './src/primitives'
+export { box, text, each, show, when, scoped, onCleanup, useAnimation, AnimationFrames } from './src/primitives'
+export type { BoxProps, TextProps, Cleanup, AnimationOptions } from './src/primitives'
 
 // State modules - Input handling
-export { keyboard } from './src/state/keyboard'
+export { keyboard, lastKey, lastEvent } from './src/state/keyboard'
+export { mouse, hitGrid, lastMouseEvent, mouseX, mouseY, isMouseDown } from './src/state/mouse'
 export { focusManager, focusedIndex } from './src/state/focus'
 export { scroll } from './src/state/scroll'
-export { mouse, hitGrid } from './src/state/mouse'
+export { globalKeys } from './src/state/global-keys'
+export { cursor } from './src/state/cursor'
 
 // Types
 export * from './src/types'
 export * from './src/types/color'
 
 // Signals re-export for convenience
-export { signal, state, derived, effect, bind, signals } from '@rlabs-inc/signals'
+export { signal, state, derived, effect, bind, signals, batch, reactiveProps } from '@rlabs-inc/signals'
+export type { PropInput, PropsInput, ReactiveProps } from '@rlabs-inc/signals'
 
 // Theme
 export {
@@ -43,3 +46,6 @@ export * from './src/renderer'
 
 // Engine (advanced)
 export * from './src/engine'
+
+// Layout (advanced - for debugging)
+export { layoutDerived } from './src/pipeline/layout'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rlabs-inc/tui",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The Terminal UI Framework for TypeScript/Bun - Blazing-fast, fine-grained reactive terminal UI with complete flexbox layout",
   "module": "index.ts",
   "main": "index.ts",
@@ -54,6 +54,6 @@
     "typescript": "^5.0.0"
   },
   "dependencies": {
-    "@rlabs-inc/signals": "^1.6.0"
+    "@rlabs-inc/signals": "^1.8.2"
   }
 }

package/src/api/mount.ts

@@ -28,12 +28,13 @@ import {
   DiffRenderer,
   InlineRenderer,
 } from '../renderer/output'
+import { AppendRegionRenderer } from '../renderer/append-region'
 import * as ansi from '../renderer/ansi'
 import { frameBufferDerived } from '../pipeline/frameBuffer'
 import { layoutDerived, terminalWidth, terminalHeight, updateTerminalSize, renderMode } from '../pipeline/layout'
 import { resetRegistry } from '../engine/registry'
-import { hitGrid, clearHitGrid } from '../state/mouse'
-import { keyboard } from '../state/keyboard'
+import { hitGrid, clearHitGrid, mouse } from '../state/mouse'
+import { globalKeys } from '../state/global-keys'
 
 // =============================================================================
 // MOUNT
@@ -54,6 +55,7 @@ export async function mount(
     mode = 'fullscreen',
     mouse = true,
     kittyKeyboard = true,
+    getStaticHeight,
   } = options
 
   // Set render mode signal BEFORE creating components
@@ -63,9 +65,10 @@ export async function mount(
   // Create renderer based on mode
   // Fullscreen uses DiffRenderer (absolute positioning)
   // Inline uses InlineRenderer (eraseLines + sequential write)
-  // Append uses DiffRenderer for now (TODO: may need AppendRenderer)
+  // Append uses AppendRegionRenderer (two-region: static + reactive)
   const diffRenderer = new DiffRenderer()
   const inlineRenderer = new InlineRenderer()
+  const appendRegionRenderer = new AppendRegionRenderer()
 
   // Mode-specific state
   let previousHeight = 0  // For append mode: track last rendered height
@@ -87,9 +90,7 @@ export async function mount(
 
   setupSequence.push(ansi.hideCursor)
 
-  if (mouse) {
-    setupSequence.push(ansi.enableMouse)
-  }
+  // Mouse tracking is handled by globalKeys.initialize() via mouse.enableTracking()
 
   if (kittyKeyboard) {
     setupSequence.push(ansi.enableKittyKeyboard)
@@ -101,9 +102,8 @@ export async function mount(
   // Write setup sequence
   process.stdout.write(setupSequence.join(''))
 
-  // Initialize keyboard module (handles stdin, raw mode, input parsing)
-  // Pass cleanup callback for proper shutdown on Ctrl+C
-  keyboard.initialize()
+  // Initialize global input system (stdin, keyboard, mouse, shortcuts)
+  globalKeys.initialize({ enableMouse: mouse })
 
   // Handle resize
   const handleResize = () => {
@@ -127,20 +127,29 @@ export async function mount(
   // Create the component tree
   root()
 
+  // Global error handlers for debugging
+  process.on('uncaughtException', (err) => {
+    console.error('[TUI] Uncaught exception:', err)
+  })
+  process.on('unhandledRejection', (err) => {
+    console.error('[TUI] Unhandled rejection:', err)
+  })
+
   // THE ONE RENDER EFFECT
   // This is where the magic happens - reactive rendering!
   // Side effects (HitGrid) are applied HERE, not in the derived.
   let stopEffect: (() => void) | null = null
 
   stopEffect = effect(() => {
+    try {
     const start = Bun.nanoseconds()
 
     // Time layout separately (reading .value triggers computation if needed)
-    // const layoutStart = Bun.nanoseconds()
-    // const _layout = layoutDerived.value
-    // const layoutNs = Bun.nanoseconds() - layoutStart
+    const layoutStart = Bun.nanoseconds()
+    const computedLayout = layoutDerived.value
+    const layoutNs = Bun.nanoseconds() - layoutStart
 
-    // Time buffer computation
+    // Time buffer computation (layout is cached, so this is just framebuffer)
     const bufferStart = Bun.nanoseconds()
     const { buffer, hitRegions, terminalSize } = frameBufferDerived.value
     const bufferNs = Bun.nanoseconds() - bufferStart
@@ -161,7 +170,13 @@ export async function mount(
       diffRenderer.render(buffer)
     } else if (mode === 'inline') {
       inlineRenderer.render(buffer)
+    } else if (mode === 'append') {
+      // Append mode: use two-region renderer
+      // staticHeight determined by getStaticHeight callback or defaults to 0
+      const staticHeight = getStaticHeight ? getStaticHeight() : 0
+      appendRegionRenderer.render(buffer, { staticHeight })
     } else {
+      // Fallback to inline for unknown modes
       inlineRenderer.render(buffer)
     }
     const renderNs = Bun.nanoseconds() - renderStart
@@ -169,12 +184,14 @@ export async function mount(
     const totalNs = Bun.nanoseconds() - start
 
     // Show all timing stats in window title
-    // const layoutMs = layoutNs / 1_000_000
+    const layoutMs = layoutNs / 1_000_000
     const bufferMs = bufferNs / 1_000_000
     const renderMs = renderNs / 1_000_000
     const totalMs = totalNs / 1_000_000
-    // process.stdout.write(`\x1b]0;TUI | ${mode} | layout: ${layoutMs.toFixed(3)}ms | buffer: ${bufferMs.toFixed(3)}ms | render: ${renderMs.toFixed(3)}ms | total: ${totalMs.toFixed(3)}ms\x07`)
-    process.stdout.write(`\x1b]0;TUI | ${mode} | buffer: ${bufferMs.toFixed(3)}ms | render: ${renderMs.toFixed(3)}ms | total: ${totalMs.toFixed(3)}ms\x07`)
+    process.stdout.write(`\x1b]0;TUI | h:${computedLayout.contentHeight} | layout: ${layoutMs.toFixed(3)}ms | buffer: ${bufferMs.toFixed(3)}ms | render: ${renderMs.toFixed(3)}ms | total: ${totalMs.toFixed(3)}ms\x07`)
+    } catch (err) {
+      console.error('[TUI] Render effect error:', err)
+    }
   })
 
   // Cleanup function
@@ -185,8 +202,13 @@ export async function mount(
       stopEffect = null
     }
 
-    // Cleanup keyboard module (removes stdin listener, restores terminal)
-    keyboard.cleanup()
+    // Cleanup global input system
+    globalKeys.cleanup()
+
+    // Cleanup append region renderer if used
+    if (mode === 'append') {
+      appendRegionRenderer.cleanup()
+    }
 
     // Remove resize listener
     process.stdout.removeListener('resize', handleResize)
@@ -201,11 +223,7 @@ export async function mount(
       restoreSequence.push(ansi.disableKittyKeyboard)
     }
 
-    if (mouse) {
-      restoreSequence.push(ansi.disableMouse)
-    }
-
-    restoreSequence.push(ansi.showCursor)
+    // Mouse disable and cursor show handled by globalKeys.cleanup()
     restoreSequence.push(ansi.reset)
 
     if (mode === 'fullscreen') {
@@ -218,10 +236,7 @@ export async function mount(
 
     process.stdout.write(restoreSequence.join(''))
 
-    // Disable raw mode
-    if (process.stdin.isTTY) {
-      process.stdin.setRawMode(false)
-    }
+    // Raw mode disabled by globalKeys.cleanup() -> input.cleanup()
 
     // Reset registry for clean slate
     resetRegistry()

package/src/engine/arrays/core.ts

@@ -8,53 +8,45 @@
  *
  * NOTE: Focus state (focusable, tabIndex) is in interaction.ts
  *
- * CRITICAL: Arrays storing Bindings must be regular arrays (NOT state!)
- * state() proxies snapshot getter values, breaking reactivity.
- * componentType is the exception - it stores values directly, not bindings.
+ * Uses slotArray for stable reactive cells that NEVER get replaced.
+ * componentType is the exception - it stores values directly, not reactively.
  */
 
-import { bind, disconnectBinding, type Binding } from '@rlabs-inc/signals'
+import { slotArray, type SlotArray } from '@rlabs-inc/signals'
 import { ComponentType } from '../../types'
 import type { ComponentTypeValue } from '../../types'
 
-/** Component type (box, text, input, etc.) - stores values directly */
+/** Component type (box, text, input, etc.) - stores values directly (not reactive) */
 export const componentType: ComponentTypeValue[] = []
 
 /** Parent component index (-1 for root) */
-export const parentIndex: Binding<number>[] = []
+export const parentIndex: SlotArray<number> = slotArray<number>(-1)
 
 /** Is component visible (0/false = hidden, 1/true = visible) */
-export const visible: Binding<number | boolean>[] = []
+export const visible: SlotArray<number | boolean> = slotArray<number | boolean>(1)
 
 /** Component ID (for debugging and lookups) */
-export const componentId: Binding<string>[] = []
+export const componentId: SlotArray<string> = slotArray<string>('')
 
 /**
  * Ensure array has capacity for the given index.
  * Called by registry when allocating.
- *
- * LAZY BINDING: We push undefined here, not bindings.
- * Primitives create bindings only for props they actually use.
- * This reduces memory from ~70 bindings/component to ~5-10.
  */
 export function ensureCapacity(index: number): void {
   while (componentType.length <= index) {
     componentType.push(ComponentType.NONE)
-    parentIndex.push(undefined as any)
-    visible.push(undefined as any)
-    componentId.push(undefined as any)
   }
+  parentIndex.ensureCapacity(index)
+  visible.ensureCapacity(index)
+  componentId.ensureCapacity(index)
 }
 
 /** Clear values at index (called when releasing) */
 export function clearAtIndex(index: number): void {
   if (index < componentType.length) {
     componentType[index] = ComponentType.NONE
-    disconnectBinding(parentIndex[index])
-    disconnectBinding(visible[index])
-    disconnectBinding(componentId[index])
-    parentIndex[index] = undefined as any
-    visible[index] = undefined as any
-    componentId[index] = undefined as any
   }
+  parentIndex.clear(index)
+  visible.clear(index)
+  componentId.clear(index)
 }

package/src/engine/arrays/dimensions.ts

@@ -5,8 +5,7 @@
  * These are INPUT values that components write.
  * The layout derived READS these and RETURNS computed positions.
  *
- * CRITICAL: Use regular arrays (NOT state!) to preserve binding getters.
- * state() proxies snapshot getter values, breaking reactivity.
+ * Uses slotArray for stable reactive cells that NEVER get replaced.
  *
  * Supports both absolute and percentage dimensions:
  *   - number: Absolute value in cells (e.g., 50)
@@ -17,52 +16,43 @@
  * Note: 0 means "auto" for width/height, "no constraint" for min/max.
  */
 
-import { bind, disconnectBinding, type Binding } from '@rlabs-inc/signals'
+import { slotArray, type SlotArray } from '@rlabs-inc/signals'
 import type { Dimension } from '../../types'
 
 /** Requested width (0 = auto, '100%' = full parent width) */
-export const width: Binding<Dimension>[] = []
+export const width: SlotArray<Dimension> = slotArray<Dimension>(0)
 
 /** Requested height (0 = auto, '100%' = full parent height) */
-export const height: Binding<Dimension>[] = []
+export const height: SlotArray<Dimension> = slotArray<Dimension>(0)
 
 /** Minimum width constraint */
-export const minWidth: Binding<Dimension>[] = []
+export const minWidth: SlotArray<Dimension> = slotArray<Dimension>(0)
 
 /** Minimum height constraint */
-export const minHeight: Binding<Dimension>[] = []
+export const minHeight: SlotArray<Dimension> = slotArray<Dimension>(0)
 
 /** Maximum width constraint (0 = no max) */
-export const maxWidth: Binding<Dimension>[] = []
+export const maxWidth: SlotArray<Dimension> = slotArray<Dimension>(0)
 
 /** Maximum height constraint (0 = no max) */
-export const maxHeight: Binding<Dimension>[] = []
+export const maxHeight: SlotArray<Dimension> = slotArray<Dimension>(0)
 
-/** LAZY BINDING: Push undefined, primitives create bindings for used props only */
+/** Ensure capacity for all dimension arrays */
 export function ensureCapacity(index: number): void {
-  while (width.length <= index) {
-    width.push(undefined as any)
-    height.push(undefined as any)
-    minWidth.push(undefined as any)
-    minHeight.push(undefined as any)
-    maxWidth.push(undefined as any)
-    maxHeight.push(undefined as any)
-  }
+  width.ensureCapacity(index)
+  height.ensureCapacity(index)
+  minWidth.ensureCapacity(index)
+  minHeight.ensureCapacity(index)
+  maxWidth.ensureCapacity(index)
+  maxHeight.ensureCapacity(index)
 }
 
+/** Clear slot at index (reset to default) */
 export function clearAtIndex(index: number): void {
-  if (index < width.length) {
-    disconnectBinding(width[index])
-    disconnectBinding(height[index])
-    disconnectBinding(minWidth[index])
-    disconnectBinding(minHeight[index])
-    disconnectBinding(maxWidth[index])
-    disconnectBinding(maxHeight[index])
-    width[index] = undefined as any
-    height[index] = undefined as any
-    minWidth[index] = undefined as any
-    minHeight[index] = undefined as any
-    maxWidth[index] = undefined as any
-    maxHeight[index] = undefined as any
-  }
+  width.clear(index)
+  height.clear(index)
+  minWidth.clear(index)
+  minHeight.clear(index)
+  maxWidth.clear(index)
+  maxHeight.clear(index)
 }