teksilo_core/focus.rs
1// SPDX-License-Identifier: MPL-2.0
2// SPDX-FileCopyrightText: 2026 FernTech
3
4use teksilo_tokens::PointerKind;
5
6/// How focus was acquired.
7///
8/// Read by `:focus-visible` — a focus ring belongs to keyboard and assistive
9/// navigation, not to a click — and by anything that has to treat a finger
10/// differently from a mouse. The pointer arm carries the device that delivered
11/// the focus, because "a pointer focused this" is not one behaviour: a mouse
12/// focuses on press, a finger and a pen focus on release, and only a release
13/// that lands back on the same focusable counts.
14///
15/// `#[non_exhaustive]`: matches need a wildcard arm. Most call sites want
16/// [`is_pointer`](Self::is_pointer) rather than a match at all.
17#[non_exhaustive]
18#[derive(Debug, Clone, Copy, PartialEq, Eq)]
19pub enum FocusOrigin {
20 /// Focus gained via Tab/Shift-Tab keyboard navigation, or by any other
21 /// keystroke a widget routes into focus.
22 Keyboard,
23 /// Focus gained by pointing at the widget, with the device that did it.
24 Pointer(PointerKind),
25 /// Focus set programmatically by the application. Carries no input
26 /// modality of its own: a scripted focus leaves the focus ring exactly as
27 /// the user's last real interaction left it, which is what
28 /// `:focus-visible` does for `element.focus()`.
29 Programmatic,
30 /// Focus moved by assistive technology — a screen reader's
31 /// [`Action::Focus`](accesskit::Action::Focus), or an automation client
32 /// standing in for one. Reveals the focus ring: the user is navigating,
33 /// they are simply not doing it with a key.
34 Accessibility,
35}
36
37impl FocusOrigin {
38 /// Focus arrived by pointer, from a site that cannot know which device
39 /// delivered it.
40 ///
41 /// A control deriving its own origin from hover or from the tree's
42 /// input-modality signal — rather than from the
43 /// [`FocusGained`](crate::event::WidgetEvent::FocusGained) it was handed —
44 /// knows only that the keyboard was not involved. It says so with
45 /// [`PointerKind::Unknown`] instead of naming a device it never saw, so a
46 /// consumer reading [`pointer_kind`](Self::pointer_kind) is never told a
47 /// finger was a mouse.
48 pub const POINTER: Self = Self::Pointer(PointerKind::Unknown);
49
50 /// Whether focus arrived by pointing at the widget.
51 ///
52 /// The predicate that replaced `== FocusOrigin::Pointer`: a pointer origin
53 /// now names its device, so equality against a bare variant no longer
54 /// compiles and equality against one device would silently exclude the
55 /// others.
56 pub const fn is_pointer(self) -> bool {
57 matches!(self, Self::Pointer(_))
58 }
59
60 /// The device that delivered a pointer focus, or `None` for every other
61 /// origin. [`PointerKind::Unknown`] for a widget-side derivation — see
62 /// [`POINTER`](Self::POINTER).
63 pub const fn pointer_kind(self) -> Option<PointerKind> {
64 match self {
65 Self::Pointer(kind) => Some(kind),
66 _ => None,
67 }
68 }
69
70 /// Whether this origin reveals the focus ring — the `:focus-visible`
71 /// question, answered in one place so the tree's modality signal and any
72 /// widget consulting the origin cannot disagree.
73 ///
74 /// Keyboard and assistive navigation reveal it; a pointer hides it.
75 /// [`Programmatic`](Self::Programmatic) answers neither: a scripted focus
76 /// declares no modality, so the tree leaves the signal where the last real
77 /// interaction put it.
78 pub const fn focus_visible(self) -> Option<bool> {
79 match self {
80 Self::Keyboard | Self::Accessibility => Some(true),
81 Self::Pointer(_) => Some(false),
82 Self::Programmatic => None,
83 }
84 }
85}
86
87/// Policy for a focus **traversal scope**, declared via the `FocusScope`
88/// wrapper widget. Controls what Tab / Shift+Tab does when it reaches the
89/// scope's ends.
90///
91/// A scope groups + scopes the `tab_index` numbering of its descendants:
92/// two sibling scopes that both number their children `1, 2, 3` never
93/// interleave — each scope is an independent, ordered unit within its
94/// parent. This is Teksilo's analogue of Flutter `FocusTraversalGroup` /
95/// WPF `KeyboardNavigation.TabNavigation`.
96#[derive(Debug, Clone, Copy, PartialEq, Eq)]
97pub enum TraversalScopePolicy {
98 /// Tab flows *out* of the scope at its ends into the enclosing scope's
99 /// next member. The scope groups `tab_index` numbering without trapping
100 /// focus — use for logical regions in a continuous Tab order (e.g. dock
101 /// panels, where each panel numbers its own controls without colliding
102 /// with sibling panels).
103 Continue,
104 /// Tab *wraps* within the scope and never exits via keyboard navigation.
105 /// Use for modal dialogs — the one surface whose pattern (ARIA's Dialog
106 /// (Modal)) actually calls for containing focus.
107 ///
108 /// **Not for popovers or menus.** Those implement Disclosure and Menu,
109 /// which mandate the opposite: Tab is an exit gesture there, and the
110 /// framework already answers it by dismissing the overlay focus leaves
111 /// rather than by trapping focus inside it. Wrapping such an overlay in a
112 /// `Cycle` scope defeats that — focus can no longer leave, so the
113 /// dismissal never fires and the panel becomes keyboard-inescapable except
114 /// via Escape.
115 Cycle,
116}