rooibos 0.5.0 → 0.6.1

data/doc/tutorial/29_configuration.md

@@ -0,0 +1,124 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Configuration
+
+
+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).
+
+## User Stories
+
+## Story 27: Configuration Management
+
+**As a** power user  
+**I want to** save my preferences  
+**So that** my settings persist between sessions
+
+### Acceptance Criteria
+- Config file in ~/.config/file_browser/config.yml
+- Configurable preferences:
+  - Default sort order
+  - Hidden files visibility default
+  - Color scheme/theme
+  - Default editor (overrides $EDITOR)
+  - Pane width ratios
+  - Mouse support enabled/disabled
+- Config file created on first run with defaults
+- Invalid config handled gracefully with warnings
+- Command-line flags override config file
+- `--config-path` flag to use alternate config location
+
+### Notes
+- Addresses specification section 5.3 (Configuration)
+- Introduces YAML parsing
+- May be deferred to 1.1 release
+- Should have schema validation
+
+---
+
+## Future Enhancements (Deferred)
+
+**As a** product owner  
+**I want to** track future enhancement ideas  
+**So that** we have a roadmap for post-1.0 releases
+
+### Deferred Features
+
+The following features are explicitly deferred to future versions:
+
+- **Bookmarks/Favorites:** Quick access to frequently used directories
+- **Multi-file Selection:** Select multiple files with Space, operate on batch
+- **File Content Search:** Integrate grep for searching within files
+- **Git Integration:** Show file status (modified, untracked, etc.)
+- **Trash/Recycle Bin:** Soft delete instead of permanent deletion
+- **Dual-Pane Mode:** Side-by-side panes for easier copying
+- **Archive Preview:** View contents of zip, tar, etc.
+- **Image Preview:** ASCII art representation of images
+- **Custom File Type Icons:** User-defined icons for extensions
+- **External Tool Integration:** Diff, merge, etc.
+- **Plugins/Extensions:** Allow third-party extensions
+- **Remote Filesystem Support:** SFTP, S3, etc.
+
+### Notes
+- These align with specification section 9 (Future Enhancements)
+- Not stories yet - just ideas for future planning
+- May become stories in 1.1, 1.2, etc.
+- Community feedback will help prioritize
+
+---
+
+## Implementation Notes
+
+### Story Sequencing
+
+Stories are ordered to:
+1. **Start with tutorial foundation** (Stories -4 to 0) - teaches Rooibos concepts incrementally
+2. **Build walking skeleton** (Story 1) - proves end-to-end integration with real files
+3. **Build core navigation** (Stories 2-3) - essential functionality
+4. **Add UI structure** (Stories 4-6) - professional appearance
+5. **Enable exploration** (Stories 7-8) - power user features
+6. **Add organization** (Stories 9-11) - finding and filtering
+7. **Enable modification** (Stories 12-17) - file operations
+8. **Improve usability** (Stories 18-19) - help and errors
+9. **Add enhancements** (Stories 20-21) - mouse and resize
+10. **Optimize and polish** (Stories 22-24) - performance and aesthetics
+11. **Ensure quality** (Story 25) - testing and documentation
+12. **Advanced features** (Stories 26-27) - color schemes and configuration
+13. **Future planning** - deferred enhancements
+
+### Story Sizing
+
+- Stories -4 to -1: Extra Small (tutorial foundation)
+- Story 0: Small (critical transition)
+- Stories 1-3: Small
+- Stories 4-8: Medium
+- Stories 9-17: Small-Medium
+- Stories 18-21: Medium
+- Stories 22-24: Large
+- Story 25: Ongoing (parallel with all stories)
+- Story 26: Medium
+- Story 27: Small-Medium
+
+### Dependencies
+
+- Story -3 depends on Story -4 (need project setup)
+- Story -2 depends on Story -3 (need runnable app)
+- Story -1 depends on Story -2 (need model and state)
+- Story 0 depends on Story -1 (need navigation working with fake data)
+- Story 1 depends on Story 0 (Story 0 completes Story 1)
+- Story 4 depends on Stories 1-3 (need basic functionality before layout)
+- Story 6 depends on Story 4 (need preview pane)
+- Story 8 depends on Story 4 (need multiple panes)
+- Stories 12-17 can be done in any order after Story 11
+- Story 21 depends on Story 4 (need layout to resize)
+- Story 24 should be done after most features complete
+
+---
+
+[**Previous:** Color Schemes](./28_color_schemes.md) | [**Next:** Going Further](./30_going_further.md)

data/doc/tutorial/30_going_further.md

@@ -0,0 +1,17 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Going Further
+
+
+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).
+
+---
+
+[**Previous:** Configuration](./29_configuration.md) | 

data/doc/tutorial/index.md

@@ -0,0 +1,17 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Tutorial: Build a File Browser
+
+
+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).
+
+---
+
+ | [**Next:** Project Setup](./01_project_setup.md)

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)