Duolith docs

0040. The kit's navigation parts sit on the router: tabs match the route, a tab bar can become a rail, and three new roles

  • Status: Proposed
  • Date: 2026-11-14
  • Decided by: integrator (internal only), pending Mik's approval
  • Planning item: WP7 (kit)

Context

examples/navigation built its tab bar by hand: links with current={route().path.startsWith(...)}, styles for the current tab and a safe-area padding. Every app would repeat that, as it would a screen header with a back button. The kit needs parts for these (TabBar, TabBarItem, NavHeader, Toolbar, Breadcrumbs, Link) that use the router from decision 0031 rather than a second one, and that are the right landmarks for assistive technology. The language's role list (decision 0029) had no landmark or toolbar.

Decision

  • A tab is a link. TabBarItem is a <view href> with current={...}, so pressing it is an ordinary navigation (a switch, decision 0032, because the tab bar sits in a layout). It marks itself current from route().path: at its href or any path below it (/inbox matches /inbox/7, not /inboxes), only at href with exact, and always exactly for /, which would otherwise contain every route. A current={...} prop overrides the matching for a tab that owns routes outside its href, such as a feed whose posts open at /post/7.
  • **current={false} leaves no mark.** On the web current was written as aria-current="false" when false, so [aria-current] matched every tab. The runtime now removes the attribute when the expression is false and writes page when it is true.
  • The rail is opt-in. <TabBar rail> becomes an 88px column at the leading edge in a large window (lg, 1024px), with a line on its trailing side. A part cannot change how the view around it lays out, so the layout says class="lg:row"; without rail the bar stays at the bottom in every window, which is never wrong. The safe-area insets (bottom, left, right) are padding on the bar.
  • Three more roles: navigation, banner and toolbar, each the web role of the same name. TabBar and Breadcrumbs are navigation landmarks named by their label; NavHeader is a banner holding the screen's heading. A view with role="toolbar" gets one Tab stop and arrow-key movement from the runtime (packages/client/src/web/toolbar.ts), as a radio-group does: Left and Right (and Up and Down) move focus without pressing, wrapping, Home and End go to the ends, disabled controls are skipped, and the Tab stop stays on the control used last.
  • Link marks other sites. An http: or https: address on another origin gets an arrow (the new arrow-up-right icon) whose accessible name is "opens another site"; a path, a mailto: or tel: address and an absolute address on this site do not. external overrides the guess.
  • What a link may point at. Every href, on every element and part, is a path in the app or an http:, https:, mailto: or tel: address. Written as text, any other scheme (javascript:, data:, vbscript:, however it is spelt or spaced) is E0170 at build time. Built from data, the web runtime reads it with the browser's own URL parser and, for any other scheme, writes no href at all and logs an error, so an address from a message or a query string can never run script when pressed. navigate() keeps its stricter rule (http and https only, decision 0031).
  • A link to the screen before goes back to it. When a link inside a screen points at the address of a screen the user would reach by pressing back (entries pushed one from the other in this visit), the router goes back to it instead of pushing a copy. A breadcrumb to the shelf a book was opened from pops the book, so the stack shrinks as on native, and a tab's first screen never gains a back button to the screen below it. Breadcrumbs stay ordinary links (open in a new tab, copy the address). Replacing the screen instead was rejected: a replace keeps the replaced screen's back button, so the tab's first screen would gain one.
  • Toolbar keys. The toolbar handles only unmodified arrow, Home and End keys; with Alt, Ctrl, Meta or Shift held, and for the caret keys inside a text field, the key is left alone. A key a toolbar inside it already handled is not handled again. When the focused control becomes disabled (disabled or aria-disabled), focus moves to the new Tab stop rather than being lost.
  • Badges and matching. A badge shows, and joins the tab's name, only when it is a number above 0. A tab's href is compared without its ?query, #fragment or trailing /, decoded, and route().path is now always the decoded path (/café, never /caf%C3%A9).

Alternatives considered

OptionWhy not
A tab bar the router draws from a list of tabsA second place for routes, and a router that knows about looks
Prefix matching on / tooThe Home tab would be current everywhere
A match prop with patternscurrent={...} already says it, in the language's own word
An automatic rail by media queryPuts a column above the screen in every layout that is not a row
Free aria-* attributes for landmarksRejected in 0029; three words map to every target
Toolbar keys in the part's scriptA part has no reference to its elements; the runtime already does this for radio groups

Consequences

  • Native targets map navigation, banner and toolbar to their traits, and the toolbar's keys to the platform's focus movement.
  • Per-tab history (each tab its own stack) is still not done (decision 0031); pressing a tab pushes onto the one stack, and the screen it opens has no back button (decision 0041).