Class: RatatuiRuby::Widgets::Sparkline

Inherits:
Object
  • Object
show all
Includes:
CoerceableWidget
Defined in:
lib/ratatui_ruby/widgets/sparkline.rb

Overview

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.

Example

Run the interactive demo from the terminal:

ruby examples/widget_sparkline/app.rb

Constant Summary collapse

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

– 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 ++

%i[empty one_eighth one_quarter three_eighths half five_eighths three_quarters seven_eighths full].freeze

Instance Method Summary collapse

Methods included from CoerceableWidget

included

Constructor Details

#initialize(data:, max: nil, style: nil, block: nil, direction: :left_to_right, absent_value_symbol: nil, absent_value_style: nil, bar_set: nil) ⇒ Sparkline

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).



118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/ratatui_ruby/widgets/sparkline.rb', line 118

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