ratatui_ruby 1.0.0 → 1.0.1

data/doc/concepts/application_architecture.md

@@ -1,321 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Application Architecture
-
-Architect robust TUI applications using core lifecycle patterns and API best practices.
-
-## Core Concepts
-
-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.
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-RatatuiRuby.run do |tui|
-  loop do
-    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
-```
-<!-- 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
-  RatatuiRuby.draw do |frame|
-    frame.render_widget(RatatuiRuby::Widgets::Paragraph.new(text: "Hello"), frame.area)
-  end
-ensure
-  RatatuiRuby.restore_terminal
-  # Terminal is restored here
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-#### Signal Handling
-
-External processes send signals. Your TUI must handle them gracefully.
-
-**The Problem:** If a signal terminates your process before `restore_terminal` runs, the terminal stays in raw mode. Your shell becomes unusable until you type `reset` and press Enter (the text won't echo, but it works).
-
-**The Solution:** Ruby's default signal handlers work correctly with `ensure` blocks. Most signals unwind the stack, which triggers cleanup.
-
-| Signal | Source | Terminal Restored? |
-|--------|--------|--------------------|
-| SIGTERM | `kill -15` | ✓ Yes — ensure runs |
-| SIGINT | `kill -2` (not Ctrl+C) | ✓ Yes — ensure runs |
-| SIGKILL | `kill -9` | ✗ No — cannot be caught |
-
-> [!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
-    # ...
-    event = tui.poll_event
-    break if event == :ctrl_c  # Handle Ctrl+C yourself
-  end
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-**Recovery:** If a TUI app leaves your terminal broken, run `reset` in the shell to restore normal behavior.
-
-
-### 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.
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```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
-```
-<!-- SPDX-SnippetEnd -->
-
-### API Convenience
-
-Writing UI trees involves nesting many widgets.
-
-**The Problem:** Explicitly namespacing `RatatuiRuby::` for every widget (e.g., `RatatuiRuby::Widgets::Paragraph.new`) is tedious. It creates visual noise that hides your layout structure.
-
-**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
-    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)),
-            tui.text_span(content: "bar")
-          ]),
-          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")
-        ),
-        content_area
-      )
-    end
-    
-    event = tui.poll_event
-    break if event == "q" || event == :ctrl_c
-  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
-    RatatuiRuby.draw do |frame|
-      # Manual split
-      rects = RatatuiRuby::Layout::Layout.split(
-        frame.area,
-        direction: :horizontal,
-        constraints: [
-          RatatuiRuby::Layout::Constraint.length(20),
-          RatatuiRuby::Layout::Constraint.min(0)
-        ]
-      )
-
-      frame.render_widget(
-        RatatuiRuby::Widgets::Paragraph.new(
-          text: RatatuiRuby::Text::Line.new(spans: [
-            RatatuiRuby::Text::Span.new(content: "Side", style: RatatuiRuby::Style::Style.new(fg: :blue)),
-            RatatuiRuby::Text::Span.new(content: "bar")
-          ]),
-          block: RatatuiRuby::Widgets::Block.new(borders: [:all], title: "Nav")
-        ),
-        rects[0]
-      )
-
-      frame.render_widget(
-        RatatuiRuby::Widgets::Paragraph.new(
-          text: "Main Content",
-          style: RatatuiRuby::Style::Style.new(fg: :green),
-          block: RatatuiRuby::Widgets::Block.new(borders: [:all], title: "Content")
-        ),
-        rects[1]
-      )
-    end
-
-    event = RatatuiRuby.poll_event
-    break if event == "q" || event == :ctrl_c
-  end
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-## 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 immutable 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 |
-|--------|-------------|
-| `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|
-  @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
-```
-<!-- SPDX-SnippetEnd -->
-
-
-## Reference Architectures
-
-Simple scripts work well with valid linear code. Complex apps need structure.
-
-We provide these reference architectures to inspire you:
-
-### 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.
-
-### 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/concepts/application_testing.md

@@ -1,193 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-# Application Testing Guide
-
-This guide explains how to test your RatatuiRuby applications using the provided `RatatuiRuby::TestHelper`.
-
-## Overview
-
-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.
-
-The `TestHelper` module solves this. It provides a headless "test terminal" to capture output and a suite of robust assertions to verify state.
-
-Use it to write fast, deterministic tests for your TUI applications.
-
-## Setup
-
-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
-
-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.
-
-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.
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-def test_rendering
-  # Uses default 80x24 terminal
-  with_test_terminal do
-    # 1. Instantiate your widget
-    widget = RatatuiRuby::Widgets::Paragraph.new(text: "Hello World")
-    
-    # 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.first, "Hello World"
-  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).
-
-## Verifying Styles
-
-You often need to check colors and modifiers (bold, italic) to ensure your highlighting logic works.
-
-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)
-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.
-
-## Simulating Input
-
-You need to test user interactions like typing or clicking. Stubbing `poll_event` directly is brittle.
-
-Use `inject_event` to push mock events into the queue. This ensures safe, deterministic handling of input.
-
-> [!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
-  inject_event("key", { code: "q" })
-
-  # The application receives the 'q' event
-  event = RatatuiRuby.poll_event
-  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`.
-
-## Snapshot Testing
-
-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.
-
-### 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.
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```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
-```
-<!-- SPDX-SnippetEnd -->
-
-See [RatatuiRuby::TestHelper::TestDoubles](../lib/ratatui_ruby/test_helper/test_doubles.rb).
-
-## Example
-
-Check out the [examples directory](../../examples/) for fully tested applications showcasing these patterns.

data/doc/concepts/async.md

@@ -1,190 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Async Operations in TUI Applications
-
-TUI applications fetch data from APIs, run shell commands, and query databases. These operations take time. Blocking the render loop freezes the interface.
-
-You want responsive UIs. The checklist shows "Loading..." while data arrives. The interface never hangs.
-
-This guide explains async patterns that work with raw terminal mode.
-
-## The Raw Terminal Problem
-
-`RatatuiRuby.run` enters raw terminal mode:
-
-- stdin reconfigures for character-by-character input
-- stdout carries terminal escape sequences
-- External commands expecting normal terminal I/O fail
-
-### 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.
-
-### Why Threads Fail
-
-Ruby's GIL releases during I/O. But:
-
-1. Subprocesses inherit the parent's terminal state.
-2. Git/SSH try to read credentials from raw-mode stdin.
-3. The read blocks forever. Or returns empty.
-
-`GIT_TERMINAL_PROMPT=0` prevents prompts. Auth fails silently instead of hanging.
-
-## Solutions
-
-### Pre-Check Before Raw Mode
-
-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.
-
-### Process.spawn with File Output
-
-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")
-
-  def initialize
-    @loading = true
-    @result = nil
-    @pid = Process.spawn("my-command > #{CACHE_FILE}")
-  end
-
-  def loading?
-    return false unless @loading
-
-    # Non-blocking poll
-    _pid, status = Process.waitpid2(@pid, Process::WNOHANG)
-    if status
-      @result = File.read(CACHE_FILE).strip
-      @loading = false
-    end
-    @loading
-  end
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-**Key points**:
-
-- `Process.spawn` returns immediately.
-- The command runs in a separate process, not a thread.
-- Results pass through a temp file. Avoids pipe/terminal issues.
-- `Process::WNOHANG` polls without blocking.
-
-### Thread for CPU-Bound Work
-
-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.
-
-## Ractors
-
-Ractors provide true parallelism. Trade-offs:
-
-- No mutable shared state.
-- Limited to Ractor-safe values.
-- Terminal I/O issues remain.
-
-For TUI async, `Process.spawn` solves the problem cleanly.
-
-## Pattern Summary
-
-| Approach | Use Case | Raw Mode Safe? |
-|----------|----------|----------------|
-| Sync before TUI | Fast checks (<100ms) | Yes |
-| Process.spawn + file | Shell commands, network | Yes |
-| Thread | CPU-bound Ruby code | Yes |
-| Thread + shell | Shell commands | **No** |
-
-## Real Example: Git Tag Check
-
-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")
-
-  def initialize
-    @version = `git describe --tags --abbrev=0`.strip
-    @tag_pushed = nil
-    @loading = true
-    @pid = Process.spawn(
-      "git ls-remote --tags origin | grep -q '#{@version}' " \
-      "&& echo true > #{CACHE_FILE} || echo false > #{CACHE_FILE}"
-    )
-  end
-
-  def loading?
-    return false unless @loading
-
-    _pid, status = Process.waitpid2(@pid, Process::WNOHANG)
-    if status
-      @tag_pushed = File.read(CACHE_FILE).strip == "true"
-      @loading = false
-    end
-    @loading
-  end
-
-  def refresh
-    # Sync version for manual refresh (user presses 'r')
-    @loading = true
-    remote_tags = `git ls-remote --tags origin`.strip
-    @tag_pushed = remote_tags.include?(@version)
-    @loading = false
-  end
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-The TUI starts instantly. The tag check runs in the background. The checklist updates when the result arrives.