@spec activate_widget(atom()) :: term()

Programmatically activate (press) a widget by its ID.

@spec animate(atom(), atom(), any(), keyword()) :: reference()

Animate a widget property.

Properties

• :opacity - Opacity (0.0 to 1.0)
• :background - Background color (RGB tuple)
• :color - Foreground color (RGB tuple)
• :offset_x - X offset in cells
• :offset_y - Y offset in cells

Options

• :duration - Animation duration in ms (default: 300)
• :easing - Easing function (default: :ease_out)
• :on_complete - Callback when animation finishes

Easing Functions

:linear, :ease, :ease_in, :ease_out, :ease_in_out, :ease_in_quad, :ease_out_quad, :ease_in_out_quad, :ease_in_cubic, :ease_out_cubic, :ease_in_out_cubic, :ease_in_elastic, :ease_out_elastic, :ease_in_bounce, :ease_out_bounce, :ease_in_out_bounce, :ease_in_back, :ease_out_back

Examples

Drafter.animate(:my_button, :opacity, 0.5, duration: 500)
Drafter.animate(:my_label, :background, {255, 0, 0}, duration: 1000, easing: :ease_out)

@spec button(
  String.t(),
  keyword()
) :: {Drafter.Widget.Button, map()}

Create a button widget

@spec container(
  [{module(), map()}],
  keyword()
) :: {Drafter.Widget.Container, map()}

Create a container widget

@spec current_skin() :: atom()

Returns the currently active skin atom.

@spec digits(
  String.t(),
  keyword()
) :: {Drafter.Widget.Digits, map()}

Create a digits widget for displaying large numbers

@spec footer(
  String.t(),
  keyword()
) :: {Drafter.Widget.Footer, map()}

Create a footer widget

@spec get_widget_state(atom()) :: struct() | nil

Get the full state of a widget by its ID.

Returns the complete widget state struct, useful for accessing multiple fields or widget-specific data.

Returns nil if widget not found.

@spec get_widget_value(atom()) :: term() | nil

Get the current value of a widget by its ID.

Returns the primary "value" of the widget:

• TextInput/TextArea: the text string
• Checkbox: boolean (checked?)
• Switch: boolean (enabled?)
• RadioSet: the selected option ID
• SelectionList: list of selected option IDs
• OptionList: the selected option ID
• Collapsible: boolean (expanded?)
• TabbedContent: the active tab index
• DataTable: list of selected row indices
• Tree: list of selected node IDs

Returns nil if widget not found.

@spec grid(
  [{module(), map()}],
  keyword()
) :: {Drafter.Widget.Grid, map()}

Create a grid widget for layouts

@spec horizontal(
  [{module(), map()}],
  keyword()
) :: {Drafter.Widget.Container, map()}

Create a horizontal layout container

@spec label(
  String.t(),
  keyword()
) :: {Drafter.Widget.Label, map()}

Create a label widget

@spec markdown(
  String.t(),
  keyword()
) :: {Drafter.Widget.Markdown, map()}

Create a markdown widget

@spec placeholder(
  String.t(),
  keyword()
) :: {Drafter.Widget.Placeholder, map()}

Create a placeholder widget

@spec query_all(String.t()) :: [atom()]

Query all widgets matching CSS-like selector.

Returns list of widget_ids.

@spec query_one(String.t()) :: atom() | nil

Query a single widget by CSS-like selector.

Selector examples:

• "Button" - first Button widget
• "#submit" - widget with id :submit
• ".primary" - widget with class :primary
• "Button.primary" - Button with class :primary

Returns widget_id or nil if not found.

@spec rule(keyword()) :: {Drafter.Widget.Rule, map()}

Create a rule (divider line) widget

@spec run(
  module(),
  keyword()
) :: :ok

Start a TUI application.

Options:

• :scroll_optimization - true (default) uses a fast render path during scroll gestures (render_hierarchy from ETS) and defers a full render_app until 150 ms after the last scroll event. Set to false to disable and trigger a full render_app on every scroll tick — maximum freshness at the cost of higher CPU during scroll.
• :syntax_highlighting - true to enable tree-sitter syntax highlighting.

@spec run_session(module(), map(), keyword()) :: :ok | {:error, term()}

Run an app module in an isolated or shared session using pre-started session services.

session_ctx must contain: event_manager, compositor, screen_manager, theme_manager, event_handler as pid values.

Options:

• :mode - :isolated (default) or :shared
• :shared_state - pid of SharedState server when mode is :shared
• All other opts are passed as mount props to the app module

@spec send_app_event(atom(), term()) :: term()

Send an app event to the active app loop.

Used by modal screens and sub-screens to communicate results back to the parent application via handle_event/3.

@spec set_interval(pos_integer(), atom()) :: :ok

Set an interval timer

@spec set_skin(atom()) :: :ok

Switch the active rendering skin.

The skin controls which characters Drafter.CharacterSet returns for every widget render. Built-in skins: :graphical (default), :wireframe, :ascii.

Can be called from inside handle_event/2 or on_timer/2 — takes effect on the next frame.

@spec set_theme(String.t()) :: :ok

Switches the active theme by name.

@spec set_timeout(pos_integer(), atom()) :: :ok

Set a one-time timeout timer

@spec stop_all_animations(atom()) :: :ok

Stop all animations for a widget.

@spec stop_animation(reference()) :: :ok

Stop an animation by its reference.

@spec validate_widget(atom()) :: :ok | {:error, String.t()}

Validate a widget's value. Sends :validate event to widget, triggering its validators.

@spec vertical(
  [{module(), map()}],
  keyword()
) :: {Drafter.Widget.Container, map()}

Create a vertical layout container