ratatui_ruby 0.3.1 → 0.5.0

data/lib/ratatui_ruby/schema/paragraph.rb

@@ -4,37 +4,94 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-  # A widget that displays a block of text.
+  # Displays a block of text.
   #
-  # [text] the text to display.
-  # [style] the style to apply (Style object).
-  # [block] an optional Block widget to wrap the paragraph.
-  # [scroll] scroll offset as (y, x) array matching ratatui convention.
-  class Paragraph < Data.define(:text, :style, :block, :wrap, :align, :scroll)
+  # Raw strings are insufficient for UIs. They overflow constraints. They don't respect alignment (left, center, right).
+  #
+  # This widget creates a smart text container. It wraps content to fit the area. It aligns text as requested. It supports scrolling.
+  #
+  # Use it for everything from simple labels to complex, multi-paragraph documents.
+  #
+  # === Examples
+  #
+  #   # Basic Text
+  #   Paragraph.new(text: "Hello, World!")
+  #
+  #   # Styled container with wrapping
+  #   Paragraph.new(
+  #     text: "This is a long line that will wrap automatically.",
+  #     style: Style.new(fg: :green),
+  #     wrap: true,
+  #     block: Block.new(title: "Output", borders: [:all])
+  #   )
+  #
+  #   # Scrolling mechanism
+  #   Paragraph.new(text: large_text, scroll: [scroll_y, 0])
+  class Paragraph < Data.define(:text, :style, :block, :wrap, :alignment, :scroll)
+    ##
+    # :attr_reader: text
+    # The content to display.
+
+    ##
+    # :attr_reader: style
+    # Base style for the text.
+
+    ##
+    # :attr_reader: block
+    # Optional wrapping block.
+
+    ##
+    # :attr_reader: wrap
+    # Whether to wrap text at the edge of the container (Boolean).
+
+    ##
+    # :attr_reader: alignment
+    # Text alignment.
+    #
+    # <tt>:left</tt>, <tt>:center</tt>, or <tt>:right</tt>.
+
+    ##
+    # :attr_reader: scroll
+    # Scroll offset [y, x].
+
     # Creates a new Paragraph.
     #
-    # [text] the text to display.
-    # [style] the style to apply.
-    # [block] the block to wrap the paragraph.
-    # [wrap] whether to wrap text at width.
-    # [align] alignment (:left, :center, :right).
-    # [scroll] scroll offset as (y, x) array (default: [0, 0]).
-    def initialize(text:, style: Style.default, block: nil, wrap: false, align: :left, scroll: [0, 0])
-      super
+    # [text] String or Text::Line array.
+    # [style] Style object.
+    # [block] Block object.
+    # [wrap] Boolean (default: false).
+    # [alignment] Symbol (default: <tt>:left</tt>).
+    # [scroll] Array of [y, x] integers (duck-typed via +to_int+).
+    def initialize(text:, style: Style.default, block: nil, wrap: false, alignment: :left, scroll: [0, 0])
+      super(
+        text:,
+        style:,
+        block:,
+        wrap:,
+        alignment:,
+        scroll: [Integer(scroll[0]), Integer(scroll[1])]
+      )
     end
 
-    # Support for legacy fg/bg arguments.
-    # [text] the text to display.
-    # [style] the style to apply.
-    # [fg] legacy foreground color.
-    # [bg] legacy background color.
-    # [block] the block to wrap the paragraph.
-    # [wrap] whether to wrap text at width.
-    # [align] alignment (:left, :center, :right).
-    # [scroll] scroll offset as (y, x) array (default: [0, 0]).
-    def self.new(text:, style: nil, fg: nil, bg: nil, block: nil, wrap: false, align: :left, scroll: [0, 0])
+    # Legacy constructor support.
+    def self.new(text:, style: nil, fg: nil, bg: nil, block: nil, wrap: false, alignment: :left, scroll: [0, 0])
       style ||= Style.new(fg:, bg:)
-      super(text:, style:, block:, wrap:, align:, scroll:)
+      coerced_scroll = [Integer(scroll[0]), Integer(scroll[1])]
+      super(text:, style:, block:, wrap:, alignment:, scroll: coerced_scroll)
+    end
+
+    # Returns the number of lines the paragraph would take up if rendered with the given width.
+    #
+    # [width] Integer (max width).
+    def line_count(width)
+      RatatuiRuby.warn_experimental_feature("Paragraph#line_count")
+      RatatuiRuby._paragraph_line_count(self, Integer(width))
+    end
+
+    # Returns the minimum width needed to not wrap any text.
+    def line_width
+      RatatuiRuby.warn_experimental_feature("Paragraph#line_width")
+      RatatuiRuby._paragraph_line_width(self)
     end
   end
 end

data/lib/ratatui_ruby/schema/ratatui_logo.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # Displays the Ratatui logo.
+  #
+  # Branding is important for identity. Users need to recognize the tools they use.
+  #
+  # This widget renders the official Ratatui logo.
+  #
+  # Use it for splash screens, about sections, or terminal dashboards.
+  #
+  # {rdoc-image:/doc/images/widget_ratatui_logo_demo.png}[link:/examples/widget_ratatui_logo_demo/app_rb.html]
+  #
+  # === Example
+  #
+  # Run the interactive demo from the terminal:
+  #
+  #   ruby examples/widget_ratatui_logo_demo/app.rb
+  class RatatuiLogo < Data.define
+    ##
+    # :method: new
+    # :call-seq: new -> RatatuiLogo
+    #
+    # Creates a new RatatuiLogo.
+  end
+end

data/lib/ratatui_ruby/schema/ratatui_mascot.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # Displays the Ratatui mascot.
+  #
+  # Interfaces without personality feel clinical and dry. Users appreciate a friendly face in their terminal.
+  #
+  # This widget renders the Ratatui mascot (a mouse).
+  #
+  # 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
+    # :call-seq: new(block: nil) -> RatatuiMascot
+    #
+    # Creates a new RatatuiMascot.
+    #
+    # @param block [Block, nil] A block to wrap the widget in.
+    def initialize(block: nil)
+      super
+    end
+  end
+end

data/lib/ratatui_ruby/schema/rect.rb

@@ -4,21 +4,70 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-  # A rectangle in the terminal grid.
+  # Defines a rectangular area in the terminal grid.
   #
-  # [x] The x-coordinate of the top-left corner.
-  # [y] The y-coordinate of the top-left corner.
-  # [width] The width of the rectangle.
-  # [height] The height of the rectangle.
+  # 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.
     #
-    # [x] The x-coordinate of the top-left corner.
-    # [y] The y-coordinate of the top-left corner.
-    # [width] The width of the rectangle.
-    # [height] The height of the rectangle.
+    # 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
+      super(
+        x: Integer(x),
+        y: Integer(y),
+        width: Integer(width),
+        height: Integer(height)
+      )
+    end
+
+    # 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
   end
 end

data/lib/ratatui_ruby/schema/scrollbar.rb

@@ -4,30 +4,138 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-  ##
-  # Visual scroll indicator.
+  # Visualizes the scroll state of a viewport.
   #
-  # A Scrollbar widget that can be oriented vertically or horizontally.
-  # It displays a track and a thumb to indicate the current scroll position
-  # relative to the total content length.
+  # Content overflows. Users get lost in long lists without landmarks. They need to know where they are and how much is left.
   #
-  # == Fields
+  # This widget maps your context. It draws a track and a thumb, representing your current position relative to the total length.
   #
-  # [+content_length+] Total length of the content (Integer).
-  # [+position+] Current scroll position (Integer).
-  # [+orientation+] +:vertical+ or +:horizontal+ (Symbol, default: +:vertical+).
-  # [+thumb_symbol+] The character used for the scrollbar thumb (String, default: "█").
-  # [+block+] An optional Block to wrap the scrollbar.
-  class Scrollbar < Data.define(:content_length, :position, :orientation, :thumb_symbol, :block)
+  # 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: 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_style
+    # Style of the position indicator (thumb).
+
+    ##
+    # :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: begin_symbol
+    # Symbol rendered at the start of the track (e.g., arrow).
+
+    ##
+    # :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_style
+    # Style of the end symbol.
+
+    ##
+    # :attr_reader: style
+    # Base style applied to the entire widget.
+
+    ##
+    # :attr_reader: block
+    # Optional wrapping block.
+
     # Creates a new Scrollbar.
     #
-    # [+content_length+] Total length of the content (Integer).
-    # [+position+] Current scroll position (Integer).
-    # [+orientation+] +:vertical+ or +:horizontal+ (Symbol, default: +:vertical+).
-    # [+thumb_symbol+] The character used for the scrollbar thumb (String, default: "█").
-    # [+block+] An optional Block to wrap the scrollbar.
-    def initialize(content_length:, position:, orientation: :vertical, thumb_symbol: "█", block: nil)
-      super
+    # [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:
+      )
     end
   end
 end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  module Shape
+    # A text label on a canvas.
+    #
+    # Labels render text at specific coordinates in canvas space.
+    # Unlike shapes, labels are always rendered on top of all other canvas elements.
+    #
+    # [x] The x-coordinate in canvas space (Numeric).
+    # [y] The y-coordinate in canvas space (Numeric).
+    # [text] The text content (String or Text::Line).
+    # [style] Optional style for the text.
+    #
+    # === Examples
+    #
+    #   # Simple label
+    #   Shape::Label.new(x: 0, y: 0, text: "Origin")
+    #
+    #   # Styled label
+    #   Shape::Label.new(
+    #     x: -122.4, y: 37.8,
+    #     text: "San Francisco",
+    #     style: Style.new(fg: :cyan, add_modifier: :bold)
+    #   )
+    #
+    #   # Label with Text::Line for rich formatting
+    #   Shape::Label.new(
+    #     x: 0.0, y: 0.0,
+    #     text: Text::Line.new(spans: [
+    #       Text::Span.new(content: "Hello ", style: Style.new(fg: :red)),
+    #       Text::Span.new(content: "World", style: Style.new(fg: :blue))
+    #     ])
+    #   )
+    class Label < Data.define(:x, :y, :text, :style)
+      ##
+      # :attr_reader: x
+      # X coordinate in canvas space (Float, duck-typed via +to_f+).
+
+      ##
+      # :attr_reader: y
+      # Y coordinate in canvas space (Float, duck-typed via +to_f+).
+
+      ##
+      # :attr_reader: text
+      # Text content (String or Text::Line).
+
+      ##
+      # :attr_reader: style
+      # Optional style for the text.
+
+      # Creates a new Label.
+      #
+      # [x] X coordinate (Numeric).
+      # [y] Y coordinate (Numeric).
+      # [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:, style:)
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/schema/sparkline.rb

@@ -4,21 +4,129 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-  # A widget that displays a compact data row.
+  # Displays high-density data in a compact row.
   #
-  # [data] Array of Integers.
-  # [max] Optional maximum value.
-  # [style] Optional style for the sparkline.
-  # [block] Optional block widget to wrap the sparkline.
-  class Sparkline < Data.define(:data, :max, :style, :block)
+  # Users need context. A single value ("90% CPU") tells you current status, but not the trend.
+  # Full charts take up too much room.
+  #
+  # This widget solves the density problem. It condenses history into a single line of variable-height blocks.
+  #
+  # Use it in dashboards, headers, or list items to providing trending data at a glance.
+  #
+  # {rdoc-image:/doc/images/widget_sparkline_demo.png}[link:/examples/widget_sparkline_demo/app_rb.html]
+  #
+  # === Example
+  #
+  # Run the interactive demo from the terminal:
+  #
+  #   ruby examples/widget_sparkline_demo/app.rb
+  class Sparkline < Data.define(:data, :max, :style, :block, :direction, :absent_value_symbol, :absent_value_style, :bar_set)
+    ##
+    # :attr_reader: data
+    # Array of integer values to plot.
+
+    ##
+    # :attr_reader: max
+    # Maximum value for scaling (optional).
+    #
+    # If nil, derived from data max.
+
+    ##
+    # :attr_reader: style
+    # Style for the bars.
+
+    ##
+    # :attr_reader: block
+    # Optional wrapping block.
+
+    ##
+    # :attr_reader: direction
+    # Direction to render data.
+    #
+    # Accepts +:left_to_right+ (default) or +:right_to_left+.
+    # Use +:right_to_left+ when new data should appear on the left.
+
+    ##
+    # :attr_reader: absent_value_symbol
+    # Character to render for absent (nil) values (optional).
+    #
+    # If nil, absent values are rendered with a space.
+
+    ##
+    # :attr_reader: absent_value_style
+    # Style for absent (nil) values (optional).
+
+    ##
+    # :attr_reader: bar_set
+    # Custom characters for the bars (optional).
+    #
+    # A Hash with keys defining the characters for the bars.
+    # Keys: <tt>:empty</tt>, <tt>:one_eighth</tt>, <tt>:one_quarter</tt>, <tt>:three_eighths</tt>, <tt>:half</tt>, <tt>:five_eighths</tt>, <tt>:three_quarters</tt>, <tt>:seven_eighths</tt>, <tt>:full</tt>.
+    #
+    # You can also use integers (0-8) as keys, where 0 is empty, 4 is half, and 8 is full.
+    #
+    # Alternatively, you can pass an Array of 9 strings, where index 0 is empty and index 8 is full.
+    #
+    # === Examples
+    #
+    #   bar_set: {
+    #     empty: " ",
+    #     one_eighth: " ",
+    #     one_quarter: "▂",
+    #     three_eighths: "▃",
+    #     half: "▄",
+    #     five_eighths: "▅",
+    #     three_quarters: "▆",
+    #     seven_eighths: "▇",
+    #     full: "█"
+    #   }
+    #
+    #   # Numeric keys (0-8)
+    #   bar_set: {
+    #     0 => " ", 1 => " ", 2 => "▂", 3 => "▃", 4 => "▄", 5 => "▅", 6 => "▆", 7 => "▇", 8 => "█"
+    #   }
+    #
+    #   # Array (9 items)
+    #   bar_set: [" ", " ", "▂", "▃", "▄", "▅", "▆", "▇", "█"]
+
+    BAR_KEYS = %i[empty one_eighth one_quarter three_eighths half five_eighths three_quarters seven_eighths full].freeze
+
     # Creates a new Sparkline widget.
     #
-    # [data] Array of Integers.
-    # [max] Optional maximum value.
-    # [style] Optional style for the sparkline.
-    # [block] Optional block widget to wrap the sparkline.
-    def initialize(data:, max: nil, style: nil, block: nil)
-      super
+    # [data] Array of Integers or nil. nil marks an absent value (distinct from 0).
+    # [max] Max value (optional).
+    # [style] Style (optional).
+    # [block] Block (optional).
+    # [direction] +:left_to_right+ or +:right_to_left+ (default: +:left_to_right+).
+    # [absent_value_symbol] Character for absent (nil) values (optional).
+    # [absent_value_style] Style for absent (nil) values (optional).
+    # [bar_set] Hash or Array of custom characters (optional).
+    def initialize(data:, max: nil, style: nil, block: nil, direction: :left_to_right, absent_value_symbol: nil, absent_value_style: nil, bar_set: nil)
+      if bar_set
+        if bar_set.is_a?(Array) && bar_set.size == 9
+          # Convert Array to Hash using BAR_KEYS order
+          bar_set = BAR_KEYS.zip(bar_set).to_h
+        else
+          bar_set = bar_set.dup
+          # Normalize numeric keys (0-8) to symbolic keys
+          BAR_KEYS.each_with_index do |key, i|
+            if (val = bar_set.delete(i) || bar_set.delete(i.to_s))
+              bar_set[key] = val
+            end
+          end
+        end
+      end
+      coerced_data = data.map { |v| v.nil? ? nil : Integer(v) }
+      super(
+        data: coerced_data,
+        max: max.nil? ? nil : Integer(max),
+        style:,
+        block:,
+        direction:,
+        absent_value_symbol:,
+        absent_value_style:,
+        bar_set:
+      )
     end
   end
 end