Implementation reference

API contracts, platform behavior, and implementation notes for app developers and contributors. These pages are also available in the repository’s docs/ directory. For step-by-step examples, start with the app guides.

Core & UI

Framework-level UI: navigation, lists, layout containers, drawing, text, and the cross-cutting concerns every app touches.

Text & typography

Labels, symbolic fonts, dynamic type, selection, and the text pipeline on every backend.

Styled runs

Several styles inside one label: the runs API over attributed text.

Markdown labels

label(…).markdown(): inline Markdown rendered through each platform's attributed text.

Buttons

Native buttons with labels, icons, reactive state, and platform styles.

Navigation

Native sidebars, tabs, and push navigation from one declarative model, plus routes and deep-link intake.

Deep links

Custom URL schemes end to end: registration, cold and warm delivery, routing, and launcher shortcuts as saved deep links.

Dialogs & modals

Imperative presentation via present(): alerts, confirmations, sheets, and how dismissal returns a value.

Menus

The app menu model: the macOS menu bar, context menus, shortcuts, and how other platforms present the same tree.

Window toolbars

Native window toolbars: items, search, overflow, and per-platform presentation.

Secondary windows

Real secondary windows on desktop, covers on mobile: open_window, the preferences singleton, and the Window menu.

Window capture

day::window_image(): the app capturing its own window as a PNG on every platform.

Grid

The grid piece's design and implementation: fixed and adaptive tracks, spans, and native measurement.

Forms

form, section, and labeled: the grouped-settings look on every platform, from Mac form sheets to Android preference lists.

Baseline alignment

How text in a row sits on a shared baseline across toolkits, and the layout rules that keep mixed fonts aligned.

Size classes

Compact to expanded: how day re-presents navigation when the window crosses a size-class boundary.

Programmatic scrolling

scroll_to and scroll position: driving native scroll views from Rust, and what each backend can promise.

Search

searchable(): a declared search surface each platform presents natively: toolbar field, navigation search, or list filter.

Fullscreen cover

The cover presentation: a fullscreen surface over everything, the system-gesture shield, and how each backend presents it.

Inspector

The inspector piece: window content beside a trailing properties panel, one visibility signal, a side pane on wide windows and a sheet on compact ones.

Focus

Keyboard focus as a reactive signal: focus order, programmatic focus, and per-toolkit behavior.

Cursor

The .cursor() decorator: one pointer-shape vocabulary, each toolkit's realization, the reactive form, and the shapes only one toolkit names.

Native list

The list piece over native table and collection views: virtualized rows, selection, swipe actions, and reorder.

Tree

A hierarchical tree piece over each platform's native tree view, with live selection, expansion, drag-to-reparent, keyboard navigation and type-ahead.

Canvas

The canvas piece records a display list each backend replays through its native 2D API: gradients, transforms, and gestures.

Fonts

Labels pick their type through FontSpec — semantic styles the reader's text-size setting scales. A drawing has different needs: it names a family from the…

Shapes

Vector shape pieces — rectangles, circles, paths — drawn through each platform's native layer API.

Progress indicators

progress and spinner: determinate and indeterminate, native on every backend.

Picker

The built-in picker piece: native segmented controls, dropdowns, and wheels, chosen per platform.

Text area

The multi-line text editor piece: line hints, wrapping, and per-platform editors.

Styled text editor

day-piece-texteditor: editing the same StyledText that labels render, in each platform's rich-text view.

Localization

Catalog generation, private namespaces, locale selection, fallback, formatting, and translation checks.

Accessibility

Uniform accessibility annotations over each platform's native tree: labels, values, focus order, stable identifiers, and the CI audit that diffs them.

App lifecycle

Foreground, background, and termination events as day delivers them, uniformly across platforms.

Async without a runtime

day::task futures on the main thread with no tokio: how background work returns to the UI through Setter and on_main.

App state

Where state lives when an app has more than one window: Ambient values, the app scope, the window scope, and the focused-window rule for menu bars.

Observable model

day-model's per-property observable store: Store, Keyed, Elem, Field, the Observable derive, and the change log.

Persistence

day-persistence: SQLite storage for the observable model — ModelContainer, the Model derive, drivers and engines, migrations, codecs, and maintenance.

Resources

The typed res:: constants: images, data files, fonts, vectors, and hierarchical assets, staged natively per platform.

Vector images

resource/vectors/ and the vector piece: one SVG master, rendered natively per platform with tinting.

Images

Raster images from bytes: decoding a PNG or JPEG the app already holds into the platform's own image type, drawing it, reading what it is, and writing it back out.

Color and Paint

Day's color currency as it ships, what a native color picker can hand back that it cannot hold, and a proposal to widen it.

App icons

Build platform icon families from one master SVG, create seeded source icons, and check for drift.

Drag and drop

Native transfers, representation types, destination policy, and platform boundaries.

Drag and drop implementation plan

Proposed transfer model, toolkit adapters, Day-Sketch behavior, and validation.

File pickers

Native open and save dialogs, scoped access on sandboxed platforms, and the piece-level API.

Pieces

Standalone UI Pieces: native widgets that live in their own crates and plug in without any core changes.

SwiftUI embedding

Host your own SwiftUI views inside the Day tree on macOS and iOS, with typed Rust constructors generated from your Swift package.

Web view JS evaluation

The web_eval dayscript compatibility command and the external webview documentation.

Map view

A native map piece — MapKit and Google Maps arms — with markers and camera control.

Media playback

The external day-piece-media crate for native audio and video playback.

Combo box

An editable text field with a native completion popup, as the external day-piece-combobox crate.

Search field

The standalone native search field as an external piece.

Activity spinner

The indeterminate activity spinner piece, native on every backend, and when to prefer progress instead.

Pull-to-refresh

The pull-to-refresh piece: native refresh controls where they exist, a faithful emulation where they don't.

Date & time pickers

Native date and time pickers as external pieces, with per-platform presentation notes.

Color picker

A color well in two idioms — the platform's chooser, and one Day draws itself out of pieces and a canvas — bound two-way to a Signal<Color>.

Stepper field

A numeric field with increment/decrement arrows in two idioms (the platform's widget, and one Day composes), bound two-way to any Binding<f64>.

App icon badge (proposed)

A proposed piece for the app icon's numeric badge, with the per-platform conveyance it would need.

Tweaks

Per-toolkit configuration of built-in pieces: reach the real native widget behind a piece, safely.

Parts

Headless capability crates, the non-UI counterpart of Pieces. They provide device and system access without any widgets.

Battery

Battery level and charging state as reactive signals, via the day-part-battery headless capability crate.

Clipboard

Reading and writing the system clipboard via day-part-clipboard, with the platform quirks that complicate round-trips.

Preferences storage

Persistent key-value preferences via day-part-prefs, stored in each platform's native store.

App-local file storage

Reading and writing app-local files via day-part-fs, including the OPFS-only web arm.

Notifications (proposed)

The proposed notification APIs: local scheduling and push, as two parts and a sending tool.

Network connectivity

Reachability and connection-type signals via day-part-network.

Sensors

Accelerometer, gyroscope, and magnetometer streams via day-part-sensors, including the synthetic web arm.

Haptics

Haptic feedback via day-part-haptics: impact styles per platform, and where haptics are silently unavailable.

Sound effects

Short sound clips via day-part-sound: bundled WAV files played through each platform's low-latency engine.

Wake lock

Keep the screen on while something is showing, via day-part-wakelock.

Device info

Device identity (OS, version, model, form factor) as a headless capability crate.

HTTP

HTTP through each platform's network stack via day-part-http: streaming, uploads, redirects, authentication, trust, cookies, caching and WebSockets.

Downloads

Large downloads with pause, resume, SHA-256 checks and retries via day-part-downloads, run by the app or handed to the OS.

OS permissions

Declaring, requesting, and explaining OS permissions across platforms, and what happens when you skip a step.

Location

One-shot and continuous location via day-part-location, with the permission flow attached.

Platform & tooling

Platform backends, the extension model for writing your own Pieces, per-backend support matrices, API conventions, and tooling.