@mdxui/terminal 2.0.0

package/src/__tests__/utils/utils.test.ts

@@ -0,0 +1,560 @@
+/**
+ * @mdxui/terminal Test Utilities Tests
+ *
+ * Verify that the test utilities themselves work correctly.
+ */
+import { describe, it, expect } from 'vitest'
+import React from 'react'
+
+import {
+  // Test renderer
+  createTestRenderer,
+  createTestRoot,
+  renderToLines,
+  renderToString,
+  prepareSnapshot,
+  mockCreateCliRenderer,
+  mockCreateRoot,
+  // Assertions
+  stripAnsi,
+  hasAnsiCodes,
+  visibleLength,
+  extractAnsiCodes,
+  getPlainContent,
+  expectTerminalContains,
+  expectTerminalNotContains,
+  expectTerminalMatches,
+  expectLineContains,
+  expectLineCount,
+  expectMinLines,
+  expectAnsiCode,
+  expectNoAnsiCode,
+  expectStyle,
+  expectReset,
+  expectBoxDrawing,
+  expectNoBoxDrawing,
+  expectMaxWidth,
+  toSnapshot,
+  terminalOutputEquals,
+} from './index'
+
+import { Box, Text, Button, Panel, renderComponent } from '../../components'
+import { ANSI, boxChars } from '../../theme'
+
+// ============================================================================
+// Test Renderer Tests
+// ============================================================================
+
+describe('Test Renderer', () => {
+  describe('createTestRenderer', () => {
+    it('creates renderer with default dimensions', () => {
+      const renderer = createTestRenderer()
+      expect(renderer.width).toBe(80)
+      expect(renderer.height).toBe(24)
+    })
+
+    it('creates renderer with custom dimensions', () => {
+      const renderer = createTestRenderer({ width: 40, height: 10 })
+      expect(renderer.width).toBe(40)
+      expect(renderer.height).toBe(10)
+    })
+
+    it('renders elements to lines', () => {
+      const renderer = createTestRenderer()
+      const element = Text({ children: 'Hello World' })
+      const lines = renderer.render(element)
+
+      expect(lines).toHaveLength(1)
+      expect(stripAnsi(lines[0])).toBe('Hello World')
+    })
+
+    it('clears buffer', () => {
+      const renderer = createTestRenderer()
+      const element = Text({ children: 'Test' })
+
+      renderer.render(element)
+      expect(renderer.getLastOutput()).toHaveLength(1)
+
+      renderer.clear()
+      expect(renderer.getLastOutput()).toHaveLength(0)
+    })
+
+    it('can be configured after creation', () => {
+      const renderer = createTestRenderer()
+      expect(renderer.width).toBe(80)
+
+      renderer.configure({ width: 40 })
+      expect(renderer.width).toBe(40)
+    })
+
+    it('lifecycle methods are callable', () => {
+      const renderer = createTestRenderer()
+      expect(() => renderer.start()).not.toThrow()
+      expect(() => renderer.stop()).not.toThrow()
+      expect(() => renderer.requestRender()).not.toThrow()
+      expect(() => renderer.destroy()).not.toThrow()
+    })
+  })
+
+  describe('createTestRoot', () => {
+    it('creates root with render/unmount methods', () => {
+      const renderer = createTestRenderer()
+      const root = createTestRoot(renderer)
+
+      expect(typeof root.render).toBe('function')
+      expect(typeof root.unmount).toBe('function')
+      expect(typeof root.getOutput).toBe('function')
+    })
+
+    it('renders elements and tracks output', () => {
+      const renderer = createTestRenderer()
+      const root = createTestRoot(renderer)
+
+      root.render(Text({ children: 'Hello' }))
+      const output = root.getOutput()
+
+      expect(output).toHaveLength(1)
+      expect(stripAnsi(output[0])).toBe('Hello')
+    })
+
+    it('clears output on unmount', () => {
+      const renderer = createTestRenderer()
+      const root = createTestRoot(renderer)
+
+      root.render(Text({ children: 'Test' }))
+      expect(root.getOutput().length).toBeGreaterThan(0)
+
+      root.unmount()
+      expect(root.getOutput()).toHaveLength(0)
+    })
+
+    it('handles null/undefined render', () => {
+      const renderer = createTestRenderer()
+      const root = createTestRoot(renderer)
+
+      root.render(null)
+      expect(root.getOutput()).toHaveLength(0)
+
+      root.render(undefined)
+      expect(root.getOutput()).toHaveLength(0)
+    })
+  })
+
+  describe('renderToLines', () => {
+    it('renders element to lines directly', () => {
+      const lines = renderToLines(Text({ children: 'Quick test' }))
+      expect(lines).toHaveLength(1)
+      expect(stripAnsi(lines[0])).toBe('Quick test')
+    })
+
+    it('accepts custom config', () => {
+      const lines = renderToLines(
+        Text({ children: 'Test' }),
+        { width: 40 }
+      )
+      expect(lines).toHaveLength(1)
+    })
+  })
+
+  describe('renderToString', () => {
+    it('renders element to joined string', () => {
+      const output = renderToString(Text({ children: 'Test' }))
+      expect(typeof output).toBe('string')
+      expect(output).toContain('Test')
+    })
+  })
+
+  describe('prepareSnapshot', () => {
+    it('strips ANSI codes when requested', () => {
+      const styledOutput = `${ANSI.bold}Bold${ANSI.reset}`
+      const snapshot = prepareSnapshot(styledOutput, { stripAnsi: true })
+      expect(snapshot).toBe('Bold')
+    })
+
+    it('preserves ANSI codes by default', () => {
+      const styledOutput = `${ANSI.bold}Bold${ANSI.reset}`
+      const snapshot = prepareSnapshot(styledOutput)
+      expect(snapshot).toContain(ANSI.bold)
+    })
+
+    it('trims trailing whitespace by default', () => {
+      const output = ['Line with trailing   ', 'Another line  ']
+      const snapshot = prepareSnapshot(output)
+      expect(snapshot).toBe('Line with trailing\nAnother line')
+    })
+
+    it('normalizes line endings', () => {
+      const output = 'Line1\r\nLine2\rLine3'
+      const snapshot = prepareSnapshot(output)
+      expect(snapshot).toBe('Line1\nLine2\nLine3')
+    })
+  })
+
+  describe('mockCreateCliRenderer', () => {
+    it('creates mock renderer factory', async () => {
+      const factory = mockCreateCliRenderer({ width: 40 })
+      const renderer = await factory()
+      expect(renderer.width).toBe(40)
+    })
+  })
+
+  describe('mockCreateRoot', () => {
+    it('creates mock root factory', () => {
+      const factory = mockCreateRoot()
+      const renderer = createTestRenderer()
+      const root = factory(renderer)
+      expect(typeof root.render).toBe('function')
+    })
+  })
+})
+
+// ============================================================================
+// ANSI Utilities Tests
+// ============================================================================
+
+describe('ANSI Utilities', () => {
+  describe('stripAnsi', () => {
+    it('removes ANSI escape codes', () => {
+      const styled = `${ANSI.bold}${ANSI.cyan}Hello${ANSI.reset}`
+      expect(stripAnsi(styled)).toBe('Hello')
+    })
+
+    it('returns unchanged string if no ANSI codes', () => {
+      expect(stripAnsi('Plain text')).toBe('Plain text')
+    })
+
+    it('handles empty string', () => {
+      expect(stripAnsi('')).toBe('')
+    })
+  })
+
+  describe('hasAnsiCodes', () => {
+    it('returns true for styled text', () => {
+      expect(hasAnsiCodes(`${ANSI.bold}Bold`)).toBe(true)
+    })
+
+    it('returns false for plain text', () => {
+      expect(hasAnsiCodes('Plain')).toBe(false)
+    })
+  })
+
+  describe('visibleLength', () => {
+    it('returns correct length ignoring ANSI', () => {
+      const styled = `${ANSI.bold}${ANSI.cyan}Hello${ANSI.reset}`
+      expect(visibleLength(styled)).toBe(5)
+    })
+  })
+
+  describe('extractAnsiCodes', () => {
+    it('extracts all ANSI codes from string', () => {
+      const styled = `${ANSI.bold}${ANSI.cyan}Hi${ANSI.reset}`
+      const codes = extractAnsiCodes(styled)
+      expect(codes).toContain(ANSI.bold)
+      expect(codes).toContain(ANSI.cyan)
+      expect(codes).toContain(ANSI.reset)
+    })
+
+    it('returns empty array for plain text', () => {
+      expect(extractAnsiCodes('Plain')).toEqual([])
+    })
+  })
+
+  describe('getPlainContent', () => {
+    it('joins array and strips ANSI', () => {
+      const lines = [`${ANSI.bold}Line 1${ANSI.reset}`, 'Line 2']
+      expect(getPlainContent(lines)).toBe('Line 1\nLine 2')
+    })
+
+    it('handles string input', () => {
+      expect(getPlainContent(`${ANSI.bold}Test${ANSI.reset}`)).toBe('Test')
+    })
+  })
+})
+
+// ============================================================================
+// Content Assertion Tests
+// ============================================================================
+
+describe('Content Assertions', () => {
+  describe('expectTerminalContains', () => {
+    it('passes when text is found', () => {
+      const output = [`${ANSI.bold}Hello World${ANSI.reset}`]
+      expect(() => expectTerminalContains(output, 'Hello')).not.toThrow()
+      expect(() => expectTerminalContains(output, 'World')).not.toThrow()
+    })
+
+    it('fails when text is not found', () => {
+      const output = ['Hello']
+      expect(() => expectTerminalContains(output, 'Goodbye')).toThrow()
+    })
+  })
+
+  describe('expectTerminalNotContains', () => {
+    it('passes when text is not found', () => {
+      const output = ['Hello']
+      expect(() => expectTerminalNotContains(output, 'Secret')).not.toThrow()
+    })
+
+    it('fails when text is found', () => {
+      const output = ['Contains Secret']
+      expect(() => expectTerminalNotContains(output, 'Secret')).toThrow()
+    })
+  })
+
+  describe('expectTerminalMatches', () => {
+    it('passes when pattern matches', () => {
+      const output = ['Hello World 123']
+      expect(() => expectTerminalMatches(output, /Hello \w+/)).not.toThrow()
+      expect(() => expectTerminalMatches(output, /\d+/)).not.toThrow()
+    })
+
+    it('fails when pattern does not match', () => {
+      const output = ['Hello']
+      expect(() => expectTerminalMatches(output, /Goodbye/)).toThrow()
+    })
+  })
+
+  describe('expectLineContains', () => {
+    it('checks specific line', () => {
+      const output = ['Header', 'Content', 'Footer']
+      expect(() => expectLineContains(output, 0, 'Header')).not.toThrow()
+      expect(() => expectLineContains(output, 1, 'Content')).not.toThrow()
+      expect(() => expectLineContains(output, 2, 'Footer')).not.toThrow()
+    })
+
+    it('fails for wrong line content', () => {
+      const output = ['Header', 'Content']
+      expect(() => expectLineContains(output, 0, 'Wrong')).toThrow()
+    })
+  })
+
+  describe('expectLineCount', () => {
+    it('checks exact line count', () => {
+      expect(() => expectLineCount(['a', 'b', 'c'], 3)).not.toThrow()
+      expect(() => expectLineCount(['a', 'b', 'c'], 2)).toThrow()
+    })
+  })
+
+  describe('expectMinLines', () => {
+    it('checks minimum line count', () => {
+      expect(() => expectMinLines(['a', 'b', 'c'], 2)).not.toThrow()
+      expect(() => expectMinLines(['a', 'b', 'c'], 3)).not.toThrow()
+      expect(() => expectMinLines(['a', 'b'], 3)).toThrow()
+    })
+  })
+})
+
+// ============================================================================
+// ANSI Style Assertion Tests
+// ============================================================================
+
+describe('ANSI Style Assertions', () => {
+  describe('expectAnsiCode', () => {
+    it('passes when code is present', () => {
+      const output = `${ANSI.bold}Bold${ANSI.reset}`
+      expect(() => expectAnsiCode(output, ANSI.bold)).not.toThrow()
+    })
+
+    it('fails when code is missing', () => {
+      const output = 'Plain text'
+      expect(() => expectAnsiCode(output, ANSI.bold)).toThrow()
+    })
+  })
+
+  describe('expectNoAnsiCode', () => {
+    it('passes when code is missing', () => {
+      const output = 'Plain text'
+      expect(() => expectNoAnsiCode(output, ANSI.bold)).not.toThrow()
+    })
+
+    it('fails when code is present', () => {
+      const output = `${ANSI.bold}Bold`
+      expect(() => expectNoAnsiCode(output, ANSI.bold)).toThrow()
+    })
+  })
+
+  describe('expectStyle', () => {
+    it('checks for named styles', () => {
+      const boldText = `${ANSI.bold}Bold${ANSI.reset}`
+      expect(() => expectStyle(boldText, 'bold')).not.toThrow()
+
+      const dimText = `${ANSI.dim}Dim${ANSI.reset}`
+      expect(() => expectStyle(dimText, 'dim')).not.toThrow()
+    })
+  })
+
+  describe('expectReset', () => {
+    it('checks for reset code', () => {
+      const styled = `${ANSI.bold}Text${ANSI.reset}`
+      expect(() => expectReset(styled)).not.toThrow()
+    })
+
+    it('fails without reset', () => {
+      const styled = `${ANSI.bold}Text`
+      expect(() => expectReset(styled)).toThrow()
+    })
+  })
+})
+
+// ============================================================================
+// Box Drawing Assertion Tests
+// ============================================================================
+
+describe('Box Drawing Assertions', () => {
+  describe('expectBoxDrawing', () => {
+    it('checks for single border characters', () => {
+      const element = Box({ border: 'single', width: 10, height: 3, children: '' })
+      const lines = renderComponent(element)
+
+      expect(() => expectBoxDrawing(lines, 'single')).not.toThrow()
+    })
+
+    it('checks for double border characters', () => {
+      const element = Box({ border: 'double', width: 10, height: 3, children: '' })
+      const lines = renderComponent(element)
+
+      expect(() => expectBoxDrawing(lines, 'double')).not.toThrow()
+    })
+
+    it('checks for rounded border characters', () => {
+      const element = Box({ border: 'rounded', width: 10, height: 3, children: '' })
+      const lines = renderComponent(element)
+
+      expect(() => expectBoxDrawing(lines, 'rounded')).not.toThrow()
+    })
+  })
+
+  describe('expectNoBoxDrawing', () => {
+    it('passes for text without borders', () => {
+      const lines = ['Plain text']
+      expect(() => expectNoBoxDrawing(lines)).not.toThrow()
+    })
+
+    it('fails when borders are present', () => {
+      const element = Box({ border: 'single', width: 10, height: 3, children: '' })
+      const lines = renderComponent(element)
+
+      expect(() => expectNoBoxDrawing(lines)).toThrow()
+    })
+  })
+})
+
+// ============================================================================
+// Dimension Assertion Tests
+// ============================================================================
+
+describe('Dimension Assertions', () => {
+  describe('expectMaxWidth', () => {
+    it('passes when all lines within width', () => {
+      const lines = ['Short', 'Also short']
+      expect(() => expectMaxWidth(lines, 20)).not.toThrow()
+    })
+
+    it('fails when line exceeds width', () => {
+      const lines = ['This is a much longer line']
+      expect(() => expectMaxWidth(lines, 10)).toThrow()
+    })
+
+    it('ignores ANSI codes when measuring', () => {
+      const lines = [`${ANSI.bold}${ANSI.cyan}Short${ANSI.reset}`]
+      expect(() => expectMaxWidth(lines, 10)).not.toThrow()
+    })
+  })
+})
+
+// ============================================================================
+// Snapshot Utility Tests
+// ============================================================================
+
+describe('Snapshot Utilities', () => {
+  describe('toSnapshot', () => {
+    it('creates snapshot-ready string', () => {
+      const lines = ['Line 1  ', 'Line 2  ']
+      const snapshot = toSnapshot(lines)
+      expect(snapshot).toBe('Line 1\nLine 2')
+    })
+
+    it('can strip ANSI codes', () => {
+      const lines = [`${ANSI.bold}Bold${ANSI.reset}`]
+      const snapshot = toSnapshot(lines, { stripAnsi: true })
+      expect(snapshot).toBe('Bold')
+    })
+  })
+
+  describe('terminalOutputEquals', () => {
+    it('compares plain content', () => {
+      const a = [`${ANSI.bold}Hello${ANSI.reset}`]
+      const b = [`${ANSI.dim}Hello${ANSI.reset}`]
+
+      expect(terminalOutputEquals(a, b)).toBe(true)
+    })
+
+    it('detects content differences', () => {
+      const a = ['Hello']
+      const b = ['Goodbye']
+
+      expect(terminalOutputEquals(a, b)).toBe(false)
+    })
+  })
+})
+
+// ============================================================================
+// Integration Tests with Real Components
+// ============================================================================
+
+describe('Integration with Components', () => {
+  it('works with Box component', () => {
+    const renderer = createTestRenderer()
+    const element = Box({ border: 'single', width: 20, height: 3, children: 'Test' })
+    const lines = renderer.render(element)
+
+    expectTerminalContains(lines, 'Test')
+    expectBoxDrawing(lines, 'single')
+    expectLineCount(lines, 3)
+  })
+
+  it('works with Text component', () => {
+    const renderer = createTestRenderer()
+    const element = Text({ bold: true, color: 'cyan', children: 'Styled' })
+    const lines = renderer.render(element)
+
+    expectTerminalContains(lines, 'Styled')
+    expectStyle(lines.join(''), 'bold')
+    expectAnsiCode(lines.join(''), ANSI.cyan)
+  })
+
+  it('works with Button component', () => {
+    const renderer = createTestRenderer()
+    const element = Button({ variant: 'primary', onPress: () => {}, children: 'Click Me' })
+    const lines = renderer.render(element)
+
+    expectTerminalContains(lines, 'Click Me')
+    expectStyle(lines.join(''), 'bold')
+  })
+
+  it('works with Panel component', () => {
+    const renderer = createTestRenderer()
+    const element = Panel({ title: 'Settings', children: 'Content' })
+    const lines = renderer.render(element)
+
+    expectTerminalContains(lines, 'Settings')
+    expectTerminalContains(lines, 'Content')
+    expectBoxDrawing(lines, 'single')
+  })
+
+  it('creates snapshots from component output', () => {
+    const element = Box({
+      border: 'single',
+      width: 15,
+      height: 3,
+      children: 'Hello'
+    })
+    const lines = renderComponent(element)
+    const snapshot = toSnapshot(lines, { stripAnsi: true })
+
+    // Snapshot should contain box and content
+    expect(snapshot).toContain(boxChars.single.topLeft)
+    expect(snapshot).toContain('Hello')
+    expect(snapshot).toContain(boxChars.single.bottomRight)
+  })
+})

package/src/components/containers/card.ts

@@ -0,0 +1,56 @@
+/**
+ * @mdxui/terminal/components/containers/card
+ *
+ * Card component for terminal rendering.
+ */
+
+import React, { type ReactElement } from 'react'
+import { ANSI, boxChars } from '../../theme'
+import type { CardProps, RenderContext } from '../types'
+import { extractChildren } from '../helpers'
+
+export function renderCard(props: CardProps, context: RenderContext): string[] {
+  const { children, title, border = 'single' } = props
+
+  const lines: string[] = []
+  const chars = border === 'double' ? boxChars.double : boxChars.single
+  const cardWidth = Math.min(context.width, 60) // Cards have max width
+
+  // Top border
+  if (border !== 'none') {
+    lines.push(chars.topLeft + chars.horizontal.repeat(cardWidth - 2) + chars.topRight)
+  }
+
+  // Title if present
+  if (title) {
+    const titleLine = ' ' + ANSI.bold + title + ANSI.reset
+    if (border !== 'none') {
+      lines.push(chars.vertical + titleLine.padEnd(cardWidth - 2 + ANSI.bold.length + ANSI.reset.length) + chars.vertical)
+      lines.push(chars.teeLeft + chars.horizontal.repeat(cardWidth - 2) + chars.teeRight)
+    } else {
+      lines.push(ANSI.bold + title + ANSI.reset)
+    }
+  }
+
+  // Content
+  const content = extractChildren(children)
+  const contentLines = content.split('\n')
+  for (const line of contentLines) {
+    if (border !== 'none') {
+      lines.push(chars.vertical + ' ' + line.padEnd(cardWidth - 4) + ' ' + chars.vertical)
+    } else {
+      lines.push(line)
+    }
+  }
+
+  // Bottom border
+  if (border !== 'none') {
+    lines.push(chars.bottomLeft + chars.horizontal.repeat(cardWidth - 2) + chars.bottomRight)
+  }
+
+  return lines
+}
+
+export function Card(props: CardProps): ReactElement {
+  return React.createElement('card', props)
+}

package/src/components/containers/dialog.ts

@@ -0,0 +1,53 @@
+/**
+ * @mdxui/terminal/components/containers/dialog
+ *
+ * Dialog component for terminal rendering.
+ */
+
+import React, { type ReactElement } from 'react'
+import { ANSI, boxChars } from '../../theme'
+import type { DialogProps, RenderContext } from '../types'
+import { extractChildren } from '../helpers'
+
+export function renderDialog(props: DialogProps, context: RenderContext): string[] {
+  const { open, title, children } = props
+
+  if (!open) {
+    return ['']
+  }
+
+  const dialogWidth = 40
+  const padding = Math.floor((context.width - dialogWidth) / 2)
+  const paddingStr = ' '.repeat(Math.max(0, padding))
+
+  const lines: string[] = []
+  const chars = boxChars.single
+
+  // Top border
+  lines.push(paddingStr + ANSI.cyan + chars.topLeft + chars.horizontal.repeat(dialogWidth - 2) + chars.topRight + ANSI.reset)
+
+  // Title if present
+  if (title) {
+    const titlePadded = (' ' + title).padEnd(dialogWidth - 2)
+    lines.push(paddingStr + ANSI.cyan + chars.vertical + ANSI.reset + ANSI.bold + titlePadded + ANSI.reset + ANSI.cyan + chars.vertical + ANSI.reset)
+    // Title separator
+    lines.push(paddingStr + ANSI.cyan + chars.teeLeft + chars.horizontal.repeat(dialogWidth - 2) + chars.teeRight + ANSI.reset)
+  }
+
+  // Content
+  const content = extractChildren(children)
+  const contentLines = content.split('\n')
+  for (const contentLine of contentLines) {
+    const paddedContent = (' ' + contentLine).padEnd(dialogWidth - 2)
+    lines.push(paddingStr + ANSI.cyan + chars.vertical + ANSI.reset + paddedContent + ANSI.cyan + chars.vertical + ANSI.reset)
+  }
+
+  // Bottom border
+  lines.push(paddingStr + ANSI.cyan + chars.bottomLeft + chars.horizontal.repeat(dialogWidth - 2) + chars.bottomRight + ANSI.reset)
+
+  return lines
+}
+
+export function Dialog(props: DialogProps): ReactElement {
+  return React.createElement('dialog', props)
+}

package/src/components/containers/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @mdxui/terminal/components/containers
+ *
+ * Container terminal components.
+ */
+
+export { renderPanel, Panel } from './panel'
+export { renderCard, Card } from './card'
+export { renderDialog, Dialog } from './dialog'