ratatui_ruby 1.0.0 → 1.0.1

data/doc/contributors/developing_examples.md

@@ -1,400 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Developing Examples
-
-Guidelines for creating and testing examples in the `examples/` directory.
-
-## Example Structure
-
-Every interactive example should follow this pattern, living in its own directory:
-
-`examples/my_example/app.rb`:
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2025 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
-require "ratatui_ruby"
-
-class MyExampleApp
-  def initialize
-    # Initialize state (styles must be initialized in run when @tui is available)
-  end
-
-  def run
-    RatatuiRuby.run do |tui|
-      @tui = tui  # Store for use in private methods
-      loop do
-        render
-        break if handle_input == :quit
-      end
-    end
-  end
-
-  private
-
-  def render
-    @tui.draw do |frame|
-      # 1. Split layout using Session helpers
-      areas = @tui.layout_split(frame.area, constraints: [@tui.constraint_fill(1)])
-      # 2. Create and render widgets
-      widget = @tui.paragraph(text: "Hello", block: @tui.block(borders: [:all]))
-      frame.render_widget(widget, areas[0])
-    end
-  end
-
-  def handle_input
-    case @tui.poll_event
-    in { type: :key, code: "q" }
-      :quit
-    in { type: :key, code: code }
-      # Handle other keys
-    else
-      # Ignore unhandled events
-    end
-  end
-end
-
-MyExampleApp.new.run if __FILE__ == $PROGRAM_NAME
-```
-<!-- SPDX-SnippetEnd -->
-
-### Naming Convention (Required)
-
-Example directories **must** follow a prefixing convention to categorize them alphabetically:
-- `app_`: Application showcases (e.g., `app_analytics`). Class name: `AppAnalytics`.
-- `widget_`: Widget-focused demonstrations (e.g., `widget_gauge`). Class name: `WidgetGaugeDemo`.
-- `verify_`: Documentation verification examples (e.g., `verify_readme_usage`). Class name: `VerifyReadmeUsage`.
-
-The directory and class names must match (snake_case directory maps to PascalCase class).
-
-This convention enables the `terminal_preview:update` rake task to automatically capture terminal output for all examples without maintaining a manual registry.
-
-### Terminal Size Constraint
-
-All interactive examples must fit within an **80×24 terminal** (standard VT100 dimensions). This ensures:
-- Examples work on minimal terminal configurations
-- Tests can use the default `with_test_terminal` size (80x24)
-- Examples remain discoverable and self-documenting through visible hotkey help
-
-**Layout pattern for 80×24:**
-- **Bottom control panel:** Allocate ~5-7 lines at bottom for a full-width control block with hotkey documentation. Style hotkeys with **bold and underline** to make them discoverable. Use double-space or pipe separators to compress multiple controls per line. This keeps all UI text at full readability while maximizing space for the main content area.
-
-**Best practices:**
-- Use descriptive names (e.g., "Yellow on Black" not "Yellow") so controls are self-documenting and discoverable.
-- **Style hotkeys visually:** Use `modifiers: [:bold, :underlined]` on hotkey letters to make them stand out from descriptions. Example: `i` (bold, underlined) followed by `Items`.
-- Test early by running the example at 80×24 and verifying all content is visible without wrapping, scrolling, or clipping.
-
-## Type Signatures
-
-Every example must also have an RBS file documenting its public methods. Type signatures live in a centralized location:
-
-`sig/examples/my_example/app.rbs`:
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2025 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```rbs
-class MyExampleApp
-  # @public
-  def self.new: () -> MyExampleApp
-
-  # @public
-  def run: () -> void
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-## Directory Structure
-
-Examples are organized across three locations:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```
-examples/
-  my_example/
-    app.rb              ← REQUIRED: The runnable example code
-    README.md           ← REQUIRED: Purpose, architecture, hotkeys, usage
-
-test/examples/
-  my_example/
-    test_app.rb         ← REQUIRED: Tests (centralized, not local to example)
-    snapshots/          ← Auto-created by snapshot assertions
-      initial_render.txt
-
-sig/examples/
-  my_example/
-    app.rbs             ← REQUIRED: Type signatures (centralized, not local to example)
-```
-<!-- SPDX-SnippetEnd -->
-
-### Key Requirements
-
-1. **Only `run` should be public.** All other methods (`render`, `handle_input`, helper methods) must be private. This prevents tests from calling internal methods directly.
-
-2. **Use `RatatuiRuby.run` for terminal management.** Never call `init_terminal` or `restore_terminal` directly. The `run` block handles terminal setup/teardown automatically and safely, even if an exception occurs.
-
-3. **Use the TUI API (`tui`) for cleaner code.** Accept the `tui` block parameter from `RatatuiRuby.run` and use it throughout your app:
-   - `@tui.draw { |frame| ... }` instead of `RatatuiRuby.draw`
-   - `@tui.poll_event` instead of `RatatuiRuby.poll_event`
-   - `@tui.style(...)` instead of `RatatuiRuby::Style::Style.new(...)`
-   - `@tui.paragraph(...)` instead of `RatatuiRuby::Widgets::Paragraph.new(...)`
-   - `@tui.block(...)` instead of `RatatuiRuby::Widgets::Block.new(...)`
-   - `@tui.layout_split(...)` instead of `RatatuiRuby::Layout.split(...)`
-   - `@tui.constraint_fill(...)` instead of `RatatuiRuby::Layout::Constraint.fill(...)`
-   - `@tui.text_line(...)` instead of `RatatuiRuby::Text::Line.new(...)`
-   - `@tui.text_span(...)` instead of `RatatuiRuby::Text::Span.new(...)`
-
-4. **Event handling must include a catch-all pattern.** When using pattern matching in `handle_input`, always include an `else` clause at the end to catch unmatched events (mouse events, resize events, focus events, etc.). Without it, unmatched events will raise `NoMatchingPatternError`:
-
-   ```ruby
-   def handle_input
-     case @tui.poll_event
-     in { type: :key, code: "q" }
-       :quit
-     in { type: :mouse, kind: "down", x:, y: }
-       handle_click(x, y)
-     else
-       # Ignore other events
-     end
-   end
-
-5. **Use keyboard keys to cycle through widget attributes.** Users should be able to interactively explore all widget options. Common patterns:
-    - Arrow keys: Navigate or adjust values
-    - Letter keys: Cycle through styles, modes, or variants. Prefer all lowercase keys to avoid confusion and simplify the UI description.
-    - Space: Toggle or select
-    - `q` or Ctrl+C: Quit
-
-6. **All examples must include a README.md** explaining:
-   - What problem the example solves
-   - Architecture (if applicable)
-   - Hotkeys (if interactive): Document all keyboard/mouse controls
-   - Key concepts demonstrated
-   - Usage instructions
-   - Learning outcomes
-
-   See examples/app_color_picker/README.md and examples/app_all_events/README.md for patterns. Adhere to docs/contributors/documentation_style.md.
-
-7. **Naming Conventions for Controls**
-
-When documenting hotkeys and cycling options in the UI, use consistent naming:
-
-- **Parameter names:** Always match the actual Ruby parameter name. For example:
-  - Use "Scroll Padding" (not "Scroll Pad") for the `scroll_padding:` parameter
-  - Use "Highlight Style" (not "Highlight") for the `highlight_style:` parameter
-  - Use "Repeat Symbol" (not "Repeat") for the `repeat_highlight_symbol:` parameter
-  
-- **Display names for cycled values:** Create a `name` field in your options hash to keep display names paired with values. Initialize style arrays inside `run` when `@tui` is available:
-  ```ruby
-  # In run method, after @tui = tui:
-  @styles = [
-    { name: "Yellow Bold", style: @tui.style(fg: :yellow, modifiers: [:bold]) },
-    { name: "Blue on White", style: @tui.style(fg: :blue, bg: :white) }
-  ]
-  
-  # In controls: "h: Highlight Style (#{@styles[@style_index][:name]})"
-  # Outputs: "h: Highlight Style (Yellow Bold)"
-  ```
-
-This keeps the UI self-documenting and users can see exact parameter names when they read the hotkey help.
-
-8. **Hit Testing**
-
-Examples with mouse interaction should use the **Frame API**. By calling `@tui.layout_split` inside `@tui.draw`, you obtain the exact `Rect`s used for rendering. Store these rects in instance variables (e.g., `@sidebar_rect`) to use them in your `handle_input` method for hit testing:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2025 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-if @sidebar_rect&.contains?(event.x, event.y)
-  # Handle click
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-## Testing Examples
-
-Example tests live in a centralized test tree:
-
-`test/examples/my_example/test_app.rb`:
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
-require "ratatui_ruby"
-require "ratatui_ruby/test_helper"
-require "minitest/autorun"
-require_relative "app"
-
-class TestMyExampleApp < Minitest::Test
-  include RatatuiRuby::TestHelper
-
-  def setup
-    @app = MyExampleApp.new
-  end
-
-  def test_initial_render
-    with_test_terminal do
-      inject_key(:q)
-      @app.run
-      assert_snapshots("initial_render")
-    end
-  end
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-## Snapshot Testing Pattern (REQUIRED)
-
-All example tests MUST use snapshot testing via the `assert_snapshots` API, not manual content assertions.
-
-### Why Snapshots
-
-- **Exact verification:** Captures complete screen state, character-by-character
-- **Auto-update:** `UPDATE_SNAPSHOTS=1 bin/agent_rake test` regenerates all snapshots
-- **Auto-managed:** Snapshots live in `test/examples/{name}/snapshots/{test_name}.txt`
-- **Maintainable:** No tedious manual string checks
-- **Self-documenting:** Snapshots show exactly what output is expected
-
-### Basic Pattern
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-def test_initial_render
-  with_test_terminal do
-    inject_key(:q)
-    @app.run
-    
-    assert_snapshots("initial_render")
-  end
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-Snapshot auto-saved to: `test/examples/widget_foo/snapshots/initial_render.txt`
-
-### With Normalization (for dynamic content)
-
-For examples with timestamps, random data, or other non-deterministic output:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-private def assert_normalized_snapshots(snapshot_name)
-  assert_plain_snapshot(snapshot_name) do |actual|
-    actual.map do |line|
-      line.gsub(/\d{2}:\d{2}:\d{2}/, "XX:XX:XX")  # Mask timestamps
-           .gsub(/Random ID: \d+/, "Random ID: XXX")  # Mask random values
-    end
-  end
-end
-
-def test_after_event
-  with_test_terminal do
-    inject_key("a")
-    inject_key(:q)
-    @app.run
-    
-    assert_normalized_snapshots("after_event")
-  end
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-See `test/examples/app_all_events/test_app.rb` for a complete example.
-
-### Regenerating Snapshots
-
-When UI changes are intentional, regenerate all snapshots:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-UPDATE_SNAPSHOTS=1 bin/agent_rake test
-```
-<!-- SPDX-SnippetEnd -->
-
-## Widget Attribute Cycling
-
-Examples should demonstrate widget configurability by allowing interactive cycling:
-
-| Widget | Attribute | Key Suggestion |
-|--------|-----------|----------------|
-| Tabs | highlight_style | Space |
-| Tabs | divider | d |
-| Tabs | style | s |
-| Block | border_type | Space |
-| Block | border_color | c |
-| List | highlight_style | Space |
-| Sparkline | direction | d |
-| Scrollbar | orientation | o |
-| Scrollbar | theme | s |
-
-Display the current state in the UI (e.g., in a title or status bar or paragraph) so users can see what changed. Display the hotkey in the UI as well, so users can see how to change it; the hotkey should not disappear as app state changes.
-
-## Data Quality
-
-Examples must use **realistic, meaningful data**—not dummy placeholder text. This ensures examples:
-- Demonstrate the widget's real-world usage
-- Provide educational value to users reading the code
-- Look professional and polished
-
-### Guidelines
-
-**For small datasets (< 10 items):**
-Use hardcoded realistic data. Examples:
-- Geographic coordinates with city names (see `widget_map/app.rb`)
-- Real product names or person names
-- Meaningful status values ("Completed", "Pending", "Failed")
-
-**For large datasets (≥ 10 items):**
-Use the [Faker](https://github.com/faker-ruby/faker) gem with **deterministic seeding** so data is consistent across runs:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-require "faker"
-
-# Seed Faker for reproducible output
-Faker::Config.random = Random.new(12345)
-
-# Generate realistic data
-users = Array.new(50) { Faker::Name.name }
-emails = Array.new(50) { Faker::Internet.email }
-```
-<!-- SPDX-SnippetEnd -->
-
-In tests, set the same seed before each test to ensure snapshot consistency.
-
-**Avoid:**
-- Repeated placeholder text like "Lorem ipsum" or "Background Layer" × 20
-- Generic numbered items like "Item 1", "Item 2" (unless the context demands it)
-- Nonsensical or visually jarring content

data/doc/contributors/documentation_style.md

@@ -1,121 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Documentation Style Guide
-
-This project follows a strict and specific documentation style designed to be helpful, readable, and consistent. It combines the structural clarity of Christopher Alexander's Pattern Language with the prose style of William Zinsser's *On Writing Well* and the usability of the U.S. Federal Plain Language Guidelines.
-
-**All agents and contributors must adhere to these standards.**
-
-## 1. Core Philosophy
-
-*   **Context, Problem, Solution (Alexandrian Form):** Do not just say *what* a class does. Explain *why* it exists. Start with the context, state the problem (the pain point without this tool), and then present the class as the solution.
-*   **Prose Style (Zinsser/Klinkenborg):** Use short, punchy sentences. Use active voice. Cut unnecessary words. Avoid "allow," "enable," "provide," "support," "functionality," and "capability" where possible. Weak verbs hide the action. Strong verbs drive the sentence.
-*   **User-Centric (Plain Language):** Speak directly to the user ("You"). Don't abstract them away ("The developer"). Focus on their goals and how this tool helps them achieve those goals.
-*   **Tone (Supportive and Authoritative, not Hostile or Prescriptive):** Avoid "must," "requires," "need to," or "mandatory." These words sound bossy. Treat the user as a capable peer. Instead of "You must do X," use imperative "Do X" or cause-and-effect "X ensures Y."
-
-## 2. Class Documentation
-
-Every public class must begin with a **Context-Problem-Solution** narrative.
-
-### Structure
-
-1.  **Summary Line:** A single line explaining the class's role.
-2.  **Context (Narrative):** A short paragraph establishing the domain or situation.
-3.  **Problem (Narrative):** A sentence or two identifying the specific difficulty, complexity, or "pain" the user faces in this context without the widget.
-4.  **Solution (Narrative):** A sentence explaining how this widget solves that problem, often starting with "This widget..." or "Use it to...".
-5.  **Usage (Narrative):** A concrete "Use it to..." sentence listing common applications.
-6.  **Example:** A comprehensive, copy-pasteable code example using `=== Examples`. Provide **multiple** examples to cover different use cases (e.g., basic usage vs. advanced configuration).
-
-### Example
-
-**Bad (Generic/Descriptive):**
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2025 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-# A widget for displaying list items.
-# It allows the user to select an item from an array of strings.
-# Supports scrolling and custom styling.
-```
-<!-- SPDX-SnippetEnd -->
-
-**Good (Alexandrian/Zinsser/Plain Language):**
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2025 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-# Displays a selectable list of items.
-#
-# Users need to choose from options. Menus, file explorers, and selectors are everywhere.
-# Implementing navigation, highlighting, and scrolling state from scratch is tedious.
-#
-# This widget manages the list. It renders the items. It highlights the selection. It handles the scrolling window.
-#
-# Use it to build main menus, navigation sidebars, or logs.
-```
-<!-- SPDX-SnippetEnd -->
-
-## 3. Method and Attribute Documentation
-
-### Prose Style
-
-*   **Attributes:** Use concise noun phrases. Avoid "This attribute returns..." or "Getter for...".
-    *   *Bad:* "This is the width of the widget."
-    *   *Good:* "Width of the widget in cells."
-*   **Methods:** Use active, third-person present tense verbs.
-    *   *Bad:* "Will calculate the total."
-    *   *Good:* "Calculates the total."
-*   **Context:** For complex methods, you may use a condensed version of the Context-Problem-Solution pattern, but keep it brief.
-
-### Syntax Standards
-
-*   **Examples:** All public methods must include at least one usage example. Use `=== Example`.
-*   **Attributes:** Use `attr_reader` with documentation comments immediately preceding them.
-*   **Parameters:** Use strict RDoc definition lists `[name] description` for parameters in the `initialize` method.
-*   **Formatting:** Use `<tt>` tags for code literals, symbols, and values (e.g., `<tt>:vertical</tt>`).
-    *   Do **not** use backticks (\`) or markdown-style links `[text](url)`. RDoc does not render them correctly in all contexts.
-    *   Do **not** use smart quotes.
-
-### Example
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2025 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-  # The styling to apply to the content.
-  attr_reader :style
-
-  # Creates a new List.
-  #
-  # [items] Array of Strings.
-  # [selected_index] Integer (nullable).
-  def initialize(items: [], selected_index: nil)
-    super
-  end
-```
-<!-- SPDX-SnippetEnd -->
-
-## 4. RDoc Specifics
-
-*   **No Endless Methods:** Do **not** use Ruby 3.0+ endless method definitions (`def foo = bar`). RDoc currently has a bug where it fails to correctly parse the end of the method, causing subsequent methods to be nested incorrectly in the documentation tree. Always use standard `def ... end` blocks.
-*   **No YARD:** Do not use `@param`, `@return`, or other YARD tags. Use standard RDoc formats.
-*   **Directives:** Use `:nodoc:` for private or internal methods that should not appear in the API docs.
-*   **Headings:** Use `===` for section headers like `=== Examples`.
-
-## 5. Checklist for Agents
-
-Before finalizing documentation, ask:
-1.  Did I explain the *problem* this code solves?
-2.  Are my sentences short and active? (Did I remove "allows the user to"?)
-3.  Is the code example valid and copy-pasteable?
-4.  Did I use `<tt>` for symbols and code values?
-5.  Did I document every attribute and parameter?

data/doc/contributors/index.md

@@ -1,21 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-# **ratatui_ruby** Contributors’ Documentation
-
-
-## Documentation for Contributors
-
-- [Contributing Guidelines](https://man.sr.ht/~kerrick/ratatui_ruby/contributing.md): Issues, pull requests, and development setup
-- [Documentation Guide](https://man.sr.ht/~kerrick/ratatui_ruby/documentation_guide.md): Where to document (RDoc, repo docs, wiki)
-- [The Design of **ratatui_ruby**](./design.md): Architecture overview
-  - [Ruby Frontend Design](./design/ruby_frontend.md): Two-layer architecture, TUI facade, data-driven UI
-  - [Rust Backend Design](./design/rust_backend.md): Rendering pipeline, namespace dispatch, magnus integration
-
-
-
-## Documentation for Users
-
-- [README](../../README.md): Project overview and installation
-- [More Documentation for Users](../index.md): Full user documentation index