ratatui_ruby 1.1.0 → 1.1.1

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;
-}

data/doc/getting_started/quickstart.md

@@ -1,291 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-# Quickstart
-
-Welcome to **ratatui_ruby**! This guide will help you get up and running with your first Terminal User Interface in Ruby.
-
-## Installation
-
-See [Installation in the README](../../README.md#installation) for setup instructions.
-
-
-## Tutorials
-
-### Basic Application
-
-Here is a "Hello World" application that demonstrates the core lifecycle of a **ratatui_ruby** app.
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-<!-- SYNC:START:examples/verify_quickstart_lifecycle/app.rb:main -->
-```ruby
-# 1. Initialize the terminal
-RatatuiRuby.init_terminal
-
-begin
-  # The Main Loop
-  loop do
-    # 2. Create your UI (Immediate Mode)
-    # We define a Paragraph widget inside a Block with a title and borders.
-    view = RatatuiRuby::Widgets::Paragraph.new(
-      text: "Hello, Ratatui! Press 'q' to quit.",
-      alignment: :center,
-      block: RatatuiRuby::Widgets::Block.new(
-        title: "My Ruby TUI App",
-        title_alignment: :center,
-        borders: [:all],
-        border_style: { fg: "cyan" },
-        style: { fg: "white" }
-      )
-    )
-
-    # 3. Draw the UI
-    RatatuiRuby.draw do |frame|
-      frame.render_widget(view, frame.area)
-    end
-
-    # 4. Poll for events
-    case RatatuiRuby.poll_event
-    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
-      break
-    else
-      nil
-    end
-
-    # 5. Guard against accidental output (optional but recommended)
-    # Wrap any code that might puts/warn to prevent screen corruption.
-    RatatuiRuby.guard_io do
-      # SomeChattyGem.do_something
-    end
-  end
-ensure
-  # 6. Restore the terminal to its original state
-  RatatuiRuby.restore_terminal
-end
-```
-<!-- SYNC:END -->
-<!-- SPDX-SnippetEnd -->
-
-[![quickstart_lifecycle](../images/verify_quickstart_lifecycle.png)](../../examples/verify_quickstart_lifecycle/README.md)
-
-#### How it works
-
-1.  **`RatatuiRuby.init_terminal`**: Enters raw mode and switches to the alternate screen.
-2.  **Immediate Mode UI**: On every iteration, describe your UI by creating `Data` objects (e.g., `Paragraph`, `Block`).
-3.  **`RatatuiRuby.draw { |frame| ... }`**: The block receives a `Frame` object as a canvas. Render widgets onto specific areas. Nothing is drawn until the block finishes, ensuring flicker-free updates.
-4.  **`RatatuiRuby.poll_event`**: Returns a typed `Event` object with predicates like `key?`, `mouse?`, `resize?`, etc. Returns `RatatuiRuby::Event::None` if no events are pending. Use predicates to check event type without pattern matching.
-5.  **`RatatuiRuby.guard_io { }`**: Wraps code that might write to stdout/stderr (e.g., chatty gems). Output is swallowed to prevent screen corruption. Optional but recommended for production apps.
-6.  **`RatatuiRuby.restore_terminal`**: Essential for leaving raw mode and returning to the shell. Always wrap your loop in `begin...ensure` to guarantee this runs.
-
-### Simplified API
-
-You can simplify your code by using `RatatuiRuby.run`. This method handles the terminal lifecycle for you, yielding a `TUI` object with factory methods for widgets.
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-<!-- SYNC:START:examples/verify_quickstart_dsl/app.rb:main -->
-```ruby
-# 1. Initialize the terminal, start the run loop, and ensure the terminal is restored.
-RatatuiRuby.run do |tui|
-  loop do
-    # 2. Create your UI with methods instead of classes.
-    view = tui.paragraph(
-      text: "Hello, Ratatui! Press 'q' to quit.",
-      alignment: :center,
-      block: tui.block(
-        title: "My Ruby TUI App",
-        title_alignment: :center,
-        borders: [:all],
-        border_style: { fg: "cyan" },
-        style: { fg: "white" }
-      )
-    )
-
-    # 3. Use RatatuiRuby methods, too.
-    tui.draw do |frame|
-      frame.render_widget(view, frame.area)
-    end
-
-    # 4. Poll for events with pattern matching
-    case tui.poll_event
-    in { type: :key, code: "q" }
-      break
-    else
-      # Ignore other events
-    end
-  end
-end
-```
-<!-- SYNC:END -->
-<!-- SPDX-SnippetEnd -->
-
-#### How it works
-
-1.  **`RatatuiRuby.run`**: This context manager initializes the terminal before the block starts and ensures `restore_terminal` is called when the block exits (even if an error occurs).
-2.  **Widget Shorthand**: The block yields a `TUI` object (here named `tui`). This object provides factory methods for every widget, allowing you to write `tui.paragraph(...)` instead of the more verbose `RatatuiRuby::Widgets::Paragraph.new(...)`.
-3.  **Method Shorthand**: The `TUI` object also provides aliases for module functions of `RatatuiRuby`, allowing you to write `tui.draw(...)` instead of the more verbose `RatatuiRuby.draw(...)`.
-4.  **Pattern Matching for Events**: Use `case...in` with pattern matching for elegant event dispatch. Always include an `else` clause at the end to catch unmatched event types (mouse, resize, paste, focus, etc.), otherwise Ruby raises `NoMatchingPatternError`.
-
-For a deeper dive into the available application architectures (Manual vs Managed), see [Application Architecture](../concepts/application_architecture.md).
-
-### Adding Layouts
-
-Real-world applications often need to split the screen into multiple areas. `RatatuiRuby::Layout` lets you do this easily.
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-<!-- SYNC:START:examples/verify_quickstart_layout/app.rb:main -->
-```ruby
-loop do
-  tui.draw do |frame|
-    # 1. Split the screen
-    top, bottom = tui.layout_split(
-      frame.area,
-      direction: :vertical,
-      constraints: [
-        tui.constraint_percentage(75),
-        tui.constraint_percentage(25),
-      ]
-    )
-
-    # 2. Render Top Widget
-    frame.render_widget(
-      tui.paragraph(
-        text: "Hello, Ratatui!",
-        alignment: :center,
-        block: tui.block(title: "Content", borders: [:all], border_style: { fg: "cyan" })
-      ),
-      top
-    )
-
-    # 3. Render Bottom Widget with Styled Text
-    # We use a Line of Spans to style specific characters
-    text_line = tui.text_line(
-      spans: [
-        tui.text_span(content: "Press '"),
-        tui.text_span(
-          content: "q",
-          style: tui.style(modifiers: [:bold, :underlined])
-        ),
-        tui.text_span(content: "' to quit."),
-      ],
-      alignment: :center
-    )
-
-    frame.render_widget(
-      tui.paragraph(
-        text: text_line,
-        block: tui.block(title: "Controls", borders: [:all])
-      ),
-      bottom
-    )
-  end
-
-  case tui.poll_event
-  in { type: :key, code: "q" }
-    break
-  else
-    # Ignore other events
-  end
-end
-```
-<!-- SYNC:END -->
-<!-- SPDX-SnippetEnd -->
-
-#### How it works
-
-1.  **`tui.layout_split` (`RatatuiRuby::Layout::Layout.split`)**: Takes an area (like `frame.area`) and splits it into multiple sub-areas based on constraints.
-2.  **`tui.constraint_*` (`RatatuiRuby::Layout::Constraint`)**: Defines how space is distributed (e.g., `percentage`, `length`, `min`, `max`).
-3.  **`Frame#render_widget(widget, rect)`**: You pass the specific area (like `top` or `bottom`) to render the widget into that exact region.
-4.  **`tui.text_span` (`RatatuiRuby::Text::Span`)**: Allows for rich styling within a single line of text.
-
-[![quickstart_layout](../images/verify_quickstart_layout.png)](../../examples/verify_quickstart_layout/README.md)
-
-## Examples
-
-These examples showcase the full power of **ratatui_ruby**. You can find their source code in the [examples directory](../../examples).
-
-### Widget Demos
-
-Focused examples for individual widgets. Each demonstrates a single widget and its configuration options.
-
-| Widget                                                        | What it demonstrates                                       |
-| ------------------------------------------------------------- | ---------------------------------------------------------- |
-| [Bar Chart](../../examples/widget_barchart/app.rb)            | Grouped bars, data visualization, custom bar styling       |
-| [Block](../../examples/widget_block/app.rb)                   | Borders, titles, padding, nested widgets                   |
-| [Box](../../examples/widget_box/app.rb)                       | Block + Paragraph composition, text wrapping               |
-| [Calendar](../../examples/widget_calendar/app.rb)             | Date highlighting, month display, event markers            |
-| [Chart](../../examples/widget_chart/app.rb)                   | Line/scatter plots, axes, legends, datasets                |
-| [Gauge](../../examples/widget_gauge/app.rb)                   | Progress bars, percentage display, unicode blocks          |
-| [Layout Split](../../examples/widget_layout_split/app.rb)     | Constraint types, flex modes, responsive layouts           |
-| [Line Gauge](../../examples/widget_line_gauge/app.rb)         | Horizontal progress, labels, thin-style gauges             |
-| [List](../../examples/widget_list/app.rb)                     | Selection, scrolling, highlight styles, rich text items    |
-| [Map](../../examples/widget_map/app.rb)                       | Canvas widget, world map rendering, coordinates            |
-| [Popup](../../examples/widget_popup/app.rb)                   | Clear widget, modal dialogs, overlay composition           |
-| [Ratatui Logo](../../examples/widget_ratatui_logo/app.rb)     | Decorative branding widget                                 |
-| [Ratatui Mascot](../../examples/widget_ratatui_mascot/app.rb) | ASCII art Ferris mascot                                    |
-| [Rect](../../examples/widget_rect/app.rb)                     | Geometry helpers, area calculations, contains/intersection |
-| [Rich Text](../../examples/widget_rich_text/app.rb)           | Spans, lines, inline styling, mixed colors                 |
-| [Scrollbar](../../examples/widget_scrollbar/app.rb)           | Orientations, thumb/track styling, scroll state            |
-| [Scroll Text](../../examples/widget_scroll_text/app.rb)       | Paragraph scrolling, viewport control, long content        |
-| [Sparkline](../../examples/widget_sparkline/app.rb)           | Mini charts, time series, bar sets                         |
-| [Style Colors](../../examples/widget_style_colors/app.rb)     | Named colors, RGB, indexed 256-color palette               |
-| [Table](../../examples/widget_table/app.rb)                   | Row selection, column widths, per-cell styling             |
-| [Tabs](../../examples/widget_tabs/app.rb)                     | Tab navigation, highlighting, dividers                     |
-| [Text Width](../../examples/widget_text_width/app.rb)         | Unicode-aware width measurement, CJK support               |
-| [Canvas](../../examples/widget_canvas/app.rb)                 | Drawing shapes, markers, custom graphics                   |
-| [Cell](../../examples/widget_cell/app.rb)                     | Buffer cell inspection, styling attributes                 |
-| [Center](../../examples/widget_center/app.rb)                 | Centering content, horizontal/vertical alignment           |
-| [Overlay](../../examples/widget_overlay/app.rb)               | Layering widgets, modal backgrounds                        |
-| [Custom Render](../../examples/widget_render/app.rb)          | Low-level Draw API, escape hatch for custom widgets        |
-
-### Sample Applications
-
-These larger examples combine widgets into complete applications, demonstrating real-world TUI patterns and architectures.
-
-| Application                                                            | Architecture      | What you'll learn                                            |
-| ---------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------ |
-| [All Events](../../examples/app_all_events/app.rb)                     | Model-View-Update | Event handling, unidirectional data flow, scalable structure |
-| [Color Picker](../../examples/app_color_picker/app.rb)                 | Component-Based   | Hit testing, modal dialogs, encapsulated state               |
-| [Debugging Showcase](../../examples/app_debugging_showcase/app.rb)     | Simple Loop       | Remote debugging, Rust backtraces, improved error messages   |
-| [Login Form](../../examples/app_login_form/app.rb)                     | Overlay + Center  | Modal forms, cursor positioning, text input                  |
-| [Stateful Interaction](../../examples/app_stateful_interaction/app.rb) | State Objects     | ListState/TableState, offset read-back, mouse click-to-row   |
-
-#### All Events
-
-[![all_events](../images/app_all_events.png)](../../examples/app_all_events/README.md)
-
-#### Color Picker
-
-[![color_picker](../images/app_color_picker.png)](../../examples/app_color_picker/README.md)
-
-#### Debugging Showcase
-
-[![debugging_showcase](../images/app_debugging_showcase.gif)](../../examples/app_debugging_showcase/README.md)
-
-#### Login Form
-
-[![login_form](../images/app_login_form.png)](../../examples/app_login_form/README.md)
-
-
-## Next Steps
-
-Now that you've seen what **ratatui_ruby** can do:
-
-- **Deep dive**: Read the [Application Architecture](../concepts/application_architecture.md) guide for scaling patterns
-- **Test your TUI**: See the [Testing Guide](../concepts/application_testing.md) for snapshot and style assertions
-- **Avoid common mistakes**: See [Terminal Output During TUI Sessions](../troubleshooting/tui_output.md) to prevent screen corruption
-- **Explore the API**: Browse the [full RDoc documentation](../index.md)
-- **Learn the philosophy**: Read [Why RatatuiRuby?](./why.md) for comparisons and design decisions
-- **Get help**: Join the [discussion mailing list](https://lists.sr.ht/~kerrick/ratatui_ruby-discuss)

data/doc/getting_started/why.md

@@ -1,93 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-# Why RatatuiRuby?
-
-The terminal is having a renaissance. Ruby deserves to be at the forefront.
-
-**RatatuiRuby** is a high-performance, immediate-mode TUI engine that brings the power of Rust's [Ratatui](https://ratatui.rs) library directly into Ruby. No ports. No emulations. A native bridge to the industry-standard Rust crate.
-
-
-## The Pitch
-
-You want to build a terminal UI. You love Ruby. Your options were:
-
-1. **Learn Go** for Bubble Tea
-2. **Learn Rust** for Ratatui
-3. **Use a pure-Ruby library** with limited performance
-
-We built a fourth option: **Write Ruby. Run Rust.**
-
-RatatuiRuby gives you Rust's layout engine, rendering speed, and battle-tested widgets — with Ruby's expressiveness, ecosystem, and joy.
-
-
-## RatatuiRuby vs. CharmRuby
-
-[CharmRuby](https://charm-ruby.dev) is an excellent project by Marco Roth. It provides Ruby bindings to Charm's Go libraries (Bubble Tea, Lipgloss). The Ruby ecosystem is better because both projects exist.
-
-So which one should you choose?
-
-| | CharmRuby | RatatuiRuby |
-|---|-----------|-------------|
-| **Backend** | Go runtime | Rust (no runtime) |
-| **Architecture** | Elm Architecture (MVU) | Immediate-mode + your choice |
-| **GC Behavior** | Two GCs (Ruby + Go) | One GC (Ruby only) |
-| **Rendering** | String manipulation | Constraint-based layout tree |
-| **Best for** | Fans of Bubble Tea, MVU | Native performance, heavy-duty apps |
-
-**What's a runtime?** A runtime is background machinery that a language needs to run. Go has one (for goroutines and garbage collection). Rust doesn't — it compiles to plain machine code. When you use Go bindings, you're running *two* runtimes in the same process (Ruby's and Go's), which adds complexity and memory overhead. With Rust bindings, there's only Ruby.
-
-**Choose CharmRuby** if you prefer Charm's aesthetics or are migrating existing Bubble Tea code.
-
-**Choose RatatuiRuby** if you want zero-overhead native performance and architectural freedom. RatatuiRuby doesn't force a framework — you can build MVU, component-based, or any pattern you prefer.
-
-
-## Why Not Just Write Rust?
-
-Rust is amazing. It's also strict.
-
-The borrow checker enforces memory safety. That's great for systems programming. It's painful for UI iteration. Moving a sidebar, changing a color, or swapping a widget often requires refactoring ownership chains.
-
-With RatatuiRuby, you just change the object. You get Rust's performance where it matters — rendering — and Ruby's flexibility where it counts — designing.
-
-
-## Why Not Just Write Go?
-
-Go is pragmatic. But using Go bindings means running *two* runtimes in the same process: Ruby's and Go's. That adds complexity and memory overhead.
-
-With RatatuiRuby, there's only Ruby. Rust compiles to plain machine code with no runtime — it integrates seamlessly.
-
-
-## Why Ruby?
-
-[Ruby isn't just another language](https://www.ruby-lang.org/en/). It's an ecosystem:
-
-- **[ActiveRecord](https://guides.rubyonrails.org/active_record_basics.html)** — Query your database with elegant, chainable methods
-- **[RSpec](https://rspec.info/)** — Write expressive, readable tests with `describe`, `it`, and `expect`
-- **[Blocks](https://docs.ruby-lang.org/en/4.0/syntax/calling_methods_rdoc.html#label-Block+Argument)** — Pass behavior to methods with `do...end`, the heart of Ruby's expressiveness
-- **[Metaprogramming](https://docs.ruby-lang.org/en/4.0/Module.html#method-i-class_eval)** — Define methods dynamically, build DSLs, and write code that writes code
-- **[Bundler](https://bundler.io/)** — Access 180,000+ gems with a single `bundle add`
-
-Build a dashboard for your Rails app. Monitor your Sidekiq jobs. Create developer tools in the same language as the code they inspect.
-
-
-## The Philosophy: A Solid Foundation
-
-RatatuiRuby is a **low-level engine**. It provides raw primitives — Layouts, Blocks, Text, Tables, Charts — to build anything.
-
-It doesn't force a framework on you. You can use:
-- **Model-View-Update** for dashboards and data displays
-- **Component-based** patterns for interactive tools
-- **Your own architecture** for everything else
-
-This is the foundation for Ruby's next generation of TUI tools, dashboards, and interactive scripts.
-
-
-## Get Started
-
-Ready to build?
-
-- [Quickstart Guide](./quickstart.md) — Your first app in 5 minutes
-- [Widget Gallery](./quickstart.md#widget-demos) — See what's possible
-- [Application Architecture](../concepts/application_architecture.md) — Patterns for scaling