class RatatuiRuby::TUI

Manages the terminal lifecycle and provides a concise API for the render loop.

Writing a TUI loop involves repetitive boilerplate. You constantly instantiate widgets (RatatuiRuby::Widgets::Paragraph.new) and call global methods (RatatuiRuby.draw). This is verbose and hard to read.

The Session object simplifies this. It acts as a factory and a facade. It provides short helper methods for every widget and delegates core commands to the main module.

Use it within RatatuiRuby.run to build your interface cleanly.

“Do What I Mean” (DWIM) Coercion

The TUI factories add a *DWIM argument coercion layer* that the underlying Widget classes don’t have. This means:

• tui.table(rows: [...]) coerces types, normalizes arrays, etc.

• RatatuiRuby::Widgets::Table.new(rows: [...]) passes arguments directly to Rust without coercion — invalid types will raise TypeError.

If you bypass the factories and call Widgets::Table.new directly, you’re responsible for providing correctly-typed arguments. This is useful for debugging (to trigger real Rust TypeErrors) or performance-critical code.

Thread/Ractor Safety

Session is an *I/O handle*, not a data object. It has side effects (draw, poll_event) and is intentionally not Ractor-shareable. Caching it in instance variables (@tui = tui) during your application’s run loop is fine. However, do not include it in immutable Models/Messages or pass it to other Ractors.

Included Mixins

Core

Terminal operations: draw, poll_event, get_cell_at, draw_cell.

LayoutFactories

Layout helpers: rect, constraint_*, layout, layout_split.

StyleFactories

Style helpers: style.

WidgetFactories

Widget creation: block, paragraph, list, table, etc. (DWIM coercion)

TextFactories

Text helpers: span, line, text_width.

StateFactories

State objects: list_state, table_state, scrollbar_state.

CanvasFactories

Canvas shapes: shape_map, shape_line, shape_point, etc.

BufferFactories

Buffer inspection: cell.

Examples

Basic Usage (Recommended)

RatatuiRuby.run do |tui|
  loop do
    tui.draw \
      tui.paragraph \
          text: "Hello, Ratatui! Press 'q' to quit.",
          alignment: :center,
          block: tui.block(
            title: "My Ruby TUI App",
            borders: [:all],
            border_style: { fg: \"cyan\" }
          )
    event = tui.poll_event
    break if event == "q" || event == :ctrl_c
  end
end