blockworx/shell/

glass.rs

//! The one look every piece of chrome is drawn in, and the berths they
//! hang from.
//!
//! Stated once so no two pieces can disagree about what the chrome is made
//! of: the fill, the elevation, the radii, the tap target, and — in the same
//! table — where each piece sits and which edge it takes room from. A
//! component that placed itself would be free to place itself somewhere the
//! [safe area](super::insets) does not know about.
//!
//! The **one elevation rule** — docked chrome is flat, square and unshadowed;
//! floating chrome is rounded and lifted — is [`Elevation`], read off the
//! berth. Both treatments come out of that one answer, which is what lets the
//! floating rail sit beside the docked bar without looking arbitrary.
//!
//! The mockup reaches its glass with `backdrop-filter: blur(24px)`, which has
//! no egui equivalent short of an offscreen pass. A see-through surface with
//! nothing blurring what is under it puts the grid through the words, so the
//! chrome is the theme's own solid surface, lifted and rounded by
//! [`Elevation`] alone.

use super::insets::Edge;

/// The smallest interactive target, on every platform.
pub const TAP: f32 = 44.0;

/// The tool cluster's cell — the mockup's `.tool`, 52 square, which with
/// [`PAD`] on either side is the 64px column the user measured off the
/// mockup. The icon carries the meaning alone and the tooltip carries
/// the words.
pub const TOOL: egui::Vec2 = egui::vec2(52.0, 52.0);

/// The icon in a tool cell.
pub const TOOL_ICON: f32 = 22.0;

/// A tool cell's corner, the one radius that is neither of the two above:
/// the allowed range is 13–20, and a cell this size reads square at 13.
pub const TOOL_RADIUS: u8 = 15;

/// How far every floating piece stands off the viewport's edge.
pub const MARGIN: f32 = 16.0;

/// The icon inside a tap target, 21px.
const TAP_ICON: f32 = 21.0;

/// The only two radii: the shell of a cluster, and the controls inside it.
const RADIUS_OUTER: u8 = 20;
const RADIUS_INNER: u8 = 13;

/// The air inside a piece, between its shell and its controls.
pub const PAD: i8 = 6;

/// The one motion the shell moves at. egui exposes no `prefers-reduced-motion`
/// signal on any of the five platforms, so honouring it is one setting the
/// toolkit does not have: what the shell can do is keep its whole vocabulary
/// to a single curve — [`spring`] — and the mockup's own durations: this one
/// for a control answering a press, and [`TRAVEL`] for a piece that comes in
/// from an edge.
pub const MOTION: std::time::Duration = std::time::Duration::from_millis(140);

/// How long a piece takes to come in from the edge it hangs off — the
/// mockup's `transition: transform .3s var(--spring)`, which it writes on the
/// navigator. Longer than [`MOTION`] because the distance is: a spring that
/// settles in 140ms over 340px reads as a jump.
pub const TRAVEL: std::time::Duration = std::time::Duration::from_millis(300);

/// How long the toast takes to rise and to go — the mockup's
/// `.toast{transition:all .25s var(--spring)}`. Between the other two,
/// because the distance is: it travels twenty pixels, not three hundred.
pub const TOAST_MOTION: std::time::Duration = std::time::Duration::from_millis(250);

/// How long the bar takes to change state — the mockup's
/// `.topbar{transition:background .25s ease}`, which is what carries the
/// amber in and out.
pub const TINT_MOTION: std::time::Duration = std::time::Duration::from_millis(250);

/// How far past its own edge a piece waits while it is away — the mockup's
/// `translateX(100%)` plus enough that its shadow is off screen with it.
const OFF_STAGE: f32 = 24.0;

/// How far a piece `extent` long has to travel to be wholly off the edge it
/// hangs from: its own size, the gap it stands off by, and enough more to
/// take its shadow too.
pub fn off_stage(extent: f32) -> f32 {
    extent + MARGIN + OFF_STAGE
}

/// Whether a piece is part of the frame or stands over it.
///
/// The one elevation rule: *docked chrome is flat with no shadow and square
/// corners; floating chrome has a shadow and large radii.* Written down once,
/// here, and read off the berth — so a piece cannot be given a place without
/// being given the treatment that place implies.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Elevation {
    /// The top bar and the navigator: flush with the edge they take, so they
    /// read as the frame rather than as objects on it.
    Docked,
    /// The tool rail, the selection bar, the toast: lifted off the canvas.
    Floating,
    /// Not a surface at all — the status line, which is ambient text and must
    /// not look like a control. It answers no pointer either.
    Bare,
}

/// What one piece of chrome is shaped like. The height is part of the shape:
/// a bar whose height came from what it happened to hold is a bar whose
/// height drifts.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Shape {
    /// The top bar: 54 tall, the whole width of the window.
    TopBar,
    /// The selection overlay — a tap target's height over the mockup's card
    /// corner, since it is a bar over the drawing rather than part of the
    /// frame.
    Bar,
    /// As tall as what it holds: the tool rail and the navigator.
    Panel,
    /// The toast: as tall as the one line in it, capped, and tighter than
    /// anything else the shell draws — the mockup's `.toast`, whose 10px of
    /// air is half a bar's, because nothing on it can be pressed.
    Toast,
    /// The status line: one line of plain text with no container at all.
    StatusLine,
}

/// The mockup's `--bar-h`, the one number the docked bar and everything
/// measured against it read.
pub const TOP_BAR_HEIGHT: f32 = 54.0;

/// The floating bar tier's height, the mockup's `.overlay` row of 44px
/// targets in 5px of air.
pub const BAR_HEIGHT: f32 = 52.0;

impl Shape {
    /// How tall the piece stands, where the mockup fixes it. A `Panel` is as
    /// tall as its contents and so answers `None`.
    fn height(self) -> Option<f32> {
        match self {
            Shape::TopBar => Some(TOP_BAR_HEIGHT),
            Shape::Bar => Some(BAR_HEIGHT),
            Shape::Panel | Shape::Toast | Shape::StatusLine => None,
        }
    }

    /// The shell's corner, for the pieces that have one. A docked piece is
    /// square whatever this says, because that is the elevation rule.
    fn radius(self) -> u8 {
        match self {
            Shape::TopBar | Shape::StatusLine => 0,
            Shape::Bar => RADIUS_CARD,
            Shape::Panel => RADIUS_OUTER,
            // The mockup's `border-radius:22px` over a line of 13px text:
            // more than half the height it comes out at, so it caps.
            Shape::Toast => TOAST_RADIUS,
        }
    }

    /// The air between the shell and what it holds. For the tiers that hold
    /// targets the vertical half is not written down — it is whatever centres
    /// a tap target in the height above, so those shells can never be shorter
    /// than the buttons inside them.
    pub fn margin(self) -> egui::Margin {
        let (sides, vertical) = match self {
            // The mockup's `.topbar{padding:0 10px 0 12px}`, evened out: the
            // bar's two ends carry the same runs of tap targets.
            Shape::TopBar => (BAR_SIDES, (TOP_BAR_HEIGHT - TAP) * 0.5),
            Shape::Bar => (BAR_SIDES, (BAR_HEIGHT - TAP) * 0.5),
            Shape::Panel => (f32::from(PAD), f32::from(PAD)),
            // The mockup's `padding:10px 18px`.
            Shape::Toast => (TOAST_SIDES, TOAST_AIR),
            Shape::StatusLine => (0.0, 0.0),
        };
        egui::Margin {
            left: sides as i8,
            right: sides as i8,
            top: vertical as i8,
            bottom: vertical as i8,
        }
    }

    /// How tall the shell's contents must stand for the piece to reach its
    /// own height.
    pub fn content_height(self) -> Option<f32> {
        self.height()
            .map(|height| height - 2.0 * f32::from(self.margin().top))
    }

    /// How big this tier sets its words, in the mockup's own points.
    ///
    /// One body size, 14px, is named for the whole shell. The mockup refines
    /// it per tier and the user read the refinement off it — *"I see 14px on
    /// the document title and 12.5 on the bottom pills. That seems like a
    /// better split than we currently have in the app."* — which it is:
    /// egui's stock scale sets everything at 12.5 with 9pt asides.
    fn type_scale(self) -> [(egui::TextStyle, f32); 4] {
        let (body, button, small, mono) = match self {
            // `.crumb` 14.5, `.mode` 13.5, `.tip` 12.5.
            Shape::TopBar => (14.5, 13.5, 12.5, 12.5),
            // `.overlay .none` 13, `.overlay .selcount` 12.5.
            Shape::Bar => (13.0, 13.5, 12.5, 12.5),
            // `.row .t1` 14, `.row .t2`/`.t3`/`.daylbl` 12, `.seg button` 13.5.
            Shape::Panel => (14.0, 13.5, 12.0, 12.0),
            // `.toast{font-size:13px}`, one line and nothing else.
            Shape::Toast => (13.0, 13.0, 13.0, 13.0),
            // `.status{font-size:12.5px}`, likewise.
            Shape::StatusLine => (12.5, 12.5, 12.5, 12.5),
        };
        [
            (egui::TextStyle::Body, body),
            (egui::TextStyle::Button, button),
            (egui::TextStyle::Small, small),
            (egui::TextStyle::Monospace, mono),
        ]
    }
}

/// Set the type scale a shell's words are drawn in. One call per piece rather
/// than a size on every `RichText`, so the tier is the thing that carries the
/// size and no widget can wander off it.
pub fn type_scale(ui: &mut egui::Ui, shape: Shape) {
    let style = ui.style_mut();
    for (text_style, points) in shape.type_scale() {
        if let Some(font) = style.text_styles.get_mut(&text_style) {
            font.size = points;
        }
    }
}

/// The mockup's `--r-md`, the corner on a card that stands over the drawing.
const RADIUS_CARD: u8 = 14;
/// A bar's ends, the mockup's `.overlay{padding:5px}`.
const BAR_SIDES: f32 = 5.0;
/// The toast's, the mockup's `.toast{padding:10px 18px;border-radius:22px}`.
const TOAST_SIDES: f32 = 18.0;
const TOAST_AIR: f32 = 10.0;
const TOAST_RADIUS: u8 = 22;

/// Where one piece of chrome hangs, the edge it takes room from, and how it
/// is lifted.
///
/// One table, because the answers must agree: a piece placed by an anchor the
/// safe area does not know about would land the model underneath it. The edge
/// is not derivable from the anchor — the top bar spans the window and the
/// navigator hangs off the same corner it starts from — so all three are
/// written down.
///
/// The three persistent regions, plus the status line, which is text rather
/// than a region.
#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
pub enum Berth {
    TopBar,
    ToolCluster,
    Navigator,
    StatusLine,
}

impl Berth {
    /// Every berth, for a test that ranges over the frame.
    pub const ALL: [Berth; 4] = [
        Berth::TopBar,
        Berth::ToolCluster,
        Berth::Navigator,
        Berth::StatusLine,
    ];

    fn align(self) -> egui::Align2 {
        match self {
            Berth::TopBar => egui::Align2::LEFT_TOP,
            Berth::ToolCluster => egui::Align2::LEFT_CENTER,
            Berth::Navigator => egui::Align2::RIGHT_TOP,
            Berth::StatusLine => egui::Align2::LEFT_BOTTOM,
        }
    }

    /// What this piece is shaped like — in the same table as where it hangs,
    /// so a berth cannot be given a place without being given a height.
    pub fn shape(self) -> Shape {
        match self {
            Berth::TopBar => Shape::TopBar,
            Berth::ToolCluster | Berth::Navigator => Shape::Panel,
            Berth::StatusLine => Shape::StatusLine,
        }
    }

    /// How this piece is lifted off the canvas, by the elevation rule.
    pub fn elevation(self) -> Elevation {
        match self {
            Berth::TopBar | Berth::Navigator => Elevation::Docked,
            Berth::ToolCluster => Elevation::Floating,
            Berth::StatusLine => Elevation::Bare,
        }
    }

    /// Which edge of the canvas this piece takes room from.
    pub fn edge(self) -> Edge {
        match self {
            Berth::TopBar => Edge::Top,
            Berth::ToolCluster => Edge::Left,
            Berth::Navigator => Edge::Right,
            Berth::StatusLine => Edge::Bottom,
        }
    }

    /// The egui id the piece's [`egui::Area`] is registered under, so a test
    /// can ask where it landed.
    pub fn id(self) -> egui::Id {
        egui::Id::new(("shell_berth", self))
    }

    /// Whether this piece hangs from the room the chrome measured before it
    /// left, rather than from the raw edge — the navigator, which starts
    /// under the top bar and runs to the bottom of the window.
    pub fn clears_the_chrome_beside_it(self) -> bool {
        matches!(self, Berth::Navigator)
    }

    /// The gap between the piece and the edge it hangs off. A docked piece
    /// keeps none: it is not standing over the canvas, it is the end of it.
    fn offset(self) -> egui::Vec2 {
        match self {
            Berth::TopBar | Berth::Navigator => egui::Vec2::ZERO,
            // The mockup centres the rail on the canvas rather than on the
            // window: `top: calc(50% + var(--bar-h)/2)`.
            Berth::ToolCluster => egui::vec2(MARGIN, TOP_BAR_HEIGHT * 0.5),
            Berth::StatusLine => egui::vec2(STATUS_INDENT, -STATUS_STANDOFF),
        }
    }
}

/// The mockup's `.status{left:88px}` — clear of the tool rail's column, which
/// is [`MARGIN`] plus the cell and its air.
const STATUS_INDENT: f32 = MARGIN + TOOL.x + 2.0 * PAD as f32 + 8.0;
/// The mockup's `.status{bottom:18px}`.
const STATUS_STANDOFF: f32 = 18.0;

/// The [`egui::Area`] a piece is drawn in: anchored to its berth, held still,
/// and above the canvas without being a window. `clear_of` is the extra room
/// a berth that hangs from what the chrome left takes; every other berth
/// passes zero.
pub fn floating(berth: Berth, clear_of: egui::Vec2) -> egui::Area {
    egui::Area::new(berth.id())
        .anchor(berth.align(), berth.offset() + clear_of)
        // Chrome the user can drag out of its berth is chrome the safe area
        // cannot reason about, and one layout on five platforms is not one
        // the user rearranges.
        .movable(false)
        // The fade egui gives a new area is motion the chrome has no reason
        // for, and it repaints until it finishes — which no idle frame should.
        .fade_in(false)
        // egui holds an area inside the screen by default, which for a piece
        // that travels off its own edge means it cannot leave: the clamp puts
        // it back the moment the slide pushes it out. Every berth is anchored
        // and none is movable, so the constraint has nothing else to do here.
        .constrain(false)
        // Ambient information is not a control, so it takes no pointer — and
        // the readout under the cursor is not given up for it.
        .interactable(berth.elevation() != Elevation::Bare)
}

/// A wash of colour over a piece's own fill — the amber the top bar takes on
/// while the lens is open, rather than raising a second object.
#[derive(Clone, Copy, PartialEq, Debug)]
pub enum Tint {
    None,
    Over(egui::Color32),
}

impl Tint {
    fn over(self, fill: egui::Color32) -> egui::Color32 {
        match self {
            Tint::None => fill,
            Tint::Over(wash) => fill.blend(wash),
        }
    }
}

/// The shell of one piece, in the treatment its elevation calls for: docked
/// chrome flat and square, floating chrome rounded and lifted, and ambient
/// text neither. No hairlines anywhere, so nothing is outlined.
pub fn shell(ui: &egui::Ui, shape: Shape, elevation: Elevation, tint: Tint) -> egui::Frame {
    let visuals = ui.visuals();
    let frame = egui::Frame::new().inner_margin(shape.margin());
    let glass = tint.over(visuals.window_fill);
    match elevation {
        Elevation::Bare => frame,
        Elevation::Docked => frame.fill(glass),
        Elevation::Floating => frame
            .fill(glass)
            .corner_radius(shape.radius())
            .shadow(lift(visuals)),
    }
}

/// How far a floating piece stands off the canvas, and how softly.
///
/// The user, on the frame egui's own window shadow gave it: *"The drop
/// shadows behind the floating pills/bars are too big and too far away from
/// the objects."* egui's default falls sideways and lands hard; the mockup's
/// `--shadow` falls straight down and diffuses, which is what reads as glass
/// lifted rather than as a second object underneath. The ink is the theme's,
/// so a scheme change reaches it; only the geometry and the weight are the
/// mockup's.
fn lift(visuals: &egui::Visuals) -> egui::Shadow {
    let ink = visuals.window_shadow.color;
    let carried = f32::from(ink.a()) / 255.0;
    egui::Shadow {
        offset: SHADOW_OFFSET,
        blur: SHADOW_BLUR,
        spread: 0,
        color: ink.gamma_multiply(SHADOW_ALPHA / carried.max(f32::EPSILON)),
    }
}

/// The mockup's `--shadow: 0 10px 34px rgba(15,25,40,.15)` — its second,
/// tighter layer is not reproduced, because one `egui::Shadow` is one layer
/// and the wide one is the one that carries the lift.
const SHADOW_OFFSET: [i8; 2] = [0, 10];
const SHADOW_BLUR: u8 = 34;
const SHADOW_ALPHA: f32 = 0.15;

/// A rule between two runs of controls in one piece — the mockup's
/// `.divider` across a row, `.toolsep` down a column.
///
/// These are the shell's only hairlines. Hairlines are forbidden
/// categorically, but the user asked for both of these by name —
/// *"There is a separator between the undo/redo and the two view controls."*
/// and *"Put a horizontal separator between the selection tool and the
/// modelling tools in the main toolbar."* — so the ban is read as *no
/// incidental hairlines*: a rule the user asked for is structure, and the
/// two places they asked for one are the only two.
///
/// A row's rule is short and unindented; a column's spans the cluster inset
/// from both shoulders. That is the mockup's own difference between the two,
/// stated here so the two clusters cannot part company over tone.
pub fn separator(ui: &mut egui::Ui, across: Run) {
    let color = ui.visuals().widgets.noninteractive.bg_stroke.color;
    ui.add_space(DIVIDER_AIR);
    // A column's rule *takes* the whole width its cluster has claimed and
    // *draws* the inset one, centred in it. Allocating the short rect instead
    // would hang the rule off the cluster's leading edge, since a column lays
    // its contents out from there — the user: *"The dividing line under the
    // select tool is not centered."*
    //
    // The width the column has already claimed, not the width it could claim:
    // an `egui::Area` is sized by its contents, so `available_width` inside
    // one is the rest of the window.
    let size = match across {
        Run::Row => egui::vec2(1.0, DIVIDER_LENGTH),
        Run::Column => egui::vec2(ui.min_rect().width(), 1.0),
    };
    let (rect, _) = ui.allocate_exact_size(size, egui::Sense::hover());
    let rule = match across {
        Run::Row => rect,
        Run::Column => egui::Rect::from_center_size(
            rect.center(),
            egui::vec2((rect.width() - 2.0 * DIVIDER_INSET).max(0.0), rect.height()),
        ),
    };
    ui.painter().rect_filled(rule, 0, color);
    ui.add_space(DIVIDER_AIR);
}

/// The air a rule keeps on each side of itself, for a test that has only the
/// gap between two cells to measure it by.
#[cfg_attr(
    not(test),
    allow(dead_code, reason = "the rule's own audit is a test of it")
)]
pub fn separator_air() -> f32 {
    DIVIDER_AIR
}

/// Which way the controls a rule separates are running.
#[derive(Clone, Copy, PartialEq, Eq)]
pub enum Run {
    Row,
    Column,
}

/// The mockup's `.divider{height:22px}` and both rules' `margin: 5px`.
const DIVIDER_LENGTH: f32 = 24.0;
const DIVIDER_AIR: f32 = 5.0;
/// The mockup's `.toolsep{margin:5px 12px}` — a column's rule stops short
/// of both shoulders where a row's runs beside its neighbours at full height.
const DIVIDER_INSET: f32 = 12.0;

/// Whether a control can be pressed this frame.
///
/// Disabled, never hidden, is the house rule for the whole editor, so every
/// control the shell draws goes through this rather than through an `if`
/// around the widget.
#[derive(Clone, Copy, PartialEq, Eq)]
pub enum Live {
    Yes,
    No,
}

impl From<bool> for Live {
    fn from(live: bool) -> Self {
        if live { Live::Yes } else { Live::No }
    }
}

impl Live {
    fn enabled(self) -> bool {
        self == Live::Yes
    }
}

/// Whether the surface a control opens — a picker, a menu, the navigator — is
/// showing, which is what draws the control pressed. Stated once so the
/// control and the thing it opened cannot disagree about which of them is up.
#[derive(Clone, Copy, PartialEq, Eq)]
pub enum Opened {
    Yes,
    No,
}

impl From<bool> for Opened {
    fn from(opened: bool) -> Self {
        if opened { Opened::Yes } else { Opened::No }
    }
}

impl Opened {
    fn showing(self) -> bool {
        self == Opened::Yes
    }
}

/// A tap-sized icon button, framed only under the pointer — the mockup's
/// `.tapbtn`. `hover` is shown whether or not the button is live, because a
/// dead control still has to say what it would do.
pub fn tap_button(
    ui: &mut egui::Ui,
    icon: egui::ImageSource<'static>,
    live: Live,
    hover: impl Into<egui::WidgetText>,
) -> egui::Response {
    tap_toggle(ui, icon, live, Opened::No, hover)
}

/// The same, drawn pressed while the surface it opens is up — the mockup's
/// `.tapbtn[aria-pressed="true"]`.
pub fn tap_toggle(
    ui: &mut egui::Ui,
    icon: egui::ImageSource<'static>,
    live: Live,
    opened: Opened,
    hover: impl Into<egui::WidgetText>,
) -> egui::Response {
    let hover = hover.into();
    ui.add_enabled_ui(live.enabled(), |ui| {
        let button = egui::Button::image(image(ui, icon, TAP_ICON))
            .min_size(egui::Vec2::splat(TAP))
            .corner_radius(RADIUS_INNER)
            .frame_when_inactive(opened.showing())
            .selected(opened.showing());
        ui.add(button)
    })
    .inner
    .on_hover_text(hover.clone())
    .on_disabled_hover_text(hover)
}

/// The one control the shell draws *filled*: a call to action inside a piece
/// that is itself already a fill — the viewing mode's Return, the mockup's
/// `.mode .ret`. Wider than its word, because a button the user is meant to
/// reach for should not be the same size as the word in it.
pub fn tap_filled(
    ui: &mut egui::Ui,
    text: &str,
    fill: egui::Color32,
    ink: egui::Color32,
    hover: impl Into<egui::WidgetText>,
) -> egui::Response {
    ui.add(
        egui::Button::new(egui::RichText::new(text).color(ink).strong())
            .fill(fill)
            .min_size(egui::vec2(FILLED_WIDTH, TAP))
            .corner_radius(RADIUS_INNER),
    )
    .on_hover_text(hover)
}

/// The mockup's `.ret` is its word with 15px of shoulder either side; this
/// is that width for the longest word the shell puts on one.
const FILLED_WIDTH: f32 = 88.0;

/// The brightest ink the shell writes in — and the one place that knows not
/// to ask egui for it.
///
/// [`egui::Visuals::strong_text_color`] reads `widgets.active.fg_stroke`,
/// which this app's palette sets to its *darkest* base: the ink for a word
/// sitting on an accent-filled control, not a louder version of body text.
/// Anything drawn with it on one of the shell's own surfaces disappears into
/// them, as the top bar's document name found. The theme's plain text colour is full strength here, and
/// `weak_text_color` is the muted one under it.
pub fn full_ink(visuals: &egui::Visuals) -> egui::Color32 {
    visuals.text_color()
}

/// An icon at `size`, tinted to whatever the enclosing `ui` is currently
/// drawing text in — so a disabled scope fades the glyph with its label.
pub fn image(ui: &egui::Ui, source: egui::ImageSource<'static>, size: f32) -> egui::Image<'static> {
    egui::Image::new(source)
        .fit_to_exact_size(egui::Vec2::splat(size))
        .tint(ui.visuals().widgets.inactive.fg_stroke.color)
}

/// How far a control shrinks under the finger — the mockup's
/// `.tool:active{transform:scale(.9)}`.
const PRESS_SCALE: f32 = 0.9;

/// Whether the pointer is down on a control this frame.
#[derive(Clone, Copy, PartialEq, Eq)]
pub enum Pressed {
    Yes,
    No,
}

impl From<bool> for Pressed {
    fn from(held: bool) -> Self {
        if held { Pressed::Yes } else { Pressed::No }
    }
}

/// How big a control's plate draws itself this frame, `id` being the control's
/// own and `held` whether the pointer is down on it.
///
/// The user, on the mockup: *"I like the bouncier tool button behavior of the
/// mockup. It looks like on press, the highlight shrinks slightly and then
/// 'pops up' with a blue highlight to indicate the tool has been selected."*
/// The mockup's `transition: transform .14s var(--spring)` overshoots in
/// whichever direction it is travelling, so [`spring`] is read forwards while
/// the finger is down and forwards *along the return* once it lets go — a
/// curve simply run backwards would ease into rest, and the bounce out of rest
/// is the half the user was pointing at.
///
/// It reaches an exact fixed point at 1.0, so an untouched cluster asks for no
/// repaints and an idle frame still settles.
pub fn press_scale(ctx: &egui::Context, id: egui::Id, held: Pressed) -> f32 {
    let down = held == Pressed::Yes;
    let travel =
        Progress::new(ctx.animate_bool_with_time(id.with("press"), down, MOTION.as_secs_f32()));
    if down {
        1.0 + (PRESS_SCALE - 1.0) * spring(travel)
    } else {
        PRESS_SCALE + (1.0 - PRESS_SCALE) * spring(travel.reversed())
    }
}

/// The space that separates two groups inside one piece — hairline rules are
/// forbidden, so a run of controls is broken by air.
pub fn group_gap(ui: &mut egui::Ui) {
    ui.add_space(GROUP_GAP);
}

const GROUP_GAP: f32 = 10.0;

/// How far through a motion the shell is. Clamped, and never NaN: a curve
/// evaluated outside its own domain is not motion, and egui hands out a raw
/// `f32` that a stalled frame can put out of range.
#[derive(Clone, Copy, PartialEq, PartialOrd, Debug)]
pub struct Progress(f32);

impl Progress {
    pub const START: Progress = Progress(0.0);
    pub const DONE: Progress = Progress(1.0);

    pub fn new(fraction: f32) -> Self {
        if fraction.is_nan() {
            Progress::DONE
        } else {
            Progress(fraction.clamp(0.0, 1.0))
        }
    }

    /// The same motion running the other way — what a piece leaving does.
    pub fn reversed(self) -> Self {
        Progress(1.0 - self.0)
    }
}

impl From<Progress> for f32 {
    fn from(progress: Progress) -> f32 {
        progress.0
    }
}

/// The shell's one motion curve, the mockup's `cubic-bezier(.32,1.5,.5,1)`:
/// the second control point sits above the track, which is where the overshoot
/// the user asked for comes from — *"animating in from the right edge with a
/// little overshoot and springy action."*
///
/// egui interpolates linearly, so the curve is evaluated here rather than
/// asked for: Newton on the horizontal polynomial recovers the Bézier
/// parameter at `at`, and the vertical polynomial at that parameter is the
/// eased fraction. It leaves the unit interval on purpose — an eased value
/// over 1 *is* the overshoot — so it answers a bare fraction rather than
/// another [`Progress`].
pub fn spring(at: Progress) -> f32 {
    /// The curve's own control points, x then y.
    const P1: (f32, f32) = (0.32, 1.5);
    const P2: (f32, f32) = (0.5, 1.0);
    /// Enough for a curve this shallow; the residual is under a tenth of a
    /// pixel over any distance the shell animates.
    const REFINEMENTS: usize = 6;

    let bezier = |a: f32, b: f32, s: f32| {
        let r = 1.0 - s;
        3.0 * r * r * s * a + 3.0 * r * s * s * b + s * s * s
    };
    let slope = |a: f32, b: f32, s: f32| {
        let r = 1.0 - s;
        3.0 * r * r * a + 6.0 * r * s * (b - a) + 3.0 * s * s * (1.0 - b)
    };

    let target = f32::from(at);
    let mut s = target;
    for _ in 0..REFINEMENTS {
        let d = slope(P1.0, P2.0, s);
        if d.abs() < f32::EPSILON {
            break;
        }
        s = (s - (bezier(P1.0, P2.0, s) - target) / d).clamp(0.0, 1.0);
    }
    bezier(P1.1, P2.1, s)
}

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

    /// The berths are distinct places: two pieces sharing an id would share
    /// egui's area state and land on top of each other.
    #[test]
    fn every_berth_is_its_own_place() {
        let ids: std::collections::HashSet<egui::Id> =
            Berth::ALL.iter().map(|berth| berth.id()).collect();
        assert_eq!(ids.len(), Berth::ALL.len());
    }

    /// The elevation rule, read off the table both ways: a docked piece is
    /// flush with the edge it takes, square and unshadowed; a floating one
    /// stands off, rounds and lifts. Nothing is half of each.
    #[test]
    fn docked_chrome_is_flat_and_flush_where_floating_chrome_is_lifted() {
        let visuals = egui::Visuals::light();
        let ctx = egui::Context::default();
        let mut frames = Vec::new();
        ctx.run_ui(egui::RawInput::default(), |ui| {
            for berth in Berth::ALL {
                frames.push((
                    berth,
                    shell(ui, berth.shape(), berth.elevation(), Tint::None),
                ));
            }
        })
        .drop_without_applying_deltas();
        for (berth, frame) in frames {
            match berth.elevation() {
                Elevation::Docked => {
                    assert_eq!(
                        berth.offset(),
                        egui::Vec2::ZERO,
                        "{berth:?} is docked but stands off its edge",
                    );
                    assert_eq!(frame.corner_radius, egui::CornerRadius::ZERO);
                    assert_eq!(frame.shadow, egui::Shadow::NONE, "{berth:?} casts a shadow");
                    assert_ne!(frame.fill, egui::Color32::TRANSPARENT);
                }
                Elevation::Floating => {
                    assert_ne!(berth.offset(), egui::Vec2::ZERO);
                    assert!(frame.corner_radius.nw > 0, "{berth:?} floats but is square");
                    assert_eq!(frame.shadow.offset, SHADOW_OFFSET);
                }
                Elevation::Bare => {
                    assert_eq!(
                        frame.fill,
                        egui::Color32::TRANSPARENT,
                        "{berth:?} is ambient text but draws a container",
                    );
                    assert_eq!(frame.shadow, egui::Shadow::NONE);
                }
            }
        }
        let _ = visuals;
    }

    /// Nothing the chrome draws is see-through, in either state. The mockup's
    /// translucency rides on a backdrop blur egui cannot render, and without
    /// one the drawing under a surface reads as noise through the words on it.
    #[test]
    fn no_surface_the_chrome_draws_is_see_through() {
        let ctx = egui::Context::default();
        let amber = egui::Color32::from_rgba_unmultiplied(255, 150, 108, 128);
        let mut fills = Vec::new();
        ctx.run_ui(egui::RawInput::default(), |ui| {
            for berth in Berth::ALL {
                for tint in [Tint::None, Tint::Over(amber)] {
                    fills.push((
                        berth,
                        shell(ui, berth.shape(), berth.elevation(), tint).fill,
                    ));
                }
            }
        })
        .drop_without_applying_deltas();
        for (berth, fill) in fills {
            if berth.elevation() == Elevation::Bare {
                continue;
            }
            assert_eq!(
                fill.a(),
                255,
                "{berth:?} is drawn at alpha {}, so the canvas shows through it",
                fill.a(),
            );
        }
    }

    /// A tinted bar is the same bar in another state, not another object: the
    /// wash goes over the fill it already had.
    #[test]
    fn a_tint_washes_over_the_fill_rather_than_replacing_it() {
        let amber = egui::Color32::from_rgba_unmultiplied(255, 150, 108, 128);
        let plain = egui::Color32::from_rgb(20, 20, 24);
        let tinted = Tint::Over(amber).over(plain);
        assert_ne!(tinted, plain, "the tint did not reach the fill");
        assert_ne!(
            tinted, amber,
            "the tint replaced the fill instead of washing it"
        );
        assert_eq!(Tint::None.over(plain), plain);
    }

    /// Nothing the shell offers is smaller than a fingertip.
    #[test]
    fn the_tap_target_is_the_specs_and_the_tool_cell_is_no_smaller() {
        assert_eq!(TAP, 44.0, "spec §2.3 fixes the target on every platform");
        let smallest = TOOL.x.min(TOOL.y);
        assert!(
            smallest >= TAP,
            "a tool cell is {smallest}, under the tap target",
        );
    }

    /// The heights the mockup fixes, and the widths they imply: the bar is
    /// `--bar-h` and stands a whole tap target inside it, and the rail is the
    /// 64px column the user measured.
    #[test]
    fn the_chrome_stands_at_the_mockups_own_heights() {
        assert_eq!(TOP_BAR_HEIGHT, 54.0);
        assert_eq!(
            TOOL.x + 2.0 * f32::from(PAD),
            64.0,
            "the tool cluster is not the mockup's 64px column",
        );
        for shape in [Shape::TopBar, Shape::Bar] {
            assert_eq!(
                shape.content_height(),
                Some(TAP),
                "{shape:?} does not stand a tap target's height",
            );
        }
        assert_eq!(Shape::Panel.content_height(), None);
        assert_eq!(Shape::StatusLine.content_height(), None);
    }

    /// The status line answers no pointer, and it is the only thing in the
    /// frame that does not.
    #[test]
    fn only_the_status_line_is_deaf_to_the_pointer() {
        let bare: Vec<Berth> = Berth::ALL
            .into_iter()
            .filter(|berth| berth.elevation() == Elevation::Bare)
            .collect();
        assert_eq!(bare, vec![Berth::StatusLine]);
    }

    /// The one curve, at its ends and over its hump. A spring that did not
    /// overshoot would be an ease, and the overshoot is what the user asked
    /// for by name.
    #[test]
    fn the_motion_curve_starts_still_ends_settled_and_overshoots_between() {
        assert_eq!(spring(Progress::START), 0.0);
        assert!(
            (spring(Progress::DONE) - 1.0).abs() < 1e-3,
            "the curve does not settle: {}",
            spring(Progress::DONE),
        );
        let peak = (0..=100)
            .map(|n| spring(Progress::new(n as f32 / 100.0)))
            .fold(f32::MIN, f32::max);
        assert!(
            peak > 1.0,
            "the curve never leaves the track, so nothing overshoots: {peak}",
        );
        assert!(peak < 1.3, "the overshoot is a bounce, not a lurch: {peak}");
        assert_eq!(
            Progress::new(f32::NAN),
            Progress::DONE,
            "a motion that lost its clock must land settled, not undefined",
        );
        assert_eq!(Progress::new(4.0), Progress::DONE);
        assert_eq!(Progress::new(-1.0), Progress::START);
        assert_eq!(Progress::new(0.25).reversed(), Progress::new(0.75));
    }

    /// The elevation the user asked to be brought in: straight down and soft,
    /// where egui's own falls sideways and lands hard.
    #[test]
    fn the_shadow_falls_straight_down_and_no_further_than_the_mockups() {
        let default = egui::Visuals::light().window_shadow;
        let ours = lift(&egui::Visuals::light());
        assert!(
            default.offset[0] != 0 && default.offset[1] > SHADOW_OFFSET[1],
            "precondition: egui's own shadow is the one the user called too far away",
        );
        assert_eq!(ours.offset, [0, 10], "the mockup's `--shadow` offset");
        assert_eq!(ours.blur, 34, "the mockup's `--shadow` blur");
        let alpha = f32::from(ours.color.a()) / 255.0;
        assert!(
            (alpha - SHADOW_ALPHA).abs() < 0.01,
            "the shadow carries {alpha}, not the mockup's {SHADOW_ALPHA}",
        );
    }
}