Crate mobiler_core 

Mobiler runtime — the developer-facing API.

Implement MobilerApp with your typed events, model, and view (built from the builders). Mobiler wraps it in MobilerShell, a Crux app speaking the fixed UI ABI (mobiler_ui); you never touch the wire protocol. Device APIs are capabilities via Cx.

Re-exports

pub use format::Currency;

pub use format::Locale;

Modules

bunny

Bunny.net Stream URL helpers — pure string builders, no I/O.

format

Locale-aware number, currency, and date formatting — pure, synchronous, dependency-light.

Structs

Caption

One subtitle/caption track for a Widget::Video. url points at a WebVTT (.vtt) file, language is a BCP-47 tag (e.g. "en"), label is the human-readable menu entry, and default_on selects it by default. Sidecar tracks work on web (<track>) and Android (Media3 subtitle configuration); on iOS only captions already embedded in an HLS manifest are selectable (AVPlayer can’t attach a sidecar VTT to an MP4 — a documented v1 gap).

ChartBracket

A right-side bracket annotation spanning [y0, y1] with a label note (e.g. a ceiling band).

ChartLegendItem

One legend entry (swatch + name) for a Widget::RegionChart.

ChartRefLine

A horizontal reference line across a Widget::RegionChart at value, with a right-edge label chip. dashed draws it dashed (e.g. a “max insured” ceiling) vs solid (a target).

ChartRegion

One rectangle in a Widget::RegionChart, spanning [x0, x1] horizontally and [y0, y1] vertically in the chart’s domain. label is centered inside (empty = none); vertical rotates it 90° for narrow columns. color overrides the auto-assigned palette slot.

ChartSeries

One named data series in a Widget::Chart. Cartesian styles plot values across the chart’s x-axis labels; circular styles (pie/donut/rings/gauge) collapse the series to a single magnitude (values summed). color overrides the auto-assigned palette slot; goal is the denominator for Rings/Gauge progress (ignored by the other styles).

ChartTick

An x-axis tick on a Widget::RegionChart at domain position at, labelled label. Ticks are irregular (the app places them), so shells position them by fraction, not even spacing.

Cx

Effects an app requests during update, generic over the app event type so continuations stay fully typed.

Fab

A floating action button anchored over the scaffold body (the raised primary action).

MobilerShell

Crux adapter: turns a MobilerApp into an app speaking the fixed ABI.

Nav

A navigation stack the app holds in its Model. The core owns the stack (single source of truth); the framework reads its route/depth to drive the shell’s push/pop transitions and back button.

PluginCall

PluginNotify

PluginResponse

PluginStreamCall

A streaming plugin subscription (powers Effect::PluginStream). Like PluginCall but carries a caller-chosen key so the subscription can be torn down (Cx::unsubscribe) — the shell registers the native source under key.

Rgb

A 24-bit RGB color. Used for a theme’s brand/seed color — the one place an app supplies an arbitrary color (everything else is intent tokens).

Segment

One option in a Widget::Segmented control (mirrors Tab). selected marks the active segment; tapping sends on_select.

Sheet

A modal bottom sheet anchored over the scaffold body (a scrim behind, a panel rising from the bottom). Present (Some) ⇒ open; tapping the scrim/handle sends on_dismiss.

SwipeButton

One revealed action in a SwipeAction row (swipe to reveal, tap to fire).

Tab

A bottom-navigation tab. selected marks the active one; tapping sends on_select. icon (optional) renders above the label for an icon tab bar.

Theme

App branding as data — the visual twin of dark_mode. Set on a Widget::Scaffold (theme: None = the framework defaults, i.e. no visual change). The shell maps these to its native theming: seed → the brand/primary color (Android M3 scheme / iOS tint / web --primary), plus a global corner, spacing, and font choice.

Enums

Action

What the shell sends back to the core. Fixed across all apps.

BoxAlign

ButtonStyle

CardStyle

ChartStyle

How a Chart draws its series.

Corner

Global corner-radius scale. Medium ≈ the current (un-themed) look.

Density

Global spacing scale. Comfortable ≈ the current (un-themed) spacing.

Effect

Built-in capabilities the generic shell fulfils.

EffectFfi

FieldKind

What a Widget::TextField accepts — selects the on-screen keyboard, secure (masked) entry, and single- vs multi-line layout in one axis.

FontFamily

A finite, cross-platform font family (maps to each platform’s nearest system font design — no bundled font files). System ≈ the current look.

Icon

A finite icon set (maps to Material icons / SF Symbols / web glyphs per shell). Grouped: editing, navigation/chrome, content, and domain icons.

ImageRatio

ImageShape

InputValue

A value produced by an input widget at runtime.

ProjectColor

Project-identity colors (distinct from semantic Tone). Concrete RGB decided in the render layer.

Spacing

TextStyle

Tone

Semantic status color (distinct from brand/identity color).

Widget

The app-agnostic widget tree the shell renders. Fixed across all apps.

Traits

MobilerApp

What a Mobiler app implements. Write typed domain events; Mobiler serializes them into opaque tokens behind the scenes.

Functions

avatar

A circular avatar image.

avatar_status

A circular avatar image with a colored status dot.

badge

bar_chart

A bar chart of values (normalized to the max), with optional per-value labels. Single-series, no axis or legend — for richer charts use chart.

button

calendar

An inline month calendar for year/month (1–12). on_day(d) builds the tap event for each day d in the month; selected highlights a day. Leading blanks + weekday header are handled by the shells from the computed first_weekday.

caption

card

card_button

A tappable card carrying a typed press event.

chart

A multi-series chart in the given style, with optional x-axis labels, y-axis gridlines/ ticks (cartesian styles), and a series legend. The general builder behind the convenience constructors below.

checkbox

chip

color_dot

A small colored identity dot.

column

decimal_field

A decimal keypad field (FieldKind::Decimal).

divider

donut_chart

A donut chart (pie with a center hole). Legend on.

email_field

An email-keyboard field (FieldKind::Email).

emphasis

field

A text field with full control over FieldKind and an optional inline validation error. The kind-specific helpers below (secure_field, email_field, …) wrap this for the common cases.

gauge_chart

A single radial gauge — the first series’ value / goal with the number in the center.

grid

icon_button

image

lazy_list

A scrollable list for long/paged feeds that fires on_load_more when the user scrolls near the end. The app owns the state: append to children on each load-more event, set loading true while the page loads (the shell shows a spinner and won’t re-fire), and has_more=false when the feed is exhausted. Add pull-to-refresh at the top with with_refresh. Give it room — a LazyList nested in a scrollable body needs a bounded height to scroll on its own.

lazy_list_static

A scrollable list with no load-more and no refresh — a plain virtualized list of children.

line_chart

A line chart of values (normalized to the max), with optional per-value labels. Single-series, no axis or legend — for richer charts use chart.

multiline_field

A growable multi-line text area (FieldKind::Multiline).

nav_scaffold

Scaffold driven by a Nav stack: fills route (from the current route’s serialization) and depth (stack depth) so the shell animates transitions, and shows a back affordance (top-bar arrow + system back button) firing on_back whenever the stack can pop.

number_field

A whole-number keypad field (FieldKind::Number).

pct_stacked_bar_chart

Bars where each x-slot fills to 100% — series as proportions. Legend on, no value axis.

pdf_view

An in-app PDF viewer for the document at url (remote https URL or local file URI) — rendered natively per platform (PDFKit / PdfRenderer / <iframe>). The app just supplies the URL, e.g. a backend-generated report. Give it room (place in a sized container or a scroller).

phone_field

A phone-keypad field (FieldKind::Phone).

pie_chart

A pie chart — each series is one wedge sized by its magnitude. Legend on.

progress

A progress bar (Some(0.0..=1.0)) or an indeterminate spinner (None).

rating

A read-only star rating. value is in tenths (e.g. 48 = 4.8 of max stars).

rating_input

A tappable star rating — on_rate carries one event per star (star i fires on_rate[i]).

region_chart

A variable-width stacked-region (“coverage-gap” / Marimekko) chart. regions are rectangles in the [0, x_max] × [0, y_max] plane (build with ChartRegion::new); ticks label the irregular x-axis; ref_lines are horizontal target/max lines (ChartRefLine::target/::max); legend names the colors. Add a right-side bracket annotation with with_bracket.

rings_chart

Concentric progress rings — one per series, swept by sum(values) / goal. Legend on. Give each series a goal via ChartSeries::with_goal.

row

scaffold

App shell: top bar + bottom-nav tabs + scrollable body. dark_mode is theme-as-data (the shell themes the whole app from it).

scaffold_back

Like scaffold, but the top bar (and the system back button) navigate back via back — e.g. a detail screen pushed over a tab (treated as depth 2). For multi-level stacks, drive navigation with Nav + nav_scaffold.

scroller

Horizontally scrolling row of children (a carousel / chip rail).

search_field

A search input (leading magnifier, pill); emits Input { id, Text } like text_field.

secure_field

A masked password field (FieldKind::Secure).

segment

One option in a segmented control, carrying a typed selection event.

segmented

A single-choice segmented control (exclusive options in a pill).

skeleton

A shimmer placeholder shown while content loads.

slider

spacer

stack

Z-stack/overlay (the Box widget). With scrim, the first child is a darkened background and the rest render on top.

stacked_bar_chart

Bars stacked to a total per x-slot. Axis + legend on by default.

stepper

styled

subtitle

swipe_action

A list row that reveals trailing actions (label, tone, event) on horizontal swipe; each is tappable. On web the actions render inline (no gesture).

tab

A bottom-nav tab carrying a typed selection event (label-only).

tab_icon

A bottom-nav tab with a leading icon (icon tab bar).

text

text_field

title

toggle

url_field

A URL-keyboard field (FieldKind::Url).

video_player

A controllable native video player for url (remote MP4/HLS or a local file URI), rendered with the native player per platform (AVPlayer / Media3 ExoPlayer / <video>). id routes the ~once-per-second position into input(id, InputValue::Int(position_ms)); build it fresh each render with the current playing (play/pause) + seek_to_ms (the shell jumps when this CHANGES; -1 = no seek). on_ended fires when the clip finishes. Defaults: controls shown, not looping/muted, no poster, no resume offset, no captions, rate 1.0, full volume, single clip (no playlist), PiP off — tune with with_loop/with_muted/without_controls/with_poster/with_start_at/with_captions/ with_rate/with_volume/with_pip (or video_playlist for a queue). Give it room.

video_playlist

A controllable native video player over a playlist of urls (auto-advances gaplessly; the shell reports the current track via input("{id}.index", InputValue::Int(i))). start_index is the first clip; build it fresh each render with the current playing. Force-jump to a track by pairing this with with_seek_index. on_ended fires when the LAST clip finishes. Same cosmetic modifiers as video_player. Empty urls renders nothing useful — use video_player for one clip.

web_view

A native web view showing the page / embedded player at url (WKWebView / Android WebView / <iframe>). General-purpose: docs, dashboards, or a hosted player embed (e.g. a Bunny.net / YouTube embed URL). NOT the default video player — use video_player for that. Give it room (a sized container or a card).

with_bracket

Attach a right-side bracket annotation to a region_chart (no-op on any other widget).

with_captions

Attach subtitle/caption tracks to a video_player (see Caption). No-op on non-Video widgets.

with_error

Attach an inline validation message to a Widget::TextField, marking it invalid. No-op on any other widget.

with_fab

Anchor a floating action button over a scaffold’s body (the raised primary action). No-op on any other widget: with_fab(scaffold(...), Icon::Add, Msg::New).

with_loop

Loop a video_player (restart on end). No-op on non-Video widgets.

with_muted

Start a video_player muted (needed for reliable autoplay). No-op on non-Video widgets.

with_pip

Enable Picture-in-Picture on a video_player (the shell adds a PiP affordance). No-op otherwise.

with_poster

Show poster (an image URL) before the first play / while idle. No-op on non-Video widgets.

with_rate

Set playback speed (1.0 = normal) on a video_player. No-op on non-Video widgets.

with_refresh

Enable pull-to-refresh on a scaffold’s body: the body becomes pull-refreshable and fires on_refresh on pull. refreshing is app-owned — set it true when the pull fires and clear it when the async reload completes (the shell shows a spinner while true). No-op on other widgets.

with_seek_index

Force a playlist video_playlist to jump to track index when this CHANGES. No-op otherwise.

with_sheet

Open a modal bottom sheet over a scaffold’s body. No-op on any other widget — drive it from the model: with_sheet(scaffold(...), title, sheet_body, Msg::CloseSheet).

with_start_at

Resume a video_player at start_at_ms (applied once on load). No-op on non-Video widgets.

with_theme

Apply a Theme to a scaffold (brand color, corner, density, font). No-op on any other widget. Lets an app brand its UI without new scaffold builder overloads: with_theme(nav_scaffold(...), Theme { seed, ..Default::default() }).

with_volume

Set the volume (0.0–1.0) on a video_player. No-op on non-Video widgets.

without_controls

Hide the native transport controls on a video_player (the app drives it). No-op otherwise.