0037. Navigation keys, Tab stops, spinbutton values and new roles for pickers and tabs
- Status: Proposed
- Date: 2026-11-14
- Decided by: integrator (internal only), pending Mik's approval as part of Specification v0
- Planning item: WP7 (kit, second half: pickers, inputs and media)
Context
The second half of the kit (decision 0028) needs keyboard models the language could not express: a calendar grid where the arrow keys move focus by day and week and the page keys change the month, a tab list with a roving Tab stop and automatic activation, and spinbuttons for a stepper and a time picker. Decision 0029 solved the radio group inside the runtime, keyed on its role; doing that again for every widget would put each widget's logic (date arithmetic, wrapping, disabled days) into the runtime. Parts already hold their own state, so what they lack is a way to hear the keys and a way to say which element is the Tab stop.
Decision
- **
on:key** onview,buttonandformruns when a navigation key is pressed while focus is on the element or inside it: an arrow key, Home, End, PageUp, PageDown or Escape. The handler receives{ key }; the key's default action (scrolling) is prevented. Inside a text field only Escape arrives, so the arrows still move the caret. On the web it iskeydown, filtered. - **
tab-stop={condition}**, a common attribute: whether the element is its group's one Tab stop (on the webtabindex0 or -1). Written with no value, the element is always a Tab stop, which makes a view focusable (a spinbutton, a tab panel). Focus follows the Tab stop: after anon:keyhandler runs, if focus was inside the element, focus moves to the element's Tab stop once the state has settled. So a part moves focus by changing state (cursor = nextDay), never by touching the DOM. - Spinbutton values:
value-now,value-min,value-maxandvalue-text, common attributes (on the webaria-valuenowand so on), for an element with role spinbutton. - **
controls={id}andlabelled-by={id}**, common attributes (on the webaria-controlsandaria-labelledby): a tab points at its panel, and the panel is named by its tab, so the name is the tab's own text and never goes out of step with it. - New role words: search, grid, row, gridcell, column-header, tab-list, tab, tab-panel, spinbutton, dialog.
selectedisaria-selectedon a tab and a gridcell (it staysaria-checkedon a radio andaria-pressedelsewhere). - Images (detailed in decision 0038):
<image>gainsdecorative,placeholder,lazyandzoomable, and the eventson:load,on:errorandon:dismiss. An<image>needsaltordecorative(E0160), and so does a placed component that declares both analtand adecorativeprop, such as the kit's Image.
Alternatives considered
| Option | Why not |
|---|---|
| A runtime behaviour per role (grid, tablist, spinbutton), as for radio-group | Puts date arithmetic, step rounding and wrapping rules into the runtime, once per widget and once per target |
A general on:keydown with every key and a preventDefault | Web-shaped; handlers would need to return whether they handled the key, and text fields would lose their arrows |
A focus() call or element references in scripts | Imperative DOM access in parts, which native targets cannot share |
aria-* attributes written freely | Web-only words (decision 0029 already chose a short role list) |
Native <input type="number"> for the stepper | Its look and touch behaviour differ per browser, and it writes text, not a number |
Consequences
- Runtime:
events.tsfilterskeydownand moves focus to the Tab stop;mount.tswritestab-stopastabindex. Native emitters will mapon:keyto hardware keyboard events andtab-stopto focus order. - The radio group keeps its runtime behaviour; it could later be rewritten on
on:keyandtab-stop. dialogis also wanted by the overlay work (decisions 0034 to 0036); whichever lands second merges the role lists.