teksilo_core/widget_tree/

query_impl.rs

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

use super::*;

impl WidgetTree {
    /// Get an immutable reference to a widget node (for internal use).
    #[allow(dead_code)]
    pub(crate) fn arena_get(&self, id: WidgetId) -> Option<&crate::arena::WidgetNode> {
        self.arena.get(id)
    }

    pub fn bounds(&self, id: WidgetId) -> Rect {
        self.arena.bounds(id)
    }

    /// The point `id`'s handlers receive for a window-logical point: the
    /// conversion the dispatcher applies to every pointer position before a
    /// handler of `id` sees it, transform scopes above and on `id` undone.
    ///
    /// For most widgets that is relative to the widget's top-left. A widget
    /// that owns a content transform (a `SceneView`) maps its content itself,
    /// so its handlers receive its parent's space instead, and so does this.
    /// With no transform anywhere above `id` it is `window_point` minus the
    /// widget's origin.
    ///
    /// The window-logical positions a handler is handed as such —
    /// [`WidgetEvent::Scroll`]'s and [`WidgetEvent::PointerCancel`]'s
    /// `window_position`, [`EventContext::coalesced`](crate::widget::EventContext::coalesced) —
    /// convert inside the handler with
    /// [`EventContext::to_local`](crate::widget::EventContext::to_local).
    pub fn window_to_local(&self, id: WidgetId, window_point: Point) -> Point {
        self.arena.local_pointer_position(id, window_point)
    }

    /// The window-logical point whose position for `id`'s handlers is
    /// `local`: the inverse of [`window_to_local`](Self::window_to_local).
    ///
    /// What aims input at a point inside a widget, exact under a `Scale`, a
    /// `Rotate` or a `SceneView` where adding the widget's origin is not:
    /// a press sent at `local_to_window(id, p)` reaches `id`'s handlers at `p`
    /// (to rounding). Where a transform above `id` is singular the subtree is
    /// collapsed and nothing can aim inside it; both conversions then apply no
    /// transform, as the dispatcher does, and stay each other's inverse.
    pub fn local_to_window(&self, id: WidgetId, local: Point) -> Point {
        self.arena.local_frame(id).to_window(local)
    }

    /// Last known position of the **primary** pointer, refreshed by
    /// every positioned event (`PointerDown` / `PointerMove` /
    /// `PointerUp`) rather than by moves alone. Used by the
    /// safe-triangle submenu hover gate to compare the cursor
    /// trajectory against the open submenu's bounds without
    /// requiring the gate's evaluation site to receive a fresh
    /// `PointerMove` itself.
    pub fn last_pointer_position(&self) -> Option<teksilo_canvas::Point> {
        self.pointers.primary().map(|e| e.position)
    }

    /// Where a *named* pointer is, in window-logical coordinates.
    ///
    /// `None` if that pointer is not live. The per-pointer companion to
    /// [`last_pointer_position`](Self::last_pointer_position), which reports
    /// the primary.
    pub fn pointer_position(
        &self,
        pointer: crate::pointer::PointerId,
    ) -> Option<teksilo_canvas::Point> {
        self.pointers.get(pointer).map(|e| e.position)
    }

    /// The widget holding `pointer`'s capture.
    ///
    /// Capture is per pointer: two contacts hold independent captures, and
    /// each is released only by its own Up or Cancel.
    pub fn captured_by(&self, pointer: crate::pointer::PointerId) -> Option<WidgetId> {
        self.pointers.get(pointer).and_then(|e| e.captured_by)
    }

    /// The widget holding the **primary** pointer's capture — the singular
    /// view of capture, and for a mouse-only machine the whole story.
    pub fn pointer_captured_by(&self) -> Option<WidgetId> {
        self.pointers.primary().and_then(|e| e.captured_by)
    }

    /// Every live pointer.
    ///
    /// A mouse appears once it has produced a sample and stays for the life of
    /// the tree (it never lifts); a contact appears at its press and is gone
    /// after its Up or Cancel.
    pub fn live_pointers(&self) -> impl Iterator<Item = crate::pointer::PointerInfo> + '_ {
        self.pointers.iter().map(|e| e.info)
    }

    /// Teksilo's single pointer — the one backing
    /// [`hovered`](Self::hovered) and
    /// [`last_pointer_position`](Self::last_pointer_position). A mouse wins
    /// the role whenever one is live; failing that, the oldest pointer does.
    ///
    /// Not the same thing as
    /// [`PointerInfo::primary`](crate::pointer::PointerInfo::primary), which
    /// is the W3C per-kind flag and can be true for two pointers at once.
    pub fn primary_pointer(&self) -> Option<crate::pointer::PointerInfo> {
        self.pointers.primary().map(|e| e.info)
    }

    /// The most recent hovering-capable pointer — a mouse, or a pen in
    /// proximity. Hover, the cursor and tooltip dwell all follow it, and a
    /// touch contact is never it.
    pub fn hover_owner(&self) -> Option<crate::pointer::PointerInfo> {
        self.pointers.hover_owner().map(|e| e.info)
    }

    /// Borrow the widget at `id` as `&dyn Any` for concrete-type
    /// introspection. Uses the `Widget::as_any` hook — widgets that
    /// haven't opted in return `None`. Primarily for tests that need
    /// to inspect a widget's private Signal state.
    pub fn widget_as_any(&self, id: WidgetId) -> Option<&dyn std::any::Any> {
        self.arena.get(id).and_then(|node| node.widget.as_any())
    }

    /// Mutable variant of [`widget_as_any`](Self::widget_as_any).
    /// Widgets opt in by overriding `Widget::as_any_mut`. Used by
    /// tests that need to mutate widget state post-layout (e.g.
    /// declaring a logical AT parent on a `SceneView` after the
    /// arena allocated the inner widget's `WidgetId`).
    pub fn widget_as_any_mut(&mut self, id: WidgetId) -> Option<&mut dyn std::any::Any> {
        self.arena
            .get_mut(id)
            .and_then(|node| node.widget.as_any_mut())
    }

    pub fn children(&self, id: WidgetId) -> Vec<WidgetId> {
        self.arena.children(id).to_vec()
    }

    /// Root widget ids of the arena (the entry points for a full widget-tree
    /// walk). Mirrors what the debug inspector starts its tree view from.
    pub fn roots(&self) -> Vec<WidgetId> {
        self.arena.roots()
    }

    /// The concrete Rust type name of the widget at `id` (e.g.
    /// `"teksilo_widgets::button::Button"`), or `None` if the id isn't in the
    /// arena. The same `Widget::type_name()` the inspector's tree view labels
    /// rows with.
    pub fn widget_type_name(&self, id: WidgetId) -> Option<&'static str> {
        self.arena.get(id).map(|n| n.widget.type_name())
    }

    /// The widget at `id` formatted via its `Debug` impl — its constructor
    /// parameters / fields, the same "debug repr" the inspector's Properties
    /// tab shows. `None` if the id isn't in the arena.
    pub fn widget_debug_string(&self, id: WidgetId) -> Option<String> {
        self.arena.get(id).map(|n| format!("{:?}", n.widget))
    }

    /// Whether the widget at `id` clips its children (e.g. `ScrollArea`,
    /// `MaxSize`). `false` if the id isn't in the arena.
    pub fn widget_clips_children(&self, id: WidgetId) -> bool {
        self.arena
            .get(id)
            .map(|n| n.clips_children)
            .unwrap_or(false)
    }

    /// The most recent layout proposal applied to this tree (the size
    /// last passed to [`layout`](Self::layout) / `layout_with_ops`).
    /// Lets a settle pass re-run layout at the current size without
    /// recomputing it from a surface dimension. Returns
    /// `SizeProposal::exact(800.0, 600.0)` on a tree that was never
    /// laid out.
    pub fn last_proposal(&self) -> SizeProposal {
        self.last_proposal
    }

    /// Monotonic accessibility-tree version. Bumped in
    /// [`sync_accessibility`](Self::sync_accessibility) only when a rebuild
    /// produces a tree whose *content* actually differs from the cached one
    /// (cache hits don't bump, and a rebuild that reproduces an identical
    /// `TreeUpdate` — e.g. from a shortcut-rebind / locale invalidation —
    /// doesn't either). Saturating, so the monotonic contract holds past
    /// `u64::MAX`. Mirrors
    /// [`ShortcutRegistry::version`](crate::shortcut::ShortcutRegistry::version):
    /// poll it to detect AT-tree changes without diffing the whole
    /// `TreeUpdate`.
    pub fn at_version(&self) -> &crate::signal::Signal<u64> {
        &self.at_version
    }

    /// The live-region announcements with `seq` strictly greater than
    /// `seq`: what the platform adapters would have announced from the
    /// updates [`sync_accessibility`](Self::sync_accessibility) has returned.
    /// See [`crate::accessibility::Announcement`] for what is and is not
    /// recorded. The ring keeps the last 256, so a caller that lags far
    /// behind sees only those. Read after a `sync_accessibility` (or a
    /// settle that ends in one) to observe what the latest update said.
    ///
    /// Only a tree that [records announcements](Self::records_announcements)
    /// has anything here. A tree built with `WidgetTree::new()` does, from
    /// its first update, so a headless test reads this unchanged; the tree
    /// of a window `teksilo-app` opens does only when the automation bridge
    /// is installed.
    pub fn announcements_since(&self, seq: u64) -> Vec<crate::accessibility::Announcement> {
        self.announcement_ring.since(seq)
    }

    /// Whether this tree replays each update it hands out through
    /// `accesskit_consumer` and records what the platform adapters would
    /// announce, for [`announcements_since`](Self::announcements_since).
    /// `true` for a tree built with `WidgetTree::new()`.
    pub fn records_announcements(&self) -> bool {
        self.announcement_ring.is_recording()
    }

    /// Start or stop recording announcements.
    ///
    /// The replay costs a pass of the consumer over every node of every
    /// update, on top of the walk, and keeps a second copy of the tree, for
    /// the benefit of a reader in process: the automation bridge, or a test.
    /// `teksilo-app` turns it off on the tree of each window it opens unless
    /// the bridge is installed, so an application that nobody drives pays
    /// nothing for it. Turned on again, the tree records from its next update
    /// on: what that update already holds is taken as heard, since the
    /// updates handed out meanwhile reached whoever was listening, and the
    /// changes after it are recorded. What was recorded before stays
    /// readable either way.
    pub fn set_records_announcements(&mut self, record: bool) {
        self.announcement_ring.set_recording(record);
    }

    /// Parent widget id in the arena graph, or `None` for roots.
    pub fn parent(&self, id: WidgetId) -> Option<WidgetId> {
        self.arena.parent(id)
    }

    pub fn needs_layout(&self) -> bool {
        self.arena.any_needs_layout()
    }

    pub fn needs_paint(&self) -> bool {
        self.arena.any_needs_paint()
    }

    pub fn active_animation_count(&self) -> usize {
        self.animation_scheduler.active_count()
    }

    pub fn pending_tooltip_count(&self) -> usize {
        self.tooltips
            .iter()
            .filter(|entry| entry.overlay_id.is_none() && entry.real_hover_start.is_some())
            .count()
    }

    /// Whether there are pending idle callbacks to run.
    pub fn has_idle_work(&self) -> bool {
        !self.idle_queue.is_empty()
    }

    pub fn has_pending_modal_requests(&self) -> bool {
        !self.pending_modal_requests.is_empty()
    }

    /// Whether a modal overlay is open in this tree: a dialog presented
    /// in the window, or a command palette. A modal request still queued
    /// ([`has_pending_modal_requests`](Self::has_pending_modal_requests))
    /// does not count until it is presented.
    pub fn has_modal_overlay(&self) -> bool {
        self.overlay_manager.topmost_modal().is_some()
    }

    pub fn has_pending_modal_dismissal(&self) -> bool {
        self.pending_modal_dismissal
    }

    /// The cursor the window would show right now.
    ///
    /// This is what `teksilo-app` hands to the OS after each pointer
    /// dispatch. It is the tree's running answer, not a function of the
    /// widgets: the hovered chain's `.cursor(..)` declaration is written into
    /// it on `PointerEnter` and undone (back to `Default`) on `PointerLeave`,
    /// and a handler's `ctx.set_cursor(..)` / `ctx.release_cursor()` moves it
    /// within a dispatch. So it follows the *hover owner* (a mouse, or a pen
    /// in proximity; a touch contact never hovers), and it changes when the
    /// pointer enters or leaves a node, never on the moves in between.
    ///
    /// It can therefore go **stale**: if a node's cursor is changed (a rebuild
    /// re-declaring it, for one) under a pointer that does not move, nothing
    /// re-applies it until the next enter / leave pair. Read
    /// [`declared_cursor`](Self::declared_cursor) for what a node asks for
    /// regardless of where the pointer is.
    pub fn current_cursor(&self) -> crate::widget::CursorIcon {
        self.current_cursor
    }

    /// The cursor a node *declares* for itself, if it declares one.
    ///
    /// Reads what `.cursor(..)` (or `HandlerSet::cursor` through
    /// `BuildContext::apply_self_handlers`) recorded on the node, whatever the
    /// pointer is doing; it says nothing about a handler's `ctx.set_cursor(..)`
    /// override, which lives only in [`current_cursor`](Self::current_cursor).
    ///
    /// `None` means the node declares nothing: entering it leaves the cursor
    /// as it was. `Some(CursorIcon::Default)` is a different answer, an
    /// explicit declaration of the default cursor, which entering the node
    /// does apply. `None` for an id that is not in the tree.
    pub fn declared_cursor(&self, id: WidgetId) -> Option<crate::widget::CursorIcon> {
        self.arena.get(id).and_then(|node| node.node_cursor)
    }

    /// The widget currently under the pointer, if any. The framework
    /// updates this on `PointerMove` / hover routing; widgets that have
    /// captured the pointer or that opt out via `event_pass_through`
    /// affect what shows up here. Mirrors the hover owner's entry in the
    /// private pointer table for read-only consumers (debug inspector,
    /// layout introspection).
    pub fn hovered(&self) -> Option<WidgetId> {
        self.hovered_id()
    }

    /// The widget a *named* pointer is over.
    ///
    /// Only ever `Some` for the hover owner: a contact produces no hover, so
    /// asking a finger what it is hovering always answers `None`.
    pub fn hovered_for(&self, pointer: crate::pointer::PointerId) -> Option<WidgetId> {
        self.pointers.get(pointer).and_then(|e| e.hovered)
    }

    /// Whether any dispatch is waiting to be replayed.
    ///
    /// Always `false` outside a dispatch — the queue is drained before a
    /// top-level `dispatch_*` returns. A test asserts that; nothing else
    /// should need to ask.
    pub fn has_pending_dispatch(&self) -> bool {
        !self.pending_dispatch.is_empty()
    }

    /// Reactive handle to the kind of the pointer that most recently produced
    /// a sample — mouse, finger, stylus.
    ///
    /// The one question an adaptive affordance actually needs: whether the
    /// user is currently working by hover or by contact. Bind it rather than
    /// remembering an `on_pointer_event` purely to learn the modality.
    pub fn last_pointer_kind_signal(&self) -> crate::signal::Signal<teksilo_tokens::PointerKind> {
        self.last_pointer_kind_signal.clone()
    }

    /// Reactive handle to the hovered widget id. Cheap clone — the
    /// underlying `Signal` is shared. Set whenever `hovered` changes
    /// during dispatch, post-layout hover recovery, widget destruction,
    /// or overlay subtree dormancy. Intended for debug tooling that
    /// wants to react to hover without polling (the inspector's hover
    /// tooltip).
    pub fn hovered_signal(&self) -> crate::signal::Signal<Option<WidgetId>> {
        self.hovered_signal.clone()
    }

    /// Reactive handle to the focused widget id. Mirror of
    /// [`hovered_signal`](Self::hovered_signal) for the focus chain;
    /// drives the inspector's Focus tab without polling.
    pub fn focused_signal(&self) -> crate::signal::Signal<Option<WidgetId>> {
        self.focused_signal.clone()
    }

    /// Drain and run all pending idle callbacks with the given time budget.
    /// Called by the event loop during idle periods between frames.
    pub fn run_idle_callbacks(&mut self, budget: std::time::Duration) {
        let callbacks = self.idle_queue.drain();
        for callback in callbacks {
            callback(crate::idle::IdleDeadline::new(budget));
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::overlay::{DismissBehavior, OverlayPlacement, OverlayRequest};
    use crate::test_widgets::FillWidget;
    use crate::widget_builder::WidgetBuilder;
    use crate::{ModalCloseBehavior, ModalContent, ModalPresentation, ModalRequest};
    use std::cell::Cell;
    use std::rc::Rc;
    use teksilo_canvas::Size;

    #[derive(Debug)]
    struct FixedWidget(f32, f32);

    impl Widget for FixedWidget {
        fn layout_response(
            &self,
            _proposal: SizeProposal,
            _ctx: &LayoutContext,
        ) -> crate::widget::LayoutResponse {
            Size::new(self.0, self.1).into()
        }
    }

    #[test]
    fn destroy_removes_from_arena() {
        let mut tree = WidgetTree::new();
        let widget = tree.add(FillWidget::new().label("Gone"));
        tree.layout(SizeProposal::exact(100.0, 50.0));
        assert!(tree.find_by_label("Gone").is_some());

        tree.arena.destroy(widget);
        assert!(tree.find_by_label("Gone").is_none());
    }

    #[test]
    fn idle_callback_requested_from_event_handler() {
        let called = Rc::new(Cell::new(false));
        let called_flag = called.clone();
        let mut tree = WidgetTree::new();
        let widget = tree.add(FillWidget::new().on_tap(move |_pos, ctx| {
            let called = called_flag.clone();
            ctx.request_idle_callback(move |_deadline| {
                called.set(true);
            });
        }));
        tree.layout(SizeProposal::exact(100.0, 50.0));

        assert!(!tree.has_idle_work());

        tree.click(widget);

        assert!(tree.has_idle_work());
        assert!(!called.get());

        tree.run_idle_callbacks(std::time::Duration::from_millis(16));

        assert!(called.get());
        assert!(!tree.has_idle_work());
    }

    #[test]
    fn set_locale_from_event_handler_is_parked_not_applied() {
        let mut tree = WidgetTree::new();
        let widget = tree.add(FillWidget::new().on_tap(|_pos, ctx| {
            ctx.set_locale("fr-FR");
        }));
        tree.layout(SizeProposal::exact(100.0, 50.0));
        assert!(tree.locale().is_none());

        tree.click(widget);

        // The tree's own locale signal must NOT have been flipped — the
        // app layer is responsible for routing the switch through
        // `WindowManager::set_locale` so the `I18nManager`'s active
        // locale, version signal, and RTL direction stay in sync.
        assert_eq!(tree.locale(), None);
        // The request is parked for the app layer to drain.
        assert_eq!(
            tree.take_pending_locale_request(),
            Some("fr-FR".to_string())
        );
        // Drained exactly once.
        assert_eq!(tree.take_pending_locale_request(), None);
    }

    #[test]
    fn set_theme_from_event_handler_is_parked_not_applied() {
        use crate::ThemeAppearance;

        let mut tree = WidgetTree::new();
        // `WidgetTree::new()` starts on the light preset.
        assert_eq!(tree.theme().appearance, ThemeAppearance::Light);

        let widget = tree.add(FillWidget::new().on_tap(|_pos, ctx| {
            ctx.set_theme(crate::presets::intui::dark());
        }));
        tree.layout(SizeProposal::exact(100.0, 50.0));

        tree.click(widget);

        // The tree's own theme must NOT have been flipped inline — the app
        // layer routes the switch through `WindowManager::set_theme` so it
        // fans out to *every* window, not just this one.
        assert_eq!(tree.theme().appearance, ThemeAppearance::Light);
        // The request is parked for the app layer to drain.
        let parked = tree.take_pending_theme_request();
        assert_eq!(parked.map(|t| t.appearance), Some(ThemeAppearance::Dark));
        // Drained exactly once.
        assert!(tree.take_pending_theme_request().is_none());
    }

    #[test]
    fn idle_deadline_provides_time_budget() {
        let deadline = crate::idle::IdleDeadline::new(std::time::Duration::from_millis(100));
        assert!(!deadline.did_timeout());
        assert!(deadline.time_remaining() > std::time::Duration::ZERO);
    }

    #[test]
    fn modal_request_requested_from_event_handler() {
        let mut tree = WidgetTree::new();
        let content = tree.add(FillWidget::new().label("Modal content"));
        let trigger = tree.add(FillWidget::new().on_tap(move |_pos, ctx| {
            ctx.present_modal(
                ModalRequest::in_tree(content)
                    .presentation(ModalPresentation::InTree)
                    .close_behavior(ModalCloseBehavior::Manual),
            );
        }));
        tree.layout(SizeProposal::exact(100.0, 50.0));

        assert!(!tree.has_pending_modal_requests());

        tree.click(trigger);

        assert!(tree.has_pending_modal_requests());
        let requests = tree.drain_pending_modal_requests();
        assert_eq!(requests.len(), 1);
        assert_eq!(requests[0].source_widget, trigger);
        assert_eq!(requests[0].request.presentation, ModalPresentation::InTree);
        assert_eq!(
            requests[0].request.close_behavior,
            ModalCloseBehavior::Manual
        );
        match requests[0].request.content {
            ModalContent::ExistingWidget(id) => assert_eq!(id, content),
            ModalContent::Deferred(_) => panic!("expected ExistingWidget content"),
        }
        assert!(!tree.has_pending_modal_requests());
    }

    #[test]
    fn draining_modal_requests_clears_queue() {
        let mut tree = WidgetTree::new();
        let content = tree.add(FillWidget::new());
        let trigger = tree.add(FillWidget::new().on_tap(move |_pos, ctx| {
            ctx.present_modal(ModalRequest::in_tree(content));
        }));
        tree.layout(SizeProposal::exact(100.0, 50.0));

        tree.click(trigger);
        assert_eq!(tree.drain_pending_modal_requests().len(), 1);
        assert!(tree.drain_pending_modal_requests().is_empty());
    }

    #[test]
    fn dismiss_modal_closes_centered_overlay_for_source_widget() {
        let mut tree = WidgetTree::new();
        let trigger = tree.add(FillWidget::new().label("Trigger"));
        let modal_content = tree.add(FixedWidget(120.0, 48.0).on_tap(|_pos, ctx| {
            ctx.dismiss_modal();
        }));
        tree.layout(SizeProposal::exact(320.0, 200.0));

        tree.show_overlay(OverlayRequest::new(
            modal_content,
            trigger,
            OverlayPlacement::Centered,
            DismissBehavior::Manual,
        ));
        tree.layout(SizeProposal::exact(320.0, 200.0));

        assert_eq!(tree.active_overlays().len(), 1);

        let center = tree
            .overlay_manager()
            .topmost_modal()
            .expect("expected centered modal overlay")
            .bounds
            .center();
        tree.pointer_down_button(center, PointerButton::Primary);
        tree.pointer_up_button(center, PointerButton::Primary);

        assert!(tree.active_overlays().is_empty());
        assert!(!tree.has_pending_modal_dismissal());
    }

    #[test]
    fn dismiss_modal_without_in_tree_modal_queues_window_dismissal() {
        let mut tree = WidgetTree::new();
        let trigger = tree.add(FillWidget::new().on_tap(|_pos, ctx| {
            ctx.dismiss_modal();
        }));
        tree.layout(SizeProposal::exact(100.0, 50.0));

        assert!(!tree.has_pending_modal_dismissal());

        tree.click(trigger);

        assert!(tree.has_pending_modal_dismissal());
        assert!(tree.drain_pending_modal_dismissal());
        assert!(!tree.has_pending_modal_dismissal());
    }
}