@rlabs-inc/tui 0.3.2 → 0.5.0

package/index.ts

@@ -9,8 +9,15 @@
 export { mount } from './src/api'
 
 // Primitives - UI building blocks
-export { box, text, each, show, when, scoped, onCleanup, useAnimation, AnimationFrames } from './src/primitives'
-export type { BoxProps, TextProps, Cleanup, AnimationOptions } from './src/primitives'
+export { box, text, input, each, show, when, scoped, onCleanup, useAnimation, AnimationFrames } from './src/primitives'
+export type { BoxProps, TextProps, InputProps, CursorConfig, CursorStyle, Cleanup, AnimationOptions } from './src/primitives'
+
+// Lifecycle hooks - Component mount/destroy callbacks
+export { onMount, onDestroy } from './src/engine/lifecycle'
+
+// Context - Reactive dependency injection
+export { createContext, provide, useContext, hasContext, clearContext } from './src/state/context'
+export type { Context } from './src/state/context'
 
 // State modules - Input handling
 export { keyboard, lastKey, lastEvent } from './src/state/keyboard'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rlabs-inc/tui",
-  "version": "0.3.2",
+  "version": "0.5.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.8.2"
+    "@rlabs-inc/signals": "^1.9.0"
   }
 }

package/src/engine/arrays/interaction.ts

@@ -65,6 +65,48 @@ export const selectionStart: SlotArray<number> = slotArray<number>(-1)
 /** Selection end position */
 export const selectionEnd: SlotArray<number> = slotArray<number>(-1)
 
+// =============================================================================
+// CURSOR STYLING (for customizable cursor appearance)
+// =============================================================================
+
+/**
+ * Cursor character codepoint.
+ * 0 = use inverse block (default), >0 = custom character
+ * Presets: bar=0x2502 (│), underline=0x5F (_)
+ */
+export const cursorChar: SlotArray<number> = slotArray<number>(0)
+
+/**
+ * Cursor alternate character for blink "off" phase.
+ * 0 = space (invisible), >0 = custom character
+ */
+export const cursorAltChar: SlotArray<number> = slotArray<number>(0)
+
+/**
+ * Cursor blink rate in FPS.
+ * 0 = no blink, >0 = blink at this FPS (default would be 2 = 500ms cycle)
+ */
+export const cursorBlinkFps: SlotArray<number> = slotArray<number>(0)
+
+/**
+ * Custom cursor foreground color (packed RGBA or 0 for default).
+ * When 0, uses inverted colors from component's bg.
+ */
+export const cursorFg: SlotArray<number> = slotArray<number>(0)
+
+/**
+ * Custom cursor background color (packed RGBA or 0 for default).
+ * When 0, uses component's fg color.
+ */
+export const cursorBg: SlotArray<number> = slotArray<number>(0)
+
+/**
+ * Cursor visibility state for blink animation.
+ * 1 = visible (default), 0 = hidden
+ * Managed by input component's animation, read by frameBuffer.
+ */
+export const cursorVisible: SlotArray<number> = slotArray<number>(1)
+
 // =============================================================================
 // CAPACITY MANAGEMENT
 // =============================================================================
@@ -81,6 +123,12 @@ export function ensureCapacity(index: number): void {
   cursorPosition.ensureCapacity(index)
   selectionStart.ensureCapacity(index)
   selectionEnd.ensureCapacity(index)
+  cursorChar.ensureCapacity(index)
+  cursorAltChar.ensureCapacity(index)
+  cursorBlinkFps.ensureCapacity(index)
+  cursorFg.ensureCapacity(index)
+  cursorBg.ensureCapacity(index)
+  cursorVisible.ensureCapacity(index)
 }
 
 /** Clear slot at index (reset to default) */
@@ -95,4 +143,10 @@ export function clearAtIndex(index: number): void {
   cursorPosition.clear(index)
   selectionStart.clear(index)
   selectionEnd.clear(index)
+  cursorChar.clear(index)
+  cursorAltChar.clear(index)
+  cursorBlinkFps.clear(index)
+  cursorFg.clear(index)
+  cursorBg.clear(index)
+  cursorVisible.clear(index)
 }

package/src/engine/lifecycle.ts

@@ -0,0 +1,186 @@
+/**
+ * TUI Framework - Component Lifecycle Hooks
+ *
+ * Provides onMount and onDestroy hooks for components.
+ * Zero overhead when not used - callbacks only stored for components that opt-in.
+ *
+ * Usage:
+ * ```ts
+ * function Timer() {
+ *   const interval = setInterval(() => tick(), 1000)
+ *   onDestroy(() => clearInterval(interval))
+ *   return text({ content: 'Timer running...' })
+ * }
+ * ```
+ */
+
+// =============================================================================
+// Current Component Tracking
+// =============================================================================
+
+/**
+ * Stack of component indices currently being created.
+ * Needed because children are created synchronously inside parent's children() callback.
+ */
+const componentStack: number[] = []
+
+/**
+ * Push a component index onto the creation stack.
+ * Called by primitives (box, text) at the start of creation.
+ */
+export function pushCurrentComponent(index: number): void {
+  componentStack.push(index)
+}
+
+/**
+ * Pop a component index from the creation stack.
+ * Called by primitives (box, text) after setup is complete.
+ */
+export function popCurrentComponent(): void {
+  componentStack.pop()
+}
+
+/**
+ * Get the current component index (the one being created).
+ * Returns -1 if not inside a component creation.
+ */
+export function getCurrentComponentIndex(): number {
+  return componentStack.length > 0 ? componentStack[componentStack.length - 1]! : -1
+}
+
+// =============================================================================
+// Lifecycle Callbacks Storage
+// =============================================================================
+
+/**
+ * Mount callbacks by component index.
+ * Called after component is fully set up in arrays.
+ */
+const mountCallbacks = new Map<number, Array<() => void>>()
+
+/**
+ * Destroy callbacks by component index.
+ * Called when component is released.
+ */
+const destroyCallbacks = new Map<number, Array<() => void>>()
+
+// =============================================================================
+// Lifecycle Hook APIs
+// =============================================================================
+
+/**
+ * Register a callback to run after the current component is mounted.
+ * The callback runs synchronously after the component setup is complete.
+ *
+ * @param fn - Callback to run on mount
+ *
+ * @example
+ * ```ts
+ * function MyComponent() {
+ *   onMount(() => {
+ *     console.log('Component mounted!')
+ *     fetchInitialData()
+ *   })
+ *   return box({ ... })
+ * }
+ * ```
+ */
+export function onMount(fn: () => void): void {
+  const index = getCurrentComponentIndex()
+  if (index === -1) {
+    console.warn('onMount called outside of component creation')
+    return
+  }
+
+  let callbacks = mountCallbacks.get(index)
+  if (!callbacks) {
+    callbacks = []
+    mountCallbacks.set(index, callbacks)
+  }
+  callbacks.push(fn)
+}
+
+/**
+ * Register a callback to run when the current component is destroyed.
+ * Use for cleanup: clearing intervals, removing event listeners, etc.
+ *
+ * @param fn - Cleanup callback
+ *
+ * @example
+ * ```ts
+ * function Timer() {
+ *   const interval = setInterval(() => tick(), 1000)
+ *   onDestroy(() => clearInterval(interval))
+ *   return text({ content: 'Timer' })
+ * }
+ * ```
+ */
+export function onDestroy(fn: () => void): void {
+  const index = getCurrentComponentIndex()
+  if (index === -1) {
+    console.warn('onDestroy called outside of component creation')
+    return
+  }
+
+  let callbacks = destroyCallbacks.get(index)
+  if (!callbacks) {
+    callbacks = []
+    destroyCallbacks.set(index, callbacks)
+  }
+  callbacks.push(fn)
+}
+
+// =============================================================================
+// Internal: Run Lifecycle Callbacks
+// =============================================================================
+
+/**
+ * Run all mount callbacks for a component.
+ * Called by primitives after setup is complete.
+ */
+export function runMountCallbacks(index: number): void {
+  const callbacks = mountCallbacks.get(index)
+  if (callbacks) {
+    for (const fn of callbacks) {
+      try {
+        fn()
+      } catch (err) {
+        console.error(`Error in onMount callback for component ${index}:`, err)
+      }
+    }
+    // Don't delete - keep for potential re-mount scenarios
+  }
+}
+
+/**
+ * Run all destroy callbacks for a component.
+ * Called by releaseIndex before cleanup.
+ */
+export function runDestroyCallbacks(index: number): void {
+  const callbacks = destroyCallbacks.get(index)
+  if (callbacks) {
+    for (const fn of callbacks) {
+      try {
+        fn()
+      } catch (err) {
+        console.error(`Error in onDestroy callback for component ${index}:`, err)
+      }
+    }
+    // Clean up storage
+    destroyCallbacks.delete(index)
+    mountCallbacks.delete(index)
+  }
+}
+
+// =============================================================================
+// Reset (for testing)
+// =============================================================================
+
+/**
+ * Reset all lifecycle state (for testing)
+ */
+export function resetLifecycle(): void {
+  componentStack.length = 0
+  mountCallbacks.clear()
+  destroyCallbacks.clear()
+}

package/src/engine/registry.ts

@@ -14,6 +14,7 @@ import { ReactiveSet } from '@rlabs-inc/signals'
 import { ensureAllCapacity, clearAllAtIndex, resetAllArrays } from './arrays'
 import { parentIndex as parentIndexArray } from './arrays/core'
 import { resetTitanArrays } from '../pipeline/layout/titan-engine'
+import { runDestroyCallbacks, resetLifecycle } from './lifecycle'
 
 // =============================================================================
 // Registry State
@@ -123,6 +124,9 @@ export function releaseIndex(index: number): void {
     releaseIndex(childIndex)
   }
 
+  // Run destroy callbacks before cleanup
+  runDestroyCallbacks(index)
+
   // Clean up mappings
   idToIndex.delete(id)
   indexToId.delete(index)
@@ -192,4 +196,5 @@ export function resetRegistry(): void {
   nextIndex = 0
   idCounter = 0
   parentStack.length = 0
+  resetLifecycle()
 }

package/src/pipeline/frameBuffer.ts

@@ -16,7 +16,7 @@
  * HitGrid updates are returned as data to be applied by the render effect.
  */
 
-import { derived, neverEquals } from '@rlabs-inc/signals'
+import { derived, neverEquals, signal } from '@rlabs-inc/signals'
 import type { FrameBuffer, RGBA } from '../types'
 import { ComponentType } from '../types'
 import { Colors, TERMINAL_DEFAULT, rgbaBlend, rgbaLerp } from '../types/color'
@@ -376,7 +376,9 @@ function renderInput(
   fg: RGBA,
   clip: ClipRect
 ): void {
-  const content = text.textContent[index] || ''  // SlotArray auto-unwraps
+  // Read through slotArray proxy - same pattern as renderText
+  const rawValue = text.textContent[index]
+  const content = rawValue == null ? '' : String(rawValue)
   const attrs = text.textAttrs[index] || 0
   const cursorPos = interaction.cursorPosition[index] || 0
 
@@ -401,14 +403,38 @@ function renderInput(
   if (interaction.focusedIndex.value === index) {
     const cursorX = x + Math.min(cursorPos - displayOffset, w - 1)
     if (cursorX >= clip.x && cursorX < clip.x + clip.width && y >= clip.y && y < clip.y + clip.height) {
-      // Draw cursor as inverse block
+      // Read cursor configuration from arrays
+      const cursorCharCode = interaction.cursorChar[index] ?? 0
+      const cursorAltCharCode = interaction.cursorAltChar[index] ?? 0
+      const cursorVisible = interaction.cursorVisible[index] ?? 1
+
       const cell = buffer.cells[y]?.[cursorX]
       if (cell) {
-        const cursorChar = content[cursorPos] || ' '
-        // Swap fg/bg for cursor visibility
-        cell.char = cursorChar.codePointAt(0) ?? 32
-        cell.fg = getInheritedBg(index)
-        cell.bg = fg
+        const charUnderCursor = content[cursorPos] || ' '
+
+        if (cursorVisible === 0) {
+          // Blink "off" phase
+          if (cursorAltCharCode > 0) {
+            // Custom alt character for "off" phase
+            cell.char = cursorAltCharCode
+            cell.fg = fg
+            cell.bg = getInheritedBg(index)
+          }
+          // else: leave cell unchanged (original text shows through)
+        } else {
+          // Cursor visible
+          if (cursorCharCode === 0) {
+            // Block cursor (inverse) - swap fg/bg
+            cell.char = charUnderCursor.codePointAt(0) ?? 32
+            cell.fg = getInheritedBg(index)
+            cell.bg = fg
+          } else {
+            // Custom cursor character (bar, underline, or user-defined)
+            cell.char = cursorCharCode
+            cell.fg = fg
+            cell.bg = getInheritedBg(index)
+          }
+        }
       }
     }
   }

package/src/pipeline/layout/titan-engine.ts

@@ -127,9 +127,10 @@ const lineMainUsed: number[] = []
 // =============================================================================
 // INTRINSIC CACHE - Skip recomputation when inputs unchanged
 // =============================================================================
-// For TEXT components: cache based on text content hash + available width
+// For TEXT components: cache based on text content hash + available width + length
 // For BOX components: cache based on children intrinsics + layout props
 const cachedTextHash: bigint[] = []
+const cachedTextLength: number[] = []  // Length check prevents hash collisions
 const cachedAvailW: number[] = []
 const cachedIntrinsicW: number[] = []
 const cachedIntrinsicH: number[] = []
@@ -166,6 +167,7 @@ export function resetTitanArrays(): void {
   lineMainUsed.length = 0
   // Intrinsic cache
   cachedTextHash.length = 0
+  cachedTextLength.length = 0
   cachedAvailW.length = 0
   cachedIntrinsicW.length = 0
   cachedIntrinsicH.length = 0
@@ -269,8 +271,9 @@ export function computeLayoutTitan(
 
           // CACHE CHECK: Hash text content, compare with cached
           // Only recompute stringWidth/measureTextHeight if content or availableW changed
+          // Length check prevents hash collisions (two strings with same hash must also have same length)
           const textHash = BigInt(Bun.hash(str))
-          if (textHash === cachedTextHash[i] && availableW === cachedAvailW[i]) {
+          if (textHash === cachedTextHash[i] && availableW === cachedAvailW[i] && str.length === cachedTextLength[i]) {
             // Cache hit - reuse cached intrinsics (skip expensive computation!)
             intrinsicW[i] = cachedIntrinsicW[i]!
             intrinsicH[i] = cachedIntrinsicH[i]!
@@ -279,6 +282,7 @@ export function computeLayoutTitan(
             intrinsicW[i] = stringWidth(str)
             intrinsicH[i] = measureTextHeight(str, availableW)
             cachedTextHash[i] = textHash
+            cachedTextLength[i] = str.length
             cachedAvailW[i] = availableW
             cachedIntrinsicW[i] = intrinsicW[i]
             cachedIntrinsicH[i] = intrinsicH[i]
@@ -288,6 +292,26 @@ export function computeLayoutTitan(
           intrinsicH[i] = 0
         }
       }
+    } else if (type === ComponentType.INPUT) {
+      // INPUT: Single-line, intrinsic width from content, height always 1
+      const content = text.textContent[i]  // SlotArray auto-unwraps & tracks
+      const str = content != null ? String(content) : ''
+
+      // Get borders and padding for this input
+      const borderStyle = visual.borderStyle[i] ?? 0
+      const borderT = borderStyle > 0 || (visual.borderTop[i] ?? 0) > 0 ? 1 : 0
+      const borderR = borderStyle > 0 || (visual.borderRight[i] ?? 0) > 0 ? 1 : 0
+      const borderB = borderStyle > 0 || (visual.borderBottom[i] ?? 0) > 0 ? 1 : 0
+      const borderL = borderStyle > 0 || (visual.borderLeft[i] ?? 0) > 0 ? 1 : 0
+      const padT = spacing.paddingTop[i] ?? 0
+      const padR = spacing.paddingRight[i] ?? 0
+      const padB = spacing.paddingBottom[i] ?? 0
+      const padL = spacing.paddingLeft[i] ?? 0
+
+      // Intrinsic width: text width + padding + borders
+      intrinsicW[i] = stringWidth(str) + padL + padR + borderL + borderR
+      // Intrinsic height: 1 line + padding + borders
+      intrinsicH[i] = 1 + padT + padB + borderT + borderB
     } else {
       // BOX/Container - calculate intrinsic from children + padding + borders
       // EXCEPTION: Scrollable containers should have minimal intrinsic height
@@ -655,6 +679,17 @@ export function computeLayoutTitan(
           }
         }
 
+        // INPUT: Single-line, always height 1 (content scrolls horizontally)
+        if (core.componentType[fkid] === ComponentType.INPUT) {
+          // Add border height if borders are present
+          const borderStyle = visual.borderStyle[fkid] ?? 0
+          const borderT = borderStyle > 0 || (visual.borderTop[fkid] ?? 0) > 0 ? 1 : 0
+          const borderB = borderStyle > 0 || (visual.borderBottom[fkid] ?? 0) > 0 ? 1 : 0
+          const padT = spacing.paddingTop[fkid] ?? 0
+          const padB = spacing.paddingBottom[fkid] ?? 0
+          outH[fkid] = 1 + borderT + borderB + padT + padB
+        }
+
         // Track max extent inline (zero overhead) - include margins
         if (isRow) {
           childrenMaxMain = Math.max(childrenMaxMain, mainOffset + mLeft + outW[fkid]! + mRight)

package/src/primitives/box.ts

@@ -30,6 +30,11 @@ import {
   pushParentContext,
   popParentContext,
 } from '../engine/registry'
+import {
+  pushCurrentComponent,
+  popCurrentComponent,
+  runMountCallbacks,
+} from '../engine/lifecycle'
 import { cleanupIndex as cleanupKeyboardListeners } from '../state/keyboard'
 import { getVariantStyle } from '../state/theme'
 import { getActiveScope } from './scope'
@@ -163,6 +168,9 @@ function getStaticBool(prop: unknown, defaultVal: boolean): boolean {
 export function box(props: BoxProps = {}): Cleanup {
   const index = allocateIndex(props.id)
 
+  // Track current component for lifecycle hooks
+  pushCurrentComponent(index)
+
   // ==========================================================================
   // CORE - Always needed
   // ==========================================================================
@@ -291,6 +299,10 @@ export function box(props: BoxProps = {}): Cleanup {
     }
   }
 
+  // Component setup complete - run lifecycle callbacks
+  popCurrentComponent()
+  runMountCallbacks(index)
+
   // Cleanup function
   const cleanup = () => {
     cleanupKeyboardListeners(index)  // Remove any focused key handlers

package/src/primitives/each.ts

@@ -50,6 +50,14 @@ export function each<T>(
         for (let i = 0; i < items.length; i++) {
           const item = items[i]!
           const key = options.key(item)
+
+          // Warn about duplicate keys in the same render pass
+          if (currentKeys.has(key)) {
+            console.warn(
+              `[TUI each()] Duplicate key detected: "${key}". ` +
+                `Keys must be unique. This may cause unexpected behavior.`
+            )
+          }
           currentKeys.add(key)
 
           if (!itemSignals.has(key)) {

package/src/primitives/index.ts

@@ -7,6 +7,7 @@
 
 export { box } from './box'
 export { text } from './text'
+export { input } from './input'
 export { each } from './each'
 export { show } from './show'
 export { when } from './when'
@@ -14,6 +15,6 @@ export { scoped, onCleanup, componentScope, cleanupCollector } from './scope'
 export { useAnimation, AnimationFrames } from './animation'
 
 // Types
-export type { BoxProps, TextProps, Cleanup } from './types'
+export type { BoxProps, TextProps, InputProps, CursorConfig, CursorStyle, BlinkConfig, Cleanup } from './types'
 export type { ComponentScopeResult } from './scope'
 export type { AnimationOptions } from './animation'