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.
Logging (docs/logging.md). day::info!("…") and friends are the log crate’s macros,
re-exported so an app needs no log dependency of its own for the common case. Because they
are log’s, anything that speaks log (env_logger, tracing-log, a hand-written
log::Log) works without adapters.
Logging (docs/logging.md). day::info!("…") and friends are the log crate’s macros,
re-exported so an app needs no log dependency of its own for the common case. Because they
are log’s, anything that speaks log (env_logger, tracing-log, a hand-written
log::Log) works without adapters.
Logging (docs/logging.md). day::info!("…") and friends are the log crate’s macros,
re-exported so an app needs no log dependency of its own for the common case. Because they
are log’s, anything that speaks log (env_logger, tracing-log, a hand-written
log::Log) works without adapters.
Logging (docs/logging.md). day::info!("…") and friends are the log crate’s macros,
re-exported so an app needs no log dependency of its own for the common case. Because they
are log’s, anything that speaks log (env_logger, tracing-log, a hand-written
log::Log) works without adapters.
Logging (docs/logging.md). day::info!("…") and friends are the log crate’s macros,
re-exported so an app needs no log dependency of its own for the common case. Because they
are log’s, anything that speaks log (env_logger, tracing-log, a hand-written
log::Log) works without adapters.
Logging (docs/logging.md). day::info!("…") and friends are the log crate’s macros,
re-exported so an app needs no log dependency of its own for the common case. Because they
are log’s, anything that speaks log (env_logger, tracing-log, a hand-written
log::Log) works without adapters.
The annotations .a11y(|a| …) collects (docs/accessibility.md). The three strings are
TextSources, so each takes a literal, a String, a Signal<String> or a closure: a
gauge’s value follows the gauge, and a localized label follows the locale.
A 2-D affine transform (CoreGraphics row-vector convention): a point p maps to
(a·p.x + c·p.y + tx, b·p.x + d·p.y + ty). Used by canvas transform ops for shape
rotate/scale/offset; every native 2-D context concatenates it onto its CTM identically.
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.
Animation intent (§8.4). Native-widget backends map it onto their own animator (Core Animation,
ViewPropertyAnimator, XAML Composition, OH_ArkUI_AnimateTo, …); the canvas/self-driven path
samples curve via Curve::fraction. Threaded through Toolkit::update/set_frame/
set_opacity/set_transform.
Animation intent (§8.4). Native-widget backends map it onto their own animator (Core Animation,
ViewPropertyAnimator, XAML Composition, OH_ArkUI_AnimateTo, …); the canvas/self-driven path
samples curve via Curve::fraction. Threaded through Toolkit::update/set_frame/
set_opacity/set_transform.
A type-erased Binding: what a piece stores when its builder takes impl Binding<T>
(docs/api-style.md “Three input spellings”), so the piece itself needs no type parameter
per bound value.
A bundled-asset directory (§18.5): a folder’s path relative to resource/assets/,
/-separated, no trailing slash. The generated res::assets::… tree carries one
constant per folder, sharing its module’s name: res::assets::web::minisite is the
AssetDir and res::assets::web::minisite::index_html a file within it.
The bundled-data name that resource resolves by: the file’s path relative to
resource/assets/, /-separated (a top-level file is just its file name, extension
included).
The deferred pop handed to a NavStack::on_back guard. Hold it, then call proceed to
perform the back the guard consumed (the unsaved-changes → confirm → leave flow).
What canvas text is drawn with beyond its size (docs/canvas.md “Text”): a family, a weight and
a slant. The default is the platform’s own UI face, regular, upright, which is what every
backend drew before the field existed, so a default font encodes to nothing on the wire.
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_item and
toolbar_item.
The content-list pane of a Mail-shaped nav (docs/navigation.md), declared with
Nav::content_list: mailboxes, message list, message. build makes 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.
A radius for each corner of a rectangle, clockwise from the top left (docs/canvas.md “Rounded
corners”). The shape a bar in a chart wants (rounded at its value end, square against its
axis), a tab (rounded on top), or a card joined to its neighbor.
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))).
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.
A set of screen edges, for the defers_system_gestures modifier (docs/cover.md). Mirrors
SwiftUI’s Edge.Set: on iOS these map to UIRectEdge for
preferredScreenEdgesDeferringSystemGestures; on Android any non-empty set enters
swipe-to-reveal immersive mode (the closest platform analogue).
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.
One face a font family ships (docs/fonts.md): its display name (“Bold Italic”), weight and
slant. What FontFamilyInfo::faces lists and what a font menu’s style picker offers.
The family name of a bundled custom font, feeding Font::custom. Holds a &'static str (so
Font stays Copy); generated res::fonts::… constants supply it. The untyped
Font::Custom(&'static str, f64) variant remains the escape hatch for a family known another way.
The full font descriptor a label carries: a semantic (or custom) Font style plus an optional
weight override, an italic flag, and the tabular-figures request. Backends resolve this to one
native font.
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, 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.
A keyed collection that keeps its own key→index map, so an element read is O(1) rather than
a scan, and no caller can forget to maintain the map, because the collection does it.
A linear gradient (docs/shapes.md §3.2 / §7): color stops along the line from start to
end, both in the unit space of the filled shape’s bounding box. Stops are
(offset 0..=1, color), ascending.
A tappable run of text that navigates to a #route or opens a URL in the platform’s default
handler: the system browser for http/https, the mail client for mailto:, and so on.
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 with each, so migrating a collection between them is a one-word change.
The loaded value, handed to a load’s ready arm: get() is a tracked read that follows
Ready(a) to Ready(b) in place, without rebuilding the arm. Copy, like a signal.
A typed, opaque id for one M row: Copy, 8 bytes, cheap to pass and compare. It wraps
the key’s path handle: Store::elem, query results, list slots and destinations all
speak it, and a wrong-model id is a compile error rather than a wrong row. ModelId::key
recovers the real key for display, deep links, or the persistence edge.
One recycled row’s connection to its store: the slot a model list’s row builder
receives. Copy, and a day-model Source, 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.
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
on Cap::Tree: a backend without tree support renders nothing.
Drag-to-move for a tree (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))). The list() counterpart is Reorder.
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.
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))).
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).
A native “open files” picker that lets the user choose several files at once. .await
(or .present().await) resolves to the chosen FileUrls in the picker’s order, or an
empty Vec if the user cancels.
A native “choose folder” picker. .await (or .present().await) resolves to the chosen
directory as a FileUrl, or None if the user cancels — and None at once on a toolkit
without a folder chooser, so ask Cap::FolderDialog before
offering the command (phones answer Unsupported).
One pan-gesture event, delivered to a .on_pan(…) handler (docs/shapes.md). delta is
the movement since the previous event, so apply it incrementally; a discrete wheel tick
arrives as a lone Changed.
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).
One pinch-gesture event, delivered to a .on_pinch(…) handler (docs/shapes.md). scale
is cumulative since Began (1.0 = unchanged); location is the centroid, the anchor a
zoom keeps stationary.
A radial gradient (docs/shapes.md §3.2 / §7): color stops from center outward. Both the
center and the radius live in the unit space of the filled shape’s bounding box, so the
gradient stretches into an ellipse when the bounds aren’t square (the XAML relative-brush
behavior; the other backends reproduce it with a local matrix on a circular gradient). A
radius of 0.5 from the default center touches the edge midpoints of the bounds.
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))).
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.
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.
A TextRun’s attributes with no range attached: what a toolbar toggles, what an editor
applies to a selection, and what it styles the next typed character with.
Search over a navigation surface (docs/search.md), declared with Nav::searchable:
Search::new(query).prompt(res::str::search()).reveal(SearchReveal::OnPull).
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 with Nav::section_id for stable identities; unkeyed
headings use their first route as a fallback identity. Takes precedence over
Nav::reorder_items; combined collapse/reordering is not supported.
A keyboard shortcut for a menu item. primary is the platform’s command modifier (⌘ on Apple,
Ctrl on GTK/Qt/XAML) so one declaration reads correctly everywhere. key is a single character
("s", ".") or a named key ("Return", "Delete", "Left", "F1").
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.
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.
Ordered document identities and the selected document. Own this above the tab host.
Payloads (editor buffers, browser profiles, etc.) remain application-owned.
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.
A named text style an app applies to many labels: label(t).preset(&CAPTION) for
const CAPTION: TextPreset = TextPreset::new(Font::Caption).secondary();. Every builder is
const, so a preset is a constant, not a runtime value, and it composes the same
LabelBuilder steps a chain would (docs/text.md).
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.
A toolbar item under construction. Build a command with toolbar_button, a two-state
button with toolbar_toggle, a pull-down with toolbar_menu, one control over a set of
choices with toolbar_segmented, static text with toolbar_label, and a divider with
toolbar_separator. Search is declared on the navigation surface instead
(Nav::searchable, docs/search.md).
A cheap per-node visual transform (§8.4 animation): translation, uniform/non-uniform scale, and
rotation about a unit anchor (0.0..1.0 within the node’s bounds; default center). Distinct
from the layout frame: animating a Transform never triggers relayout, so it is the vehicle
for movement/scaling animation. Each backend composes it onto the node’s laid-out frame via its
native transform channel (CALayer/GskTransform/RenderTransform/NODE_TRANSFORM/…).
A point in the unit space of a shape’s bounding box: (0,0) = top-leading, (1,1) =
bottom-trailing. Gradient geometry is expressed in unit points so one paint value works for
any shape size (docs/shapes.md §3.2).
The bundled-vector name that resource() callers resolve by (docs/vectors.md):
the stem of a resource/vectors/ SVG (or .symbolset bundle). Vectors and images share one
per-backend resolution namespace; staging guarantees every vector name resolves as whatever
form that backend loads natively (a VectorDrawable, a catalog entry, a rasterized PNG).
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.
Two-axis placement of a child within a container’s bounds (SwiftUI’s Alignment). Used by
the z-layering primitives (OverlayLayout): zstack, overlay/overlay_aligned.
What a NavStack::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).
The timing curve of an animation (§8.4). Native backends map each variant onto their own
easing (CAMediaTimingFunction, QEasingCurve, ArkUI ARKUI_CURVE_*, spring animators); the
canvas/self-driven path samples it via Curve::fraction. Spring matches SwiftUI’s
.spring(response:dampingFraction:).
A semantic (logical) text style. Each maps to the platform’s native text style where the
toolkit has one: UIFont/NSFont.preferredFont(forTextStyle:) on Apple (Dynamic Type), the
*TextBlockStyle resources on XAML. A Day app thus matches the OS’s own typography and
inherits its accessibility text scaling with no extra work. Backends without semantic styles
(GTK/Qt/Android) approximate with sizes that still track the platform’s text-scale /
font-scale accessibility setting.
Font weight, matching UIFont.Weight / SwiftUI Font.Weight (lightest → heaviest).
Ordered by heaviness, so backends can e.g. map >= Semibold to a synthesized bold face.
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).
How tall a window is (docs/size-classes.md). Consulted far less than WidthClass: it is
what tells a phone in landscape (wide enough for two panes, too short for a tall list) that
it should not grow vertical chrome.
An app-lifecycle phase (docs/lifecycle.md). Each backend maps these onto its OS’s native app /
activity delegate. Some phases only exist on some platforms (a mobile app enters the
background and can be low on memory, a desktop app cannot), so Lifecycle::is_universal
marks the ones every backend delivers, and Toolkit::supports_lifecycle reports per-backend
truth.
A standard menu-bar slot (macOS’s File/Edit/View/Window/Help, and their counterparts
elsewhere). A backend that has a house style for the menu bar fills every slot an app did
not claim with its own stock menu, so an app never has to restate the platform’s furniture,
and can still replace any of it by tagging its own submenu with the matching role.
A standard/system command. The backend supplies the native item, a selector on AppKit/UIKit
(cut:/copy:/paste:…) or a stock action on GTK/Qt/XAML, so it targets the focused
control, gets the platform’s default label + shortcut, and enables/disables itself
automatically. This is how default items (Edit ▸ Cut/Copy/Paste, the app’s Quit/About) are
accommodated without the app re-implementing them.
A tree move guard’s verdict (docs/tree.md). No Retarget yet: the drop vocabulary is
already positional, so a guard that wants a different target denies and the user drops
where it is allowed.
A fill source: a solid color, or a linear/radial gradient (docs/shapes.md §3.2; angular and
semantic tokens are later phases). From<Color> keeps every existing fill(shape, color)
call site compiling unchanged.
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.
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.
A programmatic scroll destination (§7.6, docs/scroll.md). Edges are axis extremes
(Top/Bottom vertical, Leading/Trailing horizontal, i.e. start/end in layout direction);
Offset pins the viewport origin to a content-space point (clamped by the platform);
Id reveals the element with that dayscript id inside its nearest enclosing scroll.
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); an Insets constructor
takes Space::L.points().
How a kinds::SPLIT lays its two panes (docs/split.md): beside each other, the divider
standing, or stacked, the divider lying. Named by where the panes go, since that is
what an app’s “layout” toggle means; the divider runs the other way.
A standard icon, named by what it means rather than by how it looks, so each backend can
draw the platform’s own glyph for it: an SF Symbol on macOS, a freedesktop icon name on
GTK and Qt, a Fluent glyph on Windows. This is the only way an icon looks native on every
desktop at once; a bundled PNG cannot, because it is one artist’s take on all four.
Where at sits vertically. Top, Middle and Bottom are edges of the line box (ascent +
descent at the font’s size, the box Toolkit::measure_text reports); Baseline is the
typographic baseline itself.
What a toolbar item is. The variants are the vocabulary every desktop toolbar shares; each
backend realizes one with its native control, never with a drawn imitation.
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.
Builder methods of Adaptive, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
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).
Linear interpolation of animatable values (t in 0.0..1.0). This drives the canvas /
self-driven animation path (docs/shapes.md §5) and Qt’s sampled spring; native-widget
animation does not use it; the toolkit interpolates on its own compositor.
Builder methods of AsyncImage, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
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’s Field is the other implementor).
Builder methods of Button, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of ColorPicker, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of Column, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of ComboBox, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of Cover, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of DatePicker, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of Divider, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of FormSection, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of Grid, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of GridRow, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of Image, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of Inspector, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
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.
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.
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 decoded Bitmap, a Signal, or a closure all convert, each
under its own marker.
Disjoint-marker conversion (the coherent form of §12.2’s IntoText):
literals, String, Signal<String>, and closures all convert, each under its own marker.
Builder methods of Label, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of Link, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of List, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of ListItem, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Anything an app menu takes: a Vec or 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 as ToolbarContent.
A one-shot, by-value view transform (the SwiftUI ViewModifier analog): wrap a piece into a
new one. Pure composition, with 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.
Builder methods of Nav, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
What a Nav::items or Nav::section block takes: one NavItem, a tuple of them, an
Option (an item the platform may not want: prefs.nav_item(key)), a Vec or array, or a
data-driven nav_items block. Any mix nests: (item(..), nav_items(..), Some(item(..))).
Builder methods of NavStack, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
A hierarchical row source for tree: the RowSource idea grown a parent per row.
Two implementations: branches (plain data) and a day-model store’s
store.tree(children_of) (feature model).
Builder methods of Picker, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Children of a container (§5.1): a tuple of pieces (the floem ViewTuple pattern), a
Vec or array of one piece type, or an Option of a piece. Implemented for exactly those
shapes, never via a blanket, to stay coherent. All of them are build-time children:
evaluated once when the parent builds, with no keyed identity or reconciliation. A child
that must come and go at runtime is a when, a
keyed, or an each.
Builder methods of Progress, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of PullRefresh, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of Row, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of Scroll, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of SearchField, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of ShapePiece, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of Slider, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of Split, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of TextArea, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of TextEditor, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of TextField, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of DatePicker, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of Toggle, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of TreePiece, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
One tree’s live connection to its data, held for the life of the tree that connected
it. All hierarchy queries are TOKEN-addressed (docs/tree.md): None = the root level.
Builder methods of Vector, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of When, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
Builder methods of ZStack, reachable through a Decorated (docs/api-style.md “Typed builders and erasure”): generic modifiers and typed ones chain in any order.
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.
Speak text through the screen reader without moving its focus (docs/accessibility.md):
the outcome of an action the user cannot otherwise learn about (“Saved”, “3 results”). The
sentence waits for whatever is being read to finish; announce_urgent interrupts it.
Nothing happens when no screen reader is running, and nothing happens on a toolkit that
answers Cap::Announce with Unsupported.
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). Takes a list of entries or a closure that derives them.
An app-writable scratch directory: the backend-supplied one, else std::env::temp_dir().
Used by the file-save flow (docs/files.md) to stage bytes before the native save picker.
Decode each source asynchronously. A replacement cancels the previous decode; disposal
cancels the pending task. A failed replacement clears the previous picture.
The binding primitive (§4.2): compute (tracked) + apply (untracked), equality-gated.
Structural priority: bindings drain before plain effects. apply receives the new value
by reference so V needs only PartialEq (no Clone).
Plain-data tree rows: a flat items closure, a key per item, and a parent key per item
(None = a root row), as in tree(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.
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).
Query the active toolkit’s support for a capability (docs). Lets app/piece code adapt its
content to the backend, e.g. a page can skip a title the native nav already shows in a header
(Cap::NavHeader), or pick a presentation from Cap::NavSplit.
color_picker(color) is a swatch showing color that opens a color chooser. color is a
Signal<Color> or any other two-way binding (a day-model Field, mapped).
combo_box(items, text): free-form text entry plus a native dropdown of suggestions.
Typing (or picking an item) writes text; setting either signal patches the control.
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.
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).
date_picker(date): a field summoning the platform’s chooser; .inline() embeds it.
date is a Signal<DayDate> or any other two-way binding (a day-model Field, mapped).
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. Probe Cap::DockMenu; elsewhere the call does nothing. Live, like
app_menu: Resume <last document>, a checked “Do Not Disturb”, the locale. Install
once, at startup.
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.
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.
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 Decorated::grid_span / Decorate::grid_align.
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).
Register the app’s locales (see day_l10n::install) and fix the layout direction from the
locale that actually resolved (docs/localization): an RTL locale (Arabic, Hebrew, …) mirrors
every horizontal placement and flips the native toolkit’s direction. Direction is resolved
once, before the first layout; runtime set_locale switches strings but not direction.
Tell layout that a node’s intrinsic size may have changed. For tweaks (docs/tweaks.md):
after a native call that alters a widget’s preferred size (fonts, tick marks, bezel styles),
the measure cache along the node’s path must be invalidated, since Day can’t see native
mutations it didn’t make. Relayout runs at the next turn boundary as usual. No-op on a
disposed node.
Whether the app is being rendered right-to-left (docs/localization), a convenience over
layout_direction. The layout engine already mirrors widget placement under an RTL locale,
but a canvas draws in its own coordinate space, so a custom drawing that has a reading
direction (a battery that drains one way, an arrow, a progress sweep) can call this to mirror
itself. Fixed for the life of the process, like layout_direction.
A nav item: item("today", res::str::today()).icon(res::images::today).page(today_page)
(docs/navigation.md). Goes into a Nav::items or Nav::section block, alone, in a
tuple, or from a nav_items mapper; an item without a page is built by
the nav’s Nav::destination. For a typed nav over Option<Section> pass the bare
Section::X.
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.
The app-wide layout direction (docs/localization): mirrors every horizontal placement in
the place pass when day_geometry::LayoutDirection::Rtl. Resolved lazily from the
DAY_LOCALE launch environment (so toolkits can read it before any UI exists);
set_layout_direction (called by install_locales for the resolved locale) overrides.
Fixed for the life of the process; switching locale at runtime does not re-mirror.
Does the running backend deliver phase? Use this to guard registration at runtime:
if day::lifecycle_supported(Lifecycle::DidEnterBackground) { on_lifecycle(...) }.
Build a recycling list from a RowSource and a row builder:
list(items(rows_fn, key_of), row_view) for plain data, list(store, row_view) (or
list(store.rows(projection), …)) for a day-model store.
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.
The three states of an async load as three subtrees (docs/async.md): the ready arm, and
optional loading and failed arms (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 through Loaded::get.
matches_search_in against the current locale. Reads the locale signal (tracked), so a
filtered list inside a reactive closure re-filters when the language changes, the same
contract crate::compare has.
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.
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.
A data-driven item block: nav_items(move || st.feeds.get(), |f| item(f.id, f.name).icon(…))
(docs/navigation.md). items is a tracked reader (a Signal<Vec<T>> via its Fn() 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 (to
None for an Option key). Static items and blocks may be mixed; the final list is their
declaration order. A row without its own page is built by the nav’s
Nav::destination.
Register f to run whenever the app reaches phase. Handlers run in registration order, in a
reactive batch (signal writes coalesce into one UI update). Register early (before launch, or
at the top of the root builder) so WillLaunch/DidLaunch handlers are in place when they
fire.
Open url in the platform’s default handler (system browser for http(s), mail client for
mailto:, …). The function behind the link piece; call it
directly from a tap handler for a custom affordance. Fire and forget: no result, unopenable
URLs are ignored by the backend.
picker(sort, [(Sort::Name, res::str::name()), (Sort::Date, res::str::date())]).segmented():
selected is a two-way binding to the chosen value (a Signal<T>, a day-model Field, a
Mapped view), 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.
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).
The window’s safe-area insets, in points. Zero on every backend that clamps Day’s root to
the safe area natively (the default everywhere); nonzero only where a backend runs the root
edge-to-edge, today day-mdc’s opt-in immersive mode (docs/layout.md, the android
platform page). Compose it yourself where a background should run under the system bars:
paint the background unpadded, pad the content by these insets. The read is tracked, but
layout attributes like .padding capture the value at build time, so a mid-run inset change
(rotation) does not re-pad already-built pages.
search_field(query): a native search input whose text mirrors query in both directions;
query is a Signal<String> or any other two-way binding (a day-model Field).
A password field: a text_field that hides its characters and tells the platform it
holds a password, so the password manager offers to fill it (docs/textfield.md).
Raise or lower the level Day’s default logger emits, at runtime. DAY_LOG sets it at startup
on native targets; the web launch path reads ?DAY_LOG= from the page URL.
Set the maximum level that will be emitted. Separate from init_logging because the web
launch path has to supply the level from the page URL rather than the environment, and because
an app may want to raise or lower it at runtime.
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_tap on the group via Decorate.
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).
The current window’s size class, or None on a backend that does not report one yet.
Tracked: a piece that lays out from this rebuilds when the window crosses a breakpoint.
Show a status item (docs/status-item.md): an icon in the macOS menu bar, the Windows
notification area, or a Linux tray. build runs 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. id names
the item; showing a second item with the same id replaces the first.
stepper(value): a numeric field with increment/decrement arrows. value is a
Signal<f64>, a day-model Field, or any other two-way binding; a step click commits one
unit through it (write_commit), so under an undo stack each click is one undoable step.
Build a swipe action with label (a literal, a res::str::… text, a signal or a closure;
resolved in the current locale each time the offer is pulled). Chain
destructive or tint for styling and
action for the work; an action without a handler still reveals and
dismisses, but does nothing.
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():
text_area(text): a native multi-line editor whose contents mirror text in both
directions; text is a Signal<String> or any other two-way binding (a day-model Field).
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.
A two-state button bound to on (a Signal<bool> or any other binding): the user flipping
it writes the binding, and writing the binding restyles the button.
Build a hierarchical tree from a NodeSource and 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.
Derive-state without effect-write loops (§4.2): source is tracked; cb runs untracked
with (new, old). Does not fire for the initial value: a “load whatever is selected”
reaction has to run once by hand first, or use bind, which applies the initial value
and then every change.
Explicitly animate every state change made in f, Day’s equivalent of SwiftUI’s
withAnimation. The mutation runs inside a day_reactive::batch; that batch’s synchronous
fixpoint drain (bindings → patch, plus the turn-end layout → set_frame) executes while
spec is ambient, so the resulting native updates carry the animation intent and the toolkit
animates them on its own compositor. Nesting overrides; the previous ambient restores after.
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.