ratatui_ruby 0.8.0 → 0.9.0

data/lib/ratatui_ruby/widgets/gauge.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
@@ -69,6 +69,20 @@ module RatatuiRuby
         ratio = Float(ratio || 0.0)
         super(ratio:, label:, style:, gauge_style:, block:, use_unicode:)
       end
+
+      # Returns true if the gauge has any fill (ratio > 0).
+      #
+      # @return [Boolean]
+      def filled?
+        ratio > 0
+      end
+
+      # Returns true if the gauge is at 100% or more (ratio >= 1.0).
+      #
+      # @return [Boolean]
+      def complete?
+        ratio >= 1.0
+      end
     end
   end
 end

data/lib/ratatui_ruby/widgets/line_gauge.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
@@ -77,6 +77,20 @@ module RatatuiRuby
           unfilled_symbol:
         )
       end
+
+      # Returns true if the gauge has any fill (ratio > 0).
+      #
+      # @return [Boolean]
+      def filled?
+        ratio > 0
+      end
+
+      # Returns true if the gauge is at 100% or more (ratio >= 1.0).
+      #
+      # @return [Boolean]
+      def complete?
+        ratio >= 1.0
+      end
     end
   end
 end

data/lib/ratatui_ruby/widgets/list.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
+    #++
     #   # Basic List
     #   List.new(items: ["Item 1", "Item 2"])
     #
@@ -30,7 +35,27 @@ module RatatuiRuby
     #     highlight_style: Style.new(bg: :blue),
     #     highlight_symbol: ">> "
     #   )
+    #--
+    # SPDX-SnippetEnd
+    #++
     class List < Data.define(:items, :selected_index, :offset, :style, :highlight_style, :highlight_symbol, :repeat_highlight_symbol, :highlight_spacing, :direction, :scroll_padding, :block)
+      ##
+      # Highlight spacing: always show the spacing column.
+      HIGHLIGHT_ALWAYS = :always
+      ##
+      # Highlight spacing: show spacing only when an item is selected (default).
+      HIGHLIGHT_WHEN_SELECTED = :when_selected
+      ##
+      # Highlight spacing: never show the spacing column.
+      HIGHLIGHT_NEVER = :never
+
+      ##
+      # Direction: render items from top to bottom (default).
+      DIRECTION_TOP_TO_BOTTOM = :top_to_bottom
+      ##
+      # Direction: render items from bottom to top.
+      DIRECTION_BOTTOM_TO_TOP = :bottom_to_top
+
       ##
       # :attr_reader: items
       # The items to display.
@@ -124,6 +149,20 @@ module RatatuiRuby
           block:
         )
       end
+
+      # Returns true if an item is selected.
+      #
+      # @return [Boolean]
+      def selected?
+        !selected_index.nil?
+      end
+
+      # Returns true if the list has no items.
+      #
+      # @return [Boolean]
+      def empty?
+        items.empty?
+      end
     end
   end
 end

data/lib/ratatui_ruby/widgets/list_item.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
+    #++
     #   # Item with red background
     #   ListItem.new(content: "Error", style: Style.new(bg: :red))
     #
@@ -24,6 +29,9 @@ module RatatuiRuby
     #   ListItem.new(
     #     content: Text::Span.new(content: "Status: OK", style: Style.new(fg: :green, modifiers: [:bold]))
     #   )
+    #--
+    # SPDX-SnippetEnd
+    #++
     class ListItem < Data.define(:content, :style)
       ##
       # :attr_reader: content

data/lib/ratatui_ruby/widgets/overlay.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
@@ -19,6 +19,11 @@ module RatatuiRuby
     #
     # === Examples
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   Overlay.new(
     #     layers: [
     #       BackgroundMap.new,
@@ -26,6 +31,9 @@ module RatatuiRuby
     #       ModalDialog.new  # Draws over everything
     #     ]
     #   )
+    #--
+    # SPDX-SnippetEnd
+    #++
     class Overlay < Data.define(:layers)
       ##
       # :attr_reader: layers

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,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_relative "ratatui_ruby/version"
@@ -53,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.
     #
@@ -71,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.
@@ -91,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.
@@ -109,8 +133,16 @@ 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
 
@@ -149,8 +181,16 @@ module RatatuiRuby
   # [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)
 
   ##
@@ -189,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"
@@ -229,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
   #
@@ -243,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
 
@@ -293,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(

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