.nornir/guide.md · nordisk/facett

facett — guide (f0: a full session)

Class: guide · Function axis: this is f0 — the end-to-end workflow that spans functions. Each function's own how-to is its -guide.md (linked below). The what is design.md; the why is reasoning.md.

f0 — from a dependency to a tested multi-component app

The whole arc, once:

Depend on it. Add the umbrella crate (re-exports every component as a module), or just the crates you need:

[dependencies]
facett = { git = "https://codeberg.org/nordisk/facett" }
# …or one component:  facett-grid = { git = "…/facett" }

Render one component. Every component is a Facet, so it has .ui(ui):

use facett::table::Table;
let mut t = Table::new("vessels", vec!["name".into(), "status".into(), "knots".into()]);
t.push_row(vec!["Hugin".into(), "active".into(), "12.4".into()]);
t.ui(ui);                     // drop into any egui Ui — that's the whole render

Set the look once. One call on the egui context recolours every component together:

use facett::set_theme;
set_theme(ctx, facett::LookTheme::default());   // the Nordisk identity preset

Preset names + the platform-adaptive layer are in theming-guide.md.

Compose many. Box them into a FacetDeck for a tabbed app + free whole-app introspection — see facet-guide.md f4.
Assert headless. Drive any component with no window and check what it drew — see f-below and harness-guide.md.

Pick the component for your data

you have…	use the component	guide
an Arrow `RecordBatch` / a big typed table	grid (flagship)	`grid-guide.md`
an Iceberg table to browse + time-travel	dataview	`dataview-guide.md`
nodes + edges (dep graph, call graph, system map)	graph	`graph-guide.md`
lon/lat points or a scrollable geo map	map	`map-guide.md`
a 3D scene / glTF model	map3d	`map3d-guide.md`
animated directed flows / a central hub	flow (Falsett)	component guide
a dataflow / job DAG (Spark, SDP, …)	pipeline	`pipeline-guide.md`
series to chart, or a box/violin/heatmap	plot	`plot-guide.md`
a rendered manual to page through	docview	`docview-guide.md`
an app shell with nav + tabs	app	`app-guide.md`

See every component at once

cargo run  -p facett-demo     # one window, a tab per component, switch any theme live
cargo test -p facett-demo     # the self-check + snapshot

facett-demo is the gallery: every component fed from one deterministic fake "fleet" dataset, every palette live. It is also the live web demo (egui → WebAssembly). See app-guide.md.

Check it without a window (headless)

Every Facet renders headlessly and reports what it drew:

use facett::{harness, LookTheme};
let mut t = Table::new("etl", vec!["stage".into(), "rows".into()]);
t.push_row(vec!["bronze".into(), "1000".into()]);
let r = harness::render_themed(&mut t, LookTheme::default());
assert!(r.drew());                 // it actually painted
assert_eq!(r.state["rows"], 1);    // state mirrors the picture

render_themed returns a RenderReport (.drew(), .vertices, .state) whose .state mirrors what the user sees — a robot asserts the picture without a display. The full seam (driving Msg scripts, snapshotting the Model, the test-matrix) is harness-guide.md.