teksilo_core/

event.rs

// SPDX-License-Identifier: MPL-2.0
// SPDX-FileCopyrightText: 2026 FernTech

use teksilo_canvas::{Point, Rect};

use crate::gesture::GestureEvent;
use crate::pointer::{CancelReason, EventTime, PointerInfo, ScrollPhase};

/// Pointer button identifiers.
///
/// `Forward` and `Back` correspond to the auxiliary mouse buttons (mouse
/// 4 / mouse 5) typically labelled "browser back / forward". Platforms
/// that don't have those buttons simply never emit them.
///
/// `#[non_exhaustive]`: a stylus barrel button and an eraser-end press are
/// buttons this enum will have to name, and neither exists yet. A downstream
/// `match` therefore needs a `_` arm.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum PointerButton {
    /// Left-click (or main-action button on left-handed mice).
    Primary,
    /// Right-click.
    Secondary,
    /// Middle / wheel-click.
    Middle,
    /// "Back" auxiliary button (mouse 4 on most 5-button mice). Often
    /// bound to "navigate back" in browsers.
    Back,
    /// "Forward" auxiliary button (mouse 5). Often bound to "navigate
    /// forward".
    Forward,
}

/// Set of pointer buttons a gesture recognizer is configured to fire
/// for. Used by the four click-style recognizers (`TapRecognizer`,
/// `DoubleTapRecognizer`, `TripleTapRecognizer`, `LongPressRecognizer`)
/// and the matching widget-level builders (`accept_tap_buttons`, …).
///
/// Default for every recognizer is [`ButtonMask::PRIMARY`] — left-click
/// only — which matches the user's expectation for a "tap" and keeps
/// right-click free to open a context menu without spuriously
/// activating the widget. Use [`ButtonMask::ALL`] or a hand-built
/// `PRIMARY | SECONDARY` etc. to opt into broader button sets.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct ButtonMask(u8);

impl ButtonMask {
    /// Empty mask — no buttons accepted.
    pub const NONE: Self = Self(0);
    /// Left-click on most desktop pointing devices.
    pub const PRIMARY: Self = Self(1 << 0);
    /// Right-click on most desktop pointing devices.
    pub const SECONDARY: Self = Self(1 << 1);
    /// Middle / wheel-click.
    pub const MIDDLE: Self = Self(1 << 2);
    /// "Back" auxiliary button (mouse 4).
    pub const BACK: Self = Self(1 << 3);
    /// "Forward" auxiliary button (mouse 5).
    pub const FORWARD: Self = Self(1 << 4);
    /// All buttons currently representable by [`PointerButton`].
    pub const ALL: Self = Self(0b0001_1111);

    /// `true` when the mask contains the given button.
    pub const fn contains(self, button: PointerButton) -> bool {
        let bit = match button {
            PointerButton::Primary => 1 << 0,
            PointerButton::Secondary => 1 << 1,
            PointerButton::Middle => 1 << 2,
            PointerButton::Back => 1 << 3,
            PointerButton::Forward => 1 << 4,
        };
        self.0 & bit != 0
    }

    /// `true` when no buttons are accepted.
    pub const fn is_empty(self) -> bool {
        self.0 == 0
    }

    /// Union — accept any button in either mask.
    pub const fn union(self, other: Self) -> Self {
        Self(self.0 | other.0)
    }

    /// Intersection — accept only buttons present in both masks.
    pub const fn intersection(self, other: Self) -> Self {
        Self(self.0 & other.0)
    }
}

impl From<PointerButton> for ButtonMask {
    fn from(button: PointerButton) -> Self {
        match button {
            PointerButton::Primary => Self::PRIMARY,
            PointerButton::Secondary => Self::SECONDARY,
            PointerButton::Middle => Self::MIDDLE,
            PointerButton::Back => Self::BACK,
            PointerButton::Forward => Self::FORWARD,
        }
    }
}

impl<const N: usize> From<[PointerButton; N]> for ButtonMask {
    fn from(buttons: [PointerButton; N]) -> Self {
        let mut mask = Self::NONE;
        let mut i = 0;
        while i < N {
            mask = mask.union(ButtonMask::from(buttons[i]));
            i += 1;
        }
        mask
    }
}

impl std::ops::BitOr for ButtonMask {
    type Output = Self;
    fn bitor(self, rhs: Self) -> Self {
        self.union(rhs)
    }
}

impl std::ops::BitAnd for ButtonMask {
    type Output = Self;
    fn bitand(self, rhs: Self) -> Self {
        self.intersection(rhs)
    }
}

impl std::ops::BitOrAssign for ButtonMask {
    fn bitor_assign(&mut self, rhs: Self) {
        self.0 |= rhs.0;
    }
}

impl std::ops::BitAndAssign for ButtonMask {
    fn bitand_assign(&mut self, rhs: Self) {
        self.0 &= rhs.0;
    }
}

impl Default for ButtonMask {
    fn default() -> Self {
        Self::PRIMARY
    }
}

/// Keyboard key identifiers.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum Key {
    Space,
    Enter,
    Escape,
    Tab,
    Backspace,
    Delete,
    Insert,
    ArrowUp,
    ArrowDown,
    ArrowLeft,
    ArrowRight,
    Home,
    End,
    PageUp,
    PageDown,
    // Letters
    A,
    B,
    C,
    D,
    E,
    F,
    G,
    H,
    I,
    J,
    K,
    L,
    M,
    N,
    O,
    P,
    Q,
    R,
    S,
    T,
    U,
    V,
    W,
    X,
    Y,
    Z,
    // Function keys
    F1,
    F2,
    F3,
    F4,
    F5,
    F6,
    F7,
    F8,
    F9,
    F10,
    F11,
    F12,
    F13,
    F14,
    F15,
    F16,
    F17,
    F18,
    F19,
    F20,
    F21,
    F22,
    F23,
    F24,
    // Other
    /// Caps Lock. Delivered as a discrete key press/release (winit's
    /// `ModifiersState` does not carry lock state), so consumers that
    /// need the *active* lock state track it themselves on the
    /// key-down edge. See `WindowState::caps_lock`.
    CapsLock,
    /// The dedicated context-menu key: `VK_APPS` on Windows (the key between
    /// the right Alt and the right Ctrl on most PC layouts), `keysyms::Menu` on
    /// X11 and Wayland.
    ///
    /// **macOS never produces it.** Its keyboards have no such key and
    /// `winit-0.30.13`'s AppKit backend references the variant zero times, so
    /// on that platform the only keyboard route to a context menu is a chord.
    /// See the dispatcher's context-menu handling for the chords Teksilo
    /// reserves.
    ContextMenu,
    Character(char),
}

impl Key {
    /// Returns the character this key represents, if any.
    /// Maps `Key::A`..`Key::Z` to `'a'`..`'z'` (lowercase) and
    /// `Key::Character(ch)` to `ch`.
    pub fn to_char(&self) -> Option<char> {
        match self {
            Key::A => Some('a'),
            Key::B => Some('b'),
            Key::C => Some('c'),
            Key::D => Some('d'),
            Key::E => Some('e'),
            Key::F => Some('f'),
            Key::G => Some('g'),
            Key::H => Some('h'),
            Key::I => Some('i'),
            Key::J => Some('j'),
            Key::K => Some('k'),
            Key::L => Some('l'),
            Key::M => Some('m'),
            Key::N => Some('n'),
            Key::O => Some('o'),
            Key::P => Some('p'),
            Key::Q => Some('q'),
            Key::R => Some('r'),
            Key::S => Some('s'),
            Key::T => Some('t'),
            Key::U => Some('u'),
            Key::V => Some('v'),
            Key::W => Some('w'),
            Key::X => Some('x'),
            Key::Y => Some('y'),
            Key::Z => Some('z'),
            Key::Character(ch) => Some(*ch),
            _ => None,
        }
    }

    /// The text the platform attaches to this key, for the handful of named
    /// keys that carry any. Mirrors winit's `NamedKey::to_text`, which is
    /// where these values reach the app from.
    ///
    /// Worth knowing because it is surprising: Escape arrives carrying
    /// U+001B, so a widget that reads `KeyDown::text` sees text on a key
    /// nobody thinks of as text. A `TextInputField` used to filter that
    /// control character out, read the empty result as "input rejected" and
    /// swallow the key — which is how Escape stopped bubbling out of a
    /// focused field.
    ///
    /// Character keys are deliberately absent: `Key::A` is `None` here, and
    /// the way to simulate typing is `type_text`, which already sends text.
    /// The gap this closes is only the surprising one.
    pub fn to_text(&self) -> Option<&'static str> {
        match self {
            Key::Enter => Some("\r"),
            Key::Backspace => Some("\u{8}"),
            Key::Tab => Some("\t"),
            Key::Space => Some(" "),
            Key::Escape => Some("\u{1b}"),
            _ => None,
        }
    }
}

/// Keyboard modifier state.
#[derive(
    Debug, Clone, Copy, PartialEq, Eq, Hash, Default, serde::Serialize, serde::Deserialize,
)]
pub struct Modifiers {
    bits: u8,
}

impl Modifiers {
    pub const NONE: Modifiers = Modifiers { bits: 0 };
    pub const CTRL: Modifiers = Modifiers { bits: 1 };
    pub const SHIFT: Modifiers = Modifiers { bits: 2 };
    pub const ALT: Modifiers = Modifiers { bits: 4 };
    pub const SUPER: Modifiers = Modifiers { bits: 8 };

    /// The **primary accelerator** modifier for this platform: [`SUPER`]
    /// (Command, ⌘) on macOS, [`CTRL`] everywhere else.
    ///
    /// Desktop platforms disagree about which physical key carries application
    /// accelerators, and on macOS the disagreement is not cosmetic: Control is
    /// reserved there for the text system and for the secondary click, while ⌘
    /// is what a user presses for Save, Copy or Find. Code that hard-codes
    /// [`CTRL`] to mean "the accelerator" therefore listens to the wrong key on
    /// one of the three desktop platforms.
    ///
    /// Compare against this constant (or call [`Modifiers::command`]) and the
    /// same code means Ctrl+A on Windows and Linux and ⌘A on macOS. This
    /// mirrors Qt's `Qt::CTRL`, which likewise resolves to ⌘ on macOS, and the
    /// convention the native menu bar already applies when it turns a declared
    /// chord into an `NSMenuItem` key equivalent.
    ///
    /// [`SUPER`]: Modifiers::SUPER
    /// [`CTRL`]: Modifiers::CTRL
    pub const COMMAND: Modifiers = if cfg!(target_os = "macos") {
        Self::SUPER
    } else {
        Self::CTRL
    };

    pub fn empty() -> Self {
        Self::NONE
    }

    pub fn ctrl(self) -> bool {
        self.bits & 1 != 0
    }

    pub fn shift(self) -> bool {
        self.bits & 2 != 0
    }

    pub fn alt(self) -> bool {
        self.bits & 4 != 0
    }

    pub fn super_key(self) -> bool {
        self.bits & 8 != 0
    }

    /// Whether the platform's primary accelerator modifier
    /// ([`Modifiers::COMMAND`]) is held: Command (⌘) on macOS, Control
    /// everywhere else.
    ///
    /// Use this instead of [`ctrl`](Self::ctrl) wherever the chord means "the
    /// accelerator" — select-all, the discontiguous-selection click, jump to
    /// the end of a list. Keep [`ctrl`](Self::ctrl) for the chords that really
    /// are Control on every platform, macOS included: Ctrl+Tab cycles tabs
    /// there too (⌘Tab belongs to the application switcher and never reaches
    /// an app).
    pub fn command(self) -> bool {
        self.contains(Self::COMMAND)
    }

    /// Whether every modifier in `other` is held.
    pub fn contains(self, other: Modifiers) -> bool {
        self.bits & other.bits == other.bits
    }

    /// These modifiers with `other` removed.
    pub fn without(self, other: Modifiers) -> Modifiers {
        Modifiers {
            bits: self.bits & !other.bits,
        }
    }

    /// These modifiers with a declared `CTRL` reinterpreted as the platform's
    /// primary accelerator — see [`Modifiers::COMMAND`] and
    /// [`KeyStroke::with_command_convention`](crate::shortcut::KeyStroke::with_command_convention),
    /// which is where this is applied.
    ///
    /// A no-op off macOS (where `COMMAND` *is* `CTRL`), and a no-op for a chord
    /// that already names `SUPER` explicitly: `Ctrl+Super` stays ⌃⌘, a genuine
    /// two-modifier chord, rather than collapsing to one.
    pub fn with_command_convention(self) -> Modifiers {
        self.with_command_convention_using(Self::COMMAND)
    }

    /// The platform-parameterised core of
    /// [`with_command_convention`](Self::with_command_convention). Split out so
    /// the macOS branch is exercised by tests running on any host — the whole
    /// point of the convention is behaviour a Linux CI cannot otherwise see.
    ///
    /// `pub(crate)` rather than private because the same split continues up the
    /// stack: [`KeyStroke`](crate::shortcut::KeyStroke) and
    /// [`Shortcut`](crate::shortcut::Shortcut) each carry a `_using` twin that
    /// bottoms out here, so a shortcut's resolution can be asked "as macOS
    /// would read it" from a Linux host without restating the rule.
    pub(crate) fn with_command_convention_using(self, command: Modifiers) -> Modifiers {
        if self.ctrl() && !self.super_key() {
            self.without(Self::CTRL) | command
        } else {
            self
        }
    }
}

impl std::fmt::Display for Key {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Key::Space => f.write_str("Space"),
            Key::Enter => f.write_str("Enter"),
            Key::Escape => f.write_str("Esc"),
            Key::Tab => f.write_str("Tab"),
            Key::Backspace => f.write_str("Backspace"),
            Key::Delete => f.write_str("Del"),
            Key::Insert => f.write_str("Ins"),
            Key::ArrowUp => f.write_str("Up"),
            Key::ArrowDown => f.write_str("Down"),
            Key::ArrowLeft => f.write_str("Left"),
            Key::ArrowRight => f.write_str("Right"),
            Key::Home => f.write_str("Home"),
            Key::End => f.write_str("End"),
            Key::PageUp => f.write_str("PageUp"),
            Key::PageDown => f.write_str("PageDown"),
            Key::A => f.write_str("A"),
            Key::B => f.write_str("B"),
            Key::C => f.write_str("C"),
            Key::D => f.write_str("D"),
            Key::E => f.write_str("E"),
            Key::F => f.write_str("F"),
            Key::G => f.write_str("G"),
            Key::H => f.write_str("H"),
            Key::I => f.write_str("I"),
            Key::J => f.write_str("J"),
            Key::K => f.write_str("K"),
            Key::L => f.write_str("L"),
            Key::M => f.write_str("M"),
            Key::N => f.write_str("N"),
            Key::O => f.write_str("O"),
            Key::P => f.write_str("P"),
            Key::Q => f.write_str("Q"),
            Key::R => f.write_str("R"),
            Key::S => f.write_str("S"),
            Key::T => f.write_str("T"),
            Key::U => f.write_str("U"),
            Key::V => f.write_str("V"),
            Key::W => f.write_str("W"),
            Key::X => f.write_str("X"),
            Key::Y => f.write_str("Y"),
            Key::Z => f.write_str("Z"),
            Key::F1 => f.write_str("F1"),
            Key::F2 => f.write_str("F2"),
            Key::F3 => f.write_str("F3"),
            Key::F4 => f.write_str("F4"),
            Key::F5 => f.write_str("F5"),
            Key::F6 => f.write_str("F6"),
            Key::F7 => f.write_str("F7"),
            Key::F8 => f.write_str("F8"),
            Key::F9 => f.write_str("F9"),
            Key::F10 => f.write_str("F10"),
            Key::F11 => f.write_str("F11"),
            Key::F12 => f.write_str("F12"),
            Key::F13 => f.write_str("F13"),
            Key::F14 => f.write_str("F14"),
            Key::F15 => f.write_str("F15"),
            Key::F16 => f.write_str("F16"),
            Key::F17 => f.write_str("F17"),
            Key::F18 => f.write_str("F18"),
            Key::F19 => f.write_str("F19"),
            Key::F20 => f.write_str("F20"),
            Key::F21 => f.write_str("F21"),
            Key::F22 => f.write_str("F22"),
            Key::F23 => f.write_str("F23"),
            Key::F24 => f.write_str("F24"),
            Key::CapsLock => f.write_str("CapsLock"),
            Key::ContextMenu => f.write_str("Menu"),
            Key::Character(c) => write!(f, "{}", c.to_uppercase()),
        }
    }
}

impl std::fmt::Display for Modifiers {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        if self.ctrl() {
            f.write_str("Ctrl+")?;
        }
        if self.alt() {
            f.write_str("Alt+")?;
        }
        if self.shift() {
            f.write_str("Shift+")?;
        }
        if self.super_key() {
            // Named for the key the user is looking at. This string reaches
            // assistive tech through the accessibility tree's
            // `keyboard_shortcut`, and a Mac screen-reader user announced
            // "Super+S" for ⌘S has been told the wrong key.
            f.write_str(if cfg!(target_os = "macos") {
                "Cmd+"
            } else {
                "Super+"
            })?;
        }
        Ok(())
    }
}

impl std::ops::BitOr for Modifiers {
    type Output = Self;
    fn bitor(self, rhs: Self) -> Self {
        Modifiers {
            bits: self.bits | rhs.bits,
        }
    }
}

/// Scroll delta from mouse wheel or trackpad.
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum ScrollDelta {
    /// Line-based scrolling (mouse wheel).
    Lines { x: f32, y: f32 },
    /// Pixel-based scrolling (trackpad).
    Pixels { x: f32, y: f32 },
}

/// Where a [`WidgetEvent::ScrollIntoView`] target should come to rest on the
/// scroll container's vertical axis.
///
/// The horizontal axis is always revealed minimally — a fraction only has an
/// obvious meaning for the axis the request is *about*, and pinning a caret
/// vertically must not yank a horizontally-scrolled view sideways.
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum ScrollAlign {
    /// Scroll the least amount that makes the target fully visible, and not at
    /// all when it already is. This is what focus-driven reveals and
    /// [`EventContext::ensure_visible`](crate::widget::EventContext::ensure_visible)
    /// use, and it is the behaviour every scroll container had before
    /// alignment existed.
    Minimal,
    /// Pin the target at `f` of the way down the viewport — `0.0` flush with
    /// the top, `0.5` centred, `1.0` flush with the bottom — **whether or not
    /// it is already visible**. Being unconditional is the whole point: a
    /// typewriter-scrolling caret that only moved the view when it fell off
    /// the edge would not be pinned at all.
    ///
    /// The container still clamps to its scroll range, so a target near the
    /// start or end of the content comes to rest as close to `f` as the range
    /// allows. See [`ScrollArea::scroll_past_end`] for buying range past the
    /// end of the content so the last line can still reach the pin.
    ///
    /// [`ScrollArea::scroll_past_end`]: https://docs.rs/teksilo-widgets
    Fraction(f32),
}

/// Whether a [`WidgetEvent::ScrollIntoView`] should jump or glide.
///
/// Split out from the container's own `smooth_scrolling` setting because the
/// right answer depends on the *request*, not the container: a caret pinned on
/// every keystroke must snap (animating it is what produces the "screen
/// bouncing" typewriter-mode users complain about in other editors), while the
/// same container gliding for a page-down or a search hit reads as polish.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ScrollMotion {
    /// Jump straight to the target offset.
    Instant,
    /// Animate to the target offset, if the container has smooth scrolling
    /// enabled. Containers with `smooth_scrolling(false)` still jump.
    Smooth,
}

/// Where the text of an [`WidgetEvent::ImeCommit`] came from: which part of the
/// platform's text input system committed it.
///
/// `#[non_exhaustive]` because it is a platform input vocabulary that grows per
/// OS, like [`CancelReason`]: match with a wildcard arm.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
#[non_exhaustive]
pub enum ImeOrigin {
    /// The end of a composition the user typed, such as a CJK candidate or a
    /// dead-key accent; what winit reports as `Ime::Commit`. The default.
    #[default]
    Composition,
    /// Speech the platform's dictation recognised (macOS Dictation, Windows
    /// voice typing).
    Dictation,
    /// Text a system writing assistant produced to replace the user's (macOS
    /// Writing Tools).
    WritingTools,
    /// Text the input system inserted outside a key press and outside a
    /// composition, such as the emoji viewer or panel, AutoFill, or an accent
    /// picked from the press-and-hold popup with the mouse.
    Insertion,
}

/// Events dispatched to widgets.
#[derive(Debug, Clone)]
pub enum WidgetEvent {
    /// A button went down.
    PointerDown {
        /// Where, in the receiving widget's own coordinate space (the router
        /// localises it on delivery — see
        /// [`WidgetTree::dispatch_pointer`](crate::WidgetTree::dispatch_pointer)).
        position: Point,
        /// Which button. A direct pointer reports
        /// [`PointerButton::Primary`] for a contact.
        button: PointerButton,
        /// Modifier keys held when the press landed.
        modifiers: Modifiers,
        /// Who pressed — identity, kind, buttons, axes and timestamp.
        ///
        /// Read it through [`EventContext::pointer`](crate::widget::EventContext::pointer)
        /// or its `pointer_kind()` shorthand rather than by destructuring, so a
        /// widget that only needs "was this a finger?" does not have to name
        /// the whole struct. Defaults to
        /// [`PointerInfo::mouse`] at the epoch for every legacy construction
        /// site and for [`pointer_down`](Self::pointer_down), so a site that
        /// says nothing about pointers keeps meaning what it meant before the
        /// touch programme.
        pointer: PointerInfo,
    },
    /// A button came up.
    PointerUp {
        /// Where, in the receiving widget's own coordinate space.
        position: Point,
        /// Which button was released.
        button: PointerButton,
        /// Modifier keys held when the release landed.
        modifiers: Modifiers,
        /// Who released. See [`PointerDown::pointer`](Self::PointerDown).
        pointer: PointerInfo,
    },
    /// A pointer moved. Sent whether or not a button is held; a contact only
    /// ever moves with its button held, since a finger cannot hover.
    PointerMove {
        /// Where, in the receiving widget's own coordinate space.
        position: Point,
        /// Modifier keys held during the move.
        ///
        /// A drag decides what it means from the modifiers at the *move*, not
        /// at the press — Shift extends a selection and Ctrl makes a marquee
        /// additive from the moment the key goes down, mid-drag included.
        /// Defaults to [`Modifiers::NONE`] for
        /// [`pointer_move`](Self::pointer_move) and for a producer that tracks
        /// no modifier state.
        modifiers: Modifiers,
        /// Who moved. See [`PointerDown::pointer`](Self::PointerDown).
        pointer: PointerInfo,
    },
    /// The hover owner came onto this widget. Never sent for a contact: a
    /// finger writes no hover (see
    /// [`PointerTable::hover_owner`](crate::pointer::table::PointerTable::hover_owner)).
    PointerEnter {
        /// Who entered — a mouse, or a pen in proximity.
        pointer: PointerInfo,
    },
    /// The hover owner left this widget.
    PointerLeave {
        /// Who left. See [`PointerEnter`](Self::PointerEnter).
        pointer: PointerInfo,
    },
    Scroll {
        delta: ScrollDelta,
        /// Modifier keys held at the time of the scroll event.
        /// Defaults to `Modifiers::NONE` for synthesized events
        /// (tests, keyboard-driven scroll requests). Real-platform
        /// scroll events populate this from the platform's tracked
        /// modifier state — apps detect Ctrl-wheel-to-zoom by
        /// inspecting `modifiers.ctrl()`.
        modifiers: Modifiers,
        /// Where the pointer was when the scroll happened, in **window**-logical
        /// coordinates, or `None` when the producer has no position for it.
        ///
        /// The frame is in the name because it is the one positional field a
        /// handler receives that is *not* localised to the receiving widget
        /// (`localize_event` deliberately has no `Scroll` arm), and a widget
        /// that reads it as a local point silently lands a cell or a row out.
        /// Convert with the receiver's own bounds before using it as content
        /// coordinates.
        ///
        /// It is window-space because both of its frame-sensitive uses need it
        /// to be. The router **routes** by it — `Some` hit-tests, `None` falls
        /// back to the hovered (else focused) widget — and hit-testing is
        /// necessarily window-space. And `common/scrollable.rs`'s
        /// `handle_scroll_event` feeds it to `pan_step` →
        /// [`KineticScroller::pan`](crate::kinetic::KineticScroller::pan),
        /// whose tracker follows the *pointer*: localisation resolves against
        /// the captor's **current** bounds on every event, so a localised
        /// position would feed that tracker samples polluted by the motion of
        /// the very widget being measured.
        ///
        /// A mouse wheel has always been positionless and stays so — hover is
        /// under the cursor, so hit-testing would find the same widget anyway.
        /// A pan synthesised from a direct pointer *must* carry one, because a
        /// contact never writes hover and a positionless pan would route
        /// nowhere.
        window_position: Option<Point>,
        /// Where in a continuous scroll gesture this sample sits.
        /// [`ScrollPhase::Discrete`] — a self-contained wheel notch — for
        /// everything Teksilo produced before the touch programme.
        phase: ScrollPhase,
        /// Who scrolled. Defaults to
        /// [`PointerInfo::mouse`](crate::pointer::PointerInfo::mouse) at the
        /// epoch for every legacy construction site; a real sample carries the
        /// pointer's identity, kind and timestamp.
        pointer: PointerInfo,
    },
    /// A pointer interaction was revoked by the system rather than completed by
    /// the user — see [`CancelReason`].
    ///
    /// Distinct from [`PointerUp`](Self::PointerUp) on purpose: an Up means the
    /// user finished, so a drag drops and a tap fires; a cancel means the
    /// interaction is being taken away, so state must be unwound and nothing
    /// may activate.
    ///
    /// **Terminal**: no `PointerUp` follows for that pointer, and one that
    /// arrives anyway is swallowed. Delivered by the cancel funnel,
    /// [`WidgetTree::cancel_pointer`](crate::WidgetTree::cancel_pointer), to
    /// the widget holding the pointer — or, failing that, to the last one that
    /// accepted an event from it. A widget receives it through
    /// `.on_pointer_cancel(..)` or through its raw `on_pointer_event` hook.
    PointerCancel {
        /// Where the pointer was last seen, in **window**-logical coordinates,
        /// when the revoking path knows. A platform cancel usually carries no
        /// position at all.
        ///
        /// Window-space, and named for it, for the same reason as
        /// [`Scroll::window_position`](Self::Scroll) — but kept there by a
        /// different mechanism, worth knowing before "fixing" either. The cancel
        /// funnel delivers through the router's **non**-localising route
        /// (`dispatch_to_widget_direct`), so what puts this value in window space
        /// is simply that the funnel records the pointer table's own position
        /// verbatim; `localize_event` having no `PointerCancel` arm is true but
        /// would not matter on this path. A widget whose
        /// `PointerDown`/`Move`/`Up` handling works in local coordinates must
        /// convert before feeding this to the same sink.
        window_position: Option<Point>,
        /// Why the interaction was revoked.
        reason: CancelReason,
        /// Which pointer was revoked.
        pointer: PointerInfo,
    },
    /// A key press.
    KeyDown {
        /// The key the chord names, on every platform: Alt+A is `Key::A`. On
        /// macOS a press with Option (and neither Control nor Command) names
        /// the key without Option too, though Option composed a character
        /// from it, so an `Alt+A` shortcut fires there as elsewhere. One
        /// exception: Option and Shift with any key but an ASCII letter (a
        /// digit, punctuation, a Cyrillic or Greek letter) keep the composed
        /// character as their key.
        key: Key,
        /// The modifiers held.
        modifiers: Modifiers,
        /// What the press typed, if anything: on macOS the character Option
        /// composed ("å" for Option+A). `None` for a command chord (Control
        /// without Alt, Super) and for a key that types nothing.
        text: Option<String>,
    },
    /// A key release.
    KeyUp {
        /// The key the chord names, as for [`WidgetEvent::KeyDown`].
        key: Key,
        /// The modifiers held.
        modifiers: Modifiers,
    },
    /// One update of the platform input method's composition (preedit).
    ImeComposition {
        /// The composition's current text. Empty ends the composition.
        text: String,
        /// The caret or selection inside `text`, in byte offsets of `text`.
        cursor: Option<std::ops::Range<usize>>,
        /// The range of the focused field's text (its character offsets) the
        /// composition takes the place of, when the input method re-marks
        /// text already in the field (Korean Hanja conversion,
        /// reconversion). Sent with the composition's first update; the
        /// field removes that text and shows the composition where it was,
        /// and puts it back if the composition is cancelled. `None` shows
        /// the composition at the selection.
        replacement: Option<std::ops::Range<usize>>,
    },
    /// Text the platform's input system committed into the focused field.
    ImeCommit {
        /// The committed text.
        text: String,
        /// Which part of the input system committed it.
        origin: ImeOrigin,
        /// The range of the focused field's text this commit replaces, in that
        /// field's character (Unicode scalar) offsets, when the input system
        /// named one (a dictation correction, a Writing Tools replacement).
        /// `None` replaces the selection, or inserts at the caret when there
        /// is none.
        replacement: Option<std::ops::Range<usize>>,
    },
    FocusGained {
        origin: crate::focus::FocusOrigin,
    },
    FocusLost,
    AccessAction {
        action: accesskit::Action,
        target: Option<crate::widget_id::WidgetId>,
        /// Raw AccessKit NodeId from the original `ActionRequest`.
        /// May be a synthetic (widget-emitted child) NodeId — use
        /// `crate::accessibility::is_synthetic` to distinguish it
        /// from a widget-derived NodeId. The widget that registered
        /// the parent (retrieved via `tree.widget_for_synthetic`)
        /// is the one set in `target`.
        target_node: accesskit::NodeId,
        /// Payload carried by the `ActionRequest`. For
        /// `Action::SetTextSelection` this is
        /// `ActionData::SetTextSelection(TextSelection)`, for
        /// `Action::SetValue` it's `ActionData::Value(Box<str>)`,
        /// for scroll actions it carries scroll offsets, etc.
        /// Widgets that declare these actions must read the payload
        /// to honour screen-reader-initiated requests.
        data: Option<accesskit::ActionData>,
    },
    /// Dispatched by the framework to a clipping ancestor when a child
    /// gains focus but is outside the viewport. The scroll area adjusts
    /// its offset to make the target bounds visible, with an optional
    /// margin around the target.
    ///
    /// `target_bounds` is where the **last layout** put the target (arena
    /// bounds), so a handler converts it to content space with the offset
    /// that layout placed its content at, and compares it with its **live**
    /// viewport (or the offset a running tween is heading for). The two differ
    /// when something scrolled the container since that layout: the focus
    /// follow ahead of a handler's own `ensure_visible`, a wheel notch, an
    /// offset written by the application, a glide. A container that marks
    /// itself with `BuildContext::judge_reveals_live` is sent the event even
    /// when the target looks visible from the laid-out bounds, so it must
    /// move only as far as the target needs, and answer `Ignored` when it
    /// does not move. `ScrollArea` and `GridView` are marked. A `SceneView`
    /// is not: the walk tests its target through the live camera transform
    /// already. The horizontal conversion assumes left-to-right placement;
    /// `ScrollArea` does not mirror it for right-to-left content.
    ScrollIntoView {
        target_bounds: Rect,
        /// Extra margin (in logical pixels) to keep around the target
        /// when scrolling it into view. Defaults to 0.0.
        margin: f32,
        /// Where the target should end up on the scroll container's
        /// **vertical** axis. [`ScrollAlign::Minimal`] (the default, and what
        /// every focus-driven reveal uses) only scrolls when the target is not
        /// already fully visible; [`ScrollAlign::Fraction`] *pins* it to a
        /// fixed height in the viewport whether or not it was already visible.
        align: ScrollAlign,
        /// Whether the container should jump to the new offset or glide to it.
        /// See [`ScrollMotion`].
        motion: ScrollMotion,
        /// Optional back-channel for the handling scroll container to report
        /// how far the target moves from where `target_bounds` puts it
        /// (`(dx, dy)` in content pixels): the move from the offset the last
        /// layout placed its content at, which includes a move earlier in the
        /// same turn even when this one moves nothing. When
        /// several nested scroll containers must each reveal the same target,
        /// the ancestor walk (`scroll_rect_into_view`) reads this after
        /// dispatching to an inner container and shifts `target_bounds` by the
        /// negated delta before asking the next (outer) one — so the outer sees
        /// where the target will land once the inner's (deferred) scroll
        /// applies, not its pre-scroll position. `None` disables reporting (the
        /// nested-reveal refinement is unavailable). A handler that ignores it
        /// still works for the common single-container case.
        ///
        /// `Arc<Mutex<..>>` (not `Rc<Cell<..>>`) so `WidgetEvent` stays `Send`
        /// — some events are posted across threads. This one is only ever
        /// touched on the dispatch thread, so the lock is always uncontended.
        applied_scroll: Option<std::sync::Arc<std::sync::Mutex<teksilo_canvas::Point>>>,
    },
    /// A recognized gesture event, routed through the same preview/bubble system.
    Gesture {
        gesture: GestureEvent,
    },
}

impl WidgetEvent {
    /// An [`ImeCommit`](Self::ImeCommit) of `text` from a composition
    /// ([`ImeOrigin::Composition`]) that names no range to replace.
    pub fn ime_commit(text: impl Into<String>) -> Self {
        Self::ImeCommit {
            text: text.into(),
            origin: ImeOrigin::Composition,
            replacement: None,
        }
    }

    /// An [`ImeComposition`](Self::ImeComposition) update that takes the
    /// place of no existing text (`replacement` is `None`).
    pub fn ime_composition(
        text: impl Into<String>,
        cursor: Option<std::ops::Range<usize>>,
    ) -> Self {
        Self::ImeComposition {
            text: text.into(),
            cursor,
            replacement: None,
        }
    }

    /// A wheel notch with no position — routed by the hovered (else focused)
    /// widget, exactly as every scroll in Teksilo was before the touch
    /// programme.
    ///
    /// It exists so that the three fields [`Scroll`](Self::Scroll) gained cost
    /// each of its construction sites one line rather than five. The pointer
    /// defaults to
    /// [`PointerInfo::mouse`] at [`EventTime::ZERO`]: a free constructor has no
    /// tree and therefore no clock, and nothing reads the timestamp of a
    /// legacy-constructed event. A sample that has a real time enters through
    /// [`WidgetTree::dispatch_scroll`](crate::WidgetTree::dispatch_scroll)
    /// instead.
    pub fn scroll(delta: ScrollDelta, modifiers: Modifiers) -> Self {
        Self::Scroll {
            delta,
            modifiers,
            window_position: None,
            phase: ScrollPhase::Discrete,
            pointer: PointerInfo::mouse(EventTime::ZERO),
        }
    }

    /// A wheel notch routed by hit test at `position` rather than by hover.
    ///
    /// Use this where the producer genuinely knows where the pointer was; a
    /// mouse-wheel translator should keep using [`scroll`](Self::scroll), whose
    /// hover routing is what it has always had.
    pub fn scroll_at(delta: ScrollDelta, modifiers: Modifiers, position: Point) -> Self {
        Self::Scroll {
            delta,
            modifiers,
            window_position: Some(position),
            phase: ScrollPhase::Discrete,
            pointer: PointerInfo::mouse(EventTime::ZERO),
        }
    }

    /// A mouse press: [`PointerInfo::mouse`] at the epoch.
    ///
    /// This and its siblings are why adding `pointer` to the five `Pointer*`
    /// variants was a one-line-per-site sweep rather than a rewrite. Use them
    /// wherever the producer genuinely describes a mouse — every test that is
    /// pinning mouse behaviour, and every synthesizer that has no pointer of
    /// its own. A producer that *does* know which pointer it speaks for must
    /// write the variant out and thread the real [`PointerInfo`], or
    /// `ctx.pointer_kind()` reads `Mouse` for a finger and every direct-pointer
    /// branch in the framework silently takes the indirect path.
    pub fn pointer_down(position: Point, button: PointerButton, modifiers: Modifiers) -> Self {
        Self::PointerDown {
            position,
            button,
            modifiers,
            pointer: PointerInfo::mouse(EventTime::ZERO),
        }
    }

    /// A mouse release. See [`pointer_down`](Self::pointer_down).
    pub fn pointer_up(position: Point, button: PointerButton, modifiers: Modifiers) -> Self {
        Self::PointerUp {
            position,
            button,
            modifiers,
            pointer: PointerInfo::mouse(EventTime::ZERO),
        }
    }

    /// A mouse move with no modifiers held. See
    /// [`pointer_down`](Self::pointer_down); use
    /// [`pointer_move_with`](Self::pointer_move_with) where the producer tracks
    /// modifier state, since a drag reads Shift and Ctrl from the *move*.
    pub fn pointer_move(position: Point) -> Self {
        Self::pointer_move_with(position, Modifiers::NONE)
    }

    /// A mouse move carrying tracked modifier state. See
    /// [`pointer_down`](Self::pointer_down).
    pub fn pointer_move_with(position: Point, modifiers: Modifiers) -> Self {
        Self::PointerMove {
            position,
            modifiers,
            pointer: PointerInfo::mouse(EventTime::ZERO),
        }
    }

    /// The mouse entered a widget. See [`pointer_down`](Self::pointer_down).
    pub fn pointer_enter() -> Self {
        Self::PointerEnter {
            pointer: PointerInfo::mouse(EventTime::ZERO),
        }
    }

    /// The mouse left a widget. See [`pointer_down`](Self::pointer_down).
    pub fn pointer_leave() -> Self {
        Self::PointerLeave {
            pointer: PointerInfo::mouse(EventTime::ZERO),
        }
    }
}

/// The result of handling an event.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum EventResponse {
    /// The event was handled; stop propagation.
    Handled,
    /// The event was not handled; let it bubble.
    Ignored,
}

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

    // The convention itself, exercised on both platform settings from any host.
    // `Modifiers::COMMAND` resolves at compile time, so a Linux CI would
    // otherwise only ever see half of what this rule does — and the half it
    // cannot see is the one the rule exists for.

    #[test]
    fn command_convention_rewrites_a_bare_ctrl_on_macos() {
        let mac = Modifiers::CTRL.with_command_convention_using(Modifiers::SUPER);
        assert_eq!(mac, Modifiers::SUPER);

        let mac =
            (Modifiers::CTRL | Modifiers::SHIFT).with_command_convention_using(Modifiers::SUPER);
        assert_eq!(mac, Modifiers::SUPER | Modifiers::SHIFT);
    }

    #[test]
    fn command_convention_is_a_no_op_where_command_is_ctrl() {
        for m in [
            Modifiers::CTRL,
            Modifiers::CTRL | Modifiers::SHIFT,
            Modifiers::ALT,
            Modifiers::NONE,
            Modifiers::SUPER,
        ] {
            assert_eq!(m.with_command_convention_using(Modifiers::CTRL), m);
        }
    }

    #[test]
    fn command_convention_leaves_an_explicit_super_alone() {
        // A chord that already names Super is a deliberate ⌘ chord, and
        // `Ctrl+Super` is a genuine two-modifier chord — neither collapses.
        assert_eq!(
            Modifiers::SUPER.with_command_convention_using(Modifiers::SUPER),
            Modifiers::SUPER
        );
        let both = Modifiers::CTRL | Modifiers::SUPER;
        assert_eq!(both.with_command_convention_using(Modifiers::SUPER), both);
    }

    #[test]
    fn command_convention_is_idempotent() {
        for command in [Modifiers::CTRL, Modifiers::SUPER] {
            for m in [
                Modifiers::CTRL,
                Modifiers::CTRL | Modifiers::SHIFT | Modifiers::ALT,
                Modifiers::SUPER,
                Modifiers::NONE,
            ] {
                let once = m.with_command_convention_using(command);
                assert_eq!(once.with_command_convention_using(command), once);
            }
        }
    }

    #[test]
    fn command_predicate_follows_the_platform() {
        // Whichever platform this runs on, `COMMAND` is one of the two, and
        // `command()` tracks exactly it.
        assert!(Modifiers::COMMAND.command());
        assert!(!Modifiers::ALT.command());
        assert!((Modifiers::COMMAND | Modifiers::SHIFT).command());

        if cfg!(target_os = "macos") {
            assert_eq!(Modifiers::COMMAND, Modifiers::SUPER);
            assert!(!Modifiers::CTRL.command());
        } else {
            assert_eq!(Modifiers::COMMAND, Modifiers::CTRL);
            assert!(!Modifiers::SUPER.command());
        }
    }

    #[test]
    fn contains_requires_every_named_modifier() {
        let cs = Modifiers::CTRL | Modifiers::SHIFT;
        assert!(cs.contains(Modifiers::CTRL));
        assert!(cs.contains(cs));
        assert!(!cs.contains(Modifiers::CTRL | Modifiers::ALT));
        assert!(cs.contains(Modifiers::NONE));
    }

    #[test]
    fn without_clears_only_the_named_modifiers() {
        let all = Modifiers::CTRL | Modifiers::SHIFT | Modifiers::SUPER;
        assert_eq!(
            all.without(Modifiers::SUPER),
            Modifiers::CTRL | Modifiers::SHIFT
        );
        assert_eq!(all.without(Modifiers::ALT), all);
    }
}

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

    #[test]
    fn ime_composition_constructor_replaces_nothing() {
        match WidgetEvent::ime_composition("x", Some(0..1)) {
            WidgetEvent::ImeComposition {
                text,
                cursor,
                replacement,
            } => {
                assert_eq!(text, "x");
                assert_eq!(cursor, Some(0..1));
                assert!(replacement.is_none());
            }
            other => panic!("unexpected {other:?}"),
        }
    }

    #[test]
    fn ime_commit_constructor_is_a_plain_composition_commit() {
        match WidgetEvent::ime_commit("x") {
            WidgetEvent::ImeCommit {
                text,
                origin,
                replacement,
            } => {
                assert_eq!(text, "x");
                assert_eq!(origin, ImeOrigin::Composition);
                assert!(replacement.is_none());
            }
            other => panic!("unexpected {other:?}"),
        }
    }
}