ratatui_ruby 0.8.0 → 0.9.0

data/doc/concepts/application_architecture.md

@@ -1,7 +1,6 @@
 <!--
-SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-
-SPDX-License-Identifier: AGPL-3.0-or-later
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
 # Application Architecture
@@ -24,6 +23,11 @@ Terminals have state. They remember cursor positions, input modes, and screen bu
 
 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.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 RatatuiRuby.run do |tui|
   loop do
@@ -35,11 +39,17 @@ RatatuiRuby.run do |tui|
 end
 # Terminal is restored here
 ```
+<!-- SPDX-SnippetEnd -->
 
 #### Manual Management
 
 Need granular control? You can initialize and restore the terminal yourself. Use `ensure` blocks to guarantee cleanup.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 RatatuiRuby.init_terminal
 begin
@@ -51,6 +61,7 @@ ensure
   # Terminal is restored here
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 #### Signal Handling
 
@@ -69,6 +80,11 @@ External processes send signals. Your TUI must handle them gracefully.
 > [!IMPORTANT]
 > **Ctrl+C in Raw Mode:** When your app is in raw mode, pressing Ctrl+C does *not* send SIGINT. It's captured as a `:ctrl_c` key event. Handle this in your event loop—don't use `trap("INT")`.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 RatatuiRuby.run do |tui|
   loop do
@@ -78,6 +94,7 @@ RatatuiRuby.run do |tui|
   end
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 **Recovery:** If a TUI app leaves your terminal broken, run `reset` in the shell to restore normal behavior.
 
@@ -97,6 +114,11 @@ Most widgets are stateless configuration. You create them, render them, and they
 
 **Use Case:** When you need to read back the scroll offset (e.g., for mouse hit testing) or persist selection without managing indexes manually.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 # Initialize state once
 @list_state = RatatuiRuby::ListState.new
@@ -116,6 +138,7 @@ RatatuiRuby.run do |tui|
   end
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 ### API Convenience
 
@@ -125,6 +148,11 @@ Writing UI trees involves nesting many widgets.
 
 **The Solution:** The TUI API (`tui`) provides shorthand factories for every widget. It yields a TUI object to your block.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 RatatuiRuby.run do |tui|
   loop do
@@ -167,11 +195,17 @@ RatatuiRuby.run do |tui|
   end
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 #### Raw API
 
 Building your own abstractions? You might prefer explicit class instantiation. The raw constants are always available.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 RatatuiRuby.run do
   loop do
@@ -212,6 +246,7 @@ RatatuiRuby.run do
   end
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 ## Thread and Ractor Safety
 
@@ -236,6 +271,11 @@ These have side effects and are intentionally not shareable:
 | `TUI` | Cache in `@tui` during run loop. Don't include in Models. |
 | `Frame` | Pass to helpers during draw block. Invalid after block returns. |
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 # Good: Cache session in instance variable
 RatatuiRuby.run do |tui|
@@ -246,6 +286,7 @@ end
 # Bad: Include in immutable Model (won't work with Ractors)
 Model = Data.define(:tui, :count)  # Don't do this
 ```
+<!-- SPDX-SnippetEnd -->
 
 
 ## Reference Architectures

data/doc/concepts/application_testing.md

@@ -1,5 +1,5 @@
 <!--
-  SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
   SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 # Application Testing Guide
@@ -18,19 +18,31 @@ Use it to write fast, deterministic tests for your TUI applications.
 
 First, require the test helper in your test file or `test_helper.rb`:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 require "ratatui_ruby/test_helper"
 require "minitest/autorun" # or your preferred test framework
 ```
+<!-- SPDX-SnippetEnd -->
 
 Then, include the module in your test class:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 class MyApplicationTest < Minitest::Test
   include RatatuiRuby::TestHelper
   # ...
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 ## Writing a View Test
 
@@ -40,6 +52,11 @@ To test a view or widget, wrap your assertions in `with_test_terminal`. This set
 2.  **Render your code:** Instantiate your widget and draw it to a frame.
 3.  **Assert output:** Check the `buffer_content` against your expectations.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 def test_rendering
   # Uses default 80x24 terminal
@@ -57,6 +74,7 @@ def test_rendering
   end
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 For the full API list, including `buffer_content` and `cursor_position`, see [RatatuiRuby::TestHelper::Terminal](../lib/ratatui_ruby/test_helper/terminal.rb).
 
@@ -66,6 +84,11 @@ You often need to check colors and modifiers (bold, italic) to ensure your highl
 
 Use `assert_fg_color`, `assert_bg_color`, and modifier helpers like `assert_bold`.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 # Assert specific cell style
 assert_fg_color(:red, 0, 0)
@@ -74,6 +97,7 @@ assert_bold(0, 0)
 # Or check a whole area
 assert_area_style({ x: 0, y: 0, w: 10, h: 1 }, bg: :blue)
 ```
+<!-- SPDX-SnippetEnd -->
 
 See [RatatuiRuby::TestHelper::StyleAssertions](../lib/ratatui_ruby/test_helper/style_assertions.rb) for the comprehensive list of style helpers.
 
@@ -86,6 +110,11 @@ Use `inject_event` to push mock events into the queue. This ensures safe, determ
 > [!IMPORTANT]
 > Call `inject_event` inside a `with_test_terminal` block to avoid race conditions.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 with_test_terminal do
   # Simulate 'q' key press
@@ -96,6 +125,7 @@ with_test_terminal do
   assert_equal "q", event.code
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 See [RatatuiRuby::TestHelper::EventInjection](../lib/ratatui_ruby/test_helper/event_injection.rb) for helper methods like `inject_keys` and `inject_click`.
 
@@ -105,12 +135,18 @@ Snapshots let you verify complex layouts without manually asserting every line.
 
 Use `assert_snapshots` to compare the current screen against stored reference files.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 with_test_terminal do
   MyApp.new.run
   assert_snapshots("dashboard_view")
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 This generates both `.txt` (plain text) and `.ansi` (styled) snapshot files. The `.ansi` files contain ANSI escape codes—`cat` them in a terminal to see exactly what the screen looked like. For a visual tour of your test suite, try `cat **/*.ansi` in any shell that supports globbing.
 
@@ -130,6 +166,11 @@ Sometimes you want to test a single view component without spinning up the full
 
 Use `MockFrame` and `StubRect` to test render logic in isolation.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 def test_logs_view
   frame = RatatuiRuby::TestHelper::TestDoubles::MockFrame.new
@@ -143,6 +184,7 @@ def test_logs_view
   assert_equal "Logs", rendered[:widget].block.title
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 See [RatatuiRuby::TestHelper::TestDoubles](../lib/ratatui_ruby/test_helper/test_doubles.rb).
 

data/doc/concepts/async.md

@@ -1,6 +1,6 @@
 <!--
-SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: AGPL-3.0-or-later
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
 # Async Operations in TUI Applications
@@ -21,12 +21,18 @@ This guide explains async patterns that work with raw terminal mode.
 
 ### What Breaks
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 # These fail inside a Thread during raw mode:
 `git ls-remote --tags origin`           # Returns empty or hangs
 IO.popen(["git", "ls-remote", ...])     # Same
 Open3.capture2("git", "ls-remote", ...) # Same
 ```
+<!-- SPDX-SnippetEnd -->
 
 The commands succeed synchronously. They fail asynchronously. The difference: thread context inherits the parent's raw terminal state.
 
@@ -46,11 +52,17 @@ Ruby's GIL releases during I/O. But:
 
 Run slow operations before entering the TUI:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 def initialize
   @data = fetch_data  # Runs before RatatuiRuby.run
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 **Trade-off**: Delays startup.
 
@@ -58,6 +70,11 @@ end
 
 Spawn a separate process before entering raw mode. Write results to a temp file. Poll for completion:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 class AsyncChecker
   CACHE_FILE = File.join(Dir.tmpdir, "my_check_result.txt")
@@ -81,6 +98,7 @@ class AsyncChecker
   end
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 **Key points**:
 
@@ -93,9 +111,15 @@ end
 
 Ruby threads work for pure computation:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 Thread.new { @result = expensive_calculation }
 ```
+<!-- SPDX-SnippetEnd -->
 
 Avoid threads for shell commands.
 
@@ -122,6 +146,11 @@ For TUI async, `Process.spawn` solves the problem cleanly.
 
 Check if a tag exists on the remote:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 class GitRepo
   CACHE_FILE = File.join(Dir.tmpdir, "git_tag_pushed.txt")
@@ -156,5 +185,6 @@ class GitRepo
   end
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 The TUI starts instantly. The tag check runs in the background. The checklist updates when the result arrives.

data/doc/concepts/custom_widgets.md

@@ -0,0 +1,247 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Custom Widgets
+
+Build anything. Escape the widget library.
+
+## What Terminals Offer
+
+Terminals do not have pixels. They have character cells arranged in a grid. Each cell holds one character with foreground color, background color, and text modifiers (bold, italic, underline).
+
+This constraint shapes what you can draw:
+
+- **Characters**: Any Unicode character fits in a cell
+- **Box-drawing**: Lines, corners, and boxes (`│`, `┌`, `─`, `└`)
+- **Block elements**: Partial fills (`▀`, `▄`, `█`, `░`, `▒`, `▓`)
+- **Braille patterns**: 2×4 "pixel" grids per cell for pseudo-graphics
+- **Nerd Fonts**: Icons and glyphs if the user's font supports them
+
+The built-in Canvas widget uses Braille patterns for line graphs and shapes. Custom widgets give you direct control over every cell.
+
+## The Problem
+
+Standard widgets handle common needs. Paragraphs display text. Lists show selections. Tables organize data.
+
+But terminals can do more. You want a game board, a network graph, or a custom visualization. The built-in widgets cannot help you here.
+
+## The Solution
+
+Any Ruby object that implements `render(area)` works as a widget. You are not limited to what the library ships. Define a class. Implement one method. Pass it to `frame.render_widget`.
+
+The Engine calls your `render` method with the area where your widget should draw. You return an array of Draw commands. The Engine executes them.
+
+## The Contract
+
+Your custom widget implements [the `_CustomWidget` interface](../../sig/ratatui_ruby/frame.rbs). The `area` parameter is a `Rect` with `x`, `y`, `width`, and `height`. It tells you where to draw and how much space you have.
+
+## Draw Commands
+
+Two commands describe what to draw:
+
+| Command | Purpose |
+|---------|---------|
+| `Draw.string(x, y, text, style)` | Draw a styled string at absolute coordinates |
+| `Draw.cell(x, y, cell)` | Draw a single cell (character + style) |
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+class HelloWidget
+  def render(area)
+    [
+      RatatuiRuby::Draw.string(
+        area.x,
+        area.y,
+        "Hello, World!",
+        RatatuiRuby::Style::Style.new(fg: :green, modifiers: [:bold])
+      )
+    ]
+  end
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+## Coordinate Offsets
+
+The `area.x` and `area.y` values are not always zero. When your widget renders inside a `Block` with borders, or within a nested layout, the area's origin shifts.
+
+Always add `area.x` and `area.y` to your drawing coordinates. This pattern ensures your widget works regardless of where it appears on screen.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+class DiagonalWidget
+  def render(area)
+    (0...area.height).filter_map do |i|
+      next if i >= area.width  # Stay within bounds
+
+      RatatuiRuby::Draw.string(
+        area.x + i,  # Offset from area origin
+        area.y + i,
+        "\\",
+        RatatuiRuby::Style::Style.new(fg: :red)
+      )
+    end
+  end
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+## Composability
+
+Custom widgets compose with standard widgets. Wrap them in Blocks. Place them in layouts. Mix them with Paragraphs and Lists.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+RatatuiRuby.run do |tui|
+  tui.draw do |frame|
+    areas = tui.layout_split(
+      frame.area,
+      direction: :horizontal,
+      constraints: [tui.constraint_percentage(50), tui.constraint_percentage(50)]
+    )
+
+    # Standard widget on the left
+    frame.render_widget(tui.paragraph(text: "Standard"), areas[0])
+
+    # Custom widget on the right
+    frame.render_widget(DiagonalWidget.new, areas[1])
+  end
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+To render inside a bordered Block, calculate the inner area first:
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+tui.draw do |frame|
+  # Render the block frame
+  block = tui.block(title: "Custom", borders: [:all])
+  frame.render_widget(block, frame.area)
+
+  # Calculate inner area (1-cell border on all sides)
+  inner = tui.rect(
+    x: frame.area.x + 1,
+    y: frame.area.y + 1,
+    width: [frame.area.width - 2, 0].max,
+    height: [frame.area.height - 2, 0].max
+  )
+
+  # Render custom widget inside
+  frame.render_widget(MyWidget.new, inner)
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+## Using Custom Widgets in Layouts
+
+Custom widgets work as children in Layout trees. The layout system passes the calculated area to your `render` method.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+layout = RatatuiRuby::Layout::Layout.new(
+  direction: :vertical,
+  constraints: [
+    RatatuiRuby::Layout::Constraint.length(1),
+    RatatuiRuby::Layout::Constraint.fill(1),
+  ],
+  children: [
+    RatatuiRuby::Widgets::Paragraph.new(text: "Header"),
+    MyCustomWidget.new,  # Your widget here
+  ]
+)
+
+RatatuiRuby.draw(layout)
+```
+<!-- SPDX-SnippetEnd -->
+
+## Testing Custom Widgets
+
+Custom widgets return arrays. Test them by calling `render` directly and asserting on the result.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+def test_hello_widget_output
+  area = RatatuiRuby::Rect.new(x: 0, y: 0, width: 20, height: 5)
+  widget = HelloWidget.new
+  commands = widget.render(area)
+
+  assert_equal 1, commands.length
+  assert_equal 0, commands[0].x
+  assert_equal 0, commands[0].y
+  assert_equal "Hello, World!", commands[0].string
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+For visual testing, use the test helper to render to a buffer and assert on content:
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+class TestMyWidget < Minitest::Test
+  include RatatuiRuby::TestHelper
+
+  def test_renders_in_terminal
+    with_test_terminal(10, 5) do
+      RatatuiRuby.draw(MyWidget.new)
+      assert_equal "Expected  ", buffer_content[0]
+    end
+  end
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+## Typing Your Widgets (RBS)
+
+Type your custom widgets by implementing the `_CustomWidget` interface:
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```rbs
+# my_widget.rbs
+class MyWidget
+  def render: (RatatuiRuby::Rect area) -> Array[RatatuiRuby::Draw::StringCmd | RatatuiRuby::Draw::CellCmd]
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+The interface uses structural typing. Any class with a matching `render` signature satisfies it.
+
+## Related Resources
+
+- [Custom Render Example](../examples/widget_render/README.md) — Full working example
+- [Cell Example](../examples/widget_cell/README.md) — Low-level cell drawing
+- [Application Testing](./application_testing.md) — Test helper reference