Skip to main content

Crate day

Crate day 

Source
Expand description

Day, the umbrella crate apps depend on. One backend feature per binary (§3.2).

Re-exports§

pub use day_part_filesystem as fs;
pub use day_part_permissions as permissions;
pub use day_piece_settings as settings;
pub use day_piece_swiftui as swiftui;
pub use day_piece_text_editor as texteditor;
pub use ::log;
pub use day_core::linkme;

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.
clipboard
MIME-typed text and binary clipboard data, with async browser support.
colorpicker
day_pieces::colorpicker is a color chooser bound two-way to a Signal<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.
conformance
Tests that run inside the built app (docs/testing.md): #[day::test], Case, Drive. Tests that run inside a built Day app (docs/testing.md): a Case is a page plus a drive, or a headless run, declared next to the code it tests with #[day::test] and collected in a registry. The dayscript engine runs them on a real toolkit under day test; the mock harness runs the same functions under cargo test. Nothing here knows how a step is executed: a DriveBackend does, and the engine supplies one.
cursor
Pointer shapes for the .cursor() decorator (docs/cursor.md).
datetime
day_pieces::datetime: core date and time pickers with native toolkit renderers and a composed DOM fallback (docs/datepicker.md; DESIGN.md §15).
frame
Window-scoped display scheduling (docs/frames.md). Native frame requests are shared by one-shot clients, continuous subscriptions and the legacy frame_clock piece. No timers, no implicit physics clamp, and no native request when there is no demand.
lifecycle
App-lifecycle support for the backend compiled into this binary (docs/lifecycle.md).
model
Persistent settings (docs/prefs.md): a small key/value string store backed by each platform’s native facility: NSUserDefaults on Apple, SharedPreferences on Android, a file store elsewhere. day::prefs::{get, set, remove, contains}, plus bind to persist a Signal and (with model) bind_json to persist a keyed store. day::launch installs it as the store .restore(key) navigation survives a relaunch through (docs/navigation.md).
pager
Native interactive horizontal paging. Slots have stable native identities; order chooses which slots participate and their reading order. Changing order never rebuilds a page. Apps must defer changing slot contents while busy is true. Native callbacks carry the presentation epoch, so delayed completions cannot select a recycled slot.
prefs
prelude
pullrefresh
day_pieces::pullrefresh: pull-to-refresh for any Day scrollable, modeled on SwiftUI’s refreshable(action:) (DESIGN.md §15; docs/extending.md).
reactive
The reactive core, whole (docs/async.md): day::reactive::{Resource, Load} for async data loading. Namespaced because the prelude’s Resource is the asset handle above, a different type that predates the async one.
record
dayscript recording and action logging (docs/dayscript.md “Recording”, DESIGN §14.6): install an observer that sees the user’s taps, edits, selections, and navigation. day::record::{start, start_into, start_to_file, stop, is_recording, recording_signal, script, steps, save, clear, exclude_prefix} captures them into a replayable dayscript; a recorder also arms headlessly from day launch --record <file> (the DAY_RECORD env, honored inside day_script::init). What it records is an ordinary dayscript, so it replays cross-toolkit through play_script or day launch -t <target> --script <file>.
res
Day’s own strings, named the way an app’s are: res::str::day_cancel(), res::str::day_about_app(name), one typed function per message in the core catalog (day-localization/catalog/en.ftl), generated from it at build time (docs/localization.md).
searchfield
Core search input with a toolkit-owned native renderer: NSSearchField, UISearchTextField, GtkSearchEntry, a Qt search field, Android search input, XAML AutoSuggestBox, or DOM search input.
stepper
day_pieces::stepper: a numeric stepper field, a text field with increment/decrement arrows, bound two-way to any Binding<f64> (docs/stepper.md).
storage
The app’s own data, cache and configuration directories, each a folder named after the app id where its platform keeps that kind of file (docs/fs.md “Where files live”): day::storage::data_dir() for a database or documents, cache_dir() for what can be fetched again, config_dir() for a small settings file. Where an app keeps its own files: its data, cache and configuration directories, each a folder named after the app id in the place its platform sets aside for that kind of file (docs/fs.md “Where files live”). Every Day crate that stores files resolves them here, so an app’s database, documents, caches, settings file and remembered window frames sit together and apart from every other app’s.
testing
Tweening for canvas animations (docs/tween.md): Lerp, Timing, animate, Tweened. Opt-in presentation policy for functional walkthroughs: fast mode is reduced motion forced on (docs/accessibility.md), nothing more. This is not a virtual clock: timers, network requests, physics and media retain their real timing.
transfer
Native drag-and-drop data and acceptance policy. Native drag data and synchronous destination policy. No clipboard or process-local transport.
tween
Tweening for canvas animations (docs/tween.md): Lerp, Timing, animate, Tweened. Tweening for self-drawn content (docs/tween.md): the pieces a canvas animation needs that native widgets get from their toolkit.

Macros§

day_start
One entry point for every platform that needs one: the single line an app’s lib.rs carries instead of one macro per platform.
day_start_android
Expands to the two JNI exports that start the app, DayBridge.nativeStart (the primary window) and DayBridge.nativeStartWindow (a secondary one), wired to the given root piece. They live in the app cdylib because they name the app’s root; every other native the bridge declares is registered by day-toolkit-material’s DayBridge binding (docs/android-jni.md).
day_start_arkui
Expands to the day_arkui_start C export the HarmonyOS ArkUI shim’s start(...) NAPI wrapper calls (from ArkTS: import native from 'libday_arkui.so'; native.start(nodeContent, w, h, density)). It mounts the app’s root piece into the ArkTS NodeContent and runs the loop.
day_start_ios
Expands to the day_main C export the iOS Runner’s main.swift calls (@_silgen_name("day_main")). The optional title is currently unused on iOS (the window fills the screen bounds); accepted for future window-scene use.
day_start_macos
Expands to the day_main C export the macOS Runner’s main.swift calls, the platform/macos/ Xcode host project’s entry (§17.4). The cargo-driven build keeps using the app’s own src/main.rs; both paths call the same launch, so the app behaves identically however it was built.
day_start_web
Expands to the day_dom_main C export the web host’s shim.js calls once the wasm module is instantiated (wasm.day_dom_main() at the end of start() in crates/day-cli/resources/web/shim.js).
debug
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.
error
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.
id
Display-synchronized, cancellable frame callbacks for any UI client. Declare an ID at its piece, including a link-time catalog entry.
info
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.
log_enabled
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.
require_lifecycle
Compile-time assert that the backend in this binary delivers $phase, else a build error. Use it to make a hard dependency on a platform-specific phase explicit: day::require_lifecycle!(day::Lifecycle::DidEnterBackground); fails to compile on desktop. For soft handling, guard with lifecycle::supported / lifecycle_supported instead.
resources
Surface the resources day-build generated for this crate as pub mod res (§18.5).
routes
Define a plain routes enum and its Route impl in one shot:
trace
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.
warn
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.

Structs§

AnyPiece
Type-erased piece for heterogeneous branches and dynamic construction.
Application
ApplicationHandlers
AssetDir
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.
AssetName
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).
AsyncImage
A growing image surface. Empty and invalid sources show the placeholder.
Bitmap
Raster images from bytes (docs/images.md): decode an encoded PNG or JPEG the app already holds (a download, a file the user picked, a paste) into the platform’s image type, then show it with image(&bitmap) or draw it with Draw::image.
BitmapId
A decoded image the toolkit holds, addressed by an id day-core mints.
BitmapInfo
What a decoded image is, in the terms every backend can answer (Toolkit::image_info, docs/images.md).
Blocking
The blocking pool (docs/async.md): spawn_blocking runs a job on a worker thread and resolves on the awaiting side; std-only, so it lives in day-async and is re-exported here. The future spawn_blocking returns: the job’s value once a pool thread has run it.
BuildCx
CanvasExports
Canvas export (docs/canvas.md “Exporting”): render a recorded Drawing to a bitmap or a PDF through the toolkit’s own painter. canvas_exports() says which of the two this target offers; the PDF writer is native on AppKit, UIKit, GTK, Qt and Android only. What this toolkit can export a canvas drawing to (Cap::CanvasBitmap, Cap::CanvasPdf). Read it to enable or hide export commands, the way image_encode_formats decides which formats to offer.
Case
One test: what it proves, what it needs, the page it shows and the body that drives it. Built by a #[day::test] function each time the test runs, so the signals a page and its drive share are fresh per run; the registry names it after that function.
Catalog
An embedded, private Fluent namespace. Generated by day_build::generate_locales. Catalog identity is its static address, so identical keys in different crates never collide. name is only the qualified lookup name used by scripting (crate::file::key).
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_item and toolbar_item.
Drawing
Canvas export (docs/canvas.md “Exporting”): render a recorded Drawing to a bitmap or a PDF through the toolkit’s own painter. canvas_exports() says which of the two this target offers; the PDF writer is native on AppKit, UIKit, GTK, Qt and Android only. A recorded drawing at a fixed size: what a [canvas] would replay, kept for export.
Drive
The handle a test drives the app with. Every method awaits the op and fails the test with the step’s own message when the op fails after its retry window.
EditState
What the app’s edit bridge can currently do, mirrored into the toolkit (Toolkit::set_edit_state) so native menu validation enables the stock items. can_paste is the app’s half (“a paste handler is installed”); the toolkit combines it with its own clipboard-has-text check where one exists.
ElementId
Display-synchronized, cancellable frame callbacks for any UI client. An application-owned element identity, declared with crate::id!.
EncodeSpec
What Toolkit::encode_image should produce (docs/images.md).
Fail
A failed assertion, with the sentence the report shows.
FontFamily
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.
ImageName
The bundled-image name that resource() callers resolve by (the file stem).
ImageProperties
The metadata an image file carries beyond its pixels (Toolkit::image_properties).
KeyEvent
LauncherShortcut
A launcher shortcut the app sets while it runs (docs/deep-links.md “Launcher shortcuts”): a route to open and the label the launcher shows, already localized.
LocalizedText
A localized text source: label(tr("greeting").arg("name", name)) (§12.2).
Modifiers
The keyboard modifiers held at an interaction, queryable ambiently (Toolkit::modifiers): primary is the platform’s command key (⌘ on Apple platforms, Ctrl elsewhere, the same convention Shortcut::primary uses). Touch-only backends answer all-false.
Monitor
One display (docs/windows.md “Monitors”), in points on the desktop’s coordinate space: top-left origin at the primary display’s top-left corner.
NativeRef
A liveness-checked reference to a mounted piece’s realized node: the retained half of the tweaks API (docs/tweaks.md). Capture one with Decorate::native_ref, then reach the native widget later (from event handlers, timers) through a toolkit ext accessor. node/with yield None before mount and after the node’s subtree is disposed, so async races are safe no-ops.
PdfDocument
Canvas export (docs/canvas.md “Exporting”): render a recorded Drawing to a bitmap or a PDF through the toolkit’s own painter. canvas_exports() says which of the two this target offers; the PDF writer is native on AppKit, UIKit, GTK, Qt and Android only. 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).
PdfInfo
The document information a PDF carries. A backend whose writer has no metadata API (Android’s PdfDocument) ignores it.
PdfPage
One page of a PDF Toolkit::render_pdf writes: the page size in PDF points (1/72 inch, the same unit as canvas points) and the ops to replay onto it, origin top-left.
RNode
Realized-node key. NodeId (the spec-boundary id) is its FFI encoding.
RenderBitmap
Canvas export (docs/canvas.md “Exporting”): render a recorded Drawing to a bitmap or a PDF through the toolkit’s own painter. canvas_exports() says which of the two this target offers; the PDF writer is native on AppKit, UIKit, GTK, Qt and Android only. 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.
RenderPdf
Canvas export (docs/canvas.md “Exporting”): render a recorded Drawing to a bitmap or a PDF through the toolkit’s own painter. canvas_exports() says which of the two this target offers; the PDF writer is native on AppKit, UIKit, GTK, Qt and Android only. 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.
Resource
A handle to a bundled resource’s bytes with efficient random read-only access.
StatusImage
A small runtime RGBA image for a status item: charts, meters, or a grid of results.
TaskHandle
A handle to a spawned task. Copy and !Send (the executor is thread-local).
TextEditor
A styled-text editor bound two-way to a StyledText signal. Build with text_editor.
TextMetricsCacheStats
What measure_text’s cache has done on this thread: a diagnostic, for an app that wants to see whether its drawing is measuring the same strings over and over (it usually is).
VectorName
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).
WindowHandle
A live secondary window (docs/windows.md). Cheap to clone; inert after close.
WindowImage
The request built by window_image.
WindowOptions

Enums§

AppBadge
What to show on the app’s icon in the Dock, launcher, home screen, or taskbar (docs/badge.md).
AppProgress
A progress indicator on the app’s Dock or taskbar icon (Toolkit::set_app_progress, docs/status-item.md).
ApplicationError
Attention
How strongly a window asks for the user’s attention (WindowChange::RequestAttention).
BlockingError
The blocking pool (docs/async.md): spawn_blocking runs a job on a worker thread and resolves on the awaiting side; std-only, so it lives in day-async and is re-exported here. Why a Blocking future resolved without its job’s value.
DateFields
Which parts of an instant to write. The locale decides their order, words and punctuation.
EditOp
A standard edit command a platform route delivered (Event::Edit).
ExportError
Why a canvas export could not answer (docs/canvas.md “Exporting”).
FArg
HandlerQuery
ImageError
Why an image operation could not answer.
ImageFormat
An encoded image format: what BitmapInfo::format reports and EncodeSpec::format asks for. Not every backend encodes every one: ask Toolkit::encode_formats (the Cap::ImageEncode pair of Toolkit::font_families/Cap::FontList) rather than assuming.
ImageSource
Where a raster image’s pixels come from (docs/images.md).
KeepRunning
Whether the app keeps running when its last window closes (docs/windows.md “Keeping the app running”), set with set_keep_running.
Lifecycle
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.
WindowBackground
What shows behind a window’s content (docs/window-chrome.md).
WindowChrome
The frame a window wears (docs/window-chrome.md), set once when it opens.
WindowKind
What a secondary window is, so backends can apply platform conventions (docs/windows.md).
WindowLevel
How a window stacks against other apps’ windows (WindowChange::Level, Cap::WindowLevel).
WindowMaterial
The system materials a window background can use (WindowBackground::Material).
WindowPlacement
Where a window opens (WindowOptions::placement).
WindowState
How a window is shown (docs/windows.md “Window properties”): what the window’s state() signal holds and what WindowChange::State asks for.
WindowTabbing
Whether and how a window joins macOS window tabs (WindowOptions::tabbing, Cap::WindowTabbing). Other platforms have no system window tabs and ignore it.

Constants§

EXPORT_MAX_PIXELS
The most pixels a rendered bitmap may hold in total: 64 megapixels, 256 MB at four bytes a pixel, which is already more than the tightest per-app heap (Android’s) comfortably holds.
EXPORT_MAX_SIDE
The largest side, in pixels, a rendered bitmap may have (docs/canvas.md “Exporting”). day-core answers ExportError::TooLarge above it before any toolkit allocates.

Traits§

AsyncImageBuilder
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.
IntoElementKey
Display-synchronized, cancellable frame callbacks for any UI client. 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.
IntoFArg
Disjoint-marker conversion for .arg values (the same E0119 dodge as IntoText).
IntoNumberFArg
Marker for IntoFArg values that carry a number, required for a Fluent variable used as a plural / select selector, where CLDR plural rules select on a number (so a string can’t be passed there by mistake). Implemented for the numeric IntoFArg types only (i64, f64, and their Signals); the generated res::str::<key>(…) functions (§18.5) type such parameters as impl IntoNumberFArg instead of impl IntoFArg.
Piece
A UI description consumed once (§5.2). Returns the root realized node it created.
PieceSeq
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.
TextEditorBuilder
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.

Functions§

app_temp_dir
An app-writable scratch directory. The OS temp dir is not app-writable on every target (Android reports getCacheDir()), so a backend records the right location at startup and this is how an app asks for it. For derived files an app can rebuild: rendered documents, thumbnails, export staging. 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.
application_handlers
Query current system associations on the UI thread. macOS AppKit implements all query kinds; other backends return Unsupported. No application is launched by discovery.
async_image
Decode each source asynchronously. A replacement cancels the previous decode; disposal cancels the pending task. A failed replacement clears the previous picture.
blocking_limit
The blocking pool (docs/async.md): spawn_blocking runs a job on a worker thread and resolves on the awaiting side; std-only, so it lives in day-async and is re-exported here. How many threads the blocking pool may hold at once: the machine’s parallelism, at least four (a job waiting behind three slow ones still gets a thread), at most thirty-two. Zero on the web, where jobs run inline.
blocking_threads
The blocking pool (docs/async.md): spawn_blocking runs a job on a worker thread and resolves on the awaiting side; std-only, so it lives in day-async and is re-exported here. How many pool threads exist right now, idle ones included: for diagnostics and tests.
canvas_exports
Canvas export (docs/canvas.md “Exporting”): render a recorded Drawing to a bitmap or a PDF through the toolkit’s own painter. canvas_exports() says which of the two this target offers; the PDF writer is native on AppKit, UIKit, GTK, Qt and Android only. What this toolkit can export a canvas drawing to.
check_for_updates
Run the registered Check for Updates… command. false = none registered.
clear_text_metrics_cache
Drop every cached measurement (the counters keep running).
compare
Compare two strings in the current locale’s collation order. Reads the locale signal (tracked), so a sort inside a reactive closure re-runs when the locale switches.
compare_in
Compare two strings in locale’s collation order (untracked; accepts -u-co- extensions, e.g. "zh-u-co-stroke"). Falls back to code-point order if the locale has no collation data.
current_window
The window the caller belongs to (docs/windows.md): the one whose content is being built right now, else the focused window, else the app’s first window. What a piece uses to change “its” window (current_window()?.set_content_protected(true)) without threading a handle through. None before boot.
dark_mode
Whether the platform is rendering in dark appearance (see Toolkit::dark_mode): the branch apps take when painting custom opaque surfaces so fills track the theme that the default text colors already follow.
decode_image
Raster images from bytes (docs/images.md): decode an encoded PNG or JPEG the app already holds (a download, a file the user picked, a paste) into the platform’s image type, then show it with image(&bitmap) or draw it with Draw::image.
decode_image_async
Raster images from bytes (docs/images.md): decode an encoded PNG or JPEG the app already holds (a download, a file the user picked, a paste) into the platform’s image type, then show it with image(&bitmap) or draw it with Draw::image.
default_browser
The OS-chosen browser for HTTPS links, read afresh rather than cached by Day.
env
An app-environment value, portably: the process environment on native targets, the page URL’s query string on web-dom (where a browser sandbox has no process environment; day launch --env K=V forwards each pair as a query parameter, docs/web.md). Prefer this over std::env::var for anything a --env flag should be able to set on every target.
focus_search
Programmatic navigation on the deep-link rail (docs/deep-links.md, docs/navigation.md): route the app to route, buffered before the root is ready and applied after, exactly like a cold launcher shortcut. The route grammar is what day::routes! keys and dayscript speak. Activate the focused window’s searchable navigation surface (for a Find command).
focused_window
The most recently focused open secondary window, if any. None ⇒ the primary window is key (or no secondary window exists).
font_families
The platform’s font families with their faces (docs/fonts.md), enumerated once per process through Toolkit::font_families and cached: the answer is stable for the process (bundled fonts register before the tree exists, and nothing tracks a system font install under a running app; the OS font panels cache too), enumeration is expensive, and the query is synchronous on the UI thread. Sorted case-insensitively by family, deduplicated, and unioned with the bundled fonts (day_spec::fonts::bundled_fonts) the toolkit’s own database did not report, which is how a res/font/ (Android), ms-appx (XAML) or registerFont (HarmonyOS) family reaches a font menu without each shim parsing sfnt. Empty where the toolkit answers Cap::FontList = Unsupported.
format_catalog
Format within one private namespace; missing keys fall back only to this catalog’s default. App/core catalogs cannot accidentally supply a similarly named key from another component.
format_date
format_date_in in the current locale (tracked, like crate::format_decimal), so a label inside a reactive closure re-renders when the locale switches.
format_date_in
Write the instant epoch_seconds (seconds since 1970-01-01T00:00:00Z, read as UTC civil time, the convention of the Fluent DATETIME() builtin and of chart time axes) in locale, showing fields (untracked).
format_decimal
Render v in the current locale (tracked, like crate::compare), so a label inside a reactive closure re-renders when the locale switches.
format_decimal_in
Render v in locale, rounded to fraction_digits and grouped by that locale’s own rule (untracked). 1234.5 is 1,234.5 in en, 1 234,5 in fr, 1.234,5 in de.
format_percent
format_percent_in in the current locale (tracked), so a label inside a reactive closure re-renders when the locale switches.
format_percent_in
Render the fraction v as a percentage in locale (0.5 is 50% in en, 50 % in fr, %50 in tr), rounded to fraction_digits places of the percentage and grouped by the locale’s rule (untracked).
http_image
Download an image through the platform HTTP client and display it through the core decoder. The request is cancelled when the owning reactive scope is disposed.
image_decode_support
Raster images from bytes (docs/images.md): decode an encoded PNG or JPEG the app already holds (a download, a file the user picked, a paste) into the platform’s image type, then show it with image(&bitmap) or draw it with Draw::image.
image_encode_formats
Raster images from bytes (docs/images.md): decode an encoded PNG or JPEG the app already holds (a download, a file the user picked, a paste) into the platform’s image type, then show it with image(&bitmap) or draw it with Draw::image.
image_encode_support
Raster images from bytes (docs/images.md): decode an encoded PNG or JPEG the app already holds (a download, a file the user picked, a paste) into the platform’s image type, then show it with image(&bitmap) or draw it with Draw::image.
initial_window
A handle to the app’s first window, once adopted. None before boot completes, and after that window closes; it is an ordinary window and can be closed like any other.
install_edit_bridge
Wire the app’s standard-edit handlers to the platform (docs/menus.md): state is a tracked read whose value mirrors into the toolkit (Cap::EditBridge: native menu validation enables the stock Cut/Copy/Paste exactly as it does for text widgets), and every invocation a platform route delivers comes back through on_invoke. On a toolkit with no native route, the menu_role(Cut/Copy/Paste) items dispatch here instead (the same standing-id fallback the undo pair uses). Call once, after launch; installing again replaces the wiring. Most apps want day::install_edit_commands, which adds the clipboard transport.
install_edit_commands
Wire the app’s shape/object Cut/Copy/Paste to the platform’s own edit commands (docs/menus.md): the same menu items, shortcuts, and responder precedence text editing uses. A focused text field keeps its clipboard behavior; everything else reaches these handlers. can_copy is a tracked read (drive it from your selection); copy/cut return the serialized payload (its format is the app’s: Day-Sketch uses SVG), which day places on the system clipboard; paste receives the text the clipboard holds, falling back to the payload this app last placed there when the platform answers nothing (docs/menus.md). Menu items come from menu_role(MenuRole::Cut/Copy/Paste).
install_locales
Register the app’s locales (see day_localization::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.
install_undo
Wire a model::UndoStack to the platform: native fronts (the stock Edit menu, ⌘Z, iOS’s three-finger gestures) where the toolkit has them, and the stack’s own signals for the app’s buttons everywhere (docs/model.md). One call, after the stack exists.
invalidate_size
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.
invoke_edit
Invoke the installed edit bridge (the same handler the platform’s Cut/Copy/Paste route reaches, clipboard transport included), returning whether one is installed. An app’s own affordances (a context menu’s Cut/Copy) call this rather than duplicating the clipboard plumbing (docs/menus.md).
launch
launch_external
Launch through an external toolkit’s backend (docs/extending.md “External toolkits”): the cfg-free counterpart of the feature-gated launch entries below, for platform-toolkit pairs registered via [package.metadata.day.toolkit]. Feature-independent because day build -t <external> compiles the app with only the external toolkit’s feature, so none of the launchers below exist in that build. Starts the dayscript engine exactly as they do, which is what keeps day launch --script, day drive, and the session registry working on a backend this repository has never heard of.
lifecycle_supported
Does the running backend deliver phase? Use this to guard registration at runtime: if day::lifecycle_supported(Lifecycle::DidEnterBackground) { on_lifecycle(...) }.
locale
The current locale (a tracked read inside bindings).
matches_search
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.
matches_search_in
Whether text matches query under locale’s rules (untracked: pass the locale explicitly).
measure_text
Measure one line of canvas text at size points in font (docs/fonts.md), in the engine that draws DrawOp::Text; a toolkit that cannot measure answers TextMetrics::approximate, so a caller always gets a usable box.
modifiers
The keyboard modifiers held right now, for interactions whose meaning they change (shift-click adds to a selection instead of replacing it). Touch platforms answer all-false; a dayscript step’s declared modifiers take precedence while it dispatches.
monitors
The displays attached now (docs/windows.md “Monitors”). A toolkit that cannot list them (Cap::Monitors unsupported) answers with one display the size of the primary window, so a placement computed from the answer stays on screen.
on_lifecycle
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.
on_open_files
Receive local document activations from the operating system. See docs/documents.md. Install the application’s file-open handler. Called on the UI thread; pending cold-start activations are delivered on the next UI turn. Register once in the application root.
on_open_url
Receive local document activations from the operating system. See docs/documents.md. Register on the UI thread. Return true to consume a URL; false retains normal deep-link routing. Delivery never performs a privileged action.
open_about
Run the registered About action (docs/settings.md): the menu item’s dispatch, and what a toolbar button or a settings row calls. false = nothing registered (logged).
open_new_window
Open a window through the registered new-window builder (the newWindowForTab: / File ▸ New Window path). None = no builder registered.
open_preferences
Open-or-focus the preferences surface (docs/windows.md): a WindowKind::Preferences singleton window on desktop, the cover fallback elsewhere: one call for menu items and toolbar gears alike. false = no preferences piece is registered (logged).
open_url_with_application
Open a URL or file URL in a chosen application. Await on the UI executor. Success means the OS accepted the open request; tab/window presentation belongs to the receiving app.
open_window
Open a secondary window (docs/windows.md): open_window(res::window_options().key("city").size(…), build). options.key names the logical window: when a window with this key is already open it is focused and returned instead of duplicated (the preferences pattern); no key always opens a new one. options.kind says whether it is a regular window or a preferences/About panel. Where the toolkit cannot open windows (Cap::MultiWindow = Unsupported; probe it to adapt chrome) the content presents as a fullscreen cover in the primary window instead, closable the same way.
pager
play_script
Replay a dayscript against the running app, in-process (docs/dayscript.md “Recording”): parse yaml and run each step through the embedded engine, on the main thread between flushes, the same executor day launch --script drives. Returns an error while a recording is live (a replay must not record itself) and on web (no background thread; drive the page over the WebSocket transport there). See record.
quit
End the app now (docs/windows.md “Keeping the app running”): the Quit item of a status item’s menu, a background helper’s own decision. Every window is disposed and Lifecycle::WillTerminate delivered first, as when the last window closes.
reduce_motion
Whether motion should be reduced (docs/accessibility.md): the user’s system setting (Toolkit::reduce_motion), or a launch that forced it (DAY_REDUCE_MOTION=1, and day launch --fast, whose fast mode is this setting forced on). Day already applies every finite animation at its destination under it and keeps only indeterminate motion; this read is for the motion an app drives itself, such as a day::frame simulation or a decorative loop, which the app opts down. Reactive: a closure reading it re-runs when the setting flips.
register_about
Declare what the app’s About command does (docs/settings.md): once, in root(). Enables the About menu item everywhere a desktop has one (the macOS App menu, Help elsewhere; both the default menu and an installed app_menu) and open_about. The action is the whole contract, so a toolkit-native About dialog (libadwaita’s) and a Day window (register_about_window) register the same way.
register_about_window
register_about with a Day-rendered About window: opened under the singleton key ABOUT_KEY as a WindowKind::About panel (fixed, centered, out of the Window menu), the cover fallback where the toolkit cannot open windows. The window titles itself with options.title.
register_catalog
Make a catalog available for qualified scripting lookups. Generated accessors call this automatically. Registration never changes the app locale or its default catalog.
register_check_for_updates
Declare the updater’s Check for Updates… command (docs/settings.md): the item appears under About in the macOS App menu and in Help elsewhere, and MenuRole::CheckForUpdates items lower to it. Registered by an update provider, not by the app.
register_new_window
Register the builder behind File ▸ New Window and the macOS tab-bar “+” (docs/windows.md): each call opens another WindowKind::Normal window. A menu_role(MenuRole::NewWindow) item lowers to this action; without a registration it lowers disabled.
register_new_window_for
Register the builder behind the macOS tab bar’s “+” for windows whose WindowOptions::tabbing names group (docs/windows.md): each call opens another window of that group, as a tab of the window the user clicked “+” in. Groups without a registration fall back to register_new_window’s builder.
register_preferences
Declare the app’s preferences piece (docs/windows.md): once, in root(), ideally before app_menu. Enables the desktop Preferences window (singleton, primary+,), the auto Settings…/Preferences menu item, and open_preferences everywhere (cover fallback where the toolkit cannot open windows). The window titles itself with options.title; use register_preferences_with to localize it or change the size.
register_preferences_with
register_preferences with explicit window options (localized title, size).
request_route
Programmatic navigation on the deep-link rail (docs/deep-links.md, docs/navigation.md): route the app to route, buffered before the root is ready and applied after, exactly like a cold launcher shortcut. The route grammar is what day::routes! keys and dayscript speak. Ask the app to navigate, from anywhere, at any time.
resource
Open a bundled resource by name for efficient random read-only access.
safe_area
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-toolkit-material’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.
set_app_badge
Put a badge on the app’s icon: the Dock, launcher, home screen, or taskbar (docs/badge.md).
set_app_progress
Show progress on the app’s Dock or taskbar icon (Cap::AppProgress, docs/status-item.md).
set_appearance
Override the app’s appearance: Some(true) dark, Some(false) light, None follow the system again. On backends reporting Cap::Appearance the native widgets restyle in place and dark_mode answers the override; app-painted surfaces pick it up on their next rebuild. Other backends ignore the call; probe before offering a theme picker.
set_dock_visible
Show or hide the app’s Dock icon while it runs (Cap::DockVisibility, macOS). A menu-bar app hides it and lives in its status item; [app.macos] dock = false in Day.toml hides it from launch, before the first frame.
set_keep_running
Choose whether the app keeps running when its last window closes (docs/windows.md).
set_launcher_shortcuts
Replace the launcher shortcuts the app sets while it runs (docs/deep-links.md “Launcher shortcuts”): Resume <last document>, the three most recent chats. They show beside the Day.toml [[shortcuts]] on the iOS Home Screen, the Android launcher and the macOS Dock menu (Cap::DynamicShortcuts), and each opens its route like a deep link. Labels are shown as given, so pass localized text.
set_log_level
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.
share_support
Whether the current toolkit can present a native sharing chooser.
share_url
Present a native chooser for a URL. Call directly from user activation (required on web). Returns false if unavailable or presentation failed; cancellation is not an error and no completion is implied. The caller owns any explicitly labeled fallback.
size_class
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.
sleep
Resolve after (at least) ms milliseconds, on the UI thread: the portable delay for day::task flows (docs/async.md). Rides Platform::post_delayed, so it works on single-threaded hosts (web) where std::thread::sleep + Setter cannot.
sort_localized
Sort a slice in place in the current locale’s collation order (tracked, like compare).
spawn_blocking
The blocking pool (docs/async.md): spawn_blocking runs a job on a worker thread and resolves on the awaiting side; std-only, so it lives in day-async and is re-exported here. Run job on a pool thread and resolve to its value on the awaiting side.
stepper
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.
task
Spawn an async flow onto Day’s main-loop executor. This is the opt-in entry point for actions that open modals or pickers: button.action(|| day::task(async move { … .await … })). The future is polled once before this returns; the returned handle can TaskHandle::abort it and is freely discardable. At app termination pending tasks are dropped while reactive state is still available. Tasks submitted after shutdown begins are dropped without being polled.
test_host
The root of an app’s test build: the app’s content, or the driven case’s page alone. The root of an app’s test build: content normally, and while day test drives 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_editor
text_editor(doc): the platform’s rich-text view over a StyledText signal.
text_metrics_cache_stats
Read the measure_text cache’s counters (docs/fonts.md).
toolkit_name
The display name of the toolkit compiled into this binary: "AppKit", "GTK", "Qt", "UIKit", "Material Components", "XAML", "WinUI", "ArkUI", "DOM" (or "Mock"). Handy for a window title that names its backend.
tr
tr_in
Bind a key to a private crate/file catalog. Prefer generated typed accessors.
window_by_key
The open window registered under key, if any (the dayscript screenshot step’s window: target resolves here). Native windows being closed are excluded; a dismissing fallback cover remains available so reopening its key can reverse the transition.
window_image
A PNG of this window, as the app itself sees it (docs/window-image.md).
window_image_support
Whether this toolkit can hand the app a picture of its own window (Cap::Snapshot).
window_title
Bind the title of the window this piece is building into to a reactive closure (docs/windows.md). This is how a window comes to be named after what it shows.

Type Aliases§

TestResult
What a test’s body answers.

Attribute Macros§

builder
#[day::builder(FooBuilder)]: a piece’s builder trait, generated from its inherent impl (docs/api-style.md “Typed builders and erasure”). A piece’s builder trait, generated from the inherent impl that holds its builder methods (docs/api-style.md “Typed builders and erasure”).
test
Mark a function that builds a Case as a Day test (docs/testing.md): the function stays as written, and a link-time registry entry is added beside it so day test and the mock harness find it. The test is named after the function, with hyphens for underscores: button_status runs as button-status.