ratatui_ruby 1.4.0-x86_64-linux

data/lib/ratatui_ruby/widgets/coerceable_widget.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Widgets
+    # Mixin that provides DWIM hash coercion for widget classes.
+    #
+    # When users call `tui.table(hash)` instead of `tui.table(**hash)`,
+    # Ruby's `...` forwarding passes the Hash as a positional argument,
+    # causing cryptic TypeErrors at the Rust FFI boundary.
+    #
+    # This mixin provides a `coerce_args` class method that detects
+    # this pattern and automatically splats the hash into keyword arguments.
+    #
+    # === Behavior
+    #
+    # - **Production mode**: Unknown keys are silently ignored
+    # - **Debug mode (RR_DEBUG=1)**: Raises ArgumentError to catch typos early
+    #
+    # === Usage
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   class Table < Data.define(:rows, :widths, ...)
+    #     include CoerceableWidget
+    #   end
+    #
+    #   # In WidgetFactories:
+    #   def table(first = nil, **kwargs)
+    #     Widgets::Table.coerce_args(first, kwargs)
+    #   end
+    #--
+    # SPDX-SnippetEnd
+    #++
+    module CoerceableWidget
+      ##
+      # Hook called when this module is included in a widget class.
+      #
+      # Extends the class with ClassMethods and defines KNOWN_KEYS constant
+      # from the Data.define members for validation.
+      #
+      # [base] The class including this module.
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.const_set(:KNOWN_KEYS, base.members.freeze) unless base.const_defined?(:KNOWN_KEYS)
+      end
+
+      # Class methods extended onto widget classes.
+      module ClassMethods
+        # Coerces a bare Hash argument into keyword arguments.
+        #
+        # @param first [Hash, nil] First positional argument (bare hash case)
+        # @param kwargs [Hash] Keyword arguments (normal splatted case)
+        # @return [Object] New instance of the widget class
+        # @raise [ArgumentError] In debug mode, if unknown keys are present
+        def coerce_args(first, kwargs)
+          if first.is_a?(Hash) && kwargs.empty?
+            unknown = first.keys - self::KNOWN_KEYS
+            if unknown.any? && RatatuiRuby::Debug.enabled?
+              raise ArgumentError, "#{name}: unknown keys #{unknown.inspect}"
+            end
+            new(**first.slice(*self::KNOWN_KEYS))
+          else
+            new(**kwargs)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/widgets/cursor.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Widgets
+    # Controls the terminal cursor position.
+    #
+    # Interfaces are not just output; they require input. Users need a visual cue—a blinking block or line—to know where their keystrokes will appear.
+    #
+    # This widget renders a ghost. It does not draw a character but instructs the terminal to place the hardware cursor at specific coordinates.
+    #
+    # Use it for text editors, input fields, or command prompts.
+    #
+    # === Examples
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   Cursor.new(x: 10, y: 5)
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # See also:
+    # - {Declarative implementation using Tree API}[link:/examples/app_login_form/app_rb.html]
+    # - {Component-based implementation using Frame API}[link:/examples/app_color_picker/app_rb.html]
+    # - RatatuiRuby::Frame#set_cursor_position (Frame API alternative)
+    class Cursor < Data.define(:x, :y)
+      include CoerceableWidget
+
+      ##
+      # :attr_reader: x
+      # X coordinate (column).
+
+      ##
+      # :attr_reader: y
+      # Y coordinate (row).
+
+      # Creates a new Cursor.
+      #
+      # [x] Integer.
+      # [y] Integer.
+      def initialize(x:, y:)
+        super(x: Integer(x), y: Integer(y))
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/widgets/gauge.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Widgets
+    # Displays a standard progress bar.
+    #
+    # Long-running tasks create anxiety. Users need to know that the system is working and how much is left to do.
+    #
+    # This widget visualizes completion. It fills a bar based on a percentage.
+    #
+    # Use it for downloads, installations, or processing jobs.
+    #
+    # {rdoc-image:/doc/images/widget_gauge.png}[link:/examples/widget_gauge/app_rb.html]
+    #
+    # === Example
+    #
+    # Run the interactive demo from the terminal:
+    #
+    #   ruby examples/widget_gauge/app.rb
+    class Gauge < Data.define(:ratio, :label, :style, :gauge_style, :block, :use_unicode)
+      include CoerceableWidget
+
+      ##
+      # :attr_reader: ratio
+      # Progress ratio from 0.0 to 1.0.
+
+      ##
+      # :attr_reader: label
+      # Text label to display (optional).
+      #
+      # Accepts String or Text::Span for rich styling.
+      #
+      # If nil, it often displays the percentage automatically depending on renderer logic,
+      # but explicit labels are preferred.
+
+      ##
+      # :attr_reader: style
+      # Base style applied to the entire gauge background (optional).
+
+      ##
+      # :attr_reader: gauge_style
+      # Style applied specifically to the filled bar portion (optional).
+
+      ##
+      # :attr_reader: block
+      # Optional wrapping block.
+
+      ##
+      # :attr_reader: use_unicode
+      # Whether to use Unicode block characters (true) or ASCII characters (false).
+      # Default is false (ASCII) to be conservative, though Ratatui defaults to true.
+
+      # Creates a new Gauge.
+      #
+      # [ratio] Float (0.0 - 1.0).
+      # [percent] Integer (0 - 100), alternative to ratio.
+      # [label] String or Text::Span (optional).
+      # [style] Style object for the background (optional).
+      # [gauge_style] Style object for the filled bar (optional).
+      # [block] Block widget (optional).
+      # [use_unicode] Boolean (default: true).
+      #
+      # Raises ArgumentError if percent is not 0..100.
+      def initialize(ratio: nil, percent: nil, label: nil, style: nil, gauge_style: nil, block: nil, use_unicode: true)
+        if percent
+          float_percent = Float(percent)
+          unless float_percent.between?(0, 100)
+            raise ArgumentError, "percent must be between 0 and 100 (got #{percent.inspect})"
+          end
+          # Float(Numeric) incorrectly returns Float? -- https://github.com/ruby/rbs/issues/2793
+          ratio = float_percent / 100.0 #: Float
+        end
+        ratio = Float(ratio || 0.0)
+        super(ratio:, label:, style:, gauge_style:, block:, use_unicode:)
+      end
+
+      # Returns true if the gauge has any fill (ratio > 0).
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Widgets::Gauge.new(ratio: 0.0).filled?  # => false
+      #   Widgets::Gauge.new(ratio: 0.5).filled?  # => true
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def filled?
+        ratio > 0
+      end
+
+      # Returns true if the gauge is at 100% or more (ratio >= 1.0).
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Widgets::Gauge.new(ratio: 0.99).complete?  # => false
+      #   Widgets::Gauge.new(ratio: 1.0).complete?   # => true
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def complete?
+        ratio >= 1.0
+      end
+
+      # Returns the progress as an integer percentage (0-100).
+      #
+      # Gauge stores progress as a ratio (0.0 to 1.0). User-facing code often
+      # displays percentages. Converting manually is tedious.
+      #
+      # This is the inverse of passing <tt>percent:</tt> to the constructor.
+      # Rounds down to the nearest integer.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   gauge = Widgets::Gauge.new(percent: 75)
+      #   gauge.percent  # => 75
+      #
+      #   gauge = Widgets::Gauge.new(ratio: 0.456)
+      #   gauge.percent  # => 45
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def percent
+        (ratio * 100).to_i
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/widgets/line_gauge.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Widgets
+    # 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.png}[link:/examples/widget_line_gauge/app_rb.html]
+    #
+    # === Example
+    #
+    # Run the interactive demo from the terminal:
+    #
+    #   ruby examples/widget_line_gauge/app.rb
+    class LineGauge < Data.define(:ratio, :label, :style, :filled_style, :unfilled_style, :block, :filled_symbol, :unfilled_symbol)
+      include CoerceableWidget
+
+      ##
+      # :attr_reader: ratio
+      # Progress ratio from 0.0 to 1.0.
+
+      ##
+      # :attr_reader: label
+      # Optional label (String or Text::Span for rich styling).
+
+      ##
+      # :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).
+      # [percent] Integer (0 - 100), alternative to ratio.
+      # [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>).
+      #
+      # Raises ArgumentError if percent is not 0..100.
+      def initialize(ratio: nil, percent: nil, label: nil, style: nil, filled_style: nil, unfilled_style: nil, block: nil, filled_symbol: "█", unfilled_symbol: "░")
+        if percent
+          float_percent = Float(percent)
+          unless float_percent.between?(0, 100)
+            raise ArgumentError, "percent must be between 0 and 100 (got #{percent.inspect})"
+          end
+          ratio = float_percent / 100.0
+        end
+        ratio = Float(ratio || 0.0)
+        super(
+          ratio:,
+          label:,
+          style:,
+          filled_style:,
+          unfilled_style:,
+          block:,
+          filled_symbol:,
+          unfilled_symbol:
+        )
+      end
+
+      # Returns true if the gauge has any fill (ratio > 0).
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Widgets::LineGauge.new(ratio: 0.0).filled?  # => false
+      #   Widgets::LineGauge.new(ratio: 0.5).filled?  # => true
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def filled?
+        ratio > 0
+      end
+
+      # Returns true if the gauge is at 100% or more (ratio >= 1.0).
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Widgets::LineGauge.new(ratio: 0.99).complete?  # => false
+      #   Widgets::LineGauge.new(ratio: 1.0).complete?   # => true
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def complete?
+        ratio >= 1.0
+      end
+
+      # Returns the progress as an integer percentage (0-100).
+      #
+      # LineGauge stores progress as a ratio (0.0 to 1.0). User-facing code often
+      # displays percentages. Converting manually is tedious.
+      #
+      # This is the inverse of passing <tt>percent:</tt> to the constructor.
+      # Rounds down to the nearest integer.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   lg = Widgets::LineGauge.new(percent: 75)
+      #   lg.percent  # => 75
+      #
+      #   lg = Widgets::LineGauge.new(ratio: 0.456)
+      #   lg.percent  # => 45
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def percent
+        (ratio * 100).to_i
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/widgets/list.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Widgets
+    # 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.png}[link:/examples/widget_list/app_rb.html]
+    #
+    # === Examples
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   # 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: ">> "
+    #   )
+    #--
+    # SPDX-SnippetEnd
+    #++
+    class List < Data.define(:items, :selected_index, :offset, :style, :highlight_style, :highlight_symbol, :repeat_highlight_symbol, :highlight_spacing, :direction, :scroll_padding, :block)
+      include CoerceableWidget
+
+      ##
+      # Highlight spacing: always show the spacing column.
+      HIGHLIGHT_ALWAYS = :always
+      ##
+      # Highlight spacing: show spacing only when an item is selected (default).
+      HIGHLIGHT_WHEN_SELECTED = :when_selected
+      ##
+      # Highlight spacing: never show the spacing column.
+      HIGHLIGHT_NEVER = :never
+
+      ##
+      # Direction: render items from top to bottom (default).
+      DIRECTION_TOP_TO_BOTTOM = :top_to_bottom
+      ##
+      # Direction: render items from bottom to top.
+      DIRECTION_BOTTOM_TO_TOP = :bottom_to_top
+
+      ##
+      # :attr_reader: items
+      # The items to display.
+      #
+      # 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).
+      #
+      # Controls the viewport's starting position in the list.
+      #
+      # When +nil+ (default), Ratatui auto-scrolls to keep the selection visible ("natural scrolling").
+      #
+      # 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.
+      #
+      # *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: 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, 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
+
+      # Returns true if an item is selected.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   list = Widgets::List.new(items: %w[a b c])
+      #   list.selected?  # => false
+      #
+      #   list = Widgets::List.new(items: %w[a b c], selected_index: 1)
+      #   list.selected?  # => true
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # Returns: Boolean.
+      def selected?
+        !selected_index.nil?
+      end
+
+      # Returns true if the list contains no items.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   list = Widgets::List.new(items: [])
+      #   list.empty?  # => true
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # Returns: Boolean.
+      def empty?
+        items.empty?
+      end
+
+      # Returns the number of items in the list.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   list = Widgets::List.new(items: %w[alpha beta gamma])
+      #   list.len  # => 3
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # Returns: Integer.
+      def len
+        items.length
+      end
+
+      alias length len
+      alias size len
+
+      # NOTE: No 'selection' alias - it's ambiguous whether it returns an item or index.
+      # Use selected_index for the index, selected_item for the item.
+
+      # Returns the currently selected item, or nil if nothing is selected.
+      #
+      # Accessing the selected item directly requires looking up +items[selected_index]+
+      # after checking that +selected_index+ is not nil. This is verbose.
+      #
+      # This method encapsulates that pattern.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   list = Widgets::List.new(items: %w[alpha beta gamma], selected_index: 1)
+      #   list.selected_item  # => "beta"
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # Returns: The item at the selected index, or nil if no selection.
+      def selected_item
+        return nil if selected_index.nil?
+
+        items[selected_index]
+      end
+    end
+  end
+end