ratatui_ruby 0.7.1 → 0.7.3

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.*