High-level application API for TermUI applications.

This module provides a convenient API for starting and running TermUI applications with automatic backend selection (raw mode or TTY mode).

The runtime owns one root module implementing TermUI.Elm. Lower-level TermUI.ComponentServer processes are not automatically connected to it.

Application Lifecycle

TermUI applications follow The Elm Architecture:

1. Model (state) - Application state
2. View - Renders UI based on state
3. Update - Handles events, returns new state
4. Messages - Events that trigger updates

Backend Selection

The API automatically selects the appropriate backend:

• Raw mode: Full terminal control (mouse, colors, Unicode) - OTP 28+
• TTY mode: Cooked input with graceful degradation

IEx Compatibility

TermUI applications work directly in IEx with no code changes. This enables:

• Interactive debugging and development
• Admin tools and dashboards in production IEx sessions
• Prototyping and testing TUI interfaces

Running in IEx

Start any TermUI application from an IEx session:

iex> TermUI.App.run(MyApp.Counter)
# Use keyboard input, press Q to quit
# Returns to IEx prompt when done

Once the cooked shell delivers their bytes, the parser supports:

• Arrow keys for navigation
• Tab for field switching
• Function keys (F1-F12)
• Ctrl+key combinations not consumed by the shell
• Alt+key combinations emitted by the terminal

IEx uses the TTY backend by default. Depending on the shell and terminal, cooked-mode input may be delivered a line at a time; press Enter when a key is not delivered immediately. Pass backend: :raw only when you explicitly want to attempt ownership of the terminal.

IEx Detection

Detect if your application is running in IEx:

iex> TermUI.iex_mode?()
true

iex> TermUI.running_mode()
:iex

Configuration

Force IEx-compatible mode via configuration:

# config/config.exs
config :term_ui,
  iex_compatible: true

Or via environment variable:

export TERM_UI_IEX_MODE=true

Troubleshooting IEx Issues

Input not reaching the application:

• Ensure the application is started from IEx (not mix run)
• Check that TermUI.iex_mode?() returns true
• Try forcing IEx mode with TERM_UI_IEX_MODE=true

Terminal state not restored after exit:

• The Runtime should restore terminal state automatically
• If problems persist, call TermUI.shutdown() manually

Performance issues in IEx:

• IEx adds some overhead due to process inspection
• Run the application standalone when it needs Raw backend timing or input

Usage

Non-blocking start (for supervisors)

{:ok, pid} = TermUI.App.start(MyApp.Root, backend: :auto)

Blocking run (for scripts and CLI apps)

{:ok, :exited_normally} = TermUI.App.run(MyApp.Root, backend: :auto)

Query backend capabilities

mode = TermUI.App.backend_mode()
unicode? = TermUI.App.supports?(:unicode)
mouse? = TermUI.App.supports?(:mouse)

Shutdown

:ok = TermUI.App.shutdown(pid)

Configuration Options

• :backend - :auto (default), :raw, :tty, a backend module, or {backend_module, backend_opts}
• :name - GenServer name for the Runtime process
• :render_interval - Milliseconds between renders (default: 16, ~60 FPS)

Example

defmodule MyApp.Counter do
  use TermUI.Elm

  @moduledoc """
  A simple counter application.
  """

  @impl true
  def init(_opts) do
    %{count: 0}
  end

  def event_to_msg(%TermUI.Event.Key{key: "+"}, _state), do: {:msg, :increment}
  def event_to_msg(%TermUI.Event.Key{key: "q"}, _state), do: {:msg, :quit}
  def event_to_msg(_event, _state), do: :ignore

  @impl true
  def view(model) do
    stack(:vertical, [
      text("Count: " <> to_string(model.count)),
      text("Press + to increment, q to quit")
    ])
  end

  @impl true
  def update(:increment, model), do: {%{model | count: model.count + 1}, []}
  def update(:quit, model), do: {model, [TermUI.Command.quit()]}
end

# Run the application
TermUI.App.run(MyApp.Counter, backend: :auto)

Root Protocol

Your root module implements TermUI.Elm callbacks:

• init/1 - Initialize the model, called once at startup
• view/1 - Render the UI based on current model
• event_to_msg/2 - Convert terminal events into application messages
• update/2 - Handle messages, returning {new_state, commands}

See TermUI.Elm for the full callback contract.