module RatatuiRuby::Tea

The Elm Architecture for RatatuiRuby.

Building TUI applications means managing state, events, and rendering. Mixing them leads to spaghetti code. Bugs hide in the tangles.

This module implements The Elm Architecture (TEA). It separates your application into three pure functions: model, view, and update. The runtime handles the rest.

Use it to build applications with predictable, testable state management.

Constants

VERSION: The version of this gem. See semver.org/spec/v2.0.0.html

Public Class Methods

delegate (message, prefix, child_update, child_model)

Source

# File lib/ratatui_ruby/tea.rb, line 79
def self.delegate(message, prefix, child_update, child_model)
  return nil unless message.is_a?(Array) && message.first == prefix

  rest = message[1..]
  new_child, command = child_update.call(rest, child_model)
  wrapped = command ? route(command, prefix) : nil
  [new_child, wrapped]
end

Delegates a prefixed message to a child bag’s UPDATE.

Parent bag UPDATE functions route messages to child bags. Each route requires pattern matching, calling the child, and rewrapping any returned command. The boilerplate adds up fast.

This method handles the dispatch. It checks the prefix, calls the child, and wraps any command. Returns nil if the prefix does not match.

message: Incoming message (e.g., [:stats, :system_info, {...}]).
prefix: Expected prefix symbol (e.g., :stats).
child_update: The child’s UPDATE callable.
child_model: The child’s current model.

Example

# Verbose:
case message
in [:stats, *rest]
  new_child, cmd = StatsPanel::UPDATE.call(rest, model.stats)
  mapped = cmd ? Command.map(cmd) { |r| [:stats, *r] } : nil
  [new_child, mapped]
end

# Concise:
Tea.delegate(message, :stats, StatsPanel::UPDATE, model.stats)

route (command, prefix)

Source

# File lib/ratatui_ruby/tea.rb, line 49
def self.route(command, prefix)
  Command.map(command) { |result| [prefix, *result] }
end

Wraps a command with a routing prefix.

Parent bags trigger child bag commands. The results need routing back to the correct child bag. Manually wrapping every command is tedious.

This method prefixes command results automatically. Use it to route child bag command results in Fractal Architecture.

command: The child bag command to wrap.
prefix: Symbol prepended to results (e.g., :stats).

Example

# Verbose:
Command.map(child_bag.fetch_command) { |r| [:stats, *r] }

# Concise:
Tea.route(child_bag.fetch_command, :stats)

run (...)

Source

# File lib/ratatui_ruby/tea.rb, line 27
def self.run(...)
  Runtime.run(...)
end

Starts the MVU event loop.

Convenience delegator to Runtime.run. See Runtime for full documentation.