Raxol.Core.KeyboardNavigator (Raxol v0.2.0)

View Source

Keyboard navigation handler for Raxol terminal UI applications.

This module integrates with the FocusManager to provide keyboard navigation between interactive components using standard key bindings:

  • Tab: Move to next focusable element
  • Shift+Tab: Move to previous focusable element
  • Arrow keys: Navigate between elements in a component group
  • Escape: Return to previous focus or dismiss dialogs
  • Enter/Space: Activate currently focused element

Usage 

# Initialize keyboard navigation in your application
KeyboardNavigator.init()

# Customize keybindings
KeyboardNavigator.configure(next_key: :right, previous_key: :left)

Summary

Functions

configure(opts \\ [])

Configure keyboard navigation behavior.

define_navigation_path(from_id, direction, to_id)

Define explicit navigation paths between components.

handle_keyboard_event(event)

Handle keyboard events for navigation.

init()

Initialize the keyboard navigator.

register_component_position(component_id, x, y, width, height)

Register component positions for spatial navigation.

register_shortcut(key, modifiers, handler)

Register a custom shortcut handler.

Functions

configure(opts \\ [])

Configure keyboard navigation behavior.

Options

  • :next_key - Key to move to next element (default: :tab)
  • :previous_key - Key to move to previous element (default: :tab with shift)
  • :activate_keys - Keys to activate elements (default: [:enter, :space])
  • :dismiss_key - Key to dismiss or go back (default: :escape)
  • :arrow_navigation - Enable arrow key navigation (default: true)
  • :vim_keys - Enable vim-style navigation with h,j,k,l (default: false)
  • :group_navigation - Enable group-based navigation (default: true)
  • :spatial_navigation - Enable spatial navigation for grid layouts (default: false)
  • :tab_navigation - Enable tab-based navigation (default: true)

Examples 

iex> KeyboardNavigator.configure(vim_keys: true)
:ok

define_navigation_path(from_id, direction, to_id)

Define explicit navigation paths between components.

This allows customizing navigation beyond spatial or tab order.

Parameters

  • from_id - Component ID to navigate from
  • direction - Navigation direction (:up, :down, :left, :right)
  • to_id - Component ID to navigate to

Examples 

iex> KeyboardNavigator.define_navigation_path("search_input", :down, "submit_button")
:ok

handle_keyboard_event(event)

Handle keyboard events for navigation.

This function is called by the EventManager when keyboard events occur.

Parameters

  • event - The keyboard event to handle

Returns

  • :handled - If the event was handled by the navigator
  • :unhandled - If the event was not handled

init()

Initialize the keyboard navigator.

This registers event handlers for keyboard navigation.

Examples 

iex> KeyboardNavigator.init()
:ok

register_component_position(component_id, x, y, width, height)

Register component positions for spatial navigation.

This allows arrow keys to navigate components based on their physical layout.

Parameters

  • component_id - Unique identifier for the component
  • x - X coordinate
  • y - Y coordinate
  • width - Width of the component
  • height - Height of the component

Examples 

iex> KeyboardNavigator.register_component_position("search_input", 10, 5, 30, 3)
:ok

register_shortcut(key, modifiers, handler)

Register a custom shortcut handler.

Parameters

  • key - The key to handle
  • modifiers - List of modifier keys (e.g., [:ctrl, :shift])
  • handler - Function to call when shortcut is pressed

Examples 

iex> KeyboardNavigator.register_shortcut(:f1, [], &show_help/0)
:ok