Navigation

Navigation connects the places in an app and gives people a way to return as they explore. Tabs, sidebars, and paths through successive pages organize those destinations according to the app’s structure.

Navigation state lives in signals. Selecting a tab or pressing Back updates the signal; changing the signal from app code updates the native container.

  • nav selects one destination, such as a tab or sidebar item. Its signal holds the active key.
  • nav_stack holds a path of destinations in a Signal<Vec<_>>. Pushing or removing a key opens or closes a level of the native stack.

Keys implement Route. Start with strings, or use an app-defined enum when you want the compiler to check destinations and their associated data. The string adapter (navigate, nav_back, current_route) lets deep links and dayscript address either form.

The UI snippets use generated res::str accessors from an app’s Fluent catalog; see the example messages and catalog setup.

nav(selection).refreshable(refreshing, action) installs the native pull control on UIKit (UIRefreshControl) and Android (SwipeRefreshLayout) sidebar menus, including lists shorter than the viewport. The native scroll view owns gesture arbitration: a pull starts only at the top, without intercepting ordinary row taps, long presses or scrolling. Android wraps the Material menu’s RecyclerView inside its NavigationView, preserving the navigation handle, presenter and context-menu ownership.

The app owns the reactive boolean and must set it synchronously when accepting work, then clear it on success, failure or cancellation. RefreshRequested is a request event; RefreshPatch renders state and never emits that event. Busy requests are ignored and requests that start no work end the indicator immediately, even when the boolean remains false. Programmatic refresh uses the same indicator. Bindings and callbacks belong to the navigation scope; native targets/listeners are owned by the released sidebar view.

This currently applies to native sidebar menus on UIKit and Android. Tabs, composed collapsible/reorderable sidebars, desktop, web and ArkUI do not provide this affordance. Keep an explicit Refresh command for accessibility, keyboard use and other platforms.

Compact sidebar activation

A row activation must present the resident content-list column even when its route is already selected. Selection alone is insufficient: UIKit can show the feeds root after initial split collapse or native Back while the model already considers the list selected. For a merged content list in stack presentation, every native row selection that satisfies ContentList::only_for reissues ListInStack(true) without rebuilding that list. The native stack remains authoritative for Back; this does not add a second stack mirror. UIKit coalesces pending list requests with a generation ticket, waits for active push/pop transitions, and checks the native stack for the list controller before showing the column. This avoids queuing duplicate pushes when Back is immediately followed by another section selection. A newer request, expansion or host disposal makes an older pending request inert. Test actual row taps, especially the initially highlighted row, empty lists and Back/reselect cycles; injecting a route change can miss this failure.

Document tabs

document_tabs(tabs, new_label, close_label, title, content) hosts documents with independent lifetimes. TabSet<K> owns their ordered stable keys and optional selected key; K implements Route. Application payloads, undo history, persistence, pinning, and suspension remain app-owned. Pass localized res::str accessors for the add/close labels and app-owned titles. Publication or user-supplied document titles can pass through unchanged.

OperationContract
TabSet::new()Starts empty with no selection. Own it above the host.
open(key, foreground)Adds an absent key once. A background open preserves selection unless the set was empty.
select(&key)Selects an existing identity; returns false for an unknown key.
move_to(&key, index)Moves to the final index, clamped to the last position; preserves selected identity.
select_next(backwards)Wraps through the collection; does nothing when empty.
close(&key)Accepts removal. If selected, chooses the following neighbor or the preceding last tab. The final close selects None.
keys(), selected(), contains(&key)Read order, selection, or membership.

The host builds each document once, including background documents. Reordering permutes resident native pages with NavPatch::Reorder: each entry is an old resident-page index in the new order. Closing disposes only that document’s scope. Selection and native indices never identify payloads. An .on_close(handler) callback receives a request; the app calls tabs.close(&key) after it accepts. Keeping the key vetoes the request. Without a handler, a request removes the key directly. .on_new(handler) delegates creation and key allocation to the app.

.native(|| preference.get()) changes presentation reactively. Supported toolkits use a native in-window control or an OS window group. Unsupported toolkits keep the composed strip. Content, scopes, and native handles survive each switch; only composed chrome is conditionally built. .chrome(|actions| ...) replaces that strip; TabActions supplies tabs, new_tab, close, drag, and drop_before. Drag payloads are host-scoped so equal keys in unrelated collections cannot move each other’s documents. .layout(|chrome, content| ...) places the composed chrome. The default strip is native buttons: the current document’s is a selected button (button(..).selected(..), docs/buttons), so it keeps its focus stop and activation, the platform draws its own selected look, and assistive tech hears a selected tab in a tab list (Role::Tab, Role::TabList). .strip_id(id!(docs)) gives the strip a declared ID. Child IDs use the document_tab, document_close, and document_new families. For document key a, the tab is document_tab:docs%3Aa; the colon in the combined host/key is percent-encoded. Without an explicit strip ID, the host uses document_strip:<n>. See element IDs before writing script locators.

ToolkitNative document presentation
AppKitOS window tabs; composed mode parks pages in an NSTabView.
QtQTabWidget; macOS can move documents into OS window tabs.
GTKAdwTabView/AdwTabBar, including macOS. OS-window grouping is unsupported because GDK owns window decorations.
WinUITabView with close requests and within-strip dragging.
AndroidScrollable Material TabLayout with add/close controls and host-scoped long-press dragging.
UIKit, ArkUI, DOMComposed strip; UIKit uses a UIViewController container for documents.

Toolkit duties distinguish OS-window grouping (native_window_tabs) from in-window chrome (native_document_tabs). Both default to false. DocumentTabsConfig carries localized labels and add-button availability through NavProps; NavMenuProps::document_keys aligns stable keys with rows. DocumentTabsPatch toggles native chrome while retaining pages. day:tab-new, day:tab-close, and day:tab-move custom events carry the key (where applicable); move carries the final destination index in num. These tags are protocol identifiers, not translated text.

let section = Signal::new("home".to_string());
nav(section) // adaptive by default; .style() pins a shape
    .title(res::str::app_title())
    .header(sidebar_header) // optional piece above the list
    .footer(sidebar_status) // pinned below the scrolling list, on the root page
    .item("home", res::str::home(), home_page)
    .item("settings", res::str::settings(), settings_page)

Styles

NavStyleWhat it draws
Automatic (default)The platform’s answer at this width — see the ladder below.
TabsA tab bar at every size, however wide the window gets.
SidebarA NavigationSplitView: both panes where there is room, collapsing to a list that pushes the detail where there is not.

Automatic walks one ladder, and only its bottom rung is platform-specific:

window widthpresentation
Expanded and wider (≥ 840pt)Split — sidebar beside detail
Medium (600–839pt)Rail — a narrow strip beside the content
Compact (< 600pt)Tabs where a tab bar is the idiom, Stack where it is not

That last row is Cap::NavTabsAdaptive, and it describes the platform rather than its widget set. Every desktop can draw a tab bar (an app is free to pin NavStyle::Tabs), and none of them grows one when its window is dragged narrow: a narrow Mail.app hides its sidebar and pushes. The phones and the web are the opposite, and they are the surfaces whose window size ranges from a phone to a desktop. So Automatic and Sidebar behave identically on a desktop, and differ on iOS, Android, HarmonyOS and the web.

Rail is not gated by that capability: a narrow sidebar is an ordinary desktop shape, and on Windows it is what NavigationView does at that width. A toolkit with no rail control rounds it to a neighbor of its own choosing: macOS has nothing that is a vertical strip of icon-only destinations, so appkit draws an ordinary sidebar there.

Page residency

A presentation whose rows are the chrome (Tabs, Rail) keeps every visited page resident: switching is a NavPatch::Select, nothing is torn down, and each tab keeps its scroll offset and focused field, which is what every native tab container does. A Split or Stack presentation keeps only the shown page and switches by pop-then-push.

Residency follows the presentation rather than the host. Making every nav page resident would keep effects running for pages nobody is looking at; making none resident would rebuild a tab’s content on every tap. Splitting it this way means a morph only ever disposes pages that are not on screen, or lazily builds ones that were not built yet; the visible page is never rebuilt, which is the invariant a morph has to keep. Pages build on first visit.

A chrome presentation is the exception, because its bar needs an item per destination: every page is built up front, in row order, before the initial selection is applied. NavPatch::Select names a page by attach order while the chrome draws the rows, so page i has to be row i; that pairing is all a suite has. Building the selected destination first (the selection a .restore(key) came back with, say) would attach it at index 0 and leave the bar highlighting the first row while another destination’s page is the one on screen.

The active key is a Signal<String>, two-way exactly like Picker/Toggle: set it and the UI switches; the user picking natively writes it back (origin-tagged, no echo).

PresentationNative container
Splita NavigationSplitView: macOS NSSplitViewController with a sidebar NSSplitViewItem (system material, source-list NSOutlineView, full-height under the titlebar) + detail; GTK two nested GtkPaneds (sidebar
Stackone page at a time, back-navigable: UINavigationController, AdwNavigationView, the Android back stack, or a desktop back-header above the pages.
Tabsthe rows drawn as a tab bar: UITabBarController / Material NavigationBarView / NavigationView.PaneDisplayMode = Top / an NSTabView on macOS / an AdwViewSwitcher on GTK / a QTabWidget on Qt / a composed bar on Web.
Railthe rows as a narrow strip: Material NavigationRailView, PaneDisplayMode = LeftCompact, an ArkUI vertical Tabs; roundable where a toolkit has none.

nav is one primitive, a selection-bound switcher, and a presentation is chrome plus page lifetime rather than a different host. That is why a window crossing a breakpoint re-presents (NavPatch::Presentation) rather than rebuilding: the pages it already has are re-homed, so nothing loses a scroll offset, a focused field, or an animation in flight.

What each toolkit draws. The rows become the platform’s destination chrome, and where a platform has no such widget the presentation rounds to the neighbor it does have (Rail lands on an ordinary sidebar on macOS and Qt). A toolkit that answers Cap::NavTabs = Unsupported sends Automatic through the sidebar ladder instead, which is what every toolkit did before adaptive navigation existed.

ToolkitTabs presentationAdaptive
macos-appkitNSTabView (top tabs on a bezel), the detail pages as its items; labels from the host’s rowsno; a Mac narrows to a stack
ios-uikitUITabBarController in .tabSidebar mode, driven by UITab on iOS 18+ and by viewControllers below it; see the iOS notes belowyes
android-materialnavigation suite: BottomNavigationView → NavigationRailView → permanent NavigationView drawer, by width. A NavStyle::Sidebar pane is a NavigationView too; see the iOS notes belowyes
linux-gtkAdwViewSwitcher over an AdwViewStack of resident pages, each in a filling DayCellno
linux-qtQTabWidget — Qt’s own one-of-N containerno
web-doma composed tab bar (.day-nav.tabs)yes
harmony-arkuia composed suite over resident pages, built from Day’s primitives (ArkUI’s native node set has no tab container): a bottom bar on a compact window, a rail on a medium one, a sidebar column on an expanded one, by the host’s width (docs/size-classes)yes
windows-winuithe same NavigationView with PaneDisplayMode = Top; Rail is LeftCompact, a real railno

Only the phones and the web grow a tab bar as the window narrows (Cap::NavTabsAdaptive); a desktop may pin one with NavStyle::Tabs, but narrowing hides its sidebar and pushes.

Row size

On macOS the sidebar follows the system’s Sidebar icon size setting (System Settings › Appearance), as Finder’s and Mail’s do, and changes with it while the app runs. The outline uses the default row size style, so AppKit sets each row’s height and its label’s font: 24, 32 or 40 points tall for Small, Medium and Large. A row’s icon draws at the size AppKit draws an SF Symbol there (16 points at Medium), measured from a system symbol rather than tabled. Day’s icons are artwork that fills its frame, and a Material Symbols glyph sits inside a margin of its grid, so each icon is measured once and sized until its drawing, not its box, matches the symbol. Day also keeps a row’s label clear of its badge, and sizes the count two points under the label.

Keyboard

A sidebar walks with the arrow keys: ↑/↓ move to the next destination, Home and End to the first and last, and the selection reports exactly what a click on that row reports. The desktops get this from the widget the style maps to (an NSOutlineView source list, a NavigationView) with nothing of Day’s in front of it: keys go to whatever has focus and no route sits above them (docs/menus).

Web has no such widget, so the toolkit builds the behavior: .day-navmenu carries the tab stop and role="listbox", its rows carry role="option" and aria-selected, and the shim moves the selection by reporting the new index the way the click handler does. It also holds the focus across the page swap its own key press caused: a detail pane can contain an element the browser focuses as soon as it appears (a <video>, a web view’s iframe), and without that the sidebar would answer one arrow and then go quiet.

Immersive items (.immersive())

item(key, title).immersive() marks that destination as an immersive-chrome page: on toolkits with an immersive nav mode (day-toolkit-material’s edge-to-edge opt-in today) its pushed page keeps the floating transparent bar over full-bleed content, while unmarked pages and the root get the standard opaque bar. Every other toolkit ignores the flag. Pair it with day::safe_area() (docs/layout): the immersive page paints its background unpadded and pads its content by the reported insets.

let path = Signal::new(Vec::<String>::new());
nav_stack(path, home_view)
    .destination(|key| detail_view(key))
// push:  path.update(|p| p.push("item-42".into()));
// pop:   path.update(|p| { p.pop(); });
// the native back button writes the pop back into `path` (origin-tagged).

Day reconciles the native stack to path (keep the common prefix, pop the rest, push the new suffix; the same diff NavigationStack/React-Navigation do). The native containers: UINavigationController (iOS), AdwNavigationView (GTK; a pushed page carries an AdwHeaderBar with the page’s title, in which the view draws its back button, over a filling cell that reports the content’s size under the bar — the root page is the content alone), Android back-stack, and a top-page-only presentation on macOS NSSplitView / Qt QSplitter in stack mode. The path is data, so deep-linking is “parse the URL into a path and set it,” and the stack is unit-testable without the framework.

Commands on the chrome

There is no bar_action. A command that belongs on the chrome rather than in the page is a TOOLBAR ITEM declared on the piece it acts on (docs/toolbars), and which bar it rides follows from that:

nav(section)
    .toolbar(
        toolbar_button(id!(add), res::str::add())
            .icon(Symbol::Add)
            .action(add_item),
    ) // the list's
    .destination(|k| page(k).toolbar(share_button())) // the page's

Nav::toolbar and NavStack::toolbar put items on that host’s own chrome — the sidebar column where the presentation has one, the root list when it has collapsed. Items declared on a destination page ride the detail. Both leave the bar when what they act on leaves the screen, so neither needs a scope to be spelled out.

The affordance that shows and hides the sidebar is the toolkit’s, not the app’s: a nav(Sidebar) supplies it, and .no_sidebar_toggle() suppresses it.

Items are values (item, nav_items, .items)

An item is a value: item(key, title) with its decorations chained onto it (.icon(..), .badge(..), .icon_tint(..), .immersive(), .page(build)). .items(..) takes one item, a tuple of them, an Option<NavItem> (an item a platform may not want, such as prefs.nav_item(Section::Settings)), a Vec, or a data-driven nav_items(..) block, in any mix; the final list is the declaration order. .item(key, title, build) stays as the shorthand for items(item(key, title).page(build)).

nav(section)
    .items((
        item(Section::Home, res::str::home()).icon(res::images::home).page(home_page),
        item(Section::Inbox, res::str::inbox()).icon(res::images::inbox).badge(move || unread.get().to_string()).page(inbox_page),
        prefs.nav_item(Section::Settings).map(|i| i.icon(res::images::settings)),
    ))

Items can also come from a signal, so a sidebar or tab set grows and shrinks with your data (a rooms list, open documents). nav_items(reader, map) is the data-driven block; static items and blocks mix, and an item without a .page is built by .destination (like nav_stack).

let tabs = Signal::new(vec!["general".to_string(), "random".to_string()]);
nav(current)
    .style(NavStyle::Tabs)
    .items(nav_items(move || tabs.get(), |k: &String| item(k.clone(), k.clone())))
    .destination(|k: &String| room_page(k))

The row set re-derives whenever a block’s signal changes: rows are added/removed on the native widget, and if the selected key disappears the selection resets (to None for an Option key). For a filtered sidebar whose current document should remain open, use .retain_selection_when(|key| record_still_exists(key)). On item-list changes, a true result keeps that destination and its state alive while the native sidebar has no highlighted row. Returning false preserves the normal fallback for deleted records. Supply .destination for dynamic keys. The same effect resolves every row title tracked, so a runtime set_locale retitles the native rows in place, static .items included. NavItem::icon also accepts an owned absolute path for downloaded image files. AppKit and UIKit preserve the colors of these file icons; bundled symbolic icons still use template rendering and icon_tint. Cache a thumbnail locally and change its filename when its bytes change so native image caches invalidate. A missing/unreadable file has no image, so apps should supply their own bundled fallback until the download is ready.

item(key, title).icon(name) is the row spec; .icon_tint(color) recolors the row’s glyph (docs/vectors), .context_menu(vec![…]) attaches a per-row context menu (docs/menus), and .immersive() on it marks that row’s pushed page immersive-chrome, same as the static form above.

.badge(text) is the row’s count or status word, drawn in the platform’s own badge slot: the source-list count on AppKit, a dim count in the GTK row and on Qt and the web, a UITab’s badge on iPadOS and in the tab bar, a Material badge on Android’s bottom bar and rail and a trailing count in its drawer. Empty text is no badge, so a count can return "" at zero rather than switching the badge off. A badge that ticks (or a title that changes language) updates that row in place on every toolkit that can (NavMenuPatch::Items::rows_changed), without rebuilding the bar or replaying its selection animation.

.badge_icon(name) puts a glyph at the row’s trailing edge, with .badge_tint(color) for a color that carries meaning (a starred page’s yellow star). It shares the trailing slot with the text .badge(…) and is drawn after it, so a row can show a count and a status at once:

item(section, title)
    .icon(res::vectors::nav_grid)
    .badge_icon(res::vectors::star)
    .badge_tint(AMBER)

Both are template glyphs, so an untinted one takes the toolkit’s neutral row color and follows the theme; a tinted one keeps its color because the color carries meaning. Every toolkit draws it: the trailing slot of the AppKit cell, the GTK row box, a QStyledItemDelegate on Qt (a QListWidgetItem has only the leading icon slot), the end compound drawable on Android, the composed NavigationViewItem.Content on WinUI, between label and chevron on ArkUI, a masked element on Web, and a trailing UIImageView on UIKit, which is also where the nav badge slot first appeared on that toolkit. A nav host used as a self-contained widget inside a page that already routes should call .local() so it does not add a segment to current_route or intercept navigate.

Section headers. nav(…).section(title, content) puts a header over content, which is anything .items takes: one item, a tuple, an Option, a nav_items block, or a mix. The header rides the first row of the content (the first row of a data-driven block, wherever the data starts). item(key, title).section(title) opens a header from inside a data-driven mapper, which is how a derived list keeps its groups under a search filter: attach the header to the first surviving row of each group, and a group whose rows are all filtered out disappears with them. Headers are a grouping hint: a toolkit without grouped rows (a tab strip, a plain phone list) shows one flat list, so a header is never the only way a row is reachable, and a row’s icon tint is the grouping signal that survives there. AppKit draws them as source-list group rows (small, bold, secondary, pinned as their group scrolls under them); the outline keys its rows by index, not by title, so a header may share its text with an item (“Controls” over Controls) without the two collapsing into one row. UIKit and Android draw them as their platforms’ own list headings, scrolling with the group they open: on iOS the heading of a UICollectionLayoutListConfiguration section, in the inset-grouped appearance at a compact width (the phone’s grouped table) and the sidebar appearance at a regular width (the Settings sidebar), with the configuration’s own default header content and nothing of Day’s painted over it; on Android Material’s NavigationView subheader for each group. Neither pins a heading over the rows below it, because neither platform’s own lists do. GTK draws them in its list box’s header slot. Qt, whose QListWidget has no header slot, draws each as a small bold dimmed item of its own that takes no click, hover or selection, and Web as a heading element between the rows. Windows adds a NavigationViewItemHeader to the pane’s items (a disabled item in the plain ListView sidebar), collapsing them while the pane is a tab strip or an icon rail, and HarmonyOS a secondary-colored title above the group’s first row. These four translate indices at the list, so a row keeps the index Day gave it however many headings sit above it.

nav(section)
    .section(res::str::smart_feeds(), (
        item("today", res::str::today()).icon(res::images::today).page(today_page),
        item("unread", res::str::unread_feed()).icon(res::images::unread).page(unread_page),
    ))
    .section(res::str::feeds(), nav_items(move || st.feeds.get(), |f| item(f.id, f.name)))

A data-driven item is a label + optional icon: the native sidebar/tab row. It is not an arbitrary rich row (an avatar + preview + badge); a master list that needs those is a list, and combining a rich master list with native master-detail push is a separate, not-yet-built feature.

Toolkit support (2026-07): dynamic add/remove/reselect renders on macos-appkit, linux-gtk, linux-qt, and web-dom (and their host variants), verified in the showcase walkthrough. The ios-uikit sidebar and tab selection are wired; dynamic rendering on the UIKit/Android/ArkUI/WinUI tab widgets is in progress (those toolkits ignore the item-set patch until then, so the initial set still shows). The item logic is toolkit-independent and covered by mock_e2e::nav_data_driven_items_reconcile.

iOS tabs

Tabs use UITabBarController. On iOS 18 and later, UIKit can adapt the tab bar into a sidebar; older versions use the conventional tab bar. Section headings do not collapse destinations into tab groups.

Author tab icons at their intended display size. A bundled vector’s declared dimensions can affect its native tab image size; see Vectors.

iOS sidebar

The sidebar uses a UICollectionView list with UIKit’s sidebar appearance and section headings. A page rooted in a scroll view extends beneath translucent navigation bars, with UIKit adjusting its scroll insets. Other content is laid out inside the safe area. Avoid adding a second safe-area inset around a navigation host.

Android sidebar

The sidebar uses Material’s NavigationView, including its row metrics, selected indicator, section headings, and scrolling behavior. Rows are recycled; row actions and context menus follow the current item.

Back interception (on_back)

NavStack::on_back intercepts the user’s back affordance (a native gesture/button, or nav_back()) to run a policy before the pop. It does not run for a programmatic path.set (a write is not a back), matching Jetpack Compose’s BackHandler.

let dirty = Signal::new(false);
nav_stack(path, home_view)
    .destination(|k| detail_view(k))
    .on_back(move |req| {
        if dirty.get() {
            // confirm asynchronously, then perform the deferred pop on "yes"
            day::task(async move {
                if confirm(res::str::discard_changes()).await {
                    dirty.set(false);
                    req.proceed(); // performs the pop the guard consumed
                }
            });
            BackResponse::Handled // consume this back
        } else {
            BackResponse::Proceed // normal pop
        }
    });

The guard returns Proceed (pop now) or Handled (consume; the pop does not happen). A Handled guard may hold the BackRequest and call proceed() later: the unsaved-changes → confirm → leave flow. proceed() performs exactly the pop Proceed would have.

While a guard is armed above the root, Day tells the toolkit to stop auto-popping on a native gesture and route the back through Day instead (NavPatch::GuardTop). What that means per toolkit:

toolkitnative-gesture arming while guarded
iOS (UIKit)swipe disabled; the back button is vetoed via a UINavigationController subclass’s navigationBar:shouldPopItem:, which emits the back to Day
Androida higher-priority OnBackPressedCallback routes the system/gesture back and the toolbar up-arrow to Day (the predictive-back preview is unavailable while armed)
HarmonyOS (ArkUI)the top NavDestination’s onBackPressed consumes the native back and defers to Day
GTKthe top AdwNavigationPage sets can-pop = false (swipe/Escape disabled; the app drives back through its own control, which is guarded)
macOS / Qt / WinUI / webno-op — the back button already routes through Day, so the guard runs with no native arming needed

The guard’s logic (intercept, defer, proceed, never-on-programmatic-write) is identical everywhere and covered by mock_e2e::nav_stack_on_back_guard_intercepts_and_defers.

A nav host arms the same patch for a reason of its own: while a detail is open beside a composed content list, so the platform’s back closes the detail instead of popping the page that holds both (see detail_visible below). The host counts the requests to arm it, so a guarded stack merged into the host and an open detail never disarm each other.

Handling the system Back (on_system_back)

on_system_back(enabled, handler) is Jetpack Compose’s BackHandler(enabled) { … }. While the decorated subtree is mounted and enabled holds, a back that no navigation surface takes runs handler instead of the platform’s default. On a phone that default is leaving the app. A browser is the usual case: with no Back button, as in Chrome on Android, the system back goes back in the page’s history while the tab can.

browser_window(browser).on_system_back(
    move || browser.current().is_some_and(|t| t.can_go_back()),
    move || {
        if let Some(t) = browser.current_untracked() {
            t.go_back();
        }
    },
)

enabled is a constant, a Signal, or a closure, and Day follows it as it changes.

Order. A back goes through the same layers everywhere:

  1. a presented cover closes (or the stack inside it pops first, as above);
  2. a pushed page pops, a guarded stack’s on_back decides, a phone’s section page returns to its list;
  3. the app’s handler runs, chosen among those that are enabled and on screen (a handler in a tab the bar is not showing is off screen): the one in the topmost cover, then the one nested most deeply in the piece tree, then the most recently mounted;
  4. the platform’s default.

Nesting is counted in pieces, not navigation hosts. A handler on a piece inside a column is deeper than a handler on that column’s sibling, so it wins even when the sibling mounted later. Each page a navigation host shows adds its own levels, so a handler inside a page beats one beside the host. Day reads the depth when a back arrives, so a page that has moved since it mounted, such as a document tab in a window of its own, is ranked where it is now. Handlers at the same depth go to the most recently mounted, as with Compose’s BackHandler.

Day follows each handler’s enabled and the selection of every tab around it. Selecting a tab from code, by writing its selection or calling navigate, arms or releases the platform’s back in the same turn as a tap on the tab does.

A handler takes only the back that would otherwise have left the app, so it never competes with navigation. A page’s own “discard your changes?” policy belongs on NavStack::on_back, which runs before the pop.

Which backs reach it. Day’s rail, nav_back(), runs the handler when no surface pops, so dayscript’s nav_back: {} and an app’s own Back control reach it on every toolkit. dayscript’s nav_back: { native: true } reaches it through the platform’s back where the toolkit has one. Day arms the platform’s back (Toolkit::set_system_back) only while some mounted handler is enabled, and releases it as soon as none is:

toolkitsystem back while a handler is enabled
Androidan OnBackPressedCallback added first, in DayActivity.onCreate, sits beneath every other: a cover’s, a nav host’s guard and section back, and the FragmentManager’s. It is enabled only while a handler is, so a pushed page still pops with the predictive-back preview, and a back that would leave the app still shows the “back to home” preview whenever no handler wants it. Enabled, it passes the press to Day as NavBack on WINDOW_NODE, and the predictive preview does not show for that press.
HarmonyOS (ArkUI)the entry page’s onBackPress, reached once Navigation has nothing to pop and no cover is up, consumes the back and passes it to Day. nav_back: { native: true } reaches the handler the same way; ArkUI has no call that presses the system back, so the native form does not pop a destination there.
iOS / macOS / GTK / Qt / WinUIno system back to take: the handler runs for nav_back() and dayscript’s nav_back
webthe browser’s Back is history-based and left to the browser; the handler runs for nav_back()

The precedence, the enabled toggling, and both dayscript forms are covered by mock_e2e::system_back_handler_runs_after_covers_and_pushed_pages, mock_e2e::system_back_arming_follows_enabled, the system_back tests in day-pieces (selecting a tab from code, and ranking by nesting), and day-script’s nav_back_steps_reach_the_system_back_handler.

Each mounted surface registers a small adapter over its own signal, so a string route can address the whole tree. The grammar:

route    = segment *( "/" segment ) [ "?" query ]     e.g.  mail/inbox/msg-42?hint=shared
segment  = a nav host/tabs item key, or a stack destination key
query    = name "=" value *( "&" name "=" value )     (params for the destination builders)

Reserved characters inside a segment or param value (/ ? & = %) are percent-encoded; day_core::nav::{parse_route, encode_route} do this for you. Two addressing modes:

  • A single key is relative: navigate("inbox") reaches the innermost surface first and falls through outward. For a nav/tabs it sets the active key; a nav_stack claims only "" (pop to root), so sibling keys fall through to the enclosing surface. This is what a button deep inside a page wants: address the nearest thing that knows the key.
  • A /-separated path is absolute: navigate("mail/inbox/msg-42") anchors at the outermost surface that knows the first segment, resets every surface inside the anchor to its root, then feeds the remaining segments inward. Segments for surfaces that only mount as the outer switch takes effect are queued and consumed as those surfaces register. One string reaches a stack three levels deep on a cold start. A stack consumes absolute segments unconditionally (its destinations are open-ended); the explicit path is the stack’s state (set-semantics: navigating mail/inbox while mail/inbox/msg-42 shows pops the detail, and switching back into a resident tab with a deeper path, settings/privacy after an earlier settings/general, first pops that tab’s stack to its root).
  • A fallback answers what nothing mounted knows: a piece that presents a destination outside the app’s navigation registers with day_core::register_nav_fallback instead of register_nav. Either form of route reaches it only after every mounted surface has refused the first segment, however early it registered, and an absolute path’s remaining segments go to its own enter. The Settings cover on a phone is one: settings/search selects an app’s own settings section when the app has one (built yet or not) and presents the cover only when it has none. A fallback contributes nothing to current_route().

Params ride the query string: route_param("hint") / route_params() inside a destination builder return the values of the navigation being applied. They describe the navigation in flight; a push you perform by writing the path signal directly carries its data in your own state instead.

  • nav_back(): pops the innermost visible surface, falling through when it is already at its root. Inactive resident tabs are skipped. A presented cover and its inner navigation take precedence over the covered window: Back pops its inner stack first, then dismisses the cover. On a sidebar with a content list, an open detail is the innermost layer, whether it is pushed over the list in a collapsed stack or shown beside it in a split: the call closes it (detail_visible := false), the same place the native back lands, and only a second call leaves the section.
  • current_route(): the full path, every mounted surface’s contribution from outermost to innermost ("mail/inbox/msg-42"). It round-trips through navigate, so persisting the whole route by hand is two lines: save current_route() on the way out (day-part-preferences works), navigate(&saved) after the first mount on the way back. For a single surface, .restore (below) does the same without the plumbing. dayscript’s assert_route compares against the same full path.
  • Startup deep links (DAY_DEEPLINK) and warm links (RouteRequested) route the same way. On hosts with no process environment the platform entry records the launch route with day_core::set_launch_deeplink instead; Web seeds it from the page’s URL hash (docs/web), so …/#controls opens on that section. The OS side (scheme registration, per-platform intake, and testing) is docs/deep-links.
  • The URL stays live both ways on Web: day-core reports every route change to the toolkit (Toolkit::set_route: the hash updates as you navigate, one history entry per step), and a hash change the app didn’t write (browser back/forward, a hand-edited URL) arrives as Event::RouteRequested and navigates. Other toolkits inherit the no-op default.

Because each surface owns its own signal, a nav(Tabs) or a nav_stack nests inside a nav(Sidebar) section with no extra wiring. There is no global navigation controller to arbitrate, only this string adapter for addressing.

Sibling one-of-N surfaces need .local(). Every routed surface contributes to the full route, so two nav/tabs at the same level (a filter tab strip beside a main tab bar) both feed current_route(): you get section/mainKey/filterKey, and navigate("filterKey") is ambiguous. Mark all but the primary one .local(); it then drives its own signal without touching the route. A nav host nested one level deeper (a Tabs inside a Sidebar section) is the opposite case and should stay routed; that cascade is what nesting is for. In debug builds, two routed one-of-N surfaces at the same level log a warning naming this fix.

Ordering caveat: relative dispatch and the full route walk the registry in mount order, which equals nesting depth for a single active chain. Two sibling surfaces mounted at once (two independent stacks visible in one window) are ordered by mount time, not focus. Prefer absolute routes (or drive the signals directly) in such layouts.

day lint cross-checks literal navigate("…") calls and dayscript navigate:/assert_route: routes against the declared keys in your sources (.item("key", …) and item("key", …) call sites, the literals in the first argument of nav_items(…), as in nav_items(|| vec![String::from("settings")], …), and routes! { … => "key" } blocks): a route whose first segment nothing declares is reported (day::lint::unknown-route) rather than failing silently at runtime.

Restoring state across launches (.restore)

When you want a surface to reopen where the user left it, mark it with .restore(key) instead of wiring current_route() by hand:

nav(section).restore("nav.section")   // reopens on the last-viewed section
nav_stack(path, home).restore("mail.path")     // rebuilds the pushed path

The selected key (or the stack’s /-joined path) is saved under key on every change and read back at build. A pending launch deep link wins: a DAY_DEEPLINK (or a set_launch_deeplink hint) routes one turn after mount, so .restore steps aside and the link decides where the app opens. A saved value that no longer fits (a nav host key whose item is gone, a stack segment that no longer parses) is ignored rather than restoring a broken state.

.restore reads and writes through the app’s preferences: day::launch installs day::prefs::install_nav_store() before the UI mounts unless the app installed a store of its own with day_core::set_nav_store first (or turned off the day-app crate’s prefs feature).

The prefs store is disk-backed, so restore also survives an Android process death: the OS reclaims a backgrounded app and rebuilds it on return, and the value is still on disk. With no store installed, .restore is a silent no-op, so the same code compiles and runs on a target where you don’t want persistence: the Showcase installs the store on web only, where a reload is routine, and starts fresh on native. To back .restore with your own storage, implement day_core::NavStore and hand it to day_core::set_nav_store.

Typed routes

Route keys are data, and strings are their wire format. The Route trait carries the two-way mapping:

pub trait Route: Clone + PartialEq + 'static {
    fn key(&self) -> String;                  // typed value → path segment
    fn from_key(key: &str) -> Option<Self>;   // path segment → typed value
    fn title(&self) -> String { self.key() }  // native nav-bar title (defaults to the key)
}

title() is the label a stack shows in the native navigation bar for a pushed page. It defaults to the wire key, so override it to display a name when the key is not presentable (e.g. a route that carries only an id can look the name up from your data). The stack tracks title() separately from route equality. A route can read reactive metadata and change its native header after a load without replacing the page. A merged stack only updates the header while it owns the top page.

String implements it (the untyped baseline: every segment parses), and for plain enums the routes! macro writes both sides:

day::routes! {
    pub enum Section { Home => "home", Stack => "stack" }
}

let section = Signal::new(None::<Section>); // None = the collapsed mobile list
nav(section)
    .item(Section::Home, res::str::home(), home_page) // compile-checked, no raw keys
    .item(Section::Stack, res::str::stack(), stack_page)

A sidebar nav keys on Option<Section> (None ↔ "", the no-selection list state); tabs always have a selection, so they key on the bare enum (Signal::new(Tab::One)). Blanket impls cover both: Option<R> is a Route whenever R is, and .item takes the bare variant either way.

Variants carry data: this is where typed routes improve on string encoding. Implement Route by hand and put the payload in the variant:

enum Drill { Depth(u32), Item { id: u32 } }        // "3" ↔ Depth(3), "item-42" ↔ Item{id:42}

let path = Signal::new(Vec::<Drill>::new());
nav_stack(path, root).destination(|d: &Drill| match d {
    Drill::Depth(n)    => level_page(*n),          // parsed, not string-split
    Drill::Item { id } => item_page(*id),
})
// push: path.update(|p| p.push(Drill::Item { id: 42 }));

The destination builder receives the parsed value; encode/decode lives in exactly one place (the Route impl). A typed stack also validates absolute routes: a segment from_key rejects is refused (the navigation stops there) instead of pushing an unparsed key; a String stack keeps its open-ended accept-anything behavior.

Typed absolute paths compose with route(…), and navigate_to is the typed relative form:

navigate_to(&Section::Home); // ≙ navigate("home")
route(&Section::Stack)
    .then(&Drill::Item { id: 42 })
    .param("hint", "linked")
    .navigate(); // ≙ navigate("stack/item-42?hint=linked")
nav_link_to(
    res::str::open_42(),
    route(&Section::Stack).then(&Drill::Item { id: 42 }),
)

Everything downstream is unchanged: current_route() still returns the encoded string (which is what you persist), deep links and dayscript still speak segments, and the two layers meet only at key/from_key. Mixed trees are fine: a typed nav host over a String stack, or vice versa.

Composition

On HarmonyOS, each realized stack owns an ArkTS Navigation/NavPathStack in DayNavigation.ets, embedded at that stack’s position in the Day tree through a BuilderNode. Its root and pushed pages occupy separate NodeContent slots and receive their actual content bounds, excluding native title bars. The window itself mounts the Day tree and the full-window cover layer; it does not wrap all tabs in a shared Navigation. This follows Harmony’s component-level Navigation model.

Titles, search, guarded Back and pop acknowledgments are addressed to their owning host. Switching tabs hides a resident stack without popping it. Late callbacks from a disposed host cannot mutate a sibling stack. The bottom tab bar remains composed from ArkUI nodes, with its highlight updated together with selection. The emulator regression fixture checks independent histories, hidden pushes, guarded Back and host reconstruction.

Resident tab pages also own their native frames. A page joining a tab host after its initial layout receives a deferred report of the current page area, excluding the tab bar. Day’s initial full-host fallback must never overwrite that frame: otherwise a nested scroll view thinks the area behind the tab bar is visible and stops scrolling before its last control can be seen. The fixture also checks native scroll bounds with wrapping and dynamically changing content.

Before this ownership fix, Harmony had one window-global navigation stack: the last realized stack could name and control unrelated tabs. This affected multi-host compositions such as Stanza’s Library/Catalogs/Settings layout, rather than implying that every single-stack Harmony app was broken.

To reproduce the Mail.app or Files.app navigation pattern, nest the containers:

nav(section)
    .style(NavStyle::Sidebar)
    .item("library", res::str::library(), || {
        nav_stack(lib_path, library_root).destination(detail)
    })

The sidebar selection drives which section shows; the selected section is itself a nav_stack that drills down. Each surface owns its signal.

Nested stacks share one native container on mobile. When the enclosing host presents as a push stack (a phone, or any window too narrow for two panes; see size classes), a nav_stack built inside one of its pages does not mint a second native navigation controller; it pushes its own pages onto the enclosing host, so the whole chain (list → section → drill-down) is one native stack with a single back button. The inner nav_stack keeps its own path signal and route registration (so current_route(), deep links, and nav_back() fall-through are unchanged); only the native container is shared. Where the enclosing host presents as split panes a nested nav_stack is not merged; it renders in the detail pane with its own back-header, which matches the desktop idiom. A resident container (nav(Tabs)) is a merge barrier: a nav_stack inside a tab keeps its own host.

Split or stacked

A nav(Sidebar) shows its list beside the selected page in a wide window and pushes the page over the list in a narrow one. That follows the window, not the platform: it is resolved from the window’s size class and re-resolved whenever the window crosses a breakpoint, so one nav is right on a desktop, a tablet, and a phone. .presentation(…) pins it where the content only works one way. docs/size-classes is normative; it covers the breakpoints, what survives a re-presentation, and which toolkits morph today.

The content list (three panes)

Native pane on macos-appkit (a real contentList NSSplitViewItem), on Qt (the middle pane of the navigation QSplitter) and ios-uikit (UISplitViewController triple-column, merging into the stack at compact width); composed by the nav host everywhere else, including the mock. Cap::NavContentList carries the three-way answer. Since 2026-08 the composed compact flow is push navigation: a list-backed tab is a nested navigation controller, not a swap.

.content_list(ContentList::new(build)) gives a nav host the Mail shape: sidebar, content list, detail (mailboxes, message list, message). The list is built once and stays resident for the host’s life; its content follows the app’s own signals (the sidebar selection scoping it, the row chosen from it), so switching sections re-scopes it without a rebuild. The pane’s configuration is one ContentList value with its own builders:

nav(section).style(NavStyle::Sidebar)
    .content_list(
        ContentList::new(timeline_pane)              // the middle column, built once
            .width(400.0)                            // preferred; drag limits are the backend's
            .only_for(|k| k != "settings")           // full-page sections collapse the pane
            .detail_visible(reader_open)             // the compact push gate, two-way
            .detail_title(move || open_title.get()), // the detail layer's bar, live
    )
    .items(…)
    .destination(…)                                  // the detail only; the list is not in here
  • Where the pane lands is Cap::NavContentList’s answer. Native (macos-appkit, Qt, GTK): a real pane at every presentation, with a draggable divider on each side; a narrow window collapses the sidebar and keeps the list, as a narrow Mail.app does. On Qt the pane is the middle of the same three-pane QSplitter the sidebar lives in, hidden on a host that declared no list, so pane indices and the back header never move; on GTK it is the start child of the inner of the host’s two nested GtkPaneds, hidden the same way (since 2026-09; the toolkit notes below have the shape). Emulated (ios-uikit): a real column while expanded that merges into the navigation stack when the host collapses. A UISplitViewController fixes its column count at creation, never shows the primary without the supplementary, and drops a controller re-mounted in another of its columns, so a destination without a list gets a double-column host and one with a list a triple-column host: a change between the two on a wide window rebuilds the host with fresh column controllers and moves the pages across, which is what SwiftUI does when a NavigationSplitView changes column count. Day’s handle for the host is a container the split’s view fills, so the rebuild never touches the tree. Unsupported (everything else): the nav host composes the list beside each list-backed destination while split, and as the root layer of the gated push flow while compact.
  • ContentList::detail_visible is the compact flow’s gate, two-way like every binding. Wide layouts never gate on it (the detail pane is always on screen, showing the app’s empty state until a row is chosen), but a back still treats it as the open layer: while it is true beside the list, the back closes the detail (writes false) and only the next back leaves the section, so clear what the pane shows when the signal goes false. Where the list is composed into the destination’s page, a platform back (Android’s, HarmonyOS’s) would pop that page, list and detail together, so the host arms NavPatch::GuardTop while a detail is open side by side and closes it through Day instead. Stacked, the content list is the top of the stack until the app writes true (a row was opened); the detail pushes then, and the platform’s back writes false on the way out. In a chrome presentation (a tab bar, a rail) the same flow runs inside the tab: the destination’s page is a nested navigation host (a UINavigationController in the tab, a Material toolbar over the fragment back stack), so the tab gets a navigation bar, a title, and a native back, and the nav host’s bar actions ride that bar (a tabs chrome otherwise draws none). Without detail_visible a stacked host behaves classically (the detail pushes on selection).
  • ContentList::detail_for(selection) is detail_visible for a list whose selection is the detail’s subject: it takes a Binding<Option<T>> and reads true while it holds a value. Writing Some opens the detail; the back’s false writes None, which clears the selection too, so one signal serves the list (List::selection, docs/list), the detail and the gate. The day new starter uses it this way.
  • ContentList::detail_title names the detail layer’s navigation bar: the pushed editor on a phone, the detail page’s bar wherever the toolkit titles one. Reactive like every title: a closure reading your own state retitles the live bar (NavPatch::Title) as that state changes, so the bar can carry the open item’s name. Unset, the detail layer keeps its destination’s title.
  • ContentList::only_for collapses the pane per destination (NavPatch::ListVisible): a settings page takes the whole detail area, and selecting a list-backed section brings the pane back.
  • A host with a content list joins the split’s default-selection rule at every presentation: the pane needs a selection to scope itself to, so a collapsed host opens on the list rather than on bare sidebar rows.
  • The native resident pane (Native, and Emulated while expanded) is a merge barrier like a chrome page: a nav_stack inside it keeps its own container, with the desktop back header above its pages. The composed compact flow is the opposite: there the list is the root page of a push stack (the tab’s own navigation controller, or the enclosing host’s), so a nav_stack inside it merges, and a drill-down from the list (a category, then its stations) is real pushes with the native back, with the gated detail pushed on top of whatever the stack pushed.

Keyboard: pair the list’s content with .focusable() + .focused(sig) + .on_key(…) (docs/focus) so the arrows walk the selection, and a scroll_target signal (ScrollTarget::Id) to keep the selected row in view.

Toolkit notes

Platform guidance: Apple: navigation and search; Windows: navigation design.

  • GTK adopts libadwaita throughout (adw::Application loads the Adwaita stylesheet). The window is an AdwApplicationWindow whose content is an AdwToolbarView (an AdwHeaderBar supplies the title, window controls, and drag; Day’s content sits below it). Navigation: Sidebar → two nested GtkPaneds — sidebar | (list | detail) — with a user-draggable divider on each side, the AppKit NSSplitView shape; nav_stack → AdwNavigationView (push/pop + back gesture; its popped signal writes native back into the path). A split pane’s page (a GtkFixed) sits in a filling DayCell — day-toolkit-gtk’s custom container, which asks GTK for no size and hands its child the whole allocation — so a page’s Day-laid frame never becomes a pane’s GTK minimum; each cell carries its pane’s honest minimum as its size request instead (NAV_SIDEBAR_MIN_W, NAV_LIST_MIN_W, and 200pt for the detail), no pane may shrink below it, and the divider stops there (the maximums are clamped on the position notify). Each pane cell reports its page’s size from its own size_allocate, before it allocates the page, and day-core dispatches the report at once when its tree is free — so the page is re-laid inside the same GTK layout pass and follows a divider drag live, as AppKit’s setFrameSize: report does. (Reporting from an idle after the position notify, as the first paned version did, trailed the divider by a frame or more.) The sidebar folds the way an AppKit split item does: when the window has no room for it beside the other panes’ minimums it collapses, and it comes back at its last width once there is room again (24pt of slack keeps a resize on the threshold from flapping); the toolbar’s sidebar toggle hides it independently, and a toggled-off sidebar stays off. The inner paned exists on every host, list or not — with no list page, or one collapsed by ContentList::only_for, GTK gives the detail the whole inner allocation and draws no handle — so the widget shape never changes under live pages. A stack page’s GtkFixed is wrapped in an AdwNavigationPage. Tabs use an AdwViewStack with a .linked toggle switcher; dialogs use AdwAlertDialog (docs/dialogs). Decision (2026-09): AdwOverlaySplitView is gone from this toolkit, with no flag to bring it back. libadwaita pins sidebar widths by design (the GNOME HIG has no draggable sidebars), so the Adw split could never give Day’s desktop apps the adjustable columns AppKit and Qt have, and its pane sizing — a min == max sidebar, a content pane whose minimum was its own Day frame — fought every relayout (the issue #19 reveal jump, the External-policy scroll windows it took to break minimum propagation). What the Adw split supplied that the paned does not — a slide on the sidebar toggle, and the adaptive collapsed breakpoint — is either not wanted (dayscript screenshots the instant a toggle returns) or done by the fold above. DAY_GTK_SPLIT, which used to select the paned, is no longer read.
  • macOS NSSplitView / Qt QSplitter honor the resolved presentation: Split shows both panes; a nav_stack collapses the empty sidebar and stacks every page (top visible) in the detail pane, with a back header (chevron + centered title, hidden at the root) above the pages; desktop has no system back affordance, so a pushed page carries its own way out. The button emits the same NavBack event mobile back does, writing the pop into the path signal.
  • Android hosts each page in an androidx Fragment that retains its Day-owned view (the react-native-screens pattern: the FragmentManager owns when a page shows, Day owns what it shows). An adaptive host keeps its current section outside fragment history, matching Android’s two-pane navigation guidance. Compact section Back clears the selector and explicitly closes the sliding pane; wide section changes replace the current content without accumulating history. Free pane dragging is locked so pane visibility cannot diverge from selection. Toolbar chrome uses the same conservative stacked default as the model before native measurement, then follows the settled presentation after every layout pass (even with unchanged outer bounds). Compact destinations and tiled nested pages expose a localized Up button. Only the tiled base section omits it, because its root list is already visible alongside it. A nested push is a replace() back-stack transaction carrying MaterialSharedAxis transitions. Each page view is a transition group, so the push and pop move the page as one view: left to the framework’s default, the transition animates the page’s leaf views individually, and Day’s layout of those views in the frames after the push (and a native row’s re-bind) cancelled the animators, so a page of settings rows appeared with no motion while a page of plain labels happened to fade. This gets the whole back behavior from the platform: OnBackPressedDispatcher dispatches hardware/gesture back on every API level, the FragmentManager seeks the pop transition live under the predictive back gesture on API 34+ (progress, cancel, commit), and its back callback is enabled only while the back stack is non-empty, so the system’s predictive back-to-home animation stays available at the root (apps opt in with android:enableOnBackInvokedCallback="true"; the scaffold does). Native pops are reported after fragment transactions settle as NavBack { already_popped: true }. Acknowledgements are tied to the removed page, consumed by either an answering Popped patch or page removal; owners that omit Popped cannot leave a stale counter that skips a later pop. Compact section Back uses an explicit OnBackPressedCallback, not fragment history; it does not have a seekable fragment predictive animation. Nested pages retain fragment predictive Back. Rust-initiated pops run popBackStack. When testing on Android 13/14 (API 33/34), the system gates predictive-back animation behind Developer options → “Predictive back animations” (adb shell settings put global enable_back_animation 1), and gesture navigation must be active; Android 15+ enables it by default.
  • Mobile presents the host as a native stack for both Sidebar (collapsed) and nav_stack. A nav_stack nested inside such a host’s page merges into it (one UINavigationController / DayNavHost, one back button) rather than nesting a second controller; see Composition. No toolkit change is involved: the shared host receives NAV_PAGE pushes/pops from both the outer surface and the inner stack identically to a single-surface stack.

Progress over sidebar icons

nav(selection).icon_progress(move || active.get()) accepts a reactive closure returning Vec<(K, Option<f64>)>: active route keys with None for indeterminate activity or Some(fraction) for progress from zero to one. Omit a key when its work finishes. Invalid fractions become indeterminate and finite fractions clamp to the valid range.

This binding is independent of .items: it emits NavMenuPatch::IconProgress without rebuilding the rows, loading their icons again, changing selection or requesting layout. Changes to the row set re-map route keys to current indexes, so filtering and reordering cannot move progress onto another item. A row revision also reapplies unchanged progress after native rows are recreated. The binding is owned by the navigation scope.

AppKit and UIKit render a small, muted circular overlay over the existing leading icon. An indeterminate quarter ring rotates in Core Animation; a known fraction fills the ring. The background softens the icon beneath it. No Rust animation timer or canvas redraw loop runs. Only changed visible cells receive updates, and newly displayed/reused cells receive the stored state. Completion removes the layer/view and its animation. Text, badges and row geometry stay unchanged. Other toolkits currently ignore this optional decoration.

Reordering sidebar destinations

Use .reorder_items(|key| is_movable(key), |moved, target| persist_move(moved, target)) to make contiguous runs of destinations draggable. Static headers and ineligible rows form boundaries that no drop can cross. target names the row whose position the moved row takes, in the pre-removal order. Keep the eligibility callback pure and persist changes in the commit callback. Cap::NavReorder says how a toolkit does it:

  • Native (AppKit): the sidebar stays the toolkit’s own. The source-list outline drags the rows in its own drag pipeline, with the gap Finder’s sidebar shows, and a drop past the end of the run lands at that end. The sidebar keeps every native trait, the system Sidebar icon size among them.
  • Emulated (GTK, Qt, WinUI, web, ArkUI): Day stands a reorderable list in for the sidebar, with long-press dragging on touch platforms.
  • Unsupported (UIKit, Android): the native navigation widget stays and ignores the option, independently of draggable content-list support. Android uses Material NavigationView so long-press feed menus do not compete with dragging.

A reorderable sidebar is addressable as nav-reorder-list for dayscript reorder steps either way, and its indices include fixed section-header rows. The stand-in list’s rows are also addressable as sidebar:item:<key> and sidebar:header:<id>; a native sidebar’s rows are not Day elements, so a script reaches them through the sidebar itself (select, reorder). Tabs and rails remain fixed. Without the option, the existing native sidebar widget is unchanged.

Moving rows between sections

.regroup_items(drag, dropped) lets a row cross section headers as well, so a reader can drag a feed from one collection’s section into another’s. drag returns a NavDrag for each row, and Day asks again whenever the rows change:

  • NavDrag::Reorder rows move within their section and into other sections.
  • NavDrag::Regroup rows move only into other sections. Use it when a section keeps the app’s sorted order, so a drop inside it would be undone by the next sort.
  • NavDrag::Fixed rows don’t drag, and their section takes no drops.

A section takes a drop only when every row in it is Reorder or Regroup. Rows above the first header form one unnamed section. dropped receives a NavDrop: the moved key, the destination’s section_id (None for a section declared without one and for the unnamed section), and before, the key the row now sits before (None at the section’s end). Day reports before for a sorted destination too; ignore it there and insert at the sorted position. A drop back where the row started reports nothing. Apply the move to the app’s data; the sidebar then shows the new rows.

nav(selected)
    .items(nav_items(move || feed_rows(), |row| {
        let item = item(row.key.clone(), row.title.clone());
        if row.first_in_collection {
            item.section_id(format!("collection:{}", row.collection), row.collection_title.clone())
        } else {
            item
        }
    }))
    .regroup_items(
        |key| if is_feed(key) { NavDrag::Regroup } else { NavDrag::Fixed },
        move |drop| store.move_feed(drop.moved, drop.section, drop.before),
    )

reorder_items and regroup_items are alternatives. A nav that declares both keeps the one declared last. Cap::NavReorder decides the path here too:

  • Native (AppKit): the source-list outline offers the gaps of every section that takes a drop, with Finder’s gap look. It offers no gap in a section that holds a fixed row, none above the first header unless rows sit there, and none in a sorted row’s own section. A gap belongs to the nearest header above it, so the gap just above a header ends the previous section. A drop onto a header lands in that section’s first gap. The outline reports the drop as Event::NavRegroup { from, section, before } in item indices, and the nav checks it against the rules above before it calls dropped.
  • Emulated (GTK, Qt, WinUI, web, ArkUI): the stand-in list lets a row cross header rows, and its guard applies the same rules.
  • Unsupported (UIKit, Android): unchanged, the sidebar doesn’t drag.

A dayscript reorder step drives both paths with the same display rows, headers counted. The row at from ends up at index to, as in any list reorder, and its section is the nearest header above that place. Moving a row down onto a header row lands it as that section’s first row; moving it up onto a header row lands it at the end of the section above. A step the rules deny fails, as a denied reorder does.

Collapsible sidebar sections

Give each group a stable, unlocalized identity with .section_id("owner:daybrite", title, content) on a Nav, or .section_id(id, title) on a dynamic NavItem. Collapsible headings are one Sections value: .sections(Sections::collapsible(collapsed)) takes the set of closed groups as a Signal<HashSet<String>> or any other binding; absent IDs default to expanded. Retain IDs for temporarily filtered-out groups. Heading identity is independent of the title and first child; unkeyed .section(title) falls back to the first route and should not be used for persistent dynamic groups. A collapsed group never removes its destinations from route resolution or changes the selected detail page.

Sections::collapsible(set).on_change(|id, expanded| ...) runs after a user/script disclosure changes state, with no callback echo when the app restores or writes the signal. Apps can persist the signal in their preference store, scoped to an account where appropriate. Sections::restored(key) provides the same behavior through the installed NavStore, encoding sorted IDs as length-prefixed records; it tolerates malformed saved data and uses a scope-owned binding. .on_change chains onto either form. Day-Hub saves groups per GitHub account; Day-Showcase saves stable group IDs in preferences.

The sidebar uses a two-level tree. AppKit retains genuine floating source-list group headers and system disclosure controls; UIKit, GTK, Qt, WinUI and Android use their native tree/group controls. DOM and ArkUI use composed disclosure. Tabs and rails do not gain disclosure. When both options are supplied, collapsible sections take precedence over reorder_items and regroup_items; reordering and collapsing in the same sidebar is not currently supported. Apps such as Day-News retain reordering until that combination is implemented.