Sparkline

A sparkline: the run of a number in the room of a word, beside the number it belongs to. It has no axes, no legend and nothing to point at: it shows which way the number has gone, and a chart shows the rest.

import com.pantrixui.components.chart.sparkline.PantrixSparkline

• Values. The values are set out at even steps from the start of the line to its end. A line and an area are drawn between the least and the most of the values: the run fills the height it has. Bars are drawn from nought.
• Ends. min is the value at the foot of the height and max the one at its top: several runs read on one scale. A value past the ends is cut off at the box's edge. An end not given comes from the values and the reference line.
• Curve. curve says how a line and an area go from one value to the next (ChartCurve): straight, rounded without going past the values, or in steps. Bars have no curve.
• Last value. markLast = true marks the last value: a dot on a line and an area, and on bars the last bar in full colour and the others fainter. The last value is the last one that is a number.
• Reference line. reference draws a dashed line behind the values, in the colour charts write in: a target, or where the run began.
• Style. style goes over the theme's sizes: the line's width (lineWidth), the gap between bars (barGap), the last value's dot (markerSize) and the reference line's width (markLineWidth).
• Kind. SparklineKind.Line is a line, Area a line faintly filled under it, Bar a bar for each value.
• A missing value. A value that is null, or no number, is a gap in a line and an empty place among bars.
• Size and colour. It is 96dp wide and 32dp tall unless the modifier says otherwise; it is drawn in color, or else in the theme's first chart colour.
• Direction. In a language read from right to left the first value stands at the right.
• Export. export puts a button over the chart: the chart is made, as it is on the screen and without the part that is pointed at or its tooltip, into a PNG, an SVG or a PDF file and handed to the app.
• Automation. Sparkline_<tagKey>.

Examples

Beside a number

At its plainest: beside a number, the run of that number over the last twelve weeks. Since the number and its name are written beside it, the run has nothing more to say to a screen reader (contentDescription = null).

val strings = PantrixTheme.strings
Row(
    horizontalArrangement = Arrangement.spacedBy(PantrixTheme.spacing.lg),
    verticalAlignment = Alignment.CenterVertically
) {
    Column {
        PantrixText(text = "Visits", color = PantrixTheme.colors.textSecondary)
        PantrixText(text = strings.decimal(SPARK_VISITS.last()), style = PantrixTheme.typography.title)
    }
    PantrixSparkline(values = SPARK_VISITS, tagKey = "plain")
}

private val SPARK_VISITS = listOf(8200, 8650, 8400, 9100, 9800, 9300, 10400, 10100, 11200, 11800, 11500, 12480)

Line, area, bars

The same values in three kinds: a line, a line filled under it, and bars. Bars start at nought; a line at the least value.

Row(horizontalArrangement = Arrangement.spacedBy(PantrixTheme.spacing.lg)) {
    PantrixSparkline(values = SPARK_VISITS, contentDescription = "Visits, line", tagKey = "line")
    PantrixSparkline(
        values = SPARK_VISITS,
        kind = SparklineKind.Area,
        contentDescription = "Visits, area",
        tagKey = "area"
    )
    PantrixSparkline(
        values = SPARK_VISITS,
        kind = SparklineKind.Bar,
        contentDescription = "Visits, bars",
        tagKey = "bar"
    )
}

private val SPARK_VISITS = listOf(8200, 8650, 8400, 9100, 9800, 9300, 10400, 10100, 11200, 11800, 11500, 12480)

Missing values and under nought

The weeks with no measure (null) are a gap in the line; a single value with none before it and none after it is a dot. The bars of values under nought go down from nought.

Row(horizontalArrangement = Arrangement.spacedBy(PantrixTheme.spacing.lg)) {
    PantrixSparkline(values = SPARK_GAPS, contentDescription = "A measure with missing weeks", tagKey = "gaps")
    PantrixSparkline(
        values = SPARK_BALANCE,
        kind = SparklineKind.Bar,
        contentDescription = "Monthly profit and loss",
        tagKey = "balance"
    )
}

private val SPARK_GAPS = listOf(12, 15, 14, null, null, 18, 21, 19, null, 24)

private val SPARK_BALANCE = listOf(64, 31, -12, -38, 22, 47, 58, 87)

Your own size and colour

The modifier gives the size, color the colour: a rising run in the success colour, a falling one in the danger colour, in a wider room.

val colors = PantrixTheme.colors
Row(horizontalArrangement = Arrangement.spacedBy(PantrixTheme.spacing.lg)) {
    PantrixSparkline(
        values = SPARK_VISITS,
        modifier = Modifier.size(160.dp, 48.dp),
        kind = SparklineKind.Area,
        color = colors.success.color,
        contentDescription = "Rising visits",
        tagKey = "up"
    )
    PantrixSparkline(
        values = SPARK_VISITS.reversed(),
        modifier = Modifier.size(160.dp, 48.dp),
        kind = SparklineKind.Area,
        color = colors.danger.color,
        contentDescription = "Falling visits",
        tagKey = "down"
    )
}

private val SPARK_VISITS = listOf(8200, 8650, 8400, 9100, 9800, 9300, 10400, 10100, 11200, 11800, 11500, 12480)

Curve, last value and target

curve says how the line goes from one value to the next: Smooth rounds it without going past the values, StepAfter holds each value until the next. markLast = true marks the last value with a dot; on bars the last bar is drawn in full colour and the others fainter. reference draws a dashed line behind: here 20 degrees for the temperature, and the daily target for the orders.

Row(horizontalArrangement = Arrangement.spacedBy(PantrixTheme.spacing.lg)) {
    PantrixSparkline(
        values = SPARK_TEMPERATURE,
        contentDescription = "Today's temperature",
        tagKey = "smooth",
        curve = ChartCurve.Smooth,
        markLast = true,
        reference = 20
    )
    PantrixSparkline(
        values = SPARK_TEMPERATURE,
        contentDescription = "Today's temperature, in steps",
        tagKey = "steps",
        curve = ChartCurve.StepAfter,
        markLast = true
    )
    PantrixSparkline(
        values = SPARK_ORDERS,
        kind = SparklineKind.Bar,
        contentDescription = "This week's orders",
        tagKey = "orders",
        markLast = true,
        reference = 40
    )
}

private val SPARK_TEMPERATURE = listOf(12.5, 11.8, 13.2, 16.4, 19.8, 22.6, 24.1, 23.4, 21.0, 18.2, 16.9, 15.7)

private val SPARK_ORDERS = listOf(32, 45, 38, 51, 29, 47, 43)

A shared scale and your own style

min and max give the ends of the height: two servers' processor use on one scale, from nought to a hundred. One is barely working, the other is full; with no ends given each would stand between its own least and most value, and both would look as high. The dashed line in both is the warning threshold at eighty percent (reference). style makes the line thicker and the last value's dot larger.

val style = ChartStyle(lineWidth = 3.dp, markerSize = 10.dp)
val servers = listOf(Triple("Server A", SPARK_QUIET, "quiet"), Triple("Server B", SPARK_BUSY, "busy"))
Column(verticalArrangement = Arrangement.spacedBy(PantrixTheme.spacing.sm)) {
    servers.forEach { (name, load, key) ->
        Row(
            horizontalArrangement = Arrangement.spacedBy(PantrixTheme.spacing.md),
            verticalAlignment = Alignment.CenterVertically
        ) {
            PantrixText(text = name, modifier = Modifier.width(80.dp))
            PantrixSparkline(
                values = load,
                modifier = Modifier.size(160.dp, 40.dp),
                contentDescription = "$name, processor use",
                tagKey = key,
                style = style,
                markLast = true,
                reference = 80,
                min = 0,
                max = 100
            )
            PantrixText(text = PantrixTheme.strings.percent(load.last() / 100.0))
        }
    }
}

private val SPARK_QUIET = listOf(12, 18, 15, 22, 19, 14, 25, 21, 17, 23)

private val SPARK_BUSY = listOf(71, 78, 84, 80, 92, 88, 95, 99, 90, 86)

Export

export = ChartExport(...) puts an export button over the chart: press it and choose the kind (PNG, SVG or PDF). The chart makes the file and hands it to onExport; below, its name and size show, and a PNG's picture, and "Save the file" hands it over in the platform's way.

A small line is exported too: the button stands over the line, and the file is the line alone.

var file by remember { mutableStateOf<ChartExportFile?>(null) }
PantrixSparkline(
    values = SPARK_VISITS,
    contentDescription = "Visits of the last twelve days",
    tagKey = "exported",
    export = ChartExport(fileName = "visits") { file = it }
)
ExportedFile(file, tagKey = "exported")

private val SPARK_VISITS = listOf(8200, 8650, 8400, 9100, 9800, 9300, 10400, 10100, 11200, 11800, 11500, 12480)

API

values

A sparkline: the run of a number in the room of a word, beside the number it belongs to. It has no axes, no legend and nothing to point at: it shows which way the number has gone, and a chart shows the rest.

ChartStyle

A chart's geometry: how tall it is where nothing says, how thick its lines and how large its marks are, and the room between its parts; and whether its fills have textures besides their colours.

Accessibility

• Screen reader. With a contentDescription it is a picture of that name; with none it is not read at all: that suits a run beside a number that says the same.