Struct Nav 

pub struct Nav<S: Binding<K>, K: Route = String> { /* private fields */ }

Implementations

impl<K: Route, S: Binding<K>> Nav<S, K>

pub fn refreshable<M>( self, refreshing: impl IntoReactive<bool, M>, action: impl Fn() + 'static, ) -> Self

Add the platform’s pull-to-refresh control to the sidebar rows (docs/navigation.md). UIKit uses UIRefreshControl, Android SwipeRefreshLayout. Other toolkits can ignore this affordance, so retain a Refresh command for keyboard/accessibility users. refreshing is app-owned: set it synchronously when accepting a request and clear it on completion, failure or cancellation. Repeated pulls while busy are ignored. A declined request stops the indicator immediately. Programmatic state writes never call action. The handler and state bindings live only as long as this navigation.

pub fn sections(self, sections: Sections) -> Self

Collapsible sidebar sections (docs/navigation.md), as a Sections value: nav(sel).sections(Sections::restored("nav.sections").on_change(f)).

pub fn section_id<M>( self, id: impl Into<String>, title: impl IntoText<M>, content: impl NavContent<K>, ) -> Self

A section with a persistent identity independent of its localized title or first row, heading content (one item, a tuple, an Option, a nav_items block, or a mix).

pub fn reorder_items( self, eligible: impl Fn(&K) -> bool + 'static, moved: impl Fn(K, K) + 'static, ) -> Self

Enable dragging within contiguous runs of eligible sidebar items. Fixed items and section headers cannot be crossed. The callback receives the moved key and the key whose position it takes (indices refer to the order before removal). Uses the shared list reorder driver where Cap::NavReorder supports it; otherwise retains the native navigation widget. UIKit navigation remains fixed even though content lists support dragging. Tab/rail chrome remains fixed. Persist the order in the callback’s backing data.

pub fn retain_selection_when(self, keep: impl Fn(&K) -> bool + 'static) -> Self

Preserve the current destination when its row disappears and keep returns true. Useful for filtered sidebars: reading a feed’s last unread article can hide its row without closing the article. The native sidebar then has no highlighted row. Return false for deleted records to retain the normal selection-reset behavior. Evaluated when the item list changes; pair with Self::destination for dynamic keys.

pub fn icon_progress( self, progress: impl Fn() -> Vec<(K, Option<f64>)> + 'static, ) -> Self

Progress over leading icons, without rebuilding rows or changing label geometry. Return active route keys with None while connecting/unknown-length, or Some(0..=1) for a known fraction. Omit finished keys. AppKit/UIKit animate in the compositor; other toolkits currently leave icons unchanged. Bind separately from .items.

pub fn style(self, style: NavStyle) -> Self

pub fn title<M>(self, t: impl IntoText<M>) -> Self

The sidebar / window title (Sidebar style).

pub fn section<M>( self, title: impl IntoText<M>, content: impl NavContent<K>, ) -> Self

A section: content (one item, a tuple, an Option, a nav_items block, or a mix) under a header. Backends without grouped rows ignore the header and show one flat list, so a section is a grouping hint, never a source of items the user cannot otherwise reach.

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

pub fn header<P: Piece>(self, build: impl FnOnce() -> P + 'static) -> Self

An optional piece shown above the sidebar list (a logo, app name…).

pub fn footer<P: Piece>(self, build: impl FnOnce() -> P + 'static) -> Self

An optional piece pinned below the sidebar list, outside its scroll area. It belongs to the root page: stacked destinations do not carry it along. Like Self::header, this slot applies to sidebar navigation, not tab/rail chrome.

pub fn presentation(self, presentation: NavPresentation) -> Self

Pin the presentation instead of letting the window’s size decide (docs/size-classes.md).

Leave this unset (the default) and the nav shows sidebar+detail on a window wide enough for both and stacks on one that is not, re-presenting live as the window is resized or the device rotated. Pin it when the content only works one way: a settings sidebar whose detail is meaningless alone, a wizard that must stay a stack.

A pin is still a preference. A toolkit with no split container (the phones today) stacks whatever is asked for, exactly as it does for the automatic case.

pub fn content_list(self, list: ContentList<K>) -> Self

A content-list pane between the sidebar and the detail, the Mail shape (docs/navigation.md), as a ContentList value:

nav(scene.section).content_list(
    ContentList::new(pages::items::item_list_pane)
        .width(320.0)
        .only_for(|s: &Section| matches!(s, Section::Items))
        .detail_visible(scene.detail_open)
        .detail_title(move || pages::items::detail_title(scene)),
)

pub fn item<M, P: Piece>( self, key: impl Into<K>, title: impl IntoText<M>, build: impl Fn() -> P + 'static, ) -> Self

Add one destination: item(key, title).page(build) in one call. key addresses it (navigate / deep link / dayscript); title is its label; build runs when the item is first shown. For a typed nav over Option<Section> pass the bare Section::X. For an icon, a badge or a tint, build the item value and add it with items.

pub fn items(self, content: impl NavContent<K>) -> Self

Add items (docs/navigation.md): one item, a tuple of them, an Option, a Vec, a data-driven nav_items block, or a mix. Static items and blocks may be mixed in any order; the final list is their declaration order.

nav(sel).items((
    item("home", res::str::home()).icon(res::images::home).page(home_page),
    nav_items(move || rooms.get(), |r| item(r.id.clone(), r.name.clone())),
    prefs.nav_item(Section::Settings),
))

pub fn destination<P: Piece>(self, build: impl Fn(&K) -> P + 'static) -> Self

Build the page for a key whose item has no page of its own (the rows of a data-driven block). Mirrors NavStack::destination; unused for a nav whose items all carry a page.

pub fn local(self) -> Self

Use this nav as a local widget: its selection is not part of the app route, so it neither adds a segment to current_route nor intercepts navigate/deep links.

Reach for this when a page already routes and you embed a second one-of-N control in it (a filter tab strip, a secondary sidebar). Two routing selectors at the same level both feed current_route(), so you’d get section/childA/childB and navigate("childB") would be ambiguous; mark all but the primary one .local(). A nav nested one level deeper (a Tabs inside a Sidebar section) is a different case and should stay routed: its key belongs in the cascade. In debug builds, two routed one-of-N surfaces at the same level log a warning naming this fix (docs/navigation.md).

pub fn restore(self, key: impl Into<String>) -> Self

Remember the selected item across launches (docs/navigation.md). The selected key is saved under key on every change and restored at build (so the app reopens on the tab/section the user last had) unless a launch deep link is pending, which wins. day::launch installs the preferences as the store (docs/navigation.md); a stale saved key (its item no longer exists) is ignored. Works whether or not the nav is routed.

pub fn toolbar<M>(self, content: impl ToolbarContent<M>) -> Self

Declare toolbar items on this host’s chrome (docs/toolbars.md): the sidebar column where the presentation has one, and the root list when it has collapsed to a stack.

This is where a command that acts on the list belongs: “add an item”, “sort”, “filter”. A command that acts on whatever page is open belongs on the page instead, declared with the same method on the piece that page builds, and then it comes and goes with that page rather than riding a list it cannot act on.

Takes one item, a list of them, or a closure that derives the list and re-runs whenever its reactive reads change.

nav(section)
    .toolbar(toolbar_button(day_core::id!(add), tr("add")).icon(Symbol::Add).action(add_item))

pub fn no_sidebar_toggle(self) -> Self

Do not draw the platform’s own show/hide-sidebar affordance on this host’s chrome. It is on by default for a sidebar presentation, since every desktop expects one and the toolkit owns both the button and the behavior; this is for a window that should not offer it.

pub fn searchable(self, search: Search) -> Self

Make this surface searchable (docs/search.md), as a Search value:

nav(section)
    .style(NavStyle::Sidebar)
    .searchable(Search::new(query).prompt(res::str::search()).reveal(SearchReveal::OnPull))
    .items(nav_items(move || destinations().filter(|d| matches_query(d, &query.get())), destination_row))

Trait Implementations

impl<K: Route, S: Binding<K>> NavBuilder<K> for Nav<S, K>

fn refreshable<M>( self, refreshing: impl IntoReactive<bool, M>, action: impl Fn() + 'static, ) -> Self

Add the platform’s pull-to-refresh control to the sidebar rows (docs/navigation.md). UIKit uses UIRefreshControl, Android SwipeRefreshLayout. Other toolkits can ignore this affordance, so retain a Refresh command for keyboard/accessibility users. refreshing is app-owned: set it synchronously when accepting a request and clear it on completion, failure or cancellation. Repeated pulls while busy are ignored. A declined request stops the indicator immediately. Programmatic state writes never call action. The handler and state bindings live only as long as this navigation.

fn sections(self, sections: Sections) -> Self

Collapsible sidebar sections (docs/navigation.md), as a Sections value: nav(sel).sections(Sections::restored("nav.sections").on_change(f)).

fn section_id<M>( self, id: impl Into<String>, title: impl IntoText<M>, content: impl NavContent<K>, ) -> Self

A section with a persistent identity independent of its localized title or first row, heading content (one item, a tuple, an Option, a nav_items block, or a mix).

fn reorder_items( self, eligible: impl Fn(&K) -> bool + 'static, moved: impl Fn(K, K) + 'static, ) -> Self

Enable dragging within contiguous runs of eligible sidebar items. Fixed items and section headers cannot be crossed. The callback receives the moved key and the key whose position it takes (indices refer to the order before removal). Uses the shared list reorder driver where Cap::NavReorder supports it; otherwise retains the native navigation widget. UIKit navigation remains fixed even though content lists support dragging. Tab/rail chrome remains fixed. Persist the order in the callback’s backing data.

fn retain_selection_when(self, keep: impl Fn(&K) -> bool + 'static) -> Self

Preserve the current destination when its row disappears and keep returns true. Useful for filtered sidebars: reading a feed’s last unread article can hide its row without closing the article. The native sidebar then has no highlighted row. Return false for deleted records to retain the normal selection-reset behavior. Evaluated when the item list changes; pair with Self::destination for dynamic keys.

fn icon_progress( self, progress: impl Fn() -> Vec<(K, Option<f64>)> + 'static, ) -> Self

Progress over leading icons, without rebuilding rows or changing label geometry. Return active route keys with None while connecting/unknown-length, or Some(0..=1) for a known fraction. Omit finished keys. AppKit/UIKit animate in the compositor; other toolkits currently leave icons unchanged. Bind separately from .items.

fn style(self, style: NavStyle) -> Self

fn title<M>(self, t: impl IntoText<M>) -> Self

The sidebar / window title (Sidebar style).

fn section<M>( self, title: impl IntoText<M>, content: impl NavContent<K>, ) -> Self

A section: content (one item, a tuple, an Option, a nav_items block, or a mix) under a header. Backends without grouped rows ignore the header and show one flat list, so a section is a grouping hint, never a source of items the user cannot otherwise reach.

fn header<P: Piece>(self, build: impl FnOnce() -> P + 'static) -> Self

An optional piece shown above the sidebar list (a logo, app name…).

fn footer<P: Piece>(self, build: impl FnOnce() -> P + 'static) -> Self

An optional piece pinned below the sidebar list, outside its scroll area. It belongs to the root page: stacked destinations do not carry it along. Like Self::header, this slot applies to sidebar navigation, not tab/rail chrome.

fn presentation(self, presentation: NavPresentation) -> Self

Pin the presentation instead of letting the window’s size decide (docs/size-classes.md).

fn content_list(self, list: ContentList<K>) -> Self

A content-list pane between the sidebar and the detail, the Mail shape (docs/navigation.md), as a ContentList value:

fn item<M, P: Piece>( self, key: impl Into<K>, title: impl IntoText<M>, build: impl Fn() -> P + 'static, ) -> Self

Add one destination: item(key, title).page(build) in one call. key addresses it (navigate / deep link / dayscript); title is its label; build runs when the item is first shown. For a typed nav over Option<Section> pass the bare Section::X. For an icon, a badge or a tint, build the item value and add it with items.

fn items(self, content: impl NavContent<K>) -> Self

Add items (docs/navigation.md): one item, a tuple of them, an Option, a Vec, a data-driven nav_items block, or a mix. Static items and blocks may be mixed in any order; the final list is their declaration order.

fn destination<P: Piece>(self, build: impl Fn(&K) -> P + 'static) -> Self

Build the page for a key whose item has no page of its own (the rows of a data-driven block). Mirrors NavStack::destination; unused for a nav whose items all carry a page.

fn local(self) -> Self

Use this nav as a local widget: its selection is not part of the app route, so it neither adds a segment to current_route nor intercepts navigate/deep links.

fn restore(self, key: impl Into<String>) -> Self

Remember the selected item across launches (docs/navigation.md). The selected key is saved under key on every change and restored at build (so the app reopens on the tab/section the user last had) unless a launch deep link is pending, which wins. day::launch installs the preferences as the store (docs/navigation.md); a stale saved key (its item no longer exists) is ignored. Works whether or not the nav is routed.

fn toolbar<M>(self, content: impl ToolbarContent<M>) -> Self

Declare toolbar items on this host’s chrome (docs/toolbars.md): the sidebar column where the presentation has one, and the root list when it has collapsed to a stack.

fn no_sidebar_toggle(self) -> Self

Do not draw the platform’s own show/hide-sidebar affordance on this host’s chrome. It is on by default for a sidebar presentation, since every desktop expects one and the toolkit owns both the button and the behavior; this is for a window that should not offer it.

fn searchable(self, search: Search) -> Self

Make this surface searchable (docs/search.md), as a Search value:

impl<K: Route, S: Binding<K>> Piece for Nav<S, K>

fn build(self, cx: &mut BuildCx) -> RNode