ratatui_ruby 0.3.1 → 0.4.0

data/doc/contributors/developing_examples.md

@@ -0,0 +1,203 @@
+<!--
+SPDX-FileCopyrightText: 2025 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`:
+```ruby
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+require "ratatui_ruby"
+
+class MyExampleApp
+  def initialize
+    # Initialize state
+  end
+
+  def run
+    RatatuiRuby.run do
+      loop do
+        render
+        break if handle_input == :quit
+      end
+    end
+  end
+
+  private
+
+  def render
+    # Build and draw UI
+    RatatuiRuby.draw(layout)
+  end
+
+  def handle_input
+    event = RatatuiRuby.poll_event
+    # Process event, return :quit to exit
+  end
+end
+
+MyExampleApp.new.run if __FILE__ == $PROGRAM_NAME
+```
+
+### Naming Convention (Required)
+
+Example classes **must** follow the naming convention:
+- **Directory:** `examples/my_example/` (snake_case)
+- **Class:** `MyExampleApp` (PascalCase with `App` suffix)
+
+The class name is derived from the directory name: `my_example` → `MyExampleApp`.
+
+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.
+
+Every example must also have an RBS file documenting its public methods:
+
+`examples/my_example/app.rbs`:
+```rbs
+class MyExampleApp
+  # @public
+  def self.new: () -> MyExampleApp
+
+  # @public
+  def run: () -> void
+end
+```
+
+### 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 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
+
+### 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:
+  ```ruby
+  @styles = [
+    { name: "Yellow Bold", style: RatatuiRuby::Style.new(fg: :yellow, modifiers: [:bold]) },
+    { name: "Blue on White", style: RatatuiRuby::Style.new(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.
+
+### Hit Testing with the Cached Layout Pattern
+
+Examples with mouse interaction should implement the **Cached Layout Pattern** documented in `doc/interactive_design.md`. The `hit_test` example demonstrates this pattern.
+
+## Testing Examples
+
+Example tests live alongside examples as `test_app.rb` files in the same directory.
+
+### Testing Pattern
+
+`examples/my_example/test_app.rb`:
+```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)  # Queue quit event
+      @app.run        # Run the app loop
+      
+      content = buffer_content.join("\n")
+      assert_includes content, "Expected Text"
+    end
+  end
+
+  def test_keyboard_interaction
+    with_test_terminal do
+      inject_key("s")  # Press 's' to cycle something
+      inject_key(:q)   # Then quit
+      @app.run
+
+      content = buffer_content.join("\n")
+      assert_includes content, "Changed State"
+    end
+  end
+end
+```
+
+### Testing Guidelines
+
+1. **Inject events, observe buffer.** Tests should only interact through:
+   - `inject_key` / `inject_keys` / `inject_event` for input
+   - `buffer_content` for output verification
+
+2. **Never call internal methods.** Don't call `render`, `handle_input`, `__send__`, or access instance variables with `instance_variable_get`. Tests verify behavior through the public `run` method.
+
+3. **Use `inject_key(:q)` to exit.** All examples should support quitting with `q`, so inject this as the final event to terminate the loop.
+
+4. **Assert and refute.** When testing which item was clicked/selected, also verify the opposite didn't happen:
+   ```ruby
+   assert_includes content, "Left Panel clicked"
+   refute_includes content, "Right Panel clicked"
+   ```
+
+5. **Test state cycling.** If an example cycles through options (styles, modes, etc.), test that pressing the key actually changes the rendered output.
+
+## 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/doc/contributors/documentation_style.md

@@ -0,0 +1,97 @@
+# 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.
+
+## 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):**
+```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.
+```
+
+**Good (Alexandrian/Zinsser/Plain Language):**
+```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.
+```
+
+## 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
+
+```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
+```
+
+## 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/dwim_dx.md

@@ -0,0 +1,366 @@
+<!-- SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com> -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+# DWIM / DX Improvements for Application Developers
+
+## Problem Statement
+
+Ruby's philosophy of "Do What I Mean" (DWIM) and human-centric design should extend to ratatui_ruby's API. Currently, app developers encounter friction points that force them to remember non-obvious conventions, use overly verbose code, or pattern-match when simple predicates would suffice.
+
+This proposal identifies DX issues across the widget API and suggests improvements that maintain backward compatibility while providing ergonomic alternatives.
+
+## DX Issues Identified
+
+### 1. Confusing Event Method Names
+
+**Current problem**: `event.char` doesn't exist, but `event.code` returns things like `"enter"`, `"ctrl"`, not just characters.
+
+**What users expect**: 
+- `event.char` should return the printable character (matching the name)
+- `event.ctrl_c?`, `event.enter?`, etc. should work for all key combinations
+- `event.key?`, `event.mouse?` predicates exist but only for broad categories
+
+**Solution implemented**: Added `char` method and dynamic predicates via `method_missing`. See `lib/ratatui_ruby/event/key.rb`.
+
+### 2. Dual Parameter APIs Without Predicates
+
+**Current problem**: Widgets accept both forms but no convenience methods to query the state:
+
+```ruby
+# Both work, but which one does the widget store?
+gauge1 = Gauge.new(ratio: 0.75)
+gauge2 = Gauge.new(percent: 75)
+gauge1.ratio  # Works
+gauge1.percent  # Does NOT exist
+```
+
+Similarly with List and Table:
+```ruby
+list.selected_index = 2  # Works
+list.selected?  # Does NOT exist
+list.is_selected?  # Does NOT exist
+```
+
+**Affected widgets**: 
+- `Gauge` (ratio vs percent)
+- `LineGauge` (ratio vs percent)
+- `List` (selected_index with no query methods)
+- `Table` (selected_row and selected_column with no query methods)
+
+**Suggested solutions**:
+
+For `Gauge` and `LineGauge`:
+```ruby
+# Add convenience predicates
+gauge.percent  # => 75 (coerced from ratio internally)
+gauge.percent = 50  # => Updates ratio to 0.5
+
+# Or provide explicit accessors
+gauge.as_percent  # => 75
+gauge.as_ratio   # => 0.75
+```
+
+For `List` and `Table`:
+```ruby
+list.selected?  # => true if selected_index is not nil
+list.selection  # => 2 (alias for selected_index)
+list.selected_item  # => "Item 3"
+
+table.selected_row?  # => true if selected_row is not nil
+table.selected_cell?  # => true if both row and column selected
+```
+
+### 3. Symbol Constants for Enum Values
+
+**Current problem**: Magic symbol values scattered across code:
+
+```ruby
+list = List.new(
+  highlight_spacing: :when_selected,  # What are the other options?
+  direction: :top_to_bottom,          # Is :bottom_to_top valid?
+)
+
+layout = Layout.new(
+  flex: :legacy  # What does "legacy" mean?
+)
+
+gauge = Gauge.new(
+  use_unicode: true  # Unclear what ASCII fallback looks like
+)
+```
+
+Users must consult docs or source code to discover valid options.
+
+**Suggested solution**: Add constants to widget classes:
+
+```ruby
+class List < Data
+  # Highlight spacing modes
+  HIGHLIGHT_ALWAYS = :always
+  HIGHLIGHT_WHEN_SELECTED = :when_selected
+  HIGHLIGHT_NEVER = :never
+
+  # Direction modes
+  DIRECTION_TOP_TO_BOTTOM = :top_to_bottom
+  DIRECTION_BOTTOM_TO_TOP = :bottom_to_top
+end
+
+list = List.new(
+  highlight_spacing: List::HIGHLIGHT_WHEN_SELECTED,
+  direction: List::DIRECTION_TOP_TO_BOTTOM,
+)
+```
+
+Benefits:
+- IDE autocomplete shows valid options
+- Self-documenting code
+- Typos caught at runtime (symbol vs constant)
+- Easy to grep for where these modes are used
+
+Affected widgets and their enum values:
+- `List`: `highlight_spacing` (:always, :when_selected, :never), `direction` (:top_to_bottom, :bottom_to_top)
+- `Table`: `highlight_spacing` (same as List), `flex` (:legacy, :default, :fill)
+- `Layout`: `direction` (:vertical, :horizontal), `flex` (:legacy, :default, :fill)
+- `Gauge`/`LineGauge`: `use_unicode` (boolean, but could have MODE_UNICODE, MODE_ASCII)
+- `Paragraph`: `alignment` (:left, :center, :right)
+- `Block`: `border_type` (:plain, :rounded, :double, :thick)
+- `Canvas`: `marker` (:braille, :dots, :half_block, :sextant, :octant)
+
+### 4. Inconsistent Style APIs
+
+**Current problem**: Different widgets accept styles differently:
+
+```ruby
+# Table accepts both
+table = Table.new(style: Style.new(fg: :blue))
+table = Table.new(style: { fg: :blue })  # Hash shorthand
+
+# But Paragraph doesn't
+paragraph = Paragraph.new(text: "hi", style: Style.new(fg: :blue))
+paragraph = Paragraph.new(text: "hi", style: { fg: :blue })  # Works but undocumented
+
+# And Gauge has separate properties
+gauge = Gauge.new(style: Style.new(fg: :blue), gauge_style: Style.new(fg: :green))
+```
+
+**Suggested solution**: Standardize style handling across all widgets:
+
+1. All widgets should accept `Style` objects and `Hash` shorthand
+2. Document this clearly in each widget
+3. Add a convenience constructor:
+
+```ruby
+class Style
+  def self.with(fg: nil, bg: nil, modifiers: [])
+    Style.new(fg: fg, bg: bg, modifiers: modifiers)
+  end
+end
+
+# Cleaner than always spelling out keyword args
+paragraph = Paragraph.new(text: "hi", style: Style.with(fg: :blue))
+```
+
+### 5. Missing State Query Predicates
+
+**Current problem**: Widgets store state but provide no query methods:
+
+```ruby
+list.selected_index = 0
+
+# To check if something is selected, must do:
+if list.selected_index&.nonzero?  # Awkward
+if list.selected_index.nil? == false  # Confusing
+
+# Should be:
+list.selected?  # => true
+list.empty?  # => false (for items array)
+```
+
+**Suggested solution**: Add predicates to state-holding widgets:
+
+```ruby
+# List
+list.selected?      # => !selected_index.nil?
+list.empty?         # => items.empty?
+list.selection      # => selected_index (alias)
+list.selected_item  # => items[selected_index] (convenience)
+
+# Table
+table.selected_row?    # => !selected_row.nil?
+table.selected_cell?   # => !selected_row.nil? && !selected_column.nil?
+table.empty?           # => rows.empty?
+
+# Gauge
+gauge.filled?          # => ratio > 0
+gauge.complete?        # => ratio >= 1.0
+```
+
+### 6. Magic Numeric Coercions
+
+**Current problem**: Widgets accept `Numeric` but silently coerce:
+
+```ruby
+# These all work, but behavior is undocumented
+list = List.new(selected_index: "2")    # Coerced to 2
+list = List.new(selected_index: 2.7)    # Coerced to 2
+list = List.new(selected_index: 2.0)    # Coerced to 2
+
+gauge = Gauge.new(percent: 150)  # Should clamp?
+gauge = Gauge.new(ratio: 1.5)    # Should clamp?
+```
+
+**Suggested solution**: 
+
+1. Document coercion rules explicitly in RDoc
+2. Add validation and raise on invalid inputs:
+
+```ruby
+def initialize(percent: nil, ...)
+  if percent
+    raise ArgumentError, "percent must be 0..100, got #{percent}" unless percent.between?(0, 100)
+    ratio = Float(percent) / 100.0
+  end
+end
+```
+
+3. Provide clear error messages:
+```ruby
+gauge = Gauge.new(percent: 150)
+# => ArgumentError: percent must be between 0 and 100 (got 150)
+```
+
+## Implementation Strategy
+
+### Phase 1: Event Improvements (DONE)
+- [x] Add `char` method to Key event
+- [x] Implement dynamic predicates via `method_missing`
+- [x] Update examples to use new API
+
+### Phase 2: State Query Predicates
+- [ ] Add predicates to `List` (selected?, empty?, selected_item)
+- [ ] Add predicates to `Table` (selected_row?, selected_cell?, empty?)
+- [ ] Add predicates to `Gauge` (filled?, complete?)
+- [ ] Tests for all new predicates
+
+### Phase 3: Symbol Constants
+- [ ] Add enum constants to `List`, `Table`, `Layout`
+- [ ] Add enum constants to `Gauge`, `LineGauge`, `Paragraph`, `Block`
+- [ ] Update all examples to use constants
+- [ ] Document constants in RDoc
+
+### Phase 4: Style Consistency
+- [ ] Standardize `Hash` shorthand support across all widgets
+- [ ] Add `Style.with(fg:, bg:, modifiers:)` convenience constructor
+- [ ] Update `.rbs` files to reflect HashStyle support
+- [ ] Document in style guide
+
+### Phase 5: Numeric Coercion Validation
+- [ ] Add validation to `Gauge`, `LineGauge`, `List`, `Table`
+- [ ] Raise `ArgumentError` on out-of-range values
+- [ ] Provide clear error messages
+- [ ] Update tests
+
+### Phase 6: Convenience Accessors
+- [ ] Add `percent` to `Gauge` and `LineGauge`
+- [ ] Add `selection` alias to `List` and `Table`
+- [ ] Add `selected_item` to `List`
+- [ ] Tests and documentation
+
+## Example: Before and After
+
+### Before (Confusing)
+```ruby
+class GameApp
+  def initialize
+    @menu = List.new(
+      items: ["Start Game", "Load Game", "Options", "Quit"],
+      selected_index: 0,
+      highlight_spacing: :when_selected,  # What's valid here?
+      direction: :top_to_bottom
+    )
+  end
+
+  def handle_input(event)
+    case event
+    when :ctrl_c
+      exit
+    when :up
+      if @menu.selected_index && @menu.selected_index > 0
+        @menu = @menu.with(selected_index: @menu.selected_index - 1)
+      end
+    end
+  end
+
+  def render(tui)
+    tui.draw(@menu)
+  end
+end
+```
+
+### After (DWIM)
+```ruby
+class GameApp
+  def initialize
+    @menu = List.new(
+      items: ["Start Game", "Load Game", "Options", "Quit"],
+      selected_index: 0,
+      highlight_spacing: List::HIGHLIGHT_WHEN_SELECTED,  # IDE autocomplete!
+      direction: List::DIRECTION_TOP_TO_BOTTOM
+    )
+  end
+
+  def handle_input(event)
+    return if event.ctrl_c?  # Dynamic predicate!
+    
+    if event.up?
+      move_menu_up if @menu.selected?  # State predicate!
+    end
+  end
+
+  def move_menu_up
+    index = @menu.selected_index
+    return if index == 0
+    @menu = @menu.with(selected_index: index - 1)
+  end
+
+  def render(tui)
+    tui.draw(@menu)
+  end
+end
+```
+
+## Migration Path
+
+All changes are backward compatible (additive):
+- Existing code using symbols continues to work
+- New constants coexist with symbols
+- New predicates don't change existing behavior
+- New methods are additions, not replacements
+
+Apps can migrate at their own pace:
+```ruby
+# Old style still works
+list = List.new(highlight_spacing: :when_selected)
+
+# New style also works
+list = List.new(highlight_spacing: List::HIGHLIGHT_WHEN_SELECTED)
+
+# Mix and match
+if list.selected?  # New predicate
+  puts list.selected_index  # Old accessor
+end
+```
+
+## Metrics for Success
+
+1. **Discoverability**: New developers can find valid options via IDE autocomplete
+2. **Clarity**: Code self-documents valid states and modes
+3. **Type safety**: Constants and predicates provide type checking
+4. **Error feedback**: Invalid inputs raise with helpful messages
+5. **Backward compatibility**: Zero breaking changes, all existing code works
+
+## Related Issues
+
+- AGENTS.md requirement: All examples must have tests verifying behavior
+- Example improvements: Apply constants and predicates to all example code
+- Documentation: Update style guide with DWIM principles