Documentation

Rust API overview

The part of the Rust authoring layer most apps need, which layer to use, and where the examples live. Version 0.1.0; signatures can still change.

This page covers the part of the Rust API that most apps need. It describes the authoring layer, aster_blueprint::ui, which is what the tutorials and the examples use. The full reference is the rustdoc of the crates and the guide rust/crates/aster-blueprint/docs/UI.md in the SDK. Nothing here is a frozen 1.0 API: the crates are version 0.1.0 and signatures can still change.

Which layer do I use?

You wantUseWhere
A window or a browser canvas from Rustthe authoring layer aster_blueprint::ui plus a hostrust/crates/aster-blueprint, native/ui-host, web/aster-web
An app in any language, described as JSONthe C ABInative/runtime (C ABI reference)
Pixels only, no widgets: rectangles, text runs, vectors, imagesthe renderer core aster_uirust/crates/aster-ui

Start with the authoring layer. The renderer core is what the authoring layer is built on; reach for it only when you are building your own toolkit on top of CPU pixels.

Five types that cover most of it

TypeWhat it is
ElOne element of the screen: text, a column, a card, a chart. You build trees of them with plain functions and chain modifiers.
StoreYour app state: named values (bool, integer, float, text, lists, records). The screen is a function of it.
ActionWhat an element does when activated: set, toggle or increment a state key, push to a list, copy text, change theme. Several can be combined with Action::seq.
ThemeA set of design tokens: colours (Role), type scale (Type), spacing, radii. The same tree re-renders under any theme.
AppThe running app. It owns the scene, layout and interaction state. A host (a window, a browser canvas, a test) feeds it input and takes its pixels.

The one import that brings in all of them:

Rust
use aster_blueprint::ui::prelude::*;

The loop

  1. Write fn screen(s: &Store) -> El. It reads state and returns a tree. It is called again after every change, so it must be pure.
  2. Create App::new(&theme, store).size(w, h).screen(screen)?. (screen takes impl Fn(&Store) -> El + 'static, so it cannot borrow locals: use a plain fn, or move owned data in.)
  3. Give the app to a host: app.run_window_with(Options { .. }.from_env()) opens a native window, Rendered frames go to a canvas in a browser, and for tests you drive it headless.

A complete interactive example (state, an element with an action, headless driving, a window), checked in this documentation pass:

Rust
use aster_blueprint::ui::prelude::*;
use aster_native::{Options, RunWindow};

fn screen(s: &Store) -> El {
    col([
        text(format!("Count: {}", s.int("count"))).style(Type::Headline),
        text("Add one").pad(3).fill(Role::Accent).color(Role::OnAccent)
            .radius(Radius::Md).id("add").role("button")
            .a11y_label("Add one").focusable()
            .on_click(Action::inc("count", 1)),
    ]).gap(3).pad(6)
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let store = Store::new().with("count", 0i64);
    let mut app = App::new(&Theme::paper_dark(), store).size(480, 260).screen(screen)?;
    if std::env::args().any(|a| a == "--headless") {
        app.click_id("add")?;
        app.click_id("add")?;
        app.settle()?;
        println!("count = {}", app.store().int("count"));
        app.write_png("docs_counter.png")?;
        return Ok(());
    }
    app.run_window_with(Options { title: "Counter".into(), ..Options::default() }.from_env())
}

Source: native/ui-host/examples/docs_counter.rs, on a review branch (not in the main source yet).

The 20% you use every day

Layout

FunctionUse
col([..]), row([..])vertical and horizontal stacks. A col stretches children; a row centres them (change with .align(..)).
grid(n, items), grid_tracks(..)equal columns, or tracks such as Track::Px(240.) and Track::Fr(1.).
wrap([..])flowing chips and tags; reports its full multi-line height.
overlay([..])layers; pin one with .place(Align::End, Align::Start).
scroll(child)a scrolling region.
spacer()flexible space in a row.

Modifiers: .gap(n), .pad(n), .w(px), .h(px), .grow(f), .align(..), .fill(Role::..), .radius(Radius::Md), .elevation(0..=4).

Numbers are theme steps. gap(3) and pad(6) index the theme's spacing scale (0, 2, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64 px), not raw pixels. Raw pixels have their own names: .w(px), .h(px), .pad_px(px), .gap_px(px), .font_px(px).

Text

  • text("Hi") is a one-line label that never wraps. Style it: .style(Type::Headline), .muted(), .bold(), .mono().
  • paragraph(long) (or text(s).wrap_fit()) wraps to the width it is given, using real font measurement. Clamp with .max_lines(3).
  • Fonts are the bundled ones. Without the native-fonts feature, rendering returns UiError::NativeFontsRequired.

Controls and state

Controls take the Store and a key. The key is the state name they read and write.

FunctionState it manages
text_field(s, "name", "placeholder")text
switch(s, "key", "Label"), checkbox(..)bool
slider(s, "key", min, max, step)number
select(s, "key", &[("id", "Label")], "placeholder")the chosen id
tabs(s, "key", &[("id", "Label")])the selected tab
dialog(s, "key", title, body, actions)open or closed
list(..), list_keyed(..)a virtualised list (only visible rows are built)

Any element becomes interactive with .id(".."), .role("button"), .focusable(), .a11y_label("..") and .on_click(Action::..). Common actions: Action::set("saved", true), Action::toggle("open"), Action::inc("count", 1), Action::push(..), Action::set_theme("paper_light"), Action::seq([..]). .selected_if(|s| ..) and .disabled_if(|s| ..) tie an element's look to state.

Components

Ready-made pieces: card, panel, heading, stat, badge, chip, meter, table, kv_list, app_bar, nav, avatar, progress_bar, skeleton, and the charts (line_chart, bar_chart, area_chart, pie_chart, donut_chart, scatter_chart, sparkline_line). rust/crates/aster-blueprint/docs/COMPONENTS.md and CHARTS.md list them.

Themes

Theme::paper_dark(), paper_light(), mission_dark(), mission_light(), mission_dusk(), high_contrast_dark(), high_contrast_light(). Colours are Role::Accent, Role::Success, Role::TextMuted and so on, never hard-coded values, so a theme switch re-tints everything. app.set_theme(&theme) switches at runtime. Theme::with_reduced_motion(true) honours the reduced-motion preference.

Motion

.animate(Prop::Scale, Transition::ms(300, Ease::Linear)) animates a property when the state it depends on changes. In tests, app.advance(ms) moves the clock by hand, so every in-between frame is reproducible. See tutorial 4.

Responsive layouts

responsive, stack_at, sidebar_layout, drawer, and the Viewport environment model (Device, Orientation, Density) adapt one screen to a phone, a desktop and a TV. See docs/RESPONSIVE.md.

One-shot rendering and testing

You do not need an App to make a picture:

Rust
let root = col([text("Hello").style(Type::Headline), badge("LIVE", Role::Success)]).pad(5);
let shot = Screen::new(&Theme::mission_dark())?.size(480, 240).render(&root)?;
shot.tree.assert_visible("Hello");   // every text and id is registered in the semantic tree
shot.png("hello.png")?;

For interaction tests drive the App headless: click_id, type_text, set, advance, settle, then read app.store(), app.tree() (with audit_a11y()), app.image() or app.write_png(path). This is the same loop the C ABI exposes as aster_app_click, aster_app_type, aster_app_tree and aster_app_shot.

Hosts

HostEntry pointNotes
Native windowaster_native::{Options, RunWindow}, app.run_window_with(options)Linux (X11 and Wayland) and Windows. Options::from_env() reads the host's diagnostic environment variables.
Browser canvasweb/aster-web compiled to wasm32-unknown-unknowna small C ABI (aw_init, aw_step, aw_frame_ptr, ...) exposes the RGBA framebuffer; JavaScript copies it to a canvas. Single-threaded.
HeadlessApp::write_png, Screen::renderno display needed: tests, docs images, video frames.
Any languagenative/runtime C ABIJSON in, JSON events out.

Where the examples are

ExampleShows
Tutorials 1 to 5 (native/ui-host/examples/tutorial_*.rs, web/aster-web/examples/tutorial_web.rs)hello window, layout and text, forms and accessibility, animation, wasm in the browser. They ship on the documentation branch that adds the Learn section; the site's Learn pages carry the full source.
native/ui-host/examples/docs_counter.rs (this page; on a review branch)the smallest interactive loop
native/ui-host/examples/settings_app.rsa settings screen with real controls
rust/crates/aster-blueprint/examples/ (start_dashboard, start_form, start_list_detail, settings_app, team_chat, library_browser, ops_dashboard)the three starters and whole apps built from the kit; the examples folder has the full table
native/runtime/samples/*.jsonthe same ideas as JSON views for the C ABI and the aster tool

Honest limits

  • The layer is 0.x: names and signatures can change before 1.0.
  • The browser build is single-threaded and the tutorial canvas is a framebuffer only. Input, text entry, IME and accessibility need a host bridge on the web; the SDK's interactive web demo (web/aster-web/demo/) is the reference adapter.
  • Performance depends on the scene and the machine. This page makes no performance claims; measured numbers are published separately with their method.