Introduction

API status: Code examples in this book fall into two categories. Tutorial and component-reference examples use the current Bevy/Beverly API and should compile. .header(...), .body(...), and .footer(...) are implemented content-section helpers on the supported fluent containers. Architecture and design-vision examples may still use application-owned conceptual names such as Command::...; those are not additional built-in DSL syntax.

Beverly

What is Beverly?

Beverly is a UI framework written in Rust and built on top of the Bevy game engine.

It is designed for applications where the UI needs to be fast, local, data-heavy, and increasingly intelligent.

Beverly provides a native application runtime with:

• Small binary size
• Low resource overhead
• Fast, near-instant startup
• High-performance rendering
• Smooth 60 FPS interaction
• Local and offline execution
• Strong compile-time guarantees from Rust
• A UI architecture designed for both humans and AI agents

Beverly is not a web browser wrapped around an application. It is a UI runtime you can ship directly inside the product.

The UI for AI

AI changes what a UI needs to be.

Traditional UI frameworks were designed primarily around a human sitting in front of a screen: click a button, fill out a form, navigate a page.

AI introduces another kind of user.

An agent can inspect application state, choose actions, invoke tools, respond to events, and operate an application alongside a human.

Beverly treats AI as a first-class participant in the application, rather than bolting an AI API onto an existing UI framework.

The same application events can be produced by:

• A human clicking a button
• A keyboard shortcut
• Another application
• An API
• An AI agent

This creates a common application language shared by humans and machines.

The UI is no longer just something an AI controls. It becomes part of the interface through which AI and humans work together.

Why Rust + Bevy?

Beverly combines Rust’s systems programming model with Bevy’s high-performance rendering architecture.

Rust

Rust provides:

• Memory safety without a garbage collector
• Strong ownership and borrowing guarantees
• Compile-time type checking
• Predictable resource usage
• Safe concurrency
• Explicit application state and data flow

For an AI application, these properties have another advantage: the UI consumes fewer resources that could otherwise be used by the application and its models.

Bevy

Bevy provides a high-performance foundation for:

• Rendering
• Animation
• Input
• Windows
• Assets
• GPU acceleration
• Cross-platform applications

Beverly builds the application UI layer on top of that foundation.

The goal is simple:

Use the game engine to build the application runtime, not a game.

Small Runtime, Large Surface Area

A UI framework shouldn’t require a massive runtime just to render a button, a dashboard, or a data table.

Beverly aims to provide a surprisingly small runtime while still supporting the components required by serious applications.

That means:

• Small binaries
• Low memory overhead
• Fast startup
• Efficient rendering
• Minimal runtime dependencies
• Components for complex applications

The result is a UI runtime that can scale from a desktop application to a constrained device without bringing an entire browser stack along with it.

Local-First, Offline, Sovereign

Beverly applications run locally.

They don’t require:

• A browser
• A remote UI server
• A CDN
• Telemetry infrastructure
• A permanent internet connection

This makes Beverly well suited to applications where data sovereignty, privacy, reliability, or deployment constraints matter.

Applications can run:

• Offline
• On private networks
• In air-gapped environments
• On dedicated devices
• Inside enterprise infrastructure
• Alongside local AI models

Your UI can live where your data lives.

Human + AI Interaction

Beverly does not create a separate interface for AI.

Instead, humans and agents interact with the same application primitives.

A button might emit:

#![allow(unused)]
fn main() {
Event::Document::Save
}

A keyboard shortcut can emit the same event.

An API can emit the same event.

An AI agent can emit the same event.

The Controller routes that event to application behavior, while the Model owns the underlying state.

This gives the application a single, explicit vocabulary that both humans and machines can understand.

Rewindable AI

When application behavior is represented as explicit Events, AI actions don’t have to disappear into an opaque execution log.

The application can record the sequence of events, the resulting state transitions, and the relevant context around an agent’s actions.

That makes AI behavior observable, rewindable, and replayable.

A human can inspect what the agent did:

User::Open(8472)
    ↓
Document::Read(8472)
    ↓
Document::Summarize(8472)
    ↓
Document::Create("Quarterly Report")
    ↓
Document::Save(9124)

They can then replay the sequence to understand what happened, inspect individual decisions, or rewind the application to an earlier point.

This creates a fundamentally different relationship between humans and AI:

The AI doesn’t just act. Its actions become part of the application’s observable history.

Instead of asking “What did the AI do?”, the application can show you.

Instead of asking “Why is the application in this state?”, you can trace the events that produced it.

And instead of treating AI behavior as something that happened somewhere inside an opaque model, Beverly makes the application-level consequences of that reasoning inspectable and reproducible.

This is the foundation for AI visibility: humans remain able to observe, understand, rewind, and replay what their AI systems are doing.

Design Philosophy

Beverly is built around a few core principles.

Explicitness over magic

The implementation can be sophisticated. The application API should remain understandable.

Magic in implementation. Explicitness at the API.

Ordinary Rust whenever possible

If something can be solved cleanly with ordinary Rust, Beverly should not introduce another abstraction for it.

Model, View, Controller, Events

Beverly uses a lightweight MVC architecture:

• Model — owns application state and behavior
• View — represents and renders the UI
• Controller — connects application events to behavior
• Events — define the application’s vocabulary and contracts

Events provide the connection between the UI, application logic, external systems, and AI agents.

Composition over complexity

Beverly components should be small, composable primitives.

#![allow(unused)]
fn main() {
card()
    .padding(16)
    .radius(12)
    .children([
        text("Hello"),
        button().text("Save"),
    ])
}

The goal is to make applications easy for both humans and AI systems to understand and construct.

When to Use Beverly

Beverly is particularly well suited to applications where the UI itself is part of the product’s infrastructure.

Consider Beverly when you need:

Local applications

Applications that should run directly on the user’s machine or device.

Resource-constrained environments

Applications where CPU, memory, storage, startup time, or bandwidth matter.

Data-heavy interfaces

Applications dealing with:

• Large datasets
• Streaming data
• Data visualization
• High-frequency updates
• Tables and grids
• Telemetry
• Scientific or operational data

AI-native applications

Applications where AI agents need to interact with the same state, events, and tools as human users.

Sovereign applications

Applications that need to operate:

• Offline
• Inside private infrastructure
• In air-gapped environments
• With sensitive local data
• Alongside local AI models

Dedicated devices

Applications where a browser runtime is unnecessary overhead.

When Not to Use Beverly

Beverly is not intended to replace the web.

A traditional web application may be the better choice when:

• The application is primarily web-based
• Browser deployment is the primary requirement
• HTML and CSS are already a strong fit
• You need the existing web ecosystem
• You want users to access the application without installing anything
• Your application benefits heavily from existing JavaScript libraries and browser APIs

If a conventional web stack solves the problem well, use it.

Beverly exists for the cases where you want something different:

A native, local, high-performance UI runtime designed for data, devices, and AI.

2. Quick Start

Beverly is designed to get you from an empty Rust project to a complete interactive application quickly.

This tutorial builds a tiny application with:

• A reusable Button component
• A Rust Model that owns application data
• A typed Bevy Message
• A Controller plugin connecting the Message to application behavior
• A View that reflects the Model
• Built-in accessibility
• A structure that is straightforward to test

The complete flow is:

View
  ↓
Message
  ↓
Controller
  ↓
Model
  ↓
Application Data
  ↓
View

2.1 Installation

Create a new Rust project:

cargo new hello_beverly
cd hello_beverly

Add Bevy and Beverly:

cargo add bevy
cargo add beverly

Beverly is a Rust crate, so you work with it the same way you work with other Rust dependencies.

2.2 Hello, Beverly

Start with a simple application:

use bevy::prelude::*;
use beverly::prelude::*;

fn main() {
    App::new().ui(my_ui()).run();
}

fn my_ui() -> Ui {
    ui()
        .theme(light_theme())
        .center()
        .children([text("Hello, Beverly!")])
}

That’s a Beverly application.

There is no browser, JavaScript runtime, HTML document, or separate frontend server.

Beverly runs as part of your native Rust application.

App::ui(...) is the primary entry point: it installs BeverlyPlugin, applies the theme, and spawns your Ui tree as the application’s root, so you never need to think in terms of entities, components, or startup systems. ui() returns a Ui, the root composition itself - configure layout, theme, and children before returning it:

#![allow(unused)]
fn main() {
fn my_ui() -> Ui {
    ui()
        .width(percent(100))
        .height(percent(100))
        .theme(dark_theme())
        .children([text("Workspace")])
}
}

2.3 Your First Component

Beverly provides reusable UI primitives.

Create a button:

#![allow(unused)]
fn main() {
button().text("Click Me")
}

The same Button component can be reused throughout your application:

#![allow(unused)]
fn main() {
button().text("Save")
button().text("Cancel")
button().text("Delete")
button().text("Create User")
}

Build a larger interface by composing components:

#![allow(unused)]
fn main() {
App::new()
    .ui(ui().children([button().text("Get Started")]))
    .run();
}

For button content, use .children([ButtonChild::icon(...), ButtonChild::text(...)]). Other Beverly components use the shared ui().children([...]) composition API.

Build a primitive once. Compose and reuse it everywhere.

2.4 Accessibility Is Part of the Component

Accessibility is not an afterthought in Beverly.

It is part of the component contract.

For example, a button gets its accessible name from its text content:

#![allow(unused)]
fn main() {
button().text("Click Me")
}

Beverly treats accessibility as a first-class runtime concern rather than something added during a final QA pass. The button plugin projects the text content into its semantic node; custom content should include a text child so assistive technology has a meaningful name.

The goal is simple:

Accessible by construction, not accessible by cleanup.

This applies to Beverly’s complex UI primitives as well — forms, navigation, dialogs, trees, data interfaces, keyboard interaction, and other components where accessibility cannot be reduced to a single visual label.

Accessibility should be something the framework helps you get right automatically, while still making the important semantics explicit.

2.5 Your First Model

The Model is ordinary Rust.

It owns the application’s underlying data.

You don’t need a separate state-management system just to keep your UI synchronized.

For our application:

#![allow(unused)]
fn main() {
struct AppModel {
    clicks: u32,
}

impl AppModel {
    fn clicks(&self) -> u32 {
        self.clicks
    }

    fn set_clicks(&mut self, clicks: u32) {
        self.clicks = clicks;
    }

    fn increment_clicks(&mut self) {
        self.set_clicks(self.clicks() + 1);
    }
}
}

The important distinction is that the Model owns the data and exposes the operations that make sense for that data.

Getters read it.

Setters and Model methods change it.

The Model can also enforce application rules:

#![allow(unused)]
fn main() {
fn set_clicks(&mut self, clicks: u32) {
    self.clicks = clicks.min(100);
}
}

Now the invariant lives with the data rather than being scattered throughout the UI.

2.6 Your First Message

Messages define the vocabulary of your application.

Declare one:

#![allow(unused)]
fn main() {
event! {
    App::Clicked
}
}

The macro generates a Bevy Message type. Register it explicitly:

#![allow(unused)]
fn main() {
app.add_message::<App::Clicked>();
}

2.7 Connect the Button

Attach an explicit callback to the Button:

#![allow(unused)]
fn main() {
fn click_button(commands: &mut Commands, _button: Entity) {
  commands.write_message(App::Clicked);
}

button()
  .text("Click Me")
  .on("click", click_button)
}

The Button does not emit application messages automatically. The callback is the explicit attachment point; other inputs may write the same message through their own application systems.

2.8 Your First Controller

The Controller connects Messages to behavior:

#![allow(unused)]
fn main() {
controller! {
  AppController {
    App::Clicked => handle_click,
  }
}

fn handle_click(_message: &App::Clicked) {
  // Call the model's domain method here.
}
}

The Controller does not define the Message.

The Message was already defined by event!.

The Controller simply says:

When this Message occurs, run this handler.

This keeps the application’s vocabulary separate from its wiring.

The basic relationship is:

Message = Contract
Controller = Connection
Model = Owner
View = Projection

2.9 The View Reflects the Model

The View reads the current state of the Model:

#![allow(unused)]
fn main() {
text(format!("Clicks: {}", model.clicks()))
}

The View does not own the application’s underlying data.

It projects the current Model state into the UI.

The relationship is straightforward:

Model changes
      ↓
View reads current state
      ↓
Bevy updates/rendering
      ↓
UI reflects the change

Beverly runs as part of Bevy’s rendering/update loop. At 60 FPS, a new frame is available roughly every 16.7 milliseconds.

That means a Model change can be reflected essentially immediately in the UI.

Change the Model. The UI reflects the Model.

2.10 Why Beverly Is Easy to Test

Beverly’s architecture makes testing straightforward because each major part has a clear responsibility.

Test the Model as Rust

The Model contains your application logic and data.

You can test it without starting a window, rendering a frame, or interacting with the UI:

#![allow(unused)]
fn main() {
#[test]
fn increments_clicks() {
    let mut model = AppModel { clicks: 0 };

    model.increment_clicks();

    assert_eq!(model.clicks(), 1);
}
}

This is just a Rust test.

Test the View as Bevy

The View is built from Bevy components.

That means View behavior can be tested using the same Bevy-oriented testing techniques used elsewhere in the application.

You don’t need a second UI architecture or a browser automation layer simply to exercise your component tree.

Test Events as contracts

Events are typed.

You can test that an interaction produces the expected Event and that the Event contains the expected payload.

Test Controllers as wiring

Controllers are explicit mappings:

#![allow(unused)]
fn main() {
App::Clicked => Model::App::increment_clicks
}

That makes the application’s behavior easy to reason about and easy to test.

The result is a useful property:

The application is testable because its architecture is explicit.

There isn’t one enormous UI layer that has to be tested as a black box.

The Model, View, Events, and Controllers each have a clear boundary.

2.11 Project Structure

A small application can start with a few files.

As it grows, Beverly’s architecture maps naturally onto your Rust project:

hello_beverly/
├── Cargo.toml
├── src/
│   ├── main.rs
│   ├── model/
│   │   └── app.rs
│   ├── view/
│   │   └── app.rs
│   ├── events/
│   │   └── app.rs
│   └── controller/
│       └── app.rs
└── assets/

A larger application might look like:

src/
├── main.rs
├── model/
│   ├── user.rs
│   ├── document.rs
│   └── application.rs
├── view/
│   ├── dashboard.rs
│   ├── users.rs
│   └── documents.rs
├── events/
│   ├── user.rs
│   └── document.rs
└── controller/
    └── application.rs

This isn’t a requirement.

It is simply a natural way to organize a Beverly application.

2.12 Running Your Application

Run your application normally:

cargo run

Check it without running:

cargo check

Build an optimized release:

cargo build --release

2.13 Beverly Commands

Beverly can also provide application-oriented Cargo commands.

For example:

cargo beverly build

Build a development application.

For distribution:

cargo beverly publish

The goal of publish is to feel like a natural extension of cargo build, while producing the artifacts you actually distribute.

Target-specific publishing can then be extended modularly:

cargo beverly publish --target macos
cargo beverly publish --target windows
cargo beverly publish --target linux

The initial implementation can target macOS while leaving the command structure open for additional platforms.

2.14 What You Just Built

You started with an empty Rust project and ended with the basic architecture of a Beverly application:

             ┌───────────┐
             │    View   │
             └─────┬─────┘
                   │
                 Event
                   │
             ┌─────▼─────┐
             │ Controller│
             └─────┬─────┘
                   │
                 Action
                   │
             ┌─────▼─────┐
             │   Model   │
             └─────┬─────┘
                   │
             Application
                Data
                   │
                   ▼
                  View

The Button is reusable.

The Model is ordinary Rust.

The View is built from Bevy.

The Event defines the application’s vocabulary.

The Controller connects Events to behavior.

Accessibility is part of the component contract.

And because each part has a clear responsibility, each part can be tested independently.

This is the foundation Beverly builds on:

The Event is the contract. The Controller is the connection. The Model is the owner. The View is the projection.

Application Structure

Beverly applications are organized around a simple idea:

Every concern has a place, and every place has a clear responsibility.

The goal is not architectural complexity. It is separation without ceremony.

A developer should be able to open an unfamiliar Beverly application and quickly answer:

• Where does the data live?
• Where can that data change?
• What does the interface look like?
• What actions can the application perform?
• What happens when an event occurs?
• Where should I make this change?

The architecture makes those answers predictable.

Application
│
├── Model
│   └── Owns application data and domain rules
│
├── View
│   └── Presents data and collects interaction
│
├── Events
│   └── Define what happened and what can happen
│
└── Controller
    └── Connects events to application actions

This is the application’s vocabulary.

One Responsibility, One Place

Beverly deliberately separates data, presentation, behavior, and communication.

The Model owns the data.

The View presents the data.

Events describe what happened or what should happen.

The Controller connects those events to actions.

That means a change should usually have an obvious destination.

Changing how data works? Look in the Model.

Changing how something looks? Look in the View.

Adding an application action? Define a Command.

Responding to something that happened? Listen for its Fact.

Changing what happens in response? Look in the Controller.

You don’t need to search through a giant application file to discover where behavior lives.

A Structure LLMs Can Understand

Modern applications are increasingly written with AI.

That changes what good architecture means.

A codebase may be edited by one developer, several developers, or multiple LLMs working simultaneously. The architecture should make it difficult for one part of the system to accidentally interfere with another.

Beverly uses explicit boundaries to make this possible.

For example, an LLM working on the View should primarily be concerned with:

View
 ↓
Components
 ↓
Events

An LLM working on the Model should primarily be concerned with:

Model
 ↓
Application Data
 ↓
Domain Rules

An LLM working on Controllers should primarily be concerned with:

Events
 ↓
Actions
 ↓
Model / Services

The boundaries give both humans and machines a smaller area to reason about.

The smaller the surface of a change, the easier the change is to understand, review, and verify.

Multiple LLMs, One Application

Beverly is designed for a development environment where multiple agents may work on the same application.

One LLM might be building a new component.

Another might be implementing a database integration.

Another might be adding an agent action.

Another might be improving accessibility.

They should not all need to understand the entire application.

Because concerns are separated, their work can remain localized.

             Application
                  │
      ┌───────────┼───────────┐
      │           │           │
     View        Model      Controller
      │           │           │
   Components   Data       Behavior
      │           │           │
      └─────── Events ────────┘

The important property is that one agent does not need to modify another agent’s area of responsibility to accomplish its own task.

A View agent should not need to rewrite Model state.

A Model agent should not need to restructure the UI.

A Controller agent should not need to duplicate application logic inside event handlers.

The architecture creates boundaries between pieces of work.

This reduces accidental overwrites, duplicated logic, and changes made in the wrong place.

Explicit State Ownership

State ownership is especially important when multiple agents are generating code.

Beverly does not encourage every component to invent its own source of truth.

The Model owns application data.

The Controller determines how application actions are connected.

The View reflects the resulting state.

          Model
        owns state
            │
            ▼
          View
      reflects state
            │
            ▼
          Event
      expresses intent
            │
            ▼
       Controller
      connects action
            │
            ▼
          Model

This creates a predictable direction of travel.

The View does not quietly become another Model.

A component does not secretly become the owner of application state.

A Controller does not become a second database.

There is one obvious place to look for the authoritative state.

One source of truth. Clear ownership. Predictable flow.

That matters even more when code is being generated or modified by machines.

Easy to Find. Easy to Change.

A good architecture should reduce the amount of code you need to read before making a change.

Suppose you want to change the way users are displayed.

You should primarily work in the View.

users/
├── model.rs
├── view.rs
├── events.rs
└── controller.rs

Suppose you want to change how users are stored.

Look at model.rs.

Suppose you want to add:

User::Delete

Look at the Events and Controller.

Suppose you want deleting a user to trigger an audit record.

Add the appropriate event/action connection rather than embedding auditing logic inside an unrelated component.

The structure itself becomes a map of the application.

Local Reasoning

Beverly favors local reasoning.

You should be able to understand a component without understanding the entire application.

You should be able to understand a Model without loading the renderer into your head.

You should be able to understand a Controller without understanding every screen.

You should be able to understand an Event without knowing which View generated it.

This makes code review dramatically simpler.

It also makes AI-generated code easier to evaluate.

An LLM can generate a change inside a constrained boundary.

A human can inspect that boundary and determine whether the change makes sense.

The architecture doesn’t eliminate mistakes.

It makes mistakes easier to locate.

A Predictable Project

A Beverly project can remain simple even as the application grows.

src/
├── main.rs
│
├── model/
│   ├── user.rs
│   ├── document.rs
│   └── settings.rs
│
├── view/
│   ├── users.rs
│   ├── documents.rs
│   └── settings.rs
│
├── events/
│   └── mod.rs
│
└── controller/
    └── mod.rs

The exact directory structure is not the important part.

The important part is that the conceptual structure remains stable.

Data       → Model
Interface  → View
Vocabulary → Events
Wiring     → Controller

A small application and a large application can use the same mental model.

Architecture as a Contract

Beverly’s architecture is intentionally boring in the best possible way.

There are no hidden state machines that developers have to learn.

No giant application controller.

No requirement that every piece of data pass through a proprietary state-management abstraction.

No reason for every component to know about every other component.

Instead, Beverly establishes a small set of contracts:

Model
  owns data

View
  presents data

Event
  describes intent or reality

Controller
  connects intent to behavior

Once those contracts are understood, the rest of the application becomes composition.

This is particularly important for AI-native development.

An LLM doesn’t need to understand an entire codebase to make a useful change.

It needs to understand the relevant contract, make the change inside that boundary, and follow the existing vocabulary.

The Application Becomes a Map

The ultimate goal is predictability.

When something doesn’t work, you know where to look.

When something needs to change, you know where to make the change.

When an LLM generates code, you know where that code belongs.

When multiple LLMs work simultaneously, their responsibilities can remain separated.

When a new developer joins the project, the architecture itself explains how the application works.

The codebase should tell you where to look.

That’s the point of Beverly’s application structure.

Not abstraction for its own sake.

Not architecture as ceremony.

Clear concerns. Clear ownership. Clear boundaries. Clear code.

The Beverly Rule

If you are unsure where something belongs, ask what the code is responsible for:

Does it own data? → Model

Does it present data? → View

Does it describe something happening or something you want to happen? → Event

Does it connect an event to behavior? → Controller

If the answer is still unclear, the code may be doing too much.

Simple enough for a human to navigate. Structured enough for multiple machines to work on simultaneously.

3.2 Model

The Model owns the application’s data.

In Beverly, a Model is a plain Rust data struct.

There is no separate state-management framework or hidden ECS resource. The application owns how and where the value is stored and how domain methods are added.

#![allow(unused)]
fn main() {
struct UserModel {
    name: String,
    email: String,
}
}

The struct is ordinary Rust. Add domain methods and validation in a normal impl UserModel block:

#![allow(unused)]
fn main() {
impl UserModel {
    fn name(&self) -> &str {
        &self.name
    }

    fn email(&self) -> &str {
        &self.email
    }

    fn set_name(&mut self, name: String) {
        self.name = name;
    }

    fn set_email(&mut self, email: String) {
        self.email = email;
    }
}
}

That’s a Beverly Model.

#![allow(unused)]
fn main() {
struct OtherModel {
    value: u32,
}
}

Models do not require a Beverly derive, macro, resource registration, or hidden runtime behavior.

Familiar by Design

Beverly deliberately uses a familiar getter/setter pattern.

Getters read the data.

Setters change the data.

Domain methods perform operations.

#![allow(unused)]
fn main() {
impl UserModel {
    fn rename(&mut self, name: String) {
        self.set_name(name);
    }
}
}

This is intentionally boring.

That’s a feature.

A developer can look at a Model and immediately understand what it owns and how it can change.

An LLM can recognize the pattern immediately and reliably generate new Models from it.

If an application already has a UserModel, an AI can predict what a DocumentModel, AccountModel, or ProjectModel should look like without having to learn a proprietary state-management system.

The Model should be obvious.

Rust Safety Without Rust Complexity

Because Models are ordinary Rust, they inherit Rust’s safety guarantees.

Data has a clear owner.

Access to that data is controlled through the Model’s interface.

Rust’s compiler handles the underlying memory-safety guarantees without requiring the developer to build their application around complicated ownership patterns.

Beverly does not ask developers to fill their application code with Arc<Mutex<T>>, elaborate borrowing patterns, or other advanced Rust techniques simply to manage application state.

The framework can handle complexity internally.

The application code stays simple.

        Model
          │
          ├── owns data
          │
          ├── getters → read
          │
          ├── setters → change
          │
          └── methods → behavior

This gives Beverly an important combination:

Familiar application architecture + Rust’s safety guarantees.

Models Own Their Access Control

A Model should also own the rules governing access to its data.

The UI should not be responsible for deciding whether an operation is permitted.

An AI agent should not be responsible for deciding whether an operation is permitted.

An API should not have to duplicate the same business rules.

The Model is the authoritative owner of the data and its domain rules.

For example:

#![allow(unused)]
fn main() {
impl UserModel {
    fn set_email(&mut self, email: String) -> Result<(), UserError> {
        if !is_valid_email(&email) {
            return Err(UserError::InvalidEmail);
        }

        self.email = email;
        Ok(())
    }
}
}

The rule travels with the data.

Every path that ultimately changes the Model goes through the same domain logic.

This becomes particularly important in AI-native applications.

An AI agent may request:

User::Delete

But the agent does not get to bypass the application’s rules.

The application decides whether that operation is authorized.

The Controller can enforce application-level policy, while the Model enforces the integrity and domain rules of the data itself.

The Model owns the data. It should also own the rules that keep that data valid.

Models Can Talk to Anything

A Model isn’t limited to in-memory data.

It can connect to whatever the application needs.

For example:

Model
 │
 ├── SQLite
 ├── PostgreSQL
 ├── APIs
 ├── Parquet
 ├── Files
 ├── Streams
 ├── Data Lakes
 └── AI-generated data

A DocumentModel might load documents from a database.

A TelemetryModel might consume a high-throughput stream.

A DataModel might query Parquet files.

A UserModel might communicate with an API.

The View doesn’t need to know where the data came from.

It simply reads the Model.

Database / Parquet / API / Stream
                ↓
              Model
                ↓
               View

This keeps the UI independent from the underlying data source.

It also makes Beverly suitable for applications that work with large, local, streaming, or heterogeneous datasets.

Models Are Easy to Test

Because a Model is ordinary Rust, testing one doesn’t require launching the application.

You can write a standard Rust unit test:

#![allow(unused)]
fn main() {
#[test]
fn user_email_can_be_changed() {
    let mut user = UserModel {
        name: "Alice".into(),
        email: "[email protected]".into(),
    };

    user.set_email("[email protected]".into());

    assert_eq!(user.email(), "[email protected]");
}
}

Domain rules can be tested the same way:

#![allow(unused)]
fn main() {
#[test]
fn invalid_email_is_rejected() {
    let mut user = UserModel {
        name: "Alice".into(),
        email: "[email protected]".into(),
    };

    assert!(user.set_email("not-an-email".into()).is_err());
}
}

No window.

No renderer.

No UI automation.

No browser.

Just Rust.

This is one of Beverly’s biggest architectural advantages:

If your application logic is Rust, test your application logic with Rust.

The same simplicity extends to AI-generated code.

An LLM can generate a Model.

A developer can read it.

A developer can modify it.

A standard Rust test can verify it.

And Rust’s compiler can enforce its safety.

The Model’s Role

The Model has a deliberately narrow responsibility:

Own the data. Define how that data can change. Enforce its domain rules. Connect to the underlying data sources.

It does not render the UI.

It does not decide how a Button looks.

It does not need to know whether a human or AI initiated an operation.

Those responsibilities belong elsewhere.

             Event
               ↓
          Controller
               ↓
             Model
          ↙    ↓    ↘
       Rules  Data  Sources
               ↓
             State
               ↓
              View

The result is a Model that is familiar to programmers, predictable for AI code generation, straightforward to test, and backed by Rust’s safety guarantees.

The Model is just Rust — and that’s exactly the point.

3.3 View

The View is the interface of the application.

It turns application state into an interactive, visual experience using Beverly’s component system.

Beverly provides a library of reusable primitives — Buttons, Cards, Inputs, Modals, Dropdowns, Tables, Navigation, Alerts, Badges, and more — that can be composed into larger interfaces.

The goal is simple:

Build the primitive once. Compose it everywhere.

Built-In Components

Beverly comes with a growing set of UI primitives designed for real applications.

Layout
├── Container
├── Row
├── Column
└── Stack

Input
├── Button
├── Input
├── Checkbox
├── Toggle
└── Dropdown

Content
├── Card
├── Text
├── Image
├── Icon
└── Table

Feedback
├── Alert
├── Toast
├── Modal
└── Badge

Navigation
├── Navbar
├── Tabs
├── Menu
└── Sidebar

These are not one-off widgets.

They are reusable building blocks intended to form the foundation of an application’s design system.

A Button can be used once or a thousand times.

#![allow(unused)]
fn main() {
button().text("Save")
button().text("Cancel")
button().text("Delete")
button().text("Create User")
}

The same primitives can be composed into completely different interfaces without creating a new implementation for every screen.

Composition

Beverly views are built through composition.

#![allow(unused)]
fn main() {
button()
    .text("Get Started")
  .on("click", open_document)
}

In the current Bevy implementation, open_document is an application function with signature fn(&mut Commands, Entity). Use app().children([...]) and the shared fluent composition API to build larger views.

Components contain other components.

Components can be nested.

Components can be reused.

This allows small primitives to become increasingly sophisticated interfaces without requiring increasingly complicated abstractions.

Primitive
    ↓
Component
    ↓
Composite Component
    ↓
Application View
    ↓
Complete Application

The same principle applies to your own components.

You can build a reusable UserCard from a Card, Text, Image, and Button, then use UserCard throughout the application.

Complex interfaces are compositions of simple things.

Familiar Syntax

Beverly deliberately uses a fluent API for component construction.

#![allow(unused)]
fn main() {
card()
    .padding(16)
    .radius(12)
    .children([
        text("Hello"),
        button().text("Save"),
    ])
}

Traits and methods can be chained together to progressively describe a component.

If you’ve ever written jQuery, the pattern should feel familiar:

select something
    ↓
configure it
    ↓
configure it again
    ↓
attach behavior
    ↓
compose

Beverly brings that familiar style to a strongly typed Rust UI.

The difference is that the compiler understands the API.

You get fluent composition without giving up Rust’s type system.

Familiar syntax. Strong types. Composable components.

Designed for Design Systems

Beverly is designed to make building and maintaining a design system a first-class use case.

Instead of every application inventing its own Button, Modal, Input, Dropdown, or notification system, teams can establish a common vocabulary of primitives and compose applications from them.

A design system might define:

#![allow(unused)]
fn main() {
button().text("Save")
button().text("Cancel")
button().text("Delete")
}

Those components can themselves be built on Beverly primitives.

Beverly Primitives
        ↓
   Design System
        ↓
 Application Components
        ↓
     Application

This creates consistency across an application without forcing every screen to share the same implementation.

The primitives provide the foundation.

The design system provides the language.

The application composes that language into an experience.

Accessibility by Construction

Accessibility is part of Beverly’s component architecture.

It is not something developers are expected to remember at the end of a project.

Beverly primitives carry accessibility requirements as part of their contracts.

For example, an interactive Button has an accessibility/ARIA requirement:

#![allow(unused)]
fn main() {
button().text("Save")
}

The button plugin derives the accessible name from .text(...) or the first text child supplied to .children(...). Application code should still test dynamic labels and semantic relationships with assistive technology.

Instead of:

Build
  ↓
QA
  ↓
Accessibility audit
  ↓
Discover missing semantics
  ↓
Fix

Beverly aims for:

Write UI
  ↓
Compiler checks requirements
  ↓
Accessible component

Accessibility becomes part of the programming model.

This is particularly important for complex enterprise interfaces where accessibility problems can become expensive compliance and legal issues.

Beverly’s philosophy is:

Don’t remember to add accessibility. Build accessibility into the primitive.

The goal is not merely to provide accessibility documentation.

The goal is to make entire categories of accessibility mistakes impossible to ship when they can be detected statically.

Modular by Design

Beverly’s component system is modular.

You don’t need to build your application as one enormous UI tree.

Small components can be assembled into larger components, which can then become reusable application primitives themselves.

#![allow(unused)]
fn main() {
fn user_card(user: &UserModel) -> impl Component {
    card()
        .padding(16)
        .children([
            text(user.name()),
            button().text("View Profile"),
        ])
}
}

That component can then be reused anywhere:

#![allow(unused)]
fn main() {
column()
    .children([
        user_card(&alice),
        user_card(&bob),
        user_card(&charlie),
    ])
}

The architecture encourages developers to create a vocabulary that matches their application.

A financial application can build AccountCard, TransactionTable, and PortfolioChart.

A healthcare application can build PatientCard, AppointmentList, and RecordViewer.

An AI application can build ToolCallCard, AgentStatus, ApprovalDialog, and EventInspector.

All of them are compositions of the same underlying primitives.

Reusability Is the Point

A UI framework becomes powerful when its components stop being screens and start becoming assets.

A Button isn’t a screen.

A Card isn’t a screen.

A Dropdown isn’t a screen.

They are reusable pieces that can appear throughout an application and across applications.

That means improvements to the primitive can propagate everywhere it is used.

Accessibility improvements.

Visual improvements.

Performance improvements.

Interaction improvements.

A component becomes a maintained piece of infrastructure rather than duplicated application code.

The View’s Role

The View has a deliberately focused responsibility:

Present application state, provide interaction, and compose the interface from reusable components.

It does not own the application’s underlying data.

It does not contain the application’s business rules.

It does not need to know whether an interaction came from a human or an AI agent.

It presents the current Model and emits Events when users interact with it.

              Model
                │
             State
                ↓
              View
                │
        ┌───────┴────────┐
        ↓                ↓
   Components         Events
        │                │
   Compose +          Controller
   Render                │
                         ↓
                       Model

The result is a View system that is familiar to developers, predictable for AI-generated code, modular enough for serious design systems, and accessible by construction.

The View is where simple primitives become an application.

3.4 Events

Events are the vocabulary of a Beverly application.

They describe what can happen and what has happened.

event! declares ordinary Bevy Message structs in namespaces. Registration and handling remain explicit application responsibilities:

#![allow(unused)]
fn main() {
use bevy::prelude::*;
use beverly::prelude::*;

event! {
    User::Create {
        name: String
    }
    User::Delete {
        id: u64
    }
}

fn setup(mut app: App) {
    app.add_message::<User::Create>()
        .add_message::<User::Delete>();
}
}

Write and read them with Bevy’s normal message APIs:

#![allow(unused)]
fn main() {
fn create_user(mut messages: MessageWriter<User::Create>) {
    messages.write(User::Create {
        name: "Alice".to_string(),
    });
}

fn handle_users(mut messages: MessageReader<User::Create>) {
    for message in messages.read() {
        info!(name = %message.name, "creating user");
    }
}
}

The macro declares types only. It does not register messages, route commands, or emit events automatically; those behaviors stay explicit in the systems and plugins that own the application contract.

Beverly uses two kinds of Events:

• Commands — things you want to happen.
• Facts — things that happened.

Command
    │
    │ "I want this to happen."
    ▼
 Application
    │
    │ "This happened."
    ▼
Fact

This distinction gives applications a simple, predictable language for describing behavior.

Commands

A Command expresses an intention.

It tells the application what you want it to do.

#![allow(unused)]
fn main() {
event! {
    User::Create {
        name: String
    }

    User::Delete {
        id: UserId
    }
}
}

These Events describe actions the application understands:

User::Create
User::Delete

A human can trigger them.

An API can trigger them.

Another application can trigger them.

An AI agent can trigger them.

The Event is the common interface.

There is no separate API for AI agents to learn.

Facts

A Fact describes something that has already happened.

#![allow(unused)]
fn main() {
event! {
    User::Created {
        id: UserId
    }

    User::Deleted {
        id: UserId
    }
}
}

The distinction is simple:

CreateUser
    = Command
    = "Create this user."

UserCreated
    = Fact
    = "This user was created."

Commands express intent.

Facts express reality.

This makes it possible for different parts of the application to react to the same facts without needing to know which component originally caused them.

Events Are Strongly Typed

Events are defined as typed Rust contracts.

#![allow(unused)]
fn main() {
event! {
    User::Create {
        name: String
    }
}
}

The compiler knows what User::Create requires.

An invalid payload is not a runtime mystery.

It is a type error.

Rust catches malformed Events at compile time.

This gives Events a property that is particularly valuable for AI-generated code:

The compiler can tell the AI when it generated something that doesn’t match the application’s contract.

The same type system that protects ordinary Rust code protects the application’s event vocabulary.

Events as Self-Documenting Code

An Event definition tells you what the application can do without requiring you to read the implementation first.

#![allow(unused)]
fn main() {
event! {
    Document::Summarize {
        id: DocumentId
    }

    Document::Delete {
        id: DocumentId
    }

    Document::Publish {
        id: DocumentId
    }
}
}

You can glance at this and immediately understand three capabilities of the application.

That is intentional.

Beverly aims to reduce boilerplate by making the code itself the documentation.

Instead of maintaining separate lists of:

• API endpoints
• AI tools
• event names
• documentation
• schemas
• permissions
• telemetry definitions

the Event becomes the authoritative definition from which these things can be derived.

The best documentation is the code that cannot lie.

Events Are an Interface for AI

This becomes especially powerful when an AI agent participates in the application.

The agent doesn’t need to understand the entire application implementation.

It needs to understand the application’s vocabulary.

For example:

User::Create
    name: String

User::Delete
    id: UserId

Document::Summarize
    id: DocumentId

The agent can discover these Commands and determine what actions are available.

To perform an action, it simply issues the corresponding Command.

Agent
  │
  │ User::Create { name: "Alice" }
  ▼
Controller
  │
  ▼
Model

The agent doesn’t need a special Agent::CreateUser interface.

It uses the same application vocabulary as everything else.

Agents can also listen for Facts:

UserCreated
DocumentPublished
PaymentCompleted

An agent can respond when the Fact it cares about occurs.

UserCreated
    ↓
Agent observes Fact
    ↓
Agent decides what to do
    ↓
Agent issues Command

This produces a very simple agent loop:

Listen for Facts. Decide. Issue Commands.

Events and Observability

Beverly Events are also observable by design.

Under the hood, Beverly’s Event system integrates with OpenTelemetry so that Events can carry standardized telemetry information as part of their normal lifecycle.

That means application activity can be observed without developers having to build a separate logging architecture around every action.

Conceptually:

Event
  ↓
Action
  ↓
State Change
  ↓
Telemetry
  ↓
Event History

The important idea is that the application already knows what happened.

The Event is the natural unit of application activity.

Logging doesn’t need to be a separate thing that developers remember to add everywhere.

Playback and Rewind

Because Events form an ordered history of application activity, playback becomes remarkably straightforward.

Instead of trying to reconstruct what happened from scattered logs, you can step through the application’s Event history:

Event 001
   ↓
Event 002
   ↓
Event 003
   ↓
Event 004
   ↓
Current State

Replaying the application means replaying its Events.

Rewinding means moving back through that history and reconstructing the corresponding state.

This creates an important capability for AI-native applications.

When an agent changes something, its actions become part of the same observable application history as human actions.

A developer can inspect:

Fact: DocumentCreated
Command: Document::Summarize
Fact: DocumentSummarized
Command: Document::Publish
Fact: DocumentPublished

The AI’s behavior is no longer hidden behind a collection of opaque tool calls.

It becomes part of the application’s history.

If the application records what happened, the application can show you what happened.

How Events Are Stored

The application state you see at any moment is not the source of truth.

The Event history is.

Event Log (append-only)
   │
   ├── 001  Fact: DocumentCreated   { id: 1 }
   ├── 002  Command: Document::Summarize { id: 1 }
   ├── 003  Fact: DocumentSummarized { id: 1 }
   ├── 004  Command: Document::Publish { id: 1 }
   └── 005  Fact: DocumentPublished { id: 1 }

Every Event is written to this log in the order it occurred, and it is never edited or removed once written.

Each entry carries the information required to reproduce it later:

Sequence   → position in history
Timestamp  → when it happened
Event      → the typed Command or Fact
Payload    → its strongly typed data

The Model’s current state is simply what you get from folding the log from the beginning:

State(0) + Event 001 + Event 002 + ... + Event N = Current State

Because the log is append-only, this is the same guarantee databases call an event-sourced or write-ahead log: history is immutable, and current state is a derived, disposable projection of it.

The log is the truth. The current state is just a cache of it.

Saving Event History

Saving an application’s history means saving its Event log, not its in-memory Models.

Event
  ↓
Serialize (typed payload → bytes)
  ↓
Append to log (disk, database, or stream)
  ↓
Acknowledge

Because Events are strongly typed Rust values, they serialize the same way any other typed Rust data does. There is no bespoke save format to invent per feature.

The log can live wherever it makes sense for the application:

Event Log
   │
   ├── a local file
   ├── SQLite / Postgres
   ├── an append-only object store
   └── a distributed log (e.g. Kafka-style stream)

Saving does not require freezing the whole application. Only the new Events since the last save need to be appended, which is what keeps this cheap even for long-running applications.

Persistence is just “keep appending.” Nothing about the Model needs a separate save/load path.

Replaying

Replaying means reading the Event log from the start and re-applying every Event, in order, to rebuild state.

Empty State
   │
   ├── apply Event 001
   ├── apply Event 002
   ├── apply Event 003
   ├── ...
   └── apply Event N
   ↓
Reconstructed State (identical to the original)

Because Facts describe what already happened, replaying them is deterministic: applying the same Events in the same order always produces the same resulting state.

This is useful in several concrete situations:

Restarting the application
    → replay the log to rebuild state from nothing

Debugging a production issue
    → replay a copied log locally to reproduce it exactly

Testing
    → replay a recorded scenario as a regression test

Migrating a Model
    → replay old Events through new logic to backfill new state

Nothing about “restoring the application” is special-cased. It’s the same replay used everywhere else.

Rewinding

Rewinding moves state backward by replaying only a prefix of the log, rather than the whole thing.

Event 001 → Event 002 → Event 003 → Event 004 → Event 005
                              ▲
                    rewind target: after Event 003

To rewind to a point in time, the application discards nothing. It simply re-derives state by folding the log up to that Event and stopping:

State(0) + Event 001 + Event 002 + Event 003 = State at that point in time

The Events after the rewind point are not deleted. They remain in the log. Rewinding is a read operation over history, not a mutation of it.

Rewind ≠ Undo-by-deleting
Rewind = Recompute state as of an earlier Event

This distinction matters. Because the full log still exists, an application (or a developer, or an agent) can rewind, inspect an earlier state, and then choose to either:

Resume forward
    → continue applying the remaining Events as normal

Branch
    → issue new Commands from that point, creating a new
      continuation of history instead of the original one

Rewinding shows you the past. It doesn’t erase it.

Stepping Through

Because the log is just an ordered list, moving through it one Event at a time is a simple index operation, not a special debugging feature bolted on afterward.

            ◀── step back            step forward ──▶

Event 001  Event 002  [ Event 003 ]  Event 004  Event 005
                            ▲
                      current cursor

A step forward applies the next Event in the log to the current state:

State(cursor) + Event(cursor + 1) = State(cursor + 1)

A step back recomputes state as of the previous Event, the same way rewinding does, just one Event at a time:

State(cursor − 1) = fold(Event 001 ..= Event(cursor − 1))

This gives an application (or a developer tool built on top of it) the same experience as stepping through a debugger, except the “breakpoints” are the application’s own Commands and Facts:

Step back  → Fact: DocumentSummarized
Step back  → Command: Document::Summarize
Step back  → Fact: DocumentCreated

Because every step is just a Command or Fact, stepping through history is also stepping through an audit trail. There is nothing else to reconstruct.

A step-through debugger for application behavior isn’t a separate feature. It’s the same Event log, read one entry at a time.

Snapshots

Replaying an entire log from the beginning is simple and correct, but for a long-running application it can become slow.

A snapshot solves this without changing anything about how replay, rewind, or stepping work conceptually:

State(0) + Events 001..500  = State at Event 500
                                     │
                                     ▼
                             Snapshot("at 500")

Snapshot("at 500") + Events 501..N = Current State

A snapshot is just a cached checkpoint: a Model’s state at a known Event, saved so replay doesn’t need to start from empty state every time.

Replay without a snapshot:
   Empty State + Events 001..10,000

Replay with a snapshot:
   Snapshot(9,900) + Events 9,901..10,000

Snapshots are an optimization, not a change to the model of history. The Event log remains the single source of truth; a snapshot can always be regenerated by replaying from the beginning.

A snapshot is a shortcut through history, never a replacement for it.

Less Boilerplate

Traditional applications often maintain multiple representations of the same capability.

A feature might require:

Implementation
API endpoint
Schema
Documentation
AI tool definition
Logging
Permissions
Tests

Beverly’s Event system is designed to collapse much of that duplication.

One strongly typed Event definition can become the source for the representations the rest of the application needs.

             Event Definition
                    │
       ┌────────────┼────────────┐
       ↓            ↓            ↓
    Rust Types    AI Tools    Documentation
       │            │            │
       ├────────────┼────────────┤
       ↓            ↓            ↓
   Validation   Permissions   Telemetry

The goal isn’t to generate more code.

It is to stop writing the same information multiple times.

Events Are the Contract

Events create a shared vocabulary between every participant in the application.

Human ────────┐
              │
Keyboard ─────┤
              │
API ──────────┤
              ├──► Command ──► Controller ──► Model
              │
AI Agent ─────┘

Model ──► Fact ──► View
              │
              ├──► Agent
              │
              ├──► Other Systems
              │
              └──► Event History

Commands tell the application what someone wants to happen.

Facts tell the application what actually happened.

The compiler makes sure those messages conform to their contracts.

OpenTelemetry makes their activity observable.

The Event history makes that activity replayable.

And the same vocabulary can be understood by both humans and AI agents.

Events turn application behavior into typed, observable, self-documenting vocabulary.

That is the foundation for Beverly’s larger idea:

One application. One vocabulary. Humans and AI use the same interface.

3.5 Controller

The Controller connects Messages to application behavior.

It answers a simple question:

When this Event occurs, what should happen?

A Controller maps an Event to one or more Model methods or other application actions.

#![allow(unused)]
fn main() {
controller! {
  UserController {
    User::Create => create_user,
    User::Delete => delete_user,
  }
}
}

The macro generates a Bevy Plugin. Each handler receives a reference to the message type it handles:

#![allow(unused)]
fn main() {
fn create_user(message: &User::Create) {
  info!(name = %message.name, "creating user");
}

fn delete_user(message: &User::Delete) {
  info!(id = message.id, "deleting user");
}
}

Register the messages and install the generated plugin explicitly:

#![allow(unused)]
fn main() {
app.add_message::<User::Create>()
  .add_message::<User::Delete>()
  .add_plugins(UserController);
}

controller! routes messages only. It does not make a view emit messages or invent application state transitions.

The Event defines the contract.

The Controller defines what the application does with that contract.

The Model owns the data and behavior.

Event
  ↓
Controller
  ↓
Action
  ↓
Model

Controllers are intentionally declarative.

You should be able to glance at one and understand the application’s behavior without tracing through a large amount of framework code.

controller! supports three composable route forms:

Sequences and fan-out groups can nest recursively. Groups must contain at least one action; trailing commas are accepted. Composed actions return Result. The first action receives &Message; later actions receive their predecessor’s owned output. Fan-out outputs form a tuple in declaration order, not completion order. Even a one-branch group produces a one-element tuple (value,).

Complete Example

use bevy::prelude::*;
use beverly::prelude::*;

event! { Document::Process { id: u32 } }

#[derive(Clone)]
struct LoadedDocument {
  id: u32,
  text: String,
}

fn load(message: &Document::Process) -> Result<LoadedDocument, &'static str> {
  Ok(LoadedDocument { id: message.id, text: "Report content".to_owned() })
}

fn summarize(document: LoadedDocument) -> Result<String, &'static str> {
  Ok(document.text)
}

fn index(document: LoadedDocument) -> Result<u32, &'static str> {
  Ok(document.id)
}

fn save((summary, id): (String, u32)) -> Result<(), &'static str> {
  info!(id, summary, "document processed");
  Ok(())
}

controller! {
  DocumentController {
    Document::Process => [load, { summarize, index }, save],
  }
}

fn main() {
  let mut app = App::new();
  app.add_message::<Document::Process>().add_plugins(DocumentController);
  app.world_mut().write_message(Document::Process { id: 42 });
  app.update();
}

Here load receives the message, the parallel branches receive independent LoadedDocument values, and save receives (String, u32) after both succeed. The compute pool is initialized on first use if the application has not initialized it through Bevy’s normal task-pool setup.

Sequential Pipelines

Multiple actions can be composed into a series using an array:

#![allow(unused)]
fn main() {
controller! {
  DocumentController {
    Document::Process => [load, parse, summarize, save],
  }
}
}

The actions execute in order.

Most importantly, the return value from one action becomes the input to the next action.

DocumentId
    ↓
Document::load
    ↓
Document
    ↓
Document::parse
    ↓
ParsedDocument
    ↓
Document::summarize
    ↓
Summary
    ↓
Document::save
    ↓
()

There is no special pipeline object or custom data-passing mechanism.

The Controller composes ordinary function signatures.

Conceptually:

#![allow(unused)]
fn main() {
fn load(message: &Document::Process) -> Result<LoadedDocument, Error>
fn parse(document: LoadedDocument) -> Result<ParsedDocument, Error>
fn summarize(document: ParsedDocument) -> Result<Summary, Error>
fn save(summary: Summary) -> Result<(), Error>
}

The output of each step must be compatible with the input of the next.

Sequential steps move values; intermediate values do not need to implement Clone. Use ordinary functions or associated function paths, such as DocumentModel::load. These are function calls, not Bevy systems with injected Res, ResMut, or Commands parameters. Obtain application dependencies explicitly through the message or values passed between actions.

If it isn’t, Rust catches the problem at compile time.

If the pipeline doesn’t type-check, it doesn’t build.

Efficient Data Flow

Rust’s ownership model also makes these pipelines extremely efficient.

A pipeline step receives the data it needs, performs its work, and passes the result to the next step.

The pipeline does not need to maintain a collection of long-lived objects waiting for a garbage collector to eventually clean them up.

Data can be moved through the pipeline with clear ownership and deterministic lifetime.

Step A
  │
  │ owns value
  ▼
Step B
  │
  │ owns value
  ▼
Step C
  │
  │ owns value
  ▼
Step D

When a value is no longer needed, its lifetime ends according to Rust’s ownership rules.

There is no tracing garbage collector periodically scanning the application’s object graph.

That matters for high-throughput applications.

Instead of building a large managed object graph and waiting for garbage collection, Beverly pipelines can move data through a predictable sequence of operations with deterministic resource management.

This is particularly valuable when processing:

• Streaming data
• Large datasets
• Telemetry
• AI inference results
• Documents
• Images
• Financial data
• Device data

The framework can orchestrate the pipeline while Rust handles the underlying memory management.

Data flows through the pipeline. It doesn’t have to live there.

This is one of the reasons Beverly can pursue high-performance application infrastructure without exposing developers to complicated memory-management APIs.

Errors Break the Chain

Controller pipelines use standard Rust Result.

There is no special Beverly error-flow abstraction to learn.

#![allow(unused)]
fn main() {
fn parse(document: Document)
    -> Result<ParsedDocument, DocumentError>
}

If an action returns:

#![allow(unused)]
fn main() {
Ok(value)
}

the value continues to the next action.

If it returns:

#![allow(unused)]
fn main() {
Err(error)
}

the current chain stops.

Sequential stages can use a common error type or convert earlier errors into the last stage’s error type through From, as with ordinary Rust ?. Fan-out branches must share one error type. The composed route’s error must implement Display: Beverly logs it with the controller and message type, then continues processing later messages. The final successful value is discarded; emit a follow-up message explicitly when the application needs a new workflow boundary. A plain Message => handler route still ignores its return value; use [handler] for a one-stage route with composed error logging.

Action A
   ↓
Action B
   ↓
Err(error)
   ↓
STOP

This uses a mechanism Rust developers already understand.

Beverly doesn’t need to reinvent Result, error propagation, or failure semantics.

Successful values flow forward. Errors stop the chain.

Parallel Fan-Out

Not every action needs to happen in sequence.

A Controller can fan an input out to multiple actions in parallel using braces:

#![allow(unused)]
fn main() {
controller! {
  UserController {
    User::Created => { notify_user_created, record_analytics, inform_agent },
  }
}
}

Conceptually:

             UserCreated
                  │
          ┌───────┼───────┐
          ↓       ↓       ↓
   Notification Analytics Agent

The actions can execute independently.

Each branch above receives &User::Created and returns Result<Output, Error>. Borrowing the same message does not require the message itself to be Clone. For an owned intermediate value, fan-out clones the input for all but one branch, so that input must implement Clone. Use Arc for shared read-only data when cloning a large payload would be expensive.

Fan-out uses Bevy’s scoped compute pool and waits for every branch to finish. Captured values and results must be Send; shared borrows must be Sync. Native builds support simultaneous execution when pool workers are available. Single-threaded browser builds preserve tuple and error semantics but do not execute synchronous branch bodies simultaneously. Branches must not rely on another branch running concurrently to make progress.

Branch completion order is unspecified. Outputs are joined in declaration order. If branches fail, all siblings are still allowed to finish; there is no rollback or sibling cancellation. The first error in declaration order is propagated and any following sequential stage is skipped. Protect shared mutable state explicitly and keep branch side effects independent.

This is useful when multiple systems need to react to the same Fact and there is no reason for them to wait on one another.

The distinction is deliberately visual:

#![allow(unused)]
fn main() {
[ A, B, C ]    // series
{ A, B, C }    // parallel
}

One means do these things in order.

The other means fan this work out.

Series and Parallel Can Be Combined

Series and parallel operations can be composed.

#![allow(unused)]
fn main() {
controller! {
  DocumentController {
    Document::Process => [load, { index, analyze, metadata }, save],
  }
}
}

The conceptual flow is:

              load
               │
               ▼
        ┌──────┼──────┐
        ↓      ↓      ↓
      index analyze metadata
        └──────┼──────┘
               ↓
              save

A parallel stage can produce a result that becomes the input to the next stage.

In this example, save receives (IndexOutput, AnalysisOutput, MetadataOutput) as one tuple argument. For a sequence inside one branch, write:

#![allow(unused)]
fn main() {
controller! {
  DocumentController {
    Document::Process => [load, { [parse, summarize], index }, save],
  }
}
}

That save receives (Summary, IndexOutput). Fan-out inside fan-out produces nested tuples; it does not flatten them. Each nested sequence preserves its own order while independent branches can overlap.

This means:

Series
   ↓
Parallel
   ↓
Series

can remain part of the same straightforward data-flow model.

The framework handles the orchestration.

The developer describes the relationships.

Type Safety Across the Pipeline

Because each action has a typed input and output, the entire pipeline can be checked before the application runs.

For example:

load()
  → Document

parse(Document)
  → ParsedDocument

summarize(ParsedDocument)
  → Summary

is valid.

But:

load()
  → Document

summarize(ParsedDocument)
  → Summary

cannot be connected directly.

The types don’t match.

Rust catches the incompatible pipeline at compile time.

This is one of the places where Beverly’s use of Rust becomes particularly powerful:

The compiler becomes a pipeline validator.

Developers don’t need to manually inspect every connection.

AI-generated pipelines don’t have to be trusted blindly.

The type system verifies that the data actually flows between the operations as described.

Async Is Explicit

Controller composition is synchronous from the route’s perspective: the controller’s Update system waits for the pipeline and all parallel branches. It accepts functions returning Result, not async fn or detached jobs. Long CPU work can still block a UI update even when it uses multiple worker threads. For long-running inference, network I/O, or cancellable work, use a worker and explicit request/response messages rather than treating fan-out as background execution.

Asynchronous operations are intentionally modeled differently.

An asynchronous operation is not treated as one magical Controller step that hides its lifecycle.

It is two operations:

1. Issue the request.
2. Listen for the response.

For example:

Command: Document::Process
        ↓
    start work
        ↓
   ... async ...
        ↓
Fact: Document::Processed

The first operation initiates the work.

The resulting Fact represents the response.

Another Controller can listen for that Fact:

#![allow(unused)]
fn main() {
controller! {
  DocumentController {
    Document::Processed => save_document,
  }
}
}

This keeps asynchronous behavior consistent with Beverly’s Event architecture.

There isn’t a hidden callback chain buried inside a single pipeline expression.

The application can see the request.

The application can see the response.

The Event history can see both.

The AI can see both.

Prefer Events for Long-Running Flows

Controllers are powerful, but they shouldn’t become enormous chains of application logic.

For short, tightly coupled operations, a series is ideal:

#![allow(unused)]
fn main() {
[A, B, C]
}

For longer or conceptually separate workflows, prefer breaking the chain with a new Event.

Instead of:

A → B → C → D → E → F → G → H

consider:

A → B → Fact
          ↓
          C → D → Fact
                    ↓
                    E → F

The Event becomes a natural boundary between stages.

This provides:

• Smaller Controllers
• Easier testing
• Clearer application behavior
• Better observability
• Natural asynchronous boundaries
• Better AI discoverability
• Easier replay and debugging

Use pipelines for composition. Use Events for boundaries.

Controllers as Application Wiring

The Controller is intentionally not where application logic lives.

It connects the pieces.

             Event
               │
               ▼
          Controller
               │
          ┌────┴────┐
          ↓         ↓
       Series    Parallel
          │         │
          └────┬────┘
               ↓
             Model

The Model owns the domain behavior.

The Event defines the contract.

The Controller determines how those pieces connect.

That separation makes the Controller easy to read, easy to generate, and easy to test.

And because the connections are typed, Rust can validate both the logic and data flow before the application ever runs.

The Controller is the wiring diagram for your application.

You describe what connects to what.

Beverly handles the orchestration.

Rust makes sure the connections make sense.

Localize

localize() provides Beverly’s interface for localized text.

At its simplest, it turns a localization key into text:

#![allow(unused)]
fn main() {
text(localize("user.welcome"))
}

But localization in an AI application can be more than a static dictionary lookup.

An application may need to:

• Switch languages at runtime.
• Generate alternative wording.
• Ask an LLM to produce localized text.
• Review previous generated versions.
• Step forward and backward through alternatives.
• Rewind to an earlier version.
• Keep the original semantic key independent from its presentation.
• Allow humans and AI agents to participate in the same localization workflow.

Beverly therefore treats localization as a stateful presentation layer while keeping the underlying semantic identity stable.

The key identifies the meaning. The locale determines the language. The translation provides the presentation.

Basic Usage

The simplest form is a localization key:

#![allow(unused)]
fn main() {
text(localize("user.welcome"))
}

The localization system resolves the key using the application’s current language.

For example:

user.welcome

might resolve to:

English:
Welcome back.

Spanish:
Bienvenido de nuevo.

French:
Bon retour.

The application does not need to change its UI code when the language changes.

#![allow(unused)]
fn main() {
text(localize("user.welcome"))
}

remains the same.

Localization Keys

A localization key represents meaning rather than a particular string.

#![allow(unused)]
fn main() {
localize("user.welcome")
}

is preferable to embedding:

#![allow(unused)]
fn main() {
"Welcome back."
}

throughout the application.

The key becomes the stable vocabulary shared between:

• UI code
• Translation files
• Language selection
• Accessibility text
• AI-generated alternatives
• Tests
• Documentation

For example:

#![allow(unused)]
fn main() {
localize("user.save")
localize("user.save.label")
localize("user.save.description")
localize("user.save.error")
}

The application can therefore change its language without changing its component structure.

Current Language

The localization system maintains the application’s current locale.

For example:

#![allow(unused)]
fn main() {
locale()
}

might return:

en-US

Changing the locale updates localized content throughout the application.

#![allow(unused)]
fn main() {
set_locale("es-ES")
}

All components using localize() can then resolve their keys using the new language.

The important point is that components do not need to manually update themselves.

Current Locale
      ↓
   localize()
      ↓
Localized Text
      ↓
      View

Change the language once. Let the interface follow the state.

Swapping Languages

Language switching should be a normal application operation.

For example:

#![allow(unused)]
fn main() {
Command::Locale::Set("fr-FR")
}

The application can connect that Command to its localization state:

#![allow(unused)]
fn main() {
controller! {
    Command::Locale::Set => Locale::set,
}
}

After the Model changes locale, every localize() expression resolves against the new locale.

This means a language selector does not need to manually update every component.

#![allow(unused)]
fn main() {
select()
    .label(localize("language.label"))
    .aria(localize("language.description"))
    .bind(Locale::current)
    .children([
        option("en-US").children(text("English")),
        option("es-ES").children(text("Español")),
        option("fr-FR").children(text("Français")),
    ])
}

The application changes one piece of state.

The View follows it.

Language Is State

The current language belongs to application state rather than individual components.

For example:

#![allow(unused)]
fn main() {
struct Locale {
    language: String,
}
}

The UI reads the current language through the localization system.

This avoids patterns such as:

#![allow(unused)]
fn main() {
button().text(localize("user.save"))
text(localize("user.description"))
modal_title(localize("user.title"))
}

The language should not be repeated throughout the interface.

Instead:

Locale
  ↓
Application State
  ↓
localize()
  ↓
Entire View

Locale is application state. Localization is its projection into language.

Rewind

Localization can maintain a history of changes and generated alternatives.

That makes it possible to rewind to an earlier localized state.

#![allow(unused)]
fn main() {
localize("document.summary")
    .rewind()
}

Rewind returns the localization state to the previous point in its history.

This is particularly useful when an LLM has generated several alternatives and the application wants to return to an earlier version.

Conceptually:

Version 1
   ↓
Version 2
   ↓
Version 3
   ↓
Version 4

Rewind can move backward:

Version 4
   ↓
Version 3

The semantic localization key remains unchanged.

Only the presentation state changes.

Step Back

step_back() moves one position backward through localization history.

#![allow(unused)]
fn main() {
localize("document.summary")
    .step_back()
}

For example:

Original
   ↓
Alternative 1
   ↓
Alternative 2
   ↓
Alternative 3

Calling step_back() from Alternative 3 produces:

Alternative 2

Calling it again produces:

Alternative 1

This is useful when reviewing generated language without discarding the history.

Step Forward

step_forward() moves one position forward through the existing history.

#![allow(unused)]
fn main() {
localize("document.summary")
    .step_forward()
}

For example:

Alternative 1
   ↓
Alternative 2
   ↓
Alternative 3

If the current version is Alternative 1, stepping forward selects Alternative 2.

This creates a simple navigation model:

step_back() ← Current → step_forward()

Rewind vs Step Back

The two operations have different purposes.

step_back() moves one position:

#![allow(unused)]
fn main() {
localize("document.summary")
    .step_back()
}

rewind() returns to an earlier known point:

#![allow(unused)]
fn main() {
localize("document.summary")
    .rewind()
}

Step navigation is useful for reviewing history.

Rewind is useful for abandoning later changes and returning to the previous stable state.

The localization system should preserve enough history to make these operations predictable.

LLM Alternatives

One of the important differences between Beverly localization and a traditional translation system is that localized text can have multiple valid representations.

For example:

Key:
document.summary

could produce:

"The document contains three sections."

An LLM might produce alternatives such as:

"This document contains three sections."

"There are three sections in this document."

"This document is divided into three sections."

These alternatives can all represent the same underlying meaning.

The localization key does not change.

Only the presentation does.

LLM Hook

The localization system should provide a clean hook for attaching an LLM to text generation.

Conceptually:

#![allow(unused)]
fn main() {
localize("document.summary")
    .generate_with(llm)
}

The LLM receives the semantic localization request and relevant context.

For example:

#![allow(unused)]
fn main() {
localize("document.summary")
    .generate_with(llm)
    .context(document)
}

The result becomes another localization candidate.

The important architectural boundary is that the LLM does not replace the localization system.

It provides an alternative representation.

Localization Key
      ↓
Localization Context
      ↓
LLM
      ↓
Alternative Text
      ↓
Localization History
      ↓
View

The LLM generates language. The localization system owns the language state.

Alternative Text

Generated alternatives should remain associated with the original localization key.

For example:

#![allow(unused)]
fn main() {
localize("document.summary")
}

might have:

Original:
The document contains three sections.

Alternative 1:
This document contains three sections.

Alternative 2:
The document is divided into three sections.

Alternative 3:
There are three sections in this document.

The application can navigate between them without changing the underlying semantic identity:

document.summary

This is important for AI-generated interfaces because it separates what the application wants to communicate from how that idea is expressed.

Language + LLM

The same localization key can be passed through the LLM in different languages.

For example:

#![allow(unused)]
fn main() {
localize("document.summary")
    .locale("es-ES")
    .generate_with(llm)
}

The result might be:

El documento contiene tres secciones.

The application can then generate another alternative:

Este documento está dividido en tres secciones.

The localization history remains associated with the same key and locale.

Conceptually:

              document.summary
                     │
          ┌──────────┴──────────┐
          ↓                     ↓
       en-US                  es-ES
          │                     │
    ┌─────┼─────┐         ┌─────┼─────┐
    ↓     ↓     ↓         ↓     ↓     ↓
   v1    v2    v3        v1    v2    v3

This provides a clean foundation for multilingual AI-generated interfaces.

Human Review

Generated alternatives should not automatically replace an approved translation simply because an LLM produced them.

Instead, the application can treat generated text as a candidate.

For example:

#![allow(unused)]
fn main() {
localize("document.summary")
    .generate_with(llm)
    .candidate()
}

The application or user can then review the result.

Current
   ↓
Generate
   ↓
Candidate
   ↓
Review
   ↓
Accept / Reject

If accepted, the candidate becomes the current localized representation.

If rejected, the application can step back or select another candidate.

This makes AI generation compatible with ordinary application state and review workflows.

Localization History

Localization history can be thought of as a sequence of presentations associated with a key.

Key: document.summary

History:
──────────────────────────────────────
v1  "The document contains three sections."
v2  "This document contains three sections."
v3  "The document is divided into three sections."
v4  "There are three sections in this document."
──────────────────────────────────────
                         ↑
                       Current

The history makes generated language inspectable and reversible.

It also means the application does not have to treat every generated result as destructive.

Generate without losing what came before.

Events

Localization changes can participate in Beverly’s Event system.

For example:

#![allow(unused)]
fn main() {
event! {
    Locale::Changed {
        locale: String
    }

    Localization::Generated {
        key: String,
        locale: String
    }

    Localization::Accepted {
        key: String,
        locale: String
    }

    Localization::Rewound {
        key: String
    }
}
}

This makes language changes and generated alternatives observable.

An agent can listen for localization events just like any other application event.

For example:

Localization::Generated
        ↓
Agent observes
        ↓
Agent evaluates
        ↓
Localization::Accepted

The same event vocabulary can therefore support humans and AI.

Telemetry and History

Because localization changes can be represented as Events, the same event history used elsewhere in Beverly can provide visibility into language changes.

For example:

Locale Changed
      ↓
Text Generated
      ↓
Alternative Created
      ↓
Alternative Accepted
      ↓
UI Updated

This makes it possible to understand how the current text came to exist.

Combined with Beverly’s Event history, an application can inspect, replay, or rewind localization changes.

The exact behavior of rewind across external LLM calls should remain explicit: replaying an application event does not necessarily reproduce the exact same external model response unless that response was recorded.

Localization and Accessibility

Localization should apply equally to accessibility text.

For example:

#![allow(unused)]
fn main() {
button().text(localize("user.save"))
}

The same keys can resolve into the active language.

This prevents an application from accidentally translating visible content while leaving accessible descriptions in another language.

Localization therefore applies to:

• Visible text
• Labels
• ARIA descriptions
• Tooltips
• Error messages
• Success messages
• Placeholder text
• Button text
• Navigation
• System messages

If the user experiences it as language, it should be localizable.

Localization Does Not Own Application Meaning

localize() should never become a replacement for the Model.

For example:

#![allow(unused)]
fn main() {
localize("user.status")
}

does not determine whether a user is active.

The Model determines:

#![allow(unused)]
fn main() {
User::status
}

Localization determines how that status is presented:

#![allow(unused)]
fn main() {
localize("user.status.active")
}

The distinction remains:

Model
  ↓
Meaning
  ↓
Localization
  ↓
Language
  ↓
View

This is especially important when LLMs are involved.

An LLM can help express meaning.

It should not silently redefine the application’s underlying meaning.

Higher-Level Localization Functions

Localization can also be wrapped by ordinary Rust functions.

For example:

#![allow(unused)]
fn main() {
fn user_status(status: UserStatus) -> LocalizedText {
    match status {
        UserStatus::Active =>
            localize("user.status.active"),

        UserStatus::Pending =>
            localize("user.status.pending"),

        UserStatus::Inactive =>
            localize("user.status.inactive"),
    }
}
}

The application can then use:

#![allow(unused)]
fn main() {
text(user_status(user.status()))
}

This keeps domain vocabulary in ordinary Rust while leaving language resolution to Beverly.

The framework provides localization. The application provides the vocabulary.

What Localize Does Not Do

The localization system does not own:

• Application state
• Domain meaning
• Business rules
• User permissions
• LLM decision-making
• Translation approval
• Content policy
• Application workflow

It provides the language layer between application meaning and user presentation.

LLMs can participate in that layer, but they remain another source of generated language rather than becoming the source of truth for application state.

The Model

The complete conceptual model is intentionally simple:

Application Meaning
        ↓
 Localization Key
        ↓
      Locale
        ↓
 Translation / LLM
        ↓
 Localization History
        ↓
       View

The locale can change.

The text can change.

An LLM can generate alternatives.

The user can step backward or forward.

The application can rewind.

But the semantic identity of the content remains stable.

One key. Many languages. Many representations. Reversible history.

The Principle

Traditional localization answers:

“What string corresponds to this key in this language?”

Beverly’s localization system can answer a broader question:

“How should this application meaning be expressed, in this language, right now?”

That distinction matters for AI-native applications.

A human translator can provide the text.

A translation service can provide the text.

An LLM can generate alternatives.

A user can review them.

An agent can evaluate them.

And the application can move backward and forward through the resulting history.

All of those operations still operate on the same underlying localization key.

Create. Resolve. Generate. Review. Navigate. Accept. Rewind.

The key represents meaning. The locale represents language. The history represents alternatives. The LLM provides another way to express the meaning.

AI Workloads, Background Workers & Channels

Beverly does not need a special AI programming model. An AI workload is simply another piece of application work. It may take a long time to complete, it may produce results incrementally, and it may need to communicate with the rest of the application while it is running, but the underlying problem is not unique to AI. Rust, Bevy, and ordinary application architecture already provide the tools needed to handle it.

The most important rule is to keep long-running work away from the main UI loop. Inference, RAG retrieval, embedding generation, document processing, network requests, and tool calls can all take enough time to make a UI unresponsive if they are performed directly as part of the main application work. Instead, run that work in the background and communicate the results back to the application.

A simple architecture looks like this:

AI Worker → Channel → Model → View

The worker performs the expensive work, a standard Rust channel carries the results back to the application, and the Model becomes the owner of those results. On the next Bevy tick, the View reflects the updated Model state automatically. The AI code does not need to know how the UI is rendered, and the UI does not need to know how inference was performed.

Background Workers

Bevy already provides mechanisms for running work outside the main application loop, while Rust provides standard concurrency primitives such as channels. Beverly should use these existing tools rather than recreate them as another abstraction. Bevy provides the runtime, Rust provides the concurrency primitives, and the application can use whatever AI library, local model, remote service, vector database, or other technology makes sense for the workload.

For example, an AI worker might perform inference and send partial results through a channel:

#![allow(unused)]
fn main() {
enum AiMessage {
    Token(String),
    Complete,
    Error(String),
}
}

As the worker receives tokens, it can send them back to the application:

#![allow(unused)]
fn main() {
tx.send(AiMessage::Token(token))?;
}

The application receives those messages and updates the Model:

#![allow(unused)]
fn main() {
while let Ok(message) = rx.try_recv() {
    match message {
        AiMessage::Token(token) => {
            chat.append_response(&token);
        }

        AiMessage::Complete => {
            chat.set_status(ChatStatus::Complete);
        }

        AiMessage::Error(error) => {
            chat.set_error(error);
        }
    }
}
}

The important part is what happens after the message is received. The response is immediately saved into the Model, and on the next tick the View sees the new state and updates automatically. There is no need to manually find a text component and update it every time a token arrives. Streaming is simply the normal Model → View relationship happening repeatedly as new data becomes available.

Streaming AI Responses

Streaming therefore does not require a special UI architecture. It is simply a case where the Model changes incrementally instead of all at once.

Suppose the Model contains the current response:

#![allow(unused)]
fn main() {
struct Chat {
    response: String,
}
}

The Model can expose ordinary getters and setters:

#![allow(unused)]
fn main() {
impl Chat {
    fn get_response(&self) -> &str {
        &self.response
    }

    fn set_response(&mut self, response: String) {
        self.response = response;
    }

    fn append_response(&mut self, token: &str) {
        self.response.push_str(token);
    }
}
}

The straightforward getter/setter approach makes the architecture particularly clear. Conceptually, each new token becomes part of the existing response:

#![allow(unused)]
fn main() {
chat.set_response(
    chat.get_response().to_owned() + &token
);
}

For an efficient implementation, the Model can instead expose an append operation:

#![allow(unused)]
fn main() {
chat.append_response(&token);
}

Both approaches express the same architectural principle: the AI response belongs to the Model. The append method is simply a more efficient way of implementing the same state transition without repeatedly constructing a new String.

The View only needs to read the current state:

#![allow(unused)]
fn main() {
text(chat.get_response())
}

The AI worker should not reach into the UI and call set_text() every time it receives a token. set_text() is a normal component-level setter and is useful when configuring or directly modifying a text component:

#![allow(unused)]
fn main() {
text("Hello")
    .set_text("Hello, world!");
}

That is different from application state. For application data, the response belongs to the Model, and the normal path remains AI result → Model setter → View. This distinction becomes increasingly valuable as an application grows because the same response can be displayed in multiple places, persisted, inspected, or consumed by other parts of the application without being trapped inside a UI component.

AI Work Is Still Application Work

Once this pattern is established, more complicated AI workloads do not require a different architecture. A RAG workflow might generate an embedding, search a vector index, retrieve documents, construct context, invoke an LLM, and stream the resulting response. Those steps can all happen in ordinary Rust code, with the channel carrying meaningful results back to the application as they become available.

For example:

#![allow(unused)]
fn main() {
enum AiMessage {
    Searching,
    ContextFound(Vec<Document>),
    Token(String),
    Complete,
    Error(String),
}
}

The application can translate those messages into Model state:

#![allow(unused)]
fn main() {
while let Ok(message) = rx.try_recv() {
    match message {
        AiMessage::Searching => {
            chat.set_status(ChatStatus::Searching);
        }

        AiMessage::ContextFound(documents) => {
            chat.set_context(documents);
        }

        AiMessage::Token(token) => {
            chat.append_response(&token);
        }

        AiMessage::Complete => {
            chat.set_status(ChatStatus::Complete);
        }

        AiMessage::Error(error) => {
            chat.set_error(error);
        }
    }
}
}

The View remains ordinary Beverly code:

#![allow(unused)]
fn main() {
chat_view(chat)
}

Nothing about RAG requires the UI to become an AI-specific UI. The AI performs the work and produces results; the application decides how those results become state and how that state is presented.

This is an important Beverly principle: AI should fit into the application, rather than forcing the application to become an AI framework.

AI Tool Calls

The same principle applies when an AI needs to take an action. Suppose the application already exposes a Command for retrieving orders:

#![allow(unused)]
fn main() {
Command::Orders::Get {
    user_id: user.get_id(),
}
}

A human interface might trigger that Command through a Button. An API could trigger the same Command from an external request, and an AI could determine that retrieving the orders is the appropriate next step. There should not need to be three different implementations of “get orders” simply because there are three different sources of the request.

The Command is the application’s existing vocabulary for that action, so every participant should use it.

This is where JEV fits naturally into the architecture.

JEV Chooses From Existing Commands

JEV does not create application behavior. The application defines its available Commands, and JEV provides a structured way for an AI to choose between those Commands.

For example, an application might already define:

#![allow(unused)]
fn main() {
Command::Orders::Get
Command::Orders::Cancel
Command::Orders::Refund
Command::User::Notify
}

JEV can choose from those existing actions:

#![allow(unused)]
fn main() {
Jev::choice("next_action", [
    Command::Orders::Get,
    Command::Orders::Cancel,
    Command::Orders::Refund,
])
}

The AI is therefore operating inside the application’s existing vocabulary. It is not generating arbitrary code, inventing an API, or creating new application capabilities at runtime. The developer defines what the application is capable of doing, while JEV provides the structured decision that determines which of those capabilities should be used.

This distinction is particularly useful for reasoning about agents. An agent does not necessarily need its own set of tools, execution framework, or application architecture. The application already has actions. The AI needs a way to observe what is happening, decide what should happen next, and request one of the actions that the application already understands.

That gives us a simple principle:

Commands define what the application can do. JEV chooses what to do.

Once JEV has selected a Command, the request follows the same Controller path as any other Command:

JEV
 ↓
Command
 ↓
Controller
 ↓
Model
 ↓
View

This shared path is also what makes the permission model powerful. The Model is the authoritative owner of application state and the rules governing whether that state is allowed to change. Because requests from humans, APIs, automations, and AI all ultimately reach the same Model, they all encounter the same permission and domain rules.

If the Model determines that an operation is not allowed, it can reject the state transition regardless of who requested it. JEV cannot grant itself additional capabilities simply by choosing a Command, because choosing a Command is not the same thing as being authorized to perform it. The Command expresses the requested action; the Model decides whether that action is valid and permitted against the current application state.

For example, an AI may choose:

#![allow(unused)]
fn main() {
Command::Orders::Refund {
    order_id: order.get_id(),
}
}

The Controller connects that Command to the appropriate Model operation. The Model then makes the authoritative decision about whether the refund is allowed:

#![allow(unused)]
fn main() {
orders.refund(order.get_id())?;
}

The Model can consider whatever rules belong to the application’s state and domain: whether the order exists, whether it has already been refunded, whether it is in a refundable state, whether the operation is permitted for the current actor, or any other invariant the application requires.

This means the permission layer does not need to trust the source of the request. It only needs to enforce the rules at the point where state changes.

That gives Beverly an important security property: the same Model rules apply regardless of whether the request came from a human or an AI.

The Controller can still handle application-level concerns such as orchestration, confirmation flows, rate limiting, auditing, and other policies that belong outside the Model. But the Model remains the final authority over its own state and the domain rules governing how that state can change.

JEV therefore does not become a privileged pathway around the application. It is simply another way to request an existing Command, and that Command must still pass through the same application machinery as every other request.

AI and the Event Vocabulary

This becomes even more powerful when combined with Beverly Events. The application already has a vocabulary describing things that happened and things that can be requested.

Facts describe things that have happened:

#![allow(unused)]
fn main() {
User::Created
Order::Cancelled
Document::Indexed
}

Commands describe things that can be requested:

#![allow(unused)]
fn main() {
User::Create
Order::Cancel
Document::Index
}

An AI can listen to Facts, reason about the current state, and choose an existing Command through JEV. The resulting Command then enters the same Controller that handles Commands from every other source.

Because JEV operates through this existing Event system, AI decisions are automatically part of the application’s event history. Beverly does not need a separate AI logging mechanism, a separate replay system, or additional instrumentation just to understand what an agent did. The JEV decision, the resulting Command, and the subsequent application Events can participate in the same history as everything else.

This makes rewinding and replaying AI behavior a natural consequence of the architecture. If the application records its Events, an AI decision that resulted in a Command is already part of that Event stream. Replaying the history can therefore reproduce the sequence of decisions and resulting actions without requiring a second AI-specific development effort.

The same mechanism also makes AI behavior inspectable. A developer can look at the event history and see what happened, which Command JEV selected, what state the application was in, and what happened afterward. When the event system supports rewind and replay, those capabilities apply to AI behavior automatically because the AI is participating in the same event system.

In that sense, observability and replay are not features that have to be bolted onto the agent later. They are inherited from the application’s existing architecture.

An agent can therefore be understood as a participant in the application’s existing event vocabulary. It listens to what happened, makes a decision, and requests something that the application already knows how to do. The Model remains the authority over whether the requested state transition is actually allowed.

Listen → Decide → Command

JEV provides the structured decision, the Controller provides the application wiring, the Model provides the state and enforces its rules, and the Event system provides the history through which those decisions can be observed, replayed, and rewound. Nothing about this requires a second application architecture for AI.

Tool Results Become Model State

Once a Command runs, its result follows the same application path as any other application data. If an AI requests the user’s orders, for example, the resulting data can simply become Model state:

#![allow(unused)]
fn main() {
orders.set_items(result);
}

The View can then render those orders:

#![allow(unused)]
fn main() {
table(orders.get_items())
}

The AI does not need to update the table directly. It updates application state, and the View follows that state.

This means AI-generated data, database data, user-entered data, and data returned by external services can all participate in the same Model → View relationship. The source of the data may be completely different, but once it enters the Model, the rest of the application does not need a special mechanism to display it.

The same principle applies to authorization. If the result would cause a state transition, it goes through the Model’s rules rather than creating a separate AI-specific path. The Model remains the place where the application decides what is valid and what is permitted.

AI, JEV, and Beverly

The resulting architecture deliberately keeps each responsibility small. Rust provides concurrency, channels, types, and resource management. Bevy provides the runtime and mechanisms for background execution. AI code performs inference, RAG, retrieval, tool calls, or whatever workload the application requires. Channels carry results from that background work into the application.

The Model owns application state and the rules governing how that state may change. Commands define the actions the application can request, while the Controller connects those actions to the rest of the application. JEV sits alongside these pieces as the structured decision layer for AI: it can choose from the Commands that the application already exposes, but it does not bypass the Model’s rules.

Because JEV participates in the same Event system as the rest of the application, its decisions also inherit the application’s existing observability, history, replay, and rewind capabilities. There is no separate AI event log to maintain and no additional replay architecture to build simply because an AI is making decisions.

This means a chatbot, RAG system, tool-using agent, streaming inference pipeline, or JEV-driven agent can all be built using the same underlying architecture.

There is no need to turn Beverly into an AI framework to accomplish this. The AI simply becomes another participant in the application.

The worker does the work, the channel carries the result, the Model owns the state and decides whether state changes are allowed, JEV chooses from existing Commands, the Controller connects the action, the Event system records the decision and its consequences, and Beverly reflects the resulting state.

That is the goal: AI should use the application’s architecture rather than replacing it.

Components Overview

API status: The executable component API is the fluent app().children / UiElement surface and the concrete component reference pages. Some older composition examples in this book are design sketches; conceptual helpers are labeled as planned and should not be copied as compiling code.

Components Overview

Beverly components are the reusable building blocks that sit on top of Bevy’s ECS and layout system. They are designed to feel native in Rust applications while still being themeable, accessible, and easy to compose into larger screens.

Component model

A typical Beverly widget is a small stateful unit with these concerns:

• semantic structure and labels
• layout and sizing rules
• interaction state and keyboard focus
• theming via design tokens
• paint and material treatment when needed

This matches the pattern used in systems like block_studio: UI widgets are built from a small shared surface model, then specialized with different semantic and visual treatments. Title and text follow the same rule: they are lightweight content primitives that inherit the app’s typography and surface rules instead of carrying their own isolated styling system.

Composition model

Beverly components are meant to be composed into app shells, form sections, toolbars, panels, and data surfaces. The best results usually come from building the screen in layers:

1. start with layout primitives such as stacks, grids, containers, and panels
2. add semantic content blocks like titles, text, cards, and badges
3. add interaction primitives like buttons, inputs, toggles, and selects
4. place contextual controls such as dropdowns, modals, and tooltips where they help the task
5. apply motion, effects, and visual emphasis only where they improve clarity

Title

Titles are the high-emphasis text primitive for screens, panels, cards, and section headers. Use them when you need a clear hierarchy marker that tells the user what area they are looking at.

In practice, titles work best when they are short, direct, and placed near the top of the relevant surface. The implementation pattern from block_studio is to treat title text as a reusable semantic block rather than a one-off label, so the same component can be used across app shells, cards, and page headers.

Text

Text is the default body-content primitive. Use it for descriptions, helper copy, metadata, and any other supporting content that should inherit the app’s global font and scale.

Text should stay flexible: the same primitive can render dense copy in a card, supporting notes under a title, or lightweight explanatory content in a panel. In block_studio-style composition, text is usually added as a child of a larger surface so it follows the same layout, spacing, and typography decisions as the rest of the interface.

Composition pattern

#![allow(unused)]
fn main() {
use bevy::prelude::*;
use beverly::prelude::*;

fn build_dashboard(mut commands: Commands) {
    commands.spawn((
        NodeBundle::default(),
        BeverlyStack::vertical(),
    )).with_children(|parent| {
        parent.spawn(BeverlyCard::new("Summary")).with_children(|card| {
            card.spawn(text("Realtime metrics and AI actions"));
        });
        parent.spawn(BeverlyButton::primary("Open report"));
    });
}
}

Recommended usage

• Start with layout primitives such as stacks and containers.
• Add semantic content blocks such as cards and badges.
• Then layer in interactive controls such as buttons, toggles, and inputs.
• Finally apply rendering effects such as shadows, gradients, or glass surfaces only where they add clarity.

Catalog

• buttons for primary actions
• title for section and page hierarchy
• text for supporting copy and body content
• inputs and selects for editable data
• modals and toasts for important feedback
• tables and pagination for dense data views
• navigation, tabs, and search for multi-surface applications
• avatars, badges, and dividers for compact interface signals

Each component should remain legible in light and dark themes and degrade gracefully when motion or contrast settings are reduced.

Button

button() starts a primary BeverlyButton builder. Add its visible content with .text(...) or .icon(...), attach an application callback with .on("click", ...), or provide an ordered set of ButtonChild values with .children(...).

For ordinary text content elsewhere in a Beverly app, use text("..."). It creates a Bevy Text component that is picked up by Beverly’s default typography pipeline.

#![allow(unused)]
fn main() {
use bevy::prelude::*;
use beverly::prelude::*;

fn save_document(_commands: &mut Commands, _button: Entity) {
	// Update application state or write an application message here.
}

app()
	.children([button().text("Save").icon("save").on("click", save_document)])
	.run();
}

BeverlyPlugin installs ButtonPlugin. If the component is used without the aggregate plugin, add ButtonPlugin yourself.

Live Demo

Open the demo in a separate tab. The embedded canvas supports pointer interaction; use the top-right control to switch between light and dark themes.

To regenerate the bundle locally, install the wasm32-unknown-unknown target and Trunk 0.21.14, then run:

mdbook build docs
bash web/button-demo/build.sh

The Pages workflow builds and publishes this bundle automatically.

Live Demo: Buttons

Open the demo in a separate tab.

Content

The convenience constructors remain available when the label is known at the call site:

#![allow(unused)]
fn main() {
let primary = BeverlyButton::primary("Save");
let danger = BeverlyButton::danger("Delete").disabled(true);
let text_only = BeverlyButton::text_button("Learn more");
}

The fluent form is useful when content is assembled conditionally:

#![allow(unused)]
fn main() {
let save = button().text("Save");
let icon_only = button().icon("save");
let custom = button().children([
	ButtonChild::icon("save"),
	ButtonChild::text("Save document"),
	ButtonChild::custom(spawn_badge),
]);
}

Custom children are setup functions with signature fn(&mut ChildSpawnerCommands, Color):

#![allow(unused)]
fn main() {
fn spawn_badge(parent: &mut ChildSpawnerCommands, color: Color) {
	parent.spawn((text("NEW"), TextColor(color)));
}
}

The first text child is used as the accessible name for a custom-content button. Icon-only buttons should add a text child or provide an application accessible-name component rather than relying on the icon name.

Activation

.on("click", save_document) accepts a function pointer with the signature fn(&mut Commands, Entity). This keeps application behavior outside the component while allowing the button to invoke the command when it is pressed by pointer or keyboard activation:

#![allow(unused)]
fn main() {
fn open_settings(commands: &mut Commands, button: Entity) {
	commands.entity(button).insert(SettingsRequested);
}

let settings = button().text("Settings").on("click", open_settings);
}

Supported event names include click, clickdown/pointerdown, clickup/pointerup, mouseenter/pointerenter, mouseleave/pointerleave, mousemove/pointermove, doubleclick, dragstart, dragmove, dragend, dragcancel, longpress, scroll, load, and unload.

load runs when the button is added to the world. unload runs when its BeverlyButton component is removed. Pointer and gesture handlers use the same callback signature: fn(&mut Commands, Entity).

Disabled buttons do not invoke pointer, click, or gesture handlers. Buttons do not emit application events; all application behavior must be attached explicitly with .on(...).

Content

Content components give a Beverly view its internal structure. They decide how information is grouped, ordered, and related so that a screen remains readable as its content grows.

The goal is not to make every view look the same. It is to give each piece of content a clear responsibility and a predictable place in the composition.

Content
│
├── Container
│   └── Defines the boundary of a content region
│
├── Row / Column
│   └── Arrange related content along a clear axis
│
├── Stack
│   └── Sequences content with consistent spacing
│
└── Children
	└── Express the relationship between a parent and its content

Content components shape the View, but they do not own application state or business rules. The Model remains the source of truth, while the View uses these primitives to present that state and collect interaction.

When choosing a content primitive, start with the relationship you need to express:

• use a container to establish a boundary and shared context
• use a row or column to make an explicit horizontal or vertical arrangement
• use a stack when the main concern is sequencing items with consistent space
• use children to make parent-child composition clear

This keeps the structure easy to read, easy to change, and local to the part of the interface it describes.

Container

Containers define the boundary of a content region. They give related children a shared width, alignment, and context so that a view can grow without becoming a loose collection of unrelated elements.

When to use

Use a container when you need to:

• establish the readable boundary of a page or panel
• align a heading, body, and actions to the same content edge
• group a section that has one clear purpose
• keep internal rows, columns, or stacks inside a predictable region

A container is especially useful at the point where page structure becomes local content structure. Use a row or column inside it to describe how that content is arranged.

Composition model

A container should provide context without hiding the hierarchy of its children. Give it a clear purpose, then let rows, columns, stacks, and individual components express the relationships inside that boundary.

Container
├── Heading
├── Content region
│   ├── Row
│   └── Column
└── Actions

The container owns the region’s boundary and alignment. Its children remain responsible for their own semantics, presentation, and interaction.

Example structure

#![allow(unused)]
fn main() {
use bevy::prelude::*;
use beverly::prelude::*;

fn build_workspace_panel(mut commands: Commands) {
	commands.spawn((
		NodeBundle::default(),
		BeverlyContainer::new(),
	)).with_children(|container| {
		container.spawn(BeverlyTitle::new("Workspace"));
		container.spawn(text("Review the latest activity."));
		container.spawn(BeverlyButton::primary("Open workspace"));
	});
}
}

The container makes these elements read as one panel without deciding what the workspace data means or what happens when the button is pressed. The Model owns the data, and the View presents it within the container’s boundary.

Guidance

• give each container a clear content boundary and purpose
• align related headings, content, and actions to the same edge
• keep internal structure explicit with rows, columns, or stacks
• avoid stretching dense content across the full viewport
• do not use a container as a substitute for semantic grouping or state ownership

Card

Live Demo: Card

Open the demo in a separate tab.

Live Demo: Cards

Open the demo in a separate tab.

A Card is a container for related content.

It provides a visual boundary around a group of components so that information, controls, and other content can be presented as a single coherent unit. A Card does not own the meaning of its contents, does not own application state, and does not decide what the application should do with the information inside it.

Cards are intentionally simple. They provide structure, presentation, composition, and optional interaction without becoming an application-specific abstraction.

The Card provides the surface. Its contents provide the meaning.

Basic Card

The simplest Card contains one piece of content.

#![allow(unused)]
fn main() {
card()
    .children(text(localize("user.profile")))
}

More commonly, a Card contains several components:

#![allow(unused)]
fn main() {
card()
    .children([
        text(localize("user.name")),
        text(localize("user.email")),
        button().text(localize("user.edit")),
    ])
}

The Card does not need to understand what the content represents. It simply provides a container in which the components can be composed.

This makes the Card useful for dashboards, settings, profiles, documents, agent activity, data records, notifications, and almost any other interface where related information benefits from a visual boundary.

Composition

children() is the fundamental composition mechanism.

A Card can contain a single value:

#![allow(unused)]
fn main() {
card()
    .children(text(localize("user.profile")))
}

Or many values:

#![allow(unused)]
fn main() {
card()
    .children([
        text(localize("user.profile")),
        text(localize("user.description")),
        button().text(localize("user.edit")),
    ])
}

Those children can themselves be Cards or any other Beverly components:

#![allow(unused)]
fn main() {
card()
    .children([
        card()
            .children(text(localize("user.account"))),

        card()
            .children(text(localize("user.preferences"))),
    ])
}

There is no separate composition system for Cards. A Card uses the same children() primitive as the rest of Beverly.

Build the primitive once. Compose it everywhere.

Named Sections

Cards implement .header(...), .body(...), and .footer(...) as top, middle, and bottom content regions. Regions always render in that order, regardless of builder-call order. Each accepts one UiElement or an iterable of elements; repeated calls append to the same region.

#![allow(unused)]
fn main() {
card()
    .header(text(localize("user.profile")))
    .body([
        text(localize("user.name")),
        text(localize("user.email")),
    ])
    .footer(button().text(localize("user.edit")))
}

These sections are implemented by Beverly as child entities carrying CardHeader, CardBody, and CardFooter markers. They do not replace children(): when sections are used, ordinary children join the body before explicit body content. The body grows to fill available card height, keeping the header at the top and footer at the bottom. Without sections, ordinary children retain their existing direct-child layout.

The concrete fluent constructor is UiElement::card(), available through beverly::prelude::*:

#![allow(unused)]
fn main() {
UiElement::card()
    .header(text("Account"))
    .body(text("Account information"))
    .footer(button().text("Save"))
}

The same sections can accept one value or multiple values:

#![allow(unused)]
fn main() {
card()
    .header([
        icon("user"),
        text(localize("user.profile")),
    ])
    .body([
        text(localize("user.name")),
        text(localize("user.email")),
        badge(localize("user.active")),
    ])
}

This gives applications a useful vocabulary for common layouts while keeping the underlying composition model simple.

Styling

A Card is commonly configured through chained style methods.

#![allow(unused)]
fn main() {
card()
    .padding(16)
    .radius(12)
    .shadow(4)
    .children([
        text(localize("user.profile")),
        text(localize("user.description")),
    ])
}

Styling remains part of the component configuration rather than requiring a separate stylesheet or styling abstraction.

Because these methods compose naturally, the same Card primitive can be used across an application’s design system:

#![allow(unused)]
fn main() {
card()
    .padding(24)
    .radius(16)
    .children([
        icon("database"),
        text(localize("database.status")),
        badge(localize("database.connected")),
    ])
}

The exact visual treatment can belong to the application’s design system while the underlying Card remains the same reusable primitive.

Card State

Cards can respond to state when the application needs state-specific presentation.

#![allow(unused)]
fn main() {
UiElement::card()
    .hover(|style| style.scale(1.02))
    .success_style(|style| style.border_width(2).border_color("#16a34a"))
    .children([text("Remote resource")])
}

Hover styling reads pointer interaction on the Card or its descendants. A Card is not focusable by default, so focused styles require the app to make it focusable and request focus. To use app-owned status styling, attach a FormStatusState to the Card entity:

#![allow(unused)]
fn main() {
let card = UiElement::card()
    .success_style(|style| style.border_color("#16a34a"))
    .body(text("Remote resource"))
    .spawn_in_context(&mut context);
context.world.entity_mut(card).insert(FormStatusState {
    status: FormStatus::Success,
});
}

Card style callbacks do not accept model predicates. Set status on the entity from app code, or attach a SemanticNode/interaction component for its corresponding interaction state. Card itself does not have a disabled policy.

Interactive Cards

A Card is not inherently interactive.

If an application wants a Card to respond to pointer or keyboard interaction, that interaction should be explicitly declared rather than being assumed from the component’s appearance.

#![allow(unused)]
fn main() {
card()
    .label(localize("document.card.label"))
    .aria(localize("document.card.description"))
    .on("click", Command::Document::Open)
    .children([
        text(Document::title),
        text(Document::summary),
    ])
}

The important part is that the Card still does not know what Command::Document::Open means. The Card produces a UI Event, and application wiring determines what happens next.

For a UI-specific interaction, the Card can expose an abstract UI Event:

#![allow(unused)]
fn main() {
card()
    .label(localize("document.card.label"))
    .aria(localize("document.card.description"))
    .on("click_start", Ui::DocumentCard::Pressed)
    .on("click_end", Ui::DocumentCard::Released)
    .on("click", Ui::DocumentCard::Clicked)
}

The distinction is the same as with Button:

UI interaction
      ↓
Ui::DocumentCard::Clicked
      ↓
application wiring
      ↓
Command::Document::Open

The Card does not need to know that it represents a document. It only exposes the interface interaction.

Accessibility

A purely visual Card that only contains content does not automatically become an interactive control simply because it looks like one.

When a Card is interactive, its accessible identity and description should be explicit:

#![allow(unused)]
fn main() {
card()
    .label(localize("document.card.label"))
    .aria(localize("document.card.description"))
    .on("click", Command::Document::Open)
    .children([
        text(Document::title),
        text(Document::summary),
    ])
}

This is particularly important for Cards that visually resemble buttons, links, selectable records, or other controls.

The visual appearance should not be the only indication of what the Card does. Its semantics should be represented explicitly in the component configuration.

A visual container is not automatically an interactive control.

Data-Driven Cards

Cards become especially useful when their contents come from application data.

#![allow(unused)]
fn main() {
card()
    .header(text(User::name))
    .body([
        text(User::email),
        badge(User::status),
    ])
}

The Card does not own User. It receives a projection of application state and presents it.

This means the same Card structure can represent many records:

#![allow(unused)]
fn main() {
users.iter()
    .map(|user| {
        card()
            .header(text(user.name()))
            .body([
                text(user.email()),
                badge(user.status()),
            ])
    })
}

The Model remains the source of truth. The View turns that state into Cards.

This separation is important for AI-generated applications because the component does not need to understand where its data came from. The same Card can present database records, API responses, local files, streams, or AI-generated data.

Conditional Content

Cards can also compose content based on application state.

#![allow(unused)]
fn main() {
card()
    .children([
        text(User::name),

        if User::is_active {
            badge(localize("user.active"))
        } else {
            badge(localize("user.inactive"))
        },
    ])
}

The Card remains responsible only for presenting the resulting composition.

The decision about whether a user is active belongs to application state or domain logic, not to the Card itself.

Loading and Async State

A Card can present loading state without implementing the operation that is loading.

#![allow(unused)]
fn main() {
card()
    .children([
        text(localize("document.title")),
        text(Document::summary),
    ])
    .submitting_style(|style| style.opacity(0.5))
}

A richer presentation can replace or augment its contents:

#![allow(unused)]
fn main() {
card()
    .children([
        text(Document::title),
        text(Document::summary),
    ])
    .submitting(|| [
        spinner(),
        text(localize("document.loading")),
    ])
}

The Card does not perform the asynchronous operation. It presents the state produced by the application.

This follows the same principle used throughout Beverly:

The Model owns the state. The View presents the state. Events describe interaction. Controllers connect interaction to application behavior.

Error and Success Presentation

Cards can present application state such as errors or successful operations.

#![allow(unused)]
fn main() {
card()
    .error(|errors| text(errors.join("\n")))
    .success(|| [
        icon("check"),
        text(localize("document.saved")),
    ])
}

The messages should come from the application’s localization and state mechanisms rather than being hard-coded into the component.

The Card presents the meaning supplied by the application; it does not decide what constitutes an error or success.

Cards Within Cards

Because Cards are ordinary composable components, they can contain other Cards.

#![allow(unused)]
fn main() {
card()
    .header(text(localize("dashboard")))
    .body([
        card()
            .children([
                text(localize("users")),
                text(User::count),
            ]),

        card()
            .children([
                text(localize("documents")),
                text(Document::count),
            ]),
    ])
}

This is useful for dashboards and hierarchical interfaces, but it is not a special Card feature. It is simply the result of components being composable.

children() provides the common language.

Card Events

When interaction is required, Card Events should remain about the Card’s UI lifecycle.

#![allow(unused)]
fn main() {
card()
    .label(localize("document.card.label"))
    .aria(localize("document.card.description"))
    .on("click_start", Ui::DocumentCard::Pressed)
    .on("click_end", Ui::DocumentCard::Released)
    .on("click", Ui::DocumentCard::Clicked)
}

These Events can be used independently of application Commands.

For example, a pressed Event could control a visual effect:

#![allow(unused)]
fn main() {
.on("click_start", Ui::DocumentCard::Pressed)
}

while the completed interaction can be connected to application behavior:

#![allow(unused)]
fn main() {
.on("click", Command::Document::Open)
}

This keeps the component’s vocabulary independent from the application’s domain vocabulary.

The Card reports interaction. The application decides what the interaction means.

The Card Contract

The Card has a deliberately small conceptual contract:

Create. Configure. Compose. Present. Optionally interact.

A Card provides:

• visual structure
• spacing and presentation
• composition through children()
• optional semantic sections such as header, body, and footer
• state-specific presentation
• accessibility semantics when acting as an interactive control
• UI Events when interaction is required

It does not own:

• application data
• business rules
• domain validation
• application Commands
• database operations
• API operations
• agent behavior

Those concerns belong elsewhere in the architecture.

The result is a component that can be reused from a simple settings page to a high-throughput enterprise dashboard without changing what a Card fundamentally is.

The Card is a container, not an application.

Row

Rows arrange related content along a horizontal axis. They make the relationship between items explicit when those items belong together but should remain distinct: a label and value, a group of actions, or a set of compact controls.

When to use

Use a row when horizontal order carries meaning or helps users scan a group quickly. Rows work well for:

• headings paired with actions
• labels paired with status or metadata
• short groups of buttons, filters, or navigation items
• compact content that should share one visual line

Use a column when the content needs a vertical reading order. Use a stack when consistent spacing and linear flow matter more than the specific horizontal relationship between items. Use a grid when several items need repeated alignment across both rows and columns.

Composition model

A row should have one clear purpose and a small number of related children. Each child keeps its own semantic role, while the row provides the shared alignment and spacing that makes the group read as one unit.

Row
├── Label
├── Supporting content
└── Action

Prefer stable alignment over decorative variation. Keep the primary content easy to find, place actions consistently, and allow long content to wrap or yield space rather than pushing related controls out of view.

Example structure

#![allow(unused)]
fn main() {
use bevy::prelude::*;
use beverly::prelude::*;

fn build_status_row(mut commands: Commands) {
	commands.spawn(NodeBundle::default()).with_children(|row| {
		row.spawn(text("Sync status"));
		row.spawn(Badge::new("Up to date"));
		row.spawn(BeverlyButton::secondary("Details"));
	});
}
}

The row is responsible for the relationship between these children. The Model still owns the status, and the View decides how that state should be presented. Keeping those responsibilities separate makes the row easy to reuse and change.

Guidance

• keep children related by meaning, not only by proximity
• use consistent alignment when several rows appear in the same view
• reserve the most stable space for the primary label or value
• avoid placing unrelated actions in the same row
• switch to a column when the content becomes difficult to scan horizontally

Column

Columns arrange related content along a vertical axis. They establish a reading order from top to bottom, making them the natural structure for forms, detail panels, settings sections, and other content that should unfold progressively.

When to use

Use a column when vertical order carries meaning or when each item needs room to be understood before the next one appears. Columns work well for:

• page and panel sections
• forms with labels, fields, and validation messages
• titles followed by supporting content
• detail views with metadata and actions
• stacked controls that should remain easy to scan

Use a row when related items belong on one horizontal line. Use a stack when the main concern is consistent spacing between a sequence of children. Use a grid when repeated content needs alignment across multiple columns.

Composition model

A column should follow the way a user reads or completes the content. Put the most important context first, keep supporting information close to the content it explains, and place actions where they naturally follow from the preceding information.

Column
├── Heading
├── Supporting content
├── Primary content
└── Actions

Each child keeps its own semantic role. The column provides the shared order, width, and spacing that lets those roles read as one coherent section.

Example structure

#![allow(unused)]
fn main() {
use bevy::prelude::*;
use beverly::prelude::*;

fn build_settings_column(mut commands: Commands) {
	commands.spawn((
		NodeBundle::default(),
		BeverlyStack::vertical(),
	)).with_children(|column| {
		column.spawn(BeverlyTitle::new("Workspace settings"));
		column.spawn(text("Manage the defaults for this workspace."));
		column.spawn(BeverlyInput::new("Workspace name"));
		column.spawn(BeverlyButton::primary("Save changes"));
	});
}
}

The column shapes the View, but it does not own the settings or the save operation. The Model remains the source of truth, and an event or controller action can handle the user’s intent when the button is pressed.

Guidance

• order children according to the user’s reading or completion flow
• keep related labels, content, and actions close together
• use consistent widths when several columns appear in the same view
• give dense sections enough vertical spacing to preserve hierarchy
• move to a row only when items are genuinely related on the same horizontal line

Stack

Stacks sequence related content with consistent spacing. They are the simplest way to create a predictable flow when the order of children matters more than a specialized alignment relationship.

A stack can run vertically or horizontally. The direction determines the reading flow; the spacing gives each child enough separation to remain distinct without breaking the group into unrelated pieces.

When to use

Use a stack when the interface should feel linear and easy to follow. Stacks work well for:

• forms and settings sections
• headings followed by supporting content
• lists of related items
• action groups and compact controls
• cards or panels with a consistent internal rhythm

Use a row when the horizontal relationship between specific children is the important part. Use a column when you need to describe a vertical hierarchy. Use a grid when repeated items need alignment across both axes.

Composition model

A stack should contain children that belong to the same sequence. It provides the rhythm between those children, while each child remains responsible for its own meaning and interaction.

Stack
├── First item
├── Second item
└── Third item

Choose vertical flow for reading, completion, and narrative order. Choose horizontal flow for short groups of controls or values that users should scan as one line. When a horizontal group becomes too long or wraps unpredictably, move it into a vertical stack or a more structured layout.

Example structure

#![allow(unused)]
fn main() {
use bevy::prelude::*;
use beverly::prelude::*;

fn build_project_setup(mut commands: Commands) {
	commands.spawn((
		NodeBundle::default(),
		BeverlyStack::vertical(),
	)).with_children(|stack| {
		stack.spawn(BeverlyTitle::new("Project setup"));
		stack.spawn(BeverlyInput::new("Workspace name"));
		stack.spawn(BeverlyButton::primary("Create workspace"));
	});
}
}

The stack controls the order and spacing of the setup flow. It does not own the workspace value or the create operation. The Model owns the data, while the View presents the form and emits the user’s intent through the application’s event and controller flow.

Guidance

• keep all children in a stack related by sequence or purpose
• use one spacing rhythm for items at the same level
• prefer vertical stacks for content that must be read or completed in order
• keep horizontal stacks short enough to scan without wrapping
• use nested stacks sparingly and give each one a clear responsibility

Content & Children

Beverly components are designed to be composed through the shared UiElement tree. text(...), button(), input(...), checkbox(), alert(...), toast(...), card(), list_item(...), form(...), radio(...), table(...), tabs(...), modal(...), and custom component adapters can all be placed in the same children collection.

The fundamental primitive for composition is:

#![allow(unused)]
fn main() {
.children(...)
}

A component can accept one child or many children.

#![allow(unused)]
fn main() {
app()
    .children([text("Hello")])
    .run()
}

Or:

#![allow(unused)]
fn main() {
app()
    .children([
        text("Hello"),
        text("World"),
    ])
    .run()
}

This simple rule provides a consistent way to build interfaces from small pieces.

Everything can be a child. Everything can be composed.

One Child or Many

children() accepts either a single value or a collection of values.

A single child is useful when the relationship is straightforward:

#![allow(unused)]
fn main() {
button()
    .text("Save")
    .children([ButtonChild::icon("save"), ButtonChild::text("Save")])
}

Multiple children allow a component to become a container:

#![allow(unused)]
fn main() {
button()
    .children([
        ButtonChild::icon("folder"),
        ButtonChild::text("Open project"),
    ])
}

The API stays the same regardless of how many children a component contains.

There is no need to learn separate APIs for one child, two children, or a list of children.

Composition Over Special Cases

Beverly components are designed to be building blocks rather than complete screens.

A component can contain another component.

That component can contain more components.

Application
    ↓
Page
    ↓
Card
    ↓
Header
    ↓
Icon + Text + Button

The same composition model works at every level.

#![allow(unused)]
fn main() {
app()
    .children([
        text("Report").children([text("Quarterly financial report")]),
        button().text("Open"),
        input("Search").label("Search reports"),
        checkbox().label("Include archived").checked(true),
        card().children([text("Summary")]),
        list_item("Recent activity").subtitle("Just now"),
        form(Form::post("/save")).children([input("Name")]),
        table(TableConfig::default()),
    ])
    .run()
}

This makes components reusable without requiring the framework to predict every possible combination developers might need.

Build the primitive once. Compose it everywhere.

Named Sections

Card, Container (column() and row()), Form, Modal, Alert, Toast, Tabs, and Sidebar implement .header(...), .body(...), and .footer(...) as real composition sections. They map to top, middle, and bottom, regardless of builder-call order. Each accepts one UiElement or an iterable; repeated calls append to the selected section. In a sized panel, the body grows into the available height so the footer stays below it.

For Card, Container, Form, and Tabs, ordinary .children(...) content becomes part of the body when sections are used. Tabs apply sections within each tab zone; Sidebar keeps its navigation controls in the body. Modal retains its dialog title and close control. Alert and Toast retain their built-in message, icon, and dismissal behavior alongside custom content.

Navbar and the standalone Footer use horizontal left/center/right regions instead. Table headers describe columns, not a generic panel header. Buttons, fields, typography, and other leaf components do not have vertical sections; compose them inside a sectioned container instead.

Some components have a meaningful internal structure.

A Card, for example, may have:

• Header
• Body
• Footer

For these components, Beverly can provide named sections alongside general children() composition.

#![allow(unused)]
fn main() {
card().children([
    text("Account"),
    text("Account information"),
    button().text("Save"),
])
}

Named sections make the intent of the interface immediately obvious.

They also provide components with a way to express their own semantic structure without requiring developers to manually construct the underlying layout.

Sections Can Still Be Composed

Named sections follow the same content rules.

A section can receive a single value:

#![allow(unused)]
fn main() {
card()
    .header(
        text("Settings")
    )
}

Or multiple values:

#![allow(unused)]
fn main() {
card()
    .header([
        icon("settings"),
        text("Settings"),
        button().text("Edit"),
    ])
}

The section itself becomes a composition boundary.

Card
├── Header
│   ├── Icon
│   ├── Text
│   └── Button
│
├── Body
│   └── Content
│
└── Footer
    └── Actions

This allows a component to provide useful semantic structure without sacrificing the flexibility of general composition.

children() Is the Universal Escape Hatch

Named sections are useful when a component has a well-defined structure.

But developers should never be trapped by them.

children() remains the general composition primitive.

For a simple container:

#![allow(unused)]
fn main() {
container()
    .children([
        text("First"),
        text("Second"),
        text("Third"),
    ])
}

For a more structured component:

#![allow(unused)]
fn main() {
card()
    .header(text("Title"))
    .children([
        chart(data),
        table(rows),
    ])
    .footer(button().text("Close"))
}

The component can provide convenient named sections while still allowing arbitrary content where appropriate.

This keeps the API expressive without creating a separate abstraction for every possible layout.

Content Is Data

Beverly treats component content as values that can be passed, returned, stored, and composed.

That means a component does not need to know where its content came from.

Content might be:

• Static text
• Another component
• A list of components
• Data-driven content
• Conditional content
• Application state
• AI-generated content

The component simply receives content and presents it according to its role.

#![allow(unused)]
fn main() {
card()
    .header(text(user.name()))
    .children([
        text(user.email()),
        badge(user.status()),
    ])
}

The View decides what should be presented.

The component decides how that content is presented.

The Model remains responsible for the underlying application data.

Consistent Composition

The same mental model should work throughout a Beverly application.

#![allow(unused)]
fn main() {
container()
    .children([
        navbar(),
        card()
            .header(text("Users"))
            .children([
                user_table(),
            ])
            .footer([
                button().text("Previous"),
                button().text("Next"),
            ]),
    ])
}

Developers don’t need to memorize a different composition system for every component.

They learn one fundamental concept:

Component
    ↓
children()
    ↓
Child or Children

Named sections simply add semantic structure where it is useful.

Why This Matters for AI

A consistent composition model is particularly valuable when code is generated by LLMs.

The model does not need to invent a new layout abstraction for every component.

It learns a small vocabulary:

component()
children(...)
header(...)
body(...)
footer(...)

That makes generated code easier to predict and easier for humans to review.

A developer looking at:

#![allow(unused)]
fn main() {
card()
    .header(...)
    .children(...)
    .footer(...)
}

can immediately understand the structure.

The code itself becomes a description of the interface.

Composition should be obvious from the code.

The Beverly Composition Rule

Beverly keeps content composition deliberately simple:

Use children() for general composition.

Use named sections when a component has meaningful semantic regions.

Accept one child or many children.

Keep components composable.

Don’t create a new abstraction when ordinary composition already solves the problem.

The result is a UI system where small primitives can become complex interfaces without the API becoming complex.

Small primitives. Simple composition. Unlimited combinations.

Layout

Layout components control how content occupies space inside a Beverly view. They define alignment, direction, spacing, sizing, and adaptation so that a composition remains readable as its content and viewport change.

Layout is a presentation responsibility. It should make relationships visible and predictable without taking ownership of application state or business rules.

Layout model

Use the smallest primitive that expresses the relationship you need:

• alignment positions children within their available space
• flex direction determines whether content flows by row or column
• gap creates consistent space between siblings
• margin controls space outside a component’s own boundary
• padding controls space between a boundary and its content
• min and max constraints keep dimensions within useful limits
• width and height define the intended size of a region
• responsive rules let the composition adapt when available space changes

Layout
├── Boundary
│   ├── Width / Height
│   └── Min / Max
├── Flow
│   └── Flex direction
├── Rhythm
│   ├── Gap
│   ├── Margin
│   └── Padding
└── Placement
	└── Alignment

Composition guidance

Start with structure, then add spacing, then tune sizing. A stable layout usually needs only a few deliberate decisions: which direction content flows, how children align, how much space separates them, and what should happen when the available space is smaller or larger than expected.

Prefer shared layout rules over per-child offsets. This keeps a screen easier to scan and prevents one component from quietly compensating for another component’s incorrect sizing.

Example

#![allow(unused)]
fn main() {
use bevy::prelude::*;

fn build_panel(mut commands: Commands) {
	commands.spawn((
		Node {
			display: Display::Flex,
			flex_direction: FlexDirection::Column,
			align_items: AlignItems::Stretch,
			row_gap: Val::Px(12.0),
			padding: UiRect::all(Val::Px(16.0)),
			width: Val::Percent(100.0),
			..default()
		},
	));
}
}

The example establishes a vertical flow, a shared rhythm, an inset boundary, and a width that can participate in its parent’s layout. The content components inside the panel can then focus on their own meaning.

Alignment

Alignment determines how children are positioned inside the space made available by their parent. It is the layout decision that turns a group of elements into a readable relationship: centered actions, leading labels, or controls aligned to a common edge.

When to use

Use alignment to establish a shared visual edge or axis. Common patterns include:

• leading-aligning labels and body content
• centering a compact action or status group
• stretching fields to the width of a form
• aligning toolbar items along their cross axis

Alignment should describe the relationship of a group, not compensate for inconsistent child sizes.

Main and cross axes

Flex direction determines the main axis. In a row, children flow horizontally; in a column, they flow vertically. Alignment then controls placement along the main axis and the cross axis.

Column flow
main axis:  top -> bottom
cross axis: left <-> right

Row flow
main axis:  left -> right
cross axis: top <-> bottom

Choose alignment based on the content’s reading path. A form usually stretches fields across its cross axis, while a compact toolbar often centers controls vertically.

Example

#![allow(unused)]
fn main() {
Node {
	display: Display::Flex,
	flex_direction: FlexDirection::Column,
	align_items: AlignItems::Stretch,
	..default()
}
}

Guidance

• align related children to a shared edge
• use center alignment for compact groups, not long reading content
• let the parent establish alignment instead of adding offsets to each child
• verify alignment at narrow and wide viewport sizes

Flex

Flex layout distributes children along a direction and lets the available space determine how that group behaves. It is the foundation for rows, columns, toolbars, forms, and other compositions whose children have a meaningful order.

When to use

Use flex layout when content should flow as a group rather than occupy unrelated absolute positions. It works well for:

• navigation and action bars
• form sections
• split content regions
• reusable component shells
• layouts that need to grow with their children

Direction and growth

Set the direction first. A row creates a horizontal flow; a column creates a vertical flow. Then decide which children may grow, shrink, or keep their intrinsic size.

Flex container
├── Child A  -> fixed or intrinsic size
├── Child B  -> may grow into remaining space
└── Child C  -> fixed or intrinsic size

Keep growth intentional. A flexible content region can absorb remaining space, while labels and actions should usually retain enough room to stay recognizable.

Example

#![allow(unused)]
fn main() {
Node {
	display: Display::Flex,
	flex_direction: FlexDirection::Row,
	align_items: AlignItems::Center,
	column_gap: Val::Px(8.0),
	..default()
}
}

Guidance

• use flex for relationships that should survive content changes
• define direction before tuning spacing or alignment
• allow the content area to grow only when that behavior is useful
• avoid deeply nested flex containers when one parent rule is enough
• use a grid when both axes need repeated alignment

Gap

Gap creates consistent space between siblings in a flex or grid layout. It expresses rhythm at the parent level, which keeps related children evenly separated without requiring each child to know about its neighbors.

When to use

Use gap for repeated spacing between items that share a layout context:

• fields in a form
• actions in a toolbar
• cards in a grid
• sections in a vertical content flow

Use margin when the space belongs to one component’s relationship with something outside its own group. Use padding when the space belongs inside a component boundary.

Row and column gaps

For a horizontal flow, column gap separates neighboring items. For a vertical flow, row gap separates items from top to bottom. In a grid, both directions may need independent values.

Parent group
├── Child A
│   < gap >
├── Child B
│   < gap >
└── Child C

Example

#![allow(unused)]
fn main() {
Node {
	display: Display::Flex,
	flex_direction: FlexDirection::Column,
	row_gap: Val::Px(12.0),
	..default()
}
}

Guidance

• choose a shared spacing token or value for siblings at the same level
• use larger gaps to separate independent sections
• use smaller gaps for tightly related labels, values, or controls
• avoid mixing child margins and parent gaps unless the distinction is deliberate

Margin

Margin creates space outside a component’s own boundary. It describes how one layout item relates to surrounding content, making it useful for separating sections or creating a deliberate offset within a larger composition.

When to use

Use margin when the space belongs to the component’s relationship with its parent or neighboring regions:

• separating a heading from the section above it
• creating page-level or panel-level breathing room
• placing a component at a deliberate outer edge
• reserving space around a standalone surface

Use gap for consistent spacing between siblings in one group. Use padding for space inside the component’s boundary.

parent boundary
	< margin > [ component boundary ] < margin >

Example

#![allow(unused)]
fn main() {
Node {
		margin: UiRect {
				top: Val::Px(24.0),
				right: Val::Px(0.0),
				bottom: Val::Px(0.0),
				left: Val::Px(0.0),
		},
		..default()
}
}

Guidance

• use margin to define a component’s outer relationship
• prefer parent-level gap when all siblings share the same rhythm
• avoid using arbitrary margins to repair a broken alignment rule
• keep page-level margins consistent across related views

Min and Max

Minimum and maximum constraints keep a layout usable across changing content and viewport sizes. They prevent a region from collapsing below a readable size or expanding until its content becomes difficult to scan.

When to use

Use constraints when a component has a useful range rather than one fixed dimension:

• readable content columns
• sidebars and navigation regions
• cards that should not become excessively wide
• controls that need room for their labels
• panels that must remain usable on narrow screens

Constraint model

Think of the final size as a bounded range:

minimum size <= resolved size <= maximum size

The available space and the component’s content determine the resolved size inside that range. Constraints should protect readability, not replace responsive composition.

Example

#![allow(unused)]
fn main() {
Node {
	width: Val::Percent(100.0),
	min_width: Val::Px(240.0),
	max_width: Val::Px(720.0),
	..default()
}
}

Guidance

• set a minimum only when the content truly needs protected space
• use maximum widths to preserve readable line lengths
• test constraints with both short and long content
• avoid incompatible constraints that leave no useful resolved size
• combine min and max values with responsive flow rather than fixed offsets

Padding

Padding creates space inside a component’s boundary, between that boundary and its children. It gives content room to breathe and makes the extent of a surface clear without changing the relationships between sibling components.

When to use

Use padding for:

• card and panel insets
• control touch and interaction areas
• separating text from a surface edge
• creating a stable content region inside a container

Use gap to separate siblings. Use margin to separate the component from content outside its boundary.

[ component boundary ]
	< padding > content < padding >
[ component boundary ]

Example

#![allow(unused)]
fn main() {
Node {
		padding: UiRect::axes(
				Val::Px(20.0),
				Val::Px(16.0),
		),
		..default()
}
}

Guidance

• keep padding consistent across surfaces that share a visual role
• use larger insets for major panels and smaller insets for compact controls
• make sure padding does not reduce the usable space of dense content too far
• treat padding as part of the component’s boundary, not as a child-specific fix

Responsive Layout

Responsive layout adapts composition when the available space changes. It is not only about shrinking dimensions; it is about preserving hierarchy, readability, and usable interaction across viewport sizes.

When to use

Use responsive rules when a composition may appear in different windows, panels, or device sizes:

• dashboards that move from multi-column to single-column content
• toolbars whose actions need a narrower arrangement
• forms that change from side-by-side fields to a vertical flow
• panels whose width should remain readable instead of filling all space

Adapt the structure first

When space becomes constrained, change the relationship between components before reducing their legibility. A row may become a column, a grid may reduce its column count, or secondary content may move below the primary content.

Wide space:   [ navigation ] [ main content ] [ details ]
Narrow space: [ navigation ]
			  [ main content ]
			  [ details ]

Use width, height, and min/max constraints to provide stable bounds. Use flex direction, wrapping, and alignment to express how the composition should respond inside those bounds.

Example

#![allow(unused)]
fn main() {
Node {
	width: Val::Percent(100.0),
	max_width: Val::Px(960.0),
	flex_direction: FlexDirection::Column,
	..default()
}
}

The example keeps the region fluid while protecting its maximum reading width. The surrounding composition can decide when related regions should stack or change priority.

Guidance

• test layouts at the smallest and largest useful sizes
• preserve action visibility and readable text before visual symmetry
• use progressive disclosure for secondary content when space is limited
• avoid relying on one fixed viewport size as the design target
• keep responsive decisions at the parent layout boundary when possible

Width and Height

Width and height define the intended dimensions of a layout region. They can be fixed, relative to the parent, or left for the layout system and content to resolve automatically.

When to use

Use explicit dimensions when a region has a stable format or interaction requirement:

• icon and media surfaces with a known aspect
• navigation bars and tool regions
• full-width fields and panels
• modal or card bounds

Use relative values when a region should participate in its parent’s available space. Use intrinsic or automatic sizing when content should determine the dimension.

Dimension choices

Fixed       -> stable pixel or logical size
Percentage  -> proportional to the parent
Auto        -> resolved from content and layout rules
Min / Max   -> bounded flexible size

Prefer the least rigid choice that preserves usability. A fixed height can stabilize a toolbar, while a content region usually benefits from a flexible width with a readable maximum.

Example

#![allow(unused)]
fn main() {
Node {
	width: Val::Percent(100.0),
	height: Val::Auto,
	min_height: Val::Px(120.0),
	max_width: Val::Px(720.0),
	..default()
}
}

Guidance

• use stable dimensions for fixed-format controls and media
• let text-heavy regions grow when content can vary
• pair fluid width with max width to preserve readable line length
• avoid fixed heights around content that may wrap or localize
• check dimensions with empty, short, and long content

Typography

Typography gives Beverly interfaces a readable hierarchy. It defines how titles, body copy, labels, captions, and other text roles differ while keeping their font, scale, and color connected to the active theme.

The typography system has three responsibilities:

• establish hierarchy so users can tell what matters first
• keep text readable across cards, panels, forms, and app shells
• provide theme-driven defaults with deliberate per-instance overrides when needed

Typography
├── Titles
│   └── Mark the hierarchy of screens and sections
├── Text roles
│   └── Describe body, label, caption, and status content
├── Dots
│   └── Animate trailing periods to signal ongoing work
└── Theme
	└── Supplies shared family, size, and color defaults

Choosing a text primitive

Use a title when the text names or introduces a screen, panel, card, or section. Use a text role when the content explains, labels, annotates, or reports status within that structure.

Choose a semantic role before reaching for a manual size or color. Roles preserve a consistent hierarchy when the theme changes, while one-off overrides should be reserved for content that genuinely needs different emphasis.

Theme relationship

Titles and themed text read their defaults from the active theme. This keeps a font or scale change global and predictable: updating the theme can restyle an entire application without editing every component that contains text.

The View chooses the semantic primitive and content. The theme supplies the visual defaults. Application state and business rules remain outside the typography layer.

Example

#![allow(unused)]
fn main() {
use bevy::prelude::*;
use beverly::prelude::*;

fn build_header(mut commands: Commands) {
	commands.spawn((
		text("Workspace"),
		ThemedTitle::new(TitleLevel::H1),
	));
	commands.spawn((
		text("Last synced 2 minutes ago"),
		ThemedText::new(TextRole::Caption),
	));
}
}

Guidance

• use titles to establish hierarchy, not to style ordinary body copy
• choose the closest semantic text role before overriding size or color
• keep titles short enough to remain scannable at narrow widths
• let the active theme control shared typography defaults
• verify contrast and legibility whenever applying a manual color override

Text

Live Demo

Open the demo in a separate tab.

Use text("...") as the canonical way to create ordinary text in a Beverly application:

#![allow(unused)]
fn main() {
ui().children([text("Hello, Beverly!")])
}

The helper returns Bevy’s Text component. Beverly’s typography systems then apply the embedded default font and synchronize its size, color, shaping, and layout. Use ThemedText when the text needs a semantic role such as a heading, caption, or muted label. Add ordinary text to an application with ui().children([...]); the root Ui composition owns the application tree. Every composable Beverly element follows the same .children([...]) convention.

Text carries the supporting content around a title: explanations, labels, metadata, helper copy, and status details. It is the flexible, lower-emphasis counterpart to the title primitive and should inherit the active theme’s typography rules.

When to use

Use themed text when content belongs inside an existing hierarchy rather than naming the hierarchy itself. Common uses include:

• descriptions below a title
• labels attached to controls
• captions and timestamps
• helper and validation messages
• muted metadata or status details

Use ThemedTitle when the text introduces a meaningful screen, panel, card, or section.

Text roles

TextRole gives common content a semantic size and color:

• Heading - title-sized supporting heading
• Body - ordinary readable copy
• Label - compact text for controls and field labels
• Caption - small muted supporting information
• Muted - body-sized secondary copy
• Accent - compact text using the theme’s primary color
• Disabled - text for unavailable controls or content

The active theme resolves the exact size and color for each role. Prefer a role change over a manual override so the text remains coherent across themes.

Example

#![allow(unused)]
fn main() {
use bevy::prelude::*;
use beverly::prelude::*;

fn my_ui() -> Ui {
	ui().children([text("Last synced 2 minutes ago")])
}
}

Overrides

When a single piece of text genuinely needs a different treatment, use .size(...) or .color(...) on ThemedText. These overrides are local decisions and should not replace the shared role system:

#![allow(unused)]
fn main() {
app()
	.children([text("Sync failed")])
	.run();
}

Manual colors bypass the theme’s default contrast choices, so verify them in every theme where the text appears. Font family is controlled through the Typography component or the application’s global typography setup.

Guidance

• use the smallest role that preserves comfortable reading
• keep labels and metadata concise
• use muted roles for secondary information, not essential instructions
• let the surrounding layout control text spacing and alignment
• allow body text to wrap rather than clipping or forcing a fixed height

Title

Live Demo

Open the demo in a separate tab.

Titles identify the screen, panel, card, or section a user is viewing. They are the highest-emphasis content primitive in a local hierarchy and should make the purpose of a surface clear at a glance.

When to use

Use a title when text names a meaningful region or introduces the content that follows. Titles work well for:

• page and screen headings
• panel and card headers
• section labels in long forms or settings views
• modal headings that establish the task

Use ThemedText for supporting copy, metadata, labels, and status. A title should not be used only because text needs to be larger; its semantic role should justify the emphasis.

Title levels

TitleLevel provides a predictable hierarchy from the largest display treatment to the smallest heading:

• Display - prominent app or feature-level heading
• H1 - primary screen heading
• H2 - major panel or subsection heading
• H3 - standard section heading
• H4 - supporting section heading
• H5 - compact heading with muted emphasis
• H6 - smallest heading, used sparingly

The active theme resolves the actual size and color for each level. Higher levels use stronger foreground emphasis, while H4 through H6 are progressively quieter for nested structure.

Example

#![allow(unused)]
fn main() {
use bevy::prelude::*;
use beverly::prelude::*;

fn build_panel_header(mut commands: Commands) {
	commands.spawn((
		text("Project settings"),
		ThemedTitle::new(TitleLevel::H2),
	));
}
}

Changing size or color

Prefer changing TitleLevel when the title’s place in the hierarchy changes. When one title genuinely needs a one-off treatment, use .size(...) or .color(...) on ThemedTitle:

#![allow(unused)]
fn main() {
commands.spawn((
	text("Ready to publish"),
	ThemedTitle::new(TitleLevel::H3)
		.size(24.0)
		.color(Color::srgb(0.12, 0.45, 0.32)),
));
}

Manual overrides bypass the corresponding theme defaults. Check contrast and verify the result in every theme where the title appears.

Composition guidance

• keep one clear primary title for each major surface
• place the title before the content it introduces
• use supporting text for explanations instead of making titles paragraph-length
• preserve a consistent level relationship between neighboring sections
• allow long titles to wrap rather than forcing a fixed height that can clip text

Titles inherit the same typography pipeline as other text entities, so font family changes made through Typography or the global font manager can apply across the application without rewriting each title.

Dots

Live Demo

Open the demo in a separate tab.

Dots is an animated run of trailing periods that signals ongoing work. It cycles through no dots, ., .., and ..., then returns to no dots, repeating for as long as the entity exists.

When to use

Use Dots after a short status phrase when something is loading, thinking, or waiting and the result has no measurable progress:

• “Thinking” while a model prepares a response
• “Loading” while content is fetched
• “Waiting for connection” in a status line

Use a progress bar when the amount of work done is known. Use a spinner when the indicator should stand alone without text.

Example

#![allow(unused)]
fn main() {
use bevy::prelude::*;
use beverly::prelude::*;

fn build_status(mut commands: Commands) {
    commands
        .spawn(Node {
            flex_direction: FlexDirection::Row,
            ..default()
        })
        .with_children(|row| {
            row.spawn((text("Thinking"), ThemedText::new(TextRole::Muted)));
            row.spawn((Dots::new(), ThemedText::new(TextRole::Muted)));
        });
}
}

Dots owns the entity’s Text, so do not set the text yourself. Pair it with ThemedText for color and size so it matches the surrounding copy.

Options

• Dots::new() - three dots, 0.4 seconds per step
• .interval(seconds) - how long each step, including the empty one, is shown
• .max_dots(count) - the most dots shown before the cycle returns to none

Guidance

• place Dots in its own text entity beside the label so the label does not re-wrap or shift as the dots change
• remove the entity when the work finishes; Dots does not stop on its own
• keep the interval slow enough to read; around 0.3 to 0.5 seconds works well
• do not rely on the animation alone to convey status, as the label carries the meaning

Forms

Supported form controls bind to Bevy resource models through .bind(...). User edits call the generated or custom setter; successful values are read back so normalization reaches the control. Model-side changes synchronize to controls on the next UI update.

Binding Controls

Configure the concrete builder first, then call .bind(...). Binding returns a UiElement that can be composed in a Form, Container, or another section.

#![allow(unused)]
fn main() {
use beverly::prelude::*;
use beverly::components::input::TextInputConfig;

#[model]
struct User {
    email: String,
    active: bool,
    priority: u32,
}

let user = User {
    email: String::new(),
    active: false,
    priority: 1,
};
let fields = [
    TextInputConfig::new("Email").label("Email address").bind(User::email),
    CheckboxConfig::new().label("Active").bind(User::active),
    Select::new(vec![1u32, 2, 3]).bind(User::priority),
];
}

Insert the model as a Bevy resource. BeverlyPlugin installs BindingPlugin; a custom app must install it explicitly. Configure concrete controls before binding because .bind(...) consumes the builder and returns UiElement.

BindingValueType has built-in conversions for String, bool, numeric scalar values, and Vec<SelectedFile>. Custom value types can implement the trait. Typed Select<T> additionally requires Display for accessible option labels. The selected model value must match one of the Select’s options; an unmatched value becomes a BindingErrorState instead of silently selecting another option. Register SelectPlugin<T> for every concrete option type used.

For custom field accessors, create FieldBinding::new(getter, setter). The getter returns the model value; the setter accepts &mut Model and returns Result<(), BindingErrors>. A setter alone cannot support two-way binding because the binding also needs a getter.

Pending and Success

Use .submitting(|| ...) and .success(|| ...) to add state-specific content below a value control, Form, or submit control. Callbacks take no arguments and return one UiElement or an iterable. They do not inspect models, messages, or requests automatically.

#![allow(unused)]
fn main() {
let form = UiElement::form(Form::new())
    .submitting(|| [spinner(), text("Saving changes…")])
    .success(|| text("Saved"))
    .spawn_in_context(&mut context);

context.world.get_mut::<FormStatusState>(form).unwrap().submitting();
// After the app's operation completes:
context.world.get_mut::<FormStatusState>(form).unwrap().success();
context.world.get_mut::<FormStatusState>(form).unwrap().idle();
}

The app owns the lifecycle. Callback content replaces on status changes and is removed on Idle; it has polite live-region semantics. Controls are not automatically disabled while submitting. Configure that policy separately. See Form for sections and complete composition.

Error Callbacks

Value controls, typed Select<T>, Form, and submit controls expose .error(|errors| ...). The callback receives the current &[String] and returns composable content. For bound fields, setter/conversion failures update BindingErrorState automatically. Form-level and unbound-control errors are app-owned and must be set on that entity.

#![allow(unused)]
fn main() {
let form = Form::new()
    .error(|errors| text(errors.join("\n")))
    .spawn_in_context(&mut context);

context.world.get_mut::<BindingErrorState>(form).unwrap()
    .error(BindingErrors::new("Unable to save. Please retry."));
}

Changed nonempty errors replace the presentation; recovery removes it. Field errors are not automatically aggregated into Form-level errors. Invalid state, error announcements, and relationships are projected into accessibility semantics; verify delivery with the platforms and screen readers you support.

Submission

A generated Form submit control gathers named descendant values and emits FormSubmitted. The app decides how to perform a request and handle its result. It does not send network traffic automatically. See Submit for GET, POST, PUT, PATCH, body encodings, and the optional blocking transport feature.

Form

Form composes value-bearing controls, optional section content, and a generated submit button. It does not own model state or perform HTTP requests. Bind each control to the model and handle the emitted FormSubmitted message in the app. See Submit for GET, POST, PUT, and PATCH requests.

Sections

UiElement::form(...) supports .header(...), .body(...), and .footer(...) regions. Each accepts one element or an iterable; repeated calls append. The regions render in header, body, footer order regardless of builder-call order. Ordinary .children(...) content joins the body. The body expands to use the available form height, and the generated submit button is placed in the footer.

#![allow(unused)]
fn main() {
UiElement::form(Form::post("/api/users"))
    .header(text("Create account"))
    .body([
        UiElement::input("Name")
            .name("name")
            .bind(User::name),
        UiElement::input("Email")
            .name("email")
            .bind(User::email),
    ])
    .footer(text("Your information is used to create the account."))
}

The generated submit button is enabled by default. To provide a custom button, set Form::show_submit_button(false) and place a button carrying the FormSubmitButton marker from beverly::components::form in the Form subtree.

Binding and Validation

Bind each value-bearing control using its generated field handle. Configure the control before calling .bind(...); the bound value then syncs in both directions between the model and control. Setter normalization is reflected back into the control, while rejected edits remain visible for correction and expose BindingErrorState on the field. Supported builders and conversions are listed in Binding Controls.

#![allow(unused)]
fn main() {
UiElement::input("Email")
    .label("Email address")
    .aria("Enter the email address associated with your account.")
    .bind(User::email)
    .error(|errors| text(errors.join("\n")))
}

Field errors are not automatically aggregated into the Form’s global error state. Use a field’s .error(...) callback for setter errors and set BindingErrorState on the Form entity for app-owned submission failures. See Error Callbacks.

Pending and Success

The application owns the request lifecycle and updates FormStatusState on the spawned Form. Callbacks add supplementary content; they do not inspect messages, perform requests, restyle the Form, or disable controls automatically.

#![allow(unused)]
fn main() {
let form = UiElement::form(Form::post("/api/users"))
    .submitting(|| [spinner(), text("Creating account…")])
    .success(|| text("Account created"))
    .spawn_in_context(&mut context);

context.world.get_mut::<FormStatusState>(form).unwrap().submitting();
// After the app's operation completes:
context.world.get_mut::<FormStatusState>(form).unwrap().success();
}

Call .idle() when state-specific content should be removed. Use Form::disabled(true) separately if the entire form should reject interaction while the request is pending. The callback content is exposed as a polite live region; validate announcement timing with supported screen readers.

Styling

Forms use the shared Styling DSL:

#![allow(unused)]
fn main() {
UiElement::form(Form::new())
    .padding(24)
    .gap(16)
    .width(480)
    .background("#ffffff")
    .border_width(1)
    .border_color("#d4d4d4")
}

Explicit style properties are reapplied after component/theme visual updates. State-specific paint uses .submitting_style(...) and .success_style(...); state content uses .submitting(...) and .success(...).

Accessibility

Provide a visible or programmatic label for each value-bearing control. Use .aria(...) when additional descriptive context is needed:

#![allow(unused)]
fn main() {
UiElement::input("Email")
    .label("Email address")
    .aria("Enter the address associated with your account.")
    .bind(User::email)
}

Beverly projects labels, invalid state, descriptions, and live regions into accessible semantics at runtime. Check interaction and announcements with the screen readers and platforms your application supports.

Reset

Reset behavior is application-owned. Update or replace the model resource with the desired values; bound controls reflect those model changes on the next UI update. The Form does not provide an implicit reset event.

Submit

Bind value-bearing controls to the model; submission is a separate action. BeverlyPlugin includes FormPlugin, which watches the generated submit button and emits FormSubmitted with the owning form entity and a FormRequest. The app owns network transport and response handling.

Methods and Encodings

Use the constructor matching the requested HTTP verb:

GET fields are URL-encoded and appended to existing query parameters before any fragment. POST, PUT, and PATCH use FormEncoding::UrlEncoded by default; .encoding(FormEncoding::Json) sends a JSON object instead. A field name can occur more than once in URL-encoded data.

#![allow(unused)]
fn main() {
let create = Form::post("https://example.test/items")
    .encoding(FormEncoding::Json)
    .field("title", "Release notes")
    .build_request();

let update = Form::put("https://example.test/items/42")
    .field("title", "Revised release notes")
    .build_request();

let partial_update = Form::patch("https://example.test/items/42")
    .field("published", "true")
    .build_request();
}

Form::field(...) and Form::fields(...) add fixed string values. Named supported descendant controls add their current values. Disabled controls and unchecked checkbox/toggle controls are omitted. The string-valued request API does not upload files.

Handling Submission

The generated submit control gathers values and emits a message; it does not perform a request:

#![allow(unused)]
fn main() {
use bevy::prelude::*;
use beverly::prelude::*;

fn search_form() -> UiElement {
    UiElement::form(Form::get("https://example.test/search"))
        .children([
            UiElement::input("Search terms")
                .label("Search terms")
                .name("q"),
        ])
}

fn handle_form_submit(mut submitted: MessageReader<FormSubmitted>) {
    for message in submitted.read() {
        let request = &message.request;
        info!(form = ?message.form, method = ?request.method, url = %request.request_url());
    }
}
}

For POST/PUT/PATCH, request_url() returns the action URL; values remain in request.fields for the selected body encoding. The default Bevy update path never performs blocking network I/O. With the optional http_form Cargo feature, FormRequest::send() and Form::submit() are blocking reqwest conveniences; call them from an app-owned worker/task, not from a Bevy system.

A custom submit button must carry the FormSubmitButton marker from beverly::components::form; the default generated button already has it. Nested forms are not included in an outer form’s field collection.

Pending and Errors

The application controls request state. Add .submitting(|| ...) and .success(|| ...) callbacks to the form or submit control, then set FormStatusState after beginning and completing the operation. These callbacks only render supplementary content; they do not observe requests or disable controls automatically. Use .disabled(true) when that is the intended policy.

Global request failures are also app-owned. Set BindingErrorState on the Form entity to render its .error(...) callback. Field errors are not aggregated into the Form automatically. See Form State and Error Callbacks.

Text Input

Live Demo

Open the demo in a separate tab.

Model binding: TextInputConfig::new("Email").label("Email").bind(User::email) connects the input to a generated model field handle. Configure first, then bind; the result is a UiElement. See Binding Controls.

The text input is the most common form element in Beverly.

It looks simple:

#![allow(unused)]
fn main() {
input()
}

But a production input has several responsibilities:

• Present a value
• Identify itself with a label
• Provide accessible semantics
• Bind to application state
• Convert user input into the Model’s type
• Invoke the appropriate setter
• Receive validation results
• Present field-level errors
• Reflect changes made by the Model
• Represent editing state such as touched, dirty, focused, and pending

Beverly keeps these responsibilities together without requiring the developer to manually wire them up.

Labels and Accessible Descriptions

Every input needs a persistent accessible name. An additional ARIA description is useful when the label alone does not explain the expected value or context.

#![allow(unused)]
fn main() {
input()
    .label(localize("user.email.label"))
    .aria(localize("user.email.description"))
}

The accessible name is essential; the description is optional context.

The label identifies the field.

The ARIA declaration provides additional accessible semantics or descriptive information.

If no explicit accessible label or floating label is present, Beverly warns at spawn time rather than treating the placeholder as the accessible name.

Accessible by construction, not accessible by cleanup.

In the concrete Rust API, TextInputConfig::label(...) sets the persistent accessible name, while floating_label(...) supplies the visible floating label. A placeholder is only a hint and is never used as the accessible name. If neither an explicit accessible label nor a floating label is provided, Beverly warns at spawn time rather than presenting the placeholder as a name:

#![allow(unused)]
fn main() {
use beverly::components::input::TextInputConfig;

let config = TextInputConfig::new("[email protected]")
    .label("Email address")
    .floating_label("Email");
}

This is particularly important for AI-generated interfaces. An agent should not have to remember accessibility requirements as a separate cleanup step. The component API makes the required structure explicit.

The Basic Input

A useful input normally has three fundamental pieces:

#![allow(unused)]
fn main() {
input()
    .label(localize("user.email.label"))
    .aria(localize("user.email.description"))
    .bind(User::email)
}

The label identifies the field.

The ARIA declaration provides accessible context.

The binding connects the field to application state.

Everything else builds on these three pieces.

Binding

.bind() connects the input to a Model field.

#![allow(unused)]
fn main() {
input()
    .label(localize("user.email.label"))
    .aria(localize("user.email.description"))
    .bind(User::email)
}

The binding handles the translation between interface input and typed application state.

Conceptually:

Model → Binding → Input
Input → Binding → Setter → Model

The Model remains the source of truth.

The developer does not need to manually write a change handler, synchronize state, or copy the input value into another form-specific state object.

The binding handles that connection.

The Setter Is Called on Every Change

A bound input invokes the Model setter every time the input changes.

For example, if a user types:

v
vi
vic
vict
victor

the corresponding setter is invoked for each change.

Input Change
     ↓
  Binding
     ↓
Model Setter
     ↓
Result

This is intentional.

The Model sees the stream of values and decides what to do with them.

For a simple field, that might mean validating immediately.

For another field, it might mean normalizing the value.

For an asynchronous field, it might mean starting or scheduling a request.

The Form does not need to know which behavior is appropriate.

The input reports every change. The Model decides what every change means.

The Model Can Change the Input

Binding is not simply a one-way mechanism for sending text into the Model.

The Model can transform the value and send the canonical value back to the input.

Phone numbers are a good example.

A user might enter:

4155551234

The Model may normalize that value to:

(415) 555-1234

For example:

#![allow(unused)]
fn main() {
impl User {
    fn set_phone(
        &mut self,
        phone: String,
    ) -> Result<(), UserError> {
        let phone = format_phone_number(phone)?;

        self.phone = phone;

        Ok(())
    }
}
}

The resulting flow is:

User Input
    ↓
Binding
    ↓
Model Setter
    ↓
Normalize / Validate
    ↓
Model State
    ↓
Binding
    ↓
Formatted Input

The input does not need to know how phone numbers are formatted.

The Model owns the canonical representation.

This applies to:

• Phone numbers
• Currency
• Dates
• Identifiers
• Capitalization
• Whitespace
• Units
• Domain-specific formats

The user edits the value.

The Model decides what the application’s value actually becomes.

The input collects the value. The Model defines the value.

The Setter Owns Validation

Validation belongs to the Model.

For example:

#![allow(unused)]
fn main() {
impl User {
    fn set_email(
        &mut self,
        email: String,
    ) -> Result<(), UserError> {
        let email = email.trim().to_lowercase();

        if !is_valid_email(&email) {
            return Err(UserError::InvalidEmail);
        }

        self.email = email;

        Ok(())
    }
}
}

The input does not know what makes an email valid.

The Form does not know either.

The Model knows.

That means the same validation rule applies whether the value comes from:

• A human using the Form
• An AI agent
• An API
• Another component
• Another internal application action

There is one validation rule and one place to maintain it.

From Setter Error to Field Error

Suppose the user enters an invalid email.

The binding passes the value to the Model:

Input
  ↓
Binding
  ↓
User::set_email(...)
  ↓
Err(UserError::InvalidEmail)

The setter rejects the state transition.

The Model does not change.

The binding receives the error and associates it with the field that produced it.

Field-level errors are therefore derived from the form binding.

Setter Result
     ↓
  Binding
     ↓
 Field Errors
     ↓
.error(...)

The UI does not independently validate the email.

It does not need to duplicate the Model’s rules.

The setter returned an error.

The binding knows which field invoked the setter.

The field therefore receives the error.

Errors Are Exposed to the Error Context

When .error(...) is configured, the current field errors are automatically exposed to the content inside the error hook.

The callback receives the field’s current errors as &[String] and returns the content to display below the input. Both TextInputConfig::error(...) and UiElement::error(...) use this contract; see Error Callbacks for concrete examples.

The error context is an array of strings:

#![allow(unused)]
fn main() {
input()
    .label(localize("user.email.label"))
    .aria(localize("user.email.description"))
    .bind(User::email)
    .error(|errors| text(errors.join("\n")))
}

The important part is that the strings come from the Model’s error response.

The form element does not invent them.

The Model produces the errors.

The binding associates those errors with the field.

The .error(...) content presents them.

A field can therefore expose multiple errors when the Model returns multiple validation messages:

errors = [
    "Email address is invalid.",
    "Email domain is not allowed."
]

The error presentation can decide how those messages should be displayed.

For example:

#![allow(unused)]
fn main() {
.error(|errors| text(errors.join("\n")))
}

The exact presentation is the View’s responsibility.

The contents of the error are the Model’s responsibility.

The Model produces the errors. The binding exposes them. The field presents them.

Internationalization

Validation text should not be hard-coded into the form element.

Avoid:

#![allow(unused)]
fn main() {
.error(|errors| text(errors.join("\n")))
}

The Model should return the semantic validation error, and the resulting error context should provide the appropriate localized message.

Conceptually:

Model
  ↓
Validation Error
  ↓
Localized Error Message
  ↓
Binding
  ↓
Field Error Context
  ↓
.error(...)

This means the reusable input does not contain English validation messages—or validation messages in any particular language.

Labels and ARIA descriptions should likewise come from the application’s localization system:

#![allow(unused)]
fn main() {
input()
    .label(localize("user.email.label"))
    .aria(localize("user.email.description"))
    .bind(User::email)
}

The component describes the structure of the interface.

The localization system provides the language.

The Model provides the meaning of validation failures.

The Model returns meaning. The UI presents language.

Asynchronous Validation

Some setters need to perform asynchronous work.

For example, an email address might need to be checked against a server to determine whether it is already registered.

The setter can represent that transition asynchronously:

#![allow(unused)]
fn main() {
impl User {
    async fn set_email(
        &mut self,
        email: String,
    ) -> Result<(), UserError> {
        let email = email.trim().to_lowercase();

        if !is_valid_email(&email) {
            return Err(UserError::InvalidEmail);
        }

        if email_exists(&email).await? {
            return Err(UserError::EmailAlreadyRegistered);
        }

        self.email = email;

        Ok(())
    }
}
}

The input does not need a special asynchronous validation framework.

It still calls the setter on every change.

The Model determines that this particular transition requires asynchronous work.

Pending State

While the Model is performing asynchronous work, the field can expose its pending state.

For example:

#![allow(unused)]
fn main() {
input()
    .label(localize("user.email.label"))
    .aria(localize("user.email.description"))
    .bind(User::email)
    .submitting(|| [spinner()])
}

Or the pending presentation can contain additional content:

#![allow(unused)]
fn main() {
input()
    .label(localize("user.email.label"))
    .aria(localize("user.email.description"))
    .bind(User::email)
    .submitting(|| [
            spinner(),
            text(localize("user.email.checking"))
        ])
}

The same principle applies:

The application sets FormStatusState::submitting() before async work and sets success() or idle() when it completes. The hook adds supplementary content below the input; it does not observe the Model or restyle the input.

Debouncing Belongs in the Model

Because the setter is called on every input change, applications that perform expensive or remote work should debounce that work in the Model layer.

For example, typing:

v
vi
vic
vict
victor

should not necessarily produce five network requests.

The Model can debounce the request:

#![allow(unused)]
fn main() {
impl User {
    async fn set_username(
        &mut self,
        username: String,
    ) -> Result<(), UserError> {
        self.username = username.clone();

        debounce(Duration::from_millis(300)).await;

        if username_exists(&username).await? {
            return Err(UserError::UsernameTaken);
        }

        Ok(())
    }
}
}

The important architectural point is that the Form still reports every change.

The Model decides that remote validation should wait until the user pauses.

Every Input Change
        ↓
      Setter
        ↓
      Model
        ↓
    Debounce
        ↓
 Async Validation
        ↓
    Model Result
        ↓
      Binding
        ↓
       Input

This keeps debounce behavior out of the UI.

If an agent, API, or another application component invokes the same state transition, the same Model behavior applies.

Avoiding Stale Requests

For remote validation, a production implementation should also prevent an older request from overwriting a newer result.

Conceptually:

#![allow(unused)]
fn main() {
impl User {
    async fn set_username(
        &mut self,
        username: String,
    ) -> Result<(), UserError> {
        self.username = username.clone();

        let request_id = self.next_validation_request();

        sleep(Duration::from_millis(300)).await;

        let available = username_available(&username).await?;

        if request_id != self.current_validation_request() {
            return Ok(());
        }

        if !available {
            return Err(UserError::UsernameTaken);
        }

        Ok(())
    }
}
}

The exact implementation can be hidden behind Beverly’s runtime primitives.

The important rule is that the Model owns the lifecycle of the asynchronous validation.

The Form should not have to implement debounce timers, request cancellation, or stale-response handling.

Validation Timing

The Model also controls when a field should be considered invalid.

For example, an application may not want to display an error before a user has interacted with a field.

If validation behavior depends on whether the field has been touched, that state must participate in the Model’s state and logic.

Conceptually:

#![allow(unused)]
fn main() {
if touched {
    validate(value)
} else {
    Ok(())
}
}

The exact implementation can vary, but the architectural principle is important:

If validation behavior depends on state, that state belongs to the Model.

The Form can present the resulting state, but it should not secretly redefine the application’s validation rules.

Successful Updates

When the setter returns:

#![allow(unused)]
fn main() {
Ok(())
}

the Model has accepted the state transition.

The binding reflects the accepted value back into the input.

If the Model transformed the value, the transformed value is what the input displays.

For example:

User types:       4155551234
                       ↓
                  set_phone()
                       ↓
Model stores:    (415) 555-1234
                       ↓
Input displays:  (415) 555-1234

The Model is always the authoritative state.

Error Updates

When the setter returns an error:

#![allow(unused)]
fn main() {
Err(...)
}

the Model rejects the transition.

The previous valid Model value remains authoritative.

The binding exposes the resulting errors to the field.

The field’s .error(...) presentation becomes active.

Input
  ↓
Setter
  ↓
Err
  ↓
Field Error Context
  ↓
.error(...)

The UI does not have to manually set an error flag.

The error is a consequence of the failed Model transition.

Styling the Input

Inputs use the same fluent API as every other Beverly component.

#![allow(unused)]
fn main() {
input()
    .label(localize("user.email.label"))
    .aria(localize("user.email.description"))
    .bind(User::email)
    .padding(12)
    .radius(8)
    .width(320)
}

State-specific presentation uses the same API:

#![allow(unused)]
fn main() {
input()
    .label(localize("user.email.label"))
    .aria(localize("user.email.description"))
    .bind(User::email)
    .error(|errors| text(errors.join("\n")))
}

Or:

#![allow(unused)]
fn main() {
input()
    .label(localize("user.email.label"))
    .aria(localize("user.email.description"))
    .bind(User::email)
    .error(|errors| text(errors.join("\n")))
}

The component API does not change because the input is in an error state.

The Complete Input

A production input might therefore look like:

#![allow(unused)]
fn main() {
input()
    .label(localize("user.email.label"))
    .aria(localize("user.email.description"))
    .bind(User::email)
    .padding(12)
    .radius(8)
    .width(320)
    .error(|errors| text(errors.join("\n")))
    .submitting(|| [spinner()])
}

The input has:

• A required label
• A required ARIA declaration
• A Model binding
• Typed application state
• Model-owned validation
• Model-owned normalization
• Automatic synchronization
• Setter error propagation
• An automatically exposed error context
• Localized error presentation
• Async/pending state
• Fluent styling

And there is no manual on_change handler.

The Text Input Contract

The text input can be understood as a contract between the Form and the Model:

              TEXT INPUT

 Label ──────────────── Identity
 ARIA ───────────────── Accessibility
 Bind ───────────────── State connection
 Input ──────────────── User intent
 Setter ─────────────── Validation + transformation
 Result ─────────────── Accepted value or errors
 Model ──────────────── Source of truth

The input reports every change.

The binding connects that change to the Model.

The setter validates and transforms it.

The Model can synchronously or asynchronously change application state.

The binding reflects the resulting state back into the input.

Errors come from the Model and are exposed through the binding.

The field presents those errors.

The input collects. The binding connects. The setter validates and transforms. The Model owns the state. The field presents the result.

Textarea

Live Demo

Open the demo in a separate tab.

Model binding: TextareaConfig::new("Notes").label("Notes").bind(User::notes) connects a text field to the textarea and returns a composable UiElement. Validation messages live in BindingErrorState; .error(|errors| ...) renders their visible presentation. See Error Callbacks.

textarea() is the multiline counterpart to input().

Disabled and Read-Only State

#![allow(unused)]
fn main() {
TextareaConfig::new("Notes")
    .label("Notes")
    .required(true)
    .read_only(true)
}

.disabled(true) removes the initial tab stop and rejects focus and editing. .read_only(true) keeps content available for focus, selection, and copying while rejecting insertion/deletion/cut/paste mutations. Both states and required are projected to AccessKit. Bound validation automatically exposes invalid state and related error text; visible error styling remains app-owned.

It follows the same patterns:

• A label is required.
• An ARIA declaration is required.
• .bind() connects it to Model state.
• The Model setter is called every time the value changes.
• The Model validates and transforms the value.
• Setter errors become field-level errors through the binding.
• Errors are exposed to the .error(...) context as an array of strings.
• The Model can perform asynchronous validation.
• Pending state is represented by the component.
• Debouncing belongs in the Model.
• The Model remains the source of truth.

The only fundamental difference is that textarea() is designed for multiline content.

In the concrete Rust API, set the accessible name with TextareaConfig::label(...). The placeholder is supplementary guidance, not a substitute for a label. When no accessible label is supplied, Beverly warns at spawn time instead of treating placeholder text as the name.

#![allow(unused)]
fn main() {
use beverly::components::textarea::TextareaConfig;

let config = TextareaConfig::new("A short biography")
    .label("Biography");
}

The Basic Textarea

A basic textarea:

#![allow(unused)]
fn main() {
textarea()
    .label(localize("profile.bio.label"))
    .aria(localize("profile.bio.description"))
}

A bound textarea:

#![allow(unused)]
fn main() {
textarea()
    .label(localize("profile.bio.label"))
    .aria(localize("profile.bio.description"))
    .bind(User::bio)
}

The API should feel immediately familiar to anyone who has used an HTML textarea, while the underlying behavior follows Beverly’s Model and binding architecture.

Binding

.bind() connects the textarea to a Model property:

#![allow(unused)]
fn main() {
textarea()
    .label(localize("profile.bio.label"))
    .aria(localize("profile.bio.description"))
    .bind(User::bio)
}

The textarea reads its initial value from the Model.

When the user types, the setter is invoked.

When the Model changes, the textarea changes.

Model → Binding → Textarea
Textarea → Binding → Setter → Model

There is no second authoritative copy of the text inside the textarea.

The Setter Is Called on Every Change

Just like input(), the Model setter is called whenever the textarea value changes.

If a user types:

H
He
Hel
Hell
Hello

the setter receives those changes.

Textarea Change
       ↓
     Binding
       ↓
   Model Setter
       ↓
     Result

The Model can then decide what to do with each change.

It can:

• Accept the value
• Reject the value
• Normalize the value
• Transform the value
• Track editing state
• Perform asynchronous validation
• Debounce expensive work

The textarea does not need to know which behavior is being used.

The Model Can Transform the Text

The Model can modify the value and send the resulting value back through the binding.

For example, suppose a description should never contain leading or trailing whitespace:

#![allow(unused)]
fn main() {
impl User {
    fn set_bio(
        &mut self,
        bio: String,
    ) -> Result<(), UserError> {
        let bio = bio.trim().to_string();

        self.bio = bio;

        Ok(())
    }
}
}

Or the Model might normalize repeated whitespace, enforce a domain-specific format, or transform the content before storing it.

The resulting flow is:

User Text
   ↓
Setter
   ↓
Normalize
   ↓
Model State
   ↓
Binding
   ↓
Textarea

The Model determines the canonical value.

Validation

Textarea validation works exactly like input validation.

Suppose a biography must contain at least 20 characters:

#![allow(unused)]
fn main() {
impl User {
    fn set_bio(
        &mut self,
        bio: String,
    ) -> Result<(), UserError> {
        let bio = bio.trim().to_string();

        if bio.chars().count() < 20 {
            return Err(UserError::BioTooShort);
        }

        self.bio = bio;

        Ok(())
    }
}
}

The textarea does not implement this rule.

The Model does.

This means the same rule applies regardless of whether the value comes from a human, an agent, an API, or another application component.

Field Errors

If the setter returns an error, the binding associates that error with the textarea.

#![allow(unused)]
fn main() {
textarea()
    .label(localize("profile.bio.label"))
    .aria(localize("profile.bio.description"))
    .bind(User::bio)
    .error(|errors| text(errors.join("\n")))
}

The error context is automatically exposed to the .error(...) content.

The errors are an array of strings.

The strings originate from the Model’s validation response.

Model Setter
     ↓
   Errors
[String, String, ...]
     ↓
  Binding
     ↓
Textarea Error Context
     ↓
.error(...)

The textarea does not generate the validation message.

The Model does.

Internationalization

Validation messages should never be hard-coded into the textarea.

Instead of:

#![allow(unused)]
fn main() {
text("Biography is too short.")
}

the Model returns the appropriate structured error, and the error exposed by the binding contains the localized message.

#![allow(unused)]
fn main() {
textarea()
    .label(localize("profile.bio.label"))
    .aria(localize("profile.bio.description"))
    .bind(User::bio)
    .error(|errors| text(errors.join("\n")))
}

The textarea contains no language-specific validation copy.

The label and ARIA description come from the application’s localization system.

The error comes from the Model.

The Model returns meaning. The UI presents language.

Multiple Errors

A Model may return more than one error for a field.

For example:

[
    "Biography is too short.",
    "Biography contains prohibited content."
]

The error context exposes the errors together.

The View decides how to present them.

For example:

#![allow(unused)]
fn main() {
textarea()
    .label(localize("profile.bio.label"))
    .aria(localize("profile.bio.description"))
    .bind(User::bio)
    .error(|errors| text(errors.join("\n")))
}

The Model determines the errors.

The component determines their presentation.

Asynchronous Validation

Textarea values can also require asynchronous validation.

For example, a content field might need to be checked by a remote service.

The Model owns that behavior:

#![allow(unused)]
fn main() {
impl User {
    async fn set_bio(
        &mut self,
        bio: String,
    ) -> Result<(), UserError> {
        let bio = bio.trim().to_string();

        if bio.chars().count() < 20 {
            return Err(UserError::BioTooShort);
        }

        if !content_allowed(&bio).await? {
            return Err(UserError::ContentNotAllowed);
        }

        self.bio = bio;

        Ok(())
    }
}
}

The textarea does not need an async validation API.

The setter is still the state transition.

The difference is that the Model performs asynchronous work before accepting that transition.

Pending State

While asynchronous validation is occurring, the textarea can expose a pending presentation:

#![allow(unused)]
fn main() {
textarea()
    .label(localize("profile.bio.label"))
    .aria(localize("profile.bio.description"))
    .bind(User::bio)
    .submitting(|| [spinner()])
}

Or:

#![allow(unused)]
fn main() {
textarea()
    .label(localize("profile.bio.label"))
    .aria(localize("profile.bio.description"))
    .bind(User::bio)
    .submitting(|| [
            spinner(),
            text(localize("profile.bio.checking"))
        ])
}

Again, self refers to the textarea itself.

The async Event or setter does not directly manipulate the textarea.

The application sets FormStatusState::submitting() while that work is pending.

The textarea observes that state and presents itself accordingly.

The callback supplies supplementary content below the textarea; set idle() or success() to replace or remove it.

Debouncing

The setter is called for every textarea change.

That means debouncing expensive work belongs in the Model.

Suppose content validation requires a remote request. A user typing a paragraph should not trigger a network request for every character.

The Model can debounce the work:

#![allow(unused)]
fn main() {
impl User {
    async fn set_bio(
        &mut self,
        bio: String,
    ) -> Result<(), UserError> {
        self.bio = bio.clone();

        debounce(Duration::from_millis(300)).await;

        validate_content(&bio).await?;

        Ok(())
    }
}
}

The textarea continues to report every change.

The Model decides when the expensive operation should actually happen.

Every Change
     ↓
  Setter
     ↓
   Model
     ↓
 Debounce
     ↓
Async Validation
     ↓
   Result
     ↓
 Binding
     ↓
 Textarea

This keeps timing and network behavior out of the View.

The same behavior therefore applies if the Model transition is initiated by another application client.

Touched State

The Model can also control when validation should occur.

For example, an application may not want to show a biography error until the user has interacted with the field.

If the validation rules depend on touched, that state participates in the Model’s logic.

#![allow(unused)]
fn main() {
if touched {
    validate_bio(&bio)
} else {
    Ok(())
}
}

The important principle is:

If validation behavior depends on state, that state belongs to the Model.

The textarea presents the result.

It does not invent the rule.

Styling

Textarea uses the same fluent component API:

#![allow(unused)]
fn main() {
textarea()
    .label(localize("profile.bio.label"))
    .aria(localize("profile.bio.description"))
    .bind(User::bio)
    .padding(12)
    .radius(8)
    .width(400)
    .height(160)
}

Error presentation follows the same pattern:

#![allow(unused)]
fn main() {
textarea()
    .label(localize("profile.bio.label"))
    .aria(localize("profile.bio.description"))
    .bind(User::bio)
    .error(|errors| text(errors.join("\n")))
}

Pending presentation:

#![allow(unused)]
fn main() {
textarea()
    .label(localize("profile.bio.label"))
    .aria(localize("profile.bio.description"))
    .bind(User::bio)
    .submitting(|| [spinner()])
}

The same component API handles normal, error, and pending states.

The Complete Textarea

A production textarea can combine all of these capabilities:

#![allow(unused)]
fn main() {
textarea()
    .label(localize("profile.bio.label"))
    .aria(localize("profile.bio.description"))
    .bind(User::bio)
    .padding(12)
    .radius(8)
    .width(400)
    .height(160)
    .error(|errors| text(errors.join("\n")))
    .submitting(|| [spinner()])
}

There is no manual change handler.

There is no second source of truth.

There is no UI-specific validation implementation.

There is no hard-coded validation language.

The input reports changes.

The binding connects those changes to the Model.

The setter validates and transforms the value.

The Model can perform asynchronous work.

The binding exposes the resulting errors.

The textarea presents the resulting state.

Textarea is not a special form system. It is the same Beverly binding contract applied to multiline text.

Checkbox

Live Demo

Open the demo in a separate tab.

Model binding: CheckboxConfig::new().label("Active").bind(User::active) connects a boolean model field to the checkbox. Configure first, then bind; the result is a composable UiElement. See Binding Controls.

checkbox() is the standard Beverly form element for boolean values.

Like every Beverly form element, a checkbox requires:

• A label
• An ARIA declaration
• A Model binding

#![allow(unused)]
fn main() {
checkbox()
    .label(localize("user.active.label"))
    .aria(localize("user.active.description"))
    .bind(User::active)
}

The checkbox does not own the boolean value.

The Model does.

Binding

A checkbox binds directly to a boolean Model property:

#![allow(unused)]
fn main() {
checkbox()
    .label(localize("user.active.label"))
    .aria(localize("user.active.description"))
    .bind(User::active)
}

The binding works in both directions:

Model → Binding → Checkbox
Checkbox → Binding → Setter → Model

If the Model contains:

#![allow(unused)]
fn main() {
active: true
}

the checkbox is checked.

If the user unchecks it, the binding sends false to the Model.

If another part of the application changes active, the checkbox reflects the new Model state.

The Setter Is Called on Every Change

Just like input() and textarea(), the setter is invoked whenever the checkbox changes.

Checked
   ↓
true
   ↓
Setter

Unchecked
   ↓
false
   ↓
Setter

For a simple boolean, the setter may be straightforward:

#![allow(unused)]
fn main() {
impl User {
    fn set_active(
        &mut self,
        active: bool,
    ) -> Result<(), UserError> {
        self.active = active;

        Ok(())
    }
}
}

The Model can still enforce domain rules.

For example, perhaps a user cannot deactivate themselves while they are the only administrator:

#![allow(unused)]
fn main() {
impl User {
    fn set_active(
        &mut self,
        active: bool,
    ) -> Result<(), UserError> {
        if !active && self.is_only_admin() {
            return Err(UserError::CannotDeactivateOnlyAdmin);
        }

        self.active = active;

        Ok(())
    }
}
}

The checkbox does not need to understand that rule.

The Model does.

The Model Can Reject a Change

Suppose the user attempts to uncheck the checkbox.

The binding invokes the setter:

Checkbox
    ↓
Binding
    ↓
User::set_active(false)
    ↓
Err(UserError::CannotDeactivateOnlyAdmin)

The Model rejects the state transition.

The existing Model value remains authoritative.

The binding receives the error and exposes it to the checkbox’s error context.

#![allow(unused)]
fn main() {
checkbox()
    .label(localize("user.active.label"))
    .aria(localize("user.active.description"))
    .bind(User::active)
    .error(|errors| text(errors.join("\n")))
}

The errors are derived from the binding.

The checkbox does not invent them.

The Model decides whether the checkbox can change. The checkbox presents the result.

Error Context

Just like the text input and textarea, the checkbox’s .error(...) callback receives &[String] from the current validation state and returns visible content below the control. See Error Callbacks.

#![allow(unused)]
fn main() {
.error(|errors| text(errors.join("\n")))
}

Two things are automatically available inside the state hook:

• self — the checkbox itself
• errors — the current field errors as &[String]

The Model supplies the errors.

The binding associates them with the checkbox.

The View determines how they are presented.

Internationalization

Validation messages should not be hard-coded into the checkbox.

Avoid:

#![allow(unused)]
fn main() {
text("You cannot deactivate yourself.")
}

Instead, the Model returns a structured error and the error context exposes the localized message.

#![allow(unused)]
fn main() {
checkbox()
    .label(localize("user.active.label"))
    .aria(localize("user.active.description"))
    .bind(User::active)
    .error(|errors| text(errors.join("\n")))
}

The label and ARIA description come from localization.

The validation error comes from the Model.

This means the checkbox contains no language-specific validation logic.

The Model returns meaning. The UI presents language.

The Model Can Transform State

A checkbox normally represents a boolean directly, but the Model can still perform additional work when the value changes.

For example, changing active might update related application state:

#![allow(unused)]
fn main() {
impl User {
    fn set_active(
        &mut self,
        active: bool,
    ) -> Result<(), UserError> {
        self.active = active;

        self.update_access_state();

        Ok(())
    }
}
}

The checkbox does not need to know what update_access_state() does.

It simply reflects the resulting Model state.

This is the same principle as phone-number formatting with input().

The form element reports intent. The Model determines the resulting state.

Asynchronous Changes

A checkbox can also trigger an asynchronous Model transition.

For example, activating an account might require a remote operation:

#![allow(unused)]
fn main() {
impl User {
    async fn set_active(
        &mut self,
        active: bool,
    ) -> Result<(), UserError> {
        update_account_status(active).await?;

        self.active = active;

        Ok(())
    }
}
}

The checkbox can represent the pending state:

#![allow(unused)]
fn main() {
checkbox()
    .label(localize("user.active.label"))
    .aria(localize("user.active.description"))
    .bind(User::active)
    .submitting(|| [spinner()])
}

Or:

#![allow(unused)]
fn main() {
checkbox()
    .label(localize("user.active.label"))
    .aria(localize("user.active.description"))
    .bind(User::active)
    .submitting(|| [
            spinner(),
            text(localize("user.active.updating"))
        ])
}

Again, self refers to the checkbox.

The async operation does not directly manipulate the component.

The application sets FormStatusState::submitting() and sets idle() or success() when the operation changes state. The callback supplies content below the checkbox; it does not style or disable the checkbox.

No Manual Change Handler

A checkbox should not require code like:

#![allow(unused)]
fn main() {
on_change(|checked| {
    // manually update the Model
})
}

The binding already establishes that relationship.

Instead:

#![allow(unused)]
fn main() {
checkbox()
    .label(localize("user.active.label"))
    .aria(localize("user.active.description"))
    .bind(User::active)
}

is enough.

The framework knows:

1. The checkbox represents User::active.
2. The current Model value determines whether it is checked.
3. A user change invokes the corresponding setter.
4. The setter can accept, reject, transform, or asynchronously process the change.
5. The resulting Model state is reflected back into the checkbox.

Styling

Checkboxes use the same fluent component API:

#![allow(unused)]
fn main() {
checkbox()
    .label(localize("user.active.label"))
    .aria(localize("user.active.description"))
    .bind(User::active)
    .gap(8)
}

Error presentation:

#![allow(unused)]
fn main() {
checkbox()
    .label(localize("user.active.label"))
    .aria(localize("user.active.description"))
    .bind(User::active)
    .error(|errors| text(errors.join("\n")))
}

Pending presentation:

#![allow(unused)]
fn main() {
checkbox()
    .label(localize("user.active.label"))
    .aria(localize("user.active.description"))
    .bind(User::active)
    .submitting(|| [spinner()])
}

The same API works for normal, error, and pending states.

The Complete Checkbox

A production checkbox might look like:

#![allow(unused)]
fn main() {
checkbox()
    .label(localize("user.active.label"))
    .aria(localize("user.active.description"))
    .bind(User::active)
    .gap(8)
    .error(|errors| text(errors.join("\n")))
    .submitting(|| [spinner()])
}

The checkbox has:

• A required label
• A required ARIA declaration
• A typed bool binding
• Two-way Model synchronization
• Model-owned validation
• Model-owned state transitions
• Model-owned asynchronous behavior
• Automatic error propagation
• Localized error presentation
• Pending-state presentation
• Fluent styling

The checkbox itself remains simple.

The checkbox represents a boolean. The binding connects it. The setter decides whether that boolean can change. The Model owns the state.

Radio

Live Demo

Open the demo in a separate tab.

Model binding: RadioGroupBuilder::new("plan").option("free", "Free").bind(User::plan) connects the group’s string-valued selection to a model field and returns UiElement. See Binding Controls.

RadioGroupBuilder::error(|errors| ...) renders the group’s current validation errors below its options. See Error Callbacks.

A radio control represents a choice from a set of mutually exclusive options.

A radio can be used as a group of options or, when the application only needs a single explicit choice, as a singular radio control.

The underlying contract is the same as every Beverly form element:

The radio represents the choice. The binding connects it. The setter decides whether the choice can change. The Model owns the state.

Radio Groups

The most common use is a group of mutually exclusive options.

For example, a user selecting a subscription plan:

#![allow(unused)]
fn main() {
radio_group()
    .label(localize("subscription.plan.label"))
    .aria(localize("subscription.plan.description"))
    .bind(User::plan)
    .children([
        radio("free")
            .label(localize("subscription.plan.free.label"))
            .aria(localize("subscription.plan.free.description")),

        radio("pro")
            .label(localize("subscription.plan.pro.label"))
            .aria(localize("subscription.plan.pro.description")),

        radio("enterprise")
            .label(localize("subscription.plan.enterprise.label"))
            .aria(localize("subscription.plan.enterprise.description")),
    ])
}

Only one option can be selected at a time.

The group binds to the Model field:

#![allow(unused)]
fn main() {
#[model]
struct User {
    plan: Plan,
}
}

The Model owns the selected value:

#![allow(unused)]
fn main() {
enum Plan {
    Free,
    Pro,
    Enterprise,
}
}

The radio group is therefore not its own state-management system. It is a visual and interactive representation of User::plan.

Binding

Binding works the same way as input(), textarea(), and checkbox().

Model → Binding → Radio Group
Radio → Binding → Setter → Model

When the Model changes, the selected radio changes.

When the user selects a radio, the binding sends the new value to the Model.

The setter is called whenever the selection changes.

#![allow(unused)]
fn main() {
impl User {
    fn set_plan(
        &mut self,
        plan: Plan,
    ) -> Result<(), UserError> {
        if self.requires_upgrade_confirmation(&plan) {
            return Err(UserError::UpgradeRequiresConfirmation);
        }

        self.plan = plan;

        Ok(())
    }
}
}

The UI does not need to reproduce this rule.

An agent, API, or another part of the application changing User::plan uses the same Model mechanics.

The UI is one client of the application. It is not the authority over the application.

Singular Radio

A radio can also be used as a single explicit choice.

This is useful when the application wants a boolean-like decision but wants the visual semantics of a radio control.

#![allow(unused)]
fn main() {
radio("yes")
    .label(localize("user.contact.label"))
    .aria(localize("user.contact.description"))
    .bind(User::contact_me)
}

The same binding rules apply.

If the application instead needs a true/false toggle, checkbox() is generally the more direct representation. Radio is most naturally used when the user is choosing among alternatives.

Radio Options Are Data

Radio groups become particularly useful when options come from application data.

#![allow(unused)]
fn main() {
radio_group()
    .label(localize("subscription.plan.label"))
    .aria(localize("subscription.plan.description"))
    .bind(User::plan)
    .children(
        plans.iter().map(|plan| {
            radio(plan.id())
                .label(localize(plan.label_key()))
                .aria(localize(plan.description_key()))
        })
    )
}

The View does not need to know where the options came from.

They can come from:

• Model state
• A database
• An API
• Configuration
• A local file
• A stream
• AI-generated application data

The View simply renders the available choices.

Validation

Validation belongs in the Model.

For example, the application might prevent a user from selecting an unavailable plan:

#![allow(unused)]
fn main() {
impl User {
    fn set_plan(
        &mut self,
        plan: Plan,
    ) -> Result<(), UserError> {
        if !self.available_plans.contains(&plan) {
            return Err(UserError::PlanUnavailable);
        }

        self.plan = plan;

        Ok(())
    }
}
}

The radio does not need to know why the option is unavailable.

If the setter rejects the change, the Model remains unchanged and the binding keeps the radio selection synchronized with the actual application state.

Field Errors

Errors belong to the binding associated with the radio group.

#![allow(unused)]
fn main() {
radio_group()
    .label(localize("subscription.plan.label"))
    .aria(localize("subscription.plan.description"))
    .bind(User::plan)
    .children([
        radio("free")
            .label(localize("subscription.plan.free.label"))
            .aria(localize("subscription.plan.free.description")),

        radio("pro")
            .label(localize("subscription.plan.pro.label"))
            .aria(localize("subscription.plan.pro.description")),
    ])
    .error(|errors| text(errors.join("\n")))
}

The error text is not hard-coded into the View.

The Model returns the semantic error. Beverly exposes the resulting error context to the field presentation.

The Model returns meaning. The UI presents language.

Async Changes

A radio selection can trigger asynchronous Model logic just like any other bound field.

#![allow(unused)]
fn main() {
impl User {
    async fn set_plan(
        &mut self,
        plan: Plan,
    ) -> Result<(), UserError> {
        check_plan_availability(&plan).await?;

        self.plan = plan;

        Ok(())
    }
}
}

While the transition is pending, the radio group can present a submitting state:

#![allow(unused)]
fn main() {
radio_group()
    .label(localize("subscription.plan.label"))
    .aria(localize("subscription.plan.description"))
    .bind(User::plan)
    .submitting(|| [spinner()])
}

Or provide a richer pending presentation:

#![allow(unused)]
fn main() {
radio_group()
    .label(localize("subscription.plan.label"))
    .aria(localize("subscription.plan.description"))
    .bind(User::plan)
    .submitting(|| [
            spinner(),
            text(localize("subscription.plan.updating")),
        ])
}

The self here refers to the radio group itself.

It does not refer to the Event that caused the state change.

The Event changes application state. The component hook declares how the component should present itself while that state is active.

The app sets and clears FormStatusState; the callback supplies supplementary content below the RadioGroup.

Accessibility

Accessibility is part of the radio’s definition, not cleanup work.

The radio group has a label and accessible description:

#![allow(unused)]
fn main() {
radio_group()
    .label(localize("subscription.plan.label"))
    .aria(localize("subscription.plan.description"))
}

Each individual option also has its own label and accessible description:

#![allow(unused)]
fn main() {
radio("pro")
    .label(localize("subscription.plan.pro.label"))
    .aria(localize("subscription.plan.pro.description"))
}

A radio without its required accessibility metadata is not a valid Beverly form element.

Beverly can therefore catch missing required accessibility declarations at compile time rather than relying entirely on manual review.

Accessible by construction, not accessible by cleanup.

Styling

Radio groups and individual radio controls use the same chained styling API as other Beverly components.

#![allow(unused)]
fn main() {
radio_group()
    .padding(16)
    .radius(12)
    .gap(8)
    .width(400)
}

Individual options can be styled independently:

#![allow(unused)]
fn main() {
radio("pro")
    .label(localize("subscription.plan.pro.label"))
    .aria(localize("subscription.plan.pro.description"))
    .padding(8)
    .radius(8)
}

State-specific styling follows the same pattern:

#![allow(unused)]
fn main() {
radio_group()
    .error(|errors| text(errors.join("\n")))
    .submitting(|| [spinner()])
}

The same API works because these are not special radio behaviors. They are component state presentations.

Complete Example

Putting the pieces together:

#![allow(unused)]
fn main() {
radio_group()
    .label(localize("subscription.plan.label"))
    .aria(localize("subscription.plan.description"))
    .bind(User::plan)
    .children([
        radio("free")
            .label(localize("subscription.plan.free.label"))
            .aria(localize("subscription.plan.free.description")),

        radio("pro")
            .label(localize("subscription.plan.pro.label"))
            .aria(localize("subscription.plan.pro.description")),

        radio("enterprise")
            .label(localize("subscription.plan.enterprise.label"))
            .aria(localize("subscription.plan.enterprise.description")),
    ])
    .error(|errors| text(errors.join("\n")))
    .submitting(|| [spinner()])
}

There is no manual change handler.

There is no second copy of plan inside the View.

There is no UI-specific validation system.

The Model owns the value. The binding keeps the interface synchronized. The radio group presents the available choices.

Radio API

Radio follows the same Beverly philosophy as every other form element:

Create. Configure. Compose. Bind. Declare state. Emit intent.

The radio is simple because the system around it is consistent.

Slider

A slider selects a numeric value within a range. Slider stores the value; SliderStyle controls the track, fill, thumb, and optional value display. BeverlyPlugin installs the slider systems.

Validation Errors

Use .bind(...) with .error(...) to render rejected numeric edits below the slider:

#![allow(unused)]
fn main() {
Slider::new(0.0, 100.0)
    .bind(User::rating)
    .error(|errors| text(errors.join("\n")))
}

Slider::error(...) also supports manual BindingErrorState without binding. See Error Callbacks for lifecycle and setup.

Live Demo

Open the demo in a separate tab.

Basic Usage

#![allow(unused)]
fn main() {
use beverly::components::slider::{Slider, SliderStyle, spawn_slider};
use beverly::prelude::ThemeResource;
use bevy::prelude::*;

fn add_slider(parent: &mut ChildSpawnerCommands, theme: &ThemeResource) {
    spawn_slider(
        parent,
        Slider::new(0.0, 100.0).value(42.0).step(1.0).label("Volume"),
        SliderStyle::default(),
        theme,
    );
}
}

Use .disabled(true) to prevent interaction. Provide .label(...) as the accessible name, and keep a visible label beside the control.

Reading Changes

Read SliderChanged with MessageReader<SliderChanged> in an update system. Each message contains the slider entity, its numeric value, and whether it is currently dragging. The example uses the entity to update only the matching readout; application state remains owned by the application.

Toggle Switch

A toggle switch represents an on/off setting. ToggleConfig supplies the label, initial checked state, and disabled state; the spawned Toggle component holds the current state. BeverlyPlugin installs its interaction and visual systems.

Live Demo

Open the demo in a separate tab.

Basic Usage

#![allow(unused)]
fn main() {
use beverly::components::toggle::{ToggleConfig, ToggleShadowMaterial, spawn_toggle};
use beverly::prelude::ThemeResource;
use bevy::prelude::*;

fn add_toggle(
    parent: &mut ChildSpawnerCommands,
    theme: &ThemeResource,
    materials: &mut Assets<ToggleShadowMaterial>,
) -> Entity {
    spawn_toggle(
        parent,
        ToggleConfig::new().label("Notifications").checked(true),
        theme,
        materials,
    )
}
}

Pass the application’s ResMut<Assets<ToggleShadowMaterial>> into this helper; do not create a temporary asset collection. Use .disabled(true) for a locked setting, or .thumb_icons(...) to configure the two thumb icons.

Read Toggle::checked through a query when synchronizing application settings or status text. The demo counts checked switches, including the disabled one. Model binding is optional. Use ToggleConfig::new().bind(User::enabled) to connect a boolean model field, or handle toggle events explicitly.

Use .error(|errors| text(errors.join("\n"))) on a ToggleConfig or its bound UiElement to render validation messages below the switch. See Error Callbacks.

Select

Model binding: Select::new(vec!["free".to_owned()]).bind(User::plan) connects a typed Select to a model field and returns UiElement. See Binding Controls.

Select<T>::error(|errors| ...) and bound fluent selects render the current error messages below the control. Typed selects preserve their actual option type and can use application-owned BindingErrorState even without automatic field binding. See Error Callbacks.

select() lets a user choose a value from a list of available choices.

It follows the same Beverly form-element contract as input(), textarea(), checkbox(), and radio_group():

The Select presents choices. The binding connects them. The setter validates and transforms the value. The Model owns the state.

The individual choices are represented by option(), which is covered separately.

Concrete Rust API

The component API is generic: Select<T> stores the actual option values, and SelectChanged<T> reports the selected value as T together with the select entity and option index. T must be Clone + Display + Send + Sync + 'static; its Display output is also used as the default accessible option label.

BeverlyPlugin registers SelectPlugin<String>. For each additional concrete option type, register its plugin once:

#![allow(unused)]
fn main() {
use beverly::components::select::spawn_select;
use beverly::prelude::{Select, SelectPlugin};

app.add_plugins(SelectPlugin::<Region>::default());
}

Then create the UI under a parent with spawn_select, supplying the options and a font handle:

#![allow(unused)]
fn main() {
use beverly::components::select::{spawn_select, Select};

spawn_select(parent, Select::new(regions), font_handle);
}

Read SelectChanged<Region> (from beverly::components::select) as a Bevy message to receive the selected typed value. .bind(...) provides automatic two-way synchronization when T implements BindingValueType + Display. Built-in conversions cover strings and numeric scalar values; custom types can implement BindingValueType to map to a model field. Enum-valued selects can also use typed messages when no binding conversion is appropriate.

Basic Select

A Select binds directly to Model state:

#![allow(unused)]
fn main() {
select()
    .label(localize("user.country.label"))
    .aria(localize("user.country.description"))
    .bind(User::country)
}

The Model owns the selected value:

#![allow(unused)]
fn main() {
#[model]
struct User {
    country: Country,
}
}

The Select does not maintain a second authoritative copy of country.

When the Model changes, the Select reflects the new value.

When the user makes a selection, the binding sends the new value to the Model.

Model → Binding → Select
Select → Binding → Setter → Model

Options

Options are added through children():

#![allow(unused)]
fn main() {
select()
    .label(localize("user.country.label"))
    .aria(localize("user.country.description"))
    .bind(User::country)
    .children([
        option("us")
            .label(localize("country.us")),
        option("ca")
            .label(localize("country.ca")),
        option("id")
            .label(localize("country.id")),
    ])
}

select() owns the selection behavior.

option() represents an individual available choice.

This separation keeps the API composable and makes the same options reusable wherever appropriate.

Data-Driven Options

Options can come directly from application data.

#![allow(unused)]
fn main() {
select()
    .label(localize("user.country.label"))
    .aria(localize("user.country.description"))
    .bind(User::country)
    .children(
        countries.iter().map(|country| {
            option(country.code())
                .label(localize(country.label_key()))
        })
    )
}

The options might come from:

• Model state
• A database
• An API
• Configuration
• A local file
• A stream
• AI-generated data

The Select only needs to render the choices provided to it.

Binding

Binding handles the conversion between the selected option and the typed Model value.

#![allow(unused)]
fn main() {
select()
    .label(localize("user.role.label"))
    .aria(localize("user.role.description"))
    .bind(User::role)
}

When the user selects a different option, the Model setter is called.

For example:

#![allow(unused)]
fn main() {
impl User {
    fn set_role(
        &mut self,
        role: Role,
    ) -> Result<(), UserError> {
        if !self.allowed_roles.contains(&role) {
            return Err(UserError::RoleNotAllowed);
        }

        self.role = role;

        Ok(())
    }
}
}

The Select does not need to know why a role is unavailable.

The Model owns that rule.

If the setter rejects the change, the Model remains unchanged and the Select remains synchronized with the actual application state.

The input reports the choice. The Model decides what that choice means.

Transformation

The setter can also transform the selected value before storing it.

#![allow(unused)]
fn main() {
impl User {
    fn set_country(
        &mut self,
        country: String,
    ) -> Result<(), UserError> {
        let country = normalize_country_code(&country)?;

        self.country = country;

        Ok(())
    }
}
}

The Select does not need to understand normalization.

The binding translates the selection into the Model’s type, and the Model remains the source of truth.

Validation Errors

Validation errors belong to the bound field.

#![allow(unused)]
fn main() {
select()
    .label(localize("user.role.label"))
    .aria(localize("user.role.description"))
    .bind(User::role)
    .error(|errors| text(errors.join("\n")))
}

The error context is supplied automatically to the field presentation.

self refers to the Select itself.

errors represents the current errors associated with its binding.

The UI does not hard-code validation messages. The Model returns the semantic error, and the application’s localization layer provides the appropriate language.

The Model returns meaning. The UI presents language.

Async Validation

A selection can trigger asynchronous validation or state transitions.

#![allow(unused)]
fn main() {
impl User {
    async fn set_role(
        &mut self,
        role: Role,
    ) -> Result<(), UserError> {
        check_role_availability(&role).await?;

        self.role = role;

        Ok(())
    }
}
}

While the transition is pending, the Select can change its presentation:

#![allow(unused)]
fn main() {
select()
    .label(localize("user.role.label"))
    .aria(localize("user.role.description"))
    .bind(User::role)
    .submitting(|| [spinner()])
}

Or provide a richer pending presentation:

#![allow(unused)]
fn main() {
select()
    .label(localize("user.role.label"))
    .aria(localize("user.role.description"))
    .bind(User::role)
    .submitting(|| [
            spinner(),
            text(localize("user.role.updating")),
        ])
}

Again, self refers to the Select component.

It does not refer to the Event that caused the state change.

The Event or Model transition changes state. The component hook declares how the Select presents that state.

The app sets and clears FormStatusState; the callback supplies supplementary content below the Select.

Styling

Select uses the same fluent styling API as other Beverly components:

#![allow(unused)]
fn main() {
select()
    .padding(12)
    .radius(8)
    .width(300)
}

State-specific styling uses the same mechanism:

#![allow(unused)]
fn main() {
select()
    .error(|errors| text(errors.join("\n")))
    .submitting(|| [spinner()])
}

There is no separate styling system for form states.

The component API remains consistent.

Accessibility

A Select is not a valid Beverly form element without its required accessibility metadata.

At minimum, the Select declares both its label and accessible description:

#![allow(unused)]
fn main() {
select()
    .label(localize("user.country.label"))
    .aria(localize("user.country.description"))
    .bind(User::country)
}

The label identifies the control.

The ARIA declaration provides additional accessible semantics or description.

These are part of the component contract, not cleanup work.

Beverly can enforce required accessibility metadata at compile time, helping prevent expensive accessibility and compliance failures.

Accessible by construction, not accessible by cleanup.

Complete Example

A complete Select combines styling, binding, options, validation, and state presentation:

#![allow(unused)]
fn main() {
select()
    .label(localize("user.country.label"))
    .aria(localize("user.country.description"))
    .bind(User::country)
    .padding(12)
    .radius(8)
    .width(300)
    .children([
        option("us")
            .label(localize("country.us")),

        option("ca")
            .label(localize("country.ca")),

        option("id")
            .label(localize("country.id")),
    ])
    .error(|errors| text(errors.join("\n")))
    .submitting(|| [spinner()])
}

The Select itself remains simple.

It presents choices.

The binding connects those choices to typed application state.

The Model owns validation, transformation, and state.

Select API

option() defines the choices inside the Select and will be covered next.

Select chooses. Binding connects. The Model owns the value.

Option

Model binding: Bind the containing Select<T> to a model field when T implements BindingValueType + Display; an individual option is a choice, not a separate value-bearing control. See Binding Controls.

Error callbacks also belong to the containing Select/RadioGroup/Dropdown, not to an individual option. See Error Callbacks.

option() represents a single available choice.

It is primarily used inside select(), but the component is intentionally designed as a simple, composable representation of a value and its presentation.

The Option represents a choice. The Select manages the choices. The Model owns the selected value.

Basic Option

An Option has a value and a label:

#![allow(unused)]
fn main() {
option("pro")
    .label(localize("subscription.plan.pro.label"))
}

The value is what the application receives.

The label is what the user sees.

These do not have to be the same.

#![allow(unused)]
fn main() {
option("enterprise-plan-v2")
    .label(localize("subscription.plan.enterprise.label"))
}

The application can use a stable internal value while presenting a human-readable, localized label.

Inside a Select

Options are normally composed inside a Select:

#![allow(unused)]
fn main() {
select()
    .label(localize("subscription.plan.label"))
    .aria(localize("subscription.plan.description"))
    .bind(User::plan)
    .children([
        option("free")
            .label(localize("subscription.plan.free.label")),

        option("pro")
            .label(localize("subscription.plan.pro.label")),

        option("enterprise")
            .label(localize("subscription.plan.enterprise.label")),
    ])
}

The Select determines which Option is selected.

The Option does not maintain its own copy of application state.

Value and Model State

The Option’s value is translated by the binding into the Model’s type.

For example:

#![allow(unused)]
fn main() {
#[model]
struct User {
    plan: Plan,
}
}

with:

#![allow(unused)]
fn main() {
enum Plan {
    Free,
    Pro,
    Enterprise,
}
}

The Select can present string values while the binding maps them to the appropriate application type.

The important boundary is:

Option value
    ↓
Select
    ↓
Binding
    ↓
Model

The Option does not need to understand the Model.

Labels

Every Option should have a user-facing label.

#![allow(unused)]
fn main() {
option("pro")
    .label(localize("subscription.plan.pro.label"))
}

The label is presentation.

The value is application data.

This separation makes Options useful for localization, changing copy, accessibility, and data-driven interfaces without changing the underlying application value.

Accessibility

Options participate in the accessibility semantics of their parent choice control.

When an Option exposes user-facing content, that content should be explicitly defined rather than relying on incidental implementation details.

#![allow(unused)]
fn main() {
option("pro")
    .label(localize("subscription.plan.pro.label"))
}

The parent select() still requires its own .label(...) and .aria(...) declarations:

#![allow(unused)]
fn main() {
select()
    .label(localize("subscription.plan.label"))
    .aria(localize("subscription.plan.description"))
    .children([
        option("free")
            .label(localize("subscription.plan.free.label")),

        option("pro")
            .label(localize("subscription.plan.pro.label")),
    ])
}

Beverly treats accessibility as part of the component contract.

Accessible by construction, not accessible by cleanup.

Disabled Options

An Option can be unavailable without removing it from the list.

#![allow(unused)]
fn main() {
option("enterprise")
    .label(localize("subscription.plan.enterprise.label"))
    .disabled(true)
}

This is useful when the application wants to communicate that a choice exists but cannot currently be selected.

The reason for that state belongs to application data and logic, not the Option itself.

For example, the Model may determine that a plan is unavailable for the current account.

The View simply reflects that state.

Data-Driven Options

Options can be generated directly from Model data:

#![allow(unused)]
fn main() {
select()
    .label(localize("user.country.label"))
    .aria(localize("user.country.description"))
    .bind(User::country)
    .children(
        countries.iter().map(|country| {
            option(country.code())
                .label(localize(country.label_key()))
        })
    )
}

This keeps the Option deliberately lightweight.

The application determines which choices exist.

The Option determines how each choice is represented.

Conditional Options

Options can also be composed conditionally:

#![allow(unused)]
fn main() {
select()
    .label(localize("user.role.label"))
    .aria(localize("user.role.description"))
    .bind(User::role)
    .children([
        option("user")
            .label(localize("role.user")),

        option("admin")
            .label(localize("role.admin")),

        if permissions.can_manage_billing() {
            option("billing")
                .label(localize("role.billing"))
        }
    ])
}

The same children() composition model applies everywhere in Beverly.

An Option is just another component that can be created, configured, and composed.

Styling

Options can expose styling hooks where the underlying choice component supports them:

#![allow(unused)]
fn main() {
option("pro")
    .label(localize("subscription.plan.pro.label"))
    .padding(8)
}

However, the Select generally owns the overall presentation of its option list.

This distinction keeps responsibilities clear:

• Select — selection behavior and list presentation
• Option — individual choice and its presentation
• Binding — connection to application state
• Model — value, validation, and domain rules

No Option-Level State Management

An Option should not become a miniature state-management system.

It does not need its own copy of the selected value.

It does not need its own event architecture.

It does not decide whether a choice is valid.

Those responsibilities already have a home.

The Option simply describes a choice.

If ordinary Rust and the parent component can solve it, Option does not need another abstraction.

Complete Example

#![allow(unused)]
fn main() {
select()
    .label(localize("user.plan.label"))
    .aria(localize("user.plan.description"))
    .bind(User::plan)
    .children([
        option("free")
            .label(localize("user.plan.free.label")),

        option("pro")
            .label(localize("user.plan.pro.label")),

        option("enterprise")
            .label(localize("user.plan.enterprise.label"))
            .disabled(!permissions.can_use_enterprise()),
    ])
}

The structure is intentionally obvious.

The user sees a list of choices.

The Select manages the selection.

The binding connects that selection to the Model.

The Model remains the source of truth.

Option API

Option is intentionally one of the smallest Beverly primitives.

Create. Label. Configure. Compose.

The complexity belongs in the components that actually own the behavior — not in the individual choice.

Search

Live Demo

Open the demo in a separate tab.

Search controls help users filter or locate items in a data-heavy interface. They are especially useful when a user is trying to find an item quickly without scanning a long list manually.

Validation Errors

Both Search and SearchBox use the shared error callback API:

#![allow(unused)]
fn main() {
UiElement::search()
    .bind(User::query)
    .error(|errors| text(errors.join("\n")))
}

Use UiElement::searchbox("Search") for the SearchBox variant. The callback renders errors below the search control, while the accessible invalid/error relationships remain attached to the editor. See Error Callbacks.

Example

#![allow(unused)]
fn main() {
use bevy::prelude::*;
use beverly::prelude::*;

fn build_search(mut commands: Commands) {
    commands.spawn(BeverlySearch::new("Search files")
        .with_action("Submit"));
}
}

Guidance

Large interfaces should provide instant filtering feedback, clear empty states, and visible results count where possible. A search surface is most useful when it feels responsive and clear about what the query is matching.

Accessibility

Search inputs must have proper labels, preserve keyboard flow, and remain easy to operate in dense layouts. Empty-state messaging and result counts should be understandable even when a user is not relying on the visual emphasis alone.

File Input

Live Demo

Open the demo in a separate tab.

Model binding: FileInput::new("Files").bind(User::files) connects a Vec<SelectedFile> model field to the selected files and returns UiElement. See Binding Controls.

FileInput::error(|errors| ...) renders file-selection validation errors below the control. See Error Callbacks.

The FileInput lets a user select a file from their device.

It follows the same binding model as every other Beverly form control: the input collects a value, the binding connects it to the Model, and the Model decides what that value means.

A file input adds a few concerns that ordinary text inputs do not have:

• Where the selected file should be saved or uploaded.
• Which file types are accepted.
• What happens when a file is selected.
• How the selected file is represented in application state.
• Optional file-size and validation constraints.
• Progress and submission state for operations that process the file.

The UI component should remain simple. It provides the interface for selecting a file; the application decides what to do with it.

The File Input selects. The binding connects. The Model owns the file state.

Basic Usage

A file input can be created with file_input() and configured using the same fluent API as other Beverly inputs.

#![allow(unused)]
fn main() {
file_input()
    .label(localize("document.file.label"))
    .aria(localize("document.file.description"))
    .placeholder(localize("document.file.placeholder"))
    .bind(Document::file)
}

The important pieces are familiar:

• .label(...) gives the control its accessible name.
• .aria(...) provides additional accessible context.
• .placeholder(...) provides guidance before a file has been selected.
• .bind(...) connects the input to the Model.

The File Input does not need to know what the application intends to do with the file.

It might be uploaded to a server, stored locally, processed immediately, passed to an AI model, imported into a database, or written to a data lake.

That decision belongs to the application.

File State

A file is not just a string.

The Model should normally represent a selected file using an application type that contains the information the application actually needs.

For example:

#![allow(unused)]
fn main() {
struct FileSelection {
    name: String,
    size: u64,
    mime_type: String,
}
}

The Model might then contain:

#![allow(unused)]
fn main() {
struct Document {
    file: Option<FileSelection>,
}
}

The File Input binds to that state:

#![allow(unused)]
fn main() {
file_input()
    .label(localize("document.file.label"))
    .aria(localize("document.file.description"))
    .placeholder(localize("document.file.placeholder"))
    .bind(Document::file)
}

The important distinction is that the File Input does not become the owner of the file.

The Model owns the application state.

Accepted File Types

Applications can specify which file types the input accepts.

#![allow(unused)]
fn main() {
file_input()
    .label(localize("document.file.label"))
    .aria(localize("document.file.description"))
    .placeholder(localize("document.file.placeholder"))
    .accept([
        "application/pdf",
        "text/plain",
        "text/markdown",
    ])
    .bind(Document::file)
}

Extensions can also be useful when the application’s vocabulary is extension-based:

#![allow(unused)]
fn main() {
file_input()
    .label(localize("document.file.label"))
    .aria(localize("document.file.description"))
    .accept([
        ".pdf",
        ".txt",
        ".md",
    ])
    .bind(Document::file)
}

The accepted types describe what the UI should offer as valid input.

They are not a substitute for Model validation.

The Model should still validate the file when it receives it.

UI constraints guide input. Model validation protects application state.

This is particularly important when files can enter the application through other sources such as APIs, automated jobs, agents, or local processes.

File Location

A File Input can optionally specify where the selected file should be saved or staged.

#![allow(unused)]
fn main() {
file_input()
    .label(localize("document.file.label"))
    .aria(localize("document.file.description"))
    .placeholder(localize("document.file.placeholder"))
    .location("/documents")
    .bind(Document::file)
}

The location is an application-level destination rather than part of the file’s identity.

For example:

#![allow(unused)]
fn main() {
file_input()
    .location("/imports")
}

could mean:

When the user selects a file, make it available to the application’s import pipeline at /imports.

The exact behavior of the location depends on the application.

A local desktop application might save directly to a filesystem location. Another application might use the location as a staging directory before uploading the file. An application could also map the location to object storage or another persistence layer.

The File Input provides the configuration point. The application owns the actual storage behavior.

Placeholder

The placeholder provides guidance before a file has been selected.

#![allow(unused)]
fn main() {
file_input()
    .label(localize("document.file.label"))
    .aria(localize("document.file.description"))
    .placeholder(localize("document.file.placeholder"))
    .bind(Document::file)
}

For example, the localized value might be:

Select a PDF or Markdown file

The placeholder should describe what the user can do rather than becoming the primary accessible name.

The .label(...) remains the control’s name.

Labels and Accessibility

A File Input is a form control, so accessibility is part of its basic construction.

Every File Input should have both a label and accessible description.

#![allow(unused)]
fn main() {
file_input()
    .label(localize("document.file.label"))
    .aria(localize("document.file.description"))
    .bind(Document::file)
}

For example:

#![allow(unused)]
fn main() {
file_input()
    .label(localize("document.file.label"))
    .aria(localize("document.file.description"))
    .placeholder(localize("document.file.placeholder"))
}

The label identifies the control.

The ARIA description can provide additional context such as supported formats, size restrictions, or what happens after selection.

For example:

Label:
Upload document

ARIA:
Select a PDF, Markdown, or text document. Maximum size 25 MB.

The important information should remain available through the control’s accessible semantics rather than relying only on visual placeholder text.

Accessible by construction, not accessible by cleanup.

File Size

File size is an important constraint for file inputs.

A UI can communicate a maximum size:

#![allow(unused)]
fn main() {
file_input()
    .label(localize("document.file.label"))
    .aria(localize("document.file.description"))
    .max_size(25 * 1024 * 1024)
    .bind(Document::file)
}

But the Model remains responsible for deciding whether the file is actually valid.

For example:

#![allow(unused)]
fn main() {
impl Document {
    fn set_file(&mut self, file: FileSelection) -> Result<(), DocumentError> {
        if file.size > 25 * 1024 * 1024 {
            return Err(DocumentError::FileTooLarge);
        }

        self.file = Some(file);

        Ok(())
    }
}
}

The input can prevent obviously invalid selections from reaching the application, while the Model provides the authoritative validation.

This keeps the same architecture used by text inputs, selects, checkboxes, and other controls.

Binding

.bind() works the same way as other Beverly form controls.

#![allow(unused)]
fn main() {
file_input()
    .label(localize("document.file.label"))
    .aria(localize("document.file.description"))
    .bind(Document::file)
}

Conceptually:

File Selection
      ↓
   Binding
      ↓
 Model Setter
      ↓
Application State

When a user selects a file, the binding passes the file to the Model.

The setter can then:

• validate the file type
• validate the file size
• normalize metadata
• save or stage the file
• initiate processing
• reject the file
• update application state

The File Input does not need to implement those rules itself.

File Validation

Validation belongs in the Model.

For example:

#![allow(unused)]
fn main() {
impl Document {
    fn set_file(&mut self, file: FileSelection) -> Result<(), DocumentError> {
        if !is_supported_type(&file.mime_type) {
            return Err(DocumentError::UnsupportedFileType);
        }

        if file.size > MAX_FILE_SIZE {
            return Err(DocumentError::FileTooLarge);
        }

        self.file = Some(file);

        Ok(())
    }
}
}

The UI can provide an accepted-type hint:

#![allow(unused)]
fn main() {
.accept([
    ".pdf",
    ".md",
    ".txt",
])
}

while the Model remains authoritative.

This means the same validation applies regardless of where the file came from.

A human selecting a file and an agent submitting a file should encounter the same application rules.

The UI suggests. The Model decides.

File Errors

File validation errors can be presented using the same .error(...) mechanism used by other form controls.

#![allow(unused)]
fn main() {
file_input()
    .label(localize("document.file.label"))
    .aria(localize("document.file.description"))
    .bind(Document::file)
    .error(|errors| text(errors.join("\n")))
}

The UI does not need to hard-code validation messages.

The Model produces the semantic error, and the presentation layer determines how that error is displayed and localized.

The Model returns meaning. The UI presents language.

Submitting State

File processing may take time.

For example, selecting a file might initiate:

• a local copy
• parsing
• indexing
• uploading
• virus scanning
• AI processing
• document extraction

The File Input can respond to the application’s submitting state:

#![allow(unused)]
fn main() {
file_input()
    .label(localize("document.file.label"))
    .aria(localize("document.file.description"))
    .bind(Document::file)
    .submitting(|| [spinner()])
}

The component does not need to know why the application is submitting.

It simply provides a presentation for that state.

Success and Error Presentation

The File Input can provide state-specific presentation hooks:

#![allow(unused)]
fn main() {
file_input()
    .label(localize("document.file.label"))
    .aria(localize("document.file.description"))
    .bind(Document::file)
    .submitting(|| [spinner()])
    .error(|errors| text(errors.join("\n")))
    .success(|| [text("Saved")])
}

These hooks describe how the component should appear when the associated state exists.

They do not create or own that state.

The application sets FormStatusState; the callback supplies supplementary content and does not infer picker or upload state.

Multiple Files

Some applications need a single file. Others need a collection.

A File Input can support multiple selection when the application requires it:

#![allow(unused)]
fn main() {
file_input()
    .label(localize("documents.files.label"))
    .aria(localize("documents.files.description"))
    .placeholder(localize("documents.files.placeholder"))
    .multiple(true)
    .accept([
        ".pdf",
        ".md",
        ".txt",
    ])
    .bind(DocumentImport::files)
}

The Model can then own a collection:

#![allow(unused)]
fn main() {
struct DocumentImport {
    files: Vec<FileSelection>,
}
}

The same principles apply.

The UI collects the selection.

The binding connects it.

The Model owns the resulting state.

File Processing Is Not File Input

The File Input should not become an upload framework.

For example, these are separate concerns:

File Input
    ↓
File Selection
    ↓
Model
    ↓
Processing / Upload / Import

Selecting a file is one operation.

Uploading it is another.

Parsing it is another.

Indexing it is another.

Sending it to an AI model is another.

Beverly’s architecture keeps those responsibilities separate.

For example:

#![allow(unused)]
fn main() {
controller! {
    Document::Selected => [
        Document::validate,
        Document::store,
        Document::index,
    ],
}
}

The File Input does not need to understand that pipeline.

It simply reports the user’s selection.

File Input Events

The File Input can expose UI lifecycle Events when the application needs to observe interaction.

For example:

#![allow(unused)]
fn main() {
file_input()
    .label(localize("document.file.label"))
    .aria(localize("document.file.description"))
    .on("select", Ui::DocumentFile::Selected)
    .bind(Document::file)
}

The UI Event describes what happened at the interface.

The application Command describes what should happen as a result.

This preserves the same distinction used throughout Beverly:

UI Event
    ↓
Controller
    ↓
Command
    ↓
Model

The File Input does not decide what selecting a file means.

Data-Driven File Inputs

File inputs can be created by ordinary Rust functions.

For example:

#![allow(unused)]
fn main() {
fn document_file_input() -> FileInput {
    file_input()
        .label(localize("document.file.label"))
        .aria(localize("document.file.description"))
        .placeholder(localize("document.file.placeholder"))
        .accept([
            ".pdf",
            ".md",
            ".txt",
        ])
        .max_size(25 * 1024 * 1024)
        .bind(Document::file)
}
}

Then:

#![allow(unused)]
fn main() {
document_file_input()
}

This is not a second component system.

It is simply ordinary Rust returning a Beverly component.

Higher-level components are ordinary Rust functions that return lower-level components.

Styling

File Inputs use the same fluent styling model as other Beverly components.

#![allow(unused)]
fn main() {
file_input()
    .label(localize("document.file.label"))
    .aria(localize("document.file.description"))
    .padding(12)
    .radius(8)
    .border_width(1)
    .width(400)
}

Application-specific presentation can be built on top:

#![allow(unused)]
fn main() {
fn document_uploader() -> FileInput {
    file_input()
        .label(localize("document.file.label"))
        .aria(localize("document.file.description"))
        .placeholder(localize("document.file.placeholder"))
        .accept([".pdf", ".md"])
        .max_size(25 * 1024 * 1024)
        .padding(16)
        .radius(12)
        .bind(Document::file)
}
}

The primitive remains simple while higher-level components can establish the application’s visual language.

What File Input Does Not Do

The File Input does not own:

• application state
• business rules
• file validation policy
• upload policy
• authentication
• authorization
• database state
• AI processing
• document parsing
• indexing
• application workflow

Those responsibilities belong elsewhere.

The File Input has one clear job:

Provide an accessible interface for selecting files and connect that selection to application state.

File Input and the Model

The complete relationship is straightforward:

User
  ↓
File Input
  ↓
Binding
  ↓
Model Setter
  ↓
Application State

The Model can then trigger whatever the application needs.

File Input
    ↓
Document::file
    ↓
Validation
    ↓
Storage
    ↓
Processing
    ↓
Indexing
    ↓
Application

The File Input remains unaware of the pipeline.

That separation is what makes it reusable.

File Input vs Text Input

The architecture stays the same even though the value is different.

The Principle

File Input does not need to become complicated simply because files are more complicated than strings.

The same Beverly model applies:

Create. Configure. Compose. Bind. Declare state. Emit intent.

The File Input provides the file-selection interface.

The binding connects it to the Model.

The Model validates and owns the resulting state.

The Controller decides what happens next.

And the rest of the application can process the file however it needs.

The File Input selects. The Binding connects. The Model validates. The Controller orchestrates. The application decides what the file means.

Use image() with .src(...) for local, embedded, handle-backed, or HTTP(S) image sources. Use Photo when a fixed framed photo surface is needed, and Avatar for circular profile imagery with initials fallback.

Images

Image

image() creates a UI image. Set its source with .src(...) and provide accessible alternative text with .alt(...):

#![allow(unused)]
fn main() {
use beverly::prelude::*;

let report = image()
    .src("photos/report.webp")
    .alt("Quarterly revenue chart")
    .width(640)
    .height(360);

let remote = image()
    .src("https://cdn.example.com/team/alex.png?size=256")
    .alt("Alex Chen");
}

The same API accepts a Handle<Image> for generated or in-memory assets, local asset paths, Bevy embedded:// paths, and external HTTP(S) URLs. An image that conveys no information should use .decorative(true) instead of an empty alternative description.

Local SVG Assets

The package includes small SVG samples at assets/examples/analytics.svg and assets/examples/mark.svg. In a Bevy application whose asset root is the workspace assets directory, refer to these as relative paths:

#![allow(unused)]
fn main() {
image()
    .src("examples/analytics.svg")
    .alt("Line chart showing monthly usage increasing through the year")
    .width(640)
    .height(360)

image()
    .src("examples/mark.svg")
    .alt("Geometric Beverly mark")
    .width(96)
    .height(96)
}

SVG is rasterized at its intrinsic size. External SVG resources are disabled; inline vector shapes and paths work, but linked images, external styles, and external fonts are not fetched.

Supported Formats

The built-in decoder supports PNG, JPEG, GIF, WebP, SVG, BMP, and ICO. These formats are enabled by Beverly’s default image_formats feature plus SVG rasterization. AVIF is unsupported by the configured Bevy decoder and produces an explicit load error. Animated GIF/WebP sources display as a decoded still image.

Encoded downloads are limited to 16 MiB and raster output to 16 megapixels. SVG output is subject to the same pixel limit. These limits reduce accidental large allocations; they are not a complete defense against untrusted assets.

External images use Bevy’s HTTP(S) asset readers. Browser servers must permit the app’s origin with CORS, and HTTPS apps require HTTPS image URLs to avoid mixed-content blocking. Query parameters are preserved, fragments are removed, and embedded credentials or non-HTTP(S) URL schemes are rejected. Apply application-specific URL allowlists when sources are not trusted.

Loading State

ImageStatus on the spawned image entity reports Empty, Loading, Ready, or Failed(message). Observe it to show a placeholder, retain a fallback, or hide a decorative image while loading. Changing .src(...) loads the new source and replaces the existing image. Photo::new(Handle<Image>) and avatar image paths remain available for their specialized layouts.

Accessibility

Provide meaningful alternative text for informative images:

#![allow(unused)]
fn main() {
image()
    .src("products/compass.webp")
    .alt("Brass pocket compass with its needle pointing north")
}

For decorative imagery, explicitly mark it:

#![allow(unused)]
fn main() {
image()
    .src("textures/paper-grain.svg")
    .decorative(true)
}

A missing or whitespace-only alt on a non-decorative image is reported as a warning when spawned. Alternative text should describe the information the image contributes, not repeat nearby captions.

Live Demo

Open the demo in a separate tab.

Avatar

Live Demo

Open the demo in a separate tab.

An Avatar is a circular image used to represent a person, account, or other identity.

It is intentionally a very small abstraction over the Image primitive. It does not introduce a new image system, state system, or composition model.

An Avatar is an Image with an opinionated shape.

Basic Usage

Create an Avatar with avatar() and configure it with the same fluent API used by other Beverly components.

#![allow(unused)]
fn main() {
avatar()
    .src("profile.jpg")
}

The default presentation is circular.

For accessibility, provide a description of who or what the image represents:

#![allow(unused)]
fn main() {
avatar()
    .src("profile.jpg")
    .aria(localize("user.avatar.description"))
}

The Avatar does not require application state. It simply presents an image.

Sizing

Use the same sizing primitives available to Image:

#![allow(unused)]
fn main() {
avatar()
    .src("profile.jpg")
    .width(48)
    .height(48)
}

Because an Avatar is circular, width and height are normally equal.

Different sizes can be used for different contexts:

#![allow(unused)]
fn main() {
avatar()
    .src("profile.jpg")
    .width(32)
    .height(32)
}

#![allow(unused)]
fn main() {
avatar()
    .src("profile.jpg")
    .width(64)
    .height(64)
}

#![allow(unused)]
fn main() {
avatar()
    .src("profile.jpg")
    .width(96)
    .height(96)
}

Styling

Avatar provides a convenient circular presentation without requiring the application to manually configure the image radius.

Additional styling can still be applied through the normal fluent API:

#![allow(unused)]
fn main() {
avatar()
    .src("profile.jpg")
    .width(48)
    .height(48)
    .border_width(2)
}

The Avatar remains an Image underneath. Its purpose is simply to establish a useful default presentation for identity images.

Data-Driven Avatars

Avatars commonly come from application data.

#![allow(unused)]
fn main() {
avatar()
    .src(user.avatar_url())
    .aria(localize("user.avatar.description"))
}

The Avatar does not care where the image came from.

The Model might provide the URL from a database, API, local file, or another source. The View simply presents it.

Model → View → Avatar → Image

The Avatar does not own the user’s identity. It presents it.

Composition

Avatar composes with other Beverly primitives like any other component.

#![allow(unused)]
fn main() {
card()
    .children([
        avatar()
            .src(user.avatar_url())
            .aria(localize("user.avatar.description")),

        text(user.name()),
        badge(user.status()),
    ])
}

It can also be used anywhere an Image can be used:

#![allow(unused)]
fn main() {
row()
    .children([
        avatar().src("alice.jpg"),
        text("Alice"),
    ])
}

There is no special Avatar composition system.

One composition model. Ordinary Rust.

Higher-Level Components

Building a higher-level Avatar component is just an ordinary Rust function that returns an Avatar.

#![allow(unused)]
fn main() {
fn user_avatar(user: &User) -> Avatar {
    avatar()
        .src(user.avatar_url())
        .width(48)
        .height(48)
        .aria(localize("user.avatar.description"))
}
}

Use it like any other component:

#![allow(unused)]
fn main() {
user_avatar(&user)
}

A more specialized component can build on the same primitive:

#![allow(unused)]
fn main() {
fn profile_avatar(user: &User) -> Avatar {
    avatar()
        .src(user.avatar_url())
        .width(64)
        .height(64)
        .aria(localize("user.profile_avatar.description"))
}
}

There is no need for a nested Avatar component or a special extension mechanism.

Higher-level components are ordinary Rust functions that return lower-level components.

Interaction

An Avatar is not inherently interactive.

If an application wants an Avatar to perform an action, the application can attach the appropriate UI event:

#![allow(unused)]
fn main() {
avatar()
    .src(user.avatar_url())
    .aria(localize("user.avatar.description"))
    .on("click", Command::User::OpenProfile)
}

The Avatar reports the interaction. The application decides what that interaction means.

An Avatar can also be placed inside another interactive component when that better represents the interface.

Accessibility

An Avatar is an image, so its accessible meaning should describe the identity or purpose represented by the image.

#![allow(unused)]
fn main() {
avatar()
    .src(user.avatar_url())
    .aria(localize("user.avatar.description"))
}

For example, the localized description might communicate that the image represents a particular user.

If the Avatar is interactive, its surrounding interaction should also have an appropriate accessible label and description.

Accessible by construction, not accessible by cleanup.

What Avatar Does Not Do

Avatar does not:

• own user state
• manage identity
• load or cache application data
• manage authentication
• provide a separate image system
• define application behavior
• create application Events
• replace the Image primitive

Those concerns belong elsewhere.

The Avatar only provides a convenient semantic presentation for a circular image.

Avatar and Image

When you need a general image, use image().

When you need a circular identity image, use avatar().

Internally, the distinction should remain small.

The Avatar is simply an Image with an opinionated presentation.

Design Principle

Beverly should not create a new abstraction unless the abstraction carries useful meaning.

Image already provides the underlying image behavior. Avatar adds a common semantic pattern: a circular image representing identity.

That makes the abstraction useful without making it complicated.

Create. Configure. Compose. Extend with ordinary Rust.

The framework provides the primitive. Your application provides the identity.

Icons

Live Demo

Open the demo in a separate tab.

Beverly includes the fabulous Feather icons: a clean, open-source set of outline icons designed by Cole Bemis and the Feather contributors. Feather is distributed under the MIT license.

The bundled icons are SVG vector assets, not bitmap images or an icon font. They scale cleanly and can be recolored and animated. Beverly embeds them at compile time, so applications do not need to copy an icon assets folder.

Basic Usage

BeverlyPlugin installs the icon system. Import IconCommands to spawn icons inside a UI parent:

#![allow(unused)]
fn main() {
use beverly::icons::IconCommands;
use bevy::prelude::*;

fn add_icons(parent: &mut ChildSpawnerCommands) {
    parent.spawn_feather("coffee");
    parent.spawn_feather_sized("heart", 32.0);
    parent.spawn_feather_muted("info", 20.0);
    parent.spawn_feather_colored("check", 24.0, Color::srgb(0.2, 0.7, 0.4));
}
}

Names match the bundled SVG filenames without .svg, such as arrow-left, check-circle, and alert-triangle. The default size is 24 pixels.

The regular and sized helpers follow the theme’s text color; muted helpers follow its muted text color. Explicitly colored icons retain their supplied color when the theme changes.

Light/Dark Circle

The additional theme-toggle SVG is Beverly’s shadcn/ui-style light/dark circle icon, used by the page’s theme-switch button. It is bundled alongside Feather icons but is not part of the original Feather set. shadcn/ui is the styling reference, not a separate SVG icon pack.

#![allow(unused)]
fn main() {
use beverly::icons::IconCommands;
use bevy::prelude::*;

fn add_theme_icon(parent: &mut ChildSpawnerCommands) {
    parent.spawn_feather_sized("theme-toggle", 24.0);
}
}

This spawns the visual icon only. To make it switch the theme, use the Theme Toggle component or wire toggle_theme to your own button.

Button Icons

ButtonChild::icon uses the same embedded icon names:

#![allow(unused)]
fn main() {
use beverly::components::button::{BeverlyButton, ButtonChild};
use bevy::prelude::*;

fn add_save_button(parent: &mut ChildSpawnerCommands) {
    parent.spawn(
        BeverlyButton::standard("Save")
            .children([
                ButtonChild::icon("save"),
                ButtonChild::text("Save"),
            ]),
    );
}
}

Give icon-only controls an accessible name through the owning control’s semantics. A decorative icon does not replace a button’s accessible label.

Animation

SVG icons are animatable through Beverly’s Bevy components. For example, the loader icon automatically spins, and its decorative rotation stops when reduced motion is enabled:

#![allow(unused)]
fn main() {
use beverly::icons::IconCommands;
use bevy::prelude::*;

fn add_loading_icon(parent: &mut ChildSpawnerCommands) {
    parent.spawn_feather_sized("loader", 24.0);
}
}

For a custom size animation, update IconNode::size and the UI slot’s dimensions together:

#![allow(unused)]
fn main() {
use beverly::icons::{IconCommands, IconNode};
use beverly::theme::AccessibilityVisualPolicyResource;
use bevy::prelude::*;

#[derive(Component)]
struct PulsingIcon;

fn add_pulsing_icon(parent: &mut ChildSpawnerCommands) {
    let icon = parent.spawn_feather_sized("heart", 24.0);
    parent.commands().entity(icon).insert(PulsingIcon);
}

fn pulse_icons(
    time: Res<Time>,
    policy: Res<AccessibilityVisualPolicyResource>,
    mut icons: Query<(&mut IconNode, &mut Node), With<PulsingIcon>>,
) {
    let size = if policy.current.reduced_motion {
        24.0
    } else {
        24.0 + 2.0 * time.elapsed_secs().sin()
    };
    for (mut icon, mut node) in &mut icons {
        icon.size = size;
        node.width = Val::Px(size);
        node.height = Val::Px(size);
    }
}
}

Register pulse_icons in Update. Reserve a stable outer slot if the changing size should not move neighboring content. SVG rendering is handled by bevy_svg; arbitrary SVG/CSS animation declarations are not executed by the icon system.

Gallery

The icon gallery includes every bundled icon, including the light/dark circle, with names and the shared theme toggle:

cargo run --example icons
cargo run --example icons -- dark

Browse the original Feather catalog for designs and names, and the Feather repository for upstream SVGs and attribution.

Navigation

Beverly provides explicit Page, Layout, and Link primitives for in-app routing, alongside reusable navigation surfaces such as Navbar, Sidebar, and NavButton.

See Pages, Links, and Layouts for route registration and page outlets. The Navigation Guide covers navigation surfaces, app-owned NavButton state, and page transitions.

Pages, Links, and Layouts

Beverly keeps route architecture explicit while letting each page and layout remain an ordinary composable UI tree.

• A Page names a route and its content.
• A Layout describes the reusable shell around a page.
• A Link points to a route pattern.

Register Pages

Return pages from named functions and register them together on the root Ui:

#![allow(unused)]
fn main() {
use beverly::prelude::*;

fn application_ui() -> Ui {
    ui().pages([
        home_page(),
        users_page(),
        user_page(),
    ])
}

fn home_page() -> Page {
    page()
        .route("/")
        .layout(app_layout())
        .children([text("Home")])
}

fn users_page() -> Page {
    page()
        .route("/users")
        .layout(app_layout())
        .children([text("User list")])
}

fn user_page() -> Page {
    page()
        .route("/users/:id")
        .layout(app_layout())
        .children([text("User profile")])
}
}

The first registered route matching / is shown at startup. If no root route exists, Beverly starts with the first registered page. Route patterns match path segments exactly; a segment beginning with : captures one value.

Compose a Layout

Layouts use the same composable elements as pages. page_outlet() marks the location where the active page’s content is rendered:

#![allow(unused)]
fn main() {
fn app_layout() -> Layout {
    layout().children([
        text("Application header"),
        row()
            .gap(Val::Px(16.0))
            .children([
                text("Sidebar"),
                page_outlet(),
            ]),
        text("Application footer"),
    ])
}
}

A page without .layout(...) renders directly in the route surface. Pages using the same layout share its shell; changing the layout does not change their routes or content.

Navigate with Links

The visible string passed to link() is its label. Accessibility description and destination are separate:

#![allow(unused)]
fn main() {
fn user_link(user_id: u64) -> UiElement {
    link("View user")
        .aria("Opens this user's profile")
        .to("/users/:id")
        .params([("id", user_id)])
}
}

When activated, a link with a target navigates only if the resolved path matches a registered page. A link without .to(...) still emits LinkClicked and can be handled by application code. Disabled links do not activate.

Query strings can be included in the target and are retained when path parameters are substituted:

#![allow(unused)]
fn main() {
link("View activity")
    .aria("Opens this user's activity")
    .to("/users/:id?tab=activity&search=red+fox")
    .params([("id", user_id)])
}

The current path, path parameters, and parsed query are available globally through Res<RouteState>. Beverly also attaches a RouteContext component to every entity in the active page subtree, including layout elements, page content, and descendants created later. Component systems can read it with Query<&RouteContext>; custom context-aware builders can read the same snapshot through UiBuildContext::route_context() while constructing their entity.

#![allow(unused)]
fn main() {
fn inspect_route(route: Res<RouteState>) {
    info!("path: {}, id: {:?}, tab: {:?}", route.path, route.params.get("id"), route.query.get("tab"));
}

fn inspect_routed_widget(contexts: Query<&RouteContext>) {
    for context in &contexts {
        info!("id: {:?}, tab: {:?}", context.param("id"), context.query_value("tab"));
    }
}
}

RouteContext exposes path, params, and query maps, with param(name) and query_value(name) convenience accessors. Query keys and values are form-decoded (+ becomes a space); repeated query keys retain the last value. The same snapshot can be read during fluent construction:

#![allow(unused)]
fn main() {
fn user_header(context: &mut UiBuildContext<'_>) -> Entity {
    let user_id = context
        .route_context()
        .and_then(|route| route.param("id").map(str::to_owned))
        .unwrap_or_default();
    context.world.spawn((Text::new(format!("User {user_id}")), ChildOf(context.parent))).id()
}
}

Routing is internal to the Bevy application and does not synchronize a browser URL. Applications that need custom state transitions can continue to use NavButton and handle its interaction in their own systems.

Navigation

Beverly supports two complementary navigation styles. Page, Layout, and routed Link provide a small route registry for applications that want named pages and reusable shells. NavButton remains an app-owned interaction primitive for applications that manage page state themselves.

The navigation pieces are:

• Navbar and NavbarSections for a three-section top bar.
• Sidebar and SidebarState for a collapsible side navigation surface.
• NavButton and PageId for page buttons used by the sidebar.

Use Page and Layout for explicit routes. Use NavButton when the application owns page state.

Routed Pages

For the built-in route registry and page outlet API, see Pages, Links, and Layouts. Pages are registered explicitly with ui().pages([...]); dynamic path segments use :name, and links can navigate to a matching route.

RouteState exposes the active path, captured path parameters, and parsed query map as a resource. Each entity in the active page subtree also has a RouteContext component, queryable by child systems; context-aware builders can read it through UiBuildContext::route_context(). Query values are form-decoded. Routing is internal and does not synchronize with a browser address bar.

Navigation Flow

nav_button(...) creates a Bevy Button with a NavButton { page } component. When the user clicks or activates it, Bevy changes the button’s Interaction. A system can observe that change and route to the selected page:

Pointer or keyboard activation
    ↓
Interaction becomes Pressed
    ↓
Query matches Changed<Interaction> + NavButton
    ↓
Application selects NavButton.page

This is an interaction-triggered system, not a Beverly navigation message. The NavButton does not publish a custom Bevy Message, change a Bevy State, or spawn page content for you.

#![allow(unused)]
fn main() {
use bevy::prelude::*;
use beverly::components::nav_button::{NavButton, PageId};

#[derive(States, Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
enum AppPage {
    #[default]
    Music,
    Settings,
}

fn route_from_nav_button(
    buttons: Query<(&Interaction, &NavButton), Changed<Interaction>>,
    mut next_page: ResMut<NextState<AppPage>>,
) {
    for (interaction, button) in &buttons {
        if *interaction == Interaction::Pressed {
            let page = match button.page {
                PageId::Settings => AppPage::Settings,
                _ => AppPage::Music,
            };
            next_page.set(page);
        }
    }
}
}

Register the app state and handler in your own plugin. BeverlyPlugin installs the visual and sidebar systems; the application still decides what each PageId means.

Sidebar

spawn_sidebar builds a sidebar with a drawer toggle and buttons for PageId::all(). It takes a parent child-spawner, the UiFonts resource, and a top offset in pixels:

#![allow(unused)]
fn main() {
use bevy::prelude::*;
use beverly::components::sidebar::spawn_sidebar;
use beverly::primitives::root::UiFonts;

fn build_sidebar(parent: &mut ChildSpawnerCommands, ui_fonts: &UiFonts) {
    spawn_sidebar(parent, ui_fonts, 64.0);
}
}

The offset is useful when the sidebar sits below a fixed top bar. SidebarPlugin, included by BeverlyPlugin, initializes SidebarState, handles the drawer toggle, animates the sidebar width, and updates its theme colors.

SidebarState is a resource with a public open: bool field. It defaults to open. The built-in drawer button toggles this value; the sidebar system animates between expanded and collapsed widths and hides text labels in the collapsed layout.

Page Buttons

nav_button(parent, page, ui_fonts) creates one sidebar button. drawer_toggle(parent, ui_fonts) creates the Menu control that toggles SidebarState:

#![allow(unused)]
fn main() {
use bevy::prelude::*;
use beverly::components::nav_button::{PageId, drawer_toggle, nav_button};
use beverly::primitives::root::UiFonts;

fn add_custom_sidebar_items(parent: &mut ChildSpawnerCommands, ui_fonts: &UiFonts) {
    drawer_toggle(parent, ui_fonts);
    nav_button(parent, PageId::Settings, ui_fonts);
}
}

PageId is the page metadata carried by a navigation button. Its methods are:

• PageId::all() returns the seven pages used in the default sidebar. PlaylistDetail is intentionally not in that list, but can still be used to create a button directly.
• page.label() returns the display label.
• page.body() returns sample descriptive text for that page.
• page.icon() returns the associated Feather icon.
• page.accent() returns the page’s example accent color.

The default button list is only a starting point. To render a custom set or order, call nav_button for the PageId values your app wants to show.

Navbar

spawn_navbar(commands, fixed) creates a full-width, three-column navbar and returns its entity. It also inserts NavbarSections on that entity, containing the child entity IDs for the left, center, and right sections.

#![allow(unused)]
fn main() {
use bevy::prelude::*;
use beverly::components::navbar::{
    NavbarSections, add_to_center, add_to_left, add_to_right, spawn_navbar,
};

fn build_top_bar(mut commands: Commands) {
    spawn_navbar(&mut commands, true);
}

fn fill_top_bar(
    mut commands: Commands,
    new_navbars: Query<&NavbarSections, Added<NavbarSections>>,
) {
    for sections in &new_navbars {
        add_to_left(&mut commands, sections, text("Workspace"));
        add_to_center(&mut commands, sections, text("Library"));
        add_to_right(&mut commands, sections, text("Account"));
    }
}
}

Run build_top_bar during Startup and fill_top_bar during Update. The section query runs after the navbar and its children have been created, and Added<NavbarSections> prevents adding the sample content repeatedly.

Use true for a fixed navbar positioned at the top of its parent, or false for a relative navbar in normal layout flow. NavbarPlugin, included by BeverlyPlugin, applies that positioning when the Navbar component changes.

The Navbar builder methods are:

• Navbar::new() creates a non-fixed navbar.
• .fixed(bool) sets whether the navbar uses fixed positioning.

NavbarBundle::new(fixed) constructs the navbar bundle directly. Most applications should use spawn_navbar, which also creates the three section entities and records their IDs.

The section helpers all take &mut Commands, &NavbarSections, and any Bevy Bundle; each returns the spawned child entity:

• add_to_left(...) places a bundle in the left section.
• add_to_center(...) places a bundle in the center section.
• add_to_right(...) places a bundle in the right section.

Enter and Exit Transitions

Page transitions belong to your page lifecycle, not to NavButton. Beverly’s UiAnimationPlugin (installed by BeverlyPlugin) can animate a page root with TransformTransitionTarget. For a Bevy UI Node, the target’s X/Y translation is measured in logical pixels.

Start an entering page slightly offset, then target its resting transform:

#![allow(unused)]
fn main() {
use std::time::Duration;
use bevy::prelude::*;
use beverly::animation::animation::{Easing, TransformTransitionTarget, Transition};

fn spawn_page(commands: &mut Commands) -> Entity {
    let transition = Transition::new(Duration::from_millis(220), Easing::EaseOut);

    commands
        .spawn((
            Node::default(),
            UiTransform::from_translation(Val2::px(24.0, 0.0)),
            TransformTransitionTarget::new(Transform::IDENTITY, transition),
        ))
        .id()
}
}

For an exit, set the current page root’s target to a small offset and let the animation run:

#![allow(unused)]
fn main() {
fn begin_page_exit(commands: &mut Commands, page_root: Entity) {
    let transition = Transition::new(Duration::from_millis(180), Easing::EaseIn);

    commands.entity(page_root).insert(TransformTransitionTarget::new(
        Transform::from_translation(Vec3::new(-24.0, 0.0, 0.0)),
        transition,
    ));
}
}

Do not despawn the outgoing root immediately when starting its exit animation. Keep it mounted until the transition duration has elapsed, then remove it and finish the route change. A common lifecycle is to mark the old page as exiting, start its target animation, and let a timer or page-transition coordinator despawn it after the transition. Spawn the new page with its own entering target. When using Bevy OnExit systems, avoid automatic immediate despawn of an entity that still needs to animate.

Transitions are decorative by default, so Beverly’s reduced-motion policy can make them immediate. Keep page identity and focus behavior correct without relying on the motion to communicate the route change.

Accessibility

Use clear page labels, preserve a logical keyboard order, and make the current route visually apparent in your app’s page-button styling. Navigation controls are actions for changing context, so the application should also move focus to an appropriate location when a new page is shown. Keep the route change understandable when motion is disabled.

Navbar

Live Demo

Open the demo in a separate tab.

A Navbar is a horizontal layout primitive for organizing content across the top or edge of an interface.

It provides three named sections:

• left
• center
• right

The center section is always centered within the Navbar. The left and right sections work inward from their respective edges.

The Navbar can also contain arbitrary children(), making it useful for simple layouts as well as more structured application navigation.

The Navbar provides the layout. The application provides the navigation.

Basic Usage

Create a Navbar with navbar() and compose content into its sections:

#![allow(unused)]
fn main() {
navbar()
    .left([
        text("My App"),
    ])
    .center([
        text("Dashboard"),
    ])
    .right([
        text("Account"),
    ])
}

The three sections have predictable spatial behavior:

┌──────────────────────────────────────────────────────────┐
│  LEFT                  CENTER                  RIGHT      │
│  ←───────              ───────              ───────→    │
└──────────────────────────────────────────────────────────┘

The center section remains centered in the Navbar rather than simply appearing after the left section.

This makes the layout predictable even when the left and right sections contain different amounts of content.

Named Sections

The three named sections are semantic conveniences for the most common Navbar layout.

Left

left() places content against the left side of the Navbar.

#![allow(unused)]
fn main() {
navbar()
    .left([
        button().text(localize("navigation.menu")),

        text("My App"),
    ])
}

The left section grows inward from the edge toward the center.

Center

center() places content in the center of the Navbar.

#![allow(unused)]
fn main() {
navbar()
    .center([
        text("Dashboard"),
    ])
}

The center section is centered relative to the Navbar itself.

It does not simply follow the left section.

This distinction is important when building predictable application layouts.

Right

right() places content against the right side of the Navbar.

#![allow(unused)]
fn main() {
navbar()
    .right([
        button().text(localize("user.profile")),
    ])
}

The right section grows inward from the right edge toward the center.

Using All Three

A common application Navbar might look like this:

#![allow(unused)]
fn main() {
navbar()
    .left([
        button().text(localize("navigation.menu")),

        text("Beverly"),
    ])
    .center([
        text("Dashboard"),
    ])
    .right([
        button().text(localize("user.profile")),
    ])
}

The resulting structure is conceptually:

LEFT CONTENT        CENTER CONTENT        RIGHT CONTENT
     →                    ●                    ←

The center remains centered even as the left and right content changes.

Children

children() remains the general composition primitive.

#![allow(unused)]
fn main() {
navbar()
    .children([
        text("Beverly"),
        text("Dashboard"),
    ])
}

This is useful when the application does not need the three-section layout.

Named sections are conveniences, not a replacement for children().

A Navbar can therefore be used as either a simple container:

#![allow(unused)]
fn main() {
navbar()
    .children([
        text("My Application"),
    ])
}

or as a structured three-section layout:

#![allow(unused)]
fn main() {
navbar()
    .left(text("Beverly"))
    .center(text("Dashboard"))
    .right(text("Account"))
}

A section can accept one child or many children.

#![allow(unused)]
fn main() {
navbar()
    .left(text("Beverly"))
}

#![allow(unused)]
fn main() {
navbar()
    .left([
        icon("menu"),
        text("Beverly"),
    ])
}

children() is the general primitive. Named sections add useful semantics.

Fixed and Non-Fixed Navbars

A Navbar can either participate in normal layout flow or remain fixed relative to its containing interface.

For a normal Navbar:

#![allow(unused)]
fn main() {
navbar()
    .left(text("Beverly"))
    .center(text("Dashboard"))
    .right(text("Account"))
}

For a fixed Navbar:

#![allow(unused)]
fn main() {
navbar()
    .fixed(true)
    .left(text("Beverly"))
    .center(text("Dashboard"))
    .right(text("Account"))
}

A fixed Navbar remains positioned according to the application’s layout rules rather than moving with ordinary content flow.

The Navbar itself does not decide whether an application should use fixed positioning. It simply provides the layout option.

Styling

Navbar uses the same fluent styling model as other Beverly components.

#![allow(unused)]
fn main() {
navbar()
    .padding(16)
    .height(64)
    .radius(12)
    .left(text("Beverly"))
    .center(text("Dashboard"))
    .right(text("Account"))
}

Layout and presentation remain separate from application behavior.

The Navbar determines where content goes. Its children determine what that content is.

Navigation

Despite its name, the Navbar does not own application navigation.

Navigation is application behavior.

A navigation control can emit a UI Event or connect directly to an application Command:

#![allow(unused)]
fn main() {
navbar()
    .left([
        button().text(localize("navigation.home"))
            .on("click", Command::Navigation::Home),

        button().text(localize("navigation.settings"))
            .on("click", Command::Navigation::Settings),
    ])
}

The Navbar does not need to know what Command::Navigation::Home does.

It only provides the surface in which the controls are arranged.

The Navbar provides the layout. Buttons provide the interaction. Commands provide the application behavior.

Responsive Content

Because the Navbar is composed from ordinary components, its contents can be data-driven.

#![allow(unused)]
fn main() {
navbar()
    .left(navigation_menu())
    .center(text(page.title()))
    .right(user_actions())
}

Higher-level pieces are ordinary Rust functions:

#![allow(unused)]
fn main() {
fn user_actions() -> impl Component {
    row()
        .children([
            button().text(localize("user.notifications")),

            avatar()
                .src(user.avatar_url())
                .aria(localize("user.avatar.description")),
        ])
}
}

There is no separate Navbar component language.

Higher-level components are ordinary Rust functions that return lower-level components.

Accessibility

The Navbar is a layout primitive. Its children remain responsible for their own interaction semantics.

Interactive elements inside the Navbar should have their own accessible labels and descriptions:

#![allow(unused)]
fn main() {
navbar()
    .left([
        button().text(localize("navigation.menu")),
    ])
    .center([
        text("Dashboard"),
    ])
}

The Navbar itself can also expose accessible semantics when the application needs the navigation surface to be identified:

#![allow(unused)]
fn main() {
navbar()
    .label(localize("navigation.primary.label"))
    .aria(localize("navigation.primary.description"))
    .left([
        text("Beverly"),
    ])
    .center([
        text("Dashboard"),
    ])
}

The exact semantic role belongs to the Navbar’s implementation and context; applications should not need to manually reproduce the underlying layout or accessibility mechanics.

Accessible by construction, not accessible by cleanup.

What Navbar Does Not Do

Navbar does not:

• own navigation state
• decide which page is active
• manage routing
• own application data
• define authentication
• define user permissions
• replace Buttons or Links
• require a separate navigation state system

Those concerns belong to the application.

The Navbar is responsible for organizing interface content.

Design Principle

The Navbar deliberately provides only the structure that is difficult to express consistently by hand:

• content from the left edge
• content from the center
• content from the right edge
• predictable centered positioning
• optional fixed positioning
• general children() composition

Everything else remains ordinary Beverly composition and ordinary Rust.

Three sections when you need them. children() when you don’t.

The center stays centered. The edges work inward. The application owns the meaning.

Sidebar

Live Demo

Open the demo in a separate tab.

Header, Body, and Footer

Use UiElement::sidebar(top_offset_px) for the concrete fluent Sidebar API:

#![allow(unused)]
fn main() {
UiElement::sidebar(0.0)
    .header(text("Workspace"))
    .body(text("Navigation details"))
    .footer(text("Signed in locally"))
}

.header(...), .body(...), and .footer(...) place content at the top, middle, and bottom of the Sidebar panel, regardless of builder-call order. Each accepts a single element or an iterable; repeated calls append content. The existing drawer toggle and navigation buttons remain inside the body, before custom body content. The body grows into available height, keeping the footer at the bottom. ContentSection markers identify each region. Supply the UiFonts resource when building a Sidebar in a custom application.

A Sidebar is a layout primitive for organizing content along the side of an interface.

A Sidebar can be positioned on either the left or right side of its containing layout.

Like the Navbar and Footer, it supports general children() composition and does not impose a separate application structure.

The Sidebar provides the layout. The application provides the content and behavior.

Basic Usage

Create a Sidebar with sidebar() and place it on the left:

#![allow(unused)]
fn main() {
sidebar()
    .side(Side::Left)
    .children([
        text("Navigation"),
        text("Dashboard"),
        text("Settings"),
    ])
}

Or place it on the right:

#![allow(unused)]
fn main() {
sidebar()
    .side(Side::Right)
    .children([
        text("Details"),
        text("Properties"),
    ])
}

The side is an explicit configuration choice:

#![allow(unused)]
fn main() {
sidebar()
    .side(Side::Left)
}

#![allow(unused)]
fn main() {
sidebar()
    .side(Side::Right)
}

One component. Two sides. Explicit configuration.

Children

children() is the fundamental composition primitive.

#![allow(unused)]
fn main() {
sidebar()
    .side(Side::Left)
    .children([
        text("Dashboard"),
        text("Projects"),
        text("Settings"),
    ])
}

A Sidebar can contain one child or many:

#![allow(unused)]
fn main() {
sidebar()
    .side(Side::Left)
    .children(text("Navigation"))
}

#![allow(unused)]
fn main() {
sidebar()
    .side(Side::Left)
    .children([
        icon("home"),
        text("Dashboard"),
        text("Projects"),
        text("Settings"),
    ])
}

There is no special Sidebar composition system.

children() is the general primitive.

Left and Right Positioning

The Sidebar works from the edge of the containing layout inward.

A left Sidebar:

┌──────────────┬──────────────────────────────────────────┐
│              │                                          │
│   SIDEBAR    │              MAIN CONTENT                │
│     ←        │                                          │
│              │                                          │
└──────────────┴──────────────────────────────────────────┘

A right Sidebar:

┌──────────────────────────────────────────┬──────────────┐
│                                          │              │
│              MAIN CONTENT                │   SIDEBAR →  │
│                                          │              │
│                                          │              │
└──────────────────────────────────────────┴──────────────┘

The application does not need separate components for these two layouts.

#![allow(unused)]
fn main() {
sidebar()
    .side(Side::Left)
}

and:

#![allow(unused)]
fn main() {
sidebar()
    .side(Side::Right)
}

Fixed and Non-Fixed Sidebars

A Sidebar can either participate in normal layout flow or remain fixed relative to its containing interface.

A normal Sidebar:

#![allow(unused)]
fn main() {
sidebar()
    .side(Side::Left)
    .children(navigation_menu())
}

A fixed Sidebar:

#![allow(unused)]
fn main() {
sidebar()
    .side(Side::Left)
    .fixed(true)
    .children(navigation_menu())
}

The same applies to a right Sidebar:

#![allow(unused)]
fn main() {
sidebar()
    .side(Side::Right)
    .fixed(true)
    .children(details_panel())
}

The Sidebar provides the positioning option. The application decides whether the Sidebar should be fixed.

Styling

Sidebar uses the same fluent styling model as other Beverly components.

#![allow(unused)]
fn main() {
sidebar()
    .side(Side::Left)
    .width(240)
    .padding(16)
    .children(navigation_menu())
}

A right Sidebar can use the same API:

#![allow(unused)]
fn main() {
sidebar()
    .side(Side::Right)
    .width(320)
    .padding(16)
    .children(details_panel())
}

The side does not change the composition model.

Interactive Content

A Sidebar is not inherently interactive.

It commonly contains interactive components such as Buttons or other navigation controls:

#![allow(unused)]
fn main() {
sidebar()
    .side(Side::Left)
    .children([
        button().text(localize("navigation.home"))
            .on("click", Command::Navigation::Home),

        button().text(localize("navigation.settings"))
            .on("click", Command::Navigation::Settings),
    ])
}

The Sidebar does not need to know what those commands mean.

It simply provides the space in which the controls are arranged.

The Sidebar provides the layout. The children provide the interaction. The application provides the behavior.

Data-Driven Sidebars

Sidebar content can come directly from application data:

#![allow(unused)]
fn main() {
sidebar()
    .side(Side::Left)
    .children(
        navigation_items()
    )
}

A higher-level component can be an ordinary Rust function:

#![allow(unused)]
fn main() {
fn navigation_items() -> impl Component {
    column()
        .children([
            navigation_item("Dashboard", Command::Navigation::Dashboard),
            navigation_item("Projects", Command::Navigation::Projects),
            navigation_item("Settings", Command::Navigation::Settings),
        ])
}
}

The Sidebar does not need to know how those items are generated.

Higher-level components are ordinary Rust functions that return lower-level components.

Accessibility

A Sidebar can expose accessible semantics when it represents a meaningful region of the interface:

#![allow(unused)]
fn main() {
sidebar()
    .side(Side::Left)
    .label(localize("navigation.sidebar.label"))
    .aria(localize("navigation.sidebar.description"))
    .children(navigation_menu())
}

Interactive elements inside the Sidebar remain responsible for their own accessible labels and descriptions:

#![allow(unused)]
fn main() {
sidebar()
    .side(Side::Left)
    .children([
        button().text(localize("navigation.home"))
            .on("click", Command::Navigation::Home),
    ])
}

The Sidebar should provide the appropriate structural semantics without requiring the application to manually reproduce the underlying accessibility behavior.

Accessible by construction, not accessible by cleanup.

Sidebar as Navigation

A Sidebar is often used for navigation, but navigation is not its responsibility.

The same Sidebar can contain navigation:

#![allow(unused)]
fn main() {
sidebar()
    .side(Side::Left)
    .children(navigation_menu())
}

or application information:

#![allow(unused)]
fn main() {
sidebar()
    .side(Side::Right)
    .children([
        text("Document Details"),
        text(document.title()),
        badge(document.status()),
    ])
}

or tools:

#![allow(unused)]
fn main() {
sidebar()
    .side(Side::Right)
    .children(tool_panel())
}

The layout primitive stays the same.

A Sidebar does not have to be navigation. It is simply content positioned at the side of an interface.

What Sidebar Does Not Do

Sidebar does not:

• own navigation state
• manage routing
• decide which page is active
• own application data
• define permissions
• define authentication
• require a separate navigation system
• dictate what content belongs inside it

Those concerns belong to the application.

The Sidebar is responsible for positioning and composing side content.

Design Principle

The Sidebar deliberately provides only the structure applications repeatedly need:

• left or right positioning
• predictable edge alignment
• optional fixed positioning
• general children() composition
• fluent styling

Everything else remains ordinary Beverly composition and ordinary Rust.

Left or right when you need it. children() when you don’t need anything more.

The Sidebar provides the space. The application gives the space meaning.

Footer

Live Demo

Open the demo in a separate tab.

The standalone Footer component is created with footer(...). This is different from the .footer(...) content-section helper available on Card, Container, Form, Modal, Alert, Toast, Tabs, and Sidebar fluent elements.

#![allow(unused)]
fn main() {
app()
    .children([footer(false, FooterConfig::default())])
    .run();
}

A Footer is a layout primitive for organizing content along the bottom of an interface.

It follows the same composition model as the Navbar, providing three named sections:

• left
• center
• right

The center section is always centered within the Footer. The left and right sections work inward from their respective edges.

The Footer can also contain arbitrary children(), making it useful for simple layouts as well as structured application footers.

The Footer provides the layout. The application provides the content.

Basic Usage

Create a Footer with footer() and compose content into its sections:

#![allow(unused)]
fn main() {
footer()
    .left([
        text("© 2026 Beverly"),
    ])
    .center([
        text("Built with Rust"),
    ])
    .right([
        text("v1.0.0"),
    ])
}

The three sections have predictable spatial behavior:

┌──────────────────────────────────────────────────────────┐
│  LEFT                  CENTER                  RIGHT      │
│  ←───────              ───────              ───────→    │
└──────────────────────────────────────────────────────────┘

The center remains centered relative to the Footer rather than simply appearing after the left section.

Named Sections

The three named sections are semantic conveniences for common Footer layouts.

Left

left() places content against the left side of the Footer.

#![allow(unused)]
fn main() {
footer()
    .left([
        text("© 2026 Beverly"),
        text("All rights reserved"),
    ])
}

The left section grows inward from the edge toward the center.

Center

center() places content in the center of the Footer.

#![allow(unused)]
fn main() {
footer()
    .center([
        text("Built with Rust"),
    ])
}

The center section is centered relative to the Footer itself.

It does not simply follow the left section.

Right

right() places content against the right side of the Footer.

#![allow(unused)]
fn main() {
footer()
    .right([
        button().text(localize("footer.settings")),
    ])
}

The right section grows inward from the right edge toward the center.

Using All Three

A typical application Footer might look like this:

#![allow(unused)]
fn main() {
footer()
    .left([
        text("© 2026 Beverly"),
    ])
    .center([
        text("Privacy"),
        text("Terms"),
    ])
    .right([
        text("v1.0.0"),
    ])
}

The center remains centered even when the left and right sections contain different amounts of content.

This makes Footer layouts predictable without requiring application-specific positioning logic.

Children

children() remains the general composition primitive.

#![allow(unused)]
fn main() {
footer()
    .children([
        text("© 2026 Beverly"),
        text("All rights reserved"),
    ])
}

This is useful when the application does not need the three-section layout.

Named sections are conveniences, not a replacement for children().

A Footer can therefore be used as a simple container:

#![allow(unused)]
fn main() {
footer()
    .children([
        text("© 2026 Beverly"),
    ])
}

or as a structured three-section layout:

#![allow(unused)]
fn main() {
footer()
    .left(text("© 2026 Beverly"))
    .center(text("Privacy"))
    .right(text("v1.0.0"))
}

A section can accept one child or many children:

#![allow(unused)]
fn main() {
footer()
    .left(text("Beverly"))
}

#![allow(unused)]
fn main() {
footer()
    .left([
        icon("copyright"),
        text("2026 Beverly"),
    ])
}

children() is the general primitive. Named sections add useful semantics.

Fixed and Non-Fixed Footers

A Footer can either participate in normal layout flow or remain fixed relative to its containing interface.

For a normal Footer:

#![allow(unused)]
fn main() {
footer()
    .left(text("© 2026 Beverly"))
    .center(text("Privacy"))
    .right(text("v1.0.0"))
}

For a fixed Footer:

#![allow(unused)]
fn main() {
footer()
    .fixed(true)
    .left(text("© 2026 Beverly"))
    .center(text("Privacy"))
    .right(text("v1.0.0"))
}

A fixed Footer remains positioned according to the application’s layout rules rather than moving with ordinary content flow.

The Footer does not decide whether fixed positioning is appropriate. It simply provides the option.

Styling

Footer uses the same fluent styling model as other Beverly components.

#![allow(unused)]
fn main() {
footer()
    .padding(16)
    .height(64)
    .radius(12)
    .left(text("© 2026 Beverly"))
    .center(text("Privacy"))
    .right(text("v1.0.0"))
}

Layout and presentation remain separate from application behavior.

The Footer determines where content goes. Its children determine what that content is.

Interactive Content

A Footer is not inherently interactive.

It can contain Buttons and other interactive components when the application needs them:

#![allow(unused)]
fn main() {
footer()
    .left([
        text("© 2026 Beverly"),
    ])
    .right([
        button().text(localize("footer.settings"))
            .on("click", Command::Settings::Open),
    ])
}

The Footer does not need to know what the Command does.

It simply provides the layout in which the control appears.

The Footer provides the layout. The children provide the interaction. The application provides the behavior.

Data-Driven Footers

Footer content can come directly from application data:

#![allow(unused)]
fn main() {
footer()
    .left(text(app.copyright()))
    .center(footer_links())
    .right(text(app.version()))
}

Higher-level pieces remain ordinary Rust functions:

#![allow(unused)]
fn main() {
fn footer_links() -> impl Component {
    row()
        .children([
            button().text(localize("footer.privacy"))
                .on("click", Command::Navigation::Privacy),

            button().text(localize("footer.terms"))
                .on("click", Command::Navigation::Terms),
        ])
}
}

There is no separate Footer component language.

Higher-level components are ordinary Rust functions that return lower-level components.

Accessibility

The Footer is primarily a layout primitive. Interactive elements inside it remain responsible for their own accessible semantics.

#![allow(unused)]
fn main() {
footer()
    .left([
        text("© 2026 Beverly"),
    ])
    .right([
        button().text(localize("footer.settings")),
    ])
}

The Footer can also expose accessible semantics when the application needs the footer region to be identified:

#![allow(unused)]
fn main() {
footer()
    .label(localize("footer.label"))
    .aria(localize("footer.description"))
    .left([
        text("© 2026 Beverly"),
    ])
    .center([
        text("Privacy"),
    ])
    .right([
        text("v1.0.0"),
    ])
}

The underlying semantic and layout behavior should be handled by Beverly rather than requiring developers to manually reproduce it.

Accessible by construction, not accessible by cleanup.

What Footer Does Not Do

Footer does not:

• own application state
• manage navigation state
• manage routing
• own application data
• define permissions
• define authentication
• require a separate layout system
• determine what footer content means

Those concerns belong to the application.

The Footer is responsible for organizing interface content.

Navbar and Footer

Navbar and Footer intentionally share the same basic layout vocabulary.

Both provide:

• children()
• left()
• center()
• right()
• predictable centered positioning
• optional fixed positioning
• fluent styling
• ordinary Rust composition

The difference is semantic placement, not architectural complexity.

Same composition model. Different place in the interface.

Design Principle

The Footer deliberately provides only the structure that applications repeatedly need:

• content from the left edge
• content from the center
• content from the right edge
• predictable centered positioning
• optional fixed positioning
• general children() composition

Everything else remains ordinary Beverly composition and ordinary Rust.

Three sections when you need them. children() when you don’t.

The center stays centered. The edges work inward. The application owns the meaning.

Feedback

Alert

Live Demo

Open the demo in a separate tab.

Header, Body, and Footer

UiElement::alert(...) supports top, middle, and bottom content regions:

#![allow(unused)]
fn main() {
UiElement::alert(Alert::warning("Storage is almost full"))
    .header(text("Workspace storage"))
    .body(text("Remove unused files before uploading more."))
    .footer(button().text("Review files"))
}

.header(...), .body(...), and .footer(...) each accept one element or an iterable; repeated calls append content. They render in that order in the alert’s content column, regardless of builder-call order. Custom header content precedes the built-in title/message, body content follows the message, and footer actions appear last. The variant icon, accessible message, timer, and dismiss control retain their existing behavior.

An Alert is a pre-styled Card used to communicate information to the user.

Alerts follow the familiar contextual pattern popularized by Bootstrap: a common surface with a predefined visual treatment for different kinds of information, such as success, warning, error, and informational messages.

Under the hood, an Alert is simply a Card with a predefined look and feel. It does not introduce a new layout system, state-management system, or application architecture.

The type is provided when the Alert is created:

#![allow(unused)]
fn main() {
alert(AlertType::Success)
}

This makes the semantic purpose of the component immediately visible in the code.

An Alert is a Card with an opinionated presentation.

Basic Alert

The simplest Alert presents a message:

#![allow(unused)]
fn main() {
alert(AlertType::Info)
    .children(
        text(localize("user.profile_updated"))
    )
}

The Alert provides the visual treatment. The content provides the meaning.

A more complete Alert might contain an icon and text:

#![allow(unused)]
fn main() {
alert(AlertType::Info)
    .children([
        icon("info"),
        text(localize("user.profile_description")),
    ])
}

The Alert does not need to understand what the message means. It simply presents its children using the visual language associated with the selected Alert type.

Alert Types

The Alert type is the first parameter because it is fundamental to what the component represents.

#![allow(unused)]
fn main() {
alert(AlertType::Info)
    .children(text(localize("user.profile_updated")))
}

#![allow(unused)]
fn main() {
alert(AlertType::Success)
    .children(text(localize("user.created")))
}

#![allow(unused)]
fn main() {
alert(AlertType::Warning)
    .children(text(localize("user.unsaved_changes")))
}

#![allow(unused)]
fn main() {
alert(AlertType::Error)
    .children(text(localize("user.create_failed")))
}

The type determines the predefined presentation. It does not determine application state.

Conceptually:

Alert Type
    ↓
Visual Treatment
    ↓
Alert Content

The application chooses AlertType::Error because it wants to present something as an error. The Alert does not create or detect that error.

The type describes the presentation. The application owns the meaning.

Why the Type Is a Parameter

The Alert type is not merely a style modifier.

Compare:

#![allow(unused)]
fn main() {
alert(AlertType::Success)
}

with:

#![allow(unused)]
fn main() {
alert()
    .success()
}

The first form makes the semantic variant part of the component’s construction. You can understand the component by reading its first argument.

That makes the API particularly useful for AI-generated code:

#![allow(unused)]
fn main() {
alert(AlertType::Warning)
}

immediately communicates:

This is a warning Alert.

There is no need to inspect later configuration to discover the Alert’s primary semantic variant.

The remaining chained methods configure the Alert itself:

#![allow(unused)]
fn main() {
alert(AlertType::Warning)
    .padding(16)
    .children(...)
}

This follows a useful Beverly convention:

Construction establishes what something is. Configuration establishes how it behaves or looks.

Alerts Are Cards

An Alert is built on the Card primitive.

A general Card might look like:

#![allow(unused)]
fn main() {
card()
    .padding(16)
    .radius(12)
    .children([
        icon("info"),
        text(localize("user.profile_updated")),
    ])
}

An Alert provides the same fundamental container behavior with a predefined semantic presentation:

#![allow(unused)]
fn main() {
alert(AlertType::Info)
    .children([
        icon("info"),
        text(localize("user.profile_updated")),
    ])
}

The Alert saves the application from repeatedly defining the same visual recipe.

Instead of every part of an application independently deciding how an informational message should look, the design system establishes that convention once.

The implementation can remain simple because the Alert does not need to become a new UI framework. It is a specialized presentation of an existing primitive.

If it is fundamentally a Card, make it a Card. Give it a name when the name carries useful meaning.

Composition

Alerts use children() just like Cards.

A single child:

#![allow(unused)]
fn main() {
alert(AlertType::Success)
    .children(
        text(localize("user.saved"))
    )
}

Multiple children:

#![allow(unused)]
fn main() {
alert(AlertType::Success)
    .children([
        icon("check"),
        text(localize("user.saved")),
        badge(localize("user.synced")),
    ])
}

More complex content can be composed normally:

#![allow(unused)]
fn main() {
alert(AlertType::Warning)
    .children([
        text(localize("user.unsaved_changes")),

        button().text(localize("user.save"))
            .on("click", Command::User::Save),
    ])
}

The Alert does not need special APIs for every possible message layout.

It provides the visual container and the predefined treatment. children() provides composition.

Styling

Alerts have a predefined visual identity, but they remain Beverly components and can participate in normal styling.

#![allow(unused)]
fn main() {
alert(AlertType::Success)
    .padding(16)
    .radius(12)
    .children([
        icon("check"),
        text(localize("user.saved")),
    ])
}

The Alert type establishes its default visual treatment. Additional styling can refine the component where appropriate.

This keeps the API expressive without forcing developers to manually reproduce the Alert design.

#![allow(unused)]
fn main() {
alert(AlertType::Error)
}

is enough to get the application’s standard error presentation.

The developer does not need to know which colors, borders, spacing, typography, or icon treatment make up that presentation.

Declare the meaning. Let the component provide the convention.

Accessibility

An Alert communicates information, so its accessible semantics should be explicit.

#![allow(unused)]
fn main() {
alert(AlertType::Error)
    .label(localize("user.create_status.label"))
    .aria(localize("user.create_status.description"))
    .children([
        icon("error"),
        text(localize("user.create_failed")),
    ])
}

The Alert’s accessibility metadata describes the communication surface itself.

Its children retain their own accessibility requirements. An interactive Button inside an Alert still declares its own label and ARIA description:

#![allow(unused)]
fn main() {
alert(AlertType::Warning)
    .children([
        text(localize("user.unsaved_changes")),

        button().text(localize("user.save"))
            .on("click", Command::User::Save),
    ])
}

Accessibility therefore remains compositional.

The Alert provides semantics for the message container. Interactive children provide their own semantics.

Color alone should not be relied upon to communicate the meaning of an Alert; the content or accessible semantics should make that meaning available to assistive technology as well. This is also a documented concern in Bootstrap’s Alert guidance.

The visual treatment communicates. The accessible semantics make that communication explicit.

Static Alerts

An Alert does not need to be connected to changing application state.

It can simply communicate information that is always present:

#![allow(unused)]
fn main() {
alert(AlertType::Info)
    .children(
        text(localize("user.profile_public"))
    )
}

The Alert is simply part of the View.

There is no requirement that every Alert represent a changing state.

Data-Driven Alerts

An Alert can also be generated from application state.

#![allow(unused)]
fn main() {
if User::has_error {
    alert(AlertType::Error)
        .children(
            text(User::error_message)
        )
}
}

Or different application conditions can determine which presentation should be used:

#![allow(unused)]
fn main() {
if User::is_saved {
    alert(AlertType::Success)
        .children(text(localize("user.saved")))
} else if User::has_error {
    alert(AlertType::Error)
        .children(text(User::error_message))
} else {
    alert(AlertType::Info)
        .children(text(localize("user.ready")))
}
}

The Alert is still not responsible for deciding which condition is true.

The Model owns the state. The View chooses the appropriate presentation.

Alert Type Is Not Application State

This distinction is important.

Consider:

#![allow(unused)]
fn main() {
alert(AlertType::Error)
    .children(text(User::error_message))
}

The Alert type says:

Present this content using the error treatment.

It does not mean:

Change the application’s state to Error.

The application already knows that an error exists. The View chooses the Alert presentation that communicates that state to the user.

This keeps presentation separate from state management.

Presentation describes state. It does not create state.

Alert Events

An Alert does not inherently represent an interaction.

Unlike a Button, an Alert’s primary responsibility is communication. It does not need to emit an Event merely because it exists.

If an Alert contains an interactive component, that component produces its own UI Events.

#![allow(unused)]
fn main() {
alert(AlertType::Warning)
    .children([
        text(localize("user.unsaved_changes")),

        button().text(localize("user.save"))
            .on("click", Command::User::Save),
    ])
}

The Alert remains a presentation container. The Button handles the interaction.

An Alert communicates. Interactive children interact.

Dismissible Alerts

An Alert can optionally contain a control that allows the user to dismiss it.

The dismissal interaction belongs to the child Button:

#![allow(unused)]
fn main() {
alert(AlertType::Info)
    .children([
        text(localize("user.profile_updated")),

        button().text(localize("user.dismiss"))
            .on("click", Command::Alert::Dismiss),
    ])
}

The Alert does not need to become a notification manager or invent its own dismissal architecture.

The application decides what Command::Alert::Dismiss means and which application state should change.

This is an important difference from frameworks where an Alert component may contain its own imperative dismissal mechanism. Beverly keeps the application state in the application and uses the normal Event → Controller → Model architecture.

Alert State

An Alert can also participate in normal component state presentation.

For example:

#![allow(unused)]
fn main() {
alert(AlertType::Error)
    .hover(|style| style.opacity(0.95))
    .focused(|style| style.outline_width(2).outline_color("#2563eb"))
    .children([
        icon("error"),
        text(User::error_message),
    ])
}

These are presentation states of the component. They do not change what kind of Alert it is.

The type remains:

#![allow(unused)]
fn main() {
AlertType::Error
}

while the component’s visual state can change based on interaction or application state.

This gives us two separate concepts:

Alert Type
    ↓
What kind of message is being presented?

Component State
    ↓
How should the Alert currently appear?

That separation prevents the two concepts from becoming tangled.

Alert and Localization

Alert content should normally come from the application’s localization system.

#![allow(unused)]
fn main() {
alert(AlertType::Success)
    .children(
        text(localize("user.created"))
    )
}

The Alert type itself is not language-specific. It provides the presentation convention.

For dynamic errors:

#![allow(unused)]
fn main() {
alert(AlertType::Error)
    .children(
        text(localize(User::error_key))
    )
}

The Model provides semantic state or error information. Localization provides the appropriate language. The Alert presents it.

The Model returns meaning. The UI presents language.

Alert as a Design-System Primitive

The real value of Alert is consistency.

Without an Alert primitive, different parts of an application might independently implement success messages:

green Card
green banner
green notification
green bordered container

Each implementation could look slightly different.

With an Alert:

#![allow(unused)]
fn main() {
alert(AlertType::Success)
    .children(...)
}

the design system establishes the convention once.

The application gets consistent presentation without requiring every developer or AI agent to reconstruct the design.

This is particularly useful for AI-generated interfaces. An agent does not need to invent a visual treatment every time it needs to communicate success or failure. It can use the existing semantic primitive.

Alert vs. Card

The relationship is deliberately simple.

A Card is general.

An Alert is opinionated.

A Modal adds a temporary interaction boundary.

All three share the same underlying composition philosophy.

Alert vs. Modal

An Alert and Modal can both communicate an error or success state, but they serve different purposes.

An Alert is part of the existing interface:

#![allow(unused)]
fn main() {
alert(AlertType::Error)
    .children(
        text(localize("user.create_failed"))
    )
}

A Modal temporarily places content above the existing interface:

#![allow(unused)]
fn main() {
modal()
    .label(localize("user.create_error.label"))
    .aria(localize("user.create_error.description"))
    .children([
        text(localize("user.create_failed")),
    ])
}

The difference is not the message. It is the interaction surface.

The Alert communicates within the current interface. The Modal establishes a temporary interface context.

Alert Contract

The Alert has a deliberately small conceptual contract:

Create with a type. Compose. Present.

It provides:

• predefined information, success, warning, and error treatments
• Card-based composition
• children() support
• consistent design-system presentation
• accessibility semantics
• optional styling refinement
• optional interactive children