ratatui_ruby 0.8.0 → 0.9.1

data/lib/ratatui_ruby/table_state.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
 module RatatuiRuby
@@ -15,6 +15,11 @@ module RatatuiRuby
   #
   # == Example
   #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
   #   @table_state = RatatuiRuby::TableState.new
   #   @table_state.select(1)        # Select second row
   #   @table_state.select_column(0) # Select first column
@@ -24,6 +29,9 @@ module RatatuiRuby
   #     frame.render_stateful_widget(table, frame.area, @table_state)
   #   end
   #
+  #--
+  # SPDX-SnippetEnd
+  #++
   class TableState
     ##
     # :method: new

data/lib/ratatui_ruby/terminal_lifecycle.rb

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-#
-# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
 module RatatuiRuby
@@ -27,6 +26,11 @@ module RatatuiRuby
     #
     # === Example
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   def log(message)
     #     if RatatuiRuby.terminal_active?
     #       @deferred_logs << message
@@ -34,6 +38,9 @@ module RatatuiRuby
     #       puts message
     #     end
     #   end
+    #--
+    # SPDX-SnippetEnd
+    #++
     def terminal_active?
       @tui_session_active
     end
@@ -112,11 +119,19 @@ module RatatuiRuby
     #
     # === Example
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   RatatuiRuby.run(focus_events: false) do |tui|
     #     tui.draw(tui.paragraph(text: "Hi"))
     #     sleep 1
     #   end
     #
+    #--
+    # SPDX-SnippetEnd
+    #++
     # @raise [Error::Invariant] if headless mode is enabled
     # @see headless!
     def run(focus_events: true, bracketed_paste: true)

data/lib/ratatui_ruby/test_helper/event_injection.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
 module RatatuiRuby
@@ -21,6 +21,11 @@ module RatatuiRuby
     #
     # === Examples
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   with_test_terminal do
     #     inject_keys("h", "e", "l", "l", "o")
     #     inject_keys(:enter, :ctrl_s)
@@ -30,6 +35,9 @@ module RatatuiRuby
     #     @app.run
     #   end
     #
+    #--
+    # SPDX-SnippetEnd
+    #++
     module EventInjection
       ##
       # Injects an event into the test terminal's event queue.
@@ -41,10 +49,18 @@ module RatatuiRuby
       #
       # === Examples
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   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"))
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # [event] A <tt>RatatuiRuby::Event</tt> object.
       def inject_event(event)
         unless @_ratatui_test_terminal_active
@@ -72,6 +88,9 @@ module RatatuiRuby
           RatatuiRuby.inject_test_event("focus_gained", {})
         when RatatuiRuby::Event::FocusLost
           RatatuiRuby.inject_test_event("focus_lost", {})
+        when RatatuiRuby::Event::Sync
+          # Sync events use the engine-level synthetic queue
+          RatatuiRuby::SyntheticEvents.push(event)
         else
           raise ArgumentError, "Unknown event type: #{event.class}"
         end
@@ -82,8 +101,16 @@ module RatatuiRuby
       #
       # === Example
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   inject_mouse(x: 10, y: 5, kind: :down, button: :left)
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # [x] Integer x-coordinate.
       # [y] Integer y-coordinate.
       # [kind] Symbol <tt>:down</tt>, <tt>:up</tt>, or <tt>:drag</tt>.
@@ -141,10 +168,18 @@ module RatatuiRuby
       #
       # === Examples
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   inject_keys("a", "b", "c")
       #   inject_keys(:enter, :esc)
       #   inject_keys(:ctrl_c, :alt_shift_left)
       #   inject_keys("j", { code: "k", modifiers: ["ctrl"] })
+      #--
+      # SPDX-SnippetEnd
+      #++
       def inject_keys(*args)
         args.each do |arg|
           event = case arg
@@ -166,6 +201,31 @@ module RatatuiRuby
         end
       end
       alias inject_key inject_keys
+
+      ##
+      # Injects a Sync event.
+      #
+      # When a runtime (Tea, Kit) encounters this event, it should wait for all
+      # pending async operations to complete before processing the next event.
+      # This enables deterministic testing of async behavior.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   inject_key("s")           # Triggers async command
+      #   inject_sync               # Wait for command to complete
+      #   inject_key(:q)            # Quit after seeing results
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def inject_sync
+        inject_event(RatatuiRuby::Event::Sync.new)
+      end
     end
   end
 end

data/lib/ratatui_ruby/test_helper/snapshot.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
 require "fileutils"
@@ -26,21 +26,42 @@ module RatatuiRuby
     #
     # Snapshots live in a <tt>snapshots/</tt> subdirectory next to your test file:
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   test/examples/my_app/test_app.rb
     #   test/examples/my_app/snapshots/initial_render.txt
     #   test/examples/my_app/snapshots/initial_render.ansi
     #
+    #--
+    # SPDX-SnippetEnd
+    #++
     # === Creating and Updating Snapshots
     #
     # Run tests with <tt>UPDATE_SNAPSHOTS=1</tt> to create or refresh snapshots:
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   UPDATE_SNAPSHOTS=1 bundle exec rake test
     #
+    #--
+    # SPDX-SnippetEnd
+    #++
     # === 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>:
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   class MyApp
     #     def initialize(seed: nil)
     #       @rng = seed ? Random.new(seed) : Random.new
@@ -56,6 +77,9 @@ module RatatuiRuby
     #     @app = MyApp.new(seed: 42)
     #   end
     #
+    #--
+    # SPDX-SnippetEnd
+    #++
     # For libraries like Faker, see their docs on deterministic random:
     # https://github.com/faker-ruby/faker#deterministic-random
     #
@@ -63,10 +87,18 @@ module RatatuiRuby
     #
     # Mask dynamic content (timestamps, IDs) with a normalization block:
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   assert_snapshots("dashboard") do |lines|
     #     lines.map { |l| l.gsub(/\d{4}-\d{2}-\d{2}/, "YYYY-MM-DD") }
     #   end
     #
+    #--
+    # SPDX-SnippetEnd
+    #++
     module Snapshot
       ##
       # Asserts that the current screen content matches a stored plain text snapshot.
@@ -78,6 +110,11 @@ module RatatuiRuby
       # Plain text snapshots are human-readable when viewed in any editor or diff tool. They
       # pair well with rich snapshots for documentation. Use <tt>assert_snapshots</tt> to generate both.
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   assert_plain_snapshot("login_screen")
       #   # Compares against: test/snapshots/login_screen.txt
       #
@@ -86,6 +123,9 @@ module RatatuiRuby
       #     actual.map { |l| l.gsub(/\d{2}:\d{2}/, "XX:XX") }
       #   end
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # [name] String name of the snapshot (without extension).
       # [msg] String optional failure message.
       def assert_plain_snapshot(name, msg = nil, snapshot_dir: nil, &)
@@ -96,13 +136,6 @@ module RatatuiRuby
         assert_screen_matches(snapshot_path, msg, &)
       end
 
-      ##
-      # @deprecated Use {#assert_plain_snapshot} instead.
-      def assert_snapshot(name, msg = nil, &)
-        warn "assert_snapshot is deprecated; use assert_plain_snapshot instead", uplevel: 1
-        assert_plain_snapshot(name, msg, &)
-      end
-
       ##
       # Asserts that the current screen content matches the expected content.
       #
@@ -117,6 +150,11 @@ module RatatuiRuby
       #
       # == Usage
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   # Direct comparison
       #   assert_screen_matches(["Line 1", "Line 2"])
       #
@@ -128,6 +166,9 @@ module RatatuiRuby
       #     lines.map { |l| l.gsub(/User ID: \d+/, "User ID: XXX") }
       #   end
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # [expected] String (file path) or Array<String> (content).
       # [msg] String optional failure message.
       #
@@ -204,6 +245,11 @@ module RatatuiRuby
       # The <tt>.ansi</tt> snapshot files contain ANSI escape codes. You can <tt>cat</tt> them in a terminal
       # to see exactly what the screen looked like.
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   assert_rich_snapshot("login_screen")
       #   # Compares against: test/snapshots/login_screen.ansi
       #
@@ -212,6 +258,9 @@ module RatatuiRuby
       #     lines.map { |l| l.gsub(/\d{2}:\d{2}:\d{2}/, "HH:MM:SS") }
       #   end
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # [name] String snapshot name.
       # [msg] String optional failure message.
       def assert_rich_snapshot(name, msg = nil, snapshot_dir: nil)
@@ -277,6 +326,11 @@ module RatatuiRuby
       # human-readable in any editor or diff tool, making them valuable for documentation and
       # code review. Together, they provide comprehensive coverage and discoverability.
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   assert_snapshots("login_screen")
       #   # Creates/compares: snapshots/login_screen.txt AND snapshots/login_screen.ansi
       #
@@ -285,6 +339,9 @@ module RatatuiRuby
       #     lines.map { |l| l.gsub(/\d{2}:\d{2}:\d{2}/, "HH:MM:SS") }
       #   end
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # [name] String snapshot name (without extension).
       # [msg] String optional failure message.
       def assert_snapshots(name, msg = nil, &)
@@ -304,6 +361,11 @@ module RatatuiRuby
       #
       # === Example
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   with_test_terminal(80, 25) do
       #     RatatuiRuby.run do |tui|
       #       tui.draw tui.paragraph(text: "Hello", block: tui.block(title: "Test"))
@@ -313,6 +375,9 @@ module RatatuiRuby
       #     puts ansi_output  # Shows styled output with escape codes
       #   end
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       def render_rich_buffer
         _render_buffer_with_ansi
       end

data/lib/ratatui_ruby/test_helper/style_assertions.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
 module RatatuiRuby
@@ -21,6 +21,11 @@ module RatatuiRuby
     #
     # === Examples
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   # Single cell
     #   assert_cell_style(0, 0, fg: :red, modifiers: [:bold])
     #
@@ -30,14 +35,25 @@ module RatatuiRuby
     #   # Entire header region
     #   assert_area_style({ x: 0, y: 0, w: 80, h: 1 }, bg: :blue)
     #
+    #--
+    # SPDX-SnippetEnd
+    #++
     module StyleAssertions
       ##
       # Asserts that a cell has the expected style attributes.
       #
       # === Example
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   assert_cell_style(0, 0, char: "H", fg: :red)
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # [x] Integer x-coordinate.
       # [y] Integer y-coordinate.
       # [expected_attributes] Hash of attribute names to expected values.
@@ -60,10 +76,18 @@ module RatatuiRuby
       #
       # === Examples
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   assert_color(:red, x: 10, y: 5)
       #   assert_color(5, x: 10, y: 5, layer: :bg)
       #   assert_color("#ff00ff", x: 10, y: 5)
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # [expected] Symbol, Integer, or String (hex).
       # [x] Integer x-coordinate.
       # [y] Integer y-coordinate.
@@ -88,11 +112,19 @@ module RatatuiRuby
       #
       # === Examples
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   header = RatatuiRuby::Layout::Rect.new(x: 0, y: 0, width: 80, height: 1)
       #   assert_area_style(header, bg: :blue, modifiers: [:bold])
       #
       #   assert_area_style({ x: 0, y: 0, w: 10, h: 1 }, fg: :red)
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # [area] Rect-like object or Hash with x, y, width/w, height/h.
       # [attributes] Style attributes to verify.
       def assert_area_style(area, **attributes)
@@ -122,8 +154,16 @@ module RatatuiRuby
       #
       # === Example
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   assert_fg_color(:yellow, 0, 2)
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # [expected] Symbol, Integer, or String (hex).
       # [x] Integer x-coordinate.
       # [y] Integer y-coordinate.
@@ -139,8 +179,16 @@ module RatatuiRuby
       #
       # === Example
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   assert_bg_color(:blue, 0, 2)
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # [expected] Symbol, Integer, or String (hex).
       # [x] Integer x-coordinate.
       # [y] Integer y-coordinate.
@@ -154,8 +202,16 @@ module RatatuiRuby
       #
       # === Example
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   assert_bold(0, 2)
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # [x] Integer x-coordinate.
       # [y] Integer y-coordinate.
       def assert_bold(x, y)
@@ -170,8 +226,16 @@ module RatatuiRuby
       #
       # === Example
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   assert_italic(0, 2)
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # [x] Integer x-coordinate.
       # [y] Integer y-coordinate.
       def assert_italic(x, y)
@@ -186,8 +250,16 @@ module RatatuiRuby
       #
       # === Example
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   assert_underlined(0, 2)
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # [x] Integer x-coordinate.
       # [y] Integer y-coordinate.
       def assert_underlined(x, y)
@@ -203,8 +275,16 @@ module RatatuiRuby
       #
       # === Example
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   assert_dim(0, 2)
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # [x] Integer x-coordinate.
       # [y] Integer y-coordinate.
       def assert_dim(x, y)
@@ -219,8 +299,16 @@ module RatatuiRuby
       #
       # === Example
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   assert_reversed(0, 2)
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # [x] Integer x-coordinate.
       # [y] Integer y-coordinate.
       def assert_reversed(x, y)
@@ -237,8 +325,16 @@ module RatatuiRuby
       #
       # === Example
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   assert_crossed_out(0, 2)
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # [x] Integer x-coordinate.
       # [y] Integer y-coordinate.
       def assert_crossed_out(x, y)