nordisk/facett

facett-plotters — mounting a line/bar/scatter chart (host guide)

Class: guide · What it's for: the how-to for a host that wants an everyday XY chart — line, bar, or scatter — over a set of named series, themeable and headless-drivable. The what is in design.md. You own the numbers; [ChartView] owns the axes, legend, tooltip, colours, and the switch between chart kinds.

1. Add the dependency

[dependencies]
facett-plotters = { path = "../facett-plotters", version = "0.1" }

No network, no nornir, no secrets pulled in.

2. Describe your data as series

use facett_plotters::{ChartView, ChartKind, Series};

let chart = ChartView::new("Revenue by region", vec![
    Series::new("north", vec![(0.0, 12.0), (1.0, 18.0), (2.0, 15.0)]),
    Series::new("south", vec![(0.0,  9.0), (1.0, 11.0), (2.0, 20.0)]),
]);

That is the whole input. Axis bounds, gridlines, the legend, and the tooltip are derived; series colours come from the theme's categorical palette in fixed order. Start on a specific kind with .with_kind(ChartKind::Bar) (default is Line).

3. Drop it in a FacetDeck (or paint it directly)

ChartView is a Facet, so it composes like any other:

use facett_core::FacetDeck;
let deck = FacetDeck::new(vec![Box::new(chart)]);
// deck.ui(ui) each frame; Ctrl-C copies the active chart's data as CSV.

Or paint one straight into a Ui with chart.ui(ui).

4. Switch the chart kind

Typed, from your own UI:

use facett_plotters::ChartMsg;
chart.update(ChartMsg::SetKind(ChartKind::Scatter));

…or headlessly over the JSON seam (the same path a robot/host driver uses):

use facett_core::Facet;
Facet::update_json(&mut chart, r#"{"set_kind":"bar"}"#);

5. Read what it drew (no GPU)

state_json reports the derived introspection — chart kind, series count, axis bounds, per-series point counts, and the current hover:

let j = facett_core::Facet::state_json(&chart);
assert_eq!(j["kind"], "bar");
assert_eq!(j["series_count"], 2);
// j["x_bounds"], j["y_bounds"] = [min, max]

This is exactly what the robot test asserts, so a headless host gets the same observability for free.

6. Theming & colour

Set the theme once on the context (facett_core::set_theme) and the chart follows: surface, axes, gridlines, and ink track the Theme, and series colour is taken from the theme-selected categorical set — a small validated palette in fixed slot order (dark themes get the dark steps, light themes the light steps of the same eight hues). You never pass a colour; identity is stable per slot.

Notes / limits

• Bar mode extends the y range to include the 0 baseline so bar heights are honest.
• Nine or more series cycle the eight-slot palette — for that many, prefer folding the tail into an "Other" series or small multiples (a dataviz house rule).
• The optional testmatrix feature turns the render-lane + robot self-reports into nornir warehouse rows; it is off by default and pulls no extra deps.