ratatui_ruby 0.5.0 → 0.6.0

data/lib/ratatui_ruby/test_helper.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
-require "timeout"
-require "minitest/mock"
 require "fileutils"
+require_relative "test_helper/terminal"
+require_relative "test_helper/snapshot"
+require_relative "test_helper/event_injection"
+require_relative "test_helper/style_assertions"
+require_relative "test_helper/test_doubles"
 
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
@@ -11,374 +14,78 @@ module RatatuiRuby
   ##
   # Helpers for testing RatatuiRuby applications.
   #
-  # This module provides methods to set up a test terminal, capture buffer content,
-  # and inject events, making it easier to write unit tests for your TUI apps.
+  # Writing TUI tests by hand is tedious. You need a headless terminal, event
+  # injection, snapshot comparisons, and style assertions. Wiring all that up
+  # yourself is error-prone.
   #
-  # == Usage
+  # This module bundles everything you need. Include it in your test class and
+  # start writing tests immediately.
+  #
+  # == Included Mixins
+  #
+  # [Terminal] Sets up a headless terminal and queries its buffer.
+  # [Snapshot] Compares the screen against stored reference files.
+  # [EventInjection] Simulates keypresses, mouse clicks, and resize events.
+  # [StyleAssertions] Checks foreground color, background color, and text modifiers.
+  # [TestDoubles] Provides mocks and stubs for testing views in isolation.
+  #
+  # == Example
   #
   #   require "ratatui_ruby/test_helper"
   #
-  #   class MyTest < Minitest::Test
+  #   class TestMyApp < Minitest::Test
   #     include RatatuiRuby::TestHelper
   #
-  #     def test_rendering
+  #     def test_initial_render
   #       with_test_terminal(80, 24) do
-  #         # ... render your app ...
-  #         assert_includes buffer_content, "Hello World"
+  #         MyApp.new.run_once
+  #         assert_snapshot("initial")
+  #       end
+  #     end
+  #
+  #     def test_themes
+  #       with_test_terminal do
+  #         app = ThemeDemo.new
+  #         app.run_once
+  #         assert_rich_snapshot("default_theme")
+  #
+  #         inject_key("t", modifiers: [:ctrl])
+  #         app.run_once
+  #         assert_rich_snapshot("dark_theme")
+  #
+  #         inject_key("t", modifiers: [:ctrl])
+  #         app.run_once
+  #         assert_rich_snapshot("high_contrast_theme")
+  #       end
+  #     end
+  #
+  #     def test_highlighter_applies_selection_style
+  #       with_test_terminal(40, 5) do
+  #         RatatuiRuby.draw do |frame|
+  #           highlighter = MyApp::UI::Highlighter.new(:yellow)
+  #           highlighter.render_at(frame, 0, 2, "Selected Item")
+  #         end
+  #
+  #         assert_fg_color(:yellow, 0, 2)
+  #         assert_bold(0, 2)
   #       end
   #     end
   #
-  #     def test_key_handling
-  #       inject_event(RatatuiRuby::Event::Key.new(code: "q"))
-  #       result = @app.handle_input
-  #       assert_equal :quit, result
+  #     def test_view_in_isolation
+  #       frame = MockFrame.new
+  #       area = StubRect.new(width: 60, height: 20)
+  #
+  #       MyView.new.call(state, tui, frame, area)
+  #
+  #       widget = frame.rendered_widgets.first[:widget]
+  #       assert_equal "Dashboard", widget.block.title
   #     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: 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 = 80, height = 24, **opts)
-      RatatuiRuby.init_test_terminal(width, height)
-      # 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
-
-    ##
-    # Returns the current content of the terminal buffer as an array of strings.
-    # Each string represents a row in the terminal.
-    #
-    #   buffer_content
-    #   # => ["Row 1 text", "Row 2 text", ...]
-    def buffer_content
-      RatatuiRuby.get_buffer_content.split("\n")
-    end
-
-    ##
-    # Returns the current cursor position as a hash with +:x+ and +:y+ keys.
-    #
-    #   cursor_position
-    #   # => { x: 0, y: 0 }
-    def cursor_position
-      x, y = RatatuiRuby.get_cursor_position
-      { x:, y: }
-    end
-
-    ##
-    # 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.
-    #
-    #   # In test/test_login.rb
-    #   assert_snapshot("login_screen")
-    #   # Look for: test/snapshots/login_screen.txt
-    #
-    #   # 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
+    include Terminal
+    include Snapshot
+    include EventInjection
+    include StyleAssertions
+    include TestDoubles
   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.5.0"
+  VERSION = "0.6.0"
 end

data/lib/ratatui_ruby.rb

@@ -10,6 +10,7 @@ require_relative "ratatui_ruby/schema/layout"
 require_relative "ratatui_ruby/schema/block"
 require_relative "ratatui_ruby/schema/constraint"
 require_relative "ratatui_ruby/schema/list"
+require_relative "ratatui_ruby/schema/list_item"
 require_relative "ratatui_ruby/schema/style"
 require_relative "ratatui_ruby/schema/gauge"
 require_relative "ratatui_ruby/schema/line_gauge"
@@ -35,6 +36,9 @@ require_relative "ratatui_ruby/schema/draw"
 require_relative "ratatui_ruby/event"
 require_relative "ratatui_ruby/cell"
 require_relative "ratatui_ruby/frame"
+require_relative "ratatui_ruby/list_state"
+require_relative "ratatui_ruby/table_state"
+require_relative "ratatui_ruby/scrollbar_state"
 
 begin
   require "ratatui_ruby/ratatui_ruby"
@@ -52,7 +56,13 @@ end
 # Use `RatatuiRuby.run` to start your application.
 module RatatuiRuby
   # Generic error class for RatatuiRuby.
-  class Error < StandardError; end
+  class Error < StandardError
+    # Raised when a terminal operation fails (e.g., I/O error, backend failure).
+    class Terminal < Error; end
+
+    # Raised when an API safety contract is violated (e.g., accessing a Frame outside its valid scope).
+    class Safety < Error; end
+  end
 
   ##
   # Initializes the terminal for TUI mode.
@@ -155,41 +165,54 @@ module RatatuiRuby
   ##
   # 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).
+  # Interactive apps must respond to input. Loops need to poll without burning CPU.
   #
-  # === Example
+  # This method checks for an event. It returns the event if one is found. It returns {RatatuiRuby::Event::None} if the timeout expires.
+  #
+  # [timeout] Float seconds to wait (default: 0.016).
+  #           Pass <tt>nil</tt> to block indefinitely (wait forever).
+  #           Pass <tt>0.0</tt> for a non-blocking check.
+  #
+  # === Examples
   #
+  #   # Standard loop (approx 60 FPS)
   #   event = RatatuiRuby.poll_event
-  #   if event.none?
-  #     puts "No input available"
-  #   elsif event.key?
-  #     puts "Key pressed"
-  #   end
   #
-  def self.poll_event
-    raw = _poll_event
-    return Event::None.new if raw.nil?
+  #   # Block until event (pauses execution)
+  #   event = RatatuiRuby.poll_event(timeout: nil)
+  #
+  #   # Non-blocking check (returns immediately)
+  #   event = RatatuiRuby.poll_event(timeout: 0.0)
+  #
+  def self.poll_event(timeout: 0.016)
+    raise ArgumentError, "timeout must be non-negative" if timeout && timeout < 0
+
+    raw = _poll_event(timeout)
+    return Event::None.new.freeze if raw.nil?
 
     case raw[:type]
     when :key
-      Event::Key.new(code: raw[:code], modifiers: raw[:modifiers] || [])
+      Event::Key.new(
+        code: raw[:code],
+        modifiers: (raw[:modifiers] || []).freeze,
+        kind: raw[:kind] || :standard
+      ).freeze
     when :mouse
       Event::Mouse.new(
         kind: raw[:kind].to_s,
         x: raw[:x],
         y: raw[:y],
         button: raw[:button].to_s,
-        modifiers: raw[:modifiers] || []
-      )
+        modifiers: (raw[:modifiers] || []).freeze
+      ).freeze
     when :resize
-      Event::Resize.new(width: raw[:width], height: raw[:height])
+      Event::Resize.new(width: raw[:width], height: raw[:height]).freeze
     when :paste
-      Event::Paste.new(content: raw[:content])
+      Event::Paste.new(content: raw[:content]).freeze
     when :focus_gained
-      Event::FocusGained.new
+      Event::FocusGained.new.freeze
     when :focus_lost
-      Event::FocusLost.new
+      Event::FocusLost.new.freeze
     else
       # Fallback for unknown events, though ideally we cover them all
       nil

data/sig/examples/app_stateful_interaction/app.rbs

@@ -0,0 +1,33 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+class AppStatefulInteraction
+  @tables: Array[String]
+  @data: Hash[String, Array[Array[String]]]
+  @list_state: RatatuiRuby::ListState
+  @table_state: RatatuiRuby::TableState
+  @active_pane: :list | :table
+  @tui: untyped
+  @style_active: RatatuiRuby::Style
+  @style_inactive: RatatuiRuby::Style
+  @style_highlight: RatatuiRuby::Style
+  @list_area: RatatuiRuby::Rect
+  @table_area: RatatuiRuby::Rect
+
+  # @public
+  def self.new: () -> AppStatefulInteraction
+
+  # @public
+  def run: () -> void
+
+  private
+
+  def render: () -> void
+  def render_list: (untyped frame, RatatuiRuby::Rect area) -> void
+  def render_table: (untyped frame, RatatuiRuby::Rect area) -> void
+  def handle_input: () -> (:quit | nil)
+  def scroll_active: (Integer delta) -> void
+  def handle_click: (Integer x, Integer y) -> void
+  def handle_list_click: (Integer mouse_y) -> void
+  def handle_table_click: (Integer mouse_y) -> void
+end

data/sig/examples/widget_block_demo/app.rbs

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+#
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+class WidgetBlockDemo
+  @tui: RatatuiRuby::Tui
+  @hotkey_style: RatatuiRuby::Style
+  @title_configs: Array[{name: String, title: String?}]
+  @title_index: Integer
+  @titles_configs: Array[{name: String, titles: Array[RatatuiRuby::Block::title_input]}]
+  @titles_index: Integer
+  @alignment_configs: Array[{name: String, alignment: RatatuiRuby::Alignment}]
+  @alignment_index: Integer
+  @title_styles: Array[{name: String, style: RatatuiRuby::Style?}]
+  @title_style_index: Integer
+  @border_configs: Array[{name: String, borders: Array[RatatuiRuby::Block::border_option]}]
+  @border_index: Integer
+  @border_type_configs: Array[{name: String, type: RatatuiRuby::Block::border_type?, set: Hash[Symbol, String]?}]
+  @border_type_index: Integer
+  @border_styles: Array[{name: String, style: RatatuiRuby::Style?}]
+  @border_style_index: Integer
+  @base_styles: Array[{name: String, style: RatatuiRuby::Style?}]
+  @base_style_index: Integer
+  @padding_configs: Array[{name: String, padding: RatatuiRuby::Block::padding_input}]
+  @padding_index: Integer
+
+  def self.new: () -> WidgetBlockDemo
+  def run: () -> void
+  private def render: () -> void
+  private def handle_input: () -> (:quit)?
+end

data/sig/examples/{app_map_demo → widget_map_demo}/app.rbs

@@ -2,9 +2,9 @@
 #
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-class AppMapDemo
+class WidgetMapDemo
   # @public
-  def self.new: () -> AppMapDemo
+  def self.new: () -> WidgetMapDemo
 
   # @public
   def run: () -> void

data/sig/examples/{app_table_select → widget_table_demo}/app.rbs

@@ -2,9 +2,9 @@
 #
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-class AppTableSelect
+class WidgetTableDemo
   # @public
-  def self.new: () -> AppTableSelect
+  def self.new: () -> WidgetTableDemo
 
   # @public
   def run: () -> void

data/sig/examples/{widget_table_flex → widget_text_width}/app.rbs

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