ratatui_ruby 0.4.0 → 0.6.0

data/lib/ratatui_ruby/schema/ratatui_mascot.rb

@@ -6,14 +6,19 @@
 module RatatuiRuby
   # Displays the Ratatui mascot.
   #
-  # A widget that renders the Ratatui mascot (a rat).
+  # Interfaces without personality feel clinical and dry. Users appreciate a friendly face in their terminal.
   #
-  # === Examples
+  # This widget renders the Ratatui mascot (a mouse).
   #
-  #   RatatuiMascot.new(
-  #     block: Block.new(title: "Mascot")
-  #   )
+  # Use it to add charm to your application, greet users on startup, or as a decorative element in sidebars.
   #
+  # {rdoc-image:/doc/images/widget_ratatui_mascot_demo.png}[link:/examples/widget_ratatui_mascot_demo/app_rb.html]
+  #
+  # === Example
+  #
+  # Run the interactive demo from the terminal:
+  #
+  #   ruby examples/widget_ratatui_mascot_demo/app.rb
   class RatatuiMascot < Data.define(:block)
     ##
     # :method: new

data/lib/ratatui_ruby/schema/rect.rb

@@ -4,70 +4,113 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-    # Defines a rectangular area in the terminal grid.
+  # Defines a rectangular area in the terminal grid.
+  #
+  # Geometry management involves passing groups of four integers (`x, y, width, height`) repeatedly.
+  # This is verbose and prone to parameter mismatch errors.
+  #
+  # This class encapsulates the geometry. It provides a standard primitive for passing area definitions
+  # between layout engines and rendering functions.
+  #
+  # Use it when manual positioning is required or when querying layout results.
+  #
+  # === Examples
+  #
+  #   area = Rect.new(x: 0, y: 0, width: 80, height: 24)
+  #   puts area.width # => 80
+  class Rect < Data.define(:x, :y, :width, :height)
+    ##
+    # :attr_reader: x
+    # X coordinate (column) of the top-left corner (Integer, coerced via +to_int+ or +to_i+).
+
+    ##
+    # :attr_reader: y
+    # Y coordinate (row) of the top-left corner (Integer, coerced via +to_int+ or +to_i+).
+
+    ##
+    # :attr_reader: width
+    # Width in characters (Integer, coerced via +to_int+ or +to_i+).
+
+    ##
+    # :attr_reader: height
+    # Height in characters (Integer, coerced via +to_int+ or +to_i+).
+
+    # Creates a new Rect.
     #
-    # Geometry management involves passing groups of four integers (`x, y, width, height`) repeatedly.
-    # This is verbose and prone to parameter mismatch errors.
+    # All parameters accept any object responding to +to_int+ or +to_i+ (duck-typed).
     #
-    # This class encapsulates the geometry. It provides a standard primitive for passing area definitions
-    # between layout engines and rendering functions.
+    # [x] Column index (Numeric).
+    # [y] Row index (Numeric).
+    # [width] Width in columns (Numeric).
+    # [height] Height in rows (Numeric).
+    def initialize(x: 0, y: 0, width: 0, height: 0)
+      super(
+        x: Integer(x),
+        y: Integer(y),
+        width: Integer(width),
+        height: Integer(height)
+      )
+    end
+
+    # Tests whether a point is inside this rectangle.
     #
-    # Use it when manual positioning is required or when querying layout results.
+    # Essential for hit testing mouse clicks against layout regions.
     #
-    # === Examples
+    #   area = Rect.new(x: 10, y: 5, width: 20, height: 10)
+    #   area.contains?(15, 8) # => true
+    #   area.contains?(5, 8)  # => false
     #
-    #   area = Rect.new(x: 0, y: 0, width: 80, height: 24)
-    #   puts area.width # => 80
-    class Rect < Data.define(:x, :y, :width, :height)
-      ##
-      # :attr_reader: x
-      # X coordinate (column) of the top-left corner (Integer, coerced via +to_int+ or +to_i+).
-
-      ##
-      # :attr_reader: y
-      # Y coordinate (row) of the top-left corner (Integer, coerced via +to_int+ or +to_i+).
+    # [px]
+    #   X coordinate to test (column).
+    # [py]
+    #   Y coordinate to test (row).
+    #
+    # 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
+    end
 
-      ##
-      # :attr_reader: width
-      # Width in characters (Integer, coerced via +to_int+ or +to_i+).
+    # Tests whether this rectangle overlaps with another.
+    #
+    # Essential for determining if a widget is visible within a viewport or clipping area.
+    #
+    #   viewport = Rect.new(x: 0, y: 0, width: 80, height: 24)
+    #   widget = Rect.new(x: 70, y: 20, width: 20, height: 10)
+    #   viewport.intersects?(widget) # => true (partial overlap)
+    #
+    # [other]
+    #   Another Rect to test against.
+    #
+    # Returns true if the rectangles overlap.
+    def intersects?(other)
+      x < other.x + other.width &&
+        x + width > other.x &&
+        y < other.y + other.height &&
+        y + height > other.y
+    end
 
-      ##
-      # :attr_reader: height
-      # Height in characters (Integer, coerced via +to_int+ or +to_i+).
+    # Returns the overlapping area between this rectangle and another.
+    #
+    # Essential for calculating visible portions of widgets inside scroll views.
+    #
+    #   viewport = Rect.new(x: 0, y: 0, width: 80, height: 24)
+    #   widget = Rect.new(x: 70, y: 20, width: 20, height: 10)
+    #   visible = viewport.intersection(widget)
+    #   # => Rect(x: 70, y: 20, width: 10, height: 4)
+    #
+    # [other]
+    #   Another Rect to intersect with.
+    #
+    # Returns a new Rect representing the intersection, or +nil+ if no overlap.
+    def intersection(other)
+      return nil unless intersects?(other)
 
-      # Creates a new Rect.
-      #
-      # All parameters accept any object responding to +to_int+ or +to_i+ (duck-typed).
-      #
-      # [x] Column index (Numeric).
-      # [y] Row index (Numeric).
-      # [width] Width in columns (Numeric).
-      # [height] Height in rows (Numeric).
-      def initialize(x: 0, y: 0, width: 0, height: 0)
-        super(
-          x: Integer(x),
-          y: Integer(y),
-          width: Integer(width),
-          height: Integer(height)
-        )
-      end
+      new_x = [x, other.x].max
+      new_y = [y, other.y].max
+      new_right = [x + width, other.x + other.width].min
+      new_bottom = [y + height, other.y + other.height].min
 
-      # Tests whether a point is inside this rectangle.
-      #
-      # Essential for hit testing mouse clicks against layout regions.
-      #
-      #   area = Rect.new(x: 10, y: 5, width: 20, height: 10)
-      #   area.contains?(15, 8) # => true
-      #   area.contains?(5, 8)  # => false
-      #
-      # [px]
-      #   X coordinate to test (column).
-      # [py]
-      #   Y coordinate to test (row).
-      #
-      # 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
-      end
+      Rect.new(x: new_x, y: new_y, width: new_right - new_x, height: new_bottom - new_y)
     end
+  end
 end

data/lib/ratatui_ruby/schema/scrollbar.rb

@@ -4,138 +4,138 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-    # Visualizes the scroll state of a viewport.
-    #
-    # Content overflows. Users get lost in long lists without landmarks. They need to know where they are and how much is left.
-    #
-    # This widget maps your context. It draws a track and a thumb, representing your current position relative to the total length.
-    #
-    # Overlay it on top of lists, paragraphs, or tables to provide spatial awareness.
-    #
-    # === Examples
-    #
-    #   Scrollbar.new(
-    #     content_length: 100,
-    #     position: 25,
-    #     orientation: :vertical
-    #   )
-    class Scrollbar < Data.define(
-      :content_length,
-      :position,
-      :orientation,
-      :thumb_symbol,
-      :thumb_style,
-      :track_symbol,
-      :track_style,
-      :begin_symbol,
-      :begin_style,
-      :end_symbol,
-      :end_style,
-      :style,
-      :block
-    )
-      ##
-      # :attr_reader: content_length
-      # Total items or lines in the content.
+  # Visualizes the scroll state of a viewport.
+  #
+  # Content overflows. Users get lost in long lists without landmarks. They need to know where they are and how much is left.
+  #
+  # This widget maps your context. It draws a track and a thumb, representing your current position relative to the total length.
+  #
+  # Overlay it on top of lists, paragraphs, or tables to provide spatial awareness.
+  #
+  # {rdoc-image:/doc/images/widget_scrollbar_demo.png}[link:/examples/widget_scrollbar_demo/app_rb.html]
+  #
+  # === Example
+  #
+  # Run the interactive demo from the terminal:
+  #
+  #   ruby examples/widget_scrollbar_demo/app.rb
+  class Scrollbar < Data.define(
+    :content_length,
+    :position,
+    :orientation,
+    :thumb_symbol,
+    :thumb_style,
+    :track_symbol,
+    :track_style,
+    :begin_symbol,
+    :begin_style,
+    :end_symbol,
+    :end_style,
+    :style,
+    :block
+  )
+    ##
+    # :attr_reader: content_length
+    # Total items or lines in the content.
 
-      ##
-      # :attr_reader: position
-      # Current scroll offset (index).
-      #
-      # Maps to Ratatui's <tt>ScrollbarState::get_position()</tt> (new in 0.30.0).
+    ##
+    # :attr_reader: position
+    # Current scroll offset (index).
+    #
+    # Maps to Ratatui's <tt>ScrollbarState::get_position()</tt> (new in 0.30.0).
 
-      ##
-      # :attr_reader: orientation
-      # Direction of the scrollbar.
-      #
-      # <tt>:vertical</tt> (default, alias for <tt>:vertical_right</tt>), <tt>:horizontal</tt> (alias for <tt>:horizontal_bottom</tt>),
-      # <tt>:vertical_left</tt>, <tt>:vertical_right</tt>, <tt>:horizontal_top</tt>, or <tt>:horizontal_bottom</tt>.
+    ##
+    # :attr_reader: orientation
+    # Direction of the scrollbar.
+    #
+    # <tt>:vertical</tt> (default, alias for <tt>:vertical_right</tt>), <tt>:horizontal</tt> (alias for <tt>:horizontal_bottom</tt>),
+    # <tt>:vertical_left</tt>, <tt>:vertical_right</tt>, <tt>:horizontal_top</tt>, or <tt>:horizontal_bottom</tt>.
 
-      ##
-      # :attr_reader: thumb_symbol
-      # Symbol used to represent the current position indicator.
+    ##
+    # :attr_reader: thumb_symbol
+    # Symbol used to represent the current position indicator.
 
-      ##
-      # :attr_reader: thumb_style
-      # Style of the position indicator (thumb).
+    ##
+    # :attr_reader: thumb_style
+    # Style of the position indicator (thumb).
 
-      ##
-      # :attr_reader: track_symbol
-      # Symbol used to represent the empty space of the scrollbar.
+    ##
+    # :attr_reader: track_symbol
+    # Symbol used to represent the empty space of the scrollbar.
 
-      ##
-      # :attr_reader: track_style
-      # Style of the filled track area.
+    ##
+    # :attr_reader: track_style
+    # Style of the filled track area.
 
-      ##
-      # :attr_reader: begin_symbol
-      # Symbol rendered at the start of the track (e.g., arrow).
+    ##
+    # :attr_reader: begin_symbol
+    # Symbol rendered at the start of the track (e.g., arrow).
 
-      ##
-      # :attr_reader: begin_style
-      # Style of the start symbol.
+    ##
+    # :attr_reader: begin_style
+    # Style of the start symbol.
 
-      ##
-      # :attr_reader: end_symbol
-      # Symbol rendered at the end of the track (e.g., arrow).
+    ##
+    # :attr_reader: end_symbol
+    # Symbol rendered at the end of the track (e.g., arrow).
 
-      ##
-      # :attr_reader: end_style
-      # Style of the end symbol.
+    ##
+    # :attr_reader: end_style
+    # Style of the end symbol.
 
-      ##
-      # :attr_reader: style
-      # Base style applied to the entire widget.
+    ##
+    # :attr_reader: style
+    # Base style applied to the entire widget.
 
-      ##
-      # :attr_reader: block
-      # Optional wrapping block.
+    ##
+    # :attr_reader: block
+    # Optional wrapping block.
 
-      # Creates a new Scrollbar.
-      #
-      # [content_length] Integer.
-      # [position] Integer.
-      # [orientation] Symbol (default: <tt>:vertical</tt>).
-      # [thumb_symbol] String (default: <tt>"█"</tt>).
-      # [thumb_style] Style (optional).
-      # [track_symbol] String (optional).
-      # [track_style] Style (optional).
-      # [begin_symbol] String (optional).
-      # [begin_style] Style (optional).
-      # [end_symbol] String (optional).
-      # [end_style] Style (optional).
-      # [style] Style (optional).
-      # [block] Block (optional).
-      def initialize(
-        content_length:,
-        position:,
-        orientation: :vertical,
-        thumb_symbol: "█",
-        thumb_style: nil,
-        track_symbol: nil,
-        track_style: nil,
-        begin_symbol: nil,
-        begin_style: nil,
-        end_symbol: nil,
-        end_style: nil,
-        style: nil,
-        block: nil
+    # Creates a new Scrollbar.
+    #
+    # [content_length] Integer.
+    # [position] Integer.
+    # [orientation] Symbol (default: <tt>:vertical</tt>).
+    # [thumb_symbol] String (default: <tt>"█"</tt>).
+    # [thumb_style] Style (optional).
+    # [track_symbol] String (optional).
+    # [track_style] Style (optional).
+    # [begin_symbol] String (optional).
+    # [begin_style] Style (optional).
+    # [end_symbol] String (optional).
+    # [end_style] Style (optional).
+    # [style] Style (optional).
+    # [block] Block (optional).
+    def initialize(
+      content_length:,
+      position:,
+      orientation: :vertical,
+      thumb_symbol: "█",
+      thumb_style: nil,
+      track_symbol: nil,
+      track_style: nil,
+      begin_symbol: nil,
+      begin_style: nil,
+      end_symbol: nil,
+      end_style: nil,
+      style: nil,
+      block: nil
+    )
+      super(
+        content_length: Integer(content_length),
+        position: Integer(position),
+        orientation:,
+        thumb_symbol:,
+        thumb_style:,
+        track_symbol:,
+        track_style:,
+        begin_symbol:,
+        begin_style:,
+        end_symbol:,
+        end_style:,
+        style:,
+        block:
       )
-        super(
-          content_length: Integer(content_length),
-          position: Integer(position),
-          orientation: orientation,
-          thumb_symbol: thumb_symbol,
-          thumb_style: thumb_style,
-          track_symbol: track_symbol,
-          track_style: track_style,
-          begin_symbol: begin_symbol,
-          begin_style: begin_style,
-          end_symbol: end_symbol,
-          end_style: end_style,
-          style: style,
-          block: block
-        )
-      end
     end
+  end
 end

data/lib/ratatui_ruby/schema/shape/label.rb

@@ -59,7 +59,7 @@ module RatatuiRuby
       # [text] Text content (String or Text::Line).
       # [style] Style (optional).
       def initialize(x:, y:, text:, style: nil)
-        super(x: Float(x), y: Float(y), text: text, style: style)
+        super(x: Float(x), y: Float(y), text:, style:)
       end
     end
   end