@mdxui/terminal 2.0.0

package/src/renderers/ansi.ts

@@ -0,0 +1,802 @@
+/**
+ * ANSI Renderer
+ *
+ * Converts UINode trees to ANSI-escaped terminal strings with support for:
+ * - 16 color, 256 color, and true color modes
+ * - Text formatting (bold, italic, underline, etc.)
+ * - Theme colors (dark/light mode with semantic colors)
+ * - Graceful color degradation
+ */
+
+import { ANSI } from '../theme/ansi-codes'
+import { hexToRgb } from '../theme/color-convert'
+import type { UINode } from '../core/types'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * ANSI render options
+ */
+interface ANSIRenderOptions {
+  colorSupport?: 'none' | '16' | '256' | 'truecolor'
+  theme?: 'dark' | 'light'
+  width?: number
+  resetBetweenElements?: boolean
+}
+
+/**
+ * RGB color object
+ */
+interface RgbColor {
+  r: number
+  g: number
+  b: number
+}
+
+// ============================================================================
+// Color Maps
+// ============================================================================
+
+/** Map of basic 16 color names to foreground codes */
+const FG_COLOR_MAP: Record<string, string> = {
+  black: '\x1b[30m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+  brightBlack: '\x1b[90m',
+  brightRed: '\x1b[91m',
+  brightGreen: '\x1b[92m',
+  brightYellow: '\x1b[93m',
+  brightBlue: '\x1b[94m',
+  brightMagenta: '\x1b[95m',
+  brightCyan: '\x1b[96m',
+  brightWhite: '\x1b[97m',
+}
+
+/** Map of basic 16 color names to background codes */
+const BG_COLOR_MAP: Record<string, string> = {
+  black: '\x1b[40m',
+  red: '\x1b[41m',
+  green: '\x1b[42m',
+  yellow: '\x1b[43m',
+  blue: '\x1b[44m',
+  magenta: '\x1b[45m',
+  cyan: '\x1b[46m',
+  white: '\x1b[47m',
+}
+
+/** Semantic color mappings for dark theme */
+const DARK_THEME_COLORS: Record<string, string> = {
+  primary: '\x1b[36m', // cyan
+  secondary: '\x1b[34m', // blue
+  accent: '\x1b[35m', // magenta
+  muted: '\x1b[90m', // brightBlack (gray)
+  success: '\x1b[32m', // green
+  warning: '\x1b[33m', // yellow
+  error: '\x1b[31m', // red
+  info: '\x1b[34m', // blue
+  foreground: '\x1b[37m', // white
+  background: '\x1b[40m', // black bg
+}
+
+/** Semantic color mappings for light theme */
+const LIGHT_THEME_COLORS: Record<string, string> = {
+  primary: '\x1b[34m', // blue (darker for light bg)
+  secondary: '\x1b[36m', // cyan
+  accent: '\x1b[35m', // magenta
+  muted: '\x1b[90m', // brightBlack (gray)
+  success: '\x1b[32m', // green
+  warning: '\x1b[33m', // yellow
+  error: '\x1b[31m', // red
+  info: '\x1b[34m', // blue
+  foreground: '\x1b[30m', // black
+  background: '\x1b[47m', // white bg
+}
+
+// ============================================================================
+// Color Utilities
+// ============================================================================
+
+/**
+ * Convert RGB to nearest ANSI 256 color code
+ */
+function rgbToAnsi256(r: number, g: number, b: number): number {
+  // Check for grayscale
+  if (Math.abs(r - g) < 10 && Math.abs(g - b) < 10 && Math.abs(r - b) < 10) {
+    const avg = (r + g + b) / 3
+    if (avg < 8) return 0
+    if (avg > 248) return 15
+    const grayIndex = Math.round((avg - 8) / 10)
+    return Math.min(255, Math.max(232, 232 + grayIndex))
+  }
+
+  // Color cube
+  const toColorCubeIndex = (v: number): number => {
+    if (v < 48) return 0
+    if (v < 115) return 1
+    return Math.min(5, Math.floor((v - 35) / 40))
+  }
+
+  const ri = toColorCubeIndex(r)
+  const gi = toColorCubeIndex(g)
+  const bi = toColorCubeIndex(b)
+
+  return 16 + 36 * ri + 6 * gi + bi
+}
+
+/**
+ * Convert ANSI 256 color to nearest basic 16 color
+ */
+function ansi256To16(code: number): number {
+  if (code < 8) return 30 + code
+  if (code < 16) return 90 + (code - 8)
+
+  let r: number, g: number, b: number
+
+  if (code >= 232) {
+    const gray = (code - 232) * 10 + 8
+    r = g = b = gray
+  } else {
+    const cubeIndex = code - 16
+    r = Math.floor(cubeIndex / 36) * 51
+    g = Math.floor((cubeIndex % 36) / 6) * 51
+    b = (cubeIndex % 6) * 51
+  }
+
+  const basicColors = [
+    { r: 0, g: 0, b: 0, code: 30 },
+    { r: 170, g: 0, b: 0, code: 31 },
+    { r: 0, g: 170, b: 0, code: 32 },
+    { r: 170, g: 170, b: 0, code: 33 },
+    { r: 0, g: 0, b: 170, code: 34 },
+    { r: 170, g: 0, b: 170, code: 35 },
+    { r: 0, g: 170, b: 170, code: 36 },
+    { r: 170, g: 170, b: 170, code: 37 },
+    { r: 85, g: 85, b: 85, code: 90 },
+    { r: 255, g: 85, b: 85, code: 91 },
+    { r: 85, g: 255, b: 85, code: 92 },
+    { r: 255, g: 255, b: 85, code: 93 },
+    { r: 85, g: 85, b: 255, code: 94 },
+    { r: 255, g: 85, b: 255, code: 95 },
+    { r: 85, g: 255, b: 255, code: 96 },
+    { r: 255, g: 255, b: 255, code: 97 },
+  ]
+
+  let minDist = Infinity
+  let closestCode = 37
+
+  for (const bc of basicColors) {
+    const dist = Math.sqrt(
+      Math.pow(r - bc.r, 2) + Math.pow(g - bc.g, 2) + Math.pow(b - bc.b, 2)
+    )
+    if (dist < minDist) {
+      minDist = dist
+      closestCode = bc.code
+    }
+  }
+
+  return closestCode
+}
+
+/**
+ * Resolve a color value to an ANSI escape code
+ */
+function resolveColor(
+  color: unknown,
+  isBackground: boolean,
+  options: ANSIRenderOptions
+): string {
+  const colorSupport = options.colorSupport || 'truecolor'
+  const theme = options.theme || 'dark'
+  const themeColors = theme === 'dark' ? DARK_THEME_COLORS : LIGHT_THEME_COLORS
+
+  // No colors when support is none
+  if (colorSupport === 'none') {
+    return ''
+  }
+
+  // Handle semantic colors
+  if (typeof color === 'string' && themeColors[color]) {
+    const ansi = themeColors[color]
+    // For background semantic colors, we need to convert fg code to bg
+    if (isBackground && ansi.startsWith('\x1b[3')) {
+      return ansi.replace('\x1b[3', '\x1b[4')
+    }
+    return ansi
+  }
+
+  // Handle named 16 colors
+  if (typeof color === 'string') {
+    const colorMap = isBackground ? BG_COLOR_MAP : FG_COLOR_MAP
+    if (colorMap[color]) {
+      return colorMap[color]
+    }
+
+    // Handle hex colors
+    if (color.startsWith('#')) {
+      const rgb = hexToRgb(color)
+      return formatRgbColor(rgb.r, rgb.g, rgb.b, isBackground, colorSupport)
+    }
+
+    // Unknown string color - return empty
+    return ''
+  }
+
+  // Handle numeric 256 colors
+  if (typeof color === 'number') {
+    const code = Math.max(0, Math.min(255, Math.floor(color)))
+
+    if (colorSupport === '16') {
+      const code16 = ansi256To16(code)
+      return `\x1b[${code16}m`
+    }
+
+    const prefix = isBackground ? '48' : '38'
+    return `\x1b[${prefix};5;${code}m`
+  }
+
+  // Handle RGB object
+  if (
+    typeof color === 'object' &&
+    color !== null &&
+    'r' in color &&
+    'g' in color &&
+    'b' in color
+  ) {
+    const rgb = color as RgbColor
+    return formatRgbColor(rgb.r, rgb.g, rgb.b, isBackground, colorSupport)
+  }
+
+  return ''
+}
+
+/**
+ * Format RGB color based on color support level
+ */
+function formatRgbColor(
+  r: number,
+  g: number,
+  b: number,
+  isBackground: boolean,
+  colorSupport: string
+): string {
+  const prefix = isBackground ? '48' : '38'
+
+  if (colorSupport === 'truecolor') {
+    return `\x1b[${prefix};2;${r};${g};${b}m`
+  }
+
+  const code256 = rgbToAnsi256(r, g, b)
+
+  if (colorSupport === '256') {
+    return `\x1b[${prefix};5;${code256}m`
+  }
+
+  if (colorSupport === '16') {
+    const code16 = ansi256To16(code256)
+    return `\x1b[${code16}m`
+  }
+
+  return ''
+}
+
+// ============================================================================
+// Style Building
+// ============================================================================
+
+/**
+ * Build ANSI escape codes from props
+ */
+function buildStyleCodes(
+  props: Record<string, unknown> | undefined,
+  options: ANSIRenderOptions
+): string[] {
+  if (!props) return []
+
+  const codes: string[] = []
+  const colorSupport = options.colorSupport || 'truecolor'
+
+  // Text formatting (preserved even when colors are stripped)
+  if (props.bold) codes.push('\x1b[1m')
+  if (props.dim) codes.push('\x1b[2m')
+  if (props.italic) codes.push('\x1b[3m')
+  if (props.underline) codes.push('\x1b[4m')
+  if (props.inverse) codes.push('\x1b[7m')
+  if (props.strikethrough) codes.push('\x1b[9m')
+
+  // Colors (only when not 'none')
+  if (colorSupport !== 'none') {
+    if (props.color !== undefined) {
+      const fg = resolveColor(props.color, false, options)
+      if (fg) codes.push(fg)
+    }
+
+    if (props.backgroundColor !== undefined) {
+      const bg = resolveColor(props.backgroundColor, true, options)
+      if (bg) codes.push(bg)
+    }
+  }
+
+  return codes
+}
+
+/**
+ * Check if any styling is applied
+ */
+function hasStyles(props: Record<string, unknown> | undefined): boolean {
+  if (!props) return false
+  return !!(
+    props.bold ||
+    props.dim ||
+    props.italic ||
+    props.underline ||
+    props.inverse ||
+    props.strikethrough ||
+    props.color !== undefined ||
+    props.backgroundColor !== undefined
+  )
+}
+
+// ============================================================================
+// Component Renderers
+// ============================================================================
+
+/**
+ * Render a badge component
+ */
+function renderBadge(node: UINode, options: ANSIRenderOptions): string {
+  const text = node.text || ''
+  const variant = (node.props?.variant as string) || 'default'
+
+  // Map variants to colors
+  const variantColors: Record<string, string> = {
+    success: 'success',
+    error: 'error',
+    warning: 'warning',
+    info: 'info',
+    default: 'primary',
+  }
+
+  const colorName = variantColors[variant] || 'primary'
+  const colorCode = resolveColor(colorName, false, options)
+
+  if (colorCode) {
+    return `${colorCode}${text}${ANSI.reset}`
+  }
+  return text
+}
+
+/**
+ * Render a button component
+ */
+function renderButton(node: UINode, options: ANSIRenderOptions): string {
+  const text = node.text || ''
+  const focused = node.props?.focused as boolean
+  const variant = (node.props?.variant as string) || 'default'
+
+  const codes: string[] = []
+
+  if (focused) {
+    codes.push(ANSI.inverse)
+  }
+
+  if (variant === 'primary') {
+    const colorCode = resolveColor('primary', false, options)
+    if (colorCode) codes.push(colorCode)
+  }
+
+  if (codes.length > 0) {
+    return `${codes.join('')}${text}${ANSI.reset}`
+  }
+  return text
+}
+
+/**
+ * Render a spinner component
+ */
+function renderSpinner(node: UINode): string {
+  const label = (node.props?.label as string) || ''
+  return label
+}
+
+/**
+ * Render a panel component
+ */
+function renderPanel(node: UINode, options: ANSIRenderOptions): string {
+  const title = (node.props?.title as string) || ''
+  const content = renderChildren(node.children, options)
+  return `${title}${content ? '\n' + content : ''}`
+}
+
+/**
+ * Render a card component
+ */
+function renderCard(node: UINode, options: ANSIRenderOptions): string {
+  const title = node.props?.title as string | undefined
+  const subtitle = node.props?.subtitle as string | undefined
+  const badge = node.props?.badge as { content: string; variant?: string } | undefined
+  const titleAction = node.props?.titleAction as { label: string; action?: string } | undefined
+  const pairs = node.props?.pairs as Array<{ key: string; value: unknown }> | undefined
+  const actions = node.props?.actions as Array<{ label: string; action?: string }> | undefined
+  const variant = node.props?.variant as string | undefined
+
+  const lines: string[] = []
+
+  // Get variant color if specified
+  const variantColor = variant ? resolveColor(variant, false, options) : null
+
+  // Title section - apply bold styling and optional variant color
+  if (title) {
+    let titleLine = title
+    if (badge) {
+      const badgeColor = badge.variant ? resolveColor(badge.variant, false, options) : null
+      const badgeText = badgeColor
+        ? `${badgeColor}[${badge.content}]${ANSI.reset}`
+        : `[${badge.content}]`
+      titleLine += ` ${badgeText}`
+    }
+    if (titleAction) {
+      titleLine += ` | ${titleAction.label}`
+    }
+    // Apply bold to title, and variant color if specified
+    const titleCodes: string[] = [ANSI.bold]
+    if (variantColor) {
+      titleCodes.push(variantColor)
+    }
+    lines.push(`${titleCodes.join('')}${titleLine}${ANSI.reset}`)
+  }
+
+  if (subtitle) {
+    // Apply muted color to subtitle
+    const mutedColor = resolveColor('muted', false, options)
+    if (mutedColor) {
+      lines.push(`${mutedColor}${subtitle}${ANSI.reset}`)
+    } else {
+      lines.push(subtitle)
+    }
+  }
+
+  // Key-value pairs
+  if (pairs && pairs.length > 0) {
+    for (const pair of pairs) {
+      const val = pair.value != null ? String(pair.value) : ''
+      // Apply variant color to value if pair has variant
+      const pairVariant = (pair as { variant?: string }).variant
+      if (pairVariant) {
+        const pairColor = resolveColor(pairVariant, false, options)
+        if (pairColor) {
+          lines.push(`${pair.key}: ${pairColor}${val}${ANSI.reset}`)
+        } else {
+          lines.push(`${pair.key}: ${val}`)
+        }
+      } else {
+        lines.push(`${pair.key}: ${val}`)
+      }
+    }
+  }
+
+  // Children content
+  const content = renderChildren(node.children, options)
+  if (content) {
+    lines.push(content)
+  }
+
+  // Actions
+  if (actions && actions.length > 0) {
+    const actionLabels = actions.map((a) => {
+      const actionVariant = (a as { variant?: string }).variant
+      if (actionVariant) {
+        const actionColor = resolveColor(actionVariant, false, options)
+        if (actionColor) {
+          return `${actionColor}[ ${a.label} ]${ANSI.reset}`
+        }
+      }
+      return `[ ${a.label} ]`
+    }).join(' ')
+    lines.push(actionLabels)
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Render an input component
+ */
+function renderInput(node: UINode): string {
+  const value = (node.props?.value as string) || ''
+  return value
+}
+
+/**
+ * Render a select component
+ */
+function renderSelect(node: UINode): string {
+  const opts = (node.props?.options as Array<{ label: string; value: unknown }>) || []
+  return opts.map((o) => o.label).join('\n')
+}
+
+/**
+ * Render a table component with ANSI styling
+ */
+function renderTable(node: UINode, options: ANSIRenderOptions): string {
+  const columns = (node.props?.columns as Array<{ key: string; header: string }>) || []
+  // Support data from node.data (TDD tests) or props.data (legacy)
+  const nodeData = (node as { data?: unknown }).data as Array<Record<string, unknown>> | undefined
+  const data = nodeData ?? (node.props?.data as Array<Record<string, unknown>>) ?? []
+  const headerStyle = node.props?.headerStyle as Record<string, unknown> | undefined
+
+  // Apply header styling (bold by default, or from props)
+  const headerCodes = buildStyleCodes(headerStyle ?? { bold: true }, options)
+  const headerPrefix = headerCodes.length > 0 ? headerCodes.join('') : ''
+  const headerSuffix = headerCodes.length > 0 ? ANSI.reset : ''
+
+  const headers = columns
+    .map((c) => `${headerPrefix}${c.header}${headerSuffix}`)
+    .join('\t')
+  const rows = data.map((row) => columns.map((c) => String(row[c.key] || '')).join('\t'))
+
+  return [headers, ...rows].join('\n')
+}
+
+/**
+ * Render a list component
+ */
+function renderList(node: UINode, options: ANSIRenderOptions, depth = 0): string {
+  const items = (node.props?.items as Array<string | { text: string; checked?: boolean }>) || []
+  const bullet = (node.props?.bullet as string) || '-'
+  const numbered = (node.props?.numbered as boolean) ?? false
+  const taskList = (node.props?.taskList as boolean) ?? false
+  const children = node.children as UINode[] | undefined
+  const indent = '  '.repeat(depth)
+
+  const lines: string[] = []
+
+  // Get color for list markers
+  const markerColor = resolveColor('muted', false, options)
+  const resetCode = ANSI.reset
+
+  // Handle items prop
+  if (items.length > 0) {
+    items.forEach((item, index) => {
+      let text: string
+      let prefix: string
+
+      if (typeof item === 'string') {
+        text = item
+        prefix = numbered ? `${index + 1}. ` : `${bullet} `
+      } else {
+        text = item.text ?? ''
+        if (taskList && 'checked' in item) {
+          prefix = item.checked ? '[x] ' : '[ ] '
+        } else {
+          prefix = numbered ? `${index + 1}. ` : `${bullet} `
+        }
+      }
+
+      // Apply marker color
+      const styledPrefix = markerColor ? `${markerColor}${prefix}${resetCode}` : prefix
+      lines.push(`${indent}${styledPrefix}${text}`)
+    })
+  }
+
+  // Handle list-item children (with nested list support)
+  if (children && Array.isArray(children)) {
+    children.forEach((child, index) => {
+      if (child.type === 'list-item') {
+        const content = (child.props?.content as string) ?? ''
+        const variant = child.props?.variant as string | undefined
+        const prefix = numbered ? `${index + 1}. ` : `${bullet} `
+
+        // Apply marker color
+        const styledPrefix = markerColor ? `${markerColor}${prefix}${resetCode}` : prefix
+
+        // Apply variant color to content if specified
+        let styledContent = content
+        if (variant) {
+          const variantColor = resolveColor(variant, false, options)
+          if (variantColor) {
+            styledContent = `${variantColor}${content}${resetCode}`
+          }
+        }
+
+        lines.push(`${indent}${styledPrefix}${styledContent}`)
+
+        // Handle nested lists
+        if (child.children && Array.isArray(child.children)) {
+          for (const nestedChild of child.children) {
+            if (nestedChild.type === 'list') {
+              const nestedLines = renderList(nestedChild, options, depth + 1)
+              if (nestedLines) {
+                lines.push(nestedLines)
+              }
+            }
+          }
+        }
+      }
+    })
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Render a breadcrumb component
+ */
+function renderBreadcrumb(node: UINode): string {
+  const items = (node.props?.items as Array<{ label: string; path: string }>) || []
+  const separator = (node.props?.separator as string) || '/'
+  return items.map((item) => item.label).join(` ${separator} `)
+}
+
+/**
+ * Render metrics (multiple metrics)
+ */
+function renderMetrics(node: UINode, options: ANSIRenderOptions): string {
+  const metrics = node.props?.metrics as Array<{
+    label: string
+    value: unknown
+    format?: string
+    unit?: string
+    trend?: string
+    variant?: string
+  }> | undefined
+
+  if (!metrics || metrics.length === 0) return ''
+
+  const labelColor = resolveColor('muted', false, options)
+  const resetCode = ANSI.reset
+
+  const lines: string[] = []
+  for (const m of metrics) {
+    const val = m.value != null ? String(m.value) : ''
+    let formatted = val
+    if (m.format === 'percentage' && !val.includes('%')) {
+      formatted = `${val}%`
+    }
+    if (m.unit) {
+      formatted = `${formatted} ${m.unit}`
+    }
+
+    // Apply variant color if specified
+    const variantColor = m.variant ? resolveColor(m.variant, false, options) : null
+    const styledLabel = labelColor ? `${labelColor}${m.label}:${resetCode}` : `${m.label}:`
+    const styledValue = variantColor ? `${variantColor}${formatted}${resetCode}` : formatted
+
+    lines.push(`${styledLabel} ${styledValue}`)
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Render a single metric
+ */
+function renderSingleMetric(node: UINode): string {
+  const label = node.props?.label as string | undefined
+  const value = node.props?.value
+  const format = node.props?.format as string | undefined
+  const unit = node.props?.unit as string | undefined
+
+  if (!label) return ''
+
+  const val = value != null ? String(value) : ''
+  let formatted = val
+  if (format === 'percentage' && !val.includes('%')) {
+    formatted = `${val}%`
+  }
+  if (unit) {
+    formatted = `${formatted} ${unit}`
+  }
+
+  return `${label}: ${formatted}`
+}
+
+// ============================================================================
+// Main Rendering
+// ============================================================================
+
+/**
+ * Render children nodes
+ */
+function renderChildren(
+  children: UINode[] | string | undefined,
+  options: ANSIRenderOptions
+): string {
+  if (!children) return ''
+
+  if (typeof children === 'string') {
+    return children
+  }
+
+  if (Array.isArray(children) && children.length === 0) {
+    return ''
+  }
+
+  return children.map((child) => renderNode(child, options)).join('')
+}
+
+/**
+ * Render a single node
+ */
+function renderNode(node: UINode, options: ANSIRenderOptions): string {
+  // Get text content
+  let text = ''
+
+  switch (node.type) {
+    case 'badge':
+      return renderBadge(node, options)
+    case 'button':
+      return renderButton(node, options)
+    case 'spinner':
+      return renderSpinner(node)
+    case 'panel':
+      return renderPanel(node, options)
+    case 'card':
+      return renderCard(node, options)
+    case 'input':
+      return renderInput(node)
+    case 'select':
+      return renderSelect(node)
+    case 'table':
+      return renderTable(node, options)
+    case 'list':
+      return renderList(node, options)
+    case 'breadcrumb':
+      return renderBreadcrumb(node)
+    case 'metrics':
+      return renderMetrics(node, options)
+    case 'metric':
+      return renderSingleMetric(node)
+    case 'text':
+    case 'box':
+    default:
+      // Handle text content - check props.content, node.text, then children
+      if (node.props?.content !== undefined) {
+        text = String(node.props.content)
+      } else if (node.text !== undefined) {
+        text = node.text
+      } else if (typeof node.children === 'string') {
+        text = node.children
+      } else if (Array.isArray(node.children)) {
+        text = renderChildren(node.children, options)
+      }
+  }
+
+  // Apply styles if present
+  if (hasStyles(node.props)) {
+    const codes = buildStyleCodes(node.props, options)
+    if (codes.length > 0) {
+      return `${codes.join('')}${text}${ANSI.reset}`
+    }
+  }
+
+  return text
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Renders a UINode tree to an ANSI-escaped string for terminal output.
+ *
+ * @param node - The UINode tree to render
+ * @param options - Rendering options (color support, theme, width)
+ * @returns ANSI-escaped string ready for terminal output
+ *
+ * @example
+ * ```tsx
+ * const node = { type: 'text', text: 'Hello', props: { color: 'cyan', bold: true } }
+ * const output = renderANSI(node)
+ * console.log(output) // Outputs bold cyan text
+ * ```
+ */
+export function renderANSI(node: UINode, options?: ANSIRenderOptions): string {
+  return renderNode(node, options || {})
+}