ratatui_ruby 0.7.4 → 0.9.0

data/lib/ratatui_ruby/widgets/paragraph.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
@@ -17,6 +17,11 @@ module RatatuiRuby
     #
     # === Examples
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   # Basic Text
     #   Paragraph.new(text: "Hello, World!")
     #
@@ -30,6 +35,9 @@ module RatatuiRuby
     #
     #   # Scrolling mechanism
     #   Paragraph.new(text: large_text, scroll: [scroll_y, 0])
+    #--
+    # SPDX-SnippetEnd
+    #++
     class Paragraph < Data.define(:text, :style, :block, :wrap, :alignment, :scroll)
       ##
       # :attr_reader: text

data/lib/ratatui_ruby/widgets/ratatui_logo.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/widgets/ratatui_mascot.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/widgets/row.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
@@ -17,6 +17,11 @@ module RatatuiRuby
     #
     # === Examples
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   # Row with red background
     #   Row.new(cells: ["Error", "Something went wrong"], style: Style.new(bg: :red))
     #
@@ -28,6 +33,9 @@ module RatatuiRuby
     #     ],
     #     height: 2
     #   )
+    #--
+    # SPDX-SnippetEnd
+    #++
     class Row < Data.define(:cells, :style, :height, :top_margin, :bottom_margin)
       ##
       # :attr_reader: cells

data/lib/ratatui_ruby/widgets/scrollbar.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/widgets/shape/label.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
@@ -20,6 +20,11 @@ module RatatuiRuby
       #
       # === Examples
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   # Simple label
       #   Shape::Label.new(x: 0, y: 0, text: "Origin")
       #
@@ -38,6 +43,9 @@ module RatatuiRuby
       #       Text::Span.new(content: "World", style: Style.new(fg: :blue))
       #     ])
       #   )
+      #--
+      # SPDX-SnippetEnd
+      #++
       class Label < Data.define(:x, :y, :text, :style)
         ##
         # :attr_reader: x

data/lib/ratatui_ruby/widgets/sparkline.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
@@ -72,6 +72,11 @@ module RatatuiRuby
       #
       # === Examples
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   bar_set: {
       #     empty: " ",
       #     one_eighth: " ",
@@ -91,6 +96,9 @@ module RatatuiRuby
       #
       #   # Array (9 items)
       #   bar_set: [" ", " ", "▂", "▃", "▄", "▅", "▆", "▇", "█"]
+      #--
+      # SPDX-SnippetEnd
+      #++
 
       BAR_KEYS = %i[empty one_eighth one_quarter three_eighths half five_eighths three_quarters seven_eighths full].freeze
 

data/lib/ratatui_ruby/widgets/table.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
@@ -24,6 +24,38 @@ module RatatuiRuby
     #
     #   ruby examples/widget_table_flex/app.rb
     class Table < Data.define(:header, :rows, :widths, :row_highlight_style, :highlight_symbol, :highlight_spacing, :column_highlight_style, :cell_highlight_style, :selected_row, :selected_column, :offset, :block, :footer, :flex, :style, :column_spacing)
+      ##
+      # Highlight spacing: always show the spacing column.
+      HIGHLIGHT_ALWAYS = :always
+      ##
+      # Highlight spacing: show spacing only when a row is selected (default).
+      HIGHLIGHT_WHEN_SELECTED = :when_selected
+      ##
+      # Highlight spacing: never show the spacing column.
+      HIGHLIGHT_NEVER = :never
+
+      ##
+      # Flex: use legacy column sizing.
+      FLEX_LEGACY = :legacy
+      ##
+      # Flex: align columns to start.
+      FLEX_START = :start
+      ##
+      # Flex: center columns.
+      FLEX_CENTER = :center
+      ##
+      # Flex: align columns to end.
+      FLEX_END = :end
+      ##
+      # Flex: space between columns.
+      FLEX_SPACE_BETWEEN = :space_between
+      ##
+      # Flex: space around columns.
+      FLEX_SPACE_AROUND = :space_around
+      ##
+      # Flex: space evenly between columns.
+      FLEX_SPACE_EVENLY = :space_evenly
+
       ##
       # :attr_reader: header
       # Header row content (Array of Strings, Text::Spans, Text::Lines, or Paragraphs).
@@ -138,6 +170,34 @@ module RatatuiRuby
           column_spacing: Integer(column_spacing)
         )
       end
+
+      # Returns true if a row is selected.
+      #
+      # @return [Boolean]
+      def row_selected?
+        !selected_row.nil?
+      end
+
+      # Returns true if a column is selected.
+      #
+      # @return [Boolean]
+      def column_selected?
+        !selected_column.nil?
+      end
+
+      # Returns true if both a row and column are selected (a cell is selected).
+      #
+      # @return [Boolean]
+      def cell_selected?
+        row_selected? && column_selected?
+      end
+
+      # Returns true if the table has no rows.
+      #
+      # @return [Boolean]
+      def empty?
+        rows.empty?
+      end
     end
   end
 end

data/lib/ratatui_ruby/widgets/tabs.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/widgets.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.rb

@@ -1,13 +1,13 @@
 # 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_relative "ratatui_ruby/version"
 
-# New modularized structure (mirrors ratatui Rust crate)
+# Core types (mirrors ratatui Rust crate)
 require_relative "ratatui_ruby/layout"   # Layout::Rect, Layout::Constraint, Layout::Layout
 require_relative "ratatui_ruby/style"    # Style::Style
 require_relative "ratatui_ruby/widgets"  # Widgets::Block, Widgets::Paragraph, etc.
@@ -24,6 +24,10 @@ require_relative "ratatui_ruby/list_state"
 require_relative "ratatui_ruby/table_state"
 require_relative "ratatui_ruby/scrollbar_state"
 
+# Behavioral mixins
+require_relative "ratatui_ruby/output_guard"
+require_relative "ratatui_ruby/terminal_lifecycle"
+
 # TUI facade (for external instantiation and caching)
 require_relative "ratatui_ruby/tui"
 
@@ -49,11 +53,19 @@ module RatatuiRuby
   #
   # === Example
   #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
   #   begin
   #     RatatuiRuby.run { |tui| ... }
   #   rescue RatatuiRuby::Error => e
   #     puts "RatatuiRuby error: #{e.message}"
   #   end
+  #--
+  # SPDX-SnippetEnd
+  #++
   class Error < StandardError
     # Operational failure during terminal I/O.
     #
@@ -67,11 +79,19 @@ module RatatuiRuby
     #
     # === Example
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   begin
     #     RatatuiRuby.init_terminal
     #   rescue RatatuiRuby::Error::Terminal => e
     #     puts "Terminal failed: #{e.message}"
     #   end
+    #--
+    # SPDX-SnippetEnd
+    #++
     class Terminal < Error; end
 
     # Object lifetime violation.
@@ -87,9 +107,17 @@ module RatatuiRuby
     #
     # === Example
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   stored_frame = nil
     #   RatatuiRuby.draw { |frame| stored_frame = frame }
     #   stored_frame.area  # => raises Error::Safety
+    #--
+    # SPDX-SnippetEnd
+    #++
     class Safety < Error; end
 
     # State invariant violation.
@@ -105,49 +133,31 @@ module RatatuiRuby
     #
     # === Example
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   RatatuiRuby.init_terminal
     #   RatatuiRuby.init_terminal  # => raises Error::Invariant
+    #--
+    # SPDX-SnippetEnd
+    #++
     class Invariant < Error; end
   end
 
-  ##
-  # Initializes the terminal for TUI mode.
-  # Enters alternate screen and enables raw mode.
-  #
-  # [focus_events] whether to enable focus gain/loss events (default: true).
-  # [bracketed_paste] whether to enable bracketed paste mode (default: true).
-  def self.init_terminal(focus_events: true, bracketed_paste: true)
-    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
+  # Mix in terminal lifecycle and output protection methods
+  extend OutputGuard
+  extend TerminalLifecycle
+
+  # Re-export NullIO at module root for backward compatibility
+  NullIO = OutputGuard::NullIO
 
   @experimental_warnings = true
   @tui_session_active = false
+  @headless_mode = false
   @deferred_warnings = []
 
-  ##
-  # 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
-  #
-  #   def log(message)
-  #     if RatatuiRuby.terminal_active?
-  #       @deferred_logs << message
-  #     else
-  #       puts message
-  #     end
-  #   end
-  def self.terminal_active?
-    @tui_session_active
-  end
-
   class << self
     ##
     # :attr_accessor: experimental_warnings
@@ -165,25 +175,22 @@ module RatatuiRuby
     end
   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.
-  def self.restore_terminal
-    _restore_terminal
-  ensure
-    @tui_session_active = false
-    flush_warnings
-  end
-
   ##
   # :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
   #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2025 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
   #   inject_test_event("key", { code: "a" })
   #
+  #--
+  # SPDX-SnippetEnd
+  #++
   # (Native method implemented in Rust)
 
   ##
@@ -207,20 +214,6 @@ module RatatuiRuby
     @warned_features[feature_name] = true
   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.
-  def self.init_test_terminal(width, height)
-    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
-
   # (Native methods implemented in Rust)
   private_class_method :_init_terminal, :_restore_terminal, :_init_test_terminal
 
@@ -236,20 +229,44 @@ module RatatuiRuby
   # {Frame} object for imperative drawing.
   #
   # [tree] A widget tree (Widgets::Paragraph, Layout::Layout, etc.) to render. Optional if
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2025 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
   #        a block is given.
   #
+  #--
+  # SPDX-SnippetEnd
+  #++
   # === Examples
   #
   # Legacy declarative style (tree-based):
   #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
   #   RatatuiRuby.draw(Widgets::Paragraph.new(text: "Hello"))
   #
+  #--
+  # SPDX-SnippetEnd
+  #++
   # New imperative style (block-based):
   #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
   #   RatatuiRuby.draw do |frame|
   #     frame.render_widget(Widgets::Paragraph.new(text: "Hello"), frame.area)
   #   end
   #
+  #--
+  # SPDX-SnippetEnd
+  #++
   def self.draw(tree = nil, &block)
     if tree && block
       raise ArgumentError, "Cannot provide both a tree and a block to draw"
@@ -276,11 +293,24 @@ module RatatuiRuby
   # This method checks for an event. It returns the event if one is found. It returns {RatatuiRuby::Event::None} if the timeout expires.
   #
   # [timeout] Float seconds to wait (default: 0.016).
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
   #           Pass <tt>nil</tt> to block indefinitely (wait forever).
   #           Pass <tt>0.0</tt> for a non-blocking check.
   #
+  #--
+  # SPDX-SnippetEnd
+  #++
   # === Examples
   #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
   #   # Standard loop (approx 60 FPS)
   #   event = RatatuiRuby.poll_event
   #
@@ -290,6 +320,9 @@ module RatatuiRuby
   #   # Non-blocking check (returns immediately)
   #   event = RatatuiRuby.poll_event(timeout: 0.0)
   #
+  #--
+  # SPDX-SnippetEnd
+  #++
   def self.poll_event(timeout: 0.016)
     raise ArgumentError, "timeout must be non-negative" if timeout && timeout < 0
 
@@ -328,26 +361,6 @@ module RatatuiRuby
   # (Native method _poll_event implemented in Rust)
   private_class_method :_poll_event
 
-  ##
-  # 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.
-  #
-  # This method handles the safety net. It initializes the terminal, yields a {TUI}, and ensures the terminal state is restored even if exceptions occur.
-  #
-  # === Example
-  #
-  #   RatatuiRuby.run(focus_events: false) do |tui|
-  #     tui.draw(tui.paragraph(text: "Hi"))
-  #     sleep 1
-  #   end
-  def self.run(focus_events: true, bracketed_paste: true)
-    init_terminal(focus_events:, bracketed_paste:)
-    yield TUI.new
-  ensure
-    restore_terminal
-  end
-
   ##
   # Inspects the terminal buffer at specific coordinates.
   #
@@ -360,11 +373,19 @@ module RatatuiRuby
   #
   # === Example
   #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2025 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
   #   cell = RatatuiRuby.get_cell_at(10, 5)
   #   expect(cell.symbol).to eq("X")
   #   expect(cell.fg).to eq(:red)
   #   expect(cell).to be_bold
   #
+  #--
+  # SPDX-SnippetEnd
+  #++
   def self.get_cell_at(x, y)
     raw = _get_cell_at(x, y)
     Buffer::Cell.new(
@@ -380,4 +401,18 @@ module RatatuiRuby
 
   # Hide native Layout._split helper
   Layout::Layout.singleton_class.__send__(:private, :_split)
+
+  # --- Terminal Safety Hooks ---
+  # These ensure the terminal is restored even on unexpected exits.
+
+  at_exit do
+    restore_terminal if terminal_active?
+  end
+
+  %i[INT TERM].each do |signal|
+    trap(signal) do
+      restore_terminal if terminal_active?
+      exit(128 + Signal.list[signal.to_s])
+    end
+  end
 end

data/sig/examples/app_all_events/view.rbs

@@ -1,4 +1,10 @@
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module View

data/sig/examples/app_all_events/view_state.rbs

@@ -1,4 +1,10 @@
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 class ViewState < Data

data/sig/examples/app_color_picker/app.rbs

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 

data/sig/examples/app_stateful_interaction/app.rbs

@@ -1,4 +1,10 @@
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 class AppStatefulInteraction

data/sig/examples/verify_quickstart_dsl/app.rbs

@@ -1,4 +1,10 @@
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: MIT-0
+#++
+
 #
 # SPDX-License-Identifier: AGPL-3.0-or-later
 

data/sig/examples/verify_quickstart_lifecycle/app.rbs

@@ -1,4 +1,10 @@
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: MIT-0
+#++
+
 #
 # SPDX-License-Identifier: AGPL-3.0-or-later