rooibos 0.5.0 → 0.6.0

data/examples/app_file_browser/app.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "rooibos"
+
+module Tutorial01
+  module FileBrowser
+    Model = Data.define(:current_directory, :file_names)
+
+    View = -> (model, tui) {
+      tui.layout(children: [
+        tui.paragraph(text: model.current_directory),
+        tui.list(items: model.file_names),
+      ])
+    }
+
+    Update = -> (message, model) {
+      if message.ctrl_c? or message.q?
+        Rooibos::Command.exit
+      else
+        model
+      end
+    }
+
+    Init = -> {
+      current_directory = Dir.pwd
+      file_names = Dir.children(current_directory)
+      Ractor.make_shareable Model.new(current_directory, file_names)
+    }
+  end
+end
+
+if __FILE__ == $0
+  Rooibos.run(Tutorial01::FileBrowser)
+end

data/examples/app_fractal_dashboard/dashboard/update_manual.rb

@@ -28,17 +28,17 @@ module DashboardManual
     # modal is active. Only user input (keys/mouse) should be blocked.
     case message
     # Route command results to panels
-    in [:stats, *rest]
+    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]
+    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]
+    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]
@@ -61,22 +61,22 @@ module DashboardManual
       [model.with(shell_modal: CustomShellModal.open), nil]
 
     in _ if message.s?
-      command = Command.map(SystemInfo.fetch_command) { |batch| [:stats, batch.envelope, batch] }
+      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.envelope, batch] }
+      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.envelope, batch] }
+      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.envelope, batch] }
+      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]
 

data/examples/app_fractal_dashboard/fragments/custom_shell_input.rb

@@ -8,12 +8,12 @@
 require "rooibos"
 # Text input fragment for custom shell command modal.
 #
-# Handles text entry. Sets cancelled: or submitted: in model for parent to detect.
+# Handles text entry. Sets canceled: or submitted: in model for parent to detect.
 module CustomShellInput
-  Model = Data.define(:text, :cancelled, :submitted)
+  Model = Data.define(:text, :canceled, :submitted)
 
   Init = -> do
-    Ractor.make_shareable(Model.new(text: "", cancelled: false, submitted: false))
+    Ractor.make_shareable(Model.new(text: "", canceled: false, submitted: false))
   end
 
   View = -> (model, tui) do
@@ -57,10 +57,10 @@ module CustomShellInput
   Update = -> (message, model) do
     case message
     in _ if message.respond_to?(:esc?) && message.esc?
-      [model.with(cancelled: true), nil]
+      [model.with(canceled: true), nil]
 
     in _ if message.respond_to?(:enter?) && message.enter?
-      return [model.with(cancelled: true), nil] if model.text.strip.empty?
+      return [model.with(canceled: true), nil] if model.text.strip.empty?
       [model.with(submitted: true), nil]
 
     in _ if message.respond_to?(:backspace?) && message.backspace?

data/examples/app_fractal_dashboard/fragments/custom_shell_modal.rb

@@ -37,7 +37,7 @@ module CustomShellModal
       # Delegate first, then check if user wants to close
       new_input, _cmd = CustomShellInput::Update.call(message, model.input)
 
-      if new_input.cancelled
+      if new_input.canceled
         [Init.(), nil]
       elsif new_input.submitted
         shell_cmd = new_input.text

data/examples/app_fractal_dashboard/fragments/disk_usage.rb

@@ -32,9 +32,9 @@ module DiskUsage
 
   Update = -> (message, model) do
     case message
-    in [{ type: :system, envelope: :disk_usage, status: 0, stdout: }]
+    in { type: :system, envelope: :disk_usage, status: 0, stdout: }
       [model.with(output: Ractor.make_shareable(stdout.strip), loading: false), nil]
-    in [{ type: :system, envelope: :disk_usage, stderr: }]
+    in { type: :system, envelope: :disk_usage, stderr: }
       [model.with(output: Ractor.make_shareable("Error: #{stderr.strip}"), loading: false), nil]
     else
       [model, nil]

data/examples/app_fractal_dashboard/fragments/network_panel.rb

@@ -32,11 +32,11 @@ module NetworkPanel
 
   Update = -> (message, model) do
     case message
-    in [:ping, *rest]
-      new_child, command = Ping::Update.call(rest, model.ping)
+    in { envelope: :ping, ** }
+      new_child, command = Ping::Update.call(message, model.ping)
       [model.with(ping: new_child), command]
-    in [:uptime, *rest]
-      new_child, command = Uptime::Update.call(rest, model.uptime)
+    in { envelope: :uptime, ** }
+      new_child, command = Uptime::Update.call(message, model.uptime)
       [model.with(uptime: new_child), command]
     else
       [model, nil]

data/examples/app_fractal_dashboard/fragments/ping.rb

@@ -32,9 +32,9 @@ module Ping
 
   Update = -> (message, model) do
     case message
-    in [{ type: :system, envelope: :ping, status: 0, stdout: }]
+    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: }]
+    in { type: :system, envelope: :ping, stderr: }
       [model.with(output: Ractor.make_shareable("Error: #{stderr.strip}"), loading: false), nil]
     else
       [model, nil]

data/examples/app_fractal_dashboard/fragments/stats_panel.rb

@@ -32,11 +32,11 @@ module StatsPanel
 
   Update = -> (message, model) do
     case message
-    in [:system_info, *rest]
-      new_child, command = SystemInfo::Update.call(rest, model.system_info)
+    in { envelope: :system_info, ** }
+      new_child, command = SystemInfo::Update.call(message, model.system_info)
       [model.with(system_info: new_child), command]
-    in [:disk_usage, *rest]
-      new_child, command = DiskUsage::Update.call(rest, model.disk_usage)
+    in { envelope: :disk_usage, ** }
+      new_child, command = DiskUsage::Update.call(message, model.disk_usage)
       [model.with(disk_usage: new_child), command]
     else
       [model, nil]

data/examples/app_fractal_dashboard/fragments/system_info.rb

@@ -32,9 +32,9 @@ module SystemInfo
 
   Update = -> (message, model) do
     case message
-    in [{ type: :system, envelope: :system_info, status: 0, stdout: }]
+    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: }]
+    in { type: :system, envelope: :system_info, stderr: }
       [model.with(output: Ractor.make_shareable("Error: #{stderr.strip}"), loading: false), nil]
     else
       [model, nil]

data/examples/app_fractal_dashboard/fragments/uptime.rb

@@ -32,9 +32,9 @@ module Uptime
 
   Update = -> (message, model) do
     case message
-    in [{ type: :system, envelope: :uptime, status: 0, stdout: }]
+    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: }]
+    in { type: :system, envelope: :uptime, stderr: }
       [model.with(output: Ractor.make_shareable("Error: #{stderr.strip}"), loading: false), nil]
     else
       [model, nil]

data/examples/verify_website_first_app/app.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: MIT-0
+#++
+
+require "rooibos"
+
+module FileBrowser
+  # Model: What state does your app need?
+  Model = Data.define(:path, :entries, :selected, :error)
+
+  Init = -> {
+    path    = Dir.pwd
+    entries = Entries[path]
+    Ractor.make_shareable( # Ensures thread safety
+      Model.new(path:, entries:, selected: entries.first, error: nil))
+  }
+
+  View = -> (model, tui) {
+    tui.block(
+      titles: [
+        model.error || model.path,
+        { content: KEYS, position: :bottom, alignment: :right },
+],
+      borders: [:all],
+      border_style: if model.error then tui.style(fg: :red) else nil end,
+      children: [
+tui.list(items: model.entries.map(&ListItem[model, tui]),
+  selected_index: model.entries.index(model.selected),
+  highlight_symbol: "",
+  highlight_style: tui.style(modifiers: [:reversed])),
+]
+    )
+  }
+
+  Update = -> (message, model) {
+    return model.with(error: ERROR) if message.error?
+    model = model.with(error: nil) if model.error && message.key?
+
+    if message.ctrl_c? || message.q? then Rooibos::Command.exit
+    elsif message.home? || message.g? then model.with(selected: model.entries.first)
+    elsif message.end? || message.G? then model.with(selected: model.entries.last)
+    elsif message.up_arrow? || message.k? then Select[:-, model]
+    elsif message.down_arrow? || message.j? then Select[:+, model]
+    elsif message.enter? then Open[model]
+    elsif message.escape? then Navigate[File.dirname(model.path), model]
+    end
+  }
+
+  KEYS  = "↑/↓/Home/End: Select | Enter: Open | Esc: Navigate Up | q: Quit"
+  ERROR = "Sorry, opening the selected file failed."
+
+  ListItem = -> (model, tui) {
+    -> (name) {
+      modifiers = name.start_with?(".") ? [:dim] : []
+      fg        = :blue if name.end_with?("/")
+      tui.list_item(content: name, style: tui.style(fg:, modifiers:))
+    }
+  }
+
+  Select = -> (operator, model) {
+    new_index = model.entries.index(model.selected).public_send(operator, 1)
+    model.with(selected: model.entries[new_index.clamp(0, model.entries.length - 1)])
+  }
+
+  Open = -> (model) {
+    full = File.join(model.path, model.selected.delete_suffix("/"))
+    model.selected.end_with?("/") ? Navigate[full, model] : Rooibos::Command.open(full)
+  }
+
+  Navigate = -> (path, model) {
+    entries = Entries[path]
+    model.with(path:, entries:, selected: entries.first, error: nil)
+  }
+
+  Entries = -> (path) {
+    Dir.children(path).map { |name|
+      File.directory?(File.join(path, name)) ? "#{name}/" : name
+    }.sort_by { |name| [name.end_with?("/") ? 0 : 1, name.downcase] }
+  }
+end
+
+Rooibos.run(FileBrowser) if __FILE__ == $0

data/examples/verify_website_hello_mvu/app.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: MIT-0
+#++
+
+require "rooibos"
+
+module Counter
+  # Init: How do you create the initial model?
+  Init = -> { 0 }
+
+  # View: What does the user see?
+  View = -> (model, tui) { tui.paragraph(text: <<~END) }
+    Current count: #{model}.
+    Press any key to increment.
+    Press Ctrl+C to quit.
+  END
+
+  # Update: What happens when things change?
+  Update = -> (message, model) {
+    if message.ctrl_c?
+      Rooibos::Command.exit
+    elsif message.key?
+      model + 1
+    end
+  }
+end
+
+Rooibos.run(Counter) if __FILE__ == $0

data/examples/widget_command_system/app.rb

@@ -25,13 +25,15 @@ require "rooibos"
 # 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
-  )
+  Init = -> {
+    Model.new(
+      result: "Press a key to run a command...",
+      loading: false,
+      last_command: nil
+    )
+  }
 
-  VIEW = -> (model, tui) do
+  View = -> (model, tui) do
     hotkey_style = tui.style(modifiers: [:bold, :underlined])
     dim_style = tui.style(fg: :dark_gray)
 
@@ -97,12 +99,12 @@ class WidgetCommandSystem
     )
   end
 
-  UPDATE = -> (message, model) do
+  Update = -> (message, model) do
     case message
-    # Handle command results
-    in [:got_output, { stdout:, status: 0 }]
+    # Handle command results (hash-based pattern matching)
+    in { type: :system, envelope: :got_output, stdout:, status: 0 }
       [model.with(result: stdout.strip.freeze, loading: false), nil]
-    in [:got_output, { stderr:, status: }]
+    in { type: :system, envelope: :got_output, stderr:, status: }
       [model.with(result: "Error (exit #{status}): #{stderr.strip}".freeze, loading: false), nil]
 
     # Handle key presses
@@ -113,11 +115,11 @@ class WidgetCommandSystem
     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'"
+      cmd = "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"
+      cmd = "ls /nonexistent_path_12345"
       [model.with(loading: true, last_command: cmd.freeze), Rooibos::Command.system(cmd, :got_output)]
     else
       model
@@ -125,7 +127,7 @@ class WidgetCommandSystem
   end
 
   def run
-    Rooibos.run(model: INITIAL, view: VIEW, update: UPDATE)
+    Rooibos.run(WidgetCommandSystem)
   end
 end
 

data/exe/rooibos

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+require "rooibos/cli"
+Rooibos::CLI.call(ARGV)

data/generate_tutorial_stubs.rb

@@ -0,0 +1,126 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "fileutils"
+
+# Parse tutorial structure from documentation_plan.md
+TUTORIAL_FILES = {
+  "index.md" => { title: "Tutorial: Build a File Browser", story: nil },
+  "01_project_setup.md" => { title: "Project Setup", story: "-4" },
+  "02_hello_world.md" => { title: "Hello World", story: "-3" },
+  "03_static_file_list.md" => { title: "Static File List", story: "-2" },
+  "04_arrow_navigation.md" => { title: "Arrow Navigation", story: "-1" },
+  "05_real_files.md" => { title: "Real Files", story: "0" },
+  "06_safe_refactoring.md" => { title: "Safe Refactoring", story: "4a" },
+  "07_red_first_tdd.md" => { title: "Red-First TDD", story: "4b" },
+  "08_file_metadata.md" => { title: "File Metadata", story: "5" },
+  "09_text_preview.md" => { title: "Text Preview", story: "6" },
+  "10_directory_tree.md" => { title: "Directory Tree", story: "7" },
+  "11_pane_focus.md" => { title: "Pane Focus", story: "8" },
+  "12_sorting.md" => { title: "Sorting", story: "9" },
+  "13_filtering.md" => { title: "Filtering", story: "10" },
+  "14_toggle_hidden.md" => { title: "Toggle Hidden Files", story: "11" },
+  "15_text_input_widget.md" => { title: "Text Input Widget", story: "12" },
+  "16_rename_files.md" => { title: "Rename Files", story: "13" },
+  "17_confirmation_dialogs.md" => { title: "Confirmation Dialogs", story: "14" },
+  "18_progress_indicators.md" => { title: "Progress Indicators", story: "15" },
+  "19_atomic_operations.md" => { title: "Atomic Operations", story: "16" },
+  "20_external_editor.md" => { title: "External Editor", story: "17" },
+  "21_modal_overlays.md" => { title: "Modal Overlays", story: "18" },
+  "22_error_handling.md" => { title: "Error Handling", story: "19" },
+  "23_terminal_capabilities.md" => { title: "Terminal Capabilities", story: "23" },
+  "24_mouse_events.md" => { title: "Mouse Events", story: "20" },
+  "25_resize_events.md" => { title: "Resize Events", story: "21" },
+  "26_loading_states.md" => { title: "Loading States", story: "22" },
+  "27_performance.md" => { title: "Performance", story: "24" },
+  "28_color_schemes.md" => { title: "Color Schemes", story: "26" },
+  "29_configuration.md" => { title: "Configuration", story: "27" },
+  "30_going_further.md" => { title: "Going Further", story: nil },
+}
+
+# Parse stories from file_browser_stories.md
+stories_content = File.read("doc/contributors/specs/file_browser_stories.md")
+
+# Extract each story
+stories = {}
+current_story = nil
+current_content = []
+
+stories_content.each_line do |line|
+  if line =~ /^## Story (-?\d+[ab]?): (.+)$/
+    # Save previous story
+    if current_story
+      stories[current_story] = current_content.join
+    end
+
+    current_story = $1
+    current_content = [line]
+  elsif current_story
+    current_content << line
+
+    # Stop at the next story or end of stories section
+    if line =~ /^---$/ && current_content.size > 5
+      # Check if next section is another story or implementation notes
+      peek_ahead = stories_content.lines[stories_content.lines.index(line) + 1]
+      if peek_ahead && !peek_ahead.start_with?("## Story")
+        stories[current_story] = current_content.join
+        break if peek_ahead.start_with?("## Implementation Notes")
+      end
+    end
+  end
+end
+
+# Save last story
+stories[current_story] = current_content.join if current_story
+
+# Create tutorial directory
+FileUtils.mkdir_p("doc/tutorial")
+
+# Generate stub files
+TUTORIAL_FILES.each do |filename, meta|
+  filepath = "doc/tutorial/#{filename}"
+
+  # Determine previous/next files
+  files_list = TUTORIAL_FILES.keys
+  current_index = files_list.index(filename)
+  prev_file = (current_index > 0) ? files_list[current_index - 1] : nil
+  next_file = (current_index < files_list.size - 1) ? files_list[current_index + 1] : nil
+
+  prev_title = prev_file ? TUTORIAL_FILES[prev_file][:title] : nil
+  next_title = next_file ? TUTORIAL_FILES[next_file][:title] : nil
+
+  # Get story content if applicable
+  story_section = ""
+  if meta[:story]
+    story_key = meta[:story]
+    if stories[story_key]
+      story_section = "\n## User Stories\n\n#{stories[story_key]}\n"
+    end
+  end
+
+  # Generate stub content
+  content = <<~MARKDOWN
+    <!--
+      SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+      SPDX-License-Identifier: CC-BY-SA-4.0
+    -->
+
+    # #{meta[:title]}
+
+
+    By the end of this guide, you will:
+
+    - TODO: Write learning objectives
+
+    > ⚠️ **This page is a stub.** Help us write it! See the [Documentation Plan](../contributors/documentation_plan.md) and [Style Guide](../contributors/documentation_style.md).
+    #{story_section}
+    ---
+
+    #{prev_file ? "[**Previous:** #{prev_title}](./#{prev_file})" : ''} | #{next_file ? "[**Next:** #{next_title}](./#{next_file})" : ''}
+  MARKDOWN
+
+  File.write(filepath, content)
+  puts "Created #{filepath}"
+end
+
+puts "\nDone! Created #{TUTORIAL_FILES.size} tutorial stub files."