nordisk/facett

.nornir/for-idiots.md

# 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`](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:

```rust
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`:
```rust
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`](theming-guide.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**.
```rust
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`](elm-for-idiots.md)
- **The flagship grid, 1M rows:** [`grid-for-idiots.md`](grid-for-idiots.md)
- **A worked DAG viewer:** [`pipeline-for-idiots.md`](pipeline-for-idiots.md)
- **Maps, 3D, graphs, charts, the demo:** each family's `*-for-idiots.md`.
- **Every component's API:** [`design.md`](design.md) (the function map) and the per-function `*-guide.md`.