ratatui_ruby 0.5.0 → 0.6.0

data/doc/quickstart.md

@@ -35,12 +35,11 @@ gem install ratatui_ruby
 
 Here is a "Hello World" application that demonstrates the core lifecycle of a **ratatui_ruby** app.
 
+<!-- SYNC:START:../examples/verify_quickstart_lifecycle/app.rb:main -->
 ```ruby
-require "ratatui_ruby"
- 
 # 1. Initialize the terminal
 RatatuiRuby.init_terminal
- 
+
 begin
   # The Main Loop
   loop do
@@ -57,21 +56,26 @@ begin
         style: { fg: "white" }
       )
     )
- 
+
     # 3. Draw the UI
     RatatuiRuby.draw do |frame|
       frame.render_widget(view, frame.area)
     end
- 
+
     # 4. Poll for events
-    event = RatatuiRuby.poll_event
-    break if event.key? && event.code == "q"
+    case RatatuiRuby.poll_event
+    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+      break
+    else
+      nil
+    end
   end
 ensure
   # 5. Restore the terminal to its original state
   RatatuiRuby.restore_terminal
 end
 ```
+<!-- SYNC:END -->
 
 ![quickstart_lifecycle](./images/verify_quickstart_lifecycle.png)
 
@@ -87,10 +91,8 @@ end
 
 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 and ensure it is restored.
+<!-- SYNC:START:../examples/verify_quickstart_dsl/app.rb:main -->
+```ruby
 RatatuiRuby.run do |tui|
   loop do
     # 2. Create your UI with methods instead of classes.
@@ -121,6 +123,7 @@ RatatuiRuby.run do |tui|
   end
 end
 ```
+<!-- SYNC:END -->
 
 #### How it works
 
@@ -135,64 +138,62 @@ For a deeper dive into the available application architectures (Manual vs Manage
 
 Real-world applications often need to split the screen into multiple areas. `RatatuiRuby::Layout` lets you do this easily.
 
+<!-- SYNC:START:../examples/verify_quickstart_layout/app.rb:main -->
 ```ruby
-require "ratatui_ruby"
+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),
+      ]
+    )
 
-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
+    )
 
-      # 2. Render Top Widget
-      frame.render_widget(
-        tui.paragraph(
-          text: "Hello, Ratatui!",
-          alignment: :center,
-          block: tui.block(title: "Content", borders: [:all], border_color: "cyan")
+    # 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])
         ),
-        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
-      )
+        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
+    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
+  case tui.poll_event
+  in { type: :key, code: "q" }
+    break
+  else
+    # Ignore other events
   end
 end
 ```
+<!-- SYNC:END -->
 
 #### How it works
 
@@ -221,7 +222,7 @@ Use it to debug your input handling or verify terminal behavior.
 
 **What you'll learn:**
 
-*   **MVVM Architecture**: Separates logic (Model), state (ViewModel), and rendering (View) for clean, testable code.
+*   **Proto-TEA Architecture**: Implements unidirectional data flow (Model-View-Update) with immutable state and pure functions.
 *   **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.
 
@@ -231,15 +232,15 @@ Use it to debug your input handling or verify terminal behavior.
 
 Interactive tools require complex state. Mapping mouse clicks to widgets and handling modal dialogs creates messy code if handled in the main loop.
 
-This app implements a full Color Picker using a "Scene-Orchestrated" pattern. The Scene calculates layout and exposes cached rectangles for hit testing.
+This app implements a full Color Picker using a "Proto-Kit (Component-Based)" pattern. Each component encapsulates its own rendering, state, and event handling.
 
 Use it to build forms, editors, and mouse-driven tools.
 
 **What you'll learn:**
 
-*   **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.
+*   **Proto-Kit Architecture**: Self-contained components with `render(tui, frame, area)` and `handle_event(event)`.
+*   **Encapsulated Hit Testing**: Components cache their render area and check `contains?` internally.
+*   **Modal Dialogs**: Implements overlay patterns that intercept input via Chain of Responsibility.
 
 #### [Custom Widget (Escape Hatch)](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/app_custom_widget/app.rb)
 
@@ -259,17 +260,9 @@ Shows how to use `Overlay`, `Center`, and `Cursor` to build a modal login form w
 
 ![login_form](./images/app_login_form.png)
 
-#### [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/app_map_demo.png)
 
-#### [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/app_table_select.png)
 
 
 ### Widget Demos
@@ -277,14 +270,14 @@ Demonstrates interactive row selection in the `Table` widget with keyboard navig
 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)
+*   [Block (Interactive Demo)](../examples/widget_block_demo/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)
+*   [Map (Canvas)](../examples/widget_map_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)
@@ -293,6 +286,6 @@ These smaller, focused examples demonstrate specific widgets and their configura
 *   [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)
+*   [Table (Selection)](../examples/widget_table_demo/app.rb)
 *   [Tabs](../examples/widget_tabs_demo/app.rb)
 *   [Widget Style Colors](../examples/widget_style_colors/app.rb)

data/doc/terminal_limitations.md

@@ -0,0 +1,92 @@
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Terminal Limitations
+
+Some behaviors are outside the control of `ratatui_ruby`. This document explains common pitfalls that affect your application or your users, but cannot be fixed in the library.
+
+## Keyboard Event Interception
+
+### The Problem
+
+Your application receives a key event, but the modifier flags are missing. You pressed Ctrl+PageUp, but the event shows `code="page_up"` with `modifiers=[]`.
+
+### The Cause
+
+Terminal emulators intercept certain key combinations for their own features. The key press never reaches your application—the terminal consumes it first.
+
+Common culprits on macOS:
+
+| Key Combination      | Terminal Behavior                    |
+|---------------------|--------------------------------------|
+| Ctrl+PageUp/Down    | Switch tabs (Terminal.app, iTerm2)   |
+| Ctrl+Tab            | Switch tabs                          |
+| Cmd+T / Cmd+N       | New tab / New window                 |
+| Cmd+C / Cmd+V       | Copy / Paste (not Ctrl)              |
+
+Linux terminals vary widely. Windows Terminal and ConEmu have their own defaults.
+
+### The Solution
+
+1. **Test with different terminals.** Kitty, WezTerm, and Alacritty pass more key combinations through to applications by default. If a key works in Kitty but not Terminal.app, the terminal is the issue.
+
+2. **Reconfigure your terminal.** Most terminal emulators let you unbind or remap default shortcuts in their settings.
+
+3. **Use alternative key bindings.** If your users will run your application in various terminals, design your keybindings to avoid commonly intercepted combinations:
+   - Use Alt+PageUp instead of Ctrl+PageUp
+   - Use Ctrl+J/K instead of Ctrl+Up/Down
+   - Avoid Ctrl+Tab entirely
+
+4. **Document requirements.** If your application depends on specific key combinations, document the terminal requirements for your users.
+
+### Enhanced Keyboard Protocol
+
+Some terminals support the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/), which provides unambiguous key event reporting including:
+
+- Individual modifier key events (LeftShift vs RightShift)
+- Media keys (Play, Pause, Volume controls)
+- Repeat and release events
+
+Terminals with full protocol support:
+- Kitty
+- WezTerm
+- Foot
+- Alacritty (partial)
+
+Standard terminals (Terminal.app, iTerm2, GNOME Terminal) do not support the enhanced protocol.
+
+**RatatuiRuby Status:** The underlying library (crossterm) supports this protocol, but RatatuiRuby does not yet expose a way to enable it. The key code mappings for media keys and individual modifier keys exist, but they will only be received from terminals that enable the protocol by default. This is planned for a future release.
+
+## Mouse Event Limitations
+
+### The Problem
+
+Mouse events work in some terminals but not others. Or they work, but only up to certain coordinates.
+
+### The Cause
+
+Mouse reporting requires terminal escape sequence support. Older terminals may not support:
+
+- SGR mouse mode (coordinates > 223)
+- Mouse motion tracking
+- Button-event tracking
+
+### The Solution
+
+Ensure your terminal supports modern mouse modes. Most actively maintained terminals do. If running in a legacy environment, test mouse functionality and provide keyboard alternatives.
+
+## Focus Events
+
+### The Problem
+
+`Event::FocusGained` and `Event::FocusLost` are never received.
+
+### The Cause
+
+Focus event reporting requires explicit terminal support and configuration. Some terminals don't support it at all.
+
+### The Solution
+
+Don't rely on focus events for critical functionality. Treat them as nice-to-have enhancements. If your application shows stale data when the user returns, periodically refresh instead of waiting for focus events.

data/examples/app_all_events/README.md

@@ -5,37 +5,54 @@ 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.
+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 the Proto-TEA architectural pattern.
 
-## Architecture: MVVM (Model-View-ViewModel)
+## Architecture: Proto-TEA (Model-View-Update)
 
-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.
+This application demonstrates **unidirectional data flow** inspired by The Elm Architecture. This separation ensures that state management is predictable and easy to test.
 
-### 1. Model (`model/`)
-The **Model** manages the application's domain data and logic. It knows nothing about the UI.
+### 1. Model (`model/app_model.rb`)
+A single immutable `Data.define` object holding **all** application state:
+*   Event log entries
+*   Focus state
+*   Window size
+*   Highlight timestamps
+*   Color cycle index
 
-*   **`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.
+State changes use `.with(...)` to return a new Model instance.
 
-### 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.
+### 2. Msg (`model/msg.rb`)
+Semantic value objects that decouple raw terminal events from business logic:
+*   `Msg::Input` — keyboard, mouse, or paste events
+*   `Msg::Resize` — terminal size changes
+*   `Msg::Focus` — focus gained/lost
+*   `Msg::Quit` — exit signal
 
-*   **`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. Update (`update.rb`)
+A **pure function** that computes the next state:
 
-### 3. View (`view/`)
-The **View** is responsible **only** for rendering. It receives the `ViewState` and draws to the screen.
+```ruby
+Update.call(msg, model) -> Model
+```
 
-*   **`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`.
+All logic previously in `Events.record` now lives here. The function never mutates, never draws, never performs IO.
 
-### 4. Controller/App (`app.rb`)
-The **`AppAllEvents`** class ties it all together. It owns the main loop:
+### 4. View (`view/`)
+Pure rendering logic. Views accept the immutable `AppModel` and draw to the screen.
+*   **`View::App`**: Root view handling high-level layout
+*   **Sub-views**: `Counts`, `Live`, `Log`, `Controls`
 
-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.
+### 5. Runtime (`app.rb`)
+The MVU loop:
+
+```ruby
+loop do
+  tui.draw { |f| view.call(model, tui, f, f.area) }
+  msg = map_event_to_msg(tui.poll_event, model)
+  break if msg.is_a?(Msg::Quit)
+  model = Update.call(msg, model)
+end
+```
 
 ## Library Features Showcased
 
@@ -57,10 +74,10 @@ Reading this code will teach you how to:
 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?"
+Hello World examples are great, but they don't scale. This example shows how to structure an application that can grow. By using immutable state and pure functions, it solves the problem of "where does my state live and how does it change?"
 
-### "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.
+### "How do I test my business logic?"
+The `Update` function is pure. You can test it by constructing a `Msg`, calling `Update.call(msg, model)`, and asserting on the returned `Model`. No mocking required.
 
 ## Comparison: Choosing an Architecture
 
@@ -68,14 +85,15 @@ Complex applications require structured state habits. `AppAllEvents` and the [Co
 
 ### 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.
+Dashboards display data. They rarely require complex mouse interaction. Proto-TEA works best here. State is immutable. Logic is pure. Updates are predictable. 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.
+Tools require interaction. Users click buttons and drag sliders. Each UI component needs to know where it exists on screen for hit testing.
 
-The Color Picker uses a "Scene" pattern. The View exposes layout rectangles. The Controller uses these rectangles to handle mouse clicks.
+The Color Picker uses a "Proto-Kit (Component-Based)" pattern. Each component encapsulates its own rendering, state, and event handling. The Container routes events and coordinates cross-component effects.
 
 Use this pattern for forms, editors, and mouse-driven tools.
+

data/examples/app_all_events/app.rb

@@ -7,8 +7,9 @@ $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 "model/app_model"
+require_relative "model/msg"
+require_relative "update"
 require_relative "view/app_view"
 
 # Demonstrates the full range of terminal events supported by RatatuiRuby.
@@ -20,6 +21,14 @@ require_relative "view/app_view"
 #
 # Use it to verify your terminal's capabilities or as a reference for complex event handling.
 #
+# === Architecture
+#
+# This example uses the Proto-TEA (Model-View-Update) pattern:
+# - **Model**: Immutable AppModel holds all state
+# - **Msg**: Semantic message types decouple events from logic
+# - **Update**: Pure function computes next state
+# - **View**: Renders Model to screen
+#
 # === Examples
 #
 #   # Run from the command line:
@@ -31,62 +40,56 @@ 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.
+  # Creates a new AppAllEvents instance and initializes its view.
   def initialize
     @view = View::App.new
-    @events = Events.new
-    @focused = true
-    @last_dimensions = [80, 24]
   end
 
   # Starts the application event loop.
   #
+  # Implements the MVU (Model-View-Update) runtime:
+  # 1. **View**: Render current model
+  # 2. **Poll**: Get next event
+  # 3. **Map**: Convert raw event to semantic Msg
+  # 4. **Update**: Compute next model
+  #
   # === Example
   #
   #   app.run
   def run
     RatatuiRuby.run do |tui|
-      @tui = tui
+      model = AppModel.initial
+
       loop do
-        render
-        break if handle_input == :quit
-      end
-    end
-  end
+        tui.draw { |frame| @view.call(model, tui, frame, frame.area) }
 
-  private def render
-    view_state = ViewState.build(
-      @events,
-      @focused,
-      @tui,
-      nil
-    )
+        event = tui.poll_event
+        msg = map_event_to_msg(event, model)
+        break if msg.is_a?(Msg::Quit)
 
-    @tui.draw { |frame| @view.call(view_state, @tui, frame, frame.area) }
+        model = Update.call(msg, model)
+      end
+    end
   end
 
-  private def handle_input
-    event = @tui.poll_event
-
+  private def map_event_to_msg(event, model)
     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)
+      return Msg::Quit.new if event.code == "q"
+      return Msg::Quit.new if event.code == "c" && event.modifiers.include?("ctrl")
+
+      Msg::Input.new(event:)
     when RatatuiRuby::Event::Resize
-      @events.record(event, context: { last_dimensions: @last_dimensions })
-      @last_dimensions = [event.width, event.height]
+      Msg::Resize.new(width: event.width, height: event.height, previous_size: model.window_size)
     when RatatuiRuby::Event::FocusGained
-      @focused = true
-      @events.record(event)
+      Msg::Focus.new(gained: true)
     when RatatuiRuby::Event::FocusLost
-      @focused = false
-      @events.record(event)
+      Msg::Focus.new(gained: false)
+    when RatatuiRuby::Event::None
+      Msg::NoneEvent.new
     else
-      @events.record(event)
+      Msg::Input.new(event:)
     end
-
-    nil
   end
 end