Trait Decorate 

pub trait Decorate: Piece + Sized {
    // Provided methods
    fn id(self, id: ElementId) -> Decorated<Self> { ... }
    fn wrapper_id(self, id: ElementId) -> Decorated<Self> { ... }
    fn apply_if(
        self,
        cond: bool,
        f: impl FnOnce(Decorated<Self>) -> Decorated<Self>,
    ) -> Decorated<Self> { ... }
    fn apply_some<T>(
        self,
        value: Option<T>,
        f: impl FnOnce(Decorated<Self>, T) -> Decorated<Self>,
    ) -> Decorated<Self> { ... }
    fn id_of(self, id: impl Fn() -> ElementId + 'static) -> Decorated<Self> { ... }
    fn tweak(self, f: impl FnOnce(RNode) + 'static) -> Decorated<Self> { ... }
    fn selectable(self) -> Decorated<Self> { ... }
    fn cursor<M>(self, cursor: impl IntoReactive<Cursor, M>) -> Decorated<Self> { ... }
    fn window_drag_region(self) -> Decorated<Self> { ... }
    fn native_ref(self, r: &NativeRef) -> Decorated<Self> { ... }
    fn padding(self, insets: impl IntoInsets) -> Decorated<Self> { ... }
    fn max_width(self, max: f64) -> Decorated<Self> { ... }
    fn min_width(self, min: f64) -> Decorated<Self> { ... }
    fn reserving(self, sample: impl Into<String>) -> Decorated<Self> { ... }
    fn frame(self, width: f64, height: f64) -> Decorated<Self> { ... }
    fn width(self, width: f64) -> Decorated<Self> { ... }
    fn height(self, height: f64) -> Decorated<Self> { ... }
    fn a11y(
        self,
        f: impl FnOnce(A11yBuilder) -> A11yBuilder + 'static,
    ) -> Decorated<Self> { ... }
    fn on_tap(self, f: impl Fn() + 'static) -> Decorated<Self> { ... }
    fn on_tap_at(self, f: impl Fn(Point) + 'static) -> Decorated<Self> { ... }
    fn focused<M>(self, binding: impl IntoFocusBinding<M>) -> Decorated<Self> { ... }
    fn on_key(self, f: impl Fn(&KeyEvent) + 'static) -> Decorated<Self> { ... }
    fn toolbar<M>(self, content: impl ToolbarContent<M>) -> Decorated<Self> { ... }
    fn searchable(self, search: Search) -> Decorated<Self> { ... }
    fn focusable(self) -> Decorated<Self> { ... }
    fn drag_source(
        self,
        source: impl Fn(Point) -> Option<Offer> + 'static,
    ) -> Decorated<Self> { ... }
    fn drop_target(self, target: Target) -> Decorated<Self> { ... }
    fn context_menu<M>(
        self,
        menu: impl ContextMenuContent<M>,
    ) -> Decorated<Self> { ... }
    fn on_drag(self, f: impl Fn(Drag) + 'static) -> Decorated<Self> { ... }
    fn on_pinch(self, f: impl Fn(Pinch) + 'static) -> Decorated<Self> { ... }
    fn on_pan(self, f: impl Fn(Pan) + 'static) -> Decorated<Self> { ... }
    fn on_hover(self, f: impl Fn(Option<Point>) + 'static) -> Decorated<Self> { ... }
    fn card(self) -> Decorated<Self> { ... }
    fn background<M>(
        self,
        color: impl IntoReactive<Color, M>,
    ) -> Decorated<Self> { ... }
    fn corner_radius(self, radius: f64) -> Decorated<Self> { ... }
    fn opacity<M>(self, opacity: impl IntoReactive<f64, M>) -> Decorated<Self> { ... }
    fn transform<M>(self, t: impl IntoReactive<Transform, M>) -> Decorated<Self> { ... }
    fn scale<M>(self, factor: impl IntoReactive<f64, M>) -> Decorated<Self> { ... }
    fn rotation<M>(self, degrees: impl IntoReactive<f64, M>) -> Decorated<Self> { ... }
    fn translation<Mx, My>(
        self,
        x: impl IntoReactive<f64, Mx>,
        y: impl IntoReactive<f64, My>,
    ) -> Decorated<Self> { ... }
    fn animation(self, anim: AnimSpec) -> Decorated<Self> { ... }
    fn modifier(self, m: impl Modifier) -> AnyPiece { ... }
    fn overlay(self, over: impl Piece) -> Decorated<Self> { ... }
    fn overlay_aligned(
        self,
        align: Alignment,
        over: impl Piece,
    ) -> Decorated<Self> { ... }
    fn aspect_ratio(self, ratio: f64) -> Decorated<Self> { ... }
    fn grow(self) -> Decorated<Self> { ... }
    fn grow_w(self) -> Decorated<Self> { ... }
    fn grow_h(self) -> Decorated<Self> { ... }
    fn grid_align(self, a: Alignment) -> Decorated<Self> { ... }
    fn defers_system_gestures(self, edges: Edges) -> Decorated<Self> { ... }
    fn status_bar_hidden<M>(
        self,
        hidden: impl IntoReactive<bool, M>,
    ) -> Decorated<Self> { ... }
    fn interactive_dismiss_disabled(self) -> Decorated<Self> { ... }
    fn any(self) -> AnyPiece { ... }
}

Provided Methods

fn id(self, id: ElementId) -> Decorated<Self>

Stable element identifier: a11y identifier + dayscript locator + lint uniqueness (§5.5).

Names the piece’s own node wherever it sits in the chain (docs/api-style.md “Modifier classes”): .padding(8.0).id(day_core::id!(x)) and .id(day_core::id!(x)).padding(8.0) tag the same node. To name a wrapper instead, use wrapper_id.

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

Name the node that is outermost at this point in the chain: the padding box, the frame, the background, whichever wrapper the modifiers before it built. For a dayscript frame assertion on the wrapper rather than on the piece. Ordered, unlike id.

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

Apply f to the chain when cond holds, else continue unchanged (see Decorated::apply_if): nav(sel).apply_if(!primary, |n| n.local()). The closure receives the decorated piece, so forwarded builder methods and modifiers both chain inside it.

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

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

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

Reactive element id: the id for rows inside a recycling list. A plain id is assigned once at build, but a recycled cell rebinds to different items over its life (and drag-to-reorder rebinds eagerly), so a static item-derived id keeps naming the first-bound item. This variant re-registers whenever the closure’s value changes; read your ItemSlot inside it: .id_of(move || day_core::id!(row_remove, slot.key())).

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

Apply a tweak: f runs once at mount, after the native widget exists, with the realized node (docs/tweaks.md). Reach the typed native handle through the compiled backend’s ext accessor (day_appkit::with_native, day_gtk::with_native, …), or apply a packaged day-tweak-* crate’s modifier instead of calling this directly. If the native change affects the widget’s intrinsic size, follow it with day_core::invalidate_size. Day may overwrite managed properties (title, value, enabled, frame, a11y) on its next patch; unmanaged properties are stable.

Order it after any modifier that can rebuild the backing widget; today that is selectable, which on UIKit realizes the label as a different native class. Chained before it, the tweak runs against the widget the rebuild discards (Day warns at runtime); chained after, it sees the widget that ships.

fn selectable(self) -> Decorated<Self>

Make this piece’s text user-selectable, so the reader can select and copy it (docs/text.md). Most useful on a label: text is not selectable by default on any backend, matching each platform’s native behavior.

Every backend honors it on a label: most flip the native widget’s selection affordance (AppKit, GTK, Qt, XAML, HarmonyOS, Android, web); UIKit, whose UILabel has none, rebuilds the label as a read-only UITextView behind the same handle. On other widgets it is best-effort: a backing with no selection affordance leaves the text unselectable rather than erroring, and a container cascades only where the platform’s affordance does (the web), so prefer the label itself. Selection visuals and the copy shortcut are the platform’s own. Unmanaged: set once at mount, and it survives Day’s text updates.

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

Shape the pointer while it is over this piece and its descendants (docs/cursor.md): a Cursor constant, a Signal<Cursor>, or a closure, so a canvas tool or a busy state moves the shape without rebuilding the piece. The nearest ancestor’s cursor wins, and Cursor::Default releases the piece back to the platform. capability(Cap::Cursor) says whether this toolkit draws the requested shapes, a nearest neighbor, or nothing; a touch-only host never shows one, which is correct rather than a failure.

fn window_drag_region(self) -> Decorated<Self>

Let the user move the window by dragging this piece, as a title bar does (docs/window-chrome.md): what a custom title bar in a WindowChrome::Overlay or WindowChrome::Frameless window needs. The piece’s own background starts the drag, with the platform’s snapping and tiling; buttons and fields inside it keep their clicks; a double click does what the user’s title-bar setting says (zoom, minimize, nothing). capability(Cap::DragRegion); on a phone the piece is an ordinary view.

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

Capture a NativeRef to this piece’s realized node for later imperative access (docs/tweaks.md). The ref clears automatically when the piece’s scope is disposed.

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

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

Cap this piece’s width at max points: the child is never PROPOSED more, so text wraps inside the cap (chat bubbles, readable columns) while narrower content hugs.

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

See Decorated::min_width.

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

Reserve at least the space sample needs, so this piece’s size stops changing with its content.

For a numeric readout beside a slider: label(move || value()).reserving("100") keeps the row still while the number changes, because the reservation is a real measurement of "100" in this piece’s own font: it scales with the platform’s accessibility text size instead of being a point value that clips when someone turns text up.

Pass the widest value the field can show ("100", "-99.9", "88:88"). Pair it with tabular numbers so the digits themselves stop shifting inside the reservation. The sample never paints and never takes hit-testing area.

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

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

Fix this piece’s width to width points while its height stays flexible (hugging its content or filling on the cross axis). The single-axis complement to Self::frame, e.g. a fixed-width sidebar pane in a row whose height fills the window.

fn height(self, height: f64) -> Decorated<Self>

Fix this piece’s height to height points while its width stays flexible. The single-axis complement to Self::frame, e.g. a fixed-height header/toolbar bar that fills its width.

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

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

Fire when this piece is tapped (bounding-box; shapes override with path-precise testing).

Do not use this to activate a native button; use crate::Button::action instead. 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.

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

on_tap, told where: the point in the piece’s own coordinate space, origin at its top-leading corner.

What a drawn control needs and a native one does not: a canvas showing a color wheel, a map, or a waveform has to turn “the user pressed here” into a value, and only the piece knows how. Pair it with on_drag, which already reports a location, to track a press that turns into a drag; the two are idempotent together, so a backend that reports a tap as a zero-length drag costs nothing.

Event::Tap has always carried the point; this is the decorator that stops throwing it away.

For native buttons use crate::Button::action, not this gesture decorator.

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

Bind this control’s keyboard focus to a signal (docs/focus.md), two-way like every other binding: native focus changes write the signal; writing the signal moves focus. Takes a Signal<bool> for one control, or (Signal<Option<K>>, K::Variant) binding one control of a group; writing false/None resigns focus (dismissing the soft keyboard on mobile). Focus applies asynchronously: a write is a request, resolved on the next turn, and the signal always ends up reflecting what the platform actually did.

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

Handle the non-text keys (the arrows) that reach this piece while it has focus (docs/menus.md). Keys follow focus, so pair it with Decorate::focused or with a piece the user can click into: a canvas takes focus on a press, and only the focused piece hears the keys, so a nudge handler can never fire while a text field, a list or a sidebar is the one being typed into.

Which pieces can hold focus is the platform’s to answer (docs/focus.md): a canvas is focusable on the backends that draw one from a real view (appkit, web-dom today).

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

Declare toolbar items on the chrome this piece sits under (docs/toolbars.md).

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

page.toolbar(toolbar_button(day_core::id!(share), tr("share")).icon(Symbol::Share).action(share))
page.toolbar([reply, forward, archive])
page.toolbar(move || vec![toolbar_button(day_core::id!(undo), tr("undo")).enabled(can_undo)])

Which chrome carries them follows from where this piece is built (a destination page’s own bar, a content-list pane’s, or the window’s if it is under no page at all), and the items are withdrawn when this piece is disposed. Where on that chrome they sit is ToolbarEntry::placement.

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

A search field for this navigation page (docs/search.md, “Page search”), drawn where the platform puts a page’s search: the window toolbar on a desktop, the page’s navigation bar on iOS (a UISearchController), its app bar on Android. It shows while this page does, and its text is the app’s query both ways. For a search the server runs, act on crate::Search::on_submit; for a local filter, read the query. Declare it on a nav_stack destination, as .toolbar(…) is declared; a whole navigation surface takes crate::Nav::searchable instead.

fn focusable(self) -> Decorated<Self>

Opt this piece into the platform’s focus system (docs/focus.md): the canvas contract for anything composed: it joins the key loop, takes focus on a press, reports through .focused(…), and hears the arrows through .on_key(…) while focused. A composed list column is the motivating case (docs/navigation.md). On a backend without the set_focusable duty the piece renders normally and never takes focus.

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

Attach a context menu, shown with the platform’s native affordance on secondary-click (desktop) or long-press (mobile). Items are built with menu_item/sub_menu/menu_role/ menu_separator. Passing an empty Vec removes any menu.

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

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

A context menu (docs/menus.md): shown on secondary-click / long-press, built from the same menu_item/sub_menu entries as everywhere else. Takes a fixed list, or a closure built when the menu is summoned (“Dynamic context menus”): with no argument, or with the summon point in this piece’s own coordinates, so a canvas can select what is under the pointer and offer commands for that selection. An empty result shows nothing.

label(t).context_menu([menu_item(res::str::copy()).action(copy)])
canvas(draw).context_menu(move |at: Point| commands_for(hit_test(at)))

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

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

Fire on each phase of a pinch/magnify over this piece (docs/canvas.md “Zoom and pan”). Only backends with a native recognizer wired emit it; pair a zoom with visible controls.

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

Fire on each viewport-pan event over this piece (docs/canvas.md “Zoom and pan”): trackpad two-finger scroll, two-finger touch pan. delta is incremental; apply it as it arrives.

fn on_hover(self, f: impl Fn(Option<Point>) + 'static) -> Decorated<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; wire on_tap_at alongside it so a touch-only device can reach the same thing.

fn card(self) -> Decorated<Self>

Fill the piece’s bounds with a solid color painted behind it: a message-bubble / card / badge surface. Accepts a constant Color, a Signal<Color>, or a Fn() -> Color; a reactive color repaints the surface when its source changes. Wraps the piece in a native container that carries the fill, so it composes with Self::corner_radius for a rounded colored surface and with Self::padding for interior inset. The platform’s card around this piece: the grouped-content surface with rounded corners and a Space::M inset (see Decorated::card).

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

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

Round the piece’s corners to radius points, clipping its background and content to the rounded rectangle. Compose after Self::background for a rounded colored surface, or use alone to round a clipped child (e.g. an avatar image).

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

Animate/set the piece’s opacity (0.0 transparent … 1.0 opaque). Wrapped in a native layer so it composes with .background; the change animates when made inside with_animation or under a .animation ancestor (§8.4).

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

Apply an animatable Transform (translate/scale/rotate about the center): the cheap movement/scaling channel that never triggers relayout (§8.4). Prefer this over .offset for animated motion.

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

Uniformly scale the piece by factor about its center (animatable). Convenience over Self::transform.

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

Rotate the piece by degrees clockwise about its center (animatable).

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

Translate the piece by (x, y) points without relayout (animatable): the animation-friendly sibling of .offset.

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

Attach an implicit animation (§8.4): changes to this piece’s (and its descendants’) animatable properties animate with anim even outside a with_animation. SwiftUI’s .animation. The ambient with_animation takes precedence when both apply.

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

Apply a Modifier (or, via the blanket impl, a plain FnOnce(AnyPiece) -> AnyPiece closure) to this piece. Pure composition: content.modifier(m) == m.apply(content.any()).

The one modifier that erases: Modifier is defined over AnyPiece, so the piece’s own type cannot survive it.

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

Draw over on top of this piece, centered, without affecting layout size: a badge / annotation overlay. self is the sizing content (bottom of the z-order); over is proposed self’s size and drawn on top. For an explicit alignment use Self::overlay_aligned; for a stack that sizes to the union of its children use zstack.

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

Self::overlay with an explicit Alignment for the annotation (e.g. a corner badge with Alignment::TopTrailing).

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

Constrain this piece to a width / height ratio: the largest box of that shape which fits whatever the parent offers (SwiftUI’s .aspectRatio(_:contentMode: .fit)).

Pair it with Self::grow_w for a piece that takes the width available and derives its height from it: a canvas whose drawing has to keep its proportions as the window resizes, say. image has carried this since it shipped; this is the same layout, for any piece.

A ratio that is not finite and positive describes no box, so it is ignored.

fn grow(self) -> Decorated<Self>

Expand to fill the available space on both axes (a filling pane / card that stretches to its container). Wraps the piece in a layout-only node carrying grow Flex: the stack offers it the space and it fills; no native backing, so this is a pure layout change.

fn grow_w(self) -> Decorated<Self>

Expand to fill the available horizontal space.

fn grow_h(self) -> Decorated<Self>

Expand to fill the available vertical space.

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

Override this cell’s alignment within its cell rect of the enclosing grid (docs/grid.md). Apply last (outermost), like Decorated::grid_span.

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

While this subtree is mounted, ask the OS to require a second swipe for its edge gestures on edges (docs/cover.md), the SwiftUI defersSystemGestures(on:) analogue. Put it on a game or drawing surface whose touches run to the screen edge, so a swipe up from the bottom doesn’t leave the app. iOS defers the chosen edges’ system gestures; Android enters swipe-to-reveal immersive mode while any subtree requests deferral; desktop backends no-op.

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

While this subtree is mounted and hidden is true, hide the system status bar, the SwiftUI statusBarHidden(_:) analogue (docs/cover.md). hidden is a constant, a Signal, or a closure, so a setting can turn it on and off in place. Put it on a page that wants the whole screen (a reader, a game, a photo viewer); the bar returns when the page unmounts. Any mounted request that answers true hides the bar. iOS, Android and HarmonyOS hide it (Cap::StatusBarHidden); desktop and web have none and ignore it.

fn interactive_dismiss_disabled(self) -> Decorated<Self>

While this subtree is mounted, the enclosing cover (or other modal surface) must not be dismissed interactively, the SwiftUI interactiveDismissDisabled() analogue (docs/cover.md). System back / sheet gestures are ignored; only programmatic writes (an explicit close control) dismiss it.

fn any(self) -> AnyPiece

Erase to a single AnyPiece: for a Vec<AnyPiece>, a -> AnyPiece signature, or any other place one concrete type is required. AnyPiece::any is inherent and returns self, so erasing an already-erased piece costs nothing.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl<P: Piece> Decorate for P