ratatui_ruby 0.7.2 → 0.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52112877db56e3edf7a4baa4c542b55570e8b1172a172934e229c0730d33ca2c
-  data.tar.gz: 1f46e0c790f33828dba5ed4cfa6ea6d56d5525634cc587d0986005e287c6b876
+  metadata.gz: f76aaa4da70206d5855ab0d4d7a9356bd57117c1d4ff6d243e86db8bb6e53be9
+  data.tar.gz: 88b96b0a71f595d7ca4b255d90f29b3aac3e2fcc02f323d2db9adfaa233bf4a0
 SHA512:
-  metadata.gz: 5ee6665ca41a8029b67f9d99ac4908ad5ab124cc8d21952d7a42e3eb3bce0dfd2ef77e19b69294a7c5e2bb1a8bb745047a8f7599712e497ba0c66d3e8607e351
-  data.tar.gz: '085180a5bab1b831521750b42398087109129fda7d20fe369b7aa4ff5c746e691e09f82a4251bc62ca964508ed21d9276ace9970ed91fec3fd979923ea2937a5'
+  metadata.gz: 9d8bc1bc8aa2ae2625302e0024f83c6b30459551377f111e9703e9ed9f70fe0c79cc5cd6af57d9770bd5cc7ecfc93e9e8472f7ebde314b1c989a9cff87110bba
+  data.tar.gz: b0d285b610e38669c9c764b492e384ae2e9f84739b5572096d70a74818b4ce87f2025c06d9055e55e3e7966c8f0ba9768533ba683ea232a3a77a224ac716f8ed

data/.builds/ruby-3.2.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.7.2.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.7.3.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/.builds/ruby-3.3.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.7.2.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.7.3.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/.builds/ruby-3.4.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.7.2.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.7.3.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/.builds/ruby-4.0.0.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.7.2.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.7.3.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/AGENTS.md

@@ -30,7 +30,8 @@ Architecture:
 - Every file MUST begin with an SPDX-compliant header. Use `AGPL-3.0-or-later` for code; `CC-BY-SA-4.0` for documentation. `reuse annotate` can help you generate the header. **For Ruby files**, wrap SPDX comments in `#--` / `#++` to hide them from RDoc output.
 - Every line of Ruby MUST be covered by tests that would stand up to mutation testing.
   - Tests must be meaningful and verify specific behavior or rendering output; simply verifying that code "doesn't crash" is insufficient and unacceptable.
-  - For UI widgets, this means using `with_test_terminal` to verify EVERY character of the terminal buffer's content.
+  - **Prefer snapshot tests** (`assert_snapshots`, plural) over manual `buffer_content` assertions for UI widgets. Snapshots are self-documenting and easier to maintain.
+  - For UI widgets, use `with_test_terminal` and snapshot assertions to verify terminal buffer content.
 - Every line of Rust MUST be covered by tests that would stand up to mutation testing.
   - Tests must be meaningful; simply verifying that code "doesn't crash" or "compiles" is insufficient and unacceptable.
   - Each widget implementation must have a `tests` module with unit tests verifying basic rendering.
@@ -137,8 +138,8 @@ Before considering a task complete and returning control to the user, you **MUST
 
 1.  **Default Rake Task Passes:** Run `bin/agent_rake` (no args). Confirm it passes with ZERO errors **or warnings**.
   - You will save time if you run `bin/agent_rake rubocop:autocorrect` first.
-  - If you think the build is looking for deleted files, it is not. Instead, tell the user and **ask them to stage changes**.
+  - If you think the build is looking for deleted files, it is not. Instead, explain to the user why staging is needed and use the `run_command` tool with `git add -A` so they get a Run button with context.
 2.  **Documentation Updated:** If public APIs or observable behavior changed, update relevant RDoc, rustdoc, `doc/` files, `README.md`, and/or `ratatui_ruby-wiki` files.
 3.  **Changelog Updated:** If public APIs, observable behavior, or gemspec dependencies have changed, update [CHANGELOG.md](CHANGELOG.md)'s **Unreleased** section.
 4.  **Commit Message Suggested:** You **MUST** ensure the final message to the user includes a suggested commit message block. This is NOT optional.
-  - You MUST also remind the user to add an AI attribution footer.
+  - You MUST also check `git log -n1` to see the current standard AI footer ("Generated  with" and "Co-Authored-By") and include it in your suggested message.

data/CHANGELOG.md

@@ -12,10 +12,37 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Added
 
+- **Block Inner Area Calculation**: `Block#inner(area)` method computes the inner content area given an outer `Rect`, accounting for borders and padding. Essential for layout calculations when you need to know usable space inside a block.
+- **Deferred Warnings During TUI Sessions**: Experimental feature warnings (like `Paragraph#line_count`) are now automatically queued during active TUI sessions and flushed to stderr after `restore_terminal`. This prevents warnings from corrupting the TUI display. See `doc/troubleshooting/tui_output.md` for details on handling terminal output during TUI sessions.
+- **Session State Tracking**: `RatatuiRuby.terminal_active?` indicates whether a TUI session is active. Calling `init_terminal` or `init_test_terminal` while a session is already active now raises `Error::Invariant`.
+- **Error::Invariant**: New error class for state invariant violations (e.g., double-init). Distinct from `Error::Safety` (lifetime violations) and `Error::Terminal` (operational I/O failures).
 ### Changed
 
 ### Fixed
 
+- **Direct Text Rendering**: `Text::Line` and `Text::Span` can now be rendered directly as widgets via `frame.render_widget(line, area)` without wrapping in a `Paragraph`. Previously, these text primitives were silently ignored when passed to `render_widget`.
+- **Text Line Alignment**: `Text::Line` `alignment:` parameter is now respected during rendering. Previously, the alignment was ignored and text always rendered left-aligned.
+
+### Removed
+
+## [0.7.3] - 2026-01-04
+
+### Added
+
+- **Symbol Shortcuts for `bar_set`**: `Sparkline` and `BarChart` now accept `:nine_levels` (full 9-character gradient) and `:three_levels` (simplified empty/half/full) as intuitive shortcuts instead of requiring custom character hashes.
+- **`:half_block` Marker**: `Chart` `Dataset` now supports `:half_block` marker for higher resolution rendering using ▀ and ▄ characters.
+- **`assert_snapshots` Method**: `RatatuiRuby::TestHelper#assert_snapshots` (plural) calls both `assert_plain_snapshot` and `assert_rich_snapshot` with the same name, generating both `.txt` and `.ansi` files for documentation and display purposes.
+- **Edge-Center Legend Positions**: `Chart` `legend_position` now accepts `:top`, `:bottom`, `:left`, and `:right` in addition to the existing corner positions (`:top_left`, `:top_right`, `:bottom_left`, `:bottom_right`).
+- **`:reset` Color**: `Style` `fg` and `bg` now accept `:reset` to explicitly clear any inherited foreground or background color, restoring the terminal's default.
+
+### Changed
+
+### Deprecated
+
+- **`assert_snapshot`**: Use `assert_snapshots` (plural) instead, or `assert_plain_snapshot` if you only need plain text. The old method name lacked clarity about whether it captured plain text or styled ANSI output.
+
+### Fixed
+
 ### Removed
 
 ## [0.7.2] - 2026-01-04
@@ -388,6 +415,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - **Testing Support**: Included `RatatuiRuby::TestHelper` and RSpec integration to make testing your TUI applications possible.
 
 [Unreleased]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/HEAD
+[0.7.3]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.7.3
 [0.7.2]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.7.2
 [0.7.1]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.7.1
 [0.7.0]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.7.0

data/README.md

@@ -6,10 +6,10 @@
 
 [![
 builds.sr.ht status](https://builds.sr.ht/~kerrick/ratatui_ruby.svg)](https://builds.sr.ht/~kerrick/ratatui_ruby?) [![
-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) [![
+License](https://img.shields.io/badge/dynamic/regex?url=https%3A%2F%2Fgit.sr.ht%2F~kerrick%2Fratatui_ruby%2Fblob%2Fstable%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.30) [![
+Ratatui Version](https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fgit.sr.ht%2F~kerrick%2Fratatui_ruby%2Fblob%2Fstable%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)

data/doc/concepts/application_testing.md

@@ -103,15 +103,17 @@ See [RatatuiRuby::TestHelper::EventInjection](../lib/ratatui_ruby/test_helper/ev
 
 Snapshots let you verify complex layouts without manually asserting every line.
 
-Use `assert_snapshot` to compare the current screen against a stored reference file.
+Use `assert_snapshots` to compare the current screen against stored reference files.
 
 ```ruby
 with_test_terminal do
   MyApp.new.run
-  assert_snapshot("dashboard_view")
+  assert_snapshots("dashboard_view")
 end
 ```
 
+This generates both `.txt` (plain text) and `.ansi` (styled) snapshot files. The `.ansi` files contain ANSI escape codes—`cat` them in a terminal to see exactly what the screen looked like. For a visual tour of your test suite, try `cat **/*.ansi` in any shell that supports globbing.
+
 ### Handling Non-Determinism
 
 Snapshots must be deterministic. Random data or current timestamps will cause test failures ("flakes").

data/doc/contributors/developing_examples.md

@@ -112,7 +112,7 @@ examples/
 test/examples/
   my_example/
     test_app.rb         ← REQUIRED: Tests (centralized, not local to example)
-    snapshots/          ← Auto-created by assert_snapshot
+    snapshots/          ← Auto-created by snapshot assertions
       initial_render.txt
 
 sig/examples/
@@ -223,7 +223,7 @@ class TestMyExampleApp < Minitest::Test
     with_test_terminal do
       inject_key(:q)
       @app.run
-      assert_snapshot("initial_render")
+      assert_snapshots("initial_render")
     end
   end
 end
@@ -231,7 +231,7 @@ end
 
 ## Snapshot Testing Pattern (REQUIRED)
 
-All example tests MUST use snapshot testing via the `assert_snapshot` API, not manual content assertions.
+All example tests MUST use snapshot testing via the `assert_snapshots` API, not manual content assertions.
 
 ### Why Snapshots
 
@@ -249,7 +249,7 @@ def test_initial_render
     inject_key(:q)
     @app.run
     
-    assert_snapshot("initial_render")
+    assert_snapshots("initial_render")
   end
 end
 ```
@@ -261,8 +261,8 @@ Snapshot auto-saved to: `test/examples/widget_foo/snapshots/initial_render.txt`
 For examples with timestamps, random data, or other non-deterministic output:
 
 ```ruby
-private def assert_normalized_snapshot(snapshot_name)
-  assert_snapshot(snapshot_name) do |actual|
+private def assert_normalized_snapshots(snapshot_name)
+  assert_plain_snapshot(snapshot_name) do |actual|
     actual.map do |line|
       line.gsub(/\d{2}:\d{2}:\d{2}/, "XX:XX:XX")  # Mask timestamps
            .gsub(/Random ID: \d+/, "Random ID: XXX")  # Mask random values
@@ -276,7 +276,7 @@ def test_after_event
     inject_key(:q)
     @app.run
     
-    assert_normalized_snapshot("after_event")
+    assert_normalized_snapshots("after_event")
   end
 end
 ```

data/doc/contributors/upstream_requests/tab_rects.md

@@ -0,0 +1,173 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Feature Request: Expose Tabs Title Rects
+
+## Summary
+
+`Tabs` computes the bounding rect for each tab title during rendering but does not expose this information. Interactive applications need these rects for mouse click hit-testing.
+
+## The Problem
+
+Building clickable tab interfaces requires knowing where each tab renders. When a user clicks within the tabs area, the application cannot determine which specific tab was clicked without duplicating the internal layout algorithm.
+
+Currently, the only options are:
+
+1. **Recompute the layout manually.** Duplicate the logic from `render_tabs`, accounting for padding, dividers, and title widths. This is fragile—any upstream change breaks the user's code.
+2. **Use coarse hit-testing.** Check if a click is anywhere in the tabs area, then guess based on x-position. This breaks when titles have different widths or styled content.
+
+Neither approach is satisfactory.
+
+## Use Case
+
+Consider a TUI with a tabbed interface:
+
+```
+┌Announce v0.7.3───────────────────────────────emate┐
+│ Preview Email  ▸  Preview Commit  ▸  Announce   │
+│                                                   │
+└───────────────────────────────────────────────────┘
+```
+
+The application wants to detect clicks on individual tab titles (`"Preview Email"`, `"Preview Commit"`, `"Announce"`) and switch to that tab.
+
+Without title rects, the application must manually compute where each tab renders:
+
+```rust
+// Manual calculation - fragile and duplicates internal logic
+let divider_width = 3; // " ▸ " is 3 characters
+let content_row = area.y + 1; // Skip top border
+let mut x = area.x + 2; // Skip border + padding
+
+let tab_rects: Vec<Rect> = titles.iter().map(|title| {
+    let tab_width = title.len() as u16;
+    let rect = Rect::new(x, content_row, tab_width, 1);
+    x += tab_width + divider_width;
+    rect
+}).collect();
+```
+
+This duplicates private logic from `Tabs::render_tabs` and breaks when:
+
+- Padding is configured differently (`padding_left`, `padding_right`)
+- Divider width changes
+- Upstream layout logic changes
+- A block is present (affects inner area calculation)
+
+## Current State (v0.30.0)
+
+`Tabs` has a private `render_tabs` method that computes title areas:
+
+```rust
+// From src/widgets/tabs.rs - private rendering logic
+fn render_tabs(&self, tabs_area: Rect, buf: &mut Buffer) {
+    let mut x = tabs_area.left();
+    for (i, title) in self.titles.iter().enumerate() {
+        // ...padding and title rendering...
+        
+        // Title rect is computed here but not exposed
+        if Some(i) == self.selected {
+            buf.set_style(
+                Rect {
+                    x,
+                    y: tabs_area.top(),
+                    width: pos.0.saturating_sub(x),
+                    height: 1,
+                },
+                self.highlight_style,
+            );
+        }
+        // ...
+    }
+}
+```
+
+The rect is computed for applying `highlight_style` but is not accessible to users.
+
+## Proposed API
+
+Following the pattern established by `Block::inner(area)`, add a pure computation method that takes an area and returns computed sub-rects without rendering:
+
+```rust
+impl Tabs {
+    /// Returns the bounding rect for each tab title given an area.
+    ///
+    /// The rects are returned in the same order as titles were added.
+    /// Useful for hit-testing mouse clicks against specific tabs.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// let tabs = Tabs::new(["Tab 1", "Tab 2", "Tab 3"])
+    ///     .divider(" | ");
+    ///
+    /// let rects = tabs.title_rects(area);
+    /// for (i, rect) in rects.iter().enumerate() {
+    ///     if rect.contains(mouse_position) {
+    ///         selected_tab = i;
+    ///         break;
+    ///     }
+    /// }
+    /// ```
+    pub fn title_rects(&self, area: Rect) -> Vec<Rect> { ... }
+}
+```
+
+Alternatively, a single-lookup method:
+
+```rust
+/// Returns the rect for the tab at the given index.
+pub fn title_rect(&self, area: Rect, index: usize) -> Option<Rect> { ... }
+```
+
+## Workaround
+
+Without this API, users must replicate the tab layout algorithm. Here is the current approach used in RatatuiRuby:
+
+```rust
+// Manually compute tab title positions
+let divider_width = 3; // " ▸ " is 3 characters  
+let content_row = area.y + 1; // Skip top border
+let mut x = area.x + 2; // Skip left border + padding
+
+let tab_rects: Vec<Rect> = TABS.iter().map(|title| {
+    let tab_width = title.len() as u16;
+    let rect = Rect::new(x, content_row, tab_width, 1);
+    x += tab_width + divider_width;
+    rect
+}).collect();
+
+// Hit testing
+for (i, rect) in tab_rects.iter().enumerate() {
+    if rect.contains(click_position) {
+        current_tab = i;
+        break;
+    }
+}
+```
+
+This works for simple cases but breaks when:
+
+- `padding_left` or `padding_right` are non-default
+- The divider is styled (Span width differs from string length)
+- A block wraps the tabs (inner area differs)
+- Title text is styled (Line width differs from string length)
+
+## Impact
+
+This feature benefits any application with clickable tabs:
+
+- Tab-based navigation interfaces
+- Multi-panel applications with panel selectors
+- Mode switchers (edit/view/preview)
+- Category selectors
+
+The `Tabs` widget is commonly used for navigation. Mouse interaction is a natural expectation for TUI applications running in modern terminals with mouse support.
+
+---
+
+This issue includes creative contributions from Claude (Anthropic) via Antigravity (Google). [https://declare-ai.org/1.0.0/creative.html](https://declare-ai.org/1.0.0/creative.html)
+
+*Discovered while implementing click handling for tab navigation in RatatuiRuby.*

data/doc/contributors/upstream_requests/title_rects.md

@@ -0,0 +1,132 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Feature Request: Expose Block Title Rects
+
+## Summary
+
+`Block` computes the position of each title during rendering but does not expose this information. Interactive applications need title rects for mouse click hit-testing.
+
+## The Problem
+
+Building clickable TUI interfaces requires knowing where widgets render. When a block has multiple titles (e.g., a left-aligned title and a right-aligned toggle label), each title occupies a specific screen region. The application cannot query these regions.
+
+Currently, the only options are:
+
+1. **Recompute the layout manually.** Duplicate the logic from `render_left_titles`, `render_right_titles`, and `render_center_titles`. This is fragile—any upstream change breaks the user's code.
+2. **Use coarse hit-testing.** Check if a click is anywhere in the block's top border row. This cannot distinguish between multiple titles.
+
+Neither approach is satisfactory.
+
+## Use Case
+
+Consider a TUI with a tabbed interface where the block's title bar contains:
+
+- A left-aligned title: `"Announce v0.7.3"`  
+- A right-aligned toggle: `"emate"` (clickable to switch email clients)
+
+```
+┌Announce v0.7.3───────────────────────────────emate┐
+│ Preview Email  ▸  Preview Commit  ▸  Announce   │
+│                                                   │
+└───────────────────────────────────────────────────┘
+```
+
+The application wants to:
+
+1. Detect clicks on `"emate"` and toggle the email client
+2. Detect clicks on tab names and switch tabs
+3. Ignore clicks on the border characters
+
+Without title rects, the application must manually compute where `"emate"` renders based on block width, borders, alignment, and title content. This duplicates private logic from `Block::render_right_titles`.
+
+## Current State (v0.30.0)
+
+`Block` has private methods that compute title areas:
+
+```rust
+// Private - not accessible to users
+fn titles_area(&self, area: Rect, position: Position) -> Rect { ... }
+fn render_left_titles(&self, position: Position, area: Rect, buf: &mut Buffer) { ... }
+fn render_center_titles(&self, position: Position, area: Rect, buf: &mut Buffer) { ... }
+fn render_right_titles(&self, position: Position, area: Rect, buf: &mut Buffer) { ... }
+```
+
+The `titles_area` method computes the general title region. The `render_*_titles` methods compute individual title rects during rendering but do not expose them.
+
+## Proposed API
+
+Following the pattern established by `Block::inner(area)`, add a pure computation method that takes an area and returns computed sub-rects without rendering:
+
+```rust
+impl Block {
+    /// Returns the bounding rect for each title given an area.
+    ///
+    /// The rects are returned in the same order as titles were added.
+    /// Useful for hit-testing mouse clicks against specific titles.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// let block = Block::bordered()
+    ///     .title_top("Left Title")
+    ///     .title_top(Line::from("Right").right_aligned());
+    ///
+    /// let rects = block.title_rects(area);
+    /// if rects[1].contains(mouse_position) {
+    ///     // Clicked on "Right"
+    /// }
+    /// ```
+    pub fn title_rects(&self, area: Rect) -> Vec<Rect> { ... }
+}
+```
+
+Alternatively, expose the individual areas by alignment:
+
+```rust
+/// Returns the rect for the title at the given index.
+pub fn title_rect(&self, area: Rect, index: usize) -> Option<Rect> { ... }
+
+/// Returns the titles area for a given position (top or bottom).
+pub fn titles_area(&self, area: Rect, position: Position) -> Rect { ... }
+```
+
+## Workaround
+
+Without this API, users must replicate the title layout algorithm. Here is the current approach used in RatatuiRuby:
+
+```rust
+// Manually compute right-aligned title position
+let email_label_width = email_client.len() as u16;
+let email_label_x = area.x + area.width - email_label_width - 2; // border + padding
+let email_label_rect = Rect::new(email_label_x, area.y, email_label_width, 1);
+
+if email_label_rect.contains(click_position) {
+    toggle_email_client();
+}
+```
+
+This works for simple cases but breaks when:
+
+- Borders are not all present (`Borders::LEFT` affects x offset)
+- Multiple right-aligned titles exist (spacing affects position)
+- Upstream layout logic changes
+
+## Impact
+
+This feature benefits any application with interactive block titles:
+
+- Clickable tabs in title bars
+- Toggle buttons in headers
+- Breadcrumb navigation
+- Window controls (minimize/maximize/close buttons in the title area)
+
+Related discussion: [ratatui#738](https://github.com/ratatui/ratatui/issues/738) (title positioning behavior)
+
+---
+
+This issue includes creative contributions from Claude (Anthropic) via Antigravity (Google). [https://declare-ai.org/1.0.0/creative.html](https://declare-ai.org/1.0.0/creative.html)
+
+*Discovered while implementing click handling for block title toggles in RatatuiRuby.*