ratatui_ruby 0.3.1 → 0.4.0

data/lib/ratatui_ruby/schema/layout.rb

@@ -4,19 +4,101 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-  # A widget that splits an area into multiple sections based on constraints.
-  #
-  # [direction] The direction of the layout (:vertical or :horizontal).
-  # [constraints] An array of Constraint objects defining the size of each section.
-  # [children] An array of widgets to render within each section.
-  class Layout < Data.define(:direction, :constraints, :children)
-    # Creates a new Layout.
+    # Divides an area into smaller chunks.
     #
-    # [direction] The direction of the layout (:vertical or :horizontal).
-    # [constraints] An array of Constraint objects defining the size of each section.
-    # [children] An array of widgets to render within each section.
-    def initialize(direction: :vertical, constraints: [], children: [])
-      super
+    # Terminal screens vary in size. Hardcoded positions break when the window resizes. You need a way to organize space dynamically.
+    #
+    # This class manages geometry. It splits a given area into multiple sections based on a list of constraints.
+    #
+    # Use layouts to build responsive grids. Stack sections vertically for a sidebar-main structure. Partition them horizontally for headers and footers. Let the layout engine do the math.
+    #
+    # === Examples
+    #
+    #   # A simple vertical split (Sidebar / Main)
+    #   Layout.new(
+    #     direction: :horizontal,
+    #     constraints: [
+    #       Constraint.length(20), # Sidebar
+    #       Constraint.min(0)      # Main content
+    #     ]
+    #   )
+    #
+    #   # Flex layout (Centering a block)
+    #   Layout.new(
+    #     direction: :vertical,
+    #     flex: :center,
+    #     constraints: [Constraint.length(10)], # A 10-row block centered vertically
+    #     children: [modal_block]
+    #   )
+    class Layout < Data.define(:direction, :constraints, :children, :flex)
+      ##
+      # :attr_reader: direction
+      # Direction of the split.
+      #
+      # Either <tt>:vertical</tt> (top to bottom) or <tt>:horizontal</tt> (left to right).
+      #
+      #   layout.direction # => :vertical
+
+      ##
+      # :attr_reader: constraints
+      # Array of rules defining section sizes.
+      #
+      # See RatatuiRuby::Constraint.
+
+      ##
+      # :attr_reader: children
+      # Widgets to render in each section (optional).
+      #
+      # If provided, `children[i]` is rendered into the area defined by `constraints[i]`.
+
+      ##
+      # :attr_reader: flex
+      # Strategy for distributing extra space.
+      #
+      # One of <tt>:legacy</tt>, <tt>:start</tt>, <tt>:center</tt>, <tt>:end</tt>, <tt>:space_between</tt>, <tt>:space_around</tt>.
+
+      # :nodoc:
+      FLEX_MODES = %i[legacy start center end space_between space_around space_evenly].freeze
+
+      # Creates a new Layout.
+      #
+      # [direction]
+      #   <tt>:vertical</tt> or <tt>:horizontal</tt> (default: <tt>:vertical</tt>).
+      # [constraints]
+      #   list of Constraint objects.
+      # [children]
+      #   List of widgets to render (optional).
+      # [flex]
+      #   Flex mode for spacing (default: <tt>:legacy</tt>).
+      def initialize(direction: :vertical, constraints: [], children: [], flex: :legacy)
+        super
+      end
+
+      # Splits an area into multiple rectangles.
+      #
+      # This is a pure calculation helper for hit testing. It computes where
+      # widgets *would* be placed without actually rendering them.
+      #
+      #   rects = Layout.split(
+      #     area,
+      #     direction: :horizontal,
+      #     constraints: [Constraint.percentage(50), Constraint.percentage(50)]
+      #   )
+      #   left, right = rects
+      #
+      # [area]
+      #   The area to split (a Rect or any object responding to x, y, width, height).
+      # [direction]
+      #   <tt>:vertical</tt> or <tt>:horizontal</tt> (default: <tt>:vertical</tt>).
+      # [constraints]
+      #   Array of Constraint objects defining section sizes.
+      # [flex]
+      #   Flex mode for spacing (default: <tt>:legacy</tt>).
+      #
+      # Returns an Array of Rect objects.
+      def self.split(area, direction: :vertical, constraints:, flex: :legacy)
+        raw_rects = _split(area, direction, constraints, flex)
+        raw_rects.map { |r| Rect.new(x: r[:x], y: r[:y], width: r[:width], height: r[:height]) }
+      end
     end
-  end
 end

data/lib/ratatui_ruby/schema/line_gauge.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+    # Displays a compact, single-line progress bar.
+    #
+    # Screen space is precious. Standard block gauges are bulky and consume multiple rows.
+    #
+    # This widget compresses the feedback. It draws a progress bar using line characters, fitting perfectly into tight layouts or lists.
+    #
+    # Use it when you need to show status without stealing focus or space.
+    #
+    # === Examples
+    #
+    #   LineGauge.new(
+    #     ratio: 0.4,
+    #     filled_style: Style.new(fg: :blue),
+    #     unfilled_symbol: "-"
+    #   )
+    class LineGauge < Data.define(:ratio, :label, :style, :filled_style, :unfilled_style, :block, :filled_symbol, :unfilled_symbol)
+       ##
+       # :attr_reader: ratio
+       # Progress ratio from 0.0 to 1.0.
+
+       ##
+       # :attr_reader: label
+       # Optional label.
+
+       ##
+       # :attr_reader: style
+       # Base style applied to the entire gauge.
+
+       ##
+       # :attr_reader: filled_style
+       # Style for the completed portion.
+
+       ##
+       # :attr_reader: unfilled_style
+       # Style for the remainder.
+
+       ##
+       # :attr_reader: block
+       # Optional wrapping block.
+
+       ##
+       # :attr_reader: filled_symbol
+       # Character for filled segments.
+
+       ##
+       # :attr_reader: unfilled_symbol
+       # Character for empty segments.
+
+       # Creates a new LineGauge.
+       #
+       # [ratio] Float (0.0 - 1.0).
+       # [label] String (optional).
+       # [style] Style (optional, base style for the gauge).
+       # [filled_style] Style.
+       # [unfilled_style] Style.
+       # [block] Block.
+       # [filled_symbol] String (default: <tt>"█"</tt>).
+       # [unfilled_symbol] String (default: <tt>"░"</tt>).
+       def initialize(ratio: 0.0, label: nil, style: nil, filled_style: nil, unfilled_style: nil, block: nil, filled_symbol: "█", unfilled_symbol: "░")
+         super(
+           ratio: Float(ratio),
+           label: label,
+           style: style,
+           filled_style: filled_style,
+           unfilled_style: unfilled_style,
+           block: block,
+           filled_symbol: filled_symbol,
+           unfilled_symbol: unfilled_symbol
+         )
+       end
+    end
+end

data/lib/ratatui_ruby/schema/list.rb

@@ -4,25 +4,99 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-  # A widget that displays a list of selectable items.
-  #
-  # [items] An array of strings to display in the list.
-  # [selected_index] The index of the currently selected item, or nil if none.
-  # [style] The base style for all items.
-  # [highlight_style] The style for the selected item.
-  # [highlight_symbol] The symbol to display in front of the selected item.
-  # [block] An optional Block widget to wrap the list.
-  class List < Data.define(:items, :selected_index, :style, :highlight_style, :highlight_symbol, :block)
-    # Creates a new List.
+    # Displays a selectable list of items.
     #
-    # [items] An array of strings to display in the list.
-    # [selected_index] The index of the currently selected item, or nil if none.
-    # [style] The base style for all items.
-    # [highlight_style] The style for the selected item.
-    # [highlight_symbol] The symbol to display in front of the selected item.
-    # [block] An optional Block widget to wrap the list.
-    def initialize(items: [], selected_index: nil, style: nil, highlight_style: nil, highlight_symbol: "> ", block: nil)
-      super
+    # Users need to choose from options. Menus, file explorers, and selectors are everywhere.
+    # Implementing navigation, highlighting, and scrolling state from scratch is tedious.
+    #
+    # This widget manages the list. It renders the items. It highlights the selection. It handles the scrolling window.
+    #
+    # Use it to build main menus, navigation sidebars, or logs.
+    #
+    # === Examples
+    #
+    #   # Basic List
+    #   List.new(items: ["Item 1", "Item 2"])
+    #
+    #   # Navigation Menu
+    #   List.new(
+    #     items: ["New Game", "Load Game", "Options", "Quit"],
+    #     selected_index: 0,
+    #     highlight_style: Style.new(bg: :blue),
+    #     highlight_symbol: ">> "
+    #   )
+    class List < Data.define(:items, :selected_index, :style, :highlight_style, :highlight_symbol, :repeat_highlight_symbol, :highlight_spacing, :direction, :scroll_padding, :block)
+      ##
+      # :attr_reader: items
+      # The items to display (Array of Strings).
+
+      ##
+      # :attr_reader: selected_index
+      # Index of the active selection (Integer or nil).
+
+      ##
+      # :attr_reader: style
+      # Base style for unselected items.
+
+      ##
+      # :attr_reader: highlight_style
+      # Style for the selected item.
+
+      ##
+      # :attr_reader: highlight_symbol
+      # Symbol drawn before the selected item.
+
+      ##
+      # :attr_reader: repeat_highlight_symbol
+      # Whether to repeat the highlight symbol for each line of the selected item.
+
+      ##
+      # :attr_reader: highlight_spacing
+      # When to show the highlight symbol column.
+      #
+      # <tt>:always</tt>, <tt>:when_selected</tt>, or <tt>:never</tt>.
+
+      ##
+      # :attr_reader: direction
+      # Render direction.
+      #
+      # <tt>:top_to_bottom</tt> or <tt>:bottom_to_top</tt>.
+
+      ##
+      # :attr_reader: scroll_padding
+      # Number of items to keep visible above/below the selected item when scrolling (Integer or nil).
+
+      ##
+      # :attr_reader: block
+      # Optional wrapping block.
+
+      # Creates a new List.
+      #
+      # Integer parameters accept any object responding to +to_int+ or +to_i+ (duck-typed).
+      #
+      # [items] Array of Strings.
+      # [selected_index] Numeric (nullable, coerced to Integer).
+      # [style] Style object.
+      # [highlight_style] Style object.
+      # [highlight_symbol] String (default: <tt>"> "</tt>).
+      # [repeat_highlight_symbol] Boolean (default: <tt>false</tt>).
+      # [highlight_spacing] Symbol (default: <tt>:when_selected</tt>).
+      # [direction] Symbol (default: <tt>:top_to_bottom</tt>).
+      # [scroll_padding] Numeric (nullable, coerced to Integer, default: <tt>nil</tt>).
+      # [block] Block (optional).
+      def initialize(items: [], selected_index: nil, style: nil, highlight_style: nil, highlight_symbol: "> ", repeat_highlight_symbol: false, highlight_spacing: :when_selected, direction: :top_to_bottom, scroll_padding: nil, block: nil)
+        super(
+          items: items,
+          selected_index: selected_index.nil? ? nil : Integer(selected_index),
+          style: style,
+          highlight_style: highlight_style,
+          highlight_symbol: highlight_symbol,
+          repeat_highlight_symbol: repeat_highlight_symbol,
+          highlight_spacing: highlight_spacing,
+          direction: direction,
+          scroll_padding: scroll_padding.nil? ? nil : Integer(scroll_padding),
+          block: block
+        )
+      end
     end
-  end
 end

data/lib/ratatui_ruby/schema/overlay.rb

@@ -4,12 +4,38 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-  # Renders children on top of each other (Painter's Algorithm).
-  #
-  # [layers] Array of Widgets.
-  class Overlay < Data.define(:layers)
-    # Creates a new Overlay.
-    #
-    # [layers] Array of Widgets.
-  end
+    # Stacks widgets on top of each other.
+    #
+    # Terminal interfaces are 2D grids, but complex UIs require depth. You need to float modals over text,
+    # or place a status bar on top of a map.
+    #
+    # This widget manages the Z-axis. It renders a list of widgets sequentially into the same area.
+    # Later widgets draw over earlier ones (Painter's Algorithm).
+    #
+    # Use overlays to compose complex scenes. Combine backgrounds, main content, and floating elements.
+    #
+    # === Examples
+    #
+    #   Overlay.new(
+    #     layers: [
+    #       BackgroundMap.new,
+    #       StatusBar.new,   # Draws over map
+    #       ModalDialog.new  # Draws over everything
+    #     ]
+    #   )
+    class Overlay < Data.define(:layers)
+      ##
+      # :attr_reader: layers
+      # The stack of widgets to render.
+      #
+      # Rendered from index 0 to N. Index N is the top-most layer.
+
+      # Creates a new Overlay.
+      #
+      # [layers]
+      #   Array of widgets.
+      def initialize(layers: [])
+        super
+      end
+    end
 end

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.
-  #
-  # [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)
-    # Creates a new Paragraph.
+    # Displays a block of text.
     #
-    # [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
-    end
+    # 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] 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: text,
+          style: style,
+          block: block,
+          wrap: wrap,
+          alignment: alignment,
+          scroll: [Integer(scroll[0]), Integer(scroll[1])]
+        )
+      end
+
+      # 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:)
+        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
 
-    # 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])
-      style ||= Style.new(fg:, bg:)
-      super(text:, style:, block:, wrap:, align:, scroll:)
+      # 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
 end

data/lib/ratatui_ruby/schema/ratatui_logo.rb

@@ -0,0 +1,25 @@
+# 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.
+  #
+  # A simple widget that renders the Ratatui logo. Useful for demos and about screens.
+  #
+  # === Examples
+  #
+  #   RatatuiLogo.new
+  #
+  class RatatuiLogo < Data.define
+    ##
+    # :method: new
+    # :call-seq: new -> RatatuiLogo
+    #
+    # Creates a new RatatuiLogo.
+    def initialize
+      super
+    end
+  end
+end

data/lib/ratatui_ruby/schema/ratatui_mascot.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 mascot.
+  #
+  # A widget that renders the Ratatui mascot (a rat).
+  #
+  # === Examples
+  #
+  #   RatatuiMascot.new(
+  #     block: Block.new(title: "Mascot")
+  #   )
+  #
+  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.
-  #
-  # [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.
-  class Rect < Data.define(:x, :y, :width, :height)
-    # Creates a new Rect.
+    # 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.
-    def initialize(x: 0, y: 0, width: 0, height: 0)
-      super
+    # 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.
+      #
+      # 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
+
+      # 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
 end