Struct Selector 

pub struct Selector<S, K = String>
where
    S: SignalRw<K>,
    K: Route,
{ /* private fields */ }

A one-of-N selector whose active key is an app-owned signal (two-way, exactly like Picker/Toggle). Deep links and dayscript address items by key (docs/navigation.md).

The key type is any Route: String for raw keys, or a typed enum — use Signal<Option<Section>> for a sidebar (None = the collapsed mobile list) and Signal<Tab> for tabs (always selected).

let section = Signal::new("home".to_string());   // or Signal::new(None::<Section>)
selector(section).style(SelectorStyle::Sidebar)
    .item("home", tr("home"), home_page)         // or .item(Section::Home, …)
    .item("settings", tr("settings"), settings_page)

Implementations

impl<K, S> Selector<S, K>

where K: Route, S: SignalRw<K>,

pub fn style(self, style: SelectorStyle) -> Selector<S, K>

pub fn title<M>(self, t: impl IntoText<M>) -> Selector<S, K>

The sidebar / window title (Sidebar style).

pub fn section<M>(self, title: impl IntoText<M>) -> Selector<S, K>

Open a section: the NEXT item added (static or the first row of the next .items block) carries this header. Backends without grouped rows ignore it and show one flat list, so a section is a grouping hint, never a source of items the user cannot otherwise reach.

selector(sel)
    .section(res::str::smart_feeds())
    .item_icon("today", res::str::today(), res::images::today, today_page)
    .section(res::str::feeds())
    .items(move || st.feeds.get(), |f| item(f.id, f.name))

pub fn badge<M>(self, badge: impl IntoText<M>) -> Selector<S, K>

Attach a trailing badge — an unread count, a status — to the item just added: .item(…).badge(move || n.get().to_string()). Reactive, so a live count repaints on its own signal. An empty string draws nothing, which is the natural “zero” case.

Ignored (in release) when no static item precedes it; data-driven rows carry their own badge via NavItem::badge.

pub fn header<P>(self, build: impl FnOnce() -> P + 'static) -> Selector<S, K>

where P: Piece,

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

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

where P: Piece,

Add a destination. key addresses it (navigate / deep link / dayscript); title is its label; build runs when the item is first shown. For a typed selector over Option<Section> pass the bare Section::X.

pub fn item_icon<M, P>( self, key: impl Into<K>, title: impl IntoText<M>, icon: impl Into<ImageName>, build: impl Fn() -> P + 'static, ) -> Selector<S, K>

where P: Piece,

Like item but with a native icon: icon is a bundled-image name (typed ImageName, resolved like image, e.g. res::images::nav_home) shown beside the label where the backend’s nav supports it (e.g. the Windows NavigationView, the iOS/macOS source list). Backends that can’t decorate rows ignore it.

pub fn immersive(self) -> Selector<S, K>

Mark the LAST-added .item/.item_icon destination as an immersive-chrome page (docs/navigation.md): on backends with an immersive nav mode (android edge-to-edge today) its pushed page keeps the floating transparent bar over full-bleed content; unmarked pages get the standard opaque bar. A no-op on every other backend. For a data-driven .items block, mark individual rows with NavItem::immersive instead.

pub fn items<T>( self, items: impl Fn() -> Vec<T> + 'static, map: impl Fn(&T) -> NavItem<K> + 'static, ) -> Selector<S, K>

where T: Clone + 'static,

A data-driven item block: .items(rooms_signal, |r| item(r.id, r.name).icon(…)) (docs/navigation.md). The block re-derives whenever the signal changes — rows are added and removed on the native sidebar/tab widget, and if the selected key disappears the selection resets (to None for an Option key). Static .items and dynamic blocks may be mixed; the final list is their declaration order. Pair with destination to build the page for a data-driven key.

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

where P: Piece,

Build the page for a data-driven key (one added by items with no static item). Mirrors Stack::destination; unused for a purely static selector.

pub fn local(self) -> Selector<S, K>

Use this selector 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 selector nested one level deeper (a Tabs inside a Sidebar section) is a different case and should stay routed: that cascade is the point. 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>) -> Selector<S, K>

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. Restore is a no-op until the app installs a store (e.g. day_part_prefs::install_nav_store); a stale saved key (its item no longer exists) is ignored. Works whether or not the selector is routed.

pub fn bar_action<M>( self, icon: impl Into<ImageName>, label: impl IntoText<M>, action: impl Fn() + 'static, ) -> Selector<S, K>

Add a trailing action button to the navigation bar, for the toolkits that have no window toolbar (the phones and HarmonyOS — Cap::Toolbar is Unsupported): an upper-right bar button drawn with the bundled icon that runs action when tapped (docs/navigation.md). icon is a bundled-image name (typed ImageName, like item_icon’s); label is the button’s accessible name and tooltip.

Desktop split presentations ignore it — they have a real toolbar, so put the same command there (docs/toolbars.md). The action is app-wide: it rides the current top page’s bar, so the same handler serves every section (read current_route inside it to act on whatever is showing).

Trait Implementations

impl<K, S> Piece for Selector<S, K>

where K: Route, S: SignalRw<K>,

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