rooibos 0.5.0 → 0.6.0

data/doc/contributors/specs/tutorials_to_stories.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "json"
+
+# Parse stories from file_browser_stories.md
+def parse_stories(file_path)
+  content = File.read(file_path)
+  stories = []
+
+  # Split by story headers and capture full content
+  sections = content.split(/^## Story (-?\d+): (.+)$/)
+
+  # sections[0] is preamble, then groups of [number, title, content]
+  (1...(sections.length)).step(3) do |i|
+    number = sections[i].to_i
+    title = sections[i + 1].strip
+    story_content = sections[i + 2]
+
+    # Extract until next story or end
+    story_content = story_content.split(/^---$/)[0].strip
+
+    stories << {
+      number:,
+      title:,
+      content: story_content,
+    }
+  end
+
+  stories.sort_by { |s| s[:number] }
+end
+
+# Parse tutorial steps from tutorial files
+def parse_tutorial_steps(tutorial_dir)
+  steps = []
+
+  # Get all tutorial files in order
+  tutorial_files = Dir.glob("#{tutorial_dir}/*.md")
+
+  tutorial_files.each do |file|
+    content = File.read(file)
+
+    # Extract H1 title
+    title_match = content.match(/^# (.+)$/)
+    title = title_match ? title_match[1].strip : File.basename(file, ".md")
+
+    # Store full content for display
+    steps << {
+      file: File.basename(file),
+      title:,
+      content:,
+    }
+  end
+
+  steps
+end
+
+# Main interactive mapping logic
+def run_interactive_mapping(stories, tutorial_steps)
+  results = {}
+  tutorial_steps.each { |step| results[step[:title]] = Set.new }
+
+  story_index = 0
+
+  tutorial_steps.each do |step|
+    while story_index < stories.length
+      story = stories[story_index]
+
+      # Display tutorial step EVERY time
+      puts "\n#{'=' * 80}"
+      puts "TUTORIAL STEP: #{step[:title]}"
+      puts "=" * 80
+      puts step[:content]
+      puts "=" * 80
+      puts "\n"
+
+      # Display current story
+      puts "-" * 80
+      puts "Story #{story[:number]}: #{story[:title]}"
+      puts "-" * 80
+      puts story[:content]
+      puts "-" * 80
+      print "\nDoes the learner know enough by this step to implement this story? [y/n]: "
+
+      answer = gets.chomp.downcase
+
+      if answer == "y"
+        results[step[:title]].add(story)
+        puts "✓ Added Story #{story[:number]} to '#{step[:title]}'"
+        story_index += 1
+        puts ""
+      else
+        puts "→ Moving to next tutorial step...\n"
+        break
+      end
+    end
+  end
+
+  # Handle unallocated stories
+  if story_index < stories.length
+    results[:unallocated] = Set.new
+    while story_index < stories.length
+      results[:unallocated].add(stories[story_index])
+      story_index += 1
+    end
+  end
+
+  results
+end
+
+# Pretty print results
+def print_results(results)
+  puts "\n\n"
+  puts "=" * 80
+  puts "FINAL MAPPING RESULTS"
+  puts "=" * 80
+
+  results.each do |step_title, stories|
+    puts "\n### #{step_title}"
+
+    if stories.empty?
+      puts "  (No stories)"
+    else
+      stories.to_a.sort_by { |s| s[:number] }.each do |story|
+        puts "  - Story #{story[:number]}: #{story[:title]}"
+      end
+    end
+  end
+
+  # Summary
+  puts "\n#{'=' * 80}"
+  puts "SUMMARY"
+  puts "=" * 80
+  total_allocated = results.except(:unallocated).values.sum(&:size)
+  total_unallocated = results[:unallocated]&.size || 0
+  puts "Total stories allocated: #{total_allocated}"
+  puts "Total stories unallocated: #{total_unallocated}"
+end
+
+# Main execution
+if __FILE__ == $0
+  stories_file = "/Users/kerrick/Developer/ratatui_ruby-tea/doc/contributors/specs/file_browser_stories.md"
+  tutorial_dir = "/Users/kerrick/Developer/ratatui_ruby-tea/doc/tutorial"
+
+  puts "Parsing stories from #{stories_file}..."
+  stories = parse_stories(stories_file)
+  puts "Found #{stories.length} stories"
+
+  puts "\nParsing tutorial steps from #{tutorial_dir}..."
+  tutorial_steps = parse_tutorial_steps(tutorial_dir)
+  puts "Found #{tutorial_steps.length} tutorial steps"
+
+  puts "\n#{'=' * 80}"
+  puts "Starting interactive mapping..."
+  puts "=" * 80
+  puts "Instructions: For each story, answer 'y' if the learner has enough"
+  puts "knowledge from the current tutorial step to implement it, 'n' otherwise."
+  puts "=" * 80
+
+  results = run_interactive_mapping(stories, tutorial_steps)
+  print_results(results)
+end

data/doc/contributors/todo/scrollbar.md

@@ -0,0 +1,118 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Scrollbar Widget Support
+
+## Status
+
+**Blocked.** Scrollbar overlays require frame-level rendering, which MVU abstracts away.
+
+## Problem
+
+Scrollbar widgets in RatatuiRuby render as overlays on the same area as content:
+
+```ruby
+# In RatatuiRuby (imperative)
+frame.render_widget(paragraph, frame.area)
+frame.render_widget(scrollbar, frame.area)  # Overlays on right edge
+```
+
+In Rooibos MVU, View returns a widget tree. The runtime renders all widgets sequentially. When a scrollbar is added as a sibling to a list inside a block:
+
+```ruby
+# In Rooibos (MVU)
+tui.block(children: [list, scrollbar])
+```
+
+The scrollbar renders **inside** the content area, not **on** the border. It also inherits layout properties (takes up width, changes sibling positioning).
+
+## Why This Happens
+
+1. **No frame access in View.** View is a pure function that returns widgets. It cannot call `frame.render_widget` for overlay positioning.
+
+2. **Children are siblings.** Block's `children` are laid out sequentially, not stacked.
+
+3. **Scrollbar is position-aware.** It needs to know the rendered area to position itself at the right edge.
+
+## Workarounds Considered
+
+### 1. Overlay Widget (Not Implemented)
+
+A dedicated overlay widget that renders children on top of each other:
+
+```ruby
+tui.overlay(base: list, overlay: scrollbar)
+```
+
+**Problem:** Would need to track which child gets which area and handle z-ordering.
+
+### 2. Block with Scrollbar Option
+
+Add scrollbar support directly to Block:
+
+```ruby
+tui.block(
+  children: [list],
+  scrollbar: { content_length: 100, position: 10 }
+)
+```
+
+The Block would render its children, then overlay the scrollbar on the right border.
+
+**Advantages:**
+- Scrollbar naturally belongs with the bordered container
+- No new widget type needed
+- Block already handles border rendering
+
+**Disadvantages:**
+- Would need to be added to RatatuiRuby, or
+- Would need to intercept TUI facade and Block.new
+
+### 3. Custom Widget (Current Pattern)
+
+Users implement scrollbar rendering in a custom widget that has frame access:
+
+```ruby
+class ScrollableList
+  def render(area)
+    # Split area, render list, then overlay scrollbar
+  end
+end
+```
+
+**Problem:** Breaks the pure View pattern. Custom widgets are RatatuiRuby-level, not MVU-level. Duplicates logic from Scrollbar.
+
+### 4. Provide `Frame` to View
+
+Pass the frame to View, so it can call `render_widget` for overlay positioning.
+
+```ruby
+module MyFragment
+  View = -> (model, tui, frame) {
+    tui.block(
+      children: [tui.list(items: model.items)],
+      scrollbar: { content_length: model.items.length, position: model.offset }
+    )
+  }
+end
+```
+
+**Problem:** Breaks the pure View-as-returned-tree pattern.
+
+## Recommendation
+
+Investigate more options.
+
+## Open Questions
+
+1. Should scrollbar position be `offset` (scroll window position) or `selected_index`?
+2. Should scrollbar automatically infer `content_length` from list children?
+3. How to handle horizontal scrollbars?
+
+## See Also
+
+- [no_stateful_widgets.md](../best_practices/no_stateful_widgets.md) — MVU scroll offset patterns
+- [RatatuiRuby Scrollbar](https://git.sr.ht/~kerrick/ratatui_ruby/tree/stable/item/lib/ratatui_ruby/widgets/scrollbar.rb)
+- [widget_scrollbar example](https://git.sr.ht/~kerrick/ratatui_ruby/tree/stable/item/examples/widget_scrollbar)

data/doc/contributors/tutorial_old/01_project_setup.md

@@ -0,0 +1,20 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Project Setup
+
+
+By the end of this guide, you will:
+
+- Create a new Rooibos project with the correct folder structure
+- Configure your Gemfile with required dependencies
+- Run a smoke test to verify your environment works
+- Understand what each file in the project does
+
+> ⚠️ **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:** Tutorial: Build a File Browser](./index.md) | [**Next:** Hello World](./02_hello_world.md)

data/doc/contributors/tutorial_old/02_hello_world.md

@@ -0,0 +1,24 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Hello World
+
+
+By the end of this guide, you will:
+
+- Write your first VIEW callable that renders text
+- Write your first UPDATE callable that handles keyboard input
+- Handle 'q' and Ctrl+C to quit the application
+- Use predicate helpers (`.q?`, `.ctrl_c?`) for key checks
+- Run your app and see output in the terminal
+- Identify the entry point that starts your application
+- Explain what a VIEW callable returns (RatatuiRuby widgets)
+- Explain what an UPDATE callable returns (new model and command)
+
+> ⚠️ **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:** Project Setup](./01_project_setup.md) | [**Next:** Adding State](./03_adding_state.md)

data/doc/contributors/tutorial_old/03_adding_state.md

@@ -0,0 +1,26 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Adding State
+
+
+By the end of this guide, you will:
+
+- Define a Model using `Data.define` to hold your app state
+- Explain why state is stored in a struct, not instance variables
+- Pass the Model to your VIEW function
+- Display dynamic content based on state
+- Use `model.with(...)` to create updated state immutably
+- Use predicate helpers (`.up?`, `.down?`, `.j?`, `.k?`) for key checks
+- Use pattern matching (`case message`) for complex message handling
+- Return a new Model from UPDATE with state changes
+- Navigate your file browser with arrow keys and vim keys
+- Understand when to use predicates vs pattern matching
+
+> ⚠️ **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:** Hello World](./02_hello_world.md) | [**Next:** Organizing Your Code](./06_organizing_your_code.md)

data/doc/contributors/tutorial_old/06_organizing_your_code.md

@@ -0,0 +1,20 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Organizing Your Code
+
+
+By the end of this guide, you will:
+
+- Extract a reusable fragment from your app
+- Define the Init callable that creates initial state
+- Compose multiple fragments into one application
+- Decide when to extract vs. keep code inline
+
+> ⚠️ **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:** Adding State](./03_adding_state.md) | [**Next:** Your First Command](./07_your_first_command.md)

data/doc/contributors/tutorial_old/07_your_first_command.md

@@ -0,0 +1,21 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Your First Command
+
+
+By the end of this guide, you will:
+
+- Understand when Commands are needed (or better) vs. direct model updates
+- Explain why some operations cannot happen inside UPDATE (I/O, async)
+- Use `Command.system` to read a file asynchronously
+- Handle the command result as a message
+- Return `[model, command]` tuples from UPDATE
+
+> ⚠️ **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:** Organizing Your Code](./06_organizing_your_code.md) | [**Next:** The Preview Pane](./08_the_preview_pane.md)

data/doc/contributors/tutorial_old/08_the_preview_pane.md

@@ -0,0 +1,20 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# The Preview Pane
+
+
+By the end of this guide, you will:
+
+- Build a second fragment that displays file contents
+- Use RatatuiRuby layouts to arrange two views side-by-side
+- Coordinate state between the tree view and preview pane
+- Route messages from parent to child fragments
+
+> ⚠️ **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:** Your First Command](./07_your_first_command.md) | [**Next:** Loading States](./09_loading_states.md)

data/doc/contributors/tutorial_old/09_loading_states.md

@@ -0,0 +1,20 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Loading States
+
+
+By the end of this guide, you will:
+
+- Model three states: loading, success, and error
+- Display a spinner or message while data loads
+- Handle errors gracefully with user feedback
+- Avoid rendering stale data during transitions
+
+> ⚠️ **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:** The Preview Pane](./08_the_preview_pane.md) | [**Next:** Testing Your App](./10_testing_your_app.md)

data/doc/contributors/tutorial_old/10_testing_your_app.md

@@ -0,0 +1,20 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Testing Your App
+
+
+By the end of this guide, you will:
+
+- Set up Rooibos::TestHelper in your test file
+- Write unit tests for UPDATE functions
+- Assert that VIEW renders expected content
+- Simulate keyboard input in tests
+
+> ⚠️ **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:** Loading States](./09_loading_states.md) | [**Next:** Polish and Refine](./11_polish_and_refine.md)

data/doc/contributors/tutorial_old/11_polish_and_refine.md

@@ -0,0 +1,20 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Polish and Refine
+
+
+By the end of this guide, you will:
+
+- Handle edge cases (empty directories, permission errors)
+- Add keyboard shortcuts with a help overlay
+- Improve perceived performance with optimistic updates
+- Apply finishing touches that make your app feel professional
+
+> ⚠️ **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:** Testing Your App](./10_testing_your_app.md) | [**Next:** Going Further](./12_going_further.md)

data/doc/contributors/tutorial_old/12_going_further.md

@@ -0,0 +1,20 @@
+<!--
+  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:
+
+- Know where to find the Essentials for deeper understanding
+- Identify which Scaling Up topics apply to your next project
+- Find Best Practices for common UI patterns
+- Decide what to build next
+
+> ⚠️ **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:** Polish and Refine](./11_polish_and_refine.md)

data/doc/contributors/tutorial_old/index.md

@@ -0,0 +1,20 @@
+<!--
+  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:
+
+- Build a fully-functional file browser TUI from scratch
+- Apply all core Rooibos concepts (Model, Update, View, Commands)
+- Understand how to structure a real-world Rooibos application
+- Have a working app you can extend and customize
+
+> ⚠️ **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/doc/essentials/commands.md

@@ -0,0 +1,20 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Commands
+
+
+By the end of this guide, you will:
+
+- Choose the right built-in command (`system`, `wait`, `http`, `batch`, `all`, `exit`, `cancel`)
+- Explain the command lifecycle: dispatch → execute → message
+- Compare Commands to React useEffect ("Commands are explicit, not magical")
+- Combine multiple commands with `Command.batch`
+
+> ⚠️ **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:** Views](./views.md) | [**Next:** The Runtime](./the_runtime.md)

data/doc/essentials/index.md

@@ -0,0 +1,31 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Essentials
+
+Core concepts for building Rooibos applications.
+
+---
+
+## The Foundation
+
+- [**The Elm Architecture**](./the_elm_architecture.md) — Model-View-Update explained
+- [**Models**](./models.md) — Designing state with `Data.define`
+- [**Messages**](./messages.md) — Events, predicates, and pattern matching
+- [**Update Functions**](./update_functions.md) — Pure state transitions
+
+## Rendering & Effects
+
+- [**Views**](./views.md) — Rendering with RatatuiRuby widgets
+- [**Commands**](./commands.md) — Async operations and side effects
+
+## The Glue
+
+- [**The Runtime**](./the_runtime.md) — How Rooibos orchestrates your app
+- [**Shortcuts**](./shortcuts.md) — `Cmd` and `Msg` aliases for concise code
+
+---
+
+**Ready for advanced patterns?** Continue to [Scaling Up](../scaling_up/custom_commands.md).

data/doc/essentials/messages.md

@@ -0,0 +1,21 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Messages
+
+
+By the end of this guide, you will:
+
+- Understand message types: RatatuiRuby::Event (user input) and Rooibos::Message (command responses)
+- Define message types that describe what happened in your app
+- Use pattern matching (`case/in`) to route messages to handlers
+- Apply predicate helpers (`.key?`, `.q?`) for keyboard events
+- Design a message vocabulary for your domain
+
+> ⚠️ **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:** Models](./models.md) | [**Next:** Update Functions](./update_functions.md)

data/doc/essentials/models.md

@@ -0,0 +1,21 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Models
+
+
+By the end of this guide, you will:
+
+- Design application state with `Data.define`
+- Explain why Rooibos uses immutable structs instead of instance variables
+- Choose between flat and nested state structures
+- Create new state with `.with()` instead of mutation
+- Split a complex Model into nested Models
+
+> ⚠️ **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:** The Elm Architecture](./the_elm_architecture.md) | [**Next:** Messages](./messages.md)

data/doc/essentials/shortcuts.md

@@ -0,0 +1,19 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Shortcuts
+
+
+By the end of this guide, you will:
+
+- Use `Cmd` and `Msg` module aliases for concise code
+- Understand the full vs. shorthand forms
+- Know when shorthand improves vs. hurts readability
+
+> ⚠️ **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:** The Runtime](./the_runtime.md)

data/doc/essentials/the_elm_architecture.md

@@ -0,0 +1,24 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# The Elm Architecture
+
+
+By the end of this guide, you will:
+
+- Identify the three callables: Init, Update, and View
+- Explain why UPDATE must be a pure function (no side effects)
+- Understand the separation of concerns in MVU architecture
+- Explain Model-View-Update in your own words
+- Trace data flow through the complete MVU cycle
+- Describe how unidirectional data flow prevents bugs
+- Draw the MVU loop from memory
+- Compare MVU to web server request/response cycle ("unlike a web request, state persists")
+
+> ⚠️ **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:** Models](./models.md)