ratatui_ruby 1.4.0-x86_64-linux

data/lib/ratatui_ruby/widgets/sparkline.rb

@@ -0,0 +1,153 @@
+# 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 high-density data in a compact row.
+    #
+    # 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.png}[link:/examples/widget_sparkline/app_rb.html]
+    #
+    # === Example
+    #
+    # Run the interactive demo from the terminal:
+    #
+    #   ruby examples/widget_sparkline/app.rb
+    class Sparkline < Data.define(:data, :max, :style, :block, :direction, :absent_value_symbol, :absent_value_style, :bar_set)
+      include CoerceableWidget
+
+      ##
+      # :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
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   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: [" ", " ", "▂", "▃", "▄", "▅", "▆", "▇", "█"]
+      #--
+      # SPDX-SnippetEnd
+      #++
+
+      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 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] Symbol, Hash, or Array of custom characters (optional).
+      #   Symbols: <tt>:nine_levels</tt> (default gradient), <tt>:three_levels</tt> (simplified).
+      def initialize(data:, max: nil, style: nil, block: nil, direction: :left_to_right, absent_value_symbol: nil, absent_value_style: nil, bar_set: nil)
+        # Normalize bar_set to Hash[Symbol, String] if provided as Array or Hash
+        bar_set = case bar_set
+                  when Symbol, nil
+                    bar_set
+                  when Array
+                    # Convert Array to Hash using BAR_KEYS order
+                    BAR_KEYS.zip(bar_set).to_h
+                  when Hash
+                    # @type var raw_hash: Hash[untyped, untyped]
+                    raw_hash = bar_set.dup
+                    normalized = {} #: Hash[Symbol, String]
+                    # Normalize numeric keys (0-8) to symbolic keys
+                    BAR_KEYS.each_with_index do |key, i|
+                      val = raw_hash.delete(i) || raw_hash.delete(i.to_s) || raw_hash.delete(key)
+                      normalized[key] = val.to_s if val
+                    end
+                    normalized
+                  else
+                    bar_set
+        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
+end

data/lib/ratatui_ruby/widgets/table.rb

@@ -0,0 +1,213 @@
+# 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 structured data in rows and columns.
+    #
+    # Data is often multidimensional. You need to show relationships between fields (Name, Age, ID).
+    # Aligning columns manually in a monospaced environment is painful and error-prone.
+    #
+    # This widget creates a grid. It enforces column widths using constraints. It renders headers, rows, and footers aligned perfectly.
+    #
+    # Use it to display database records, logs, or file lists.
+    #
+    # {rdoc-image:/doc/images/widget_table.png}[link:/examples/widget_table/app_rb.html]
+    #
+    # === Example
+    #
+    # Run the interactive demo from the terminal:
+    #
+    #   ruby examples/widget_table/app.rb
+    class Table < Data.define(:header, :rows, :widths, :row_highlight_style, :highlight_symbol, :highlight_spacing, :column_highlight_style, :cell_highlight_style, :selected_row, :selected_column, :offset, :block, :footer, :flex, :style, :column_spacing)
+      include CoerceableWidget
+
+      ##
+      # Highlight spacing: always show the spacing column.
+      HIGHLIGHT_ALWAYS = :always
+      ##
+      # Highlight spacing: show spacing only when a row is selected (default).
+      HIGHLIGHT_WHEN_SELECTED = :when_selected
+      ##
+      # Highlight spacing: never show the spacing column.
+      HIGHLIGHT_NEVER = :never
+
+      ##
+      # Flex: use legacy column sizing.
+      FLEX_LEGACY = :legacy
+      ##
+      # Flex: align columns to start.
+      FLEX_START = :start
+      ##
+      # Flex: center columns.
+      FLEX_CENTER = :center
+      ##
+      # Flex: align columns to end.
+      FLEX_END = :end
+      ##
+      # Flex: space between columns.
+      FLEX_SPACE_BETWEEN = :space_between
+      ##
+      # Flex: space around columns.
+      FLEX_SPACE_AROUND = :space_around
+      ##
+      # Flex: space evenly between columns.
+      FLEX_SPACE_EVENLY = :space_evenly
+
+      ##
+      # :attr_reader: header
+      # Header row content (Array of Strings, Text::Spans, Text::Lines, or Paragraphs).
+
+      ##
+      # :attr_reader: rows
+      # Data rows (Array of Arrays). Each cell can be String, Text::Span, Text::Line, Paragraph, or Cell.
+
+      ##
+      # :attr_reader: widths
+      # Column width constraints (Array of Constraint or Integer).
+      # Integers are automatically coerced to Constraint.length.
+
+      ##
+      # :attr_reader: row_highlight_style
+      # Style for the selected row.
+
+      ##
+      # :attr_reader: highlight_symbol
+      # Symbol for the selected row.
+
+      ##
+      # :attr_reader: highlight_spacing
+      # When to show the highlight symbol column (<tt>:always</tt>, <tt>:when_selected</tt>, <tt>:never</tt>).
+
+      ##
+      # :attr_reader: column_highlight_style
+      # Style for the selected column.
+
+      ##
+      # :attr_reader: cell_highlight_style
+      # Style for the selected cell (intersection of row and column).
+
+      ##
+      # :attr_reader: selected_row
+      # Index of the selected row (Integer or nil).
+
+      ##
+      # :attr_reader: selected_column
+      # Index of the selected column (Integer or nil).
+
+      ##
+      # :attr_reader: offset
+      # Scroll offset (Integer or nil).
+      #
+      # Controls the viewport's starting row position in the table.
+      #
+      # When +nil+ (default), Ratatui auto-scrolls to keep the selection visible ("natural scrolling").
+      #
+      # When set, forces the viewport to start at this row index. Use this for:
+      # - **Passive scrolling**: Scroll through a log table without selecting rows.
+      # - **Click-to-select math**: Calculate which row index corresponds to a click coordinate.
+      #
+      # *Important*: When both +offset+ and +selected_row+ are set, Ratatui may still adjust
+      # the viewport during rendering to ensure the selection stays visible. Set +selected_row+
+      # to +nil+ for fully manual scroll control.
+
+      ##
+      # :attr_reader: block
+      # Optional wrapping block.
+
+      ##
+      # :attr_reader: footer
+      # Footer row content (Array of Strings, Text::Spans, Text::Lines, or Paragraphs).
+
+      ##
+      # :attr_reader: flex
+      # Flex mode for column distribution.
+
+      ##
+      # :attr_reader: style
+      # Base style for the entire table.
+
+      ##
+      # :attr_reader: column_spacing
+      # Spacing between columns (Integer, default 1).
+
+      # Creates a new Table.
+      #
+      # [header] Array of strings, Text::Spans, Text::Lines, or paragraphs.
+      # [rows] 2D Array where each cell is String, Text::Span, Text::Line, Paragraph, or Cell.
+      # [widths] Array of Constraints or Integers (integers coerce to Constraint.length).
+      # [row_highlight_style] Style object.
+      # [highlight_symbol] String.
+      # [highlight_spacing] Symbol (optional, default: <tt>:when_selected</tt>).
+      # [column_highlight_style] Style object.
+      # [cell_highlight_style] Style object.
+      # [selected_row] Integer (nullable).
+      # [selected_column] Integer (nullable).
+      # [offset] Numeric (nullable, coerced to Integer). Forces scroll position when set.
+      # [block] Block (optional).
+      # [footer] Array of strings/paragraphs (optional).
+      # [flex] Symbol (optional, default: <tt>:legacy</tt>).
+      # [style] Style object or Hash (optional).
+      # [column_spacing] Integer (optional, default: 1).
+      def initialize(header: nil, rows: [], widths: [], row_highlight_style: nil, highlight_symbol: "> ", highlight_spacing: :when_selected, column_highlight_style: nil, cell_highlight_style: nil, selected_row: nil, selected_column: nil, offset: nil, block: nil, footer: nil, flex: :legacy, style: nil, column_spacing: 1)
+        coerced_widths = widths.map do |w|
+          w.is_a?(Integer) ? Layout::Constraint.length(w) : w
+        end
+
+        super(
+          header:,
+          rows:,
+          widths: coerced_widths,
+          row_highlight_style:,
+          highlight_symbol:,
+          highlight_spacing:,
+          column_highlight_style:,
+          cell_highlight_style:,
+          selected_row: selected_row.nil? ? nil : Integer(selected_row),
+          selected_column: selected_column.nil? ? nil : Integer(selected_column),
+          offset: offset.nil? ? nil : Integer(offset),
+          block:,
+          footer:,
+          flex:,
+          style:,
+          column_spacing: Integer(column_spacing)
+        )
+      end
+
+      # Returns true if a row is selected.
+      #
+      # @return [Boolean]
+      def row_selected?
+        !selected_row.nil?
+      end
+
+      # Returns true if a column is selected.
+      #
+      # @return [Boolean]
+      def column_selected?
+        !selected_column.nil?
+      end
+
+      # Returns true if both a row and column are selected (a cell is selected).
+      #
+      # @return [Boolean]
+      def cell_selected?
+        row_selected? && column_selected?
+      end
+
+      # Returns true if the table has no rows.
+      #
+      # @return [Boolean]
+      def empty?
+        rows.empty?
+      end
+
+      # NOTE: No 'selection' alias - it's ambiguous whether it returns a row or index.
+      # Use selected_row for the row index, selected_column for the column index.
+    end
+  end
+end

data/lib/ratatui_ruby/widgets/tabs.rb

@@ -0,0 +1,91 @@
+# 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 tab bar for navigation.
+    #
+    # Screen real estate is limited. You cannot show everything at once. Segregating content into views is necessary for complex apps.
+    #
+    # This widget separates dimensions. It displays a row of titles, indicating which view is active.
+    #
+    # Use it at the top of your interface to switch between major modes or contexts.
+    #
+    # {rdoc-image:/doc/images/widget_tabs.png}[link:/examples/widget_tabs/app_rb.html]
+    #
+    # === Example
+    #
+    # Run the interactive demo from the terminal:
+    #
+    #   ruby examples/widget_tabs/app.rb
+    class Tabs < Data.define(:titles, :selected_index, :block, :divider, :highlight_style, :style, :padding_left, :padding_right)
+      include CoerceableWidget
+
+      ##
+      # :attr_reader: titles
+      # Tab titles (Array of Strings).
+
+      ##
+      # :attr_reader: selected_index
+      # Index of the active tab.
+
+      ##
+      # :attr_reader: block
+      # Optional wrapping block.
+
+      ##
+      # :attr_reader: divider
+      # Separator string between tabs.
+
+      ##
+      # :attr_reader: highlight_style
+      # Style for the selected tab title.
+
+      ##
+      # :attr_reader: style
+      # Base style for the tabs area.
+
+      ##
+      # :attr_reader: padding_left
+      # Left padding for the tabs area.
+      # Accepts Integer (number of spaces), String, or Line for styled content.
+
+      ##
+      # :attr_reader: padding_right
+      # Right padding for the tabs area.
+      # Accepts Integer (number of spaces), String, or Line for styled content.
+
+      # Creates a new Tabs widget.
+      #
+      # [titles] Array of Strings/Lines.
+      # [selected_index] Integer (default: 0).
+      # [block] Block (optional).
+      # [divider] String (optional).
+      # [highlight_style] Style (optional).
+      # [style] Style (optional).
+      # [padding_left] String, Line, or anything that responds to <tt>to_i</tt> (default: 0).
+      # [padding_right] String, Line, or anything that responds to <tt>to_i</tt> (default: 0).
+      def initialize(titles: [], selected_index: 0, block: nil, divider: nil, highlight_style: nil, style: nil, padding_left: 0, padding_right: 0)
+        super(
+          titles:,
+          selected_index: Integer(selected_index),
+          block:,
+          divider:,
+          highlight_style:,
+          style:,
+          padding_left: (padding_left.is_a?(Text::Line) || padding_left.is_a?(String)) ? padding_left : Integer(padding_left),
+          padding_right: (padding_right.is_a?(Text::Line) || padding_right.is_a?(String)) ? padding_right : Integer(padding_right)
+        )
+      end
+
+      # Returns the total width of the tabs.
+      def width
+        RatatuiRuby._tabs_width(self)
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/widgets.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  # Widget classes for building terminal UIs.
+  #
+  # This module mirrors +ratatui::widgets+ and contains all renderable
+  # widget types: Block, Paragraph, List, Table, Gauge, Chart, etc.
+  module Widgets
+  end
+end
+
+# Core widgets
+require_relative "widgets/coerceable_widget"
+require_relative "widgets/block"
+require_relative "widgets/paragraph"
+require_relative "widgets/list"
+require_relative "widgets/list_item"
+require_relative "widgets/table"
+require_relative "widgets/row"
+require_relative "widgets/cell"
+require_relative "widgets/tabs"
+require_relative "widgets/gauge"
+require_relative "widgets/line_gauge"
+require_relative "widgets/sparkline"
+require_relative "widgets/bar_chart"
+require_relative "widgets/bar_chart/bar"
+require_relative "widgets/bar_chart/bar_group"
+require_relative "widgets/chart"
+require_relative "widgets/scrollbar"
+require_relative "widgets/calendar"
+require_relative "widgets/canvas"
+require_relative "widgets/clear"
+require_relative "widgets/cursor"
+require_relative "widgets/overlay"
+require_relative "widgets/center"
+require_relative "widgets/ratatui_logo"
+require_relative "widgets/ratatui_mascot"
+require_relative "widgets/shape/label"