ratatui_ruby 0.3.0 → 0.4.0

data/README.md

@@ -9,7 +9,7 @@ builds.sr.ht status](https://builds.sr.ht/~kerrick/ratatui_ruby.svg)](https://bu
 License](https://img.shields.io/badge/dynamic/regex?url=https%3A%2F%2Fgit.sr.ht%2F~kerrick%2Fratatui_ruby%2Fblob%2Fmain%2Fratatui_ruby.gemspec&search=spec%5C.license%20%3D%20%22(.*)%22&replace=%241&label=License&color=a2c93e)](https://spdx.org/licenses/AGPL-3.0-or-later.html) [![
 Gem Total Downloads](https://img.shields.io/gem/dt/ratatui_ruby)](https://rubygems.org/gems/ratatui_ruby) [![
 Gem Version](https://img.shields.io/gem/v/ratatui_ruby)](https://rubygems.org/gems/ratatui_ruby) [![
-Ratatui Version](https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fgit.sr.ht%2F~kerrick%2Fratatui_ruby%2Fblob%2Fmain%2Fext%2Fratatui_ruby%2FCargo.toml&query=%24.dependencies.ratatui.version&prefix=v&logo=ratatui&label=Ratatui)](https://crates.io/crates/ratatui/0.26.3) [![
+Ratatui Version](https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fgit.sr.ht%2F~kerrick%2Fratatui_ruby%2Fblob%2Fmain%2Fext%2Fratatui_ruby%2FCargo.toml&query=%24.dependencies.ratatui.version&prefix=v&logo=ratatui&label=Ratatui)](https://crates.io/crates/ratatui/0.30) [![
 Mailing List: Discussion](https://img.shields.io/badge/mailing_list-discussion-5865F2.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmZmZmYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBjbGFzcz0iaWNvbiBpY29uLXRhYmxlciBpY29ucy10YWJsZXItb3V0bGluZSBpY29uLXRhYmxlci1tYWlsIj48cGF0aCBzdHJva2U9Im5vbmUiIGQ9Ik0wIDBoMjR2MjRIMHoiIGZpbGw9Im5vbmUiLz48cGF0aCBkPSJNMyA3YTIgMiAwIDAgMSAyIC0yaDE0YTIgMiAwIDAgMSAyIDJ2MTBhMiAyIDAgMCAxIC0yIDJoLTE0YTIgMiAwIDAgMSAtMiAtMnYtMTB6IiAvPjxwYXRoIGQ9Ik0zIDdsOSA2bDkgLTYiIC8+PC9zdmc+Cg==)](https://lists.sr.ht/~kerrick/ratatui_ruby-discuss) [![
 Mailing List: Development](https://img.shields.io/badge/mailing_list-development-4954d5.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmZmZmYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBjbGFzcz0iaWNvbiBpY29uLXRhYmxlciBpY29ucy10YWJsZXItb3V0bGluZSBpY29uLXRhYmxlci1tYWlsIj48cGF0aCBzdHJva2U9Im5vbmUiIGQ9Ik0wIDBoMjR2MjRIMHoiIGZpbGw9Im5vbmUiLz48cGF0aCBkPSJNMyA3YTIgMiAwIDAgMSAyIC0yaDE0YTIgMiAwIDAgMSAyIDJ2MTBhMiAyIDAgMCAxIC0yIDJoLTE0YTIgMiAwIDAgMSAtMiAtMnYtMTB6IiAvPjxwYXRoIGQ9Ik0zIDdsOSA2bDkgLTYiIC8+PC9zdmc+Cg==)](https://lists.sr.ht/~kerrick/ratatui_ruby-devel) [![
 Mailing List: Announcements](https://img.shields.io/badge/mailing_list-announcements-3b44ac.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmZmZmYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBjbGFzcz0iaWNvbiBpY29uLXRhYmxlciBpY29ucy10YWJsZXItb3V0bGluZSBpY29uLXRhYmxlci1tYWlsIj48cGF0aCBzdHJva2U9Im5vbmUiIGQ9Ik0wIDBoMjR2MjRIMHoiIGZpbGw9Im5vbmUiLz48cGF0aCBkPSJNMyA3YTIgMiAwIDAgMSAyIC0yaDE0YTIgMiAwIDAgMSAyIDJ2MTBhMiAyIDAgMCAxIC0yIDJoLTE0YTIgMiAwIDAgMSAtMiAtMnYtMTB6IiAvPjxwYXRoIGQ9Ik0zIDdsOSA2bDkgLTYiIC8+PC9zdmc+Cg==)](https://lists.sr.ht/~kerrick/ratatui_ruby-announce)
@@ -21,7 +21,7 @@ Mailing List: Announcements](https://img.shields.io/badge/mailing_list-announcem
 **ratatui_ruby** is a community wrapper that is not affiliated with [the Ratatui team](https://github.com/orgs/ratatui/people).
 
 > [!WARNING]  
-> **ratatui_ruby** is currently in an early stage of development. Use at your own risk.
+> **ratatui_ruby** is currently in **BETA**. The API may change between minor versions.
 
 Please join the **announce** mailing list at https://lists.sr.ht/~kerrick/ratatui_ruby-announce to stay up-to-date on new releases and announcements.
 
@@ -34,8 +34,8 @@ Please join the **announce** mailing list at https://lists.sr.ht/~kerrick/ratatu
 - x86_64 (AMD, Intel) and ARM (Apple Silicon, Raspberry Pi).
 
 We support the latest minor version of every
-[non-eol Ruby version](https://www.ruby-lang.org/en/downloads/branches/).
-Support for Ruby 4 is coming soon.
+[non-eol Ruby version](https://www.ruby-lang.org/en/downloads/branches/),
+including Ruby 4.
 
 
 ## Installation
@@ -65,22 +65,24 @@ gem install ratatui_ruby
 
 ```ruby
 require "ratatui_ruby"
-RatatuiRuby.main_loop do |tui|
-  tui.draw \
-    tui.paragraph \
-        text: "Hello, Ratatui! Press 'q' to quit.",
-        align: :center,
-        block: tui.block(
-          title: "My Ruby TUI App",
-          borders: [:all],
-          border_color: "cyan"
-        )
-  event = tui.poll_event
-  break if event && event[:type] == :key && event[:code] == "q"
+RatatuiRuby.run do |tui|
+  loop do
+    tui.draw \
+      tui.paragraph \
+          text: "Hello, Ratatui! Press 'q' to quit.",
+          alignment: :center,
+          block: tui.block(
+            title: "My Ruby TUI App",
+            borders: [:all],
+            border_color: "cyan"
+          )
+    event = tui.poll_event
+    break if event == "q" || event == :ctrl_c
+  end
 end
 ```
 
-For a full tutorial, see [the Quickstart](./doc/quickstart.md).
+For a full tutorial, see [the Quickstart](./doc/quickstart.md). For an explanation of the application architecture, see [Application Architecture](./doc/application_architecture.md).
 
 
 ## Documentation

data/REUSE.toml

@@ -1,10 +1,5 @@
 version = 1
 
-[[annotations]]
-path = '.ruby-version'
-SPDX-FileCopyrightText = "2025 Kerrick Long <me@kerricklong.com>"
-SPDX-License-Identifier = "CC0-1.0"
-
 [[annotations]]
 path = 'Gemfile.lock'
 SPDX-FileCopyrightText = "2025 Kerrick Long <me@kerricklong.com>"

data/doc/application_architecture.md

@@ -0,0 +1,116 @@
+# Core Concepts
+
+This guide explains the core concepts and patterns available in `ratatui_ruby` for structuring your terminal applications.
+
+## 1. Lifecycle Management
+
+Managing the terminal state is critical. You must enter "alternate screen" and "raw mode" on startup, and **always** restore the terminal on exit (even on errors), otherwise the user's terminal will be left in a broken state.
+
+### `RatatuiRuby.run` (Recommended)
+
+The `run` method acts as a **Context Manager**. It handles the initialization and restoration for you, ensuring the terminal is always restored even if your code raises an exception. We recommend using `run` for all applications, as it provides a safe sandbox for your TUI.
+
+```ruby
+RatatuiRuby.run do |tui|
+  loop do
+     # Your code here
+    tui.draw(...)
+  end
+end
+# Terminal is restored here
+```
+
+### Manual Management (Advanced)
+
+You can manage this manually if you need granular control, but use `ensure` blocks!
+
+```ruby
+RatatuiRuby.init_terminal
+begin
+  # Your code here
+  RatatuiRuby.draw(...)
+ensure
+  RatatuiRuby.restore_terminal
+end
+```
+
+## 2. API Convenience
+
+### Session API (Recommended)
+
+The block yielded by `run` is a `RatatuiRuby::Session` instance (`tui`).
+It provides factory methods for every widget class (converting snake_case to CamelCase) and aliases for module functions.
+
+**Why use it?** It significantly reduces verbosity and repeated `RatatuiRuby::` namespacing, making the UI tree structure easier to read.
+
+```ruby
+RatatuiRuby.run do |tui|
+  loop do
+    layout = tui.layout(
+      direction: :horizontal,
+      constraints: [
+        RatatuiRuby::Constraint.length(20),
+        RatatuiRuby::Constraint.min(0)
+      ],
+      children: [
+        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")
+        ),
+        tui.paragraph(
+          text: "Main Content",
+          style: tui.style(fg: :green),
+          block: tui.block(borders: [:all], title: "Content")
+        )
+      ]
+    )
+    
+    tui.draw(layout)
+    
+    event = tui.poll_event
+    break if event == "q" || event == :ctrl_c
+  end
+end
+```
+
+### Raw API
+
+You can always use the raw module methods and classes directly. This is useful if you are building your own abstractions or prefer explicit class instantiation.
+
+**Comparison:** Notice how much more verbose the same UI definition is.
+
+```ruby
+RatatuiRuby.run do
+  loop do
+    layout = RatatuiRuby::Layout.new(
+      direction: :horizontal,
+      constraints: [
+        RatatuiRuby::Constraint.length(20),
+        RatatuiRuby::Constraint.min(0)
+      ],
+      children: [
+        RatatuiRuby::Paragraph.new(
+          text: RatatuiRuby::Text::Line.new(spans: [
+            RatatuiRuby::Text::Span.new(content: "Side", style: RatatuiRuby::Style.new(fg: :blue)),
+            RatatuiRuby::Text::Span.new(content: "bar")
+          ]),
+          block: RatatuiRuby::Block.new(borders: [:all], title: "Nav")
+        ),
+        RatatuiRuby::Paragraph.new(
+          text: "Main Content",
+          style: RatatuiRuby::Style.new(fg: :green),
+          block: RatatuiRuby::Block.new(borders: [:all], title: "Content")
+        )
+      ]
+    )
+    
+    RatatuiRuby.draw(layout)
+
+    event = RatatuiRuby.poll_event
+    break if event == "q" || event == :ctrl_c
+  end
+end
+```

data/doc/application_testing.md

@@ -44,8 +44,8 @@ Wrap your test assertions in `with_test_terminal`. This sets up a temporary, in-
 
 ```ruby
 def test_rendering
-  # Create a 80x24 terminal
-  with_test_terminal(80, 24) do
+  # Uses default 80x24 terminal
+  with_test_terminal do
     # 1. Instantiate your app/component
     widget = RatatuiRuby::Paragraph.new(text: "Hello World")
     
@@ -82,13 +82,18 @@ assert_equal 2, pos[:y]
 
 Injects a mock event into the event queue. This is the preferred way to simulate user input instead of stubbing `poll_event`.
 
+> [!IMPORTANT]
+> You must call `inject_event` inside a `with_test_terminal` block. Calling it outside leads to race conditions where events are flushed before the application starts.
+
 ```ruby
-# Simulate 'q' key press
-inject_event("key", { code: "q" })
+with_test_terminal do
+  # Simulate 'q' key press
+  inject_event("key", { code: "q" })
 
-# Now poll_event will return the 'q' key event
-event = RatatuiRuby.poll_event
-assert_equal "q", event[:code]
+  # Now poll_event will return the 'q' key event
+  event = RatatuiRuby.poll_event
+  assert_equal "q", event.code
+end
 ```
 
 ## Example