@spec draw(terminal_ref(), [{widget(), ExRatatui.Layout.Rect.t()}]) ::
  :ok | {:error, term()}

Draws a list of {widget, rect} tuples to the terminal in a single frame.

Each tuple pairs a widget struct (e.g. %Paragraph{}, %Table{}) with a %Rect{} that defines where to render it. Returns :ok on success or {:error, reason} on failure.

Examples

iex> terminal = ExRatatui.init_test_terminal(40, 10)
iex> paragraph = %ExRatatui.Widgets.Paragraph{text: "Hello!"}
iex> rect = %ExRatatui.Layout.Rect{x: 0, y: 0, width: 40, height: 10}
iex> ExRatatui.draw(terminal, [{paragraph, rect}])
:ok

@spec get_buffer_content(terminal_ref()) :: String.t() | {:error, term()}

Returns the test terminal's buffer contents as a string.

Each line is trimmed of trailing whitespace and joined with newlines. Only works with a test terminal reference from init_test_terminal/2.

Examples

iex> terminal = ExRatatui.init_test_terminal(20, 3)
iex> paragraph = %ExRatatui.Widgets.Paragraph{text: "Hi there"}
iex> rect = %ExRatatui.Layout.Rect{x: 0, y: 0, width: 20, height: 3}
iex> ExRatatui.draw(terminal, [{paragraph, rect}])
iex> ExRatatui.get_buffer_content(terminal) =~ "Hi there"
true

@spec init_test_terminal(non_neg_integer(), non_neg_integer()) ::
  terminal_ref() | {:error, term()}

Initializes a headless test terminal with the given dimensions.

Takes width (columns) and height (rows) for the virtual terminal. Uses ratatui's TestBackend — no real terminal needed. Useful for testing rendering output without a TTY. Returns a terminal reference.

Examples

iex> terminal = ExRatatui.init_test_terminal(40, 10)
iex> is_reference(terminal)
true

iex> terminal = ExRatatui.init_test_terminal(40, 10)
iex> alias ExRatatui.Widgets.Paragraph
iex> alias ExRatatui.Layout.Rect
iex> :ok = ExRatatui.draw(terminal, [{%Paragraph{text: "Hello!"}, %Rect{x: 0, y: 0, width: 40, height: 10}}])
iex> ExRatatui.get_buffer_content(terminal) =~ "Hello!"
true

@spec poll_event(non_neg_integer()) :: ExRatatui.Event.t() | nil | {:error, term()}

Polls for terminal events with a timeout (default 250ms).

Returns an Event.Key, Event.Mouse, Event.Resize struct, nil if no event within the timeout, or {:error, reason} on failure.

@spec run((terminal_ref() -> term())) :: term() | {:error, term()}

Runs a TUI application.

Initializes the terminal, calls fun with the terminal reference, and ensures terminal cleanup on exit.

ExRatatui.run(fn terminal ->
  # your TUI loop here
end)

@spec terminal_size() :: {non_neg_integer(), non_neg_integer()} | {:error, term()}

Returns the current terminal size as {width, height}.

Returns {:error, reason} if the terminal size cannot be determined.

@spec text_input_cursor(reference()) :: non_neg_integer()

Returns the current cursor position from the TextInput state.

Examples

iex> state = ExRatatui.text_input_new()
iex> ExRatatui.text_input_cursor(state)
0
iex> ExRatatui.text_input_handle_key(state, "a")
:ok
iex> ExRatatui.text_input_cursor(state)
1

@spec text_input_get_value(reference()) :: String.t()

Returns the current text value from the TextInput state.

Examples

iex> state = ExRatatui.text_input_new()
iex> ExRatatui.text_input_get_value(state)
""

@spec text_input_handle_key(reference(), String.t()) :: :ok

Forwards a key event to the TextInput state.

Pass the code field from an ExRatatui.Event.Key struct. Supports printable characters, "backspace", "delete", "left", "right", "home", and "end".

Examples

iex> state = ExRatatui.text_input_new()
iex> ExRatatui.text_input_handle_key(state, "h")
:ok
iex> ExRatatui.text_input_handle_key(state, "i")
:ok
iex> ExRatatui.text_input_get_value(state)
"hi"

@spec text_input_new() :: reference()

Creates a new TextInput state.

Returns a reference to the Rust-side state (ResourceArc). Pass this reference as the :state field of %ExRatatui.Widgets.TextInput{}.

Examples

iex> state = ExRatatui.text_input_new()
iex> is_reference(state)
true

@spec text_input_set_value(reference(), String.t()) :: :ok

Sets the text value on the TextInput state.

The cursor is moved to the end of the new value.

Examples

iex> state = ExRatatui.text_input_new()
iex> ExRatatui.text_input_set_value(state, "hello")
:ok
iex> ExRatatui.text_input_get_value(state)
"hello"

@spec textarea_cursor(reference()) :: {non_neg_integer(), non_neg_integer()}

Returns the cursor position as {row, col} from the Textarea state.

Examples

iex> state = ExRatatui.textarea_new()
iex> ExRatatui.textarea_cursor(state)
{0, 0}

@spec textarea_get_value(reference()) :: String.t()

Returns the current text from the Textarea as a string (lines joined with \n).

Examples

iex> state = ExRatatui.textarea_new()
iex> ExRatatui.textarea_get_value(state)
""

@spec textarea_handle_key(reference(), String.t(), [String.t()]) :: :ok

Forwards a key event with modifiers to the Textarea state.

modifiers is a list of active modifier strings (e.g. ["ctrl"]), defaults to []. The textarea supports Emacs-style shortcuts (Ctrl+Z undo, Ctrl+Y redo, etc.).

Examples

iex> state = ExRatatui.textarea_new()
iex> ExRatatui.textarea_handle_key(state, "h", [])
:ok
iex> ExRatatui.textarea_handle_key(state, "i", [])
:ok
iex> ExRatatui.textarea_get_value(state)
"hi"

@spec textarea_line_count(reference()) :: non_neg_integer()

Returns the number of lines in the Textarea state.

Examples

iex> state = ExRatatui.textarea_new()
iex> ExRatatui.textarea_line_count(state)
1

@spec textarea_new() :: reference()

Creates a new Textarea state.

Returns a reference to the Rust-side state (ResourceArc). Pass this reference as the :state field of %ExRatatui.Widgets.Textarea{}.

Examples

iex> state = ExRatatui.textarea_new()
iex> is_reference(state)
true

@spec textarea_set_value(reference(), String.t()) :: :ok

Sets the text value on the Textarea state.

Examples

iex> state = ExRatatui.textarea_new()
iex> ExRatatui.textarea_set_value(state, "hello\nworld")
:ok
iex> ExRatatui.textarea_get_value(state)
"hello\nworld"