ratatui_ruby 0.5.0 → 0.7.0

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/examples/app_all_events/model/events.rb

@@ -1,180 +0,0 @@
-# frozen_string_literal: true
-
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
-
-require_relative "timestamp"
-require_relative "event_color_cycle"
-require_relative "event_entry"
-
-# Manages the history and state of all application events.
-#
-# Applications need to track, count, and display event history for debugging and feedback.
-# Direct management of event arrays and counters across the app leads to scattered state.
-#
-# This class centralizes event storage. It records new events, maintains counts, and manages temporary highlights.
-#
-# Use it to store key presses, mouse clicks, and window resizes for display in a log or counter.
-#
-# === Examples
-#
-#   events = Events.new
-#   events.record(key_event)
-#   puts events.count(:key) #=> 1
-#
-#   if events.lit?(:key)
-#     puts "Key event just happened!"
-#   end
-class Events
-  # Duration in milliseconds for an event to remain highlighted in the UI.
-  HIGHLIGHT_DURATION_MS = 300
-
-  # Creates a new Events manager.
-  def initialize
-    @entries = []
-    @color_cycle = EventColorCycle.new
-    @none_count = 0
-    @lit_type = nil
-    @lit_until = Timestamp.now
-    @live = {}
-  end
-
-  # Records a new event.
-  #
-  # [event] RatatuiRuby::Event object.
-  # [context] Hash of additional context (e.g., last_dimensions).
-  #
-  # === Example
-  #
-  #   events.record(mouse_event)
-  def record(event, context: {})
-    if event.is_a?(RatatuiRuby::Event::None) || event == :none
-      @none_count += 1
-      return
-    end
-
-    color = @color_cycle.next_color
-    timestamp = Timestamp.now
-    entry = EventEntry.create(event, color, timestamp)
-    @entries << entry
-    update_lit_type(entry)
-
-    display_type = live_type_for(entry.type)
-    @live[display_type] = { time: Time.now, description: entry.description }
-  end
-
-  private def live_type_for(type)
-    case type
-    when :focus_gained, :focus_lost
-      :focus
-    else
-      type
-    end
-  end
-
-  # Returns the most recent live event data for a type.
-  #
-  # [type] Symbol event type to look up.
-  #
-  # === Example
-  #
-  #   events.live_event(:key) #=> { time: ..., description: "..." }
-  def live_event(type)
-    @live[type]
-  end
-
-  # Returns all recorded live event data.
-  #
-  # === Example
-  #
-  #   events.live_events #=> { key: { ... }, mouse: { ... } }
-  def live_events
-    @live
-  end
-
-  # Returns the most recent entries up to the given limit.
-  #
-  # [max_entries] Integer maximum number of entries to return.
-  #
-  # === Example
-  #
-  #   events.visible(10) #=> [#<EventEntry ...>, ...]
-  def visible(max_entries)
-    @entries.last(max_entries)
-  end
-
-  # Checks if any events have been recorded.
-  #
-  # === Example
-  #
-  #   events.empty? #=> true
-  def empty?
-    @entries.empty?
-  end
-
-  # Returns the count of events for a type.
-  #
-  # [type] Symbol event type.
-  #
-  # === Example
-  #
-  #   events.count(:key) #=> 5
-  def count(type)
-    return @none_count if type == :none
-
-    @entries.count { |e| e.matches_type?(type) }
-  end
-
-  # Returns counts grouped by subtype (kind or modifier status).
-  #
-  # [type] Symbol event type.
-  #
-  # === Example
-  #
-  #   events.sub_counts(:mouse) #=> { "down" => 1, "up" => 2 }
-  def sub_counts(type)
-    return {} if type == :none
-
-    entries = @entries.select { |e| e.matches_type?(type) }
-
-    defaults = { key: %w[unmodified modified], focus: %w[gained lost], mouse: %w[down up drag moved scroll_up scroll_down] }
-    entries.each_with_object(defaults.fetch(type, []).to_h { |k| [k, 0] }) do |entry, counts|
-      group = if entry.event.respond_to?(:kind)
-        entry.event.kind.to_s
-      elsif entry.event.respond_to?(:modifiers)
-        entry.event.modifiers.empty? ? "unmodified" : "modified"
-      elsif type == :focus
-        entry.type.to_s.sub("focus_", "")
-      end
-
-      counts[group] += 1 if group
-    end
-  end
-
-  # Checks if a type should be highlighted.
-  #
-  # [type] Symbol event type.
-  #
-  # === Example
-  #
-  #   events.lit?(:key) #=> true
-  def lit?(type)
-    return false if Timestamp.now.milliseconds >= @lit_until.milliseconds
-
-    @lit_type == type
-  end
-
-  # Returns all event entries.
-  #
-  # === Example
-  #
-  #   events.entries #=> [#<EventEntry ...>, ...]
-  def entries
-    @entries
-  end
-
-  private def update_lit_type(entry)
-    @lit_type = live_type_for(entry.type)
-    @lit_until = Timestamp.new(milliseconds: Timestamp.now.milliseconds + HIGHLIGHT_DURATION_MS)
-  end
-end

data/examples/app_all_events/model/highlight.rb

@@ -1,57 +0,0 @@
-# frozen_string_literal: true
-
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
-
-require_relative "timestamp"
-
-# Manages temporary visual highlights for different event types.
-#
-# Users need visual feedback when an event occurs, but highlights should fade.
-# Manually tracking timers for every highlightable element is complex.
-#
-# This class manages the "lit" state of multiple keys with a consistent duration.
-#
-# Use it to trigger and check for temporary UI highlights.
-#
-# === Examples
-#
-#   highlight = Highlight.new
-#   highlight.light_up(:key)
-#   highlight.lit?(:key) #=> true
-#   sleep(0.4)
-#   highlight.lit?(:key) #=> false
-class Highlight
-  # Duration in milliseconds that a highlight remains active.
-  DURATION_MS = 300
-
-  # Creates a new Highlight manager.
-  def initialize
-    @lit_types = {}
-  end
-
-  # Triggers a highlight for the given type.
-  #
-  # [type] Symbol to highlight.
-  #
-  # === Example
-  #
-  #   highlight.light_up(:mouse)
-  def light_up(type)
-    @lit_types[type] = Timestamp.now
-  end
-
-  # Checks if a highlight is currently active for the given type.
-  #
-  # [type] Symbol to check.
-  #
-  # === Example
-  #
-  #   highlight.lit?(:mouse) #=> true
-  def lit?(type)
-    timestamp = @lit_types[type]
-    return false unless timestamp
-
-    !timestamp.elapsed?(DURATION_MS)
-  end
-end

data/examples/app_all_events/test/snapshots/after_focus_lost.txt

@@ -1,24 +0,0 @@
-┌Event Counts──────┐ ┌Live Display─────────────────────────────────────────────┐
-│Key: 0            │ │Type     Time      Description                           │
-│  Unmodified: 0   │ │Key      —         —                                     │
-│  Modified: 0     │ │Mouse    —         —                                     │
-│Mouse: 0          │ │Resize   —         —                                     │
-│  Down: 0         │ │Paste    —         —                                     │
-│  Up: 0           │ │Focus    XX:XX:XX  #<RatatuiRuby::Event::FocusLost:0xXXXXXX│
-│  Drag: 0         │ │                                                         │
-│  Moved: 0        │ └─────────────────────────────────────────────────────────┘
-│  Scroll_up: 0    │ ┌Event Log────────────────────────────────────────────────┐
-│  Scroll_down: 0  │ │#<RatatuiRuby::Event::FocusLost:0xXXXXXX>      │
-│Resize: 0         │ │                                                         │
-│Paste: 0          │ │                                                         │
-│Focus: 1          │ │                                                         │
-│  Gained: 0       │ │                                                         │
-│  Lost: 1         │ │                                                         │
-│None: 0           │ │                                                         │
-│                  │ │                                                         │
-│                  │ │                                                         │
-│                  │ │                                                         │
-└──────────────────┘ └─────────────────────────────────────────────────────────┘
-┌Controls──────────────────────────────────────────────────────────────────────┐
-│q: Quit  Ctrl+C: Quit                                                         │
-└──────────────────────────────────────────────────────────────────────────────┘

data/examples/app_all_events/test/snapshots/after_focus_regained.txt

@@ -1,24 +0,0 @@
-┌Event Counts──────┐ ┌Live Display─────────────────────────────────────────────┐
-│Key: 0            │ │Type     Time      Description                           │
-│  Unmodified: 0   │ │Key      —         —                                     │
-│  Modified: 0     │ │Mouse    —         —                                     │
-│Mouse: 0          │ │Resize   —         —                                     │
-│  Down: 0         │ │Paste    —         —                                     │
-│  Up: 0           │ │Focus    XX:XX:XX  #<RatatuiRuby::Event::FocusGained:0xXXXXXX│
-│  Drag: 0         │ │                                                         │
-│  Moved: 0        │ └─────────────────────────────────────────────────────────┘
-│  Scroll_up: 0    │ ┌Event Log────────────────────────────────────────────────┐
-│  Scroll_down: 0  │ │#<RatatuiRuby::Event::FocusLost:0xXXXXXX>      │
-│Resize: 0         │ │                                                         │
-│Paste: 0          │ │#<RatatuiRuby::Event::FocusGained:0xXXXXXX>    │
-│Focus: 2          │ │                                                         │
-│  Gained: 1       │ │                                                         │
-│  Lost: 1         │ │                                                         │
-│None: 0           │ │                                                         │
-│                  │ │                                                         │
-│                  │ │                                                         │
-│                  │ │                                                         │
-└──────────────────┘ └─────────────────────────────────────────────────────────┘
-┌Controls──────────────────────────────────────────────────────────────────────┐
-│q: Quit  Ctrl+C: Quit                                                         │
-└──────────────────────────────────────────────────────────────────────────────┘