Duolith docs

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

  1. **on:key** on view, button and form runs 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 is keydown, filtered.
  2. **tab-stop={condition}**, a common attribute: whether the element is its group's one Tab stop (on the web tabindex 0 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 an on:key handler 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.
  3. Spinbutton values: value-now, value-min, value-max and value-text, common attributes (on the web aria-valuenow and so on), for an element with role spinbutton.
  4. **controls={id} and labelled-by={id}**, common attributes (on the web aria-controls and aria-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.
  5. New role words: search, grid, row, gridcell, column-header, tab-list, tab, tab-panel, spinbutton, dialog. selected is aria-selected on a tab and a gridcell (it stays aria-checked on a radio and aria-pressed elsewhere).
  6. Images (detailed in decision 0038): <image> gains decorative, placeholder, lazy and zoomable, and the events on:load, on:error and on:dismiss. An <image> needs alt or decorative (E0160), and so does a placed component that declares both an alt and a decorative prop, such as the kit's Image.

Alternatives considered

OptionWhy not
A runtime behaviour per role (grid, tablist, spinbutton), as for radio-groupPuts 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 preventDefaultWeb-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 scriptsImperative DOM access in parts, which native targets cannot share
aria-* attributes written freelyWeb-only words (decision 0029 already chose a short role list)
Native <input type="number"> for the stepperIts look and touch behaviour differ per browser, and it writes text, not a number

Consequences

  • Runtime: events.ts filters keydown and moves focus to the Tab stop; mount.ts writes tab-stop as tabindex. Native emitters will map on:key to hardware keyboard events and tab-stop to focus order.
  • The radio group keeps its runtime behaviour; it could later be rewritten on on:key and tab-stop.
  • dialog is also wanted by the overlay work (decisions 0034 to 0036); whichever lands second merges the role lists.