rooibos 0.5.0

data/examples/app_fractal_dashboard/fragments/ping.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: MIT-0
+#++
+
+require "rooibos"
+# Pings localhost to check network connectivity.
+# A fragment for pinging localhost.
+module Ping
+  Command = Rooibos::Command
+
+  Model = Data.define(:output, :loading)
+
+  Init = -> do
+    Model.new(output: "Press 'p' for ping", loading: false)
+  end
+
+  View = -> (model, tui, disabled: false) do
+    text_style = if disabled && model.output == Init.().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 = -> (message, model) do
+    case message
+    in [{ type: :system, envelope: :ping, status: 0, stdout: }]
+      [model.with(output: Ractor.make_shareable(stdout.strip), loading: false), nil]
+    in [{ type: :system, envelope: :ping, stderr: }]
+      [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 3 8.8.8.8", :ping)
+  end
+end

data/examples/app_fractal_dashboard/fragments/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 "rooibos"
+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)
+
+  Init = -> do
+    system_info, = Rooibos.normalize_init(SystemInfo::Init.())
+    disk_usage, = Rooibos.normalize_init(DiskUsage::Init.())
+    Model.new(system_info:, disk_usage:)
+  end
+
+  View = -> (model, tui, disabled: false) do
+    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 = -> (message, model) do
+    case message
+    in [:system_info, *rest]
+      new_child, command = SystemInfo::Update.call(rest, model.system_info)
+      [model.with(system_info: new_child), command]
+    in [:disk_usage, *rest]
+      new_child, command = DiskUsage::Update.call(rest, model.disk_usage)
+      [model.with(disk_usage: new_child), command]
+    else
+      [model, nil]
+    end
+  end
+end

data/examples/app_fractal_dashboard/fragments/system_info.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: MIT-0
+#++
+
+require "rooibos"
+# Fetches and displays system information via +uname -a+.
+# A fragment for fetching and displaying system information.
+module SystemInfo
+  Command = Rooibos::Command
+
+  Model = Data.define(:output, :loading)
+
+  Init = -> do
+    Model.new(output: "Press 's' for system info", loading: false)
+  end
+
+  View = -> (model, tui, disabled: false) do
+    text_style = if disabled && model.output == Init.().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 = -> (message, model) do
+    case message
+    in [{ type: :system, envelope: :system_info, status: 0, stdout: }]
+      [model.with(output: Ractor.make_shareable(stdout.strip), loading: false), nil]
+    in [{ type: :system, envelope: :system_info, stderr: }]
+      [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/fragments/uptime.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: MIT-0
+#++
+
+require "rooibos"
+# Displays system uptime.
+# A fragment for displaying system uptime.
+module Uptime
+  Command = Rooibos::Command
+
+  Model = Data.define(:output, :loading)
+
+  Init = -> do
+    Model.new(output: "Press 'u' for uptime", loading: false)
+  end
+
+  View = -> (model, tui, disabled: false) do
+    text_style = if disabled && model.output == Init.().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 = -> (message, model) do
+    case message
+    in [{ type: :system, envelope: :uptime, status: 0, stdout: }]
+      [model.with(output: Ractor.make_shareable(stdout.strip), loading: false), nil]
+    in [{ type: :system, envelope: :uptime, stderr: }]
+      [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/verify_readme_usage/README.md

@@ -0,0 +1,54 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# README Usage Verification
+
+Verifies the primary usage example for the Rooibos gem.
+
+This example exists as a documentation regression test. It ensures that the very first MVU pattern a user sees actually works.
+
+## Usage
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+<!-- SYNC:START:./app.rb:mvu -->
+```ruby
+Model = Data.define(:text)
+
+Init = -> do
+  Model.new(text: "Hello, Ratatui! Press 'q' to quit.")
+end
+
+View = -> (model, tui) do
+  tui.paragraph(
+    text: model.text,
+    alignment: :center,
+    block: tui.block(
+      title: "My Ruby TUI App",
+      borders: [:all],
+      border_style: { fg: "cyan" }
+    )
+  )
+end
+
+Update = -> (msg, model) do
+  if msg.q? || msg.ctrl_c?
+    Rooibos::Command.exit
+  else
+    model
+  end
+end
+
+def run
+  Rooibos.run(VerifyReadmeUsage)
+end
+```
+<!-- SYNC:END -->
+<!-- SPDX-SnippetEnd -->
+
+[![verify_readme_usage](../../doc/images/verify_readme_usage.png)](../../README.md#usage)

data/examples/verify_readme_usage/app.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: MIT-0
+#++
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+
+require "ratatui_ruby"
+require "rooibos"
+
+class VerifyReadmeUsage
+  # [SYNC:START:mvu]
+  Model = Data.define(:text)
+
+  Init = -> do
+    Model.new(text: "Hello, Ratatui! Press 'q' to quit.")
+  end
+
+  View = -> (model, tui) do
+    tui.paragraph(
+      text: model.text,
+      alignment: :center,
+      block: tui.block(
+        title: "My Ruby TUI App",
+        borders: [:all],
+        border_style: { fg: "cyan" }
+      )
+    )
+  end
+
+  Update = -> (msg, model) do
+    if msg.q? || msg.ctrl_c?
+      Rooibos::Command.exit
+    else
+      model
+    end
+  end
+
+  def run
+    Rooibos.run(VerifyReadmeUsage)
+  end
+  # [SYNC:END:mvu]
+end
+
+VerifyReadmeUsage.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_command_system/README.md

@@ -0,0 +1,70 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+# Cmd.exec Example
+
+Demonstrates running shell commands using `Cmd.exec`.
+
+Commands in TEA produce **messages**, not callbacks. When a command completes, the runtime sends a tagged tuple to your `update` function. Pattern match on the tag to handle success and failure.
+
+## Key Concepts
+
+- **Message Tags:** `Cmd.exec(command, tag)` produces `[tag, {stdout:, stderr:, status:}]`.
+- **Non-Blocking:** Commands run in background threads. The UI remains responsive.
+- **Success Handling:** Match on `status: 0` to handle successful execution.
+- **Error Handling:** Match on non-zero status to handle failures.
+- **Ractor-Safe:** No callbacks means no Proc captures. Messages are shareable.
+
+## Hotkeys
+
+- `d`: Run `ls -la` (directory listing)
+- `u`: Run `uname -a` (system info)
+- `f`: Run a command that fails (demonstrates error handling)
+- `q`: **Quit**
+
+## Usage
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```bash
+ruby examples/widget_cmd_exec/app.rb
+```
+<!-- SPDX-SnippetEnd -->
+
+## How It Works
+
+The update function handles both key presses and command results:
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+UPDATE = -> (msg, model) do
+  case msg
+  # Handle command results
+  in [:got_output, {stdout:, status: 0}]
+    [model.with(result: stdout.strip, loading: false), nil]
+  in [:got_output, {stderr:, status:}]
+    [model.with(result: "Error (exit #{status}): #{stderr.strip}", loading: false), nil]
+
+  # Handle key presses
+  in _ if msg.d?
+    [model.with(loading: true), Cmd.exec("ls -la", :got_output)]
+  else
+    model
+  end
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+All logic stays in `update`. The command just runs and produces a message.
+
+[Read the source code →](app.rb)
+
+[![widget_cmd_exec](../../doc/images/widget_cmd_exec.png)](app.rb)

data/examples/widget_command_system/app.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: MIT-0
+#++
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+
+require "ratatui_ruby"
+require "rooibos"
+
+# 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
+# command output in the main area with controls at the bottom.
+#
+# === Examples
+#
+# Run the demo from the terminal:
+#
+#   ruby examples/widget_cmd_exec/app.rb
+#
+# rdoc-image:/doc/images/widget_cmd_exec.png
+class WidgetCommandSystem
+  Model = Data.define(:result, :loading, :last_command)
+  INITIAL = Model.new(
+    result: "Press a key to run a command...",
+    loading: false,
+    last_command: nil
+  )
+
+  VIEW = -> (model, tui) do
+    hotkey_style = tui.style(modifiers: [:bold, :underlined])
+    dim_style = tui.style(fg: :dark_gray)
+
+    # Styles
+    border_color = if model.loading
+      "yellow"
+    elsif model.result.start_with?("Error")
+      "red"
+    else
+      "cyan"
+    end
+
+    title = model.last_command ? "Output: #{model.last_command}" : "Command.execute Demo"
+    content_text = model.loading ? "Running command..." : model.result
+
+    # 1. Main Output Widget
+    output_widget = tui.paragraph(
+      text: content_text,
+      block: tui.block(
+        title:,
+        borders: [:all],
+        border_style: { fg: border_color },
+        padding: 1
+      )
+    )
+
+    # 2. Control Panel Widget
+    control_widget = tui.paragraph(
+      text: [
+        tui.text_line(spans: [
+          tui.text_span(content: "d", style: hotkey_style),
+          tui.text_span(content: ": Directory listing (ls -la)  "),
+          tui.text_span(content: "u", style: hotkey_style),
+          tui.text_span(content: ": System info (uname -a)"),
+        ]),
+        tui.text_line(spans: [
+          tui.text_span(content: "f", style: hotkey_style),
+          tui.text_span(content: ": Force failure  "),
+          tui.text_span(content: "s", style: hotkey_style),
+          tui.text_span(content: ": Sleep (3s)  "),
+          tui.text_span(content: "q", style: hotkey_style),
+          tui.text_span(content: ": Quit"),
+        ]),
+      ],
+      block: tui.block(
+        title: "Controls",
+        borders: [:all],
+        border_style: dim_style
+      )
+    )
+
+    # Return the Root Layout Widget (Blueprint)
+    tui.layout(
+      direction: :vertical,
+      constraints: [
+        tui.constraint_fill(1),
+        tui.constraint_length(6),
+      ],
+      children: [
+        output_widget,
+        control_widget,
+      ]
+    )
+  end
+
+  UPDATE = -> (message, model) do
+    case message
+    # Handle command results
+    in [:got_output, { stdout:, status: 0 }]
+      [model.with(result: stdout.strip.freeze, loading: false), nil]
+    in [:got_output, { stderr:, status: }]
+      [model.with(result: "Error (exit #{status}): #{stderr.strip}".freeze, loading: false), nil]
+
+    # Handle key presses
+    in _ if message.q? || message.ctrl_c?
+      Rooibos::Command.exit
+    in _ if message.d?
+      [model.with(loading: true, last_command: "ls -la"), Rooibos::Command.system("ls -la", :got_output)]
+    in _ if message.u?
+      [model.with(loading: true, last_command: "uname -a"), Rooibos::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), Rooibos::Command.system(cmd, :got_output)]
+    in _ if message.f?
+      # Intentional failure to demonstrate error handling
+      command = "ls /nonexistent_path_12345"
+      [model.with(loading: true, last_command: cmd.freeze), Rooibos::Command.system(cmd, :got_output)]
+    else
+      model
+    end
+  end
+
+  def run
+    Rooibos.run(model: INITIAL, view: VIEW, update: UPDATE)
+  end
+end
+
+WidgetCommandSystem.new.run if __FILE__ == $PROGRAM_NAME

data/lib/rooibos/command/all.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Command
+    # An aggregating parallel command.
+    All = Data.define(:envelope, :commands, :nested) do
+      include Custom
+
+      def self.new(tag, *args)
+        # DWIM: detect nested vs splatted based on call-site arity
+        if args.size == 1 && args.first.is_a?(Array)
+          commands = args.first
+          nested = true
+        else
+          commands = args
+          nested = false
+        end
+
+        if RatatuiRuby::Debug.enabled?
+          commands.each do |cmd|
+            unless Ractor.shareable?(cmd)
+              raise Rooibos::Error::Invariant,
+                "Command is not Ractor-shareable: #{cmd.inspect}\n" \
+                  "Use Ractor.make_shareable or a Data.define command."
+            end
+          end
+        end
+
+        instance = allocate
+        instance.__send__(:initialize, envelope: tag, commands: commands.freeze, nested:)
+        instance
+      end
+
+      def call(out, token)
+        # Early return for empty commands - prevents hang from zip_futures([])
+        if commands.empty?
+          response = Message::All.new(envelope:, results: [].freeze, nested:)
+          out.put(Ractor.make_shareable(response))
+          return
+        end
+
+        child_lifecycle = Lifecycle.new
+
+        futures = commands.map do |command|
+          Concurrent::Promises.future do
+            child_channel = Concurrent::Promises::Channel.new
+            child_outlet = Outlet.new(child_channel, lifecycle: child_lifecycle)
+            command.call(child_outlet, token)
+            child_channel.pop
+          end
+        end
+
+        all_done = Concurrent::Promises.zip_futures(*futures)
+        Concurrent::Promises.any_event(all_done, token.origin).wait
+
+        return out.put(Command.cancel(self)) if token.canceled?
+
+        shareable_results = Ractor.make_shareable(all_done.value!)
+        response = Message::All.new(envelope:, results: shareable_results, nested:)
+        out.put(Ractor.make_shareable(response))
+      end
+    end
+  end
+end

data/lib/rooibos/command/batch.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Command
+    # A fire-and-forget parallel command.
+    #
+    # Applications fetch data from multiple sources. Dashboard panels load
+    # users, stats, and notifications. Waiting sequentially is slow.
+    # Managing threads and error handling manually is error-prone.
+    #
+    # This command runs children in parallel. Each child sends its own messages
+    # independently. The batch completes when all children finish or when
+    # cancellation fires. On cancellation, emits <tt>Command.cancel(self)</tt>.
+    #
+    # Use it for parallel fetches, concurrent refreshes, or any work that
+    # does not need coordinated results.
+    #
+    # === Example
+    #
+    #   def update(msg, model)
+    #     case msg
+    #     in :refresh_all
+    #       batch = Command.batch(
+    #         Command.http(:get, "/users", :users),
+    #         Command.http(:get, "/stats", :stats),
+    #       )
+    #       [model.with(loading: true), batch]
+    #     in :users | :stats
+    #       [model.with(msg => data), nil]
+    #     end
+    #   end
+    class Batch < Data.define(:commands) do
+      include Custom
+
+      # Initialize
+      def self.new(*args)
+        # DWIM: accept (cmd1, cmd2) or ([cmd1, cmd2])
+        commands = (args.size == 1 && args.first.is_a?(Array)) ? args.first : args
+
+        if RatatuiRuby::Debug.enabled?
+          commands.each do |cmd|
+            unless Ractor.shareable?(cmd)
+              raise Rooibos::Error::Invariant,
+                "Command is not Ractor-shareable: #{cmd.inspect}\n" \
+                  "Use Ractor.make_shareable or a Data.define command."
+            end
+          end
+        end
+
+        instance = allocate
+        instance.__send__(:initialize, commands: commands.freeze)
+        instance
+      end
+
+      # Call it
+      def call(out, token)
+        futures = commands.map do |command|
+          Concurrent::Promises.future { command.call(out, token) }
+        end
+
+        all_done = Concurrent::Promises.zip_futures(*futures)
+        Concurrent::Promises.any_event(all_done, token.origin).wait
+
+        # Re-raise any child exception for runtime to wrap in Command::Error
+        futures.each { |f| raise f.reason if f.rejected? }
+
+        out.put(Command.cancel(self)) if token.canceled?
+      end
+    end
+    end
+  end
+end