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.
navselects one destination, such as a tab or sidebar item. Its signal holds the active key.nav_stackholds a path of destinations in aSignal<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.
Sidebar pull-to-refresh
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.
| Operation | Contract |
|---|---|
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.
| Toolkit | Native document presentation |
|---|---|
| AppKit | OS window tabs; composed mode parks pages in an NSTabView. |
| Qt | QTabWidget; macOS can move documents into OS window tabs. |
| GTK | AdwTabView/AdwTabBar, including macOS. OS-window grouping is unsupported because GDK owns window decorations. |
| WinUI | TabView with close requests and within-strip dragging. |
| Android | Scrollable Material TabLayout with add/close controls and host-scoped long-press dragging. |
| UIKit, ArkUI, DOM | Composed 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.
nav: one-of-N
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
NavStyle | What it draws |
|---|---|
Automatic (default) | The platform’s answer at this width — see the ladder below. |
Tabs | A tab bar at every size, however wide the window gets. |
Sidebar | A 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 width | presentation |
|---|---|
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).
| Presentation | Native container |
|---|---|
Split | a NavigationSplitView: macOS NSSplitViewController with a sidebar NSSplitViewItem (system material, source-list NSOutlineView, full-height under the titlebar) + detail; GTK two nested GtkPaneds (sidebar |
Stack | one page at a time, back-navigable: UINavigationController, AdwNavigationView, the Android back stack, or a desktop back-header above the pages. |
Tabs | the 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. |
Rail | the 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.
| Toolkit | Tabs presentation | Adaptive |
|---|---|---|
| macos-appkit | NSTabView (top tabs on a bezel), the detail pages as its items; labels from the host’s rows | no; a Mac narrows to a stack |
| ios-uikit | UITabBarController in .tabSidebar mode, driven by UITab on iOS 18+ and by viewControllers below it; see the iOS notes below | yes |
| android-material | navigation suite: BottomNavigationView → NavigationRailView → permanent NavigationView drawer, by width. A NavStyle::Sidebar pane is a NavigationView too; see the iOS notes below | yes |
| linux-gtk | AdwViewSwitcher over an AdwViewStack of resident pages, each in a filling DayCell | no |
| linux-qt | QTabWidget — Qt’s own one-of-N container | no |
| web-dom | a composed tab bar (.day-nav.tabs) | yes |
| harmony-arkui | a 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-winui | the same NavigationView with PaneDisplayMode = Top; Rail is LeftCompact, a real rail | no |
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.
nav_stack: push/pop with a value path
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:
| toolkit | native-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 |
| Android | a 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 |
| GTK | the top AdwNavigationPage sets can-pop = false (swipe/Escape disabled; the app drives back through its own control, which is guarded) |
| macOS / Qt / WinUI / web | no-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:
- a presented
covercloses (or the stack inside it pops first, as above); - a pushed page pops, a guarded stack’s
on_backdecides, a phone’s section page returns to its list; - 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;
- 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:
| toolkit | system back while a handler is enabled |
|---|---|
| Android | an 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 / WinUI | no system back to take: the handler runs for nav_back() and dayscript’s nav_back |
| web | the 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.
Routes: the string-route adapter (deep links & dayscript)
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 anav/tabs it sets the active key; anav_stackclaims 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: navigatingmail/inboxwhilemail/inbox/msg-42shows pops the detail, and switching back into a resident tab with a deeper path,settings/privacyafter an earliersettings/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_fallbackinstead ofregister_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 ownenter. The Settings cover on a phone is one:settings/searchselects an app’s ownsettingssection when the app has one (built yet or not) and presents the cover only when it has none. A fallback contributes nothing tocurrent_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 throughnavigate, so persisting the whole route by hand is two lines: savecurrent_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’sassert_routecompares 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 withday_core::set_launch_deeplinkinstead; Web seeds it from the page’s URL hash (docs/web), so…/#controlsopens 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 asEvent::RouteRequestedand 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
contentListNSSplitViewItem), on Qt (the middle pane of the navigationQSplitter) and ios-uikit (UISplitViewControllertriple-column, merging into the stack at compact width); composed by the nav host everywhere else, including the mock.Cap::NavContentListcarries 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-paneQSplitterthe 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 nestedGtkPaneds, 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. AUISplitViewControllerfixes 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 aNavigationSplitViewchanges 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_visibleis 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 istruebeside the list, the back closes the detail (writesfalse) and only the next back leaves the section, so clear what the pane shows when the signal goesfalse. 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 armsNavPatch::GuardTopwhile 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 writestrue(a row was opened); the detail pushes then, and the platform’s back writesfalseon 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 (aUINavigationControllerin 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). Withoutdetail_visiblea stacked host behaves classically (the detail pushes on selection).ContentList::detail_for(selection)isdetail_visiblefor a list whose selection is the detail’s subject: it takes aBinding<Option<T>>and readstruewhile it holds a value. WritingSomeopens the detail; the back’sfalsewritesNone, which clears the selection too, so one signal serves the list (List::selection, docs/list), the detail and the gate. Theday newstarter uses it this way.ContentList::detail_titlenames 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_forcollapses 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, andEmulatedwhile expanded) is a merge barrier like a chrome page: anav_stackinside 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 anav_stackinside 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::Applicationloads the Adwaita stylesheet). The window is anAdwApplicationWindowwhose content is anAdwToolbarView(anAdwHeaderBarsupplies the title, window controls, and drag; Day’s content sits below it). Navigation:Sidebar→ two nestedGtkPaneds — sidebar | (list | detail) — with a user-draggable divider on each side, the AppKitNSSplitViewshape;nav_stack→AdwNavigationView(push/pop + back gesture; itspoppedsignal writes native back into the path). A split pane’s page (aGtkFixed) sits in a fillingDayCell— 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 ownsize_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’ssetFrameSize: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 byContentList::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’sGtkFixedis wrapped in anAdwNavigationPage. Tabs use anAdwViewStackwith a.linkedtoggle switcher; dialogs useAdwAlertDialog(docs/dialogs). Decision (2026-09):AdwOverlaySplitViewis 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 adaptivecollapsedbreakpoint — 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/ QtQSplitterhonor the resolved presentation:Splitshows both panes; anav_stackcollapses 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 sameNavBackevent 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 carryingMaterialSharedAxistransitions. 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:OnBackPressedDispatcherdispatches 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 withandroid:enableOnBackInvokedCallback="true"; the scaffold does). Native pops are reported after fragment transactions settle asNavBack { already_popped: true }. Acknowledgements are tied to the removed page, consumed by either an answeringPoppedpatch or page removal; owners that omitPoppedcannot leave a stale counter that skips a later pop. Compact section Back uses an explicitOnBackPressedCallback, not fragment history; it does not have a seekable fragment predictive animation. Nested pages retain fragment predictive Back. Rust-initiated pops runpopBackStack. 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) andnav_stack. Anav_stacknested inside such a host’s page merges into it (oneUINavigationController/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::Reorderrows move within their section and into other sections.NavDrag::Regrouprows 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::Fixedrows 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 callsdropped. - 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.