ratatui_ruby 0.4.0 → 0.6.0

data/lib/ratatui_ruby/schema/line_gauge.rb

@@ -4,75 +4,75 @@
 # 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.
+  # 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.
+  #
+  # {rdoc-image:/doc/images/widget_line_gauge_demo.png}[link:/examples/widget_line_gauge_demo/app_rb.html]
+  #
+  # === Example
+  #
+  # Run the interactive demo from the terminal:
+  #
+  #   ruby examples/widget_line_gauge_demo/app.rb
+  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: label
+    # Optional label (String or Text::Span for rich styling).
 
-       ##
-       # :attr_reader: style
-       # Base style applied to the entire gauge.
+    ##
+    # :attr_reader: style
+    # Base style applied to the entire gauge.
 
-       ##
-       # :attr_reader: filled_style
-       # Style for the completed portion.
+    ##
+    # :attr_reader: filled_style
+    # Style for the completed portion.
 
-       ##
-       # :attr_reader: unfilled_style
-       # Style for the remainder.
+    ##
+    # :attr_reader: unfilled_style
+    # Style for the remainder.
 
-       ##
-       # :attr_reader: block
-       # Optional wrapping block.
+    ##
+    # :attr_reader: block
+    # Optional wrapping block.
 
-       ##
-       # :attr_reader: filled_symbol
-       # Character for filled segments.
+    ##
+    # :attr_reader: filled_symbol
+    # Character for filled segments.
 
-       ##
-       # :attr_reader: unfilled_symbol
-       # Character for empty 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
+    # Creates a new LineGauge.
+    #
+    # [ratio] Float (0.0 - 1.0).
+    # [label] String or Text::Span (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:,
+        style:,
+        filled_style:,
+        unfilled_style:,
+        block:,
+        filled_symbol:,
+        unfilled_symbol:
+      )
     end
+  end
 end

data/lib/ratatui_ruby/schema/list.rb

@@ -4,99 +4,122 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-    # Displays a selectable list of items.
+  # Displays a selectable list of items.
+  #
+  # 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.
+  #
+  # {rdoc-image:/doc/images/widget_list_demo.png}[link:/examples/widget_list_demo/app_rb.html]
+  #
+  # === 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, :offset, :style, :highlight_style, :highlight_symbol, :repeat_highlight_symbol, :highlight_spacing, :direction, :scroll_padding, :block)
+    ##
+    # :attr_reader: items
+    # The items to display.
     #
-    # 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.
+    # Accepts Array of Strings, Text::Spans, Text::Lines, or ListItem objects.
+    # For styled individual rows, use ListItem with a style.
+
+    ##
+    # :attr_reader: selected_index
+    # Index of the active selection (Integer or nil).
+
+    ##
+    # :attr_reader: offset
+    # Scroll offset (Integer or nil).
     #
-    # Use it to build main menus, navigation sidebars, or logs.
+    # Controls the viewport's starting position in the list.
     #
-    # === Examples
+    # When +nil+ (default), Ratatui auto-scrolls to keep the selection visible ("natural scrolling").
     #
-    #   # Basic List
-    #   List.new(items: ["Item 1", "Item 2"])
+    # When set, forces the viewport to start at this item index. Use this for:
+    # - **Passive scrolling**: Scroll through a log viewer without selecting items.
+    # - **Click-to-select math**: Calculate which item index corresponds to a click coordinate.
     #
-    #   # 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).
+    # *Important*: When both +offset+ and +selected_index+ are set, Ratatui may still adjust
+    # the viewport during rendering to ensure the selection stays visible. Set +selected_index+
+    # to +nil+ for fully manual scroll control.
 
-      ##
-      # :attr_reader: style
-      # Base style for unselected items.
+    ##
+    # :attr_reader: style
+    # Base style for unselected items.
 
-      ##
-      # :attr_reader: highlight_style
-      # Style for the selected item.
+    ##
+    # :attr_reader: highlight_style
+    # Style for the selected item.
 
-      ##
-      # :attr_reader: highlight_symbol
-      # Symbol drawn before 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: 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: 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: 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: scroll_padding
+    # Number of items to keep visible above/below the selected item when scrolling (Integer or nil).
 
-      ##
-      # :attr_reader: block
-      # Optional wrapping block.
+    ##
+    # :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
+    # Creates a new List.
+    #
+    # Integer parameters accept any object responding to +to_int+ or +to_i+ (duck-typed).
+    #
+    # [items] Array of Strings, Text::Spans, Text::Lines, or ListItem objects.
+    # [selected_index] Numeric (nullable, coerced to Integer).
+    # [offset] Numeric (nullable, coerced to Integer). Forces scroll position when set.
+    # [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, offset: 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:,
+        selected_index: selected_index.nil? ? nil : Integer(selected_index),
+        offset: offset.nil? ? nil : Integer(offset),
+        style:,
+        highlight_style:,
+        highlight_symbol:,
+        repeat_highlight_symbol:,
+        highlight_spacing:,
+        direction:,
+        scroll_padding: scroll_padding.nil? ? nil : Integer(scroll_padding),
+        block:
+      )
     end
+  end
 end

data/lib/ratatui_ruby/schema/list_item.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # A styled list item combining content with optional style.
+  #
+  # By default, List items are strings. For more control over styling individual rows,
+  # wrap the content in a ListItem to apply a style specific to that item.
+  #
+  # The content can be a String, Text::Span, or Text::Line. The style applies to the
+  # entire row background.
+  #
+  # === Examples
+  #
+  #   # Item with red background
+  #   ListItem.new(content: "Error", style: Style.new(bg: :red))
+  #
+  #   # Item with styled content
+  #   ListItem.new(
+  #     content: Text::Span.new(content: "Status: OK", style: Style.new(fg: :green, modifiers: [:bold]))
+  #   )
+  class ListItem < Data.define(:content, :style)
+    ##
+    # :attr_reader: content
+    # The content to display (String, Text::Span, or Text::Line).
+
+    ##
+    # :attr_reader: style
+    # The style to apply to the item (optional Style).
+
+    # Creates a new ListItem.
+    #
+    # [content] String, Text::Span, or Text::Line.
+    # [style] Style object (optional).
+    def initialize(content:, style: nil)
+      super
+    end
+  end
+end

data/lib/ratatui_ruby/schema/overlay.rb

@@ -4,38 +4,38 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-    # Stacks widgets on top of each other.
+  # 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.
     #
-    # 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.
+    # 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
+    # Creates a new Overlay.
+    #
+    # [layers]
+    #   Array of widgets.
+    def initialize(layers: [])
+      super
     end
+  end
 end

data/lib/ratatui_ruby/schema/paragraph.rb

@@ -4,94 +4,94 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-    # Displays a block of text.
-    #
-    # 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.
+  # Displays a block of text.
+  #
+  # 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: style
+    # Base style for the text.
 
-      ##
-      # :attr_reader: block
-      # Optional wrapping block.
+    ##
+    # :attr_reader: block
+    # Optional wrapping block.
 
-      ##
-      # :attr_reader: wrap
-      # Whether to wrap text at the edge of the container (Boolean).
+    ##
+    # :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: alignment
+    # Text alignment.
+    #
+    # <tt>:left</tt>, <tt>:center</tt>, or <tt>:right</tt>.
 
-      ##
-      # :attr_reader: scroll
-      # Scroll offset [y, x].
+    ##
+    # :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
+    # 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:,
+        style:,
+        block:,
+        wrap:,
+        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
+    # 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
+    # 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
+    # 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

@@ -6,20 +6,24 @@
 module RatatuiRuby
   # Displays the Ratatui logo.
   #
-  # A simple widget that renders the Ratatui logo. Useful for demos and about screens.
+  # Branding is important for identity. Users need to recognize the tools they use.
   #
-  # === Examples
+  # This widget renders the official Ratatui logo.
   #
-  #   RatatuiLogo.new
+  # 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.
-    def initialize
-      super
-    end
   end
 end