blockworx/shell/

mod.rs

//! The editor's frame: the three persistent regions of `docs/cad-ui-spec.md`
//! §2, mapped onto blockworx by `docs/cad-shell-playbook.md`.
//!
//! | Piece | Module | Berth | Elevation |
//! |---|---|---|---|
//! | top bar | [`top_bar`] | top, spanning | docked |
//! | tool rail | [`tool_cluster`] | left, centred | floating |
//! | navigator | [`navigator`] | right, full height | docked |
//! | status line | [`status_line`] | bottom left | bare |
//!
//! The canvas runs edge to edge under all of it, which is why [`insets`]
//! exists: nothing reflows the drawing surface, so fit-to-view has to inset
//! by the chrome's *measured* boxes or the model lands underneath it.
//! [`Chrome`] is the one place both halves happen — a piece cannot be drawn
//! without being measured.
//!
//! The [`toast`] is the exception, and is not in the table: it is transient,
//! it cannot be pressed, and it takes no room from the canvas — so it draws
//! itself rather than going through [`Chrome`], and the safe area never hears
//! about it.

pub mod glass;
pub mod insets;
pub mod navigator;
#[cfg(all(test, feature = "kittest"))]
pub(crate) mod picture;
pub mod status_line;
pub mod toast;
pub mod tool_cluster;
pub mod top_bar;
pub mod workspace;

pub use glass::Berth;
pub use insets::SafeArea;

/// One frame's chrome: where each visible piece landed, and therefore what
/// the canvas has left.
///
/// Built fresh each frame and thrown away with it. A piece that did not draw
/// contributes nothing, so the navigator opening or closing changes the region
/// in the frame it happens and there is no cache to invalidate.
pub struct Chrome {
    ctx: egui::Context,
    safe: SafeArea,
}

impl Chrome {
    /// Begin a frame's chrome over the canvas `viewport`.
    pub fn over(ctx: &egui::Context, viewport: egui::Rect) -> Self {
        Chrome {
            ctx: ctx.clone(),
            safe: SafeArea::over(viewport),
        }
    }

    /// Draw one piece in its berth, in the treatment its elevation calls for,
    /// and record the room it took from the canvas.
    pub fn piece<R>(&mut self, berth: Berth, add: impl FnOnce(&mut egui::Ui) -> R) -> R {
        self.shaped(berth, egui::Vec2::ZERO, glass::Tint::None, add)
    }

    /// One piece, `slide` away from where it settles and washed with `tint`.
    ///
    /// The canvas is inset by where a travelling piece *settles*, not by
    /// where it is this frame: fit-to-view reads the safe region every frame,
    /// so a region that travelled with the animation would set the drawing
    /// chasing it for the length of the motion.
    pub fn shaped<R>(
        &mut self,
        berth: Berth,
        slide: egui::Vec2,
        tint: glass::Tint,
        add: impl FnOnce(&mut egui::Ui) -> R,
    ) -> R {
        let shape = berth.shape();
        let elevation = berth.elevation();
        let area = glass::floating(berth, self.clearance(berth) + slide).show(&self.ctx, |ui| {
            glass::shell(ui, shape, elevation, tint)
                .show(ui, |ui| {
                    glass::type_scale(ui, shape);
                    match shape.content_height() {
                        // Every piece the mockup fixes a height for is one row of
                        // controls, so the row is opened here rather than by each
                        // piece: it stands the bar's full height from the first
                        // widget on, which is what centres a label placed before a
                        // taller button beside it.
                        Some(height) => {
                            ui.horizontal(|ui| {
                                ui.set_min_height(height);
                                add(ui)
                            })
                            .inner
                        }
                        None => add(ui),
                    }
                })
                .inner
        });
        self.safe
            .covered_by(berth.edge(), area.response.rect.translate(-slide));
        area.inner
    }

    /// The room a berth that hangs from what the chrome already measured
    /// takes — the navigator, whose top is the top bar's bottom. Every other
    /// berth hangs off its own corner and needs none.
    fn clearance(&self, berth: Berth) -> egui::Vec2 {
        if berth.clears_the_chrome_beside_it() {
            egui::vec2(0.0, self.safe.depth(insets::Edge::Top))
        } else {
            egui::Vec2::ZERO
        }
    }

    /// How tall a piece that runs the length of its edge may be: what the
    /// chrome already measured beside it has left. Read before drawing it, so
    /// the piece's own box is not in the answer.
    pub fn edge_span(&self) -> f32 {
        self.safe.viewport().height() - self.safe.depth(insets::Edge::Top)
    }

    /// What the canvas has left, for the framing that has to land inside it
    /// and the overlay that has to clamp into it.
    pub fn safe(&self) -> SafeArea {
        self.safe
    }

    /// The context the frame is drawing into — for the one piece that
    /// animates, which has to ask egui where its motion has got to.
    pub fn ctx(&self) -> &egui::Context {
        &self.ctx
    }
}

/// Where a piece landed last frame, as egui recorded it — for a test that
/// asks whether the chrome and the drawing can collide, and for the gesture
/// that has to know whether it ended on the glass.
pub fn berth_rect(ctx: &egui::Context, berth: Berth) -> Option<egui::Rect> {
    egui::AreaState::load(ctx, berth.id())
        .map(|state| state.rect())
        .filter(|rect| rect.is_positive())
}

/// Whether `at` lands on a piece of chrome rather than on the canvas under
/// it — what a gesture that began on the glass must ask before the document
/// hears about where it ended. The status line is not chrome for this
/// purpose: it answers no pointer, so the canvas under it is reachable.
pub fn over_the_chrome(ctx: &egui::Context, at: egui::Pos2) -> bool {
    Berth::ALL
        .into_iter()
        .filter(|berth| berth.elevation() != glass::Elevation::Bare)
        .any(|berth| berth_rect(ctx, berth).is_some_and(|rect| rect.contains(at)))
}

/// The glass drawn in the canvas's own layer, where it stood last frame —
/// the selection bar, the notices strip. egui's hit test gives a click there
/// to the control, but counts the canvas beneath as hovered while the button
/// is pressed and not once it is released, so the canvas would hear the
/// press and never the release. The canvas is told these before it takes
/// a press.
pub(crate) fn glass(ctx: &egui::Context) -> Vec<blockworx_geom::Rect> {
    [
        crate::panels::overlay::bar_rect(ctx),
        crate::panels::notices::strip_rect(ctx),
    ]
    .into_iter()
    .flatten()
    .map(crate::canvas::convert::IntoGeom::geom)
    .collect()
}

/// The one text style the frame sets numbers in: coordinates and zoom line up
/// column-wise only in a fixed pitch, and a proportional readout jitters as
/// the pointer moves.
pub(crate) fn mono(text: impl Into<String>) -> egui::RichText {
    egui::RichText::new(text).monospace().small()
}

#[cfg(test)]
pub(crate) mod tests {
    use super::*;

    /// A screen the whole frame lays out on comfortably.
    pub(crate) fn screen() -> egui::Rect {
        egui::Rect::from_min_size(egui::pos2(0.0, 0.0), egui::vec2(1000.0, 700.0))
    }

    /// Spec v3's frame is three regions and only three, plus the status line
    /// that is text rather than a region — one berth each, and one form each:
    /// the navigator has no second way of hanging.
    #[test]
    fn the_frame_has_a_place_for_every_piece_and_no_piece_two_places() {
        assert_eq!(
            Berth::ALL.len(),
            4,
            "§2's three regions and §2.0.1's status line",
        );
        let regions = Berth::ALL
            .into_iter()
            .filter(|berth| berth.elevation() != glass::Elevation::Bare)
            .count();
        assert_eq!(regions, 3, "spec §2's table lists exactly three regions");
    }
}