@mdxui/terminal 2.0.0

package/src/renderers/ascii.ts

@@ -0,0 +1,680 @@
+/**
+ * ASCII Renderer - TDD GREEN Phase Implementation
+ *
+ * This file implements the ASCII renderer for the 6-tier Universal Terminal UI.
+ * All output uses pure ASCII characters (0x00-0x7F) for maximum compatibility.
+ *
+ * ASCII Tier Constraints:
+ * - Output must contain ONLY ASCII characters (0x00-0x7F)
+ * - No unicode box drawing characters (U+2500-U+257F)
+ * - No ANSI escape sequences
+ * - No emoji or special symbols
+ */
+
+import type { UINode, RenderContext, ThemeTokens } from '../core/types'
+import {
+  sanitizeToASCII,
+  boxDrawingToASCII,
+  wrapText,
+  padText,
+  DEFAULT_THEME_TOKENS,
+  DEFAULT_RENDER_CONTEXT,
+  getASCIIBoxChars,
+  calculateColumnWidths,
+  buildTableSeparator,
+  buildTableRow,
+} from './utils'
+
+// Default context values
+const DEFAULT_WIDTH = DEFAULT_RENDER_CONTEXT.width
+const DEFAULT_HEIGHT = DEFAULT_RENDER_CONTEXT.height
+
+const DEFAULT_THEME: ThemeTokens = { ...DEFAULT_THEME_TOKENS }
+
+/**
+ * Creates a default render context
+ */
+function createDefaultContext(): RenderContext {
+  return {
+    tier: 'ascii',
+    width: DEFAULT_WIDTH,
+    height: DEFAULT_HEIGHT,
+    depth: 0,
+    theme: DEFAULT_THEME,
+    interactive: false,
+  }
+}
+
+// sanitizeToASCII, boxDrawingToASCII, and wrapText are now imported from ./utils
+
+/**
+ * Renders a UINode tree to pure ASCII output for low-capability terminals.
+ */
+export function renderASCII(node: UINode, context?: RenderContext): string {
+  const ctx = context ?? createDefaultContext()
+  return renderNode(node, ctx)
+}
+
+/**
+ * Main node renderer - dispatches to type-specific renderers
+ */
+function renderNode(node: UINode, ctx: RenderContext): string {
+  switch (node.type) {
+    case 'text':
+      return renderText(node, ctx)
+    case 'box':
+      return renderBox(node, ctx)
+    case 'table':
+      return renderTable(node, ctx)
+    case 'list':
+      return renderList(node, ctx)
+    case 'progress':
+      return renderProgress(node, ctx)
+    case 'spinner':
+      return renderSpinner(node, ctx)
+    case 'panel':
+      return renderPanel(node, ctx)
+    case 'card':
+      return renderCard(node, ctx)
+    case 'badge':
+      return renderBadge(node, ctx)
+    case 'button':
+      return renderButton(node, ctx)
+    case 'input':
+      return renderInput(node, ctx)
+    case 'select':
+      return renderSelect(node, ctx)
+    case 'dialog':
+      return renderDialog(node, ctx)
+    case 'breadcrumb':
+      return renderBreadcrumb(node, ctx)
+    case 'sidebar':
+      return renderSidebar(node, ctx)
+    case 'metrics':
+      return renderMetrics(node, ctx)
+    case 'metric':
+      return renderSingleMetric(node, ctx)
+    default:
+      // Unknown type - render children if present
+      return renderChildren(node, ctx)
+  }
+}
+
+/**
+ * Renders children of a node
+ */
+function renderChildren(node: UINode, ctx: RenderContext): string {
+  if (!node.children || node.children.length === 0) {
+    return ''
+  }
+  if (typeof node.children === 'string') {
+    return node.children
+  }
+  return node.children.map((child) => renderNode(child, ctx)).join('\n')
+}
+
+/**
+ * Renders a text node
+ */
+function renderText(node: UINode, ctx: RenderContext): string {
+  const content = String(node.props?.content ?? '')
+  const sanitized = sanitizeToASCII(content)
+  const width = ctx.width > 0 ? ctx.width : DEFAULT_WIDTH
+  const lines = wrapText(sanitized, width)
+  return lines.join('\n')
+}
+
+/**
+ * Renders a box with ASCII borders
+ */
+function renderBox(node: UINode, ctx: RenderContext): string {
+  const border = node.props?.border as string
+  const explicitWidth = node.props?.width as number | undefined
+  const padding = (node.props?.padding as number) ?? 0
+
+  // If border is 'none', just render content
+  if (border === 'none') {
+    return renderChildren(node, ctx)
+  }
+
+  // Get border characters from shared utils
+  const chars = getASCIIBoxChars(border)
+  const { horizontal, vertical } = chars
+  const corner = chars.topLeft // All corners are '+' in ASCII
+
+  // Calculate available inner width for children
+  // We need at least some space for the content
+  const availableWidth = explicitWidth ?? ctx.width
+  const neededForBorders = 2 + padding * 2 // | on each side + padding
+  const childWidth = Math.max(1, availableWidth - neededForBorders)
+
+  // Render children first to determine content
+  const childCtx: RenderContext = {
+    ...ctx,
+    depth: ctx.depth + 1,
+    width: childWidth,
+  }
+  const childContent = renderChildren(node, childCtx)
+  const contentLines = childContent.split('\n').filter((line, idx, arr) => {
+    // Keep all lines, including empty ones in the middle
+    return line.length > 0 || (idx > 0 && idx < arr.length - 1)
+  })
+
+  // Calculate box width based on actual content (not wrapped to child width)
+  let contentWidth = 0
+  for (const line of contentLines) {
+    contentWidth = Math.max(contentWidth, line.length)
+  }
+
+  // If explicit width is set, use it (minus borders)
+  let innerWidth: number
+  if (explicitWidth !== undefined) {
+    innerWidth = explicitWidth - 2 // Account for | on each side
+  } else {
+    // Use content width, but ensure enough space for content + padding
+    innerWidth = Math.max(contentWidth + padding * 2, 1)
+  }
+
+  // Respect context width, but ensure minimum space for content
+  if (ctx.width > 0 && innerWidth > ctx.width - 2) {
+    innerWidth = ctx.width - 2
+  }
+
+  // Build the box
+  const lines: string[] = []
+  const topBottom = corner + horizontal.repeat(Math.max(innerWidth, 1)) + corner
+  lines.push(topBottom)
+
+  // Add padding lines at top
+  for (let i = 0; i < padding; i++) {
+    lines.push(vertical + ' '.repeat(innerWidth) + vertical)
+  }
+
+  // Add content lines (or at least one empty line)
+  const linesToRender = contentLines.length > 0 ? contentLines : ['']
+  for (const line of linesToRender) {
+    const paddedLine = ' '.repeat(padding) + line
+    // Ensure the line fits within innerWidth
+    const truncated = paddedLine.length > innerWidth ? paddedLine.slice(0, innerWidth) : paddedLine
+    const padded = truncated.padEnd(innerWidth)
+    lines.push(vertical + padded + vertical)
+  }
+
+  // Add padding lines at bottom
+  for (let i = 0; i < padding; i++) {
+    lines.push(vertical + ' '.repeat(innerWidth) + vertical)
+  }
+
+  lines.push(topBottom)
+
+  return lines.join('\n')
+}
+
+/**
+ * Renders a table with ASCII borders
+ */
+function renderTable(node: UINode, ctx: RenderContext): string {
+  // Support new TDD format (columns + node.data) and legacy format (headers + rows)
+  const columns = node.props?.columns as Array<{ key: string; header: string }> | undefined
+  const nodeData = (node.data as Array<Record<string, unknown>> | undefined) ??
+                   (node.props?.data as Array<Record<string, unknown>> | undefined)
+
+  let headers: string[] = []
+  let rows: string[][] = []
+
+  if (columns && columns.length > 0) {
+    // New TDD format
+    headers = columns.map((col) => col.header)
+    if (nodeData && nodeData.length > 0) {
+      rows = nodeData.map((row) =>
+        columns.map((col) => {
+          const val = row[col.key]
+          return val != null ? String(val) : ''
+        })
+      )
+    }
+  } else {
+    // Legacy format
+    headers = (node.props?.headers as string[]) ?? []
+    rows = (node.props?.rows as string[][]) ?? []
+  }
+
+  // Handle empty table
+  if (headers.length === 0 && rows.length === 0) {
+    return ''
+  }
+
+  // Calculate column widths using shared utility
+  const maxTableWidth = ctx.width > 0 ? ctx.width : DEFAULT_WIDTH
+  const colWidths = calculateColumnWidths(headers, rows, maxTableWidth)
+
+  // Table separator characters (ASCII)
+  const separatorChars = { left: '+', middle: '+', right: '+', horizontal: '-' }
+
+  const lines: string[] = []
+  lines.push(buildTableSeparator(colWidths, separatorChars))
+
+  // Headers
+  if (headers.length > 0) {
+    lines.push(buildTableRow(headers, colWidths, '|'))
+    lines.push(buildTableSeparator(colWidths, separatorChars))
+  }
+
+  // Data rows
+  for (const row of rows) {
+    // Handle multi-line cells - for now just take first line
+    const processedRow = row.map((cell) => {
+      const firstLine = cell.split('\n')[0] ?? ''
+      return sanitizeToASCII(firstLine)
+    })
+    lines.push(buildTableRow(processedRow, colWidths, '|'))
+  }
+
+  if (rows.length > 0 || headers.length > 0) {
+    lines.push(buildTableSeparator(colWidths, separatorChars))
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Renders a list with ASCII bullets
+ */
+function renderList(node: UINode, ctx: RenderContext): string {
+  const items = (node.props?.items as Array<string | { text: string; checked?: boolean }>) ?? []
+  const ordered = (node.props?.ordered as boolean) ?? false
+  const numbered = (node.props?.numbered as boolean) ?? false
+  const taskList = (node.props?.taskList as boolean) ?? false
+  const bullet = (node.props?.bullet as string) ?? '*'
+
+  const lines: string[] = []
+
+  // Determine indent based on depth
+  const baseIndent = ctx.depth * 2
+  const indent = ' '.repeat(baseIndent)
+
+  // Handle items prop
+  if (items.length > 0) {
+    const maxNum = items.length
+    const numWidth = String(maxNum).length
+
+    for (let i = 0; i < items.length; i++) {
+      const item = items[i]
+      let text: string
+      let prefix: string
+
+      if (typeof item === 'string') {
+        text = sanitizeToASCII(item)
+        if (ordered || numbered) {
+          const num = String(i + 1).padStart(numWidth)
+          prefix = `${num}. `
+        } else {
+          prefix = `${bullet} `
+        }
+      } else {
+        text = sanitizeToASCII(item.text ?? '')
+        if (taskList && 'checked' in item) {
+          prefix = item.checked ? '[x] ' : '[ ] '
+        } else if (ordered || numbered) {
+          const num = String(i + 1).padStart(numWidth)
+          prefix = `${num}. `
+        } else {
+          prefix = `${bullet} `
+        }
+      }
+
+      lines.push(`${indent}${prefix}${text}`)
+    }
+  }
+
+  // Handle list-item children (TDD test format)
+  if (node.children && Array.isArray(node.children) && node.children.length > 0) {
+    const nestedCtx: RenderContext = {
+      ...ctx,
+      depth: ctx.depth + 1,
+    }
+    node.children.forEach((child: UINode, index: number) => {
+      if (child.type === 'list-item') {
+        const content = sanitizeToASCII(String(child.props?.content ?? ''))
+        const prefix = (ordered || numbered) ? `${index + 1}. ` : `${bullet} `
+        lines.push(`${indent}${prefix}${content}`)
+
+        // Handle nested children of list-item
+        if (child.children && Array.isArray(child.children) && child.children.length > 0) {
+          child.children.forEach((nestedChild: UINode) => {
+            const nestedOutput = renderNode(nestedChild, nestedCtx)
+            if (nestedOutput) {
+              lines.push(nestedOutput)
+            }
+          })
+        }
+      } else {
+        const nestedContent = renderNode(child, nestedCtx)
+        if (nestedContent.length > 0) {
+          lines.push(nestedContent)
+        }
+      }
+    })
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Renders a progress bar
+ */
+function renderProgress(node: UINode, ctx: RenderContext): string {
+  const value = Math.max(0, Math.min(100, Number(node.props?.value) ?? 0))
+  const barWidth = (node.props?.width as number) ?? 20
+  const showLabel = node.props?.showLabel as boolean
+  const label = node.props?.label as string | undefined
+
+  // Inner width (excluding brackets)
+  const innerWidth = Math.max(1, barWidth - 2)
+  const filledCount = Math.round((value / 100) * innerWidth)
+  const emptyCount = innerWidth - filledCount
+
+  const bar = '[' + '='.repeat(filledCount) + ' '.repeat(emptyCount) + ']'
+
+  let result = bar
+  if (showLabel) {
+    result += ` ${Math.round(value)}%`
+  }
+  if (label) {
+    result += ` ${label}`
+  }
+
+  return result
+}
+
+/**
+ * Renders a spinner (static frame for ASCII output)
+ */
+function renderSpinner(node: UINode, ctx: RenderContext): string {
+  const label = node.props?.label as string | undefined
+  // ASCII spinner frames: | / - \
+  const frame = '-' // Static frame for non-animated output
+
+  if (label) {
+    return `${frame} ${label}`
+  }
+  return frame
+}
+
+/**
+ * Renders a panel with title
+ */
+function renderPanel(node: UINode, ctx: RenderContext): string {
+  const title = String(node.props?.title ?? '')
+
+  // Render children
+  const childCtx: RenderContext = {
+    ...ctx,
+    depth: ctx.depth + 1,
+    width: Math.max(1, ctx.width - 4),
+  }
+  const childContent = renderChildren(node, childCtx)
+  const contentLines = childContent.split('\n')
+
+  // Calculate width
+  let contentWidth = title.length
+  for (const line of contentLines) {
+    contentWidth = Math.max(contentWidth, line.length)
+  }
+  const innerWidth = Math.min(contentWidth + 2, ctx.width > 0 ? ctx.width - 2 : DEFAULT_WIDTH - 2)
+
+  // Build panel
+  const lines: string[] = []
+  const topLine = '+' + '-'.repeat(innerWidth) + '+'
+  lines.push(topLine)
+
+  // Title line
+  if (title) {
+    const titlePadded = (' ' + title).padEnd(innerWidth)
+    lines.push('|' + titlePadded + '|')
+    lines.push('+' + '-'.repeat(innerWidth) + '+')
+  }
+
+  // Content
+  for (const line of contentLines) {
+    const padded = (' ' + line).padEnd(innerWidth)
+    lines.push('|' + padded + '|')
+  }
+
+  lines.push(topLine)
+
+  return lines.join('\n')
+}
+
+/**
+ * Renders a card
+ */
+function renderCard(node: UINode, ctx: 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 boolean | undefined
+
+  const contentLines: string[] = []
+
+  // Title section
+  if (title) {
+    let titleLine = title
+    if (badge) {
+      titleLine += ` [${badge.content}]`
+    }
+    if (titleAction) {
+      titleLine += ` | ${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('')
+    const childCtx: RenderContext = { ...ctx, depth: ctx.depth + 1 }
+    const childContent = renderChildren(node, childCtx)
+    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 true or not specified with title, wrap in box
+  if (border === true) {
+    const boxNode: UINode = {
+      type: 'box',
+      props: { border: 'single' },
+      children: [{ type: 'text', props: { content: contentLines.join('\n') } }],
+    }
+    return renderBox(boxNode, ctx)
+  }
+
+  return contentLines.join('\n')
+}
+
+/**
+ * Renders a badge
+ */
+function renderBadge(node: UINode, ctx: RenderContext): string {
+  const label = String(node.props?.label ?? '')
+  return `[${label}]`
+}
+
+/**
+ * Renders a button
+ */
+function renderButton(node: UINode, ctx: RenderContext): string {
+  const label = String(node.props?.label ?? '')
+  return `[ ${label} ]`
+}
+
+/**
+ * Renders an input field
+ */
+function renderInput(node: UINode, ctx: RenderContext): string {
+  const value = String(node.props?.value ?? '')
+  const placeholder = String(node.props?.placeholder ?? '')
+  const display = value || placeholder
+
+  return `[${display}]`
+}
+
+/**
+ * Renders a select dropdown
+ */
+function renderSelect(node: UINode, ctx: RenderContext): string {
+  const options = (node.props?.options as Array<{ label: string; value: string }>) ?? []
+  const selectedValue = node.props?.value as string
+
+  const lines: string[] = []
+  for (const opt of options) {
+    const marker = opt.value === selectedValue ? '>' : ' '
+    lines.push(`${marker} ${opt.label}`)
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Renders a dialog
+ */
+function renderDialog(node: UINode, ctx: RenderContext): string {
+  const title = String(node.props?.title ?? '')
+
+  // Render children
+  const childCtx: RenderContext = {
+    ...ctx,
+    depth: ctx.depth + 1,
+    width: Math.max(1, ctx.width - 4),
+  }
+  const childContent = renderChildren(node, childCtx)
+  const contentLines = childContent.split('\n')
+
+  // Calculate width
+  let contentWidth = title.length
+  for (const line of contentLines) {
+    contentWidth = Math.max(contentWidth, line.length)
+  }
+  const innerWidth = Math.min(contentWidth + 2, ctx.width > 0 ? ctx.width - 2 : DEFAULT_WIDTH - 2)
+
+  // Build dialog (similar to panel)
+  const lines: string[] = []
+  const topLine = '+' + '-'.repeat(innerWidth) + '+'
+  lines.push(topLine)
+
+  // Title line
+  if (title) {
+    const titlePadded = (' ' + title).padEnd(innerWidth)
+    lines.push('|' + titlePadded + '|')
+    lines.push('+' + '-'.repeat(innerWidth) + '+')
+  }
+
+  // Content
+  for (const line of contentLines) {
+    const padded = (' ' + line).padEnd(innerWidth)
+    lines.push('|' + padded + '|')
+  }
+
+  lines.push(topLine)
+
+  return lines.join('\n')
+}
+
+/**
+ * Renders breadcrumbs
+ */
+function renderBreadcrumb(node: UINode, ctx: RenderContext): string {
+  const items = (node.props?.items as Array<{ label: string; href?: string }>) ?? []
+  const labels = items.map((item) => item.label)
+  return labels.join(' > ')
+}
+
+/**
+ * Renders a sidebar
+ */
+function renderSidebar(node: UINode, ctx: RenderContext): string {
+  const items = (node.props?.items as Array<{ label: string; icon?: string }>) ?? []
+  const lines: string[] = []
+
+  for (const item of items) {
+    lines.push(`* ${item.label}`)
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Renders metrics (multiple metrics)
+ */
+function renderMetrics(node: UINode, ctx: RenderContext): string {
+  const metrics = node.props?.metrics as Array<{
+    label: string
+    value: unknown
+    format?: string
+    unit?: string
+    trend?: string
+  }> | 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}`
+    }
+    lines.push(`${m.label}: ${formatted}`)
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Renders a single metric
+ */
+function renderSingleMetric(node: UINode, ctx: RenderContext): 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}`
+}