@mdxui/terminal 2.0.0

package/src/storybook/keyboard-simulator.ts

@@ -0,0 +1,501 @@
+/**
+ * @mdxui/terminal Keyboard Simulator
+ *
+ * Provides utilities for simulating keyboard events in Storybook stories
+ * for testing interactive terminal components.
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```tsx
+ * import { createKeyboardSimulator, KeySequence } from '@mdxui/terminal/storybook'
+ *
+ * const simulator = createKeyboardSimulator({ renderer })
+ *
+ * // Single key press
+ * simulator.press('enter')
+ *
+ * // Key with modifiers
+ * simulator.press('s', { ctrl: true })
+ *
+ * // Predefined sequences
+ * simulator.sequence(KeySequence.NAVIGATE_DOWN_3)
+ * ```
+ */
+
+import type { InteractiveRenderer } from '../renderers/interactive'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Key modifiers for keyboard events
+ */
+export interface KeyModifiers {
+  /** Ctrl key pressed */
+  ctrl?: boolean
+  /** Alt/Option key pressed */
+  alt?: boolean
+  /** Shift key pressed */
+  shift?: boolean
+  /** Meta/Command key pressed */
+  meta?: boolean
+}
+
+/**
+ * Single key press event
+ */
+export interface KeyPress {
+  /** Key name (e.g., 'enter', 'tab', 'a', 'escape') */
+  key: string
+  /** Key modifiers */
+  modifiers?: KeyModifiers
+  /** Delay in ms before this key press (default: 0) */
+  delay?: number
+}
+
+/**
+ * Configuration for the keyboard simulator
+ */
+export interface KeyboardSimulatorConfig {
+  /** Interactive renderer instance */
+  renderer: InteractiveRenderer
+  /** Default delay between key presses in ms (default: 0) */
+  defaultDelay?: number
+  /** Callback when key is pressed */
+  onKeyPress?: (key: string, modifiers: KeyModifiers) => void
+  /** Callback when sequence completes */
+  onSequenceComplete?: (sequence: KeyPress[]) => void
+}
+
+/**
+ * Keyboard simulator instance
+ */
+export interface KeyboardSimulator {
+  /** Press a single key */
+  press(key: string, modifiers?: KeyModifiers): void
+  /** Press a key and return a promise that resolves after the default delay */
+  pressAsync(key: string, modifiers?: KeyModifiers): Promise<void>
+  /** Execute a sequence of key presses */
+  sequence(keys: KeyPress[]): void
+  /** Execute a sequence of key presses with delays */
+  sequenceAsync(keys: KeyPress[]): Promise<void>
+  /** Type a string character by character */
+  type(text: string): void
+  /** Type a string character by character with delays */
+  typeAsync(text: string, charDelay?: number): Promise<void>
+  /** Reset simulator state */
+  reset(): void
+  /** Get list of pressed keys (for assertions) */
+  getPressedKeys(): string[]
+  /** Clear pressed keys history */
+  clearHistory(): void
+}
+
+// ============================================================================
+// Predefined Key Sequences
+// ============================================================================
+
+/**
+ * Common key sequences for testing navigation patterns
+ */
+export const KeySequence = {
+  /** Navigate down one item */
+  NAVIGATE_DOWN: [{ key: 'down' }] as KeyPress[],
+
+  /** Navigate down three items */
+  NAVIGATE_DOWN_3: [
+    { key: 'down' },
+    { key: 'down' },
+    { key: 'down' },
+  ] as KeyPress[],
+
+  /** Navigate up one item */
+  NAVIGATE_UP: [{ key: 'up' }] as KeyPress[],
+
+  /** Navigate up three items */
+  NAVIGATE_UP_3: [
+    { key: 'up' },
+    { key: 'up' },
+    { key: 'up' },
+  ] as KeyPress[],
+
+  /** Tab forward through focusables */
+  TAB_FORWARD: [{ key: 'tab' }] as KeyPress[],
+
+  /** Tab forward three times */
+  TAB_FORWARD_3: [
+    { key: 'tab' },
+    { key: 'tab' },
+    { key: 'tab' },
+  ] as KeyPress[],
+
+  /** Tab backward through focusables */
+  TAB_BACKWARD: [{ key: 'tab', modifiers: { shift: true } }] as KeyPress[],
+
+  /** Tab backward three times */
+  TAB_BACKWARD_3: [
+    { key: 'tab', modifiers: { shift: true } },
+    { key: 'tab', modifiers: { shift: true } },
+    { key: 'tab', modifiers: { shift: true } },
+  ] as KeyPress[],
+
+  /** Select/activate focused element */
+  SELECT: [{ key: 'enter' }] as KeyPress[],
+
+  /** Toggle focused element (e.g., checkbox) */
+  TOGGLE: [{ key: 'space' }] as KeyPress[],
+
+  /** Cancel/escape current action */
+  CANCEL: [{ key: 'escape' }] as KeyPress[],
+
+  /** Navigate to first item (vim: gg) */
+  GOTO_FIRST: [{ key: 'g' }, { key: 'g' }] as KeyPress[],
+
+  /** Navigate to last item (vim: G) */
+  GOTO_LAST: [{ key: 'G', modifiers: { shift: true } }] as KeyPress[],
+
+  /** Open search mode (vim: /) */
+  SEARCH: [{ key: '/' }] as KeyPress[],
+
+  /** Navigate down and select */
+  NAVIGATE_DOWN_SELECT: [{ key: 'down' }, { key: 'enter' }] as KeyPress[],
+
+  /** Navigate to next item using j (vim) */
+  VIM_DOWN: [{ key: 'j' }] as KeyPress[],
+
+  /** Navigate to previous item using k (vim) */
+  VIM_UP: [{ key: 'k' }] as KeyPress[],
+
+  /** Navigate left using h (vim) */
+  VIM_LEFT: [{ key: 'h' }] as KeyPress[],
+
+  /** Navigate right using l (vim) */
+  VIM_RIGHT: [{ key: 'l' }] as KeyPress[],
+
+  /** Delete sequence (vim: dd) */
+  VIM_DELETE: [{ key: 'd' }, { key: 'd' }] as KeyPress[],
+
+  /** Home key - jump to beginning */
+  HOME: [{ key: 'home' }] as KeyPress[],
+
+  /** End key - jump to end */
+  END: [{ key: 'end' }] as KeyPress[],
+
+  /** Page down */
+  PAGE_DOWN: [{ key: 'pagedown' }] as KeyPress[],
+
+  /** Page up */
+  PAGE_UP: [{ key: 'pageup' }] as KeyPress[],
+
+  /** Ctrl+C - cancel/interrupt */
+  INTERRUPT: [{ key: 'c', modifiers: { ctrl: true } }] as KeyPress[],
+
+  /** Ctrl+S - save */
+  SAVE: [{ key: 's', modifiers: { ctrl: true } }] as KeyPress[],
+} as const
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+/**
+ * Convert key and modifiers to binding string format
+ */
+function toBindingString(key: string, modifiers?: KeyModifiers): string {
+  const parts: string[] = []
+
+  if (modifiers?.ctrl) parts.push('ctrl')
+  if (modifiers?.alt) parts.push('alt')
+  if (modifiers?.shift) parts.push('shift')
+  if (modifiers?.meta) parts.push('meta')
+
+  parts.push(key.toLowerCase())
+
+  return parts.join('+')
+}
+
+/**
+ * Sleep utility for async operations
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/**
+ * Creates a keyboard simulator for testing interactive terminal components.
+ *
+ * The simulator wraps the interactive renderer's `emitKey` method and provides
+ * higher-level abstractions for common keyboard testing patterns.
+ *
+ * @param config - Simulator configuration
+ * @returns Keyboard simulator instance
+ *
+ * @example
+ * ```tsx
+ * const renderer = await createInteractiveRenderer({ vimBindings: true })
+ * const simulator = createKeyboardSimulator({ renderer })
+ *
+ * // Register some focusable elements
+ * renderer.registerFocusable('item-1', { tabIndex: 0 })
+ * renderer.registerFocusable('item-2', { tabIndex: 0 })
+ * renderer.registerFocusable('item-3', { tabIndex: 0 })
+ *
+ * // Focus first item
+ * renderer.focusById('item-1')
+ *
+ * // Navigate down using simulator
+ * simulator.press('j')  // vim down
+ * expect(renderer.getFocusedId()).toBe('item-2')
+ *
+ * // Or use predefined sequences
+ * simulator.sequence(KeySequence.NAVIGATE_DOWN)
+ * expect(renderer.getFocusedId()).toBe('item-3')
+ * ```
+ */
+export function createKeyboardSimulator(
+  config: KeyboardSimulatorConfig
+): KeyboardSimulator {
+  const { renderer, defaultDelay = 0, onKeyPress, onSequenceComplete } = config
+
+  // Track pressed keys for assertions
+  const pressedKeys: string[] = []
+
+  const simulator: KeyboardSimulator = {
+    press(key: string, modifiers?: KeyModifiers): void {
+      const bindingString = toBindingString(key, modifiers)
+      pressedKeys.push(bindingString)
+      onKeyPress?.(key, modifiers ?? {})
+      renderer.emitKey(bindingString)
+    },
+
+    async pressAsync(key: string, modifiers?: KeyModifiers): Promise<void> {
+      this.press(key, modifiers)
+      if (defaultDelay > 0) {
+        await sleep(defaultDelay)
+      }
+    },
+
+    sequence(keys: KeyPress[]): void {
+      for (const keyPress of keys) {
+        this.press(keyPress.key, keyPress.modifiers)
+      }
+      onSequenceComplete?.(keys)
+    },
+
+    async sequenceAsync(keys: KeyPress[]): Promise<void> {
+      for (const keyPress of keys) {
+        const delay = keyPress.delay ?? defaultDelay
+        if (delay > 0) {
+          await sleep(delay)
+        }
+        this.press(keyPress.key, keyPress.modifiers)
+      }
+      onSequenceComplete?.(keys)
+    },
+
+    type(text: string): void {
+      for (const char of text) {
+        // Handle special characters
+        if (char === '\n') {
+          this.press('enter')
+        } else if (char === '\t') {
+          this.press('tab')
+        } else if (char === ' ') {
+          this.press('space')
+        } else {
+          // Check if uppercase (implies shift)
+          const isUpperCase = char === char.toUpperCase() && char !== char.toLowerCase()
+          this.press(char, isUpperCase ? { shift: true } : undefined)
+        }
+      }
+    },
+
+    async typeAsync(text: string, charDelay = 50): Promise<void> {
+      for (const char of text) {
+        if (charDelay > 0) {
+          await sleep(charDelay)
+        }
+        if (char === '\n') {
+          this.press('enter')
+        } else if (char === '\t') {
+          this.press('tab')
+        } else if (char === ' ') {
+          this.press('space')
+        } else {
+          const isUpperCase = char === char.toUpperCase() && char !== char.toLowerCase()
+          this.press(char, isUpperCase ? { shift: true } : undefined)
+        }
+      }
+    },
+
+    reset(): void {
+      this.clearHistory()
+    },
+
+    getPressedKeys(): string[] {
+      return [...pressedKeys]
+    },
+
+    clearHistory(): void {
+      pressedKeys.length = 0
+    },
+  }
+
+  return simulator
+}
+
+// ============================================================================
+// Assertion Helpers
+// ============================================================================
+
+/**
+ * Assert that a specific key was pressed
+ */
+export function expectKeyPressed(
+  simulator: KeyboardSimulator,
+  key: string,
+  modifiers?: KeyModifiers
+): void {
+  const bindingString = toBindingString(key, modifiers)
+  const pressedKeys = simulator.getPressedKeys()
+
+  if (!pressedKeys.includes(bindingString)) {
+    throw new Error(
+      `Expected key "${bindingString}" to be pressed, but it was not. Pressed keys: [${pressedKeys.join(', ')}]`
+    )
+  }
+}
+
+/**
+ * Assert that a sequence of keys was pressed in order
+ */
+export function expectSequencePressed(
+  simulator: KeyboardSimulator,
+  sequence: KeyPress[]
+): void {
+  const pressedKeys = simulator.getPressedKeys()
+  const expectedKeys = sequence.map((kp) => toBindingString(kp.key, kp.modifiers))
+
+  // Find the sequence in pressed keys
+  let found = false
+  for (let i = 0; i <= pressedKeys.length - expectedKeys.length; i++) {
+    let match = true
+    for (let j = 0; j < expectedKeys.length; j++) {
+      if (pressedKeys[i + j] !== expectedKeys[j]) {
+        match = false
+        break
+      }
+    }
+    if (match) {
+      found = true
+      break
+    }
+  }
+
+  if (!found) {
+    throw new Error(
+      `Expected sequence [${expectedKeys.join(', ')}] to be pressed in order, but it was not. Pressed keys: [${pressedKeys.join(', ')}]`
+    )
+  }
+}
+
+/**
+ * Assert that no keys were pressed
+ */
+export function expectNoKeysPressed(simulator: KeyboardSimulator): void {
+  const pressedKeys = simulator.getPressedKeys()
+
+  if (pressedKeys.length > 0) {
+    throw new Error(
+      `Expected no keys to be pressed, but found: [${pressedKeys.join(', ')}]`
+    )
+  }
+}
+
+/**
+ * Assert total number of key presses
+ */
+export function expectKeyPressCount(
+  simulator: KeyboardSimulator,
+  count: number
+): void {
+  const pressedKeys = simulator.getPressedKeys()
+
+  if (pressedKeys.length !== count) {
+    throw new Error(
+      `Expected ${count} key press(es), but found ${pressedKeys.length}. Pressed keys: [${pressedKeys.join(', ')}]`
+    )
+  }
+}
+
+// ============================================================================
+// Browser/DOM Key Event Integration (for Storybook)
+// ============================================================================
+
+/**
+ * Map DOM KeyboardEvent to our key format
+ */
+export function mapDOMKeyEvent(event: KeyboardEvent): KeyPress {
+  // Normalize key names
+  let key = event.key.toLowerCase()
+
+  // Map special keys
+  const keyMap: Record<string, string> = {
+    arrowup: 'up',
+    arrowdown: 'down',
+    arrowleft: 'left',
+    arrowright: 'right',
+    ' ': 'space',
+    return: 'enter',
+  }
+
+  key = keyMap[key] ?? key
+
+  return {
+    key,
+    modifiers: {
+      ctrl: event.ctrlKey,
+      alt: event.altKey,
+      shift: event.shiftKey,
+      meta: event.metaKey,
+    },
+  }
+}
+
+/**
+ * Create a keyboard event handler for DOM events that forwards to simulator
+ */
+export function createDOMKeyHandler(
+  simulator: KeyboardSimulator,
+  options?: {
+    /** Prevent default browser behavior */
+    preventDefault?: boolean
+    /** Stop event propagation */
+    stopPropagation?: boolean
+    /** Keys to ignore (don't forward to simulator) */
+    ignoreKeys?: string[]
+  }
+): (event: KeyboardEvent) => void {
+  const { preventDefault = true, stopPropagation = true, ignoreKeys = [] } = options ?? {}
+
+  return (event: KeyboardEvent) => {
+    const keyPress = mapDOMKeyEvent(event)
+
+    // Check if key should be ignored
+    if (ignoreKeys.includes(keyPress.key)) {
+      return
+    }
+
+    if (preventDefault) {
+      event.preventDefault()
+    }
+
+    if (stopPropagation) {
+      event.stopPropagation()
+    }
+
+    simulator.press(keyPress.key, keyPress.modifiers)
+  }
+}

package/src/theme/ansi-codes.ts

@@ -0,0 +1,80 @@
+/**
+ * ANSI Escape Code Constants
+ *
+ * Standard ANSI escape sequences for terminal text styling.
+ * These codes work in all terminals that support ANSI escape codes.
+ *
+ * @module
+ */
+
+/**
+ * ANSI escape code constants for terminal styling.
+ *
+ * Includes:
+ * - Reset code to clear all styles
+ * - Text styling (bold, dim, italic, underline, strikethrough)
+ * - Standard 8 foreground colors (black through white)
+ * - Bright variants of all 8 foreground colors
+ * - Standard 8 background colors
+ *
+ * @example
+ * ```tsx
+ * // Apply bold cyan text
+ * console.log(`${ANSI.bold}${ANSI.cyan}Hello${ANSI.reset}`)
+ *
+ * // Use with styled helper
+ * console.log(styled('Error!', ANSI.bold, ANSI.red))
+ * ```
+ */
+export const ANSI = {
+  // Reset
+  reset: '\x1b[0m',
+
+  // Styles
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  italic: '\x1b[3m',
+  underline: '\x1b[4m',
+  inverse: '\x1b[7m',
+  strikethrough: '\x1b[9m',
+
+  // Foreground colors (basic)
+  black: '\x1b[30m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+
+  // Bright foreground colors
+  brightBlack: '\x1b[90m',
+  brightRed: '\x1b[91m',
+  brightGreen: '\x1b[92m',
+  brightYellow: '\x1b[93m',
+  brightBlue: '\x1b[94m',
+  brightMagenta: '\x1b[95m',
+  brightCyan: '\x1b[96m',
+  brightWhite: '\x1b[97m',
+
+  // Background colors
+  bgBlack: '\x1b[40m',
+  bgRed: '\x1b[41m',
+  bgGreen: '\x1b[42m',
+  bgYellow: '\x1b[43m',
+  bgBlue: '\x1b[44m',
+  bgMagenta: '\x1b[45m',
+  bgCyan: '\x1b[46m',
+  bgWhite: '\x1b[47m',
+
+  // Bright background colors
+  bgBrightBlack: '\x1b[100m',
+  bgBrightRed: '\x1b[101m',
+  bgBrightGreen: '\x1b[102m',
+  bgBrightYellow: '\x1b[103m',
+  bgBrightBlue: '\x1b[104m',
+  bgBrightMagenta: '\x1b[105m',
+  bgBrightCyan: '\x1b[106m',
+  bgBrightWhite: '\x1b[107m',
+} as const

package/src/theme/box-drawing.ts

@@ -0,0 +1,132 @@
+/**
+ * Box Drawing Characters
+ *
+ * Unicode box-drawing character sets for terminal UI borders
+ * and utility functions for drawing boxes.
+ *
+ * @module
+ */
+
+/**
+ * Unicode box-drawing character sets for terminal UI borders.
+ *
+ * Provides three styles:
+ * - `single` - Standard single-line borders (┌─┐│└┘)
+ * - `double` - Double-line borders (╔═╗║╚╝)
+ * - `rounded` - Single-line with rounded corners (╭─╮│╰╯)
+ *
+ * Each set includes:
+ * - Corner characters (topLeft, topRight, bottomLeft, bottomRight)
+ * - Line characters (horizontal, vertical)
+ * - T-junction characters (teeLeft, teeRight, teeTop, teeBottom)
+ * - Cross character (cross)
+ *
+ * @example
+ * ```tsx
+ * const chars = boxChars.single
+ * const top = chars.topLeft + chars.horizontal.repeat(10) + chars.topRight
+ * // Outputs: ┌──────────┐
+ * ```
+ */
+export const boxChars = {
+  single: {
+    topLeft: '┌',
+    topRight: '┐',
+    bottomLeft: '└',
+    bottomRight: '┘',
+    horizontal: '─',
+    vertical: '│',
+    teeLeft: '├',
+    teeRight: '┤',
+    teeTop: '┬',
+    teeBottom: '┴',
+    cross: '┼',
+  },
+  double: {
+    topLeft: '╔',
+    topRight: '╗',
+    bottomLeft: '╚',
+    bottomRight: '╝',
+    horizontal: '═',
+    vertical: '║',
+    teeLeft: '╠',
+    teeRight: '╣',
+    teeTop: '╦',
+    teeBottom: '╩',
+    cross: '╬',
+  },
+  rounded: {
+    topLeft: '╭',
+    topRight: '╮',
+    bottomLeft: '╰',
+    bottomRight: '╯',
+    horizontal: '─',
+    vertical: '│',
+    teeLeft: '├',
+    teeRight: '┤',
+    teeTop: '┬',
+    teeBottom: '┴',
+    cross: '┼',
+  },
+} as const
+
+/**
+ * Available box drawing styles.
+ * - `'single'` - Standard single-line borders
+ * - `'double'` - Double-line borders
+ * - `'rounded'` - Single-line with rounded corners
+ */
+export type BoxStyle = keyof typeof boxChars
+
+/**
+ * Draws a box with specified style and dimensions.
+ *
+ * Creates an array of strings representing each line of the box.
+ * The box is hollow (empty inside) and can be used as a container
+ * for content in terminal UIs.
+ *
+ * @param width - Total width of the box including borders
+ * @param height - Total height of the box including borders
+ * @param style - Box style ('single', 'double', or 'rounded')
+ * @returns Array of strings, one per line of the box
+ *
+ * @example
+ * ```tsx
+ * const box = drawBox(20, 5, 'rounded')
+ * box.forEach(line => console.log(line))
+ * // ╭──────────────────╮
+ * // │                  │
+ * // │                  │
+ * // │                  │
+ * // ╰──────────────────╯
+ * ```
+ */
+export function drawBox(
+  width: number,
+  height: number,
+  style: BoxStyle = 'single'
+): string[] {
+  // Handle edge cases for dimensions
+  if (width < 2) width = 2
+  if (height < 2) height = 2
+
+  // Ensure integers
+  width = Math.floor(width)
+  height = Math.floor(height)
+
+  const chars = boxChars[style]
+  const lines: string[] = []
+
+  // Top border
+  lines.push(chars.topLeft + chars.horizontal.repeat(Math.max(0, width - 2)) + chars.topRight)
+
+  // Middle rows
+  for (let i = 0; i < height - 2; i++) {
+    lines.push(chars.vertical + ' '.repeat(Math.max(0, width - 2)) + chars.vertical)
+  }
+
+  // Bottom border
+  lines.push(chars.bottomLeft + chars.horizontal.repeat(Math.max(0, width - 2)) + chars.bottomRight)
+
+  return lines
+}