Documentation
¶
Overview ¶
Package chart renders data as text: Sparkline, BarChart, LineChart, HeatMap and Gauge. Like widgets, each is a stateless function from its data and a theme to a string, with no Msg handling, and the package never imports tui or a stateful component. It is split from widgets because charts share one concern (turning numbers into marks) and one scaling convention (the slice's own min and max), where widgets holds the chrome around content (Badge, Box, Divider, ProgressBar, ChatMessage, ...).
Each chart also has a Linearize function (LinearizeSparkline, ...) returning a plain-text summary of its data for accessible output.
Stability: stable-ish.
Index ¶
- func BarChart(items []BarItem, width int, t theme.Theme) string
- func Gauge(percent float64, width int, t theme.Theme) string
- func HeatMap(values [][]float64, t theme.Theme) string
- func LineChart(values []float64, width, height int, t theme.Theme) string
- func LinearizeBarChart(items []BarItem) string
- func LinearizeGauge(percent float64) string
- func LinearizeHeatMap(values [][]float64) string
- func LinearizeLineChart(values []float64) string
- func LinearizeSparkline(values []float64) string
- func Sparkline(values []float64) string
- func SparklineWith(values []float64, t theme.Theme) string
- type BarItem
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BarChart ¶
BarChart renders items as one horizontal bar per row, width columns wide: the Label (left-aligned, padded to the widest label across all items so every bar starts at the same column, the same alignment convention as widgets.KeyValue) followed by a bar whose filled length is proportional to Value scaled against the dataset's max Value, the same min/max-scaling approach as Sparkline. If the max Value is <= 0 (all zero or negative), bars render zero-length rather than dividing by zero. An empty items slice renders as "".
func Gauge ¶
Gauge renders a semicircular meter width columns wide, filled from the left end of the arc clockwise to the right in proportion to percent (clamped to [0,1]; NaN counts as 0), with the rounded percentage centred under the arc. Like ProgressBar it is stateless: the caller passes the current value in on every render.
The arc is drawn with braille dots (2x4 per cell), which are close to square on a terminal grid, so the half-ring keeps its proportions. The filled part uses t.Primary, the remainder t.Muted, and the label t.Text. Every line is exactly width columns wide and the line count depends only on width, so the layout never shifts as the value changes. Below gaugeMinWidth columns there's no room for the arc, and Gauge returns a one-line ProgressBar instead.
func HeatMap ¶
HeatMap renders a 2D grid of values as one output row per row of values, with each cell replaced by a shading character from heatShades chosen by that value's position between the whole grid's own min and max (not a per-row min/max), the same normalization convention as Sparkline. A flat grid (min == max across every value) renders a uniform mid-level shade for every cell, matching Sparkline's flat-case convention. Rows may have different lengths; each renders using its own length. An empty grid (no rows, or every row with zero columns) renders "".
Denser cells (the top of the scale) are styled with t.Primary; the emptiest cells (level 0, a blank space) are left unstyled since color on a blank adds nothing.
func LineChart ¶
LineChart renders values as a line plotted on a width x height grid of character cells, using braille dots (2 sub-columns x 4 sub-rows per cell) for roughly double the horizontal and quadruple the vertical resolution of a plain block-character plot.
Each value maps to a point: its index spaces it evenly across the width*2 dot-columns (first value at column 0, last at the rightmost column), and its value is scaled between the slice's own min and max into the height*4 dot-rows, min at the bottom and max at the top — the same min/max scaling convention as Sparkline, including the flat case: when min == max the line renders straight across the vertical middle rather than collapsing to one edge.
Consecutive points are connected with a linearly interpolated line (stepped along whichever axis has more dots between the two points) so the series reads as a continuous line rather than isolated dots. A single value renders as one dot; zero values renders "".
Every returned line is at most width columns wide (measured with ansi.Width) and there are at most height lines, matching the requested grid regardless of how many values are plotted. The line is styled with t.Primary.
func LinearizeBarChart ¶
LinearizeBarChart summarises a BarChart's items as text: the item count and one "label value" entry per item in order, then the largest. Empty input returns "Bar chart: no data".
func LinearizeGauge ¶
LinearizeGauge summarises a Gauge's percent (a fraction, clamped to [0,1], NaN counting as 0) as text, for example "Gauge: 42 percent".
func LinearizeHeatMap ¶
LinearizeHeatMap summarises a HeatMap's grid as text: its row and column counts (columns being the longest row) and the min and max over all cells. An empty grid returns "Heat map: no data".
func LinearizeLineChart ¶
LinearizeLineChart summarises a LineChart's values as text, in the same form as LinearizeSparkline with the prefix "Line chart". Empty input returns "Line chart: no data".
func LinearizeSparkline ¶
LinearizeSparkline summarises a Sparkline's values as text: the count, min, max, average and last value, and whether the series rose, fell or stayed flat from first to last. Empty input returns "Sparkline: no data".
func Sparkline ¶
Sparkline renders values as a single line of block characters, scaled between the slice's own min and max. A flat slice (min == max, including a single value) renders at a uniform middle height rather than full height, since "no variance" and "at the max" are different things worth looking different. An empty slice renders as "".
Example ¶
package main
import (
"fmt"
"github.com/ows4444/tui/ansi"
"github.com/ows4444/tui/widgets/chart"
)
func main() {
fmt.Println(ansi.StripANSI(chart.Sparkline([]float64{1, 3, 2, 8, 5, 9, 4})))
}
Output: ▁▃▂▇▅█▄
Source Files