cotis_interactivity/

mouse.rs

//! Mouse hover hit-testing and click edge detection.
//!
//! This module provides traits for querying whether the cursor is over a layout
//! element, strategies for turning raw button state into click signals, and
//! per-element managers that combine hover with a [`MouseButton`].
//!
//! Raw mouse state comes from [`cotis_utils::interactivity::mouse::MouseProvider`];
//! layout bounds come from [`cotis_utils::element_state::ElementBoundingBox`].

use crate::utils::UpdatableSignal;
use cotis::cotis_app::CotisApp;
use cotis::layout::LayoutManagerCompatible;
use cotis::renders::RenderCompatibleWith;
use cotis::utils::ElementId;
use cotis_utils::element_state::ElementBoundingBox;
use cotis_utils::interactivity::mouse::{MouseButton, MouseProvider};

/// Hit test `cursor` against `x, y, width, height` after expanding or shrinking the rect per side.
///
/// Positive margins move edges outward (larger hit area); negative margins inset (smaller hit area).
///
/// Uses half-open intervals on both axes: the right and bottom edges are excluded
/// (`cursor_x < max_x`, `cursor_y < max_y`).
///
/// # Examples
///
/// ```
/// use cotis_interactivity::mouse::cursor_in_rect_with_margins;
///
/// // Cursor inside the rect
/// assert!(cursor_in_rect_with_margins(50.0, 50.0, 0.0, 0.0, 100.0, 100.0, 0.0, 0.0, 0.0, 0.0));
///
/// // Right and bottom edges are exclusive
/// assert!(!cursor_in_rect_with_margins(100.0, 50.0, 0.0, 0.0, 100.0, 100.0, 0.0, 0.0, 0.0, 0.0));
/// assert!(!cursor_in_rect_with_margins(50.0, 100.0, 0.0, 0.0, 100.0, 100.0, 0.0, 0.0, 0.0, 0.0));
///
/// // Positive margin expands the hit area outward
/// assert!(cursor_in_rect_with_margins(105.0, 50.0, 0.0, 0.0, 100.0, 100.0, 0.0, 0.0, 10.0, 0.0));
/// ```
#[allow(clippy::too_many_arguments)]
pub fn cursor_in_rect_with_margins(
    cursor_x: f32,
    cursor_y: f32,
    x: f32,
    y: f32,
    width: f32,
    height: f32,
    margin_left: f32,
    margin_top: f32,
    margin_right: f32,
    margin_bottom: f32,
) -> bool {
    let min_x = x - margin_left;
    let max_x = x + width + margin_right;
    let min_y = y - margin_top;
    let max_y = y + height + margin_bottom;
    cursor_x >= min_x && cursor_x < max_x && cursor_y >= min_y && cursor_y < max_y
}

/// Query whether the cursor is over a layout element.
///
/// Implementors resolve the element's bounding box and compare it against the
/// current cursor position. Returns `false` when the element is unknown.
///
/// # Blanket implementation
///
/// [`CotisApp`] implements this trait when:
///
/// - `Renderer: RenderCompatibleWith<Manager> + MouseProvider`
/// - `Manager: LayoutManagerCompatible<Renderer> + ElementBoundingBox`
pub trait ElementCursorState {
    /// Same margin on every side (positive expands the hover region outward).
    fn is_hovered_with_margin(&self, id: ElementId, margin: f32) -> bool {
        self.is_hovered_with_margins(id, margin, margin, margin, margin)
    }

    /// Horizontal margin applied to left and right; vertical margin to top and bottom.
    fn is_hovered_with_axis_margin(&self, id: ElementId, horizontal: f32, vertical: f32) -> bool {
        self.is_hovered_with_margins(id, horizontal, vertical, horizontal, vertical)
    }

    /// Per-edge margins: left, top, right, bottom.
    ///
    /// Uses [`cursor_in_rect_with_margins`] against the element's layout bounding box.
    fn is_hovered_with_margins(
        &self,
        id: ElementId,
        margin_left: f32,
        margin_top: f32,
        margin_right: f32,
        margin_bottom: f32,
    ) -> bool;

    /// Returns whether the cursor is inside the element's bounding box with zero margins.
    fn is_hovered(&self, id: ElementId) -> bool {
        self.is_hovered_with_margins(id, 0.0, 0.0, 0.0, 0.0)
    }
}

/// Extends [`ElementCursorState`] with raw mouse button state.
///
/// Used by [`MouseButtonElementManager`] and scroll element managers to read
/// button presses alongside hover. You can implement this trait on custom app
/// shells; [`CotisApp`] provides the primary blanket implementation.
pub trait FullElementCursorState: ElementCursorState {
    /// Returns whether `mouse_button` is currently held down.
    fn mouse_button_down(&self, mouse_button: MouseButton) -> bool;
}

impl<
    Renderer: RenderCompatibleWith<Manager> + MouseProvider,
    Manager: LayoutManagerCompatible<Renderer> + ElementBoundingBox,
    Pipe,
> ElementCursorState for CotisApp<Renderer, Manager, Pipe>
{
    fn is_hovered_with_margins(
        &self,
        id: ElementId,
        margin_left: f32,
        margin_top: f32,
        margin_right: f32,
        margin_bottom: f32,
    ) -> bool {
        let cursor_pos = self.render_borrow().get_mouse_position();
        let bound_box = self.layout_manager_borrow().bounding_box(id);
        if let Some(bound_box) = bound_box {
            cursor_in_rect_with_margins(
                cursor_pos.x,
                cursor_pos.y,
                bound_box.x,
                bound_box.y,
                bound_box.width,
                bound_box.height,
                margin_left,
                margin_top,
                margin_right,
                margin_bottom,
            )
        } else {
            false
        }
    }
}

impl<
    Renderer: RenderCompatibleWith<Manager> + MouseProvider,
    Manager: LayoutManagerCompatible<Renderer> + ElementBoundingBox,
    Pipe,
> FullElementCursorState for CotisApp<Renderer, Manager, Pipe>
{
    fn mouse_button_down(&self, mouse_button: MouseButton) -> bool {
        MouseProvider::mouse_button_down(self.render_borrow(), mouse_button)
    }
}

/// Determines when [`MouseButtonManager::is_clicked`] returns `true`.
///
/// Each variant tracks button state through an internal edge detector. All
/// variants respect the manager's **cooldown**: while `cooldown > 0`,
/// `is_clicked()` always returns `false` and button presses are ignored.
///
/// After handling a click, call [`MouseButtonManager::change_cooldown`] to
/// set a debounce duration; the cooldown does not restart automatically.
///
/// # Variants
///
/// | Variant | `is_clicked` when |
/// |---|---|
/// | [`Pressed`](Self::Pressed) | Button is gated-pressed this frame |
/// | [`NotPressed`](Self::NotPressed) | Button is not gated-pressed |
/// | [`FallingEdge`](Self::FallingEdge) | Falling edge of gated press (release) |
/// | [`RisingEdge`](Self::RisingEdge) | Rising edge of gated press (initial press) |
/// | [`DoubleEdge`](Self::DoubleEdge) | Release after a valid press-while-hovered sequence |
/// | [`RisingHold`](Self::RisingHold) | Hold timer reaches `goal` while armed |
/// | [`Hold`](Self::Hold) | Hold timer reaches `goal` while pressed and hovered |
pub enum MouseClickingStrategy {
    /// `is_clicked` is `true` while the button is held (after cooldown).
    Pressed,
    /// `is_clicked` is `true` while the button is not held (after cooldown).
    NotPressed,
    /// `is_clicked` is `true` on the frame the button is released.
    FallingEdge,
    /// `is_clicked` is `true` on the frame the button is first pressed.
    RisingEdge,
    /// Click-on-release after a press-while-hovered sequence.
    ///
    /// During a press, `rising_edge` is armed when hovered and cooldown has
    /// expired. `is_clicked` fires on the release (falling edge) when armed.
    ///
    /// # Note
    ///
    /// This is **not** an operating-system double-click detector.
    DoubleEdge {
        /// Internal arming flag; initialized to `false`.
        rising_edge: bool,
    },
    /// Fires when `time >= goal` after the same arming logic as [`DoubleEdge`](Self::DoubleEdge).
    ///
    /// While armed, `time` increases each frame; when not armed, `time` decreases.
    /// `time` resets to zero when the button is released.
    RisingHold {
        /// Internal arming flag; initialized to `false`.
        rising_edge: bool,
        /// Accumulated hold time in seconds.
        time: f32,
        /// Duration in seconds required for `is_clicked` to return `true`.
        goal: f32,
    },
    /// Fires when `time >= goal` while the button is held and the element is hovered.
    ///
    /// `time` resets to zero when the button is released or the cursor leaves
    /// the hover region.
    Hold {
        /// Accumulated hold time in seconds.
        time: f32,
        /// Duration in seconds required for `is_clicked` to return `true`.
        goal: f32,
    },
}

/// Tracks click signals for a single mouse button with a configurable strategy.
///
/// Call [`update`](Self::update) every frame with the raw button state, frame
/// delta time, and whether the target region is hovered. Then query
/// [`is_clicked`](Self::is_clicked).
///
/// # Cooldown
///
/// The cooldown decrements each `update`. While `cooldown > 0`, button presses
/// are ignored and `is_clicked()` returns `false`. After handling a click, call
/// [`change_cooldown`](Self::change_cooldown) to debounce subsequent clicks.
pub struct MouseButtonManager {
    strategy: MouseClickingStrategy,
    signal: UpdatableSignal,
    cooldown: f32,
}

impl MouseButtonManager {
    /// Creates a manager with the given clicking strategy and initial cooldown.
    ///
    /// For hold strategies ([`MouseClickingStrategy::Hold`] and
    /// [`MouseClickingStrategy::RisingHold`]), initialize struct-variant fields
    /// before passing the strategy here, for example:
    ///
    /// ```rust
    /// use cotis_interactivity::mouse::{MouseButtonManager, MouseClickingStrategy};
    ///
    /// let strategy = MouseClickingStrategy::Hold { time: 0.0, goal: 0.5 };
    /// let manager = MouseButtonManager::new(strategy, 0.0);
    /// ```
    pub fn new(strategy: MouseClickingStrategy, cooldown: f32) -> MouseButtonManager {
        Self {
            strategy,
            signal: UpdatableSignal::new(false),
            cooldown,
        }
    }

    /// Advances state for one frame.
    ///
    /// * `button_pressed` — raw button state from a [`MouseProvider`].
    /// * `delta_time` — elapsed seconds since the last frame.
    /// * `hovered` — whether the cursor is over the target region.
    pub fn update(&mut self, button_pressed: bool, delta_time: f32, hovered: bool) {
        self.cooldown -= delta_time;
        let gated_press = button_pressed && self.cooldown <= 0.0;
        self.signal.update(gated_press);
        if button_pressed {
            match &mut self.strategy {
                MouseClickingStrategy::Hold { time, .. } => {
                    if !hovered {
                        *time = 0.0;
                    } else {
                        *time += delta_time
                    }
                }
                MouseClickingStrategy::RisingHold {
                    rising_edge, time, ..
                } => {
                    *rising_edge = self.cooldown <= 0.0
                        && hovered
                        && (*rising_edge || self.signal.rising_edge())
                        && (button_pressed || self.signal.falling_edge());
                    if *rising_edge {
                        *time += delta_time;
                    } else {
                        *time -= delta_time;
                    }
                }
                MouseClickingStrategy::DoubleEdge { rising_edge } => {
                    *rising_edge = self.cooldown <= 0.0
                        && hovered
                        && (*rising_edge || self.signal.rising_edge())
                        && (button_pressed || self.signal.falling_edge());
                }
                _ => {}
            }
        } else {
            match &mut self.strategy {
                MouseClickingStrategy::Hold { time, .. }
                | MouseClickingStrategy::RisingHold { time, .. } => {
                    *time = 0.0;
                }
                _ => {}
            }
        }
    }

    /// Clears the cooldown immediately, allowing the next press to register.
    pub fn reset_cooldown(&mut self) {
        self.cooldown = 0.0;
    }

    /// Sets the cooldown to `cooldown` seconds.
    ///
    /// Call this after handling a click to debounce further input.
    pub fn change_cooldown(&mut self, cooldown: f32) {
        self.cooldown = cooldown;
    }

    /// Returns whether a click signal is active this frame according to the strategy.
    ///
    /// Always returns `false` while the cooldown is positive.
    pub fn is_clicked(&self) -> bool {
        if self.cooldown > 0.0 {
            return false;
        }
        match &self.strategy {
            MouseClickingStrategy::Pressed => self.signal.is_on(),
            MouseClickingStrategy::NotPressed => !self.signal.is_on(),
            MouseClickingStrategy::FallingEdge => self.signal.falling_edge(),
            MouseClickingStrategy::RisingEdge => self.signal.rising_edge(),
            MouseClickingStrategy::DoubleEdge { rising_edge } => {
                self.signal.falling_edge() && *rising_edge
            }
            MouseClickingStrategy::RisingHold { time, goal, .. } => time >= goal,
            MouseClickingStrategy::Hold { time, goal } => time >= goal,
        }
    }
}

/// Per-element click manager that combines hover and a mouse button.
///
/// Wraps [`MouseButtonManager`] for a specific [`ElementId`]. Each frame, call
/// [`update`](Self::update) with a [`FullElementCursorState`] provider (such as
/// [`CotisApp`]).
///
/// # Examples
///
/// ```rust,ignore
/// use cotis_interactivity::mouse::{
///     FullElementCursorState, MouseButtonElementManager, MouseClickingStrategy,
/// };
/// use cotis_utils::interactivity::mouse::MouseButton;
///
/// // let mut click_manager = MouseButtonElementManager::new(
/// //     element_id,
/// //     MouseButton::Left,
/// //     MouseClickingStrategy::RisingEdge,
/// //     0.0,
/// // );
/// // click_manager.update(&app as &dyn FullElementCursorState, dt);
/// // if click_manager.is_clicked() { ... }
/// ```
pub struct MouseButtonElementManager {
    key: MouseButton,
    manager: MouseButtonManager,
    element: ElementId,
}

impl MouseButtonElementManager {
    /// Creates a click manager bound to `element_id` and `key`.
    pub fn new(
        element_id: ElementId,
        key: MouseButton,
        strategy: MouseClickingStrategy,
        cooldown: f32,
    ) -> MouseButtonElementManager {
        Self {
            key,
            element: element_id,
            manager: MouseButtonManager::new(strategy, cooldown),
        }
    }

    /// Advances state for one frame using hover and button state from `element_state_provider`.
    pub fn update(&mut self, element_state_provider: &dyn FullElementCursorState, delta_time: f32) {
        self.manager.update(
            FullElementCursorState::mouse_button_down(element_state_provider, self.key),
            delta_time,
            element_state_provider.is_hovered(self.element),
        );
    }

    /// Clears the inner manager's cooldown. See [`MouseButtonManager::reset_cooldown`].
    pub fn reset_cooldown(&mut self) {
        self.manager.reset_cooldown()
    }

    /// Sets the inner manager's cooldown. See [`MouseButtonManager::change_cooldown`].
    pub fn change_cooldown(&mut self, cooldown: f32) {
        self.manager.change_cooldown(cooldown)
    }

    /// Returns whether a click signal is active this frame.
    pub fn is_clicked(&self) -> bool {
        self.manager.is_clicked()
    }
}