uzor 1.5.32

Core UI engine — geometry, interaction, input state
Documentation
//! Headless per-frame widget test harness.

use crate::a11y::A11yTree;
use crate::input::driver::CoordinatorDriver;
use crate::input::{InputCoordinator, WidgetResponse};
use crate::types::WidgetId;

use super::events::EventSynthesizer;

/// Drives an [`InputCoordinator`] through the real `begin_frame` /
/// `end_frame` lifecycle, one synthesized frame at a time.
///
/// # The warm-up frame
///
/// `InputCoordinator::begin_frame` bakes this frame's hover/press state by
/// hit-testing the pointer position against the widgets registered during
/// the PREVIOUS frame's `build` call (see that method's own doc comment —
/// this is deliberate: it fixes a z-order leak where mid-frame baking saw
/// an incomplete widget list). One consequence: a widget registered for
/// the FIRST time inside a `frame()` call is never `Hovered`/`Pressed` in
/// that SAME call, even if the pointer already sits over it — the
/// coordinator has nothing to hit-test against yet. Call `frame()` (or
/// [`Self::settle`]) once more with the same registrations before
/// asserting `Hovered`/`Pressed` for a widget that has only been
/// registered once so far.
pub struct TestHarness {
    /// The coordinator under test.
    pub coordinator: InputCoordinator,
    /// The event synthesizer driving `coordinator`'s input.
    pub events: EventSynthesizer,
    frame_a11y: A11yTree,
}

/// What one [`TestHarness::frame`] call produced.
pub struct FrameOutcome {
    /// Widget responses `end_frame` returned this frame.
    pub responses: Vec<(WidgetId, WidgetResponse)>,
    /// The accessibility tree `build` pushed nodes into this frame.
    pub a11y: A11yTree,
}

impl Default for TestHarness {
    fn default() -> Self {
        Self::new()
    }
}

impl TestHarness {
    /// Create a harness with a fresh [`InputCoordinator`] and
    /// [`EventSynthesizer`].
    pub fn new() -> Self {
        Self {
            coordinator: InputCoordinator::new(),
            events: EventSynthesizer::new(),
            frame_a11y: A11yTree::new(),
        }
    }

    /// Drive exactly one frame: feed `events`'s current `InputState` into
    /// `begin_frame`, run `build` (the test's own register/draw closure —
    /// same shape a real per-frame `ui()` callback takes: register widgets
    /// on `coord`, push this frame's `A11yNode`s into the tree), call
    /// `end_frame`, then `events.end_frame()` to clear one-shot input
    /// state for the next call.
    ///
    /// See the struct-level doc for the warm-up-frame caveat around
    /// first-time registrations.
    pub fn frame<R>(
        &mut self,
        build: impl FnOnce(&mut InputCoordinator, &mut A11yTree) -> R,
    ) -> (R, FrameOutcome) {
        self.coordinator.begin_frame(self.events.input_state());
        self.frame_a11y.clear();
        let result = build(&mut self.coordinator, &mut self.frame_a11y);
        let responses = self.coordinator.end_frame();
        self.events.end_frame();
        (
            result,
            FrameOutcome {
                responses,
                a11y: self.frame_a11y.clone(),
            },
        )
    }

    /// Run one additional frame using the CURRENT input snapshot with no
    /// new events synthesized — the explicit warm-up call for the caveat
    /// documented on [`Self::frame`]. Named separately (rather than having
    /// `frame()` silently run twice) so a test's warm-up is visible at the
    /// call site.
    pub fn settle<R>(
        &mut self,
        build: impl FnOnce(&mut InputCoordinator, &mut A11yTree) -> R,
    ) -> (R, FrameOutcome) {
        self.frame(build)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::input::driver::CoordinatorDriver;
    use crate::input::pointer::state::{InputState, MouseButton};
    use crate::input::Sense;
    use crate::types::{Rect, WidgetState};

    fn register(coord: &mut InputCoordinator, id: WidgetId, rect: Rect) {
        coord.register(id, rect, Sense::CLICK);
    }

    #[test]
    fn click_through_a_trivial_widget_reports_clicked() {
        let id = WidgetId::from("trivial-click");
        let rect = Rect::new(0.0, 0.0, 40.0, 20.0);
        let mut harness = TestHarness::new();

        // Frame 1 — first-ever registration.
        harness.frame(|coord, _| register(coord, id.clone(), rect));

        // Frame 2 — press: frame 1 already registered this widget/rect, so
        // this frame's `begin_frame` bake reports `Pressed` immediately.
        harness.events.pointer_down(10.0, 10.0, MouseButton::Left);
        harness.frame(|coord, _| register(coord, id.clone(), rect));
        assert_eq!(harness.coordinator.widget_state(&id), WidgetState::Pressed);

        // Frame 3 — release: `end_frame`'s own THIS-frame hit test (not
        // the `begin_frame` bake) reports `clicked` straight off this
        // frame's registration, no extra warm-up needed.
        harness.events.pointer_up(10.0, 10.0, MouseButton::Left);
        let (_, outcome) = harness.frame(|coord, _| register(coord, id.clone(), rect));
        let (_, response) = outcome
            .responses
            .iter()
            .find(|(wid, _)| wid == &id)
            .expect("clicked response must exist");
        assert!(response.clicked);
    }

    #[test]
    fn drag_in_while_held_does_not_press_the_widget_dragged_onto() {
        let widget_a = WidgetId::from("drag-a");
        let widget_b = WidgetId::from("drag-b");
        let rect_a = Rect::new(0.0, 0.0, 50.0, 50.0);
        let rect_b = Rect::new(100.0, 0.0, 50.0, 50.0);
        let mut harness = TestHarness::new();

        let build = |coord: &mut InputCoordinator, _: &mut A11yTree| {
            register(coord, widget_a.clone(), rect_a);
            register(coord, widget_b.clone(), rect_b);
        };

        // Frame 1 — first-ever registration of both widgets.
        harness.frame(build);

        // Frame 2 — press on widget A.
        harness.events.pointer_down(25.0, 25.0, MouseButton::Left);
        harness.frame(build);
        assert_eq!(harness.coordinator.widget_state(&widget_a), WidgetState::Pressed);

        // Frame 3 — drag the still-held pointer onto widget B.
        harness.events.pointer_move(125.0, 25.0);
        harness.frame(build);
        assert_eq!(
            harness.coordinator.widget_state(&widget_b),
            WidgetState::Hovered,
            "press-origin widget A must not transfer Pressed onto B on drag-in"
        );
        assert_eq!(harness.coordinator.widget_state(&widget_a), WidgetState::Normal);
        assert!(
            harness.coordinator.cook_state().drag_armed,
            "a held press that travelled past DRAG_THRESHOLD_PX is armed as a drag"
        );
    }

    fn response_for<'a>(outcome: &'a FrameOutcome, id: &WidgetId) -> Option<&'a WidgetResponse> {
        outcome.responses.iter().find(|(wid, _)| wid == id).map(|(_, r)| r)
    }

    #[test]
    fn quick_clicks_report_double_then_triple_and_a_slow_one_resets() {
        let id = WidgetId::from("multi-click");
        let rect = Rect::new(0.0, 0.0, 40.0, 20.0);
        let mut harness = TestHarness::new();
        let build = |coord: &mut InputCoordinator, _: &mut A11yTree| register(coord, id.clone(), rect);
        harness.frame(build);

        let click_at = |harness: &mut TestHarness, dt: f64, x: f64| {
            harness.events.tick(dt);
            harness.events.click(x, 10.0);
            let (_, outcome) = harness.frame(build);
            let r = response_for(&outcome, &id).expect("clicked response").clone();
            assert!(r.clicked);
            (r.double_clicked, r.triple_clicked, harness.coordinator.cook_state().click_count)
        };

        assert_eq!(click_at(&mut harness, 1.0, 10.0), (false, false, 1));
        assert_eq!(click_at(&mut harness, 0.1, 11.0), (true, false, 2));
        assert_eq!(click_at(&mut harness, 0.1, 11.0), (false, true, 3));
        // outside DOUBLE_CLICK_WINDOW_S
        assert_eq!(click_at(&mut harness, 1.0, 11.0), (false, false, 1));
        // inside the window but farther than MULTI_CLICK_MAX_DIST_PX
        assert_eq!(click_at(&mut harness, 0.1, 30.0), (false, false, 1));
    }

    #[test]
    fn a_host_that_stamps_no_time_never_reports_a_double_click() {
        let id = WidgetId::from("unstamped");
        let rect = Rect::new(0.0, 0.0, 40.0, 20.0);
        let mut coord = InputCoordinator::new();
        let mut input = InputState::new();
        input.pointer.pos = Some((10.0, 10.0));
        for _ in 0..3 {
            input.pointer.clicked = Some(MouseButton::Left);
            coord.begin_frame(input.clone());
            register(&mut coord, id.clone(), rect);
            let responses = coord.end_frame();
            let (_, r) = responses.iter().find(|(wid, _)| wid == &id).expect("response");
            assert!(r.clicked && !r.double_clicked && !r.triple_clicked);
            assert_eq!(coord.cook_state().click_count, 1);
        }
    }

    #[test]
    fn a_pointer_grab_keeps_input_on_the_grabbing_widget_until_release() {
        let handle = WidgetId::from("splitter");
        let other = WidgetId::from("other");
        let rect_h = Rect::new(0.0, 0.0, 10.0, 100.0);
        let rect_o = Rect::new(50.0, 0.0, 100.0, 100.0);
        let mut harness = TestHarness::new();
        let build = |coord: &mut InputCoordinator, _: &mut A11yTree| {
            register(coord, handle.clone(), rect_h);
            register(coord, other.clone(), rect_o);
        };
        harness.frame(build);

        harness.events.tick(0.5).pointer_down(5.0, 50.0, MouseButton::Left);
        harness.frame(build);
        harness.coordinator.grab_pointer(handle.clone());

        // pointer travels over the other widget while held
        harness.events.pointer_move(100.0, 50.0);
        let (_, outcome) = harness.frame(build);
        assert!(response_for(&outcome, &handle).is_some_and(|r| r.hovered), "grab keeps the handle hovered");
        assert!(response_for(&outcome, &other).is_none_or(|r| !r.hovered), "the widget under the cursor is not hovered");

        // release over the other widget: the click lands on the grabber, and the grab ends
        harness.events.pointer_up(100.0, 50.0, MouseButton::Left);
        let (_, outcome) = harness.frame(build);
        assert!(response_for(&outcome, &handle).is_some_and(|r| r.clicked));
        assert!(response_for(&outcome, &other).is_none_or(|r| !r.clicked));
        assert_eq!(harness.coordinator.cook_state().grabbed, None);

        // next motion follows the hit test again
        harness.events.pointer_move(101.0, 50.0);
        let (_, outcome) = harness.frame(build);
        assert!(response_for(&outcome, &other).is_some_and(|r| r.hovered));
    }

    #[test]
    fn release_pointer_ends_a_grab_early() {
        let mut coord = InputCoordinator::new();
        coord.grab_pointer("h");
        assert_eq!(coord.cook_state().grabbed, Some(WidgetId::from("h")));
        coord.release_pointer();
        assert_eq!(coord.cook_state().grabbed, None);
    }

    #[test]
    fn settle_makes_a_first_time_registration_hoverable() {
        let id = WidgetId::from("first-timer");
        let rect = Rect::new(0.0, 0.0, 40.0, 20.0);
        let mut harness = TestHarness::new();
        harness.events.pointer_move(10.0, 10.0);

        // Frame 1 — first-ever registration: `begin_frame`'s bake ran
        // against the EMPTY previous-frame widget list, so the widget
        // cannot be Hovered yet even though the pointer already sits
        // inside its rect.
        harness.frame(|coord, _| register(coord, id.clone(), rect));
        assert_eq!(harness.coordinator.widget_state(&id), WidgetState::Normal);

        // settle(): one more frame with no NEW input re-registers the
        // same widget; `begin_frame`'s bake now sees frame 1's
        // registration.
        harness.settle(|coord, _| register(coord, id.clone(), rect));
        assert_eq!(harness.coordinator.widget_state(&id), WidgetState::Hovered);
    }
}