blockworx_kernel/

bar.rs

//! The selection overlay's own policy: which verbs it carries, in what
//! order, where the row ends and the overflow begins, and where the bar
//! stands over the diagram.
//!
//! None of it is a drawing. Two front ends that decided any of this
//! themselves would offer two different bars over one selection, so it is
//! decided once, here, and each of them only paints the answer.

use blockworx_geom::{Rect, Vec2, pos2};
use blockworx_tools::commands::Precedence;

/// How many controls the bar's row holds. A selection offering more shows
/// this many and puts the rest behind the ellipsis; one offering this many or
/// fewer has no ellipsis at all.
pub const INLINE_CONTROLS: usize = 5;

/// The air between the selection's bounding box and the bar.
pub const CLEAR: f32 = 14.0;

/// What a selection with no commands says, rather than raising no bar at all.
///
/// A selection that silently draws no bar is indistinguishable from a
/// selection whose bar is broken, so the empty case says so out loud
/// whether one thing is selected or several.
#[must_use]
pub fn nothing_to_say(count: usize) -> &'static str {
    if count > 1 {
        "No actions shared by this selection"
    } else {
        "No actions for this selection"
    }
}

/// What the bar shows for one selection: the one list, in the order the row,
/// the overflow and the right-click menu all read.
///
/// Generic over what is being cut so the ids a test compares and the controls
/// a frame draws cannot be divided differently.
pub enum Bar<T> {
    /// Every control, own verbs before clerical ones; [`Bar::row`] and
    /// [`Bar::overflow`] are its two halves.
    Row(Vec<T>),
    /// A multi-selection whose members share no command. Saying so is
    /// the point: an empty bar reads as a bug.
    NothingShared,
    /// One thing selected with nothing to do to it. It says so, rather than
    /// drawing nothing: a selection that raises no bar reads as a bug.
    Nothing,
}

impl<T> Bar<T> {
    /// Order the one list by precedence, keeping the registry's order within
    /// each rank.
    pub fn of(mut commands: Vec<T>, count: usize, precedence: impl Fn(&T) -> Precedence) -> Self {
        if commands.is_empty() {
            return if count > 1 {
                Bar::NothingShared
            } else {
                Bar::Nothing
            };
        }
        commands.sort_by_key(&precedence);
        Bar::Row(commands)
    }

    /// Everything the bar offers, row then overflow — which is exactly what
    /// the right-click menu carries.
    #[must_use]
    pub fn all(&self) -> &[T] {
        match self {
            Bar::Row(all) => all,
            Bar::NothingShared | Bar::Nothing => &[],
        }
    }

    /// The controls drawn in the row.
    #[must_use]
    pub fn row(&self) -> &[T] {
        self.all().split_at(self.cut()).0
    }

    /// The controls behind the ellipsis.
    #[must_use]
    pub fn overflow(&self) -> &[T] {
        self.all().split_at(self.cut()).1
    }

    #[must_use]
    pub fn cut(&self) -> usize {
        self.all().len().min(INLINE_CONTROLS)
    }
}

/// Where a bar of `size` stands over a selection of `sel`, inside `region` —
/// the part of the viewport the front end's chrome leaves clear.
///
/// Centred above the selection, flipped below when that would land under the
/// top chrome, and — for a selection taller than the region, which is an area
/// whose interior is not hit-testable anyway — inside it. The fit test is
/// vertical only: both candidates are wholly clear of the selection in `y`
/// and the clamp moves the bar in `x`, which is why the bar provably never
/// covers what is selected.
///
/// `None` only when there is no region at all to put it in.
#[must_use]
pub fn place(sel: Rect, size: Vec2, region: Rect) -> Option<Rect> {
    let band = |top: f32| Rect::from_min_size(pos2(sel.center().x - size.x / 2.0, top), size);
    let fits = |bar: &Rect| bar.min.y >= region.min.y && bar.max.y <= region.max.y;
    let outside = [band(sel.min.y - CLEAR - size.y), band(sel.max.y + CLEAR)]
        .into_iter()
        .find(fits);
    let inside = || {
        let bar = band(sel.min.y.max(region.min.y) + CLEAR);
        fits(&bar).then_some(bar)
    };
    outside.or_else(inside).map(|bar| clamp(bar, region))
}

/// `rect` moved — never resized — until it lies inside `region`. A rect too
/// big for the region aligns to the region's top left, so what overflows is
/// the far edge rather than the near one.
#[must_use]
pub fn clamp(rect: Rect, region: Rect) -> Rect {
    let shift = |low: f32, high: f32, min: f32, max: f32| {
        if min < low {
            low - min
        } else if max > high {
            (high - max).max(low - min)
        } else {
            0.0
        }
    };
    rect.translate(Vec2::new(
        shift(region.min.x, region.max.x, rect.min.x, rect.max.x),
        shift(region.min.y, region.max.y, rect.min.y, rect.max.y),
    ))
}

#[cfg(test)]
mod tests {
    use blockworx_geom::{pos2, vec2};

    use super::*;

    /// The room the chrome left, as the placement tests read it: the whole
    /// canvas, or the canvas minus a band an inset took off an edge.
    fn region() -> Rect {
        Rect::from_min_size(pos2(0.0, 0.0), vec2(1000.0, 800.0))
    }

    /// A bar of a size the placement tests can reason about without drawing
    /// it.
    const SIZE: Vec2 = Vec2::new(200.0, 40.0);

    #[test]
    fn places_the_bar_above_the_selection_with_the_specs_air() {
        let sel = Rect::from_min_size(pos2(400.0, 400.0), vec2(100.0, 100.0));
        let region = region();
        assert!(
            region.contains_rect(sel),
            "precondition: the selection is inside the room the chrome left",
        );
        let bar = place(sel, SIZE, region).expect("a mid-canvas selection has room above it");
        assert_eq!(bar.max.y, sel.min.y - CLEAR, "the air is not §3.3's 14px");
        assert_eq!(
            bar.center().x,
            sel.center().x,
            "the bar is not centred on it"
        );
        assert_eq!(bar.size(), SIZE, "placing resized the bar");
    }

    #[test]
    fn flips_below_when_above_would_land_under_the_top_chrome() {
        let region = Rect::from_min_max(pos2(0.0, 80.0), pos2(1000.0, 800.0));
        let sel = Rect::from_min_size(pos2(400.0, 100.0), vec2(100.0, 100.0));
        assert!(
            sel.min.y - CLEAR - SIZE.y < region.min.y,
            "precondition: above is under the chrome",
        );
        let bar = place(sel, SIZE, region).expect("there is room below it");
        assert_eq!(bar.min.y, sel.max.y + CLEAR, "it did not flip below");
    }

    #[test]
    fn clamps_sideways_into_the_room_the_chrome_left() {
        let region = Rect::from_min_max(pos2(0.0, 0.0), pos2(688.0, 800.0));
        let sel = Rect::from_min_size(pos2(640.0, 400.0), vec2(40.0, 40.0));
        assert!(
            sel.center().x + SIZE.x / 2.0 > region.max.x,
            "precondition: centred, the bar would run under the navigator",
        );
        let bar = place(sel, SIZE, region).expect("a clamped bar still has a place");
        assert!(
            region.contains_rect(bar),
            "the bar landed at {bar:?}, outside {region:?}",
        );
        assert_eq!(bar.size(), SIZE, "clamping resized the bar");
    }

    /// Invariant 5, over a spread of selections: wherever the bar lands, it is
    /// never on top of the thing it describes. This holds because the clamp is
    /// horizontal and both candidate bands are wholly clear in *y* — so a
    /// clamp that ever moved *y* would fail here.
    #[test]
    fn the_bar_never_covers_what_is_selected() {
        let region = Rect::from_min_max(pos2(92.0, 80.0), pos2(1000.0, 800.0));
        let mut placed = 0;
        for x in [-60.0, 0.0, 120.0, 500.0, 900.0, 980.0] {
            for y in [-60.0, 0.0, 90.0, 400.0, 700.0, 780.0] {
                for size in [vec2(24.0, 24.0), vec2(320.0, 180.0)] {
                    let sel = Rect::from_min_size(pos2(x, y), size);
                    let Some(bar) = place(sel, SIZE, region) else {
                        continue;
                    };
                    placed += 1;
                    assert!(
                        !bar.intersects(sel),
                        "the bar at {bar:?} covers the selection at {sel:?}",
                    );
                    assert!(
                        region.contains_rect(bar),
                        "the bar at {bar:?} left {region:?}",
                    );
                }
            }
        }
        assert!(
            placed > 0,
            "no selection was placed — the sweep proved nothing"
        );
    }

    /// A selection bigger than the room around it takes the band just inside
    /// its own leading edge (item 25). Invariant 5 — *the bar never covers
    /// what is selected* — is kept where it can be: the bar goes outside the
    /// selection whenever there is an outside, and only an oversized
    /// selection sees it inside, which beats an area with no overlay at all.
    #[test]
    fn a_selection_with_no_room_either_side_takes_the_band_inside_itself() {
        let sel = Rect::from_min_size(pos2(-100.0, -100.0), vec2(1200.0, 1000.0));
        let region = region();
        assert!(
            !region.contains_rect(sel),
            "precondition: the selection overruns the region",
        );
        let placed = place(sel, SIZE, region).expect("an oversized selection still gets a bar");
        assert!(
            region.contains_rect(placed),
            "the bar landed outside the region at {placed:?}",
        );
        assert!(
            placed.min.y >= region.min.y + CLEAR,
            "the bar sits flush against the region's own edge: {placed:?}",
        );
    }

    /// A rect too big for the region aligns to its top left, so what
    /// overflows is the far edge rather than the near one.
    #[test]
    fn a_rect_too_big_for_the_region_aligns_to_its_near_edge() {
        let region = Rect::from_min_max(pos2(100.0, 50.0), pos2(300.0, 150.0));
        let wide = Rect::from_min_size(pos2(0.0, 0.0), vec2(400.0, 400.0));
        assert_eq!(clamp(wide, region).min, region.min);
    }

    /// An empty selection says so rather than raising no bar, and says which
    /// kind of nothing it is.
    #[test]
    fn an_empty_bar_names_which_nothing_it_is() {
        let none: Bar<u8> = Bar::of(Vec::new(), 1, |_: &u8| Precedence::Own);
        assert!(matches!(none, Bar::Nothing));
        assert!(none.all().is_empty());
        let shared: Bar<u8> = Bar::of(Vec::new(), 3, |_: &u8| Precedence::Own);
        assert!(matches!(shared, Bar::NothingShared));
        assert_eq!(nothing_to_say(1), "No actions for this selection");
        assert_eq!(nothing_to_say(3), "No actions shared by this selection");
    }

    /// The own verbs lead and the clerical ones follow, and within each rank
    /// the order the registry pushed them in survives.
    #[test]
    fn precedence_orders_the_bar_and_the_registry_orders_each_rank() {
        let ranked = |at: &u8| {
            if at.is_multiple_of(2) {
                Precedence::Clerical
            } else {
                Precedence::Own
            }
        };
        let bar = Bar::of(vec![0_u8, 1, 2, 3, 4, 5, 6], 1, ranked);
        assert_eq!(bar.all(), [1, 3, 5, 0, 2, 4, 6]);
        assert_eq!(bar.row().len(), INLINE_CONTROLS);
        assert_eq!(bar.row(), [1, 3, 5, 0, 2]);
        assert_eq!(bar.overflow(), [4, 6]);
    }
}