@rlabs-inc/tui 0.1.0

package/README.md

@@ -0,0 +1,141 @@
+# TUI Framework
+
+**The Terminal UI Framework for TypeScript/Bun**
+
+A blazing-fast, fine-grained reactive terminal UI framework with complete flexbox layout and zero CPU when idle.
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Single update latency | 0.028ms |
+| Updates per second | 41,000+ |
+| Layout (10K components) | 0.66ms |
+| Memory per component | ~500 bytes |
+| Maximum components tested | 1,000,000 |
+
+## Quick Start
+
+```bash
+bun add tui @rlabs-inc/signals
+```
+
+```typescript
+import { mount, box, text } from 'tui'
+import { signal } from '@rlabs-inc/signals'
+
+// Create reactive state
+const count = signal(0)
+
+// Build your UI
+box({ width: 40, height: 10, children: () => {
+  text({ content: `Count: ${count.value}` })
+}})
+
+// Mount to terminal
+mount()
+
+// Update anywhere - UI reacts automatically
+setInterval(() => count.value++, 1000)
+```
+
+## Features
+
+### Complete Flexbox Layout (TITAN Engine)
+- Direction: row, column, row-reverse, column-reverse
+- Wrap: nowrap, wrap, wrap-reverse
+- Justify: flex-start, center, flex-end, space-between, space-around, space-evenly
+- Align: stretch, flex-start, center, flex-end
+- Grow, shrink, basis, gap
+- Min/max constraints
+- Percentage dimensions
+
+### Fine-Grained Reactivity
+- Signals for primitive values
+- Derived for computed values
+- Effects for side effects
+- 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
+- **focus** - Tab navigation, focus trapping
+- **scroll** - Scroll state and navigation
+- **theme** - 14 color variants, theming
+
+## Architecture
+
+```
+User Signals → bind() → Parallel Arrays → layoutDerived → frameBufferDerived → render
+```
+
+### Why So Fast?
+
+1. **Parallel Arrays** - ECS-like data layout for cache efficiency
+2. **No Reconciliation** - Fine-grained reactivity replaces diffing
+3. **Single Effect** - One render effect for entire app
+4. **TITAN Layout** - O(n) flexbox in pure TypeScript
+5. **Zero CPU Idle** - Only updates when signals change
+
+## Examples
+
+```bash
+# Run examples
+bun run examples/hello.ts
+bun run examples/showcase.ts
+
+# Run tests
+bun run examples/tests/01-box-basics.ts
+bun run examples/tests/03-layout-flex.ts
+```
+
+## Documentation
+
+- [CLAUDE.md](./CLAUDE.md) - Development guide and philosophy
+- [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) - Deep dive into the architecture
+- [docs/API.md](./docs/API.md) - Complete API reference
+- [docs/BIND_PRIMITIVE.md](./docs/BIND_PRIMITIVE.md) - Understanding reactivity
+
+## Primitives
+
+| Primitive | Status | Description |
+|-----------|--------|-------------|
+| `box` | Complete | Container with flexbox layout |
+| `text` | Complete | Text display with styling |
+| `input` | Planned | Text input field |
+| `select` | Planned | Dropdown selection |
+| `progress` | Planned | Progress bar |
+
+## Test Coverage
+
+- **130 tests** passing
+- TITAN layout engine: 48 tests
+- Parallel arrays: 17 tests
+- Focus manager: 29 tests
+- Compiler: 36 tests (unit + integration)
+
+## Requirements
+
+- Bun 1.0+ (for runtime and build)
+- Node.js 18+ (for compatibility)
+- Terminal with ANSI support
+
+## License
+
+MIT
+
+---
+
+Built with love by Rusty & Watson in São Paulo, Brazil.

package/index.ts

@@ -0,0 +1,45 @@
+/**
+ * TUI Framework
+ *
+ * The definitive TypeScript/Bun terminal UI framework.
+ * Fine-grained reactivity, parallel arrays, zero fixed-FPS rendering.
+ */
+
+// API - User-facing
+export { mount } from './src/api'
+
+// Primitives - UI building blocks
+export { box, text } from './src/primitives'
+export type { BoxProps, TextProps, Cleanup } from './src/primitives'
+
+// State modules - Input handling
+export { keyboard } from './src/state/keyboard'
+export { focusManager, focusedIndex } from './src/state/focus'
+export { scroll } from './src/state/scroll'
+export { mouse, hitGrid } from './src/state/mouse'
+
+// 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'
+
+// Theme
+export {
+  theme,
+  themes,
+  setTheme,
+  resolveColor,
+  resolvedTheme,
+  t,
+  getVariantStyle,
+  variantStyle,
+} from './src/state/theme'
+export type { Variant, VariantStyle, ThemeColor } from './src/state/theme'
+
+// Renderer (advanced)
+export * from './src/renderer'
+
+// Engine (advanced)
+export * from './src/engine'

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@rlabs-inc/tui",
+  "version": "0.1.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",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./primitives": "./src/primitives/index.ts",
+    "./state": "./src/state/index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src"
+  ],
+  "scripts": {
+    "dev": "bun run examples/hello.ts",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "tui",
+    "terminal",
+    "ui",
+    "framework",
+    "reactive",
+    "signals",
+    "flexbox",
+    "bun",
+    "typescript",
+    "cli"
+  ],
+  "author": "Rusty & Watson",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rlabs-inc/tui.git"
+  },
+  "homepage": "https://github.com/rlabs-inc/tui",
+  "bugs": {
+    "url": "https://github.com/rlabs-inc/tui/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "@rlabs-inc/signals": "^1.6.0"
+  }
+}

package/src/api/index.ts

@@ -0,0 +1,7 @@
+/**
+ * TUI Framework - API
+ *
+ * User-facing API for mounting applications.
+ */
+
+export { mount } from './mount'

package/src/api/mount.ts

@@ -0,0 +1,230 @@
+/**
+ * TUI Framework - Mount API
+ *
+ * The entry point for TUI applications.
+ * Sets up terminal, creates the render effect, handles cleanup.
+ *
+ * Usage:
+ * ```ts
+ * const cleanup = await mount(() => {
+ *   box({
+ *     width: 40,
+ *     height: 10,
+ *     border: 1,
+ *     children: () => {
+ *       text({ content: 'Hello, TUI!' })
+ *     }
+ *   })
+ * })
+ *
+ * // Later...
+ * await cleanup()
+ * ```
+ */
+
+import { effect } from '@rlabs-inc/signals'
+import type { MountOptions, ResizeEvent } from '../types'
+import {
+  DiffRenderer,
+  InlineRenderer,
+} from '../renderer/output'
+import * as ansi from '../renderer/ansi'
+import { frameBufferDerived } from '../pipeline/frameBuffer'
+import { layoutDerived, terminalWidth, terminalHeight, updateTerminalSize, renderMode } from '../pipeline/layout'
+import { resetRegistry } from '../engine/registry'
+import { hitGrid, clearHitGrid } from '../state/mouse'
+import { keyboard } from '../state/keyboard'
+
+// =============================================================================
+// MOUNT
+// =============================================================================
+
+/**
+ * Mount a TUI application.
+ *
+ * @param root - Function that creates the component tree
+ * @param options - Mount options (mode, mouse, keyboard)
+ * @returns Cleanup function to unmount
+ */
+export async function mount(
+  root: () => void,
+  options: MountOptions = {}
+): Promise<() => Promise<void>> {
+  const {
+    mode = 'fullscreen',
+    mouse = true,
+    kittyKeyboard = true,
+  } = options
+
+  // Set render mode signal BEFORE creating components
+  // This affects how layout and frameBuffer compute dimensions
+  renderMode.value = mode
+
+  // Create renderer based on mode
+  // Fullscreen uses DiffRenderer (absolute positioning)
+  // Inline uses InlineRenderer (eraseLines + sequential write)
+  // Append uses DiffRenderer for now (TODO: may need AppendRenderer)
+  const diffRenderer = new DiffRenderer()
+  const inlineRenderer = new InlineRenderer()
+
+  // Mode-specific state
+  let previousHeight = 0  // For append mode: track last rendered height
+  let isFirstRender = true
+
+  // Resize handlers (keyboard module handles key/mouse)
+  const resizeHandlers: Set<(event: ResizeEvent) => void> = new Set()
+
+  // Setup terminal
+  const setupSequence: string[] = []
+
+  if (mode === 'fullscreen') {
+    setupSequence.push(ansi.enterAlternativeScreen)
+    setupSequence.push(ansi.clearScreen)
+    setupSequence.push(ansi.cursorTo(1, 1))  // Cursor home
+  }
+  // Inline/Append: no special setup needed
+  // InlineRenderer handles erasing previous content
+
+  setupSequence.push(ansi.hideCursor)
+
+  if (mouse) {
+    setupSequence.push(ansi.enableMouse)
+  }
+
+  if (kittyKeyboard) {
+    setupSequence.push(ansi.enableKittyKeyboard)
+  }
+
+  setupSequence.push(ansi.enableBracketedPaste)
+  setupSequence.push(ansi.enableFocusReporting)
+
+  // Write setup sequence
+  process.stdout.write(setupSequence.join(''))
+
+  // Initialize keyboard module (handles stdin, raw mode, input parsing)
+  // Pass cleanup callback for proper shutdown on Ctrl+C
+  keyboard.initialize()
+
+  // Handle resize
+  const handleResize = () => {
+    updateTerminalSize()
+
+    // For fullscreen, invalidate diff renderer to force full redraw
+    if (mode === 'fullscreen') {
+      diffRenderer.invalidate()
+    }
+    // For inline/append, InlineRenderer always redraws (eraseLines approach)
+
+    for (const handler of resizeHandlers) {
+      handler({ width: terminalWidth.value, height: terminalHeight.value })
+    }
+  }
+  process.stdout.on('resize', handleResize)
+
+  // Initialize terminal size
+  updateTerminalSize()
+
+  // Create the component tree
+  root()
+
+  // THE ONE RENDER EFFECT
+  // This is where the magic happens - reactive rendering!
+  // Side effects (HitGrid) are applied HERE, not in the derived.
+  let stopEffect: (() => void) | null = null
+
+  stopEffect = effect(() => {
+    const start = Bun.nanoseconds()
+
+    // Time layout separately (reading .value triggers computation if needed)
+    // const layoutStart = Bun.nanoseconds()
+    // const _layout = layoutDerived.value
+    // const layoutNs = Bun.nanoseconds() - layoutStart
+
+    // Time buffer computation
+    const bufferStart = Bun.nanoseconds()
+    const { buffer, hitRegions, terminalSize } = frameBufferDerived.value
+    const bufferNs = Bun.nanoseconds() - bufferStart
+
+    // Apply hit regions to HitGrid (side effect happens in effect, not derived!)
+    if (hitGrid.width !== terminalSize.width || hitGrid.height !== terminalSize.height) {
+      hitGrid.resize(terminalSize.width, terminalSize.height)
+    } else {
+      clearHitGrid()
+    }
+    for (const region of hitRegions) {
+      hitGrid.fillRect(region.x, region.y, region.width, region.height, region.componentIndex)
+    }
+
+    // Time render to terminal
+    const renderStart = Bun.nanoseconds()
+    if (mode === 'fullscreen') {
+      diffRenderer.render(buffer)
+    } else if (mode === 'inline') {
+      inlineRenderer.render(buffer)
+    } else {
+      inlineRenderer.render(buffer)
+    }
+    const renderNs = Bun.nanoseconds() - renderStart
+
+    const totalNs = Bun.nanoseconds() - start
+
+    // Show all timing stats in window title
+    // const layoutMs = layoutNs / 1_000_000
+    const bufferMs = bufferNs / 1_000_000
+    const renderMs = renderNs / 1_000_000
+    const totalMs = totalNs / 1_000_000
+    // process.stdout.write(`\x1b]0;TUI | ${mode} | layout: ${layoutMs.toFixed(3)}ms | buffer: ${bufferMs.toFixed(3)}ms | render: ${renderMs.toFixed(3)}ms | total: ${totalMs.toFixed(3)}ms\x07`)
+    process.stdout.write(`\x1b]0;TUI | ${mode} | buffer: ${bufferMs.toFixed(3)}ms | render: ${renderMs.toFixed(3)}ms | total: ${totalMs.toFixed(3)}ms\x07`)
+  })
+
+  // Cleanup function
+  return async () => {
+    // Stop the render effect
+    if (stopEffect) {
+      stopEffect()
+      stopEffect = null
+    }
+
+    // Cleanup keyboard module (removes stdin listener, restores terminal)
+    keyboard.cleanup()
+
+    // Remove resize listener
+    process.stdout.removeListener('resize', handleResize)
+
+    // Restore terminal
+    const restoreSequence: string[] = []
+
+    restoreSequence.push(ansi.disableFocusReporting)
+    restoreSequence.push(ansi.disableBracketedPaste)
+
+    if (kittyKeyboard) {
+      restoreSequence.push(ansi.disableKittyKeyboard)
+    }
+
+    if (mouse) {
+      restoreSequence.push(ansi.disableMouse)
+    }
+
+    restoreSequence.push(ansi.showCursor)
+    restoreSequence.push(ansi.reset)
+
+    if (mode === 'fullscreen') {
+      restoreSequence.push(ansi.exitAlternativeScreen)
+    } else if (mode === 'inline' || mode === 'append') {
+      // For inline/append: content is already on screen, just reset and add newline
+      // InlineRenderer leaves cursor at end of content
+      restoreSequence.push('\n')
+    }
+
+    process.stdout.write(restoreSequence.join(''))
+
+    // Disable raw mode
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(false)
+    }
+
+    // Reset registry for clean slate
+    resetRegistry()
+  }
+}
+

package/src/engine/arrays/core.ts

@@ -0,0 +1,60 @@
+/**
+ * TUI Framework - Core Arrays
+ *
+ * The most fundamental component arrays:
+ * - componentType: What kind of component (box, text, etc.)
+ * - parentIndex: Parent in hierarchy
+ * - visible: Is component rendered
+ *
+ * NOTE: Focus state (focusable, tabIndex) is in interaction.ts
+ *
+ * CRITICAL: Arrays storing Bindings must be regular arrays (NOT state!)
+ * state() proxies snapshot getter values, breaking reactivity.
+ * componentType is the exception - it stores values directly, not bindings.
+ */
+
+import { bind, disconnectBinding, type Binding } from '@rlabs-inc/signals'
+import { ComponentType } from '../../types'
+import type { ComponentTypeValue } from '../../types'
+
+/** Component type (box, text, input, etc.) - stores values directly */
+export const componentType: ComponentTypeValue[] = []
+
+/** Parent component index (-1 for root) */
+export const parentIndex: Binding<number>[] = []
+
+/** Is component visible (0/false = hidden, 1/true = visible) */
+export const visible: Binding<number | boolean>[] = []
+
+/** Component ID (for debugging and lookups) */
+export const componentId: Binding<string>[] = []
+
+/**
+ * Ensure array has capacity for the given index.
+ * Called by registry when allocating.
+ *
+ * LAZY BINDING: We push undefined here, not bindings.
+ * Primitives create bindings only for props they actually use.
+ * This reduces memory from ~70 bindings/component to ~5-10.
+ */
+export function ensureCapacity(index: number): void {
+  while (componentType.length <= index) {
+    componentType.push(ComponentType.NONE)
+    parentIndex.push(undefined as any)
+    visible.push(undefined as any)
+    componentId.push(undefined as any)
+  }
+}
+
+/** Clear values at index (called when releasing) */
+export function clearAtIndex(index: number): void {
+  if (index < componentType.length) {
+    componentType[index] = ComponentType.NONE
+    disconnectBinding(parentIndex[index])
+    disconnectBinding(visible[index])
+    disconnectBinding(componentId[index])
+    parentIndex[index] = undefined as any
+    visible[index] = undefined as any
+    componentId[index] = undefined as any
+  }
+}

package/src/engine/arrays/dimensions.ts

@@ -0,0 +1,68 @@
+/**
+ * TUI Framework - Dimension Arrays
+ *
+ * Width, height, min/max constraints.
+ * These are INPUT values that components write.
+ * The layout derived READS these and RETURNS computed positions.
+ *
+ * CRITICAL: Use regular arrays (NOT state!) to preserve binding getters.
+ * state() proxies snapshot getter values, breaking reactivity.
+ *
+ * Supports both absolute and percentage dimensions:
+ *   - number: Absolute value in cells (e.g., 50)
+ *   - string: Percentage of parent (e.g., '50%', '100%')
+ *
+ * TITAN resolves percentages against parent computed sizes at layout time.
+ *
+ * Note: 0 means "auto" for width/height, "no constraint" for min/max.
+ */
+
+import { bind, disconnectBinding, type Binding } from '@rlabs-inc/signals'
+import type { Dimension } from '../../types'
+
+/** Requested width (0 = auto, '100%' = full parent width) */
+export const width: Binding<Dimension>[] = []
+
+/** Requested height (0 = auto, '100%' = full parent height) */
+export const height: Binding<Dimension>[] = []
+
+/** Minimum width constraint */
+export const minWidth: Binding<Dimension>[] = []
+
+/** Minimum height constraint */
+export const minHeight: Binding<Dimension>[] = []
+
+/** Maximum width constraint (0 = no max) */
+export const maxWidth: Binding<Dimension>[] = []
+
+/** Maximum height constraint (0 = no max) */
+export const maxHeight: Binding<Dimension>[] = []
+
+/** LAZY BINDING: Push undefined, primitives create bindings for used props only */
+export function ensureCapacity(index: number): void {
+  while (width.length <= index) {
+    width.push(undefined as any)
+    height.push(undefined as any)
+    minWidth.push(undefined as any)
+    minHeight.push(undefined as any)
+    maxWidth.push(undefined as any)
+    maxHeight.push(undefined as any)
+  }
+}
+
+export function clearAtIndex(index: number): void {
+  if (index < width.length) {
+    disconnectBinding(width[index])
+    disconnectBinding(height[index])
+    disconnectBinding(minWidth[index])
+    disconnectBinding(minHeight[index])
+    disconnectBinding(maxWidth[index])
+    disconnectBinding(maxHeight[index])
+    width[index] = undefined as any
+    height[index] = undefined as any
+    minWidth[index] = undefined as any
+    minHeight[index] = undefined as any
+    maxWidth[index] = undefined as any
+    maxHeight[index] = undefined as any
+  }
+}