blockworx/shell/

toast.rs

//! The toast: what needs *attention*, said once at the bottom of the frame
//! and never interactive.
//!
//! One surface, and one kind of news on it: a failure. What *worked* is not
//! here — the routine confirmations belong to the
//! [status line](super::status_line), because keeping the toast rare is what
//! keeps it noticeable. It stays capable of carrying an action button when an
//! attention event that has one arrives.
//!
//! It cannot be pressed and it carries no control, so it takes no room from
//! the canvas: it is not a [`Berth`](super::glass::Berth), and the safe area
//! never hears about it.

use crate::canvas::convert::IntoEgui as _;
use crate::{
    shell::glass::{self, Progress},
    theme::{Role, Theme},
};

/// Raise something that needs attention. Whatever was showing gives way — the
/// mockup's toast is one element with one timer, and the newest news is the
/// news.
///
/// Callable from a worker thread, which is where the file paths finish: an
/// [`egui::Context`] is shared, and this asks it for a repaint on the way
/// out.
pub fn say(ctx: &egui::Context, said: impl Into<String>) {
    let raised = ctx.input(|i| i.time);
    let said = Message {
        said: said.into(),
        raised,
    };
    ctx.data_mut(|data| data.insert_temp(id(), said));
    ctx.request_repaint();
}

/// Draw whatever is being said, wherever its motion has got to. Called every
/// frame; a frame with nothing to say draws nothing and asks for nothing.
pub fn toast(ctx: &egui::Context, theme: &Theme) {
    let Some(message) = ctx.data(|data| data.get_temp::<Message>(id())) else {
        return;
    };
    let elapsed =
        core::time::Duration::from_secs_f64((ctx.input(|i| i.time) - message.raised).max(0.0));
    let Some(motion) = Motion::at(elapsed) else {
        ctx.data_mut(|data| data.remove::<Message>(id()));
        return;
    };
    match motion.rest() {
        // Holding still costs nothing until it is time to go, which is what
        // lets an idle frame with a toast up still settle.
        Some(left) => ctx.request_repaint_after(left),
        None => ctx.request_repaint(),
    }
    let ink = theme.resolve(Role::ToastText).egui();
    egui::Area::new(id())
        .anchor(
            egui::Align2::CENTER_BOTTOM,
            egui::vec2(0.0, -STANDOFF + motion.offset()),
        )
        .order(egui::Order::Foreground)
        .movable(false)
        .fade_in(false)
        .constrain(false)
        // The mockup's `pointer-events:none`. The toast stands over the
        // drawing for two seconds and must not eat a click meant for it.
        .interactable(false)
        .show(ctx, |ui| {
            ui.set_opacity(motion.opacity());
            glass::shell(
                ui,
                glass::Shape::Toast,
                glass::Elevation::Floating,
                glass::Tint::None,
            )
            .fill(theme.resolve(Role::Toast).egui())
            .show(ui, |ui| {
                glass::type_scale(ui, glass::Shape::Toast);
                ui.label(egui::RichText::new(&message.said).color(ink));
            });
        });
}

/// What is being said, and when it started being said. Kept in egui's own
/// memory rather than in the editor: a toast is chrome that dies with the
/// frame it is on, and the paths that raise one — a dialog thread finishing
/// a write — have a context and no editor.
#[derive(Clone)]
struct Message {
    said: String,
    raised: f64,
}

/// What the toast is saying — for a test that drives a real file path and
/// asks what the user was told about it.
#[cfg(test)]
pub(crate) fn showing(ctx: &egui::Context) -> Option<String> {
    ctx.data(|data| data.get_temp::<Message>(id()))
        .map(|message| message.said)
}

fn id() -> egui::Id {
    egui::Id::new("shell_toast")
}

/// Where a toast is in its life: rising, holding, or going. It reaches an
/// end rather than a fixed point — nothing is left on screen — which is what
/// makes the absent case free.
#[derive(Clone, Copy, PartialEq, Debug)]
enum Motion {
    Rising(Progress),
    Holding(core::time::Duration),
    Leaving(Progress),
}

impl Motion {
    fn at(elapsed: core::time::Duration) -> Option<Self> {
        let through =
            |span: core::time::Duration| Progress::new(span.div_duration_f32(glass::TOAST_MOTION));
        if let Some(left) = DWELL.checked_sub(elapsed) {
            return Some(if elapsed < glass::TOAST_MOTION {
                Motion::Rising(through(elapsed))
            } else {
                Motion::Holding(left)
            });
        }
        let going = elapsed.checked_sub(DWELL)?;
        (going < glass::TOAST_MOTION).then(|| Motion::Leaving(through(going)))
    }

    /// How long until the next frame is owed, or `None` while the toast is
    /// moving and owes one immediately.
    fn rest(self) -> Option<core::time::Duration> {
        match self {
            Motion::Holding(left) => Some(left),
            Motion::Rising(_) | Motion::Leaving(_) => None,
        }
    }

    /// How far below its berth the toast is drawn — the mockup's
    /// `translateY(20px)`, run through the shell's one curve, so it
    /// overshoots coming up and again going down.
    fn offset(self) -> f32 {
        match self {
            Motion::Rising(through) => RISE * (1.0 - glass::spring(through)),
            Motion::Holding(_) => 0.0,
            Motion::Leaving(through) => RISE * glass::spring(through),
        }
    }

    /// The mockup fades the toast with the same transition it moves it by.
    fn opacity(self) -> f32 {
        match self {
            Motion::Rising(through) => glass::spring(through).clamp(0.0, 1.0),
            Motion::Holding(_) => 1.0,
            Motion::Leaving(through) => 1.0 - glass::spring(through).clamp(0.0, 1.0),
        }
    }
}

/// How long the toast holds before it leaves — the mockup's own
/// `setTimeout(…, 2400)`, measured from when it was raised.
const DWELL: core::time::Duration = core::time::Duration::from_millis(2400);

/// How far below its resting place the toast starts and ends — the mockup's
/// `translateY(20px)`.
const RISE: f32 = 20.0;

/// Where it rests: the mockup's `.toast{bottom:22px}`, which is its own
/// number rather than the frame's [`glass::MARGIN`] — the mockup stands the
/// toast a little further off the edge than the chips beside it, and it is
/// the piece that has to be read from wherever the eye happens to be.
const STANDOFF: f32 = 22.0;

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

    /// The three phases in order, and the end after them. A toast that never
    /// ended would be chrome the user cannot dismiss.
    #[test]
    fn a_toast_rises_holds_goes_and_is_over() {
        let at = |millis| Motion::at(core::time::Duration::from_millis(millis));
        assert!(matches!(at(0), Some(Motion::Rising(_))));
        assert!(matches!(at(200), Some(Motion::Rising(_))));
        assert!(matches!(at(1_000), Some(Motion::Holding(_))));
        assert!(matches!(at(2_500), Some(Motion::Leaving(_))));
        assert_eq!(at(2_651), None, "the toast outlived its own exit");
    }

    /// It comes up from below and goes back down the same way, and it is
    /// only ever whole in the middle.
    #[test]
    fn it_travels_the_mockups_twenty_pixels_and_fades_with_the_move() {
        let at = |millis| {
            Motion::at(core::time::Duration::from_millis(millis)).expect("the toast is up")
        };
        assert_eq!(
            at(0).offset(),
            RISE,
            "the toast does not start below where it rests",
        );
        assert_eq!(at(0).opacity(), 0.0);
        assert_eq!(at(1_000).offset(), 0.0);
        assert_eq!(at(1_000).opacity(), 1.0);
        assert!(
            at(2_600).offset() > 0.0,
            "the toast leaves upward, or not at all",
        );
        assert!(at(2_600).opacity() < 1.0);
        for millis in [0, 100, 200, 1_000, 2_450, 2_600] {
            let opacity = at(millis).opacity();
            assert!(
                (0.0..=1.0).contains(&opacity),
                "the spring's overshoot reached the fade at {millis}ms: {opacity}",
            );
        }
    }

    /// Only a moving toast owes an immediate frame; a holding one owes the
    /// frame it will leave on and nothing before it. This is what keeps the
    /// settle probe honest with a toast on screen.
    #[test]
    fn a_holding_toast_asks_for_one_frame_and_not_a_stream_of_them() {
        let at = |millis| {
            Motion::at(core::time::Duration::from_millis(millis)).expect("the toast is up")
        };
        assert_eq!(at(0).rest(), None, "a rising toast owes a frame now");
        assert_eq!(
            at(1_000).rest(),
            Some(core::time::Duration::from_millis(1_400)),
            "a holding toast asked for the wrong next frame",
        );
        assert_eq!(at(2_500).rest(), None);
    }

    /// Through real frames: the toast draws its words, then stops drawing
    /// them, and the frames after it is gone ask for nothing — a toast that
    /// pinned the repaint delay at zero would redraw the editor at full rate
    /// for as long as the app was open.
    #[test]
    fn a_said_toast_settles_after_it_has_been_said() {
        let mut said = false;
        let theme = Theme::default();
        let settle = crate::canvas::settle::probe(200, |ui| {
            if !said {
                say(ui.ctx(), "Could not export engine.pdf");
                said = true;
            }
            toast(ui.ctx(), &theme);
        });
        assert!(
            settle.shape_counts[..40].iter().any(|count| *count > 0),
            "the toast never drew: {:?}",
            &settle.shape_counts[..40],
        );
        assert_eq!(
            settle.shape_counts.last(),
            Some(&0),
            "the toast was still on screen three seconds later",
        );
        crate::canvas::settle::assert_settles(&settle, 190);
    }

    /// The newest news is the news: saying a second thing replaces the
    /// first rather than queueing behind it, exactly as the mockup's one
    /// element and one timer do.
    #[test]
    fn the_second_thing_said_is_what_shows() {
        let ctx = egui::Context::default();
        ctx.run_ui(egui::RawInput::default(), |ui| {
            say(ui.ctx(), "Could not export engine.pdf");
            say(ui.ctx(), "Could not save as engine");
        })
        .drop_without_applying_deltas();
        assert_eq!(showing(&ctx).as_deref(), Some("Could not save as engine"),);
    }
}