nordisk/facett

viewers — the graph-navigator / 3D-tube / lineage / Streamlit — for idiots

Class: idiot. Every step, nothing assumed. Goal: see a graph in a window, a 3D data-tube in a window, a lineage DAG in a window — and get a Streamlit component with one command. If you already know Rust, read viewers-guide.md instead; this one spells it out.

What you need first

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

cd /home/rickard/git/facett

• Rust installed (the cargo command exists). Type cargo --version and press Enter; if it prints a version, you are good.

The one thing to remember

Every facett viewer is a Facet: a thing with a ui(ui) method that paints itself, and a state_json() method that says in plain data exactly what it drew. To see one on screen you wrap it in a tiny eframe window. To test one you skip the window and read state_json(). That's the whole story.

Part 1 — see a graph, a tube, or a lineage DAG in a window

Step 1 — make a place for the program

We'll add a throwaway example inside the repo. Make the folder and file:

mkdir -p facett-demo/examples

Step 2 — the 15-line program

Open a new file facett-demo/examples/show.rs in your editor and paste this. It shows the graph navigator. (To show the tube or the lineage DAG instead, change the ONE marked line — see Step 4.)

use eframe::egui;
use facett_core::Facet;

// One Facet, held in a tiny window app.
struct Show(Box<dyn Facet>);

impl eframe::App for Show {
    fn ui(&mut self, ui: &mut egui::Ui, _frame: &mut eframe::Frame) {
        self.0.ui(ui);                       // the viewer paints itself
    }
}

fn main() -> eframe::Result<()> {
    let view: Box<dyn Facet> = Box::new(facett_graphnav::GraphNav::demo()); // ← the viewer
    eframe::run_native(
        "facett viewer",
        eframe::NativeOptions::default(),
        Box::new(|_cc| Ok(Box::new(Show(view)))),
    )
}

Step 3 — tell cargo the example exists

The example needs its viewer crates. Open facett-demo/Cargo.toml, find the [dev-dependencies] section (or add one at the bottom), and make sure these lines are there:

[dev-dependencies]
eframe = { version = "0.34", default-features = false, features = ["default_fonts", "glow"] }
facett-core = { path = "../facett-core" }
facett-graphnav = { path = "../facett-graphnav" }
facett-helix = { path = "../facett-helix" }
facett-lineage = { path = "../facett-lineage" }

Now run it:

cargo run -p facett-demo --example show

A window opens with the graph navigator: a query bar, a laid-out graph of people and companies, an inspector, a layout switcher, styling, search — the whole graph-DB IDE. Click a node. Type MATCH (n:Person) RETURN n in the query bar and hit run. Switch the layout to Radial.

Step 4 — swap in the tube or the lineage DAG

Change only the ← the viewer line in show.rs:

• A real 3D data-tube (data smeared on the pipe walls + a glowing data core down the middle, orbiting):

let view: Box<dyn Facet> = Box::new(facett_helix::TubeView::demo());

• A lineage DAG (datasets as boxes, data-processing runs as arrows — a Spark ingest flowing through clean/metrics into gold):

let view: Box<dyn Facet> = Box::new(facett_lineage::LineageView::demo());

Run cargo run -p facett-demo --example show again. Same window, different viewer.

Stuck at a black window? Make sure the features = [..., "glow"] part is on the eframe line — that's the software renderer that works everywhere.

Part 2 — turn a viewer into a Streamlit component (one command)

You want one of these viewers on a web page built with Streamlit (a Python dashboard tool). You do not write any JavaScript. Run this one command:

cargo xtask wrap-wasm && cargo xtask publish-pip

That builds the viewer to WebAssembly and packs it into a Python package called facet-wrapped (the wasm bundle) / facet-wrapped-web (the wheel). (Add --publish to also upload it to PyPI.) The command is pure Rust — no shell scripts, no hand steps. It even installs the WebAssembly toolchain for you if it's missing.

Then in your Python Streamlit app:

import streamlit as st
from facett_streamlit import facett_component, components

st.sidebar.write("Available:", [c["name"] for c in components()])
facett_component("graphnav", height=560)     # a live, clickable graph navigator

Change "graphnav" to any of the built-in names to embed a different viewer:

graphnav   helix-tube   lineage   stat-grid   console   timeline
table      log          matrix    tabbar      graphpan  plandag   security

The component is live — you can pan and click it right there in the Streamlit page, because it's the real egui viewer running on a canvas in the iframe, not a screenshot.

What you just learned

• Every facett viewer is a Facet; a 12-line eframe wrapper puts any of them in a window (view.ui(ui)).
• GraphNav::demo(), TubeView::demo(), LineageView::demo() are ready-made viewers with data already in them.
• cargo xtask wrap-wasm + cargo xtask publish-pip is the ONE command that turns them into an embeddable Streamlit component — pick the viewer by name from Python.
• To test a viewer without a window, call view.state_json() and read the plain data it returns — that's the same thing a robot or the Streamlit host reads.