class RatatuiRuby::Widgets::BarChart

Displays categorical data as bars.

Raw tables of numbers are hard to scan. Comparing magnitudes requires mental arithmetic, which slows down decision-making.

This widget visualizes the data. It renders vertical bars proportional to their value.

Use it to compare server loads, sales figures, or any discrete datasets.

Example

Run the interactive demo from the terminal:

ruby examples/widget_barchart/app.rb

# Grouped Bar Chart
BarChart.new(
  data: [
    BarGroup.new(label: "Q1", bars: [Bar.new(value: 40), Bar.new(value: 45)]),
    BarGroup.new(label: "Q2", bars: [Bar.new(value: 50), Bar.new(value: 55)])
  ],
  bar_width: 5,
  group_gap: 3
)

Constants

BAR_KEYS

:attr_reader: bar_set Custom characters for the bars (optional).

A Hash with keys defining the characters for the bars. Keys: :empty, :one_eighth, :one_quarter, :three_eighths, :half, :five_eighths, :three_quarters, :seven_eighths, :full.

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

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: [" ", " ", "▂", "▃", "▄", "▅", "▆", "▇", "█"]

Attributes

bar_gap [R]

Spaces between bars.

bar_width [R]

Width of each bar in characters.

block [R]

Optional wrapping block.

data [R]

The data to display.

Supports multiple formats:

Hash: Mapping labels (String or Symbol) to values (Integer).
Array of tuples: Ordered list of ["Label", Value] or ["Label", Value, Style] pairs.
Array of BarChart::BarGroup: List of BarChart::BarGroup objects for grouped charts.

Examples

Hash (Simple):

{ "Apples" => 10, :Oranges => 15 }

Array of Tuples (Ordered):

[["Mon", 20], ["Tue", 30], ["Wed", 25]]

BarGroup (Grouped):

[
  RatatuiRuby::BarChart::BarGroup.new(label: "Q1", bars: [
    RatatuiRuby::BarChart::Bar.new(value: 50, label: "Rev"),
    RatatuiRuby::BarChart::Bar.new(value: 30, label: "Cost")
  ])
]

group_gap [R]

Spaces between groups (for grouped bar charts).

label_style [R]

Style for the bar labels (optional).

max [R]

Maximum value for the Y-axis (optional).

If nil, it is calculated from the data.

style [R]

Style for the bars.

value_style [R]

Style for the bar values (optional).

Public Class Methods

new (data:, bar_width: 3, bar_gap: 1, group_gap: 0, max: nil, style: nil, block: nil, direction: :vertical, label_style: nil, value_style: nil, bar_set: nil)

Source

# File lib/ratatui_ruby/widgets/bar_chart.rb, line 219
def initialize(data:, bar_width: 3, bar_gap: 1, group_gap: 0, max: nil, style: nil, block: nil, direction: :vertical, label_style: nil, 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

  # Normalize data to Array of BarGroup
  data = if data.is_a?(Hash)
    if direction == :horizontal
      bars = data.map do |label, value|
        Bar.new(value:, label: label.to_s)
      end
      [BarGroup.new(label: "", bars:)]
    else
      data.map do |label, value|
        BarGroup.new(label: label.to_s, bars: [Bar.new(value:)])
      end
    end
  elsif data.is_a?(Array)
    if data.empty?
      []
    elsif data.first.is_a?(BarGroup)
      data
    elsif data.first.is_a?(Array)
      # Tuples - use type assertion for Steep
      if direction == :horizontal
        bars = data.map do |item|
          tuple = item #: Array[untyped]
          label = tuple[0].to_s
          value = tuple[1]
          style = tuple[2]

          bar = Bar.new(value:, label:)
          bar = bar.with(style:) if style
          bar
        end
        [BarGroup.new(label: "", bars:)]
      else
        data.map do |item|
          tuple = item #: Array[untyped]
          label = tuple[0].to_s
          value = tuple[1]
          style = tuple[2]

          bar = Bar.new(value:)
          bar = bar.with(style:) if style
          BarGroup.new(label:, bars: [bar])
        end
      end
    else
      # Fallback
      data
    end
  else
    data
  end

  super(
    data:,
    bar_width: Integer(bar_width),
    bar_gap: Integer(bar_gap),
    group_gap: Integer(group_gap),
    max: max.nil? ? nil : Integer(max),
    style:,
    block:,
    direction:,
    label_style:,
    value_style:,
    bar_set:
  )
end

Creates a new BarChart widget.

data: Data to display. Hash, Array of arrays, or Array of BarGroup.
bar_width: Width of each bar (Integer).
bar_gap: Gap between bars (Integer).
group_gap: Gap between groups (Integer).
max: Maximum value of the bar chart (Integer).
style: Base style for the widget (Style).
block: Block to render around the chart (Block).
direction: Direction of the bars (:vertical or :horizontal).
label_style: Style object for labels (optional).
value_style: Style object for values (optional).
bar_set: Symbol, Hash, or Array: Custom characters for bars. Symbols: :nine_levels (default gradient), :three_levels (simplified).

Calls superclass method