ratatui_ruby 0.6.0 → 0.7.1

data/doc/contributors/dwim_dx.md

@@ -1,366 +0,0 @@
-<!-- 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

data/doc/contributors/examples_audit/p1_high.md

@@ -1,21 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Priority 1: High (Polish & Ecosystem)
-
-Important for v1.0.0 quality and ecosystem goals. Not blocking release, but recommended before ship.
-
----
-
-## 1. Ensure All Widgets Have Examples
-
-**Status:** Done
-
-Verified that all widget types shipped with ratatui_ruby have at least one example showing how to use them.
-
-**Action:**
-- [x] Check widget manifest against example inventory
-- [x] Create `widget_canvas_demo`, `widget_center_demo`, and `widget_overlay_demo`
-

data/doc/contributors/examples_audit/p2_moderate.md

@@ -1,81 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Priority 2: Moderate (Quality Gates)
-
-These are v1.0.0 quality improvements that refine the example suite after P0 is complete. Not blocking, but recommended for maintainability and API consistency.
-
----
-
-## 1. Add RDoc Cross-Links (Examples & Aliases)
-
-**Status:** Important for API discoverability — Documentation should link library and examples
-
-RDoc should cross-link between:
-- **Library classes/methods** ↔ **Examples that use them** (See also: examples/widget_foo_demo)
-- **Primary methods** ↔ **DWIM/TIMTOWTDI aliases** (See also: tui.foo_bar as alias for tui.foo(:bar))
-
-### Current Practice
-
-Done for:
-- `RatatuiRuby::Frame#set_cursor_position` ↔ `RatatuiRuby::Cursor` (cross-linking)
-- Limited elsewhere
-
-### Gaps
-
-- Most widget classes have no "See also: example_foo_demo" links
-- Aliases/TIMTOWTDI variants are not documented as such
-- Users can't easily find examples for a given class/method
-
-### Action
-
-1. Add `# See also: examples/widget_foo_demo/app.rb` to class/method RDoc
-2. Link DWIM methods to TIMTOWTDI variants: `# Also available as: tui.constraint_length (DWIM) vs tui.constraint(:length) (TIMTOWTDI)`
-3. Create consistent pattern across all public APIs in `lib/ratatui_ruby/`
-
-### Example Pattern
-
-```ruby
-# Renders text with styling.
-#
-# See also: examples/widget_paragraph_demo/app.rb (basic paragraph rendering)
-class Paragraph < Data.define(...)
-  # ...
-end
-
-# DWIM version of constraint creation
-# Also available as: constraint(type, value) for explicit control
-def constraint_length(length)
-  constraint(:length, length)
-end
-```
-
----
-
-## Dependencies
-
-- P0 (developing_examples.md, README.md, tests) should be complete before consolidation
-
----
-
-## 4. Enhance Widget Examples with Functional Context
-
-**Status:** Recommended — Move beyond "parameter playgrounds" to "real-world patterns"
-
-Current `widget_*` examples mostly focus on interactive parameter turning (changing colors, borders, etc.). While useful for API discovery, they don't show *how* to use the widget in a real application logic flow.
-
-### The Standard: widget_tabs_demo
-
-The `widget_tabs_demo` was enhanced to show **conditional rendering** of content based on the selected tab in git commit `38ceed39a011d557cc66e11a4598d3341dc7a0cc`. It doesn't just highlight the tab; it changes the screen content. This connects the widget (the tabs) to the problem it solves (view segregation).
-
-### Action
-
-Identify other widget examples that could benefit from this "functional context" treatment:
-
--   **widget_popup_demo:** Show a multi-step modal flow (e.g., Confirm -> Success) rather than just a static overlay.
--   **widget_list_demo:** Show a master-detail view where selecting a list item updates a detail pane.
--   **widget_input_demo:** (If created) Show specific validation logic (email vs number).
-
-**Goal:** Every widget example should answer "How do I build a feature with this?" not just "What does this parameter do?"

data/doc/contributors/examples_audit.md

@@ -1,41 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Examples Audit Report
-
-Audit of ratatui_ruby `examples/` directory for v1.0.0 readiness.
-
-## P0: Critical (Completed ✓)
-
-All P0 critical items have been completed:
-
-1. **Migrate Example Tests to Snapshot API** ✓
-   - Migrated 31 test files from manual `buffer_content` assertions to `assert_snapshot` and `assert_rich_snapshot`
-   - Added deterministic seeding for tests with random content (Faker, RATA_SEED)
-   - Generates `.txt` (plain) and `.ansi` (styled) snapshots for mutation-testing capability
-
----
-
-## [P1: High (Polish)](./examples_audit/p1_high.md)
-
-1. **[Ensure All Widgets Have Examples](./examples_audit/p1_high.md#1-ensure-all-widgets-have-examples)** (Completeness)
-   - Check widget manifest against example inventory
-   - Create examples for any missing widgets
-
----
-
-## [P2: Moderate (Quality)](./examples_audit/p2_moderate.md)
-
-1. **[Add RDoc Cross-Links](./examples_audit/p2_moderate.md#1-add-rdoc-cross-links-examples--aliases)** (Documentation discoverability)
-   - Link library classes/methods to examples
-   - Link DWIM/TIMTOWTDI aliases
-   - Create consistent pattern across public APIs
-
----
-
-## Success Criteria for v1.0.0
-
-- ✓ All P0 items are fixed
-- ✓ All P1 items are mitigated (or time has run out)