blockworx_editor/presentation/

mod.rs

//! How the document actually appears on the canvas: where wires run
//! (solved route geometry), how big text really is (measured extents),
//! what color pin stubs show (accents propagated from route roles).
//! Everything here is computed *from* the authored document and lives
//! *beside* it — never authored, never undone, never persisted.
//!
//! Owned by the app for the life of a session and threaded through
//! [`Drawing`](crate::widget::drawing::Drawing) like the spatial index,
//! mutably, because the passes that fill it run inside `Drawing` methods.
//! Each part is gated on the document's own stamp, so a commit that landed
//! anywhere — local, foreign, or an undo — re-derives it on the next
//! borrow and nothing has to remember to invalidate it. A live preview is
//! the one writer that does not follow the document: it *previews*
//! geometry and says so ([`Presentation::routes_previewed`]), which is what
//! takes an abandoned drag's preview back.

pub mod route;
pub mod store;

pub use route::{Crossing, LocAndDirection, RouteDirection, RouteEdge, RouteGeometry};

use ahash::HashMap;

use crate::render::text_box::BoxWidth;

use blockworx_doc::{
    block_model::Text,
    document::{IndexedDocument, chronological},
    geometry::GridSize,
    id::{PinId, RouteId, TextId},
    rev::DocStamp,
};

use crate::edit::lower::accent_from_role;
use crate::path::Scope;

/// Solved geometry per route. Flat rather than keyed by scope: route ids are
/// document-wide unique, so a scope key would distinguish nothing.
pub type RouteGeometries = HashMap<RouteId, RouteGeometry>;

#[derive(Default)]
pub struct Presentation {
    pub pin_accents: PinAccents,
    pub text_extents: TextExtents,
    /// A missing entry is a route that has not been reconstructed —
    /// nothing to draw or hit-test yet.
    pub routes: RouteGeometries,
    /// The document value [`Self::routes`] was reconstructed from.
    routes_stamp: Option<DocStamp>,
    /// Wires a preview drew geometry for that the document does not hold. The
    /// next borrow re-derives exactly these, and no others.
    previewed: std::collections::HashSet<RouteId>,
    /// The scope those previews happened in, since taking them back means
    /// reconstructing them where they live.
    previewed_in: Option<crate::path::BlockPath>,
}

impl Presentation {
    /// Forget the geometry of every wire `live` does not hold: a deleted
    /// wire has none.
    pub(crate) fn keep_routes(&mut self, live: impl Fn(RouteId) -> bool) {
        self.routes.retain(|&id, _| live(id));
    }

    /// Bring the accent propagation up to date with the document behind
    /// `indexed`. Gated on the document's stamp, so the once-per-borrow
    /// call sites stay cheap.
    pub fn refresh_accents(&mut self, indexed: &IndexedDocument<'_>) {
        if self.pin_accents.stamp == Some(indexed.doc.stamp()) {
            return;
        }
        self.pin_accents.recompute(indexed);
    }

    /// Rebuild every scope's wire geometry from the authored waypoints
    /// behind `indexed`. Gated on the document's stamp like
    /// [`Self::refresh_accents`], so a borrow that changed nothing costs a
    /// comparison — and a commit that landed anywhere, local or foreign,
    /// re-derives the wires without anyone asking.
    ///
    /// The stamp is claimed before the pass runs: the reconstruction builds
    /// its own scoped [`Drawing`](crate::widget::drawing::Drawing)s, whose
    /// constructor calls back in here.
    pub fn refresh_routes(&mut self, indexed: &IndexedDocument<'_>) {
        if self.routes_stamp == Some(indexed.doc.stamp()) {
            self.take_previews_back(indexed);
            return;
        }
        self.routes_stamp = Some(indexed.doc.stamp());
        self.previewed.clear();
        self.previewed_in = None;
        let _s = tracing::info_span!("present_document").entered();
        crate::widget::drawing::present_document(indexed, self);
    }

    /// Re-derive the wires a preview drew for, and only those. The document
    /// never moved — a preview supposes, it does not write — so every other
    /// wire is already showing what the document implies.
    fn take_previews_back(&mut self, indexed: &IndexedDocument<'_>) {
        if self.previewed.is_empty() {
            return;
        }
        let _s = tracing::info_span!("take_previews_back", routes = self.previewed.len()).entered();
        let taking_back = std::mem::take(&mut self.previewed);
        let Some(path) = self.previewed_in.take() else {
            return;
        };
        crate::widget::drawing::reconstruct_scope(
            indexed,
            self,
            &path,
            crate::widget::routing::Reconstructing::These(&taking_back),
        );
    }

    /// Bring the wires `disturbed` reaches up to date against `indexed`, and
    /// claim its stamp — what a commit does when it knows what it touched.
    ///
    /// The gate in [`Self::refresh_routes`] is all-or-nothing: a moved stamp
    /// re-derives every wire in the document. That is right for an open, an
    /// undo or a commit from elsewhere, and wrong for a nudge, which knows the
    /// rectangle it disturbed and leaves 7,549 wires drawn exactly as they
    /// were.
    ///
    /// Correctness rests on `disturbed` covering everything the commit wrote —
    /// the same superset rule the foreground is tested against
    /// (`a_move_writes_nothing_outside_the_foreground`).
    pub fn reconstruct_within(
        &mut self,
        indexed: &IndexedDocument<'_>,
        path: &crate::path::BlockPath,
        disturbed: blockworx_geom::Rect,
    ) {
        let _s = tracing::info_span!("reconstruct_within").entered();
        // Claimed before the pass runs, as [`Self::refresh_routes`] claims it:
        // the pass builds a `Drawing`, whose constructor calls back in here,
        // and a stamp still showing the old document would send it off to
        // re-derive every wire before this one re-derives a few.
        self.routes_stamp = Some(indexed.doc.stamp());
        let previewed = if self.previewed_in.as_ref() == Some(path) {
            self.previewed_in = None;
            std::mem::take(&mut self.previewed)
        } else {
            std::collections::HashSet::new()
        };
        crate::widget::drawing::reconstruct_scope(
            indexed,
            self,
            path,
            crate::widget::routing::Reconstructing::Within {
                disturbed,
                previewed: &previewed,
            },
        );
    }

    /// A throwaway presentation for a solve against a document that does not
    /// exist yet: the geometry the editor is showing, held as already
    /// reconstructed so the pass compares against what the user can see rather
    /// than re-deriving it. Measurement caches start empty — the solve reads
    /// neither.
    #[must_use]
    pub fn scratch(&self, indexed: &IndexedDocument<'_>) -> Self {
        Self {
            routes: self.routes.clone(),
            routes_stamp: Some(indexed.doc.stamp()),
            ..Self::default()
        }
    }

    /// A preview drew geometry the document does not hold for *these* wires,
    /// so the next borrow must take it back. Previews never move the document,
    /// hence never its stamp — this is how an abandoned drag's preview is
    /// undone.
    ///
    /// Named wire by wire rather than by dropping the stamp: a drag previews a
    /// handful and blanking the stamp had the next borrow re-derive the whole
    /// document, every frame.
    pub fn routes_previewed(
        &mut self,
        routes: impl IntoIterator<Item = RouteId>,
        in_scope: &crate::path::BlockPath,
    ) {
        self.previewed.extend(routes);
        self.previewed_in = Some(in_scope.clone());
    }
}

/// Route-role propagation onto pin stubs: a wire's accent colors the pins
/// it lands on. Derived fresh from the routes on every borrow — the last
/// route at a scope to touch a pin wins, including a plain (`None`) role —
/// so it cannot go stale the way a stored propagation would.
///
/// Keyed by the *scope* the coloring happened in, not the pin's owner: one
/// pin is drawn twice, as its own block's boundary port and as a stub on
/// that block seen from the parent, and each drawing takes the accent of
/// the wires in the scope it is drawn in.
#[derive(Default)]
pub struct PinAccents {
    stamp: Option<DocStamp>,
    accents: HashMap<(Scope, PinId), Option<u8>>,
}

impl PinAccents {
    /// The stub accent of `pin` as drawn in `scope`.
    pub fn pin(&self, scope: Scope, pin: PinId) -> Option<u8> {
        self.accents.get(&(scope, pin)).copied().flatten()
    }

    fn recompute(&mut self, indexed: &IndexedDocument<'_>) {
        let _s = tracing::info_span!("pin_accents").entered();
        self.accents.clear();
        for id in chronological(indexed.doc.routes()) {
            let Some(route) = indexed.doc.route(&id) else {
                continue;
            };
            let accent = accent_from_role(route.role);
            let scope = Scope::from_wire(route.owner);
            for endpoint in [route.from, route.to] {
                self.accents.insert((scope, endpoint), accent);
            }
        }
        self.stamp = Some(indexed.doc.stamp());
    }
}

/// Galley-measured text-box extents, keyed by the text and the width they
/// were measured for: an entry is consulted only while the box still holds
/// that text at that width, so the cache can never serve a stale rect —
/// undo, load, or restore leave it self-invalidated and readers fall back
/// to the character-count estimate until the box is next measured.
#[derive(Default)]
pub struct TextExtents {
    map: HashMap<TextId, (String, BoxWidth, GridSize)>,
}

impl TextExtents {
    pub fn set(&mut self, id: TextId, measured: &Text, size: GridSize) {
        self.map
            .insert(id, (measured.text.clone(), BoxWidth::of(measured), size));
    }

    /// The measured extent, if it was measured for exactly `current`'s text
    /// and width.
    pub fn valid_for(&self, id: TextId, current: &Text) -> Option<GridSize> {
        self.map
            .get(&id)
            .filter(|(text, width, _)| *text == current.text && *width == BoxWidth::of(current))
            .map(|&(_, _, size)| size)
    }
}

/// The accent lookup for the pins of one shape, resolved by a caller that
/// knows which scope the shape is being drawn in.
#[derive(Clone, Copy)]
pub struct ShapeAccents<'a> {
    scope: Scope,
    accents: &'a PinAccents,
}

impl<'a> ShapeAccents<'a> {
    pub fn new(scope: Scope, accents: &'a PinAccents) -> Self {
        Self { scope, accents }
    }

    pub fn pin(&self, pin: PinId) -> Option<u8> {
        self.accents.pin(self.scope, pin)
    }
}