@mdxui/terminal 2.0.0

package/src/renderers/index.ts

@@ -0,0 +1,101 @@
+/**
+ * @mdxui/terminal Renderers
+ *
+ * Multi-tier rendering architecture for Universal Terminal UI.
+ * Each tier provides progressively richer output capabilities:
+ *
+ * - TEXT: Plain text without formatting (tier 1)
+ * - MARKDOWN: Markdown syntax for AI agents (tier 2)
+ * - ASCII: ASCII art and basic drawing characters (tier 3)
+ * - UNICODE: Unicode box drawing and symbols (tier 4)
+ * - ANSI: Full ANSI escape sequences for colors/styles (tier 5)
+ * - INTERACTIVE: Full interactive terminal UI with input handling (tier 6)
+ */
+
+// TEXT tier renderer
+export { renderText } from './text'
+export type { TextRenderOptions } from './text'
+
+// MARKDOWN tier renderer
+export { renderMarkdown } from './markdown'
+export type { MarkdownRenderOptions } from './markdown'
+
+// ASCII tier renderer
+export { renderASCII } from './ascii'
+
+// UNICODE tier renderer
+export { renderUnicode } from './unicode'
+
+// ANSI tier renderer
+export { renderANSI } from './ansi'
+
+// INTERACTIVE tier renderer
+export { renderInteractive, createInteractiveRenderer } from './interactive'
+export type {
+  InteractiveRendererConfig,
+  InteractiveRenderer,
+  FocusableOptions,
+  ClickableOptions,
+  InputOptions,
+  ComponentOptions,
+} from './interactive'
+
+// ANSI to CSS conversion utilities for web rendering
+export {
+  ansiToCSS,
+  ansiToHTML,
+  parseAnsiToSpans,
+  spanToInlineStyle,
+} from './ansi-css'
+export type {
+  CSSStyleProperties,
+  StyledSpan,
+  ANSIToCSSResult,
+} from './ansi-css'
+
+// Common utilities used across renderers
+export {
+  getIndentStr,
+  getTextWidth,
+  padText,
+  wrapText,
+  sanitizeToASCII,
+  boxDrawingToASCII,
+  buildBox,
+  extractStringArray,
+  extractHeaders,
+  extractRowValues,
+  joinParts,
+  getProp,
+  calculateColumnWidths,
+  buildTableSeparator,
+  buildTableRow,
+  matchPath,
+  normalizePath,
+  matchPathPattern,
+  generateBreadcrumbSegments,
+  formatSegmentLabel,
+  findActiveItemByPath,
+  findActiveItemInSections,
+  joinPath,
+  extractPathParams,
+  createCallbackRouterAdapter,
+  ASCII_BOX_CHARS,
+  ASCII_DOUBLE_BOX_CHARS,
+  UNICODE_SINGLE_BOX_CHARS,
+  UNICODE_DOUBLE_BOX_CHARS,
+  UNICODE_ROUNDED_BOX_CHARS,
+  getASCIIBoxChars,
+  getUnicodeBoxChars,
+  UNICODE_SYMBOLS,
+  SPINNER_FRAMES,
+  DEFAULT_THEME_TOKENS,
+  DEFAULT_RENDER_CONTEXT,
+} from './utils'
+export type {
+  BoxChars,
+  TextAlign,
+  RendererRegistry,
+  RouterAdapter,
+  RouteMatchMode,
+} from './utils'

package/src/renderers/interactive/component-handlers.ts

@@ -0,0 +1,622 @@
+/**
+ * @mdxui/terminal Component Handlers
+ *
+ * Handles per-component rendering and state management
+ * for the interactive renderer.
+ *
+ * @packageDocumentation
+ */
+
+import type {
+  ComponentOptions,
+  ComponentManagerState,
+  FocusManagerState,
+  InputManagerState,
+  UINode,
+  InteractiveRenderer,
+} from './types'
+import { registerFocusable, unregisterFocusable } from './focus-manager'
+import { handleInputKey } from './input-handler'
+
+/**
+ * Creates the component manager state
+ */
+export function createComponentManagerState(): ComponentManagerState {
+  return {
+    components: new Map<string, ComponentOptions>(),
+  }
+}
+
+/**
+ * Register a component
+ */
+export function registerComponent(
+  componentState: ComponentManagerState,
+  focusState: FocusManagerState,
+  id: string,
+  options: ComponentOptions,
+  destroyed?: boolean
+): void {
+  if (destroyed) return
+  componentState.components.set(id, { ...options })
+
+  // Register as focusable if applicable
+  if (['select', 'checkbox', 'radiogroup', 'slider', 'tree', 'scrollview'].includes(options.type)) {
+    registerFocusable(focusState, id, { tabIndex: 0 }, destroyed)
+  }
+}
+
+/**
+ * Unregister a component
+ */
+export function unregisterComponent(
+  componentState: ComponentManagerState,
+  focusState: FocusManagerState,
+  id: string,
+  destroyed?: boolean
+): void {
+  if (destroyed) return
+  componentState.components.delete(id)
+  unregisterFocusable(focusState, id, destroyed)
+}
+
+/**
+ * Get a component
+ */
+export function getComponent(
+  componentState: ComponentManagerState,
+  id: string,
+  destroyed?: boolean
+): ComponentOptions | undefined {
+  if (destroyed) return undefined
+  return componentState.components.get(id)
+}
+
+/**
+ * Update a component
+ */
+export function updateComponent(
+  componentState: ComponentManagerState,
+  id: string,
+  updates: Partial<ComponentOptions>,
+  destroyed?: boolean
+): void {
+  if (destroyed) return
+  const existing = componentState.components.get(id)
+  if (existing) {
+    Object.assign(existing, updates)
+  }
+}
+
+/**
+ * Get visible tree nodes
+ */
+export function getVisibleTreeNodes(
+  nodes: Array<{ id: string; children?: string[]; expanded?: boolean; parent?: string }>
+): typeof nodes {
+  const result: typeof nodes = []
+  const rootNodes = nodes.filter(n => !n.parent)
+
+  const addNode = (node: (typeof nodes)[0]) => {
+    result.push(node)
+    if (node.expanded && node.children) {
+      for (const childId of node.children) {
+        const child = nodes.find(n => n.id === childId)
+        if (child) addNode(child)
+      }
+    }
+  }
+
+  for (const root of rootNodes) {
+    addNode(root)
+  }
+
+  return result
+}
+
+/**
+ * Handle component key press
+ */
+export function handleComponentKeyInternal(
+  id: string,
+  component: ComponentOptions,
+  key: string
+): boolean {
+  const {
+    type,
+    onChange,
+    onSelect,
+    onToggle,
+    options,
+    selectedIndex,
+    checked,
+    value,
+    min,
+    max,
+    step,
+    searchable,
+    onScroll,
+    nodes,
+    selectedId,
+  } = component as ComponentOptions & {
+    onChange?: (index: number, value?: string) => void
+    onSelect?: (index: number | string, value?: string) => void
+    onToggle?: (id: string, expanded: boolean) => void
+    options?: string[]
+    selectedIndex?: number
+    checked?: boolean
+    value?: number
+    min?: number
+    max?: number
+    step?: number
+    searchable?: boolean
+    onScroll?: (event: { scrollY: number }) => void
+    nodes?: Array<{ id: string; label: string; children?: string[]; expanded?: boolean; parent?: string }>
+    selectedId?: string
+  }
+
+  if (type === 'select') {
+    const opts = options as string[]
+    const idx = selectedIndex as number
+
+    if (key === 'down' || key === 'j') {
+      const newIdx = Math.min(idx + 1, opts.length - 1)
+      component.selectedIndex = newIdx
+      onChange?.(newIdx, opts[newIdx])
+      return true
+    }
+    if (key === 'up' || key === 'k') {
+      const newIdx = Math.max(idx - 1, 0)
+      component.selectedIndex = newIdx
+      onChange?.(newIdx, opts[newIdx])
+      return true
+    }
+    if (key === 'enter') {
+      // If onSelect is provided, call it
+      if (onSelect) {
+        onSelect(idx, opts[idx])
+      }
+      // Toggle open state for dropdown behavior
+      component.isOpen = !component.isOpen
+      return true
+    }
+    // Type-ahead search
+    if (searchable && key.length === 1) {
+      const matchIdx = opts.findIndex(o => o.toLowerCase().startsWith(key.toLowerCase()))
+      if (matchIdx !== -1) {
+        component.selectedIndex = matchIdx
+        onChange?.(matchIdx, opts[matchIdx])
+      }
+      return true
+    }
+    return false
+  }
+
+  if (type === 'checkbox') {
+    if (key === 'space' || key === 'enter') {
+      const newChecked = !checked
+      component.checked = newChecked
+      ;(component.onChange as (checked: boolean) => void)?.(newChecked)
+      return true
+    }
+    return false
+  }
+
+  if (type === 'radiogroup') {
+    const opts = options as string[]
+    const idx = selectedIndex as number
+
+    if (key === 'down' || key === 'up') {
+      const newIdx = key === 'down' ? Math.min(idx + 1, opts.length - 1) : Math.max(idx - 1, 0)
+      component.selectedIndex = newIdx
+      ;(component.onChange as (index: number) => void)?.(newIdx)
+      return true
+    }
+    if (key === 'space') {
+      onSelect?.(idx, opts[idx])
+      return true
+    }
+    return false
+  }
+
+  if (type === 'slider') {
+    const v = value as number
+    const minV = min as number
+    const maxV = max as number
+    const stepV = step ?? 1
+
+    if (key === 'right' || key === 'up') {
+      const newV = Math.min(v + stepV, maxV)
+      component.value = newV
+      ;(component.onChange as (value: number) => void)?.(newV)
+      return true
+    }
+    if (key === 'left' || key === 'down') {
+      const newV = Math.max(v - stepV, minV)
+      component.value = newV
+      ;(component.onChange as (value: number) => void)?.(newV)
+      return true
+    }
+    if (key === 'home') {
+      component.value = minV
+      ;(component.onChange as (value: number) => void)?.(minV)
+      return true
+    }
+    if (key === 'end') {
+      component.value = maxV
+      ;(component.onChange as (value: number) => void)?.(maxV)
+      return true
+    }
+    return false
+  }
+
+  if (type === 'tree') {
+    const nodeList = nodes as Array<{
+      id: string
+      label: string
+      children?: string[]
+      expanded?: boolean
+      parent?: string
+    }>
+    const currentId = selectedId as string
+    const currentNode = nodeList.find(n => n.id === currentId)
+
+    if (key === 'enter' && currentNode?.children) {
+      const newExpanded = !currentNode.expanded
+      currentNode.expanded = newExpanded
+      onToggle?.(currentId, newExpanded)
+      return true
+    }
+    if (key === 'down') {
+      // Find next visible node
+      const visibleNodes = getVisibleTreeNodes(nodeList)
+      const currentIndex = visibleNodes.findIndex(n => n.id === currentId)
+      if (currentIndex < visibleNodes.length - 1) {
+        const nextNode = visibleNodes[currentIndex + 1]
+        component.selectedId = nextNode.id
+        ;(component.onSelect as (id: string) => void)?.(nextNode.id)
+      }
+      return true
+    }
+    return false
+  }
+
+  if (type === 'scrollview') {
+    const currentScrollY = (component.scrollY as number) ?? 0
+    const viewportHeight = (component.viewportHeight as number) ?? 20
+
+    if (key === 'down') {
+      const newScrollY = currentScrollY + 1
+      component.scrollY = newScrollY
+      onScroll?.({ scrollY: newScrollY })
+      return true
+    }
+    if (key === 'up') {
+      const newScrollY = Math.max(0, currentScrollY - 1)
+      component.scrollY = newScrollY
+      onScroll?.({ scrollY: newScrollY })
+      return true
+    }
+    if (key === 'pagedown') {
+      const newScrollY = currentScrollY + viewportHeight
+      component.scrollY = newScrollY
+      onScroll?.({ scrollY: newScrollY })
+      return true
+    }
+    if (key === 'pageup') {
+      const newScrollY = Math.max(0, currentScrollY - viewportHeight)
+      component.scrollY = newScrollY
+      onScroll?.({ scrollY: newScrollY })
+      return true
+    }
+    return false
+  }
+
+  return false
+}
+
+/**
+ * Handle key for focused component
+ */
+export function handleComponentKey(
+  focusedId: string | null,
+  inputState: InputManagerState,
+  componentState: ComponentManagerState,
+  focusState: FocusManagerState,
+  key: string
+): boolean {
+  if (!focusedId) return false
+
+  // Check if focused element is an input
+  const input = inputState.inputs.get(focusedId)
+  if (input) {
+    return handleInputKey(focusedId, input, key)
+  }
+
+  // Check if focused element is a component
+  const component = componentState.components.get(focusedId)
+  if (component) {
+    return handleComponentKeyInternal(focusedId, component, key)
+  }
+
+  // Check focusable handlers
+  const focusable = focusState.focusables.get(focusedId)
+  if (focusable) {
+    if (key === 'enter' && focusable.options.onActivate) {
+      focusable.options.onActivate({ id: focusedId })
+      return true
+    }
+    if (key === 'space' && focusable.options.onToggle) {
+      focusable.options.onToggle({ id: focusedId })
+      return true
+    }
+  }
+
+  return false
+}
+
+/**
+ * Clear component state on destroy
+ */
+export function clearComponentState(componentState: ComponentManagerState): void {
+  componentState.components.clear()
+}
+
+/**
+ * Registers a UINode with the interactive renderer (for component state management).
+ * This is used internally for focus management and event handling.
+ */
+export function registerInteractiveNode(
+  node: UINode,
+  renderer: InteractiveRenderer,
+  options?: { group?: string }
+): void {
+  const { type, props } = node
+  const id = props.id as string | undefined
+  const group = options?.group
+
+  if (!id) return
+
+  // Handle different node types
+  switch (type) {
+    case 'button': {
+      const { onClick, disabled } = props as { onClick?: () => void; disabled?: boolean }
+      renderer.registerFocusable(id, {
+        tabIndex: 0,
+        disabled,
+        group,
+        onActivate: onClick ? () => !disabled && onClick() : undefined,
+        onToggle: onClick ? () => !disabled && onClick() : undefined,
+      })
+      break
+    }
+
+    case 'input': {
+      const { placeholder, value, type: inputType } = props as {
+        placeholder?: string
+        value?: string
+        type?: string
+      }
+      renderer.registerComponent(id, {
+        type: 'input',
+        placeholder,
+        value: value ?? '',
+        displayValue: inputType === 'password' && value ? '*'.repeat(value.length) : value,
+      })
+      renderer.registerFocusable(id, { tabIndex: 0, group })
+      break
+    }
+
+    case 'select': {
+      const { options: selectOptions } = props as { options?: Array<{ value: string; label: string }> }
+      renderer.registerComponent(id, {
+        type: 'select',
+        options: selectOptions ?? [],
+        selectedIndex: 0,
+        isOpen: false,
+      })
+      renderer.registerFocusable(id, { tabIndex: 0, group })
+      break
+    }
+
+    case 'dialog': {
+      const { open, onClose, children } = props as {
+        open?: boolean
+        onClose?: () => void
+        children?: UINode[]
+      }
+      if (open) {
+        // Push focus trap
+        renderer.pushFocusTrap(id)
+
+        // Register cancel handler
+        if (onClose) {
+          renderer.onCancel(onClose)
+        }
+
+        // Render children with this dialog's group
+        if (children) {
+          for (const child of children) {
+            registerInteractiveNode(child, renderer, { group: id })
+          }
+        }
+      }
+      break
+    }
+
+    case 'table': {
+      const { rows, onRowSelect, onCellSelect, cellNavigation, columns, data } = props as {
+        rows?: Array<{ id: string; cells: string[] }>
+        onRowSelect?: (id: string) => void
+        onCellSelect?: (rowId: string, cellIndex: number) => void
+        cellNavigation?: boolean
+        columns?: Array<{ key: string; header: string }>
+        data?: Array<Record<string, unknown>>
+      }
+
+      // Get data from node.data (TDD) or props.data
+      const nodeData = node.data as Array<Record<string, unknown>> | undefined
+      const tableData = nodeData ?? data
+
+      let currentRowIndex = 0
+      let currentCellIndex = 0
+
+      renderer.registerComponent(id, {
+        type: 'table',
+        rows: rows ?? [],
+        columns: columns ?? [],
+        data: tableData ?? [],
+        selectedRowIndex: 0,
+        selectedCellIndex: 0,
+        cellNavigation,
+        onRowSelect,
+        onCellSelect,
+      })
+
+      renderer.registerFocusable(id, {
+        tabIndex: 0,
+        onActivate: () => {
+          if (rows && rows[currentRowIndex]) {
+            onRowSelect?.(rows[currentRowIndex].id)
+          }
+        },
+      })
+
+      // Custom key handling for table
+      renderer.onKeyPress(
+        'down',
+        () => {
+          if (renderer.getFocusedId() !== id || !rows) return false
+          if (currentRowIndex < rows.length - 1) {
+            currentRowIndex++
+            onRowSelect?.(rows[currentRowIndex].id)
+          }
+          return true
+        },
+        { priority: 10 }
+      )
+
+      renderer.onKeyPress(
+        'right',
+        () => {
+          if (renderer.getFocusedId() !== id || !rows || !cellNavigation) return false
+          const row = rows[currentRowIndex]
+          if (row && currentCellIndex < row.cells.length - 1) {
+            currentCellIndex++
+            onCellSelect?.(row.id, currentCellIndex)
+          }
+          return true
+        },
+        { priority: 10 }
+      )
+      break
+    }
+
+    case 'progress': {
+      const { value, max } = props as { value?: number; max?: number }
+      renderer.registerComponent(id, {
+        type: 'progress',
+        value: value ?? 0,
+        max: max ?? 100,
+      })
+      break
+    }
+
+    case 'spinner': {
+      renderer.registerComponent(id, {
+        type: 'spinner',
+        isAnimating: true,
+      })
+      break
+    }
+
+    case 'scrollview': {
+      const { contentHeight, viewportHeight, onScroll, scrollY } = props as {
+        contentHeight?: number
+        viewportHeight?: number
+        onScroll?: (event: { scrollY: number }) => void
+        scrollY?: number
+      }
+
+      renderer.registerComponent(id, {
+        type: 'scrollview',
+        contentHeight: contentHeight ?? 100,
+        viewportHeight: viewportHeight ?? 20,
+        scrollY: scrollY ?? 0,
+        onScroll,
+      })
+      renderer.registerFocusable(id, { tabIndex: 0 })
+      break
+    }
+
+    case 'list': {
+      const { items, numbered, taskList, children } = props as {
+        items?: Array<string | { text: string; checked?: boolean }>
+        numbered?: boolean
+        taskList?: boolean
+        children?: UINode[]
+      }
+
+      renderer.registerComponent(id, {
+        type: 'list',
+        items: items ?? [],
+        numbered: numbered ?? false,
+        taskList: taskList ?? false,
+        children,
+      })
+      break
+    }
+
+    case 'card': {
+      const { title, subtitle, badge, titleAction, pairs, actions } = props as {
+        title?: string
+        subtitle?: string
+        badge?: { content: string; variant?: string }
+        titleAction?: { label: string; action?: string }
+        pairs?: Array<{ key: string; value: unknown }>
+        actions?: Array<{ label: string; action?: string }>
+      }
+
+      renderer.registerComponent(id, {
+        type: 'card',
+        title,
+        subtitle,
+        badge,
+        titleAction,
+        pairs,
+        actions,
+      })
+      break
+    }
+
+    case 'metrics': {
+      const { metrics } = props as {
+        metrics?: Array<{ label: string; value: unknown; format?: string; unit?: string; trend?: string }>
+      }
+
+      renderer.registerComponent(id, {
+        type: 'metrics',
+        metrics: metrics ?? [],
+      })
+      break
+    }
+
+    case 'metric': {
+      const { label, value, format, unit } = props as {
+        label?: string
+        value?: unknown
+        format?: string
+        unit?: string
+      }
+
+      renderer.registerComponent(id, {
+        type: 'metric',
+        label,
+        value,
+        format,
+        unit,
+      })
+      break
+    }
+  }
+}