ratatui_ruby 0.4.0 → 0.6.0

data/examples/app_all_events/README.md

@@ -0,0 +1,99 @@
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# App All Events Example
+
+This example application captures and visualizes every event supported by `ratatui_ruby`. It serves as a comprehensive reference for event handling and a demonstration of the Proto-TEA architectural pattern.
+
+## Architecture: Proto-TEA (Model-View-Update)
+
+This application demonstrates **unidirectional data flow** inspired by The Elm Architecture. This separation ensures that state management is predictable and easy to test.
+
+### 1. Model (`model/app_model.rb`)
+A single immutable `Data.define` object holding **all** application state:
+*   Event log entries
+*   Focus state
+*   Window size
+*   Highlight timestamps
+*   Color cycle index
+
+State changes use `.with(...)` to return a new Model instance.
+
+### 2. Msg (`model/msg.rb`)
+Semantic value objects that decouple raw terminal events from business logic:
+*   `Msg::Input` — keyboard, mouse, or paste events
+*   `Msg::Resize` — terminal size changes
+*   `Msg::Focus` — focus gained/lost
+*   `Msg::Quit` — exit signal
+
+### 3. Update (`update.rb`)
+A **pure function** that computes the next state:
+
+```ruby
+Update.call(msg, model) -> Model
+```
+
+All logic previously in `Events.record` now lives here. The function never mutates, never draws, never performs IO.
+
+### 4. View (`view/`)
+Pure rendering logic. Views accept the immutable `AppModel` and draw to the screen.
+*   **`View::App`**: Root view handling high-level layout
+*   **Sub-views**: `Counts`, `Live`, `Log`, `Controls`
+
+### 5. Runtime (`app.rb`)
+The MVU loop:
+
+```ruby
+loop do
+  tui.draw { |f| view.call(model, tui, f, f.area) }
+  msg = map_event_to_msg(tui.poll_event, model)
+  break if msg.is_a?(Msg::Quit)
+  model = Update.call(msg, model)
+end
+```
+
+## Library Features Showcased
+
+Reading this code will teach you how to:
+
+*   **Handle All Events**:
+    *   **Keyboard**: Capture normal keys and modifiers (`Ctrl+c`, `q`).
+    *   **Mouse**: track clicks, drags, and scroll events.
+    *   **Focus**: React to the terminal window gaining or losing focus (`FocusGained`/`FocusLost`).
+    *   **Resize**: Dynamically adapt layouts when the terminal size changes.
+    *   **Paste**: Handle bracketed paste events (if supported by the terminal).
+*   **Layouts**: Use `tui.layout_split` with constraints (`Length`, `Fill`) to create complex, responsive dashboards.
+*   **Styling**: Apply dynamic styles (bold, colors) based on application state.
+*   **Structure**: Organize a non-trivial CLI tool into small, single-purpose classes.
+
+## What Problems Does This Solve?
+
+### "What key code is my terminal sending?"
+If you are building an app and your logic isn't catching `Ctrl+Left`, run this app and press the keys. You will see exactly how `ratatui_ruby` parses that input (e.g., is it a `Key` event? What are the modifiers?).
+
+### "How do I structure a real app?"
+Hello World examples are great, but they don't scale. This example shows how to structure an application that can grow. By using immutable state and pure functions, it solves the problem of "where does my state live and how does it change?"
+
+### "How do I test my business logic?"
+The `Update` function is pure. You can test it by constructing a `Msg`, calling `Update.call(msg, model)`, and asserting on the returned `Model`. No mocking required.
+
+## Comparison: Choosing an Architecture
+
+Complex applications require structured state habits. `AppAllEvents` and the [Color Picker](../app_color_picker/README.md) demonstrate two different approaches.
+
+### The Dashboard Approach (AppAllEvents)
+
+Dashboards display data. They rarely require complex mouse interaction. Proto-TEA works best here. State is immutable. Logic is pure. Updates are predictable. This simplifies testing.
+
+Use this pattern for logs, monitors, and data viewers.
+
+### The Tool Approach (Color Picker)
+
+Tools require interaction. Users click buttons and drag sliders. Each UI component needs to know where it exists on screen for hit testing.
+
+The Color Picker uses a "Proto-Kit (Component-Based)" pattern. Each component encapsulates its own rendering, state, and event handling. The Container routes events and coordinates cross-component effects.
+
+Use this pattern for forms, editors, and mouse-driven tools.
+

data/examples/app_all_events/app.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+$LOAD_PATH.unshift File.expand_path(__dir__)
+
+require "ratatui_ruby"
+require_relative "model/app_model"
+require_relative "model/msg"
+require_relative "update"
+require_relative "view/app_view"
+
+# Demonstrates the full range of terminal events supported by RatatuiRuby.
+#
+# Developers need a comprehensive example to understand how keys, mouse, resize, and focus events behave.
+# Testing event handling across different terminal emulators and platforms can be unpredictable.
+#
+# This application captures and logs every event received from the backend, providing real-time feedback and history.
+#
+# Use it to verify your terminal's capabilities or as a reference for complex event handling.
+#
+# === Architecture
+#
+# This example uses the Proto-TEA (Model-View-Update) pattern:
+# - **Model**: Immutable AppModel holds all state
+# - **Msg**: Semantic message types decouple events from logic
+# - **Update**: Pure function computes next state
+# - **View**: Renders Model to screen
+#
+# === Examples
+#
+#   # Run from the command line:
+#   # ruby examples/app_all_events/app.rb
+#
+#   app = AppAllEvents.new
+#   app.run
+class AppAllEvents
+  # List of all event types tracked by this application.
+  EVENT_TYPES = %i[key mouse resize paste focus none].freeze
+
+  # Creates a new AppAllEvents instance and initializes its view.
+  def initialize
+    @view = View::App.new
+  end
+
+  # Starts the application event loop.
+  #
+  # Implements the MVU (Model-View-Update) runtime:
+  # 1. **View**: Render current model
+  # 2. **Poll**: Get next event
+  # 3. **Map**: Convert raw event to semantic Msg
+  # 4. **Update**: Compute next model
+  #
+  # === Example
+  #
+  #   app.run
+  def run
+    RatatuiRuby.run do |tui|
+      model = AppModel.initial
+
+      loop do
+        tui.draw { |frame| @view.call(model, tui, frame, frame.area) }
+
+        event = tui.poll_event
+        msg = map_event_to_msg(event, model)
+        break if msg.is_a?(Msg::Quit)
+
+        model = Update.call(msg, model)
+      end
+    end
+  end
+
+  private def map_event_to_msg(event, model)
+    case event
+    when RatatuiRuby::Event::Key
+      return Msg::Quit.new if event.code == "q"
+      return Msg::Quit.new if event.code == "c" && event.modifiers.include?("ctrl")
+
+      Msg::Input.new(event:)
+    when RatatuiRuby::Event::Resize
+      Msg::Resize.new(width: event.width, height: event.height, previous_size: model.window_size)
+    when RatatuiRuby::Event::FocusGained
+      Msg::Focus.new(gained: true)
+    when RatatuiRuby::Event::FocusLost
+      Msg::Focus.new(gained: false)
+    when RatatuiRuby::Event::None
+      Msg::NoneEvent.new
+    else
+      Msg::Input.new(event:)
+    end
+  end
+end
+
+AppAllEvents.new.run if __FILE__ == $PROGRAM_NAME

data/examples/app_all_events/model/app_model.rb

@@ -0,0 +1,157 @@
+# 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_entry"
+require_relative "event_color_cycle"
+
+# Immutable application state for the Proto-TEA architecture.
+#
+# The Elm Architecture requires a single immutable Model. State changes return
+# a new Model instance. This consolidates all app state into one place.
+#
+# Use `AppModel.initial` to create the starting state, and `model.with(...)`
+# to create updated states.
+#
+# === Attributes
+#
+# [entries] Array of EventEntry objects (event log)
+# [focused] Boolean window focus state
+# [window_size] Array [width, height] of terminal dimensions
+# [lit_types] Hash mapping event types to Timestamp (for highlight expiry)
+# [none_count] Integer count of :none events (not logged)
+# [color_cycle_index] Integer index into EventColorCycle::COLORS
+#
+# === Example
+#
+#   model = AppModel.initial
+#   model.count(:key)  #=> 0
+#   model.focused      #=> true
+class AppModel < Data.define(:entries, :focused, :window_size, :lit_types, :none_count, :color_cycle_index)
+  # Highlight duration in milliseconds.
+  HIGHLIGHT_DURATION_MS = 300
+
+  # Creates the initial application state.
+  #
+  # === Example
+  #
+  #   AppModel.initial #=> #<data AppModel entries=[] focused=true ...>
+  def self.initial
+    new(
+      entries: [],
+      focused: true,
+      window_size: [80, 24],
+      lit_types: {},
+      none_count: 0,
+      color_cycle_index: 0
+    )
+  end
+
+  # Returns the count of events for a given type.
+  #
+  # [type] Symbol event type (:key, :mouse, :resize, :paste, :focus, :none)
+  #
+  # === Example
+  #
+  #   model.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
+  #
+  #   model.sub_counts(:mouse) #=> { "down" => 1, "up" => 2 }
+  def sub_counts(type)
+    return {} if type == :none
+
+    matching = entries.select { |e| e.matches_type?(type) }
+    defaults = {
+      key: %w[standard function media system modifier],
+      focus: %w[gained lost],
+      mouse: %w[down up drag moved scroll_up scroll_down],
+    }
+
+    matching.each_with_object(defaults.fetch(type, []).to_h { |k| [k, 0] }) do |entry, counts|
+      group = subtype_for(entry, type)
+      counts[group] += 1 if group
+    end
+  end
+
+  # Checks if an event type should be highlighted.
+  #
+  # [type] Symbol event type.
+  #
+  # === Example
+  #
+  #   model.lit?(:key) #=> true
+  def lit?(type)
+    timestamp = lit_types[type]
+    return false unless timestamp
+
+    !timestamp.elapsed?(HIGHLIGHT_DURATION_MS)
+  end
+
+  # Returns the most recent entries up to the given limit.
+  #
+  # [max_entries] Integer maximum number of entries to return.
+  #
+  # === Example
+  #
+  #   model.visible(10) #=> [#<EventEntry ...>, ...]
+  def visible(max_entries)
+    entries.last(max_entries)
+  end
+
+  # Checks if any events have been recorded.
+  #
+  # === Example
+  #
+  #   model.empty? #=> true
+  def empty?
+    entries.empty?
+  end
+
+  # Returns the most recent live event data for a type.
+  #
+  # [type] Symbol event type.
+  #
+  # === Example
+  #
+  #   model.live_event(:key) #=> { time: Time, description: "..." }
+  def live_event(type)
+    entry = entries.reverse.find { |e| e.live_type == type }
+    return nil unless entry
+
+    { time: Time.at(entry.timestamp.milliseconds / 1000.0), description: entry.description }
+  end
+
+  # Returns the next color in the cycle for a new event.
+  #
+  # === Example
+  #
+  #   model.next_color #=> :cyan
+  def next_color
+    EventColorCycle::COLORS[color_cycle_index]
+  end
+
+  private def subtype_for(entry, type)
+    case type
+    when :key
+      # Key events: group by category kind (standard/function/media/modifier/system)
+      entry.event.kind.to_s if entry.event.respond_to?(:kind)
+    when :mouse
+      # Mouse events: group by event kind (down/up/drag/moved/scroll_up/scroll_down)
+      entry.event.kind.to_s if entry.event.respond_to?(:kind)
+    when :focus
+      entry.type.to_s.sub("focus_", "")
+    end
+  end
+end

data/examples/app_all_events/model/event_color_cycle.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# Cycles through a set of colors for event logging.
+#
+# Sequential events in a log are hard to distinguish if they all look the same.
+# Manually assigning colors to every event type or entry is repetitive.
+#
+# This class automatically cycles through a predefined list of vibrant colors.
+#
+# Use it to give each event in a log a distinct visual identity.
+#
+# === Examples
+#
+#   cycler = EventColorCycle.new
+#   cycler.next_color #=> :cyan
+#   cycler.next_color #=> :magenta
+#   cycler.next_color #=> :yellow
+#   cycler.next_color #=> :cyan
+class EventColorCycle
+  # List of colors to cycle through.
+  COLORS = %i[cyan magenta yellow].freeze
+
+  # Creates a new EventColorCycle.
+  def initialize
+    @index = 0
+  end
+
+  # Returns the next color in the cycle.
+  #
+  # === Example
+  #
+  #   cycler.next_color #=> :cyan
+  def next_color
+    color = COLORS[@index]
+    @index = (@index + 1) % COLORS.length
+    color
+  end
+end

data/examples/app_all_events/model/event_entry.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require_relative "timestamp"
+require "ratatui_ruby"
+
+# Stores details about a single event in the history log.
+#
+# Event logs need to store diverse data including types, keys, colors, and timestamps.
+# Managing loose hashes or arrays for event history is error-prone and hard to query.
+#
+# This class provides a structured data object for every recorded event.
+#
+# Use it to represent mouse clicks, key presses, or resize events in a log.
+#
+# === Examples
+#
+#   # Typically created via Events.record
+#   entry = EventEntry.create(key_event, :cyan, Timestamp.now)
+#   puts entry.type #=> :key
+#   puts entry.description #=> '#<RatatuiRuby::Event::Key ...>'
+class EventEntry < Data.define(:event, :color, :timestamp)
+  # Creates a new EventEntry.
+  #
+  # [event] RatatuiRuby::Event object.
+  # [color] Symbol color for the log display.
+  # [timestamp] Timestamp of when the event occurred.
+  def self.create(event, color, timestamp)
+    new(
+      event:,
+      color:,
+      timestamp:
+    )
+  end
+
+  # Returns the event type.
+  #
+  # === Example
+  #
+  #   entry.type #=> :key
+  def type
+    case event
+    when RatatuiRuby::Event::Key then :key
+    when RatatuiRuby::Event::Mouse then :mouse
+    when RatatuiRuby::Event::Resize then :resize
+    when RatatuiRuby::Event::Paste then :paste
+    when RatatuiRuby::Event::FocusGained then :focus_gained
+    when RatatuiRuby::Event::FocusLost then :focus_lost
+    else :unknown
+    end
+  end
+
+  # Returns the event description using inspect.
+  #
+  # === Example
+  #
+  #   entry.description #=> '#<RatatuiRuby::Event::Key code="a" modifiers=[]>'
+  def description
+    event.inspect
+  end
+
+  # Checks if the entry matches the given type.
+  #
+  # [check_type] Symbol type to check against.
+  #
+  # === Example
+  #
+  #   entry.matches_type?(:key) #=> true
+  def matches_type?(check_type)
+    return true if check_type == :focus && (type == :focus_gained || type == :focus_lost)
+
+    type == check_type
+  end
+
+  # Returns the display type for live event grouping.
+  #
+  # Normalizes focus_gained and focus_lost to :focus.
+  #
+  # === Example
+  #
+  #   entry.live_type #=> :focus
+  def live_type
+    case type
+    when :focus_gained, :focus_lost
+      :focus
+    else
+      type
+    end
+  end
+end

data/examples/app_all_events/model/msg.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# Semantic message types for the Proto-TEA architecture.
+#
+# Raw events from the terminal are converted to semantic Msg types. This
+# decouples the Update function from the event system, making it easier
+# to test and reason about.
+#
+# === Example
+#
+#   msg = Msg::Input.new(event: key_event)
+#   msg = Msg::Quit.new
+module Msg
+  # A keyboard, mouse, or paste event to record.
+  Input = Data.define(:event)
+
+  # A terminal resize event.
+  #
+  # [width] Integer new terminal width
+  # [height] Integer new terminal height
+  # [previous_size] Array [width, height] before resize
+  Resize = Data.define(:width, :height, :previous_size)
+
+  # A focus change event.
+  #
+  # [gained] Boolean true if focus was gained, false if lost
+  Focus = Data.define(:gained)
+
+  # A none/timeout event (no input received).
+  NoneEvent = Data.define
+
+  # A quit signal.
+  Quit = Data.define
+end

data/examples/app_all_events/model/timestamp.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# Represents a high-resolution point in time.
+#
+# Comparing events and calculating durations requires consistent time measurement.
+# Standard Time objects are often too granular or complex for simple millisecond offsets.
+#
+# This class provides a millisecond-precision timestamp for event measurement.
+#
+# Use it to track event timing, calculate elapsed time, or trigger debouncing.
+#
+# === Examples
+#
+#   timestamp = Timestamp.now
+#   puts timestamp.milliseconds
+#
+#   if timestamp.elapsed?(300)
+#     puts "More than 300ms have passed."
+#   end
+class Timestamp < Data.define(:milliseconds)
+  # Returns a new Timestamp representing the current time.
+  #
+  # === Example
+  #
+  #   Timestamp.now #=> #<struct Timestamp milliseconds=123456789>
+  def self.now
+    new(milliseconds: (Time.now.to_f * 1000).to_i)
+  end
+
+  # Checks if a duration has passed since this timestamp.
+  #
+  # [duration_ms] Integer duration in milliseconds.
+  #
+  # === Example
+  #
+  #   timestamp = Timestamp.now
+  #   sleep(0.5)
+  #   timestamp.elapsed?(300) #=> true
+  def elapsed?(duration_ms)
+    Timestamp.now.milliseconds >= milliseconds + duration_ms
+  end
+
+  # Returns the current time in milliseconds.
+  #
+  # === Example
+  #
+  #   Timestamp.current #=> 123456789
+  def self.current
+    now.milliseconds
+  end
+end

data/examples/app_all_events/update.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require_relative "model/app_model"
+require_relative "model/msg"
+require_relative "model/event_entry"
+require_relative "model/timestamp"
+require_relative "model/event_color_cycle"
+
+# Pure update function for the Proto-TEA architecture.
+#
+# Given a Msg and the current AppModel, returns the next AppModel.
+# This function is pure: it does not mutate arguments, draw to the screen,
+# or perform IO. It simply calculates the next state.
+#
+# === Example
+#
+#   model = AppModel.initial
+#   msg = Msg::Input.new(event: key_event)
+#   new_model = Update.call(msg, model)
+module Update
+  extend self
+
+  # Processes a message and returns the next model.
+  #
+  # [msg] A Msg value object
+  # [model] The current AppModel
+  #
+  # === Example
+  #
+  #   Update.call(Msg::Quit.new, model) #=> model (unchanged)
+  def call(msg, model)
+    case msg
+    in Msg::Quit
+      model
+    in Msg::NoneEvent
+      model.with(none_count: model.none_count + 1)
+    in Msg::Focus(gained:)
+      event = gained ? RatatuiRuby::Event::FocusGained.new : RatatuiRuby::Event::FocusLost.new
+      entry = create_entry(event, model)
+      add_entry(model, entry, :focus).with(focused: gained)
+    in Msg::Resize(width:, height:, previous_size: _)
+      event = RatatuiRuby::Event::Resize.new(width:, height:)
+      entry = create_entry(event, model)
+      add_entry(model, entry, :resize).with(window_size: [width, height])
+    in Msg::Input(event:)
+      entry = create_entry(event, model)
+      add_entry(model, entry, entry.live_type)
+    else
+      model
+    end
+  end
+
+  # Creates an EventEntry with the next color and current timestamp.
+  def create_entry(event, model)
+    EventEntry.create(event, model.next_color, Timestamp.now)
+  end
+
+  # Adds an entry to the model, updates highlights, and advances the color cycle.
+  def add_entry(model, entry, live_type)
+    new_entries = model.entries + [entry]
+    new_lit_types = model.lit_types.merge(live_type => Timestamp.now)
+    new_color_index = (model.color_cycle_index + 1) % EventColorCycle::COLORS.length
+
+    model.with(
+      entries: new_entries,
+      lit_types: new_lit_types,
+      color_cycle_index: new_color_index
+    )
+  end
+end