Expand description
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 async_image::AsyncImage;pub use async_image::AsyncImageBuilder;pub use async_image::async_image;pub use colorpicker::ColorPicker;pub use colorpicker::ColorPickerBuilder;pub use colorpicker::PickerIdiom;pub use colorpicker::color_picker;pub use combobox::ComboBox;pub use combobox::ComboBoxBuilder;pub use combobox::combo_box;pub use datetime::DatePicker;pub use datetime::DatePickerBuilder;pub use datetime::TimePicker;pub use datetime::TimePickerBuilder;pub use datetime::date_picker;pub use datetime::time_picker;pub use pager::Pager;pub use pager::pager;pub use pullrefresh::PullRefresh;pub use pullrefresh::PullRefreshBuilder;pub use pullrefresh::pull_to_refresh;pub use searchfield::SearchField;pub use searchfield::SearchFieldBuilder;pub use searchfield::search_field;pub use stepper::NumberField;pub use stepper::NumberFieldBuilder;pub use stepper::Stepper;pub use stepper::StepperBuilder;pub use stepper::StepperIdiom;pub use stepper::number_field;pub use stepper::stepper;
Modules§
- async_
image - Images decoded from reactive bytes, with a placeholder and optional clipping. Uses the core decoder and canvas; no toolkit-specific image pipeline or HTTP dependency.
- colorpicker
day_pieces::colorpickeris a color chooser bound two-way to aSignal<Color>, in two idioms (docs/colorpicker.md; DESIGN.md §15).- combobox
- Core editable combo box. Protocol types live in
day-spec; each supported toolkit owns its native renderer and any required C++ or Java shim. - datetime
day_pieces::datetime: core date and time pickers with native toolkit renderers and a composed DOM fallback (docs/datepicker.md; DESIGN.md §15).- markdown
- Inline markdown → styled runs (docs/markdown.md). The parser moved to day-spec, beside
the
TextRuns it produces and the other format codecs; this keeps the old path working. Inline markdown → styled runs (docs/markdown.md). Lives here rather than in day-pieces because it producesTextRuns, and every format codec beside it reads the same model. Inline markdown → styled runs, parsed at RUNTIME (docs/markdown.md). - pager
- Native interactive horizontal paging. Slots have stable native identities;
orderchooses which slots participate and their reading order. Changing order never rebuilds a page. Apps must defer changing slot contents whilebusyis true. Native callbacks carry the presentation epoch, so delayed completions cannot select a recycled slot. - prelude
- pullrefresh
day_pieces::pullrefresh: pull-to-refresh for any Day scrollable, modeled on SwiftUI’srefreshable(action:)(DESIGN.md §15; docs/extending.md).- render
- The per-toolkit glue-module declaration for a piece crate (docs/extending.md §2). The
renderer registration macros are day-spec’s (
day_spec::renderer!), beside theRenderertype they fill in. - searchfield
- Core search input with a toolkit-owned native renderer:
NSSearchField,UISearchTextField,GtkSearchEntry, a Qt search field, Android search input, XAMLAutoSuggestBox, or DOM search input. - stepper
day_pieces::stepper: a numeric stepper field, a text field with increment/decrement arrows, bound two-way to anyBinding<f64>(docs/stepper.md).
Macros§
- 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 bindinglib-<toolkit>.rsnext to the invoking lib.rs: - id
#[day_pieces::builder(FooBuilder)]: a piece’s builder trait, generated from its inherent impl (docs/api-style.md “Typed builders and erasure”). Declare an ID at its piece, including a link-time catalog entry.- routes
- Define a plain routes enum and its
Routeimpl in one shot:
Structs§
- A11y
Builder - The annotations
.a11y(|a| …)collects (docs/accessibility.md). The three strings areTextSources, so each takes a literal, aString, aSignal<String>or a closure: a gauge’s value follows the gauge, and a localized label follows the locale. - Adaptive
- The piece
adaptivebuilds. - Alert
- A dialog / confirmation / action sheet. Buttons carry a typed payload
T;.present()awaits and returns the chosen button’s payload, orNoneon cancel/dismiss. - AtPoint
Mark - Marker for a summon-time closure that takes the summon point.
- Back
Request - The deferred pop handed to a
NavStack::on_backguard. Hold it, then callproceedto perform the back the guard consumed (the unsaved-changes → confirm → leave flow). - Branches
- The plain-data
NodeSourcebuilt bybranches. - Branches
Conn Branches’ connection: the current data snapshot plus its derived shape.- Button
- Canvas
Exports - What this toolkit can export a canvas drawing to (
Cap::CanvasBitmap,Cap::CanvasPdf). Read it to enable or hide export commands, the wayimage_encode_formatsdecides which formats to offer. - Column
- Command
- An application operation shared by buttons, menus, toolbars, and direct callers
(docs/commands.md): one id, one title, one availability, one handler, presented through
button,menu_itemandtoolbar_item. - Confirm
- A yes/no confirmation. Resolves to
trueonly if the confirm button is chosen. - Content
List - The content-list pane of a Mail-shaped nav (docs/navigation.md), declared with
Nav::content_list: mailboxes, message list, message.buildmakes the middle column, built once and resident for the host’s life; its content follows the app’s own signals (the selection scoping it, the row chosen from it), never a rebuild. - Cover
- DayDate
- A civil (zoneless) calendar date, proleptic Gregorian. Ordered chronologically;
DisplayandDayDate::parse_isospeak ISO-8601 (YYYY-MM-DD). - DayTime
- A civil (zoneless) wall-clock time.
DisplayandDayTime::parse_isospeak ISO-8601 (HH:MM, orHH:MM:SSwhen seconds are nonzero). - Decorated
- A piece with modifiers chained onto it, keeping the decorated piece’s type (§5.2).
- Delete
- Swipe-to-delete for a
list()(docs/list.md): the handler that applies a committed delete, the label the platform puts on its affordance, an optional per-row guard, and whether the gesture is offered right now. A list is deletable exactly when it carries one of these (list(..).deletable(Delete::new(f))). - Derived
Mark - Marker for a closure that derives the list.
- Derived
Options Mark - Marker for a derived list of options.
- Divider
- A hairline between neighbors: across a column’s width by default, down a row’s height
with
Divider::vertical. - Document
Tabs - A resident, closable document surface. Content is built once per key and disposed on removal. A selected document owns its native focus and command context.
- Drag
- Drag info delivered to a shape’s
.on_draghandler. - Draw
- Drawing
- A recorded drawing at a fixed size: what a
canvaswould replay, kept for export. - Element
Id #[day_pieces::builder(FooBuilder)]: a piece’s builder trait, generated from its inherent impl (docs/api-style.md “Typed builders and erasure”). An application-owned element identity, declared withcrate::id!.- File
Access - A resolved file and the lifetime of its native access grant. Borrow the file while doing I/O; a cloned path alone does not retain access after this guard is dropped.
- FileUrl
- A cross-platform handle to a file the user chose in a native open/save picker.
- Fixed
Options Mark - Marker for a fixed list of options.
- FnMark
- Focus
Bool Mark - Focus
Group Mark - Form
- A whole form, created by
form: the shared label column wrapped around a vertical run ofsections. - Form
Section - One grouped form section (created by
section): an optional header above a rounded card whose background is the platform’s theme-adaptive grouped-content material (SurfaceRole::SectionCard: quaternary fill on AppKit, libadwaita.card, Qtpalette(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
- An image: a bundled asset resolved by name through the backend’s native image pipeline
(§18.3), encoded bytes the app already holds, or an image decoded once and shared
(docs/images.md). Scales with
ContentMode::Fitby default (never stretches); tune with.content_mode()/.fill()/.stretch(), and optionally constrain the frame with.aspect_ratio(w/h). - Image
FnMark - Marker for
Fn() -> ImageSource. - Image
Signal Mark - Marker for
Signal<ImageSource>. - Image
Value Mark - Marker for the by-value conversions (a name, bytes, a bitmap, a source).
- Inspector
- Window content beside a trailing inspector panel, visibility bound to
visible(docs/inspector.md). - Item
Slot - A
Copyhandle to one keyed item’s state: the unifiedeach/listcontract (§5.4). - Items
- The plain-data
RowSourcebuilt byitems. - Items
Conn Items’ connection: the current data snapshot the slots read from.- Keyed
- The piece
keyedandswitchbuild: an anchor whose single child subtree follows a key. - Label
- Labeled
- One form row, created by
labeled: a label in the form-wide column beside its control. - Link
- A tappable run of text that navigates to a
#routeor opens a URL in the platform’s default handler: the system browser forhttp/https, the mail client formailto:, and so on. - List
- A native recycling list: the platform widget owns scrolling + cell reuse; Day builds each
visible row once and rebinds it as cells recycle. Takes any
RowSource; shares the row contract witheach, so migrating a collection between them is a one-word change. - List
Item - A list row’s standard content, built by
list_item(docs/list.md “List items”). - Load
Piece - The piece
loadbuilds. - Loaded
- The loaded value, handed to a
load’s ready arm:get()is a tracked read that followsReady(a)toReady(b)in place, without rebuilding the arm.Copy, like a signal. - Localized
Mark - Many
Mark - Marker for a list of entries: a
Vecor an array. - Menu
Button - A button that opens a menu when pressed: the ⋯ More button beside a browser’s address bar, an
Add ▾ button, a page-actions button in a toolbar row the app draws itself. Build one with
menu_button. - Menu
Entry - A menu entry under construction. Build a command with
menu_item, a nested submenu withsub_menu, a standard system command withmenu_role, and a divider withmenu_separator. Attach to a Piece viaDecorate::context_menuor install app-wide viaapp_menu. - Model
Slot - One recycled row’s connection to its store: the slot a model list’s row builder
receives.
Copy, and a day-modelSource, so#[derive(Observable)]accessors hang off it.text_field(slot.name())binds two-way and follows the slot to its next row when the cell recycles, because the slot resolves its row on every operation. - Move
- A native hierarchical tree (docs/tree.md): rows nest, disclose, and drag to a new parent.
The platform widget owns scrolling, disclosure and cell reuse; Day builds each visible row
once and rebinds it as cells recycle (
list()’s contract, token-addressed). Gate its UI onCap::Tree: a backend without tree support renders nothing. Drag-to-move for atree(docs/tree.md): the handler that applies a committed re-parent, an optional guard consulted while the drag is live, and whether the gesture is offered right now. A tree is movable exactly when it carries one of these (tree(..).movable(Move::new(f))). Thelist()counterpart isReorder. - Native
Ref - 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/withyieldNonebefore mount and after the node’s subtree is disposed, so async races are safe no-ops. - Nav
- NavDrop
- Where a dragged sidebar row landed (
Nav::regroup_items). - NavItem
- One nav item (docs/navigation.md): a key, a title, and its decorations, built by
item. The same value describes a static destination (item("home", title).page(home_page)) and a row of a data-driven block (nav_items(move || feeds(), |f| item(f.id, f.name))). - NavItems
- A data-driven block of nav items (docs/navigation.md), built by
nav_items: re-derives whenever the signal changes. - NavStack
- 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). - Number
Format - A decimal or percentage format shared by numeric controls and readouts.
- OneMark
- Marker for a single
ToolbarEntry. - Open
File - A native “open file” picker.
.await(or.present().await) resolves to the chosenFileUrl, orNoneif the user cancels. - Open
Files - A native “open files” picker that lets the user choose several files at once.
.await(or.present().await) resolves to the chosenFileUrls in the picker’s order, or an emptyVecif the user cancels. - Open
Folder - A native “choose folder” picker.
.await(or.present().await) resolves to the chosen directory as aFileUrl, orNoneif the user cancels — andNoneat once on a toolkit without a folder chooser, so askCap::FolderDialogbefore offering the command (phones answerUnsupported). - Optional
- A
picker_optional’s selection: a binding toOption<T>. - Pager
State - Pan
- One pan-gesture event, delivered to a
.on_pan(…)handler (docs/shapes.md).deltais the movement since the previous event, so apply it incrementally; a discrete wheel tick arrives as a loneChanged. - Path
Builder - Build a
Shape::Path: several contours, straight or curved, with a fill rule. - PdfDocument
- A PDF of one or more drawings, one per page; each page takes its drawing’s size in PDF points (1/72 inch, the same unit as canvas points: US Letter is 612 × 792, A4 595 × 842).
- Picker
- A native one-of-N selector bound two-way to a typed value (docs/picker.md). Style via
.menu()/.segmented()/.inline(). - Pinch
- One pinch-gesture event, delivered to a
.on_pinch(…)handler (docs/shapes.md).scaleis cumulative sinceBegan(1.0 = unchanged);locationis the centroid, the anchor a zoom keeps stationary. - Progress
- A progress indicator: a determinate bar (from
progress) or an indeterminate spinner (fromspinner). See docs/progress.md. - Prompt
- A single-line text prompt. Resolves to
Some(text)on OK,Noneon cancel/dismiss. - Render
Bitmap - A bitmap render in flight. Resolves with the rendered
Bitmap, or why it could not be. Nothing is asked of the toolkit until the first poll. - Render
Pdf - A PDF render in flight. Resolves with the document’s bytes, or why they could not be produced. Nothing is asked of the toolkit until the first poll.
- Reorder
- Drag-to-reorder for a
list()(docs/list.md): the handler that applies a committed move, an optional guard consulted while the drag is live, and whether the gesture is offered right now. A list is reorderable exactly when it carries one of these (list(..).reorderable(Reorder::new(f))). - Required
- A
picker’s selection: a binding toT. - Resource
Mark - Marker for a
Resource. - Rotate
- One rotation-gesture event, delivered to a
.on_rotate(…)handler (docs/canvas.md “Zoom and pan”). - Route
Path - A typed absolute route: segments built from
Routevalues plus query params.route(&Section::Stack).then(&Drill::Item { id: 42 }).param("hint", "linked")encodes to"stack/item-42?hint=linked";RoutePath::navigateit, or hand it tonav_link_to. - Row
- Rows
- A display projection over a store:
store.rows(move || ordered_keys()). The projection is a tracked read of key ids: read only the fields the order depends on, and a write to any other field cannot re-run it. - Save
File - A native “save file” picker carrying the bytes to write.
.awaitresolves to the chosen destinationFileUrl, orNoneon cancel. - Scroll
- Search
- Search over a navigation surface (docs/search.md), declared with
Nav::searchable:Search::new(query).prompt(res::str::search()).reveal(SearchReveal::OnPull). - Sections
- Collapsible sidebar sections (docs/navigation.md), declared with
Nav::sections. The state is the set of COLLAPSED section ids; missing ids default to expanded, and temporarily filtered-out ids are retained. Pair withNav::section_idfor stable identities; unkeyed headings use their first route as a fallback identity. Takes precedence overNav::reorder_itemsandNav::regroup_items; combined collapse/reordering is not supported. - Segment
- One choice in a
toolbar_segmentedcontrol. - Shape
Piece - A shape piece: one data-oriented piece parameterized by
ShapeKind, rendered atop the canvas. - Share
- A link to share through the system’s share chooser, with the app’s own actions beside the
system’s targets: Safari’s Add Bookmark and Find on Page. Build one with
Share::url, thenpresentit from a user action. - Share
Action - One of the app’s actions in a share chooser (see
Share::action). - Signal
Mark - Slider
- Source
Mark - Marker for an already-converted
TextSource. - Spacer
- Split
- Two panes and the divider between them, bound to the app (docs/split.md).
- Static
Mark - Status
Item - What a status item shows: its icon, text and menu. Built by the closure handed to
status_item, which re-runs whenever a signal it reads changes. - Status
Item Handle - A shown status item. Dropping the handle leaves the item up; call
removeto take it down. - Store
Tree - A hierarchy over a store:
store.tree(children_of)(docs/tree.md). The projection maps a parent key (None= the root) to its ordered child keys, a tracked read, so re-parenting or re-ordering writes re-run it; tokens are the store’s keys. - Store
Tree Conn StoreTree’s connection: the derived shape; values flow through the store’s own per-field notifications, so an unchanged shape skips the native reload entirely.- Swipe
Action - One button in a row’s swipe-action offer (docs/list.md): what the platform reveals as the
user drags a row aside, built by
swipe_action. Holds the label, the styling hints the backend maps onto its own affordance, and the handler the activation runs. - TabActions
- Commands shared by native and application-drawn tab chrome.
- TabSet
- Ordered document identities and the selected document. Own this above the tab host. Payloads (editor buffers, browser profiles, etc.) remain application-owned.
- Text
Area - 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 reactivebool, and updates live). A backend that can’t honor an attribute answers the matchingCap::Text{Editable,Selectable,SpellCheck}withSupport::Unsupported. - Text
Builder - Build a styled paragraph run by run (docs/text-runs.md).
- Text
Field - A single-line text input bound to a
String(docs/textfield.md). - Text
Preset - A named text style an app applies to many labels:
label(t).preset(&CAPTION)forconst CAPTION: TextPreset = TextPreset::new(Font::Caption).secondary();. Every builder isconst, so a preset is a constant, not a runtime value, and it composes the sameLabelBuildersteps a chain would (docs/text.md). - Text
Style - Canvas text styling (named fields per the API style rule, docs/api-style.md). Fill what you
set and take the rest from
..Default::default(): 12 points, black, top-leading, the platform’s own face. - Toggle
- Toolbar
Entry - A toolbar item under construction. Build a command with
toolbar_button, a two-state button withtoolbar_toggle, a pull-down withtoolbar_menu, one control over a set of choices withtoolbar_segmented, static text withtoolbar_label, and a divider withtoolbar_separator. Search is declared on the navigation surface instead (Nav::searchable, docs/search.md). - Tree
Piece - Vector
- A bundled vector glyph, resolved by name through whatever form the backend loads natively
(§18.3: a
VectorDrawableon Android, a catalog entry on Apple, an SVG on the web, a build-rasterized PNG where the toolkit has no vector path). Distinct fromimage()on purpose: only a typedVectorNameis accepted, and the modifiers are the vector-appropriate ones:tintrecolors 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). - When
- A conditional subtree, optionally with an else arm. Built by
when. - 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; contrastDecorate::overlay, which sizes to its content and treats the overlaid piece as a non-sizing annotation. Pure composition: it is the same native panel ascolumn()/row(), so there is no per-backend work.
Enums§
- Back
Response - What a
NavStack::on_backguard returns for one back-like event (a native back gesture/button, ornav_back). Programmatic path writes are not guarded; the guard is a policy on the user’s back affordance, matching Jetpack Compose’sBackHandler(docs/navigation.md). - Context
Menu Source - Where a context menu’s entries come from (see
Decorate::context_menu). - Corner
- A corner radius: absolute points, or a 0..1 fraction of
min(width, height). - Dimension
#[day_pieces::builder(FooBuilder)]: a piece’s builder trait, generated from its inherent impl (docs/api-style.md “Typed builders and erasure”). Dimensions in which a piece expands to fill the space offered by its parent. UnlikeAxis, this can select both width and height.- Drag
Phase - The phase of a drag gesture (docs/shapes.md).
- Fraction
Source - Gesture
Kind - 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
- Menu
Source - Where a menu’s entries come from: a fixed list, or a closure that derives the list and
re-runs whenever its reactive reads change. What
app_menu,dock_menuandStatusItem::menuaccept, throughMenuContent. - Move
Verdict - A tree move guard’s verdict (docs/tree.md). No
Retargetyet: the drop vocabulary is already positional, so a guard that wants a different target denies and the user drops where it is allowed. - NavDrag
- How a sidebar row drags under
Nav::regroup_items. - NavStyle
- How a
navpresents its one-of-N choice (docs/navigation.md). - Picker
Options - The options of a
picker:(value, title)pairs, fixed or derived. - Reactive
- A parameter that is either a constant or a reactive source.
get()is a tracked read, so anyReactiveused inside a canvas draw closure makes that shape re-record when the source changes. - Reorder
Verdict - 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.
- RowFit
- How a
rowtreats content wider than the window it is in (docs/size-classes.md “Row fit policies”). - Search
Reveal - How a navigation surface’s search field comes and goes on a phone (docs/search.md). The desktop toolbar field is always there whatever this says.
- Shape
Kind - A shape’s geometry, resolved against the rect layout assigns it (frame-relative, SwiftUI-style).
- Space
- A semantic spacing step, accepted wherever a container or modifier takes a gap or an inset
in points:
column(..).spacing(Space::S),.padding(Space::M); anInsetsconstructor takesSpace::L.points(). - Text
Source - Toolbar
Source - Where a contribution’s items come from: a fixed list, or a closure re-run on every change.
- VAlign
- Vector
Weight - A vector glyph’s stroke weight (docs/vectors.md). Template-form sources (SF template SVGs,
.symbolsetbundles) 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.
Constants§
- INSPECTOR_
WIDTH - The pane’s default width in points; Keynote-class inspectors sit in the 250–300 range.
- SEARCH_
ITEM_ ID - The toolbar item id a
.searchable()surface’s field carries when its placement resolves to the window toolbar (docs/search.md). Reserved and stable: dayscript’stoolbar:step addresses the field by this id, and it is Day’s own rather than the app’s, since the app never declares the item. - SPLIT_
MIN_ PANE - The least length either pane may be dragged to, in points (default).
Traits§
- Adaptive
Builder - Builder methods of
Adaptive, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - Ambient
- State an ancestor provides once and any descendant reads back by type: SwiftUI’s
@EnvironmentObject, and Day’s answer to “where does app state live?” (docs/state.md). - Binding
- A readable-writable value a control can bind to two-way: a
Signal, or any projection that knows how to read and write its own slot (day-model’sFieldis the other implementor). - Button
Builder - Builder methods of
Button, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - Column
Builder - Builder methods of
Column, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - Context
Menu Content - Anything
Decorate::context_menuaccepts: aVecor array of entries, a closure building them on summon, or a closure given the summon point. The marker parameter is the same E0119 dodge asIntoText. - Cover
Builder - Builder methods of
Cover, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - Decorate
- Divider
Builder - Builder methods of
Divider, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - Form
Section Builder - Builder methods of
FormSection, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - Grid
Builder - Builder methods of
Grid, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - Grid
RowBuilder - Builder methods of
GridRow, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - Image
Builder - Builder methods of
Image, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - Inspector
Builder - Builder methods of
Inspector, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - Into
Element Key #[day_pieces::builder(FooBuilder)]: a piece’s builder trait, generated from its inherent impl (docs/api-style.md “Typed builders and erasure”). Explicit, stable canonical text for an instance key. No blanket Display conversion. Integer 42 and text “42” intentionally denote the same key. Composite keys must define an unambiguous app-owned encoding before the framework percent-escapes it.- Into
Focus Binding - A focus-binding target for
Decorate::focused(docs/focus.md): either aSignal<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 asIntoText. - Into
Fraction - Disjoint-marker conversion (like
IntoText) soprogress(_)accepts a constantf64, aSignal<f64>, or a closure. Reuses the same marker types. - Into
Image Source - Disjoint-marker conversion into an image source (the same shape as
IntoText, and for the same coherence reason): a staged name, a byte buffer, a decodedBitmap, aSignal, or a closure all convert, each under its own marker. - Into
Insets - Into
Picker Options - Anything
pickertakes as its options: an array orVecof(value, title)pairs, or a closure that derives the list and re-runs whenever its reactive reads change. Titles take the same sources as a label. The two-level marker is the same E0119 dodge asIntoText. - Into
Reactive - Disjoint-marker conversion (like
IntoText): acceptsT,Signal<T>, orFn() -> T. - Into
Text - Disjoint-marker conversion (the coherent form of §12.2’s IntoText):
literals,
String,Signal<String>, and closures all convert, each under its own marker. - Label
Builder - Builder methods of
Label, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - Link
Builder - Builder methods of
Link, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - List
Builder - Builder methods of
List, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - List
Item Builder - Builder methods of
ListItem, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - Load
Source - Where a
loadreads its state: aResource, aSignal<Load<T>>, or a closure. The marker is the same E0119 dodge asIntoText. - Menu
Button Builder - Builder methods of
MenuButton, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - Menu
Content - Anything an app menu takes: a
Vecor array of entries, or a closure that derives the entries and re-runs whenever its reactive reads change. The marker parameter is the same E0119 dodge asToolbarContent. - Modifier
- A one-shot, by-value view transform (the SwiftUI
ViewModifieranalog): wrap a piece into a new one. Pure composition, with no per-backend work. A plainFnOnce(AnyPiece) -> AnyPiececlosure is aModifiertoo (the blanket impl below), so the common case needs no new type. Apply one withDecorate::modifier. - NavBuilder
- Builder methods of
Nav, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - NavContent
- What a
Nav::itemsorNav::sectionblock takes: oneNavItem, a tuple of them, anOption(an item the platform may not want:prefs.nav_item(key)), aVecor array, or a data-drivennav_itemsblock. Any mix nests:(item(..), nav_items(..), Some(item(..))). - NavStack
Builder - Builder methods of
NavStack, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - Node
Source - A hierarchical row source for
tree: theRowSourceidea grown a parent per row. Two implementations:branches(plain data) and a day-model store’sstore.tree(children_of)(featuremodel). - Picker
Builder - Builder methods of
Picker, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - Picker
Selection - How a picker reads and writes its selection: a required value (
picker) or an optional one (picker_optional). Implemented by the two adapters below, never by apps. - Progress
Builder - Builder methods of
Progress, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - Route
- A typed route key, the compile-checked alternative to raw string keys.
- RowBuilder
- Builder methods of
Row, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - RowConn
- One collection’s live connection to its data, held for the life of the
each/listthatRowSource::connected it. - RowSource
- Where a collection’s rows come from.
each(source, row)andlist()(source, row)accept anything implementing this: plain data viaitems(closure, key_of), or (with themodelfeature) a day-model store directly (collection order) orstore.rows(projection)(a tracked display projection of key ids). - Scroll
Builder - Builder methods of
Scroll, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - Selection
Key - A row reference that names its row by a key: what
List::selectionbinds. A day-model store’s rows (anElem) answer their key, which is also the row’s identity token. - Shape
Piece Builder - Builder methods of
ShapePiece, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - Slider
Builder - Builder methods of
Slider, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - Split
Builder - Builder methods of
Split, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - Store
Rows store.rows(projection): the display-ordered row source forlist()/each.- Store
Trees store.tree(children_of): the hierarchical source forsuper::tree.- Text
Area Builder - Builder methods of
TextArea, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - Text
Field Builder - Builder methods of
TextField, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - Toggle
Builder - Builder methods of
Toggle, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - Toolbar
Content - Anything
crate::Decorate::toolbaraccepts: one entry, a list of them, or a closure that derives the list and re-runs whenever its reactive reads change. - Tree
Builder - Builder methods of
TreePiece, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - Tree
Conn - One tree’s live connection to its data, held for the life of the
treethat connected it. All hierarchy queries are TOKEN-addressed (docs/tree.md):None= the root level. - Vector
Builder - Builder methods of
Vector, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - When
Builder - Builder methods of
When, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order. - ZStack
Builder - Builder methods of
ZStack, reachable through aDecorated(docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Functions§
- adaptive
- A stack that is a row on a regular width and a column on a compact one, re-laid out (never rebuilt) as the window crosses the breakpoint, so its children keep their state. The shape a label-plus-control-plus-result line wants, where wrapping members independently would tear apart what reads as one sentence.
- alert
- app_
environment - The app-wide
T: created on the reactive root scope the first time it is asked for, and returned unchanged by every later call (docs/state.md). - app_
menu - Install the application menu: the native menu bar on desktop, the app-bar overflow on Android,
the
UIMenuBuildermain menu on iPadOS/Catalyst. Top-level entries are usuallysub_menu(…)s (the menu-bar menus). Takes a list of entries or a closure that derives them. - arc
- branches
- Plain-data tree rows: a flat items closure, a key per item, and a parent key per item
(
None= a root row), as intree(branches(model::all, |n| n.id, |n| n.parent), row_view). Children keep the items’ own relative order; an item whose parent key is absent from the set is treated as a root row rather than dropped. - button
- canvas
- The drawing closure is a binding: signal reads re-record; layout size changes re-record
(via
FrameChanged); replay is equality-gated byDrawOp’sPartialEq(§4.2). - canvas_
exports - What this toolkit can export a canvas drawing to.
- capsule
- circle
- column
- confirm
- contribute
- Register
contentagainstchromefor as long as the current reactive scope lives. - cover
- A fullscreen cover over
open:Some(r)presentsbuild(&r),Nonedismisses (docs/cover.md). Registers a string-route adapter, sonavigate("<key>")opens it andnav_back()closes it, andcurrent_route()reports the presented key. - current_
route - The full current route: every mounted surface’s contribution, outermost to innermost,
/-joined. Round-trips throughnavigate: persist it on exit,navigate(&saved)on launch (docs/navigation.md). - divider
- dock_
menu - Install the app’s Dock menu (docs/menus.md “Dock menu”): the entries macOS lists when the
user right-clicks the app’s Dock icon, above the app’s
[[shortcuts]]and the system’s own Show / Hide / Quit items. ProbeCap::DockMenu; elsewhere the call does nothing. Live, likeapp_menu:Resume <last document>, a checked “Do Not Disturb”, the locale. Install once, at startup. - document_
tabs - Labels are required rather than supplying untranslated English chrome.
- each
- Reactive keyed collection (§5.4): keyed diff, per-key child scopes, slot rebinds for
surviving rows, debug key-uniqueness assertion. Takes any
RowSource. - ellipse
- environment
- Read the nearest ambient
Tprovided by an enclosingwith_environment, orNoneif none is in scope. Call it while constructing or building a piece within that subtree. - focused_
environment - The ambient
Tof the window that currently has focus (docs/state.md): SwiftUI’s@FocusedValue. - form
- A settings-style form: a vertical run of
sections whoselabeledrows share one label column across the whole form. - frame_
clock - A frame clock (§8.4): an invisible, zero-size piece that calls
tickevery 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 acanvasin azstack) to drive a game loop or self-driven animation: the tick mutates stateSignals, and acanvasreading them re-records that frame. - grid
- A SwiftUI-style eager grid (docs/grid.md): columns are inferred from
grid_rowchildren. A column is as wide as its widest cell, agrow_wcell 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 withDecorated::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 plainrow. Rows are transparent carriers (the grid places their cells directly), so decorating agrid_rowitself is unsupported (decorate the cells, or the grid). - guarded_
page - A case’s page, built with a panic caught and recorded rather than taking the app down. Also what a browsing view of the cases shows (the conformance app’s navigation).
- image
- Draw an image from any
ImageSource: a staged asset name, encoded bytes, or a decodedBitmap. - inspector
- Build an
Inspector:contentbeside a trailing panel toggled byvisible. - item
- A nav item:
item("today", res::str::today()).icon(res::images::today).page(today_page)(docs/navigation.md). Goes into aNav::itemsorNav::sectionblock, alone, in a tuple, or from anav_itemsmapper; an item without apageis built by the nav’sNav::destination. For a typed nav overOption<Section>pass the bareSection::X. - items
- Plain-data rows: an items closure plus a key function, as in
list(items(model::ordered, |i: &Item| i.id), row_view). - keyed
- A subtree keyed by a value: rebuilt when the key changes, left alone while it does not
(so focus and local state survive), nothing while it is
None. - label
- labeled
- A form row:
labelsits in the form-wide aligned label column (right-aligned, vertically centered),controlbeside it. Outside aformthe label column is just this row’s own label width. A control with.grow(Dimension::Both)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
Linkthat activatesurlthroughopen_linkwhen tapped. - list
- Build a recycling list from a
RowSourceand a row builder:list(items(rows_fn, key_of), row_view)for plain data,list(store, row_view)(orlist(store.rows(projection), …)) for a day-model store. - list_
item - A list row’s standard content: a leading icon, a title, an optional subtitle and trailing detail, and a check mark, drawn the way the platform draws its own list rows (docs/list.md “List items”). UIKit shows it with the cell’s default content configuration, Android as a Material list item, AppKit as a table cell’s image and text, GTK as a row box; elsewhere the piece composes the same parts. Each part may follow a signal, and changes in place, so a recycled row tracks its item.
- load
- The three states of an async load as three subtrees (docs/async.md): the ready arm, and
optional
loadingandfailedarms (nothing is built for a state without an arm). Arms rebuild only when the variant changes; a new ready value updates the ready arm in place throughLoaded::get. - menu_
button - A button that opens
entriesas a menu when pressed (docs/menus.md “Menu buttons”). - menu_
item - A clickable command:
menu_item(res::str::save()).key("s").action(|| …). The title takes the same sources as a label (a literal, a localized text, a signal, a closure) and stays live. - 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
- nav_
back - Pop one navigation level. False = nothing to pop.
- nav_
items - A data-driven item block:
nav_items(move || st.feeds.get(), |f| item(f.id, f.name).icon(…))(docs/navigation.md).itemsis a tracked reader (aSignal<Vec<T>>via itsFn()deref, or a closure); the block re-derives whenever it changes: rows are added and removed on the native sidebar/tab widget, and if the selected key disappears the selection resets (toNonefor anOptionkey). Static items and blocks may be mixed; the final list is their declaration order. A row without its ownpageis built by the nav’sNav::destination. - nav_
link - A tappable link that navigates to
pathwhen pressed. - nav_
link_ to - A tappable link that navigates to a typed
RoutePathwhen pressed. - nav_
stack - 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 aroute. - open_
file - Start a native open-file picker (docs/files.md).
- open_
files - Start a native multi-file open picker (docs/files.md).
- open_
folder - Start a native folder chooser (docs/files.md).
- open_
link - Activate a link target, using the same policy as
linkand markdown labels. - picker
picker(sort, [(Sort::Name, res::str::name()), (Sort::Date, res::str::date())]).segmented():selectedis a two-way binding to the chosen value (aSignal<T>, a day-modelField, aMappedview), and the options are(value, title)pairs, fixed or derived from a closure. The mapping between values and the native control’s indexes lives here, once.- picker_
optional pickerover an optional value:Noneis “nothing chosen” (no selection where the toolkit can show none), and a user’s choice writesSome(value).- 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.
fractionis the completed portion in0.0..=1.0; pass a constant, aSignal<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
RoutePathat 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 aform(shared label column) or standalone. - secure_
field - A password field: a
text_fieldthat hides its characters and tells the platform it holds a password, so the password manager offers to fill it (docs/textfield.md). - segment
- A segment showing
label; add.icon(…)for the platforms that draw one. - 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, so put
.on_tapon the group viaDecorate. - shape_
group_ fn - Size-aware
shape_group: the closure derives the shapes from the laid-out size and re-runs onFrameChanged, exactly likecanvas, for geometry that depends on the final size (e.g. data mapped along the width). - share_
action - Build a share-chooser action named
label(a literal or ares::str::…text, resolved when the chooser opens). Chainsymbolfor its glyph andactionfor the work, which runs once the chooser has closed. - share_
support - Whether this target can present a share chooser at all (docs/sharing.md).
- sidebar_
toggle_ item - The item a sidebar host draws for itself: leading, the platform’s glyph, and no app action, since the click drives that window’s split directly.
- slider
- spacer
- spinner
- An indeterminate, animated progress indicator (a spinner / busy bar) for work with no known extent.
- split
- Build a
Split:firstbeside (or above)second, divided at half until dragged. - status_
item - Show a status item (docs/status-item.md): an icon in the macOS menu bar, the Windows
notification area, or a Linux tray.
buildruns now and again whenever a signal it reads changes, so a timer’s title or a “Pause sync” check mark follows the app’s state.idnames the item; showing a second item with the same id replaces the first. - sub_
menu - A nested submenu:
sub_menu(res::str::menu_file(), vec![menu_item(…), …]). - swipe_
action - Build a swipe action with
label(a literal, ares::str::…text, a signal or a closure; resolved in the current locale each time the offer is pulled). Chaindestructiveortintfor styling andactionfor the work; an action without a handler still reveals and dismisses, but does nothing. - switch
- One tracked read, one arm (docs/state.md): a subtree per value of
selector, rebuilt when the value changes. The arm closure usually matches, so its arms erase with.any(): - test_
host - The root of an app’s test build:
contentnormally, and whileday testdrives a GUI case, that case’s page alone, built fresh for the case and disposed when the next one starts. One page mounted at a time is what keeps one case’s ids, signals and resident native views out of the next one’s way. - text_
area text_area(text): a native multi-line editor whose contents mirrortextin both directions;textis aSignal<String>or any other two-way binding (a day-modelField).- text_
field - toggle
- toolbar_
button - A push button:
toolbar_button(day_core::id!(refresh), tr("refresh")).icon(Symbol::Refresh).action(…). - 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_menutakes. - toolbar_
segmented - A row of mutually exclusive choices as one native control (docs/toolbars.md): the platform’s
segmented control, bound to
selected. - toolbar_
separator - A divider, where the platform draws one (macOS toolbars have none, so AppKit renders it as a fixed gap; docs/toolbars.md). It takes an id like every other item: an id is an item’s identity on the bar, which is what lets Day add and remove one item at a time.
- toolbar_
toggle - A two-state button bound to
on(aSignal<bool>or any other binding): the user flipping it writes the binding, and writing the binding restyles the button. - tree
- Build a hierarchical tree from a
NodeSourceand a row builder:tree(branches(items_fn, key_of, parent_of), row_view)for plain data,tree(store.tree(children_of), row_view)for a day-model store. - 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
Ttocontentand 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 withenvironment. A thin, non-reactive wrapper:Tis a snapshot captured here; for a value that must react, provide aSignal<T>(or aMemo<T>) and read it reactively inside the subtree. - zstack
- Build a
ZStackfrom a tuple,Vecor array of children.
Attribute Macros§
- builder
- A piece’s builder trait, generated from the inherent
implthat holds its builder methods (docs/api-style.md “Typed builders and erasure”).