@rlabs-inc/tui 0.1.0 → 0.2.1

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.1",
   "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/history.ts

@@ -0,0 +1,451 @@
+/**
+ * TUI Framework - History Rendering for Append Mode
+ *
+ * Provides utilities for rendering content to terminal history (scrollback).
+ * Used in append mode where completed content is frozen to history while
+ * active content remains reactive.
+ *
+ * Key concepts:
+ * - History content is written once via FileSink (Bun's efficient stdout writer)
+ * - Uses the same component API as active rendering
+ * - Isolated rendering: creates temporary components, renders, cleans up
+ */
+
+import { batch } from '@rlabs-inc/signals'
+import type { FrameBuffer, RGBA } from '../types'
+import { ComponentType } from '../types'
+import { Colors, TERMINAL_DEFAULT } from '../types/color'
+import {
+  createBuffer,
+  fillRect,
+  drawBorder,
+  drawText,
+  drawTextCentered,
+  drawTextRight,
+  createClipRect,
+  intersectClipRects,
+  type ClipRect,
+  type BorderConfig,
+} from '../renderer/buffer'
+import {
+  getAllocatedIndices,
+  getCapacity,
+  releaseIndex,
+} from '../engine/registry'
+import { wrapText, truncateText } from '../utils/text'
+import {
+  getInheritedFg,
+  getInheritedBg,
+  getBorderColors,
+  getBorderStyles,
+  hasBorder,
+  getEffectiveOpacity,
+} from '../engine/inheritance'
+import { computeLayoutTitan } from '../pipeline/layout/titan-engine'
+import { terminalWidth, terminalHeight } from '../pipeline/layout'
+import * as ansi from '../renderer/ansi'
+
+// Import arrays
+import * as core from '../engine/arrays/core'
+import * as visual from '../engine/arrays/visual'
+import * as text from '../engine/arrays/text'
+import * as spacing from '../engine/arrays/spacing'
+import * as layout from '../engine/arrays/layout'
+import * as interaction from '../engine/arrays/interaction'
+import { Attr } from '../types'
+import { rgbaEqual } from '../types/color'
+
+// =============================================================================
+// FILESINK WRITER
+// =============================================================================
+
+/**
+ * Writer for appending to terminal stdout using Bun's FileSink API.
+ * Buffers writes and flushes efficiently.
+ */
+export class HistoryWriter {
+  private writer: ReturnType<ReturnType<typeof Bun.file>['writer']>
+  private hasContent = false
+
+  constructor() {
+    // Create writer for stdout (file descriptor 1)
+    const stdoutFile = Bun.file(1)
+    this.writer = stdoutFile.writer({ highWaterMark: 1024 * 1024 }) // 1MB buffer
+  }
+
+  write(content: string): void {
+    if (content.length === 0) return
+    this.writer.write(content)
+    this.hasContent = true
+  }
+
+  flush(): void {
+    if (this.hasContent) {
+      this.writer.flush()
+      this.hasContent = false
+    }
+  }
+
+  end(): void {
+    this.writer.end()
+  }
+}
+
+// =============================================================================
+// BUFFER TO ANSI CONVERSION
+// =============================================================================
+
+/**
+ * Convert a FrameBuffer to ANSI escape sequence string.
+ */
+function bufferToAnsi(buffer: FrameBuffer): string {
+  if (buffer.height === 0) return ''
+
+  const chunks: string[] = []
+
+  // Track last colors/attrs for optimization
+  let lastFg: RGBA | null = null
+  let lastBg: RGBA | null = null
+  let lastAttrs: number = Attr.NONE
+
+  for (let y = 0; y < buffer.height; y++) {
+    for (let x = 0; x < buffer.width; x++) {
+      const cell = buffer.cells[y]![x]!
+
+      // Attributes changed - reset first
+      if (cell.attrs !== lastAttrs) {
+        chunks.push(ansi.reset)
+        if (cell.attrs !== Attr.NONE) {
+          chunks.push(ansi.attrs(cell.attrs))
+        }
+        lastFg = null
+        lastBg = null
+        lastAttrs = cell.attrs
+      }
+
+      // Foreground color changed
+      if (!lastFg || !rgbaEqual(cell.fg, lastFg)) {
+        chunks.push(ansi.fg(cell.fg))
+        lastFg = cell.fg
+      }
+
+      // Background color changed
+      if (!lastBg || !rgbaEqual(cell.bg, lastBg)) {
+        chunks.push(ansi.bg(cell.bg))
+        lastBg = cell.bg
+      }
+
+      // Output character
+      if (cell.char === 0) {
+        chunks.push(' ')
+      } else {
+        chunks.push(String.fromCodePoint(cell.char))
+      }
+    }
+    chunks.push('\n')
+  }
+
+  chunks.push(ansi.reset)
+
+  return chunks.join('')
+}
+
+// =============================================================================
+// ISOLATED FRAME BUFFER COMPUTATION
+// =============================================================================
+
+/**
+ * Compute a frame buffer for a specific set of component indices.
+ * Used for isolated history rendering.
+ */
+function computeBufferForIndices(
+  indices: Set<number>,
+  layoutResult: ReturnType<typeof computeLayoutTitan>,
+  tw: number
+): FrameBuffer {
+  const bufferWidth = tw
+  const bufferHeight = Math.max(1, layoutResult.contentHeight)
+
+  // Create fresh buffer
+  const buffer = createBuffer(bufferWidth, bufferHeight, TERMINAL_DEFAULT)
+
+  if (indices.size === 0) {
+    return buffer
+  }
+
+  // Find root components and build child index map (only for our indices)
+  const rootIndices: number[] = []
+  const childMap = new Map<number, number[]>()
+
+  for (const i of indices) {
+    if (core.componentType[i] === ComponentType.NONE) continue
+    const vis = core.visible[i]
+    if (vis === 0 || vis === false) continue
+
+    const parent = core.parentIndex[i] ?? -1
+    if (parent === -1 || !indices.has(parent)) {
+      // Root if no parent or parent not in our set
+      rootIndices.push(i)
+    } else {
+      const children = childMap.get(parent)
+      if (children) {
+        children.push(i)
+      } else {
+        childMap.set(parent, [i])
+      }
+    }
+  }
+
+  // Sort by zIndex
+  rootIndices.sort((a, b) => (layout.zIndex[a] || 0) - (layout.zIndex[b] || 0))
+  for (const children of childMap.values()) {
+    children.sort((a, b) => (layout.zIndex[a] || 0) - (layout.zIndex[b] || 0))
+  }
+
+  // Render tree recursively
+  for (const rootIdx of rootIndices) {
+    renderComponentToBuffer(
+      buffer,
+      rootIdx,
+      layoutResult,
+      childMap,
+      undefined,
+      0,
+      0
+    )
+  }
+
+  return buffer
+}
+
+/**
+ * Render a component and its children to a buffer.
+ */
+function renderComponentToBuffer(
+  buffer: FrameBuffer,
+  index: number,
+  computedLayout: { x: number[]; y: number[]; width: number[]; height: number[]; scrollable: number[] },
+  childMap: Map<number, number[]>,
+  parentClip: ClipRect | undefined,
+  parentScrollY: number,
+  parentScrollX: number
+): void {
+  const vis = core.visible[index]
+  if (vis === 0 || vis === false) return
+  if (core.componentType[index] === ComponentType.NONE) return
+
+  const x = Math.floor((computedLayout.x[index] || 0) - parentScrollX)
+  const y = Math.floor((computedLayout.y[index] || 0) - parentScrollY)
+  const w = Math.floor(computedLayout.width[index] || 0)
+  const h = Math.floor(computedLayout.height[index] || 0)
+
+  if (w <= 0 || h <= 0) return
+
+  const componentBounds = createClipRect(x, y, w, h)
+
+  if (parentClip) {
+    const intersection = intersectClipRects(componentBounds, parentClip)
+    if (!intersection) return
+  }
+
+  // Get colors
+  const fg = getInheritedFg(index)
+  const bg = getInheritedBg(index)
+  const opacity = getEffectiveOpacity(index)
+
+  const effectiveFg = opacity < 1 ? { ...fg, a: Math.round(fg.a * opacity) } : fg
+  const effectiveBg = opacity < 1 ? { ...bg, a: Math.round(bg.a * opacity) } : bg
+
+  // Fill background
+  if (effectiveBg.a > 0 && effectiveBg.r !== -1) {
+    fillRect(buffer, x, y, w, h, effectiveBg, parentClip)
+  }
+
+  // Borders
+  const borderStyles = getBorderStyles(index)
+  const borderColors = getBorderColors(index)
+  const hasAnyBorder = hasBorder(index)
+
+  if (hasAnyBorder && w >= 2 && h >= 2) {
+    const config: BorderConfig = {
+      styles: borderStyles,
+      colors: {
+        top: opacity < 1 ? { ...borderColors.top, a: Math.round(borderColors.top.a * opacity) } : borderColors.top,
+        right: opacity < 1 ? { ...borderColors.right, a: Math.round(borderColors.right.a * opacity) } : borderColors.right,
+        bottom: opacity < 1 ? { ...borderColors.bottom, a: Math.round(borderColors.bottom.a * opacity) } : borderColors.bottom,
+        left: opacity < 1 ? { ...borderColors.left, a: Math.round(borderColors.left.a * opacity) } : borderColors.left,
+      },
+    }
+    drawBorder(buffer, x, y, w, h, config, undefined, parentClip)
+  }
+
+  // Content area
+  const padTop = (spacing.paddingTop[index] || 0) + (hasAnyBorder && borderStyles.top > 0 ? 1 : 0)
+  const padRight = (spacing.paddingRight[index] || 0) + (hasAnyBorder && borderStyles.right > 0 ? 1 : 0)
+  const padBottom = (spacing.paddingBottom[index] || 0) + (hasAnyBorder && borderStyles.bottom > 0 ? 1 : 0)
+  const padLeft = (spacing.paddingLeft[index] || 0) + (hasAnyBorder && borderStyles.left > 0 ? 1 : 0)
+
+  const contentX = x + padLeft
+  const contentY = y + padTop
+  const contentW = w - padLeft - padRight
+  const contentH = h - padTop - padBottom
+
+  const contentBounds = createClipRect(contentX, contentY, contentW, contentH)
+  const contentClip = parentClip
+    ? intersectClipRects(contentBounds, parentClip)
+    : contentBounds
+
+  if (!contentClip || contentW <= 0 || contentH <= 0) {
+    return
+  }
+
+  // Render by type
+  switch (core.componentType[index]) {
+    case ComponentType.BOX:
+      break
+
+    case ComponentType.TEXT:
+      renderTextToBuffer(buffer, index, contentX, contentY, contentW, contentH, effectiveFg, contentClip)
+      break
+
+    // Other types can be added as needed
+  }
+
+  // Render children
+  if (core.componentType[index] === ComponentType.BOX) {
+    const children = childMap.get(index) || []
+    const isScrollable = (computedLayout.scrollable[index] ?? 0) === 1
+    const scrollY = isScrollable ? (interaction.scrollOffsetY[index] || 0) : 0
+    const scrollX = isScrollable ? (interaction.scrollOffsetX[index] || 0) : 0
+
+    for (const childIdx of children) {
+      renderComponentToBuffer(
+        buffer,
+        childIdx,
+        computedLayout,
+        childMap,
+        contentClip,
+        parentScrollY + scrollY,
+        parentScrollX + scrollX
+      )
+    }
+  }
+}
+
+/**
+ * Render text component to buffer.
+ */
+function renderTextToBuffer(
+  buffer: FrameBuffer,
+  index: number,
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+  fg: RGBA,
+  clip: ClipRect
+): void {
+  const rawValue = text.textContent[index]
+  const content = rawValue == null ? '' : String(rawValue)
+  if (!content) return
+
+  const attrs = text.textAttrs[index] || 0
+  const align = text.textAlign[index] || 0
+
+  const lines = wrapText(content, w)
+
+  for (let lineIdx = 0; lineIdx < lines.length && lineIdx < h; lineIdx++) {
+    const line = lines[lineIdx] ?? ''
+    const lineY = y + lineIdx
+
+    if (lineY < clip.y || lineY >= clip.y + clip.height) continue
+
+    switch (align) {
+      case 0:
+        drawText(buffer, x, lineY, line, fg, undefined, attrs, clip)
+        break
+      case 1:
+        drawTextCentered(buffer, x, lineY, w, line, fg, undefined, attrs, clip)
+        break
+      case 2:
+        drawTextRight(buffer, x, lineY, w, line, fg, undefined, attrs, clip)
+        break
+    }
+  }
+}
+
+// =============================================================================
+// RENDER TO HISTORY
+// =============================================================================
+
+/**
+ * Create a renderToHistory function bound to a HistoryWriter and AppendRegionRenderer.
+ *
+ * The renderer is needed to coordinate:
+ * 1. Erase the active area BEFORE writing history
+ * 2. History is written (becomes permanent scrollback)
+ * 3. Next render will start fresh below the history
+ *
+ * Usage:
+ * ```ts
+ * const renderToHistory = createRenderToHistory(historyWriter, appendRegionRenderer)
+ *
+ * // When freezing content:
+ * renderToHistory(() => {
+ *   Message({ content: 'Hello!' })
+ * })
+ * ```
+ */
+export function createRenderToHistory(
+  historyWriter: HistoryWriter,
+  appendRegionRenderer: { eraseActive: () => void }
+) {
+  return function renderToHistory(componentFn: () => void): void {
+    // CRITICAL: Wrap in batch() to prevent reactive updates during this operation.
+    // Without batch, the ReactiveSet triggers updates when we allocate/release indices,
+    // causing the render effect to run mid-operation and duplicate content.
+    batch(() => {
+      // Save current allocated indices BEFORE creating history components
+      const beforeIndices = new Set(getAllocatedIndices())
+
+      // Run component function - creates new components
+      componentFn()
+
+      // Find NEW indices (ones that didn't exist before)
+      const historyIndices = new Set<number>()
+      for (const idx of getAllocatedIndices()) {
+        if (!beforeIndices.has(idx)) {
+          historyIndices.add(idx)
+        }
+      }
+
+      if (historyIndices.size === 0) {
+        return
+      }
+
+      // Get terminal width for layout
+      const tw = terminalWidth.value
+      const th = terminalHeight.value
+
+      // Compute layout for just history components
+      const layoutResult = computeLayoutTitan(tw, th, historyIndices, false)
+
+      // Build frame buffer for history components
+      const buffer = computeBufferForIndices(historyIndices, layoutResult, tw)
+
+      // STEP 2: Convert to ANSI and write to history
+      // This becomes permanent terminal scrollback
+      const output = bufferToAnsi(buffer)
+      historyWriter.write(output)
+      historyWriter.flush()
+
+      // Cleanup: release all history components
+      // Batched, so render effect won't run until after release completes.
+      // The renderer's previousHeight is already 0 from eraseActive(), so next render
+      // will simply render the active area fresh below our history output
+      for (const idx of historyIndices) {
+        releaseIndex(idx)
+      }
+    })
+  }
+}