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.
TabBarItemis a<view href>withcurrent={...}, so pressing it is an ordinary navigation (aswitch, decision 0032, because the tab bar sits in a layout). It marks itself current fromroute().path: at itshrefor any path below it (/inboxmatches/inbox/7, not/inboxes), only athrefwithexact, and always exactly for/, which would otherwise contain every route. Acurrent={...}prop overrides the matching for a tab that owns routes outside itshref, such as a feed whose posts open at/post/7. - **
current={false}leaves no mark.** On the webcurrentwas written asaria-current="false"when false, so[aria-current]matched every tab. The runtime now removes the attribute when the expression is false and writespagewhen 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 saysclass="lg:row"; withoutrailthe 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,bannerandtoolbar, each the web role of the same name. TabBar and Breadcrumbs are navigation landmarks named by theirlabel; NavHeader is a banner holding the screen's heading. A view withrole="toolbar"gets one Tab stop and arrow-key movement from the runtime (packages/client/src/web/toolbar.ts), as aradio-groupdoes: 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:orhttps:address on another origin gets an arrow (the newarrow-up-righticon) whose accessible name is "opens another site"; a path, amailto:ortel:address and an absolute address on this site do not.externaloverrides the guess. - What a link may point at. Every
href, on every element and part, is a path in the app or anhttp:,https:,mailto:ortel: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 nohrefat 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 (
disabledoraria-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
hrefis compared without its?query,#fragmentor trailing/, decoded, androute().pathis now always the decoded path (/café, never/caf%C3%A9).
Alternatives considered
| Option | Why not |
|---|---|
| A tab bar the router draws from a list of tabs | A second place for routes, and a router that knows about looks |
Prefix matching on / too | The Home tab would be current everywhere |
A match prop with patterns | current={...} already says it, in the language's own word |
| An automatic rail by media query | Puts a column above the screen in every layout that is not a row |
Free aria-* attributes for landmarks | Rejected in 0029; three words map to every target |
| Toolbar keys in the part's script | A part has no reference to its elements; the runtime already does this for radio groups |
Consequences
- Native targets map
navigation,bannerandtoolbarto 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).