@rlabs-inc/tui 0.1.0

package/src/pipeline/layout/types.ts

@@ -0,0 +1,194 @@
+/**
+ * TUI Framework - Layout Engine Types
+ *
+ * THE terminal layout system. Not just Flexbox - everything.
+ *
+ * Features:
+ * - Full Flexbox (6-phase algorithm with freeze loop)
+ * - Grid layout (coming soon)
+ * - Fixed/Absolute/Relative positioning
+ * - Animation & transitions support (built into the architecture)
+ *
+ * Pure parallel arrays - NO objects for working data.
+ * Every array is indexed by component index.
+ */
+
+// =============================================================================
+// OUTPUT TYPES (same interface as current Yoga integration)
+// =============================================================================
+
+export interface ComputedLayout {
+  x: number[]
+  y: number[]
+  width: number[]
+  height: number[]
+  scrollable: number[]
+  maxScrollY: number[]
+  maxScrollX: number[]
+  // Content bounds (max extent of all components)
+  contentWidth: number   // Max x + width across all components
+  contentHeight: number  // Max y + height across all components
+}
+
+// =============================================================================
+// FLEX DIRECTION AND WRAP ENUMS
+// =============================================================================
+
+export const FlexDirection = {
+  COLUMN: 0,
+  ROW: 1,
+  COLUMN_REVERSE: 2,
+  ROW_REVERSE: 3,
+} as const
+
+export const FlexWrap = {
+  NO_WRAP: 0,
+  WRAP: 1,
+  WRAP_REVERSE: 2,
+} as const
+
+export const JustifyContent = {
+  FLEX_START: 0,
+  CENTER: 1,
+  FLEX_END: 2,
+  SPACE_BETWEEN: 3,
+  SPACE_AROUND: 4,
+  SPACE_EVENLY: 5,
+} as const
+
+export const AlignItems = {
+  STRETCH: 0,
+  FLEX_START: 1,
+  CENTER: 2,
+  FLEX_END: 3,
+  BASELINE: 4,
+} as const
+
+// =============================================================================
+// POSITIONING
+// =============================================================================
+
+export const Position = {
+  RELATIVE: 0,    // Normal flow, offsets relative to normal position
+  ABSOLUTE: 1,    // Out of flow, positioned relative to nearest positioned ancestor
+  FIXED: 2,       // Out of flow, positioned relative to terminal viewport
+  STICKY: 3,      // Hybrid - relative until scroll threshold, then fixed
+} as const
+
+// =============================================================================
+// DISPLAY MODE (for future Grid support)
+// =============================================================================
+
+export const Display = {
+  FLEX: 0,        // Flexbox layout
+  GRID: 1,        // Grid layout (future)
+  NONE: 2,        // Hidden, not in layout
+} as const
+
+// =============================================================================
+// OVERFLOW (for scroll containers)
+// =============================================================================
+
+export const Overflow = {
+  VISIBLE: 0,     // Content can overflow
+  HIDDEN: 1,      // Content clipped
+  SCROLL: 2,      // Scrollable
+  AUTO: 3,        // Scroll only if needed
+} as const
+
+// =============================================================================
+// WORKING DATA - Pure Parallel Arrays
+// =============================================================================
+
+/**
+ * All working data for layout computation.
+ * Every array is indexed by component index.
+ * Pre-allocated for performance, reset each layout pass.
+ */
+export interface WorkingData {
+  // Hierarchy (computed once per layout)
+  depth: number[]              // Nesting depth (root = 0)
+  childStart: number[]         // Index into childrenOrdered
+  childCount: number[]         // Number of direct children
+
+  // Flex working data
+  flexBaseSize: number[]       // Initial size before flex
+  hypotheticalMainSize: number[] // Clamped by min/max
+  targetMainSize: number[]     // Size after flex distribution
+  targetCrossSize: number[]    // Cross axis size
+  frozen: Uint8Array           // 0 = unfrozen, 1 = frozen
+
+  // Final computed values
+  computedX: number[]
+  computedY: number[]
+  computedWidth: number[]
+  computedHeight: number[]
+
+  // Scroll detection
+  contentWidth: number[]       // Total content width
+  contentHeight: number[]      // Total content height
+}
+
+/**
+ * Line data for flex wrap.
+ * Stored separately since number of lines varies per container.
+ */
+export interface LineData {
+  // Per-container line info
+  lineStart: number[]          // Index into items array where lines begin
+  lineCount: number[]          // Number of lines in this container
+
+  // Flattened line items (all lines concatenated)
+  items: number[][]            // items[lineIndex] = array of component indices
+
+  // Per-line computed data
+  lineCrossSize: number[]      // Cross size of each line
+}
+
+// =============================================================================
+// HELPER TYPES
+// =============================================================================
+
+export type FlexDirectionValue = typeof FlexDirection[keyof typeof FlexDirection]
+export type FlexWrapValue = typeof FlexWrap[keyof typeof FlexWrap]
+export type JustifyContentValue = typeof JustifyContent[keyof typeof JustifyContent]
+export type AlignItemsValue = typeof AlignItems[keyof typeof AlignItems]
+export type PositionValue = typeof Position[keyof typeof Position]
+export type DisplayValue = typeof Display[keyof typeof Display]
+export type OverflowValue = typeof Overflow[keyof typeof Overflow]
+
+// =============================================================================
+// ANIMATION TYPES (built into architecture from day 1)
+// =============================================================================
+
+export interface TransitionConfig {
+  property: string           // Which property to animate
+  duration: number           // Duration in ms
+  easing: EasingFunction     // Easing function
+  delay: number              // Delay before start
+}
+
+export type EasingFunction =
+  | 'linear'
+  | 'ease'
+  | 'ease-in'
+  | 'ease-out'
+  | 'ease-in-out'
+  | 'step-start'
+  | 'step-end'
+  | ((t: number) => number)  // Custom easing function
+
+// Animation state per component (for future use)
+export interface AnimationState {
+  startValue: number
+  endValue: number
+  startTime: number
+  duration: number
+  easing: EasingFunction
+}
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+export const INFINITY = 999999  // Terminal has finite size, use large number

package/src/pipeline/layout/utils/hierarchy.ts

@@ -0,0 +1,202 @@
+/**
+ * TUI Framework - Hierarchy Utilities
+ *
+ * Builds hierarchy data from parallel arrays for efficient iteration.
+ * NO recursion - just flat loops over arrays.
+ *
+ * Key insight: Instead of walking a tree, we:
+ * 1. Calculate depth for each component (one loop)
+ * 2. Group children by parent (one loop)
+ * 3. Build ordered children array (one loop)
+ *
+ * Result: O(n) regardless of nesting depth.
+ */
+
+import { unwrap } from '@rlabs-inc/signals'
+import * as core from '../../../engine/arrays/core'
+import * as layout from '../../../engine/arrays/layout'
+
+// =============================================================================
+// HIERARCHY DATA (reused across layouts)
+// =============================================================================
+
+// Depth of each component (root = 0)
+export const depth: number[] = []
+
+// Children organization
+export const childStart: number[] = []   // Index into childrenOrdered
+export const childCount: number[] = []   // Number of direct children
+
+// Flat array of all children, ordered by parent
+export const childrenOrdered: number[] = []
+
+// Root components (parentIndex === -1)
+export const roots: number[] = []
+
+// Components sorted by depth (for bottom-up/top-down iteration)
+export const sortedByDepth: number[] = []
+
+// Maximum depth in the tree
+export let maxDepth = 0
+
+// =============================================================================
+// HIERARCHY PREPARATION
+// =============================================================================
+
+/**
+ * Prepare hierarchy data for layout.
+ * Called once at the start of each layout pass.
+ *
+ * This replaces recursive tree traversal with flat array iteration.
+ */
+export function prepareHierarchy(indices: Set<number>): void {
+  // Reset arrays
+  roots.length = 0
+  childrenOrdered.length = 0
+  sortedByDepth.length = 0
+  maxDepth = 0
+
+  if (indices.size === 0) return
+
+  // Step 1: Calculate depth for each component
+  // This is the only "recursive-like" part, but we do it iteratively
+  for (const i of indices) {
+    let d = 0
+    let p = unwrap(core.parentIndex[i]) ?? -1
+
+    // Walk up to root, counting depth
+    while (p >= 0 && indices.has(p)) {
+      d++
+      p = unwrap(core.parentIndex[p]) ?? -1
+    }
+
+    depth[i] = d
+    if (d > maxDepth) maxDepth = d
+
+    // Track roots
+    if (d === 0) {
+      roots.push(i)
+    }
+  }
+
+  // Step 2: Group children by parent
+  const childrenByParent = new Map<number, number[]>()
+
+  for (const i of indices) {
+    const parent = unwrap(core.parentIndex[i]) ?? -1
+
+    if (parent >= 0) {
+      let children = childrenByParent.get(parent)
+      if (!children) {
+        children = []
+        childrenByParent.set(parent, children)
+      }
+      children.push(i)
+    }
+  }
+
+  // Step 3: Sort children within each parent by order property
+  for (const children of childrenByParent.values()) {
+    children.sort((a, b) => {
+      const orderA = unwrap(layout.order[a]) ?? 0
+      const orderB = unwrap(layout.order[b]) ?? 0
+      return orderA - orderB
+    })
+  }
+
+  // Step 4: Build childrenOrdered array and set childStart/childCount
+  let offset = 0
+
+  for (const i of indices) {
+    const children = childrenByParent.get(i)
+
+    if (children && children.length > 0) {
+      childStart[i] = offset
+      childCount[i] = children.length
+
+      for (const child of children) {
+        childrenOrdered[offset++] = child
+      }
+    } else {
+      childStart[i] = 0
+      childCount[i] = 0
+    }
+  }
+
+  // Step 5: Sort all indices by depth
+  for (const i of indices) {
+    sortedByDepth.push(i)
+  }
+  sortedByDepth.sort((a, b) => depth[a]! - depth[b]!)
+}
+
+/**
+ * Get children of a component.
+ * Returns array slice from childrenOrdered.
+ */
+export function getChildren(index: number): number[] {
+  const start = childStart[index] ?? 0
+  const count = childCount[index] ?? 0
+
+  if (count === 0) return []
+
+  const result: number[] = []
+  for (let i = 0; i < count; i++) {
+    result.push(childrenOrdered[start + i]!)
+  }
+  return result
+}
+
+/**
+ * Check if component has children.
+ */
+export function hasChildren(index: number): boolean {
+  return (childCount[index] ?? 0) > 0
+}
+
+/**
+ * Get depth of a component.
+ */
+export function getDepth(index: number): number {
+  return depth[index] ?? 0
+}
+
+/**
+ * Iterate components in depth order (roots first, then children).
+ * Useful for top-down traversal.
+ */
+export function* iterateTopDown(): Generator<number> {
+  for (const i of sortedByDepth) {
+    yield i
+  }
+}
+
+/**
+ * Iterate components in reverse depth order (deepest first).
+ * Useful for bottom-up traversal (content sizing).
+ */
+export function* iterateBottomUp(): Generator<number> {
+  for (let i = sortedByDepth.length - 1; i >= 0; i--) {
+    yield sortedByDepth[i]!
+  }
+}
+
+/**
+ * Get the root components.
+ */
+export function getRoots(): number[] {
+  return roots
+}
+
+/**
+ * Reset hierarchy data (called when clearing layout).
+ */
+export function resetHierarchy(): void {
+  depth.length = 0
+  childStart.length = 0
+  childCount.length = 0
+  childrenOrdered.length = 0
+  roots.length = 0
+  sortedByDepth.length = 0
+  maxDepth = 0
+}

package/src/pipeline/layout/utils/math.ts

@@ -0,0 +1,134 @@
+/**
+ * TUI Framework - Layout Math Utilities
+ *
+ * Integer-only math for terminal cells.
+ * No sub-pixel nonsense - terminals work in discrete cells.
+ */
+
+/**
+ * Clamp a value between min and max.
+ * Returns integer.
+ */
+export function clamp(min: number, value: number, max: number): number {
+  if (value < min) return min
+  if (value > max) return max
+  return value
+}
+
+/**
+ * Clamp and round to integer.
+ * Use at final step when writing to computed arrays.
+ */
+export function clampInt(min: number, value: number, max: number): number {
+  return Math.round(clamp(min, value, max))
+}
+
+/**
+ * Round to nearest integer.
+ * Always round at the end, not during intermediate calculations.
+ */
+export function round(value: number): number {
+  return Math.round(value)
+}
+
+/**
+ * Floor to integer.
+ * Use for flex grow to avoid overflow.
+ */
+export function floor(value: number): number {
+  return Math.floor(value)
+}
+
+/**
+ * Ceiling to integer.
+ * Use for flex shrink to ensure minimum coverage.
+ */
+export function ceil(value: number): number {
+  return Math.ceil(value)
+}
+
+/**
+ * Check if a number is effectively zero (within epsilon).
+ */
+export function isZero(value: number, epsilon = 0.001): boolean {
+  return Math.abs(value) < epsilon
+}
+
+/**
+ * Distribute a total amount across N items proportionally.
+ * Returns array of integer amounts that sum to exactly `total`.
+ *
+ * Uses largest remainder method to ensure exact distribution.
+ */
+export function distributeProportionally(
+  total: number,
+  weights: number[]
+): number[] {
+  if (weights.length === 0) return []
+
+  const totalWeight = weights.reduce((a, b) => a + b, 0)
+  if (totalWeight === 0) {
+    // Equal distribution if no weights
+    const base = Math.floor(total / weights.length)
+    const remainder = total - base * weights.length
+    return weights.map((_, i) => base + (i < remainder ? 1 : 0))
+  }
+
+  // Calculate exact (floating) shares
+  const exact = weights.map(w => (total * w) / totalWeight)
+
+  // Floor each share
+  const floored = exact.map(Math.floor)
+
+  // Calculate remainders
+  const remainders = exact.map((e, i) => ({
+    index: i,
+    remainder: e - floored[i]!,
+  }))
+
+  // Sort by remainder descending
+  remainders.sort((a, b) => b.remainder - a.remainder)
+
+  // Distribute leftover to items with largest remainders
+  const distributed = total - floored.reduce((a, b) => a + b, 0)
+  for (let i = 0; i < distributed; i++) {
+    floored[remainders[i]!.index]!++
+  }
+
+  return floored
+}
+
+/**
+ * Sum an array of numbers.
+ */
+export function sum(arr: number[]): number {
+  let total = 0
+  for (let i = 0; i < arr.length; i++) {
+    total += arr[i]!
+  }
+  return total
+}
+
+/**
+ * Find maximum in an array.
+ */
+export function max(arr: number[]): number {
+  if (arr.length === 0) return 0
+  let m = arr[0]!
+  for (let i = 1; i < arr.length; i++) {
+    if (arr[i]! > m) m = arr[i]!
+  }
+  return m
+}
+
+/**
+ * Find minimum in an array.
+ */
+export function min(arr: number[]): number {
+  if (arr.length === 0) return 0
+  let m = arr[0]!
+  for (let i = 1; i < arr.length; i++) {
+    if (arr[i]! < m) m = arr[i]!
+  }
+  return m
+}

package/src/pipeline/layout/utils/text-measure.ts

@@ -0,0 +1,160 @@
+/**
+ * TUI Framework - Text Measurement
+ *
+ * Terminal text measurement using Bun.stringWidth.
+ * Handles Unicode, emoji, CJK wide characters correctly.
+ */
+
+import { stringWidth } from '../../../utils/text'
+
+/**
+ * Measure the width of a string in terminal cells.
+ * Handles:
+ * - Regular ASCII (1 cell each)
+ * - Emoji (usually 2 cells)
+ * - CJK characters (2 cells)
+ * - Control characters (0 cells)
+ */
+export function measureTextWidth(content: string): number {
+  return stringWidth(content)
+}
+
+/**
+ * Measure text height when wrapped to a maximum width.
+ * Returns number of lines.
+ */
+export function measureTextHeight(content: string, maxWidth: number): number {
+  if (!content || maxWidth <= 0) return 0
+
+  // Simple word wrap - count lines
+  let lines = 1
+  let currentLineWidth = 0
+
+  // Split by existing newlines first
+  const paragraphs = content.split('\n')
+
+  for (const paragraph of paragraphs) {
+    if (paragraph === '') {
+      lines++
+      continue
+    }
+
+    // Process each character
+    for (const char of paragraph) {
+      const charWidth = stringWidth(char)
+
+      if (currentLineWidth + charWidth > maxWidth && currentLineWidth > 0) {
+        lines++
+        currentLineWidth = charWidth
+      } else {
+        currentLineWidth += charWidth
+      }
+    }
+
+    // Reset for next paragraph
+    currentLineWidth = 0
+    if (paragraphs.indexOf(paragraph) < paragraphs.length - 1) {
+      lines++
+    }
+  }
+
+  return lines
+}
+
+/**
+ * Measure text dimensions for layout.
+ * Returns both width (longest line) and height (number of lines).
+ */
+export function measureText(
+  content: string,
+  maxWidth: number
+): { width: number; height: number } {
+  if (!content) return { width: 0, height: 0 }
+
+  const lines = wrapTextLines(content, maxWidth)
+  let maxLineWidth = 0
+
+  for (const line of lines) {
+    const lineWidth = stringWidth(line)
+    if (lineWidth > maxLineWidth) {
+      maxLineWidth = lineWidth
+    }
+  }
+
+  return {
+    width: maxLineWidth,
+    height: lines.length,
+  }
+}
+
+/**
+ * Wrap text to a maximum width, returning array of lines.
+ * Simple word-boundary wrapping with fallback to character wrap.
+ */
+export function wrapTextLines(content: string, maxWidth: number): string[] {
+  if (!content) return []
+  if (maxWidth <= 0) return [content]
+
+  const result: string[] = []
+  const paragraphs = content.split('\n')
+
+  for (const paragraph of paragraphs) {
+    if (paragraph === '') {
+      result.push('')
+      continue
+    }
+
+    let currentLine = ''
+    let currentWidth = 0
+    const words = paragraph.split(' ')
+
+    for (let i = 0; i < words.length; i++) {
+      const word = words[i]!
+      const wordWidth = stringWidth(word)
+
+      // Check if word fits on current line
+      const needsSpace = currentLine.length > 0
+      const spaceWidth = needsSpace ? 1 : 0
+
+      if (currentWidth + spaceWidth + wordWidth <= maxWidth) {
+        // Word fits
+        if (needsSpace) {
+          currentLine += ' '
+          currentWidth += 1
+        }
+        currentLine += word
+        currentWidth += wordWidth
+      } else if (currentLine.length === 0) {
+        // Word is too long for any line - character wrap
+        let remaining = word
+        while (remaining.length > 0) {
+          let chunk = ''
+          let chunkWidth = 0
+          for (const char of remaining) {
+            const charWidth = stringWidth(char)
+            if (chunkWidth + charWidth > maxWidth && chunk.length > 0) {
+              break
+            }
+            chunk += char
+            chunkWidth += charWidth
+          }
+          result.push(chunk)
+          remaining = remaining.slice(chunk.length)
+        }
+        currentLine = ''
+        currentWidth = 0
+      } else {
+        // Start new line
+        result.push(currentLine)
+        currentLine = word
+        currentWidth = wordWidth
+      }
+    }
+
+    if (currentLine.length > 0) {
+      result.push(currentLine)
+    }
+  }
+
+  return result.length > 0 ? result : ['']
+}