ratatui_ruby 0.3.1 → 0.5.0

data/doc/interactive_design.md

@@ -0,0 +1,116 @@
+<!--
+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 |tui|
+    @tui = tui
+    loop do
+      @tui.draw do |frame|
+        calculate_layout(frame.area) # Phase 1: Geometry (once per frame)
+        render(frame)                # Phase 2: Draw
+      end
+      break if handle_input == :quit  # Phase 3: Input
+    end
+  end
+end
+```
+
+**Phase 1: Layout Calculation**
+
+Call this inside your `draw` block. It uses the current terminal area provided by the frame:
+
+```ruby
+def calculate_layout(area)
+  # Main area vs sidebar (70% / 30%)
+  main_area, @sidebar_area = @tui.layout_split(
+    area,
+    direction: :horizontal,
+    constraints: [
+      @tui.constraint_percentage(70),
+      @tui.constraint_percentage(30),
+    ]
+  )
+
+  # Within main area, left vs right panels
+  @left_rect, @right_rect = @tui.layout_split(
+    main_area,
+    direction: :horizontal,
+    constraints: [
+      @tui.constraint_percentage(@left_ratio),
+      @tui.constraint_percentage(100 - @left_ratio)
+    ]
+  )
+end
+```
+
+**Phase 2: Rendering**
+
+Reuse the cached rects. Build and draw:
+
+```ruby
+def render(frame)
+  frame.render_widget(build_widget(@left_rect), @left_rect)
+  frame.render_widget(build_widget(@right_rect), @right_rect)
+end
+```
+
+**Phase 3: Event Handling**
+
+Reuse the cached rects. Test clicks:
+
+```ruby
+def handle_input
+  event = RatatuiRuby.poll_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. While you can call `RatatuiRuby::Layout.split` directly, we recommend using the `Session` helper (`tui.layout_split`) for cleaner application code.
+
+```ruby
+# Preferred (Session API)
+left, right = tui.layout_split(area, constraints: [...])
+
+# Manual (Core API)
+left, right = RatatuiRuby::Layout.split(area, constraints: [...])
+```
+
+Use it to establish the single source of truth inside your `draw` block. Store the results in instance variables and reuse them in both `render` and `handle_input`.

data/doc/quickstart.md

@@ -14,19 +14,24 @@ Add this line to your application's Gemfile:
 gem "ratatui_ruby"
 ```
 
+
 And then execute:
 
 ```bash
 bundle install
 ```
 
+
 Or install it yourself as:
 
 ```bash
 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.
 
@@ -43,22 +48,24 @@ begin
     # We define a Paragraph widget inside a Block with a title and borders.
     view = RatatuiRuby::Paragraph.new(
       text: "Hello, Ratatui! Press 'q' to quit.",
-      align: :center,
+      alignment: :center,
       block: RatatuiRuby::Block.new(
         title: "My Ruby TUI App",
+        title_alignment: :center,
         borders: [:all],
-        border_color: "cyan"
+        border_color: "cyan",
+        style: { fg: "white" }
       )
     )
  
     # 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
-    if event && event[:type] == :key && event[:code] == "q"
-      break
-    end
+    break if event.key? && event.code == "q"
   end
 ensure
   # 5. Restore the terminal to its original state
@@ -66,131 +73,226 @@ ensure
 end
 ```
 
-![Basic Application Screenshot](./images/examples-quickstart_lifecycle.rb.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.
 
-### DSL
+### Idiomatic Session
 
-A small DSL is provided for convenience when writing scripts.
+You can simplify your code by using `RatatuiRuby.run`. This method handles the terminal lifecycle for you, yielding a `Session` object with factory methods for widgets.
 
 ```rb
 require "ratatui_ruby"
 
-# 1. Initialize the terminal, start the main loop, and ensure the terminal is restored.
-RatatuiRuby.main_loop do |tui|
-  # 2. Create your UI with methods instead of classes.
-  view = tui.paragraph(
-    text: "Hello, Ratatui! Press 'q' to quit.",
-    align: :center,
-    block: tui.block(
-      title: "My Ruby TUI App",
-      borders: [:all],
-      border_color: "cyan"
+# 1. Initialize the terminal and ensure it is restored.
+RatatuiRuby.run do |tui|
+  loop do
+    # 2. Create your UI with methods instead of classes.
+    view = tui.paragraph(
+      text: "Hello, Ratatui! Press 'q' to quit.",
+      alignment: :center,
+      block: tui.block(
+        title: "My Ruby TUI App",
+        title_alignment: :center,
+        borders: [:all],
+        border_color: "cyan",
+        style: { fg: "white" }
+      )
     )
-  )
-
-  # 3. Use RatatuiRuby methods, too.
-  tui.draw(view)
-  event = tui.poll_event
-  
-  if event && event[:type] == :key && event[:code] == "q"
-    break
+
+    # 3. Use RatatuiRuby methods, too.
+    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.main_loop`**: This helper method manages the entire terminal lifecycle for you. It 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 special DSL 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 DSL object also provides aliases for module functions of `RatatuiRuby`, allowing you to write `tui.draw(...)` instead of the more verbose `RatatuiRuby::draw(...)`.
+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(...)`.
+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).
+
+### Adding Layouts
+
+Real-world applications often need to split the screen into multiple areas. `RatatuiRuby::Layout` lets you do this easily.
+
+```ruby
+require "ratatui_ruby"
+
+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),
+        ]
+      )
+
+      # 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
+      )
+
+      # 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
+      )
+
+      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
+```
+
+#### How it works
+
+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.
 
 ## Examples
 
-To see more complex layouts and widget usage, check out the `examples/` directory in the repository.
+These examples showcase the full power of **ratatui_ruby**. You can find their source code in the [examples directory](../examples).
 
-### [Analytics](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/analytics.rb)
-Demonstrates the use of `Tabs` and `BarChart` widgets with a simple data-switching mechanism.
+### Sample Applications
 
-![Analytics Screenshot](./images/examples-analytics.rb.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.rb)
-A simple demonstration of `Block` and `Paragraph` widgets, reacting to arrow key presses to change colors.
 
-![Box Demo Screenshot](./images/examples-box_demo.rb.png)
 
-### [Calendar Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/calendar_demo.rb)
-A simple demo application for the `Calendar` widget.
+#### [All Events](../examples/app_all_events/app.rb)
 
-![Calendar Screenshot](./images/examples-calendar_demo.rb.png)
+Handling terminal events is unpredictable. Developers need to know exactly what the terminal sends for `Ctrl+C` or a mouse drag.
 
-### [Chart Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/chart_demo.rb)
-Demonstrates the `Chart` widget with both scatter and line datasets, including custom axes.
+This app captures and visualizes every event—keys, mouse, resize, paste, and focus.
 
-![Chart Screenshot](./images/examples-chart_demo.rb.png)
+Use it to debug your input handling or verify terminal behavior.
 
-### [Custom Widget (Escape Hatch)](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/custom_widget.rb)
-Demonstrates how to define a custom widget in pure Ruby using the `render(area, buffer)` escape hatch for low-level drawing.
+**What you'll learn:**
 
-![Custom Widget Screenshot](./images/examples-custom_widget.rb.png)
+*   **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.
 
-### [Dashboard](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/dashboard.rb)
-Uses `Layout`, `List`, and `Paragraph` to create a classic sidebar-and-content interface.
+![all_events](./images/app_all_events.png)
 
-![Dashboard Screenshot](./images/examples-dashboard.rb.png)
+#### [Color Picker](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/app_color_picker/app.rb)
 
-### [List Styles](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/list_styles.rb)
-Showcases advanced styling options for the `List` widget, including selection highlighting.
+Interactive tools require complex state. Mapping mouse clicks to widgets and handling modal dialogs creates messy code if handled in the main loop.
 
-### [Login Form](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/login_form.rb)
-Shows how to use `Overlay`, `Center`, and `Cursor` to build a modal login form with text input.
+This app implements a full Color Picker using a "Scene-Orchestrated" pattern. The Scene calculates layout and exposes cached rectangles for hit testing.
 
-![Login Form Screenshot](./images/examples-login_form.rb.png)
+Use it to build forms, editors, and mouse-driven tools.
 
-### [Map Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/map_demo.rb)
-Exhibits the `Canvas` widget's power, rendering a world map along with animated circles and lines.
+**What you'll learn:**
 
-![Map Demo Screenshot](./images/examples-map_demo.rb.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.
 
-### [Mouse Events](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/mouse_events.rb)
-Detailed plumbing of mouse events, including clicks, drags, and movement tracking.
+#### [Custom Widget (Escape Hatch)](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/app_custom_widget/app.rb)
 
-![Mouse Events Screenshot](./images/examples-mouse_events.rb.png)
+Demonstrates how to define a custom widget in pure Ruby using the `render(area, buffer)` escape hatch for low-level drawing.
+
+![custom_widget](./images/app_custom_widget.png)
+
+#### [Layout Split Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/widget_layout_split/app.rb)
 
-### [Popup Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/popup_demo.rb)
-Demonstrates the `Clear` widget and how to prevent "style bleed" when rendering opaque popups over colored backgrounds.
+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).
 
-![Popup Demo Screenshot](./images/examples-popup_demo.rb.gif)
+![widget_layout_split](./images/widget_layout_split.png)
+
+#### [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.
 
-### [Scrollbar Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/scrollbar_demo.rb)
-A simple example of integrating the `Scrollbar` widget and handling mouse wheel events for scrolling.
+![login_form](./images/app_login_form.png)
 
-![Scrollbar Demo Screenshot](./images/examples-scrollbar_demo.rb.png)
+#### [Map Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/app_map_demo/app.rb)
 
-### [Scroll Text](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/scroll_text.rb)
-Demonstrates the `Paragraph` widget's scroll functionality, allowing navigation through long text content using arrow keys for both horizontal and vertical scrolling.
+Exhibits the `Canvas` widget's power, rendering a world map with city labels, animated circles, and lines.
 
-![Scroll Text Screenshot](./images/examples-scroll_text.rb.png)
+![map_demo](./images/app_map_demo.png)
 
-### [Stock Ticker](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/stock_ticker.rb)
-Utilizes `Sparkline` and `Chart` widgets to visualize real-time (simulated) data.
+#### [Table Select](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/app_table_select/app.rb)
 
-![Stock Ticker Screenshot](./images/examples-stock_ticker.rb.png)
+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.
 
-### [System Monitor](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/system_monitor.rb)
-Combines `Table` and `Gauge` widgets in a vertical layout to create a functional system overview.
+![table_select](./images/app_table_select.png)
 
-![System Monitor Screenshot](./images/examples-system_monitor.rb.png)
 
-### [Table Select](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/table_select.rb)
-Demonstrates interactive row selection in the `Table` widget with keyboard navigation, highlighting selected rows with custom styles and symbols.
+### Widget Demos
 
-![Table Select Screenshot](./images/examples-table_select.rb.png)
+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