Raxol.Core.FocusManager (Raxol v0.2.0)

View Source

Focus management system for Raxol terminal UI applications.

This module provides utilities for managing focus between interactive components:

  • Tab-based keyboard navigation
  • Focus history tracking
  • Focus ring rendering
  • Screen reader announcements

Usage

# Register focusable components in your view
FocusManager.register_focusable("search_input", 1)
FocusManager.register_focusable("submit_button", 2)

# Initialize the focus manager with the first focusable element
FocusManager.set_initial_focus("search_input")

Summary

Functions

Disable a focusable component, preventing it from receiving focus.

Enable a previously disabled focusable component.

Move focus to the next focusable element.

Move focus to the previous focusable element.

Alias for get_focused_element/0.

Get the ID of the currently focused element.

Get the next focusable element after the given one. (Placeholder implementation - mirrors focus_next logic)

Get the previous focusable element before the given one. Mirrors the logic of get_next_focusable/1 but searches backwards.

Check if a component has focus.

Register a handler function to be called when focus changes.

Register a focusable component with the focus manager.

Return to the previously focused element.

Set focus to a specific component.

Set the initial focus to a specific component.

Unregister a focus change handler function. (Placeholder implementation)

Unregister a focusable component.

Functions

disable_component(component_id)

Disable a focusable component, preventing it from receiving focus.

Examples

iex> FocusManager.disable_component("submit_button")
:ok

enable_component(component_id)

Enable a previously disabled focusable component.

Examples

iex> FocusManager.enable_component("submit_button")
:ok

focus_next(opts \\ [])

Move focus to the next focusable element.

Options

  • :group - Only navigate within this group (default: nil - use current group)
  • :wrap - Wrap around to first element when at the end (default: true)

Examples

iex> FocusManager.focus_next()
:ok

iex> FocusManager.focus_next(group: :form_actions)
:ok

focus_previous(opts \\ [])

Move focus to the previous focusable element.

Options

  • :group - Only navigate within this group (default: nil - use current group)
  • :wrap - Wrap around to last element when at the beginning (default: true)

Examples

iex> FocusManager.focus_previous()
:ok

get_current_focus()

@spec get_current_focus() :: String.t() | nil

Alias for get_focused_element/0.

get_focused_element()

Get the ID of the currently focused element.

Examples

iex> FocusManager.set_initial_focus("my_button")
iex> FocusManager.get_focused_element()
"my_button"

get_next_focusable(current_focus_id)

@spec get_next_focusable(String.t() | nil) :: String.t() | nil

Get the next focusable element after the given one. (Placeholder implementation - mirrors focus_next logic)

get_previous_focusable(current_focus_id)

@spec get_previous_focusable(String.t() | nil) :: String.t() | nil

Get the previous focusable element before the given one. Mirrors the logic of get_next_focusable/1 but searches backwards.

has_focus?(component_id)

Check if a component has focus.

Examples

iex> FocusManager.has_focus?("search_input")
true

register_focus_change_handler(handler_fun)

@spec register_focus_change_handler((String.t() | nil, String.t() | nil -> any())) ::
  :ok

Register a handler function to be called when focus changes.

The handler function should accept two arguments: old_focus and new_focus. (Placeholder implementation)

register_focusable(component_id, tab_index, opts \\ [])

Register a focusable component with the focus manager.

Parameters

  • component_id - Unique identifier for the component
  • tab_index - Tab order index (lower numbers are focused first)
  • opts - Additional options

Options

  • :group - Focus group name for grouped navigation (default: :default)
  • :disabled - Whether the component is initially disabled (default: false)
  • :announce - Announcement text for screen readers when focused (default: nil)

Examples

iex> FocusManager.register_focusable("search_input", 1)
:ok

iex> FocusManager.register_focusable("submit_button", 2, group: :form_actions)
:ok

return_to_previous()

Return to the previously focused element.

Examples

iex> FocusManager.return_to_previous()
:ok

set_focus(component_id)

Set focus to a specific component.

Examples

iex> FocusManager.set_focus("submit_button")
:ok

set_initial_focus(component_id)

Set the initial focus to a specific component.

Examples

iex> FocusManager.set_initial_focus("search_input")
:ok

unregister_focus_change_handler(handler_fun)

@spec unregister_focus_change_handler((String.t() | nil, String.t() | nil -> any())) ::
  :ok

Unregister a focus change handler function. (Placeholder implementation)

unregister_focusable(component_id)

Unregister a focusable component.

Examples

iex> FocusManager.unregister_focusable("search_input")
:ok