Crate day_pieces 

day-pieces — the built-in piece library (DESIGN.md §5.3).

Every constructor is a plain function returning a piece value; builder methods configure; build runs once. Dynamic attributes become seeded bindings writing sparse typed patches through the thread-local tree.

The vocabulary is split across sibling modules (one logical group each) and re-exported here, so the public API stays flat — day_pieces::button, day_pieces::stack, … — regardless of which module a piece is defined in.

Re-exports

pub use render::fill_measure;

pub use linkme;

Modules

prelude

render

External-piece registration surface (DESIGN.md §8.2). The renderer! macro registers a piece’s per-toolkit native renderer into a backend’s RENDERERS slice with typed make/update (the macro inserts the &dyn Any downcast) and no hand-written linkme boilerplate. fill_measure is the shared “growing leaf” sizing, so pieces stop hand-rolling it per backend.

Macros

dom_renderer

Register a piece’s web-dom renderer, whose registry is populated at RUNTIME.

glue_modules

Declare a satellite piece’s per-toolkit glue modules — the #[cfg]/#[path] block every piece otherwise hand-writes (docs/extending.md §2). Each named toolkit expands to the house-convention module gate binding lib-<toolkit>.rs next to the invoking lib.rs:

renderer

Register a piece’s per-toolkit native renderer into $slice (a backend’s RENDERERS).

routes

Define a plain routes enum and its Route impl in one shot:

Structs

A11yBuilder

Alert

A dialog / confirmation / action sheet. Buttons carry a typed payload T; .present() awaits and returns the chosen button’s payload, or None on cancel/dismiss.

BackRequest

The deferred pop handed to a Stack::on_back guard. Hold it, then call proceed to perform the back the guard consumed (the unsaved-changes → confirm → leave flow).

Button

Column

Confirm

A yes/no confirmation. Resolves to true only if the confirm button is chosen.

Cover

Divider

Drag

Drag info delivered to a shape’s .on_drag handler.

Draw

FileUrl

A cross-platform handle to a file the user chose in a native open/save picker.

FilledButtonStyle

A filled, rounded button style: a solid color background with a white label and comfortable padding, composed from Decorate::padding/Decorate::background/Decorate::corner_radius. v1 is static (no pressed/hover feedback).

FnMark

FocusBoolMark

FocusGroupMark

FormSection

One grouped form section (created by section): an optional header above a rounded card whose background is the platform’s own theme-adaptive grouped-content material (SurfaceRole::SectionCard — quaternary fill on AppKit, libadwaita .card, Qt palette(alternate-base), tertiary system fill on iOS, Material surface-container, the XAML card brush), so it follows light/dark mode with no app code.

Grid

GridRow

Image

A bundled image, resolved by name through the backend’s native image pipeline (§18.3). Scales with ContentMode::Fit by default (never stretches); tune with .content_mode() / .fill() / .stretch(), and optionally constrain the frame with .aspect_ratio(w/h).

ItemSlot

A Copy handle to one keyed item’s state — the unified each/list contract (§5.4).

Label

Link

A tappable run of text that opens url in the platform’s default handler — the system browser for http/https, the mail client for mailto:, and so on. This is Day’s analogue of SwiftUI’s Link.

List

A native recycling list: the platform widget owns scrolling + cell reuse; Day builds each visible row once and rebinds it (a slot-write into its ItemSlot) as cells recycle. Shares the ItemSlot row contract with each; migrating is a one-word change.

MenuEntry

A menu entry under construction. Build a command with menu_item, a nested submenu with sub_menu, a standard system command with menu_role, and a divider with menu_separator. Attach to a Piece via [Decorate::context_menu] or install app-wide via app_menu.

NativeRef

A liveness-checked reference to a mounted piece’s realized node — the retained half of the tweaks API (docs/tweaks.md). Capture one with Decorate::native_ref, then reach the native widget later (from event handlers, timers) through a toolkit ext accessor. node/with yield None before mount and after the node’s subtree is disposed, so async races are safe no-ops.

NavItem

One data-driven selector item, returned by item inside a Selector::items mapper.

OpenFile

A native “open file” picker. .await (or .present().await) resolves to the chosen FileUrl, or None if the user cancels.

Picker

A native picker bound two-way to selected. Style via .menu()/.segmented()/.inline().

Progress

A progress indicator: a determinate bar (from progress) or an indeterminate spinner (from spinner). See docs/progress.md.

Prompt

A single-line text prompt. Resolves to Some(text) on OK, None on cancel/dismiss.

Renderer

A third-party piece’s per-toolkit implementation. make receives the concrete backend (public helper surface) and returns a native handle the backend then owns like any built-in.

RoutePath

A typed absolute route: segments built from Route values plus query params. route(&Section::Stack).then(&Drill::Item { id: 42 }).param("hint", "linked") encodes to "stack/item-42?hint=linked" — RoutePath::navigate it, or hand it to nav_link_to.

Row

SaveFile

A native “save file” picker carrying the bytes to write. .await resolves to the chosen destination FileUrl, or None on cancel.

Scroll

Selector

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).

ShapePiece

A shape piece — one data-oriented piece parameterised by ShapeKind, rendered atop the canvas.

SignalMark

Slider

Spacer

Stack

A push/pop navigation stack whose contents are an app-owned Signal<Vec<K>> (the path above the root). Day reconciles the native stack to the path; the native back button writes the pop back into it (docs/navigation.md).

StaticMark

TextArea

A native multi-line text editor bound two-way to text. Configure a prompt with .placeholder(_), the auto-growing height band with .min_lines(_) / .max_lines(_), and the native editor attributes with .editable(_) / .selectable(_) / .spellcheck(_) (each accepts a constant or a reactive bool, and updates live). A backend that can’t honor an attribute answers the matching Cap::Text{Editable,Selectable,SpellCheck} with Support::Unsupported.

TextField

TextStyle

Canvas text styling (named fields per the API style rule, docs/api-style.md).

Toggle

ToolbarEntry

A toolbar item under construction. Build a command with toolbar_button, a two-state button with toolbar_toggle, a pull-down with toolbar_menu, a search field with toolbar_search, and the gaps with toolbar_space / toolbar_flexible_space.

Vector

A bundled vector glyph, resolved by name through whatever form the backend loads natively (§18.3: a VectorDrawable on Android, a catalog entry on Apple, an SVG on the web, a build-rasterized PNG where the toolkit has no vector path). Distinct from image on purpose: only a typed VectorName is accepted, and the modifiers are the vector-appropriate ones — tint recolors a monochrome glyph where the backend can (template rendering on Apple, drawable tint on Android, pixel recolor on GTK; backends without a tint path draw the authored colors).

ZStack

A z-stack: children are layered back-to-front (the first child sits at the bottom), all sharing the container bounds and positioned by the stack’s Alignment. The stack sizes to the UNION (max width/height) of its children — contrast [Decorate::overlay], which sizes to its content and treats the overlaid piece as a non-sizing annotation. Pure composition: it is the same native panel as [column]/row, so there is no per-backend work.

Enums

BackResponse

What a Stack::on_back guard returns for one back-like event (a native back gesture/button, or nav_back). Programmatic path writes are NOT guarded — the guard is a policy on the user’s back affordance, matching Jetpack Compose’s BackHandler (docs/navigation.md).

Corner

A corner radius: absolute points, or a 0..1 fraction of min(width, height).

DragPhase

The phase of a drag gesture (docs/shapes.md).

FractionSource

GestureKind

A gesture a node wants delivered. Backends attach the matching native recognizer when day-core calls Toolkit::enable_gesture; the default is no gesture (recognizers cost, so opt-in).

HAlign

Reactive

A parameter that is either a constant or a reactive source. get() is a tracked read, so any Reactive used inside a canvas draw closure makes that shape re-record when the source changes.

Reorder

A reorder guard’s verdict on a proposed row move (docs/list.md): consulted synchronously from the native drag’s validate hook, so the affordance (gap, insertion mark, forbidden cursor) reflects the answer while the user is still dragging.

SelectorStyle

How a selector presents its one-of-N choice.

ShapeKind

A shape’s geometry, resolved against the rect layout assigns it (frame-relative, SwiftUI-style).

TextSource

VAlign

VectorWeight

A vector glyph’s stroke weight (docs/vectors.md). Template-form sources (SF template SVGs, .symbolset bundles) carry true per-weight art; plain SVGs alias every weight to the same glyph, so .weight(…) degrades to Regular rather than to a missing asset.

Traits

ButtonStyle

A pluggable button appearance (the SwiftUI ButtonStyle analog). Pure composition — a style builds its body from existing pieces/decorators, so it needs no per-backend native code. Apply one with Button::style.

Decorate

IntoFocusBinding

A focus-binding target for [Decorate::focused] (docs/focus.md): either a Signal<bool> (one control) or a (Signal<Option<K>>, K) pair (one control of a group sharing a signal). The two-marker split is the same E0119 dodge as IntoText.

IntoFraction

Disjoint-marker conversion (like IntoText) so progress(_) accepts a constant f64, a Signal<f64>, or a closure. Reuses the same marker types.

IntoInsets

IntoReactive

Disjoint-marker conversion (like IntoText): accepts T, Signal<T>, or Fn() -> T.

IntoText

Disjoint-marker conversion (the coherent form of §12.2’s IntoText): literals, String, Signal<String>, and closures all convert, each under its own marker.

Modifier

A one-shot, by-value view transform (the SwiftUI ViewModifier analog): wrap a piece into a new one. Pure composition — no per-backend work. A plain FnOnce(AnyPiece) -> AnyPiece closure is a Modifier too (the blanket impl below), so the common case needs no new type. Apply one with Decorate::modifier.

Route

A typed route key — the compile-checked alternative to raw string keys.

SignalRw

Functions

alert

app_menu

Install the application menu — the native menu bar on desktop, the app-bar overflow on Android, the UIMenuBuilder main menu on iPadOS/Catalyst. Top-level entries are usually sub_menu(...)s (the menu-bar menus). Call at startup or whenever the menu changes; it replaces any previous app menu.

app_menu_reactive

app_menu that re-lowers and re-installs whenever a locale-tracked read inside the builder changes — menu_role labels, res::str titles, and day::tr all read the locale signal, so a runtime language switch rebuilds the menu in the new language (docs/menus.md). Replacement drops the previous install’s action closures (context menus are unaffected). The binding lives in a root-owned scope: install once, at startup.

arc

button

canvas

The drawing closure is a binding: signal reads re-record; layout size changes re-record (via FrameChanged); replay is equality-gated by DrawOp’s PartialEq (§4.2).

capsule

circle

column

confirm

cover

A fullscreen cover over open: Some(r) presents build(&r), None dismisses (docs/cover.md). Registers a string-route adapter, so navigate("<key>") opens it and nav_back() closes it, and current_route() reports the presented key.

current_route

The FULL current route — every mounted surface’s contribution, outermost to innermost, /-joined. Round-trips through navigate: persist it on exit, navigate(&saved) on launch (docs/navigation.md).

divider

each

Reactive keyed collection (§5.4): keyed diff, per-key child scopes, slot writes for surviving keys, debug key-uniqueness assertion.

ellipse

environment

Read the nearest ambient T provided by an enclosing with_environment, or None if none is in scope. Call it while constructing or building a piece within that subtree.

form

A settings-style form: a vertical run of sections whose labeled rows share one label column across the WHOLE form.

frame_clock

A frame clock (§8.4): an invisible, zero-size piece that calls tick every animation frame with the wall-clock delta since the previous frame, for as long as it is mounted. Drop it into the tree (e.g. behind a canvas in a zstack) to drive a game loop or self-driven animation: the tick mutates state Signals, and a canvas reading them re-records that frame.

grid

A SwiftUI-style eager grid (docs/grid.md): columns are inferred from grid_row children — a column is as wide as its widest cell, a grow_w cell makes its column share the leftover width evenly, and a non-row child becomes a full-width cell spanning every column. spacer() inside a row is an inert empty cell that still occupies its column (a grid has explicit gutters, so stack-style push-apart spacers don’t apply). Cells opt into spans and per-cell alignment with [Decorate::grid_span] / [Decorate::grid_align].

grid_row

One row of a grid: each child is a cell, assigned to columns left to right. Outside a grid a row degrades gracefully to a plain row. Rows are transparent carriers — the grid places their cells directly — so decorating a grid_row itself is unsupported (decorate the cells, or the grid).

image

item

A selector item for a data-driven list: item(room.id, room.name).icon(res::images::room) (docs/navigation.md). Used inside the .items(signal, |t| …) mapper; the page it selects is built by the selector’s Selector::destination.

label

labeled

A form row: label sits in the form-wide aligned label column (right-aligned, vertically centered), control beside it. Outside a form the label column is just this row’s own label width. A control with .grow() stretches to the row’s remaining width.

line

A stroked segment between two unit points of the frame: line((0.16, 0.5), (0.84, 0.5)).

link

Build a Link that opens url when tapped.

list

Build a recycling list from a reactive items closure, a key function, and a row builder.

menu_item

A clickable command: menu_item("Save").key("s").action(|| …).

menu_role

A standard/system command (MenuRole::Copy, MenuRole::Quit, …) rendered with the platform’s NATIVE item — correct label, default shortcut, focus-targeting, and automatic enable/disable — so default menu items (Edit ▸ Cut/Copy/Paste, the app’s Quit/About) work without re-implementation.

menu_separator

A visual divider between items.

nav_back

Pop one navigation level. False = nothing to pop.

nav_link

A tappable link that navigates to path when pressed.

nav_link_to

A tappable link that navigates to a typed RoutePath when pressed.

navigate

Navigate to a route (docs/navigation.md).

navigate_to

Navigate to a single typed key, RELATIVE (innermost surface first) — the typed navigate(&r.key()), percent-escaped. For absolute paths chain a route.

open_file

Start a native open-file picker (docs/files.md).

picker

picker(["A", "B", "C"], choice).segmented() — options are fixed, selected is the bound index.

polygon

A polygon of unit points of the frame: polygon([(0.5, 0.0), (1.0, 1.0), (0.0, 1.0)]).

progress

A determinate progress bar. fraction is the completed portion in 0.0..=1.0; pass a constant, a Signal<f64>, or a closure and it tracks reactively (out-of-range values are clamped).

prompt

rectangle

SwiftUI-ergonomic sugar — all build the same ShapePiece.

rounded_rectangle

route

Start a typed RoutePath at the outermost segment.

route_param

One query param of the most recent navigate (None = not present).

route_params

The query params of the most recent navigate (?name=value&…) — read inside a destination builder. See docs/navigation.md for when params apply.

row

save_file

Start a native save-file picker for data (docs/files.md).

scroll

section

A grouped card of form rows; .title(…) adds the header. Works inside a form (shared label column) or standalone.

selector

shape

The unified constructor: shape(ShapeKind::RoundedRectangle { corner: 12.0.into() }).

shape_group

Flatten many shape descriptions into ONE canvas leaf — one native view no matter how many shapes (docs/shapes.md §3.6). Shapes draw in order; reactive properties re-record the group. Child gestures are not wired inside a group — put .on_tap on the group via Decorate.

shape_group_fn

Size-aware shape_group: the closure derives the shapes from the laid-out size and re-runs on FrameChanged, exactly like canvas — for geometry that depends on the final size (e.g. data mapped along the width).

slider

spacer

spinner

An indeterminate, animated progress indicator (a spinner / busy bar) for work with no known extent.

stack

sub_menu

A nested submenu: sub_menu("File", vec![menu_item("New"), …]).

text_area

text_area(text) — a native multi-line editor whose contents mirror text in both directions.

text_field

toggle

toolbar

Install the toolbar on the window being built — the primary window at startup, and the new window inside a register_new_window builder. Replaces any previous toolbar on that window; an empty items removes it. Add or remove an item by calling this again with a different list, or use toolbar_reactive to keep the list derived from state.

toolbar_button

A push button: toolbar_button("refresh", tr("refresh")).icon(Symbol::Refresh).action(…).

toolbar_flexible_space

A gap that absorbs the leftover width. Everything before the first one is packed to the leading edge and everything after it to the trailing edge, which is how each toolkit’s own packing (GTK’s start/end, XAML’s content/commands) is expressed in one ordered list.

toolbar_label

Static text in the bar — a status or a caption.

toolbar_menu

A button that drops a menu, built from the same entries crate::app_menu takes.

toolbar_reactive

toolbar that re-lowers and re-installs whenever a reactive read inside builder changes — a locale switch, or a command list that depends on what is selected.

toolbar_search

A native search field bound two-way to query — NSSearchToolbarItem, GtkSearchEntry, a Qt search QLineEdit, an AutoSuggestBox. Set the prompt with .placeholder(_).

toolbar_separator

A divider, where the platform draws one (macOS toolbars have none — AppKit renders it as a fixed gap; docs/toolbars.md).

toolbar_space

A fixed gap.

toolbar_toggle

A two-state button bound to on: the user flipping it writes the signal, and writing the signal restyles the button.

vector

when

Reactive conditional subtree. The anchor is a layout-transparent group; the active arm lives in its own child scope, disposed on switch (§4.3).

with_environment

Provide an ambient value T to content and its ENTIRE descendant subtree (the SwiftUI @Environment/.environment(_) analog, layered over day-reactive’s scope context). content — and any piece built within it — reads it back with environment. A thin, non-reactive wrapper: T is a snapshot captured here; for a value that must react, provide a Signal<T> (or a Memo<T>) and read it reactively inside the subtree.

zstack

Build a ZStack from a tuple of children (or a PieceVec).