@mdxui/terminal 2.0.0

package/src/keyboard/manager.ts

@@ -0,0 +1,377 @@
+/**
+ * Keyboard Manager
+ *
+ * Core keyboard binding manager for handling key bindings and sequences.
+ * Supports single keys, modifier combinations, and multi-key sequences.
+ *
+ * @packageDocumentation
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Modifier key state for a key press event.
+ *
+ * Tracks which modifier keys are held during a key press.
+ */
+export interface KeyModifiers {
+  /** Control key is pressed */
+  ctrl: boolean
+  /** Alt/Option key is pressed */
+  alt: boolean
+  /** Shift key is pressed */
+  shift: boolean
+  /** Meta/Command key is pressed */
+  meta: boolean
+}
+
+/**
+ * A keyboard action - either a string action name or a callback function.
+ *
+ * String actions are dispatched via the onAction handler.
+ * Function actions are called directly when the key is pressed.
+ */
+export type KeyboardAction = string | (() => void)
+
+/**
+ * Maps key names/sequences to actions.
+ *
+ * Keys can be:
+ * - Single characters: 'j', 'k', 'q'
+ * - Special keys: 'enter', 'escape', 'tab'
+ * - Modifier combinations: 'ctrl+c', 'shift+tab'
+ * - Key sequences: 'gg', 'dd' (multi-character without '+')
+ */
+export type KeyBindings = Record<string, KeyboardAction>
+
+/**
+ * Context passed to action handlers with the triggering key and optional extra data.
+ */
+export interface ActionContext {
+  /** The key or sequence that triggered this action */
+  key: string
+  /** Optional context data set via setContext() */
+  context?: Record<string, unknown>
+}
+
+/**
+ * Callback invoked when a keyboard action is triggered.
+ *
+ * @param action - The action name (string actions only)
+ * @param context - Context including the key and optional data
+ */
+export type ActionHandler = (action: string, context: ActionContext) => void
+
+/**
+ * Configuration options for creating a keyboard manager.
+ */
+export interface KeyboardManagerOptions {
+  /** Key-to-action bindings */
+  bindings: KeyBindings
+  /** Handler called when string actions are triggered */
+  onAction?: ActionHandler
+  /** Whether the manager starts enabled (default: true) */
+  enabled?: boolean
+  /** Optional context data passed to action handlers */
+  context?: Record<string, unknown> | null
+  /** Timeout in ms for key sequences (default: 1000) */
+  sequenceTimeout?: number
+}
+
+/**
+ * Interface for the keyboard manager returned by createKeyboardManager.
+ */
+export interface KeyboardManager {
+  /** Get the action bound to a specific key */
+  getAction(key: string): KeyboardAction | undefined
+  /** Handle a key press, returns true if the key was handled */
+  handleKey(key: string, handler?: ActionHandler): boolean
+  /** Add a new key binding */
+  addBinding(key: string, action: KeyboardAction): void
+  /** Remove a key binding */
+  removeBinding(key: string): void
+  /** Replace all bindings */
+  setBindings(bindings: KeyBindings): void
+  /** Get all string bindings (excludes function bindings) */
+  getBindings(): Record<string, string>
+  /** Disable the keyboard manager */
+  disable(): void
+  /** Enable the keyboard manager */
+  enable(): void
+  /** Toggle enabled state */
+  toggle(): void
+  /** Check if the manager is enabled */
+  isEnabled(): boolean
+  /** Get the current pending key sequence */
+  getPendingSequence(): string
+  /** Set context data passed to action handlers */
+  setContext(context: Record<string, unknown>): void
+  /** Clean up resources (clears pending sequence timer to prevent memory leaks) */
+  destroy(): void
+}
+
+// ============================================================================
+// KEY Constants
+// ============================================================================
+
+/**
+ * Common key constants for keyboard handling.
+ * Use these with matchKey() for consistent key comparisons.
+ */
+export const KEY = {
+  ENTER: 'enter',
+  ESCAPE: 'escape',
+  UP: 'up',
+  DOWN: 'down',
+  LEFT: 'left',
+  RIGHT: 'right',
+  TAB: 'tab',
+  SPACE: 'space',
+  BACKSPACE: 'backspace',
+  DELETE: 'delete',
+} as const
+
+/**
+ * Check if a key matches an expected key.
+ *
+ * @param key - The key to check
+ * @param expected - The expected key value
+ * @returns true if keys match
+ *
+ * @example
+ * ```tsx
+ * import { matchKey, KEY } from '@mdxui/terminal'
+ *
+ * if (matchKey(pressedKey, KEY.ENTER)) {
+ *   handleSubmit()
+ * }
+ * ```
+ */
+export function matchKey(key: string, expected: string): boolean {
+  return key === expected
+}
+
+// ============================================================================
+// createKeyboardManager
+// ============================================================================
+
+/**
+ * Creates a keyboard manager for handling key bindings and sequences.
+ *
+ * The manager supports:
+ * - Single key bindings ('j', 'enter', 'q')
+ * - Modifier combinations ('ctrl+c', 'shift+tab')
+ * - Multi-key sequences ('gg', 'dd') with configurable timeout
+ * - Dynamic binding changes at runtime
+ * - Enable/disable toggling
+ *
+ * @param options - Configuration options
+ * @returns A keyboard manager instance
+ *
+ * @example
+ * ```tsx
+ * const keyboard = createKeyboardManager({
+ *   bindings: { ...VIM_BINDINGS, ...ARROW_BINDINGS },
+ *   onAction: (action, ctx) => {
+ *     switch (action) {
+ *       case 'move-down': moveDown(); break
+ *       case 'select': handleSelect(); break
+ *     }
+ *   }
+ * })
+ *
+ * // Later, handle input
+ * process.stdin.on('keypress', (ch, key) => {
+ *   keyboard.handleKey(key.name || ch)
+ * })
+ * ```
+ */
+export function createKeyboardManager(options: KeyboardManagerOptions): KeyboardManager {
+  let bindings = { ...options.bindings }
+  let enabled = options.enabled !== false
+  let context: Record<string, unknown> | null = options.context ?? null
+  const onAction = options.onAction
+  const sequenceTimeout = options.sequenceTimeout ?? 1000
+
+  // Track pending key sequence for multi-key bindings like 'gg'
+  let pendingSequence = ''
+  let sequenceTimer: ReturnType<typeof setTimeout> | null = null
+
+  // Find all multi-key bindings (sequences)
+  function getSequenceBindings(): string[] {
+    return Object.keys(bindings).filter((key) => key.length > 1 && !key.includes('+'))
+  }
+
+  // Check if a key could start a sequence
+  function startsSequence(key: string): boolean {
+    const sequences = getSequenceBindings()
+    return sequences.some((seq) => seq.startsWith(key))
+  }
+
+  // Check if a key could continue the pending sequence
+  function continuesSequence(key: string): boolean {
+    if (!pendingSequence) return false
+    const potential = pendingSequence + key
+    const sequences = getSequenceBindings()
+    return sequences.some((seq) => seq.startsWith(potential))
+  }
+
+  function clearSequence(): void {
+    pendingSequence = ''
+    if (sequenceTimer) {
+      clearTimeout(sequenceTimer)
+      sequenceTimer = null
+    }
+  }
+
+  function buildActionContext(key: string): ActionContext {
+    const actionContext: ActionContext = { key }
+    if (context !== null) {
+      actionContext.context = context
+    }
+    return actionContext
+  }
+
+  function handleSequenceTimeout(): void {
+    // When sequence times out, try to execute the pending sequence as-is
+    if (pendingSequence && bindings[pendingSequence]) {
+      const action = bindings[pendingSequence]
+      if (typeof action === 'function') {
+        action()
+      } else if (onAction) {
+        onAction(action, buildActionContext(pendingSequence))
+      }
+    }
+    clearSequence()
+  }
+
+  const manager: KeyboardManager = {
+    getAction(key: string): KeyboardAction | undefined {
+      return bindings[key]
+    },
+
+    handleKey(key: string, handler?: ActionHandler): boolean {
+      if (!enabled) return false
+
+      // Handle escape - clears pending sequence
+      if (key === 'escape') {
+        if (pendingSequence) {
+          clearSequence()
+          // Don't trigger escape action if we just cleared a sequence
+          return true
+        }
+        // Fall through to normal handling if no pending sequence
+      }
+
+      // Check if this key could be part of a sequence
+      const potentialSequence = pendingSequence + key
+
+      // Check if the potential sequence matches a binding
+      if (bindings[potentialSequence]) {
+        clearSequence()
+        const action = bindings[potentialSequence]
+        if (typeof action === 'function') {
+          action()
+        } else {
+          const effectiveHandler = handler || onAction
+          if (effectiveHandler) {
+            effectiveHandler(action, buildActionContext(potentialSequence))
+          }
+        }
+        return true
+      }
+
+      // Check if this could continue or start a sequence
+      if (continuesSequence(key) || (!pendingSequence && startsSequence(key))) {
+        pendingSequence = potentialSequence
+
+        // Set timeout to execute fallback or clear sequence
+        if (sequenceTimer) clearTimeout(sequenceTimer)
+        sequenceTimer = setTimeout(handleSequenceTimeout, sequenceTimeout)
+
+        return true
+      }
+
+      // Not a sequence - check for direct binding
+      if (pendingSequence) {
+        // Had a pending sequence but this key doesn't continue it
+        // Clear and don't handle
+        clearSequence()
+      }
+
+      const action = bindings[key]
+      if (action === undefined) {
+        return false
+      }
+
+      if (typeof action === 'function') {
+        action()
+      } else {
+        const effectiveHandler = handler || onAction
+        if (effectiveHandler) {
+          effectiveHandler(action, buildActionContext(key))
+        }
+      }
+
+      return true
+    },
+
+    addBinding(key: string, action: KeyboardAction): void {
+      bindings[key] = action
+    },
+
+    removeBinding(key: string): void {
+      delete bindings[key]
+    },
+
+    setBindings(newBindings: KeyBindings): void {
+      bindings = { ...newBindings }
+    },
+
+    getBindings(): Record<string, string> {
+      const result: Record<string, string> = {}
+      for (const [key, action] of Object.entries(bindings)) {
+        if (typeof action === 'string') {
+          result[key] = action
+        }
+      }
+      return result
+    },
+
+    disable(): void {
+      enabled = false
+    },
+
+    enable(): void {
+      enabled = true
+    },
+
+    toggle(): void {
+      enabled = !enabled
+    },
+
+    isEnabled(): boolean {
+      return enabled
+    },
+
+    getPendingSequence(): string {
+      return pendingSequence
+    },
+
+    setContext(newContext: Record<string, unknown>): void {
+      context = newContext
+    },
+
+    destroy(): void {
+      if (sequenceTimer) {
+        clearTimeout(sequenceTimer)
+        sequenceTimer = null
+      }
+      pendingSequence = ''
+    },
+  }
+
+  return manager
+}

package/src/keyboard/presets.ts

@@ -0,0 +1,90 @@
+/**
+ * Preset Key Bindings
+ *
+ * Common keyboard binding presets for terminal applications.
+ * Includes Vim-style, arrow key, and common UI bindings.
+ *
+ * @packageDocumentation
+ */
+
+import type { KeyBindings } from './manager'
+
+/**
+ * Vim-style navigation bindings.
+ *
+ * Includes:
+ * - h/j/k/l for directional movement
+ * - gg/G for first/last
+ * - / and : for search/command
+ * - i for insert mode
+ * - enter/escape/q for select/back/quit
+ *
+ * @example
+ * ```tsx
+ * const keyboard = createKeyboardManager({
+ *   bindings: VIM_BINDINGS,
+ *   onAction: handleAction
+ * })
+ * ```
+ */
+export const VIM_BINDINGS: KeyBindings = {
+  h: 'move-left',
+  j: 'move-down',
+  k: 'move-up',
+  l: 'move-right',
+  gg: 'move-first',
+  G: 'move-last',
+  '/': 'search',
+  ':': 'command',
+  i: 'insert',
+  enter: 'select',
+  escape: 'back',
+  q: 'quit',
+}
+
+/**
+ * Arrow key navigation bindings.
+ *
+ * Maps arrow keys to directional movement actions.
+ */
+export const ARROW_BINDINGS: KeyBindings = {
+  up: 'move-up',
+  down: 'move-down',
+  left: 'move-left',
+  right: 'move-right',
+}
+
+/**
+ * Common UI bindings for Enter, Escape, Tab, and Space.
+ *
+ * Maps common interaction keys to semantic actions:
+ * - enter: 'select'
+ * - escape: 'back'
+ * - tab/shift+tab: focus navigation
+ * - space: 'toggle'
+ */
+export const COMMON_BINDINGS: KeyBindings = {
+  enter: 'select',
+  escape: 'back',
+  tab: 'focus-next',
+  'shift+tab': 'focus-prev',
+  space: 'toggle',
+}
+
+/**
+ * Emacs-style navigation bindings.
+ *
+ * Includes:
+ * - ctrl+f/b/n/p for forward/back/next/previous
+ * - ctrl+a/e for start/end of line
+ * - ctrl+g for cancel
+ */
+export const EMACS_BINDINGS: KeyBindings = {
+  'ctrl+f': 'move-right',
+  'ctrl+b': 'move-left',
+  'ctrl+n': 'move-down',
+  'ctrl+p': 'move-up',
+  'ctrl+a': 'move-first',
+  'ctrl+e': 'move-last',
+  'ctrl+g': 'back',
+}