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.
The deferred pop handed to a Stack::on_back guard. Hold it, then call proceed to
perform the back the guard consumed (the unsaved-changes → confirm → leave flow).
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).
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 and italic flag. 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 own theme-adaptive grouped-content material
(SurfaceRole::SectionCard — quaternary fill on AppKit, libadwaita .card, Qt
palette(alternate-base), tertiary system fill on iOS, Material surface-container, the
XAML card brush), so it follows light/dark mode with no app code.
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 opens url in the platform’s default handler — the system browser
for http/https, the mail client for mailto:, and so on. This is Day’s analogue of
SwiftUI’s Link.
A native recycling list: the platform widget owns scrolling + cell reuse; Day builds each
visible row once and rebinds it (a slot-write into its ItemSlot) as cells recycle.
Shares the ItemSlot row contract with each; migrating is a one-word change.
A menu entry under construction. Build a command with menu_item, a nested submenu with
sub_menu, a standard system command with menu_role, and a divider with menu_separator.
Attach to a Piece via [Decorate::context_menu] or install app-wide via app_menu.
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.
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.
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 one-of-N selector whose active key is an app-owned signal (two-way, exactly like
Picker/Toggle). Deep links and dayscript address items by key (docs/navigation.md).
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 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 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 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 vector 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 Stack::on_back guard returns for one back-like event (a native back gesture/button,
or nav_back). Programmatic path writes are NOT guarded — the guard is a policy on the
user’s back affordance, matching Jetpack Compose’s BackHandler (docs/navigation.md).
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 — so a Day app matches the OS’s own typography and inherits its
accessibility text scaling for free. 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).
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 truly enters the
background and can be low on memory, a desktop app essentially 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 — selector on AppKit/UIKit
(cut:/copy:/paste:…), 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 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 — 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 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.
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.
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.
A pluggable button appearance (the SwiftUI ButtonStyle analog). Pure composition — a style
builds its body from existing pieces/decorators, so it needs no per-backend native code.
Apply one with Button::style.
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 (the coherent form of §12.2’s IntoText):
literals, String, Signal<String>, and closures all convert, each under its own marker.
A one-shot, by-value view transform (the SwiftUI ViewModifier analog): wrap a piece into a
new one. Pure composition — no per-backend work. A plain FnOnce(AnyPiece) -> AnyPiece closure
is a Modifier too (the blanket impl below), so the common case needs no new type. Apply one
with Decorate::modifier.
Children of a container: a tuple of pieces (the floem ViewTuple pattern — implemented
ONLY for tuples, (), and PieceVec, never via a blanket, to stay coherent).
Install the application menu — the native menu bar on desktop, the app-bar overflow on Android, the
UIMenuBuilder main menu on iPadOS/Catalyst. Top-level entries are usually sub_menu(...)s (the
menu-bar menus). Call at startup or whenever the menu changes; it replaces any previous app menu.
app_menu that re-lowers and re-installs whenever a locale-tracked read inside the
builder changes — menu_role labels, res::str titles, and day::tr all read the
locale signal, so a runtime language switch rebuilds the menu in the new language
(docs/menus.md). Replacement drops the previous install’s action closures (context
menus are unaffected). The binding lives in a root-owned scope: install once, at startup.
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.
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).
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 own
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.
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).
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 [Decorate::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 — 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 selector item for a data-driven list: item(room.id, room.name).icon(res::images::room)
(docs/navigation.md). Used inside the .items(signal, |t| …) mapper; the page it selects is
built by the selector’s Selector::destination.
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(...) }.
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 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.
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 seam 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.
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-android’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 — a mid-run inset change
(rotation) does not re-pad already-built pages.
Flatten many shape descriptions into ONE canvas leaf — one native view no matter how many
shapes (docs/shapes.md §3.6). Shapes draw in order; reactive properties re-record the group.
Child gestures are not wired inside a group — put .on_tap on the group via Decorate.
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).
Install the toolbar on the window being built — the primary window at startup, and the new
window inside a register_new_window builder. Replaces any previous toolbar on that window;
an empty items removes it. Add or remove an item by calling this again with a different
list, or use toolbar_reactive to keep the list derived from state.
A gap that absorbs the leftover width. Everything before the first one is packed to the
leading edge and everything after it to the trailing edge, which is how each toolkit’s own
packing (GTK’s start/end, XAML’s content/commands) is expressed in one ordered list.
toolbar that re-lowers and re-installs whenever a reactive read inside builder changes —
a locale switch, or a command list that depends on what is selected.
A native search field bound two-way to query — NSSearchToolbarItem, GtkSearchEntry,
a Qt search QLineEdit, an AutoSuggestBox. Set the prompt with .placeholder(_).
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.