facett-graphview 0.1.12

//! The **domain-agnostic graph model** — the same shape nornir's
//! `src/viz/graph_render.rs::draw_graph` accepts, so this engine is a future
//! drop-in for that egui routine. Nodes are laid out in *world space* by the
//! caller (each domain owns its own layout/columns); edges reference nodes by
//! id. [`Decorations`] is the **caller-supplied** overlay — facett mustn't know
//! what a "release gate" is, so rings/badges/emphasis-edges are opaque here.
//!
//! Colours are a tiny POD [`Color`] (premultiply-free sRGBA8) with a `From`
//! conversion off egui's `Color32`, so a caller already speaking egui (exactly
//! nornir's `draw_graph`) maps straight across with zero glue.

use serde::{Deserialize, Serialize};

/// A straight sRGBA8 colour (NOT premultiplied). The render backends convert to
/// their own colour type at the seam.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct Color {
    pub r: u8,
    pub g: u8,
    pub b: u8,
    pub a: u8,
}

impl Color {
    pub const fn rgb(r: u8, g: u8, b: u8) -> Self {
        Self { r, g, b, a: 255 }
    }
    pub const fn rgba(r: u8, g: u8, b: u8, a: u8) -> Self {
        Self { r, g, b, a }
    }
    pub const TRANSPARENT: Color = Color::rgba(0, 0, 0, 0);
    pub const WHITE: Color = Color::rgb(255, 255, 255);
    pub const GRAY: Color = Color::rgb(128, 128, 128);

    /// Dim toward transparency (the off-trace fade — mirrors `graph_render::dim`).
    pub fn dim(self, k: f32) -> Color {
        Color::rgba(self.r, self.g, self.b, (self.a as f32 * k) as u8)
    }
}

impl From<egui::Color32> for Color {
    fn from(c: egui::Color32) -> Self {
        let [r, g, b, a] = c.to_srgba_unmultiplied();
        Color { r, g, b, a }
    }
}

impl From<Color> for egui::Color32 {
    fn from(c: Color) -> Self {
        egui::Color32::from_rgba_unmultiplied(c.r, c.g, c.b, c.a)
    }
}

/// A 2D point in world space (caller-owned layout coordinates).
#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
pub struct Pos {
    pub x: f32,
    pub y: f32,
}

impl Pos {
    pub const fn new(x: f32, y: f32) -> Self {
        Self { x, y }
    }
}

/// Default node chip size in world units (matches nornir's arch board:
/// `BOX_W`/`BOX_H`), before any pan/zoom transform.
pub const BOX_W: f32 = 184.0;
pub const BOX_H: f32 = 34.0;

/// One laid-out node: stable id, label, chip fill + stroke (the *kind* colour,
/// caller's choice), and its world-space centre.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct GraphNode {
    pub id: String,
    pub label: String,
    pub fill: Color,
    pub stroke: Color,
    pub pos: Pos,
}

/// One edge: endpoints by node id, colour, a `dashed` flag, and an optional
/// mid-edge label (a cut rationale).
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct GraphEdge {
    pub from: String,
    pub to: String,
    pub color: Color,
    pub dashed: bool,
    pub label: Option<String>,
}

/// The full graph to paint — nodes (laid out) + edges.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct GraphModel {
    pub nodes: Vec<GraphNode>,
    pub edges: Vec<GraphEdge>,
}

impl GraphModel {
    /// World-space bounding box of all node chips `(min_x, min_y, max_x, max_y)`,
    /// chip extents included. Used to fit the camera. `None` if empty.
    pub fn world_bounds(&self) -> Option<(f32, f32, f32, f32)> {
        let mut it = self.nodes.iter();
        let first = it.next()?;
        let (hw, hh) = (BOX_W * 0.5, BOX_H * 0.5);
        let mut b = (first.pos.x - hw, first.pos.y - hh, first.pos.x + hw, first.pos.y + hh);
        for n in it {
            b.0 = b.0.min(n.pos.x - hw);
            b.1 = b.1.min(n.pos.y - hh);
            b.2 = b.2.max(n.pos.x + hw);
            b.3 = b.3.max(n.pos.y + hh);
        }
        Some(b)
    }
}

/// A per-node decoration layered over the base chip: an optional status **ring**
/// colour (drawn outside the kind stroke), an optional **badge** (a short glyph/text
/// at the chip's top-right corner), and an optional **scale** — a multiplier on the
/// node's marker radius so a caller can size nodes by an importance metric
/// (population, degree, …) without the engine learning what the metric means. The
/// L0 lowering reads `scale` (default `1.0`) when it sizes the node marker.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct NodeDecoration {
    pub ring: Option<Color>,
    pub badge: Option<String>,
    pub badge_color: Option<Color>,
    /// Marker-radius multiplier (`None`/`1.0` = the default chip size). Domain-
    /// agnostic node sizing (e.g. kommun population, node degree).
    pub scale: Option<f32>,
}

/// The **caller-supplied** overlay layer (domain-agnostic). Per-node rings/badges
/// keyed by node id, plus extra emphasis edges painted on top (e.g. a cycle's
/// suggested cut). Empty = no overlay.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct Decorations {
    /// node id -> its ring/badge overlay.
    pub nodes: std::collections::HashMap<String, NodeDecoration>,
    /// Extra emphasis edges painted ON TOP of the base edges (the cut lines).
    pub edges: Vec<GraphEdge>,
}

/// The camera transform: pan + zoom over the world. World point `p` projects to
/// screen as `center + pan + p * zoom` (the same affine nornir's `draw_graph`
/// applies). Owned by the caller so navigation survives across frames.
#[derive(Clone, Copy, Debug)]
pub struct Camera {
    pub pan_x: f32,
    pub pan_y: f32,
    pub zoom: f32,
}

impl Default for Camera {
    fn default() -> Self {
        Self { pan_x: 0.0, pan_y: 0.0, zoom: 1.0 }
    }
}

impl Camera {
    /// A camera that fits `model`'s world bounds into a `w × h` viewport with a
    /// margin. The "⊙ fit" button, computed once instead of by trial pan/zoom.
    pub fn fit(model: &GraphModel, w: f32, h: f32, margin: f32) -> Camera {
        let Some((min_x, min_y, max_x, max_y)) = model.world_bounds() else {
            return Camera::default();
        };
        let (bw, bh) = ((max_x - min_x).max(1.0), (max_y - min_y).max(1.0));
        let zoom = ((w - 2.0 * margin) / bw).min((h - 2.0 * margin) / bh).clamp(0.05, 4.0);
        // Pan so the world-bounds centre lands at the viewport centre.
        let (cx, cy) = ((min_x + max_x) * 0.5, (min_y + max_y) * 0.5);
        Camera { pan_x: w * 0.5 - cx * zoom, pan_y: h * 0.5 - cy * zoom, zoom }
    }

    /// Project a world point to screen pixels.
    #[inline]
    pub fn project(&self, p: Pos) -> (f32, f32) {
        (p.x * self.zoom + self.pan_x, p.y * self.zoom + self.pan_y)
    }
}