ratatui_ruby 0.5.0 → 0.6.0

data/lib/ratatui_ruby/table_state.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # Mutable state object for Table widgets.
+  #
+  # When using {Frame#render_stateful_widget}, the State object is the
+  # *single source of truth* for selection and scroll offset. Widget
+  # properties (+selected_row+, +selected_column+, +offset+) are *ignored*
+  # in stateful mode.
+  #
+  # == Example
+  #
+  #   @table_state = RatatuiRuby::TableState.new
+  #   @table_state.select(1)        # Select second row
+  #   @table_state.select_column(0) # Select first column
+  #
+  #   RatatuiRuby.draw do |frame|
+  #     table = RatatuiRuby::Table.new(rows: [...], widths: [...])
+  #     frame.render_stateful_widget(table, frame.area, @table_state)
+  #   end
+  #
+  class TableState
+    ##
+    # :method: new
+    # :call-seq: new(selected = nil) -> TableState
+    #
+    # Creates a new TableState with optional initial row selection.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: select
+    # :call-seq: select(index) -> nil
+    #
+    # Sets the selected row index. Pass +nil+ to deselect.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: selected
+    # :call-seq: selected() -> Integer or nil
+    #
+    # Returns the currently selected row index.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: select_column
+    # :call-seq: select_column(index) -> nil
+    #
+    # Sets the selected column index. Pass +nil+ to deselect.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: selected_column
+    # :call-seq: selected_column() -> Integer or nil
+    #
+    # Returns the currently selected column index.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: offset
+    # :call-seq: offset() -> Integer
+    #
+    # Returns the current scroll offset.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: scroll_down_by
+    # :call-seq: scroll_down_by(n) -> nil
+    #
+    # Scrolls down by +n+ rows.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: scroll_up_by
+    # :call-seq: scroll_up_by(n) -> nil
+    #
+    # Scrolls up by +n+ rows.
+    #
+    # (Native method implemented in Rust)
+  end
+end

data/lib/ratatui_ruby/test_helper/event_injection.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  module TestHelper
+    ##
+    # Event injection helpers for testing TUI interactions.
+    #
+    # Testing keyboard navigation and mouse clicks requires simulating user input.
+    # Constructing event objects by hand for every test is verbose and repetitive.
+    #
+    # This mixin provides convenience methods to inject keys, clicks, and other events
+    # into the test terminal's event queue. Events are consumed by the next
+    # <tt>poll_event</tt> call.
+    #
+    # Use it to simulate user interactions: typing, clicking, dragging, pasting.
+    #
+    # === Examples
+    #
+    #   with_test_terminal do
+    #     inject_keys("h", "e", "l", "l", "o")
+    #     inject_keys(:enter, :ctrl_s)
+    #     inject_click(x: 10, y: 5)
+    #     inject_event(RatatuiRuby::Event::Paste.new(content: "pasted text"))
+    #
+    #     @app.run
+    #   end
+    #
+    module EventInjection
+      ##
+      # Injects an event into the test terminal's event queue.
+      #
+      # Pass any <tt>RatatuiRuby::Event</tt> object. The event is returned by
+      # the next <tt>poll_event</tt> call.
+      #
+      # Raises <tt>RuntimeError</tt> if called outside a <tt>with_test_terminal</tt> block.
+      #
+      # === Examples
+      #
+      #   inject_event(RatatuiRuby::Event::Key.new(code: "q"))
+      #   inject_event(RatatuiRuby::Event::Mouse.new(kind: "down", button: "left", x: 10, y: 5))
+      #   inject_event(RatatuiRuby::Event::Paste.new(content: "Hello"))
+      #
+      # [event] A <tt>RatatuiRuby::Event</tt> object.
+      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.
+      #
+      # === Example
+      #
+      #   inject_mouse(x: 10, y: 5, kind: :down, button: :left)
+      #
+      # [x] Integer x-coordinate.
+      # [y] Integer y-coordinate.
+      # [kind] Symbol <tt>:down</tt>, <tt>:up</tt>, or <tt>:drag</tt>.
+      # [button] Symbol <tt>:left</tt>, <tt>:right</tt>, or <tt>:middle</tt>.
+      # [modifiers] Array of modifier strings.
+      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 left mouse click.
+      #
+      # === Example
+      #
+      #   inject_click(x: 10, y: 5)
+      def inject_click(x:, y:, modifiers: [])
+        inject_mouse(x:, y:, kind: :down, modifiers:, button: :left)
+      end
+
+      ##
+      # Injects a right mouse click.
+      #
+      # === Example
+      #
+      #   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.
+      #
+      # === Example
+      #
+      #   inject_drag(x: 10, y: 5)
+      def inject_drag(x:, y:, modifiers: [], button: :left)
+        inject_mouse(x:, y:, kind: :drag, modifiers:, button:)
+      end
+
+      ##
+      # Injects one or more key events.
+      #
+      # Accepts multiple formats for convenience:
+      # - String: Character key (e.g., <tt>"a"</tt>, <tt>"q"</tt>)
+      # - Symbol: Named key or modifier combo (e.g., <tt>:enter</tt>, <tt>:ctrl_c</tt>)
+      # - Hash: Passed to <tt>Key.new</tt>
+      # - Key: Passed directly
+      #
+      # === Examples
+      #
+      #   inject_keys("a", "b", "c")
+      #   inject_keys(:enter, :esc)
+      #   inject_keys(:ctrl_c, :alt_shift_left)
+      #   inject_keys("j", { code: "k", modifiers: ["ctrl"] })
+      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
+    end
+  end
+end

data/lib/ratatui_ruby/test_helper/snapshot.rb

@@ -0,0 +1,390 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require "fileutils"
+
+module RatatuiRuby
+  module TestHelper
+    ##
+    # Snapshot testing assertions for terminal UIs.
+    #
+    # Verifying every character of a TUI screen by hand is tedious. Snapshots let you
+    # capture the screen once and compare against it in future runs.
+    #
+    # This mixin provides <tt>assert_snapshot</tt> for plain text and
+    # <tt>assert_rich_snapshot</tt> for styled ANSI output. Both auto-create
+    # snapshot files on first run.
+    #
+    # Use it to verify complex layouts, styles, and interactions without manual assertions.
+    #
+    # === Snapshot Files
+    #
+    # Snapshots live in a <tt>snapshots/</tt> subdirectory next to your test file:
+    #
+    #   test/examples/my_app/test_app.rb
+    #   test/examples/my_app/snapshots/initial_render.txt
+    #   test/examples/my_app/snapshots/initial_render.ansi
+    #
+    # === Creating and Updating Snapshots
+    #
+    # Run tests with <tt>UPDATE_SNAPSHOTS=1</tt> to create or refresh snapshots:
+    #
+    #   UPDATE_SNAPSHOTS=1 bundle exec rake test
+    #
+    # === Seeding Random Data
+    #
+    # Random data (scatter plots, generated content) breaks snapshot stability.
+    # Use a seeded <tt>Random</tt> instance instead of <tt>Kernel.rand</tt>:
+    #
+    #   class MyApp
+    #     def initialize(seed: nil)
+    #       @rng = seed ? Random.new(seed) : Random.new
+    #     end
+    #
+    #     def generate_data
+    #       (0..20).map { @rng.rand(0.0..10.0) }
+    #     end
+    #   end
+    #
+    #   # In your test
+    #   def setup
+    #     @app = MyApp.new(seed: 42)
+    #   end
+    #
+    # For libraries like Faker, see their docs on deterministic random:
+    # https://github.com/faker-ruby/faker#deterministic-random
+    #
+    # === Normalization Blocks
+    #
+    # Mask dynamic content (timestamps, IDs) with a normalization block:
+    #
+    #   assert_snapshot("dashboard") do |lines|
+    #     lines.map { |l| l.gsub(/\d{4}-\d{2}-\d{2}/, "YYYY-MM-DD") }
+    #   end
+    #
+    module Snapshot
+      ##
+      # 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.
+      #
+      # == Non-Determinism
+      #
+      # To prevent flaky tests, this assertion performs a "Flakiness Check" when creating or updating
+      # snapshots. It captures the screen content, immediately re-renders the buffer, and compares
+      # the two results.
+      #
+      # Ensure your render logic is deterministic by seeding random number generators and stubbing
+      # time where necessary.
+      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))
+
+            content_to_write = "#{actual_lines.join("\n")}\n"
+
+            begin
+              # Delete old file first to avoid git index stale-read issues
+              FileUtils.rm_f(snapshot_path)
+
+              # Write with explicit mode to ensure clean write
+              File.write(snapshot_path, content_to_write, mode: "w")
+
+              # Flush filesystem buffers to ensure durability
+              File.open(snapshot_path, "r", &:fsync) if File.exist?(snapshot_path)
+            rescue => e
+              warn "Failed to write snapshot #{snapshot_path}: #{e.message}"
+              raise
+            end
+
+            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
+
+      ##
+      # Asserts that the current screen content (including colors!) matches a stored ANSI snapshot.
+      #
+      # Generates/Compares against a file with <tt>.ansi</tt> extension.
+      # You can <tt>cat</tt> this file to see exactly what the screen looked like.
+      #
+      #   assert_rich_snapshot("login_screen")
+      #
+      #   # With normalization
+      #   assert_rich_snapshot("log_view") do |lines|
+      #     lines.map { |l| l.gsub(/\d{2}:\d{2}:\d{2}/, "HH:MM:SS") }
+      #   end
+      #
+      # [name] String snapshot name.
+      # [msg] String optional failure message.
+      def assert_rich_snapshot(name, msg = nil)
+        caller_path = caller_locations(1, 1).first.path
+        snapshot_dir = File.join(File.dirname(caller_path), "snapshots")
+        snapshot_path = File.join(snapshot_dir, "#{name}.ansi")
+
+        actual_content = _render_buffer_with_ansi
+
+        if block_given?
+          lines = actual_content.split("\n")
+          # Yield lines to user block for modification (e.g. masking IDs/Times)
+          lines = yield(lines)
+          actual_content = "#{lines.join("\n")}\n"
+        end
+
+        update_snapshots = ENV["UPDATE_SNAPSHOTS"] == "1" || ENV["UPDATE_SNAPSHOTS"] == "true"
+
+        if !File.exist?(snapshot_path) || update_snapshots
+          FileUtils.mkdir_p(File.dirname(snapshot_path))
+
+          begin
+            # Delete old file first to avoid git index stale-read issues
+            FileUtils.rm_f(snapshot_path)
+
+            # Write with explicit mode to ensure clean write
+            File.write(snapshot_path, actual_content, mode: "w")
+
+            # Flush filesystem buffers to ensure durability
+            File.open(snapshot_path, "r", &:fsync) if File.exist?(snapshot_path)
+          rescue => e
+            warn "Failed to write rich snapshot #{snapshot_path}: #{e.message}"
+            raise
+          end
+
+          puts (update_snapshots ? "Updated" : "Created") + " rich snapshot: #{snapshot_path}"
+
+        end
+
+        expected_content = File.read(snapshot_path)
+
+        # Compare byte-for-byte first
+        if expected_content != actual_content
+          # Fallback to line-by-line diff for better error messages
+          expected_lines = expected_content.split("\n")
+          actual_lines = actual_content.split("\n")
+
+          assert_equal expected_lines.size, actual_lines.size, "#{msg}: Line count mismatch"
+
+          expected_lines.each_with_index do |exp, i|
+            act = actual_lines[i]
+            assert_equal exp, act, "#{msg}: Rich content mismatch at line #{i + 1}"
+          end
+        end
+      end
+
+      private def _render_buffer_with_ansi
+        RatatuiRuby.get_buffer_content # Ensure buffer is fresh if needed
+
+        lines = buffer_content
+        height = lines.size
+        width = lines.first&.length || 0
+
+        output = String.new
+
+        (0...height).each do |y|
+          current_fg = nil
+          current_bg = nil
+          current_modifiers = []
+
+          # Reset at start of line
+          output << "\e[0m"
+
+          (0...width).each do |x|
+            cell = RatatuiRuby.get_cell_at(x, y)
+            char = cell.char || " "
+
+            # Check for changes
+            fg_changed = cell.fg != current_fg
+            bg_changed = cell.bg != current_bg
+            mod_changed = cell.modifiers != current_modifiers
+
+            if fg_changed || bg_changed || mod_changed
+              # If modifiers change, easiest is to reset and re-apply everything
+              # because removing a modifier (e.g. bold) requires reset usually.
+              if mod_changed
+                output << "\e[0m"
+                output << _ansi_for_modifiers(cell.modifiers)
+                # Force re-apply colors after reset
+                output << _ansi_for_color(cell.fg, :fg)
+                output << _ansi_for_color(cell.bg, :bg)
+              else
+                # Modifiers same, just update colors if needed
+                output << _ansi_for_color(cell.fg, :fg) if fg_changed
+                output << _ansi_for_color(cell.bg, :bg) if bg_changed
+              end
+
+              current_fg = cell.fg
+              current_bg = cell.bg
+              current_modifiers = cell.modifiers
+            end
+
+            output << char
+          rescue
+            output << " "
+          end
+          output << "\e[0m\n" # Reset at end of line
+        end
+        output
+      end
+
+      private def _ansi_for_color(color, layer)
+        return "" if color.nil?
+
+        base = (layer == :fg) ? 38 : 48
+
+        case color
+        when Symbol
+          if color.to_s.start_with?("indexed_")
+            # Extracted indexed color :indexed_5 -> 5
+            idx = color.to_s.split("_").last.to_i
+            "\e[#{base};5;#{idx}m"
+          else
+            # Named colors
+            _ansi_named_color(color, layer == :fg)
+          end
+        when String
+          if color.start_with?("#")
+            # Hex color: #RRGGBB -> r;g;b
+            r = color[1..2].to_i(16)
+            g = color[3..4].to_i(16)
+            b = color[5..6].to_i(16)
+            "\e[#{base};2;#{r};#{g};#{b}m"
+          else
+            ""
+          end
+        else
+          ""
+        end
+      end
+
+      private def _ansi_named_color(name, is_fg)
+        # Map symbol to standard ANSI code offset
+        # FG: 30-37 (dim), 90-97 (bright)
+        # BG: 40-47 (dim), 100-107 (bright)
+
+        offset = is_fg ? 30 : 40
+
+        case name
+        when :black then "\e[#{offset}m"
+        when :red then "\e[#{offset + 1}m"
+        when :green then "\e[#{offset + 2}m"
+        when :yellow then "\e[#{offset + 3}m"
+        when :blue then "\e[#{offset + 4}m"
+        when :magenta then "\e[#{offset + 5}m"
+        when :cyan then "\e[#{offset + 6}m"
+        when :gray then is_fg ? "\e[90m" : "\e[100m" # Dark gray usually
+        when :dark_gray then is_fg ? "\e[90m" : "\e[100m"
+        when :light_red then "\e[#{offset + 60 + 1}m"
+        when :light_green then "\e[#{offset + 60 + 2}m"
+        when :light_yellow then "\e[#{offset + 60 + 3}m"
+        when :light_blue then "\e[#{offset + 60 + 4}m"
+        when :light_magenta then "\e[#{offset + 60 + 5}m"
+        when :light_cyan then "\e[#{offset + 60 + 6}m"
+        when :white then "\e[#{offset + 60 + 7}m"
+        else ""
+        end
+      end
+
+      private def _ansi_for_modifiers(modifiers)
+        return "" if modifiers.nil? || modifiers.empty?
+
+        seq = []
+        seq << "1" if modifiers.include?(:bold)
+        seq << "2" if modifiers.include?(:dim)
+        seq << "3" if modifiers.include?(:italic)
+        seq << "4" if modifiers.include?(:underlined)
+        seq << "5" if modifiers.include?(:slow_blink)
+        seq << "6" if modifiers.include?(:rapid_blink)
+        seq << "7" if modifiers.include?(:reversed)
+        seq << "8" if modifiers.include?(:hidden)
+        seq << "9" if modifiers.include?(:crossed_out)
+
+        if seq.any?
+          "\e[#{seq.join(';')}m"
+        else
+          ""
+        end
+      end
+    end
+  end
+end