ratatui_ruby 0.7.4 → 0.9.0

data/doc/troubleshooting/tui_output.md

@@ -9,7 +9,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 
 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:
+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
@@ -24,8 +24,34 @@ In raw mode:
 
 ## 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 = []
 
@@ -39,22 +65,40 @@ end
 # Now safe to print
 messages.each { |msg| puts msg }
 ```
+<!-- SPDX-SnippetEnd -->
+
+### Use Logger to write to a file
 
-### Use debug logging 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
-DEBUG_LOG = File.open("/tmp/my_app_debug.log", "a")
+require "logger"
+require "tmpdir"
+
+LOG = Logger.new(File.join(Dir.tmpdir, "my_app.log"))
+LOG.level = Logger::DEBUG
 
 RatatuiRuby.run do |tui|
-  DEBUG_LOG.puts "Debug: something happened"
-  DEBUG_LOG.flush
-  
+  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"
@@ -68,9 +112,86 @@ RatatuiRuby.run do |tui|
   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,6 +1,6 @@
 <!--
-SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
 # App All Events Example
@@ -33,9 +33,15 @@ Semantic value objects that decouple raw terminal events from business logic:
 ### 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.
 
@@ -47,6 +53,11 @@ Pure rendering logic. Views accept the immutable `AppModel` and draw to the scre
 ### 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) }
@@ -55,6 +66,7 @@ loop do
   model = Update.call(msg, model)
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 ## Library Features Showcased
 

data/examples/app_all_events/app.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_all_events/model/app_model.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_all_events/model/event_color_cycle.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_all_events/model/event_entry.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_all_events/model/msg.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_all_events/model/timestamp.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_all_events/update.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_all_events/view/app_view.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_all_events/view/controls_view.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_all_events/view/counts_view.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_all_events/view/live_view.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_all_events/view/log_view.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_all_events/view.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_color_picker/README.md

@@ -1,6 +1,6 @@
 <!--
-SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
 # Color Picker Example
@@ -23,6 +23,11 @@ This app uses a **Strict Component-Based Architecture** where every UI element e
 
 Every component implements this duck-type interface:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 # Renders the component into the given area
 # Caches `area` for hit testing
@@ -40,6 +45,7 @@ end
 def tick
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 ### 1. The MainContainer (Orchestrator)
 
@@ -85,6 +91,11 @@ Components return semantic symbols instead of just `:consumed`:
 
 The `MainContainer` interprets these signals to coordinate cross-component communication:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 result = @input.handle_event(event)
 case result
@@ -93,6 +104,7 @@ when :submitted
   return :consumed
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 ### ⏱️ Lifecycle Hooks (`tick`)
 
@@ -109,9 +121,15 @@ Read this example if you are trying to solve:
 
 ## Usage
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```bash
 ruby examples/app_color_picker/app.rb
 ```
+<!-- SPDX-SnippetEnd -->
 
 -   Type a hex code (e.g., `#FF0055`) or color name (`cyan`).
 -   Press `Enter` to generate the palette.

data/examples/app_color_picker/app.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_color_picker/clipboard.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_color_picker/color.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_color_picker/controls.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_color_picker/copy_dialog.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_color_picker/export_pane.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_color_picker/harmony.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_color_picker/input.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_color_picker/main_container.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_color_picker/palette.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_login_form/README.md

@@ -1,6 +1,6 @@
 <!--
-SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
 # Login Form Example
@@ -36,9 +36,15 @@ This example solves this by using the `Overlay` widget to stack a centered popup
 
 ## Usage
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```bash
 ruby examples/app_login_form/app.rb
 ```
+<!-- SPDX-SnippetEnd -->
 
 ## Learning Outcomes
 

data/examples/app_login_form/app.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_stateful_interaction/README.md

@@ -1,6 +1,6 @@
 <!--
-SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
 # Stateful Interaction Example