ratatui_ruby 0.7.1 → 0.7.2

data/doc/index.md

@@ -2,20 +2,34 @@
   SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
   SPDX-License-Identifier: CC-BY-SA-4.0
 -->
-# **ratatui_ruby** Documentation
+# Start Here
 
 
 ## Documentation for Users
 
 - [README](../README.md): Project overview and installation
-- [Why RatatuiRuby?](./why.md): Philosophy, comparisons, and what makes us different
-- [Quickstart](./quickstart.md): Build your first TUI app
-- [Application Architecture](./application_architecture.md): Lifecycle patterns and API choices
-- [Event Handling](./event_handling.md): Keyboard, mouse, and terminal events
-- [Interactive Design](./interactive_design.md): Cached layout pattern for hit testing
-- [Terminal Limitations](./terminal_limitations.md): Platform quirks and workarounds
-- [Testing Your Application](./application_testing.md): Snapshot testing and style assertions
-- [Migrating to v0.7.0](./v0.7.0_migration.md): Namespace changes and upgrade guide
+
+### 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
+- [Async Operations](./concepts/async.md): Background tasks and non-blocking I/O
+
+### Troubleshooting
+
+- [Debugging](./troubleshooting/debugging.md): Debugging techniques and tools
+- [Terminal Limitations](./troubleshooting/terminal_limitations.md): Platform quirks and workarounds
+
+### Migration
+
+- [Migrating to v0.7.0](./migration/v0_7_0.md): Namespace changes and upgrade guide
 
 
 ## Documentation for Contributors

data/doc/{terminal_limitations.md → troubleshooting/terminal_limitations.md}

@@ -90,3 +90,36 @@ Focus event reporting requires explicit terminal support and configuration. Some
 ### 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:
+
+```bash
+# Graceful first, force if needed
+kill -15 $PID
+sleep 2
+kill -0 $PID 2>/dev/null && kill -9 $PID
+```
+
+See [Application Architecture: Signal Handling](../concepts/application_architecture.md#signal-handling) for programmatic cleanup strategies.
+

data/examples/app_all_events/README.md

@@ -99,3 +99,4 @@ The Color Picker uses a Component-Based pattern. Each component encapsulates its
 
 Use this pattern for forms, editors, and mouse-driven tools.
 
+[Read the source code →](app.rb)

data/examples/app_all_events/app.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 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__)

data/examples/app_all_events/model/app_model.rb

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

data/examples/app_all_events/model/event_color_cycle.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 # Cycles through a set of colors for event logging.
 #

data/examples/app_all_events/model/event_entry.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 require_relative "timestamp"
 require "ratatui_ruby"

data/examples/app_all_events/model/msg.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 # Semantic message types for the Model-View-Update architecture.
 #

data/examples/app_all_events/model/timestamp.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 # Represents a high-resolution point in time.
 #

data/examples/app_all_events/update.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 require_relative "model/app_model"
 require_relative "model/msg"

data/examples/app_all_events/view/app_view.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 require_relative "../view"
 require_relative "counts_view"

data/examples/app_all_events/view/controls_view.rb

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

data/examples/app_all_events/view/counts_view.rb

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

data/examples/app_all_events/view/live_view.rb

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

data/examples/app_all_events/view/log_view.rb

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

data/examples/app_all_events/view.rb

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

data/examples/app_color_picker/README.md

@@ -134,3 +134,5 @@ Use this pattern for forms, editors, and mouse-driven tools.
 Dashboards display data. They rarely require complex mouse interaction. Model-View-Update works best there. State is immutable. Logic is pure. Updates are predictable. This simplifies testing.
 
 Use that pattern for logs, monitors, and data viewers.
+
+[Read the source code →](app.rb)

data/examples/app_color_picker/app.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 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__)

data/examples/app_color_picker/clipboard.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 # Manages system clipboard interaction with transient feedback.
 #

data/examples/app_color_picker/color.rb

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

data/examples/app_color_picker/controls.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 # A display-only component showing keyboard shortcuts and clipboard feedback.
 #

data/examples/app_color_picker/copy_dialog.rb

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

data/examples/app_color_picker/export_pane.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 # A self-contained component displaying export formats for a color.
 #

data/examples/app_color_picker/harmony.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 # A single color variant with label and styling information.
 #

data/examples/app_color_picker/input.rb

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

data/examples/app_color_picker/main_container.rb

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

data/examples/app_color_picker/palette.rb

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

data/examples/app_login_form/README.md

@@ -43,7 +43,10 @@ ruby examples/app_login_form/app.rb
 ## Learning Outcomes
 
 Use this example if you need to...
+
 - Create a modal dialog or popup.
 - Center a widget on the screen (vertically and horizontally).
 - Implement a simple text input field with cursor management.
 - layer widgets using the `Overlay` widget.
+
+[Read the source code →](app.rb)

data/examples/app_login_form/app.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 require "ratatui_ruby"

data/examples/app_stateful_interaction/README.md

@@ -31,3 +31,5 @@ In `ratatui_ruby`'s Stateful Rendering:
 | `Tab` / `←` / `→` | Switch active pane (List vs Table) |
 | `Mouse Click` | Select the clicked row (Works with scrolling!) |
 | `q` | Quit |
+
+[Read the source code →](app.rb)

data/examples/app_stateful_interaction/app.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 require "ratatui_ruby"

data/examples/timeout_demo.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 # Timeout Demo: Non-Blocking Event Polling
 #

data/examples/verify_quickstart_dsl/README.md

@@ -5,7 +5,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 
 # Quickstart DSL Verification
 
-Verifies the "Simplified API" tutorial in the [Quickstart](../../doc/quickstart.md#simplified-api).
+Verifies the "Simplified API" tutorial in the [Quickstart](../../doc/getting_started/quickstart.md#simplified-api).
 
 This example exists as a documentation regression test. It ensures the recommended TUI facade and managed lifecycle workflow remains functional.
 
@@ -46,4 +46,4 @@ end
 ```
 <!-- SYNC:END -->
 
-[![verify_quickstart_dsl](../../doc/images/verify_quickstart_dsl.png)](../../doc/quickstart.md#simplified-api)
+[![verify_quickstart_dsl](../../doc/images/verify_quickstart_dsl.png)](../../doc/getting_started/quickstart.md#simplified-api)

data/examples/verify_quickstart_dsl/app.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 

data/examples/verify_quickstart_layout/README.md

@@ -5,7 +5,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 
 # Quickstart Layout Verification
 
-Verifies the "Adding Layouts" tutorial in the [Quickstart](../../doc/quickstart.md#adding-layouts).
+Verifies the "Adding Layouts" tutorial in the [Quickstart](../../doc/getting_started/quickstart.md#adding-layouts).
 
 This example exists as a documentation regression test. It ensures the layout and constraints examples remain functional.
 
@@ -68,4 +68,4 @@ end
 ```
 <!-- SYNC:END -->
 
-[![verify_quickstart_layout](../../doc/images/verify_quickstart_layout.png)](../../doc/quickstart.md#adding-layouts)
+[![verify_quickstart_layout](../../doc/images/verify_quickstart_layout.png)](../../doc/getting_started/quickstart.md#adding-layouts)

data/examples/verify_quickstart_layout/app.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 

data/examples/verify_quickstart_lifecycle/README.md

@@ -5,7 +5,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 
 # Quickstart Lifecycle Verification
 
-Verifies the "Basic Application" tutorial in the [Quickstart](../../doc/quickstart.md#basic-application).
+Verifies the "Basic Application" tutorial in the [Quickstart](../../doc/getting_started/quickstart.md#basic-application).
 
 This example exists as a documentation regression test. It ensures the core lifecycle example presented to new users remains functional.
 
@@ -53,4 +53,4 @@ end
 ```
 <!-- SYNC:END -->
 
-[![verify_quickstart_lifecycle](../../doc/images/verify_quickstart_lifecycle.png)](../../doc/quickstart.md#basic-application)
+[![verify_quickstart_lifecycle](../../doc/images/verify_quickstart_lifecycle.png)](../../doc/getting_started/quickstart.md#basic-application)

data/examples/verify_quickstart_lifecycle/app.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 

data/examples/verify_readme_usage/app.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 

data/examples/{widget_barchart_demo → widget_barchart}/README.md

@@ -3,9 +3,9 @@ SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
-# BarChart Widget Example
+# BarChart (Bar, BarGroup) Example
 
-[![BarChart Demo](../../doc/images/widget_barchart_demo.png)](app.rb)
+[![
](../../doc/images/widget_barchart.png)](app.rb)
 
 Visualizes categorical data with interactive attribute cycling.
 
@@ -38,13 +38,15 @@ Comparing magnitudes in raw tables requires mental arithmetic. Bar charts make t
 ## Usage
 
 ```bash
-ruby examples/widget_barchart_demo/app.rb
+ruby examples/widget_barchart/app.rb
 ```
 
 ## Learning Outcomes
 
 Use this example if you need to...
+
 - Visualize categorical data (e.g., sales by quarter, CPU usage by core).
 - Create "stats" dashboards with compact visualizations.
 - Understand how `RatatuiRuby::BarChart` handles different data structures.
 
+[Read the source code →](app.rb)

data/examples/{widget_barchart_demo → widget_barchart}/app.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 require "ratatui_ruby"
@@ -18,10 +20,10 @@ require "ratatui_ruby"
 #
 # Run the demo from the terminal:
 #
-#   ruby examples/widget_barchart_demo/app.rb
+#   ruby examples/widget_barchart/app.rb
 #
-# rdoc-image:/doc/images/widget_barchart_demo.png
-class WidgetBarchartDemo
+# rdoc-image:/doc/images/widget_barchart.png
+class WidgetBarchart
   def initialize
     @data_index = 2
     @styles = nil # Initialized in run
@@ -149,7 +151,7 @@ class WidgetBarchartDemo
         value_style: @styles[@value_style_index][:style],
         bar_set: @bar_sets[@bar_set_index][:set],
         block: @tui.block(
-          title: "BarChart Demo: #{data_name}",
+          title: "BarChart: #{data_name}",
           borders: [:all]
         )
       )
@@ -235,4 +237,4 @@ class WidgetBarchartDemo
   end
 end
 
-WidgetBarchartDemo.new.run if __FILE__ == $0
+WidgetBarchart.new.run if __FILE__ == $0

data/examples/{widget_block_demo → widget_block}/README.md

@@ -2,9 +2,9 @@
   SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
   SPDX-License-Identifier: CC-BY-SA-4.0
 -->
-# Block Widget Demo
+# Block Example
 
-[![Block Demo](../../doc/images/widget_block_demo.png)](app.rb)
+[![
](../../doc/images/widget_block.png)](app.rb)
 
 This example demonstrates the versatile `Block` widget, which provides the visual container, borders, and titles for almost every other widget in `ratatui_ruby`.
 
@@ -32,5 +32,7 @@ This example demonstrates the versatile `Block` widget, which provides the visua
 ## Usage
 
 ```bash
-ruby examples/widget_block_demo/app.rb
+ruby examples/widget_block/app.rb
 ```
+
+[Read the source code →](app.rb)

data/examples/{widget_block_demo → widget_block}/app.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 require "ratatui_ruby"
@@ -16,10 +18,10 @@ require "ratatui_ruby"
 #
 # Run the demo from the terminal:
 #
-#   ruby examples/widget_block_demo/app.rb
+#   ruby examples/widget_block/app.rb
 #
-# rdoc-image:/doc/images/widget_block_demo.png
-class WidgetBlockDemo
+# rdoc-image:/doc/images/widget_block.png
+class WidgetBlock
   def initialize
     @title_configs = [
       { name: "None", title: nil },
@@ -253,4 +255,4 @@ set: {
   end
 end
 
-WidgetBlockDemo.new.run if __FILE__ == $PROGRAM_NAME
+WidgetBlock.new.run if __FILE__ == $PROGRAM_NAME

data/examples/{widget_box_demo → widget_box}/README.md

@@ -3,9 +3,9 @@ SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
-# Box (Block) Widget Example
+# Block (Box) Example
 
-[![widget_box_demo](../../doc/images/widget_box_demo.png)](app.rb)
+[![widget_box](../../doc/images/widget_box.png)](app.rb)
 
 Demonstrates visual container attributes with interactive cycling.
 
@@ -33,13 +33,16 @@ Widgets often float in a void. Without boundaries, interfaces become a chaotic m
 ## Usage
 
 ```bash
-ruby examples/widget_box_demo/app.rb
+ruby examples/widget_box/app.rb
 ```
 
 ## Learning Outcomes
 
 Use this example if you need to...
+
 - Group related widgets together.
 - Create distinct "panels" or "cards" in your UI.
 - Style borders to indicate state (e.g., Red border for error state).
-- Understand the difference between `style` (content) and `border_style` (frame).
+- Understand the difference between `style` (content) and `border_style` (frame).
+
+[Read the source code →](app.rb)