ratatui_ruby 0.4.0 → 0.5.0

data/lib/ratatui_ruby/test_helper.rb

@@ -1,8 +1,8 @@
 # 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
@@ -45,25 +45,24 @@ module RatatuiRuby
     # +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, timeout: 2)
+    def with_test_terminal(width = 80, height = 24, **opts)
       RatatuiRuby.init_test_terminal(width, height)
       # Flush any lingering events from previous tests
-      while RatatuiRuby.poll_event; end
+      while (event = RatatuiRuby.poll_event) && !event.none?; end
 
       RatatuiRuby.stub :init_terminal, nil do
         RatatuiRuby.stub :restore_terminal, nil do
-          begin
-            @_ratatui_test_terminal_active = true
-            if timeout
-              Timeout.timeout(timeout) do
-                yield
-              end
-            else
+          @_ratatui_test_terminal_active = true
+          timeout = opts.fetch(:timeout, 2)
+          if timeout
+            Timeout.timeout(timeout) do
               yield
             end
-          ensure
-            @_ratatui_test_terminal_active = false
+          else
+            yield
           end
+        ensure
+          @_ratatui_test_terminal_active = false
         end
       end
     ensure
@@ -121,8 +120,8 @@ module RatatuiRuby
     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."
+          "Calling this method outside the block causes a race condition where the event " \
+          "is flushed before the application starts."
       end
 
       case event
@@ -134,7 +133,7 @@ module RatatuiRuby
           button: event.button,
           x: event.x,
           y: event.y,
-          modifiers: event.modifiers
+          modifiers: event.modifiers,
         })
       when RatatuiRuby::Event::Resize
         RatatuiRuby.inject_test_event("resize", { width: event.width, height: event.height })
@@ -149,6 +148,45 @@ module RatatuiRuby
       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.
     #
@@ -176,14 +214,14 @@ module RatatuiRuby
                   parts = arg.to_s.split("_")
                   code = parts.pop
                   modifiers = parts
-                  RatatuiRuby::Event::Key.new(code: code, modifiers: modifiers)
+                  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
+        end
         inject_event(event)
       end
     end
@@ -213,6 +251,134 @@ module RatatuiRuby
         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
   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.4.0"
+  VERSION = "0.5.0"
 end

data/lib/ratatui_ruby.rb

@@ -34,6 +34,7 @@ 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"
@@ -71,6 +72,23 @@ module RatatuiRuby
     attr_accessor :experimental_warnings
   end
 
+  ##
+  # :singleton-method: restore_terminal
+  # Restores the terminal to its original state.
+  # Leaves alternate screen and disables raw mode.
+  #
+  # (Native method implemented in Rust)
+
+  ##
+  # :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
+  #
+  #   inject_test_event("key", { code: "a" })
+  #
+  # (Native method implemented in Rust)
+
   ##
   # Warns about usage of an experimental feature unless warnings are suppressed.
   #
@@ -91,40 +109,67 @@ module RatatuiRuby
   private_class_method :_init_terminal
 
   ##
-  # :method: restore_terminal
-  # :call-seq: restore_terminal() -> nil
+  # Draws the given UI node tree to the terminal.
   #
-  # Restores the terminal to its original state.
-  # Leaves alternate screen and disables raw mode.
+  # 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.
   #
-  # (Native method implemented in Rust)
-
-  ##
-  # :method: draw
-  # :call-seq: draw(node) -> nil
+  # 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.
   #
-  # Draws the given UI node tree to the terminal.
-  # [node] the root node of the UI tree (Paragraph, Layout).
+  # [tree] A widget tree (Paragraph, Layout, etc.) to render. Optional if
+  #        a block is given.
   #
-  # (Native method implemented in Rust)
+  # === 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
 
   ##
-  # :method: poll_event
-  # :call-seq: poll_event() -> Event, nil
-  #
   # Checks for user input.
   #
   # Returns a discrete event (Key, Mouse, Resize) if one is available in the queue.
-  # Returns nil immediately if the queue is empty (non-blocking).
+  # Returns RatatuiRuby::Event::None if the queue is empty (non-blocking).
   #
   # === Example
   #
   #   event = RatatuiRuby.poll_event
-  #   puts "Key pressed" if event.is_a?(RatatuiRuby::Event::Key)
+  #   if event.none?
+  #     puts "No input available"
+  #   elsif event.key?
+  #     puts "Key pressed"
+  #   end
   #
   def self.poll_event
     raw = _poll_event
-    return nil if raw.nil?
+    return Event::None.new if raw.nil?
 
     case raw[:type]
     when :key
@@ -155,21 +200,6 @@ module RatatuiRuby
   private_class_method :_poll_event
 
   ##
-  # :method: inject_test_event
-  # :call-seq: inject_test_event(event_type, data) -> nil
-  #
-  # Injects a mock event into the event queue for testing purposes.
-  # [event_type] "key" or "mouse"
-  # [data] a Hash containing event data
-  #
-  #   inject_test_event("key", { code: "a" })
-  #
-  # (Native method implemented in Rust)
-
-  ##
-  # :method: run
-  # :call-seq: run { |session| ... } -> Object
-  #
   # 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.
@@ -184,16 +214,13 @@ module RatatuiRuby
   #   end
   def self.run(focus_events: true, bracketed_paste: true)
     require_relative "ratatui_ruby/session"
-    init_terminal(focus_events: focus_events, bracketed_paste: bracketed_paste)
+    init_terminal(focus_events:, bracketed_paste:)
     yield Session.new
   ensure
     restore_terminal
   end
 
   ##
-  # :method: get_cell_at
-  # :call-seq: get_cell_at(x, y) -> Cell
-  #
   # Inspects the terminal buffer at specific coordinates.
   #
   # When writing tests, you need to verify that your widget drew the correct characters and styles.
@@ -224,6 +251,5 @@ module RatatuiRuby
   private_class_method :_get_cell_at
 
   # Hide native Layout._split helper
-  Layout.singleton_class.send(:private, :_split)
-
+  Layout.singleton_class.__send__(:private, :_split)
 end

data/{examples/sparkline_demo → sig/examples/app_all_events}/app.rbs

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

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

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

@@ -0,0 +1,15 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+class Events
+  def initialize: () -> void
+  def record: (Symbol type, ?time: Time, ?description: String, ?sub_key: Symbol | String | nil, ?data: Hash[Symbol, untyped], ?live_type: Symbol) -> void
+  def live_event: (Symbol type) -> { time: Time, description: String } | nil
+  def live_events: () -> Hash[Symbol, { time: Time, description: String }]
+  def visible: (Integer max_entries) -> Array[EventEntry]
+  def empty?: () -> bool
+  def count: (Symbol type, ?Symbol | nil sub_type) -> Integer
+  def count_by_kind: (String kind) -> Integer
+  def lit?: (Symbol type, ?Symbol | String | nil sub_key) -> bool
+  def entries: () -> Array[EventEntry]
+end

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

@@ -0,0 +1,11 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+class Timestamp < Data
+  attr_reader milliseconds: Integer
+
+  def self.now: () -> instance
+  def self.current: () -> Integer
+  def elapsed?: (Integer duration_ms) -> bool
+  def self.new: (?milliseconds: Numeric) -> instance
+end

data/sig/examples/app_all_events/view/app_view.rbs

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+class View::App
+  include View::_View
+
+  def initialize: () -> void
+end

data/sig/examples/app_all_events/view/controls_view.rbs

@@ -0,0 +1,6 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+class View::Controls
+  include View::_View
+end

data/sig/examples/app_all_events/view/counts_view.rbs

@@ -0,0 +1,6 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+class View::Counts
+  include View::_View
+end

data/sig/examples/app_all_events/view/live_view.rbs

@@ -0,0 +1,6 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+class View::Live
+  include View::_View
+end

data/sig/examples/app_all_events/view/log_view.rbs

@@ -0,0 +1,6 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+class View::Log
+  include View::_View
+end

data/sig/examples/app_all_events/view.rbs

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module View
+  interface _View
+    def call(state: ViewState, tui: RatatuiRuby::Session, frame: RatatuiRuby::Frame, area: RatatuiRuby::Rect) -> void
+  end
+end

data/sig/examples/app_all_events/view_state.rbs

@@ -0,0 +1,15 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+class ViewState < Data
+  attr_reader events: Events
+  attr_reader focused: bool
+  attr_reader hotkey_style: RatatuiRuby::Style
+  attr_reader dimmed_style: RatatuiRuby::Style
+  attr_reader lit_style: RatatuiRuby::Style
+  attr_reader border_color: Symbol
+  attr_reader area: RatatuiRuby::Rect?
+
+  def self.build(events: Events, focused: bool, tui: RatatuiRuby::Session, _resize_sub_counter: untyped) -> instance
+  def self.new: (?events: Events, ?focused: bool, ?hotkey_style: RatatuiRuby::Style, ?dimmed_style: RatatuiRuby::Style, ?lit_style: RatatuiRuby::Style, ?border_color: Symbol, ?area: RatatuiRuby::Rect | nil) -> instance
+end

data/{examples/list_demo → sig/examples/app_color_picker}/app.rbs

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

data/sig/examples/app_login_form/app.rbs

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

data/sig/examples/app_map_demo/app.rbs

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

data/sig/examples/app_table_select/app.rbs

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

data/sig/examples/verify_quickstart_dsl/app.rbs

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

data/sig/examples/verify_quickstart_lifecycle/app.rbs

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

data/sig/examples/verify_readme_usage/app.rbs

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

data/sig/examples/widget_block_padding/app.rbs

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

data/sig/examples/widget_block_titles/app.rbs

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