@mdxui/terminal 2.0.0

package/src/renderers/interactive/types.ts

@@ -0,0 +1,338 @@
+/**
+ * @mdxui/terminal Interactive Renderer Types
+ *
+ * Type definitions for the interactive renderer, including:
+ * - Configuration options
+ * - Focusable/Clickable options
+ * - Input and component options
+ * - Internal state types
+ *
+ * @packageDocumentation
+ */
+
+// ============================================================================
+// Configuration Types
+// ============================================================================
+
+/**
+ * Configuration options for creating an interactive renderer
+ */
+export interface InteractiveRendererConfig {
+  /** Terminal width in columns */
+  width?: number
+  /** Terminal height in rows */
+  height?: number
+  /** Enable mouse support */
+  useMouse?: boolean
+  /** Use alternate screen buffer */
+  useAlternateScreen?: boolean
+  /** Wrap focus at boundaries */
+  wrapFocus?: boolean
+  /** Enable vim-style key bindings */
+  vimBindings?: boolean
+  /** Timeout for key sequences in ms */
+  sequenceTimeout?: number
+  /** Target frames per second */
+  targetFps?: number
+}
+
+// ============================================================================
+// Focus Types
+// ============================================================================
+
+/**
+ * Focusable element options
+ */
+export interface FocusableOptions {
+  /** Tab order index */
+  tabIndex: number
+  /** Focus group */
+  group?: string
+  /** Callback when focused */
+  onFocus?: (event: { id: string }) => void
+  /** Callback when blurred */
+  onBlur?: (event: { id: string }) => void
+  /** Callback when activated */
+  onActivate?: (event: { id: string }) => void
+  /** Callback when toggled */
+  onToggle?: (event: { id: string }) => void
+  /** Whether element is disabled */
+  disabled?: boolean
+  /** Column position for grid navigation */
+  column?: number
+  /** Cursor position for input elements */
+  cursorPosition?: { x: number; y: number }
+  /** Whether to show cursor when focused */
+  showCursor?: boolean
+}
+
+/**
+ * Internal focusable entry with registration metadata
+ */
+export interface FocusableEntry {
+  id: string
+  options: FocusableOptions
+  registrationOrder: number
+}
+
+/**
+ * Focus trap stack entry
+ */
+export interface FocusTrapEntry {
+  group: string
+  previousFocusId: string | null
+}
+
+// ============================================================================
+// Mouse Types
+// ============================================================================
+
+/**
+ * Clickable area options
+ */
+export interface ClickableOptions {
+  /** X position */
+  x: number
+  /** Y position */
+  y: number
+  /** Width */
+  width: number
+  /** Height */
+  height: number
+  /** Z-index for layering */
+  zIndex?: number
+  /** Whether clicking focuses the element */
+  focusable?: boolean
+  /** Click handler */
+  onClick?: (event: { x: number; y: number; id: string }) => void
+  /** Double-click handler */
+  onDoubleClick?: () => void
+  /** Right-click handler */
+  onRightClick?: () => void
+}
+
+// ============================================================================
+// Input Types
+// ============================================================================
+
+/**
+ * Input registration options
+ */
+export interface InputOptions {
+  /** Current value */
+  value: string
+  /** Placeholder text */
+  placeholder?: string
+  /** Input mask */
+  mask?: string
+  /** Maximum length */
+  maxLength?: number
+  /** Validation function */
+  validate?: (value: string) => boolean
+  /** Whether multiline */
+  multiline?: boolean
+  /** Current cursor index */
+  cursorIndex?: number
+  /** Change handler */
+  onChange?: (value: string) => void
+  /** Submit handler */
+  onSubmit?: (value: string) => void
+}
+
+/**
+ * Internal input state with current values
+ */
+export interface InputState extends InputOptions {
+  currentValue: string
+  currentCursorIndex: number
+}
+
+// ============================================================================
+// Component Types
+// ============================================================================
+
+/**
+ * Component registration options
+ */
+export interface ComponentOptions {
+  /** Component type */
+  type: string
+  /** Additional options */
+  [key: string]: unknown
+}
+
+// ============================================================================
+// Keyboard Types
+// ============================================================================
+
+/**
+ * Key handler with priority
+ */
+export interface KeyHandler {
+  handler: () => boolean | void
+  priority: number
+}
+
+// ============================================================================
+// Renderer Interface
+// ============================================================================
+
+/**
+ * Interactive renderer interface
+ */
+export interface InteractiveRenderer {
+  // Dimensions
+  width: number
+  height: number
+
+  // Lifecycle
+  start(): void
+  stop(): void
+  destroy(): void
+  requestRender(): void
+
+  // Focus management
+  focusNext(): void
+  focusPrev(): void
+  focusById(id: string): void
+  getFocusedId(): string | null
+  getFocusableIds(): string[]
+  registerFocusable(id: string, options: FocusableOptions): void
+  unregisterFocusable(id: string): void
+  setActiveGroup(group: string): void
+  pushFocusTrap(group: string): void
+  popFocusTrap(): void
+
+  // Keyboard management
+  onKeyPress(key: string, handler: () => boolean | void, options?: { priority?: number }): void
+  offKeyPress(key: string, handler: () => boolean | void): void
+  emitKey(key: string): void
+  onKeySequence(sequence: string, handler: () => void): void
+  getPendingSequence(): string
+  onSearchMode(handler: () => void): void
+  onCancel(handler: () => void): void
+  getMode(): string
+
+  // Mouse management
+  onClick(handler: (event: { x: number; y: number }) => void): void
+  offClick(handler: (event: { x: number; y: number }) => void): void
+  emitClick(x: number, y: number, options?: { clickCount?: number; button?: string }): void
+  registerClickable(id: string, options: ClickableOptions): void
+  unregisterClickable(id: string): void
+  getClickableAreas(): Array<{ id: string } & ClickableOptions>
+  onScroll(handler: (event: { deltaY: number }) => void): void
+  emitScroll(x: number, y: number, options: { deltaY: number }): void
+
+  // Cursor management
+  setCursorPosition(x: number, y: number): void
+  getCursorPosition(): { x: number; y: number }
+  showCursor(): void
+  hideCursor(): void
+  isCursorVisible(): boolean
+  setCursorStyle(style: 'block' | 'underline' | 'bar'): void
+  getCursorStyle(): string
+  setCursorBlink(blink: boolean): void
+  isCursorBlinking(): boolean
+  updateCursorPosition(id: string, position: { x: number; y: number }): void
+
+  // State management
+  setState(key: string, value: unknown): void
+  getState(key: string): unknown
+  subscribe(key: string, subscriber: (newValue: unknown, oldValue: unknown) => void): () => void
+  onRender(handler: () => void): void
+  getTargetFps(): number
+
+  // Input management
+  registerInput(id: string, options: InputOptions): void
+  getInputCursorIndex(id: string): number
+
+  // Component management
+  registerComponent(id: string, options: ComponentOptions): void
+  unregisterComponent(id: string): void
+  getComponent(id: string): ComponentOptions | undefined
+  updateComponent(id: string, updates: Partial<ComponentOptions>): void
+}
+
+/**
+ * UINode type for rendering
+ */
+export interface UINode {
+  type: string
+  props: Record<string, unknown>
+  children?: UINode[]
+  data?: unknown
+}
+
+// ============================================================================
+// Manager State Types (for internal use)
+// ============================================================================
+
+/**
+ * Focus manager state
+ */
+export interface FocusManagerState {
+  focusables: Map<string, FocusableEntry>
+  focusedId: string | null
+  activeGroup: string | null
+  focusTrapStack: FocusTrapEntry[]
+  registrationCounter: number
+  wrapFocus: boolean
+}
+
+/**
+ * Keyboard manager state
+ */
+export interface KeyboardManagerState {
+  keyHandlers: Map<string, KeyHandler[]>
+  sequenceHandlers: Map<string, () => void>
+  pendingSequence: string
+  sequenceTimer: ReturnType<typeof setTimeout> | null
+  sequenceTimeout: number
+  mode: 'normal' | 'search'
+  searchModeHandler: (() => void) | null
+  cancelHandler: (() => void) | null
+  vimBindings: boolean
+}
+
+/**
+ * Cursor manager state
+ */
+export interface CursorManagerState {
+  cursorPosition: { x: number; y: number }
+  cursorVisible: boolean
+  cursorStyle: 'block' | 'underline' | 'bar'
+  cursorBlinking: boolean
+}
+
+/**
+ * State manager state
+ */
+export interface StateManagerState {
+  state: Map<string, unknown>
+  stateSubscribers: Map<string, Set<(newValue: unknown, oldValue: unknown) => void>>
+  renderHandler: (() => void) | null
+  targetFps: number
+}
+
+/**
+ * Mouse manager state
+ */
+export interface MouseManagerState {
+  clickables: Map<string, ClickableOptions>
+  clickHandlers: Array<(event: { x: number; y: number }) => void>
+  scrollHandler: ((event: { deltaY: number }) => void) | null
+}
+
+/**
+ * Input manager state
+ */
+export interface InputManagerState {
+  inputs: Map<string, InputState>
+}
+
+/**
+ * Component manager state
+ */
+export interface ComponentManagerState {
+  components: Map<string, ComponentOptions>
+}

package/src/renderers/interactive-string.ts

@@ -0,0 +1,299 @@
+/**
+ * @mdxui/terminal Interactive String Renderer
+ *
+ * This module provides a string-based implementation of the interactive tier
+ * that does not depend on @opentui/core. It is used for testing and situations
+ * where a string output is needed rather than an actual TUI.
+ *
+ * @packageDocumentation
+ */
+
+import type { UINode, RenderContext } from '../core/types'
+
+/**
+ * Options for interactive rendering
+ */
+export interface InteractiveRenderOptions {
+  width?: number
+  height?: number
+}
+
+/**
+ * Renders a UINode to a string for the interactive tier.
+ * This provides compatibility with the test suite that expects
+ * a string-returning render function like other tiers.
+ */
+export function renderInteractive(node: UINode, _context: RenderContext): string {
+  return renderInteractiveToString(node, 0)
+}
+
+function renderInteractiveToString(node: UINode, depth: number): string {
+  const props = node.props || {}
+
+  switch (node.type) {
+    case 'text':
+      return (props.content as string) || ''
+
+    case 'list':
+      return renderInteractiveList(node)
+
+    case 'table':
+      return renderInteractiveTable(node)
+
+    case 'card':
+      return renderInteractiveCard(node)
+
+    case 'metrics':
+      return renderInteractiveMetrics(node)
+
+    case 'metric':
+      return renderInteractiveSingleMetric(node)
+
+    default:
+      // For unknown types, try to render children
+      if (node.children && Array.isArray(node.children) && node.children.length > 0) {
+        return node.children
+          .map(child => renderInteractiveToString(child, depth + 1))
+          .join('\n')
+      }
+      return ''
+  }
+}
+
+function renderInteractiveList(node: UINode): string {
+  const props = node.props || {}
+  const items = props.items as Array<string | { text: string; checked?: boolean }> | undefined
+  const numbered = (props.numbered as boolean) ?? false
+  const taskList = (props.taskList as boolean) ?? false
+  const style = (props.style as string) || 'unordered'
+  const rawChildren = node.children
+  const children: UINode[] = Array.isArray(rawChildren) ? rawChildren : []
+
+  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
+        marker = numbered || style === 'ordered' ? `${index + 1}. ` : '- '
+      } else {
+        text = item.text ?? ''
+        if (taskList && 'checked' in item) {
+          marker = item.checked ? '[x] ' : '[ ] '
+        } else {
+          marker = numbered || style === 'ordered' ? `${index + 1}. ` : '- '
+        }
+      }
+
+      lines.push(marker + text)
+    })
+  }
+
+  // Handle list-item children (with nested list support)
+  children.forEach((child: UINode, index: number) => {
+    if (child.type === 'list-item') {
+      const content = (child.props?.content as string) || ''
+      let marker: string
+
+      if (numbered || style === 'ordered') {
+        marker = `${index + 1}. `
+      } else if (taskList || style === 'checklist') {
+        const checked = child.props?.checked as boolean
+        marker = checked ? '[x] ' : '[ ] '
+      } else {
+        marker = '- '
+      }
+
+      lines.push(marker + content)
+
+      // Handle nested lists
+      const childChildren = child.children
+      if (childChildren && Array.isArray(childChildren) && childChildren.length > 0) {
+        for (const nestedChild of childChildren) {
+          if (nestedChild.type === 'list') {
+            const nestedLines = renderNestedInteractiveList(nestedChild, 1)
+            lines.push(...nestedLines)
+          }
+        }
+      }
+    }
+  })
+
+  return lines.join('\n')
+}
+
+function renderNestedInteractiveList(node: UINode, depth: number): string[] {
+  const props = node.props || {}
+  const style = (props.style as string) || 'unordered'
+  const numbered = (props.numbered as boolean) ?? false
+  const rawChildren = node.children
+  const children: UINode[] = Array.isArray(rawChildren) ? rawChildren : []
+  const lines: string[] = []
+  const indent = '  '.repeat(depth)
+
+  children.forEach((child: UINode, index: number) => {
+    if (child.type === 'list-item') {
+      const content = (child.props?.content as string) || ''
+      let marker: string
+
+      if (numbered || style === 'ordered') {
+        marker = `${index + 1}. `
+      } else {
+        marker = '- '
+      }
+
+      lines.push(indent + marker + content)
+
+      // Handle deeper nested lists
+      const childChildren = child.children
+      if (childChildren && Array.isArray(childChildren) && childChildren.length > 0) {
+        for (const nestedChild of childChildren) {
+          if (nestedChild.type === 'list') {
+            const nestedLines = renderNestedInteractiveList(nestedChild, depth + 1)
+            lines.push(...nestedLines)
+          }
+        }
+      }
+    }
+  })
+
+  return lines
+}
+
+function renderInteractiveTable(node: UINode): string {
+  const props = node.props || {}
+  const columns = (props.columns as Array<{ key: string; header: string; width?: number }>) || []
+  // Support data from node.data (TDD tests) or props.data
+  const nodeData = node.data as Array<Record<string, unknown>> | undefined
+  const propsData = props.data as Array<Record<string, unknown>> | undefined
+  const data = nodeData ?? propsData ?? []
+
+  if (columns.length === 0) return ''
+
+  const lines: string[] = []
+
+  // Header
+  const headers = columns.map(c => c.header).join('\t')
+  lines.push(headers)
+
+  // Rows
+  for (const row of data) {
+    const cells = columns.map(c => {
+      const val = row[c.key]
+      return val != null ? String(val) : ''
+    })
+    lines.push(cells.join('\t'))
+  }
+
+  return lines.join('\n')
+}
+
+function renderInteractiveCard(node: UINode): string {
+  const props = node.props || {}
+  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 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) {
+    for (const pair of pairs) {
+      const val = pair.value != null ? String(pair.value) : ''
+      contentLines.push(`${pair.key}: ${val}`)
+    }
+  }
+
+  // Children content
+  const rawChildren = node.children
+  const children: UINode[] = Array.isArray(rawChildren) ? rawChildren : []
+  if (children.length > 0) {
+    const childContent = children
+      .map((child: UINode) => renderInteractiveToString(child, 0))
+      .filter((s: string) => s)
+      .join('\n')
+    if (childContent) {
+      contentLines.push(childContent)
+    }
+  }
+
+  // Actions
+  if (actions && actions.length > 0) {
+    const actionLabels = actions.map(a => `[ ${a.label} ]`).join(' ')
+    contentLines.push(actionLabels)
+  }
+
+  return contentLines.join('\n')
+}
+
+function renderInteractiveMetrics(node: UINode): string {
+  const props = node.props || {}
+  const metrics = 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')
+}
+
+function renderInteractiveSingleMetric(node: UINode): string {
+  const props = node.props || {}
+  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}`
+}

package/src/renderers/interactive.ts

@@ -0,0 +1,59 @@
+/**
+ * @mdxui/terminal Interactive Renderer
+ *
+ * The Interactive renderer is the highest-capability tier providing:
+ * - Full TUI with keyboard navigation
+ * - Focus management and Tab cycling
+ * - Mouse click support
+ * - Cursor positioning
+ * - Real-time updates
+ * - Input field handling
+ * - Component state management
+ *
+ * This file re-exports from the modular implementation in ./interactive/
+ *
+ * @packageDocumentation
+ */
+
+// Re-export everything from the modular implementation
+export {
+  // Main factory function
+  createInteractiveRenderer,
+  // Node registration function
+  registerInteractiveNode,
+  // String-based renderer for testing
+  renderInteractive,
+} from './interactive/index'
+
+// Re-export all types
+export type {
+  // Configuration types
+  InteractiveRendererConfig,
+  // Focus types
+  FocusableOptions,
+  FocusableEntry,
+  FocusTrapEntry,
+  // Mouse types
+  ClickableOptions,
+  // Input types
+  InputOptions,
+  InputState,
+  // Component types
+  ComponentOptions,
+  // Keyboard types
+  KeyHandler,
+  // Main interface
+  InteractiveRenderer,
+  // Node type
+  UINode,
+  // Manager state types (for advanced usage)
+  FocusManagerState,
+  KeyboardManagerState,
+  CursorManagerState,
+  StateManagerState,
+  MouseManagerState,
+  InputManagerState,
+  ComponentManagerState,
+  // String renderer options
+  InteractiveRenderOptions,
+} from './interactive/index'