rooibos 0.5.0 → 0.6.1

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)

data/doc/tutorial/17_confirmation_dialogs.md

@@ -0,0 +1,43 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Confirmation Dialogs
+
+
+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 14: Delete Files and Directories
+
+**As a** terminal user  
+**I want to** delete the selected file or directory  
+**So that** I can remove unwanted items
+
+### Acceptance Criteria
+- `d` key prompts for confirmation
+- Confirmation dialog shows item name and size
+- `Y` confirms deletion, `N` cancels
+- Warning message for directory deletion
+- File list refreshes after deletion
+- Error shown if deletion fails
+
+### Notes
+- Introduces confirmation dialogs
+- Introduces destructive operations
+- Introduces modal UI elements
+- Critical to get right - no undo!
+
+---
+
+
+
+---
+
+[**Previous:** Rename Files](./16_rename_files.md) | [**Next:** Progress Indicators](./18_progress_indicators.md)

data/doc/tutorial/18_progress_indicators.md

@@ -0,0 +1,43 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Progress Indicators
+
+
+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 15: Copy Files and Directories
+
+**As a** terminal user  
+**I want to** copy files to another location  
+**So that** I can duplicate content
+
+### Acceptance Criteria
+- `c` key prompts for destination path
+- User types destination and presses Enter
+- File/directory copied to destination
+- Progress indicator for large operations
+- Error shown if copy fails
+- File list refreshes if copying to current directory
+
+### Notes
+- Introduces path input
+- Introduces progress indicators
+- Introduces recursive directory copying
+- Performance considerations for large files
+
+---
+
+
+
+---
+
+[**Previous:** Confirmation Dialogs](./17_confirmation_dialogs.md) | [**Next:** Atomic Operations](./19_atomic_operations.md)

data/doc/tutorial/19_atomic_operations.md

@@ -0,0 +1,42 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Atomic Operations
+
+
+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 16: Move Files and Directories
+
+**As a** terminal user  
+**I want to** move files to another location  
+**So that** I can reorganize my filesystem
+
+### Acceptance Criteria
+- `m` key prompts for destination path
+- User types destination and presses Enter
+- File/directory moved to destination
+- File list refreshes to remove moved item
+- Error shown if move fails
+- Handles cross-filesystem moves
+
+### Notes
+- Similar to copy but removes source
+- May need to fall back to copy+delete for cross-filesystem
+- Introduces atomic operation handling
+
+---
+
+
+
+---
+
+[**Previous:** Progress Indicators](./18_progress_indicators.md) | [**Next:** External Editor](./20_external_editor.md)

data/doc/tutorial/20_external_editor.md

@@ -0,0 +1,42 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# External Editor
+
+
+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 17: Open in External Editor
+
+**As a** terminal user  
+**I want to** open the selected file in my $EDITOR  
+**So that** I can edit files
+
+### Acceptance Criteria
+- `e` key opens file in $EDITOR
+- File browser suspends while editor runs
+- File browser resumes when editor closes
+- File list refreshes to show any changes
+- Error shown if $EDITOR not set or fails
+
+### Notes
+- Introduces external process spawning
+- Introduces suspend/resume cycle
+- Introduces environment variable reading
+- Tests integration with external tools
+
+---
+
+
+
+---
+
+[**Previous:** Atomic Operations](./19_atomic_operations.md) | [**Next:** Modal Overlays](./21_modal_overlays.md)

data/doc/tutorial/21_modal_overlays.md

@@ -0,0 +1,41 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Modal Overlays
+
+
+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 18: Help Overlay
+
+**As a** terminal user  
+**I want to** see a list of keyboard shortcuts  
+**So that** I can learn how to use the application
+
+### Acceptance Criteria
+- `?` key shows help overlay
+- Help displays all keyboard shortcuts organized by category
+- Help overlay is modal (blocks other input)
+- Any key closes help overlay
+- Help is scrollable if content is long
+
+### Notes
+- Introduces modal overlays
+- Introduces help content management
+- Critical for discoverability
+
+---
+
+
+
+---
+
+[**Previous:** External Editor](./20_external_editor.md) | [**Next:** Error Handling](./22_error_handling.md)

data/doc/tutorial/22_error_handling.md

@@ -0,0 +1,43 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Error Handling
+
+
+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 19: Error Handling and Messages
+
+**As a** terminal user  
+**I want to** see clear error messages when operations fail  
+**So that** I understand what went wrong and how to fix it
+
+### Acceptance Criteria
+- Permission errors show specific message and suggestion
+- File not found errors are handled gracefully
+- Invalid input shows validation errors
+- Errors displayed in status bar or dialog
+- Errors auto-dismiss after 5 seconds or on next action
+- Error messages are actionable, not generic
+
+### Notes
+- Introduces comprehensive error handling
+- Introduces error message system
+- Introduces auto-dismiss timers
+- Polish pass on all error paths
+
+---
+
+
+
+---
+
+[**Previous:** Modal Overlays](./21_modal_overlays.md) | [**Next:** Terminal Capabilities](./23_terminal_capabilities.md)

data/doc/tutorial/23_terminal_capabilities.md

@@ -0,0 +1,53 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Terminal Capabilities
+
+
+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 23: Visual Polish and Theming
+
+**As a** terminal user  
+**I want to** see a polished, professional interface  
+**So that** the application is pleasant to use
+
+### Acceptance Criteria
+- Consistent color scheme throughout:
+  - Directories: Blue (bold)
+  - Regular files: Default terminal color
+  - Executable files: Green
+  - Hidden files: Dim/gray when shown
+  - Selected item: Inverted colors or highlighted background
+  - Error messages: Red
+  - Success messages: Green
+  - Information messages: Yellow
+- File type icons (📁 📄 🔗) where appropriate
+- Smooth animations for state transitions
+- Proper spacing and alignment
+- Visual hierarchy clear
+- Works in both light and dark terminal themes
+
+### Notes
+- Polish pass on all UI elements
+- Introduces color management
+- Introduces Unicode symbols
+- Introduces animation system
+- Final aesthetic improvements
+- Implements all color requirements from specification section 2.2
+
+---
+
+
+
+---
+
+[**Previous:** Error Handling](./22_error_handling.md) | [**Next:** Mouse Events](./24_mouse_events.md)

data/doc/tutorial/24_mouse_events.md

@@ -0,0 +1,43 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Mouse Events
+
+
+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 20: Mouse Support
+
+**As a** terminal user with mouse-enabled terminal  
+**I want to** use my mouse to click and scroll  
+**So that** I have an alternative to keyboard navigation
+
+### Acceptance Criteria
+- Click on pane to focus it
+- Click on item to select it
+- Click on expand/collapse indicators
+- Mouse wheel scrolls in focused pane
+- All functionality remains keyboard-accessible
+- Mouse events don't break text selection
+
+### Notes
+- Optional enhancement
+- Introduces mouse event handling
+- Must not compromise keyboard experience
+- Terminal capability detection
+
+---
+
+
+
+---
+
+[**Previous:** Terminal Capabilities](./23_terminal_capabilities.md) | [**Next:** Resize Events](./25_resize_events.md)

data/doc/tutorial/25_resize_events.md

@@ -0,0 +1,43 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Resize Events
+
+
+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 21: Terminal Resize Handling
+
+**As a** terminal user  
+**I want to** resize my terminal window  
+**So that** the application adapts to the new size
+
+### Acceptance Criteria
+- Application detects terminal resize events
+- Layout adjusts proportionally to new size
+- Content reflows to fit new dimensions
+- Selection and scroll position preserved
+- No flickering during resize
+- Graceful degradation at small sizes (hide panes)
+
+### Notes
+- Introduces resize event handling
+- Introduces responsive layout logic
+- Introduces graceful degradation
+- Performance critical - must be smooth
+
+---
+
+
+
+---
+
+[**Previous:** Mouse Events](./24_mouse_events.md) | [**Next:** Loading States](./26_loading_states.md)

data/doc/tutorial/26_loading_states.md

@@ -0,0 +1,42 @@
+<!--
+  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:
+
+- 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 22: Loading States for Large Directories
+
+**As a** terminal user  
+**I want to** see a loading indicator for large directories  
+**So that** I know the application is working
+
+### Acceptance Criteria
+- Loading indicator shown when reading large directories
+- Spinner animation with item count
+- User can cancel loading with Esc
+- Partial results shown as they load
+- Performance remains responsive during load
+
+### Notes
+- Introduces async loading
+- Introduces loading indicators
+- Introduces cancellation
+- Performance optimization for 10,000+ files
+
+---
+
+
+
+---
+
+[**Previous:** Resize Events](./25_resize_events.md) | [**Next:** Performance](./27_performance.md)

data/doc/tutorial/27_performance.md

@@ -0,0 +1,43 @@
+<!--
+  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:
+
+- 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 24: Performance Optimization
+
+**As a** terminal user  
+**I want to** experience fast, responsive performance  
+**So that** the application doesn't slow me down
+
+### Acceptance Criteria
+- Startup time under 500ms
+- Keyboard input response under 50ms
+- Directory listing under 200ms for typical directories
+- Preview rendering under 100ms
+- No memory leaks during extended use
+- Efficient rendering (only redraw changed areas)
+
+### Notes
+- Performance profiling and optimization
+- Introduces benchmarking
+- Introduces efficient rendering strategies
+- May require caching and memoization
+
+---
+
+
+
+---
+
+[**Previous:** Loading States](./26_loading_states.md) | [**Next:** Color Schemes](./28_color_schemes.md)

data/doc/tutorial/28_color_schemes.md

@@ -0,0 +1,47 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Color Schemes
+
+
+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 26: Configurable Color Schemes
+
+**As a** user with color blindness  
+**I want to** configure the color scheme  
+**So that** I can distinguish different file types
+
+### Acceptance Criteria
+- Configuration file for color preferences (~/.config/file_browser/colors.yml)
+- Multiple built-in themes:
+  - Default (current colors)
+  - High contrast (black/white with bold)
+  - Colorblind-friendly (uses patterns + colors)
+  - Monochrome (no colors, uses bold/dim/underline)
+- Colors can be customized per file type
+- Theme selection persists between sessions
+- Theme can be changed via command-line flag
+- Preview of theme before applying
+
+### Notes
+- Addresses specification section 2.3 (Accessibility)
+- Introduces configuration file system
+- May be deferred to 1.1 release
+- Should validate color values
+
+---
+
+
+
+---
+
+[**Previous:** Performance](./27_performance.md) | [**Next:** Configuration](./29_configuration.md)