rooibos 0.6.2 → 0.7.0

data/examples/app_fractal_dashboard/README.md

@@ -1,60 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Cmd.map Fractal Dashboard
-
-Demonstrates **Fractal Architecture** using `Cmd.map` for component composition.
-
-## Problem
-
-Without composition, a complex app needs one giant `case` statement handling every possible message from every child—the "God Reducer" anti-pattern. This doesn't scale.
-
-## Solution
-
-`Cmd.map` wraps child commands so their results route through parents:
-
-```ruby
-# Child produces [:system_info, {stdout:, ...}]
-child_cmd = SystemInfoWidget.fetch_cmd
-
-# Parent wraps to produce [:stats, :system_info, {...}]
-parent_cmd = Cmd.map(child_cmd) { |m| [:stats, *m] }
-```
-
-Each layer handles only its own messages. Parents pattern-match on the first element to route to the correct child.
-
-## Architecture
-
-```
-Dashboard (root)
-├── StatsPanel
-│   ├── SystemInfoWidget → Cmd.exec("uname -a", :system_info)
-│   └── DiskUsageWidget  → Cmd.exec("df -h", :disk_usage)
-└── NetworkPanel
-    ├── PingWidget       → Cmd.exec("ping -c 1 localhost", :ping)
-    └── UptimeWidget     → Cmd.exec("uptime", :uptime)
-```
-
-## Hotkeys
-
-| Key | Action |
-|-----|--------|
-| `s` | Fetch system info |
-| `d` | Fetch disk usage |
-| `p` | Ping localhost |
-| `u` | Fetch uptime |
-| `q` | Quit |
-
-## Key Concepts
-
-1. **Widget isolation**: Each widget has its own `Model`, `UPDATE`, and `fetch_cmd`. It knows nothing about parents.
-2. **Message routing**: Parents prefix child messages (`:stats`, `:network`) and pattern-match to route.
-3. **Recursive dispatch**: `Cmd.map` delegates inner command execution to the runtime, then transforms the result.
-
-## Usage
-
-```bash
-ruby examples/widget_cmd_map/app.rb
-```

data/examples/app_fractal_dashboard/app.rb

@@ -1,63 +0,0 @@
-# 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 three approaches to UPDATE routing in Fractal Architecture.
-#
-# == Usage
-#
-#   ruby app.rb           # Defaults to 'manual'
-#   ruby app.rb manual    # Verbose pattern matching
-#   ruby app.rb helpers   # Rooibos.route and Rooibos.delegate helpers
-#   ruby app.rb router    # Rooibos::Router DSL
-#
-# All three share the same fragments, Model, INITIAL, and VIEW. Only the UPDATE
-# implementation differs. Compare the three update_*.rb files to see the
-# progression from verbose to declarative.
-#
-# == Architecture
-#
-#   app.rb              ← Entry point (you are here)
-#   dashboard/
-#   ├── base.rb         ← Shared: Model, INITIAL, VIEW
-#   ├── update_manual.rb
-#   ├── update_helpers.rb
-#   └── update_router.rb
-#   fragments/
-#   ├── system_info.rb
-#   ├── disk_usage.rb
-#   ├── ping.rb
-#   ├── uptime.rb
-#   ├── stats_panel.rb
-#   └── network_panel.rb
-
-VALID_MODES = %w[manual helpers router].freeze
-
-mode = ARGV[0] || "manual"
-unless VALID_MODES.include?(mode)
-  warn "Usage: ruby app.rb [#{VALID_MODES.join('|')}]"
-  exit 1
-end
-
-dashboard = case mode
-            when "manual"
-              require_relative "dashboard/update_manual"
-              DashboardManual
-            when "helpers"
-              require_relative "dashboard/update_helpers"
-              DashboardHelpers
-            when "router"
-              require_relative "dashboard/update_router"
-              DashboardRouter
-end
-
-puts "Running with #{mode} UPDATE..."
-Rooibos.run(fragment: dashboard)

data/examples/app_fractal_dashboard/dashboard/base.rb

@@ -1,73 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: MIT-0
-#++
-
-require_relative "../fragments/stats_panel"
-require_relative "../fragments/network_panel"
-require_relative "../fragments/custom_shell_modal"
-
-# Shared Model, Init, and View for the Dashboard.
-# Each Dashboard variation (Manual, Router, Helpers) provides its own Update.
-module DashboardBase
-  Command = Rooibos::Command
-
-  Model = Data.define(:stats, :network, :shell_modal)
-
-  Init = -> do
-    stats, = Rooibos.normalize_init(StatsPanel::Init.())
-    network, = Rooibos.normalize_init(NetworkPanel::Init.())
-    shell_modal, = Rooibos.normalize_init(CustomShellModal::Init.())
-    Model.new(stats:, network:, shell_modal:)
-  end
-
-  View = -> (model, tui) do
-    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

@@ -1,86 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: MIT-0
-#++
-
-require_relative "base"
-
-# UPDATE using Rooibos.route and Rooibos.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 = Rooibos::Command
-  # Alias for readability
-
-  # Shared with other UPDATE variants
-  Model = DashboardBase::Model
-  Init = DashboardBase::Init
-  View = DashboardBase::View
-
-  Update = -> (message, model) do
-    # Global Force Quit
-    return [model, Rooibos::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 = Rooibos.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 fragments
-    if (result = Rooibos.delegate(message, :stats, StatsPanel::Update, model.stats))
-      new_child, command = result
-      return [model.with(stats: new_child), command && Rooibos.route(command, :stats)]
-    end
-
-    if (result = Rooibos.delegate(message, :network, NetworkPanel::Update, model.network))
-      new_child, command = result
-      return [model.with(network: new_child), command && Rooibos.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 = Rooibos.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 = Rooibos.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 = Rooibos.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 = Rooibos.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

@@ -1,87 +0,0 @@
-# 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 = Rooibos::Command
-
-  # Shared with other UPDATE variants
-  Model = DashboardBase::Model
-  Init = DashboardBase::Init
-  View = DashboardBase::View
-
-  Update = -> (message, model) do
-    # Global Force Quit
-    return [model, Rooibos::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) { |batch| [:stats, batch] }
-      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) { |batch| [:stats, batch] }
-      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) { |batch| [:network, batch] }
-      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) { |batch| [:network, batch] }
-      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

@@ -1,43 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: MIT-0
-#++
-
-require_relative "base"
-
-# UPDATE using the declarative Rooibos::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 Rooibos::Router
-
-  Command = Rooibos::Command
-
-  # Shared with other Update variants
-  Model = DashboardBase::Model
-  Init = DashboardBase::Init
-  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/app_fractal_dashboard/fragments/custom_shell_input.rb

@@ -1,81 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: LGPL-3.0-or-later
-#++
-
-require "rooibos"
-# Text input fragment for custom shell command modal.
-#
-# Handles text entry. Sets canceled: or submitted: in model for parent to detect.
-module CustomShellInput
-  Model = Data.define(:text, :canceled, :submitted)
-
-  Init = -> do
-    Ractor.make_shareable(Model.new(text: "", canceled: false, submitted: false))
-  end
-
-  View = -> (model, tui) do
-    content = if model.text.empty?
-      tui.paragraph(text: tui.text_span(content: "Type a command...", style: { fg: :dark_gray }))
-    else
-      tui.paragraph(text: model.text)
-    end
-
-    tui.layout(
-      direction: :vertical,
-      constraints: [
-        tui.constraint_length(1),
-        tui.constraint_length(3),
-        tui.constraint_min(0),
-      ],
-      children: [
-        nil,
-        tui.center(
-          width_percent: 80,
-          child: tui.overlay(
-            layers: [
-              tui.clear,
-              tui.block(
-                title: "Run Command",
-                titles: [
-                  { content: "ESC: Cancel", position: :bottom, alignment: :left },
-                  { content: "ENTER: Run", position: :bottom, alignment: :right },
-                ],
-                borders: [:all],
-                children: [content]
-              ),
-            ]
-          )
-        ),
-        nil,
-      ]
-    )
-  end
-
-  Update = -> (message, model) do
-    case message
-    in _ if message.respond_to?(:esc?) && message.esc?
-      [model.with(canceled: true), nil]
-
-    in _ if message.respond_to?(:enter?) && message.enter?
-      return [model.with(canceled: true), nil] if model.text.strip.empty?
-      [model.with(submitted: true), nil]
-
-    in _ if message.respond_to?(:backspace?) && message.backspace?
-      [model.with(text: model.text.chop.freeze), nil]
-
-    in RatatuiRuby::Event::Paste
-      # Handle continuation backslashes: "foo \\\nbar" → "foo bar"
-      normalized = message.content.gsub(/\\\r?\n/, "").gsub(/[\r\n]/, " ")
-      [model.with(text: "#{model.text}#{normalized}".freeze), nil]
-
-    in RatatuiRuby::Event::Key if message.text? && message.code.length == 1
-      [model.with(text: "#{model.text}#{message.code}".freeze), nil]
-
-    else
-      [model, nil]
-    end
-  end
-end

data/examples/app_fractal_dashboard/fragments/custom_shell_modal.rb

@@ -1,82 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: LGPL-3.0-or-later
-#++
-
-require_relative "custom_shell_input"
-require_relative "custom_shell_output"
-
-# Modal overlay for custom shell command execution.
-module CustomShellModal
-  Command = Rooibos::Command
-
-  Model = Data.define(:mode, :input, :output)
-
-  Init = -> do
-    input, = Rooibos.normalize_init(CustomShellInput::Init.())
-    output, = Rooibos.normalize_init(CustomShellOutput::Init.())
-    Ractor.make_shareable(Model.new(mode: :none, input:, output:))
-  end
-
-  View = -> (model, tui) do
-    case model.mode
-    when :input
-      CustomShellInput::View.call(model.input, tui)
-    when :output
-      CustomShellOutput::View.call(model.output, tui)
-    else
-      nil
-    end
-  end
-
-  Update = -> (message, model) do
-    case [model.mode, message]
-    in [:input, _]
-      # Delegate first, then check if user wants to close
-      new_input, _cmd = CustomShellInput::Update.call(message, model.input)
-
-      if new_input.canceled
-        [Init.(), nil]
-      elsif new_input.submitted
-        shell_cmd = new_input.text
-        new_output = CustomShellOutput::Init.().with(command: shell_cmd, running: true)
-        reset_input, = Rooibos.normalize_init(CustomShellInput::Init.())
-        [
-          model.with(mode: :output, input: reset_input, output: new_output),
-          Command.system(shell_cmd, :shell_output, stream: true),
-        ]
-      else
-        [model.with(input: new_input), nil]
-      end
-
-    in [:output, _]
-      # Delegate first, then check if user wants to close
-      case message
-      in RatatuiRuby::Event::Key if message.ctrl_c?
-        [Init.(), nil]
-      else
-        new_output, _cmd = CustomShellOutput::Update.call(message, model.output)
-
-        if new_output.dismissed
-          [Init.(), nil]
-        else
-          [model.with(output: new_output), nil]
-        end
-      end
-
-    else
-      [model, nil]
-    end
-  end
-
-  def self.open
-    input, = Rooibos.normalize_init(CustomShellInput::Init.())
-    Init.().with(mode: :input, input:)
-  end
-
-  def self.active?(model)
-    model.mode != :none
-  end
-end

data/examples/app_fractal_dashboard/fragments/custom_shell_output.rb

@@ -1,90 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: LGPL-3.0-or-later
-#++
-
-require "rooibos"
-# Streaming output fragment for custom shell command modal.
-#
-# Displays interleaved stdout/stderr. Border color reflects exit status.
-# Sets dismissed: in model for parent to detect.
-module CustomShellOutput
-  Chunk = Data.define(:stream, :text)
-  Model = Data.define(:command, :chunks, :running, :exit_status, :dismissed)
-
-  Init = -> do
-    Ractor.make_shareable(Model.new(command: "", chunks: [].freeze, running: false, exit_status: nil, dismissed: false))
-  end
-
-  View = -> (model, tui) do
-    # Build styled spans from chunks
-    spans = if model.chunks.empty? && model.running
-      [tui.text_span(content: "Running...", style: tui.style(fg: :dark_gray))]
-    else
-      model.chunks.map do |chunk|
-        style = (chunk.stream == :stderr) ? tui.style(fg: :yellow) : nil
-        tui.text_span(content: chunk.text, style:)
-      end
-    end
-
-    # Border color: green if exited 0, red if exited non-zero, default if running
-    border_style = case model.exit_status
-                   when nil then nil
-                   when 0 then tui.style(fg: :green)
-                   else tui.style(fg: :red)
-    end
-
-    left_title = model.running ? "ESC: Cancel" : "ESC: Dismiss"
-    display_cmd = (model.command.length > 60) ? "#{model.command[0..57]}..." : model.command
-
-    tui.center(
-      width_percent: 80,
-      height_percent: 80,
-      child: tui.overlay(
-        layers: [
-          tui.clear,
-          tui.block(
-            title: display_cmd,
-            titles: [
-              { content: left_title, position: :bottom, alignment: :left },
-              { content: "ENTER: Dismiss", position: :bottom, alignment: :right },
-            ],
-            borders: [:all],
-            border_style:,
-            children: [tui.paragraph(text: spans)]
-          ),
-        ]
-      )
-    )
-  end
-
-  Update = -> (message, model) do
-    case message
-    in [:stdout, chunk]
-      new_chunks = Ractor.make_shareable([*model.chunks, Chunk.new(stream: :stdout, text: chunk)].freeze)
-      [model.with(chunks: new_chunks), nil]
-
-    in [:stderr, chunk]
-      new_chunks = Ractor.make_shareable([*model.chunks, Chunk.new(stream: :stderr, text: chunk)].freeze)
-      [model.with(chunks: new_chunks), nil]
-
-    in [:complete, { status: }]
-      [model.with(running: false, exit_status: status), nil]
-
-    in [:error, { message: error_msg }]
-      new_chunks = Ractor.make_shareable([*model.chunks, Chunk.new(stream: :stderr, text: "Error: #{error_msg}\n")].freeze)
-      [model.with(chunks: new_chunks, running: false, exit_status: 1), nil]
-
-    in _ if message.respond_to?(:esc?) && message.esc?
-      [model.with(dismissed: true), nil]
-
-    in _ if message.respond_to?(:enter?) && message.enter?
-      [model.with(dismissed: true), nil]
-
-    else
-      [model, nil]
-    end
-  end
-end