ratatui_ruby 0.5.0 → 0.6.0

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_entry.rb

@@ -70,6 +70,23 @@ class EventEntry < Data.define(:event, :color, :timestamp)
   #   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/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

data/examples/app_all_events/view/app_view.rb

@@ -21,7 +21,7 @@ require_relative "controls_view"
 # === Examples
 #
 #   app_view = View::App.new
-#   app_view.call(state, tui, frame, area)
+#   app_view.call(model, tui, frame, area)
 class View::App
   # Creates a new View::App and initializes sub-views.
   def initialize
@@ -33,15 +33,15 @@ class View::App
 
   # Renders the entire application UI to the given area.
   #
-  # [state] ViewState containing all application data.
+  # [model] AppModel containing all application data.
   # [tui] RatatuiRuby instance.
   # [frame] RatatuiRuby::Frame being rendered.
   # [area] RatatuiRuby::Rect defining the total available space.
   #
   # === Example
   #
-  #   app_view.call(state, tui, frame, area)
-  def call(state, tui, frame, area)
+  #   app_view.call(model, tui, frame, area)
+  def call(model, tui, frame, area)
     main_area, control_area = tui.layout_split(
       area,
       direction: :vertical,
@@ -70,9 +70,9 @@ class View::App
       ]
     )
 
-    @counts_view.call(state, tui, frame, counts_area)
-    @live_view.call(state, tui, frame, live_area)
-    @log_view.call(state, tui, frame, log_area)
-    @controls_view.call(state, tui, frame, control_area)
+    @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

@@ -17,25 +17,27 @@ require_relative "../view"
 # === Examples
 #
 #   controls = View::Controls.new
-#   controls.call(state, tui, frame, area)
+#   controls.call(model, tui, frame, area)
 class View::Controls
   # Renders the controls widget to the given area.
   #
-  # [state] ViewState containing style information.
+  # [model] AppModel (unused, included for consistent interface).
   # [tui] RatatuiRuby instance.
   # [frame] RatatuiRuby::Frame being rendered.
   # [area] RatatuiRuby::Rect defining the widget's bounds.
   #
   # === Example
   #
-  #   controls.call(state, tui, frame, area)
-  def call(state, tui, frame, area)
+  #   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: state.hotkey_style),
+          tui.text_span(content: "q", style: hotkey_style),
           tui.text_span(content: ": Quit  "),
-          tui.text_span(content: "Ctrl+C", style: state.hotkey_style),
+          tui.text_span(content: "Ctrl+C", style: hotkey_style),
           tui.text_span(content: ": Quit"),
         ]),
       ],

data/examples/app_all_events/view/counts_view.rb

@@ -15,28 +15,32 @@ require_relative "../view"
 class View::Counts
   # Renders the event counts widget to the given area.
   #
-  # [state] ViewState containing event data and styles.
+  # [model] AppModel containing event data.
   # [tui] RatatuiRuby instance.
   # [frame] RatatuiRuby::Frame being rendered.
   # [area] RatatuiRuby::Rect defining the widget's bounds.
-  def call(state, tui, frame, area)
+  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 = state.events.count(type)
+      count = model.count(type)
       label = type.to_s.capitalize
-      style = state.events.lit?(type) ? state.lit_style : nil
+      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)),
       ])
 
-      state.events.sub_counts(type).each do |sub_type, sub_count|
+      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: state.dimmed_style),
-          tui.text_span(content: sub_count.to_s, style: state.dimmed_style),
+          tui.text_span(content: "  #{sub_label}: ", style: dimmed_style),
+          tui.text_span(content: sub_count.to_s, style: dimmed_style),
         ])
       end
     end
@@ -47,7 +51,7 @@ class View::Counts
       block: tui.block(
         title: "Event Counts",
         borders: [:all],
-        border_style: tui.style(fg: state.border_color)
+        border_style: tui.style(fg: border_color)
       )
     )
     frame.render_widget(widget, area)

data/examples/app_all_events/view/live_view.rb

@@ -17,19 +17,20 @@ require_relative "../view"
 # === Examples
 #
 #   live_view = View::Live.new
-#   live_view.call(state, tui, frame, area)
+#   live_view.call(model, tui, frame, area)
 class View::Live
   # Renders the live event table to the given area.
   #
-  # [state] ViewState containing event data and styles.
+  # [model] AppModel containing event data.
   # [tui] RatatuiRuby instance.
   # [frame] RatatuiRuby::Frame being rendered.
   # [area] RatatuiRuby::Rect defining the widget's bounds.
   #
   # === Example
   #
-  #   live_view.call(state, tui, frame, area)
-  def call(state, tui, frame, area)
+  #   live_view.call(model, tui, frame, area)
+  def call(model, tui, frame, area)
+    border_color = model.focused ? :green : :gray
     rows = []
 
     rows << tui.text_line(spans: [
@@ -39,13 +40,13 @@ class View::Live
     ])
 
     (AppAllEvents::EVENT_TYPES - [:none]).each do |type|
-      event_data = state.events.live_event(type)
+      event_data = model.live_event(type)
 
       class_str = type.to_s.capitalize
       time_str = event_data ? event_data[:time].strftime("%H:%M:%S") : "—"
       desc_str = event_data ? event_data[:description] : "—"
 
-      is_lit = state.events.lit?(type)
+      is_lit = model.lit?(type)
       row_style = is_lit ? tui.style(fg: :black, bg: :green) : nil
 
       rows << tui.text_line(spans: [
@@ -61,7 +62,7 @@ class View::Live
       block: tui.block(
         title: "Live Display",
         borders: [:all],
-        border_style: tui.style(fg: state.border_color)
+        border_style: tui.style(fg: border_color)
       )
     )
     frame.render_widget(widget, area)

data/examples/app_all_events/view/log_view.rb

@@ -16,32 +16,27 @@ require_relative "../view"
 class View::Log
   # Renders the event log widget to the given area.
   #
-  # [state] ViewState containing event data and styles.
+  # [model] AppModel containing event data.
   # [tui] RatatuiRuby instance.
   # [frame] RatatuiRuby::Frame being rendered.
   # [area] RatatuiRuby::Rect defining the widget's bounds.
-  def call(state, tui, frame, area)
+  def call(model, tui, frame, area)
+    dimmed_style = tui.style(fg: :dark_gray)
+    border_color = model.focused ? :green : :gray
+
     visible_entries_count = (area.height - 2) / 2
-    display_entries = state.events.visible(visible_entries_count)
+    display_entries = model.visible(visible_entries_count)
 
     log_lines = []
-    if state.events.empty?
-      log_lines << tui.text_line(spans: [tui.text_span(content: "No events yet...", style: state.dimmed_style)])
+    if model.empty?
+      log_lines << tui.text_line(spans: [tui.text_span(content: "No events yet...", style: dimmed_style)])
     else
       display_entries.each do |entry|
         entry_style = tui.style(fg: entry.color)
-
-        # Split description into lines if it's too long, or just let it wrap conceptually (though paragraph wraps by character by default)
-        # Using simple inspect output as requested.
         description = entry.description
 
-        # We want to display it over potentially multiple lines if needed, but the original code did manual 2-line formatting.
-        # Let's try to just dump the inspect string. If it's very long, it might be cut off.
-        # But the User asked specifically to use inspect.
-
         log_lines << tui.text_line(spans: [tui.text_span(content: description, style: entry_style)])
-        log_lines << tui.text_line(spans: [tui.text_span(content: "", style: entry_style)]) # Spacer line to match previous 2-line rhythm? Or just compact?
-        # Previous view had 2 lines per entry. Let's keep a spacer to make it readable.
+        log_lines << tui.text_line(spans: [tui.text_span(content: "", style: entry_style)])
       end
     end
 
@@ -52,7 +47,7 @@ class View::Log
       block: tui.block(
         title: "Event Log",
         borders: [:all],
-        border_style: tui.style(fg: state.border_color)
+        border_style: tui.style(fg: border_color)
       )
     )
     frame.render_widget(widget, area)