Crate whisker 

Whisker

Cross-platform mobile UI framework for Rust, built on the Lynx C++ engine.

Most users only need prelude:

use whisker::prelude::*;

#[whisker::main]
fn app() -> Element {
    render! {
        page(style: "background: white;") {
            text(value: "Hello, Whisker")
        }
    }
}

What’s in this crate

The whisker crate is an umbrella — almost everything here is a re-export from a more specialised companion crate, surfaced through a single import root so app code never needs to know which inner crate owns which symbol. The conceptual groupings:

• Macros (component, main, module_component, render) — proc macros that lower component definitions and the render! { … } DSL into builder chains over the items in [__tags].
• Reactive primitives — signal(), computed(), effect(), on_cleanup, on_mount, provide_context, use_context, resource(), and their handle types (Signal, ReadSignal, RwSignal, Resource, …).
• Async — spawn_local, run_blocking, run_on_main_thread.
• Control flow — [ForEach] (keyed list), [Show] (conditional). Both are written as ordinary #[component] functions.
• CSS — the css type-safe builder + the css! macro.
• Built-in elements — view, text, scroll_view, list, page, raw_text, fragment. The render! macro lowers each tag invocation into a builder chain on the corresponding struct in [__tags]; the [__tags::ElementBuilder] trait provides the shared style / class / on_<event> / … methods.
• Platform bridges — PlatformModule + module! for function-shaped native modules, ElementRef for imperative methods on mounted components, ElementHandle et al for the typed return values.
• Typed attribute enums — see attrs for the closed-set string attributes (attrs::ScrollOrientation, etc.).

Everything intended for direct user code is also pulled into prelude; reaching into the long paths is only necessary when writing framework-level extension code.

Re-exports

pub use whisker_config as config;

pub use whisker_runtime as runtime;

pub use whisker_css as css;

Modules

arc_signal

Refcount-backed signal primitives — the Arc* family.

attrs

Typed enums for built-in element attributes whose Lynx-side contract is a closed set of strings.

computed

Derived (computed) values.

effect

Side-effecting reactive computation.

event

Typed event objects handed to on_<event> handlers on built-in elements and #[whisker::module_component] view methods.

owner

Owner / scope API surface.

platform_module

Whisker platform module invocation entry point.

prelude

Common imports for Whisker app code.

resource

Async-data primitive — runs an async fetcher on Whisker’s single-threaded task pool (crate::tasks) and exposes the loading / ready / error state through a [ReadSignal]-shaped handle.

signal

Signal primitives: ReadSignal, WriteSignal, RwSignal, and the signal constructor.

Macros

module

Build a PlatformModule handle for the native module named $name, with the calling crate’s name prepended (<crate>:<$name>) so two crates can ship same-named modules without colliding in the dispatch registry. env!("CARGO_PKG_NAME") resolves in the calling crate, so the prefix is always the crate that wrote the module!(...) call.

render

Fine-grained renderer macro. Emits imperative element-creation code that calls into [whisker::runtime::view] through the thread-local installed renderer, and returns an [Element].

Structs

AnimateOptions

Typed timing options for animate_start.

ArcReadSignal

Refcount-backed read-only handle. Clone-cheap (Rc bump), !Copy. The companion to ArcRwSignal::read_only.

ArcRwSignal

Refcount-backed combined read/write signal.

ArcWriteSignal

Refcount-backed write-only handle. Clone-cheap (Rc bump), !Copy. The companion to ArcRwSignal::write_only.

BoundingClientRect

Result of ElementHandle::bounding_client_rect — the element’s layout box in LynxView coordinates (Lynx’s boundingClientRect UI method). Every field is #[serde(default)], so any key the platform omits reads back as 0.0 rather than failing the decode.

EachFn

Fn() -> Vec<T> — the “what items to render” closure for a keyed-list control flow. Wrapping in a newtype gives typed-builder a concrete Props field type plus an Into path from any matching closure literal.

Element

The return type of a #[component] / #[whisker::main] function — an opaque handle to a mounted view subtree. Re-exported at the crate root (and in the prelude) so component signatures read -> Element without an internal runtime::view import. Backend-agnostic element handle. Copy so it threads through reactive closures without lifetime gymnastics.

ElementHandle

Imperative handle to any mounted element — the generic Lynx UI methods that work regardless of tag. Allocate with ElementHandle::new, bind via view(ref: handle.r()) (or text, page, …) in render!, then call the methods below.

ElementRef

Framework-internal handle to a mounted platform element. Lives in #[module_component]-emitted prop tables and the wrapping #[component]s that drive a Handle. Not part of an app-author’s surface — Handles wrap this.

Fallback

The fallback branch of a show-style conditional. Wraps an optional Fn() -> Element closure — None means “render nothing on false”; Some(closure) is what the user typed as fallback: || ….

ForEachProps

ItemFn

Fn(T) -> Element — the “render one item” closure for a keyed-list control flow. The returned Element is what gets attached to the surrounding fragment / list.

KeyFn

Fn(&T) -> K — the “key extractor” closure for a keyed-list control flow. Items whose keys match across reactive reruns reuse their owners + per-item state.

Owner

Identifier for an Owner slot in the runtime’s owner map. Generational — disposing an owner invalidates outstanding Owners pointing at the same slot index.

PlatformModule

A handle to a native Whisker (function-only) module, identified by its fully-qualified name (<crate>:<Name>).

ReadSignal

Read-only signal handle. Copy; safe to clone freely and move into closures.

Resource

Copy handle to a deferred value. Wraps an RwSignal whose slot the worker thread writes into once the fetch completes; consumer code reads through the accessors below.

RwSignal

Combined read-write signal handle. Equivalent to holding both a ReadSignal<T> and WriteSignal<T> for the same underlying node.

ScrollInfo

Result of ScrollViewHandle::get_scroll_info — the current scroll offset and scrollable range of a <scroll-view> (Lynx’s getScrollInfo UI method). Every field is #[serde(default)], so whichever subset the platform’s scroll UI reports populates and the rest read back 0.0: UIScrollView fills scroll_x/scroll_y/scroll_range; the internal scroller fills scroll_x/scroll_y plus scroll_width/scroll_height.

ScrollViewHandle

Imperative handle to a mounted <scroll-view>. Allocate with ScrollViewHandle::new, bind via scroll_view(ref: handle.r()) in render!, then query scroll state.

ShowProps

StoredValue

A non-reactive, owner-bound value slot. Copy.

TextBoundingRect

Result of TextHandle::get_text_bounding_rect — the layout boxes of a <text> substring (Lynx’s getTextBoundingRect). bounding_rect is the union box covering [start, end); boxes is the per-line box list. All rects are in LynxView coordinates (same shape as BoundingClientRect).

TextHandle

Imperative handle to a mounted <text>. Allocate with TextHandle::new, bind via text(ref: handle.r()) in render!, then drive / read text selection.

UiInfo

Result of ElementHandle::request_ui_info — the element’s id, layout box, size, and scroll offset in one call (Lynx’s requestUIInfo, requesting the id / rect / size / scrollOffset fields). Every field is #[serde(default)], so whichever the platform reports populates and the rest read back empty / 0.0. (rect + size overlap BoundingClientRect; scroll_left / scroll_top overlap ScrollInfo — requestUIInfo just bundles them.)

WhenFn

Fn() -> bool — the predicate closure for a show-style conditional control flow. Wrapping in a newtype gives typed-builder a concrete Props field type plus an Into path from any matching closure literal.

WriteSignal

Write-only signal handle. Copy. Setting or updating notifies all subscribers; the notifications are enqueued (not run synchronously) to support batched event-handler semantics — call flush to drain.

Enums

AnimateOp

Lynx-side animation lifecycle operations exposed by Element::Animate. Matches JavaScriptElement::AnimationOperation in the Lynx fork — same numeric values, same semantics.

ElementTag

Element tag. Numeric repr stays in sync with WhiskerElementTag in crates/whisker-driver-sys/bridge/include/whisker_bridge.h.

RefError

Errors that can surface from imperative element-method dispatch.

ResourceState

Three-state machine the Resource cycles through. Clone so reads inside effects can take owned copies without borrowing the underlying signal slot.

Signal

Prop value: either a static T or a reactive ReadSignal<T>.

Style

Value the style: builder method receives. One of the two variants below.

WhiskerValue

The universal tagged-union value model. Crosses the native boundary as both module args/returns and event payloads, so it lives at the crate root rather than buried under platform_module (where it’s also re-exported for back-compat). Tagged-union variant set passed between Rust and the platform side — module args/returns and event payloads alike.

Functions

animate_cancel

Cancel a running named animation — drops styles, clears state.

animate_start

High-level wrapper around invoke_element_animate for the START operation: starts a named animation with explicit keyframes + timing.

apply_style

Apply a Style to a Lynx element. The Static branch sets the inline-styles attribute once; the Dynamic branch wraps the closure in an effect so it re-applies whenever any signal it reads fires.

arc_signal

Allocate a fresh Arc-backed signal and split into read/write halves. The Arc analog of signal:

computed

Create a computed (derived) value. f is run once immediately to seed the cache, then re-run whenever a tracked source changes.

effect

Register f as a reactive effect. Returns the node id (so tests can inspect it; user code generally discards the return value).

flush

Drain the pending queue, re-running effects and computeds in the order they were scheduled. Skips entries whose node has been disposed.

invoke_element_animate

Element-level animation dispatch — wraps lynx_element_animate via whisker_bridge_element_animate.

on_cleanup

Register a callback to run when the current owner is disposed. Calls accumulate in LIFO order, mirroring Solid / Leptos onCleanup semantics.

on_mount

Register f as a post-mount callback for the current owner. Fires once on the next flush_mounts call (driven by the renderer after the component’s view is appended to its parent).

provide_context

Provide a context value in the current owner. Subsequent use_context::<T> / with_context::<T> calls inside this owner or any descendant find this value (unless a closer descendant shadows it).

resource

Reactive async fetch. Drives fetcher (an async fn or async move {…} block) on Whisker’s task pool and writes the resolved Result into the returned Resource’s signal — then re-runs the fetcher whenever any signal it read changes.

resource_sync

Synchronous-fetch variant. Runs fetcher inline on the calling thread and writes the result directly into the resource’s signal. No worker thread, no main-thread dispatcher needed — useful for tests, for cases where the value is already in memory, and for computed pseudo-resources (e.g. derive from a context value).

run_blocking

Offload a synchronous closure to a fresh worker thread and return a future that resolves once the closure completes.

run_on_main_thread

Marshal a closure onto the main (Lynx) thread.

signal

Allocate a fresh signal in the current owner. Returns a (ReadSignal, WriteSignal) pair — Solid-style separation.

spawn_local

Queue future for execution on Whisker’s task pool.

use_context

Look up the nearest provided context of type T, returning a clone. Returns None if no ancestor owner provides one.

with_context

Look up the nearest provided context of type T and run f with a borrow of it. Returns None if no ancestor owner provides one.

Type Aliases

Children

Type used by #[component] for the conventional children prop. The render! macro routes a component invocation’s non-kwarg children into a move || View::Fragment(…) closure of this type; the component body invokes it to materialise the children at the point in the tree where they should appear.

Attribute Macros

component

Mark a function as a Whisker reactive component.

main

Annotates the user’s app function (returning whisker::Element) and generates the FFI symbols the iOS/Android host expects.

module_component

Declare a Whisker-side wrapper for a Lynx-registered view module’s element.