Raxol.Core.KeyboardNavigator.NavigatorServer (Raxol v2.0.1)

BaseManager implementation for keyboard navigation in Raxol terminal UI applications.

This server provides a pure functional approach to keyboard navigation, eliminating Process dictionary usage and implementing proper OTP patterns.

Features

Tab-based keyboard navigation between focusable elements
Arrow key navigation for spatial layouts
Vim-style navigation support (h,j,k,l)
Custom navigation paths between components
Group-based navigation
Spatial navigation for grid layouts
Configurable key bindings
Supervised state management with fault tolerance

State Structure

The server maintains state with the following structure:

%{
  config: %{
    next_key: :tab,
    previous_key: :tab,  # with shift modifier
    activate_keys: [:enter, :space],
    dismiss_key: :escape,
    arrow_navigation: true,
    vim_keys: false,
    group_navigation: true,
    spatial_navigation: false,
    tab_navigation: true
  },
  spatial_map: %{component_id => position_data},
  navigation_paths: %{from_id => %{direction => to_id}},
  focus_stack: [],  # Navigation history for back navigation
  groups: %{group_name => [component_ids]}
}

Summary

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

configure(server \\ __MODULE__, opts)

Configures keyboard navigation behavior.

define_navigation_path(server \\ __MODULE__, from_id, direction, to_id)

Defines an explicit navigation path between components.

get_config(server \\ __MODULE__)

Gets the current configuration.

get_navigation_paths(server \\ __MODULE__)

Gets navigation paths.

get_spatial_map(server \\ __MODULE__)

Gets the spatial map.

get_state(server \\ __MODULE__)

Gets the current state (for debugging/testing).

handle_keyboard_event(server \\ __MODULE__, event)

Handles keyboard events for navigation. This is typically called by the EventManager.

handle_manager_info(msg, state)

Callback implementation for Raxol.Core.Behaviours.BaseManager.handle_manager_info/2.

init_navigator(server \\ __MODULE__)

Initializes the keyboard navigator. Registers event handlers for keyboard navigation.

pop_focus(server \\ __MODULE__)

Pops and returns to the previous focus.

push_focus(server \\ __MODULE__, component_id)

Pushes current focus to the stack (for back navigation).

register_component_position(server \\ __MODULE__, component_id, x, y, width, height)

Registers a component's position for spatial navigation.

register_to_group(server \\ __MODULE__, component_id, group_name)

Registers a component to a navigation group.

reset(server \\ __MODULE__)

Resets to initial state.

start_link(init_opts \\ [])

unregister_from_group(server \\ __MODULE__, component_id, group_name)

Unregisters a component from a navigation group.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

configure(server \\ MODULE, opts)

Configures keyboard navigation behavior.

define_navigation_path(server \\ MODULE, from_id, direction, to_id)

Defines an explicit navigation path between components.

get_config(server \\ MODULE)

Gets the current configuration.

get_navigation_paths(server \\ MODULE)

Gets navigation paths.

get_spatial_map(server \\ MODULE)

Gets the spatial map.

get_state(server \\ MODULE)

Gets the current state (for debugging/testing).

handle_keyboard_event(server \\ MODULE, event)

Handles keyboard events for navigation. This is typically called by the EventManager.

handle_manager_info(msg, state)

Callback implementation for Raxol.Core.Behaviours.BaseManager.handle_manager_info/2.

init_navigator(server \\ MODULE)

Initializes the keyboard navigator. Registers event handlers for keyboard navigation.

pop_focus(server \\ MODULE)

Pops and returns to the previous focus.

push_focus(server \\ MODULE, component_id)

Pushes current focus to the stack (for back navigation).

register_component_position(server \\ MODULE, component_id, x, y, width, height)

Registers a component's position for spatial navigation.

register_to_group(server \\ MODULE, component_id, group_name)

Registers a component to a navigation group.

reset(server \\ MODULE)

Resets to initial state.

start_link(init_opts \\ [])

unregister_from_group(server \\ MODULE, component_id, group_name)

Unregisters a component from a navigation group.