ratatui_ruby 0.5.0 → 0.7.0

data/doc/v0.7.0_migration.md

@@ -0,0 +1,236 @@
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Migrating to v0.7.0
+
+v0.7.0 restructures the library to align with upstream Ratatui. For most users, this is a non-breaking change. For some, it is breaking.
+
+## Are You Affected?
+
+**If your code looks like this, you're fine:**
+
+```ruby
+RatatuiRuby.run do |tui|
+  tui.draw tui.paragraph(text: "Hello", block: tui.block(title: "Title"))
+  event = tui.poll_event
+end
+```
+
+The TUI API method names are unchanged. Your application works without modification.
+
+**If your code uses `highlight_style:` on Tables, rename it:**
+
+```ruby
+# Before (v0.6.0)
+tui.table(rows: [...], highlight_style: tui.style(fg: :yellow))
+
+# After (v0.7.0)
+tui.table(rows: [...], row_highlight_style: tui.style(fg: :yellow))
+```
+
+This change aligns with Ratatui's API naming convention.
+
+**If your code instantiates classes directly, you have work to do:**
+
+```ruby
+# These lines break in v0.7.0
+paragraph = RatatuiRuby::Paragraph.new(text: "Hello")
+style = RatatuiRuby::Style.new(fg: :red)
+rect = RatatuiRuby::Rect.new(x: 0, y: 0, width: 10, height: 5)
+```
+
+The old flat namespace no longer exists. Classes moved into modules.
+
+## Option 1: Use the TUI API (Recommended)
+
+Switch to the TUI API. It hides namespace verbosity and provides IDE autocomplete.
+
+```ruby
+RatatuiRuby.run do |tui|
+  # All these work exactly as before
+  paragraph = tui.paragraph(text: "Hello")
+  style = tui.style(fg: :red)
+  rect = tui.rect(x: 0, y: 0, width: 10, height: 5)
+  constraint = tui.constraint_length(20)
+  
+  # New in v0.7.0
+  cell = tui.table_cell(content: "Error", style: tui.style(bg: :red))
+  row = tui.table_row(cells: ["A", "B", "C"], style: tui.style(bg: :dark_gray))
+end
+```
+
+## Option 2: Update to New Namespaces
+
+If you prefer direct class instantiation, update to the new paths:
+
+| Before | After |
+|--------|-------|
+| `RatatuiRuby::Rect` | `RatatuiRuby::Layout::Rect` |
+| `RatatuiRuby::Constraint` | `RatatuiRuby::Layout::Constraint` |
+| `RatatuiRuby::Layout` | `RatatuiRuby::Layout::Layout` |
+| `RatatuiRuby::Style` | `RatatuiRuby::Style::Style` |
+| `RatatuiRuby::Paragraph` | `RatatuiRuby::Widgets::Paragraph` |
+| `RatatuiRuby::Block` | `RatatuiRuby::Widgets::Block` |
+| `RatatuiRuby::Table` | `RatatuiRuby::Widgets::Table` |
+| `RatatuiRuby::List` | `RatatuiRuby::Widgets::List` |
+| `RatatuiRuby::Cell` | `RatatuiRuby::Buffer::Cell` |
+| *(all other widgets)* | `RatatuiRuby::Widgets::*` |
+
+### Bulk Migration
+
+```bash
+find . -name "*.rb" -exec sed -i '' \
+  's/RatatuiRuby::Rect/RatatuiRuby::Layout::Rect/g; \
+   s/RatatuiRuby::Constraint\./RatatuiRuby::Layout::Constraint./g; \
+   s/RatatuiRuby::Paragraph\.new/RatatuiRuby::Widgets::Paragraph.new/g; \
+   s/RatatuiRuby::Block\.new/RatatuiRuby::Widgets::Block.new/g; \
+   s/RatatuiRuby::List\.new/RatatuiRuby::Widgets::List.new/g; \
+   s/RatatuiRuby::Table\.new/RatatuiRuby::Widgets::Table.new/g; \
+   s/RatatuiRuby::Style\.new/RatatuiRuby::Style::Style.new/g; \
+   s/RatatuiRuby::Session/RatatuiRuby::TUI/g; \
+   s/highlight_style:/row_highlight_style:/g' {} \;
+```
+
+## Session → TUI Rename
+
+The `Session` class is now `TUI`. If you reference it directly:
+
+```ruby
+# Before
+tui = RatatuiRuby::Session.new
+
+# After
+tui = RatatuiRuby::TUI.new
+```
+
+Most users never reference the class directly. The `|tui|` block parameter works unchanged.
+
+## Table: highlight_style → row_highlight_style
+
+The `highlight_style:` parameter on Table is now `row_highlight_style:`. This aligns with Ratatui's naming convention where `row_highlight_style`, `column_highlight_style`, and `cell_highlight_style` form a consistent trio.
+
+```ruby
+# Before (v0.6.0)
+tui.table(
+  rows: data,
+  highlight_style: tui.style(fg: :yellow)
+)
+
+# After (v0.7.0)
+tui.table(
+  rows: data,
+  row_highlight_style: tui.style(fg: :yellow)
+)
+```
+
+## Text::Line style Field
+
+`Text::Line` now accepts a `style:` parameter for line-level styling. This matches Ratatui's `Line` struct.
+
+```ruby
+# New in v0.7.0: Line-level styling
+line = tui.text_line(
+  spans: [tui.text_span(content: "Hello")],
+  style: tui.style(bg: :dark_gray)  # Applied to entire line
+)
+```
+
+Existing code without `style:` continues to work unchanged.
+
+## New Table Cell and Row Classes
+
+v0.7.0 adds `Widgets::Cell` and `Widgets::Row` for table construction with per-cell styling:
+
+```ruby
+table = tui.table(
+  rows: [
+    tui.table_row(
+      cells: [
+        tui.table_cell(content: "Name", style: tui.style(fg: :blue)),
+        "Value"
+      ],
+      style: tui.style(bg: :dark_gray)
+    )
+  ],
+  widths: [tui.constraint_length(20), tui.constraint_fill]
+)
+```
+
+## Buffer::Cell vs Widgets::Cell
+
+Two `Cell` classes now exist:
+
+- **`Buffer::Cell`** — Terminal cell for inspection (returned by `get_cell_at`)
+- **`Widgets::Cell`** — Table cell for construction (content + style wrapper)
+
+```ruby
+# Buffer inspection (unchanged)
+cell = RatatuiRuby.get_cell_at(0, 0)  # Returns Buffer::Cell
+cell.char  # => "X"
+cell.fg    # => :red
+
+# Table cell construction (new)
+cell = tui.table_cell(content: "Error", style: tui.style(bg: :red))
+```
+
+## Why This Change?
+
+The old flat namespace caused name collisions (`Cell` for buffers vs. tables) and diverged from Ratatui's module structure. The new hierarchy:
+
+- Maps 1:1 to Ratatui documentation
+- Prevents future collisions
+- Enables IDE autocomplete via explicit TUI methods
+
+---
+
+## For LLMs
+
+Copy the following prompt to your AI assistant to help migrate your `ratatui_ruby` application from v0.6.0 to v0.7.0.
+
+````markdown
+I'm migrating a Ruby TUI application from `ratatui_ruby` v0.6.0 to v0.7.0. The library restructured its namespaces. Apply these transformations:
+
+**Namespace Changes:**
+- `RatatuiRuby::Rect` → `RatatuiRuby::Layout::Rect`
+- `RatatuiRuby::Constraint` → `RatatuiRuby::Layout::Constraint`
+- `RatatuiRuby::Layout` → `RatatuiRuby::Layout::Layout`
+- `RatatuiRuby::Style` → `RatatuiRuby::Style::Style`
+- `RatatuiRuby::Paragraph` → `RatatuiRuby::Widgets::Paragraph`
+- `RatatuiRuby::Block` → `RatatuiRuby::Widgets::Block`
+- `RatatuiRuby::Table` → `RatatuiRuby::Widgets::Table`
+- `RatatuiRuby::List` → `RatatuiRuby::Widgets::List`
+- `RatatuiRuby::Cell` → `RatatuiRuby::Buffer::Cell`
+- All other widgets: `RatatuiRuby::X` → `RatatuiRuby::Widgets::X`
+
+**Class Rename:**
+- `RatatuiRuby::Session` → `RatatuiRuby::TUI`
+
+**Parameter Rename:**
+- `Table` `highlight_style:` → `row_highlight_style:`
+
+**Preferred Approach:** Convert direct class instantiation to TUI API:
+```ruby
+# Instead of:
+RatatuiRuby::Widgets::Paragraph.new(text: "Hello")
+
+# Use:
+tui.paragraph(text: "Hello")
+```
+
+**TUI API method names are unchanged.** Code using `tui.paragraph(...)`, `tui.block(...)`, `tui.style(...)` etc. works without modification.
+
+**Cell Disambiguation:**
+- `Buffer::Cell` — Terminal cell for inspection (returned by `get_cell_at`)
+- `Widgets::Cell` — Table cell for construction (use `tui.table_cell`)
+- The old `RatatuiRuby::Cell` is now `RatatuiRuby::Buffer::Cell`
+
+**New in v0.7.0:**
+- `tui.table_cell(content:, style:)` — styled table cells
+- `tui.table_row(cells:, style:, height:)` — styled table rows
+- `Text::Line` now accepts `style:` parameter
+
+Please update my code following these rules.
+````
+

data/doc/why.md

@@ -0,0 +1,93 @@
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+# Why RatatuiRuby?
+
+The terminal is having a renaissance. Ruby deserves to be at the forefront.
+
+**RatatuiRuby** is a high-performance, immediate-mode TUI engine that brings the power of Rust's [Ratatui](https://ratatui.rs) library directly into Ruby. No ports. No emulations. A native bridge to the industry-standard Rust crate.
+
+
+## The Pitch
+
+You want to build a terminal UI. You love Ruby. Your options were:
+
+1. **Learn Go** for Bubble Tea
+2. **Learn Rust** for Ratatui
+3. **Use a pure-Ruby library** with limited performance
+
+We built a fourth option: **Write Ruby. Run Rust.**
+
+RatatuiRuby gives you Rust's layout engine, rendering speed, and battle-tested widgets — with Ruby's expressiveness, ecosystem, and joy.
+
+
+## RatatuiRuby vs. CharmRuby
+
+[CharmRuby](https://github.com/marcoroth/charm_ruby) is an excellent project by Marco Roth. It provides Ruby bindings to Charm's Go libraries (Bubble Tea, Lipgloss). The Ruby ecosystem is better because both projects exist.
+
+So which one should you choose?
+
+| | CharmRuby | RatatuiRuby |
+|---|-----------|-------------|
+| **Backend** | Go runtime | Rust (no runtime) |
+| **Architecture** | Elm Architecture (MVU) | Immediate-mode + your choice |
+| **GC Behavior** | Two GCs (Ruby + Go) | One GC (Ruby only) |
+| **Rendering** | String manipulation | Constraint-based layout tree |
+| **Best for** | Fans of Bubble Tea, MVU | Native performance, heavy-duty apps |
+
+**What's a runtime?** A runtime is background machinery that a language needs to run. Go has one (for goroutines and garbage collection). Rust doesn't — it compiles to plain machine code. When you use Go bindings, you're running *two* runtimes in the same process (Ruby's and Go's), which adds complexity and memory overhead. With Rust bindings, there's only Ruby.
+
+**Choose CharmRuby** if you prefer Charm's aesthetics or are migrating existing Bubble Tea code.
+
+**Choose RatatuiRuby** if you want zero-overhead native performance and architectural freedom. RatatuiRuby doesn't force a framework — you can build MVU, component-based, or any pattern you prefer.
+
+
+## Why Not Just Write Rust?
+
+Rust is amazing. It's also strict.
+
+The borrow checker enforces memory safety. That's great for systems programming. It's painful for UI iteration. Moving a sidebar, changing a color, or swapping a widget often requires refactoring ownership chains.
+
+With RatatuiRuby, you just change the object. You get Rust's performance where it matters — rendering — and Ruby's flexibility where it counts — designing.
+
+
+## Why Not Just Write Go?
+
+Go is pragmatic. But using Go bindings means running *two* runtimes in the same process: Ruby's and Go's. That adds complexity and memory overhead.
+
+With RatatuiRuby, there's only Ruby. Rust compiles to plain machine code with no runtime — it integrates seamlessly.
+
+
+## Why Ruby?
+
+[Ruby isn't just another language](https://www.ruby-lang.org/en/). It's an ecosystem:
+
+- **[ActiveRecord](https://guides.rubyonrails.org/active_record_basics.html)** — Query your database with elegant, chainable methods
+- **[RSpec](https://rspec.info/)** — Write expressive, readable tests with `describe`, `it`, and `expect`
+- **[Blocks](https://ruby-doc.org/docs/ruby-doc-bundle/UsersGuide/rg/blocks.html)** — Pass behavior to methods with `do...end`, the heart of Ruby's expressiveness
+- **[Metaprogramming](https://ruby-doc.org/docs/ruby-doc-bundle/UsersGuide/rg/objinitialization.html)** — Define methods dynamically, build DSLs, and write code that writes code
+- **[Bundler](https://bundler.io/)** — Access 180,000+ gems with a single `bundle add`
+
+Build a dashboard for your Rails app. Monitor your Sidekiq jobs. Create developer tools in the same language as the code they inspect.
+
+
+## The Philosophy: A Solid Foundation
+
+RatatuiRuby is a **low-level engine**. It provides raw primitives — Layouts, Blocks, Text, Tables, Charts — to build anything.
+
+It doesn't force a framework on you. You can use:
+- **Model-View-Update** for dashboards and data displays
+- **Component-based** patterns for interactive tools
+- **Your own architecture** for everything else
+
+This is the foundation for Ruby's next generation of TUI tools, dashboards, and interactive scripts.
+
+
+## Get Started
+
+Ready to build?
+
+- [Quickstart Guide](./quickstart.md) — Your first app in 5 minutes
+- [Widget Gallery](./quickstart.md#widget-demos) — See what's possible
+- [Application Architecture](./application_architecture.md) — Patterns for scaling

data/examples/app_all_events/README.md

@@ -5,37 +5,56 @@ 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.
+[![App All Events](../../doc/images/app_all_events.png)](app.rb)
 
-## Architecture: MVVM (Model-View-ViewModel)
+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 Model-View-Update architectural pattern.
 
-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.
+## Architecture: Model-View-Update
 
-### 1. Model (`model/`)
-The **Model** manages the application's domain data and logic. It knows nothing about the UI.
+This application demonstrates **unidirectional data flow** inspired by The Elm Architecture. This separation ensures that state management is predictable and easy to test.
 
-*   **`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.
+### 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
 
-### 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.
+State changes use `.with(...)` to return a new Model instance.
 
-*   **`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`.
+### 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
 
-### 3. View (`view/`)
-The **View** is responsible **only** for rendering. It receives the `ViewState` and draws to the screen.
+### 3. Update (`update.rb`)
+A **pure function** that computes the next state:
 
-*   **`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`.
+```ruby
+Update.call(msg, model) -> Model
+```
 
-### 4. Controller/App (`app.rb`)
-The **`AppAllEvents`** class ties it all together. It owns the main loop:
+All logic previously in `Events.record` now lives here. The function never mutates, never draws, never performs IO.
 
-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.
+### 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`
+
+### 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 +76,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 +87,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. Model-View-Update 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 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 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