ratatui_ruby 0.4.0 → 0.5.0

data/doc/quickstart.md

@@ -29,7 +29,9 @@ gem install ratatui_ruby
 ```
 
 
-## Basic Application
+## Tutorials
+
+### Basic Application
 
 Here is a "Hello World" application that demonstrates the core lifecycle of a **ratatui_ruby** app.
 
@@ -44,7 +46,6 @@ begin
   loop do
     # 2. Create your UI (Immediate Mode)
     # We define a Paragraph widget inside a Block with a title and borders.
-    # Other widgets include RatatuiRuby::RatatuiMascot, RatatuiRuby::RatatuiLogo, etc.
     view = RatatuiRuby::Paragraph.new(
       text: "Hello, Ratatui! Press 'q' to quit.",
       alignment: :center,
@@ -58,11 +59,13 @@ begin
     )
  
     # 3. Draw the UI
-    RatatuiRuby.draw(view)
+    RatatuiRuby.draw do |frame|
+      frame.render_widget(view, frame.area)
+    end
  
     # 4. Poll for events
     event = RatatuiRuby.poll_event
-    break if event == "q" || event == :ctrl_c
+    break if event.key? && event.code == "q"
   end
 ensure
   # 5. Restore the terminal to its original state
@@ -70,15 +73,15 @@ ensure
 end
 ```
 
-![quickstart_lifecycle](./images/quickstart_lifecycle.png)
+![quickstart_lifecycle](./images/verify_quickstart_lifecycle.png)
 
-### How it works
+#### How it works
 
 1.  **`RatatuiRuby.init_terminal`**: Enters raw mode and switches to the alternate screen.
-2.  **Immediate Mode UI**: On every iteration of the loop, you describe what the UI should look like by creating `Data` objects (like `Paragraph` and `Block`).
-3.  **`RatatuiRuby.draw(view)`**: The Ruby UI tree is passed to the Rust backend, which renders it to the terminal.
-4.  **`RatatuiRuby.poll_event`**: Checks for keyboard, mouse, or resize events.
-5.  **`RatatuiRuby.restore_terminal`**: Crucial for leaving raw mode and returning the user to their shell properly. Always wrap your loop in a `begin...ensure` block to guarantee this runs.
+2.  **Immediate Mode UI**: On every iteration, describe your UI by creating `Data` objects (e.g., `Paragraph`, `Block`).
+3.  **`RatatuiRuby.draw { |frame| ... }`**: The block receives a `Frame` object as a canvas. Render widgets onto specific areas. Nothing is drawn until the block finishes, ensuring flicker-free updates.
+4.  **`RatatuiRuby.poll_event`**: Returns a typed `Event` object with predicates like `key?`, `mouse?`, `resize?`, etc. Returns `RatatuiRuby::Event::None` if no events are pending. Use predicates to check event type without pattern matching.
+5.  **`RatatuiRuby.restore_terminal`**: Essential for leaving raw mode and returning to the shell. Always wrap your loop in `begin...ensure` to guarantee this runs.
 
 ### Idiomatic Session
 
@@ -104,168 +107,192 @@ RatatuiRuby.run do |tui|
     )
 
     # 3. Use RatatuiRuby methods, too.
-    tui.draw(view)
-    event = tui.poll_event
-    
-    break if event == "q" || event == :ctrl_c
+    tui.draw do |frame|
+      frame.render_widget(view, frame.area)
+    end
+
+    # 4. Poll for events with pattern matching
+    case tui.poll_event
+    in { type: :key, code: "q" }
+      break
+    else
+      # Ignore other events
+    end
   end
 end
-
+```
 
 #### How it works
 
 1.  **`RatatuiRuby.run`**: This context manager initializes the terminal before the block starts and ensures `restore_terminal` is called when the block exits (even if an error occurs).
 2.  **Widget Shorthand**: The block yields a `Session` object (here named `tui`). This object provides factory methods for every widget, allowing you to write `tui.paragraph(...)` instead of the more verbose `RatatuiRuby::Paragraph.new(...)`.
-3.  **Method Shorthand**: The session object also provides aliases for module functions of `RatatuiRuby`, allowing you to write `tui.draw(...)` instead of the more verbose `RatatuiRuby::draw(...)`.
+3.  **Method Shorthand**: The session object also provides aliases for module functions of `RatatuiRuby`, allowing you to write `tui.draw(...)` instead of the more verbose `RatatuiRuby.draw(...)`.
+4.  **Pattern Matching for Events**: Use `case...in` with pattern matching for elegant event dispatch. Always include an `else` clause at the end to catch unmatched event types (mouse, resize, paste, focus, etc.), otherwise Ruby raises `NoMatchingPatternError`.
 
 For a deeper dive into the available application architectures (Manual vs Managed), see [Application Architecture](./application_architecture.md).
 
-## Examples
-
-To see more complex layouts and widget usage, check out the `examples/` directory in the repository.
+### Adding Layouts
 
-### [Analytics](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/analytics/app.rb)
+Real-world applications often need to split the screen into multiple areas. `RatatuiRuby::Layout` lets you do this easily.
 
-Demonstrates the use of `Tabs` and `BarChart` widgets. Features custom highlight styles, base styles, dividers for the tabs, and dynamic width calculation. The `BarChart` showcases both standard and grouped bars (Quarterly view), highlighting features like `group_gap` spacing, toggling `BarChart::direction`, customizing label/value styles, cycling custom `BarChart::bar_set` characters, and switching between Full and Mini height modes.
+```ruby
+require "ratatui_ruby"
 
-![analytics](./images/analytics.png)
+RatatuiRuby.run do |tui|
+  loop do
+    tui.draw do |frame|
+      # 1. Split the screen
+      top, bottom = tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          tui.constraint_percentage(75),
+          tui.constraint_percentage(25),
+        ]
+      )
 
-### [All Events](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/all_events/app.rb)
+      # 2. Render Top Widget
+      frame.render_widget(
+        tui.paragraph(
+          text: "Hello, Ratatui!",
+          alignment: :center,
+          block: tui.block(title: "Content", borders: [:all], border_color: "cyan")
+        ),
+        top
+      )
 
-A comprehensive demonstration of every event type supported by **ratatui_ruby**: Key, Mouse, Resize, Paste, and Focus events.
+      # 3. Render Bottom Widget with Styled Text
+      # We use a Line of Spans to style specific characters
+      text_line = tui.text_line(
+        spans: [
+          tui.text_span(content: "Press '"),
+          tui.text_span(
+            content: "q",
+            style: tui.style(modifiers: [:bold, :underlined])
+          ),
+          tui.text_span(content: "' to quit."),
+        ],
+        alignment: :center
+      )
 
-![all_events](./images/all_events.png)
+      frame.render_widget(
+        tui.paragraph(
+          text: text_line,
+          block: tui.block(title: "Controls", borders: [:all])
+        ),
+        bottom
+      )
+    end
+
+    case tui.poll_event
+    in { type: :key, code: "q" }
+      break
+    else
+      # Ignore other events
+    end
+  end
+end
+```
 
-### [Block Padding](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/block_padding/app.rb)
+#### How it works
 
-Demonstrates the `padding` property of the `Block` widget, supporting both uniform and directional padding.
+1.  **`tui.layout_split` (`RatatuiRuby::Layout.split`)**: Takes an area (like `frame.area`) and splits it into multiple sub-areas based on constraints.
+2.  **`tui.constraint_*` (`RatatuiRuby::Constraint`)**: Defines how space is distributed (e.g., `percentage`, `length`, `min`, `max`).
+3.  **`Frame#render_widget(widget, rect)`**: You pass the specific area (like `top` or `bottom`) to render the widget into that exact region.
+4.  **`tui.text_span` (`RatatuiRuby::Text::Span`)**: Allows for rich styling within a single line of text.
 
-![block_padding](./images/block_padding.png)
+## Examples
 
-### [Block Titles](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/block_titles/app.rb)
+These examples showcase the full power of **ratatui_ruby**. You can find their source code in the [examples directory](../examples).
 
-Demonstrates the `Block` widget's ability to render multiple titles with individual alignment and positioning (top/bottom).
+### Sample Applications
 
-![block_titles](./images/block_titles.png)
+Full-featured examples demonstrating complex layouts and real-world TUI patterns.
 
-### [Box Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/box_demo/app.rb)
 
-A simple demonstration of `Block` and `Paragraph` widgets, reacting to key presses to change colors, border types, border styles, and title styling. Features the new `border_style` parameter for applying colors and modifiers (bold, italic) to borders independently of the content background.
 
-![box_demo](./images/box_demo.png)
+#### [All Events](../examples/app_all_events/app.rb)
 
-### [Calendar Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/calendar_demo/app.rb)
+Handling terminal events is unpredictable. Developers need to know exactly what the terminal sends for `Ctrl+C` or a mouse drag.
 
-Demonstrates the `Calendar` widget with interactive attribute cycling. Features event highlighting (dates with specific styles), toggleable month/weekday headers, and surrounding month visibility (with custom styling) via keyboard shortcuts. Press `h` to toggle month header, `w` to toggle weekday header, `s` to toggle surrounding month dates, and `e` to toggle events.
+This app captures and visualizes every event—keys, mouse, resize, paste, and focus.
 
-![calendar_demo](./images/calendar_demo.png)
+Use it to debug your input handling or verify terminal behavior.
 
-### [Chart Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/chart_demo/app.rb)
+**What you'll learn:**
 
-Demonstrates the `Chart` widget with both scatter and line datasets, including custom axes. Features customizable axis label alignment and legend positioning.
+*   **MVVM Architecture**: Separates logic (Model), state (ViewModel), and rendering (View) for clean, testable code.
+*   **Event Handling**: Captures and distinguishes all input types, including modifiers (`Ctrl+C`) and focus changes.
+*   **Scalable Structure**: Organizes a non-trivial application into small, focused classes instead of a monolithic script.
 
-![chart_demo](./images/chart_demo.png)
+![all_events](./images/app_all_events.png)
 
-### [Custom Widget (Escape Hatch)](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/custom_widget/app.rb)
+#### [Color Picker](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/app_color_picker/app.rb)
 
-Demonstrates how to define a custom widget in pure Ruby using the `render(area, buffer)` escape hatch for low-level drawing.
+Interactive tools require complex state. Mapping mouse clicks to widgets and handling modal dialogs creates messy code if handled in the main loop.
 
-![custom_widget](./images/custom_widget.png)
+This app implements a full Color Picker using a "Scene-Orchestrated" pattern. The Scene calculates layout and exposes cached rectangles for hit testing.
 
-### [Flex Layout](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/flex_layout/app.rb)
+Use it to build forms, editors, and mouse-driven tools.
 
-Demonstrates modern layout features including `Constraint.fill` and `Constraint.ratio` for proportional space distribution and `flex: :space_between` for evenly distributing fixed-size elements.
+**What you'll learn:**
 
-![flex_layout](./images/flex_layout.png)
+*   **Scene-Orchestrated MVC**: Separates the View (layout/rendering) from the Controller (event loop) and Model (business logic).
+*   **Hit Testing**: Caches layout rectangles during the render pass to handle mouse clicks on specific elements.
+*   **Modal Dialogs**: Implements overlay patterns that intercept input.
 
-### [LineGauge Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/line_gauge_demo/app.rb)
+#### [Custom Widget (Escape Hatch)](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/app_custom_widget/app.rb)
 
-Demonstrates the `LineGauge` widget with customizable filled and unfilled symbols, base style support via the `style` parameter, independent styling for filled/unfilled portions, and interactive ratio cycling with arrow keys.
+Demonstrates how to define a custom widget in pure Ruby using the `render(area, buffer)` escape hatch for low-level drawing.
 
-![line_gauge_demo](./images/line_gauge_demo.png)
+![custom_widget](./images/app_custom_widget.png)
 
-### [List Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/list_demo/app.rb)
+#### [Layout Split Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/widget_layout_split/app.rb)
 
-Demonstrates the `List` widget with interactive attribute cycling. Features multiple item sets to browse, customizable highlight styles and symbols, and exploration of all List options including direction, highlight spacing, repeat symbol mode, scroll padding, and base styling. The sidebar provides hotkey documentation for discovering all List features, including the new `p` key to adjust scroll padding.
+Demonstrates `Layout.split` with interactive attribute cycling. Features hotkey controls For direction (vertical/horizontal), all 7 flex modes (legacy, start, center, end, space_between, space_around, space_evenly), and constraint types (fill, length, percentage, min, ratio).
 
-![list_demo](./images/list_demo.png)
+![widget_layout_split](./images/widget_layout_split.png)
 
-### [Login Form](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/login_form/app.rb)
+#### [Login Form](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/app_login_form/app.rb)
 
 Shows how to use `Overlay`, `Center`, and `Cursor` to build a modal login form with text input.
 
-![login_form](./images/login_form.png)
+![login_form](./images/app_login_form.png)
 
-### [Map Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/map_demo/app.rb)
+#### [Map Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/app_map_demo/app.rb)
 
 Exhibits the `Canvas` widget's power, rendering a world map with city labels, animated circles, and lines.
 
-![map_demo](./images/map_demo.png)
-
-### [Mouse Events](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/mouse_events/app.rb)
-
-Detailed plumbing of mouse events, including clicks, drags, and movement tracking.
-
-![mouse_events](./images/mouse_events.png)
-
-### [Popup Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/popup_demo/app.rb)
-
-Demonstrates the `Clear` widget and how to prevent "style bleed" when rendering opaque popups over colored backgrounds.
-
-![popup_demo](./images/popup_demo.png)
+![map_demo](./images/app_map_demo.png)
 
-### [Ratatui Logo Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/ratatui_logo_demo/app.rb)
-
-Demonstrates the `RatatuiLogo` widget.
-
-
-![ratatui_logo_demo](./images/ratatui_logo_demo.png)
-
-### [Rich Text](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/rich_text/app.rb)
-
-Demonstrates `Text::Span` and `Text::Line` for creating styled text with inline formatting, enabling word-level control over colors and text modifiers.
-
-![rich_text](./images/rich_text.png)
-
-### [Scrollbar Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/scrollbar_demo/app.rb)
-
-A demonstration of the `Scrollbar` widget, featuring mouse wheel scrolling and extensive customization of symbols and styles.
-
-![scrollbar_demo](./images/scrollbar_demo.png)
-
-### [Scroll Text](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/scroll_text/app.rb)
-
-Demonstrates the `Paragraph` widget's scroll functionality, allowing navigation through long text content using arrow keys for both horizontal and vertical scrolling.
-
-![scroll_text](./images/scroll_text.png)
-
-### [Sparkline Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/sparkline_demo/app.rb)
-
-Demonstrates the `Sparkline` widget with interactive attribute cycling. Features multiple data sets with different patterns (steady growth, gaps, random, sawtooth, peaks), and explores all `Sparkline` options including direction, color, the new `absent_value_symbol` and `absent_value_style` parameters for distinguishing zero/absent values from low data, and the new `bar_set` parameter for custom bar characters.
-
-![sparkline_demo](./images/sparkline_demo.png)
-
-### [Gauge Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/gauge_demo/app.rb)
-
-Demonstrates the `Gauge` widget with interactive attribute cycling. Features multiple gauge instances with customizable ratio, gauge color, background style, Unicode toggle, and label modes. The sidebar provides hotkey documentation for exploring all Gauge options, including the distinction between `style` (background) and `gauge_style` (filled bar).
-
-![gauge_demo](./images/gauge_demo.png)
-
-### [Table Select](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/table_select/app.rb)
+#### [Table Select](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/app_table_select/app.rb)
 
 Demonstrates interactive row selection in the `Table` widget with keyboard navigation, highlighting selected rows with custom styles and symbols, applying a base style, and dynamically adjusting `column_spacing`. Also demonstrates `column_highlight_style` and the new `cell_highlight_style` for precise selection visualization.
 
-![table_select](./images/table_select.png)
-
-### [Table Flex](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/table_flex/app.rb)
-
-Demonstrates different flex modes in the `Table` widget, such as `:space_between` and `:space_around`, allowing for modern, responsive table layouts.
-
-![table_flex](./images/table_flex.png)
-
-### [Widget Style Colors](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/widget_style_colors/app.rb)
-
-Demonstrates hexadecimal color code support in Style parameters. Renders an 80x24 color gradient using HSL-to-RGB conversion and #RRGGBB hex codes, showcasing 24-bit true color rendering on capable terminals.
-
-![widget_style_colors](./images/widget_style_colors.png)
-
+![table_select](./images/app_table_select.png)
+
+
+### Widget Demos
+
+These smaller, focused examples demonstrate specific widgets and their configuration options.
+
+*   [Bar Chart](../examples/widget_barchart_demo/app.rb)
+*   [Block Padding](../examples/widget_block_padding/app.rb)
+*   [Block Titles](../examples/widget_block_titles/app.rb)
+*   [Box (Block/Paragraph)](../examples/widget_box_demo/app.rb)
+*   [Calendar](../examples/widget_calendar_demo/app.rb)
+*   [Chart](../examples/widget_chart_demo/app.rb)
+*   [Gauge](../examples/widget_gauge_demo/app.rb)
+*   [Line Gauge](../examples/widget_line_gauge_demo/app.rb)
+*   [List](../examples/widget_list_demo/app.rb)
+*   [Popup (Clear)](../examples/widget_popup_demo/app.rb)
+*   [Rect](../examples/widget_rect/app.rb)
+*   [Ratatui Logo](../examples/widget_ratatui_logo_demo/app.rb)
+*   [Ratatui Mascot](../examples/widget_ratatui_mascot_demo/app.rb)
+*   [Rich Text](../examples/widget_rich_text/app.rb)
+*   [Scrollbar](../examples/widget_scrollbar_demo/app.rb)
+*   [Scroll Text](../examples/widget_scroll_text/app.rb)
+*   [Sparkline](../examples/widget_sparkline_demo/app.rb)
+*   [Table Flex](../examples/widget_table_flex/app.rb)
+*   [Tabs](../examples/widget_tabs_demo/app.rb)
+*   [Widget Style Colors](../examples/widget_style_colors/app.rb)

data/examples/app_all_events/README.md

@@ -0,0 +1,81 @@
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# App All Events Example
+
+This example application captures and visualizes every event supported by `ratatui_ruby`. It serves as a comprehensive reference for event handling and a demonstration of a clean, scalable architectural pattern.
+
+## Architecture: MVVM (Model-View-ViewModel)
+
+This application demonstrates the **Model-View-ViewModel (MVVM)** pattern, modified for the immediate-mode nature of terminal UIs. This separation of concerns ensures that the UI logic is completely decoupled from the business logic, making the application easier to test and maintain.
+
+### 1. Model (`model/`)
+The **Model** manages the application's domain data and logic. It knows nothing about the UI.
+
+*   **`Events` (`model/events.rb`)**: The core store. It records incoming events, maintains statistics (counts), and handles business logic like "highlight this event type for 300ms."
+*   **`EventEntry` (`model/event_entry.rb`)**: A value object representing a single recorded event.
+
+### 2. View State (ViewModel) (`view_state.rb`)
+The **View State** (comparable to a ViewModel or Presenter) is an immutable data structure built specifically for the View.
+
+*   **`ViewState`**: It acts as a bridge. In every render loop, the application builds a fresh `ViewState` object, calculating derived data (like styles, active flags, and formatted strings) from the raw Model data.
+*   **Why?**: This prevents the View from having to contain logic. The View doesn't ask "is the app focused so I should use green?"; it just asks `state.border_color`.
+
+### 3. View (`view/`)
+The **View** is responsible **only** for rendering. It receives the `ViewState` and draws to the screen.
+
+*   **`View::App` (`view/app_view.rb`)**: The root view. It handles the high-level layout (splitting the screen into areas).
+*   **Sub-views**: `Counts`, `Live`, `Log`, `Controls`. Each is a small, focused component that renders a specific part of the screen based on the data in `ViewState`.
+
+### 4. Controller/App (`app.rb`)
+The **`AppAllEvents`** class ties it all together. It owns the main loop:
+
+1.  **Poll**: Waits for an event from the terminal.
+2.  **Update**: Passes the event to the **Model** (`@events.record`).
+3.  **Build State**: Creates a new **ViewState** from the current Model and global state.
+4.  **Render**: Passes the **ViewState** to the **View** to draw the frame.
+
+## Library Features Showcased
+
+Reading this code will teach you how to:
+
+*   **Handle All Events**:
+    *   **Keyboard**: Capture normal keys and modifiers (`Ctrl+c`, `q`).
+    *   **Mouse**: track clicks, drags, and scroll events.
+    *   **Focus**: React to the terminal window gaining or losing focus (`FocusGained`/`FocusLost`).
+    *   **Resize**: Dynamically adapt layouts when the terminal size changes.
+    *   **Paste**: Handle bracketed paste events (if supported by the terminal).
+*   **Layouts**: Use `tui.layout_split` with constraints (`Length`, `Fill`) to create complex, responsive dashboards.
+*   **Styling**: Apply dynamic styles (bold, colors) based on application state.
+*   **Structure**: Organize a non-trivial CLI tool into small, single-purpose classes.
+
+## What Problems Does This Solve?
+
+### "What key code is my terminal sending?"
+If you are building an app and your logic isn't catching `Ctrl+Left`, run this app and press the keys. You will see exactly how `ratatui_ruby` parses that input (e.g., is it a `Key` event? What are the modifiers?).
+
+### "How do I structure a real app?"
+Hello World examples are great, but they don't scale. This example shows how to structure an application that can grow. By simulating a "dashboard" with multiple independent widgets updating in real-time, it solves the problem of "how do I pass data around without global variables?"
+
+### "How do I implement an event loop?"
+It provides a robust reference implementation of the standard `loop { draw; handle_input }` cycle, including the correct way to handle quit signals.
+
+## Comparison: Choosing an Architecture
+
+Complex applications require structured state habits. `AppAllEvents` and the [Color Picker](../app_color_picker/README.md) demonstrate two different approaches.
+
+### The Dashboard Approach (AppAllEvents)
+
+Dashboards display data. They rarely require complex mouse interaction. Strict MVVM works best here. The View is a pure function. It accepts a `ViewState` and draws it. It ignores input. This simplifies testing.
+
+Use this pattern for logs, monitors, and data viewers.
+
+### The Tool Approach (Color Picker)
+
+Tools require interaction. Users click buttons and drag sliders. The Controller needs to know where components exist on screen. MVVM hides this layout data.
+
+The Color Picker uses a "Scene" pattern. The View exposes layout rectangles. The Controller uses these rectangles to handle mouse clicks.
+
+Use this pattern for forms, editors, and mouse-driven tools.

data/examples/app_all_events/app.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+$LOAD_PATH.unshift File.expand_path(__dir__)
+
+require "ratatui_ruby"
+require_relative "model/events"
+require_relative "view_state"
+require_relative "view/app_view"
+
+# Demonstrates the full range of terminal events supported by RatatuiRuby.
+#
+# Developers need a comprehensive example to understand how keys, mouse, resize, and focus events behave.
+# Testing event handling across different terminal emulators and platforms can be unpredictable.
+#
+# This application captures and logs every event received from the backend, providing real-time feedback and history.
+#
+# Use it to verify your terminal's capabilities or as a reference for complex event handling.
+#
+# === Examples
+#
+#   # Run from the command line:
+#   # ruby examples/app_all_events/app.rb
+#
+#   app = AppAllEvents.new
+#   app.run
+class AppAllEvents
+  # List of all event types tracked by this application.
+  EVENT_TYPES = %i[key mouse resize paste focus none].freeze
+
+  # Creates a new AppAllEvents instance and initializes its state.
+  def initialize
+    @view = View::App.new
+    @events = Events.new
+    @focused = true
+    @last_dimensions = [80, 24]
+  end
+
+  # Starts the application event loop.
+  #
+  # === Example
+  #
+  #   app.run
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+      loop do
+        render
+        break if handle_input == :quit
+      end
+    end
+  end
+
+  private def render
+    view_state = ViewState.build(
+      @events,
+      @focused,
+      @tui,
+      nil
+    )
+
+    @tui.draw { |frame| @view.call(view_state, @tui, frame, frame.area) }
+  end
+
+  private def handle_input
+    event = @tui.poll_event
+
+    case event
+    when RatatuiRuby::Event::Key
+      return :quit if event.code == "q"
+      return :quit if event.code == "c" && event.modifiers.include?("ctrl")
+      @events.record(event)
+    when RatatuiRuby::Event::Resize
+      @events.record(event, context: { last_dimensions: @last_dimensions })
+      @last_dimensions = [event.width, event.height]
+    when RatatuiRuby::Event::FocusGained
+      @focused = true
+      @events.record(event)
+    when RatatuiRuby::Event::FocusLost
+      @focused = false
+      @events.record(event)
+    else
+      @events.record(event)
+    end
+
+    nil
+  end
+end
+
+AppAllEvents.new.run if __FILE__ == $PROGRAM_NAME

data/examples/app_all_events/model/event_color_cycle.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# Cycles through a set of colors for event logging.
+#
+# Sequential events in a log are hard to distinguish if they all look the same.
+# Manually assigning colors to every event type or entry is repetitive.
+#
+# This class automatically cycles through a predefined list of vibrant colors.
+#
+# Use it to give each event in a log a distinct visual identity.
+#
+# === Examples
+#
+#   cycler = EventColorCycle.new
+#   cycler.next_color #=> :cyan
+#   cycler.next_color #=> :magenta
+#   cycler.next_color #=> :yellow
+#   cycler.next_color #=> :cyan
+class EventColorCycle
+  # List of colors to cycle through.
+  COLORS = %i[cyan magenta yellow].freeze
+
+  # Creates a new EventColorCycle.
+  def initialize
+    @index = 0
+  end
+
+  # Returns the next color in the cycle.
+  #
+  # === Example
+  #
+  #   cycler.next_color #=> :cyan
+  def next_color
+    color = COLORS[@index]
+    @index = (@index + 1) % COLORS.length
+    color
+  end
+end

data/examples/app_all_events/model/event_entry.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require_relative "timestamp"
+require "ratatui_ruby"
+
+# Stores details about a single event in the history log.
+#
+# Event logs need to store diverse data including types, keys, colors, and timestamps.
+# Managing loose hashes or arrays for event history is error-prone and hard to query.
+#
+# This class provides a structured data object for every recorded event.
+#
+# Use it to represent mouse clicks, key presses, or resize events in a log.
+#
+# === Examples
+#
+#   # Typically created via Events.record
+#   entry = EventEntry.create(key_event, :cyan, Timestamp.now)
+#   puts entry.type #=> :key
+#   puts entry.description #=> '#<RatatuiRuby::Event::Key ...>'
+class EventEntry < Data.define(:event, :color, :timestamp)
+  # Creates a new EventEntry.
+  #
+  # [event] RatatuiRuby::Event object.
+  # [color] Symbol color for the log display.
+  # [timestamp] Timestamp of when the event occurred.
+  def self.create(event, color, timestamp)
+    new(
+      event:,
+      color:,
+      timestamp:
+    )
+  end
+
+  # Returns the event type.
+  #
+  # === Example
+  #
+  #   entry.type #=> :key
+  def type
+    case event
+    when RatatuiRuby::Event::Key then :key
+    when RatatuiRuby::Event::Mouse then :mouse
+    when RatatuiRuby::Event::Resize then :resize
+    when RatatuiRuby::Event::Paste then :paste
+    when RatatuiRuby::Event::FocusGained then :focus_gained
+    when RatatuiRuby::Event::FocusLost then :focus_lost
+    else :unknown
+    end
+  end
+
+  # Returns the event description using inspect.
+  #
+  # === Example
+  #
+  #   entry.description #=> '#<RatatuiRuby::Event::Key code="a" modifiers=[]>'
+  def description
+    event.inspect
+  end
+
+  # Checks if the entry matches the given type.
+  #
+  # [check_type] Symbol type to check against.
+  #
+  # === Example
+  #
+  #   entry.matches_type?(:key) #=> true
+  def matches_type?(check_type)
+    return true if check_type == :focus && (type == :focus_gained || type == :focus_lost)
+    type == check_type
+  end
+end