@effect-tui/react 0.1.0-alpha.1

package/src/terminal.ts

@@ -0,0 +1,67 @@
+// ANSI escape sequences for terminal control
+
+export const ANSI = {
+  cursor: {
+    to: (x: number, y: number) => `\x1b[${y};${x}H`,
+    toCol: (col: number) => `\x1b[${col}G`,
+    up: (n: number) => (n > 0 ? `\x1b[${n}A` : ""),
+    down: (n: number) => (n > 0 ? `\x1b[${n}B` : ""),
+    hide: "\x1b[?25l",
+    show: "\x1b[?25h",
+    startOfLine: "\r",
+  },
+  line: {
+    clear: "\x1b[2K",
+    clearToEnd: "\x1b[0K",
+  },
+  screen: {
+    enterAlt: "\x1b[?1049h",
+    exitAlt: "\x1b[?1049l",
+    clear: "\x1b[2J",
+    clearToEnd: "\x1b[J", // Clear from cursor to end of screen
+  },
+  style: (s: {
+    fg?: number
+    bg?: number
+    bold?: boolean
+    italic?: boolean
+    underline?: boolean
+    inverse?: boolean
+  }) => {
+    const codes: number[] = []
+    if (s.bold) codes.push(1)
+    if (s.italic) codes.push(3)
+    if (s.underline) codes.push(4)
+    if (s.inverse) codes.push(7)
+    if (s.fg !== undefined) {
+      if (s.fg < 256) {
+        codes.push(38, 5, s.fg)
+      } else {
+        // Truecolor: decode from packed RGB
+        const r = (s.fg >> 16) & 0xff
+        const g = (s.fg >> 8) & 0xff
+        const b = s.fg & 0xff
+        codes.push(38, 2, r, g, b)
+      }
+    }
+    if (s.bg !== undefined) {
+      if (s.bg < 256) {
+        codes.push(48, 5, s.bg)
+      } else {
+        const r = (s.bg >> 16) & 0xff
+        const g = (s.bg >> 8) & 0xff
+        const b = s.bg & 0xff
+        codes.push(48, 2, r, g, b)
+      }
+    }
+    return codes.length > 0 ? `\x1b[${codes.join(";")}m` : ""
+  },
+  resetStyle: "\x1b[0m",
+}
+
+export const Terminal = {
+  enterFullscreen: ANSI.screen.enterAlt + ANSI.screen.clear + ANSI.cursor.hide,
+  exitFullscreen: ANSI.screen.exitAlt + ANSI.cursor.show,
+  hideCursor: ANSI.cursor.hide,
+  showCursor: ANSI.cursor.show,
+}

package/src/test/index.ts

@@ -0,0 +1,8 @@
+export { renderTUI, type RenderTUIOptions, type RenderTUIResult } from "./render-tui.js"
+export {
+  MockStdout,
+  MockStdin,
+  encodeKey,
+  stripAnsi,
+  getVisibleLines,
+} from "./mock-streams.js"

package/src/test/mock-streams.ts

@@ -0,0 +1,149 @@
+import { EventEmitter } from "node:events"
+import type { KeyMsg } from "@effect-tui/core"
+
+/**
+ * Mock stdout for testing. Captures all writes and simulates terminal properties.
+ */
+export class MockStdout extends EventEmitter {
+  columns: number
+  rows: number
+  buf = ""
+
+  constructor(width = 80, height = 24) {
+    super()
+    this.columns = width
+    this.rows = height
+  }
+
+  write(s: string): boolean {
+    this.buf += s
+    return true
+  }
+
+  /** Clear captured output */
+  clear(): void {
+    this.buf = ""
+  }
+
+  /** Simulate terminal resize */
+  resize(width: number, height: number): void {
+    this.columns = width
+    this.rows = height
+    this.emit("resize")
+  }
+}
+
+/**
+ * Mock stdin for testing. Simulates TTY input with key event emission.
+ */
+export class MockStdin extends EventEmitter {
+  isTTY = true
+
+  setRawMode(_mode: boolean): this {
+    return this
+  }
+
+  resume(): this {
+    return this
+  }
+
+  pause(): this {
+    return this
+  }
+
+  /** Send raw bytes (for testing decodeKeys directly) */
+  sendRaw(data: Buffer): void {
+    this.emit("data", data)
+  }
+
+  /** Send a key by encoding it to bytes */
+  sendKey(key: KeyMsg): void {
+    const encoded = encodeKey(key)
+    this.emit("data", encoded)
+  }
+}
+
+/**
+ * Encode a KeyMsg to raw bytes for stdin simulation.
+ * This is the reverse of decodeKeys().
+ */
+export function encodeKey(key: KeyMsg): Buffer {
+  const name = key.name
+  const text = key.text
+
+  // Control keys (Ctrl + printable character)
+  if (key.ctrl && text) {
+    const lower = text.toLowerCase()
+    if (lower === "c") return Buffer.from([0x03])
+    if (lower === "d") return Buffer.from([0x04])
+    if (lower === "z") return Buffer.from([0x1a])
+    if (lower === "w") return Buffer.from([0x17])
+    // Ctrl+letter = letter code - 0x60
+    if (text.length === 1) {
+      const code = lower.charCodeAt(0) - 0x60
+      if (code >= 1 && code <= 26) return Buffer.from([code])
+    }
+  }
+
+  // Special keys (escape sequences)
+  switch (name) {
+    case "up":
+      return Buffer.from([0x1b, 0x5b, 0x41])
+    case "down":
+      return Buffer.from([0x1b, 0x5b, 0x42])
+    case "right":
+      return Buffer.from([0x1b, 0x5b, 0x43])
+    case "left":
+      return Buffer.from([0x1b, 0x5b, 0x44])
+    case "home":
+      return Buffer.from([0x1b, 0x5b, 0x48])
+    case "end":
+      return Buffer.from([0x1b, 0x5b, 0x46])
+    case "pageup":
+      return Buffer.from([0x1b, 0x5b, 0x35, 0x7e])
+    case "pagedown":
+      return Buffer.from([0x1b, 0x5b, 0x36, 0x7e])
+    case "delete":
+      return Buffer.from([0x1b, 0x5b, 0x33, 0x7e])
+    case "insert":
+      return Buffer.from([0x1b, 0x5b, 0x32, 0x7e])
+    case "escape":
+      return Buffer.from([0x1b])
+    case "tab":
+      return Buffer.from([0x09])
+    case "enter":
+    case "return":
+      return Buffer.from([0x0d])
+    case "backspace":
+      return Buffer.from([0x7f])
+    case "space":
+      return Buffer.from([0x20])
+  }
+
+  // Regular character
+  if (text) {
+    return Buffer.from(text, "utf8")
+  }
+
+  // Unknown key, return empty
+  return Buffer.from([])
+}
+
+/**
+ * Strip ANSI escape codes from a string for easier assertions.
+ */
+export function stripAnsi(str: string): string {
+  // eslint-disable-next-line no-control-regex
+  return str.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, "").replace(/\x1b\][^\x07]*\x07/g, "")
+}
+
+/**
+ * Extract visible text lines from raw terminal output.
+ * Removes ANSI codes and splits by newlines.
+ */
+export function getVisibleLines(output: string): string[] {
+  const stripped = stripAnsi(output)
+  // Replace carriage returns with newlines for consistency
+  const normalized = stripped.replace(/\r\n/g, "\n").replace(/\r/g, "\n")
+  return normalized.split("\n")
+}

package/src/test/render-tui.ts

@@ -0,0 +1,118 @@
+import type { ReactElement } from "react"
+import type { KeyMsg } from "@effect-tui/core"
+import { createRenderer, createRoot } from "../renderer.js"
+import { flushPassiveEffects, flushSync, discreteUpdates } from "../reconciler/host-config.js"
+import { MockStdout, MockStdin, stripAnsi, getVisibleLines } from "./mock-streams.js"
+
+export interface RenderTUIOptions {
+  width?: number
+  height?: number
+}
+
+export interface RenderTUIResult {
+  /** Get last rendered frame as raw string (includes ANSI codes) */
+  lastFrameRaw(): string
+  /** Get last rendered frame with ANSI codes stripped */
+  lastFrame(): string
+  /** Get visible text lines from last frame */
+  lines(): string[]
+  /** Send a key event */
+  sendKey(key: KeyMsg): void
+  /** Trigger a render cycle and process React updates */
+  flush(): void
+  /** Unmount the component and stop the renderer */
+  unmount(): void
+  /** Access mock stdout for advanced assertions */
+  stdout: MockStdout
+  /** Access mock stdin for advanced input simulation */
+  stdin: MockStdin
+  /** Resize the terminal */
+  resize(width: number, height: number): void
+}
+
+/**
+ * Render a TUI component for testing.
+ * Similar to ink-testing-library's render().
+ *
+ * @example
+ * ```ts
+ * const { lastFrame, sendKey, flush, unmount } = renderTUI(<Counter />)
+ *
+ * expect(lastFrame()).toContain("Count: 0")
+ *
+ * sendKey({ key: "up" })
+ * flush()
+ *
+ * expect(lastFrame()).toContain("Count: 1")
+ *
+ * unmount()
+ * ```
+ */
+export function renderTUI(element: ReactElement, options?: RenderTUIOptions): RenderTUIResult {
+  const width = options?.width ?? 80
+  const height = options?.height ?? 24
+
+  const stdout = new MockStdout(width, height)
+  const stdin = new MockStdin()
+
+  const renderer = createRenderer({
+    stdout: stdout as any,
+    stdin: stdin as any,
+    manualMode: true,
+    skipTerminalSetup: true,
+  })
+
+  const root = createRoot(renderer)
+  root.render(element, true) // sync mode
+
+  // Flush effects
+  flushPassiveEffects()
+
+  // Initial render
+  renderer.flush()
+
+  const flush = () => {
+    // Flush React updates synchronously
+    flushSync(() => {})
+    flushPassiveEffects()
+    // Clear buffer before re-render to get clean frame
+    stdout.clear()
+    renderer.requestRender()
+    renderer.flush()
+  }
+
+  return {
+    lastFrameRaw() {
+      return stdout.buf
+    },
+
+    lastFrame() {
+      return stripAnsi(stdout.buf)
+    },
+
+    lines() {
+      return getVisibleLines(stdout.buf)
+    },
+
+    sendKey(key: KeyMsg) {
+      // Use discreteUpdates to ensure React processes state updates synchronously
+      discreteUpdates(() => {
+        stdin.sendKey(key)
+      })
+    },
+
+    flush,
+
+    unmount() {
+      root.unmount()
+    },
+
+    stdout,
+    stdin,
+
+    resize(w: number, h: number) {
+      stdout.resize(w, h)
+      flush()
+    },
+  }
+}

package/src/trace/SpanTree.tsx

@@ -0,0 +1,195 @@
+// React component for visualizing span tree
+
+import { Colors, type ColorValue } from "@effect-tui/core"
+import type { SpanNode, SpanTreeState } from "./span-state.js"
+
+const SPINNER_FRAMES = ["⠋", "⠙", "⠸", "⠴", "⠦", "⠇"] as const
+
+function formatDuration(ms: number): string {
+  if (ms < 1000) return `${Math.round(ms)}ms`
+  return `${(ms / 1000).toFixed(1)}s`
+}
+
+// Map opacity (0-1) to gray level (8-23 for visible range)
+function opacityToGray(opacity: number): number {
+  const minGray = 8
+  const maxGray = 23
+  return Math.round(minGray + opacity * (maxGray - minGray))
+}
+
+// Interpolate RGB color based on opacity
+function dimColor(r: number, g: number, b: number, opacity: number): ColorValue {
+  const minOpacity = 0.3 // Don't go completely dark
+  const factor = minOpacity + opacity * (1 - minOpacity)
+  return Colors.rgb(Math.round(r * factor), Math.round(g * factor), Math.round(b * factor))
+}
+
+// Get log level color
+function logLevelColor(level: string, opacity: number): ColorValue {
+  switch (level) {
+    case "ERROR":
+      return dimColor(255, 80, 80, opacity)
+    case "WARN":
+      return dimColor(255, 200, 0, opacity)
+    case "INFO":
+      return dimColor(100, 180, 255, opacity)
+    default:
+      return Colors.gray(opacityToGray(opacity))
+  }
+}
+
+interface SpanRowProps {
+  node: SpanNode
+  state: SpanTreeState
+  spinnerIndex: number
+  prefix: string
+  isLast: boolean
+}
+
+function SpanRow({ node, state, spinnerIndex, prefix, isLast }: SpanRowProps) {
+  const connector = isLast ? "└─" : "├─"
+  const childPrefix = prefix + (isLast ? "   " : "│  ")
+
+  const opacity = node.opacity
+  const grayLevel = opacityToGray(opacity)
+
+  const isSelected = state.selectedSpanId === node.id
+  const isExpanded = state.expandedSpanIds.has(node.id)
+
+  // Status icon
+  let icon: string
+  let iconColor: ColorValue | number
+  if (node.status === "running") {
+    icon = SPINNER_FRAMES[spinnerIndex]
+    iconColor = Colors.brightCyan
+  } else if (node.status === "success") {
+    icon = "✓"
+    iconColor = dimColor(0, 255, 0, opacity)
+  } else {
+    icon = "✗"
+    iconColor = dimColor(255, 80, 80, opacity)
+  }
+
+  // Name color - selected gets blue bg with bright text
+  const nameColor = isSelected
+    ? Colors.brightWhite
+    : node.status === "running"
+      ? Colors.brightWhite
+      : Colors.gray(grayLevel)
+  const nameBg = isSelected ? Colors.rgb(30, 60, 120) : undefined
+
+  // Duration display
+  const durationStr =
+    node.duration !== undefined
+      ? formatDuration(node.duration)
+      : node.status === "running"
+        ? formatDuration(Date.now() - node.startTime)
+        : ""
+  const durationColor = Colors.gray(Math.max(8, grayLevel - 4))
+
+  // Log counts from logEntries
+  const logCounts = { info: 0, warn: 0, error: 0, debug: 0 }
+  for (const entry of node.logEntries) {
+    if (entry.level === "INFO") logCounts.info++
+    else if (entry.level === "WARN") logCounts.warn++
+    else if (entry.level === "ERROR") logCounts.error++
+    else logCounts.debug++
+  }
+
+  const logParts: Array<{ text: string; color: ColorValue | number }> = []
+  if (logCounts.error > 0) logParts.push({ text: `${logCounts.error} err`, color: dimColor(255, 80, 80, opacity) })
+  if (logCounts.warn > 0) logParts.push({ text: `${logCounts.warn} warn`, color: dimColor(255, 200, 0, opacity) })
+  if (logCounts.info > 0) logParts.push({ text: `${logCounts.info} info`, color: dimColor(100, 180, 255, opacity) })
+  if (logCounts.debug > 0) logParts.push({ text: `${logCounts.debug} dbg`, color: Colors.gray(grayLevel) })
+
+  return (
+    <vstack>
+      <hstack>
+        <text fg={Colors.gray(Math.max(8, grayLevel - 2))}>
+          {prefix}
+          {connector}
+        </text>
+        <text fg={iconColor}> {icon} </text>
+        <text fg={nameColor} bg={nameBg}>
+          {node.name}
+        </text>
+        {durationStr && <text fg={durationColor}> {durationStr}</text>}
+        {logParts.length > 0 && <text fg={durationColor}> [</text>}
+        {logParts.map((p, i) => (
+          <text key={i} fg={p.color}>
+            {i > 0 ? " " : ""}
+            {p.text}
+          </text>
+        ))}
+        {logParts.length > 0 && <text fg={durationColor}>]</text>}
+        {node.error && <text fg={Colors.red}> ({node.error})</text>}
+      </hstack>
+      {/* Expanded log entries */}
+      {isExpanded &&
+        node.logEntries.map((entry, i) => (
+          <hstack key={i}>
+            <text fg={Colors.gray(10)}>
+              {childPrefix}
+              {node.children.length > 0 ? "│  " : "   "}
+            </text>
+            <text fg={logLevelColor(entry.level, opacity)}>{entry.level}</text>
+            <text fg={Colors.gray(16)}> {entry.message}</text>
+          </hstack>
+        ))}
+      {node.children.map((child, i) => (
+        <SpanRow
+          key={child.id}
+          node={child}
+          state={state}
+          spinnerIndex={spinnerIndex}
+          prefix={childPrefix}
+          isLast={i === node.children.length - 1}
+        />
+      ))}
+    </vstack>
+  )
+}
+
+interface SpanTreeProps {
+  state: SpanTreeState
+  spinnerIndex: number
+  serviceName?: string
+  showExitPrompt?: boolean
+}
+
+export function SpanTree({ state, spinnerIndex, serviceName, showExitPrompt }: SpanTreeProps) {
+  // No subscription needed - parent's 60fps loop drives re-renders
+  const roots = state.getRoots()
+
+  if (roots.length === 0) {
+    return <text fg={Colors.gray(10)}>Waiting for spans...</text>
+  }
+
+  const hasAnyLogs = state.getSpansWithLogs().length > 0
+
+  return (
+    <vstack>
+      {serviceName && (
+        <text fg={Colors.brightWhite} bold>
+          {serviceName}
+        </text>
+      )}
+      {roots.map((root, i) => (
+        <SpanRow
+          key={root.id}
+          node={root}
+          state={state}
+          spinnerIndex={spinnerIndex}
+          prefix=""
+          isLast={i === roots.length - 1}
+        />
+      ))}
+      {showExitPrompt && (
+        <text fg={Colors.gray(12)}>
+          {"\n"}
+          {hasAnyLogs ? "↑↓ navigate, Enter expand, O open, q to exit" : "q to exit"}
+        </text>
+      )}
+    </vstack>
+  )
+}