ratatui_ruby 0.8.0 → 0.9.0

data/lib/ratatui_ruby/layout/rect.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,8 +19,16 @@ module RatatuiRuby
     #
     # === Examples
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   area = Layout::Rect.new(x: 0, y: 0, width: 80, height: 24)
     #   puts area.width # => 80
+    #--
+    # SPDX-SnippetEnd
+    #++
     class Rect < Data.define(:x, :y, :width, :height)
       ##
       # :attr_reader: x
@@ -59,15 +67,31 @@ module RatatuiRuby
       #
       # Essential for hit testing mouse clicks against layout regions.
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   area = Layout::Rect.new(x: 10, y: 5, width: 20, height: 10)
       #   area.contains?(15, 8) # => true
       #   area.contains?(5, 8)  # => false
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # [px]
       #   X coordinate to test (column).
       # [py]
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   Y coordinate to test (row).
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # Returns true if the point (px, py) is within the rectangle bounds.
       def contains?(px, py)
         px >= x && px < x + width && py >= y && py < y + height
@@ -77,13 +101,29 @@ module RatatuiRuby
       #
       # Essential for determining if a widget is visible within a viewport or clipping area.
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   viewport = Layout::Rect.new(x: 0, y: 0, width: 80, height: 24)
       #   widget = Layout::Rect.new(x: 70, y: 20, width: 20, height: 10)
       #   viewport.intersects?(widget) # => true (partial overlap)
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # [other]
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   Another Rect to test against.
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # Returns true if the rectangles overlap.
       def intersects?(other)
         x < other.x + other.width &&
@@ -96,14 +136,30 @@ module RatatuiRuby
       #
       # Essential for calculating visible portions of widgets inside scroll views.
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   viewport = Layout::Rect.new(x: 0, y: 0, width: 80, height: 24)
       #   widget = Layout::Rect.new(x: 70, y: 20, width: 20, height: 10)
       #   visible = viewport.intersection(widget)
       #   # => Rect(x: 70, y: 20, width: 10, height: 4)
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # [other]
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   Another Rect to intersect with.
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # Returns a new Rect representing the intersection, or +nil+ if no overlap.
       def intersection(other)
         return nil unless intersects?(other)
@@ -115,6 +171,351 @@ module RatatuiRuby
 
         Rect.new(x: new_x, y: new_y, width: new_right - new_x, height: new_bottom - new_y)
       end
+
+      # Left edge coordinate.
+      #
+      # Layout algorithms compute bounding boxes and check overlaps.
+      # Reading <tt>rect.x</tt> forces you to remember that x means "left."
+      #
+      # Call <tt>left</tt> instead. Your code reads like prose.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   rect = Layout::Rect.new(x: 10, y: 5, width: 80, height: 24)
+      #   rect.left # => 10
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def left
+        x
+      end
+
+      # Right edge coordinate.
+      #
+      # Bounds checks compare edges. Writing <tt>x + width</tt> inline clutters conditions.
+      # Errors creep in when you forget the addition.
+      #
+      # This method computes and names the boundary. Returns the first column outside the rect.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   rect = Layout::Rect.new(x: 10, y: 5, width: 80, height: 24)
+      #   rect.right # => 90
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def right
+        x + width
+      end
+
+      # Top edge coordinate.
+      #
+      # Layout algorithms compute bounding boxes and check overlaps.
+      # Reading <tt>rect.y</tt> forces you to remember that y means "top."
+      #
+      # Call <tt>top</tt> instead. Your code reads like prose.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   rect = Layout::Rect.new(x: 10, y: 5, width: 80, height: 24)
+      #   rect.top # => 5
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def top
+        y
+      end
+
+      # Bottom edge coordinate.
+      #
+      # Bounds checks compare edges. Writing <tt>y + height</tt> inline clutters conditions.
+      # Errors creep in when you forget the addition.
+      #
+      # This method computes and names the boundary. Returns the first row outside the rect.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   rect = Layout::Rect.new(x: 10, y: 5, width: 80, height: 24)
+      #   rect.bottom # => 29
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def bottom
+        y + height
+      end
+
+      # Total area in cells.
+      #
+      # Size comparisons and allocation calculations need area.
+      # Computing <tt>width * height</tt> inline is noisy and error-prone.
+      #
+      # This method does the multiplication once.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   rect = Layout::Rect.new(x: 0, y: 0, width: 10, height: 5)
+      #   rect.area # => 50
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def area
+        width * height
+      end
+
+      # True when the rect has zero area.
+      #
+      # Zero-width or zero-height rects break layout math.
+      # Checking <tt>width == 0 || height == 0</tt> inline is tedious and easy to forget.
+      #
+      # Guard clauses call <tt>empty?</tt> to skip degenerate rects.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Layout::Rect.new(width: 0, height: 10).empty? # => true
+      #   Layout::Rect.new(width: 10, height: 5).empty? # => false
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def empty?
+        width.zero? || height.zero?
+      end
+
+      # Bounding box containing both rectangles.
+      #
+      # Damage tracking and hit testing combine rects.
+      # Computing min/max of all four edges inline is tedious and error-prone.
+      #
+      # This method returns the smallest rect that encloses both.
+      #
+      # [other] Rect to merge.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   r1 = Layout::Rect.new(x: 0, y: 0, width: 10, height: 10)
+      #   r2 = Layout::Rect.new(x: 5, y: 5, width: 10, height: 10)
+      #   r1.union(r2) # => Rect(x: 0, y: 0, width: 15, height: 15)
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def union(other)
+        new_x = [left, other.left].min
+        new_y = [top, other.top].min
+        new_right = [right, other.right].max
+        new_bottom = [bottom, other.bottom].max
+
+        Rect.new(
+          x: new_x,
+          y: new_y,
+          width: new_right - new_x,
+          height: new_bottom - new_y
+        )
+      end
+
+      # Shrinks the rect by a uniform margin on all sides.
+      #
+      # Widgets render text inside borders. Subtracting margin from all four edges inline is verbose.
+      # Off-by-one errors happen when you forget to double the margin.
+      #
+      # This method computes the content area. Returns a zero-area rect if margin exceeds dimensions.
+      #
+      # [margin] Integer padding on all sides.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   rect = Layout::Rect.new(x: 0, y: 0, width: 20, height: 10)
+      #   rect.inner(2) # => Rect(x: 2, y: 2, width: 16, height: 6)
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def inner(margin)
+        doubled = margin * 2
+        return Rect.new(x: 0, y: 0, width: 0, height: 0) if width < doubled || height < doubled
+
+        Rect.new(
+          x: x + margin,
+          y: y + margin,
+          width: width - doubled,
+          height: height - doubled
+        )
+      end
+
+      # Moves the rect without changing size.
+      #
+      # Animations and drag-and-drop shift widgets.
+      # Adding offsets to x and y inline clutters the code.
+      #
+      # This method returns a translated copy.
+      #
+      # [dx] Horizontal shift (positive moves right).
+      # [dy] Vertical shift (positive moves down).
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   rect = Layout::Rect.new(x: 10, y: 5, width: 20, height: 10)
+      #   rect.offset(5, 3) # => Rect(x: 15, y: 8, width: 20, height: 10)
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def offset(dx, dy)
+        Rect.new(x: x + dx, y: y + dy, width:, height:)
+      end
+
+      # Constrains the rect to fit inside bounds.
+      #
+      # Popups and tooltips may extend beyond screen edges.
+      # Manually clamping x, y, width, and height is verbose and error-prone.
+      #
+      # This method repositions and shrinks the rect to stay within bounds.
+      #
+      # [other] Bounding Rect.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   screen = Layout::Rect.new(x: 0, y: 0, width: 100, height: 100)
+      #   popup = Layout::Rect.new(x: 80, y: 80, width: 30, height: 30)
+      #   popup.clamp(screen) # => Rect(x: 70, y: 70, width: 30, height: 30)
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def clamp(other)
+        clamped_width = [width, other.width].min
+        clamped_height = [height, other.height].min
+        clamped_x = x.clamp(other.left, other.right - clamped_width)
+        clamped_y = y.clamp(other.top, other.bottom - clamped_height)
+
+        Rect.new(x: clamped_x, y: clamped_y, width: clamped_width, height: clamped_height)
+      end
+
+      # Iterates over horizontal slices.
+      #
+      # Lists render line by line. Looping <tt>height.times</tt> and constructing rects inline is noisy.
+      #
+      # This method yields each row as a Rect with height 1. Returns an Enumerator if no block given.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   rect = Layout::Rect.new(x: 0, y: 0, width: 5, height: 3)
+      #   rect.rows.map { |r| r.y } # => [0, 1, 2]
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def rows
+        return to_enum(:rows) unless block_given?
+
+        height.times do |i|
+          yield Rect.new(x:, y: y + i, width:, height: 1)
+        end
+      end
+
+      # Iterates over vertical slices.
+      #
+      # Grids render column by column. Looping <tt>width.times</tt> and constructing rects inline is noisy.
+      #
+      # This method yields each column as a Rect with width 1. Returns an Enumerator if no block given.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   rect = Layout::Rect.new(x: 0, y: 0, width: 5, height: 3)
+      #   rect.columns.map { |c| c.x } # => [0, 1, 2, 3, 4]
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def columns
+        return to_enum(:columns) unless block_given?
+
+        width.times do |i|
+          yield Rect.new(x: x + i, y:, width: 1, height:)
+        end
+      end
+
+      # Iterates over every cell in row-major order.
+      #
+      # Hit testing and pixel rendering touch every position.
+      # Nested loops with manual coordinate math are verbose.
+      #
+      # This method yields <tt>[x, y]</tt> pairs. Returns an Enumerator if no block given.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   rect = Layout::Rect.new(x: 0, y: 0, width: 2, height: 2)
+      #   rect.positions.to_a # => [[0, 0], [1, 0], [0, 1], [1, 1]]
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def positions
+        return to_enum(:positions) unless block_given?
+
+        height.times do |row|
+          width.times do |col|
+            yield [x + col, y + row]
+          end
+        end
+      end
     end
   end
 end

data/lib/ratatui_ruby/layout.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/list_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
@@ -24,6 +24,11 @@ module RatatuiRuby
   #
   # == Example
   #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
   #   @list_state = RatatuiRuby::ListState.new
   #   @list_state.select(2) # Select third item
   #
@@ -34,6 +39,9 @@ module RatatuiRuby
   #
   #   puts @list_state.offset # Scroll position after render
   #
+  #--
+  # SPDX-SnippetEnd
+  #++
   class ListState
     ##
     # :method: new
@@ -86,5 +94,108 @@ module RatatuiRuby
     # Scrolls up by +n+ items.
     #
     # (Native method implemented in Rust)
+
+    ##
+    # :method: select_next
+    # :call-seq: select_next() -> nil
+    #
+    # Moves selection to the next item. Selects first item if nothing selected.
+    #
+    # === Optimistic Indexing
+    #
+    # Increments the index immediately, even past list bounds. The renderer
+    # clamps to valid range on draw. Reading <tt>selected</tt> between this
+    # call and render may return an out-of-bounds value.
+    #
+    # Matches upstream Ratatui behavior. See
+    # {ListState#select_next}[https://docs.rs/ratatui/0.30/ratatui/widgets/struct.ListState.html#method.select_next].
+    #
+    # To detect actual selection changes, check bounds first:
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   max_index = items.size - 1
+    #   return if (state.selected || 0) >= max_index
+    #   state.select_next
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: select_previous
+    # :call-seq: select_previous() -> nil
+    #
+    # Moves selection to the previous item. Selects last item if nothing selected.
+    #
+    # === Optimistic Indexing
+    #
+    # At index 0, does nothing. With no selection, sets index to maximum value;
+    # the renderer clamps to actual last item on draw.
+    #
+    # To detect actual selection changes, check bounds first:
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   return if (state.selected || 0) <= 0
+    #   state.select_previous
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: select_first
+    # :call-seq: select_first() -> nil
+    #
+    # Jumps selection to the first item (index 0).
+    #
+    # To detect actual selection changes:
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   return if (state.selected || 0) == 0
+    #   state.select_first
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: select_last
+    # :call-seq: select_last() -> nil
+    #
+    # Jumps selection to the last item.
+    #
+    # === Optimistic Indexing
+    #
+    # Sets index to maximum possible value. The renderer clamps to actual last
+    # item on draw. To get or check the real last index, track item count:
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   max_index = items.size - 1
+    #   return if (state.selected || 0) == max_index
+    #   state.select(max_index)
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # (Native method implemented in Rust)
   end
 end

data/lib/ratatui_ruby/output_guard.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
@@ -70,13 +69,26 @@ module RatatuiRuby
     # (like lazygit does when editing a commit message), use
     # {restore_terminal} and {init_terminal} instead:
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   RatatuiRuby.restore_terminal
     #   puts "Press enter to continue..."
     #   gets
     #   RatatuiRuby.init_terminal
     #
+    #--
+    # SPDX-SnippetEnd
+    #++
     # === Example
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   if ARGV.include?("--no-tui")
     #     RatatuiRuby.headless!
     #     process_batch_work  # guard_io calls are silent no-ops
@@ -86,6 +98,9 @@ module RatatuiRuby
     #     end
     #   end
     #
+    #--
+    # SPDX-SnippetEnd
+    #++
     # Note: Calling {run} or {init_terminal} after {headless!} raises
     # {Error::Invariant}. The block is never executed.
     #
@@ -117,12 +132,20 @@ module RatatuiRuby
     #
     # === Example
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   RatatuiRuby.run do |tui|
     #     RatatuiRuby.guard_io do
     #       SomeChattyGem.do_something  # Any puts/warn calls are swallowed
     #     end
     #   end
     #
+    #--
+    # SPDX-SnippetEnd
+    #++
     # @see headless!
     def guard_io
       # TUI active: guard the output

data/lib/ratatui_ruby/schema/bar_chart/bar.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/schema/bar_chart/bar_group.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