nordisk/facett

facett — for idiots (f0: zero to a picture on screen)

Class: idiot. Every step, nothing assumed. Goal: from a cold shell to a running window showing every facett component, then your own table drawn in ~10 lines. If you already know Rust, read guide.md instead. Each component has its own idiot walkthrough (*-for-idiots.md) linked at the end.

What facett is (one breath)

A box of reusable egui pictures. You hand one some data; it draws the picture — a graph, a table, a grid, a map, a pipeline, a chart, a 3D scene. Each is a tiny crate, each is a Facet you drop into any egui screen. They don't know or care where your data came from; they just render it.

What you need first

• A terminal (the black window where you type commands).
• Rust installed (if cargo --version prints a version, you're set; if not, install from https://rustup.rs).
• The facett repo on disk. In the terminal, type this and press Enter:

cd /run/media/rickard/T9/git/facett

Step 1 — see the whole library in one window

Type this and press Enter:

cargo run -p facett-demo

The first time it will compile for a while (normal). A window opens with a tab per component. Click the tabs — graph, grid, map, pipeline, charts, 3D — and try the theme switcher. That is the entire library, live. Close the window when done.

Step 2 — draw your own table in a tiny program

You don't need the demo to use facett. Any egui app can drop a component in. The three lines that matter:

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.push_row(vec!["Munin".into(),   "docked".into(), "0.0".into()]);
t.ui(ui);        // ← drop into any egui Ui. That is the whole render.

You get a striped, scrollable, click-to-select table with a row/column/selected counter. That t.ui(ui) line is the same shape for every component — a map, a graph, a chart: build it, hand it data, call .ui(ui).

Step 3 — change the whole look with one line

Put this once per frame (or whenever the look changes), where ctx is your egui::Context:

facett::set_theme(ctx, facett::LookTheme::default());

Every component — graphs, tables, progress bars — recolours together. No per-component wiring. The available palettes and the platform-adaptive layer are spelled out in theming-for-idiots.md.

Step 4 — check a component without opening a window

This is facett's trick: a component can be tested with no window at all.

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 something
assert_eq!(r.state["rows"], 1);    // the state matches the picture

Run your tests the usual way:

cargo test

Green test result: ok means the picture is correct — asserted without a display.

Where to go next

• Migrate/​write a component the Elm way: elm-for-idiots.md
• The flagship grid, 1M rows: grid-for-idiots.md
• A worked DAG viewer: pipeline-for-idiots.md
• Maps, 3D, graphs, charts, the demo: each family's *-for-idiots.md.
• Every component's API: design.md (the function map) and the per-function *-guide.md.