ratatui_ruby-tea 0.2.0 → 0.3.0

data/examples/app_fractal_dashboard/bags/disk_usage.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: MIT-0
+#++
+
+# Fetches and displays disk usage via +df -h+.
+# A bag for fetching and displaying disk usage.
+module DiskUsage
+  Command = RatatuiRuby::Tea::Command
+
+  Model = Data.define(:output, :loading)
+  INITIAL = Model.new(output: "Press 'd' for disk usage", loading: false)
+
+  VIEW = lambda do |model, tui, disabled: false|
+    text_style = if disabled && model.output == INITIAL.output
+      tui.style(fg: :dark_gray)
+    else
+      nil
+    end
+
+    tui.paragraph(
+      text: tui.text_span(content: model.output, style: text_style),
+      block: tui.block(title: "Disk Usage", borders: [:all], border_style: { fg: :cyan })
+    )
+  end
+
+  UPDATE = lambda do |message, model|
+    case message
+    in [:disk_usage, { stdout:, status: 0 }]
+      lines = Ractor.make_shareable(stdout.lines.first(4).join.strip)
+      [model.with(output: lines, loading: false), nil]
+    in [:disk_usage, { stderr:, _status: }]
+      [model.with(output: Ractor.make_shareable("Error: #{stderr.strip}"), loading: false), nil]
+    else
+      [model, nil]
+    end
+  end
+
+  def self.fetch_command
+    Command.system("df -h", :disk_usage)
+  end
+end

data/examples/app_fractal_dashboard/bags/network_panel.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: MIT-0
+#++
+
+require_relative "ping"
+require_relative "uptime"
+
+# Composes Ping and Uptime in a horizontal layout.
+module NetworkPanel
+  Model = Data.define(:ping, :uptime)
+
+  INITIAL = Model.new(
+    ping: Ping::INITIAL,
+    uptime: Uptime::INITIAL
+  )
+
+  VIEW = lambda do |model, tui, disabled: false|
+    tui.layout(
+      direction: :horizontal,
+      constraints: [tui.constraint_percentage(50), tui.constraint_percentage(50)],
+      children: [
+        Ping::VIEW.call(model.ping, tui, disabled:),
+        Uptime::VIEW.call(model.uptime, tui, disabled:),
+      ]
+    )
+  end
+
+  UPDATE = lambda do |message, model|
+    case message
+    in [:ping, *rest]
+      child_message = [:ping, *rest]
+      new_child, command = Ping::UPDATE.call(child_message, model.ping)
+      [model.with(ping: new_child), command]
+    in [:uptime, *rest]
+      child_message = [:uptime, *rest]
+      new_child, command = Uptime::UPDATE.call(child_message, model.uptime)
+      [model.with(uptime: new_child), command]
+    else
+      [model, nil]
+    end
+  end
+end

data/examples/app_fractal_dashboard/bags/ping.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: MIT-0
+#++
+
+# Pings localhost to check network connectivity.
+# A bag for pinging localhost.
+module Ping
+  Command = RatatuiRuby::Tea::Command
+
+  Model = Data.define(:output, :loading)
+  INITIAL = Model.new(output: "Press 'p' for ping", loading: false)
+
+  VIEW = lambda do |model, tui, disabled: false|
+    text_style = if disabled && model.output == INITIAL.output
+      tui.style(fg: :dark_gray)
+    else
+      nil
+    end
+
+    tui.paragraph(
+      text: tui.text_span(content: model.output, style: text_style),
+      block: tui.block(title: "Ping", borders: [:all], border_style: { fg: :magenta })
+    )
+  end
+
+  UPDATE = lambda do |message, model|
+    case message
+    in [:ping, { stdout:, status: 0 }]
+      [model.with(output: Ractor.make_shareable(stdout.strip), loading: false), nil]
+    in [:ping, { stderr:, _status: }]
+      [model.with(output: Ractor.make_shareable("Error: #{stderr.strip}"), loading: false), nil]
+    else
+      [model, nil]
+    end
+  end
+
+  def self.fetch_command
+    Command.system("ping -c 1 localhost", :ping)
+  end
+end

data/examples/app_fractal_dashboard/bags/stats_panel.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: MIT-0
+#++
+
+require_relative "system_info"
+require_relative "disk_usage"
+
+# Composes SystemInfo and DiskUsage in a horizontal layout.
+module StatsPanel
+  Model = Data.define(:system_info, :disk_usage)
+
+  INITIAL = Model.new(
+    system_info: SystemInfo::INITIAL,
+    disk_usage: DiskUsage::INITIAL
+  )
+
+  VIEW = lambda do |model, tui, disabled: false|
+    tui.layout(
+      direction: :horizontal,
+      constraints: [tui.constraint_percentage(50), tui.constraint_percentage(50)],
+      children: [
+        SystemInfo::VIEW.call(model.system_info, tui, disabled:),
+        DiskUsage::VIEW.call(model.disk_usage, tui, disabled:),
+      ]
+    )
+  end
+
+  UPDATE = lambda do |message, model|
+    case message
+    in [:system_info, *rest]
+      child_message = [:system_info, *rest]
+      new_child, command = SystemInfo::UPDATE.call(child_message, model.system_info)
+      [model.with(system_info: new_child), command]
+    in [:disk_usage, *rest]
+      child_message = [:disk_usage, *rest]
+      new_child, command = DiskUsage::UPDATE.call(child_message, model.disk_usage)
+      [model.with(disk_usage: new_child), command]
+    else
+      [model, nil]
+    end
+  end
+end

data/examples/app_fractal_dashboard/bags/system_info.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: MIT-0
+#++
+
+# Fetches and displays system information via +uname -a+.
+# A bag for fetching and displaying system information.
+module SystemInfo
+  Command = RatatuiRuby::Tea::Command
+
+  Model = Data.define(:output, :loading)
+  INITIAL = Model.new(output: "Press 's' for system info", loading: false)
+
+  VIEW = lambda do |model, tui, disabled: false|
+    text_style = if disabled && model.output == INITIAL.output
+      tui.style(fg: :dark_gray)
+    else
+      nil
+    end
+
+    tui.paragraph(
+      text: tui.text_span(content: model.output, style: text_style),
+      block: tui.block(title: "System Info", borders: [:all], border_style: { fg: :cyan })
+    )
+  end
+
+  UPDATE = lambda do |message, model|
+    case message
+    in [:system_info, { stdout:, status: 0 }]
+      [model.with(output: Ractor.make_shareable(stdout.strip), loading: false), nil]
+    in [:system_info, { stderr:, _status: }]
+      [model.with(output: Ractor.make_shareable("Error: #{stderr.strip}"), loading: false), nil]
+    else
+      [model, nil]
+    end
+  end
+
+  def self.fetch_command
+    Command.system("uname -a", :system_info)
+  end
+end

data/examples/app_fractal_dashboard/bags/uptime.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: MIT-0
+#++
+
+# Displays system uptime.
+# A bag for displaying system uptime.
+module Uptime
+  Command = RatatuiRuby::Tea::Command
+
+  Model = Data.define(:output, :loading)
+  INITIAL = Model.new(output: "Press 'u' for uptime", loading: false)
+
+  VIEW = lambda do |model, tui, disabled: false|
+    text_style = if disabled && model.output == INITIAL.output
+      tui.style(fg: :dark_gray)
+    else
+      nil
+    end
+
+    tui.paragraph(
+      text: tui.text_span(content: model.output, style: text_style),
+      block: tui.block(title: "Uptime", borders: [:all], border_style: { fg: :magenta })
+    )
+  end
+
+  UPDATE = lambda do |message, model|
+    case message
+    in [:uptime, { stdout:, status: 0 }]
+      [model.with(output: Ractor.make_shareable(stdout.strip), loading: false), nil]
+    in [:uptime, { stderr:, _status: }]
+      [model.with(output: Ractor.make_shareable("Error: #{stderr.strip}"), loading: false), nil]
+    else
+      [model, nil]
+    end
+  end
+
+  def self.fetch_command
+    Command.system("uptime", :uptime)
+  end
+end

data/examples/app_fractal_dashboard/dashboard/base.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: MIT-0
+#++
+
+require_relative "../bags/stats_panel"
+require_relative "../bags/network_panel"
+require_relative "../bags/custom_shell_modal"
+
+# Shared Model, INITIAL, and VIEW for the Dashboard.
+#
+# This module is extended by the three UPDATE variants to demonstrate
+# the progression from verbose manual routing to declarative DSL.
+module DashboardBase
+  Command = RatatuiRuby::Tea::Command
+
+  Model = Data.define(:stats, :network, :shell_modal)
+
+  INITIAL = Model.new(
+    stats: StatsPanel::INITIAL,
+    network: NetworkPanel::INITIAL,
+    shell_modal: CustomShellModal::INITIAL
+  )
+
+  VIEW = lambda do |model, tui|
+    modal_active = CustomShellModal.active?(model.shell_modal)
+    hotkey, label_style = if modal_active
+      [tui.style(fg: :dark_gray), tui.style(fg: :dark_gray)]
+    else
+      [tui.style(modifiers: [:bold, :underlined]), nil]
+    end
+    dim = tui.style(fg: :dark_gray)
+
+    controls = tui.paragraph(
+      text: [
+        tui.text_line(spans: [
+          tui.text_span(content: "s", style: hotkey),
+          tui.text_span(content: ": System  ", style: label_style),
+          tui.text_span(content: "d", style: hotkey),
+          tui.text_span(content: ": Disk  ", style: label_style),
+          tui.text_span(content: "p", style: hotkey),
+          tui.text_span(content: ": Ping  ", style: label_style),
+          tui.text_span(content: "u", style: hotkey),
+          tui.text_span(content: ": Uptime  ", style: label_style),
+          tui.text_span(content: "c", style: hotkey),
+          tui.text_span(content: ": Custom  ", style: label_style),
+          tui.text_span(content: "q", style: hotkey),
+          tui.text_span(content: ": Quit", style: label_style),
+        ]),
+      ],
+      block: tui.block(title: "Fractal Dashboard", borders: [:all], border_style: dim)
+    )
+
+    dashboard = tui.layout(
+      direction: :vertical,
+      constraints: [tui.constraint_fill(1), tui.constraint_fill(1), tui.constraint_length(3)],
+      children: [
+        StatsPanel::VIEW.call(model.stats, tui, disabled: modal_active),
+        NetworkPanel::VIEW.call(model.network, tui, disabled: modal_active),
+        controls,
+      ]
+    )
+
+    # Compose modal overlay if active
+    modal_widget = CustomShellModal::VIEW.call(model.shell_modal, tui)
+    if modal_widget
+      tui.overlay(layers: [dashboard, modal_widget])
+    else
+      dashboard
+    end
+  end
+end

data/examples/app_fractal_dashboard/dashboard/update_helpers.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: MIT-0
+#++
+
+require_relative "base"
+
+# UPDATE using Tea.route and Tea.delegate helpers.
+#
+# This is the medium-verbosity approach: routing helpers reduce boilerplate
+# while keeping the case statement visible. A good middle ground.
+module DashboardHelpers
+  Command = RatatuiRuby::Tea::Command
+  Tea = RatatuiRuby::Tea
+
+  # Shared with other UPDATE variants
+  Model = DashboardBase::Model
+  INITIAL = DashboardBase::INITIAL
+  VIEW = DashboardBase::VIEW
+
+  UPDATE = lambda do |message, model|
+    # Global Force Quit
+    return [model, RatatuiRuby::Tea::Command.exit] if message.respond_to?(:ctrl_c?) && message.ctrl_c?
+
+    # IMPORTANT: Route command results BEFORE modal intercept.
+    # Async command results must always reach their destination, even when a
+    # modal is active. Only user input (keys/mouse) should be blocked.
+
+    # Route streaming command output to modal
+    if (result = Tea.delegate(message, :shell_output, CustomShellModal::UPDATE, model.shell_modal))
+      new_modal, command = result
+      return [model.with(shell_modal: new_modal), command]
+    end
+
+    # Route to child bags
+    if (result = Tea.delegate(message, :stats, StatsPanel::UPDATE, model.stats))
+      new_child, command = result
+      return [model.with(stats: new_child), command && Tea.route(command, :stats)]
+    end
+
+    if (result = Tea.delegate(message, :network, NetworkPanel::UPDATE, model.network))
+      new_child, command = result
+      return [model.with(network: new_child), command && Tea.route(command, :network)]
+    end
+
+    # Modal intercepts user input (not command results)
+    if CustomShellModal.active?(model.shell_modal)
+      new_modal, command = CustomShellModal::UPDATE.call(message, model.shell_modal)
+      return [model.with(shell_modal: new_modal), command]
+    end
+
+    # Handle user input
+    case message
+    in _ if message.q? || message.ctrl_c?
+      Command.exit
+
+    in _ if message.c?
+      [model.with(shell_modal: CustomShellModal.open), nil]
+
+    in _ if message.s?
+      command = Tea.route(SystemInfo.fetch_command, :stats)
+      new_stats = model.stats.with(system_info: model.stats.system_info.with(loading: true))
+      [model.with(stats: new_stats), command]
+
+    in _ if message.d?
+      command = Tea.route(DiskUsage.fetch_command, :stats)
+      new_stats = model.stats.with(disk_usage: model.stats.disk_usage.with(loading: true))
+      [model.with(stats: new_stats), command]
+
+    in _ if message.p?
+      command = Tea.route(Ping.fetch_command, :network)
+      new_network = model.network.with(ping: model.network.ping.with(loading: true))
+      [model.with(network: new_network), command]
+
+    in _ if message.u?
+      command = Tea.route(Uptime.fetch_command, :network)
+      new_network = model.network.with(uptime: model.network.uptime.with(loading: true))
+      [model.with(network: new_network), command]
+
+    else
+      model
+    end
+  end
+end

data/examples/app_fractal_dashboard/dashboard/update_manual.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: MIT-0
+#++
+
+require_relative "base"
+
+# UPDATE using verbose manual routing.
+#
+# This is the most explicit approach: full pattern matching, explicit
+# Command.map calls, manual model updates. Maximum control, maximum boilerplate.
+module DashboardManual
+  Command = RatatuiRuby::Tea::Command
+
+  # Shared with other UPDATE variants
+  Model = DashboardBase::Model
+  INITIAL = DashboardBase::INITIAL
+  VIEW = DashboardBase::VIEW
+
+  UPDATE = lambda do |message, model|
+    # Global Force Quit
+    return [model, RatatuiRuby::Tea::Command.exit] if message.respond_to?(:ctrl_c?) && message.ctrl_c?
+
+    # IMPORTANT: Route command results BEFORE modal intercept.
+    # Async command results must always reach their destination, even when a
+    # modal is active. Only user input (keys/mouse) should be blocked.
+    case message
+    # Route command results to panels
+    in [:stats, *rest]
+      new_panel, command = StatsPanel::UPDATE.call(rest, model.stats)
+      mapped_command = command ? Command.map(command) { |child_result| [:stats, *child_result] } : nil
+      return [model.with(stats: new_panel), mapped_command]
+
+    in [:network, *rest]
+      new_panel, command = NetworkPanel::UPDATE.call(rest, model.network)
+      mapped_command = command ? Command.map(command) { |child_result| [:network, *child_result] } : nil
+      return [model.with(network: new_panel), mapped_command]
+
+    in [:shell_output, *rest]
+      # Route streaming command output to modal
+      new_modal, command = CustomShellModal::UPDATE.call(message, model.shell_modal)
+      return [model.with(shell_modal: new_modal), command]
+    else
+      nil # Fall through to input handling
+    end
+
+    # Modal intercepts user input (not command results)
+    if CustomShellModal.active?(model.shell_modal)
+      new_modal, command = CustomShellModal::UPDATE.call(message, model.shell_modal)
+      return [model.with(shell_modal: new_modal), command]
+    end
+
+    case message
+    # Handle user input
+    in _ if message.q? || message.ctrl_c?
+      Command.exit
+
+    in _ if message.c?
+      [model.with(shell_modal: CustomShellModal.open), nil]
+
+    in _ if message.s?
+      command = Command.map(SystemInfo.fetch_command) { |r| [:stats, *r] }
+      new_stats = model.stats.with(system_info: model.stats.system_info.with(loading: true))
+      [model.with(stats: new_stats), command]
+
+    in _ if message.d?
+      command = Command.map(DiskUsage.fetch_command) { |r| [:stats, *r] }
+      new_stats = model.stats.with(disk_usage: model.stats.disk_usage.with(loading: true))
+      [model.with(stats: new_stats), command]
+
+    in _ if message.p?
+      command = Command.map(Ping.fetch_command) { |r| [:network, *r] }
+      new_network = model.network.with(ping: model.network.ping.with(loading: true))
+      [model.with(network: new_network), command]
+
+    in _ if message.u?
+      command = Command.map(Uptime.fetch_command) { |r| [:network, *r] }
+      new_network = model.network.with(uptime: model.network.uptime.with(loading: true))
+      [model.with(network: new_network), command]
+
+    else
+      model
+    end
+  end
+end

data/examples/app_fractal_dashboard/dashboard/update_router.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: MIT-0
+#++
+
+require_relative "base"
+
+# UPDATE using the declarative Tea::Router DSL.
+#
+# This is the minimal-boilerplate approach: declare routes and keymaps,
+# let from_router generate the UPDATE lambda. Maximum DX, least control.
+module DashboardRouter
+  include RatatuiRuby::Tea::Router
+
+  Command = RatatuiRuby::Tea::Command
+
+  # Shared with other UPDATE variants
+  Model = DashboardBase::Model
+  INITIAL = DashboardBase::INITIAL
+  VIEW = DashboardBase::VIEW
+
+  route :stats, to: StatsPanel
+  route :network, to: NetworkPanel
+
+  # Guard: only handle keys when modal is not active
+  MODAL_INACTIVE = -> (model) { !CustomShellModal.active?(model.shell_modal) }
+
+  keymap do
+    key :ctrl_c, -> { Command.exit }
+    only when: MODAL_INACTIVE do
+      key :q, -> { Command.exit }
+      key :s, -> { SystemInfo.fetch_command }
+      key :d, -> { DiskUsage.fetch_command }
+      key :p, -> { Ping.fetch_command }
+      key :u, -> { Uptime.fetch_command }
+      key :c, -> { CustomShellModal.open }
+    end
+  end
+
+  UPDATE = from_router
+end

data/examples/verify_readme_usage/README.md

@@ -35,7 +35,7 @@ end
 
 UPDATE = -> (msg, model) do
   if msg.q? || msg.ctrl_c?
-    RatatuiRuby::Tea::Cmd.quit
+    RatatuiRuby::Tea::Command.exit
   else
     model
   end

data/examples/verify_readme_usage/app.rb

@@ -29,7 +29,7 @@ class VerifyReadmeUsage
 
   UPDATE = -> (msg, model) do
     if msg.q? || msg.ctrl_c?
-      RatatuiRuby::Tea::Cmd.quit
+      RatatuiRuby::Tea::Command.exit
     else
       model
     end

data/examples/{widget_cmd_exec → widget_command_system}/app.rb

@@ -10,7 +10,7 @@ $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 require "ratatui_ruby"
 require "ratatui_ruby/tea"
 
-# Demonstrates the Cmd.exec command for running shell commands.
+# Demonstrates the Command.execute command for running shell commands.
 #
 # This example shows how to execute shell commands and handle both success
 # and failure cases using pattern matching in update. The split layout shows
@@ -23,7 +23,7 @@ require "ratatui_ruby/tea"
 #   ruby examples/widget_cmd_exec/app.rb
 #
 # rdoc-image:/doc/images/widget_cmd_exec.png
-class WidgetCmdExec
+class WidgetCommandSystem
   Model = Data.define(:result, :loading, :last_command)
   INITIAL = Model.new(
     result: "Press a key to run a command...",
@@ -44,7 +44,7 @@ class WidgetCmdExec
       "cyan"
     end
 
-    title = model.last_command ? "Output: #{model.last_command}" : "Cmd.exec Demo"
+    title = model.last_command ? "Output: #{model.last_command}" : "Command.execute Demo"
     content_text = model.loading ? "Running command..." : model.result
 
     # 1. Main Output Widget
@@ -97,8 +97,8 @@ class WidgetCmdExec
     )
   end
 
-  UPDATE = -> (msg, model) do
-    case msg
+  UPDATE = -> (message, model) do
+    case message
     # Handle command results
     in [:got_output, { stdout:, status: 0 }]
       [model.with(result: stdout.strip.freeze, loading: false), nil]
@@ -106,19 +106,19 @@ class WidgetCmdExec
       [model.with(result: "Error (exit #{status}): #{stderr.strip}".freeze, loading: false), nil]
 
     # Handle key presses
-    in _ if msg.q? || msg.ctrl_c?
-      RatatuiRuby::Tea::Cmd.quit
-    in _ if msg.d?
-      [model.with(loading: true, last_command: "ls -la"), RatatuiRuby::Tea::Cmd.exec("ls -la", :got_output)]
-    in _ if msg.u?
-      [model.with(loading: true, last_command: "uname -a"), RatatuiRuby::Tea::Cmd.exec("uname -a", :got_output)]
-    in _ if msg.s?
-      cmd = "sleep 3 && echo 'Slept for 3s'"
-      [model.with(loading: true, last_command: cmd.freeze), RatatuiRuby::Tea::Cmd.exec(cmd, :got_output)]
-    in _ if msg.f?
+    in _ if message.q? || message.ctrl_c?
+      RatatuiRuby::Tea::Command.exit
+    in _ if message.d?
+      [model.with(loading: true, last_command: "ls -la"), RatatuiRuby::Tea::Command.system("ls -la", :got_output)]
+    in _ if message.u?
+      [model.with(loading: true, last_command: "uname -a"), RatatuiRuby::Tea::Command.system("uname -a", :got_output)]
+    in _ if message.s?
+      command = "sleep 3 && echo 'Slept for 3s'"
+      [model.with(loading: true, last_command: cmd.freeze), RatatuiRuby::Tea::Command.system(cmd, :got_output)]
+    in _ if message.f?
       # Intentional failure to demonstrate error handling
-      cmd = "ls /nonexistent_path_12345"
-      [model.with(loading: true, last_command: cmd.freeze), RatatuiRuby::Tea::Cmd.exec(cmd, :got_output)]
+      command = "ls /nonexistent_path_12345"
+      [model.with(loading: true, last_command: cmd.freeze), RatatuiRuby::Tea::Command.system(cmd, :got_output)]
     else
       model
     end
@@ -129,4 +129,4 @@ class WidgetCmdExec
   end
 end
 
-WidgetCmdExec.new.run if __FILE__ == $PROGRAM_NAME
+WidgetCommandSystem.new.run if __FILE__ == $PROGRAM_NAME