ratatui_ruby 1.1.0 → 1.1.1

data/doc/index.md

@@ -1,34 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-# Start Here
-
-
-## Documentation for Users
-
-- [README](../README.md): Project overview and installation
-
-### Getting Started
-
-- [Why RatatuiRuby?](./getting_started/why.md): Philosophy, comparisons, and what makes us different
-- [Quickstart](./getting_started/quickstart.md): Build your first TUI app
-
-### Concepts
-
-- [Application Architecture](./concepts/application_architecture.md): Lifecycle patterns and API choices
-- [Event Handling](./concepts/event_handling.md): Keyboard, mouse, and terminal events
-- [Interactive Design](./concepts/interactive_design.md): Cached layout pattern for hit testing
-- [Testing Your Application](./concepts/application_testing.md): Snapshot testing and style assertions
-- [Custom Widgets](./concepts/custom_widgets.md): Build anything with the Draw API
-- [Async Operations](./concepts/async.md): Background tasks and non-blocking I/O
-
-### Troubleshooting
-
-- [Debugging](./concepts/debugging.md): Debugging techniques and tools
-- [Terminal Limitations](./troubleshooting/terminal_limitations.md): Platform quirks and workarounds
-
-## Documentation for Contributors
-
-- [Contributing Guidelines](https://man.sr.ht/~kerrick/ratatui_ruby/contributing.md): How to contribute patches and features
-- [More Documentation for Contributors](./contributors/index.md): Internal design docs and style guides

data/doc/troubleshooting/async.md

@@ -1,4 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->

data/doc/troubleshooting/terminal_limitations.md

@@ -1,131 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Terminal Limitations
-
-Some behaviors are outside the control of `ratatui_ruby`. This document explains common pitfalls that affect your application or your users, but cannot be fixed in the library.
-
-## Keyboard Event Interception
-
-### The Problem
-
-Your application receives a key event, but the modifier flags are missing. You pressed Ctrl+PageUp, but the event shows `code="page_up"` with `modifiers=[]`.
-
-### The Cause
-
-Terminal emulators intercept certain key combinations for their own features. The key press never reaches your application—the terminal consumes it first.
-
-Common culprits on macOS:
-
-| Key Combination      | Terminal Behavior                    |
-|---------------------|--------------------------------------|
-| Ctrl+PageUp/Down    | Switch tabs (Terminal.app, iTerm2)   |
-| Ctrl+Tab            | Switch tabs                          |
-| Cmd+T / Cmd+N       | New tab / New window                 |
-| Cmd+C / Cmd+V       | Copy / Paste (not Ctrl)              |
-
-Linux terminals vary widely. Windows Terminal and ConEmu have their own defaults.
-
-### The Solution
-
-1. **Test with different terminals.** Kitty, WezTerm, and Alacritty pass more key combinations through to applications by default. If a key works in Kitty but not Terminal.app, the terminal is the issue.
-
-2. **Reconfigure your terminal.** Most terminal emulators let you unbind or remap default shortcuts in their settings.
-
-3. **Use alternative key bindings.** If your users will run your application in various terminals, design your keybindings to avoid commonly intercepted combinations:
-   - Use Alt+PageUp instead of Ctrl+PageUp
-   - Use Ctrl+J/K instead of Ctrl+Up/Down
-   - Avoid Ctrl+Tab entirely
-
-4. **Document requirements.** If your application depends on specific key combinations, document the terminal requirements for your users.
-
-### Enhanced Keyboard Protocol
-
-Some terminals support the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/), which provides unambiguous key event reporting including:
-
-- Individual modifier key events (LeftShift vs RightShift)
-- Media keys (Play, Pause, Volume controls)
-- Repeat and release events
-
-Terminals with full protocol support:
-- Kitty
-- WezTerm
-- Foot
-- Alacritty (partial)
-
-Standard terminals (Terminal.app, iTerm2, GNOME Terminal) do not support the enhanced protocol.
-
-**RatatuiRuby Status:** The underlying library (crossterm) supports this protocol, but RatatuiRuby does not yet expose a way to enable it. The key code mappings for media keys and individual modifier keys exist, but they will only be received from terminals that enable the protocol by default. This is planned for a future release.
-
-## Mouse Event Limitations
-
-### The Problem
-
-Mouse events work in some terminals but not others. Or they work, but only up to certain coordinates.
-
-### The Cause
-
-Mouse reporting requires terminal escape sequence support. Older terminals may not support:
-
-- SGR mouse mode (coordinates > 223)
-- Mouse motion tracking
-- Button-event tracking
-
-### The Solution
-
-Ensure your terminal supports modern mouse modes. Most actively maintained terminals do. If running in a legacy environment, test mouse functionality and provide keyboard alternatives.
-
-## Focus Events
-
-### The Problem
-
-`Event::FocusGained` and `Event::FocusLost` are never received.
-
-### The Cause
-
-Focus event reporting requires explicit terminal support and configuration. Some terminals don't support it at all.
-
-### The Solution
-
-Don't rely on focus events for critical functionality. Treat them as nice-to-have enhancements. If your application shows stale data when the user returns, periodically refresh instead of waiting for focus events.
-
-## Process Termination
-
-### The Problem
-
-Your TUI app is terminated by `kill -9` or the [OOM killer](https://en.wikipedia.org/wiki/Out_of_memory#Out_of_memory_management). The terminal stays in raw mode. The user's cursor vanishes. Input echoes weirdly. Their shell is unusable.
-
-### The Cause
-
-SIGKILL (`kill -9`) terminates processes immediately. No cleanup code runs. The terminal never receives the escape sequences to restore normal mode.
-
-This also happens when:
-- The system OOM killer terminates your process
-- A parent process force-kills your app
-- A debugger disconnects ungracefully
-
-### The Solution
-
-There's no way to catch SIGKILL. You can only mitigate the impact.
-
-**Tell your users how to recover.** In your README or troubleshooting docs, explain: if the terminal breaks, type `reset` and press Enter. The characters won't echo, but the command runs.
-
-**Script graceful shutdowns.** If you write deployment or process management scripts, prefer graceful signals with a timeout before SIGKILL:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-# Graceful first, force if needed
-kill -15 $PID
-sleep 2
-kill -0 $PID 2>/dev/null && kill -9 $PID
-```
-<!-- SPDX-SnippetEnd -->
-
-See [Application Architecture: Signal Handling](../concepts/application_architecture.md#signal-handling) for programmatic cleanup strategies.
-

data/doc/troubleshooting/tui_output.md

@@ -1,197 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Terminal Output During TUI Sessions
-
-## The Problem
-
-Writing to stdout or stderr during a TUI session **corrupts the display**.
-
-When your application is running inside `RatatuiRuby.run`, the terminal is in "raw mode" and RatatuiRuby has taken control of the display buffer. Any output via `puts`, `warn`, `p`, `print`, or direct writes to `$stdout`/`$stderr` will:
-
-1. **Corrupt the screen layout** - Characters appear in random positions
-2. **Mix with TUI output** - Text interleaves with your widgets unpredictably
-3. **Trigger escape sequence errors** - Partial ANSI codes can break rendering
-
-## Why This Happens
-
-In raw mode:
-- The terminal doesn't process newlines or carriage returns normally
-- Output bypasses the TUI's controlled buffer
-- Cursor position is undefined from the TUI's perspective
-
-## Safe Patterns
-
-### Use `guard_io` to swallow output from gems
-
-If you're using a gem that might write to stdout/stderr, wrap its calls:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-RatatuiRuby.run do |tui|
-  RatatuiRuby.guard_io do
-    SomeChattyGem.do_something  # Any puts/warn calls are swallowed
-  end
-
-  # Outside guard_io, you can still debug intentionally:
-  # Object::STDERR.puts "debug: something"  # Escape hatch (corrupts display!)
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-### Defer output until after the TUI exits
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-messages = []
-
-RatatuiRuby.run do |tui|
-  # Collect messages instead of printing them
-  messages << "Something happened"
-  
-  # ... TUI logic ...
-end
-
-# Now safe to print
-messages.each { |msg| puts msg }
-```
-<!-- SPDX-SnippetEnd -->
-
-### Use Logger to write to a file
-
-The `Logger` class from Ruby's standard library is the idiomatic solution:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-require "logger"
-require "tmpdir"
-
-LOG = Logger.new(File.join(Dir.tmpdir, "my_app.log"))
-LOG.level = Logger::DEBUG
-
-RatatuiRuby.run do |tui|
-  LOG.info "Application started"
-  LOG.debug "Processing event: #{event.inspect}"
-
-  # ... TUI logic ...
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-### Display messages in the TUI itself
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-RatatuiRuby.run do |tui|
-  @status_message = "Something happened"
-  
-  tui.draw do |frame|
-    # Show status in the UI
-    frame.render_widget(
-      tui.paragraph(text: @status_message),
-      status_area
-    )
-  end
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-## Library Behavior
-
-RatatuiRuby automatically defers its own warnings (like experimental feature notices) during TUI sessions. They are queued and printed after `restore_terminal` is called.
-
-You don't need to do anything special for library warnings—they're handled automatically.
-
-## Bypassing guard_io
-
-If you need to write to stdout/stderr even when `guard_io` is active (e.g., for [pipeline integration](#headless-mode-batchpipelinecli) or IPC), use the original IO constants:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-RatatuiRuby.guard_io do
-  SomeChattyGem.do_something  # This is swallowed
-
-  # But this gets through:
-  Object::STDOUT.puts "structured output for downstream tools"
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-This works regardless of whether `guard_io` is active. During a TUI session, the display will be corrupted—but the output will reach its destination.
-
-## Headless Mode (Batch/Pipeline/CLI)
-
-If your app supports both TUI and non-TUI modes (e.g., `my_app --no-tui`), call `headless!` at startup to silence `guard_io` warnings:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-if ARGV.include?("--no-tui")
-  RatatuiRuby.headless!
-  # guard_io calls are now silent no-ops
-  process_batch_work
-else
-  RatatuiRuby.run do |tui|
-    # TUI mode - guard_io works normally
-  end
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-When headless, `guard_io` becomes a no-op (output flows normally), and calling `run` or `init_terminal` raises an error.
-
-## Temporarily Exiting TUI Mode
-
-Some apps need to temporarily leave TUI mode for user interaction—like lazygit does when opening an external editor for commit messages. Use `restore_terminal` and `init_terminal`:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-RatatuiRuby.run do |tui|
-  # ... TUI is active ...
-  
-  if user_wants_external_editor
-    RatatuiRuby.restore_terminal
-    
-    # Now in normal terminal mode
-    system("$EDITOR", filename)
-    puts "Press Enter to return to the TUI..."
-    gets
-    
-    RatatuiRuby.init_terminal
-  end
-  
-  # ... TUI is active again ...
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-This pattern lets you hand control back to the user or spawn external processes that need normal terminal access.

data/examples/app_all_events/README.md

@@ -1,114 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# App All Events Example
-
-[![App All Events](../../doc/images/app_all_events.png)](app.rb)
-
-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.
-
-## Architecture: Model-View-Update
-
-This application demonstrates **unidirectional data flow** inspired by The Elm Architecture. This separation ensures that state management is predictable and easy to test.
-
-### 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
-
-State changes use `.with(...)` to return a new Model instance.
-
-### 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. Update (`update.rb`)
-A **pure function** that computes the next state:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-Update.call(msg, model) -> Model
-```
-<!-- SPDX-SnippetEnd -->
-
-All logic previously in `Events.record` now lives here. The function never mutates, never draws, never performs IO.
-
-### 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:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```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
-```
-<!-- SPDX-SnippetEnd -->
-
-## Library Features Showcased
-
-Reading this code will teach you how to:
-
-*   **Handle All Events**:
-    *   **Keyboard**: Capture normal keys and modifiers (`Ctrl+c`, `q`).
-    *   **Mouse**: track clicks, drags, and scroll events.
-    *   **Focus**: React to the terminal window gaining or losing focus (`FocusGained`/`FocusLost`).
-    *   **Resize**: Dynamically adapt layouts when the terminal size changes.
-    *   **Paste**: Handle bracketed paste events (if supported by the terminal).
-*   **Layouts**: Use `tui.layout_split` with constraints (`Length`, `Fill`) to create complex, responsive dashboards.
-*   **Styling**: Apply dynamic styles (bold, colors) based on application state.
-*   **Structure**: Organize a non-trivial CLI tool into small, single-purpose classes.
-
-## What Problems Does This Solve?
-
-### "What key code is my terminal sending?"
-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 using immutable state and pure functions, it solves the problem of "where does my state live and how does it change?"
-
-### "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
-
-Complex applications require structured state habits. `AppAllEvents` and the [Color Picker](../app_color_picker/README.md) demonstrate two different approaches.
-
-### The Dashboard Approach (AppAllEvents)
-
-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. Each UI component needs to know where it exists on screen for hit testing.
-
-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.
-
-[Read the source code →](app.rb)

data/examples/app_all_events/app.rb

@@ -1,98 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
-#++
-
-$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
-$LOAD_PATH.unshift File.expand_path(__dir__)
-
-require "ratatui_ruby"
-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.
-#
-# Developers need a comprehensive example to understand how keys, mouse, resize, and focus events behave.
-# Testing event handling across different terminal emulators and platforms can be unpredictable.
-#
-# This application captures and logs every event received from the backend, providing real-time feedback and history.
-#
-# 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:
-#   # ruby examples/app_all_events/app.rb
-#
-#   app = AppAllEvents.new
-#   app.run
-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 view.
-  def initialize
-    @view = View::App.new
-  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|
-      model = AppModel.initial
-
-      loop do
-        tui.draw { |frame| @view.call(model, tui, frame, frame.area) }
-
-        event = tui.poll_event
-        msg = map_event_to_msg(event, model)
-        break if msg.is_a?(Msg::Quit)
-
-        model = Update.call(msg, model)
-      end
-    end
-  end
-
-  private def map_event_to_msg(event, model)
-    case event
-    when RatatuiRuby::Event::Key
-      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
-      Msg::Resize.new(width: event.width, height: event.height, previous_size: model.window_size)
-    when RatatuiRuby::Event::FocusGained
-      Msg::Focus.new(gained: true)
-    when RatatuiRuby::Event::FocusLost
-      Msg::Focus.new(gained: false)
-    when RatatuiRuby::Event::None
-      Msg::NoneEvent.new
-    else
-      Msg::Input.new(event:)
-    end
-  end
-end
-
-AppAllEvents.new.run if __FILE__ == $PROGRAM_NAME