Raxol (Raxol v0.2.0)

Raxol is a feature-rich terminal UI framework for Elixir.

It provides a comprehensive set of components and tools for building beautiful, accessible, and responsive terminal applications.

Features

Modern Component Library: A rich set of pre-built UI components like buttons, text inputs, tables, modals, and more.
Accessibility Support: Built-in features for screen readers, high contrast mode, and keyboard navigation.
Theming System: Customize the look and feel of your application with consistent theming.
Responsive Layouts: Create layouts that adapt to different terminal sizes.
The Elm Architecture: Follows TEA (The Elm Architecture) for predictable state management.
Event Handling: Comprehensive event system for keyboard, mouse, and terminal events.

Getting Started

To create a new Raxol application, you need to define three core functions:

init/1: Initializes your application state
update/2: Updates the state based on events
render/1: Renders the UI based on the current state

Here's a simple counter example:

```text
defmodule Counter do
  @behaviour Raxol.Core.Runtime.Application

  require Raxol.Core.Renderer.View
  alias Raxol.Core.Runtime.Events.Event

  def init(_opts) do
    {%{count: 0}, []}
  end

  def update(%{count: count} = model, %Event{type: :command, data: :increment}) do
    {%{model | count: count + 1}, []}
  end

  def update(%{count: count} = model, %Event{type: :command, data: :decrement}) do
    {%{model | count: count - 1}, []}
  end

  def update(model, _event_or_msg), do: {model, []}

  def view(model) do
    Raxol.Core.Renderer.View.column [padding: 1] do
      [
        Raxol.Core.Renderer.View.text("Count: #{model.count}"),
        Raxol.Core.Renderer.View.row [gap: 1] do
          [
            Raxol.Core.Renderer.View.button "-", on_click: {:command, :decrement},
            Raxol.Core.Renderer.View.button "+", on_click: {:command, :increment}
          ]
        end
      ]
    end
  end
end

# Start the application
Raxol.run(Counter)
```

Architecture

Raxol is built on the Elm Architecture:

Model: Your application state
Update: Logic to update the state based on messages
View: Pure functions to render UI based on the current state

Messages can be generated by user interactions (like button clicks) or system events (like terminal resize).

Components

Raxol provides a rich set of built-in components in the Raxol.Components module. Common components include:

Buttons
Text inputs
Tables
Progress indicators
Modals
Dropdown menus
Tab bars

Each component follows consistent patterns for styling and behavior.

Summary

Functions

accessibility_settings()

Gets the current accessibility settings.

current_theme()

Gets the current default theme.

run(app, opts \\ [])

Runs a Raxol application.

set_accessibility(opts \\ [])

Enables or disables accessibility features.

set_theme(theme)

Sets the default theme for Raxol applications.

stop(return_value \\ :ok)

Gracefully stops a running Raxol application.

terminal_info()

Returns information about the terminal environment.

version()

Returns the current version of Raxol.

Functions

accessibility_settings()

Gets the current accessibility settings.

Returns

A map of current accessibility settings.

Example

settings = Raxol.accessibility_settings()
if settings.high_contrast do
  # Do something for high contrast mode
end

current_theme()

Gets the current default theme.

Returns

The current theme map.

Example

theme = Raxol.current_theme()

run(app, opts \\ [])

Runs a Raxol application.

This function starts the Raxol runtime with the provided application module and options. The application module must implement the Raxol.Core.Runtime.Application behaviour.

Parameters

app - Module implementing the Raxol.Core.Runtime.Application behaviour
opts - Additional options for the runtime

Options

:quit_keys - List of keys that will quit the application (default: [{:ctrl, ?c}])
:fps - Target frames per second (default: 60)
:title - Terminal window title (default: "Raxol Application")
:font - Terminal font (if supported)
:font_size - Terminal font size (if supported)
:accessibility - Accessibility options
- :screen_reader - Enable screen reader support (default: true)
- :high_contrast - Enable high contrast mode (default: false)
- :large_text - Enable large text mode (default: false)

Returns

The return value of the application when it exits.

Example

Raxol.run(MyApp, %{initial: "state"}, title: "My Application", fps: 30)

set_accessibility(opts \\ [])

Enables or disables accessibility features.

Parameters

opts - Map of accessibility features to enable/disable

Options

:screen_reader - Enable screen reader support
:high_contrast - Enable high contrast mode
:large_text - Enable large text mode
:reduced_motion - Reduce or eliminate animations

Example

Raxol.set_accessibility(screen_reader: true, high_contrast: true)

set_theme(theme)

Sets the default theme for Raxol applications.

This function sets the default theme that will be used by Raxol components.

Parameters

theme - A theme created with Raxol.UI.Theming.Theme.new/1 or one of the built-in themes

Example

# Use a built-in theme
Raxol.set_theme(Raxol.UI.Theming.Theme.dark())

# Create and use a custom theme
custom_theme = Raxol.UI.Theming.Theme.new(name: "Custom", colors: %{primary: :green})
Raxol.set_theme(custom_theme)

stop(return_value \\ :ok)

Gracefully stops a running Raxol application.

This function can be called from within your application to exit gracefully.

Parameters

return_value - Value to return from the Raxol.run/3 function

Example

def update(model, :exit) do
  Raxol.stop(:normal)
  model
end

terminal_info()

Returns information about the terminal environment.

This includes terminal size, color support, and other capabilities.

Returns

A map with terminal information.

Example

Raxol.terminal_info()
# => %{
#      name: "iTerm2",
#      version: "3.5.0",
#      features: [:true_color, :unicode, :mouse, :clipboard],
#      ...
#    }

version()

Returns the current version of Raxol.

Returns

A string representing the current version.

Example

Raxol.version()
# => "1.0.0"