ratatui_ruby 1.0.0 → 1.0.1

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

data/examples/app_all_events/model/app_model.rb

@@ -1,159 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
-#++
-
-require_relative "timestamp"
-require_relative "event_entry"
-require_relative "event_color_cycle"
-
-# Immutable application state for the Model-View-Update architecture.
-#
-# The Elm Architecture requires a single immutable Model. State changes return
-# a new Model instance. This consolidates all app state into one place.
-#
-# Use `AppModel.initial` to create the starting state, and `model.with(...)`
-# to create updated states.
-#
-# === Attributes
-#
-# [entries] Array of EventEntry objects (event log)
-# [focused] Boolean window focus state
-# [window_size] Array [width, height] of terminal dimensions
-# [lit_types] Hash mapping event types to Timestamp (for highlight expiry)
-# [none_count] Integer count of :none events (not logged)
-# [color_cycle_index] Integer index into EventColorCycle::COLORS
-#
-# === Example
-#
-#   model = AppModel.initial
-#   model.count(:key)  #=> 0
-#   model.focused      #=> true
-class AppModel < Data.define(:entries, :focused, :window_size, :lit_types, :none_count, :color_cycle_index)
-  # Highlight duration in milliseconds.
-  HIGHLIGHT_DURATION_MS = 300
-
-  # Creates the initial application state.
-  #
-  # === Example
-  #
-  #   AppModel.initial #=> #<data AppModel entries=[] focused=true ...>
-  def self.initial
-    new(
-      entries: [],
-      focused: true,
-      window_size: [80, 24],
-      lit_types: {},
-      none_count: 0,
-      color_cycle_index: 0
-    )
-  end
-
-  # Returns the count of events for a given type.
-  #
-  # [type] Symbol event type (:key, :mouse, :resize, :paste, :focus, :none)
-  #
-  # === Example
-  #
-  #   model.count(:key) #=> 5
-  def count(type)
-    return none_count if type == :none
-
-    entries.count { |e| e.matches_type?(type) }
-  end
-
-  # Returns counts grouped by subtype (kind or modifier status).
-  #
-  # [type] Symbol event type.
-  #
-  # === Example
-  #
-  #   model.sub_counts(:mouse) #=> { "down" => 1, "up" => 2 }
-  def sub_counts(type)
-    return {} if type == :none
-
-    matching = entries.select { |e| e.matches_type?(type) }
-    defaults = {
-      key: %w[standard function media system modifier],
-      focus: %w[gained lost],
-      mouse: %w[down up drag moved scroll_up scroll_down],
-    }
-
-    matching.each_with_object(defaults.fetch(type, []).to_h { |k| [k, 0] }) do |entry, counts|
-      group = subtype_for(entry, type)
-      counts[group] += 1 if group
-    end
-  end
-
-  # Checks if an event type should be highlighted.
-  #
-  # [type] Symbol event type.
-  #
-  # === Example
-  #
-  #   model.lit?(:key) #=> true
-  def lit?(type)
-    timestamp = lit_types[type]
-    return false unless timestamp
-
-    !timestamp.elapsed?(HIGHLIGHT_DURATION_MS)
-  end
-
-  # Returns the most recent entries up to the given limit.
-  #
-  # [max_entries] Integer maximum number of entries to return.
-  #
-  # === Example
-  #
-  #   model.visible(10) #=> [#<EventEntry ...>, ...]
-  def visible(max_entries)
-    entries.last(max_entries)
-  end
-
-  # Checks if any events have been recorded.
-  #
-  # === Example
-  #
-  #   model.empty? #=> true
-  def empty?
-    entries.empty?
-  end
-
-  # Returns the most recent live event data for a type.
-  #
-  # [type] Symbol event type.
-  #
-  # === Example
-  #
-  #   model.live_event(:key) #=> { time: Time, description: "..." }
-  def live_event(type)
-    entry = entries.reverse.find { |e| e.live_type == type }
-    return nil unless entry
-
-    { time: Time.at(entry.timestamp.milliseconds / 1000.0), description: entry.description }
-  end
-
-  # Returns the next color in the cycle for a new event.
-  #
-  # === Example
-  #
-  #   model.next_color #=> :cyan
-  def next_color
-    EventColorCycle::COLORS[color_cycle_index]
-  end
-
-  private def subtype_for(entry, type)
-    case type
-    when :key
-      # Key events: group by category kind (standard/function/media/modifier/system)
-      entry.event.kind.to_s if entry.event.respond_to?(:kind)
-    when :mouse
-      # Mouse events: group by event kind (down/up/drag/moved/scroll_up/scroll_down)
-      entry.event.kind.to_s if entry.event.respond_to?(:kind)
-    when :focus
-      entry.type.to_s.sub("focus_", "")
-    end
-  end
-end

data/examples/app_all_events/model/event_color_cycle.rb

@@ -1,43 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
-#++
-
-# Cycles through a set of colors for event logging.
-#
-# Sequential events in a log are hard to distinguish if they all look the same.
-# Manually assigning colors to every event type or entry is repetitive.
-#
-# This class automatically cycles through a predefined list of vibrant colors.
-#
-# Use it to give each event in a log a distinct visual identity.
-#
-# === Examples
-#
-#   cycler = EventColorCycle.new
-#   cycler.next_color #=> :cyan
-#   cycler.next_color #=> :magenta
-#   cycler.next_color #=> :yellow
-#   cycler.next_color #=> :cyan
-class EventColorCycle
-  # List of colors to cycle through.
-  COLORS = %i[cyan magenta yellow].freeze
-
-  # Creates a new EventColorCycle.
-  def initialize
-    @index = 0
-  end
-
-  # Returns the next color in the cycle.
-  #
-  # === Example
-  #
-  #   cycler.next_color #=> :cyan
-  def next_color
-    color = COLORS[@index]
-    @index = (@index + 1) % COLORS.length
-    color
-  end
-end

data/examples/app_all_events/model/event_entry.rb

@@ -1,94 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
-#++
-
-require_relative "timestamp"
-require "ratatui_ruby"
-
-# Stores details about a single event in the history log.
-#
-# Event logs need to store diverse data including types, keys, colors, and timestamps.
-# Managing loose hashes or arrays for event history is error-prone and hard to query.
-#
-# This class provides a structured data object for every recorded event.
-#
-# Use it to represent mouse clicks, key presses, or resize events in a log.
-#
-# === Examples
-#
-#   # Typically created via Events.record
-#   entry = EventEntry.create(key_event, :cyan, Timestamp.now)
-#   puts entry.type #=> :key
-#   puts entry.description #=> '#<RatatuiRuby::Event::Key ...>'
-class EventEntry < Data.define(:event, :color, :timestamp)
-  # Creates a new EventEntry.
-  #
-  # [event] RatatuiRuby::Event object.
-  # [color] Symbol color for the log display.
-  # [timestamp] Timestamp of when the event occurred.
-  def self.create(event, color, timestamp)
-    new(
-      event:,
-      color:,
-      timestamp:
-    )
-  end
-
-  # Returns the event type.
-  #
-  # === Example
-  #
-  #   entry.type #=> :key
-  def type
-    case event
-    when RatatuiRuby::Event::Key then :key
-    when RatatuiRuby::Event::Mouse then :mouse
-    when RatatuiRuby::Event::Resize then :resize
-    when RatatuiRuby::Event::Paste then :paste
-    when RatatuiRuby::Event::FocusGained then :focus_gained
-    when RatatuiRuby::Event::FocusLost then :focus_lost
-    else :unknown
-    end
-  end
-
-  # Returns the event description using inspect.
-  #
-  # === Example
-  #
-  #   entry.description #=> '#<RatatuiRuby::Event::Key code="a" modifiers=[]>'
-  def description
-    event.inspect
-  end
-
-  # Checks if the entry matches the given type.
-  #
-  # [check_type] Symbol type to check against.
-  #
-  # === Example
-  #
-  #   entry.matches_type?(:key) #=> true
-  def matches_type?(check_type)
-    return true if check_type == :focus && (type == :focus_gained || type == :focus_lost)
-
-    type == check_type
-  end
-
-  # Returns the display type for live event grouping.
-  #
-  # Normalizes focus_gained and focus_lost to :focus.
-  #
-  # === Example
-  #
-  #   entry.live_type #=> :focus
-  def live_type
-    case type
-    when :focus_gained, :focus_lost
-      :focus
-    else
-      type
-    end
-  end
-end