ratatui_ruby 0.3.1 → 0.4.0

data/doc/contributors/example_analysis.md

@@ -0,0 +1,82 @@
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Example Analysis
+
+The `examples/` directory contains examples in three distinct categories, each serving a different purpose.
+
+## Category 1: Widget Showcases
+
+Single-widget (or widget-focused) examples that exhaustively demonstrate a widget's configuration options through interactive attribute cycling.
+
+These examples follow the pattern described in `developing_examples.md`: they expose all major widget parameters as hotkey-controllable options so users can interactively explore the behavior. They render at most two widgets side-by-side or vertically stacked for comparison purposes, all in service of the primary widget.
+
+**Examples:**
+- `box_demo`: Demonstrates Block widget variations (border types, styles, padding, titles).
+- `gauge_demo`: Demonstrates Gauge with adjustable ratio, color, Unicode flag, and label modes.
+- `list_demo`: Demonstrates List with items, highlight styles, symbols, spacing, direction, and scroll padding.
+- `line_gauge_demo`: Demonstrates LineGauge widget attributes.
+- `sparkline_demo`: Demonstrates Sparkline with direction, style, absent value markers, and bar sets.
+- `scrollbar_demo`: Demonstrates Scrollbar with orientation and theme cycling.
+- `chart_demo`: Demonstrates Chart widget attributes.
+- `calendar_demo`: Demonstrates Calendar widget.
+- `cell_demo`: Demonstrates Cell widget.
+- `block_titles`: Demonstrates Block title positioning and alignment.
+- `block_padding`: Demonstrates Block padding (uniform and directional).
+- `ratatui_logo_demo`: Demonstrates RatatuiLogo with style cycling.
+- `ratatui_mascot_demo`: Demonstrates RatatuiMascot with style cycling.
+- `list_styles`: Demonstrates List styling variations.
+- `popup_demo`: Demonstrates Popup widget positioning and behavior.
+- `scroll_text`: Demonstrates text scrolling behavior.
+
+## Category 2: Real-Application Showcases
+
+Examples that function as proof-of-concept TUI applications, demonstrating how to build moderately complex, interactive programs.
+
+These are not API documentation—they do not systematically cycle through all widget parameters. Instead, they showcase composing multiple widgets to solve realistic problems (dashboards, forms, data views). They serve as inspiration for developers building their own applications and do not strictly follow the single-focus pattern.
+
+**Examples:**
+- `analytics`: Multi-widget analytics dashboard with Tabs and BarChart, demonstrating tab navigation and multi-chart layouts.
+- `login_form`: Form UI with text input, cursor positioning, and popup feedback using Paragraph, Overlay, Center, and Cursor.
+- `table_select`: Interactive table viewer with row/column selection, simulating a process monitor application.
+- `hit_test`: Demonstrates layout caching pattern for hit testing with split panels and mouse interaction.
+- `map_demo`: Canvas-based world map visualization with animated shapes and interactive marker cycling.
+- `mouse_events`: Multi-panel event display app showcasing all mouse event types.
+- `all_events`: Multi-panel dashboard displaying all event types (key, mouse, resize, paste, focus).
+- `flex_layout`: Layout demo showcasing Layout flex modes (space_between, space_evenly, fill, ratio).
+- `custom_widget`: Demonstrates custom widget implementation with a diagonal line widget.
+
+## Category 3: Documentation-Verification Examples
+
+Examples that are verbatim copies (or near copies) of code snippets from documentation files, added to the `examples/` directory to ensure they remain executable and don't rot.
+
+These serve as automated documentation tests: if the example code changes but the documentation does not, tests will fail and reveal the inconsistency.
+
+**Examples:**
+- `quickstart_lifecycle`: Copy of the lifecycle example from `README.md` or quickstart documentation.
+- `quickstart_dsl`: Copy of the DSL-style example from quickstart documentation.
+- `readme_usage`: Copy of the simple "Hello, Ratatui!" example from `README.md`.
+
+## TODO
+
+- [ ] **Establish a naming prefix convention** to disambiguate categories alphabetically without requiring subdirectories. Suggested prefixes:
+  - `app_` (application): `app_analytics`, `app_login_form`, etc.
+  - `verify_` (doc/documentation): `verify_quickstart_lifecycle`, `verify_readme_usage`, etc.
+  - `widget_` (widget showcase): `widget_gauge_demo`, `widget_list_demo`, etc.
+  - Apply this retroactively to all examples via directory renames (includes renaming screenshots in `doc/images/`, updating markdown image references in documentation, updating links in markdown files, and ensuring the `ExampleApp.all` list reflects the new names).
+
+- [ ] **Split `analytics`** (demonstrates both Tabs and BarChart interactively). Create `widget_tabs_demo` and move BarChart demo to it, or extract BarChart into its own single-widget showcase.
+
+- [ ] **Split `all_events`** (demonstrates multiple event types in a 2×2 grid). Consider extracting each event type into its own single-widget panel, or clarify whether this remains a "showcase of everything" vs. a focused event-demo.
+
+- [ ] **Split `flex_layout`** (demonstrates Layout flex modes with multiple examples). This is borderline—it's quasi-documentation-verification of Layout behavior. Consider whether it belongs as `verify_flex_layout` or if it should remain as a showcase.
+
+- [ ] **Reassign `mouse_events`**: Currently straddles Category 2 (real app) and Category 3 (doc verification). Clarify its purpose: is it an app showcase or documenting mouse event structure? If doc-verification, move to Category 3 and rename to `verify_mouse_events`.
+
+- [ ] **Reassign `hit_test`**: Currently categorized as Category 2 but serves partly to document the "Cached Layout Pattern". Consider renaming to `verify_hit_test` if it should be documentation-verification, or ensure it's purely a showcase of an application pattern.
+
+- [ ] **Verify `custom_widget`**: Currently Category 2 (real app), but is it actually a documented pattern or example code? If it's meant to verify custom widget documentation, rename to `verify_custom_widget`.
+
+- [ ] **Update documentation** (developing_examples.md) to reflect the new naming convention and clarify which category each example should belong to.

data/doc/custom.css

@@ -1,3 +1,8 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
 img {
   max-width: 100%;
   height: auto;
@@ -5,4 +10,13 @@ img {
 
 .theme-toggle {
   margin-left: 0 !important;
+}
+
+/* Terminal Previews (Native PNGs)
+ * The images already contain the window chrome and shadows.
+ * We just need to center them and ensure they scale down on mobile.
+ */
+img[src*="images/"] {
+  display: block;
+  margin: 2em auto;
 }

data/doc/event_handling.md

@@ -0,0 +1,119 @@
+# Event Handling in RatatuiRuby
+
+`ratatui_ruby` provides a rich, object-oriented event system that supports multiple coding styles, from simple boolean predicates to modern Ruby pattern matching.
+
+Events are retrieved using `RatatuiRuby.poll_event`. This method returns an instance of a subclass of `RatatuiRuby::Event` (e.g., `RatatuiRuby::Event::Key`, `RatatuiRuby::Event::Mouse`) or `nil` if no event is available.
+
+## 1. Symbol and String Comparison (Simplest)
+
+For simple key events, `RatatuiRuby::Event::Key` objects can be compared directly to Symbols or Strings. This is often the quickest way to get started.
+
+*   **String**: Matches the key character (e.g., "a", "q").
+*   **Symbol**: Matches special keys (e.g., `:enter`, `:esc`) or modifier combinations (e.g., `:ctrl_c`).
+
+> [!NOTE]
+> On macOS, the **Option** key is mapped to `alt`. The **Command** key is typically intercepted by the terminal emulator and may not be sent to the application, or it may be mapped to Meta/Alt depending on your terminal settings.
+
+For a complete list of supported keys, modifiers, and event types, please refer to the [API Documentation for RatatuiRuby::Event](file:///Users/kerrick/Developer/ratatui_ruby/lib/ratatui_ruby/event.rb).
+
+```ruby
+event = RatatuiRuby.poll_event
+next unless event
+
+# 1. Check for quit keys
+if event == "q" || event == :ctrl_c
+  break
+end
+
+# 2. Check for special key
+if event == :enter
+  submit_form
+end
+```
+
+## 2. Predicate Methods (Intermediate)
+
+If you need more control or logic (e.g. `if/elsif`), or need to handle non-key events like Resize or Mouse, use the predicate methods.
+
+### Polymorphic Predicates
+
+Safe to call on *any* event object. They return `true` only for the matching event type.
+
+Available: `key?`, `mouse?`, `resize?`, `paste?`, `focus_gained?`, `focus_lost?`.
+
+```ruby
+event = RatatuiRuby.poll_event
+
+if event.key?
+  handle_keypress(event)
+elsif event.mouse?
+  handle_click(event)
+elsif event.resize?
+  resize_layout(event.width, event.height)
+end
+```
+
+### Helper Predicates
+
+Specific to certain event classes to simplify checks.
+
+#### `RatatuiRuby::Event::Key`
+*   `ctrl?`, `alt?`, `shift?`: Check if modifier is held.
+*   `text?`: Returns `true` if the event is a printable character (length == 1).
+
+```ruby
+if event.key? && event.ctrl? && event.code == "s"
+  save_file
+end
+```
+
+#### `RatatuiRuby::Event::Mouse`
+*   `down?`, `up?`, `drag?`: Check mouse action.
+*   `scroll_up?`, `scroll_down?`: Check scroll direction.
+
+```ruby
+if event.mouse? && event.scroll_up?
+  scroll_view(-1)
+end
+```
+
+## 3. Pattern Matching (Powerful)
+
+For complex applications, Ruby 3.0+ Pattern Matching with the `type:` discriminator is the most idiomatic and concise approach.
+
+```ruby
+loop do
+  case RatatuiRuby.poll_event
+  
+  # Match specific key code
+  in type: :key, code: "q"
+    break
+
+  # Match complex combo
+  in type: :key, code: "c", modifiers: ["ctrl"]
+    break
+
+  # Capture variables
+  in type: :key, code: "up" | "down" => direction
+    move_cursor(direction)
+
+  # Match mouse events
+  in type: :mouse, kind: "down", x:, y:
+    handle_click(x, y)
+
+  else
+    # Ignore
+  end
+end
+```
+
+## Summary of Event Classes
+
+| Event Class | Discriminator (`type:`) | Attributes | Predicate |
+| :--- | :--- | :--- | :--- |
+| `RatatuiRuby::Event::Key` | `:key` | `code`, `modifiers` | `key?` |
+| `RatatuiRuby::Event::Mouse` | `:mouse` | `kind`, `x`, `y`, `button`, `modifiers` | `mouse?` |
+| `RatatuiRuby::Event::Resize` | `:resize` | `width`, `height` | `resize?` |
+| `RatatuiRuby::Event::Paste` | `:paste` | `content` | `paste?` |
+| `RatatuiRuby::Event::FocusGained` | `:focus_gained` | (none) | `focus_gained?` |
+| `RatatuiRuby::Event::FocusLost` | `:focus_lost` | (none) | `focus_lost?` |

data/doc/index.md

@@ -9,6 +9,7 @@
 
 - [README](../README.md)
 - [Quickstart](./quickstart.md)
+- [Application Architecture](./application_architecture.md)
 - [Testing Your Application](./application_testing.md)
 
 

data/doc/interactive_design.md

@@ -0,0 +1,121 @@
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Interactive TUI Design Patterns
+
+Canonical patterns for building responsive, interactive terminal user interfaces with ratatui_ruby.
+
+## The Cached Layout Pattern
+
+**Context:** In immediate-mode TUI development, you render once per event loop. The render happens, the user clicks, you respond. This cycle repeats 60 times a second.
+
+**Problem:** Your layout has constraints. When you render, you calculate where each widget goes. When the user clicks, you need to know which widget was under the cursor. Two separate calculations means two separate constraint definitions. Change the layout once and forget to update the hit test logic—bugs happen.
+
+**Solution:** Calculate layout once. Cache the results. Reuse them everywhere.
+
+### The Three-Phase Lifecycle
+
+Structure your event loop into three clear phases:
+
+```ruby
+def run
+  RatatuiRuby.run do
+    loop do
+      calculate_layout   # Phase 1: Geometry (once per frame)
+      render             # Phase 2: Draw
+      break if handle_input == :quit  # Phase 3: Input
+    end
+  end
+end
+```
+
+**Phase 1: Layout Calculation**
+
+Call this before rendering and event handling. It's the single source of truth for geometry:
+
+```ruby
+def calculate_layout
+  full_area = RatatuiRuby::Rect.new(x: 0, y: 0, width: 80, height: 24)
+
+  # Main area vs sidebar (70% / 30%)
+  main_area, @sidebar_area = RatatuiRuby::Layout.split(
+    full_area,
+    direction: :horizontal,
+    constraints: [
+      RatatuiRuby::Constraint.percentage(70),
+      RatatuiRuby::Constraint.percentage(30),
+    ]
+  )
+
+  # Within main area, left vs right panels
+  @left_rect, @right_rect = RatatuiRuby::Layout.split(
+    main_area,
+    direction: :horizontal,
+    constraints: [
+      RatatuiRuby::Constraint.percentage(@left_ratio),
+      RatatuiRuby::Constraint.percentage(100 - @left_ratio)
+    ]
+  )
+end
+```
+
+**Phase 2: Rendering**
+
+Reuse the cached rects. Build and draw:
+
+```ruby
+def render
+  left_panel = build_widget(@left_rect)
+  right_panel = build_widget(@right_rect)
+  # ... draw ...
+end
+```
+
+**Phase 3: Event Handling**
+
+Reuse the cached rects. Test clicks:
+
+```ruby
+def handle_input
+  event = RatatuiRuby.poll_event
+  return unless event
+
+  case event
+  in type: :mouse, kind: "down", x:, y:
+    if @left_rect.contains?(x, y)
+      handle_left_click
+    elsif @right_rect.contains?(x, y)
+      handle_right_click
+    end
+  else
+    nil
+  end
+end
+```
+
+### Why This Matters
+
+- **Single source of truth:** Change constraints once. They apply everywhere.
+- **No duplication:** Write `Layout.split(area, constraints:)` once. Use the result in render and input.
+- **Testable:** Layout geometry is explicit. You can verify it.
+- **Foundation for components:** In Gem 1.5, the `Component` class automates this caching. This pattern teaches the mental model.
+
+## Layout.split
+
+`Layout.split` computes layout geometry without rendering. It returns an array of `Rect` objects.
+
+```ruby
+rects = Layout.split(
+  area,
+  direction: :horizontal,
+  constraints: [Constraint.percentage(70), Constraint.percentage(30)]
+)
+
+left, right = rects
+# left is a Rect describing the left 70% of the area
+# right is a Rect describing the right 30% of the area
+```
+
+Use it to establish the single source of truth in `calculate_layout`. Reuse the results in both render and event handling.