ratatui_ruby 0.4.0 → 0.5.0

data/doc/application_architecture.md

@@ -1,58 +1,81 @@
-# 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
 ```
 
-## 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 +83,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 +103,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 +129,48 @@ 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
 ```
+
+## Reference Architectures
+
+Simple scripts work well with valid linear code. Complex apps need structure.
+
+We provide these reference architectures to inspire you:
+
+### MVVM (Model-View-ViewModel)
+
+**Source:** [examples/app_all_events](../examples/app_all_events/README.md)
+
+This pattern strictly separates concerns:
+*   **Model:** Pure business logic. It handles data and events.
+*   **View State (ViewModel):** An immutable data structure built fresh every frame. It calculates logic-dependent properties (like `border_color`) so the View doesn't have to.
+*   **View:** Pure rendering logic. It takes the View State and draws it.
+
+Use this when your app has complex state rules that clutter your rendering code.
+
+### Scene-Orchestrated MVC
+
+**Source:** [examples/app_color_picker](../examples/app_color_picker/README.md)
+
+This pattern addresses the difficulty of mouse interaction and layout management:
+*   **Scene:** A specialized View that owns the layout *and* hit testing. It caches the screen coordinates of widgets during the draw phase.
+*   **App (Controller):** Handles events by querying the Scene (e.g., `scene.rect_at(x, y)`).
+
+Use this when you need rich interactivity (mouse clicks, drag-and-drop) or complex dynamic layouts.

data/doc/application_testing.md

@@ -46,11 +46,13 @@ Wrap your test assertions in `with_test_terminal`. This sets up a temporary, in-
 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"

data/doc/contributors/design/ruby_frontend.md

@@ -9,6 +9,8 @@ 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
@@ -43,11 +45,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/developing_examples.md

@@ -18,11 +18,12 @@ require "ratatui_ruby"
 
 class MyExampleApp
   def initialize
-    # Initialize state
+    # Initialize state (styles must be initialized in run when @tui is available)
   end
 
   def run
-    RatatuiRuby.run do
+    RatatuiRuby.run do |tui|
+      @tui = tui  # Store for use in private methods
       loop do
         render
         break if handle_input == :quit
@@ -33,13 +34,24 @@ class MyExampleApp
   private
 
   def render
-    # Build and draw UI
-    RatatuiRuby.draw(layout)
+    @tui.draw do |frame|
+      # 1. Split layout using Session helpers
+      areas = @tui.layout_split(frame.area, constraints: [@tui.constraint_fill(1)])
+      # 2. Create and render widgets
+      widget = @tui.paragraph(text: "Hello", block: @tui.block(borders: [:all]))
+      frame.render_widget(widget, areas[0])
+    end
   end
 
   def handle_input
-    event = RatatuiRuby.poll_event
-    # Process event, return :quit to exit
+    case @tui.poll_event
+    in { type: :key, code: "q" }
+      :quit
+    in { type: :key, code: code }
+      # Handle other keys
+    else
+      # Ignore unhandled events
+    end
   end
 end
 
@@ -48,11 +60,12 @@ MyExampleApp.new.run if __FILE__ == $PROGRAM_NAME
 
 ### Naming Convention (Required)
 
-Example classes **must** follow the naming convention:
-- **Directory:** `examples/my_example/` (snake_case)
-- **Class:** `MyExampleApp` (PascalCase with `App` suffix)
+Example directories **must** follow a prefixing convention to categorize them alphabetically:
+- `app_`: Application showcases (e.g., `app_analytics`). Class name: `AppAnalytics`.
+- `widget_`: Widget-focused demonstrations (e.g., `widget_gauge_demo`). Class name: `WidgetGaugeDemo`.
+- `verify_`: Documentation verification examples (e.g., `verify_readme_usage`). Class name: `VerifyReadmeUsage`.
 
-The class name is derived from the directory name: `my_example` → `MyExampleApp`.
+The directory and class names must match (snake_case directory maps to PascalCase class).
 
 This convention enables the `terminal_preview:update` rake task to automatically capture terminal output for all examples without maintaining a manual registry.
 
@@ -90,13 +103,39 @@ end
 
 2. **Use `RatatuiRuby.run` for terminal management.** Never call `init_terminal` or `restore_terminal` directly. The `run` block handles terminal setup/teardown automatically and safely, even if an exception occurs.
 
-3. **Use keyboard keys to cycle through widget attributes.** Users should be able to interactively explore all widget options. Common patterns:
+3. **Use the Session API (`tui`) for cleaner code.** Accept the `tui` block parameter from `RatatuiRuby.run` and use it throughout your app:
+   - `@tui.draw { |frame| ... }` instead of `RatatuiRuby.draw`
+   - `@tui.poll_event` instead of `RatatuiRuby.poll_event`
+   - `@tui.style(...)` instead of `RatatuiRuby::Style.new(...)`
+   - `@tui.paragraph(...)` instead of `RatatuiRuby::Paragraph.new(...)`
+   - `@tui.block(...)` instead of `RatatuiRuby::Block.new(...)`
+   - `@tui.layout_split(...)` instead of `RatatuiRuby::Layout.split(...)`
+   - `@tui.constraint_fill(...)` instead of `RatatuiRuby::Constraint.fill(...)`
+   - `@tui.text_line(...)` instead of `RatatuiRuby::Text::Line.new(...)`
+   - `@tui.text_span(...)` instead of `RatatuiRuby::Text::Span.new(...)`
+
+4. **Event handling must include a catch-all pattern.** When using pattern matching in `handle_input`, always include an `else` clause at the end to catch unmatched events (mouse events, resize events, focus events, etc.). Without it, unmatched events will raise `NoMatchingPatternError`:
+
+   ```ruby
+   def handle_input
+     case @tui.poll_event
+     in { type: :key, code: "q" }
+       :quit
+     in { type: :mouse, kind: "down", x:, y: }
+       handle_click(x, y)
+     else
+       # Ignore other events
+     end
+   end
+   ```
+
+5. **Use keyboard keys to cycle through widget attributes.** Users should be able to interactively explore all widget options. Common patterns:
     - Arrow keys: Navigate or adjust values
     - Letter keys: Cycle through styles, modes, or variants. Prefer all lowercase keys to avoid confusion and simplify the UI description.
     - Space: Toggle or select
     - `q` or Ctrl+C: Quit
 
-### Naming Conventions for Controls
+5. **Naming Conventions for Controls**
 
 When documenting hotkeys and cycling options in the UI, use consistent naming:
 
@@ -105,11 +144,12 @@ When documenting hotkeys and cycling options in the UI, use consistent naming:
   - Use "Highlight Style" (not "Highlight") for the `highlight_style:` parameter
   - Use "Repeat Symbol" (not "Repeat") for the `repeat_highlight_symbol:` parameter
   
-- **Display names for cycled values:** Create a `name` field in your options hash to keep display names paired with values:
+- **Display names for cycled values:** Create a `name` field in your options hash to keep display names paired with values. Initialize style arrays inside `run` when `@tui` is available:
   ```ruby
+  # In run method, after @tui = tui:
   @styles = [
-    { name: "Yellow Bold", style: RatatuiRuby::Style.new(fg: :yellow, modifiers: [:bold]) },
-    { name: "Blue on White", style: RatatuiRuby::Style.new(fg: :blue, bg: :white) }
+    { name: "Yellow Bold", style: @tui.style(fg: :yellow, modifiers: [:bold]) },
+    { name: "Blue on White", style: @tui.style(fg: :blue, bg: :white) }
   ]
   
   # In controls: "h: Highlight Style (#{@styles[@style_index][:name]})"
@@ -118,9 +158,15 @@ When documenting hotkeys and cycling options in the UI, use consistent naming:
 
 This keeps the UI self-documenting and users can see exact parameter names when they read the hotkey help.
 
-### Hit Testing with the Cached Layout Pattern
+7. **Hit Testing**
 
-Examples with mouse interaction should implement the **Cached Layout Pattern** documented in `doc/interactive_design.md`. The `hit_test` example demonstrates this pattern.
+Examples with mouse interaction should use the **Frame API**. By calling `@tui.layout_split` inside `@tui.draw`, you obtain the exact `Rect`s used for rendering. Store these rects in instance variables (e.g., `@sidebar_rect`) to use them in your `handle_input` method for hit testing:
+
+```ruby
+if @sidebar_rect&.contains?(event.x, event.y)
+  # Handle click
+end
+```
 
 ## Testing Examples
 
@@ -163,13 +209,25 @@ class TestMyExampleApp < Minitest::Test
       assert_includes content, "Changed State"
     end
   end
+
+  def test_mouse_interaction
+    with_test_terminal do
+      # Click at (10, 5)
+      inject_click(x: 10, y: 5)
+      inject_key(:q)
+      @app.run
+
+      content = buffer_content.join("\n")
+      assert_includes content, "Clicked at (10, 5)"
+    end
+  end
 end
 ```
 
 ### Testing Guidelines
 
 1. **Inject events, observe buffer.** Tests should only interact through:
-   - `inject_key` / `inject_keys` / `inject_event` for input
+   - `inject_key`, `inject_click`, `inject_event`, etc. for input
    - `buffer_content` for output verification
 
 2. **Never call internal methods.** Don't call `render`, `handle_input`, `__send__`, or access instance variables with `instance_variable_get`. Tests verify behavior through the public `run` method.

data/doc/contributors/documentation_style.md

@@ -1,3 +1,9 @@
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Documentation Style Guide
 
 This project follows a strict and specific documentation style designed to be helpful, readable, and consistent. It combines the structural clarity of Christopher Alexander's Pattern Language with the prose style of William Zinsser's *On Writing Well* and the usability of the U.S. Federal Plain Language Guidelines.
@@ -9,6 +15,7 @@ This project follows a strict and specific documentation style designed to be he
 *   **Context, Problem, Solution (Alexandrian Form):** Do not just say *what* a class does. Explain *why* it exists. Start with the context, state the problem (the pain point without this tool), and then present the class as the solution.
 *   **Prose Style (Zinsser/Klinkenborg):** Use short, punchy sentences. Use active voice. Cut unnecessary words. Avoid "allow," "enable," "provide," "support," "functionality," and "capability" where possible. Weak verbs hide the action. Strong verbs drive the sentence.
 *   **User-Centric (Plain Language):** Speak directly to the user ("You"). Don't abstract them away ("The developer"). Focus on their goals and how this tool helps them achieve those goals.
+*   **Tone (Supportive and Authoritative, not Hostile or Prescriptive):** Avoid "must," "requires," "need to," or "mandatory." These words sound bossy. Treat the user as a capable peer. Instead of "You must do X," use imperative "Do X" or cause-and-effect "X ensures Y."
 
 ## 2. Class Documentation
 

data/doc/contributors/index.md

@@ -11,6 +11,8 @@
 - [Documentation Guide](https://man.sr.ht/~kerrick/ratatui_ruby/documentation_guide.md)
 - [The Design of **ratatui_ruby**](./design.md)
 
+
+
 ## Documentation for Users
 
 - [README](../../README.md)

data/doc/event_handling.md

@@ -1,8 +1,14 @@
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Event Handling in RatatuiRuby
 
 `ratatui_ruby` provides a rich, object-oriented event system that supports multiple coding styles, from simple boolean predicates to modern Ruby pattern matching.
 
-Events are retrieved using `RatatuiRuby.poll_event`. This method returns an instance of a subclass of `RatatuiRuby::Event` (e.g., `RatatuiRuby::Event::Key`, `RatatuiRuby::Event::Mouse`) or `nil` if no event is available.
+Events are retrieved using `RatatuiRuby.poll_event`. This method returns an instance of a subclass of `RatatuiRuby::Event` (e.g., `RatatuiRuby::Event::Key`, `RatatuiRuby::Event::Mouse`). When no event is available, it returns `RatatuiRuby::Event::None`—a [null object](https://martinfowler.com/eaaCatalog/specialCase.html) that safely responds to all event predicates with `false`.
 
 ## 1. Symbol and String Comparison (Simplest)
 
@@ -18,7 +24,6 @@ For a complete list of supported keys, modifiers, and event types, please refer
 
 ```ruby
 event = RatatuiRuby.poll_event
-next unless event
 
 # 1. Check for quit keys
 if event == "q" || event == :ctrl_c
@@ -101,8 +106,8 @@ loop do
   in type: :mouse, kind: "down", x:, y:
     handle_click(x, y)
 
-  else
-    # Ignore
+  in type: :none
+    # No event available, continue loop
   end
 end
 ```
@@ -117,3 +122,4 @@ end
 | `RatatuiRuby::Event::Paste` | `:paste` | `content` | `paste?` |
 | `RatatuiRuby::Event::FocusGained` | `:focus_gained` | (none) | `focus_gained?` |
 | `RatatuiRuby::Event::FocusLost` | `:focus_lost` | (none) | `focus_lost?` |
+| `RatatuiRuby::Event::None` | `:none` | (none) | `none?` |

data/doc/interactive_design.md

@@ -21,10 +21,13 @@ Structure your event loop into three clear phases:
 
 ```ruby
 def run
-  RatatuiRuby.run do
+  RatatuiRuby.run do |tui|
+    @tui = tui
     loop do
-      calculate_layout   # Phase 1: Geometry (once per frame)
-      render             # Phase 2: Draw
+      @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
@@ -33,29 +36,27 @@ end
 
 **Phase 1: Layout Calculation**
 
-Call this before rendering and event handling. It's the single source of truth for geometry:
+Call this inside your `draw` block. It uses the current terminal area provided by the frame:
 
 ```ruby
-def calculate_layout
-  full_area = RatatuiRuby::Rect.new(x: 0, y: 0, width: 80, height: 24)
-
+def calculate_layout(area)
   # Main area vs sidebar (70% / 30%)
-  main_area, @sidebar_area = RatatuiRuby::Layout.split(
-    full_area,
+  main_area, @sidebar_area = @tui.layout_split(
+    area,
     direction: :horizontal,
     constraints: [
-      RatatuiRuby::Constraint.percentage(70),
-      RatatuiRuby::Constraint.percentage(30),
+      @tui.constraint_percentage(70),
+      @tui.constraint_percentage(30),
     ]
   )
 
   # Within main area, left vs right panels
-  @left_rect, @right_rect = RatatuiRuby::Layout.split(
+  @left_rect, @right_rect = @tui.layout_split(
     main_area,
     direction: :horizontal,
     constraints: [
-      RatatuiRuby::Constraint.percentage(@left_ratio),
-      RatatuiRuby::Constraint.percentage(100 - @left_ratio)
+      @tui.constraint_percentage(@left_ratio),
+      @tui.constraint_percentage(100 - @left_ratio)
     ]
   )
 end
@@ -66,10 +67,9 @@ end
 Reuse the cached rects. Build and draw:
 
 ```ruby
-def render
-  left_panel = build_widget(@left_rect)
-  right_panel = build_widget(@right_rect)
-  # ... draw ...
+def render(frame)
+  frame.render_widget(build_widget(@left_rect), @left_rect)
+  frame.render_widget(build_widget(@right_rect), @right_rect)
 end
 ```
 
@@ -80,7 +80,6 @@ Reuse the cached rects. Test clicks:
 ```ruby
 def handle_input
   event = RatatuiRuby.poll_event
-  return unless event
 
   case event
   in type: :mouse, kind: "down", x:, y:
@@ -104,18 +103,14 @@ end
 
 ## Layout.split
 
-`Layout.split` computes layout geometry without rendering. It returns an array of `Rect` objects.
+`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
-rects = Layout.split(
-  area,
-  direction: :horizontal,
-  constraints: [Constraint.percentage(70), Constraint.percentage(30)]
-)
-
-left, right = rects
-# left is a Rect describing the left 70% of the area
-# right is a Rect describing the right 30% of the area
+# 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 in `calculate_layout`. Reuse the results in both render and event handling.
+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`.