@mdxui/terminal 2.0.0

package/src/renderers/text.ts

@@ -0,0 +1,791 @@
+/**
+ * Text Renderer - Plain text output without formatting
+ *
+ * The TEXT renderer is the first tier in the Universal Terminal UI's
+ * multi-tier rendering architecture. It outputs plain text without any
+ * formatting markers, colors, or special characters.
+ *
+ * Text Tier (tier 1 of 6):
+ * - Simple content only, no bold/italic/code markers
+ * - Tables rendered as key=value lines (one per line)
+ * - Lists rendered as bullet points (- item)
+ * - Metrics rendered as "Label: value" format
+ * - Nested structures indented (2 spaces per level)
+ * - Dashboard layout as labeled sections with separators
+ * - All special characters and formatting stripped
+ */
+
+import type { UINode } from '../core/types'
+import { getIndentStr, extractStringArray, extractHeaders, extractRowValues, joinParts, getProp } from './utils'
+
+/**
+ * Text render options
+ */
+export interface TextRenderOptions {
+  /** Current indentation level */
+  indent?: number
+}
+
+/**
+ * Renders a UINode tree to a plain text string.
+ *
+ * @param node - The UINode tree to render
+ * @param options - Optional rendering configuration
+ * @returns Plain text string
+ */
+export function renderText(node: UINode, options: TextRenderOptions = {}): string {
+  const indent = options.indent ?? 0
+  const indentStr = getIndentStr(indent)
+
+  const type = node.type
+  const props = node.props || {}
+  // Normalize children: string becomes a text node array
+  const rawChildren = node.children
+  const children: UINode[] = typeof rawChildren === 'string'
+    ? [{ type: 'text', props: { content: rawChildren } }]
+    : rawChildren || []
+
+  switch (type) {
+    case 'text':
+      return renderTextNode(props)
+
+    case 'header':
+      return renderHeader(props)
+
+    case 'list':
+      return renderList(props, children, indent)
+
+    case 'table':
+      return renderTable(props, node.data)
+
+    case 'code':
+      return renderCode(props)
+
+    case 'link':
+      return renderLink(props)
+
+    case 'button':
+      return renderButton(props)
+
+    case 'box':
+      return renderBox(props, children, indent)
+
+    case 'panel':
+      return renderPanel(props, children, indent)
+
+    case 'card':
+      return renderCard(props, children, indent)
+
+    case 'metrics':
+      return renderMetrics(props)
+
+    case 'metric':
+      return renderSingleMetric(props)
+
+    case 'sidebar':
+      return renderSidebar(props, indent)
+
+    case 'breadcrumb':
+      return renderBreadcrumb(props)
+
+    case 'badge':
+      return renderBadge(props)
+
+    case 'dialog':
+      return renderDialog(props, children, indent)
+
+    case 'spinner':
+      return renderSpinner(props)
+
+    case 'dashboard':
+      return renderDashboard(props, children, indent)
+
+    case 'settings':
+      return renderSettings(props, children, indent)
+
+    case 'input':
+      return renderInput(props)
+
+    case 'select':
+      return renderSelect(props)
+
+    case 'hero':
+      return renderHero(props)
+
+    case 'features':
+      return renderFeatures(props)
+
+    case 'pricing':
+      return renderPricing(props)
+
+    case 'faq':
+      return renderFAQ(props)
+
+    case 'footer':
+      return renderFooter(props)
+
+    default:
+      // Unknown types: render children only
+      return renderChildren(children, indent)
+  }
+}
+
+function renderTextNode(props: Record<string, unknown>): string {
+  const content = props.content
+  if (content == null) return ''
+  return String(content)
+}
+
+function renderHeader(props: Record<string, unknown>): string {
+  const content = props.content
+  const nav = props.nav as Array<{ label: string; href?: string }> | undefined
+  const callToAction = props.callToAction as string | undefined
+  const breadcrumbs = props.breadcrumbs as Array<{ label: string; href?: string }> | undefined
+
+  // If it has content (simple heading), return it
+  if (content != null) {
+    return String(content)
+  }
+
+  // Otherwise handle as site header with nav/cta/breadcrumbs
+  const parts: string[] = []
+
+  if (nav && Array.isArray(nav) && nav.length > 0) {
+    const navLabels = nav.map((item) => item.label).join(' | ')
+    parts.push(navLabels)
+  }
+
+  if (breadcrumbs && Array.isArray(breadcrumbs) && breadcrumbs.length > 0) {
+    const crumbLabels = breadcrumbs.map((item) => item.label).join(' > ')
+    parts.push(crumbLabels)
+  }
+
+  if (callToAction) {
+    parts.push(callToAction)
+  }
+
+  return parts.join('\n')
+}
+
+function renderList(
+  props: Record<string, unknown>,
+  children: UINode[],
+  indent: number
+): string {
+  const items = props.items as unknown[] | undefined
+  const numbered = getProp(props, 'numbered', false)
+  const taskList = getProp(props, 'taskList', false)
+  const indentStr = getIndentStr(indent)
+  const lines: string[] = []
+
+  // Handle items prop (simple items or task items)
+  if (items && Array.isArray(items)) {
+    items.forEach((item, index) => {
+      let text: string
+      let prefix: string
+
+      if (typeof item === 'string') {
+        text = item
+        prefix = numbered ? `${index + 1}. ` : '- '
+      } else if (typeof item === 'object' && item !== null) {
+        const itemObj = item as { text?: string; checked?: boolean }
+        text = itemObj.text ?? String(item)
+        if (taskList && 'checked' in itemObj) {
+          prefix = itemObj.checked ? '[x] ' : '[ ] '
+        } else {
+          prefix = numbered ? `${index + 1}. ` : '- '
+        }
+      } else {
+        text = String(item)
+        prefix = numbered ? `${index + 1}. ` : '- '
+      }
+
+      lines.push(`${indentStr}${prefix}${text}`)
+    })
+  }
+
+  // Handle list-item children (TDD test format)
+  const nestedChildren = (children && children.length > 0)
+    ? children
+    : (props.children as UINode[] | undefined)
+
+  if (nestedChildren && nestedChildren.length > 0) {
+    nestedChildren.forEach((child, index) => {
+      if (child.type === 'list-item') {
+        const content = child.props?.content as string ?? ''
+        const prefix = numbered ? `${index + 1}. ` : '- '
+        lines.push(`${indentStr}${prefix}${content}`)
+
+        // Handle nested children of list-item
+        const childChildren = child.children
+        if (childChildren && Array.isArray(childChildren) && childChildren.length > 0) {
+          childChildren.forEach((nestedChild: UINode) => {
+            const nestedOutput = renderText(nestedChild, { indent: indent + 1 })
+            if (nestedOutput) {
+              lines.push(nestedOutput)
+            }
+          })
+        }
+      } else {
+        const childOutput = renderText(child, { indent: indent + 1 })
+        if (childOutput) {
+          lines.push(childOutput)
+        }
+      }
+    })
+  }
+
+  return lines.join('\n')
+}
+
+function renderTable(props: Record<string, unknown>, nodeData?: unknown): string {
+  const columns = props.columns as Array<{ key: string; header: string }> | undefined
+  // Support data from node.data (TDD tests) or props.data (legacy)
+  const data = (nodeData as Array<Record<string, unknown>> | undefined) ??
+               (props.data as Array<Record<string, unknown>> | undefined)
+  const lines: string[] = []
+
+  if (!columns || !Array.isArray(columns)) return ''
+
+  // Add headers using shared utility
+  const headers = extractHeaders(columns)
+  lines.push(headers.join(', '))
+
+  // Add data rows using shared utility
+  if (data && Array.isArray(data)) {
+    data.forEach((row) => {
+      const values = extractRowValues(row, columns)
+      lines.push(values.join(', '))
+    })
+  }
+
+  return lines.join('\n')
+}
+
+function renderCode(props: Record<string, unknown>): string {
+  const code = props.code
+  if (code == null) return ''
+  return String(code)
+}
+
+function renderLink(props: Record<string, unknown>): string {
+  const text = props.text
+  if (text == null) return ''
+  return String(text)
+}
+
+function renderButton(props: Record<string, unknown>): string {
+  const label = props.label as string | undefined
+  const hotkey = props.hotkey as string | undefined
+
+  if (!label) return ''
+
+  if (hotkey) {
+    return `${label} (${hotkey})`
+  }
+  return label
+}
+
+function renderBox(
+  props: Record<string, unknown>,
+  children: UINode[],
+  indent: number
+): string {
+  const title = props.title as string | undefined
+  const parts: string[] = []
+
+  if (title) {
+    parts.push(title)
+  }
+
+  const childOutput = renderChildren(children, indent)
+  if (childOutput) {
+    parts.push(childOutput)
+  }
+
+  return parts.join('\n\n')
+}
+
+function renderPanel(
+  props: Record<string, unknown>,
+  children: UINode[],
+  indent: number
+): string {
+  const title = props.title as string | undefined
+  const collapsed = props.collapsed as boolean | undefined
+  const parts: string[] = []
+
+  if (title) {
+    parts.push(title)
+  }
+
+  // If collapsed, still show title but skip content for now
+  // Based on tests, collapsed panels still show title
+  const childOutput = renderChildren(children, indent)
+  if (childOutput) {
+    parts.push(childOutput)
+  }
+
+  return parts.join('\n\n')
+}
+
+function renderCard(
+  props: Record<string, unknown>,
+  children: UINode[],
+  indent: number
+): string {
+  const title = props.title as string | undefined
+  const subtitle = props.subtitle as string | undefined
+  const badge = props.badge as { content: string; variant?: string } | undefined
+  const titleAction = props.titleAction as { label: string; action?: string } | undefined
+  const pairs = props.pairs as Array<{ key: string; value: unknown }> | undefined
+  const actions = props.actions as Array<{ label: string; action?: string }> | undefined
+  const parts: string[] = []
+
+  // Title section
+  if (title) {
+    let titleLine = title
+    if (badge) {
+      titleLine += ` ${badge.content}`
+    }
+    if (titleAction) {
+      titleLine += ` ${titleAction.label}`
+    }
+    parts.push(titleLine)
+  }
+
+  if (subtitle) {
+    parts.push(subtitle)
+  }
+
+  // Key-value pairs
+  if (pairs && Array.isArray(pairs)) {
+    const pairLines = pairs.map((p) => {
+      const val = p.value != null ? String(p.value) : ''
+      return `${p.key}: ${val}`
+    })
+    if (pairLines.length > 0) {
+      parts.push(pairLines.join('\n'))
+    }
+  }
+
+  // Children content
+  const childOutput = renderChildren(children, indent)
+  if (childOutput) {
+    parts.push(childOutput)
+  }
+
+  // Actions
+  if (actions && Array.isArray(actions)) {
+    const actionLabels = actions.map((a) => a.label).join(' | ')
+    if (actionLabels) {
+      parts.push(actionLabels)
+    }
+  }
+
+  return parts.join('\n\n')
+}
+
+function renderMetrics(props: Record<string, unknown>): string {
+  const metrics = props.metrics as Array<{
+    label: string
+    value: unknown
+    format?: string
+    unit?: string
+    trend?: string
+  }> | undefined
+
+  if (!metrics || !Array.isArray(metrics) || metrics.length === 0) {
+    return ''
+  }
+
+  return metrics.map((m) => {
+    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}`
+    }
+    return `${m.label}: ${formatted}`
+  }).join('\n')
+}
+
+function renderSingleMetric(props: Record<string, unknown>): string {
+  const label = props.label as string | undefined
+  const value = props.value
+  const format = props.format as string | undefined
+  const unit = 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}`
+}
+
+function renderSidebar(props: Record<string, unknown>, indent: number): string {
+  const nav = props.nav as Array<{
+    label: string
+    href?: string
+    active?: boolean
+    children?: Array<{ label: string; href?: string }>
+  }> | undefined
+  const sections = props.sections as Array<{
+    title: string
+    items: Array<{ label: string; href?: string }>
+  }> | undefined
+
+  const lines: string[] = []
+  const indentStr = getIndentStr(indent)
+
+  if (nav && Array.isArray(nav)) {
+    nav.forEach((item) => {
+      lines.push(`${indentStr}- ${item.label}`)
+      if (item.children && Array.isArray(item.children)) {
+        item.children.forEach((child) => {
+          lines.push(`${indentStr}  - ${child.label}`)
+        })
+      }
+    })
+  }
+
+  if (sections && Array.isArray(sections)) {
+    sections.forEach((section) => {
+      lines.push(`${indentStr}${section.title}`)
+      if (section.items && Array.isArray(section.items)) {
+        section.items.forEach((item) => {
+          lines.push(`${indentStr}  - ${item.label}`)
+        })
+      }
+    })
+  }
+
+  return lines.join('\n')
+}
+
+function renderBreadcrumb(props: Record<string, unknown>): string {
+  const items = props.items as Array<{ label: string; path?: string }> | undefined
+  const separator = (props.separator as string) || '>'
+
+  if (!items || !Array.isArray(items)) return ''
+
+  return items.map((item) => item.label).join(` ${separator} `)
+}
+
+function renderBadge(props: Record<string, unknown>): string {
+  const children = props.children
+  if (children == null) return ''
+  return String(children)
+}
+
+function renderDialog(
+  props: Record<string, unknown>,
+  children: UINode[],
+  indent: number
+): string {
+  const open = props.open as boolean | undefined
+  const title = props.title as string | undefined
+  const actions = props.actions as Array<{ label: string; action: string }> | undefined
+
+  // Skip closed dialogs
+  if (open === false) return ''
+
+  const parts: string[] = []
+
+  if (title) {
+    parts.push(title)
+  }
+
+  const childOutput = renderChildren(children, indent)
+  if (childOutput) {
+    parts.push(childOutput)
+  }
+
+  if (actions && Array.isArray(actions)) {
+    const actionLabels = actions.map((a) => a.label).join(' | ')
+    parts.push(actionLabels)
+  }
+
+  return parts.join('\n\n')
+}
+
+function renderSpinner(props: Record<string, unknown>): string {
+  const label = props.label as string | undefined
+  return label || 'Loading...'
+}
+
+function renderDashboard(
+  props: Record<string, unknown>,
+  children: UINode[],
+  indent: number
+): string {
+  const title = props.title as string | undefined
+  const metrics = props.metrics as Array<{
+    label: string
+    value: string | number
+    trend?: string
+  }> | undefined
+
+  const parts: string[] = []
+
+  if (title) {
+    parts.push(title)
+  }
+
+  if (metrics && Array.isArray(metrics) && metrics.length > 0) {
+    const metricsOutput = metrics.map((m) => `${m.label}: ${m.value}`).join('\n')
+    parts.push(metricsOutput)
+  }
+
+  const childOutput = renderChildren(children, indent)
+  if (childOutput) {
+    parts.push(childOutput)
+  }
+
+  return parts.join('\n\n')
+}
+
+function renderSettings(
+  props: Record<string, unknown>,
+  children: UINode[],
+  indent: number
+): string {
+  const sections = props.sections as string[] | undefined
+  const parts: string[] = []
+
+  if (sections && Array.isArray(sections)) {
+    sections.forEach((section) => {
+      parts.push(section)
+    })
+  }
+
+  const childOutput = renderChildren(children, indent)
+  if (childOutput) {
+    parts.push(childOutput)
+  }
+
+  return parts.join('\n')
+}
+
+function renderInput(props: Record<string, unknown>): string {
+  const label = props.label as string | undefined
+  const value = props.value as string | undefined
+  const placeholder = props.placeholder as string | undefined
+
+  const parts: string[] = []
+
+  if (label) {
+    parts.push(label)
+  }
+
+  if (value != null) {
+    parts.push(String(value))
+  } else if (placeholder) {
+    parts.push(placeholder)
+  }
+
+  return parts.join(': ')
+}
+
+function renderSelect(props: Record<string, unknown>): string {
+  const label = props.label as string | undefined
+  const value = props.value as string | undefined
+  const options = props.options as Array<{ label: string; value: string }> | undefined
+
+  const parts: string[] = []
+
+  if (label) {
+    parts.push(label)
+  }
+
+  // Show current selection if there is one
+  if (value && options) {
+    const selected = options.find((o) => o.value === value)
+    if (selected) {
+      parts.push(`Selected: ${selected.label}`)
+    }
+  }
+
+  // List all options
+  if (options && Array.isArray(options)) {
+    options.forEach((opt) => {
+      parts.push(`- ${opt.label}`)
+    })
+  }
+
+  return parts.join('\n')
+}
+
+function renderHero(props: Record<string, unknown>): string {
+  const title = props.title as string | undefined
+  const subtitle = props.subtitle as string | undefined
+  const callToAction = props.callToAction as string | undefined
+  const secondaryCallToAction = props.secondaryCallToAction as string | undefined
+  const badge = props.badge as string | undefined
+
+  const parts: string[] = []
+
+  if (badge) {
+    parts.push(badge)
+  }
+
+  if (title) {
+    parts.push(title)
+  }
+
+  if (subtitle) {
+    parts.push(subtitle)
+  }
+
+  const ctas: string[] = []
+  if (callToAction) {
+    ctas.push(callToAction)
+  }
+  if (secondaryCallToAction) {
+    ctas.push(secondaryCallToAction)
+  }
+  if (ctas.length > 0) {
+    parts.push(ctas.join(' | '))
+  }
+
+  return parts.join('\n\n')
+}
+
+function renderFeatures(props: Record<string, unknown>): string {
+  const title = props.title as string | undefined
+  const features = props.features as Array<{
+    title: string
+    description?: string
+    icon?: string
+  }> | undefined
+
+  const parts: string[] = []
+
+  if (title) {
+    parts.push(title)
+  }
+
+  if (features && Array.isArray(features)) {
+    features.forEach((feature) => {
+      if (feature.description) {
+        parts.push(`${feature.title}: ${feature.description}`)
+      } else {
+        parts.push(feature.title)
+      }
+    })
+  }
+
+  return parts.join('\n\n')
+}
+
+function renderPricing(props: Record<string, unknown>): string {
+  const tiers = props.tiers as Array<{
+    name: string
+    price: string
+    features: string[]
+    callToAction?: string
+  }> | undefined
+
+  if (!tiers || !Array.isArray(tiers)) return ''
+
+  const parts: string[] = []
+
+  tiers.forEach((tier) => {
+    const tierParts: string[] = []
+    tierParts.push(`${tier.name} - ${tier.price}`)
+
+    if (tier.features && Array.isArray(tier.features)) {
+      tier.features.forEach((feature) => {
+        tierParts.push(`  - ${feature}`)
+      })
+    }
+
+    if (tier.callToAction) {
+      tierParts.push(`  ${tier.callToAction}`)
+    }
+
+    parts.push(tierParts.join('\n'))
+  })
+
+  return parts.join('\n\n')
+}
+
+function renderFAQ(props: Record<string, unknown>): string {
+  const title = props.title as string | undefined
+  const items = props.items as Array<{
+    question: string
+    answer: string
+  }> | undefined
+
+  const parts: string[] = []
+
+  if (title) {
+    parts.push(title)
+  }
+
+  if (items && Array.isArray(items)) {
+    items.forEach((item) => {
+      parts.push(`Q: ${item.question}`)
+      parts.push(`A: ${item.answer}`)
+    })
+  }
+
+  return parts.join('\n\n')
+}
+
+function renderFooter(props: Record<string, unknown>): string {
+  const links = props.links as Array<{
+    title: string
+    links: Array<{ label: string; href: string }>
+  }> | undefined
+  const copyright = props.copyright as string | undefined
+  const social = props.social as Array<{ platform: string; href: string }> | undefined
+
+  const parts: string[] = []
+
+  if (links && Array.isArray(links)) {
+    links.forEach((section) => {
+      parts.push(section.title)
+      if (section.links && Array.isArray(section.links)) {
+        section.links.forEach((link) => {
+          parts.push(`  - ${link.label}`)
+        })
+      }
+    })
+  }
+
+  if (social && Array.isArray(social)) {
+    const socialParts = social.map((s) => s.platform).join(' | ')
+    parts.push(socialParts)
+  }
+
+  if (copyright) {
+    parts.push(copyright)
+  }
+
+  return parts.join('\n')
+}
+
+function renderChildren(children: UINode[], indent: number): string {
+  if (!children || children.length === 0) return ''
+
+  const parts: string[] = []
+
+  children.forEach((child) => {
+    const output = renderText(child, { indent })
+    if (output) {
+      parts.push(output)
+    }
+  })
+
+  return parts.join('\n\n')
+}