Summary#
Hover is a pointer's. Whatever a pointer opens on hover — a title, a definition, a preview — a keyboard user has to be able to open too (WCAG 2.1.1 and 1.4.13), and to close again with Escape:
component WhenSaid(string words, string exact) {
bool open = false;
action Show() { open = true; }
action Hide() { open = false; }
render {
Box(position: Position.Relative,
onPointerEnter: Show, onPointerLeave: Hide, // the pointer
onFocus: Show, onBlur: Hide, // the keyboard — and onFocus makes this Box a tab stop
onEscape: open ? Hide : null) { // Escape closes it while it is open
Text(words);
if (open) { Box(role: UiRole.Tooltip, label: "Exact time") { Text(exact); } }
}
}
}Signature#
onFocus: <action> // the element itself took focus
onFocusWithin: <action> // focus entered the element or anything inside it, from outside it
onBlurWithin: <action> // focus left the element and everything inside itDescription#
onFocus makes the element a tab stop#
A Box never takes focus on its own, so an onFocus on one would compile, wire up and never fire. Binding onFocus
to an action therefore makes a plain element a stop in the tab order (tabindex="0", in the server's paint and the
browser's alike). Binding it to null makes none — so onFocus: titled ? Show : null is a stop only while there is
something to show. A Button, Pressable, Input, TextArea, Select, Link or frame is reachable already and
gets nothing extra.
The group pair, and why onBlurWithin exists#
onFocusWithin and onBlurWithin judge a move by where focus came from or goes to. Moving from one control inside
the group to another is neither an entry nor a departure, so neither runs. That is the case onBlur cannot serve: a
popover opened from its owner has buttons of its own, and onBlur on the owner fires the moment focus steps into
them — the popover would close under the keyboard that came to use it. onBlurWithin on the group closes it only
when focus has left the owner and the popover both. Focus leaving to nowhere (the page itself, another window) counts
as leaving. A group that only listens is not itself a stop: its controls are.
Not activations#
Like onBlur, none of the three is an activation: no busy spinner, no in-flight guard. Arriving somewhere is not a
submission.
Closing on Escape#
Pair an opened-on-focus surface with onEscape bound only while it is open — onEscape: open ? Hide : null —
so it is the innermost Escape handler exactly while there is something to close, and the page's other Escape
handlers are untouched the rest of the time. Escape hides it without moving focus; arriving again opens it again.
A pure-CSS tip (inside Button.Focus { Display = Display.Flex; }, the kit's KeyTip) needs none of this: Escape
hides every such reveal by itself — see [[ui-styling#inside]].
In a test#
Ui.Focus("3 h ago") moves the keyboard to the stop holding that text, as a Tab arriving there would, and refuses a
control the keyboard cannot reach. Then Assert.Focused, Ui.Press("Escape") and Ui.Press("Tab") say the rest —
see [[testing-ui#focus]].
Examples#
component Term() {
bool open = false;
action Show() { open = true; }
action Hide() { open = false; }
render {
Box(position: Position.Relative, onPointerEnter: Show, onPointerLeave: Hide, onFocus: Show, onBlur: Hide,
onEscape: open ? Hide : null) {
Text("WCAG");
if (open) { Box(role: UiRole.Tooltip, label: "Meaning") { Text("Web Content Accessibility Guidelines"); } }
}
}
}component Toolbar() {
bool open = false;
action Show() { open = true; }
action Hide() { open = false; }
render {
Row(onFocusWithin: Show, onBlurWithin: Hide, onEscape: open ? Hide : null) {
Button("Format", onPress: Show);
if (open) {
Button("Bold", onPress: Hide);
Button("Italic", onPress: Hide);
}
}
}
}See also#
- onEscape — Escape as the dismiss gesture, page-wide while mounted
- pointer —
onPointerEnter/onPointerLeave, the pointer half of hover - accessibility — what the platform does for keyboard and screen-reader users
- Ui — drive the app's UI from a test —
Ui.Focus,Ui.Press("Tab")andAssert.Focused