@rlabs-inc/tui 0.1.0

package/src/engine/arrays/visual.ts

@@ -0,0 +1,140 @@
+/**
+ * TUI Framework - Visual Arrays
+ *
+ * Colors, borders, and visual styling.
+ * Colors stored as RGBA objects for alpha blending support.
+ *
+ * CRITICAL: Use regular arrays (NOT state!) to preserve binding getters.
+ * state() proxies snapshot getter values, breaking reactivity.
+ *
+ * Border styles:
+ *   0 = none
+ *   1 = single   (─ │ ┌ ┐ └ ┘)
+ *   2 = double   (═ ║ ╔ ╗ ╚ ╝)
+ *   3 = rounded  (─ │ ╭ ╮ ╰ ╯)
+ *   4 = heavy    (━ ┃ ┏ ┓ ┗ ┛)
+ *   5 = dashed   (╌ ╎ ┌ ┐ └ ┘)
+ *   6 = dotted   (· · · · · ·)
+ *   7 = ascii    (- | + + + +)
+ *   8 = block    (█ █ █ █ █ █)
+ *   9 = mixedDoubleH (═ │ ╒ ╕ ╘ ╛)
+ *  10 = mixedDoubleV (─ ║ ╓ ╖ ╙ ╜)
+ *
+ * Per-side borders can have independent styles.
+ */
+
+import { bind, disconnectBinding, type Binding } from '@rlabs-inc/signals'
+import type { RGBA } from '../../types'
+
+// =============================================================================
+// COLORS - Regular arrays to preserve binding reactivity
+// =============================================================================
+
+/** Foreground color (text) - null means inherit from parent */
+export const fgColor: Binding<RGBA | null>[] = []
+
+/** Background color - null means transparent/inherit */
+export const bgColor: Binding<RGBA | null>[] = []
+
+/** Opacity 0-1 (1 = fully opaque) */
+export const opacity: Binding<number>[] = []
+
+// =============================================================================
+// BORDERS - Per-side independent styles
+// =============================================================================
+
+/** Default border style for all sides (0-10) */
+export const borderStyle: Binding<number>[] = []
+
+/** Default border color for all sides - null means use foreground */
+export const borderColor: Binding<RGBA | null>[] = []
+
+/** Top border style (0=none or inherit from borderStyle, 1-10=specific style) */
+export const borderTop: Binding<number>[] = []
+
+/** Right border style */
+export const borderRight: Binding<number>[] = []
+
+/** Bottom border style */
+export const borderBottom: Binding<number>[] = []
+
+/** Left border style */
+export const borderLeft: Binding<number>[] = []
+
+/** Per-side border colors - null means use borderColor or foreground */
+export const borderColorTop: Binding<RGBA | null>[] = []
+export const borderColorRight: Binding<RGBA | null>[] = []
+export const borderColorBottom: Binding<RGBA | null>[] = []
+export const borderColorLeft: Binding<RGBA | null>[] = []
+
+// =============================================================================
+// FOCUS RING
+// =============================================================================
+
+/** Show focus ring when focused (1=yes, 0=no) */
+export const showFocusRing: Binding<number>[] = []
+
+/** Focus ring color */
+export const focusRingColor: Binding<RGBA>[] = []
+
+// =============================================================================
+// DEFAULT VALUES
+// =============================================================================
+
+const DEFAULT_FOCUS_COLOR: RGBA = { r: 100, g: 149, b: 237, a: 255 } // cornflowerblue
+
+/** LAZY BINDING: Push undefined, primitives create bindings for used props only */
+export function ensureCapacity(index: number): void {
+  while (fgColor.length <= index) {
+    fgColor.push(undefined as any)
+    bgColor.push(undefined as any)
+    opacity.push(undefined as any)
+    borderStyle.push(undefined as any)
+    borderColor.push(undefined as any)
+    borderTop.push(undefined as any)
+    borderRight.push(undefined as any)
+    borderBottom.push(undefined as any)
+    borderLeft.push(undefined as any)
+    borderColorTop.push(undefined as any)
+    borderColorRight.push(undefined as any)
+    borderColorBottom.push(undefined as any)
+    borderColorLeft.push(undefined as any)
+    showFocusRing.push(undefined as any)
+    focusRingColor.push(undefined as any)
+  }
+}
+
+export function clearAtIndex(index: number): void {
+  if (index < fgColor.length) {
+    disconnectBinding(fgColor[index])
+    disconnectBinding(bgColor[index])
+    disconnectBinding(opacity[index])
+    disconnectBinding(borderStyle[index])
+    disconnectBinding(borderColor[index])
+    disconnectBinding(borderTop[index])
+    disconnectBinding(borderRight[index])
+    disconnectBinding(borderBottom[index])
+    disconnectBinding(borderLeft[index])
+    disconnectBinding(borderColorTop[index])
+    disconnectBinding(borderColorRight[index])
+    disconnectBinding(borderColorBottom[index])
+    disconnectBinding(borderColorLeft[index])
+    disconnectBinding(showFocusRing[index])
+    disconnectBinding(focusRingColor[index])
+    fgColor[index] = undefined as any
+    bgColor[index] = undefined as any
+    opacity[index] = undefined as any
+    borderStyle[index] = undefined as any
+    borderColor[index] = undefined as any
+    borderTop[index] = undefined as any
+    borderRight[index] = undefined as any
+    borderBottom[index] = undefined as any
+    borderLeft[index] = undefined as any
+    borderColorTop[index] = undefined as any
+    borderColorRight[index] = undefined as any
+    borderColorBottom[index] = undefined as any
+    borderColorLeft[index] = undefined as any
+    showFocusRing[index] = undefined as any
+    focusRingColor[index] = undefined as any
+  }
+}

package/src/engine/index.ts

@@ -0,0 +1,25 @@
+/**
+ * TUI Framework - Engine
+ *
+ * The component engine using parallel arrays pattern.
+ * Components allocate indices and write to arrays.
+ * Deriveds read arrays and RETURN computed values.
+ */
+
+// Registry
+export {
+  allocateIndex,
+  releaseIndex,
+  getIndex,
+  getId,
+  getAllocatedIndices,
+  isAllocated,
+  getAllocatedCount,
+  getCurrentParentIndex,
+  pushParentContext,
+  popParentContext,
+  resetRegistry,
+} from './registry'
+
+// Parallel arrays
+export * as arrays from './arrays'

package/src/engine/inheritance.ts

@@ -0,0 +1,138 @@
+/**
+ * TUI Framework - Color and Style Inheritance
+ *
+ * Utilities for walking up the component tree to inherit colors and styles.
+ * Used when a component has null colors (meaning "inherit from parent").
+ */
+
+import { unwrap } from '@rlabs-inc/signals'
+import type { RGBA } from '../types'
+import { Colors, TERMINAL_DEFAULT } from '../types/color'
+import * as core from './arrays/core'
+import * as visual from './arrays/visual'
+
+/**
+ * Get inherited foreground color by walking up the parent tree.
+ * Returns TERMINAL_DEFAULT if no explicit color is found.
+ */
+export function getInheritedFg(index: number): RGBA {
+  let current: number = index
+
+  while (current >= 0) {
+    const fg = unwrap(visual.fgColor[current])
+    if (fg !== null && fg !== undefined) return fg
+    const parent = unwrap(core.parentIndex[current])
+    if (parent === undefined || parent < 0) break
+    current = parent
+  }
+
+  return TERMINAL_DEFAULT
+}
+
+/**
+ * Get inherited background color by walking up the parent tree.
+ * Returns TERMINAL_DEFAULT if no explicit color is found.
+ */
+export function getInheritedBg(index: number): RGBA {
+  let current: number = index
+
+  while (current >= 0) {
+    const bg = unwrap(visual.bgColor[current])
+    if (bg !== null && bg !== undefined) return bg
+    const parent = unwrap(core.parentIndex[current])
+    if (parent === undefined || parent < 0) break
+    current = parent
+  }
+
+  return TERMINAL_DEFAULT
+}
+
+/**
+ * Get inherited border color for a specific side.
+ * Falls back to unified border color, then foreground color.
+ */
+export function getInheritedBorderColor(index: number, side: 'top' | 'right' | 'bottom' | 'left'): RGBA {
+  const colorArray = {
+    top: visual.borderColorTop,
+    right: visual.borderColorRight,
+    bottom: visual.borderColorBottom,
+    left: visual.borderColorLeft,
+  }[side]
+
+  const color = unwrap(colorArray[index])
+  if (color !== null && color !== undefined) return color
+
+  // Try unified border color
+  const unifiedColor = unwrap(visual.borderColor[index])
+  if (unifiedColor !== null && unifiedColor !== undefined) return unifiedColor
+
+  // Fall back to foreground color
+  return getInheritedFg(index)
+}
+
+/**
+ * Get all four border colors for a component.
+ */
+export function getBorderColors(index: number): {
+  top: RGBA
+  right: RGBA
+  bottom: RGBA
+  left: RGBA
+} {
+  const fg = getInheritedFg(index)
+  const unified = unwrap(visual.borderColor[index])
+  const fallback = unified ?? fg
+
+  return {
+    top: unwrap(visual.borderColorTop[index]) ?? fallback,
+    right: unwrap(visual.borderColorRight[index]) ?? fallback,
+    bottom: unwrap(visual.borderColorBottom[index]) ?? fallback,
+    left: unwrap(visual.borderColorLeft[index]) ?? fallback,
+  }
+}
+
+/**
+ * Get all four border styles for a component.
+ * Falls back to the unified borderStyle if per-side not set.
+ */
+export function getBorderStyles(index: number): {
+  top: number
+  right: number
+  bottom: number
+  left: number
+} {
+  const unified = unwrap(visual.borderStyle[index]) || 0
+
+  return {
+    top: unwrap(visual.borderTop[index]) || unified,
+    right: unwrap(visual.borderRight[index]) || unified,
+    bottom: unwrap(visual.borderBottom[index]) || unified,
+    left: unwrap(visual.borderLeft[index]) || unified,
+  }
+}
+
+/**
+ * Check if a component has any border.
+ */
+export function hasBorder(index: number): boolean {
+  const styles = getBorderStyles(index)
+  return styles.top > 0 || styles.right > 0 || styles.bottom > 0 || styles.left > 0
+}
+
+/**
+ * Get effective opacity by multiplying down the parent chain.
+ */
+export function getEffectiveOpacity(index: number): number {
+  let opacity = 1
+  let current: number | undefined = index
+
+  while (current !== undefined && current >= 0) {
+    const nodeOpacity = unwrap(visual.opacity[current])
+    if (nodeOpacity !== undefined && nodeOpacity !== 1) {
+      opacity *= nodeOpacity
+    }
+    current = unwrap(core.parentIndex[current])
+  }
+
+  return opacity
+}

package/src/engine/registry.ts

@@ -0,0 +1,180 @@
+/**
+ * TUI Framework - Component Registry
+ *
+ * Manages index allocation for the parallel arrays pattern.
+ * Each component gets a unique index, which is used across all arrays.
+ *
+ * Features:
+ * - ID ↔ Index bidirectional mapping
+ * - Free index pool for O(1) reuse
+ * - ReactiveSet for allocatedIndices (deriveds react to add/remove)
+ */
+
+import { ReactiveSet } from '@rlabs-inc/signals'
+import { ensureAllCapacity, clearAllAtIndex, resetAllArrays } from './arrays'
+import { resetTitanArrays } from '../pipeline/layout/titan-engine'
+
+// =============================================================================
+// Registry State
+// =============================================================================
+
+/** Map component ID to array index */
+const idToIndex = new Map<string, number>()
+
+/** Map array index to component ID */
+const indexToId = new Map<number, string>()
+
+/**
+ * Set of currently allocated indices (for iteration).
+ *
+ * Using ReactiveSet so deriveds that iterate over this set
+ * automatically react when components are added or removed.
+ */
+const allocatedIndices = new ReactiveSet<number>()
+
+/** Pool of freed indices for reuse */
+const freeIndices: number[] = []
+
+/** Next index to allocate if pool is empty */
+let nextIndex = 0
+
+/** Counter for generating unique IDs */
+let idCounter = 0
+
+// =============================================================================
+// Parent Context Stack
+// =============================================================================
+
+/** Stack of parent indices for nested component creation */
+const parentStack: number[] = []
+
+/** Get current parent index (-1 if at root) */
+export function getCurrentParentIndex(): number {
+  return parentStack.length > 0 ? (parentStack[parentStack.length - 1] ?? -1) : -1
+}
+
+/** Push a parent index onto the stack */
+export function pushParentContext(index: number): void {
+  parentStack.push(index)
+}
+
+/** Pop a parent index from the stack */
+export function popParentContext(): void {
+  parentStack.pop()
+}
+
+// =============================================================================
+// Index Allocation
+// =============================================================================
+
+/**
+ * Allocate an index for a new component.
+ *
+ * @param id - Optional component ID. If not provided, one is generated.
+ * @returns The allocated index.
+ */
+export function allocateIndex(id?: string): number {
+  // Generate ID if not provided
+  const componentId = id ?? `c${idCounter++}`
+
+  // Check if already allocated
+  const existing = idToIndex.get(componentId)
+  if (existing !== undefined) {
+    return existing
+  }
+
+  // Reuse free index or allocate new
+  const index = freeIndices.length > 0
+    ? freeIndices.pop()!
+    : nextIndex++
+
+  // Register mappings
+  idToIndex.set(componentId, index)
+  indexToId.set(index, componentId)
+  allocatedIndices.add(index)
+
+  // Ensure arrays have capacity for this index
+  ensureAllCapacity(index)
+
+  return index
+}
+
+/**
+ * Release an index back to the pool.
+ *
+ * @param index - The index to release.
+ */
+export function releaseIndex(index: number): void {
+  const id = indexToId.get(index)
+  if (id === undefined) return
+
+  // Clean up mappings
+  idToIndex.delete(id)
+  indexToId.delete(index)
+  allocatedIndices.delete(index)
+
+  // Clear all array values at this index
+  clearAllAtIndex(index)
+
+  // Return to pool for reuse
+  freeIndices.push(index)
+
+  // AUTO-CLEANUP: When all components destroyed, reset all arrays to free memory
+  if (allocatedIndices.size === 0) {
+    resetAllArrays()
+    resetTitanArrays()
+    freeIndices.length = 0
+    nextIndex = 0
+    // Note: GC is NOT forced here to avoid performance hit during rapid create/destroy cycles
+    // The FinalizationRegistry will clean up automatically when GC runs naturally
+  }
+}
+
+// =============================================================================
+// Lookups
+// =============================================================================
+
+/** Get index for a component ID */
+export function getIndex(id: string): number | undefined {
+  return idToIndex.get(id)
+}
+
+/** Get ID for an index */
+export function getId(index: number): string | undefined {
+  return indexToId.get(index)
+}
+
+/** Get all currently allocated indices */
+export function getAllocatedIndices(): Set<number> {
+  return allocatedIndices
+}
+
+/** Check if an index is currently allocated */
+export function isAllocated(index: number): boolean {
+  return allocatedIndices.has(index)
+}
+
+/** Get the current capacity (highest index that would be allocated next) */
+export function getCapacity(): number {
+  return nextIndex
+}
+
+/** Get the count of currently allocated components */
+export function getAllocatedCount(): number {
+  return allocatedIndices.size
+}
+
+// =============================================================================
+// Reset (for testing)
+// =============================================================================
+
+/** Reset all registry state (for testing) */
+export function resetRegistry(): void {
+  idToIndex.clear()
+  indexToId.clear()
+  allocatedIndices.clear()
+  freeIndices.length = 0
+  nextIndex = 0
+  idCounter = 0
+  parentStack.length = 0
+}