ratatui_ruby 1.4.0-x86_64-linux

data/lib/ratatui_ruby/test_helper/terminal.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+require "timeout"
+require "minitest/mock"
+
+module RatatuiRuby
+  module TestHelper
+    ##
+    # Terminal setup and buffer inspection for TUI tests.
+    #
+    # Testing TUIs against a real terminal is slow, flaky, and hard to automate.
+    # Initializing, cleaning up, and inspecting terminal state by hand is tedious.
+    #
+    # This mixin wraps a headless test terminal. It handles setup, teardown,
+    # and provides methods to query buffer content, cursor position, and cell styles.
+    #
+    # Use it to write fast, deterministic tests for your TUI applications.
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   class MyTest < Minitest::Test
+    #     include RatatuiRuby::TestHelper
+    #
+    #     def test_rendering
+    #       with_test_terminal(80, 24) do
+    #         MyApp.new.run_once
+    #         assert_includes buffer_content.join, "Hello"
+    #       end
+    #     end
+    #   end
+    #--
+    # SPDX-SnippetEnd
+    #++
+    module Terminal
+      ##
+      # Initializes a test terminal context with specified dimensions.
+      # Restores the original terminal state after the block executes.
+      #
+      # [width] Integer width of the test terminal (default: 80).
+      # [height] Integer height of the test terminal (default: 24).
+      # [timeout] Integer maximum execution time in seconds (default: 2). Pass <tt>nil</tt> to disable.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   with_test_terminal(120, 40) do
+      #     # render and test your app
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def with_test_terminal(width = 80, height = 24, **opts)
+        # Defensive cleanup: reset any stale session state from previous test failures
+        RatatuiRuby.instance_variable_set(:@tui_session_active, false)
+
+        # Extract and resolve viewport
+        viewport_param = opts[:viewport]
+        viewport = case viewport_param
+        when nil then RatatuiRuby::Terminal::Viewport.fullscreen
+        when RatatuiRuby::Terminal::Viewport then viewport_param
+        end
+
+        RatatuiRuby.init_test_terminal(width, height, viewport.type.to_s, viewport.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
+
+      ##
+      # Current content of the terminal buffer as an array of strings.
+      # Each string represents one row.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   buffer_content
+      #   # => ["Row 1 text", "Row 2 text", ...]
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def buffer_content
+        RatatuiRuby.get_buffer_content.split("\n")
+      end
+
+      ##
+      # Current cursor position as a hash with <tt>:x</tt> and <tt>:y</tt> keys.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   cursor_position
+      #   # => { x: 0, y: 0 }
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def cursor_position
+        x, y = RatatuiRuby.get_cursor_position
+        { x:, y: }
+      end
+
+      ##
+      # Cell attributes at the given coordinates.
+      #
+      # Returns a hash with <tt>"symbol"</tt>, <tt>"fg"</tt>, and <tt>"bg"</tt> keys.
+      #
+      # [x] Integer column position (0-indexed).
+      # [y] Integer row position (0-indexed).
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   get_cell(0, 0)
+      #   # => { "symbol" => "H", "fg" => :red, "bg" => nil }
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def get_cell(x, y)
+        RatatuiRuby.get_cell_at(x, y)
+      end
+
+      ##
+      # Prints the current buffer to STDOUT with full ANSI colors.
+      # Useful for debugging test failures.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   with_test_terminal do
+      #     MyApp.new.render
+      #     print_buffer  # see exactly what would display
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def print_buffer
+        puts _render_buffer_with_ansi
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/test_helper/test_doubles.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module TestHelper
+    ##
+    # Test doubles for view testing.
+    #
+    # View tests verify widget rendering without a real terminal. Real frames draw
+    # to the screen. Real rects come from terminal dimensions. Mocking both by hand
+    # is tedious.
+    #
+    # This mixin provides <tt>MockFrame</tt> to capture rendered widgets and
+    # <tt>StubRect</tt> to supply fixed dimensions.
+    #
+    # Use them to test view logic in isolation.
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   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
+    #--
+    # SPDX-SnippetEnd
+    #++
+    module TestDoubles
+      ##
+      # Mock frame for view tests.
+      #
+      # Captures widgets passed to <tt>render_widget</tt> for later inspection.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   frame = MockFrame.new
+      #   View::Log.new.call(state, tui, frame, area)
+      #   widget = frame.rendered_widgets.first[:widget]
+      #   assert_equal "Event Log", widget.block.title
+      #--
+      # SPDX-SnippetEnd
+      #++
+      MockFrame = Data.define(:rendered_widgets) do
+        def initialize(rendered_widgets: [])
+          super
+        end
+
+        def render_widget(widget, area)
+          rendered_widgets << { widget:, area: }
+        end
+      end
+
+      ##
+      # Stub rect with fixed dimensions.
+      #
+      # [x] Integer left edge (default: 0).
+      # [y] Integer top edge (default: 0).
+      # [width] Integer width in cells (default: 80).
+      # [height] Integer height in cells (default: 24).
+      #
+      # === Example
+      #
+      #   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
+    end
+  end
+end

data/lib/ratatui_ruby/test_helper.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+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"
+require_relative "test_helper/global_state"
+require_relative "test_helper/subprocess_timeout"
+
+module RatatuiRuby
+  ##
+  # Helpers for testing RatatuiRuby applications.
+  #
+  # 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.
+  #
+  # 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.
+  # [GlobalState] Provides with_argv and with_env helpers for testing global state access.
+  #
+  # == Example
+  #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
+  #   require "ratatui_ruby/test_helper"
+  #
+  #   class TestMyApp < Minitest::Test
+  #     include RatatuiRuby::TestHelper
+  #
+  #     def test_initial_render
+  #       with_test_terminal(80, 24) do
+  #         MyApp.new.run_once
+  #         assert_snapshots("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_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
+  #--
+  # SPDX-SnippetEnd
+  #++
+  module TestHelper
+    ##
+    # Auto-enables debug mode when TestHelper is included.
+    #
+    # This ensures Rust backtraces are available in tests.
+    # Skips remote debugging since tests don't need it.
+    def self.included(base)
+      RatatuiRuby::Debug.enable!(source: :test)
+    end
+
+    include Terminal
+    include Snapshot
+    include EventInjection
+    include StyleAssertions
+    include TestDoubles
+    include GlobalState
+    include SubprocessTimeout
+  end
+end

data/lib/ratatui_ruby/text/line.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Text
+    # A sequence of styled spans.
+    #
+    # Words form sentences. Spans form lines.
+    #
+    # This class composes multiple {Span} objects into a single horizontal row of text.
+    # It handles the layout of rich text fragments within the flow of a paragraph.
+    #
+    # Use it to build multi-colored headers, status messages, or log entries.
+    #
+    # === Examples
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2025 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   Text::Line.new(
+    #     spans: [
+    #       Text::Span.styled("User: ", Style.new(modifiers: [:bold])),
+    #       Text::Span.styled("kerrick", Style.new(fg: :blue))
+    #     ]
+    #   )
+    #--
+    # SPDX-SnippetEnd
+    #++
+    class Line < Data.define(:spans, :alignment, :style)
+      ##
+      # :attr_reader: spans
+      # Array of Span objects.
+
+      ##
+      # :attr_reader: alignment
+      # Alignment within the container.
+      #
+      # <tt>:left</tt>, <tt>:center</tt>, or <tt>:right</tt>.
+
+      ##
+      # :attr_reader: style
+      # Line-level style applied to all spans.
+      #
+      # A Style object that sets colors/modifiers for the entire line.
+
+      # Creates a new Line.
+      #
+      # [spans] Array of Span objects (or Strings).
+      # [alignment] Symbol (optional).
+      # [style] Style object (optional).
+      def initialize(spans: [], alignment: nil, style: nil)
+        super
+      end
+
+      # Creates a simple line from a string.
+      #
+      #   Text::Line.from_string("Hello")
+      def self.from_string(content, alignment: nil)
+        new(spans: [Span.new(content:, style: nil)], alignment:)
+      end
+
+      # Calculates the display width of this line in terminal cells.
+      #
+      # Sums the widths of all span contents using the same unicode-aware
+      # algorithm as Text.width. Useful for layout calculations.
+      #
+      # === Examples
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   line = Text::Line.new(spans: [
+      #     Text::Span.new(content: "Hello "),
+      #     Text::Span.new(content: "世界")
+      #   ])
+      #   line.width  # => 10 (6 ASCII + 4 CJK)
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # Returns: Integer (number of terminal cells).
+      def width
+        RatatuiRuby::Text.width(spans.map { |s| s.content.to_s }.join)
+      end
+
+      # Left-aligns this line of text.
+      #
+      # Convenience shortcut for <tt>alignment: :left</tt>. Setting the alignment of a Line
+      # overrides the alignment of its parent Text or Widget.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   line = Text::Line.new(spans: [Text::Span.new(content: "Hello")])
+      #   aligned = line.left_aligned
+      #   aligned.alignment  # => :left
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # Returns: Line.
+      def left_aligned
+        with(alignment: :left)
+      end
+
+      # Center-aligns this line of text.
+      #
+      # Convenience shortcut for <tt>alignment: :center</tt>. Setting the alignment of a Line
+      # overrides the alignment of its parent Text or Widget.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   line = Text::Line.new(spans: [Text::Span.new(content: "Hello")])
+      #   centered = line.centered
+      #   centered.alignment  # => :center
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # Returns: Line.
+      def centered
+        with(alignment: :center)
+      end
+
+      # Right-aligns this line of text.
+      #
+      # Convenience shortcut for <tt>alignment: :right</tt>. Setting the alignment of a Line
+      # overrides the alignment of its parent Text or Widget.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   line = Text::Line.new(spans: [Text::Span.new(content: "Hello")])
+      #   aligned = line.right_aligned
+      #   aligned.alignment  # => :right
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # Returns: Line.
+      def right_aligned
+        with(alignment: :right)
+      end
+
+      # Adds a span to the line.
+      #
+      # Since Line is immutable (a Data subclass), this returns a new Line with the span appended.
+      # The original line remains unchanged.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   line = Text::Line.new(spans: [Text::Span.new(content: "Hello, ")])
+      #   extended = line.push_span(Text::Span.new(content: "world!"))
+      #   extended.spans.size  # => 2
+      #   line.spans.size      # => 1 (original unchanged)
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # [span] Span to append.
+      #
+      # Returns: Line.
+      def push_span(span)
+        with(spans: spans + [span])
+      end
+
+      # Patches the style of this line, adding modifiers from the given style.
+      #
+      # Applies <tt>patch_style</tt> to each span in the line. Use this when you want to layer
+      # styles on all spans without replacing their existing styles.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   line = Text::Line.new(spans: [Text::Span.new(content: "Hello")])
+      #   styled = line.patch_style(Style::Style.new(fg: :red))
+      #   styled.spans.first.style.fg  # => :red
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # [patch] Style::Style to merge onto each span.
+      #
+      # Returns: Line.
+      def patch_style(patch)
+        with(spans: spans.map { |s| s.patch_style(patch) })
+      end
+
+      # Resets the style of this line.
+      #
+      # Applies <tt>reset_style</tt> to each span in the line, clearing all styling.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   line = Text::Line.new(spans: [
+      #     Text::Span.new(content: "styled", style: Style::Style.new(fg: :red))
+      #   ])
+      #   reset = line.reset_style
+      #   reset.spans.first.style  # => nil
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # Returns: Line.
+      def reset_style
+        with(spans: spans.map(&:reset_style))
+      end
+    end
+  end
+end