ratatui_ruby 0.4.0 → 0.6.0

data/doc/application_architecture.md

@@ -1,58 +1,116 @@
-# Core Concepts
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 
-This guide explains the core concepts and patterns available in `ratatui_ruby` for structuring your terminal applications.
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
 
-## 1. Lifecycle Management
+# Application Architecture
 
-Managing the terminal state is critical. You must enter "alternate screen" and "raw mode" on startup, and **always** restore the terminal on exit (even on errors), otherwise the user's terminal will be left in a broken state.
+Architect robust TUI applications using core lifecycle patterns and API best practices.
 
-### `RatatuiRuby.run` (Recommended)
+## Core Concepts
 
-The `run` method acts as a **Context Manager**. It handles the initialization and restoration for you, ensuring the terminal is always restored even if your code raises an exception. We recommend using `run` for all applications, as it provides a safe sandbox for your TUI.
+Your app lives inside a terminal. You need to respect its rules.
+
+### Lifecycle Management
+
+Terminals have state. They remember cursor positions, input modes, and screen buffers.
+
+**The Problem:** If your app crashes or exits without cleaning up, it "breaks" the user's terminal. The cursor vanishes. Input echoes constantly. The alternate screen doesn't clear.
+
+**The Solution:** The library's lifecycle manager handles this for you. It enters "raw mode" on startup and guarantees restoration on exit.
+
+#### Use `RatatuiRuby.run`
+
+This method acts as a safety net. It initializes the terminal, yields control to your block, and restores the terminal afterwards—even if your code raises an exception.
 
 ```ruby
 RatatuiRuby.run do |tui|
   loop do
-     # Your code here
-    tui.draw(...)
+    tui.draw do |frame|
+      frame.render_widget(tui.paragraph(text: "Hello"), frame.area)
+    end
+    break if tui.poll_event == "q"
   end
 end
 # Terminal is restored here
 ```
 
-### Manual Management (Advanced)
+#### Manual Management
 
-You can manage this manually if you need granular control, but use `ensure` blocks!
+Need granular control? You can initialize and restore the terminal yourself. Use `ensure` blocks to guarantee cleanup.
 
 ```ruby
 RatatuiRuby.init_terminal
 begin
-  # Your code here
-  RatatuiRuby.draw(...)
+  RatatuiRuby.draw do |frame|
+    frame.render_widget(RatatuiRuby::Paragraph.new(text: "Hello"), frame.area)
+  end
 ensure
   RatatuiRuby.restore_terminal
+  # Terminal is restored here
+end
+```
+
+### Stateful Widgets
+
+Most widgets are stateless configuration. You create them, render them, and they are gone. However, the **runtime status** of some widgets (like Lists and Tables) must persist across frames (e.g., scroll offsets or selection).
+
+**The Problem:** If you re-create a List configuration every frame, you lose the context of where it was scrolled or what was selected. If Ratatui auto-scrolls to a selection, you can't read that new offset back from an immutable input widget.
+
+**The Solution:** Use "Stateful Rendering". You create a mutable State object (Output/Status) once and pass it to `render_stateful_widget`. **The Widget configuration (Input) is still mandatory**, but the State object (passed separately) captures the runtime changes.
+
+> [!IMPORTANT]
+> **Precedence Rule:** When using `render_stateful_widget`, the **State object is the single source of truth** for selection and offset. Widget properties (`selected_index`, `selected_row`, `offset`) are **ignored**.
+>
+> For example: `list(selected_index: 0)` with `state.select(5)` → Item 5 is highlighted, not Item 0.
+
+**Use Case:** When you need to read back the scroll offset (e.g., for mouse hit testing) or persist selection without managing indexes manually.
+
+```ruby
+# Initialize state once
+@list_state = RatatuiRuby::ListState.new
+
+RatatuiRuby.run do |tui|
+  loop do
+    tui.draw do |frame|
+      # Create immutable widget (selected_index is ignored in stateful mode)
+      list = tui.list(items: ["A", "B", "C"])
+      
+      # Render with state — state takes precedence
+      frame.render_stateful_widget(list, frame.area, @list_state)
+    end
+    
+    # Read back offset calculated by Ratatui
+    puts "Current Scroll Offset: #{@list_state.offset}"
+  end
 end
 ```
 
-## 2. API Convenience
+### API Convenience
 
-### Session API (Recommended)
+Writing UI trees involves nesting many widgets.
 
-The block yielded by `run` is a `RatatuiRuby::Session` instance (`tui`).
-It provides factory methods for every widget class (converting snake_case to CamelCase) and aliases for module functions.
+**The Problem:** Explicitly namespacing `RatatuiRuby::` for every widget (e.g., `RatatuiRuby::Paragraph.new`) is tedious. It creates visual noise that hides your layout structure.
 
-**Why use it?** It significantly reduces verbosity and repeated `RatatuiRuby::` namespacing, making the UI tree structure easier to read.
+**The Solution:** The Session API (`tui`) provides shorthand factories for every widget. It yields a session object to your block.
 
 ```ruby
 RatatuiRuby.run do |tui|
   loop do
-    layout = tui.layout(
-      direction: :horizontal,
-      constraints: [
-        RatatuiRuby::Constraint.length(20),
-        RatatuiRuby::Constraint.min(0)
-      ],
-      children: [
+    tui.draw do |frame|
+      # Split layout using Session helpes
+      sidebar_area, content_area = tui.layout_split(
+        frame.area,
+        direction: :horizontal,
+        constraints: [
+          tui.constraint_length(20),
+          tui.constraint_min(0)
+        ]
+      )
+
+      # Render sidebar
+      frame.render_widget(
         tui.paragraph(
           text: tui.text_line(spans: [
             tui.text_span(content: "Side", style: tui.style(fg: :blue)),
@@ -60,15 +118,19 @@ RatatuiRuby.run do |tui|
           ]),
           block: tui.block(borders: [:all], title: "Nav")
         ),
+        sidebar_area
+      )
+
+      # Render main content
+      frame.render_widget(
         tui.paragraph(
           text: "Main Content",
           style: tui.style(fg: :green),
           block: tui.block(borders: [:all], title: "Content")
-        )
-      ]
-    )
-    
-    tui.draw(layout)
+        ),
+        content_area
+      )
+    end
     
     event = tui.poll_event
     break if event == "q" || event == :ctrl_c
@@ -76,22 +138,25 @@ RatatuiRuby.run do |tui|
 end
 ```
 
-### Raw API
+#### Raw API
 
-You can always use the raw module methods and classes directly. This is useful if you are building your own abstractions or prefer explicit class instantiation.
-
-**Comparison:** Notice how much more verbose the same UI definition is.
+Building your own abstractions? You might prefer explicit class instantiation. The raw constants are always available.
 
 ```ruby
 RatatuiRuby.run do
   loop do
-    layout = RatatuiRuby::Layout.new(
-      direction: :horizontal,
-      constraints: [
-        RatatuiRuby::Constraint.length(20),
-        RatatuiRuby::Constraint.min(0)
-      ],
-      children: [
+    RatatuiRuby.draw do |frame|
+      # Manual split
+      rects = RatatuiRuby::Layout.split(
+        frame.area,
+        direction: :horizontal,
+        constraints: [
+          RatatuiRuby::Constraint.length(20),
+          RatatuiRuby::Constraint.min(0)
+        ]
+      )
+
+      frame.render_widget(
         RatatuiRuby::Paragraph.new(
           text: RatatuiRuby::Text::Line.new(spans: [
             RatatuiRuby::Text::Span.new(content: "Side", style: RatatuiRuby::Style.new(fg: :blue)),
@@ -99,18 +164,87 @@ RatatuiRuby.run do
           ]),
           block: RatatuiRuby::Block.new(borders: [:all], title: "Nav")
         ),
+        rects[0]
+      )
+
+      frame.render_widget(
         RatatuiRuby::Paragraph.new(
           text: "Main Content",
           style: RatatuiRuby::Style.new(fg: :green),
           block: RatatuiRuby::Block.new(borders: [:all], title: "Content")
-        )
-      ]
-    )
-    
-    RatatuiRuby.draw(layout)
+        ),
+        rects[1]
+      )
+    end
 
     event = RatatuiRuby.poll_event
     break if event == "q" || event == :ctrl_c
   end
 end
 ```
+
+## Thread and Ractor Safety
+
+Building for Ruby 4.0's parallel future? Know which objects can travel between Ractors.
+
+### Data Objects (Shareable)
+
+These are deeply frozen and `Ractor.shareable?`. Include them in TEA Models/Messages freely:
+
+| Object | Source |
+|--------|--------|
+| `Event::*` | `poll_event` |
+| `Cell` | `get_cell_at` |
+| `Rect` | `Layout.split`, `Frame#area` |
+
+### I/O Handles (Not Shareable)
+
+These have side effects and are intentionally not shareable:
+
+| Object | Valid Usage |
+|--------|-------------|
+| `Session` | Cache in `@tui` during run loop. Don't include in Models. |
+| `Frame` | Pass to helpers during draw block. Invalid after block returns. |
+
+```ruby
+# Good: Cache session in instance variable
+RatatuiRuby.run do |tui|
+  @tui = tui
+  loop { render; handle_input }
+end
+
+# Bad: Include in immutable Model (won't work with Ractors)
+Model = Data.define(:tui, :count)  # Don't do this
+```
+
+
+## Reference Architectures
+
+Simple scripts work well with valid linear code. Complex apps need structure.
+
+We provide these reference architectures to inspire you:
+
+### Proto-TEA (Model-View-Update)
+
+**Source:** [examples/app_all_events](../examples/app_all_events/README.md)
+
+This pattern implements unidirectional data flow inspired by The Elm Architecture:
+*   **Model:** A single immutable `Data.define` object holding all application state.
+*   **Msg:** Semantic value objects that decouple raw events from business logic.
+*   **Update:** A pure function that computes the next state: `Update.call(msg, model) -> Model`.
+*   **View:** Pure rendering logic that accepts the immutable Model.
+
+Use this when you want predictable state management and easy-to-test logic.
+
+### Proto-Kit (Component-Based)
+
+**Source:** [examples/app_color_picker](../examples/app_color_picker/README.md)
+
+This pattern addresses the difficulty of mouse interaction and complex UI orchestration:
+*   **Component Contract:** Every UI element implements `render(tui, frame, area)` and `handle_event(event)`.
+*   **Encapsulated Hit Testing:** Components cache their render area and check `contains?` internally.
+*   **Symbolic Signals:** `handle_event` returns semantic symbols (`:consumed`, `:submitted`) instead of just booleans.
+*   **Container (Mediator):** A parent container routes events via Chain of Responsibility and coordinates cross-component effects.
+
+Use this when you need rich interactivity (mouse clicks, drag-and-drop) or complex dynamic layouts.
+

data/doc/application_testing.md

@@ -8,15 +8,11 @@ This guide explains how to test your RatatuiRuby applications using the provided
 
 ## Overview
 
-RatatuiRuby includes a `TestHelper` module designed to simplify unit testing of TUI applications. It allows you to:
+You need to verify that your application looks and behaves correctly. Manually checking every character on a terminal screen is tedious. Dealing with race conditions and complex state management in tests creates friction.
 
-- Initialize a virtual "test terminal" with specific dimensions.
+The `TestHelper` module solves this. It provides a headless "test terminal" to capture output and a suite of robust assertions to verify state.
 
-- Capture the rendered output (the "buffer") to assert against expected text.
-
-- Inspect the cursor position.
-
-- Simulate user input (using `inject_event`).
+Use it to write fast, deterministic tests for your TUI applications.
 
 ## Setup
 
@@ -36,66 +32,118 @@ class MyApplicationTest < Minitest::Test
 end
 ```
 
-## Basic Usage
+## Writing a View Test
 
-### `with_test_terminal`
+To test a view or widget, wrap your assertions in `with_test_terminal`. This sets up a temporary, in-memory backend for Ratatui to draw to.
 
-Wrap your test assertions in `with_test_terminal`. This sets up a temporary, in-memory backend for Ratatui to draw to, instead of the real terminal. It automatically cleans up afterwards.
+1.  **Initialize the terminal:** Call `with_test_terminal`.
+2.  **Render your code:** Instantiate your widget and draw it to a frame.
+3.  **Assert output:** Check the `buffer_content` against your expectations.
 
 ```ruby
 def test_rendering
   # Uses default 80x24 terminal
   with_test_terminal do
-    # 1. Instantiate your app/component
+    # 1. Instantiate your widget
     widget = RatatuiRuby::Paragraph.new(text: "Hello World")
     
-    # 2. Render it
-    RatatuiRuby.draw(widget)
+    # 2. Render it using the Frame API
+    RatatuiRuby.draw do |frame|
+      frame.render_widget(widget, frame.area)
+    end
     
     # 3. Assert on the output
-    assert_includes buffer_content[0], "Hello World"
+    assert_includes buffer_content.first, "Hello World"
   end
 end
 ```
 
-### `buffer_content`
+For the full API list, including `buffer_content` and `cursor_position`, see [RatatuiRuby::TestHelper::Terminal](../lib/ratatui_ruby/test_helper/terminal.rb).
 
-Returns the current state of the terminal as an Array of Strings. Useful for verifying that specific text appears where you expect it.
-
-```ruby
-rows = buffer_content
-assert_equal "Title", rows[0].strip
-assert_match /Results: \d+/, rows[2]
-```
+## Verifying Styles
 
-### `cursor_position`
+You often need to check colors and modifiers (bold, italic) to ensure your highlighting logic works.
 
-Returns the current cursor coordinates as `{ x: Integer, y: Integer }`. Useful for forms or ensuring focus is correct.
+Use `assert_fg_color`, `assert_bg_color`, and modifier helpers like `assert_bold`.
 
 ```ruby
-pos = cursor_position
-assert_equal 5, pos[:x]
-assert_equal 2, pos[:y]
+# Assert specific cell style
+assert_fg_color(:red, 0, 0)
+assert_bold(0, 0)
+
+# Or check a whole area
+assert_area_style({ x: 0, y: 0, w: 10, h: 1 }, bg: :blue)
 ```
 
-### `inject_event`
+See [RatatuiRuby::TestHelper::StyleAssertions](../lib/ratatui_ruby/test_helper/style_assertions.rb) for the comprehensive list of style helpers.
+
+## Simulating Input
+
+You need to test user interactions like typing or clicking. Stubbing `poll_event` directly is brittle.
 
-Injects a mock event into the event queue. This is the preferred way to simulate user input instead of stubbing `poll_event`.
+Use `inject_event` to push mock events into the queue. This ensures safe, deterministic handling of input.
 
 > [!IMPORTANT]
-> You must call `inject_event` inside a `with_test_terminal` block. Calling it outside leads to race conditions where events are flushed before the application starts.
+> Call `inject_event` inside a `with_test_terminal` block to avoid race conditions.
 
 ```ruby
 with_test_terminal do
   # Simulate 'q' key press
   inject_event("key", { code: "q" })
 
-  # Now poll_event will return the 'q' key event
+  # The application receives the 'q' event
   event = RatatuiRuby.poll_event
   assert_equal "q", event.code
 end
 ```
 
+See [RatatuiRuby::TestHelper::EventInjection](../lib/ratatui_ruby/test_helper/event_injection.rb) for helper methods like `inject_keys` and `inject_click`.
+
+## Snapshot Testing
+
+Snapshots let you verify complex layouts without manually asserting every line.
+
+Use `assert_snapshot` to compare the current screen against a stored reference file.
+
+```ruby
+with_test_terminal do
+  MyApp.new.run
+  assert_snapshot("dashboard_view")
+end
+```
+
+### Handling Non-Determinism
+
+Snapshots must be deterministic. Random data or current timestamps will cause test failures ("flakes").
+
+To prevent this:
+1.  **Seed Randomness:** Use a fixed seed for any RNG.
+2.  **Stub Time:** Force the application to use a static time.
+
+For detailed strategies and code examples, see [RatatuiRuby::TestHelper::Snapshot](../lib/ratatui_ruby/test_helper/snapshot.rb).
+
+## Isolated View Testing
+
+Sometimes you want to test a single view component without spinning up the full `TestTerminal` engine.
+
+Use `MockFrame` and `StubRect` to test render logic in isolation.
+
+```ruby
+def test_logs_view
+  frame = RatatuiRuby::TestHelper::TestDoubles::MockFrame.new
+  area = RatatuiRuby::TestHelper::TestDoubles::StubRect.new(width: 40, height: 10)
+  
+  # Call your view directly
+  MyView.new.render(frame, area)
+  
+  # Inspect what was rendered
+  rendered = frame.rendered_widgets.first
+  assert_equal "Logs", rendered[:widget].block.title
+end
+```
+
+See [RatatuiRuby::TestHelper::TestDoubles](../lib/ratatui_ruby/test_helper/test_doubles.rb).
+
 ## Example
 
-Be sure to check out the [examples directory](../examples/) in the repository, which contains several fully tested example applications showcasing these patterns.
+Check out the [examples directory](../examples/) for fully tested applications showcasing these patterns.

data/doc/contributors/design/ruby_frontend.md

@@ -9,15 +9,20 @@ This document describes the design philosophy and structure of the Ruby layer in
 
 ## Core Philosophy: Data-Driven UI
 
+
+
 The Ruby frontend is designed as a **thin, declarative layer** over the Rust backend. It uses an **Immediate Mode** paradigm where the user constructs a tree of pure data objects every frame to represent the desired UI state.
 
-### 1. View Tree as Data
+### 1. Separation of Configuration and Status
 
-Unlike traditional OO GUI toolkits (like Qt or Swing) where widgets are retained objects with internal state, `ratatui_ruby` widgets are immutable value objects.
+`ratatui_ruby` strictly separates **what** a widget is (Configuration) from **where** it is (Status).
+
+#### Configuration (Input)
+Widgets (e.g., `RatatuiRuby::List`) are immutable value objects defining the *desired appearance* for the current frame. They are pure inputs to the renderer.
 
 *   Implemented using Ruby 3.2+ `Data` classes.
 *   Located in `lib/ratatui_ruby/schema/`.
-*   These objects act as a Schema or Interface Definition Language (IDL) between Ruby and Rust.
+*   Act as a Schema/IDL between Ruby and Rust.
 
 **Example:**
 ```ruby
@@ -29,6 +34,39 @@ paragraph = RatatuiRuby::Paragraph.new(
 )
 ```
 
+#### Status (Output)
+**Optional.** Only specific widgets (like `List` and `Table`) rely on runtime status. State objects (e.g., `RatatuiRuby::ListState`) track metrics calculated by the backend, such as scroll offsets.
+
+*   passed as a *secondary argument* to `render_stateful_widget`.
+*   **The Widget Configuration is still required.** You cannot render a State without its corresponding Widget.
+*   Updated in-place by the Rust backend to reflect the actual rendered state.
+
+**Example:**
+```ruby
+# 1. Initialize State once (Input/Output)
+list_state = RatatuiRuby::ListState.new
+list_state.select(3)
+
+RatatuiRuby.run do |tui|
+  loop do
+    tui.draw do |frame|
+      # 2. Define Configuration (Input)
+      # (Note: In a real app, you'd probably use `tui.list(...)` helper)
+      list = RatatuiRuby::List.new(items: ["A", "B", "C", "D"])
+      
+      # 3. Render with both (Side Effect: updates list_state)
+      frame.render_stateful_widget(list, frame.area, list_state)
+    end
+    
+    # 4. Read back Status (Output)
+    # If the backend auto-scrolled to keep index 3 visible:
+    puts "Scroll Offset: #{list_state.offset}"
+    
+    break if tui.poll_event == "q"
+  end
+end
+```
+
 ### 2. Immediate Mode Rendering
 
 The application loop typically looks like this:
@@ -43,11 +81,13 @@ loop do
   event = RatatuiRuby.poll_event
   break if event == :esc
 
-  # 3. Construct View Tree
-  ui = RatatuiRuby::Paragraph.new(text: "Time: #{Time.now}")
-
-  # 4. Draw
-  RatatuiRuby.draw(ui)
+  # 3. Construct View Tree & Draw
+  RatatuiRuby.draw do |frame|
+    frame.render_widget(
+      RatatuiRuby::Paragraph.new(text: "Time: #{Time.now}"),
+      frame.area
+    )
+  end
 end
 ```
 

data/doc/contributors/design/rust_backend.md

@@ -16,6 +16,7 @@ The project follows a **Structured Design** approach, separating concerns into m
 1.  **Single Generic Renderer**: The backend implements a single generic renderer that accepts a Ruby `Value` representing the root of the view tree.
 2.  **No Custom Rust Structs for UI**: Do not define custom Rust structs that mirror Ruby UI components. Instead, extract data directly from Ruby objects using `funcall`.
 3.  **Dynamic Dispatch**: Use `value.class().name()` (e.g., `"RatatuiRuby::Paragraph"`) to dynamically dispatch rendering logic to the appropriate widget module.
+    *   *Exception:* `render_stateful_widget` bypasses generic dispatch for specific Widget/State pairs (e.g., List + ListState) to allow mutating the State object.
 4.  **Immediate Mode**: The renderer traverses the Ruby object tree every frame and rebuilds the Ratatui widget tree on the fly.
 
 ### Module Structure