.nornir/grid-for-idiots.md · nordisk/facett

facett-grid — for idiots

Class: idiot. Every step, nothing assumed. Goal: run the flagship grid demo, watch it hold a million Arrow rows at a smooth scroll, and try every headline feature with your own hands. If you already know Rust, read grid-guide.md instead.

Note before you start: facett-grid takes an in-memory Arrow RecordBatch, not a file path — there is no "open an .arrow file" button in this workspace. Every step below builds the data in Rust code, which is exactly how every real consumer of this grid feeds it.

What you need first

A terminal (the black window where you type commands).
The facett repo on disk. Type this and press Enter:

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

Step 1 — run the flagship demo

Type and press Enter:

cargo run -p facett-grid --example grid_demo

The first run compiles the workspace, which can take a couple of minutes. A window opens showing a grid of 50,000 vessels — grouped numbers, coloured "risk" cells (heat), an in-cell progress bar column, a tiny sparkline column, and a sticky totals row at the bottom. If nothing appears, read the red text in the terminal — it names the missing thing (usually a system graphics library) and stop here to fix it before continuing.

Step 2 — scroll it

Put your mouse over the grid and scroll. Notice it never stutters, no matter how fast you scroll or how far down the list you go — that's because only the rows currently on screen are ever painted (facett-grid/src/viewport.rs), not the whole 50,000.

Step 3 — sort it

Click a column header (try "risk"). The rows re-order and an arrow (▲ or ▼) appears in that header. Click it again — the arrow flips and the order reverses.

Now shift-click a different header ("region", say). It becomes a second sort key: rows are grouped by region first, then ordered by risk within each region. Both headers now show a small priority number next to their arrow.

Step 4 — select cells and copy

Click one cell — it highlights.
Hold Shift and click another cell — everything between them highlights as a rectangle.
Hold Ctrl and click a third, unrelated cell — it adds a second, disjoint selection.
Press Ctrl+A — the whole grid is selected.
Press Ctrl+C — the selection is copied as tab-separated text. Paste it into any text editor or spreadsheet to see the exact rows/columns you selected, with a header row.

Step 5 — see the type-aware cells

Look at the columns as you scroll:

id / speed_kn / risk — numbers are right-aligned with thousands commas.
region / class — repeating string values render as small tinted chips (facett auto-detects low-cardinality text columns and chips them, no config).
flagged — a boolean check/dash glyph, not the word "true"/"false".
last_seen — a plain YYYY-MM-DD date.
risk is additionally tinted (colour-scale heat: cooler = lower, warmer = higher).
scan shows a small filled bar in the cell (an in-cell progress bar).
trend shows a tiny sparkline per row.

Step 6 — scale it up to a million rows

Now change the demo's row count. Open /run/media/rickard/T9/git/facett/facett-grid/examples/grid_demo.rs in your editor and find this line near the top:

const ROWS: usize = 50_000;

Change 50_000 to 1_000_000 and save the file. Back in the terminal, run the demo again:

cargo run -p facett-grid --example grid_demo

Give it a little longer to build the 1,000,000-row Arrow batch and ingest it — then scroll. It should feel exactly as smooth as the 50k version: the grid never paints more than what's visible on your screen, whether the table has 50 thousand rows or a million. When you're done, you can change 1_000_000 back to 50_000 if you want the faster startup again.

Step 7 — see the proof, not just the vibe

The "stays fast at any size" claim is a machine-checked test, not just a feeling. Run it:

cargo test -p facett-grid --test perf

Green output means the test just measured that building the visible window for a 10-million-row grid takes about the same time as for a 10-thousand-row grid — the exact thing you felt when you scrolled the million-row demo.

Step 8 (optional) — try inline editing

Editing is off by default in the demo. To turn it on, open facett-grid/examples/grid_demo.rs, find the build_grid() function, and add .with_editable() to the builder chain, e.g.:

let mut g = Grid::from_record_batch(format!("{ROWS} vessels"), &demo_batch(ROWS))
    .pin_columns(2)
    .with_totals(true)
    .with_density(Density::Comfortable)
    .with_cond_fmt(5, CondFmt::ColorScale)
    .with_progress(6)
    .with_sparkline(7)
    .with_editable();   // <-- added

Save, then run the demo again (cargo run -p facett-grid --example grid_demo). Click a cell, then press Enter — a text box appears over the cell. Type a new value and press Enter again to commit it (or Escape to cancel without changing anything). Typing something that doesn't fit the column's type (letters into a number column, for example) tints the box red and refuses to commit until you fix it.

Step 9 — save your work

If you changed the example file and want to keep the change:

git add -A
git commit -m "facett-grid: tweak demo"
git push

If you were just exploring and want to discard your edits to the example file:

git checkout -- facett-grid/examples/grid_demo.rs

That's the whole tour: ingest, virtualize, sort, select, format, and (optionally) edit — the same six things grid-design.md documents and grid-guide.md shows you how to drive from code.