ratatui_ruby 1.0.0 → 1.0.1

data/doc/concepts/event_handling.md

@@ -1,162 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Event Handling
-
-`ratatui_ruby` provides a rich, object-oriented event system that supports multiple coding styles, from simple boolean predicates to modern Ruby pattern matching.
-
-Events are retrieved using `RatatuiRuby.poll_event`. This method returns an instance of a subclass of `RatatuiRuby::Event` (e.g., `RatatuiRuby::Event::Key`, `RatatuiRuby::Event::Mouse`). When no event is available, it returns `RatatuiRuby::Event::None`—a [null object](https://martinfowler.com/eaaCatalog/specialCase.html) that safely responds to all event predicates with `false`.
-
-## 1. Blocking vs. Polling
-
-Most applications run in a loop (e.g., a game loop or UI loop). To prevent high CPU usage, the loop should wait briefly for input.
-
-*   **Default (Polling):** `RatatuiRuby.poll_event` (no args) waits for **0.016s** (approx 60 FPS). If no event occurs, it returns `RatatuiRuby::Event::None`. This keeps the application responsive.
-*   **Blocking:** `RatatuiRuby.poll_event(timeout: nil)` waits **forever** until an event occurs. Use this for scripts that only react to input and do not need to update the UI on a timer.
-*   **Non-Blocking:** `RatatuiRuby.poll_event(timeout: 0.0)` returns immediately.
-
-## 2. Symbol and String Comparison (Simplest)
-
-For simple key events, `RatatuiRuby::Event::Key` objects can be compared directly to Symbols or Strings. This is often the quickest way to get started.
-
-*   **String**: Matches the key character (e.g., "a", "q").
-*   **Symbol**: Matches special keys (e.g., `:enter`, `:esc`) or modifier combinations (e.g., `:ctrl_c`).
-
-> [!NOTE]
-> On macOS, the **Option** key is mapped to `alt`. The **Command** key is typically intercepted by the terminal emulator and may not be sent to the application, or it may be mapped to Meta/Alt depending on your terminal settings.
-
-For a complete list of supported keys, modifiers, and event types, please refer to the [API Documentation for RatatuiRuby::Event](file:///Users/kerrick/Developer/ratatui_ruby/lib/ratatui_ruby/event.rb).
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2025 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-event = RatatuiRuby.poll_event
-
-# 1. Check for quit keys
-if event == "q" || event == :ctrl_c
-  break
-end
-
-# 2. Check for special key
-if event == :enter
-  submit_form
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-## 3. Predicate Methods (Intermediate)
-
-If you need more control or logic (e.g. `if/elsif`), or need to handle non-key events like Resize or Mouse, use the predicate methods.
-
-### Polymorphic Predicates
-
-Safe to call on *any* event object. They return `true` only for the matching event type.
-
-Available: `key?`, `mouse?`, `resize?`, `paste?`, `focus_gained?`, `focus_lost?`.
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2025 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-event = RatatuiRuby.poll_event
-
-if event.key?
-  handle_keypress(event)
-elsif event.mouse?
-  handle_click(event)
-elsif event.resize?
-  resize_layout(event.width, event.height)
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-### Helper Predicates
-
-Specific to certain event classes to simplify checks.
-
-#### `RatatuiRuby::Event::Key`
-*   `ctrl?`, `alt?`, `shift?`: Check if modifier is held.
-*   `text?`: Returns `true` if the event is a printable character (length == 1).
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2025 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-if event.key? && event.ctrl? && event.code == "s"
-  save_file
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-#### `RatatuiRuby::Event::Mouse`
-*   `down?`, `up?`, `drag?`: Check mouse action.
-*   `scroll_up?`, `scroll_down?`: Check scroll direction.
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2025 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-if event.mouse? && event.scroll_up?
-  scroll_view(-1)
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-## 4. Pattern Matching (Powerful)
-
-For complex applications, Ruby 3.0+ Pattern Matching with the `type:` discriminator is the most idiomatic and concise approach.
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2025 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-loop do
-  case RatatuiRuby.poll_event
-  
-  # Match specific key code
-  in type: :key, code: "q"
-    break
-
-  # Match complex combo
-  in type: :key, code: "c", modifiers: ["ctrl"]
-    break
-
-  # Capture variables
-  in type: :key, code: "up" | "down" => direction
-    move_cursor(direction)
-
-  # Match mouse events
-  in type: :mouse, kind: "down", x:, y:
-    handle_click(x, y)
-
-  in type: :none
-    # No event available, continue loop
-  end
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-## Summary of Event Classes
-
-| Event Class | Discriminator (`type:`) | Attributes | Predicate |
-| :--- | :--- | :--- | :--- |
-| `RatatuiRuby::Event::Key` | `:key` | `code`, `modifiers` | `key?` |
-| `RatatuiRuby::Event::Mouse` | `:mouse` | `kind`, `x`, `y`, `button`, `modifiers` | `mouse?` |
-| `RatatuiRuby::Event::Resize` | `:resize` | `width`, `height` | `resize?` |
-| `RatatuiRuby::Event::Paste` | `:paste` | `content` | `paste?` |
-| `RatatuiRuby::Event::FocusGained` | `:focus_gained` | (none) | `focus_gained?` |
-| `RatatuiRuby::Event::FocusLost` | `:focus_lost` | (none) | `focus_lost?` |
-| `RatatuiRuby::Event::None` | `:none` | (none) | `none?` |

data/doc/concepts/interactive_design.md

@@ -1,146 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Interactive TUI Design Patterns
-
-Canonical patterns for building responsive, interactive terminal user interfaces with ratatui_ruby.
-
-## The Cached Layout Pattern
-
-**Context:** In immediate-mode TUI development, you render once per event loop. The render happens, the user clicks, you respond. This cycle repeats 60 times a second.
-
-**Problem:** Your layout has constraints. When you render, you calculate where each widget goes. When the user clicks, you need to know which widget was under the cursor. Two separate calculations means two separate constraint definitions. Change the layout once and forget to update the hit test logic—bugs happen.
-
-**Solution:** Calculate layout once. Cache the results. Reuse them everywhere.
-
-### The Three-Phase Lifecycle
-
-Structure your event loop into three clear phases:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-def run
-  RatatuiRuby.run do |tui|
-    @tui = tui
-    loop do
-      @tui.draw do |frame|
-        calculate_layout(frame.area) # Phase 1: Geometry (once per frame)
-        render(frame)                # Phase 2: Draw
-      end
-      break if handle_input == :quit  # Phase 3: Input
-    end
-  end
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-**Phase 1: Layout Calculation**
-
-Call this inside your `draw` block. It uses the current terminal area provided by the frame:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-def calculate_layout(area)
-  # Main area vs sidebar (70% / 30%)
-  main_area, @sidebar_area = @tui.layout_split(
-    area,
-    direction: :horizontal,
-    constraints: [
-      @tui.constraint_percentage(70),
-      @tui.constraint_percentage(30),
-    ]
-  )
-
-  # Within main area, left vs right panels
-  @left_rect, @right_rect = @tui.layout_split(
-    main_area,
-    direction: :horizontal,
-    constraints: [
-      @tui.constraint_percentage(@left_ratio),
-      @tui.constraint_percentage(100 - @left_ratio)
-    ]
-  )
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-**Phase 2: Rendering**
-
-Reuse the cached rects. Build and draw:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-def render(frame)
-  frame.render_widget(build_widget(@left_rect), @left_rect)
-  frame.render_widget(build_widget(@right_rect), @right_rect)
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-**Phase 3: Event Handling**
-
-Reuse the cached rects. Test clicks:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2025 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-def handle_input
-  event = RatatuiRuby.poll_event
-
-  case event
-  in type: :mouse, kind: "down", x:, y:
-    if @left_rect.contains?(x, y)
-      handle_left_click
-    elsif @right_rect.contains?(x, y)
-      handle_right_click
-    end
-  else
-    nil
-  end
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-### Why This Matters
-
-- **Single source of truth:** Change constraints once. They apply everywhere.
-- **No duplication:** Write `Layout.split(area, constraints:)` once. Use the result in render and input.
-- **Testable:** Layout geometry is explicit. You can verify it.
-- **Foundation for components:** In Gem 1.5, the `Component` class automates this caching. This pattern teaches the mental model.
-
-## Layout.split
-
-`Layout.split` computes layout geometry without rendering. It returns an array of `Rect` objects. While you can call `RatatuiRuby::Layout.split` directly, we recommend using the `TUI` helper (`tui.layout_split`) for cleaner application code.
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-# Preferred (TUI API)
-left, right = tui.layout_split(area, constraints: [...])
-
-# Manual (Core API)
-left, right = RatatuiRuby::Layout.split(area, constraints: [...])
-```
-<!-- SPDX-SnippetEnd -->
-
-Use it to establish the single source of truth inside your `draw` block. Store the results in instance variables and reuse them in both `render` and `handle_input`.

data/doc/contributors/auditing/parity.md

@@ -1,239 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Parity Auditing Process
-
-This guide describes the **process** for auditing RatatuiRuby against upstream Rust Ratatui to find API parity gaps of any kind.
-
-## Philosophy
-
-RatatuiRuby should behave identically to Rust Ratatui. When a Rust user can do something with a widget, a Ruby user should be able to do the equivalent. Deviations are bugs.
-
-## The Audit Mindset
-
-### Ask the Right Questions
-
-Every audit begins with a question:
-
-- "Does RatatuiRuby support everything upstream supports for widget X?"
-- "When I pass type Y to parameter Z, does Ruby do what Rust does?"
-- "Are there features in upstream that we haven't exposed at all?"
-
-### Symptoms That Trigger Audits
-
-- **Inspect strings in output** (`#<data RatatuiRuby::...>`) — type conversion failure
-- **Missing methods** — user can't access upstream functionality
-- **Wrong behavior** — code runs but produces different results than Rust
-- **Type mismatches** — Ruby API accepts different types than Rust API
-
-## The Three-Layer Model
-
-Every RatatuiRuby feature has three layers. Gaps can occur at any layer:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```
-┌─────────────────────────────┐
-│  Ruby API (lib/**/*.rb)    │  ← What users see
-├─────────────────────────────┤
-│  Rust Bindings (ext/**/*.rs)│  ← Bridge layer
-├─────────────────────────────┤
-│  Upstream Ratatui          │  ← Source of truth
-└─────────────────────────────┘
-```
-<!-- SPDX-SnippetEnd -->
-
-### Layer 1: Ruby API Gaps
-Ruby doesn't expose a parameter that upstream supports.
-
-### Layer 2: Binding Gaps  
-Ruby exposes a parameter, but the Rust binding converts it incorrectly.
-
-### Layer 3: Upstream Changes
-New upstream features we haven't implemented yet.
-
-## Audit Process
-
-### 1. Choose an Audit Scope
-
-Define what you're auditing:
-- **Single widget**: All parameters of `Tabs`
-- **Single feature**: All places that accept styled text
-- **Version delta**: Everything new in Ratatui 0.29
-
-### 2. Establish Source of Truth
-
-For any scope, identify the authoritative upstream source:
-- **Method signatures** → Rust source files
-- **Type constraints** → Generic bounds (`Into<Line>`, `&str`, etc.)
-- **Behavior** → Upstream documentation and tests
-
-### 3. Inventory Our Implementation
-
-List everything in our codebase related to the scope:
-- Ruby classes and methods
-- Rust binding functions
-- Conversion/parsing logic
-
-### 4. Compare Systematically
-
-For each item in the upstream source of truth, ask:
-1. Do we expose this at all?
-2. If yes, does our implementation match the type signature?
-3. If yes, does our behavior match?
-
-### 5. Document Findings
-
-For each gap found, record:
-- What the gap is
-- Where it occurs (files, lines)
-- What upstream expects
-- What we currently do
-
-### 6. Fix and Verify
-
-Apply fixes, then verify:
-- Compiles without errors
-- Tests pass
-- Visual/manual verification if applicable
-
-## Verifying Completeness
-
-Finding gaps is not enough. You must verify you've found **all** gaps within your scope.
-
-### The Completeness Mindset
-
-An initial audit pass often finds the obvious issues. But "obvious" means "incomplete." After your first pass, stop and ask:
-
-- Did I search for **every variation** of the pattern I was looking for?
-- Are there **synonyms or related terms** I should also search?
-- Did I check **all code paths**, not just the happy path?
-- Are there **duplicate implementations** (e.g., `render` vs `render_stateful`)?
-
-### Broaden Your Search Terms
-
-Your first search term won't catch everything. For each pattern, think of variations:
-
-| If you searched for... | Also search for... |
-|------------------------|-------------------|
-| `funcall("to_s"` | `String::try_convert` |
-| `Into<Line>` | `Into<Span>`, `Into<Text>` |
-| One widget's file | All widget files |
-| The method you're fixing | Related methods in the same file |
-
-### Work From the Complete List
-
-Don't spot-check. Generate the **complete list** of potential issues, then classify each one:
-
-1. Run a search that catches all possible instances
-2. Count them (e.g., "31 `to_s` call sites")
-3. Review **every single one**, marking each as "gap" or "correct"
-
-Half-measures lead to half-fixes.
-
-### Verify Against Upstream Exhaustively
-
-For type-related gaps, don't just check the methods you already know about. Search upstream for **all uses of the pattern**:
-
-- `grep -rn 'Into<Line' /path/to/ratatui/src/widgets` finds EVERY place upstream accepts `Line`
-- Then verify we handle EACH of those correctly
-
-### Question Your Assumptions
-
-After completing your audit, challenge yourself:
-
-- "Is there anywhere I should look that I haven't?"
-- "Is there any term I should search that I haven't?"
-- "Am I sure I didn't miss anything?"
-
-If you can't answer confidently, keep searching.
-
-### The "One More Pass" Rule
-
-When you think you're done, do one more verification pass with a different approach:
-
-- If you searched our code first, now search upstream first
-- If you searched for method names, now search for type signatures
-- If you audited file-by-file, now audit feature-by-feature
-
-This catches gaps your initial framing missed.
-
-
-## Search Strategies
-
-Different gap types require different search approaches:
-
-### Finding Type Conversion Gaps
-
-Look for places where we convert Ruby objects to simpler types:
-- `funcall("to_s", ...)` — converting to string
-- `String::try_convert(...)` — same
-- `u16::try_convert(...)` — numeric conversion
-
-Then check: does upstream accept richer types?
-
-### Finding Missing Features
-
-Compare file structure:
-- What files/modules exist upstream?
-- What methods exist in each upstream struct?
-- What parameters does each upstream method accept?
-
-### Finding Behavioral Differences
-
-Run equivalent code in both environments and compare output.
-
-## Red Flags in Our Code
-
-When reviewing RatatuiRuby code, these patterns suggest potential gaps:
-
-| Pattern | Potential Gap |
-|---------|---------------|
-| `funcall("to_s", ...)` | Upstream may accept styled types |
-| `usize` or `u16` for padding | Upstream may accept content types |
-| Missing `parse_*` call before using a value | Type not being converted properly |
-| Widget with fewer Ruby methods than Rust methods | Missing functionality |
-| `// TODO` or `// FIXME` comments | Known gaps |
-
-## Upstream Patterns to Watch For
-
-When reading upstream Rust code, these signatures indicate rich type support:
-
-| Rust Signature | Meaning | Ruby Should Accept |
-|----------------|---------|-------------------|
-| `Into<Span<'a>>` | Styled single fragment | `Text::Span` or `String` |
-| `Into<Line<'a>>` | Styled line | `Text::Line`, `Text::Span`, or `String` |
-| `Into<Text<'a>>` | Multi-line styled | `Text::Text`, `Text::Line`, or `String` |
-| `T: AsRef<str>` | Any string-like | `String` (OK) |
-| `&'a str` | String slice | `String` (OK) |
-
-## Keeping Audits Maintainable
-
-### Create Checklists
-
-For each widget or feature area, maintain a checklist of all parameters with their expected types.
-
-### Track Upstream Changes
-
-When upgrading Ratatui versions:
-1. Read the changelog
-2. Search for new `pub fn` in widget files
-3. Audit new functionality before exposing it
-
-### Automate Where Possible
-
-Consider tooling that:
-- Compares upstream method counts to ours
-- Flags new `to_s` calls in code review
-- Tests styled content rendering
-
-## Example Audit Narrative
-
-> "I noticed inspect strings appearing in my tabs. I asked: 'What types does upstream accept for the divider parameter?' I found `Into<Span>`. I then asked: 'What does our binding do?' I found we call `to_s`. Gap identified."
-
-This narrative approach—asking questions, finding answers, comparing—works for any parity issue.