@mdxui/terminal 2.0.0

package/src/__tests__/errors.test.ts

@@ -0,0 +1,660 @@
+/**
+ * @mdxui/terminal Error Handling Tests
+ *
+ * TDD RED Phase: These tests define the contract for proper error handling
+ * behavior throughout the terminal package. Tests verify:
+ * - Graceful handling of invalid inputs
+ * - Proper error throwing vs silent fallbacks
+ * - Edge case behavior for boundary conditions
+ *
+ * NOTE: Some tests define expected behavior that may need implementation fixes.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import React from 'react'
+
+// ============================================================================
+// Color Conversion Error Handling
+// ============================================================================
+
+describe('Error Handling', () => {
+  describe('Color Conversion', () => {
+    describe('hex()', () => {
+      it('throws ZodError for invalid hex string', async () => {
+        const { hex } = await import('@mdxui/terminal')
+        // With Zod validation, invalid hex throws instead of falling back
+        expect(() => hex('not-a-hex')).toThrow(/Invalid hex color format/)
+      })
+
+      it('throws ZodError for empty string', async () => {
+        const { hex } = await import('@mdxui/terminal')
+        // With Zod validation, empty string throws instead of falling back
+        expect(() => hex('')).toThrow(/Invalid hex color format/)
+      })
+
+      it('handles 3-digit hex correctly', async () => {
+        const { hex } = await import('@mdxui/terminal')
+        // #fff should expand to #ffffff (255, 255, 255)
+        const result = hex('#fff')
+        expect(result).toBe('\x1b[38;2;255;255;255m')
+      })
+
+      it('handles 6-digit hex correctly', async () => {
+        const { hex } = await import('@mdxui/terminal')
+        // #3b82f6 is Tailwind blue-500
+        const result = hex('#3b82f6')
+        expect(result).toBe('\x1b[38;2;59;130;246m')
+      })
+
+      it('handles hex without # prefix', async () => {
+        const { hex } = await import('@mdxui/terminal')
+        const result = hex('ff0000')
+        expect(result).toBe('\x1b[38;2;255;0;0m')
+      })
+
+      it('handles 3-digit hex without # prefix', async () => {
+        const { hex } = await import('@mdxui/terminal')
+        const result = hex('f00')
+        expect(result).toBe('\x1b[38;2;255;0;0m')
+      })
+    })
+
+    describe('hexToRgb()', () => {
+      it('returns black for invalid hex string', async () => {
+        const { hexToRgb } = await import('@mdxui/terminal')
+        const result = hexToRgb('invalid')
+        expect(result).toEqual({ r: 0, g: 0, b: 0 })
+      })
+
+      it('returns black for hex with wrong length', async () => {
+        const { hexToRgb } = await import('@mdxui/terminal')
+        expect(hexToRgb('#12')).toEqual({ r: 0, g: 0, b: 0 })
+        expect(hexToRgb('#1234')).toEqual({ r: 0, g: 0, b: 0 })
+        expect(hexToRgb('#12345')).toEqual({ r: 0, g: 0, b: 0 })
+        expect(hexToRgb('#1234567')).toEqual({ r: 0, g: 0, b: 0 })
+      })
+
+      it('returns black for empty string', async () => {
+        const { hexToRgb } = await import('@mdxui/terminal')
+        const result = hexToRgb('')
+        expect(result).toEqual({ r: 0, g: 0, b: 0 })
+      })
+
+      it('returns black for only hash prefix', async () => {
+        const { hexToRgb } = await import('@mdxui/terminal')
+        const result = hexToRgb('#')
+        expect(result).toEqual({ r: 0, g: 0, b: 0 })
+      })
+    })
+
+    describe('rgb() validation', () => {
+      it('accepts RGB values in valid range (0-255)', async () => {
+        const { rgb } = await import('@mdxui/terminal')
+        // Valid range should produce valid ANSI codes
+        expect(rgb(0, 0, 0)).toBe('\x1b[38;2;0;0;0m')
+        expect(rgb(255, 255, 255)).toBe('\x1b[38;2;255;255;255m')
+        expect(rgb(128, 128, 128)).toBe('\x1b[38;2;128;128;128m')
+      })
+
+      it('throws ZodError for values outside 0-255 range', async () => {
+        const { rgb } = await import('@mdxui/terminal')
+        // With Zod validation, out-of-range values throw instead of passing through
+        expect(() => rgb(-10, 0, 0)).toThrow(/RGB component must be >= 0/)
+        expect(() => rgb(300, 0, 0)).toThrow(/RGB component must be <= 255/)
+      })
+    })
+
+    describe('tailwindToTerminal()', () => {
+      it('handles unknown colors gracefully by returning empty string', async () => {
+        const { tailwindToTerminal } = await import('@mdxui/terminal')
+        expect(tailwindToTerminal('text-unknown-999')).toBe('')
+        expect(tailwindToTerminal('bg-nonexistent-500')).toBe('')
+        expect(tailwindToTerminal('random-class')).toBe('')
+      })
+
+      it('handles empty string gracefully', async () => {
+        const { tailwindToTerminal } = await import('@mdxui/terminal')
+        expect(tailwindToTerminal('')).toBe('')
+      })
+
+      it('handles null-like input gracefully', async () => {
+        const { tailwindToTerminal } = await import('@mdxui/terminal')
+        // The function should handle null/undefined gracefully
+        expect(tailwindToTerminal(null as unknown as string)).toBe('')
+        expect(tailwindToTerminal(undefined as unknown as string)).toBe('')
+      })
+
+      it('handles whitespace-only input', async () => {
+        const { tailwindToTerminal } = await import('@mdxui/terminal')
+        expect(tailwindToTerminal('   ')).toBe('')
+      })
+    })
+
+    describe('tailwindToAnsi()', () => {
+      it('returns empty string for unknown classes', async () => {
+        const { tailwindToAnsi } = await import('@mdxui/terminal')
+        expect(tailwindToAnsi('text-fake-color-999')).toBe('')
+        expect(tailwindToAnsi('completely-invalid')).toBe('')
+      })
+
+      it('returns empty string for empty input', async () => {
+        const { tailwindToAnsi } = await import('@mdxui/terminal')
+        expect(tailwindToAnsi('')).toBe('')
+      })
+    })
+  })
+
+  // ============================================================================
+  // Component Rendering Error Handling
+  // ============================================================================
+
+  describe('Component Rendering', () => {
+    describe('Box component', () => {
+      it('handles width of 0 gracefully', async () => {
+        const { renderComponent, Box } = await import('@mdxui/terminal')
+        const element = React.createElement(Box, { width: 0, children: 'test' })
+        // Should not throw, should return some output (possibly empty or minimal)
+        expect(() => renderComponent(element)).not.toThrow()
+      })
+
+      it('handles negative width gracefully', async () => {
+        const { renderComponent, Box } = await import('@mdxui/terminal')
+        const element = React.createElement(Box, { width: -10, children: 'test' })
+        // Should not throw - implementation should handle gracefully
+        expect(() => renderComponent(element)).not.toThrow()
+      })
+
+      it('handles undefined children gracefully', async () => {
+        const { renderComponent, Box } = await import('@mdxui/terminal')
+        const element = React.createElement(Box, { width: 20 })
+        const result = renderComponent(element)
+        expect(Array.isArray(result)).toBe(true)
+      })
+
+      it('handles null children gracefully', async () => {
+        const { renderComponent, Box } = await import('@mdxui/terminal')
+        const element = React.createElement(Box, { width: 20, children: null })
+        const result = renderComponent(element)
+        expect(Array.isArray(result)).toBe(true)
+      })
+    })
+
+    describe('Table component', () => {
+      it('renders empty array for empty data', async () => {
+        const { renderComponent, Table } = await import('@mdxui/terminal')
+        const element = React.createElement(Table, {
+          data: [],
+          columns: [{ key: 'name', header: 'Name' }],
+        })
+        const result = renderComponent(element)
+        expect(Array.isArray(result)).toBe(true)
+        // Should have at least the header row
+        expect(result.length).toBeGreaterThanOrEqual(1)
+      })
+
+      it('handles empty columns array', async () => {
+        const { renderComponent, Table } = await import('@mdxui/terminal')
+        const element = React.createElement(Table, {
+          data: [{ name: 'test' }],
+          columns: [],
+        })
+        // Should not throw with empty columns
+        expect(() => renderComponent(element)).not.toThrow()
+      })
+
+      it('handles missing column key in data', async () => {
+        const { renderComponent, Table } = await import('@mdxui/terminal')
+        const element = React.createElement(Table, {
+          data: [{ name: 'test' }],
+          columns: [{ key: 'nonexistent', header: 'Missing' }],
+        })
+        // Should render without throwing, showing empty/undefined values
+        expect(() => renderComponent(element)).not.toThrow()
+      })
+    })
+
+    describe('renderComponent()', () => {
+      it('throws when given null element', async () => {
+        const { renderComponent } = await import('@mdxui/terminal')
+        // @ts-expect-error Testing invalid input
+        // Current implementation throws on null - does not handle gracefully
+        expect(() => renderComponent(null)).toThrow()
+      })
+
+      it('handles unknown component type gracefully', async () => {
+        const { renderComponent } = await import('@mdxui/terminal')
+        // Creating an element with an unknown type string
+        const unknownElement = React.createElement('unknown-component', {
+          children: 'content',
+        })
+        const result = renderComponent(unknownElement)
+        // Should return empty array or the children text for unknown types
+        expect(Array.isArray(result)).toBe(true)
+      })
+
+      it('handles deeply nested invalid elements', async () => {
+        const { renderComponent, Box } = await import('@mdxui/terminal')
+        const element = React.createElement(Box, {
+          children: React.createElement('invalid', {
+            children: React.createElement('also-invalid', { children: 'text' }),
+          }),
+        })
+        expect(() => renderComponent(element)).not.toThrow()
+      })
+    })
+  })
+
+  // ============================================================================
+  // Keyboard Manager Error Handling
+  // ============================================================================
+
+  describe('Keyboard Manager', () => {
+    describe('binding validation', () => {
+      it('handles empty bindings object', async () => {
+        const { createKeyboardManager } = await import('@mdxui/terminal')
+        const manager = createKeyboardManager({ bindings: {} })
+        expect(manager.getAction('anything')).toBeUndefined()
+        expect(manager.handleKey('anything')).toBe(false)
+      })
+
+      it('handles binding with empty string key', async () => {
+        const { createKeyboardManager } = await import('@mdxui/terminal')
+        const manager = createKeyboardManager({
+          bindings: { '': 'empty-key-action' },
+        })
+        // Empty string key behavior - should be retrievable
+        expect(manager.getAction('')).toBe('empty-key-action')
+      })
+    })
+
+    describe('destroyed manager behavior', () => {
+      it('clears pending sequence on destroy', async () => {
+        const { createKeyboardManager } = await import('@mdxui/terminal')
+        const manager = createKeyboardManager({
+          bindings: { gg: 'move-first' },
+        })
+
+        manager.handleKey('g')
+        expect(manager.getPendingSequence()).toBe('g')
+
+        manager.destroy()
+        expect(manager.getPendingSequence()).toBe('')
+      })
+
+      it('can be called multiple times safely', async () => {
+        const { createKeyboardManager } = await import('@mdxui/terminal')
+        const manager = createKeyboardManager({
+          bindings: { gg: 'move-first' },
+        })
+
+        manager.handleKey('g')
+        expect(() => {
+          manager.destroy()
+          manager.destroy()
+          manager.destroy()
+        }).not.toThrow()
+      })
+
+      it('handles calls after destroy without crashing', async () => {
+        const { createKeyboardManager } = await import('@mdxui/terminal')
+        const onAction = vi.fn()
+        const manager = createKeyboardManager({
+          bindings: { j: 'move-down' },
+          onAction,
+        })
+
+        manager.destroy()
+
+        // After destroy, the manager should still be usable but in disabled state
+        // or handle calls gracefully
+        expect(() => manager.handleKey('j')).not.toThrow()
+        expect(() => manager.getAction('j')).not.toThrow()
+        expect(() => manager.addBinding('k', 'move-up')).not.toThrow()
+      })
+    })
+
+    describe('sequence timeout behavior', () => {
+      it('sequence times out and triggers fallback action', async () => {
+        const { createKeyboardManager } = await import('@mdxui/terminal')
+        const onAction = vi.fn()
+
+        const manager = createKeyboardManager({
+          bindings: {
+            gg: 'move-first',
+            g: 'go', // Fallback if only single g
+          },
+          onAction,
+          sequenceTimeout: 100,
+        })
+
+        manager.handleKey('g')
+
+        // Wait for timeout to fire
+        await new Promise((r) => setTimeout(r, 150))
+
+        // Should have called the fallback 'g' action after timeout
+        expect(onAction).toHaveBeenCalledWith('go', { key: 'g' })
+      })
+
+      it('sequence timeout does nothing when no fallback exists', async () => {
+        const { createKeyboardManager } = await import('@mdxui/terminal')
+        const onAction = vi.fn()
+
+        const manager = createKeyboardManager({
+          bindings: {
+            gg: 'move-first',
+            // No fallback for single 'g'
+          },
+          onAction,
+          sequenceTimeout: 100,
+        })
+
+        manager.handleKey('g')
+        await new Promise((r) => setTimeout(r, 150))
+
+        // Should not have called any action since 'g' alone has no binding
+        expect(onAction).not.toHaveBeenCalled()
+      })
+
+      it('destroy clears pending sequence timer to prevent memory leak', async () => {
+        const { createKeyboardManager } = await import('@mdxui/terminal')
+        const onAction = vi.fn()
+
+        const manager = createKeyboardManager({
+          bindings: {
+            gg: 'move-first',
+            g: 'go',
+          },
+          onAction,
+          sequenceTimeout: 100,
+        })
+
+        // Start a sequence which creates a timer
+        manager.handleKey('g')
+
+        // Immediately destroy before timeout fires
+        manager.destroy()
+
+        const callCountBeforeWait = onAction.mock.calls.length
+
+        // Wait for what would have been the timeout
+        await new Promise((r) => setTimeout(r, 200))
+
+        // The timeout handler should NOT have been called because destroy cleared it
+        expect(onAction.mock.calls.length).toBe(callCountBeforeWait)
+      })
+    })
+
+    describe('disabled manager', () => {
+      it('ignores key handling when disabled', async () => {
+        const { createKeyboardManager } = await import('@mdxui/terminal')
+        const onAction = vi.fn()
+
+        const manager = createKeyboardManager({
+          bindings: { j: 'move-down' },
+          onAction,
+          enabled: false,
+        })
+
+        const result = manager.handleKey('j')
+        expect(result).toBe(false)
+        expect(onAction).not.toHaveBeenCalled()
+      })
+
+      it('enable/disable toggles work correctly', async () => {
+        const { createKeyboardManager } = await import('@mdxui/terminal')
+        const onAction = vi.fn()
+
+        const manager = createKeyboardManager({
+          bindings: { j: 'move-down' },
+          onAction,
+        })
+
+        manager.disable()
+        manager.handleKey('j')
+        expect(onAction).not.toHaveBeenCalled()
+
+        manager.enable()
+        manager.handleKey('j')
+        expect(onAction).toHaveBeenCalledWith('move-down', { key: 'j' })
+      })
+    })
+  })
+
+  // ============================================================================
+  // Theme System Error Handling
+  // ============================================================================
+
+  describe('Theme System', () => {
+    describe('createTheme()', () => {
+      it('throws ZodError for invalid ANSI color values', async () => {
+        const { createTheme } = await import('@mdxui/terminal')
+        // With Zod validation, the error message comes from the schema
+        expect(() =>
+          createTheme({
+            primary: 'not-an-ansi-code',
+          })
+        ).toThrow(/Invalid ANSI escape sequence/)
+      })
+
+      it('accepts empty string as valid color (no color)', async () => {
+        const { createTheme } = await import('@mdxui/terminal')
+        expect(() =>
+          createTheme({
+            background: '',
+          })
+        ).not.toThrow()
+      })
+
+      it('accepts valid ANSI codes', async () => {
+        const { createTheme } = await import('@mdxui/terminal')
+        expect(() =>
+          createTheme({
+            primary: '\x1b[34m',
+            secondary: '\x1b[38;5;45m',
+          })
+        ).not.toThrow()
+      })
+
+      it('creates theme with defaults when no options provided', async () => {
+        const { createTerminalTheme } = await import('@mdxui/terminal')
+        const theme = createTerminalTheme({})
+        expect(theme.mode).toBe('dark')
+        expect(theme.colors).toBeDefined()
+        expect(theme.colors.primary).toBeDefined()
+      })
+    })
+
+    describe('extendTheme()', () => {
+      it('merges partial themes safely without modifying original', async () => {
+        const { extendTheme, defaultTheme } = await import('@mdxui/terminal')
+
+        const originalPrimary = defaultTheme.primary
+        const extended = extendTheme(defaultTheme, {
+          primary: '\x1b[35m',
+        })
+
+        // Original should not be modified
+        expect(defaultTheme.primary).toBe(originalPrimary)
+        // Extended should have new value
+        expect(extended.primary).toBe('\x1b[35m')
+      })
+
+      it('handles empty override object', async () => {
+        const { extendTheme, defaultTheme } = await import('@mdxui/terminal')
+        const extended = extendTheme(defaultTheme, {})
+        expect(extended).toEqual(defaultTheme)
+      })
+
+      it('deep merges nested objects like typography and spacing', async () => {
+        const { extendTheme, defaultTheme } = await import('@mdxui/terminal')
+        const extended = extendTheme(defaultTheme, {
+          typography: { headingWeight: 'normal' },
+        })
+
+        // Should have merged the typography object
+        expect(extended.typography?.headingWeight).toBe('normal')
+        // Other typography properties should be preserved
+        expect(extended.typography?.bodyWeight).toBe('normal')
+        expect(extended.typography?.codeFont).toBe('monospace')
+      })
+    })
+
+    describe('getThemeColor()', () => {
+      it('throws when unknown key and no fallback provided', async () => {
+        const { getThemeColor, createTerminalTheme } = await import('@mdxui/terminal')
+        const theme = createTerminalTheme({ mode: 'dark' })
+
+        expect(() =>
+          getThemeColor(theme, 'nonexistent' as unknown as 'primary')
+        ).toThrow()
+      })
+
+      it('returns fallback for unknown key when provided', async () => {
+        const { getThemeColor, createTerminalTheme } = await import('@mdxui/terminal')
+        const theme = createTerminalTheme({ mode: 'dark' })
+        const fallback = '\x1b[37m'
+
+        const color = getThemeColor(
+          theme,
+          'nonexistent' as unknown as 'primary',
+          fallback
+        )
+        expect(color).toBe(fallback)
+      })
+    })
+
+    describe('degradeColor()', () => {
+      it('returns empty string for support level none', async () => {
+        const { degradeColor } = await import('@mdxui/terminal')
+        const color = '\x1b[38;5;33m'
+        expect(degradeColor(color, 'none')).toBe('')
+      })
+
+      it('passes through valid color when support matches', async () => {
+        const { degradeColor } = await import('@mdxui/terminal')
+        const color256 = '\x1b[38;5;33m'
+        expect(degradeColor(color256, '256')).toBe(color256)
+      })
+
+      it('handles empty string input', async () => {
+        const { degradeColor } = await import('@mdxui/terminal')
+        expect(degradeColor('', '256')).toBe('')
+      })
+
+      it('handles invalid ANSI code gracefully', async () => {
+        const { degradeColor } = await import('@mdxui/terminal')
+        // Invalid ANSI should pass through unchanged
+        expect(degradeColor('not-ansi', '256')).toBe('not-ansi')
+      })
+
+      it('converts truecolor to 256 correctly', async () => {
+        const { degradeColor } = await import('@mdxui/terminal')
+        const truecolor = '\x1b[38;2;59;130;246m' // RGB for blue-500
+        const degraded = degradeColor(truecolor, '256')
+        // Should be a valid 256-color code
+        expect(degraded).toMatch(/\x1b\[38;5;\d+m/)
+      })
+
+      it('converts 256 to 16 color correctly', async () => {
+        const { degradeColor } = await import('@mdxui/terminal')
+        const color256 = '\x1b[38;5;33m' // Blue in 256 palette
+        const degraded = degradeColor(color256, '16')
+        // Should be a basic 16-color code (30-37 or 90-97)
+        expect(degraded).toMatch(/\x1b\[(3[0-7]|9[0-7])m/)
+      })
+    })
+
+    describe('cssVarToAnsi()', () => {
+      it('returns empty string for unknown CSS variables', async () => {
+        const { cssVarToAnsi, createTerminalTheme } = await import('@mdxui/terminal')
+        const theme = createTerminalTheme({ mode: 'dark' })
+        expect(cssVarToAnsi('--unknown-variable', theme)).toBe('')
+        expect(cssVarToAnsi('not-a-css-var', theme)).toBe('')
+      })
+
+      it('handles empty string CSS variable', async () => {
+        const { cssVarToAnsi, createTerminalTheme } = await import('@mdxui/terminal')
+        const theme = createTerminalTheme({ mode: 'dark' })
+        expect(cssVarToAnsi('', theme)).toBe('')
+      })
+    })
+  })
+
+  // ============================================================================
+  // Input Normalization Edge Cases
+  // ============================================================================
+
+  describe('Input Normalization', () => {
+    describe('normalizeReadlineKey()', () => {
+      it('handles undefined string and key', async () => {
+        const { normalizeReadlineKey } = await import('@mdxui/terminal')
+        const result = normalizeReadlineKey(undefined, undefined)
+        expect(result.name).toBe('')
+        expect(result.ctrl).toBe(false)
+        expect(result.alt).toBe(false)
+        expect(result.shift).toBe(false)
+        expect(result.meta).toBe(false)
+      })
+
+      it('handles empty string input', async () => {
+        const { normalizeReadlineKey } = await import('@mdxui/terminal')
+        const result = normalizeReadlineKey('', undefined)
+        expect(result.name).toBe('')
+      })
+    })
+
+    describe('keyToBindingString()', () => {
+      it('handles key with no modifiers', async () => {
+        const { keyToBindingString } = await import('@mdxui/terminal')
+        const result = keyToBindingString({
+          name: 'a',
+          ctrl: false,
+          alt: false,
+          shift: false,
+          meta: false,
+        })
+        expect(result).toBe('a')
+      })
+
+      it('handles empty key name', async () => {
+        const { keyToBindingString } = await import('@mdxui/terminal')
+        const result = keyToBindingString({
+          name: '',
+          ctrl: false,
+          alt: false,
+          shift: false,
+          meta: false,
+        })
+        expect(result).toBe('')
+      })
+
+      it('handles empty key name with modifiers', async () => {
+        const { keyToBindingString } = await import('@mdxui/terminal')
+        const result = keyToBindingString({
+          name: '',
+          ctrl: true,
+          alt: false,
+          shift: false,
+          meta: false,
+        })
+        // Should produce 'ctrl+' with empty key
+        expect(result).toBe('ctrl+')
+      })
+    })
+
+    describe('attachKeyboardManager()', () => {
+      it('throws error for non-TTY stdin', async () => {
+        const { createKeyboardManager, attachKeyboardManager } = await import('@mdxui/terminal')
+        const manager = createKeyboardManager({ bindings: {} })
+
+        const mockStream = {
+          isTTY: false,
+        } as NodeJS.ReadStream
+
+        expect(() => attachKeyboardManager(manager, { input: mockStream })).toThrow(
+          /requires a TTY stdin/
+        )
+      })
+    })
+  })
+})