ratatui_ruby 0.3.1 → 0.5.0

data/lib/ratatui_ruby/test_helper.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require "timeout"
+require "minitest/mock"
+require "fileutils"
+
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
@@ -8,7 +12,7 @@ module RatatuiRuby
   # Helpers for testing RatatuiRuby applications.
   #
   # This module provides methods to set up a test terminal, capture buffer content,
-  # and check cursor position, making it easier to write unit tests for your TUI apps.
+  # and inject events, making it easier to write unit tests for your TUI apps.
   #
   # == Usage
   #
@@ -18,24 +22,49 @@ module RatatuiRuby
   #     include RatatuiRuby::TestHelper
   #
   #     def test_rendering
-  #       with_test_terminal(width: 80, height: 24) do
+  #       with_test_terminal(80, 24) do
   #         # ... render your app ...
   #         assert_includes buffer_content, "Hello World"
   #       end
   #     end
+  #
+  #     def test_key_handling
+  #       inject_event(RatatuiRuby::Event::Key.new(code: "q"))
+  #       result = @app.handle_input
+  #       assert_equal :quit, result
+  #     end
   #   end
   module TestHelper
     ##
     # Initializes a test terminal context with specified dimensions.
     # Restores the original terminal state after the block executes.
     #
-    # +width+:: width of the test terminal (default: 20)
-    # +height+:: height of the test terminal (default: 10)
+    # +width+:: width of the test terminal (default: 80)
+    # +height+:: height of the test terminal (default: 24)
+    #
+    # +timeout+:: maximum execution time in seconds (default: 2). Pass nil to disable.
     #
     # If a block is given, it is executed within the test terminal context.
-    def with_test_terminal(width = 20, height = 10)
+    def with_test_terminal(width = 80, height = 24, **opts)
       RatatuiRuby.init_test_terminal(width, height)
-      yield
+      # Flush any lingering events from previous tests
+      while (event = RatatuiRuby.poll_event) && !event.none?; end
+
+      RatatuiRuby.stub :init_terminal, nil do
+        RatatuiRuby.stub :restore_terminal, nil do
+          @_ratatui_test_terminal_active = true
+          timeout = opts.fetch(:timeout, 2)
+          if timeout
+            Timeout.timeout(timeout) do
+              yield
+            end
+          else
+            yield
+          end
+        ensure
+          @_ratatui_test_terminal_active = false
+        end
+      end
     ensure
       RatatuiRuby.restore_terminal
     end
@@ -61,15 +90,295 @@ module RatatuiRuby
     end
 
     ##
-    # Injects a mock event into the event queue for testing purposes.
+    # Injects an event into the event queue for testing.
+    #
+    # Pass any RatatuiRuby::Event object. The event will be returned by
+    # the next call to RatatuiRuby.poll_event.
+    #
+    # Raises a +RuntimeError+ if called outside of a +with_test_terminal+ block.
+    #
+    # == Examples
+    #
+    #   with_test_terminal do
+    #     # Key events
+    #     inject_event(RatatuiRuby::Event::Key.new(code: "q"))
+    #     inject_event(RatatuiRuby::Event::Key.new(code: "s", modifiers: ["ctrl"]))
+    #
+    #     # Mouse events
+    #     inject_event(RatatuiRuby::Event::Mouse.new(kind: "down", button: "left", x: 10, y: 5))
+    #
+    #     # Resize events
+    #     inject_event(RatatuiRuby::Event::Resize.new(width: 120, height: 40))
+    #
+    #     # Paste events
+    #     inject_event(RatatuiRuby::Event::Paste.new(content: "Hello"))
+    #
+    #     # Focus events
+    #     inject_event(RatatuiRuby::Event::FocusGained.new)
+    #     inject_event(RatatuiRuby::Event::FocusLost.new)
+    #   end
+    def inject_event(event)
+      unless @_ratatui_test_terminal_active
+        raise "Events must be injected inside a `with_test_terminal` block. " \
+          "Calling this method outside the block causes a race condition where the event " \
+          "is flushed before the application starts."
+      end
+
+      case event
+      when RatatuiRuby::Event::Key
+        RatatuiRuby.inject_test_event("key", { code: event.code, modifiers: event.modifiers })
+      when RatatuiRuby::Event::Mouse
+        RatatuiRuby.inject_test_event("mouse", {
+          kind: event.kind,
+          button: event.button,
+          x: event.x,
+          y: event.y,
+          modifiers: event.modifiers,
+        })
+      when RatatuiRuby::Event::Resize
+        RatatuiRuby.inject_test_event("resize", { width: event.width, height: event.height })
+      when RatatuiRuby::Event::Paste
+        RatatuiRuby.inject_test_event("paste", { content: event.content })
+      when RatatuiRuby::Event::FocusGained
+        RatatuiRuby.inject_test_event("focus_gained", {})
+      when RatatuiRuby::Event::FocusLost
+        RatatuiRuby.inject_test_event("focus_lost", {})
+      else
+        raise ArgumentError, "Unknown event type: #{event.class}"
+      end
+    end
+
+    ##
+    # Injects a mouse event.
+    #
+    #   inject_mouse(x: 10, y: 5, kind: :down, button: :left)
+    def inject_mouse(x:, y:, kind: :down, modifiers: [], button: :left)
+      event = RatatuiRuby::Event::Mouse.new(
+        kind: kind.to_s,
+        x:,
+        y:,
+        button: button.to_s,
+        modifiers:
+      )
+      inject_event(event)
+    end
+
+    ##
+    # Injects a mouse left click (down) event.
+    #
+    #   inject_click(x: 10, y: 5)
+    def inject_click(x:, y:, modifiers: [])
+      inject_mouse(x:, y:, kind: :down, modifiers:, button: :left)
+    end
+
+    ##
+    # Injects a mouse right click (down) event.
+    #
+    #   inject_right_click(x: 10, y: 5)
+    def inject_right_click(x:, y:, modifiers: [])
+      inject_mouse(x:, y:, kind: :down, modifiers:, button: :right)
+    end
+
+    ##
+    # Injects a mouse drag event.
+    #
+    #   inject_drag(x: 10, y: 5)
+    def inject_drag(x:, y:, modifiers: [], button: :left)
+      inject_mouse(x:, y:, kind: :drag, modifiers:, button:)
+    end
+
+    ##
+    # Injects multiple Key events into the queue.
+    #
+    # Supports multiple formats for convenience:
+    #
+    # * String: Converted to a Key event with that code.
+    # * Symbol: Parsed as modifier_code (e.g., <tt>:ctrl_c</tt>, <tt>:enter</tt>).
+    # * Hash: Passed to Key.new constructor.
+    # * Key: Passed directly.
+    #
+    # == Examples
+    #
+    #   with_test_terminal do
+    #     inject_keys("a", "b", "c")
+    #     inject_keys(:enter, :esc)
+    #     inject_keys(:ctrl_c, :alt_shift_left)
+    #     inject_keys("j", { code: "k", modifiers: ["ctrl"] })
+    #   end
+    def inject_keys(*args)
+      args.each do |arg|
+        event = case arg
+                when String
+                  RatatuiRuby::Event::Key.new(code: arg)
+                when Symbol
+                  parts = arg.to_s.split("_")
+                  code = parts.pop
+                  modifiers = parts
+                  RatatuiRuby::Event::Key.new(code:, modifiers:)
+                when Hash
+                  RatatuiRuby::Event::Key.new(**arg)
+                when RatatuiRuby::Event::Key
+                  arg
+                else
+                  raise ArgumentError, "Invalid key argument: #{arg.inspect}. Expected String, Symbol, Hash, or Key event."
+        end
+        inject_event(event)
+      end
+    end
+    alias inject_key inject_keys
+
+    ##
+    # Returns the cell attributes at the given coordinates.
+    #
+    #   get_cell(0, 0)
+    #   # => { "symbol" => "H", "fg" => :red, "bg" => nil }
+    def get_cell(x, y)
+      RatatuiRuby.get_cell_at(x, y)
+    end
+
+    ##
+    # Asserts that the cell at the given coordinates has the expected attributes.
+    #
+    #   assert_cell_style(0, 0, char: "H", fg: :red)
+    def assert_cell_style(x, y, **expected_attributes)
+      cell = get_cell(x, y)
+      expected_attributes.each do |key, value|
+        actual_value = cell.public_send(key)
+        if value.nil?
+          assert_nil actual_value, "Expected cell at (#{x}, #{y}) to have #{key}=nil, but got #{actual_value.inspect}"
+        else
+          assert_equal value, actual_value, "Expected cell at (#{x}, #{y}) to have #{key}=#{value.inspect}, but got #{actual_value.inspect}"
+        end
+      end
+    end
+
+    ##
+    # Mock frame for unit testing views.
+    #
+    # Captures widgets passed to +render_widget+ for inspection.
+    # Does not render anything—purely captures the output.
+    #
+    # == Examples
+    #
+    #   frame = MockFrame.new
+    #   View::Log.new.call(state, tui, frame, area)
+    #   widget = frame.rendered_widgets.first[:widget]
+    #   assert_equal "Event Log", widget.block.title
+    MockFrame = Data.define(:rendered_widgets) do
+      def initialize(rendered_widgets: [])
+        super
+      end
+
+      def render_widget(widget, area)
+        rendered_widgets << { widget:, area: }
+      end
+    end
+
+    ##
+    # Stub area for unit testing views.
+    #
+    # Provides the minimal interface views expect (+width+, +height+).
+    #
+    # == Examples
+    #
+    #   area = StubRect.new(width: 60, height: 20)
+    StubRect = Data.define(:x, :y, :width, :height) do
+      def initialize(x: 0, y: 0, width: 80, height: 24)
+        super
+      end
+    end
+
+    ##
+    # Asserts that the current screen content matches a stored snapshot.
+    #
+    # This method simplifies snapshot testing by automatically resolving the snapshot path
+    # relative to the test file calling this method. It assumes a "snapshots" directory
+    # exists in the same directory as the test file.
     #
-    # +event_type+:: "key" or "mouse"
-    # +data+:: a Hash containing event data
+    #   # In test/test_login.rb
+    #   assert_snapshot("login_screen")
+    #   # Look for: test/snapshots/login_screen.txt
     #
-    #   inject_event("key", { code: "a" })
-    #   inject_event("mouse", { kind: "down", x: 0, y: 0 })
-    def inject_event(event_type, data)
-      RatatuiRuby.inject_test_event(event_type, data)
+    #   # With normalization block
+    #   assert_snapshot("clock") do |actual|
+    #     actual.map { |l| l.gsub(/\d{2}:\d{2}/, "XX:XX") }
+    #   end
+    #
+    # [name] String name of the snapshot (without extension).
+    # [msg] String optional failure message.
+    def assert_snapshot(name, msg = nil, &)
+      # Get the path of the test file calling this method
+      caller_path = caller_locations(1, 1).first.path
+      snapshot_dir = File.join(File.dirname(caller_path), "snapshots")
+      snapshot_path = File.join(snapshot_dir, "#{name}.txt")
+
+      assert_screen_matches(snapshot_path, msg, &)
+    end
+
+    ##
+    # Asserts that the current screen content matches the expected content.
+    #
+    # Users need to verify that the entire TUI screen looks exactly as expected.
+    # Manually checking every cell or line is tedious and error-prone.
+    #
+    # This helper compares the current buffer content against an expected string (file path)
+    # or array of strings. It supports automatic snapshot creation and updating via
+    # the +UPDATE_SNAPSHOTS+ environment variable.
+    #
+    # Use it to verify complex UI states, layouts, and renderings.
+    #
+    # == Usage
+    #
+    #   # Direct comparison
+    #   assert_screen_matches(["Line 1", "Line 2"])
+    #
+    #   # File comparison
+    #   assert_screen_matches("test/snapshots/login.txt")
+    #
+    #   # With normalization (e.g., masking dynamic data)
+    #   assert_screen_matches("test/snapshots/dashboard.txt") do |lines|
+    #     lines.map { |l| l.gsub(/User ID: \d+/, "User ID: XXX") }
+    #   end
+    #
+    # [expected] String (file path) or Array<String> (content).
+    # [msg] String optional failure message.
+    def assert_screen_matches(expected, msg = nil)
+      actual_lines = buffer_content
+
+      if block_given?
+        actual_lines = yield(actual_lines)
+      end
+
+      if expected.is_a?(String)
+        # Snapshot file mode
+        snapshot_path = expected
+        update_snapshots = ENV["UPDATE_SNAPSHOTS"] == "1" || ENV["UPDATE_SNAPSHOTS"] == "true"
+
+        if !File.exist?(snapshot_path) || update_snapshots
+          FileUtils.mkdir_p(File.dirname(snapshot_path))
+          File.write(snapshot_path, "#{actual_lines.join("\n")}\n")
+          if update_snapshots
+            puts "Updated snapshot: #{snapshot_path}"
+          else
+            puts "Created snapshot: #{snapshot_path}"
+          end
+        end
+
+        expected_lines = File.readlines(snapshot_path, chomp: true)
+      else
+        # Direct comparison mode
+        expected_lines = expected
+      end
+
+      msg ||= "Screen content mismatch"
+
+      assert_equal expected_lines.size, actual_lines.size, "#{msg}: Line count mismatch"
+
+      expected_lines.each_with_index do |expected_line, i|
+        actual_line = actual_lines[i]
+        assert_equal expected_line, actual_line,
+          "#{msg}: Line #{i + 1} mismatch.\nExpected: #{expected_line.inspect}\nActual:   #{actual_line.inspect}"
+      end
     end
   end
 end

data/lib/ratatui_ruby/version.rb

@@ -6,5 +6,5 @@
 module RatatuiRuby
   # The version of the ratatui_ruby gem.
   # See https://semver.org/spec/v2.0.0.html
-  VERSION = "0.3.1"
+  VERSION = "0.5.0"
 end

data/lib/ratatui_ruby.rb

@@ -12,9 +12,12 @@ require_relative "ratatui_ruby/schema/constraint"
 require_relative "ratatui_ruby/schema/list"
 require_relative "ratatui_ruby/schema/style"
 require_relative "ratatui_ruby/schema/gauge"
+require_relative "ratatui_ruby/schema/line_gauge"
 require_relative "ratatui_ruby/schema/table"
 require_relative "ratatui_ruby/schema/tabs"
 require_relative "ratatui_ruby/schema/bar_chart"
+require_relative "ratatui_ruby/schema/bar_chart/bar"
+require_relative "ratatui_ruby/schema/bar_chart/bar_group"
 require_relative "ratatui_ruby/schema/sparkline"
 require_relative "ratatui_ruby/schema/chart"
 require_relative "ratatui_ruby/schema/clear"
@@ -23,7 +26,15 @@ require_relative "ratatui_ruby/schema/overlay"
 require_relative "ratatui_ruby/schema/center"
 require_relative "ratatui_ruby/schema/scrollbar"
 require_relative "ratatui_ruby/schema/canvas"
+require_relative "ratatui_ruby/schema/shape/label"
 require_relative "ratatui_ruby/schema/calendar"
+require_relative "ratatui_ruby/schema/ratatui_logo"
+require_relative "ratatui_ruby/schema/ratatui_mascot"
+require_relative "ratatui_ruby/schema/text"
+require_relative "ratatui_ruby/schema/draw"
+require_relative "ratatui_ruby/event"
+require_relative "ratatui_ruby/cell"
+require_relative "ratatui_ruby/frame"
 
 begin
   require "ratatui_ruby/ratatui_ruby"
@@ -32,78 +43,213 @@ rescue LoadError
   require_relative "ratatui_ruby/ratatui_ruby"
 end
 
-# The RatatuiRuby module acts as a namespace for the entire gem.
-# It provides the main entry points for initializing the terminal and drawing the UI.
+# Main entry point for the library.
+#
+# Terminal UIs require low-level control using C/Rust and high-level abstraction in Ruby.
+#
+# This module bridges the gap. It provides the native methods to initialize the terminal, handle raw mode, and render the widget tree.
+#
+# Use `RatatuiRuby.run` to start your application.
 module RatatuiRuby
   # Generic error class for RatatuiRuby.
   class Error < StandardError; end
 
   ##
-  # :method: init_terminal
-  # :call-seq: init_terminal() -> nil
-  #
   # Initializes the terminal for TUI mode.
   # Enters alternate screen and enables raw mode.
   #
-  # (Native method implemented in Rust)
+  # [focus_events] whether to enable focus gain/loss events (default: true).
+  # [bracketed_paste] whether to enable bracketed paste mode (default: true).
+  def self.init_terminal(focus_events: true, bracketed_paste: true)
+    _init_terminal(focus_events, bracketed_paste)
+  end
+
+  @experimental_warnings = true
+  class << self
+    ##
+    # :attr_accessor: experimental_warnings
+    # Whether to show warnings when using experimental features (default: true).
+    attr_accessor :experimental_warnings
+  end
 
   ##
-  # :method: restore_terminal
-  # :call-seq: restore_terminal() -> nil
-  #
+  # :singleton-method: restore_terminal
   # Restores the terminal to its original state.
   # Leaves alternate screen and disables raw mode.
   #
   # (Native method implemented in Rust)
 
   ##
-  # :method: draw
-  # :call-seq: draw(node) -> nil
+  # :singleton-method: inject_test_event
+  # Injects a mock event into the event queue for testing purposes.
+  # [event_type] "key" or "mouse"
+  # [data] a Hash containing event data
   #
-  # Draws the given UI node tree to the terminal.
-  # [node] the root node of the UI tree (Paragraph, Layout).
+  #   inject_test_event("key", { code: "a" })
   #
   # (Native method implemented in Rust)
 
   ##
-  # :method: poll_event
-  # :call-seq: poll_event() -> Hash, nil
-  #
-  # Polls for a keyboard event.
+  # Warns about usage of an experimental feature unless warnings are suppressed.
   #
-  #   poll_event
-  #   # => { type: :key, code: "a", modifiers: ["ctrl"] }
+  # [feature_name] String name of the feature (e.g., "Paragraph#line_count")
   #
-  # (Native method implemented in Rust)
+  # This warns only once per feature name per session.
+  def self.warn_experimental_feature(feature_name)
+    return unless experimental_warnings
+
+    @warned_features ||= {}
+    return if @warned_features[feature_name]
+
+    warn "WARNING: #{feature_name} is an experimental feature and may change in future versions. Disable this warning with RatatuiRuby.experimental_warnings = false."
+    @warned_features[feature_name] = true
+  end
+
+  # (Native method _init_terminal implemented in Rust)
+  private_class_method :_init_terminal
 
   ##
-  # :method: inject_test_event
-  # :call-seq: inject_test_event(event_type, data) -> nil
+  # Draws the given UI node tree to the terminal.
   #
-  # Injects a mock event into the event queue for testing purposes.
-  # [event_type] "key" or "mouse"
-  # [data] a Hash containing event data
+  # TUI applications need to render widgets to the screen. Rendering could
+  # happen all at once with a pre-built tree, or incrementally with direct
+  # frame access.
   #
-  #   inject_test_event("key", { code: "a" })
+  # This method handles both. Pass a tree for declarative rendering, or
+  # pass a block to manipulate the frame directly. The block receives a
+  # {Frame} object for imperative drawing.
   #
-  # (Native method implemented in Rust)
+  # [tree] A widget tree (Paragraph, Layout, etc.) to render. Optional if
+  #        a block is given.
+  #
+  # === Examples
+  #
+  # Legacy declarative style (tree-based):
+  #
+  #   RatatuiRuby.draw(Paragraph.new(text: "Hello"))
+  #
+  # New imperative style (block-based):
+  #
+  #   RatatuiRuby.draw do |frame|
+  #     frame.render_widget(Paragraph.new(text: "Hello"), frame.area)
+  #   end
+  #
+  def self.draw(tree = nil, &block)
+    if tree && block
+      raise ArgumentError, "Cannot provide both a tree and a block to draw"
+    end
+    unless tree || block
+      raise ArgumentError, "Must provide either a tree or a block to draw"
+    end
+
+    if tree
+      _draw(tree)
+    else
+      _draw(&block)
+    end
+  end
+
+  # (Native method _draw implemented in Rust)
+  private_class_method :_draw
 
   ##
-  # Provides a convenience wrapper for the main TUI loop.
-  # Initializes the terminal, runs the loop, and ensures the terminal is restored.
+  # Checks for user input.
+  #
+  # Returns a discrete event (Key, Mouse, Resize) if one is available in the queue.
+  # Returns RatatuiRuby::Event::None if the queue is empty (non-blocking).
+  #
+  # === Example
   #
-  #   RatatuiRuby.main_loop do
-  #     draw RatatuiRuby::Paragraph.new(text: "Hello")
-  #     event = RatatuiRuby::poll_event
-  #     break if event && event[:type] == :key && event[:code] == "q"
+  #   event = RatatuiRuby.poll_event
+  #   if event.none?
+  #     puts "No input available"
+  #   elsif event.key?
+  #     puts "Key pressed"
   #   end
-  def self.main_loop
-    require_relative "ratatui_ruby/dsl"
-    init_terminal
-    loop do
-      yield DSL.new
+  #
+  def self.poll_event
+    raw = _poll_event
+    return Event::None.new if raw.nil?
+
+    case raw[:type]
+    when :key
+      Event::Key.new(code: raw[:code], modifiers: raw[:modifiers] || [])
+    when :mouse
+      Event::Mouse.new(
+        kind: raw[:kind].to_s,
+        x: raw[:x],
+        y: raw[:y],
+        button: raw[:button].to_s,
+        modifiers: raw[:modifiers] || []
+      )
+    when :resize
+      Event::Resize.new(width: raw[:width], height: raw[:height])
+    when :paste
+      Event::Paste.new(content: raw[:content])
+    when :focus_gained
+      Event::FocusGained.new
+    when :focus_lost
+      Event::FocusLost.new
+    else
+      # Fallback for unknown events, though ideally we cover them all
+      nil
     end
+  end
+
+  # (Native method _poll_event implemented in Rust)
+  private_class_method :_poll_event
+
+  ##
+  # Starts the TUI application lifecycle.
+  #
+  # Managing generic setup/teardown (raw mode, alternate screen) manualy is error-prone. If your app crashes, the terminal might be left in a broken state.
+  #
+  # This method handles the safety net. It initializes the terminal, yields a {Session}, and ensures the terminal state is restored even if exceptions occur.
+  #
+  # === Example
+  #
+  #   RatatuiRuby.run(focus_events: false) do |tui|
+  #     tui.draw(tui.paragraph(text: "Hi"))
+  #     sleep 1
+  #   end
+  def self.run(focus_events: true, bracketed_paste: true)
+    require_relative "ratatui_ruby/session"
+    init_terminal(focus_events:, bracketed_paste:)
+    yield Session.new
   ensure
     restore_terminal
   end
+
+  ##
+  # Inspects the terminal buffer at specific coordinates.
+  #
+  # When writing tests, you need to verify that your widget drew the correct characters and styles.
+  # This method provides deep inspection of the cell's state (symbol, colors, modifiers).
+  #
+  # Returns a {Cell} object.
+  #
+  # Values depend on what the backend has rendered. If nothing has been rendered to a cell, it may contain defaults (empty symbol, nil colors).
+  #
+  # === Example
+  #
+  #   cell = RatatuiRuby.get_cell_at(10, 5)
+  #   expect(cell.symbol).to eq("X")
+  #   expect(cell.fg).to eq(:red)
+  #   expect(cell).to be_bold
+  #
+  def self.get_cell_at(x, y)
+    raw = _get_cell_at(x, y)
+    Cell.new(
+      char: raw["char"],
+      fg: raw["fg"],
+      bg: raw["bg"],
+      modifiers: raw["modifiers"] || []
+    )
+  end
+
+  # (Native method _get_cell_at implemented in Rust)
+  private_class_method :_get_cell_at
+
+  # Hide native Layout._split helper
+  Layout.singleton_class.__send__(:private, :_split)
 end

data/sig/examples/app_all_events/app.rbs

@@ -0,0 +1,11 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+class AppAllEvents
+  # @public
+  def self.new: () -> AppAllEvents
+
+  # @public
+  def run: () -> void
+end

data/sig/examples/app_all_events/model/event_entry.rbs

@@ -0,0 +1,16 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+class EventEntry < Data
+  attr_reader type: Symbol
+  attr_reader sub_key: Symbol | String | nil
+  attr_reader color: Symbol
+  attr_reader timestamp: Timestamp
+  attr_reader data: Hash[Symbol, untyped]
+
+  def self.from_event(type: Symbol, sub_key: Symbol | String | nil, color: Symbol, timestamp: Timestamp, data: Hash[Symbol, untyped]) -> instance
+  def matches_type?: (Symbol check_type) -> bool
+  def matches_sub_type?: (Symbol check_type, Symbol | String check_sub_key) -> bool
+  def matches_kind?: (String kind) -> bool
+  def self.new: (?type: Symbol, ?sub_key: Symbol | String | nil, ?color: Symbol, ?timestamp: Timestamp, ?data: Hash[Symbol, untyped]) -> instance
+end