ratatui_ruby 1.0.0 → 1.0.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/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.*

data/doc/contributors/upstream_requests/title_rects.md

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

data/doc/custom.css

@@ -1,22 +0,0 @@
-/*
- * SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
- * SPDX-License-Identifier: AGPL-3.0-or-later
- */
-
-img {
-  max-width: 100%;
-  height: auto;
-}
-
-.theme-toggle {
-  margin-left: 0 !important;
-}
-
-/* Terminal Previews (Native PNGs)
- * The images already contain the window chrome and shadows.
- * We just need to center them and ensure they scale down on mobile.
- */
-img[src*="images/"] {
-  display: block;
-  margin: 2em auto;
-}