frus_widgets/

focus.rs

//! The **focus** wrappers: which parts of a tree the keyboard can reach, and in what
//! order.
//!
//! Focus already existed here as a property of a widget — a text field is focusable, a
//! label is not — and Tab already walked the tree. What was missing is the declarative
//! surface the reference puts over it: the five wrappers that let a caller say *this
//! subtree is out of reach*, *skip this one with Tab but let a click land on it*, *these
//! come in this order*, and *resolve that order among these and nowhere else*.
//!
//! ```ignore
//! FocusTraversalGroup::new(
//!     column![
//!         FocusTraversalOrder::new(2.0, name_field),   // second, whatever the tree says
//!         FocusTraversalOrder::new(1.0, email_field),  // first
//!         ExcludeFocusTraversal::new(help_button),     // clickable, not in the order
//!     ],
//! )
//! ```
//!
//! All five are **single-child boxes** that take their child's sizing and add nothing to
//! the picture. The flags they set are *subtree-scoped*: the walk pushes them on the way
//! in and pops them on the way out, so a sibling never inherits one.
//!
//! ## The two questions Tab and a click ask separately
//!
//! [`ExcludeFocus`] removes a subtree from focus entirely — nothing in it registers a stop
//! at all. [`ExcludeFocusTraversal`] keeps the stops and takes them out of *Tab's order*:
//! a click still lands, the keyboard passes by. They are separate because the reasons are
//! separate — a panel behind a sheet is unreachable, a toolbar button is reachable but
//! does not belong in a form's keyboard order.

use frus_core::{Rect, Scene};
use frus_layout::Style;

use crate::interaction::Status;
use crate::theme::Theme;
use crate::widget::{sizing_of, Widget};

/// The shared body of all five: one child, its box, and a set of focus flags.
struct Wrapper<Msg> {
    child: Vec<Box<dyn Widget<Msg>>>,
    focusable: bool,
    descendants_focusable: bool,
    skip_traversal: bool,
    order: Option<f32>,
    group: bool,
    /// Told when the focus arrives in or leaves the subtree; see [`Focus::on_focus_change`].
    on_focus_change: Option<Box<dyn Fn(bool) -> Msg>>,
}

impl<Msg> Wrapper<Msg> {
    fn new(child: Box<dyn Widget<Msg>>) -> Self {
        Self {
            child: vec![child],
            focusable: false,
            descendants_focusable: true,
            skip_traversal: false,
            order: None,
            group: false,
            on_focus_change: None,
        }
    }
}

impl<Msg: Clone> Widget<Msg> for Wrapper<Msg> {
    fn style(&self) -> Style {
        sizing_of(self.child[0].style())
    }

    fn style_themed(&self, theme: &Theme) -> Style {
        sizing_of(self.child[0].style_themed(theme))
    }

    fn build_themed(&self, theme: &Theme) {
        self.child[0].build_themed(theme);
    }

    fn children(&self) -> &[Box<dyn Widget<Msg>>] {
        &self.child
    }

    fn paint(&self, _bounds: Rect, _status: Status, _theme: &Theme, _scene: &mut Scene) {}

    fn on_click(&self) -> Option<Msg> {
        None
    }

    fn focusable(&self) -> bool {
        self.focusable
    }

    fn descendants_focusable(&self) -> bool {
        self.descendants_focusable
    }

    fn focus_skip_traversal(&self) -> bool {
        self.skip_traversal
    }

    fn focus_order(&self) -> Option<f32> {
        self.order
    }

    fn focus_group(&self) -> bool {
        self.group
    }

    fn on_focus_change(&self, focused: bool) -> Option<Msg> {
        self.on_focus_change.as_ref().map(|make| make(focused))
    }
}

/// Makes its child a **focus stop**: somewhere Tab can land and a click can focus, even
/// when the child itself has no opinion about focus.
pub struct Focus<Msg = crate::callback::Callback>(Wrapper<Msg>);

impl<Msg> Focus<Msg> {
    /// A focus stop around `child`.
    pub fn new(child: impl Widget<Msg> + 'static) -> Self {
        let mut w = Wrapper::new(Box::new(child));
        w.focusable = true;
        Self(w)
    }

    /// Whether it can take focus at all — the reference's `canRequestFocus`. `false`
    /// leaves the subtree in place and simply stops being a stop.
    pub fn can_request_focus(mut self, can: bool) -> Self {
        self.0.focusable = can;
        self
    }

    /// Focusable by a click, passed over by Tab.
    pub fn skip_traversal(mut self) -> Self {
        self.0.skip_traversal = true;
        self
    }

    /// A message for the focus **arriving in or leaving** this subtree — the reference's
    /// `onFocusChange` (milestone 660): `true` when it, or anything inside it, now has the
    /// focus and did not, `false` the other way. A move between two widgets inside it says
    /// nothing.
    pub fn on_focus_change<R: crate::callback::IntoMsg<Msg>>(
        mut self,
        on_change: impl Fn(bool) -> R + 'static,
    ) -> Self {
        self.0.on_focus_change = Some(Box::new(crate::callback::handler1(on_change)));
        self
    }
}

/// **Nothing inside can take focus.** The subtree is still drawn and still measured; it
/// is simply not somewhere the keyboard can go.
pub struct ExcludeFocus<Msg = crate::callback::Callback>(Wrapper<Msg>);

impl<Msg> ExcludeFocus<Msg> {
    /// Puts `child` out of the keyboard's reach.
    pub fn new(child: impl Widget<Msg> + 'static) -> Self {
        let mut w = Wrapper::new(Box::new(child));
        w.descendants_focusable = false;
        Self(w)
    }
}

/// **Skipped by Tab, reachable by a click** — a different question from
/// [`ExcludeFocus`], which takes the subtree out of the keyboard's reach altogether. A
/// panel behind a sheet is unreachable; a toolbar button is reachable and simply does not
/// belong in a form's keyboard order.
pub struct ExcludeFocusTraversal<Msg = crate::callback::Callback>(Wrapper<Msg>);

impl<Msg> ExcludeFocusTraversal<Msg> {
    /// Takes `child`'s focus stops out of Tab's order.
    pub fn new(child: impl Widget<Msg> + 'static) -> Self {
        let mut w = Wrapper::new(Box::new(child));
        w.skip_traversal = true;
        Self(w)
    }
}

/// An explicit **traversal position** for a subtree, smallest first.
///
/// Ordered stops come before unordered ones, and everything without an order keeps tree
/// order — so this is a local statement rather than a rearrangement of the frame.
pub struct FocusTraversalOrder<Msg = crate::callback::Callback>(Wrapper<Msg>);

impl<Msg> FocusTraversalOrder<Msg> {
    /// Gives `child`'s focus stops the position `order`.
    pub fn new(order: f32, child: impl Widget<Msg> + 'static) -> Self {
        let mut w = Wrapper::new(Box::new(child));
        w.order = Some(order);
        Self(w)
    }
}

/// A **traversal group**: an order set inside it is resolved among its own members and
/// nowhere else, so a reordered dialog does not reshuffle the page behind it.
pub struct FocusTraversalGroup<Msg = crate::callback::Callback>(Wrapper<Msg>);

impl<Msg> FocusTraversalGroup<Msg> {
    /// Scopes `child`'s traversal order to `child`.
    pub fn new(child: impl Widget<Msg> + 'static) -> Self {
        let mut w = Wrapper::new(Box::new(child));
        w.group = true;
        Self(w)
    }
}

/// Each of the five is the same box with different flags; the delegation is mechanical
/// and identical, so it is written once.
macro_rules! delegate {
    ($($ty:ident),* $(,)?) => {$(
        impl<Msg: Clone> Widget<Msg> for $ty<Msg> {
            fn style(&self) -> Style {
                Widget::<Msg>::style(&self.0)
            }
            fn style_themed(&self, theme: &Theme) -> Style {
                Widget::<Msg>::style_themed(&self.0, theme)
            }
            fn build_themed(&self, theme: &Theme) {
                Widget::<Msg>::build_themed(&self.0, theme)
            }
            fn children(&self) -> &[Box<dyn Widget<Msg>>] {
                Widget::<Msg>::children(&self.0)
            }
            fn paint(&self, bounds: Rect, status: Status, theme: &Theme, scene: &mut Scene) {
                Widget::<Msg>::paint(&self.0, bounds, status, theme, scene)
            }
            fn on_click(&self) -> Option<Msg> {
                Widget::<Msg>::on_click(&self.0)
            }
            fn focusable(&self) -> bool {
                Widget::<Msg>::focusable(&self.0)
            }
            fn descendants_focusable(&self) -> bool {
                Widget::<Msg>::descendants_focusable(&self.0)
            }
            fn focus_skip_traversal(&self) -> bool {
                Widget::<Msg>::focus_skip_traversal(&self.0)
            }
            fn focus_order(&self) -> Option<f32> {
                Widget::<Msg>::focus_order(&self.0)
            }
            fn focus_group(&self) -> bool {
                Widget::<Msg>::focus_group(&self.0)
            }
            fn on_focus_change(&self, focused: bool) -> Option<Msg> {
                Widget::<Msg>::on_focus_change(&self.0, focused)
            }
        }
    )*};
}

delegate!(
    Focus,
    ExcludeFocus,
    ExcludeFocusTraversal,
    FocusTraversalOrder,
    FocusTraversalGroup,
);

#[cfg(test)]
mod tests {
    use super::*;
    use crate::runtime::Runtime;
    use crate::ui::build_ui;
    use crate::{Container, TextField};
    use frus_core::Size;

    #[derive(Clone, Debug, PartialEq)]
    enum Msg {
        Edited(String),
    }

    /// Three fields in a column, so there is a tree order to disturb.
    fn field(label: &str) -> TextField<Msg> {
        TextField::new(label.to_string())
            .label(label.to_string())
            .on_input(Msg::Edited)
    }

    fn order_of(root: &dyn Widget<Msg>) -> Vec<usize> {
        let ui = build_ui(
            root,
            Size::new(400.0, 400.0),
            &Runtime::default(),
            &Theme::default(),
        );
        let ids: Vec<_> = ui.focusable_ids().collect();
        ui.traversal_order()
            .iter()
            .map(|id| ids.iter().position(|x| x == id).expect("a known stop"))
            .collect()
    }

    /// Untouched, Tab follows the tree.
    #[test]
    fn tab_follows_the_tree_by_default() {
        let root = crate::column![field("a"), field("b"), field("c")];
        assert_eq!(order_of(&root), vec![0, 1, 2]);
    }

    /// An order moves a subtree without moving anything else.
    #[test]
    fn an_order_moves_only_what_it_names() {
        let root = crate::column![
            FocusTraversalOrder::new(2.0, field("a")),
            FocusTraversalOrder::new(1.0, field("b")),
            field("c"),
        ];
        // b then a, both ordered; c has no order, so it comes after them.
        assert_eq!(order_of(&root), vec![1, 0, 2]);
    }

    /// Skipped by Tab, and still a focus stop for a click.
    #[test]
    fn skipping_traversal_leaves_the_stop_where_it_was() {
        let root = crate::column![
            field("a"),
            ExcludeFocusTraversal::new(field("b")),
            field("c"),
        ];
        assert_eq!(order_of(&root), vec![0, 2], "Tab passes b by");

        let ui = build_ui(
            &root,
            Size::new(400.0, 400.0),
            &Runtime::default(),
            &Theme::default(),
        );
        assert_eq!(
            ui.focusable_ids().count(),
            3,
            "but b is still somewhere a click can land"
        );
    }

    /// Excluded outright: not a stop at all.
    #[test]
    fn an_excluded_subtree_registers_nothing() {
        let root = crate::column![field("a"), ExcludeFocus::new(field("b")), field("c")];
        let ui = build_ui(
            &root,
            Size::new(400.0, 400.0),
            &Runtime::default(),
            &Theme::default(),
        );
        assert_eq!(ui.focusable_ids().count(), 2);
        assert_eq!(order_of(&root), vec![0, 1]);
    }

    /// The flags are **subtree-scoped**: what follows an excluded subtree is not itself
    /// excluded. This is the bug the scope exists to prevent, and the one a flag set on
    /// the way in and never cleared would produce.
    #[test]
    fn the_flags_do_not_leak_to_what_comes_after() {
        let root = crate::column![
            ExcludeFocus::new(crate::column![field("a"), field("b")]),
            field("c"),
            field("d"),
        ];
        let ui = build_ui(
            &root,
            Size::new(400.0, 400.0),
            &Runtime::default(),
            &Theme::default(),
        );
        assert_eq!(ui.focusable_ids().count(), 2, "only c and d");
    }

    /// A group keeps an order to itself: the dialog reorders, the page behind it does not.
    #[test]
    fn a_group_resolves_its_order_among_its_own_members() {
        let root = crate::column![
            field("page-1"),
            FocusTraversalGroup::new(crate::column![
                FocusTraversalOrder::new(2.0, field("dialog-1")),
                FocusTraversalOrder::new(1.0, field("dialog-2")),
            ]),
            field("page-2"),
        ];
        // The page keeps tree order around a dialog that swapped its two fields.
        assert_eq!(order_of(&root), vec![0, 2, 1, 3]);
    }

    /// A `Focus` makes something focusable that had no opinion about it.
    #[test]
    fn it_makes_an_ordinary_box_a_focus_stop() {
        let plain = Container::<Msg>::new().width(40.0).height(40.0);
        assert!(!Widget::<Msg>::focusable(&plain));
        let wrapped = Focus::new(Container::<Msg>::new().width(40.0).height(40.0));
        assert!(Widget::<Msg>::focusable(&wrapped));
        assert!(!Widget::<Msg>::focusable(
            &Focus::new(Container::<Msg>::new()).can_request_focus(false)
        ));
    }
}

/// The focus arriving in and leaving a subtree (milestone 660).
#[cfg(test)]
mod focus_change_tests {
    use super::*;
    use crate::WidgetId;
    use crate::{build_ui, focus_changes, Flex, Runtime, Size, TextField};

    #[derive(Clone, Debug, PartialEq)]
    enum Msg {
        Group(bool),
        Typed,
    }

    /// A group of two fields under a `Focus`, and a third field beside it.
    fn page() -> Flex<Msg> {
        Flex::column()
            .width(300.0)
            .height(300.0)
            .child(
                Focus::new(
                    Flex::column()
                        .child(TextField::new("a").on_input(|_| Msg::Typed))
                        .child(TextField::new("b").on_input(|_| Msg::Typed)),
                )
                .skip_traversal()
                .on_focus_change(Msg::Group),
            )
            .child(TextField::new("c").on_input(|_| Msg::Typed))
    }

    /// The three fields' ids, in order: `a`, `b`, `c`.
    fn fields(page: &Flex<Msg>) -> Vec<WidgetId> {
        let ui = build_ui(
            page,
            Size::new(300.0, 300.0),
            &Runtime::default(),
            &crate::Theme::default(),
        );
        let ids: Vec<WidgetId> = ui.focusable_ids().collect();
        // The group itself is a stop too, ahead of its fields.
        assert_eq!(ids.len(), 4, "{ids:?}");
        ids[1..].to_vec()
    }

    /// **The group hears the focus arrive and leave**, and nothing for a move between its
    /// own fields.
    #[test]
    fn a_group_hears_the_focus_arrive_and_leave() {
        let page = page();
        let ids = fields(&page);
        let (a, b, c) = (Some(ids[0]), Some(ids[1]), Some(ids[2]));
        assert_eq!(
            focus_changes(&page, None, a),
            vec![Msg::Group(true)],
            "arrived"
        );
        assert_eq!(focus_changes(&page, a, b), vec![], "moved inside");
        assert_eq!(focus_changes(&page, b, c), vec![Msg::Group(false)], "left");
        assert_eq!(focus_changes(&page, c, a), vec![Msg::Group(true)]);
        assert_eq!(
            focus_changes(&page, a, None),
            vec![Msg::Group(false)],
            "cleared"
        );
        assert_eq!(focus_changes(&page, a, a), vec![], "no move");
        let gone = Some(WidgetId::ROOT.child(9));
        assert_eq!(
            focus_changes(&page, gone, a),
            vec![Msg::Group(true)],
            "a widget no longer there is not heard from"
        );
    }

    /// **The one that lost the focus hears first**, deepest first.
    #[test]
    fn the_one_that_lost_it_hears_first() {
        let nested = Flex::column()
            .width(300.0)
            .height(300.0)
            .child(
                Focus::new(TextField::new("a").on_input(|_| Msg::Typed))
                    .skip_traversal()
                    .on_focus_change(|f| if f { Msg::Group(true) } else { Msg::Typed }),
            )
            .child(
                Focus::new(TextField::new("b").on_input(|_| Msg::Typed))
                    .skip_traversal()
                    .on_focus_change(Msg::Group),
            );
        let ui = build_ui(
            &nested,
            Size::new(300.0, 300.0),
            &Runtime::default(),
            &crate::Theme::default(),
        );
        let ids: Vec<WidgetId> = ui.focusable_ids().collect();
        // [group a, a, group b, b]
        let (a, b) = (Some(ids[1]), Some(ids[3]));
        assert_eq!(
            focus_changes(&nested, a, b),
            vec![Msg::Typed, Msg::Group(true)],
            "the first group's `false`, then the second's `true`"
        );
    }

    /// **Nested groups the focus leaves hear it deepest first**, as do those it enters.
    #[test]
    fn nested_groups_hear_it_deepest_first() {
        let nested = Flex::column()
            .width(300.0)
            .height(300.0)
            .child(
                Focus::new(
                    Focus::new(TextField::new("a").on_input(|_| Msg::Typed))
                        .skip_traversal()
                        .on_focus_change(|f| Msg::Group(!f)),
                )
                .skip_traversal()
                .on_focus_change(Msg::Group),
            )
            .child(TextField::new("b").on_input(|_| Msg::Typed));
        let ui = build_ui(
            &nested,
            Size::new(300.0, 300.0),
            &Runtime::default(),
            &crate::Theme::default(),
        );
        let ids: Vec<WidgetId> = ui.focusable_ids().collect();
        // [outer, inner, a, b]
        let (a, b) = (Some(ids[2]), Some(ids[3]));
        assert_eq!(
            focus_changes(&nested, a, b),
            vec![Msg::Group(true), Msg::Group(false)],
            "the inner group (which says the opposite) first, then the outer"
        );
        assert_eq!(
            focus_changes(&nested, b, a),
            vec![Msg::Group(false), Msg::Group(true)],
            "entering: the inner first, then the outer"
        );
    }
}