Raxol.Core.UXRefinement (Raxol v0.3.0)

View Source

User experience refinement module for the Raxol terminal UI.

This module provides comprehensive UX features to enhance the terminal UI experience:

  • Focus Management - Track and manage focus across UI components
  • Keyboard Navigation - Enable intuitive keyboard navigation
  • Contextual Hints - Display helpful hints based on current context
  • Focus Indicators - Visual indicators for focused elements
  • Multi-level Hints - Basic, detailed, and examples for different help levels
  • Keyboard Shortcuts - Global and context-specific keyboard shortcuts
  • Accessibility Features - Screen reader support, high contrast, reduced motion, etc.

All features can be enabled or disabled individually to customize the UX to your needs.

Summary

Functions

Make an announcement for screen readers.

Disable a previously enabled UX refinement feature.

Enable a UX refinement feature.

Check if a UX refinement feature is enabled.

Get accessibility metadata for a component.

Get all available shortcuts for a given context. If no context is provided, returns shortcuts for the current active context.

Get a specific hint level for a component.

Get shortcuts for a component.

Get the hint for a component.

Initialize the UX refinement system.

Register accessibility metadata for a component.

Register comprehensive hints for a component with multiple detail levels.

Register a hint for a component.

Set the active context for keyboard shortcuts.

Display help for available keyboard shortcuts.

Functions

announce(message, opts \\ [])

Make an announcement for screen readers.

disable_feature(feature)

Disable a previously enabled UX refinement feature.

Parameters

  • feature - The feature to disable

Examples

iex> UXRefinement.disable_feature(:hints)
:ok

enable_feature(feature, opts \\ [])

Enable a UX refinement feature.

Available features:

  • :focus_management - Enable focus tracking and management
  • :keyboard_navigation - Enable keyboard navigation
  • :hints - Enable contextual hints
  • :focus_ring - Enable visual focus indicators
  • :accessibility - Enable accessibility features
  • :keyboard_shortcuts - Enable keyboard shortcuts
  • :events - Enable event management system

Parameters

  • feature - The feature to enable
  • opts - Options for the feature

Examples

iex> UXRefinement.enable_feature(:focus_management)
:ok

iex> UXRefinement.enable_feature(:accessibility, high_contrast: true)
:ok

feature_enabled?(feature)

Check if a UX refinement feature is enabled.

Parameters

  • feature - The feature to check

Examples

iex> UXRefinement.feature_enabled?(:focus_management)
true

get_accessibility_metadata(component_id)

Get accessibility metadata for a component.

get_available_shortcuts(context \\ nil)

Get all available shortcuts for a given context. If no context is provided, returns shortcuts for the current active context.

get_component_hint(component_id, level)

Get a specific hint level for a component.

Parameters

  • component_id - The ID of the component
  • level - The hint level to retrieve (:basic, :detailed, :examples)

Examples

iex> UXRefinement.get_component_hint("search_button", :detailed)
"Search for content in the application using keywords"

get_component_shortcuts(component_id)

Get shortcuts for a component.

Parameters

  • component_id - The ID of the component

Examples

iex> UXRefinement.get_component_shortcuts("search_button")
[{"Enter", "Execute search"}, {"Alt+S", "Focus search"}]

get_hint(component_id)

Get the hint for a component.

This returns the basic hint by default. Use get_component_hint/2 for more detailed hints.

Parameters

  • component_id - The ID of the component

Examples

iex> UXRefinement.get_hint("search_button")
"Search for content"

init()

Initialize the UX refinement system.

This function sets up the basic infrastructure for UX refinement features. It should be called before enabling any specific features.

Examples

iex> UXRefinement.init()
:ok

register_accessibility_metadata(component_id, metadata)

Register accessibility metadata for a component.

Parameters

  • component_id - The ID of the component
  • metadata - The metadata to register

Examples

iex> UXRefinement.register_accessibility_metadata("search_button", %{label: "Search"})
:ok

register_component_hint(component_id, hint_info_string)

Register comprehensive hints for a component with multiple detail levels.

Parameters

  • component_id - The ID of the component
  • hint_info - Map containing different levels of hints and shortcuts

Hint Info Structure

  • :basic - Basic hint (shown by default)
  • :detailed - More detailed explanation
  • :examples - Examples of usage
  • :shortcuts - List of keyboard shortcuts for the component: [{"Ctrl+S", "Save"}, ...]

Examples

iex> UXRefinement.register_component_hint("search_button", %{
...>   basic: "Search for content",
...>   detailed: "Search for content in the application using keywords",
...>   examples: "Type keywords like 'settings' or 'help'",
...>   shortcuts: [
...>     {"Enter", "Execute search"},
...>     {"Alt+S", "Focus search"}
...>   ]
...> })
:ok

iex> UXRefinement.register_component_hint("simple_button", "Click me")
:ok

register_hint(component_id, hint)

Register a hint for a component.

Parameters

  • component_id - The ID of the component
  • hint - The hint text

Examples

iex> UXRefinement.register_hint("search_button", "Search for content")
:ok

set_shortcuts_context(context)

Set the active context for keyboard shortcuts.

show_shortcuts_help()

Display help for available keyboard shortcuts.