@mdxui/terminal 2.0.0

package/src/renderers/interactive/index.ts

@@ -0,0 +1,661 @@
+/**
+ * @mdxui/terminal Interactive Renderer
+ *
+ * The Interactive renderer is the highest-capability tier providing:
+ * - Full TUI with keyboard navigation
+ * - Focus management and Tab cycling
+ * - Mouse click support
+ * - Cursor positioning
+ * - Real-time updates
+ * - Input field handling
+ * - Component state management
+ *
+ * @packageDocumentation
+ */
+
+// NOTE: @opentui/core is imported dynamically inside createInteractiveRenderer()
+// to avoid loading .scm files when only the string-based renderer is needed
+
+// Re-export types
+export type {
+  InteractiveRendererConfig,
+  FocusableOptions,
+  ClickableOptions,
+  InputOptions,
+  ComponentOptions,
+  InteractiveRenderer,
+  UINode,
+  // Internal types for advanced usage
+  FocusableEntry,
+  FocusTrapEntry,
+  KeyHandler,
+  InputState,
+  FocusManagerState,
+  KeyboardManagerState,
+  CursorManagerState,
+  StateManagerState,
+  MouseManagerState,
+  InputManagerState,
+  ComponentManagerState,
+} from './types'
+
+// Import manager creators and functions
+import {
+  createFocusManagerState,
+  getSortedFocusableIds,
+  getCurrentFocusIndex,
+  focusNext as focusNextFn,
+  focusPrev as focusPrevFn,
+  focusById as focusByIdFn,
+  getFocusedId as getFocusedIdFn,
+  getFocusableIds as getFocusableIdsFn,
+  registerFocusable as registerFocusableFn,
+  unregisterFocusable as unregisterFocusableFn,
+  setActiveGroup as setActiveGroupFn,
+  pushFocusTrap as pushFocusTrapFn,
+  popFocusTrap as popFocusTrapFn,
+} from './focus-manager'
+
+import {
+  createKeyboardManagerState,
+  onKeyPress as onKeyPressFn,
+  offKeyPress as offKeyPressFn,
+  emitKey as emitKeyFn,
+  onKeySequence as onKeySequenceFn,
+  getPendingSequence as getPendingSequenceFn,
+  onSearchMode as onSearchModeFn,
+  onCancel as onCancelFn,
+  getMode as getModeFn,
+  clearKeyboardState,
+} from './keyboard-handler'
+
+import {
+  createCursorManagerState,
+  setCursorPosition as setCursorPositionFn,
+  getCursorPosition as getCursorPositionFn,
+  showCursor as showCursorFn,
+  hideCursor as hideCursorFn,
+  isCursorVisible as isCursorVisibleFn,
+  setCursorStyle as setCursorStyleFn,
+  getCursorStyle as getCursorStyleFn,
+  setCursorBlink as setCursorBlinkFn,
+  isCursorBlinking as isCursorBlinkingFn,
+  updateCursorPosition as updateCursorPositionFn,
+} from './cursor-manager'
+
+import {
+  createStateManagerState,
+  setState as setStateFn,
+  getState as getStateFn,
+  subscribe as subscribeFn,
+  onRender as onRenderFn,
+  getTargetFps as getTargetFpsFn,
+  clearStateManager,
+} from './state-manager'
+
+import {
+  createMouseManagerState,
+  onClick as onClickFn,
+  offClick as offClickFn,
+  emitClick as emitClickFn,
+  registerClickable as registerClickableFn,
+  unregisterClickable as unregisterClickableFn,
+  getClickableAreas as getClickableAreasFn,
+  onScroll as onScrollFn,
+  emitScroll as emitScrollFn,
+  clearMouseState,
+} from './mouse-handler'
+
+import {
+  createInputManagerState,
+  registerInput as registerInputFn,
+  getInputCursorIndex as getInputCursorIndexFn,
+  clearInputState,
+} from './input-handler'
+
+import {
+  createComponentManagerState,
+  registerComponent as registerComponentFn,
+  unregisterComponent as unregisterComponentFn,
+  getComponent as getComponentFn,
+  updateComponent as updateComponentFn,
+  handleComponentKey,
+  clearComponentState,
+} from './component-handlers'
+
+import type {
+  InteractiveRendererConfig,
+  InteractiveRenderer,
+  FocusableOptions,
+  ClickableOptions,
+  InputOptions,
+  ComponentOptions,
+} from './types'
+
+// Re-export registerInteractiveNode
+export { registerInteractiveNode } from './component-handlers'
+
+/**
+ * Creates an interactive renderer instance.
+ */
+export async function createInteractiveRenderer(
+  config?: InteractiveRendererConfig
+): Promise<InteractiveRenderer> {
+  // Dynamic import to avoid .scm file loading at module load time
+  const { createCliRenderer } = await import('@opentui/core')
+  // Get base renderer from @opentui/core
+  const cliRenderer = await createCliRenderer()
+
+  // State
+  let destroyed = false
+  const wrapFocus = config?.wrapFocus ?? true
+  const vimBindings = config?.vimBindings ?? false
+  const sequenceTimeout = config?.sequenceTimeout ?? 500
+  const targetFps = config?.targetFps ?? 60
+
+  // Create manager states
+  const focusState = createFocusManagerState(wrapFocus)
+  const keyboardState = createKeyboardManagerState(vimBindings, sequenceTimeout)
+  const cursorState = createCursorManagerState()
+  const stateManagerState = createStateManagerState(targetFps)
+  const mouseState = createMouseManagerState()
+  const inputState = createInputManagerState()
+  const componentState = createComponentManagerState()
+
+  // Helper: emit key to focused component's handlers
+  const handleComponentKeyWrapper = (key: string): boolean => {
+    return handleComponentKey(
+      focusState.focusedId,
+      inputState,
+      componentState,
+      focusState,
+      key
+    )
+  }
+
+  // Setup built-in key handlers
+  const setupBuiltInKeyHandlers = () => {
+    // Tab handling
+    keyboardState.keyHandlers.set('tab', [
+      {
+        handler: () => {
+          renderer.focusNext()
+          return true
+        },
+        priority: -100,
+      },
+    ])
+    keyboardState.keyHandlers.set('shift+tab', [
+      {
+        handler: () => {
+          renderer.focusPrev()
+          return true
+        },
+        priority: -100,
+      },
+    ])
+
+    // Arrow keys for focus navigation
+    keyboardState.keyHandlers.set('down', [
+      {
+        handler: () => {
+          if (handleComponentKeyWrapper('down')) return true
+          renderer.focusNext()
+          return true
+        },
+        priority: -100,
+      },
+    ])
+
+    keyboardState.keyHandlers.set('up', [
+      {
+        handler: () => {
+          if (handleComponentKeyWrapper('up')) return true
+          renderer.focusPrev()
+          return true
+        },
+        priority: -100,
+      },
+    ])
+
+    keyboardState.keyHandlers.set('left', [
+      {
+        handler: () => {
+          if (handleComponentKeyWrapper('left')) return true
+          renderer.focusPrev()
+          return true
+        },
+        priority: -100,
+      },
+    ])
+
+    keyboardState.keyHandlers.set('right', [
+      {
+        handler: () => {
+          if (handleComponentKeyWrapper('right')) return true
+          renderer.focusNext()
+          return true
+        },
+        priority: -100,
+      },
+    ])
+
+    // Enter/Space for activation
+    keyboardState.keyHandlers.set('enter', [
+      { handler: () => handleComponentKeyWrapper('enter'), priority: -100 },
+    ])
+    keyboardState.keyHandlers.set('space', [
+      { handler: () => handleComponentKeyWrapper('space'), priority: -100 },
+    ])
+
+    // Escape handling
+    keyboardState.keyHandlers.set('escape', [
+      {
+        handler: () => {
+          // Clear pending sequence
+          keyboardState.pendingSequence = ''
+          if (keyboardState.sequenceTimer) {
+            clearTimeout(keyboardState.sequenceTimer)
+            keyboardState.sequenceTimer = null
+          }
+
+          // Exit search mode
+          if (keyboardState.mode === 'search') {
+            keyboardState.mode = 'normal'
+            return true
+          }
+
+          // Call cancel handler
+          keyboardState.cancelHandler?.()
+          return true
+        },
+        priority: -100,
+      },
+    ])
+
+    // Other special keys
+    keyboardState.keyHandlers.set('backspace', [
+      { handler: () => handleComponentKeyWrapper('backspace'), priority: -100 },
+    ])
+    keyboardState.keyHandlers.set('delete', [
+      { handler: () => handleComponentKeyWrapper('delete'), priority: -100 },
+    ])
+    keyboardState.keyHandlers.set('home', [
+      { handler: () => handleComponentKeyWrapper('home'), priority: -100 },
+    ])
+    keyboardState.keyHandlers.set('end', [
+      { handler: () => handleComponentKeyWrapper('end'), priority: -100 },
+    ])
+    keyboardState.keyHandlers.set('pagedown', [
+      { handler: () => handleComponentKeyWrapper('pagedown'), priority: -100 },
+    ])
+    keyboardState.keyHandlers.set('pageup', [
+      { handler: () => handleComponentKeyWrapper('pageup'), priority: -100 },
+    ])
+    keyboardState.keyHandlers.set('ctrl+enter', [
+      { handler: () => handleComponentKeyWrapper('ctrl+enter'), priority: -100 },
+    ])
+
+    // Vim bindings
+    if (vimBindings) {
+      keyboardState.keyHandlers.set('j', [
+        {
+          handler: () => {
+            if (handleComponentKeyWrapper('j')) return true
+            renderer.focusNext()
+            return true
+          },
+          priority: -100,
+        },
+      ])
+
+      keyboardState.keyHandlers.set('k', [
+        {
+          handler: () => {
+            if (handleComponentKeyWrapper('k')) return true
+            renderer.focusPrev()
+            return true
+          },
+          priority: -100,
+        },
+      ])
+
+      keyboardState.keyHandlers.set('h', [
+        {
+          handler: () => {
+            // Horizontal navigation - find prev column
+            const ids = getSortedFocusableIds(focusState, destroyed)
+            const currentIdx = getCurrentFocusIndex(focusState, destroyed)
+            if (currentIdx <= 0) return true
+
+            const currentFocusable = focusState.focusables.get(focusState.focusedId!)
+            const currentColumn = currentFocusable?.options.column ?? 0
+
+            // Find previous element with lower column
+            for (let i = currentIdx - 1; i >= 0; i--) {
+              const f = focusState.focusables.get(ids[i])
+              if (f && (f.options.column ?? 0) < currentColumn) {
+                renderer.focusById(ids[i])
+                return true
+              }
+            }
+
+            // Just go prev
+            renderer.focusPrev()
+            return true
+          },
+          priority: -100,
+        },
+      ])
+
+      keyboardState.keyHandlers.set('l', [
+        {
+          handler: () => {
+            // Horizontal navigation - find next column
+            const ids = getSortedFocusableIds(focusState, destroyed)
+            const currentIdx = getCurrentFocusIndex(focusState, destroyed)
+            if (currentIdx < 0 || currentIdx >= ids.length - 1) return true
+
+            const currentFocusable = focusState.focusables.get(focusState.focusedId!)
+            const currentColumn = currentFocusable?.options.column ?? 0
+
+            // Find next element with higher column
+            for (let i = currentIdx + 1; i < ids.length; i++) {
+              const f = focusState.focusables.get(ids[i])
+              if (f && (f.options.column ?? 0) > currentColumn) {
+                renderer.focusById(ids[i])
+                return true
+              }
+            }
+
+            // Just go next
+            renderer.focusNext()
+            return true
+          },
+          priority: -100,
+        },
+      ])
+
+      keyboardState.keyHandlers.set('g', [
+        {
+          handler: () => {
+            // Part of gg sequence - handled by sequence handler
+            return false
+          },
+          priority: -100,
+        },
+      ])
+
+      keyboardState.keyHandlers.set('G', [
+        {
+          handler: () => {
+            // Jump to last
+            const ids = getSortedFocusableIds(focusState, destroyed)
+            if (ids.length > 0) {
+              renderer.focusById(ids[ids.length - 1])
+            }
+            return true
+          },
+          priority: -100,
+        },
+      ])
+
+      keyboardState.keyHandlers.set('/', [
+        {
+          handler: () => {
+            keyboardState.mode = 'search'
+            keyboardState.searchModeHandler?.()
+            return true
+          },
+          priority: -100,
+        },
+      ])
+
+      // Register gg sequence
+      keyboardState.sequenceHandlers.set('gg', () => {
+        const ids = getSortedFocusableIds(focusState, destroyed)
+        if (ids.length > 0) {
+          renderer.focusById(ids[0])
+        }
+      })
+    }
+  }
+
+  const renderer: InteractiveRenderer = {
+    width: cliRenderer.width,
+    height: cliRenderer.height,
+
+    // Lifecycle
+    start() {
+      if (destroyed) return
+      cliRenderer.start()
+    },
+
+    stop() {
+      if (destroyed) return
+      cliRenderer.stop()
+    },
+
+    destroy() {
+      if (destroyed) return
+      destroyed = true
+      cliRenderer.destroy()
+      focusState.focusables.clear()
+      clearMouseState(mouseState)
+      clearKeyboardState(keyboardState)
+      clearInputState(inputState)
+      clearComponentState(componentState)
+      clearStateManager(stateManagerState)
+      focusState.focusedId = null
+    },
+
+    requestRender() {
+      if (destroyed) return
+      cliRenderer.requestRender()
+    },
+
+    // Focus management
+    focusNext() {
+      focusNextFn(focusState, cursorState, destroyed)
+    },
+
+    focusPrev() {
+      focusPrevFn(focusState, cursorState, destroyed)
+    },
+
+    focusById(id: string) {
+      focusByIdFn(focusState, cursorState, id, destroyed)
+    },
+
+    getFocusedId() {
+      return getFocusedIdFn(focusState, destroyed)
+    },
+
+    getFocusableIds() {
+      return getFocusableIdsFn(focusState, destroyed)
+    },
+
+    registerFocusable(id: string, options: FocusableOptions) {
+      registerFocusableFn(focusState, id, options, destroyed)
+    },
+
+    unregisterFocusable(id: string) {
+      unregisterFocusableFn(focusState, id, destroyed)
+    },
+
+    setActiveGroup(group: string) {
+      setActiveGroupFn(focusState, group, destroyed)
+    },
+
+    pushFocusTrap(group: string) {
+      pushFocusTrapFn(focusState, group, destroyed)
+    },
+
+    popFocusTrap() {
+      popFocusTrapFn(focusState, cursorState, destroyed)
+    },
+
+    // Keyboard management
+    onKeyPress(key: string, handler: () => boolean | void, options?: { priority?: number }) {
+      onKeyPressFn(keyboardState, key, handler, options, destroyed)
+    },
+
+    offKeyPress(key: string, handler: () => boolean | void) {
+      offKeyPressFn(keyboardState, key, handler, destroyed)
+    },
+
+    emitKey(key: string) {
+      emitKeyFn(keyboardState, key, handleComponentKeyWrapper, focusState.focusedId, destroyed)
+    },
+
+    onKeySequence(sequence: string, handler: () => void) {
+      onKeySequenceFn(keyboardState, sequence, handler, destroyed)
+    },
+
+    getPendingSequence() {
+      return getPendingSequenceFn(keyboardState, destroyed)
+    },
+
+    onSearchMode(handler: () => void) {
+      onSearchModeFn(keyboardState, handler, destroyed)
+    },
+
+    onCancel(handler: () => void) {
+      onCancelFn(keyboardState, handler, destroyed)
+    },
+
+    getMode() {
+      return getModeFn(keyboardState, destroyed)
+    },
+
+    // Mouse management
+    onClick(handler: (event: { x: number; y: number }) => void) {
+      onClickFn(mouseState, handler, destroyed)
+    },
+
+    offClick(handler: (event: { x: number; y: number }) => void) {
+      offClickFn(mouseState, handler, destroyed)
+    },
+
+    emitClick(x: number, y: number, options?: { clickCount?: number; button?: string }) {
+      emitClickFn(mouseState, focusState, cursorState, x, y, options, destroyed)
+    },
+
+    registerClickable(id: string, options: ClickableOptions) {
+      registerClickableFn(mouseState, id, options, destroyed)
+    },
+
+    unregisterClickable(id: string) {
+      unregisterClickableFn(mouseState, id, destroyed)
+    },
+
+    getClickableAreas() {
+      return getClickableAreasFn(mouseState, destroyed)
+    },
+
+    onScroll(handler: (event: { deltaY: number }) => void) {
+      onScrollFn(mouseState, handler, destroyed)
+    },
+
+    emitScroll(x: number, y: number, options: { deltaY: number }) {
+      emitScrollFn(mouseState, x, y, options, destroyed)
+    },
+
+    // Cursor management
+    setCursorPosition(x: number, y: number) {
+      setCursorPositionFn(cursorState, x, y, destroyed)
+    },
+
+    getCursorPosition() {
+      return getCursorPositionFn(cursorState, destroyed)
+    },
+
+    showCursor() {
+      showCursorFn(cursorState, destroyed)
+    },
+
+    hideCursor() {
+      hideCursorFn(cursorState, destroyed)
+    },
+
+    isCursorVisible() {
+      return isCursorVisibleFn(cursorState, destroyed)
+    },
+
+    setCursorStyle(style: 'block' | 'underline' | 'bar') {
+      setCursorStyleFn(cursorState, style, destroyed)
+    },
+
+    getCursorStyle() {
+      return getCursorStyleFn(cursorState, destroyed)
+    },
+
+    setCursorBlink(blink: boolean) {
+      setCursorBlinkFn(cursorState, blink, destroyed)
+    },
+
+    isCursorBlinking() {
+      return isCursorBlinkingFn(cursorState, destroyed)
+    },
+
+    updateCursorPosition(id: string, position: { x: number; y: number }) {
+      updateCursorPositionFn(cursorState, focusState, id, position, destroyed)
+    },
+
+    // State management
+    setState(key: string, value: unknown) {
+      setStateFn(stateManagerState, key, value, destroyed)
+    },
+
+    getState(key: string) {
+      return getStateFn(stateManagerState, key, destroyed)
+    },
+
+    subscribe(key: string, subscriber: (newValue: unknown, oldValue: unknown) => void) {
+      return subscribeFn(stateManagerState, key, subscriber, destroyed)
+    },
+
+    onRender(handler: () => void) {
+      onRenderFn(stateManagerState, handler, destroyed)
+    },
+
+    getTargetFps() {
+      return getTargetFpsFn(stateManagerState)
+    },
+
+    // Input management
+    registerInput(id: string, options: InputOptions) {
+      registerInputFn(inputState, focusState, id, options, destroyed)
+    },
+
+    getInputCursorIndex(id: string) {
+      return getInputCursorIndexFn(inputState, id, destroyed)
+    },
+
+    // Component management
+    registerComponent(id: string, options: ComponentOptions) {
+      registerComponentFn(componentState, focusState, id, options, destroyed)
+    },
+
+    unregisterComponent(id: string) {
+      unregisterComponentFn(componentState, focusState, id, destroyed)
+    },
+
+    getComponent(id: string) {
+      return getComponentFn(componentState, id, destroyed)
+    },
+
+    updateComponent(id: string, updates: Partial<ComponentOptions>) {
+      updateComponentFn(componentState, id, updates, destroyed)
+    },
+  }
+
+  // Setup built-in handlers
+  setupBuiltInKeyHandlers()
+
+  return renderer
+}
+
+// Re-export the string-based renderer for test compatibility
+export { renderInteractive } from '../interactive-string'
+export type { InteractiveRenderOptions } from '../interactive-string'