ratatui_ruby 0.6.0 → 0.7.0

data/lib/ratatui_ruby/widgets/chart.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  module Widgets
+    # Defines an Axis for a Chart
+    # [title] String
+    # [bounds] Array<Float> [min, max]
+    # [labels] Array<String>
+    # [style] Style
+    # [labels_alignment] Symbol (<tt>:left</tt>, <tt>:center</tt>, <tt>:right</tt>)
+    class Axis < Data.define(:title, :bounds, :labels, :style, :labels_alignment)
+      ##
+      # :attr_reader: title
+      # Label for the axis (String).
+
+      ##
+      # :attr_reader: bounds
+      # Range [min, max] (Array of Floats).
+
+      ##
+      # :attr_reader: labels
+      # Explicit labels for ticks (Array of Strings).
+
+      ##
+      # :attr_reader: style
+      # Style for axis lines/text.
+
+      ##
+      # :attr_reader: labels_alignment
+      # Alignment of axis labels (:left, :center, :right).
+
+      # Creates a new Axis.
+      #
+      # [title] String.
+      # [bounds] Array [min, max].
+      # [labels] Array of Strings.
+      # [style] Style.
+      # [labels_alignment] Symbol (:left, :center, :right).
+      def initialize(title: "", bounds: [0.0, 10.0], labels: [], style: nil, labels_alignment: nil)
+        super(
+          title:,
+          bounds: [Float(bounds[0]), Float(bounds[1])],
+          labels:,
+          style:,
+          labels_alignment:
+        )
+      end
+    end
+
+    # Defines a Dataset for a Chart.
+    # [name] The name of the dataset.
+    # [data] Array of arrays [[x, y], [x, y]] (Floats).
+    # [style] The style of the line.
+    # [marker] Symbol (<tt>:dot</tt>, <tt>:braille</tt>, <tt>:block</tt>, <tt>:bar</tt>)
+    # [graph_type] Symbol (<tt>:line</tt>, <tt>:scatter</tt>)
+    class Dataset < Data.define(:name, :data, :style, :marker, :graph_type)
+      ##
+      # :attr_reader: name
+      # Name for logical identification or legend.
+
+      ##
+      # :attr_reader: data
+      # list of [x, y] coordinates.
+
+      ##
+      # :attr_reader: style
+      # Style applied to the dataset (Style).
+      #
+      # **Note**: Due to Ratatui's Chart widget design, only the foreground color (<tt>fg</tt>) is applied to markers in the chart area.
+      # The full style (including <tt>bg</tt> and <tt>modifiers</tt>) is displayed in the legend.
+      #
+      # Supports:
+      # - +fg+: Foreground color of markers (Symbol/Hex) - _applied to chart_
+      # - +bg+: Background color (Symbol/Hex) - _legend only_
+      # - +modifiers+: Array of effects (<tt>:bold</tt>, <tt>:dim</tt>, <tt>:italic</tt>, <tt>:underlined</tt>, <tt>:slow_blink</tt>, <tt>:rapid_blink</tt>, <tt>:reversed</tt>, <tt>:hidden</tt>, <tt>:crossed_out</tt>) - _legend only_
+
+      ##
+      # :attr_reader: marker
+      # Marker type (<tt>:dot</tt>, <tt>:braille</tt>).
+
+      ##
+      # :attr_reader: graph_type
+      # Type of graph (<tt>:line</tt>, <tt>:scatter</tt>).
+
+      # Creates a new Dataset.
+      #
+      # [name] String.
+      # [data] Array of [x, y] (Numeric, duck-typed via +to_f+).
+      # [style] Style.
+      # [marker] Symbol.
+      # [graph_type] Symbol.
+      def initialize(name:, data:, style: nil, marker: :dot, graph_type: :line)
+        coerced_data = data.map { |point| [Float(point[0]), Float(point[1])] }
+        super(name:, data: coerced_data, style:, marker:, graph_type:)
+      end
+    end
+
+    # Plots data points on a Cartesian coordinate system.
+    #
+    # Trends and patterns are invisible in raw logs. You need to see the shape of the data to understand the story it tells.
+    #
+    # This widget plots X/Y coordinates. It supports multiple datasets, custom axes, and different marker types.
+    #
+    # Use it for analytics, scientific data, or monitoring metrics over time.
+    #
+    # {rdoc-image:/doc/images/widget_chart_demo.png}[link:/examples/widget_chart_demo/app_rb.html]
+    #
+    # === Example
+    #
+    # Run the interactive demo from the terminal:
+    #
+    #   ruby examples/widget_chart_demo/app.rb
+    class Chart < Data.define(:datasets, :x_axis, :y_axis, :block, :style, :legend_position, :hidden_legend_constraints)
+      ##
+      # :attr_reader: datasets
+      # Array of Dataset objects to plot.
+
+      ##
+      # :attr_reader: x_axis
+      # Configuration for the X Axis.
+
+      ##
+      # :attr_reader: y_axis
+      # Configuration for the Y Axis.
+
+      ##
+      # :attr_reader: block
+      # Optional wrapping block.
+
+      ##
+      # :attr_reader: style
+      # Base style for the chart area.
+
+      ##
+      # :attr_reader: legend_position
+      # Position of the legend (<tt>:top_left</tt>, <tt>:top_right</tt>, <tt>:bottom_left</tt>, <tt>:bottom_right</tt>).
+
+      ##
+      # :attr_reader: hidden_legend_constraints
+      # Constraints for hiding the legend when the chart is too small (Array of [width, height]).
+
+      # Creates a new Chart widget.
+      #
+      # [datasets] Array of Datasets.
+      # [x_axis] X Axis config.
+      # [y_axis] Y Axis config.
+      # [block] Wrapper (optional).
+      # [style] Base style (optional).
+      # [legend_position] Symbol (<tt>:top_left</tt>, <tt>:top_right</tt>, <tt>:bottom_left</tt>, <tt>:bottom_right</tt>).
+      # [hidden_legend_constraints] Array of two Constraints [width, height] (optional).
+      def initialize(datasets:, x_axis:, y_axis:, block: nil, style: nil, legend_position: nil, hidden_legend_constraints: [])
+        super
+      end
+    end
+
+    # A complex chart widget. (Legacy/Alias for Chart)
+    #
+    # [datasets] Array of Dataset objects.
+    # [x_labels] Array of Strings for the X-axis labels.
+    # [y_labels] Array of Strings for the Y-axis labels.
+    # [y_bounds] Array of two Floats [min, max] for the Y-axis.
+    # [block] Optional block widget to wrap the chart.
+    class LineChart < Data.define(:datasets, :x_labels, :y_labels, :y_bounds, :block)
+      # Creates a new LineChart widget.
+      #
+      # [datasets] Array of Dataset objects.
+      # [x_labels] Array of Strings for the X-axis labels.
+      # [y_labels] Array of Strings for the Y-axis labels.
+      # [y_bounds] Array of two Floats [min, max] for the Y-axis.
+      # [block] Optional block widget to wrap the chart.
+      def initialize(datasets:, x_labels: [], y_labels: [], y_bounds: [0.0, 100.0], block: nil)
+        super(
+          datasets:,
+          x_labels:,
+          y_labels:,
+          y_bounds: [Float(y_bounds[0]), Float(y_bounds[1])],
+          block:
+        )
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/widgets/clear.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  module Widgets
+    # Resets the terminal buffer for a specific area.
+    #
+    # Painting in a terminal is additive. New content draws over old content. If the new content has transparency
+    # or empty spaces, the old content "bleeds" through. This ruins popups and modals.
+    #
+    # This widget wipes the slate clean. It resets all cells in its area to their default state (spaces with default background).
+    #
+    # Use it as the first layer in an Overlay stack when building popups. Ensure your floating windows are truly opaque.
+    #
+    # === Examples
+    #
+    #   # Opaque Popup Construction
+    #   Overlay.new(
+    #     layers: [
+    #       MainUI.new,
+    #       Center.new(
+    #         child: Overlay.new(
+    #           layers: [
+    #             Clear.new, # Wipe the area first
+    #             Block.new(title: "Modal", borders: [:all])
+    #           ]
+    #         ),
+    #         width_percent: 50,
+    #         height_percent: 50
+    #       )
+    #     ]
+    #   )
+    #
+    #   # Shortcut: rendering a block directly
+    #   Clear.new(block: Block.new(title: "Cleared area", borders: [:all]))
+    class Clear < Data.define(:block)
+      ##
+      # :attr_reader: block
+      # Optional Block to render after clearing.
+      #
+      # If provided, the borders/title of this block are drawn on top of the cleared area.
+
+      # Creates a new Clear widget.
+      #
+      # [block]
+      #   Block widget to render (optional).
+      def initialize(block: nil)
+        super
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/widgets/cursor.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-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
+    #
+    #   Cursor.new(x: 10, y: 5)
+    #
+    # 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)
+      ##
+      # :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,72 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-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_demo.png}[link:/examples/widget_gauge_demo/app_rb.html]
+    #
+    # === Example
+    #
+    # Run the interactive demo from the terminal:
+    #
+    #   ruby examples/widget_gauge_demo/app.rb
+    class Gauge < Data.define(:ratio, :label, :style, :gauge_style, :block, :use_unicode)
+      ##
+      # :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).
+      def initialize(ratio: nil, percent: nil, label: nil, style: nil, gauge_style: nil, block: nil, use_unicode: true)
+        if percent
+          ratio = Float(percent) / 100.0
+        end
+        ratio = Float(ratio || 0.0)
+        super(ratio:, label:, style:, gauge_style:, block:, use_unicode:)
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/widgets/line_gauge.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-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_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 (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).
+      # [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
+end

data/lib/ratatui_ruby/widgets/list.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-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_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.
+      #
+      # 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
+    end
+  end
+end

data/lib/ratatui_ruby/widgets/list_item.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  module Widgets
+    # 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
+end

data/lib/ratatui_ruby/widgets/overlay.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  module Widgets
+    # 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
+end