@mdxui/terminal 2.0.0

package/src/keyboard/index.ts

@@ -0,0 +1,96 @@
+/**
+ * @mdxui/terminal Keyboard Navigation
+ *
+ * Keyboard binding manager and React hooks for terminal keyboard navigation.
+ * Supports Vim-style bindings, modifier keys, and key sequences.
+ *
+ * This module provides:
+ * - Keyboard manager for handling key bindings and sequences
+ * - React hooks for keyboard input, focus management, and navigation
+ * - Preset bindings for Vim-style and arrow key navigation
+ * - Focus provider for managing focus across components
+ *
+ * @example
+ * ```tsx
+ * import { createKeyboardManager, VIM_BINDINGS, useFocus } from '@mdxui/terminal'
+ *
+ * // Create a keyboard manager with Vim bindings
+ * const keyboard = createKeyboardManager({
+ *   bindings: VIM_BINDINGS,
+ *   onAction: (action) => console.log('Action:', action)
+ * })
+ *
+ * // Handle key presses
+ * keyboard.handleKey('j') // triggers 'move-down'
+ * keyboard.handleKey('g')
+ * keyboard.handleKey('g') // triggers 'move-first' (sequence: gg)
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// Manager exports
+export {
+  // Types
+  type KeyModifiers,
+  type KeyboardAction,
+  type KeyBindings,
+  type ActionContext,
+  type ActionHandler,
+  type KeyboardManagerOptions,
+  type KeyboardManager,
+  // Constants
+  KEY,
+  // Functions
+  matchKey,
+  createKeyboardManager,
+} from './manager'
+
+// Preset exports
+export {
+  VIM_BINDINGS,
+  ARROW_BINDINGS,
+  COMMON_BINDINGS,
+  EMACS_BINDINGS,
+} from './presets'
+
+// Focus exports
+export {
+  // Types
+  type UseKeyboardOptions,
+  type UseKeyboardResult,
+  type UseFocusOptions,
+  type FocusableElement,
+  type FocusManagerState,
+  type UseNavigableListOptions,
+  type UseNavigableListResult,
+  type UseNavigableGridOptions,
+  type UseNavigableGridResult,
+  type FocusProviderProps,
+  // Context
+  FocusContext,
+  // Hooks
+  useKeyboard,
+  useFocus,
+  useFocusManager,
+  useNavigableList,
+  useNavigableGrid,
+  // Components
+  FocusProvider,
+} from './focus'
+
+// Integration exports
+export {
+  // Types
+  type NormalizedKey,
+  type ReadlineKey,
+  type AttachKeyboardOptions,
+  type DetachKeyboard,
+  type OpenTUIKeyEvent,
+  // Functions
+  normalizeReadlineKey,
+  keyToBindingString,
+  attachKeyboardManager,
+  normalizeOpenTUIKey,
+  createOpenTUIKeyHandler,
+} from './integration'

package/src/keyboard/integration.ts

@@ -0,0 +1,371 @@
+/**
+ * Terminal Input Integration
+ *
+ * Integration helpers for connecting keyboard managers to terminal input sources.
+ * Supports Node.js readline and OpenTUI key events.
+ *
+ * @packageDocumentation
+ */
+
+import type { KeyboardManager, ActionHandler } from './manager'
+
+// ============================================================================
+// Normalized Key Types
+// ============================================================================
+
+/**
+ * Normalized key event structure for keyboard handling.
+ *
+ * This is the standardized format used internally by the keyboard manager.
+ * Input from various sources (readline, OpenTUI) is normalized to this format.
+ */
+export interface NormalizedKey {
+  /** The key name (e.g., 'a', 'enter', 'up', 'escape') */
+  name: string
+  /** Whether Ctrl was held */
+  ctrl: boolean
+  /** Whether Alt/Option was held */
+  alt: boolean
+  /** Whether Shift was held */
+  shift: boolean
+  /** Whether Meta/Cmd was held */
+  meta: boolean
+  /** Raw character sequence if available */
+  sequence?: string
+}
+
+/**
+ * Readline key event structure from Node.js readline module.
+ * @see https://nodejs.org/api/readline.html#event-keypress
+ */
+export interface ReadlineKey {
+  /** Key name */
+  name?: string
+  /** Whether Ctrl was held */
+  ctrl?: boolean
+  /** Whether Meta/Cmd was held */
+  meta?: boolean
+  /** Whether Shift was held */
+  shift?: boolean
+  /** Raw sequence */
+  sequence?: string
+}
+
+// ============================================================================
+// Readline Integration
+// ============================================================================
+
+/**
+ * Normalizes a readline key event to our standard NormalizedKey format.
+ *
+ * @param str - The character string from the keypress event
+ * @param key - The readline key object
+ * @returns Normalized key event
+ *
+ * @example
+ * ```typescript
+ * import { emitKeypressEvents } from 'readline'
+ *
+ * emitKeypressEvents(process.stdin)
+ * process.stdin.on('keypress', (str, key) => {
+ *   const normalized = normalizeReadlineKey(str, key)
+ *   console.log(normalized) // { name: 'a', ctrl: false, ... }
+ * })
+ * ```
+ */
+export function normalizeReadlineKey(str: string | undefined, key: ReadlineKey | undefined): NormalizedKey {
+  // Handle special characters by their sequence
+  if (!key && str) {
+    // Single character input
+    return {
+      name: str,
+      ctrl: false,
+      alt: false,
+      shift: str !== str.toLowerCase() && str === str.toUpperCase(),
+      meta: false,
+      sequence: str,
+    }
+  }
+
+  // Map readline key names to our standard names
+  const nameMap: Record<string, string> = {
+    return: 'enter',
+    escape: 'escape',
+    up: 'up',
+    down: 'down',
+    left: 'left',
+    right: 'right',
+    tab: 'tab',
+    backspace: 'backspace',
+    delete: 'delete',
+    space: 'space',
+  }
+
+  const keyName = key?.name ?? str ?? ''
+  const normalizedName = nameMap[keyName.toLowerCase()] ?? keyName.toLowerCase()
+
+  return {
+    name: normalizedName,
+    ctrl: key?.ctrl ?? false,
+    alt: false, // readline doesn't distinguish alt reliably
+    shift: key?.shift ?? false,
+    meta: key?.meta ?? false,
+    sequence: key?.sequence ?? str,
+  }
+}
+
+/**
+ * Converts a NormalizedKey to a string format for binding lookup.
+ *
+ * Produces strings like:
+ * - 'a' (plain key)
+ * - 'ctrl+c' (with ctrl modifier)
+ * - 'shift+tab' (with shift modifier)
+ * - 'ctrl+shift+s' (combined modifiers)
+ *
+ * @param key - The normalized key event
+ * @returns String representation for binding lookup
+ *
+ * @example
+ * ```typescript
+ * const key: NormalizedKey = { name: 'c', ctrl: true, alt: false, shift: false, meta: false }
+ * console.log(keyToBindingString(key)) // 'ctrl+c'
+ * ```
+ */
+export function keyToBindingString(key: NormalizedKey): string {
+  const modifiers: string[] = []
+
+  if (key.ctrl) modifiers.push('ctrl')
+  if (key.alt) modifiers.push('alt')
+  if (key.shift) modifiers.push('shift')
+  if (key.meta) modifiers.push('meta')
+
+  if (modifiers.length > 0) {
+    return `${modifiers.join('+')}+${key.name}`
+  }
+
+  return key.name
+}
+
+/**
+ * Configuration for attaching a keyboard manager to terminal input.
+ */
+export interface AttachKeyboardOptions {
+  /** Custom input stream (defaults to process.stdin) */
+  input?: NodeJS.ReadStream
+  /** Whether to exit on Ctrl+C (defaults to true) */
+  exitOnCtrlC?: boolean
+}
+
+/**
+ * Cleanup function returned by attachKeyboardManager.
+ * Call this to detach the keyboard manager from input.
+ */
+export type DetachKeyboard = () => void
+
+/**
+ * Attaches a keyboard manager to terminal stdin for receiving key events.
+ *
+ * This function sets up raw mode on stdin and processes keypress events,
+ * normalizing them and passing them to the keyboard manager.
+ *
+ * **Important:** This function requires a TTY stdin. It will throw if
+ * stdin is not a TTY (e.g., when input is piped).
+ *
+ * @param manager - The keyboard manager to receive key events
+ * @param options - Configuration options
+ * @returns A cleanup function to detach the keyboard manager
+ *
+ * @example
+ * ```typescript
+ * import { createKeyboardManager, attachKeyboardManager, VIM_BINDINGS } from '@mdxui/terminal'
+ *
+ * const manager = createKeyboardManager({
+ *   bindings: VIM_BINDINGS,
+ *   onAction: (action) => console.log('Action:', action),
+ * })
+ *
+ * const detach = attachKeyboardManager(manager)
+ *
+ * // Later, to clean up:
+ * detach()
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom options
+ * const detach = attachKeyboardManager(manager, {
+ *   exitOnCtrlC: false, // Don't exit on Ctrl+C, let manager handle it
+ * })
+ * ```
+ */
+export function attachKeyboardManager(
+  manager: KeyboardManager,
+  options: AttachKeyboardOptions = {}
+): DetachKeyboard {
+  const { input = process.stdin, exitOnCtrlC = true } = options
+
+  // Check if we have a TTY
+  if (!input.isTTY) {
+    throw new Error('attachKeyboardManager requires a TTY stdin. Cannot attach to non-TTY input.')
+  }
+
+  // Dynamic import readline to emit keypress events
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const readline = require('readline')
+  readline.emitKeypressEvents(input)
+
+  // Store original raw mode state
+  const wasRaw = input.isRaw
+
+  // Enable raw mode to receive individual keypresses
+  input.setRawMode(true)
+
+  // Keypress handler
+  const handleKeypress = (str: string | undefined, key: ReadlineKey | undefined) => {
+    // Handle Ctrl+C exit if enabled
+    if (exitOnCtrlC && key?.ctrl && key?.name === 'c') {
+      // Restore terminal state before exiting
+      input.setRawMode(wasRaw ?? false)
+      process.exit(0)
+    }
+
+    // Normalize the key event
+    const normalized = normalizeReadlineKey(str, key)
+
+    // Convert to binding string format
+    const bindingKey = keyToBindingString(normalized)
+
+    // Pass to manager
+    manager.handleKey(bindingKey)
+  }
+
+  // Attach the handler
+  input.on('keypress', handleKeypress)
+
+  // Resume stdin (required when raw mode is enabled)
+  input.resume()
+
+  // Return cleanup function
+  return () => {
+    input.off('keypress', handleKeypress)
+    input.setRawMode(wasRaw ?? false)
+    // Note: We don't pause stdin as other handlers may still need it
+  }
+}
+
+// ============================================================================
+// OpenTUI Integration
+// ============================================================================
+
+/**
+ * OpenTUI key event structure.
+ * Matches the KeyEvent interface from @opentui/core.
+ */
+export interface OpenTUIKeyEvent {
+  /** Key name (e.g., 'a', 'enter', 'escape') */
+  name: string
+  /** Ctrl modifier */
+  ctrl: boolean
+  /** Meta/Cmd modifier */
+  meta: boolean
+  /** Shift modifier */
+  shift: boolean
+  /** Option/Alt modifier */
+  option: boolean
+  /** Raw sequence */
+  sequence: string
+  /** Event type: 'press', 'repeat', or 'release' */
+  eventType?: 'press' | 'repeat' | 'release'
+  /** Whether this is a repeated key */
+  repeated?: boolean
+}
+
+/**
+ * Normalizes an OpenTUI KeyEvent to our standard NormalizedKey format.
+ *
+ * @param event - The OpenTUI KeyEvent
+ * @returns Normalized key event
+ *
+ * @example
+ * ```typescript
+ * import { useKeyboard } from '@opentui/react'
+ *
+ * useKeyboard((event) => {
+ *   const normalized = normalizeOpenTUIKey(event)
+ *   manager.handleKey(keyToBindingString(normalized))
+ * })
+ * ```
+ */
+export function normalizeOpenTUIKey(event: OpenTUIKeyEvent): NormalizedKey {
+  // Map OpenTUI key names to our standard names
+  const nameMap: Record<string, string> = {
+    return: 'enter',
+    escape: 'escape',
+    up: 'up',
+    down: 'down',
+    left: 'left',
+    right: 'right',
+    tab: 'tab',
+    backspace: 'backspace',
+    delete: 'delete',
+    space: 'space',
+  }
+
+  const normalizedName = nameMap[event.name.toLowerCase()] ?? event.name.toLowerCase()
+
+  return {
+    name: normalizedName,
+    ctrl: event.ctrl,
+    alt: event.option, // OpenTUI uses 'option' for Alt
+    shift: event.shift,
+    meta: event.meta,
+    sequence: event.sequence,
+  }
+}
+
+/**
+ * Creates a keyboard event handler for use with OpenTUI's useKeyboard hook.
+ *
+ * This function returns a handler that can be passed directly to OpenTUI's
+ * useKeyboard hook to connect it to a KeyboardManager.
+ *
+ * @param manager - The keyboard manager to receive key events
+ * @returns A handler function for OpenTUI's useKeyboard hook
+ *
+ * @example
+ * ```tsx
+ * import { useKeyboard } from '@opentui/react'
+ * import { createKeyboardManager, createOpenTUIKeyHandler, VIM_BINDINGS } from '@mdxui/terminal'
+ *
+ * function MyComponent() {
+ *   const manager = useMemo(() => createKeyboardManager({
+ *     bindings: VIM_BINDINGS,
+ *     onAction: (action) => console.log('Action:', action),
+ *   }), [])
+ *
+ *   const handler = useMemo(() => createOpenTUIKeyHandler(manager), [manager])
+ *
+ *   useKeyboard(handler)
+ *
+ *   return <div>...</div>
+ * }
+ * ```
+ */
+export function createOpenTUIKeyHandler(manager: KeyboardManager): (event: OpenTUIKeyEvent) => void {
+  return (event: OpenTUIKeyEvent) => {
+    // Skip release events - only handle press/repeat
+    if (event.eventType === 'release') {
+      return
+    }
+
+    // Normalize the key event
+    const normalized = normalizeOpenTUIKey(event)
+
+    // Convert to binding string format
+    const bindingKey = keyToBindingString(normalized)
+
+    // Pass to manager
+    manager.handleKey(bindingKey)
+  }
+}