makeover-immediate 0.3.0

//! The immediate-mode renderer for [`makeover_layout`].
//!
//! <!-- wiki: makeover-immediate -->
//!
//! Named for the mode, not the library, the way [`makeover-tui`] is named for
//! the target and not for ratatui. Immediate mode is the constraint that
//! actually separates this renderer from the other two, and egui is the
//! backend it is written against.
//!
//! It is the harshest renderer the description has to survive: no
//! `box-shadow`, no `inset`, no cascade, no retained tree to mutate, and
//! `Visuals.widgets.*.bg_stroke` is a single stroke with no per-side control.
//! A two-tone lit edge is not something egui can be configured into producing,
//! so it gets painted by hand here, once, instead of in every consuming app.
//!
//! # What this crate does and does not own
//!
//! It owns the *expression*: two mitred polylines for a bevel and a `Frame`
//! for a filled region. It owns no colours and no sizes, and no longer owns a
//! substitution: it briefly supplied the page for a well, which was a stand-in
//! for `surface-well` before makeover derived it, and every consumer reads the
//! real token now. [`Palette`] is supplied by the caller,
//! already resolved, and every radius, margin and stroke width arrives in
//! [`FrameStyle`].
//!
//! That split is why the crate has no dependency on `makeover` itself: the app
//! already resolves a theme, and coupling a renderer to a colour crate's
//! version would buy nothing.
//!
//! # The cascade is the real difference
//!
//! A stylesheet can say "a pressed button inverts its bevel" once and let the
//! cascade carry it. An immediate-mode renderer has nowhere to put that, so
//! every call site decides. [`makeover_layout::Depth::pressed`] is what keeps
//! the decision from being re-derived per widget.

#![forbid(unsafe_code)]

use egui::{Color32, CornerRadius, Margin, Painter, Rect, Shape, Stroke, Ui};
use makeover_layout::{Bevel, Depth, Edge, Fill};

/// The resolved colours this renderer needs, as flat values.
///
/// Built by the app from whatever it already uses to resolve a theme, then
/// held and reused. Deliberately not a trait and not string-keyed: a bevel is
/// painted per widget per frame, and a map lookup per edge is a cost with
/// nothing to show for it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Palette {
    /// `surface-page`.
    pub page: Color32,
    /// `surface-raised`.
    pub raised: Color32,
    /// `surface-overlay`.
    pub overlay: Color32,
    /// `surface-well`.
    ///
    /// Required, not optional. makeover derives it for every theme from 2.3.0,
    /// so a resolved palette without a well is not a thing that exists here.
    /// It was an `Option` while that was untrue, and this renderer substituted
    /// the page; `makeover-tui` keeps its own `Option` for a different reason,
    /// since a terminal can have the colour and still be unable to show it.
    pub well: Color32,
    /// `surface-sunken`.
    ///
    /// A surface set back from the one it sits on, by colour and nothing else.
    /// Not a well: a well is a hole with an edge, and this has no edge. An
    /// immediate-mode renderer paints an arbitrary rect, so unlike
    /// `makeover-tui` it has no excuse for declining this one.
    ///
    /// Required rather than optional, on the same footing as `well`: all 31
    /// themes makeover embeds author it.
    pub sunken: Color32,
    /// `bevel-light`.
    pub bevel_light: Color32,
    /// `bevel-dark`.
    pub bevel_dark: Color32,
}

impl Palette {
    /// Resolve a surface intent, or `None` for one this renderer does not know.
    ///
    /// A plain lookup. There is still no substitution: the old one existed only
    /// while `surface-well` was underived, and every consumer reads the real
    /// token now.
    ///
    /// `Option` since 0.3.0, because [`Fill`] became `#[non_exhaustive]` in
    /// `makeover-layout` 0.4.0 and a total function over an open enum can only
    /// stay total by inventing a colour for a member it has never heard of.
    /// That is the substitution this crate spent 0.2.0 removing, so the return
    /// type moved instead. Every member the description has today is answered
    /// with `Some`.
    #[must_use]
    pub const fn fill(&self, fill: Fill) -> Option<Color32> {
        match fill {
            Fill::Page => Some(self.page),
            Fill::Raised => Some(self.raised),
            Fill::Overlay => Some(self.overlay),
            Fill::Well => Some(self.well),
            Fill::Sunken => Some(self.sunken),
            _ => None,
        }
    }

    /// Resolve a bevel edge intent.
    #[must_use]
    pub const fn edge(&self, edge: Edge) -> Color32 {
        match edge {
            Edge::Light => self.bevel_light,
            Edge::Dark => self.bevel_dark,
        }
    }
}

/// The geometry a framed region is drawn with.
///
/// Every field is a value, which is why they all arrive from the caller:
/// radius and border width belong to `makeover-geometry`, and margins come
/// from its relational gaps.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct FrameStyle {
    /// Corner radius. Square under the Platinum default.
    pub radius: CornerRadius,
    /// Inner margin between the frame and its contents.
    pub margin: Margin,
    /// Bevel stroke width, in points.
    pub stroke: f32,
}

impl Default for FrameStyle {
    /// A one-point square frame with no inner margin.
    fn default() -> Self {
        Self {
            radius: CornerRadius::ZERO,
            margin: Margin::ZERO,
            stroke: 1.0,
        }
    }
}

/// Paint a two-tone edge just inside `rect`.
///
/// Fill first, bevel after: this adds two polylines and nothing else, so it
/// composes over whatever is already there. That is what lets it go over an
/// [`egui::TextEdit`] after `ui.add`, where the widget's own fill has landed.
///
/// Two three-point polylines meeting at opposite corners, rather than four
/// segments, so egui mitres the corner joins instead of leaving a notch.
pub fn paint_bevel(painter: &Painter, rect: Rect, bevel: Bevel, palette: &Palette, stroke: f32) {
    let (top_left, bottom_right) = bevel.edges();

    // Inset by half a stroke so the line lands inside `rect` rather than
    // straddling its edge, which on a fractional-scale display is the
    // difference between one crisp pixel and two dim ones.
    let r = rect.shrink(stroke / 2.0);

    painter.add(Shape::line(
        vec![r.left_bottom(), r.left_top(), r.right_top()],
        Stroke::new(stroke, palette.edge(top_left)),
    ));
    painter.add(Shape::line(
        vec![r.right_top(), r.right_bottom(), r.left_bottom()],
        Stroke::new(stroke, palette.edge(bottom_right)),
    ));
}

/// Draw a region at a given [`Depth`]: its fill and its edge, together.
///
/// [`Depth::Flat`] gets neither, and inherits whatever it sits on. That is the
/// difference between level-with and painted-the-same-colour, and it is the
/// reason `Depth::fill` returns an [`Option`] rather than defaulting to the
/// page.
pub fn frame<R>(
    ui: &mut Ui,
    depth: Depth,
    palette: &Palette,
    style: FrameStyle,
    add_contents: impl FnOnce(&mut Ui) -> R,
) -> R {
    let mut f = egui::Frame::new()
        .corner_radius(style.radius)
        .inner_margin(style.margin);
    // Two ways there is no fill to paint, and they collapse to the same
    // outcome: the depth names none (Depth::Flat), or it names one this
    // renderer cannot resolve. Either way the frame goes unfilled and the
    // bevel below carries the depth on its own, which is the rule this
    // module already documents for Flat.
    if let Some(fill) = depth.fill().and_then(|f| palette.fill(f)) {
        f = f.fill(fill);
    }
    let framed = f.show(ui, add_contents);
    if let Some(bevel) = depth.bevel() {
        paint_bevel(
            ui.painter(),
            framed.response.rect,
            bevel,
            palette,
            style.stroke,
        );
    }
    framed.inner
}

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

    fn palette(well: Color32) -> Palette {
        Palette {
            page: Color32::from_rgb(1, 1, 1),
            raised: Color32::from_rgb(2, 2, 2),
            overlay: Color32::from_rgb(3, 3, 3),
            well,
            sunken: Color32::from_rgb(4, 4, 4),
            bevel_light: Color32::WHITE,
            bevel_dark: Color32::BLACK,
        }
    }

    #[test]
    fn a_well_resolves_to_its_own_token() {
        // No substitution left. The page-filled well was a stand-in for a
        // token that did not exist yet; it exists now.
        let w = Color32::from_rgb(9, 9, 9);
        let p = palette(w);
        assert_eq!(p.fill(Fill::Well), Some(w));
        assert_ne!(p.fill(Fill::Well), Some(p.page));
    }

    #[test]
    fn every_intent_is_a_plain_lookup() {
        let p = palette(Color32::from_rgb(9, 9, 9));
        assert_eq!(p.fill(Fill::Page), Some(p.page));
        assert_eq!(p.fill(Fill::Raised), Some(p.raised));
        assert_eq!(p.fill(Fill::Overlay), Some(p.overlay));
    }

    /// Sunken is its own colour, not the well's and not the page's. The two
    /// are authored in opposite directions and an earlier cut of the
    /// description conflated them.
    #[test]
    fn sunken_is_neither_the_well_nor_the_page() {
        let p = palette(Color32::from_rgb(9, 9, 9));
        assert_eq!(p.fill(Fill::Sunken), Some(p.sunken));
        assert_ne!(p.fill(Fill::Sunken), p.fill(Fill::Well));
        assert_ne!(p.fill(Fill::Sunken), p.fill(Fill::Page));
    }

    #[test]
    fn a_raised_region_never_resolves_to_the_well_fill() {
        // The cross-app bug, asserted at the renderer boundary this time.
        let p = palette(Color32::from_rgb(9, 9, 9));
        let raised = Depth::Raised.fill().and_then(|f| p.fill(f));
        let well = Depth::Well.fill().and_then(|f| p.fill(f));
        assert_eq!(raised, Some(p.raised));
        assert_ne!(raised, well);
    }

    #[test]
    fn the_lit_edge_swaps_when_a_card_is_pressed() {
        let p = palette(Color32::from_rgb(9, 9, 9));
        let (tl, _) = Depth::Raised.bevel().unwrap().edges();
        let (ptl, _) = Depth::Raised.pressed().bevel().unwrap().edges();
        assert_eq!(p.edge(tl), p.bevel_light);
        assert_eq!(p.edge(ptl), p.bevel_dark);
    }

    #[test]
    fn flat_asks_for_neither_fill_nor_edge() {
        assert!(Depth::Flat.fill().is_none());
        assert!(Depth::Flat.bevel().is_none());
    }

    #[test]
    fn the_default_frame_is_square_and_one_point() {
        let d = FrameStyle::default();
        assert_eq!(d.radius, CornerRadius::ZERO);
        assert_eq!(d.margin, Margin::ZERO);
        assert!((d.stroke - 1.0).abs() < f32::EPSILON);
    }
}