rooibos 0.5.0 → 0.6.0

data/doc/troubleshooting/performance.md

@@ -0,0 +1,20 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Performance
+
+
+By the end of this guide, you will:
+
+- Use `Benchmark` or `TracePoint` to identify slow VIEW, UPDATE, and Command callables
+- Adjust `fps:` parameter to balance responsiveness and CPU usage
+- Store expensive calculations in your Model so VIEW doesn't recalculate them every frame
+- Use `Benchmark` to profile bottlenecks in your application
+
+> ⚠️ **This page is a stub.** Help us write it! See the [Documentation Plan](../contributors/documentation_plan.md) and [Style Guide](../contributors/documentation_style.md).
+
+---
+
+**Troubleshooting:** [Common Errors](./common_errors.md) | [Debugging](./debugging.md)

data/doc/tutorial/01_project_setup.md

@@ -0,0 +1,44 @@
+<!--
+  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:
+
+- Install Ruby (if you don't have it already)
+- Verify your Ruby installation works
+- Install the `rooibos` gem
+- Use `rooibos new` to create a new project with proper structure
+- Understand the files that `rooibos new` creates for you
+- Run your first Rooibos application to verify everything works
+- Understand the difference between application code and test code directories
+
+> ⚠️ **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 -4: Project Setup
+
+**As a** developer  
+**I want to** set up a new Ruby project with proper dependencies  
+**So that** I have a foundation to build the file browser
+
+### Acceptance Criteria
+- Project directory exists with proper structure
+- Dependencies are installed
+- Application can be started without errors
+
+### Notes
+- Absolute starting point for the tutorial
+- Establishes project foundation
+
+---
+
+
+
+---
+
+[**Previous:** Tutorial: Build a File Browser](./index.md) | [**Next:** Hello World](./02_hello_world.md)

data/doc/tutorial/02_hello_world.md

@@ -0,0 +1,45 @@
+<!--
+  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 to the terminal
+- Write your first UPDATE callable that handles keyboard events
+- Use predicate helpers (`.q?`, `.ctrl_c?`) to check which key was pressed
+- Return `Command.exit` from UPDATE to quit the application
+- Understand what `Rooibos.run` does to start your app
+- Understand what a VIEW returns (RatatuiRuby widgets like `paragraph`)
+- Understand what an UPDATE returns (model or command)
+- Run your app and see it respond to keyboard input
+
+> ⚠️ **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 -3: Hello World + Quit
+
+**As a** terminal user  
+**I want to** launch a minimal TUI application that I can quit  
+**So that** I can verify the application runs
+
+### Acceptance Criteria
+- Application displays "Hello, File Browser!" text
+- Application displays "Press 'q' to quit" instruction
+- Pressing 'q' or Ctrl+C exits the application cleanly
+
+### Notes
+- First runnable TUI application
+- Demonstrates basic rendering and quit functionality
+
+---
+
+
+
+---
+
+[**Previous:** Project Setup](./01_project_setup.md) | [**Next:** Static File List](./03_static_file_list.md)

data/doc/tutorial/03_static_file_list.md

@@ -0,0 +1,44 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Static File List
+
+
+By the end of this guide, you will:
+
+- Define a Model using `Data.define` to hold your application state
+- Understand why state is immutable (Data objects, not instance variables)
+- Write an INIT callable that returns your initial model
+- Display a static list of example files in your VIEW
+- Write your first test using `Rooibos::TestHelper`
+- Use `assert_snapshots` to verify your VIEW renders correctly
+- Understand why tests with static data are fast and reliable
+
+> ⚠️ **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 -2: Static File List
+
+**As a** terminal user  
+**I want to** see a list of example files displayed  
+**So that** I can understand the basic file browser interface
+
+### Acceptance Criteria
+- Application displays a list of example filenames
+- One file is visually highlighted
+- Application can be quit with 'q'
+
+### Notes
+- Uses hardcoded example data ("README.md", "Gemfile", "lib/", "test/")
+- No navigation yet - always highlights first item
+
+---
+
+
+
+---
+
+[**Previous:** Hello World](./02_hello_world.md) | [**Next:** Arrow Navigation](./04_arrow_navigation.md)

data/doc/tutorial/04_arrow_navigation.md

@@ -0,0 +1,47 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Arrow Navigation
+
+
+By the end of this guide, you will:
+
+- Add a `selected` field to your Model to track which file is highlighted
+- Use `model.with(...)` to create updated state immutably
+- Use pattern matching (`case message`) to handle multiple keys
+- Combine pattern matching with predicate guards (`in _ if message.up?`)
+- Handle arrow keys (up/down) and vim keys (j/k) in one UPDATE
+- Scroll through the file list when it's longer than the screen
+- Return an updated model from UPDATE to change state
+- Write tests that verify state transitions (selected: 0 → selected: 1)
+- Understand when to use pattern matching vs simple if/else
+
+> ⚠️ **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 -1: Arrow Key Navigation
+
+**As a** terminal user  
+**I want to** navigate through the file list with arrow keys  
+**So that** I can select different files
+
+### Acceptance Criteria
+- Up/Down arrow keys change which file is highlighted
+- 'j'/'k' vim keys also work for navigation
+- Selection wraps at top/bottom of list
+- Visual highlight follows selection
+
+### Notes
+- Still using hardcoded file list
+- Adds interactive navigation
+
+---
+
+
+
+---
+
+[**Previous:** Static File List](./03_static_file_list.md) | [**Next:** Real Files](./05_real_files.md)

data/doc/tutorial/05_real_files.md

@@ -0,0 +1,45 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Real Files
+
+
+By the end of this guide, you will:
+
+- Load real files from your current directory instead of static examples
+- See your tests fail and understand why
+- Fix your tests by telling them what files to expect
+- Understand why good tests don't depend on the filesystem
+- Know when to use fake data in tests
+- Have a file browser that works with your files
+
+> ⚠️ **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 0: Real Files
+
+**As a** terminal user  
+**I want to** see my actual files instead of example data  
+**So that** the file browser is useful for real work
+
+### Acceptance Criteria
+- Application shows actual files from the current directory
+- File list reflects real filesystem contents
+- Can navigate through real files with arrow keys
+- All previous keyboard shortcuts still work
+
+### Notes
+- **Critical transition** - from example data to real filesystem
+- Transforms toy example into functional tool
+- After this story, Story 1 is COMPLETE
+
+---
+
+
+
+---
+
+[**Previous:** Arrow Navigation](./04_arrow_navigation.md) | [**Next:** Safe Refactoring](./06_safe_refactoring.md)

data/doc/tutorial/06_safe_refactoring.md

@@ -0,0 +1,21 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Safe Refactoring
+
+
+By the end of this guide, you will:
+
+- Extract your file list code into a separate module (a Fragment)
+- Understand what a Fragment is (a module with Model, Init, Update, View)
+- Use the Router DSL to route messages and events to your Fragment
+- Run your tests and see them still pass (refactor fearlessly)
+- Know when to extract code vs keep it 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:** Real Files](./05_real_files.md) | [**Next:** Red-First TDD](./07_red_first_tdd.md)

data/doc/tutorial/07_red_first_tdd.md

@@ -0,0 +1,26 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Red-First TDD
+
+
+By the end of this guide, you will:
+
+- Understand the red-green-refactor cycle
+- Know why writing tests first leads to better design
+- Write a failing test for your second Fragment's View (red)
+- Implement the View to make the test pass (green)
+- Write a failing test for your Fragment's Update (red)
+- Implement the Update to make the test pass (green)
+- Use RatatuiRuby layouts to arrange Fragments side-by-side
+- Coordinate state between two Fragments
+- Understand when to split UI into separate Fragments
+- Refactor your code while tests keep you safe
+
+> ⚠️ **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:** Safe Refactoring](./06_safe_refactoring.md) | [**Next:** File Metadata](./08_file_metadata.md)

data/doc/tutorial/08_file_metadata.md

@@ -0,0 +1,42 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# File Metadata
+
+
+By the end of this guide, you will:
+
+- Display file sizes and permissions in your file list
+- Understand the pre-calculation pattern
+
+> ⚠️ **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 5: File Metadata Display
+
+**As a** terminal user  
+**I want to** see file sizes and modification dates  
+**So that** I can make informed decisions about files
+
+### Acceptance Criteria
+- File list shows: name, size, modification date
+- Sizes displayed in human-readable format (KB, MB, GB)
+- Dates displayed in consistent format
+- Columns aligned properly
+- Directories show "-" for size
+
+### Notes
+- Introduces file metadata reading
+- Introduces formatting utilities
+- Introduces column layout
+
+---
+
+
+
+---
+
+[**Previous:** Red-First TDD](./07_red_first_tdd.md) | [**Next:** Text Preview](./09_text_preview.md)

data/doc/tutorial/09_text_preview.md

@@ -0,0 +1,44 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Text Preview
+
+
+By the end of this guide, you will:
+
+- Build a third Fragment for the preview pane
+- Read file contents using Ruby's File API
+- Detect whether a file is text or binary
+
+> ⚠️ **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 6: Text File Preview
+
+**As a** terminal user  
+**I want to** see a preview of text files in the preview pane  
+**So that** I can verify file contents before opening
+
+### Acceptance Criteria
+- When text file is selected, preview pane shows first ~20 lines
+- Preview updates as selection changes
+- Binary files show "Binary file" message
+- Preview pane scrolls if content is long
+- File type is detected (text vs binary)
+
+### Notes
+- Introduces file reading
+- Introduces text detection
+- Introduces preview scrolling
+- Limit to first 1000 lines for performance
+
+---
+
+
+
+---
+
+[**Previous:** File Metadata](./08_file_metadata.md) | [**Next:** Directory Tree](./10_directory_tree.md)

data/doc/tutorial/10_directory_tree.md

@@ -0,0 +1,42 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Directory Tree
+
+
+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 7: Directory Tree Expansion
+
+**As a** terminal user  
+**I want to** expand and collapse directories in the tree pane  
+**So that** I can see the directory structure at a glance
+
+### Acceptance Criteria
+- Directories show expand/collapse indicator (▶/▼)
+- Arrow right/left or `l`/`h` expands/collapses
+- Tree shows nested structure with indentation
+- Expanded state persists during session
+- Tree scrolls if structure is large
+
+### Notes
+- Introduces tree data structure
+- Introduces recursive directory reading
+- Introduces tree rendering logic
+- Major complexity increase
+
+---
+
+
+
+---
+
+[**Previous:** Text Preview](./09_text_preview.md) | [**Next:** Pane Focus](./11_pane_focus.md)

data/doc/tutorial/11_pane_focus.md

@@ -0,0 +1,40 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Pane Focus
+
+
+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 8: Pane Focus Switching
+
+**As a** terminal user  
+**I want to** switch focus between panes with Tab  
+**So that** I can navigate the tree or scroll the preview
+
+### Acceptance Criteria
+- Tab key cycles focus: tree → list → preview → tree
+- Active pane has visual indicator (highlighted border)
+- Keyboard shortcuts work in context of focused pane
+- Arrow keys navigate within focused pane
+
+### Notes
+- Introduces focus management
+- Introduces context-sensitive key handling
+- Preview pane becomes interactive (scrollable)
+
+---
+
+
+
+---
+
+[**Previous:** Directory Tree](./10_directory_tree.md) | [**Next:** Sorting](./12_sorting.md)

data/doc/tutorial/12_sorting.md

@@ -0,0 +1,41 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Sorting
+
+
+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 9: Sort Files
+
+**As a** terminal user  
+**I want to** sort files by name, size, or date  
+**So that** I can find files more easily
+
+### Acceptance Criteria
+- `s` key cycles through sort options
+- Sort options: name (asc/desc), size (asc/desc), date (asc/desc), type
+- Status bar shows current sort order
+- Directories can be sorted first or mixed with files
+- Sort persists during session
+
+### Notes
+- Introduces sorting logic
+- Introduces sort state management
+- Introduces status bar messaging
+
+---
+
+
+
+---
+
+[**Previous:** Pane Focus](./11_pane_focus.md) | [**Next:** Filtering](./13_filtering.md)

data/doc/tutorial/13_filtering.md

@@ -0,0 +1,43 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Filtering
+
+
+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 10: Filter Files by Name
+
+**As a** terminal user  
+**I want to** filter the file list by typing a pattern  
+**So that** I can quickly find specific files
+
+### Acceptance Criteria
+- `f` key opens filter input
+- User types pattern (supports * and ? wildcards)
+- File list updates to show only matching items
+- Status bar shows filter pattern and match count
+- Esc clears filter
+- Filter is case-insensitive
+
+### Notes
+- Introduces text input mode
+- Introduces filtering logic
+- Introduces wildcard matching
+- Introduces mode switching (normal vs input)
+
+---
+
+
+
+---
+
+[**Previous:** Sorting](./12_sorting.md) | [**Next:** Toggle Hidden Files](./14_toggle_hidden.md)

data/doc/tutorial/14_toggle_hidden.md

@@ -0,0 +1,41 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Toggle Hidden Files
+
+
+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 11: Toggle Hidden Files
+
+**As a** terminal user  
+**I want to** show or hide files starting with `.`  
+**So that** I can reduce clutter or see configuration files
+
+### Acceptance Criteria
+- `.` key toggles hidden file visibility
+- Hidden files are dimmed/grayed when shown
+- Status bar indicates when hidden files are shown
+- Preference persists during session
+- Default is to hide hidden files
+
+### Notes
+- Introduces filtering by file attribute
+- Introduces visual styling variations
+- Simple toggle state
+
+---
+
+
+
+---
+
+[**Previous:** Filtering](./13_filtering.md) | [**Next:** Text Input Widget](./15_text_input_widget.md)

data/doc/tutorial/15_text_input_widget.md

@@ -0,0 +1,43 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Text Input Widget
+
+
+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 12: Create New Directory
+
+**As a** terminal user  
+**I want to** create a new directory  
+**So that** I can organize files
+
+### Acceptance Criteria
+- `n` key prompts for directory name
+- User types name and presses Enter to create
+- Directory is created in current location
+- File list refreshes to show new directory
+- Error message shown if creation fails
+- Esc cancels operation
+
+### Notes
+- First file operation
+- Introduces filesystem mutation
+- Introduces input validation
+- Introduces error handling
+
+---
+
+
+
+---
+
+[**Previous:** Toggle Hidden Files](./14_toggle_hidden.md) | [**Next:** Rename Files](./16_rename_files.md)

data/doc/tutorial/16_rename_files.md

@@ -0,0 +1,42 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Rename Files
+
+
+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 13: Rename Files and Directories
+
+**As a** terminal user  
+**I want to** rename the selected file or directory  
+**So that** I can fix typos or improve organization
+
+### Acceptance Criteria
+- `r` key prompts for new name
+- Input pre-populated with current name
+- Enter confirms rename
+- File list updates to show new name
+- Error shown if name conflicts or is invalid
+- Esc cancels operation
+
+### Notes
+- Introduces pre-populated input
+- Introduces conflict detection
+- Introduces name validation
+
+---
+
+
+
+---
+
+[**Previous:** Text Input Widget](./15_text_input_widget.md) | [**Next:** Confirmation Dialogs](./17_confirmation_dialogs.md)