@mdxui/terminal 2.0.0

package/src/renderers/unicode.ts

@@ -0,0 +1,917 @@
+/**
+ * Unicode Renderer - Renders UINode trees using Unicode box-drawing characters
+ *
+ * This renderer is part of the 6-tier Universal Terminal UI system.
+ * It uses Unicode characters for beautiful terminal output without ANSI colors.
+ *
+ * Unicode box drawing characters:
+ * - Single: ┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼
+ * - Double: ╔ ═ ╗ ║ ╚ ╝
+ * - Rounded: ╭ ╮ ╰ ╯
+ *
+ * Bullets: • ◦ ▪ ▸ ▾ ✓ ✗
+ * Progress: ▓ ░ ▒
+ * Spinners: ⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏
+ */
+
+import type { UINode, RenderContext, ThemeTokens } from '../core/types'
+import {
+  DEFAULT_THEME_TOKENS,
+  DEFAULT_RENDER_CONTEXT,
+  type BoxChars,
+  getUnicodeBoxChars,
+  UNICODE_SYMBOLS,
+  SPINNER_FRAMES,
+} from './utils'
+
+// ============================================================================
+// Unicode Characters
+// ============================================================================
+
+const UNICODE = {
+  // Single box drawing
+  topLeft: '┌',
+  topRight: '┐',
+  bottomLeft: '└',
+  bottomRight: '┘',
+  horizontal: '─',
+  vertical: '│',
+
+  // T-junctions
+  teeLeft: '├',
+  teeRight: '┤',
+  teeTop: '┬',
+  teeBottom: '┴',
+  crossJunction: '┼',
+
+  // Double box drawing
+  doubleTopLeft: '╔',
+  doubleTopRight: '╗',
+  doubleBottomLeft: '╚',
+  doubleBottomRight: '╝',
+  doubleHorizontal: '═',
+  doubleVertical: '║',
+
+  // Rounded corners
+  roundedTopLeft: '╭',
+  roundedTopRight: '╮',
+  roundedBottomLeft: '╰',
+  roundedBottomRight: '╯',
+
+  // Bullets and list markers
+  bullet: '•',
+  hollowBullet: '◦',
+  squareBullet: '▪',
+  triangleRight: '▸',
+  triangleDown: '▾',
+  checkmark: '✓',
+  crossMark: '✗',
+  unchecked: '☐',
+  arrowRight: '→',
+  arrowDown: '↓',
+
+  // Progress bar characters
+  progressFull: '▓',
+  progressEmpty: '░',
+  progressHalf: '▒',
+
+  // Dividers
+  ellipsis: '…',
+  middleDot: '·',
+} as const
+
+// Note: SPINNER_FRAMES is now imported from utils
+
+// ============================================================================
+// Default Context
+// ============================================================================
+
+function createDefaultTheme(): ThemeTokens {
+  return { ...DEFAULT_THEME_TOKENS }
+}
+
+function createDefaultContext(): RenderContext {
+  return {
+    tier: 'unicode',
+    width: DEFAULT_RENDER_CONTEXT.width,
+    height: DEFAULT_RENDER_CONTEXT.height,
+    depth: DEFAULT_RENDER_CONTEXT.depth,
+    theme: createDefaultTheme(),
+    interactive: false,
+  }
+}
+
+// ============================================================================
+// Box Rendering
+// ============================================================================
+
+// Note: BoxChars interface and getUnicodeBoxChars are now imported from utils
+
+function renderBox(node: UINode, context: RenderContext): string {
+  const props = node.props || {}
+  const border = (props.border as string) || 'single'
+  const chars = getUnicodeBoxChars(border)
+
+  // Render children first to determine content
+  let content = ''
+  if (node.children && (typeof node.children === 'string' || node.children.length > 0)) {
+    if (typeof node.children === 'string') {
+      content = node.children
+    } else {
+      content = node.children
+        .map((child: UINode) => renderUnicode(child, { ...context, depth: context.depth + 1 }))
+        .join('\n')
+    }
+  }
+
+  const contentLines = content ? content.split('\n') : []
+  const contentWidth = Math.max(
+    ...contentLines.map((line) => line.length),
+    0
+  )
+
+  // Determine box dimensions
+  let width = (props.width as number) || contentWidth + 2 || 6
+  let height = (props.height as number) || contentLines.length + 2 || 3
+
+  // Handle zero dimensions
+  if (width <= 0) width = 2
+  if (height <= 0) return ''
+
+  const innerWidth = Math.max(width - 2, 0)
+
+  // Build box
+  const lines: string[] = []
+
+  // Top border
+  lines.push(chars.topLeft + chars.horizontal.repeat(innerWidth) + chars.topRight)
+
+  // Content lines
+  const numContentLines = height - 2
+  for (let i = 0; i < numContentLines; i++) {
+    const lineContent = contentLines[i] || ''
+    const paddedContent = lineContent.padEnd(innerWidth, ' ')
+    lines.push(chars.vertical + paddedContent.slice(0, innerWidth) + chars.vertical)
+  }
+
+  // Bottom border
+  lines.push(chars.bottomLeft + chars.horizontal.repeat(innerWidth) + chars.bottomRight)
+
+  return lines.join('\n')
+}
+
+// ============================================================================
+// Text Rendering
+// ============================================================================
+
+function renderText(node: UINode): string {
+  const content = (node.props?.content as string) || ''
+  // Unicode tier ignores style props (bold, color, etc.) - no ANSI codes
+  return content
+}
+
+// ============================================================================
+// List Rendering
+// ============================================================================
+
+function renderList(node: UINode, context: RenderContext): string {
+  const style = (node.props?.style as string) || 'unordered'
+  const items = node.props?.items as Array<string | { text: string; checked?: boolean }> | undefined
+  const numbered = (node.props?.numbered as boolean) ?? false
+  const taskList = (node.props?.taskList as boolean) ?? false
+  const children = Array.isArray(node.children) ? node.children : []
+  const lines: string[] = []
+
+  // Handle items prop
+  if (items && items.length > 0) {
+    items.forEach((item, index) => {
+      let text: string
+      let marker: string
+
+      if (typeof item === 'string') {
+        text = item
+        if (style === 'ordered' || numbered) {
+          marker = `${index + 1}. `
+        } else {
+          marker = `${UNICODE.bullet} `
+        }
+      } else {
+        text = item.text ?? ''
+        if (taskList && 'checked' in item) {
+          marker = item.checked ? `${UNICODE.checkmark} ` : `${UNICODE.unchecked} `
+        } else if (style === 'ordered' || numbered) {
+          marker = `${index + 1}. `
+        } else {
+          marker = `${UNICODE.bullet} `
+        }
+      }
+
+      lines.push(marker + text)
+    })
+  }
+
+  // Handle list-item children
+  children.forEach((child: UINode, index: number) => {
+    if (child.type === 'list-item') {
+      const content = (child.props?.content as string) || ''
+      let marker: string
+
+      if (style === 'ordered' || numbered) {
+        marker = `${index + 1}. `
+      } else if (style === 'checklist' || taskList) {
+        const checked = child.props?.checked as boolean
+        marker = checked ? `${UNICODE.checkmark} ` : `${UNICODE.unchecked} `
+      } else {
+        // unordered
+        marker = `${UNICODE.bullet} `
+      }
+
+      lines.push(marker + content)
+
+      // Handle nested lists
+      if (child.children && Array.isArray(child.children) && child.children.length > 0) {
+        child.children.forEach((nestedChild: UINode) => {
+          if (nestedChild.type === 'list') {
+            const nestedLines = renderNestedList(nestedChild, context)
+            lines.push(...nestedLines.split('\n').map((line) => '  ' + line))
+          }
+        })
+      }
+    }
+  })
+
+  return lines.join('\n')
+}
+
+function renderNestedList(node: UINode, context: RenderContext, depth = 1): string {
+  const style = (node.props?.style as string) || 'unordered'
+  const children = Array.isArray(node.children) ? node.children : []
+  const lines: string[] = []
+
+  // Different bullet styles for different nesting levels
+  const bulletStyles = [UNICODE.bullet, UNICODE.hollowBullet, '▪', '▫', '▸']
+  const bullet = bulletStyles[Math.min(depth, bulletStyles.length - 1)]
+
+  children.forEach((child: UINode, index: number) => {
+    if (child.type === 'list-item') {
+      const content = (child.props?.content as string) || ''
+      let marker: string
+
+      if (style === 'ordered') {
+        marker = `${index + 1}. `
+      } else {
+        // Use different bullet for nested unordered lists
+        marker = `${bullet} `
+      }
+
+      lines.push(marker + content)
+
+      // Handle deeper nested lists
+      if (child.children && Array.isArray(child.children) && child.children.length > 0) {
+        child.children.forEach((nestedChild: UINode) => {
+          if (nestedChild.type === 'list') {
+            const nestedLines = renderNestedList(nestedChild, context, depth + 1)
+            lines.push(...nestedLines.split('\n').map((line) => '  ' + line))
+          }
+        })
+      }
+    }
+  })
+
+  return lines.join('\n')
+}
+
+// ============================================================================
+// Progress Bar Rendering
+// ============================================================================
+
+function renderProgress(node: UINode): string {
+  const value = (node.props?.value as number) || 0
+  const max = (node.props?.max as number) || 100
+  const width = (node.props?.width as number) || 10
+
+  const percentage = Math.min(Math.max(value / max, 0), 1)
+  const filledBlocks = percentage * width
+
+  const fullBlocks = Math.floor(filledBlocks)
+  const hasHalf = filledBlocks - fullBlocks >= 0.5
+  const emptyBlocks = width - fullBlocks - (hasHalf ? 1 : 0)
+
+  let bar = UNICODE.progressFull.repeat(fullBlocks)
+  if (hasHalf) {
+    bar += UNICODE.progressHalf
+  }
+  bar += UNICODE.progressEmpty.repeat(Math.max(emptyBlocks, 0))
+
+  return bar
+}
+
+// ============================================================================
+// Table Rendering
+// ============================================================================
+
+interface TableColumn {
+  key: string
+  header: string
+  width: number
+}
+
+function renderTable(node: UINode, context: RenderContext): string {
+  const props = node.props || {}
+  const columns = (props.columns as TableColumn[]) || []
+  // Support data from node.data (TDD tests) or props.data (legacy)
+  const nodeData = node.data as Record<string, unknown>[] | undefined
+  const propsData = props.data as Record<string, unknown>[] | undefined
+  const data = nodeData ?? propsData ?? []
+  const rowSeparators = props.rowSeparators as boolean
+
+  if (columns.length === 0) return ''
+
+  const lines: string[] = []
+
+  // Build widths array - calculate from content if not specified
+  const widths = columns.map((col) => {
+    if (col.width && col.width > 0) return col.width
+
+    // Calculate based on header and data
+    let maxWidth = col.header.length
+    for (const row of data) {
+      const val = row[col.key]
+      const str = val != null ? String(val) : ''
+      maxWidth = Math.max(maxWidth, str.length)
+    }
+    return maxWidth
+  })
+
+  // Top border
+  const topBorder =
+    UNICODE.topLeft +
+    widths.map((w) => UNICODE.horizontal.repeat(w)).join(UNICODE.teeTop) +
+    UNICODE.topRight
+  lines.push(topBorder)
+
+  // Header row
+  const headerRow =
+    UNICODE.vertical +
+    columns.map((col, i) => col.header.padEnd(widths[i]).slice(0, widths[i])).join(UNICODE.vertical) +
+    UNICODE.vertical
+  lines.push(headerRow)
+
+  // Header separator
+  const headerSep =
+    UNICODE.teeLeft +
+    widths.map((w) => UNICODE.horizontal.repeat(w)).join(UNICODE.crossJunction) +
+    UNICODE.teeRight
+  lines.push(headerSep)
+
+  // Data rows
+  data.forEach((row, rowIndex) => {
+    const dataRow =
+      UNICODE.vertical +
+      columns
+        .map((col, i) => {
+          const value = String(row[col.key] ?? '')
+          return value.padEnd(widths[i]).slice(0, widths[i])
+        })
+        .join(UNICODE.vertical) +
+      UNICODE.vertical
+    lines.push(dataRow)
+
+    // Row separator if enabled and not last row
+    if (rowSeparators && rowIndex < data.length - 1) {
+      const rowSep =
+        UNICODE.teeLeft +
+        widths.map((w) => UNICODE.horizontal.repeat(w)).join(UNICODE.crossJunction) +
+        UNICODE.teeRight
+      lines.push(rowSep)
+    }
+  })
+
+  // Bottom border
+  const bottomBorder =
+    UNICODE.bottomLeft +
+    widths.map((w) => UNICODE.horizontal.repeat(w)).join(UNICODE.teeBottom) +
+    UNICODE.bottomRight
+  lines.push(bottomBorder)
+
+  return lines.join('\n')
+}
+
+// ============================================================================
+// Panel Rendering
+// ============================================================================
+
+function renderPanel(node: UINode, context: RenderContext): string {
+  const props = node.props || {}
+  const title = (props.title as string) || ''
+  const width = (props.width as number) || 40
+
+  // Render children
+  let content = ''
+  if (node.children && (typeof node.children === 'string' || node.children.length > 0)) {
+    if (typeof node.children === 'string') {
+      content = node.children
+    } else {
+      content = node.children
+        .map((child: UINode) => renderUnicode(child, { ...context, depth: context.depth + 1 }))
+        .join('\n')
+    }
+  }
+
+  const innerWidth = width - 2
+  const lines: string[] = []
+
+  // Top border
+  lines.push(UNICODE.topLeft + UNICODE.horizontal.repeat(innerWidth) + UNICODE.topRight)
+
+  // Title row
+  const paddedTitle = (' ' + title + ' ').padEnd(innerWidth).slice(0, innerWidth)
+  lines.push(UNICODE.vertical + paddedTitle + UNICODE.vertical)
+
+  // Title separator
+  lines.push(UNICODE.teeLeft + UNICODE.horizontal.repeat(innerWidth) + UNICODE.teeRight)
+
+  // Content rows
+  const contentLines = content ? content.split('\n') : []
+  contentLines.forEach((line) => {
+    const paddedLine = (' ' + line).padEnd(innerWidth).slice(0, innerWidth)
+    lines.push(UNICODE.vertical + paddedLine + UNICODE.vertical)
+  })
+
+  // Bottom border
+  lines.push(UNICODE.bottomLeft + UNICODE.horizontal.repeat(innerWidth) + UNICODE.bottomRight)
+
+  return lines.join('\n')
+}
+
+// ============================================================================
+// Divider Rendering
+// ============================================================================
+
+function renderDivider(node: UINode, context: RenderContext): string {
+  const props = node.props || {}
+  const label = props.label as string | undefined
+  const width = (props.width as number) || context.width || 40
+
+  if (label) {
+    const labelWithSpaces = ` ${label} `
+    const remaining = width - labelWithSpaces.length
+    const leftSide = Math.floor(remaining / 2)
+    const rightSide = remaining - leftSide
+    return (
+      UNICODE.horizontal.repeat(Math.max(leftSide, 0)) +
+      labelWithSpaces +
+      UNICODE.horizontal.repeat(Math.max(rightSide, 0))
+    )
+  }
+
+  return UNICODE.horizontal.repeat(width)
+}
+
+// ============================================================================
+// Spinner Rendering
+// ============================================================================
+
+function renderSpinner(node: UINode): string {
+  const props = node.props || {}
+  const frame = (props.frame as number) || 0
+  const label = props.label as string | undefined
+
+  const spinnerChar = SPINNER_FRAMES[frame % SPINNER_FRAMES.length]
+
+  if (label) {
+    return `${spinnerChar} ${label}`
+  }
+
+  return spinnerChar
+}
+
+// ============================================================================
+// Badge Rendering
+// ============================================================================
+
+function renderBadge(node: UINode): string {
+  const props = node.props || {}
+  const content = (props.content as string) || ''
+  // Use unicode brackets
+  return `【${content}】`
+}
+
+// ============================================================================
+// Tree Rendering
+// ============================================================================
+
+function renderTree(node: UINode, context: RenderContext): string {
+  const children = Array.isArray(node.children) ? node.children : []
+  const lines: string[] = []
+
+  children.forEach((child: UINode) => {
+    if (child.type === 'tree-item') {
+      const treeLines = renderTreeItem(child, '', true, context, true)
+      lines.push(...treeLines)
+    }
+  })
+
+  return lines.join('\n')
+}
+
+function renderTreeItem(
+  node: UINode,
+  prefix: string,
+  isLast: boolean,
+  context: RenderContext,
+  isRoot: boolean = false
+): string[] {
+  const label = (node.props?.label as string) || ''
+  const children = Array.isArray(node.children) ? node.children : []
+  const lines: string[] = []
+
+  // Root items have no connector prefix
+  if (isRoot) {
+    lines.push(label)
+  } else {
+    const connector = isLast ? UNICODE.bottomLeft : UNICODE.teeLeft
+    lines.push(prefix + connector + UNICODE.horizontal + UNICODE.horizontal + ' ' + label)
+  }
+
+  // Determine prefix for children
+  // For root items, children start with empty prefix (just the connector)
+  // For non-root items, extend the prefix with continuation lines
+  const childPrefix = isRoot ? '' : prefix + (isLast ? '    ' : UNICODE.vertical + '   ')
+
+  // Render children
+  children.forEach((child: UINode, index: number) => {
+    if (child.type === 'tree-item') {
+      const isChildLast = index === children.length - 1
+      const childLines = renderTreeItem(child, childPrefix, isChildLast, context, false)
+      lines.push(...childLines)
+    }
+  })
+
+  return lines
+}
+
+// ============================================================================
+// Breadcrumb Rendering
+// ============================================================================
+
+function renderBreadcrumb(node: UINode): string {
+  const children = Array.isArray(node.children) ? node.children : []
+  const items: string[] = []
+
+  children.forEach((child: UINode) => {
+    if (child.type === 'breadcrumb-item') {
+      const label = (child.props?.label as string) || ''
+      items.push(label)
+    }
+  })
+
+  return items.join(` ${UNICODE.arrowRight} `)
+}
+
+// ============================================================================
+// Tooltip Rendering
+// ============================================================================
+
+function renderTooltip(node: UINode): string {
+  const props = node.props || {}
+  const content = (props.content as string) || ''
+  const position = (props.position as string) || 'top'
+
+  let pointer = '▲' // default top
+  switch (position) {
+    case 'bottom':
+      pointer = '▼'
+      break
+    case 'left':
+      pointer = '◀'
+      break
+    case 'right':
+      pointer = '▶'
+      break
+  }
+
+  return `${pointer} ${content}`
+}
+
+// ============================================================================
+// Input Rendering
+// ============================================================================
+
+function renderInput(node: UINode, context: RenderContext): string {
+  const props = node.props || {}
+  const label = (props.label as string) || ''
+  const value = (props.value as string) || ''
+
+  return `${label}: [${value}]`
+}
+
+// ============================================================================
+// Button Rendering
+// ============================================================================
+
+function renderButton(node: UINode): string {
+  const props = node.props || {}
+  const label = (props.label as string) || ''
+
+  return `[ ${label} ]`
+}
+
+// ============================================================================
+// Card Rendering
+// ============================================================================
+
+function renderCard(node: UINode, context: RenderContext): 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 border = node.props?.border as string | undefined
+
+  const contentLines: string[] = []
+
+  // Title section
+  if (title) {
+    let titleLine = title
+    if (badge) {
+      titleLine += ` 【${badge.content}】`
+    }
+    if (titleAction) {
+      titleLine += ` ${UNICODE.arrowRight} ${titleAction.label}`
+    }
+    contentLines.push(titleLine)
+  }
+
+  if (subtitle) {
+    contentLines.push(subtitle)
+  }
+
+  // Key-value pairs
+  if (pairs && pairs.length > 0) {
+    if (contentLines.length > 0) contentLines.push('')
+    for (const pair of pairs) {
+      const val = pair.value != null ? String(pair.value) : ''
+      contentLines.push(`${pair.key}: ${val}`)
+    }
+  }
+
+  // Children content
+  if (node.children && (typeof node.children === 'string' || node.children.length > 0)) {
+    if (contentLines.length > 0) contentLines.push('')
+    let childContent: string
+    if (typeof node.children === 'string') {
+      childContent = node.children
+    } else {
+      childContent = node.children
+        .map((child: UINode) => renderUnicode(child, { ...context, depth: context.depth + 1 }))
+        .join('\n')
+    }
+    if (childContent) {
+      contentLines.push(childContent)
+    }
+  }
+
+  // Actions
+  if (actions && actions.length > 0) {
+    if (contentLines.length > 0) contentLines.push('')
+    const actionLabels = actions.map((a) => `[ ${a.label} ]`).join(' ')
+    contentLines.push(actionLabels)
+  }
+
+  // If border is specified, wrap content in a box
+  if (border) {
+    const chars = getUnicodeBoxChars(border)
+    // Calculate the width based on content
+    const contentWidth = Math.max(
+      ...contentLines.map((line) => line.length),
+      0
+    )
+    const boxWidth = contentWidth + 4 // 2 for border chars, 2 for padding
+
+    const lines: string[] = []
+    const innerWidth = boxWidth - 2
+
+    // Top border
+    lines.push(chars.topLeft + chars.horizontal.repeat(innerWidth) + chars.topRight)
+
+    // Content lines with padding
+    for (const line of contentLines) {
+      const paddedLine = ' ' + line.padEnd(innerWidth - 2) + ' '
+      lines.push(chars.vertical + paddedLine.slice(0, innerWidth) + chars.vertical)
+    }
+
+    // If no content, add an empty line
+    if (contentLines.length === 0) {
+      lines.push(chars.vertical + ' '.repeat(innerWidth) + chars.vertical)
+    }
+
+    // Bottom border
+    lines.push(chars.bottomLeft + chars.horizontal.repeat(innerWidth) + chars.bottomRight)
+
+    return lines.join('\n')
+  }
+
+  return contentLines.join('\n')
+}
+
+// ============================================================================
+// Metrics Rendering
+// ============================================================================
+
+// Sparkline characters (8 levels of height)
+const SPARKLINE_CHARS = ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█']
+
+// Trend arrow characters
+const TREND_ARROWS = {
+  up: '↑',
+  down: '↓',
+  neutral: '→',
+}
+
+function renderSparkline(data: number[]): string {
+  if (!data || data.length === 0) return ''
+  const min = Math.min(...data)
+  const max = Math.max(...data)
+  const range = max - min || 1 // Avoid division by zero
+  return data
+    .map((v) => {
+      const normalized = (v - min) / range
+      const charIndex = Math.min(Math.floor(normalized * 8), 7)
+      return SPARKLINE_CHARS[charIndex]
+    })
+    .join('')
+}
+
+function renderMetrics(node: UINode): string {
+  const metrics = node.props?.metrics as Array<{
+    label: string
+    value: unknown
+    format?: string
+    unit?: string
+    trend?: 'up' | 'down' | 'neutral'
+    trendValue?: number
+    sparkline?: number[]
+  }> | undefined
+
+  if (!metrics || metrics.length === 0) return ''
+
+  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}`
+    }
+
+    // Add trend arrow if specified
+    if (m.trend && TREND_ARROWS[m.trend]) {
+      formatted = `${formatted} ${TREND_ARROWS[m.trend]}`
+      if (m.trendValue !== undefined) {
+        formatted = `${formatted} ${m.trendValue}%`
+      }
+    }
+
+    // Add sparkline if specified
+    if (m.sparkline && m.sparkline.length > 0) {
+      const sparkline = renderSparkline(m.sparkline)
+      formatted = `${formatted} ${sparkline}`
+    }
+
+    lines.push(`${m.label}: ${formatted}`)
+  }
+
+  return lines.join('\n')
+}
+
+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 Render Function
+// ============================================================================
+
+/**
+ * Renders a UINode tree to Unicode box-drawing output.
+ *
+ * This renderer is part of the 6-tier Universal Terminal UI system.
+ * It outputs Unicode characters for beautiful terminal borders and
+ * symbols without using ANSI escape sequences for colors.
+ *
+ * @param node - The UINode tree to render
+ * @param context - Optional render context with width, height, theme
+ * @returns Unicode string ready for terminal output
+ *
+ * @example
+ * ```ts
+ * const node: UINode = {
+ *   type: 'box',
+ *   props: { border: 'single' },
+ *   children: [{ type: 'text', props: { content: 'Hello' } }]
+ * }
+ *
+ * const output = renderUnicode(node)
+ * // ┌───────┐
+ * // │ Hello │
+ * // └───────┘
+ * ```
+ */
+export function renderUnicode(node: UINode, context?: RenderContext): string {
+  const ctx = context || createDefaultContext()
+
+  switch (node.type) {
+    case 'text':
+      return renderText(node)
+
+    case 'box':
+      return renderBox(node, ctx)
+
+    case 'list':
+      return renderList(node, ctx)
+
+    case 'list-item':
+      // List items are handled by list
+      return (node.props?.content as string) || ''
+
+    case 'progress':
+      return renderProgress(node)
+
+    case 'table':
+      return renderTable(node, ctx)
+
+    case 'panel':
+      return renderPanel(node, ctx)
+
+    case 'divider':
+      return renderDivider(node, ctx)
+
+    case 'spinner':
+      return renderSpinner(node)
+
+    case 'badge':
+      return renderBadge(node)
+
+    case 'tree':
+      return renderTree(node, ctx)
+
+    case 'tree-item':
+      return (node.props?.label as string) || ''
+
+    case 'breadcrumb':
+      return renderBreadcrumb(node)
+
+    case 'breadcrumb-item':
+      return (node.props?.label as string) || ''
+
+    case 'tooltip':
+      return renderTooltip(node)
+
+    case 'input':
+      return renderInput(node, ctx)
+
+    case 'button':
+      return renderButton(node)
+
+    case 'card':
+      return renderCard(node, ctx)
+
+    case 'metrics':
+      return renderMetrics(node)
+
+    case 'metric':
+      return renderSingleMetric(node)
+
+    default:
+      // Unknown node type - return empty or render children
+      if (node.children && (typeof node.children === 'string' || node.children.length > 0)) {
+        if (typeof node.children === 'string') {
+          return node.children
+        }
+        return node.children
+          .map((child: UINode) => renderUnicode(child, { ...ctx, depth: ctx.depth + 1 }))
+          .join('\n')
+      }
+      return ''
+  }
+}