@rlabs-inc/tui 0.1.0

package/src/engine/arrays/index.ts

@@ -0,0 +1,166 @@
+/**
+ * TUI Framework - Parallel Arrays
+ *
+ * All component state lives in these parallel arrays.
+ * Each array index corresponds to one component.
+ *
+ * Components write directly to these arrays.
+ * Deriveds read from these arrays and RETURN computed values.
+ *
+ * Array categories:
+ * - core: Component type, parent, visibility
+ * - dimensions: Width, height, min/max constraints
+ * - spacing: Margin, padding, gap
+ * - layout: Flexbox properties, positioning
+ * - visual: Colors, borders, opacity
+ * - text: Text content and styling
+ * - interaction: Scroll, focus, mouse state
+ */
+
+export * as core from './core'
+export * as dimensions from './dimensions'
+export * as spacing from './spacing'
+export * as layout from './layout'
+export * as visual from './visual'
+export * as text from './text'
+export * as interaction from './interaction'
+
+import { disconnectBinding } from '@rlabs-inc/signals'
+import * as core from './core'
+import * as dimensions from './dimensions'
+import * as spacing from './spacing'
+import * as layout from './layout'
+import * as visual from './visual'
+import * as text from './text'
+import * as interaction from './interaction'
+
+/**
+ * Ensure all arrays have capacity for the given index.
+ * Called by registry when allocating.
+ */
+export function ensureAllCapacity(index: number): void {
+  core.ensureCapacity(index)
+  dimensions.ensureCapacity(index)
+  spacing.ensureCapacity(index)
+  layout.ensureCapacity(index)
+  visual.ensureCapacity(index)
+  text.ensureCapacity(index)
+  interaction.ensureCapacity(index)
+}
+
+/**
+ * Clear all array values at an index.
+ * Called by registry when releasing.
+ */
+export function clearAllAtIndex(index: number): void {
+  core.clearAtIndex(index)
+  dimensions.clearAtIndex(index)
+  spacing.clearAtIndex(index)
+  layout.clearAtIndex(index)
+  visual.clearAtIndex(index)
+  text.clearAtIndex(index)
+  interaction.clearAtIndex(index)
+}
+
+/** Disconnect all bindings in an array before truncating */
+function disconnectArray(arr: unknown[]): void {
+  for (let i = 0; i < arr.length; i++) {
+    disconnectBinding(arr[i] as any)
+  }
+  arr.length = 0
+}
+
+/**
+ * Reset all parallel arrays to release memory.
+ * Called automatically when all components are destroyed (allocatedIndices.size === 0).
+ * This is the "reset on zero" cleanup - no manual API needed!
+ *
+ * IMPORTANT: Disconnects all bindings before truncating to break circular refs.
+ */
+export function resetAllArrays(): void {
+  // Core arrays
+  core.componentType.length = 0
+  disconnectArray(core.parentIndex)
+  disconnectArray(core.visible)
+  disconnectArray(core.componentId)
+
+  // Dimension arrays
+  disconnectArray(dimensions.width)
+  disconnectArray(dimensions.height)
+  disconnectArray(dimensions.minWidth)
+  disconnectArray(dimensions.minHeight)
+  disconnectArray(dimensions.maxWidth)
+  disconnectArray(dimensions.maxHeight)
+
+  // Spacing arrays
+  disconnectArray(spacing.marginTop)
+  disconnectArray(spacing.marginRight)
+  disconnectArray(spacing.marginBottom)
+  disconnectArray(spacing.marginLeft)
+  disconnectArray(spacing.paddingTop)
+  disconnectArray(spacing.paddingRight)
+  disconnectArray(spacing.paddingBottom)
+  disconnectArray(spacing.paddingLeft)
+  disconnectArray(spacing.gap)
+  disconnectArray(spacing.rowGap)
+  disconnectArray(spacing.columnGap)
+
+  // Layout arrays
+  disconnectArray(layout.flexDirection)
+  disconnectArray(layout.flexWrap)
+  disconnectArray(layout.justifyContent)
+  disconnectArray(layout.alignItems)
+  disconnectArray(layout.alignContent)
+  disconnectArray(layout.flexGrow)
+  disconnectArray(layout.flexShrink)
+  disconnectArray(layout.flexBasis)
+  disconnectArray(layout.alignSelf)
+  disconnectArray(layout.order)
+  disconnectArray(layout.position)
+  disconnectArray(layout.top)
+  disconnectArray(layout.right)
+  disconnectArray(layout.bottom)
+  disconnectArray(layout.left)
+  disconnectArray(layout.borderTop)
+  disconnectArray(layout.borderRight)
+  disconnectArray(layout.borderBottom)
+  disconnectArray(layout.borderLeft)
+  disconnectArray(layout.zIndex)
+  disconnectArray(layout.overflow)
+
+  // Visual arrays
+  disconnectArray(visual.fgColor)
+  disconnectArray(visual.bgColor)
+  disconnectArray(visual.opacity)
+  disconnectArray(visual.borderStyle)
+  disconnectArray(visual.borderColor)
+  disconnectArray(visual.borderTop)
+  disconnectArray(visual.borderRight)
+  disconnectArray(visual.borderBottom)
+  disconnectArray(visual.borderLeft)
+  disconnectArray(visual.borderColorTop)
+  disconnectArray(visual.borderColorRight)
+  disconnectArray(visual.borderColorBottom)
+  disconnectArray(visual.borderColorLeft)
+  disconnectArray(visual.showFocusRing)
+  disconnectArray(visual.focusRingColor)
+
+  // Text arrays
+  disconnectArray(text.textContent)
+  disconnectArray(text.textAttrs)
+  disconnectArray(text.textAlign)
+  disconnectArray(text.textWrap)
+  disconnectArray(text.ellipsis)
+
+  // Interaction arrays
+  disconnectArray(interaction.scrollOffsetX)
+  disconnectArray(interaction.scrollOffsetY)
+  disconnectArray(interaction.focusable)
+  disconnectArray(interaction.tabIndex)
+  disconnectArray(interaction.hovered)
+  disconnectArray(interaction.pressed)
+  disconnectArray(interaction.mouseEnabled)
+  disconnectArray(interaction.cursorPosition)
+  disconnectArray(interaction.selectionStart)
+  disconnectArray(interaction.selectionEnd)
+}

package/src/engine/arrays/interaction.ts

@@ -0,0 +1,112 @@
+/**
+ * TUI Framework - Interaction Arrays
+ *
+ * State for scroll, focus, and mouse interactions.
+ *
+ * CRITICAL: Use regular arrays (NOT state!) to preserve binding getters.
+ * state() proxies snapshot getter values, breaking reactivity.
+ *
+ * Exception: focusedIndex is a single signal, not an array.
+ *
+ * NOTE: scrollable/maxScrollX/maxScrollY are COMPUTED by TITAN layout engine
+ * and live in ComputedLayout, not here. Only scroll OFFSETS (user state) are here.
+ */
+
+import { signal, bind, disconnectBinding, type Binding } from '@rlabs-inc/signals'
+
+// =============================================================================
+// SCROLL STATE (user-controlled position only)
+// =============================================================================
+
+/** Current vertical scroll offset (user state) */
+export const scrollOffsetY: Binding<number>[] = []
+
+/** Current horizontal scroll offset (user state) */
+export const scrollOffsetX: Binding<number>[] = []
+
+// NOTE: scrollable, maxScrollX, maxScrollY are COMPUTED values from TITAN.
+// Read them from layoutDerived.value, not from interaction arrays.
+
+// =============================================================================
+// FOCUS STATE
+// =============================================================================
+
+/** Can this component receive focus */
+export const focusable: Binding<number>[] = [] // 0=no, 1=yes
+
+/** Tab order for focus navigation (-1 = not in tab order) */
+export const tabIndex: Binding<number>[] = []
+
+/** Currently focused component index (-1 = none) - SINGLE SIGNAL, not array */
+export const focusedIndex = signal(-1)
+
+// =============================================================================
+// MOUSE STATE
+// =============================================================================
+
+/** Is mouse currently hovering over this component */
+export const hovered: Binding<number>[] = [] // 0=no, 1=yes
+
+/** Is mouse button currently pressed on this component */
+export const pressed: Binding<number>[] = [] // 0=no, 1=yes
+
+/** Is mouse events enabled for this component */
+export const mouseEnabled: Binding<number>[] = [] // 0=no, 1=yes
+
+// =============================================================================
+// CURSOR STATE (for input components)
+// =============================================================================
+
+/** Cursor position in text content */
+export const cursorPosition: Binding<number>[] = []
+
+/** Selection start position (-1 = no selection) */
+export const selectionStart: Binding<number>[] = []
+
+/** Selection end position */
+export const selectionEnd: Binding<number>[] = []
+
+// =============================================================================
+// CAPACITY MANAGEMENT
+// =============================================================================
+
+/** LAZY BINDING: Push undefined, primitives create bindings for used props only */
+export function ensureCapacity(index: number): void {
+  while (scrollOffsetY.length <= index) {
+    scrollOffsetY.push(undefined as any)
+    scrollOffsetX.push(undefined as any)
+    focusable.push(undefined as any)
+    tabIndex.push(undefined as any)
+    hovered.push(undefined as any)
+    pressed.push(undefined as any)
+    mouseEnabled.push(undefined as any)
+    cursorPosition.push(undefined as any)
+    selectionStart.push(undefined as any)
+    selectionEnd.push(undefined as any)
+  }
+}
+
+export function clearAtIndex(index: number): void {
+  if (index < scrollOffsetY.length) {
+    disconnectBinding(scrollOffsetY[index])
+    disconnectBinding(scrollOffsetX[index])
+    disconnectBinding(focusable[index])
+    disconnectBinding(tabIndex[index])
+    disconnectBinding(hovered[index])
+    disconnectBinding(pressed[index])
+    disconnectBinding(mouseEnabled[index])
+    disconnectBinding(cursorPosition[index])
+    disconnectBinding(selectionStart[index])
+    disconnectBinding(selectionEnd[index])
+    scrollOffsetY[index] = undefined as any
+    scrollOffsetX[index] = undefined as any
+    focusable[index] = undefined as any
+    tabIndex[index] = undefined as any
+    hovered[index] = undefined as any
+    pressed[index] = undefined as any
+    mouseEnabled[index] = undefined as any
+    cursorPosition[index] = undefined as any
+    selectionStart[index] = undefined as any
+    selectionEnd[index] = undefined as any
+  }
+}

package/src/engine/arrays/layout.ts

@@ -0,0 +1,175 @@
+/**
+ * TUI Framework - Layout Arrays
+ *
+ * Flexbox properties, positioning, and stacking.
+ * Uses numeric enums for compact storage.
+ *
+ * CRITICAL: Use regular arrays (NOT state!) to preserve binding getters.
+ * state() proxies snapshot getter values, breaking reactivity.
+ *
+ * Flex direction: 0=column, 1=row, 2=column-reverse, 3=row-reverse
+ * Flex wrap: 0=nowrap, 1=wrap, 2=wrap-reverse
+ * Justify: 0=flex-start, 1=center, 2=flex-end, 3=space-between, 4=space-around, 5=space-evenly
+ * Align: 0=stretch, 1=flex-start, 2=center, 3=flex-end, 4=baseline
+ * Position: 0=relative, 1=absolute
+ * Overflow: 0=visible, 1=hidden, 2=scroll
+ */
+
+import { bind, disconnectBinding, type Binding } from '@rlabs-inc/signals'
+
+// =============================================================================
+// FLEX CONTAINER PROPERTIES
+// =============================================================================
+
+/** Main axis direction: 0=column, 1=row, 2=column-reverse, 3=row-reverse */
+export const flexDirection: Binding<number>[] = []
+
+/** Wrap behavior: 0=nowrap, 1=wrap, 2=wrap-reverse */
+export const flexWrap: Binding<number>[] = []
+
+/** Main axis alignment: 0=flex-start, 1=center, 2=flex-end, 3=space-between, 4=space-around, 5=space-evenly */
+export const justifyContent: Binding<number>[] = []
+
+/** Cross axis alignment for items: 0=stretch, 1=flex-start, 2=center, 3=flex-end, 4=baseline */
+export const alignItems: Binding<number>[] = []
+
+/** Cross axis alignment for wrapped lines: 0=stretch, 1=flex-start, 2=center, 3=flex-end */
+export const alignContent: Binding<number>[] = []
+
+// =============================================================================
+// FLEX ITEM PROPERTIES
+// =============================================================================
+
+/** Grow factor - how much item grows to fill space (0 = don't grow) */
+export const flexGrow: Binding<number>[] = []
+
+/** Shrink factor - how much item shrinks when overflow (1 = default, 0 = don't shrink) */
+export const flexShrink: Binding<number>[] = []
+
+/** Initial size before growing/shrinking (0 = use width/height) */
+export const flexBasis: Binding<number>[] = []
+
+/** Override alignItems for this item: 0=auto, 1=stretch, 2=flex-start, 3=center, 4=flex-end */
+export const alignSelf: Binding<number>[] = []
+
+/** Visual order override (not used yet) */
+export const order: Binding<number>[] = []
+
+// =============================================================================
+// POSITIONING
+// =============================================================================
+
+/** Position mode: 0=relative (in flow), 1=absolute (out of flow) */
+export const position: Binding<number>[] = []
+
+/** Offset from top of positioned ancestor (for absolute) or normal position (for relative) */
+export const top: Binding<number>[] = []
+
+/** Offset from right of positioned ancestor */
+export const right: Binding<number>[] = []
+
+/** Offset from bottom of positioned ancestor */
+export const bottom: Binding<number>[] = []
+
+/** Offset from left of positioned ancestor */
+export const left: Binding<number>[] = []
+
+// =============================================================================
+// BORDER (for layout calculations)
+// =============================================================================
+
+/** Has top border? 0=no, 1+=yes (takes 1 cell) */
+export const borderTop: Binding<number>[] = []
+
+/** Has right border? 0=no, 1+=yes (takes 1 cell) */
+export const borderRight: Binding<number>[] = []
+
+/** Has bottom border? 0=no, 1+=yes (takes 1 cell) */
+export const borderBottom: Binding<number>[] = []
+
+/** Has left border? 0=no, 1+=yes (takes 1 cell) */
+export const borderLeft: Binding<number>[] = []
+
+// =============================================================================
+// STACKING & OVERFLOW
+// =============================================================================
+
+/** Z-index for overlapping components (higher = on top) */
+export const zIndex: Binding<number>[] = []
+
+/** Overflow handling: 0=visible, 1=hidden, 2=scroll, 3=auto */
+export const overflow: Binding<number>[] = []
+
+/** LAZY BINDING: Push undefined, primitives create bindings for used props only */
+export function ensureCapacity(index: number): void {
+  while (flexDirection.length <= index) {
+    flexDirection.push(undefined as any)
+    flexWrap.push(undefined as any)
+    justifyContent.push(undefined as any)
+    alignItems.push(undefined as any)
+    alignContent.push(undefined as any)
+    flexGrow.push(undefined as any)
+    flexShrink.push(undefined as any)
+    flexBasis.push(undefined as any)
+    alignSelf.push(undefined as any)
+    order.push(undefined as any)
+    position.push(undefined as any)
+    top.push(undefined as any)
+    right.push(undefined as any)
+    bottom.push(undefined as any)
+    left.push(undefined as any)
+    borderTop.push(undefined as any)
+    borderRight.push(undefined as any)
+    borderBottom.push(undefined as any)
+    borderLeft.push(undefined as any)
+    zIndex.push(undefined as any)
+    overflow.push(undefined as any)
+  }
+}
+
+export function clearAtIndex(index: number): void {
+  if (index < flexDirection.length) {
+    disconnectBinding(flexDirection[index])
+    disconnectBinding(flexWrap[index])
+    disconnectBinding(justifyContent[index])
+    disconnectBinding(alignItems[index])
+    disconnectBinding(alignContent[index])
+    disconnectBinding(flexGrow[index])
+    disconnectBinding(flexShrink[index])
+    disconnectBinding(flexBasis[index])
+    disconnectBinding(alignSelf[index])
+    disconnectBinding(order[index])
+    disconnectBinding(position[index])
+    disconnectBinding(top[index])
+    disconnectBinding(right[index])
+    disconnectBinding(bottom[index])
+    disconnectBinding(left[index])
+    disconnectBinding(borderTop[index])
+    disconnectBinding(borderRight[index])
+    disconnectBinding(borderBottom[index])
+    disconnectBinding(borderLeft[index])
+    disconnectBinding(zIndex[index])
+    disconnectBinding(overflow[index])
+    flexDirection[index] = undefined as any
+    flexWrap[index] = undefined as any
+    justifyContent[index] = undefined as any
+    alignItems[index] = undefined as any
+    alignContent[index] = undefined as any
+    flexGrow[index] = undefined as any
+    flexShrink[index] = undefined as any
+    flexBasis[index] = undefined as any
+    alignSelf[index] = undefined as any
+    order[index] = undefined as any
+    position[index] = undefined as any
+    top[index] = undefined as any
+    right[index] = undefined as any
+    bottom[index] = undefined as any
+    left[index] = undefined as any
+    borderTop[index] = undefined as any
+    borderRight[index] = undefined as any
+    borderBottom[index] = undefined as any
+    borderLeft[index] = undefined as any
+    zIndex[index] = undefined as any
+    overflow[index] = undefined as any
+  }
+}

package/src/engine/arrays/spacing.ts

@@ -0,0 +1,100 @@
+/**
+ * TUI Framework - Spacing Arrays
+ *
+ * Margin, padding, and gap values.
+ * All values are in terminal cells (integers).
+ *
+ * CRITICAL: Use regular arrays (NOT state!) to preserve binding getters.
+ * state() proxies snapshot getter values, breaking reactivity.
+ */
+
+import { bind, disconnectBinding, type Binding } from '@rlabs-inc/signals'
+
+// =============================================================================
+// MARGIN - Space outside the component (offsets position in parent)
+// =============================================================================
+
+/** Top margin - adds space above the component (in cells) */
+export const marginTop: Binding<number>[] = []
+
+/** Right margin - adds space to the right of the component (in cells) */
+export const marginRight: Binding<number>[] = []
+
+/** Bottom margin - adds space below the component (in cells) */
+export const marginBottom: Binding<number>[] = []
+
+/** Left margin - adds space to the left of the component (in cells) */
+export const marginLeft: Binding<number>[] = []
+
+// =============================================================================
+// PADDING - Space inside the component (reduces content area)
+// =============================================================================
+
+/** Top padding - pushes content down from top edge (in cells) */
+export const paddingTop: Binding<number>[] = []
+
+/** Right padding - pushes content left from right edge (in cells) */
+export const paddingRight: Binding<number>[] = []
+
+/** Bottom padding - pushes content up from bottom edge (in cells) */
+export const paddingBottom: Binding<number>[] = []
+
+/** Left padding - pushes content right from left edge (in cells) */
+export const paddingLeft: Binding<number>[] = []
+
+// =============================================================================
+// GAP - Space between flex items (CSS gap property)
+// =============================================================================
+
+/** Gap between flex items in both directions (in cells) */
+export const gap: Binding<number>[] = []
+
+/** Row gap - vertical space between wrapped lines (in cells) */
+export const rowGap: Binding<number>[] = []
+
+/** Column gap - horizontal space between items in a row (in cells) */
+export const columnGap: Binding<number>[] = []
+
+/** LAZY BINDING: Push undefined, primitives create bindings for used props only */
+export function ensureCapacity(index: number): void {
+  while (marginTop.length <= index) {
+    marginTop.push(undefined as any)
+    marginRight.push(undefined as any)
+    marginBottom.push(undefined as any)
+    marginLeft.push(undefined as any)
+    paddingTop.push(undefined as any)
+    paddingRight.push(undefined as any)
+    paddingBottom.push(undefined as any)
+    paddingLeft.push(undefined as any)
+    gap.push(undefined as any)
+    rowGap.push(undefined as any)
+    columnGap.push(undefined as any)
+  }
+}
+
+export function clearAtIndex(index: number): void {
+  if (index < marginTop.length) {
+    disconnectBinding(marginTop[index])
+    disconnectBinding(marginRight[index])
+    disconnectBinding(marginBottom[index])
+    disconnectBinding(marginLeft[index])
+    disconnectBinding(paddingTop[index])
+    disconnectBinding(paddingRight[index])
+    disconnectBinding(paddingBottom[index])
+    disconnectBinding(paddingLeft[index])
+    disconnectBinding(gap[index])
+    disconnectBinding(rowGap[index])
+    disconnectBinding(columnGap[index])
+    marginTop[index] = undefined as any
+    marginRight[index] = undefined as any
+    marginBottom[index] = undefined as any
+    marginLeft[index] = undefined as any
+    paddingTop[index] = undefined as any
+    paddingRight[index] = undefined as any
+    paddingBottom[index] = undefined as any
+    paddingLeft[index] = undefined as any
+    gap[index] = undefined as any
+    rowGap[index] = undefined as any
+    columnGap[index] = undefined as any
+  }
+}

package/src/engine/arrays/text.ts

@@ -0,0 +1,55 @@
+/**
+ * TUI Framework - Text Arrays
+ *
+ * Text content and styling for text/input components.
+ *
+ * CRITICAL: Use regular arrays (NOT state!) to preserve binding getters.
+ * state() proxies snapshot getter values, breaking reactivity.
+ *
+ * Flow: user signal → bind() → Binding stored → unwrap() reads .value → dependency!
+ */
+
+import { bind, disconnectBinding, type Binding } from '@rlabs-inc/signals'
+import type { CellAttrs } from '../../types'
+import { Attr } from '../../types'
+
+// Text content - Regular array to preserve binding getters
+export const textContent: Binding<string>[] = []
+
+// Text styling (CellAttrs bitfield)
+export const textAttrs: Binding<CellAttrs>[] = []
+
+// Text alignment: 0=left, 1=center, 2=right
+export const textAlign: Binding<number>[] = []
+
+// Text wrapping: 0=nowrap, 1=wrap, 2=truncate
+export const textWrap: Binding<number>[] = []
+
+// Ellipsis for truncated text
+export const ellipsis: Binding<string>[] = []
+
+/** LAZY BINDING: Push undefined, primitives create bindings for used props only */
+export function ensureCapacity(index: number): void {
+  while (textContent.length <= index) {
+    textContent.push(undefined as any)
+    textAttrs.push(undefined as any)
+    textAlign.push(undefined as any)
+    textWrap.push(undefined as any)
+    ellipsis.push(undefined as any)
+  }
+}
+
+export function clearAtIndex(index: number): void {
+  if (index < textContent.length) {
+    disconnectBinding(textContent[index])
+    disconnectBinding(textAttrs[index])
+    disconnectBinding(textAlign[index])
+    disconnectBinding(textWrap[index])
+    disconnectBinding(ellipsis[index])
+    textContent[index] = undefined as any
+    textAttrs[index] = undefined as any
+    textAlign[index] = undefined as any
+    textWrap[index] = undefined as any
+    ellipsis[index] = undefined as any
+  }
+}