ratatui_ruby 0.7.4 → 0.9.0

data/lib/ratatui_ruby/scrollbar_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
@@ -14,6 +14,11 @@ module RatatuiRuby
   #
   # == Example
   #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
   #   @scrollbar_state = RatatuiRuby::ScrollbarState.new(100)
   #   @scrollbar_state.position = 25
   #
@@ -22,6 +27,9 @@ module RatatuiRuby
   #     frame.render_stateful_widget(scrollbar, frame.area, @scrollbar_state)
   #   end
   #
+  #--
+  # SPDX-SnippetEnd
+  #++
   class ScrollbarState
     ##
     # :method: new

data/lib/ratatui_ruby/style/style.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
@@ -18,12 +18,20 @@ module RatatuiRuby
     #
     # === Examples
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   # Standard colors
     #   Style::Style.new(fg: :red, bg: :white, modifiers: [:bold])
     #
     #   # Hex colors
     #   Style::Style.new(fg: "#ff00ff")
     #
+    #--
+    # SPDX-SnippetEnd
+    #++
     # === Supported Colors
     #
     # ==== Integer
@@ -37,8 +45,16 @@ module RatatuiRuby
     # * <tt>:black</tt>, <tt>:red</tt>, <tt>:green</tt>, <tt>:yellow</tt>,
     #   <tt>:blue</tt>, <tt>:magenta</tt>, <tt>:cyan</tt>, <tt>:gray</tt>
     # * <tt>:dark_gray</tt>, <tt>:light_red</tt>, <tt>:light_green</tt>,
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   <tt>:light_yellow</tt>, <tt>:light_blue</tt>, <tt>:light_magenta</tt>,
     #   <tt>:light_cyan</tt>, <tt>:white</tt>
+    #--
+    # SPDX-SnippetEnd
+    #++
     # * <tt>:reset</tt> — Restores the terminal's default color.
     #
     # ==== String

data/lib/ratatui_ruby/style.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

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

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  ##
+  # Terminal lifecycle management for TUI sessions.
+  #
+  # This module provides methods to initialize, restore, and manage the terminal
+  # state for TUI applications. It handles raw mode, alternate screen, and ensures
+  # proper cleanup on exit.
+  #
+  # @see init_terminal
+  # @see restore_terminal
+  # @see run
+  module TerminalLifecycle
+    ##
+    # Whether a TUI session is currently active.
+    #
+    # Writing to stdout/stderr during a TUI session corrupts the display.
+    # Use this to defer logging, warnings, or debug output until
+    # after the session ends.
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   def log(message)
+    #     if RatatuiRuby.terminal_active?
+    #       @deferred_logs << message
+    #     else
+    #       puts message
+    #     end
+    #   end
+    #--
+    # SPDX-SnippetEnd
+    #++
+    def terminal_active?
+      @tui_session_active
+    end
+
+    ##
+    # Initializes the terminal for TUI mode.
+    # Enters alternate screen and enables raw mode.
+    #
+    # In headless mode ({headless!}), this method raises {Error::Invariant}.
+    # Use headless mode for batch/CLI apps.
+    #
+    # [focus_events] whether to enable focus gain/loss events (default: true).
+    # [bracketed_paste] whether to enable bracketed paste mode (default: true).
+    #
+    # @raise [Error::Invariant] if headless mode is enabled or a session is already active
+    # @see headless!
+    def init_terminal(focus_events: true, bracketed_paste: true)
+      if @headless_mode
+        raise Error::Invariant, "Cannot initialize terminal: headless mode is enabled"
+      end
+      if @tui_session_active
+        raise Error::Invariant, "Cannot initialize terminal: TUI session already active"
+      end
+      @tui_session_active = true
+      _init_terminal(focus_events, bracketed_paste)
+    end
+
+    ##
+    # Initializes a test terminal for unit testing.
+    # Sets session active state like init_terminal.
+    #
+    # [width] Integer width of the test terminal.
+    # [height] Integer height of the test terminal.
+    #
+    # @raise [Error::Invariant] if headless mode is enabled or a session is already active
+    def init_test_terminal(width, height)
+      if @headless_mode
+        raise Error::Invariant, "Cannot initialize terminal: headless mode is enabled"
+      end
+      if @tui_session_active
+        raise Error::Invariant, "Cannot initialize terminal: TUI session already active"
+      end
+      @tui_session_active = true
+      _init_test_terminal(width, height)
+    end
+
+    ##
+    # Restores the terminal to its original state.
+    # Leaves alternate screen and disables raw mode.
+    # Also flushes any deferred warnings that were queued during the session.
+    #
+    # In headless mode ({headless!}), this method is a silent no-op since
+    # no terminal was ever initialized.
+    #
+    # @see headless!
+    def restore_terminal
+      return if @headless_mode
+
+      _restore_terminal
+    ensure
+      @tui_session_active = false
+      flush_warnings
+    end
+
+    ##
+    # Starts the TUI application lifecycle.
+    #
+    # Managing generic setup/teardown (raw mode, alternate screen) manually is error-prone.
+    # If your app crashes, the terminal might be left in a broken state.
+    #
+    # This method handles the safety net. It initializes the terminal, yields a {TUI},
+    # and ensures the terminal state is restored even if exceptions occur.
+    #
+    # In headless mode ({headless!}), this method raises {Error::Invariant} immediately
+    # and the block is never executed. Use headless mode for batch/CLI apps.
+    #
+    # === 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)
+      init_terminal(focus_events:, bracketed_paste:)
+      yield TUI.new
+    ensure
+      restore_terminal
+    end
+  end
+end

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
@@ -82,8 +98,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 +165,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

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