@mdxui/terminal 2.0.0

package/dist/index-CQRFZntR.d.ts

@@ -0,0 +1,867 @@
+import React__default, { ReactNode, ReactElement } from 'react';
+
+/**
+ * Keyboard Manager
+ *
+ * Core keyboard binding manager for handling key bindings and sequences.
+ * Supports single keys, modifier combinations, and multi-key sequences.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Modifier key state for a key press event.
+ *
+ * Tracks which modifier keys are held during a key press.
+ */
+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.
+ */
+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 '+')
+ */
+type KeyBindings = Record<string, KeyboardAction>;
+/**
+ * Context passed to action handlers with the triggering key and optional extra data.
+ */
+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
+ */
+type ActionHandler = (action: string, context: ActionContext) => void;
+/**
+ * Configuration options for creating a keyboard manager.
+ */
+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.
+ */
+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;
+}
+/**
+ * Common key constants for keyboard handling.
+ * Use these with matchKey() for consistent key comparisons.
+ */
+declare const KEY: {
+    readonly ENTER: "enter";
+    readonly ESCAPE: "escape";
+    readonly UP: "up";
+    readonly DOWN: "down";
+    readonly LEFT: "left";
+    readonly RIGHT: "right";
+    readonly TAB: "tab";
+    readonly SPACE: "space";
+    readonly BACKSPACE: "backspace";
+    readonly DELETE: "delete";
+};
+/**
+ * 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()
+ * }
+ * ```
+ */
+declare function matchKey(key: string, expected: string): boolean;
+/**
+ * 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)
+ * })
+ * ```
+ */
+declare function createKeyboardManager(options: KeyboardManagerOptions): KeyboardManager;
+
+/**
+ * Preset Key Bindings
+ *
+ * Common keyboard binding presets for terminal applications.
+ * Includes Vim-style, arrow key, and common UI bindings.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * 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
+ * })
+ * ```
+ */
+declare const VIM_BINDINGS: KeyBindings;
+/**
+ * Arrow key navigation bindings.
+ *
+ * Maps arrow keys to directional movement actions.
+ */
+declare const ARROW_BINDINGS: KeyBindings;
+/**
+ * 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'
+ */
+declare const COMMON_BINDINGS: KeyBindings;
+/**
+ * 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
+ */
+declare const EMACS_BINDINGS: KeyBindings;
+
+/**
+ * @mdxui/terminal Type Definitions
+ *
+ * Branded types and type utilities for type-safe terminal components.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Brand symbol for FocusId type.
+ * Used to create a nominal/branded type that prevents accidental string usage.
+ */
+declare const FocusIdBrand: unique symbol;
+/**
+ * Branded type for focus element IDs.
+ *
+ * This is a nominal/branded type that appears as a string at runtime but
+ * provides compile-time type safety. You cannot accidentally pass an
+ * arbitrary string where a FocusId is expected.
+ *
+ * @example
+ * ```tsx
+ * import { createFocusId, type FocusId } from '@mdxui/terminal'
+ *
+ * // Correct - use createFocusId to get a valid FocusId
+ * const id: FocusId = createFocusId('my-element')
+ *
+ * // Error - cannot assign plain string to FocusId
+ * const badId: FocusId = 'some-string' // TypeScript error!
+ * ```
+ */
+type FocusId = string & {
+    readonly [FocusIdBrand]: true;
+};
+/**
+ * Creates a branded FocusId from an optional string.
+ *
+ * If no id is provided, generates a unique id like `focus-1`, `focus-2`, etc.
+ * The returned value is typed as FocusId, which provides compile-time
+ * safety against accidentally using wrong strings.
+ *
+ * @param id - Optional custom ID string. If not provided, auto-generates one.
+ * @returns A branded FocusId that can be used with focus management APIs.
+ *
+ * @example
+ * ```tsx
+ * import { createFocusId } from '@mdxui/terminal'
+ *
+ * // Auto-generate an ID
+ * const autoId = createFocusId() // 'focus-1', 'focus-2', etc.
+ *
+ * // Use a custom ID
+ * const customId = createFocusId('submit-button')
+ *
+ * // Use with useFocus
+ * const focusable = useFocus({ id: 'my-element' })
+ * console.log(focusable.id) // FocusId typed
+ * ```
+ */
+declare function createFocusId(id?: string): FocusId;
+/**
+ * Type guard to check if a value is a valid FocusId.
+ *
+ * At runtime, FocusId is just a string, so this check validates that
+ * the value is a non-empty string. For compile-time safety, use the
+ * branded type system instead.
+ *
+ * @param value - Value to check
+ * @returns True if value could be a valid FocusId
+ *
+ * @example
+ * ```tsx
+ * const maybeId: unknown = getUserInput()
+ * if (isFocusId(maybeId)) {
+ *   // maybeId is now typed as FocusId
+ *   focusManager.focusById(maybeId)
+ * }
+ * ```
+ */
+declare function isFocusId(value: unknown): value is FocusId;
+/**
+ * Resets the focus ID counter. For testing purposes only.
+ * @internal
+ */
+declare function __resetFocusIdCounter(): void;
+
+/**
+ * Focus Management System
+ *
+ * React hooks and context for managing focus state across terminal UI components.
+ * Provides focus tracking, navigation, and keyboard integration.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Options for the useKeyboard hook.
+ */
+interface UseKeyboardOptions {
+    /** Whether keyboard handling is enabled (default: true) */
+    enabled?: boolean;
+    /** Priority for keyboard event handling (higher wins) */
+    priority?: number;
+}
+/**
+ * Return value from the useKeyboard hook.
+ */
+interface UseKeyboardResult {
+    /** Whether keyboard handling is currently enabled */
+    enabled: boolean;
+    /** Current priority level */
+    priority: number;
+    /** Enable keyboard handling */
+    enable: () => void;
+    /** Disable keyboard handling */
+    disable: () => void;
+    /** Cleanup function (called on unmount) */
+    cleanup: () => void;
+}
+/**
+ * React hook for handling keyboard input with modifier key support.
+ *
+ * Provides a handler that receives key presses along with modifier state.
+ * Useful for building custom keyboard interaction patterns.
+ *
+ * @param handler - Callback receiving key name and modifier state
+ * @param options - Configuration options
+ * @returns Controls for enabling/disabling keyboard handling
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const keyboard = useKeyboard((key, modifiers) => {
+ *     if (modifiers.ctrl && key === 'c') {
+ *       handleCopy()
+ *     }
+ *   })
+ *
+ *   return <div>...</div>
+ * }
+ * ```
+ */
+declare function useKeyboard(handler: (key: string, modifiers: KeyModifiers) => void, options?: UseKeyboardOptions): UseKeyboardResult;
+/**
+ * Options for the useFocus hook.
+ */
+interface UseFocusOptions {
+    /** Custom ID for the focusable element */
+    id?: string;
+    /** Whether to focus on mount (default: false) */
+    autoFocus?: boolean;
+    /** Tab order index */
+    tabIndex?: number;
+    /** Callback when element receives focus */
+    onFocus?: () => void;
+    /** Callback when element loses focus */
+    onBlur?: () => void;
+}
+/**
+ * Interface for a focusable element returned by useFocus.
+ */
+interface FocusableElement {
+    /** Unique ID for this focusable element */
+    id: FocusId;
+    /** Whether this element currently has focus */
+    focused: boolean;
+    /** Tab order index */
+    tabIndex: number;
+    /** Programmatically focus this element */
+    focus: () => void;
+    /** Programmatically blur this element */
+    blur: () => void;
+    /** Move focus to the next focusable element */
+    focusNext: () => void;
+    /** Move focus to the previous focusable element */
+    focusPrev: () => void;
+    /** Move focus to the first focusable element */
+    focusFirst: () => void;
+    /** Move focus to the last focusable element */
+    focusLast: () => void;
+}
+/**
+ * React hook for focus management in terminal UIs.
+ *
+ * Provides focus state and navigation helpers for building
+ * accessible keyboard-navigable interfaces.
+ *
+ * @param options - Configuration options
+ * @returns Focus state and control methods
+ *
+ * @example
+ * ```tsx
+ * function MenuItem({ label }: { label: string }) {
+ *   const { focused, focus, blur } = useFocus({
+ *     onFocus: () => console.log('focused'),
+ *     onBlur: () => console.log('blurred')
+ *   })
+ *
+ *   return (
+ *     <Text color={focused ? 'primary' : undefined}>
+ *       {focused ? '> ' : '  '}{label}
+ *     </Text>
+ *   )
+ * }
+ * ```
+ */
+declare function useFocus(options?: UseFocusOptions): FocusableElement;
+/**
+ * State and controls from the focus manager context.
+ */
+interface FocusManagerState {
+    /** IDs of all registered focusable elements */
+    focusableIds: FocusId[];
+    /** ID of the currently focused element, or null */
+    focusedId: FocusId | null;
+    /** Whether focus is trapped within a container */
+    isTrapped: boolean;
+    /** Focus a specific element by ID */
+    focusById: (id: FocusId) => void;
+    /** Move focus to the next element */
+    focusNext: () => void;
+    /** Move focus to the previous element */
+    focusPrev: () => void;
+    /** Move focus to the first element */
+    focusFirst: () => void;
+    /** Move focus to the last element */
+    focusLast: () => void;
+    /** Register a focusable element with the provider */
+    registerFocusable: (id: FocusId, tabIndex: number) => void;
+    /** Unregister a focusable element from the provider */
+    unregisterFocusable: (id: FocusId) => void;
+}
+/**
+ * React context for focus manager state.
+ */
+declare const FocusContext: React__default.Context<FocusManagerState | null>;
+/**
+ * React hook to access the focus manager context.
+ *
+ * Must be used within a FocusProvider. Returns a default
+ * no-op implementation if used outside a provider.
+ *
+ * @returns Focus manager state and controls
+ *
+ * @example
+ * ```tsx
+ * function NavigationHelp() {
+ *   const { focusFirst, focusLast } = useFocusManager()
+ *
+ *   return (
+ *     <Box>
+ *       <Button onPress={focusFirst}>Go to start</Button>
+ *       <Button onPress={focusLast}>Go to end</Button>
+ *     </Box>
+ *   )
+ * }
+ * ```
+ */
+declare function useFocusManager(): FocusManagerState;
+/**
+ * Options for the useNavigableList hook.
+ */
+interface UseNavigableListOptions<T> {
+    /** Array of items to navigate */
+    items: T[];
+    /** Initial selected index (default: 0) */
+    initialIndex?: number;
+    /** Wrap around at list boundaries (default: false) */
+    wrap?: boolean;
+    /** Enable keyboard navigation (default: false) */
+    useKeyboard?: boolean;
+    /** Callback when an item is selected */
+    onSelect?: (item: T, index: number) => void;
+}
+/**
+ * Return value from the useNavigableList hook.
+ */
+interface UseNavigableListResult<T> {
+    /** Current selected index */
+    currentIndex: number;
+    /** Current selected item */
+    currentItem: T | undefined;
+    /** Whether wrapping is enabled */
+    wrap: boolean;
+    /** Whether keyboard navigation is enabled */
+    keyboardEnabled: boolean;
+    /** Move selection up (decrease index) */
+    moveUp: () => void;
+    /** Move selection down (increase index) */
+    moveDown: () => void;
+    /** Move selection to the first item */
+    moveToFirst: () => void;
+    /** Move selection to the last item */
+    moveToLast: () => void;
+    /** Set the selection to a specific index */
+    setIndex: (index: number) => void;
+}
+/**
+ * React hook for keyboard-navigable lists.
+ *
+ * Manages selection state and provides navigation methods
+ * for building interactive list interfaces.
+ *
+ * @param options - Configuration options
+ * @returns Selection state and navigation controls
+ *
+ * @example
+ * ```tsx
+ * function Menu() {
+ *   const items = ['File', 'Edit', 'View', 'Help']
+ *   const { currentIndex, moveUp, moveDown } = useNavigableList({
+ *     items,
+ *     wrap: true,
+ *     onSelect: (item) => console.log('Selected:', item)
+ *   })
+ *
+ *   return (
+ *     <List items={items} selectedIndex={currentIndex} />
+ *   )
+ * }
+ * ```
+ */
+declare function useNavigableList<T>(options: UseNavigableListOptions<T>): UseNavigableListResult<T>;
+/**
+ * Options for the useNavigableGrid hook.
+ */
+interface UseNavigableGridOptions {
+    /** Number of rows in the grid */
+    rows: number;
+    /** Number of columns in the grid */
+    cols: number;
+    /** Initial row (default: 0) */
+    initialRow?: number;
+    /** Initial column (default: 0) */
+    initialCol?: number;
+    /** Wrap horizontally at column boundaries (default: false) */
+    wrapHorizontal?: boolean;
+    /** Wrap vertically at row boundaries (default: false) */
+    wrapVertical?: boolean;
+    /** Enable keyboard navigation (default: false) */
+    useKeyboard?: boolean;
+}
+/**
+ * Return value from the useNavigableGrid hook.
+ */
+interface UseNavigableGridResult {
+    /** Current row position */
+    row: number;
+    /** Current column position */
+    col: number;
+    /** Whether horizontal wrapping is enabled */
+    wrapHorizontal: boolean;
+    /** Whether vertical wrapping is enabled */
+    wrapVertical: boolean;
+    /** Whether keyboard navigation is enabled */
+    keyboardEnabled: boolean;
+    /** Move up one row */
+    moveUp: () => void;
+    /** Move down one row */
+    moveDown: () => void;
+    /** Move left one column */
+    moveLeft: () => void;
+    /** Move right one column */
+    moveRight: () => void;
+    /** Move to a specific cell */
+    moveToCell: (row: number, col: number) => void;
+}
+/**
+ * React hook for keyboard-navigable grids.
+ *
+ * Manages 2D position state and provides navigation methods
+ * for building grid-based interactive interfaces.
+ *
+ * @param options - Configuration options
+ * @returns Position state and navigation controls
+ *
+ * @example
+ * ```tsx
+ * function Calendar() {
+ *   const { row, col, moveUp, moveDown, moveLeft, moveRight } = useNavigableGrid({
+ *     rows: 5,
+ *     cols: 7,
+ *     wrapHorizontal: true
+ *   })
+ *
+ *   // Render 5x7 calendar grid with selection at [row, col]
+ * }
+ * ```
+ */
+declare function useNavigableGrid(options: UseNavigableGridOptions): UseNavigableGridResult;
+/**
+ * Props for the FocusProvider component.
+ */
+interface FocusProviderProps {
+    /** Child components */
+    children?: ReactNode;
+    /** Trap focus within this provider (default: false) */
+    trap?: boolean;
+    /** Wrap focus when reaching boundaries (default: false) */
+    wrapFocus?: boolean;
+    /** ID of element to focus initially */
+    initialFocus?: FocusId;
+    /** Focus first element on mount (default: false) */
+    focusFirstOnMount?: boolean;
+    /** Restore focus to previous element when provider unmounts */
+    restoreFocus?: boolean;
+    /** Group name for nested focus management */
+    group?: string;
+}
+/**
+ * Focus provider component for managing focus state across components.
+ *
+ * Provides focus management context to child components, enabling
+ * coordinated focus navigation within a container.
+ *
+ * **Features:**
+ * - Focus tracking across registered focusable elements
+ * - Focus trapping for modals and dialogs
+ * - Wrap-around navigation at boundaries
+ * - Initial focus and focus restoration support
+ * - Named focus groups for scoped management
+ *
+ * @param props - Configuration and children
+ * @returns React element with focus context
+ *
+ * @example
+ * ```tsx
+ * function Dialog() {
+ *   return (
+ *     <FocusProvider trap focusFirstOnMount>
+ *       <Input label="Name" />
+ *       <Input label="Email" />
+ *       <Button>Submit</Button>
+ *     </FocusProvider>
+ *   )
+ * }
+ * ```
+ */
+declare function FocusProvider(props: FocusProviderProps): ReactElement;
+
+/**
+ * Terminal Input Integration
+ *
+ * Integration helpers for connecting keyboard managers to terminal input sources.
+ * Supports Node.js readline and OpenTUI key events.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * 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.
+ */
+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
+ */
+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;
+}
+/**
+ * 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, ... }
+ * })
+ * ```
+ */
+declare function normalizeReadlineKey(str: string | undefined, key: ReadlineKey | undefined): NormalizedKey;
+/**
+ * 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'
+ * ```
+ */
+declare function keyToBindingString(key: NormalizedKey): string;
+/**
+ * Configuration for attaching a keyboard manager to terminal input.
+ */
+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.
+ */
+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
+ * })
+ * ```
+ */
+declare function attachKeyboardManager(manager: KeyboardManager, options?: AttachKeyboardOptions): DetachKeyboard;
+/**
+ * OpenTUI key event structure.
+ * Matches the KeyEvent interface from @opentui/core.
+ */
+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))
+ * })
+ * ```
+ */
+declare function normalizeOpenTUIKey(event: OpenTUIKeyEvent): NormalizedKey;
+/**
+ * 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>
+ * }
+ * ```
+ */
+declare function createOpenTUIKeyHandler(manager: KeyboardManager): (event: OpenTUIKeyEvent) => void;
+
+export { type ActionContext as A, keyToBindingString as B, COMMON_BINDINGS as C, type DetachKeyboard as D, EMACS_BINDINGS as E, type FocusableElement as F, attachKeyboardManager as G, normalizeOpenTUIKey as H, createOpenTUIKeyHandler as I, type FocusId as J, type KeyModifiers as K, createFocusId as L, isFocusId as M, type NormalizedKey as N, type OpenTUIKeyEvent as O, type ReadlineKey as R, type UseKeyboardOptions as U, VIM_BINDINGS as V, __resetFocusIdCounter as _, type KeyboardAction as a, type KeyBindings as b, type ActionHandler as c, type KeyboardManagerOptions as d, type KeyboardManager as e, KEY as f, createKeyboardManager as g, ARROW_BINDINGS as h, type UseKeyboardResult as i, type UseFocusOptions as j, type FocusManagerState as k, type UseNavigableListOptions as l, matchKey as m, type UseNavigableListResult as n, type UseNavigableGridOptions as o, type UseNavigableGridResult as p, type FocusProviderProps as q, FocusContext as r, useFocus as s, useFocusManager as t, useKeyboard as u, useNavigableList as v, useNavigableGrid as w, FocusProvider as x, type AttachKeyboardOptions as y, normalizeReadlineKey as z };