Module api 

The app-facing api feature: builders returning impl View<State> compositions over the platform-agnostic controls/runtime/events machinery crate already carries — the facade-glue half of this crate that sanctions depending on frust.

Feature-gated, not the crate’s default shape

Everything under this module compiles ONLY behind the default-on frust-api feature — cargo check -p frust-native-widgets --no-default-features must still hold the platform-plugin charter line (frust-plugin + FFI crates only, docs/ARCHITECTURE.md’s Module Structure): no frust/frust-core dependency reaches the crate at all with the feature off. See Cargo.toml’s comment on why this crate keeps frust-core alongside frust under the same gate (a downstream View impl needs BuildCtx/ChangeFlags, which the frust facade does not re-export).

The internal NativeWidget trait is still not the public one

Every builder in [builders] is a plain data struct implementing frust_core::Component (frust-core’s retained-local-state seam) — never the crate’s own pub(crate) [crate::runtime::NativeWidget] trait, which stays internal permanently.

The public form is a different trait entirely: crate::component::NativeComponent, with &self methods, already-typed Props the app constructs directly, no decode_props step and no Result returns. The eleven builders here keep riding the internal trait’s wire (params_json in, EventPayload callbacks out) unchanged — bridging the public trait onto the same runtime (crate::component::Bridge) is what let that stay true.

Two builder families, one slot shape

The eleven built-in controls above are one family (native_segmented/ native_stepper on iOS/macOS only and native_tab_bar on iOS only — a compile-time refusal banner elsewhere; native_date_picker on all three arms, reporting a CivilDate); native_component is the generic one, mounting any registered NativeComponent (another plugin’s included — an app crate cannot implement one; see that trait’s own doc) into the same single platform_view slot, reusing the eight’s own factory constant, slot counter, sizing rule and refusal placeholder. It is what closes define → register → mount; the eight are deliberately not rewritten to route through it (see src/api/mount.rs’s module doc).

One platform_view slot per control

Each builder composes exactly one frust::platform_view slot resolving to this crate’s one Android factory (dev.frust.nativewidgets.FrustNativeControlFactory) — N controls = N slots, within the differ’s design envelope (a shared-container optimization is future work).

Native presentations — not a slot

show_native_alert / show_native_alert_into and show_native_sheet / show_native_sheet_into are the app-facing front door to crate::present: an alert or a sheet is an imperative request answered by one outcome, never a platform_view slot (nor does a sheet host one — its content is a constrained native schema). The _into forms write that outcome into an RwSignal, the same events-as-signals idiom the builders’ on_... callbacks follow, spawned on frust::spawn_local.

Theme ladder L2

Each builder’s Component::build reads the active theme (use_context::<Theme>()) and folds it, via [theme::resolve], into the same params_json body every other property already rides — see [theme]’s module doc for the mapping table and crate::android::theme for L1 (the night-qualified Context control creation builds against).

Structs

CivilDate

The date value native_date_picker shows and reports — defined beside the control (crate::controls::date_picker) because the platform-agnostic event vocabulary carries it too, and re-exported here as the builder’s public vocabulary. A calendar date — year, month, day — with no time of day and no time zone: what a native date picker shows and what its change handler reports.

NativeButtonView

A real android.widget.Button rendered from pure Rust — see the module docs. Build one with native_button.

NativeComponentView

One mounted NativeComponent — build it with native_component.

NativeDatePickerView

A real DATE-mode picker (no time) rendered from pure Rust — android.widget.DatePicker, UIDatePicker, NSDatePicker. Controlled, like NativeSwitchView: the app owns date, and a pick only ever arrives through Self::on_change as a requested CivilDate the app confirms by feeding it back. Build one with native_date_picker.

NativeImageView

A real android.widget.ImageView rendered from pure Rust, showing app-supplied encoded bytes (PNG/JPEG/WebP — whatever BitmapFactory reads). Display-only (no listener, no .interactive()). Build one with native_image.

NativeLabelView

A real android.widget.TextView rendered from pure Rust — display-only (no listener, no .interactive()). Build one with native_label.

NativeProgressView

A real android.widget.ProgressBar rendered from pure Rust — display-only (no listener, no .interactive()). Build one with native_progress.

NativeSegmentedView

A real segmented control rendered from pure Rust — UISegmentedControl on iOS/iPadOS, NSSegmentedControl on macOS, and a frust-drawn refusal banner everywhere else (Android included: see [SEGMENTED_ARM]). A controlled component, like NativeSwitchView: the app owns selected, and a tap only ever arrives through Self::on_select as a requested index. Build one with native_segmented.

NativeSliderView

A real android.widget.SeekBar rendered from pure Rust — controlled, like NativeSwitchView: the app owns value, and a drag only ever arrives through Self::on_change as a requested value. Build one with native_slider.

NativeSpinnerView

A real indeterminate activity indicator rendered from pure Rust — display-only (no listener, no .interactive()). Build one with native_spinner.

NativeStepperView

A real increment/decrement control rendered from pure Rust — UIStepper on iOS/iPadOS, NSStepper on macOS, and a frust-drawn refusal banner everywhere else (Android included: see [STEPPER_ARM]). A controlled component, like NativeSliderView: the app owns value, and a tap on either button only ever arrives through Self::on_change as a requested value. Build one with native_stepper.

NativeSwitchView

A real android.widget.Switch rendered from pure Rust — a controlled component (docs/CODE_STANDARDS.md’s Interaction Semantics): the app owns checked, and a user toggle only ever arrives through Self::on_toggle as a requested value. Build one with native_switch.

NativeTabBarView

A real, bare UITabBar on iOS/iPadOS — a controlled bottom tab bar that never navigates by itself: a tap reports the requested TabId through Self::on_select, the app routes (typically RouteNavigator::go) and feeds the confirmed id back as selected on the next build. A tap on the tab already showing reports through Self::on_reselect instead (“scroll to top / pop to root”). macOS and Android (and every host target) render a frust-drawn refusal banner. Build one with native_tab_bar.

TabId

A tab’s stable, app-chosen identity — what native_tab_bar’s selected names and what NativeTabBarView::on_select/ NativeTabBarView::on_reselect report. Never an index: reordering or inserting items keeps every id meaning the same tab.

TabItem

One tab of a native_tab_bar: a stable TabId, a title, an icon, and optionally a selected-state icon, a badge and a disabled state.

Enums

NativeDatePickerStyle

How NativeDatePickerView presents itself — the public mirror of crate::controls::date_picker::DatePickerStyle, which stays pub(crate).

NativeImageFit

How a NativeImageView scales its bytes into the slot’s box — the public mirror of crate::controls::image::Fit, which stays pub(crate).

NativeSpinnerSize

How large the spinner renders — the public mirror of crate::controls::spinner::SizeClass, which stays pub(crate). iOS has no distinct small style (UIActivityIndicatorView.Style offers only .medium/.large), so Self::Small renders the same as Self::Medium on that one arm — see crate::controls::spinner’s module doc.

TabIcon

A tab’s icon: encoded image bytes, or an Apple SF Symbol name — never an arbitrary string passed off as a cross-platform icon (the bar is iOS-only, and a symbol name means nothing anywhere else).

Functions

ensure_native_factory_registered

Make sure this build’s platform factory exists before the host can look it up — optional: every builder already does this for you.

live_slot_count

The number of native controls this crate’s internal runtime currently retains — the leak bar registry::Registry::live_count’s own doc comment describes (“the number the leak bar every create/dispose cycle must return to 0”), surfaced app-side for exactly one reason: a device-gate harness (a mount/unmount cycler plus a 50-slot stress toggle, examples/native-widgets-demo/src/pages/stress.rs’s GATE HARNESS section) needs an in-app readout to prove the teardown-retire path disposes promptly rather than waiting out the differ’s missing-streak backstop (crate::registry’s module doc’s Idle-deferred dispose finding).

native_button

A native Button captioned text — see NativeButtonView.

native_component

Mount the registered NativeComponent C as one native slot, driven by props.

native_date_picker

A native date picker showing date — see NativeDatePickerView.

native_image

A native Image showing bytes — see NativeImageView.

native_label

A native Label showing text — see NativeLabelView.

native_progress

A native ProgressBar at value, ranging over [min, max] — see NativeProgressView.

native_segmented

A native segmented control over labels, with the app-owned selected segment — see NativeSegmentedView. An out-of-range selected shows no selection rather than failing; at most 64 segments are shown (crate::controls::segmented::MAX_SEGMENTS).

native_slider

A native Slider at value, ranging over [min, max] — see NativeSliderView.

native_spinner

A native spinner, animating or not — see NativeSpinnerView.

native_stepper

A native Stepper at value, ranging over [min, max] — see NativeStepperView.

native_switch

A native Switch at the app-owned checked state — see NativeSwitchView.

native_tab_bar

A native bottom tab bar over items, with the app-owned selected tab — see NativeTabBarView. A selected id no item carries shows no selection; duplicate ids resolve to the first item carrying them; at most 16 items are shown (crate::controls::tab_bar::MAX_ITEMS).

show_native_alert

The app-facing native-presentation entry points over crate::present: for an alert and for a sheet, an awaitable form and an events-as-signals form — see the present submodule doc. The app-facing native-presentation entry points over crate::present: for an alert and for a sheet, an awaitable form and an events-as-signals form — see the present submodule doc. The app-facing native-presentation entry points over crate::present: for an alert and for a sheet, an awaitable form and an events-as-signals form — see the present submodule doc. Present a native alert and await its one outcome.

show_native_alert_into

The app-facing native-presentation entry points over crate::present: for an alert and for a sheet, an awaitable form and an events-as-signals form — see the present submodule doc. The app-facing native-presentation entry points over crate::present: for an alert and for a sheet, an awaitable form and an events-as-signals form — see the present submodule doc. The app-facing native-presentation entry points over crate::present: for an alert and for a sheet, an awaitable form and an events-as-signals form — see the present submodule doc. Present a native alert and write its one outcome into signal as Some(outcome) — the no-async form (module doc’s Controlled).

show_native_sheet

The app-facing native-presentation entry points over crate::present: for an alert and for a sheet, an awaitable form and an events-as-signals form — see the present submodule doc. The app-facing native-presentation entry points over crate::present: for an alert and for a sheet, an awaitable form and an events-as-signals form — see the present submodule doc. The app-facing native-presentation entry points over crate::present: for an alert and for a sheet, an awaitable form and an events-as-signals form — see the present submodule doc. Present a native sheet and await its one outcome.

show_native_sheet_into

The app-facing native-presentation entry points over crate::present: for an alert and for a sheet, an awaitable form and an events-as-signals form — see the present submodule doc. The app-facing native-presentation entry points over crate::present: for an alert and for a sheet, an awaitable form and an events-as-signals form — see the present submodule doc. The app-facing native-presentation entry points over crate::present: for an alert and for a sheet, an awaitable form and an events-as-signals form — see the present submodule doc. Present a native sheet and write its one outcome into signal as Some(outcome) — the no-async form, with exactly show_native_alert_into’s contract (module doc’s Controlled): synchronous refusals come back as Err and never touch signal; a later platform error is logged, not written.