Struct Decorated 

pub struct Decorated<P> { /* private fields */ }

A piece with modifiers chained onto it, keeping the decorated piece’s type (§5.2).

Every Decorate modifier returns one of these rather than erasing to AnyPiece, which is what lets a chain keep reaching the piece’s builder methods: label(…).padding(8.0) is still a decorated Label, so .font(…) after it resolves. Modifiers applied to a Decorated append in place (the inherent methods below shadow the trait’s), so a chain stays flat instead of nesting Decorated<Decorated<…>>.

Modifiers fall into three classes (docs/api-style.md “Modifier classes”), and only one of them is ordered:

• Identity (id, id_of) names the piece’s own node, the one its build returns, wherever it sits in the chain: label(t).padding(8.0).id(day_core::id!(x)) and label(t).id(day_core::id!(x)).padding(8.0) are the same tree.
• Wrapping modifiers (padding, frame, background, grow, …) each add a node around what came before, so they compose outward in call order, as they read.
• Outer-layout facts (grid_span, grid_align) describe the piece to the container it sits in, so they land on the outermost node whatever wrappers follow them.

wrapper_id is the one way to name a wrapper deliberately: it tags whatever node is outermost at the point it is called, for a frame assertion on a padded box.

Erase explicitly with .any() when a single AnyPiece is what’s needed (a Vec<AnyPiece>, a -> AnyPiece signature).

Implementations

impl<P: Piece> Decorated<P>

pub fn new(inner: P) -> Self

An undecorated piece, ready to have modifiers applied CONDITIONALLY. Starting here gives every branch the same type, so an optional modifier needs no erasure:

let leaf = Decorated::new(draw);
let leaf = match id { Some(id) => leaf.id(id), None => leaf };
let leaf = if editable { leaf.on_tap(f) } else { leaf };

apply_if and apply_some are the same move as a chain step.

pub fn map_inner<Q: Piece>(self, f: impl FnOnce(P) -> Q) -> Decorated<Q>

Replace the undecorated piece, keeping the modifier chain: how a typed builder trait reaches through a decoration (docs/api-style.md “Typed builders”). f sees the piece as it was before any modifier, which is why modifier order stops mattering.

pub fn apply_if(self, cond: bool, f: impl FnOnce(Self) -> Self) -> Self

Apply f to the chain when cond holds, else continue unchanged: the conditional modifier, with no let x = if c { x.m() } else { x } rebinding and no erasure.

nav(sel).apply_if(!primary, |n| n.local())

cond is a plain bool resolved at build, like the arms of a match; the modifiers f applies may themselves be reactive.

pub fn apply_some<T>( self, value: Option<T>, f: impl FnOnce(Self, T) -> Self, ) -> Self

Apply f with the value when there is one, else continue unchanged: canvas(draw).apply_some(id, |c, id| c.id(id)).

impl<P: Piece> Decorated<P>

pub fn id(self, id: ElementId) -> Self

pub fn id_of(self, id: impl Fn() -> ElementId + 'static) -> Self

pub fn wrapper_id(self, id: ElementId) -> Self

pub fn tweak(self, f: impl FnOnce(RNode) + 'static) -> Self

pub fn selectable(self) -> Self

pub fn cursor<M>(self, cursor: impl IntoReactive<Cursor, M>) -> Self

pub fn native_ref(self, r: &NativeRef) -> Self

pub fn window_drag_region(self) -> Self

pub fn padding(self, insets: impl IntoInsets) -> Self

pub fn max_width(self, max: f64) -> Self

pub fn min_width(self, min: f64) -> Self

Never narrower than min: a stretching control keeps a usable width, and a row that cannot give it that overflows, so a labeled row stacks the control under its label rather than squeezing it (docs/forms.md).

pub fn reserving(self, sample: impl Into<String>) -> Self

pub fn frame(self, width: f64, height: f64) -> Self

pub fn width(self, width: f64) -> Self

pub fn height(self, height: f64) -> Self

pub fn a11y(self, f: impl FnOnce(A11yBuilder) -> A11yBuilder + 'static) -> Self

pub fn on_tap(self, f: impl Fn() + 'static) -> Self

Handle a tap gesture on this piece.

Do not use this to activate a native button; use crate::ButtonBuilder::action. A separate gesture recognizer can delay pressed feedback and bypass native keyboard, accessibility, and disabled behavior. Day warns when it attaches a tap to a button.

pub fn on_tap_at(self, f: impl Fn(Point) + 'static) -> Self

Handle a tap with its local position. Like Self::on_tap, this is a gesture, not native button activation; use crate::ButtonBuilder::action for buttons.

pub fn focused<M>(self, binding: impl IntoFocusBinding<M>) -> Self

pub fn on_key(self, f: impl Fn(&KeyEvent) + 'static) -> Self

pub fn focusable(self) -> Self

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

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

See Decorate::searchable.

pub fn drag_source( self, source: impl Fn(Point) -> Option<Offer> + 'static, ) -> Self

Offer data through the platform’s native drag session.

pub fn drop_target(self, target: Target) -> Self

Attach native drop acceptance policy and an owned-data receiver.

pub fn context_menu<M>(self, menu: impl ContextMenuContent<M>) -> Self

pub fn on_drag(self, f: impl Fn(Drag) + 'static) -> Self

pub fn on_pinch(self, f: impl Fn(Pinch) + 'static) -> Self

pub fn on_pan(self, f: impl Fn(Pan) + 'static) -> Self

pub fn on_hover(self, f: impl Fn(Option<Point>) + 'static) -> Self

The pointer moving over this piece: Some(point) in its own coordinates while inside, None when it leaves (docs/canvas.md “Interaction”).

Pointer-only, which is not a gap: every desktop delivers it, an iPad does with a trackpad or pencil, an Android device with a mouse or stylus, and a touch-only phone delivers nothing at all. Anything reachable by hover must also be reachable by a tap: wire on_tap_at alongside it, exactly as a chart’s selection does.

pub fn card(self) -> Self

The platform’s card: the grouped-content surface (SurfaceRole::SectionCard) with rounded corners and a Space::M inset. Drawn by the toolkit, so it follows the appearance and never steals hit testing from the content.

pub fn background<M>(self, color: impl IntoReactive<Color, M>) -> Self

pub fn corner_radius(self, radius: f64) -> Self

pub fn opacity<M>(self, opacity: impl IntoReactive<f64, M>) -> Self

pub fn transform<M>(self, t: impl IntoReactive<Transform, M>) -> Self

pub fn scale<M>(self, factor: impl IntoReactive<f64, M>) -> Self

pub fn rotation<M>(self, degrees: impl IntoReactive<f64, M>) -> Self

pub fn translation<Mx, My>( self, x: impl IntoReactive<f64, Mx>, y: impl IntoReactive<f64, My>, ) -> Self

pub fn animation(self, anim: AnimSpec) -> Self

pub fn modifier(self, m: impl Modifier) -> AnyPiece

Erases, like Decorate::modifier: Modifier is defined over AnyPiece.

pub fn overlay(self, over: impl Piece) -> Self

pub fn overlay_aligned(self, align: Alignment, over: impl Piece) -> Self

pub fn aspect_ratio(self, ratio: f64) -> Self

pub fn grow(self) -> Self

pub fn grow_w(self) -> Self

pub fn grow_h(self) -> Self

pub fn grid_span(self, n: usize) -> Self

pub fn grid_align(self, a: Alignment) -> Self

pub fn defers_system_gestures(self, edges: Edges) -> Self

pub fn interactive_dismiss_disabled(self) -> Self

pub fn status_bar_hidden<M>(self, hidden: impl IntoReactive<bool, M>) -> Self

pub fn any(self) -> AnyPiece

Erase to a single AnyPiece.

Trait Implementations

impl<DecoratedInner: AdaptiveBuilder + Piece> AdaptiveBuilder for Decorated<DecoratedInner>

fn spacing(self, s: impl Into<f64>) -> Self

The gap between children, in either arrangement: a Space step or points.

fn stack_at(self, at: WidthClass) -> Self

The widest WidthClass at which the children stack.

fn align(self, a: VAlign) -> Self

The cross-axis alignment while the children sit in a row (default centered, as a row); stacked, they always align leading.

impl<DecoratedInner: ButtonBuilder + Piece> ButtonBuilder for Decorated<DecoratedInner>

fn icon<M>(self, symbol: impl IntoReactive<Symbol, M>) -> Self

Show a platform symbol. A signal or closure updates it without replacing the button.

fn image(self, name: impl Into<ImageName>) -> Self

Show a bundled image or vector alongside the label.

fn icon_only(self) -> Self

Hide the visible label when an icon is available; retain it for accessibility and help.

fn action(self, f: impl Fn() + 'static) -> Self

Handle native button activation by pointer, keyboard, or accessibility action. Disabled buttons do not invoke this callback.

fn bordered(self) -> Self

Ask for a visually CONTAINED native button on toolkits whose stock look is borderless (iOS’s plain system button reads as a link); a no-op where buttons are already bordered.

fn enabled<M>(self, v: impl IntoReactive<bool, M>) -> Self

Whether the button is interactive (default true; false = disabled/grayed by the native control). Reactive, so it can follow app state, e.g. .enabled(move || !busy.get()) to lock a control while a long operation runs.

fn prominent(self) -> Self

The platform’s accent-filled / default-action button (iOS bordered-prominent, macOS return-key blue, GTK suggested-action, XAML accent style). Use for the one primary action of a view.

fn tint<M>(self, color: impl IntoReactive<Color, M>) -> Self

A filled button in a color of your choosing, still drawn by the native control.

fn compact(self) -> Self

A button no wider than its title: a stepper’s “−” and “+”, a chip’s “×”. Drops the minimum width and wide insets of toolkits that have them (Material); a no-op where the stock button already hugs its title.

fn plain(self) -> Self

Borderless native action button for toolbars and list-row accessories. Preserves native interaction, focus, disabled rendering, and accessibility.

fn selected<M>(self, v: impl IntoReactive<bool, M>) -> Self

Mark this button as the current choice among its peers: a document tab, one view of a switcher. The platform draws its own checked or selected look (an NSButton’s on state, UIButton.isSelected, GTK’s :checked, a checked QPushButton, a checked MaterialButton, aria-pressed on the web) and announces it as selected, while the button stays enabled, focusable and activatable, which a disabled stand-in is not.

impl<DecoratedInner: ColumnBuilder + Piece> ColumnBuilder for Decorated<DecoratedInner>

fn spacing(self, s: impl Into<f64>) -> Self

The gap between children: a Space step or points.

fn align(self, a: HAlign) -> Self

impl<R: Route, DecoratedInner: CoverBuilder<R> + Piece> CoverBuilder<R> for Decorated<DecoratedInner>

fn sheet(self) -> Self

Prefer a native modal sheet. Backends without sheets retain their modal cover.

fn half_sheet(self) -> Self

Present as a half-height sheet rising from the bottom edge, the window content above it staying on show: an inspector over the canvas it describes, a transport over the media it controls (docs/cover.md “Half sheet”). iOS presents a medium-detent sheet that leaves the content interactive, Android a Material bottom sheet, the web, HarmonyOS and the emulated desktop tiers a bottom-anchored half panel, and macOS its window sheet at half the window’s height. Implies Cover::sheet.

fn background(self, f: impl Fn(&R) -> Color + 'static) -> Self

The surface color painted edge-to-edge behind the content (under the status bar and home indicator) while r is presented. Without it the platform’s default surface color shows in the unsafe areas.

fn unrouted(self) -> Self

Keep this cover out of the app’s route space: navigate("<key>") never presents it, it contributes nothing to current_route(), and nav_back() walks past it.

impl<DecoratedInner: DividerBuilder + Piece> DividerBuilder for Decorated<DecoratedInner>

fn vertical(self) -> Self

Turn the rule on its side: a thin vertical line that fills the row’s height, the way the horizontal one fills a column’s width. Between a row’s panes, where a horizontal rule would draw a stray line across one of them.

impl<DecoratedInner: FormSectionBuilder + Piece> FormSectionBuilder for Decorated<DecoratedInner>

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

The section header, shown above the card in the footnote style.

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

The section footer, shown under the card in the footnote style: the explanatory line settings screens put beneath a group of rows (iOS section footers, libadwaita’s group description).

impl<DecoratedInner: GridBuilder + Piece> GridBuilder for Decorated<DecoratedInner>

fn spacing(self, s: impl Into<f64>) -> Self

Set both the row and column gutters: a Space step or points.

fn row_spacing(self, s: impl Into<f64>) -> Self

fn column_spacing(self, s: impl Into<f64>) -> Self

fn align(self, a: Alignment) -> Self

Default alignment of every cell within its cell rect (cell/row overrides win).

impl<DecoratedInner: GridRowBuilder + Piece> GridRowBuilder for Decorated<DecoratedInner>

fn align(self, a: VAlign) -> Self

Vertical alignment override for this row’s cells (the grid’s alignment applies otherwise).

impl<DecoratedInner: ImageBuilder + Piece> ImageBuilder for Decorated<DecoratedInner>

fn content_mode(self, m: ContentMode) -> Self

How the image scales within its frame (default ContentMode::Fit).

fn fit(self) -> Self

Scale to fit entirely inside the frame, preserving aspect ratio (the default).

fn fill(self) -> Self

Scale to fill the frame, preserving aspect ratio and cropping the overflow.

fn stretch(self) -> Self

Stretch to fill the frame exactly, ignoring aspect ratio.

fn aspect_ratio(self, ratio: f64) -> Self

Constrain the view to a width / height ratio (e.g. 16.0 / 9.0).

fn decorative(self) -> Self

Mark the image decorative (hidden from accessibility).

fn template(self) -> Self

Draw a monochrome glyph as a template (docs/vectors.md “Template”): in the foreground of the surface it sits on, following the theme, rather than in its authored colors. What a row icon in a sidebar wants; a photo does not.

impl<DecoratedInner: InspectorBuilder + Piece> InspectorBuilder for Decorated<DecoratedInner>

fn width(self, width: f64) -> Self

The panel’s preferred width in points (default INSPECTOR_WIDTH). Where the native pane has a user-draggable divider this is the initial width, not a limit.

fn not_scrollable(self) -> Self

Do not wrap the panel in a scroll view (it is wrapped by default): for a panel that owns a recycling list or its own scroller, so it receives a bounded viewport.

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

The label of the compact sheet’s dismiss button (default ✕). Pass a localized “Done”; the sheet is the one home where the panel needs its own way out.

fn edge(self, edge: PaneEdge) -> Self

Put the pane on the leading side of the content, for a layer panel rather than a properties inspector (docs/tree.md). Default PaneEdge::Trailing.

fn half_sheet(self) -> Self

On a compact window, present the panel as a half-height sheet rising from the bottom edge rather than a fullscreen one, so the content it describes stays on show (and, on iOS, interactive) while it is open: Cover::half_sheet. Default: the fullscreen sheet.

impl<DecoratedInner: LabelBuilder + Piece> LabelBuilder for Decorated<DecoratedInner>

fn single_line(self) -> Self

Keep plain text on one line. UIKit, Android, GTK, AppKit and DOM truncate with an ellipsis.

fn max_lines(self, lines: u32) -> Self

Limit a plain label to this many lines, truncating the last line on native Apple backends. Zero means unlimited. Rebuild the label to change its line limit.

fn font(self, f: Font) -> Self

The semantic text style (Font::Title, Font::Footnote, …) or a custom Font::System(pt). Backends render it with the platform’s native style + accessibility text scaling.

fn font_scale(self, scale: f64) -> Self

Scale the resolved native font, preserving its semantic style and accessibility size. Applies to the label’s base font; explicit styled runs retain their own descriptors.

fn weight(self, w: FontWeight) -> Self

Override the font weight (e.g. FontWeight::Semibold). See also Label::bold.

fn bold(self) -> Self

Shorthand for .weight(FontWeight::Bold).

fn secondary(self) -> Self

De-emphasize the text: the platform’s secondary label color, whatever that is here (secondaryLabelColor on Apple, ?android:textColorSecondary, a dim label on GTK).

fn italic(self) -> Self

Render the text italic (slanted).

fn tabular(self) -> Self

Ask for tabular (monospaced) figures, so a changing number stops changing width.

fn monospace(self) -> Self

Ask for the platform’s monospaced face at this style’s size, which is what inline code wants.

fn runs(self, runs: Vec<TextRun>) -> Self

Style spans within this label’s text (docs/text-runs.md): one wrapping paragraph with emphasis, color, code or a link inside it, rather than several labels in a row.

fn runs_from(self, b: TextBuilder) -> Self

Take both the text and its runs from a TextBuilder, replacing whatever text the label was built with. This is the intended entry point: the builder guarantees the ranges match the string, which is the invariant hand-written runs get wrong.

fn align(self, align: TextAlign) -> Self

Read the label’s text as inline Markdown (docs/markdown.md): **bold**, *italic*, `code`, ~~strike~~ and [text](url) become styled runs, and the markers themselves are stripped.

fn markdown(self) -> Self

fn on_link(self, f: impl Fn(&str) + 'static) -> Self

Handle a tapped link run yourself instead of opening its target.

fn color<M>(self, c: impl IntoReactive<Color, M>) -> Self

The text color: a constant, a Signal<Color>, or a Fn() -> Color. A reactive source recolors the native label when it changes (theme systems ride this).

fn preset(self, preset: &TextPreset) -> Self

Apply a named TextPreset: the font, weight, scale, emphasis and color an app defined once (label(t).preset(&CAPTION)).

impl<DecoratedInner: LinkBuilder + Piece> LinkBuilder for Decorated<DecoratedInner>

fn font(self, f: Font) -> Self

The text style (default Font::Body).

fn color(self, c: Color) -> Self

Override the link color (default the platform tint blue).

fn bold(self) -> Self

Render the link text bold.

impl<S: RowSource + 'static, DecoratedInner: ListBuilder<S> + Piece> ListBuilder<S> for Decorated<DecoratedInner>

fn row_height(self, h: RowHeight) -> Self

Row sizing: Uniform(h) (fastest) or Automatic (self-sizing).

fn on_activate(self, f: impl Fn(S::Ref) + 'static) -> Self

Open, play, or otherwise activate a row. Desktop lists use double-click or Enter; touch lists use a tap. Selection callbacks remain independent.

fn on_select(self, f: impl Fn(S::Ref) + 'static) -> Self

Called with the selected row when the native list reports a selection: the key for a plain-data source, the row’s Elem handle for a store source.

fn multi_select(self) -> Self

Allow selecting several rows at once, where the toolkit supports it (docs/list.md has the matrix; single-selection backends fall back to one row at a time). Every selection change calls Self::on_selection with the full set of selected rows.

fn on_selection(self, f: impl Fn(Vec<S::Ref>) + 'static) -> Self

Called with the full set of selected rows (row order, empty = cleared) whenever the selection changes: the multi-select analogue of Self::on_select. Also fired by single-selection backends with a one-element (or empty) set.

fn selected_rows(self, rows: impl Fn() -> Vec<usize> + 'static) -> Self

Reactively sync the native selection to rows (row indices; empty clears). Re-runs whenever the closure’s tracked reads change; the toolkit applies the sync without re-emitting a selection event. Drive it from app state to build “Clear selection”.

fn selection(self, selected: impl Binding<Option<u64>>) -> Self

where S::Ref: SelectionKey,

Two-way single selection by key, for a list of day-model store rows: selected holds the selected row’s key (None for no selection). A row the user picks writes its key, clearing the selection writes None, and a key the app writes selects that row and scrolls it into view, following the row through inserts and moves.

fn scroll_to_end(self, trigger: Trigger) -> Self

Scroll the list so its last row is fully visible whenever trigger fires, e.g. a chat timeline sticking to the newest message. Fire it with day_reactive::Trigger::notify after appending. No-op while the list is empty. The scroll targets the native list (NSTableView/UITableView/GtkListView/QListView/RecyclerView), so it respects the platform’s own scroll physics.

fn stick_to_bottom(self) -> Self

Best-effort auto-stick: after a data reload, scroll to the end so freshly appended rows stay visible. Convenience over Self::scroll_to_end for feeds that always follow the newest row; for finer control (only stick when the user is already near the bottom) drive scroll_to_end from your own logic instead. Off by default.

fn scroll_to_row(self, target: impl Binding<Option<usize>>) -> Self

Programmatic scroll-to-row (docs/list.md): set the signal to Some(row) and the native list scrolls that row into view, realizing it if it was virtualized away: the row rail’s counterpart to scroll(...).scroll_target(...). The signal is left as written; setting the same row again re-fires. Takes a Signal<Option<usize>> or any other binding.

fn first_visible_row(self, first: impl Binding<usize>) -> Self

The first actually visible article/item index, reported by native scrolling into first (a Signal<usize> or any other binding). Use with a heading overlay for floating group headers. No periodic timer is used.

fn reorderable(self, reorder: Reorder) -> Self

Let the user drag rows into a new order (docs/list.md): the list is reorderable exactly when it carries a Reorder, whose handler applies the move to the app’s data.

fn deletable(self, delete: Delete) -> Self

Let the user delete rows with the platform’s delete gesture (docs/list.md): the list is deletable exactly when it carries a Delete, whose handler applies the removal to the app’s data.

fn swipe_leading( self, provider: impl Fn(usize) -> Vec<SwipeAction> + 'static, ) -> Self

Offer swipe actions on the row’s leading edge, the reading-direction start, where the platform reveals them as the user drags the row aside (probe Cap::ListSwipeActions; docs/list.md has the matrix; a backend without the affordance shows nothing, so pair each action with an explicit control for the rest). provider runs at gesture time with the row index, so the offer can reflect the row’s current state (“Mark as Read” vs “Mark as Unread”). Keep it pure and fast; it runs inside the platform’s swipe callback; the actions’ handlers run later, at the event drain. A full swipe across activates the edge’s first action.

fn swipe_trailing( self, provider: impl Fn(usize) -> Vec<SwipeAction> + 'static, ) -> Self

Offer swipe actions on the row’s trailing edge, the reading-direction end. Same contract as swipe_leading.

fn separators(self) -> Self

Draw a separator under each row. It is the host’s separator, drawn at the row boundary and never by row content (docs/list.md): it aligns with the native selection and stays put while a macOS/iOS swipe slides the row past it, exactly as Mail’s separators do. Unset, each platform keeps its default (iOS draws them, the desktops don’t); see Self::no_separators for the other override. A backend without a separator mechanism ignores this (the docs matrix says which); don’t re-create the old hand-drawn hairline there. Rows separate by their pitch.

fn no_separators(self) -> Self

Draw no separator between rows, on a platform whose default draws one (iOS).

fn editing<M>(self, on: impl IntoReactive<bool, M>) -> Self

Put the list in the platform’s editing mode (docs/list.md): on iOS, the rows show their delete controls (where a Delete offers one) and reorder grips (where a Reorder moves them), and a tap still activates the row. Reactive, so an Edit/Done button can toggle it, and the change animates.

impl<DecoratedInner: ListItemBuilder + Piece> ListItemBuilder for Decorated<DecoratedInner>

fn subtitle<M>(self, text: impl IntoText<M>) -> Self

A second line under the title, in the platform’s secondary style.

fn detail<M>(self, text: impl IntoText<M>) -> Self

Trailing text, such as a count or a value, in the platform’s secondary style.

fn icon<M>(self, name: impl IntoReactive<VectorName, M>) -> Self

The leading glyph: an app vector (res::vectors::…), drawn as a template in the foreground color unless Self::icon_tint names one. A signal or closure swaps it in place.

fn symbol(self, symbol: Symbol) -> Self

The leading glyph as a standard symbol.

fn icon_tint<M>(self, color: impl IntoReactive<Color, M>) -> Self

The leading glyph’s color.

fn checked<M>(self, on: impl IntoReactive<bool, M>) -> Self

A trailing check mark while on holds: the platform’s mark for a chosen or completed row, announced as selected.

impl<K: Route, DecoratedInner: NavBuilder<K> + Piece> NavBuilder<K> for Decorated<DecoratedInner>

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, DecoratedInner: NavStackBuilder<K> + Piece> NavStackBuilder<K> for Decorated<DecoratedInner>

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

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

Declare toolbar items on this stack’s root page chrome (docs/toolbars.md): the commands that act on what the root shows, and that have nothing to act on once a pushed page covers it. A pushed page declares its own with the same method on the piece it builds.

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

Build the view for a pushed key (&String for raw keys, the typed value otherwise).

fn on_back(self, guard: impl Fn(BackRequest) -> BackResponse + 'static) -> Self

Intercept the back affordance (docs/navigation.md). The guard runs for every native back gesture/button and nav_back while the stack is above its root; it returns BackResponse::Proceed to pop now or BackResponse::Handled to consume the back (stash the BackRequest and call BackRequest::proceed later). Programmatic path writes are never guarded. While a guard is armed the toolkit stops auto-popping on a native gesture and routes the back through Day instead (NavPatch::GuardTop).

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

Remember the pushed path across launches (docs/navigation.md). On every change the path’s keys are /-joined and saved under key; at build the saved path is parsed back (each segment via Route::from_key) and restored, so the app reopens exactly where the user left off, including after an Android process death, unless a launch deep link is pending, which wins. day::launch installs the preferences as the store (docs/navigation.md); a saved path with a segment that no longer parses is ignored whole.

impl<DecoratedInner: PickerBuilder + Piece> PickerBuilder for Decorated<DecoratedInner>

fn enabled<M>(self, v: impl IntoReactive<bool, M>) -> Self

Whether the picker takes input (default true); a constant or a reactive bool.

fn separators_before(self, indexes: impl IntoIterator<Item = usize>) -> Self

Insert native menu separators before these option indexes. Indexes still refer to options, so separators never change the selection binding. AppKit/UIKit menu style honors this; other backends and styles display the same options without grouping.

fn menu(self) -> Self

fn segmented(self) -> Self

fn inline(self) -> Self

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

impl<P: Piece> Piece for Decorated<P>

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

impl<DecoratedInner: RowBuilder + Piece> RowBuilder for Decorated<DecoratedInner>

fn spacing(self, s: impl Into<f64>) -> Self

The gap between children: a Space step or points.

fn align(self, a: VAlign) -> Self

fn fit(self, fit: RowFit) -> Self

What happens when the children outgrow the row’s width (docs/size-classes.md).

impl<DecoratedInner: ScrollBuilder + Piece> ScrollBuilder for Decorated<DecoratedInner>

fn horizontal(self) -> Self

Scroll horizontally instead of vertically (a filmstrip of cards, a chip row). The content is measured unconstrained on the horizontal axis and the native view scrolls sideways.

fn axis(self, axis: Axis) -> Self

Set the scroll axis explicitly.

fn scroll_target(self, target: impl Binding<Option<ScrollTarget>>) -> Self

Programmatic scrolling (docs/scroll.md): each Some(target) written to sig scrolls there (animated), then the signal resets to None. Write-and-forget, so the same target can be sent twice in a row.

impl<DecoratedInner: ShapePieceBuilder + Piece> ShapePieceBuilder for Decorated<DecoratedInner>

fn fill<M>(self, p: impl IntoReactive<Color, M>) -> Self

fn fill_linear<M>(self, g: impl IntoReactive<LinearGradient, M>) -> Self

Fill with a LinearGradient (unit points resolve against the shape’s bounds). Takes precedence over Self::fill when both are set; reactive like every other property: rectangle().fill_linear(move || sky_gradient(state.get())).

fn fill_radial<M>(self, g: impl IntoReactive<RadialGradient, M>) -> Self

Fill with a RadialGradient (center + radius in the unit space of the shape’s bounds, stretching elliptically in non-square bounds). Precedence: radial over linear over solid.

fn stroke<M1, M2>( self, color: impl IntoReactive<Color, M1>, width: impl IntoReactive<f64, M2>, ) -> Self

fn inset<M>(self, v: impl IntoReactive<f64, M>) -> Self

Uniform inset applied before resolving geometry (keeps strokes inside the frame).

fn rotate<M>(self, deg: impl IntoReactive<f64, M>) -> Self

Rotate the drawn shape about its center, in degrees.

fn scale<M>(self, s: impl IntoReactive<f64, M>) -> Self

Scale the drawn shape about its center (uniform).

fn offset<M1, M2>( self, x: impl IntoReactive<f64, M1>, y: impl IntoReactive<f64, M2>, ) -> Self

Translate the drawn shape within its frame.

fn at(self, fx: f64, fy: f64, fw: f64, fh: f64) -> Self

Resolve this shape inside the fractional sub-rect (fx, fy, fw, fh) of its bounds (unit-space, applied before Self::inset). The workhorse for composing glyphs in a shape_group, mirroring hand-drawn Rect::new(ox + fx * s, oy + fy * s, …) canvas code.

fn on_tap(self, f: impl Fn() + 'static) -> Self

Fire when the shape is tapped (path-precise: the tap is tested against the resolved path).

fn on_drag(self, f: impl Fn(Drag) + 'static) -> Self

Fire on each phase of a drag over the shape.

impl<DecoratedInner: SliderBuilder + Piece> SliderBuilder for Decorated<DecoratedInner>

fn enabled<M>(self, v: impl IntoReactive<bool, M>) -> Self

Whether the slider takes input (default true); a constant or a reactive bool.

fn range(self, r: RangeInclusive<f64>) -> Self

fn step(self, s: f64) -> Self

impl<DecoratedInner: SplitBuilder + Piece> SplitBuilder for Decorated<DecoratedInner>

fn axis<M>(self, axis: impl IntoReactive<SplitAxis, M>) -> Self

Side by side (SplitAxis::Horizontal, the default) or stacked; a signal or a closure turns the split live, keeping the share.

fn fraction(self, fraction: impl Binding<f64>) -> Self

The first pane’s share of the length, 0.0..=1.0, two-way: a dragged divider writes it, writing it moves the divider. Unbound, the split keeps a share of its own from 0.5.

fn min_pane(self, points: f64) -> Self

The least length either pane may be dragged to (default SPLIT_MIN_PANE).

impl<DecoratedInner: TextAreaBuilder + Piece> TextAreaBuilder for Decorated<DecoratedInner>

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

The empty-state prompt shown when the editor is empty (a constant, Signal<String>, or closure, evaluated once for the initial value; not reactive after build).

fn min_lines(self, lines: u32) -> Self

The minimum height, in text lines (default 1): the editor never shrinks below this.

fn max_lines(self, lines: u32) -> Self

The maximum height, in text lines, before the editor scrolls internally. 0 (the default) means unbounded: the editor keeps growing and never scrolls.

fn editable<M>(self, v: impl IntoReactive<bool, M>) -> Self

Whether the user can edit the text (default true; false = read-only). Reactive.

fn selectable<M>(self, v: impl IntoReactive<bool, M>) -> Self

Whether the text can be selected and copied (default true). Reactive. Unsupported on backends where selection is always on (GTK).

fn spellcheck<M>(self, v: impl IntoReactive<bool, M>) -> Self

Whether spell-check / autocorrect highlighting is on (default true). Reactive. Unsupported on backends with no built-in spell-check (GTK, Qt).

fn on_submit(self, f: impl Fn() + 'static) -> Self

Submit on Enter: a plain Enter runs f instead of inserting a newline, the chat-composer contract. Shift+Enter still inserts a line break on desktop and ArkUI; Android and ArkUI show a Send action on the soft keyboard; iOS’s return key submits. Backends without the intercept (web-dom today) keep inserting newlines, so pair this with a visible send button. The bound text signal is already up to date when f runs.

impl<DecoratedInner: TextFieldBuilder + Piece> TextFieldBuilder for Decorated<DecoratedInner>

fn enabled<M>(self, v: impl IntoReactive<bool, M>) -> Self

Whether the field takes input (default true); a constant or a reactive bool. A disabled field neither edits nor focuses; TextField::read_only keeps it selectable.

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

fn on_submit(self, f: impl Fn() + 'static) -> Self

Fire when the user submits the field (Return / the keyboard’s action key). Field chaining is a focus write inside the handler: focus.set(Some(Field::Next)) (docs/focus.md).

fn secure<M>(self, v: impl IntoReactive<bool, M>) -> Self

Hide the characters as they are typed (default false). Reactive: bind it to a signal for a show-password switch. The text, the placeholder and the focus carry across the change on every backend, including the two whose secure field is a different native class.

fn read_only<M>(self, v: impl IntoReactive<bool, M>) -> Self

Show the text and let it be selected and copied, and take no edits (default false). Reactive. Unlike .disabled(true) the field keeps its ordinary look and still takes focus.

fn input_purpose(self, purpose: InputPurpose) -> Self

What the field collects: the on-screen keyboard, capitalization and correction, and what the system offers to fill in all follow from it.

fn submit_label(self, label: SubmitLabel) -> Self

What the on-screen keyboard’s action key says. The key fires on_submit either way.

fn max_length(self, characters: u32) -> Self

The most characters the field takes. Typing or pasting past it is cut to fit before the bound value sees it.

impl<DecoratedInner: ToggleBuilder + Piece> ToggleBuilder for Decorated<DecoratedInner>

fn enabled<M>(self, v: impl IntoReactive<bool, M>) -> Self

Whether the toggle is interactive (default true; false = disabled/grayed). Reactive, e.g. .enabled(capability(Cap::TextSpellCheck) == Support::Native) to gray it out where a backend can’t honor the thing it controls.

impl<S: NodeSource + 'static, DecoratedInner: TreeBuilder<S> + Piece> TreeBuilder<S> for Decorated<DecoratedInner>

fn row_height(self, h: RowHeight) -> Self

Row sizing: Uniform(h) (fastest) or Automatic (self-sizing).

fn indent(self, pts: f64) -> Self

Indentation per depth level, in points (unset = the platform’s default step).

fn section_headers(self) -> Self

Render a two-level source as sections. Root branches are headings and cannot be selected; root leaves remain ordinary rows. Children must be leaves. This enables native ExpandableListView on Android, where arbitrary-depth trees are composed.

fn on_expansion(self, f: impl Fn(S::Key, bool) + 'static) -> Self

Reports an actual user/scripting disclosure change with the stable application key. Programmatic writes to expanded do not echo this callback.

fn expanded(self, set: impl Binding<HashSet<S::Key>>) -> Self

The app-owned expansion set (docs/tree.md): the user’s disclosure clicks update it, and the app writing it discloses/collapses the native rows. Persist it (or don’t); it is plain state.

fn expandable(self, f: impl Fn(&S::Key) -> bool + 'static) -> Self

Which rows can hold children at all: what draws (or omits) the disclosure, and which rows a drop may land on. Defaults to “has children right now”, which draws no disclosure on an empty group; a source with real branch/leaf kinds should say so.

fn selected(self, f: impl Fn() -> Vec<S::Key> + 'static) -> Self

Reactively sync the native selection to these keys (empty clears). Point it and Self::on_selection at one signal and selection is two-way, shared with anything else reading the same state.

fn on_selection(self, f: impl Fn(Vec<S::Key>) + 'static) -> Self

Called with the full selected key set (empty = cleared) whenever the user changes the selection.

fn multi_select(self) -> Self

Allow selecting several rows at once, where the toolkit supports it.

fn movable(self, mv: Move<S::Key>) -> Self

Let the user drag rows to a new parent/position with the platform’s native mechanism, where the backend supports it (probe Cap::TreeMove): the tree is movable exactly when it carries a Move, whose handler re-parents the app’s data.

fn type_ahead(self, f: impl Fn(&S::Key) -> String + 'static) -> Self

The row’s type-ahead string (docs/tree.md): what native type-select matches against. Unset rows don’t participate.

fn reveal(self, target: impl Binding<Option<S::Key>>) -> Self

Programmatic reveal: set the signal to Some(key) and the row scrolls into view with every ancestor expanded (through Self::expanded, so the app sees the change).

fn row_id(self, f: impl Fn(&S::Key) -> ElementId + 'static) -> Self

A dayscript element id per row, from its key (docs/tree.md): re-applied on every recycle, so tap/assert_text address the row wherever its cell currently sits. It is also what the expand:/tree_move: steps resolve rows by.

fn row_context_menu( self, f: impl Fn(&S::Key) -> Vec<MenuEntry> + 'static, ) -> Self

A per-row context menu, built when the menu is summoned (docs/menus.md “Dynamic context menus”): right-click on desktop, long-press on touch. The closure receives the row’s key and returns the menu to show; it may adjust the app’s selection first (the convention: a summon outside the current selection selects that row). An empty result shows nothing for that row.

impl<DecoratedInner: VectorBuilder + Piece> VectorBuilder for Decorated<DecoratedInner>

fn tint<M>(self, color: impl IntoReactive<Color, M>) -> Self

Recolor the glyph (monochrome art) where the backend supports tinting.

fn weight(self, w: VectorWeight) -> Self

Select the glyph’s weight (template-form sources render true weights; plain SVGs degrade to Regular; see VectorWeight).

fn decorative(self) -> Self

Mark the glyph decorative (hidden from accessibility).

fn template(self) -> Self

Draw the glyph as a template (docs/vectors.md “Template”): untinted, it takes the foreground of the surface it sits on and follows the theme, instead of its authored colors. A .tint(…) still wins while it is set.

impl<DecoratedInner: WhenBuilder + Piece> WhenBuilder for Decorated<DecoratedInner>

fn otherwise<P: Piece>(self, build_arm: impl Fn() -> P + 'static) -> Self

The arm built while the condition is false. Without it, false means “no subtree”.

impl<DecoratedInner: ZStackBuilder + Piece> ZStackBuilder for Decorated<DecoratedInner>

fn align(self, a: Alignment) -> Self

Where children sit within the stack’s bounds (default Alignment::Center).