ratatui_ruby 1.3.0 → 1.4.0

data/examples/app_all_events/model/app_model.rb

@@ -1,159 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 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 Model-View-Update 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

@@ -1,43 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 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

@@ -1,94 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 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

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
-#++
-
-# Semantic message types for the Model-View-Update 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

@@ -1,56 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 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

@@ -1,75 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 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 Model-View-Update 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

data/examples/app_all_events/view/app_view.rb

@@ -1,80 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
-#++
-
-require_relative "../view"
-require_relative "counts_view"
-require_relative "live_view"
-require_relative "log_view"
-require_relative "controls_view"
-
-# Orchestrates the complete UI layout and sub-view composition.
-#
-# Complex applications need a structured way to divide the screen and delegate rendering.
-# Placing all layout logic in one monolithic method makes the code difficult to maintain.
-#
-# This class defines the screen layout using a series of split constraints and delegates to sub-views.
-#
-# Use it as the root view for the All Events example application.
-#
-# === Examples
-#
-#   app_view = View::App.new
-#   app_view.call(model, tui, frame, area)
-class View::App
-  # Creates a new View::App and initializes sub-views.
-  def initialize
-    @counts_view = View::Counts.new
-    @live_view = View::Live.new
-    @log_view = View::Log.new
-    @controls_view = View::Controls.new
-  end
-
-  # Renders the entire application UI to the given area.
-  #
-  # [model] AppModel containing all application data.
-  # [tui] RatatuiRuby instance.
-  # [frame] RatatuiRuby::Frame being rendered.
-  # [area] RatatuiRuby::Layout::Rect defining the total available space.
-  #
-  # === Example
-  #
-  #   app_view.call(model, tui, frame, area)
-  def call(model, tui, frame, area)
-    main_area, control_area = tui.layout_split(
-      area,
-      direction: :vertical,
-      constraints: [
-        tui.constraint_fill(1),
-        tui.constraint_length(3),
-      ]
-    )
-
-    counts_area, _margin_area, right_area = tui.layout_split(
-      main_area,
-      direction: :horizontal,
-      constraints: [
-        tui.constraint_length(20),
-        tui.constraint_length(1),
-        tui.constraint_fill(1),
-      ]
-    )
-
-    live_area, log_area = tui.layout_split(
-      right_area,
-      direction: :vertical,
-      constraints: [
-        tui.constraint_length(9),
-        tui.constraint_fill(1),
-      ]
-    )
-
-    @counts_view.call(model, tui, frame, counts_area)
-    @live_view.call(model, tui, frame, live_area)
-    @log_view.call(model, tui, frame, log_area)
-    @controls_view.call(model, tui, frame, control_area)
-  end
-end

data/examples/app_all_events/view/controls_view.rb

@@ -1,54 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
-#++
-
-require_relative "../view"
-
-# Renders the keyboard controls and shortcuts panel.
-#
-# Users need to know how to interact with the application and exit.
-# Hardcoding control descriptions into the main layout makes the code hard to read.
-#
-# This component renders a formatted paragraph listing available global shortcuts.
-#
-# Use it to display help information in a sidebar or dedicated panel.
-#
-# === Examples
-#
-#   controls = View::Controls.new
-#   controls.call(model, tui, frame, area)
-class View::Controls
-  # Renders the controls widget to the given area.
-  #
-  # [model] AppModel (unused, included for consistent interface).
-  # [tui] RatatuiRuby instance.
-  # [frame] RatatuiRuby::Frame being rendered.
-  # [area] RatatuiRuby::Layout::Rect defining the widget's bounds.
-  #
-  # === Example
-  #
-  #   controls.call(model, tui, frame, area)
-  def call(_model, tui, frame, area)
-    hotkey_style = tui.style(modifiers: [:bold, :underlined])
-
-    widget = tui.paragraph(
-      text: [
-        tui.text_line(spans: [
-          tui.text_span(content: "q", style: hotkey_style),
-          tui.text_span(content: ": Quit  "),
-          tui.text_span(content: "Ctrl+C", style: hotkey_style),
-          tui.text_span(content: ": Quit"),
-        ]),
-      ],
-      block: tui.block(
-        title: "Controls",
-        borders: [:all],
-        border_style: tui.style(fg: :white)
-      )
-    )
-    frame.render_widget(widget, area)
-  end
-end

data/examples/app_all_events/view/counts_view.rb

@@ -1,61 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
-#++
-
-require_relative "../view"
-
-# Renders the event statistics dashboard.
-#
-# Developers auditing input need to see real-time counts of various event types.
-#
-# This component displays a list of event types with their total counts.
-#
-# Use it to build an interactive dashboard of application activity.
-class View::Counts
-  # Renders the event counts widget to the given area.
-  #
-  # [model] AppModel containing event data.
-  # [tui] RatatuiRuby instance.
-  # [frame] RatatuiRuby::Frame being rendered.
-  # [area] RatatuiRuby::Layout::Rect defining the widget's bounds.
-  def call(model, tui, frame, area)
-    dimmed_style = tui.style(fg: :dark_gray)
-    lit_style = tui.style(fg: :green, modifiers: [:bold])
-    border_color = model.focused ? :green : :gray
-
-    count_lines = []
-
-    AppAllEvents::EVENT_TYPES.each do |type|
-      count = model.count(type)
-      label = type.to_s.capitalize
-      style = model.lit?(type) ? lit_style : nil
-
-      count_lines << tui.text_line(spans: [
-        tui.text_span(content: "#{label}: ", style:),
-        tui.text_span(content: count.to_s, style: style || tui.style(fg: :yellow)),
-      ])
-
-      model.sub_counts(type).each do |sub_type, sub_count|
-        sub_label = sub_type.to_s.capitalize
-        count_lines << tui.text_line(spans: [
-          tui.text_span(content: "  #{sub_label}: ", style: dimmed_style),
-          tui.text_span(content: sub_count.to_s, style: dimmed_style),
-        ])
-      end
-    end
-
-    widget = tui.paragraph(
-      text: count_lines,
-      scroll: [0, 0],
-      block: tui.block(
-        title: "Event Counts",
-        borders: [:all],
-        border_style: tui.style(fg: border_color)
-      )
-    )
-    frame.render_widget(widget, area)
-  end
-end