ratatui_ruby 1.1.0 → 1.1.1

data/doc/contributors/todo/future_work.md

@@ -1,169 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Future Work
-
-Ideas for post-v1.0.0 development. These do not block the initial release.
-
----
-
-## Port Upstream Ratatui Examples
-
-Ratatui ships [example applications](https://github.com/ratatui/ratatui/tree/main/examples) demonstrating real-world patterns. Porting these to RatatuiRuby would:
-
-1. Validate API parity in realistic usage
-2. Provide learning resources for Ruby developers
-3. Surface gaps in the alignment audit
-
-**Candidates for porting:**
-
-- `demo2` — Kitchen sink showcasing all widgets
-- `async` — Background task handling
-- `user_input` — Text input patterns
-- `popup` — Modal dialogs
-
----
-
-## Cross-Platform Distribution
-
-[CosmoRuby](https://github.com/igravious/cosmoruby) aims to build Ruby with [Cosmopolitan Libc](https://justine.lol/cosmopolitan/), producing single binaries that run on Linux, macOS, Windows, and BSD without recompilation.
-
-**Gap:** RatatuiRuby is a native extension. CosmoRuby does not yet support native extensions.
-
-**When this becomes viable:**
-
-- CosmoRuby adds native extension support
-- Demand emerges for single-binary TUI app distribution
-
----
-
-## Terminal Graphics Protocols
-
-Terminal graphics protocols (Sixel, Kitty graphics, iTerm2 inline images) bypass the character cell model. Supporting them requires extension points that do not exist today.
-
-### What Third Parties Need
-
-| Extension Point | Purpose | Status |
-|-----------------|---------|--------|
-| `Draw::RawCmd` | Write raw escape sequences, bypassing the cell buffer | Not available |
-| Terminal capability queries | Detect if terminal supports Sixel, Kitty, etc. | Not available |
-| Frame hooks | Run code before/after buffer flush | Not available |
-
-### Why These Matter
-
-The `ratatui-image` crate provides graphics support for Rust Ratatui apps. A `ratatui_ruby-sixels` gem could wrap it, but only if RatatuiRuby exposes:
-
-1. **Raw output access** — Sixel data writes directly to stdout as escape sequences
-2. **Capability detection** — Apps need to query terminal support before sending graphics
-3. **Render coordination** — Graphics must be positioned after the cell buffer renders
-
-### Implementation Sketch
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-# Proposed API (not implemented)
-
-# 1. Raw draw command
-class Draw
-  RawCmd = Data.define(:bytes)
-  def self.raw(bytes) = RawCmd.new(bytes:)
-end
-
-# 2. Terminal queries
-RatatuiRuby.terminal_supports?(:sixel)      # => true/false
-RatatuiRuby.terminal_supports?(:kitty)      # => true/false
-RatatuiRuby.terminal_size_pixels             # => { width: 1920, height: 1080 }
-
-# 3. Custom widget using raw output
-class SixelImage
-  def render(area)
-    sixel_data = encode_image_as_sixel(@image, area)
-    [RatatuiRuby::Draw.raw(sixel_data)]
-  end
-end
-```
-<!-- SPDX-SnippetEnd -->
-
----
-
-## Custom Backends
-
-Currently hardcoded to Crossterm. A third party might want:
-
-- SSH backend (render to a remote terminal)
-- Web backend (render to browser canvas)
-- Recording backend (capture frames for replay)
-
-**Gap:** No backend plugin architecture.
-
----
-
-## Custom Event Sources
-
-Currently hardcoded to Crossterm events. A third party might want:
-
-- Network events (WebSocket messages as TUI events)
-- File watcher events
-- IPC events
-
-**Gap:** No event source plugin architecture.
-
----
-
-## Event Test Doubles
-
-The TestHelper module provides `MockFrame` and `StubRect` for testing render logic in isolation. However, testing `handle_event` currently requires `init_test_terminal` and `inject_test_event`.
-
-For pure unit tests of Kit components, stub event objects would be useful:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-# Proposed API (not implemented)
-StubKeyEvent = Data.define(:code, :modifiers) do
-  def initialize(code:, modifiers: [])
-    super
-  end
-
-  def key? = true
-  def mouse? = false
-end
-
-StubMouseEvent = Data.define(:kind, :button, :x, :y, :modifiers) do
-  def initialize(kind:, button: "left", x:, y:, modifiers: [])
-    super
-  end
-
-  def key? = false
-  def mouse? = true
-  def down? = kind == "down"
-  def up? = kind == "up"
-end
-
-# Usage
-event = StubKeyEvent.new(code: "a", modifiers: ["ctrl"])
-result = component.handle_event(event)
-assert_equal :consumed, result
-```
-<!-- SPDX-SnippetEnd -->
-
-This would let developers test component event handling without terminal dependencies.
-
-## Prioritization
-
-When prioritizing post-1.0 work, consider:
-
-1. **Port upstream examples** — Validates parity, provides learning resources
-2. **`Draw::RawCmd`** — Lowest effort, highest impact for graphics support
-3. **Terminal capability queries** — Required for any graphics work
-4. **Backend plugins** — Large undertaking, defer until clear demand
-5. **CosmoRuby** — Blocked on upstream; monitor progress

data/doc/contributors/upstream_requests/paragraph_span_rects.md

@@ -1,259 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Feature Request: Expose Paragraph Span Rects
-
-## Summary
-
-`Paragraph` computes the bounding rect for each span during word-wrapping and rendering, but does not expose this information. Interactive applications need these rects for:
-
-- Mouse click hit-testing on clickable text (links, buttons)
-- Accessibility tooling that needs semantic element positions
-- Tooltip positioning relative to specific text spans
-
-## The Problem
-
-Building clickable text within paragraphs requires knowing where each span renders after word wrapping. When a user clicks within a paragraph, the application cannot determine which specific span was clicked without duplicating the internal word-wrapping algorithm.
-
-Currently, the only options are:
-
-1. **Recompute the layout manually.** Duplicate the logic from `WordWrapper` and `LineTruncator`, accounting for word boundaries, trimming, and alignment. This is extremely fragile—the wrapping algorithm is complex and any upstream change breaks the user's code.
-
-2. **Use character counting.** Calculate `chars_before / width` for y-offset and `chars_before % width` for x-offset. This breaks with:
-   - Non-monospace Unicode (CJK, emoji)
-   - Word-level wrapping (spans don't split at character boundaries)
-   - Alignment (center/right shifts all positions)
-   - Trimmed leading whitespace
-
-Neither approach is satisfactory.
-
-## Use Case
-
-Consider a TUI welcome screen with a clickable link:
-
-```
-┌Hello, Rooibos!───────────────────────────────────────┐
-│                                                       │
-│ Welcome to Rooibos! You will find the Ruby code for  │
-│ this application in lib/saturday.rb. The tests that  │
-│ verify it are at test/test_saturday.rb. You can run  │
-│ the tests with bundle exec rake test. Visit          │
-│  www.rooibos.run  to learn about Rooibos and to find │
-│ other Rooibos developers. You can press Control + C  │
-│ to exit at any time.                                  │
-│                                                       │
-└───────────────────────────────────────────────────────┘
-```
-
-The link ` www.rooibos.run ` appears on row 5 after word-wrapping. The application wants to:
-
-1. Detect clicks on the link span
-2. Highlight the link on hover
-3. Open the URL when clicked
-
-Without span rects, the application must manually compute where the link renders after wrapping:
-
-<!--
-SPDX-SnippetBegin
-SPDX-FileCopyrightText: 2026 Kerrick Long
-SPDX-License-Identifier: MIT-0
--->
-```rust
-// Manual calculation - fragile and duplicates internal logic
-let text_before_link = "Welcome to Rooibos! You will find the Ruby code for \
-    this application in lib/saturday.rb. The tests that verify it are at \
-    test/test_saturday.rb. You can run the tests with bundle exec rake test. Visit ";
-let chars_before = text_before_link.width(); // ~204 characters
-let inner_width = block.inner(area).width; // ~74 characters
-
-let y_offset = chars_before / inner_width; // Wrong: doesn't account for word wrapping
-let x_offset = chars_before % inner_width; // Wrong: words don't wrap mid-word
-```
-<!--
-SPDX-SnippetEnd
--->
-
-This fails because `WordWrapper`:
-
-- Wraps at word boundaries, not character positions
-- May trim leading whitespace on wrapped lines
-- Produces lines of varying length
-
-The computed position is always wrong by several cells.
-
-## Current State (v0.30.0)
-
-`Paragraph::render_paragraph` uses `WordWrapper` or `LineTruncator` to compose lines:
-
-<!--
-SPDX-SnippetBegin
-SPDX-FileCopyrightText: 2016-2022 Florian Dehau
-SPDX-FileCopyrightText: 2023-2025 The Ratatui Developers
-SPDX-License-Identifier: MIT
--->
-```rust
-// From src/widgets/paragraph.rs - private rendering logic
-fn render_paragraph(&self, text_area: Rect, buf: &mut Buffer) {
-    let styled = self.text.iter().map(|line| {
-        let graphemes = line.styled_graphemes(self.text.style);
-        let alignment = line.alignment.unwrap_or(self.alignment);
-        (graphemes, alignment)
-    });
-
-    if let Some(Wrap { trim }) = self.wrap {
-        let mut line_composer = WordWrapper::new(styled, text_area.width, trim);
-        render_lines(line_composer, text_area, buf);
-    } else {
-        // ...LineTruncator path...
-    }
-}
-
-fn render_line(wrapped: &WrappedLine<'_, '_>, area: Rect, buf: &mut Buffer, y: u16) {
-    let mut x = get_line_offset(wrapped.width, area.width, wrapped.alignment);
-    for StyledGrapheme { symbol, style } in wrapped.graphemes {
-        // Position is computed here but not exposed
-        let position = Position::new(area.left() + x, area.top() + y);
-        buf[position].set_symbol(symbol).set_style(*style);
-        x += u16::try_from(width).unwrap_or(u16::MAX);
-    }
-}
-```
-<!--
-SPDX-SnippetEnd
--->
-
-The grapheme positions are computed during rendering but never associated back to the source spans.
-
-## Proposed API
-
-Following the pattern established by `Block::inner(area)` and `Layout::split()`, add a pure computation method that takes an area and returns computed span rects without rendering:
-
-### Option 1: Return all span rects
-
-<!--
-SPDX-SnippetBegin
-SPDX-FileCopyrightText: 2026 Kerrick Long
-SPDX-License-Identifier: MIT-0
--->
-```rust
-impl Paragraph {
-    /// Returns the bounding rect for each span given an area.
-    ///
-    /// For wrapped paragraphs, a span that wraps across multiple lines
-    /// returns a rect covering all lines it occupies.
-    ///
-    /// # Example
-    ///
-    /// ```rust
-    /// let link_span = Span::styled(" www.rooibos.run ", Style::new().underlined());
-    /// let text = Text::from(Line::from(vec![
-    ///     Span::raw("Visit "),
-    ///     link_span.clone(),
-    ///     Span::raw(" for more info."),
-    /// ]));
-    /// let paragraph = Paragraph::new(text).wrap(Wrap { trim: true });
-    ///
-    /// let span_rects = paragraph.span_rects(area);
-    /// if span_rects[1].contains(mouse_position) {
-    ///     // User clicked the link!
-    /// }
-    /// ```
-    pub fn span_rects(&self, area: Rect) -> Vec<Rect> { ... }
-}
-```
-<!--
-SPDX-SnippetEnd
--->
-
-### Option 2: Lookup by span index
-
-<!--
-SPDX-SnippetBegin
-SPDX-FileCopyrightText: 2026 Kerrick Long
-SPDX-License-Identifier: MIT-0
--->
-```rust
-/// Returns the rect for the span at the given index.
-pub fn span_rect(&self, area: Rect, line_index: usize, span_index: usize) -> Option<Rect> { ... }
-```
-<!--
-SPDX-SnippetEnd
--->
-
-### Option 3: Iterator-based (memory efficient)
-
-<!--
-SPDX-SnippetBegin
-SPDX-FileCopyrightText: 2026 Kerrick Long
-SPDX-License-Identifier: MIT-0
--->
-```rust
-/// Returns an iterator over (line_index, span_index, Rect) tuples.
-pub fn span_rects_iter(&self, area: Rect) -> impl Iterator<Item = (usize, usize, Rect)> { ... }
-```
-<!--
-SPDX-SnippetEnd
--->
-
-## Implementation Notes
-
-The implementation would reuse `WordWrapper`/`LineTruncator` in a non-rendering mode:
-
-1. Process the text through the line composer (same as `render_paragraph`)
-2. Track grapheme positions as they're composed (same loop as `render_line`)
-3. Group grapheme positions by source span
-4. Return span bounding rects
-
-Key considerations:
-
-- **Wrapped spans**: A span that wraps to the next line should return a rect covering both lines (bounding box) or multiple rects (one per line fragment)
-- **Empty spans**: Zero-width spans should return the position where they would appear
-- **Scroll offset**: Rects should be adjusted by the paragraph's scroll offset
-- **Block**: The area should be the inner area after block borders/padding
-
-## Workaround
-
-Without this API, users must reimplement word wrapping. This is impractical for production use—the workaround in RatatuiRuby uses simple character math that produces incorrect positions:
-
-<!--
-SPDX-SnippetBegin
-SPDX-FileCopyrightText: 2026 Kerrick Long
-SPDX-License-Identifier: MIT-0
--->
-```rust
-// This is WRONG but the only option without span_rects
-let chars_before = preceding_spans.iter().map(|s| s.width()).sum();
-let x = area.x + (chars_before % area.width);
-let y = area.y + (chars_before / area.width);
-```
-<!--
-SPDX-SnippetEnd
--->
-
-The correct implementation requires processing the entire text through `WordWrapper`, which is private.
-
-## Impact
-
-This feature benefits any application with clickable or interactive text:
-
-- **Hyperlinks**: Click to open URLs in wrapped text
-- **Command help**: Click command names to execute them
-- **Error messages**: Click file paths to open editors
-- **Documentation viewers**: Interactive code examples
-- **Accessibility**: Screen readers need element positions
-
-Rich text interaction is a natural expectation for modern TUI applications. Word-wrapped paragraphs with clickable elements are common in web UIs—TUIs should offer the same capability.
-
-## Related
-
-- `Block::inner(area)` - Same pattern: pure computation of content area
-- `Layout::split(area, constraints)` - Same pattern: pure computation of child areas
-- `Tabs::title_rects(area)` (proposed in separate issue) - Same pattern for tab hit-testing
-
----
-
-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 link click handling for RatatuiRuby's Saturday demo app.*

data/doc/contributors/upstream_requests/tab_rects.md

@@ -1,173 +0,0 @@
-<!--
-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.*