12 KiB
Writing a component
A component is a Rust type on the contract in craft_ui::contract. It supplies its own parts and look; the library runs one show pipeline for it: id, style, sizing, focus, pointer sensing, state, value binding, commands, popups, accessibility, mirroring and the shared test cases. Nothing in a component calls egui's behavioural APIs.
File layout
One file per component in its family module: <family>/<component>.rs, for example choice/radio.rs. The file holds the type, its style, its words (words!) and a stories submodule:
#[cfg(feature = "testing")]
mod stories {
use super::*;
use craft_ui::testing::{StoryData, StoryOutput, story};
#[story(Block, covers = [Default])]
fn block(ui: &mut Ui, _: &mut StoryData) -> StoryOutput {
Block::new(CELL).show(ui).into()
}
}
Tests that need more than the shared cases go in crates/ui/tests/it/<family>/ as #[craft_ui::testing::trial] functions.
A family trial drives frames through Fixture (Fixture::new or Fixture::story, then click, drag, key, by_label, part and the other helpers), the kit's one frame driver. It writes no click or drag helper of its own.
A new crate with components
A crate that holds contract types has its own testing feature, enables it on itself, and runs the suite from one integration binary:
[features]
testing = ["craft-ui/testing"]
[dev-dependencies]
my-crate = { path = ".", features = ["testing"] }
[[test]]
name = "it"
path = "tests/it/main.rs"
harness = false
The crate's testing module calls craft_ui::testing_registered!() once, which writes registered() for the package. The binary's main collects the #[trial] functions and adds suite::trials(env!("CARGO_PKG_NAME"), &my_crate::testing::registered()), as crates/ui/tests/it/main.rs does. The derive writes registrations and stories only under feature = "testing", so release builds carry none.
Shapes
The shape is a fact of the type, set by what the caller supplies:
| Shape | Declare | Caller supplies | Shown with |
|---|---|---|---|
| Leaf | #[derive(Component)] |
nothing | Show::show |
| Container | #[component(container)] and a #[container] ContainerProps field, then impl Container |
a body closure | ShowContainer::show |
| Collection | #[component(collection)] and a CollectionProps field, then impl Collection |
an item source and an item closure | ShowCollection::show |
A type that only assembles components has no pipeline. It is a pattern and implements the Pattern marker trait.
The show traits are sealed. A component never has an inherent show; contract/shadow rejects one.
The type
#[derive(Component, Props)]
pub struct Badge {
#[common]
common: Common,
/// The count shown beside the label.
#[prop]
count: Option<u32>,
/// Working: shown dimmed.
#[prop(flag)]
busy: bool,
}
Commonholds what every component has: label, id, variant, size, enabled, read-only, selected, tooltip. Its setters come fromProps. A component adds noenabled,id_saltortooltipfield of its own (props/*).#[prop]fields become setters. A#[prop]field is not a size in points (f32,Vec2,Px): sizes come from the style, a token step or the content (props/point-size). A number that is not a size, such as an opacity, declares#[prop(quantity = "opacity")].- The derive writes
<Type>StyleKey, the setters and the registration that lets the suite find the type. A type that implementsComponentby hand registers withregister_contract!.
The trait
impl Component for Badge states the type's facts and implements only the hooks it needs:
| Item | Purpose |
|---|---|
const ROLE: Role |
The AccessKit role. |
type Style, fn style(cx, key) |
The look, built from style parts. |
type Output |
What show returns: Response, EditResponse<T>, a collection response. |
fn sense(&self) -> Sense |
The default follows the shape; override to add or remove click, drag and focus. |
fn measure(&mut self, cx: &MeasureCx<'_, Self>) -> Vec2 |
The content size. Padding and minimum size are added by the pipeline. |
fn parts(&mut self, rect, cx: &mut PartsCx<'_, Self>) |
Named sub-rects with PartKey, Sense and HitShape. |
fn paint(&mut self, ui: &mut PaintUi<'_>, cx: &Cx<'_, Self>) |
Content paint through PaintUi and Draw. |
fn content_env(&self, cx, values: &mut AppValues) |
App values set for the body or items. |
fn finish(self, cx: Cx<'_, Self>) -> Self::Output |
The output. |
A component is shown through a parent's show, never by allocating a rect itself: contract/allocate rejects allocate_*, ui.interact and ui.put.
Parts and faces
cx.part(KEY, rect) registers a part. ui.face(KEY, Other::new()) paints another component as the look of a part, so a composite reuses the look of the component it wears. A part that only a pointer reaches states why keyboard users do not need it: .pointer_only("Enter activates the component").
Values
A value component's Output is EditResponse<T>. It binds with Bind<T> and reports through cx.propose, cx.commit and cx.adopt; each gesture ends in one EditEvent::Commit. Components with Input::Editor own their caret through ImeSurface.
Looks
A style is a plain struct deriving ComponentStyle:
#[derive(Clone, Debug, PartialEq, ComponentStyle)]
pub struct BadgeStyle {
#[style(metrics)]
metrics: Metrics,
}
#[style(metrics)] marks the Metrics field (padding, minimum size, gap); #[style(surface)] and #[style(focus)] mark the surface and focus-ring parts. The style function reads semantic tokens and BySize tables through StyleCx. It does not match on state: state colours come from States, and style/* rejects colour picks from response state, size arms and per-instance setters.
An app changes a look with Looks::style::<Badge>(f) before install; the replacement is frozen at install. A variant is a const CustomVariant with a crate-prefixed id and a look function over semantic tokens; a variant describes itself and needs no registration.
Tokens
A component reads only semantic tokens. It has no tokens of its own and no unnamed size literals. A crate's own concepts go in a #[derive(TokenGroup)] struct whose derive(tokens) function gives defaults from the resolved semantic tokens; a theme overrides them under the group's PATH.
Stories
A story shows one registered type in one state. #[story(Type, covers = [..])] registers it. The probe of the type lists the states it must show:
| Type has | Required stories |
|---|---|
| any | Default |
| a value output | Mixed, Invalid |
Input::Text or Input::Editor |
LongText |
#[component(overlay)] |
Open |
| items | Empty, One, Many |
A value a story edits comes from StoryData::value(name, init). The suite fails when a required state has no story. Drive::Auto picks how the suite changes the value; a story names another drive (Drive::Drag(Grip::part(HANDLE.at(i)).toward(vec2(1.0, 1.0))), Drive::Pick { row }, Drive::Custom(f)) only when the default does not fit; a drag of a part of the subject is a Drive::Drag, which also gets the run cancelled by Escape, never a Drive::Custom. The runner makes the disabled, read-only, right-to-left and narrow-room variants of each story itself, so a story shows only the type in its state. The cases the runner runs are the Case::new entries in crates/ui/src/testing/suite.rs and its suite/ modules: required states, shows, access, tab, values, mixed, activation, text size, motion, language, text input, and the container and collection cases for the shapes that have them.
Suite rules:
- Drawing code changes no state and sends no request. The suite's
measure-purecase runs each story'sshowtwice per pass (a measuring run first, then the real one) and again on rerun passes, which an edit's no-input rerun adds. It fails when either changes story values or sends a command, announcement, toast or request. State changes belong in event branches (if out.clicked(),for edit in out.edits) or before the container.
A type that cannot meet a shared case lists it, with a reason:
#[component(exempt(case = "face-only", reason = "A face of the title row, shown only inside it."))]
Each exemption is an entry of kind probe in design/exceptions/<crate>/<family>.toml, with the rule probe/exempt/<case> and the file that declares it. A case is a case name of the runner, face-only (a type shown only inside another type's stories) or state:<Required> (one required state the type cannot show, such as state:Mixed). craft-design-lint structure reads the exempt(..) declarations from the sources, rejects one without a reason, and fails when a declaration has no entry or an entry lists more than exist; the count cannot rise.
Seeing and checking the result
cargo run -p craft-ui-galleryshows every registered story in both directions and both control sizes, in light or dark, with a filter.cargo test -p craft-ui --features testing --test itruns the shared cases and the trials.cargo run -p craft-design-lint -- structurechecks the layer map, imports, exceptions and clones;checkreports the source rules.cargo run -p craft-ui-gallery --bin components-indexrewritesdocs/components-index.md, the list of what exists. Read it before writing a type, to avoid a second copy of one that exists.
Decisions an author meets
- One press per pass. A pass carries at most one press. The press is classified once from the hit list, and a focused text field commits in the press pass, so a click handler elsewhere sees the committed text.
- Popups close on an outside press by default.
Outside::Closecloses the layer and the press reaches the widget below;Outside::Keepignores the press. A dialog and a floating panel keep. - A popup or layer body sees the opener's environment. The overlay host installs the opener's captured values (tokens, size, app values) and resets the layer-local ones: the arena, the transform, the row, the in-scroll flag and the ink.
content_envreaches the body and the items only. A child shown byPaintUiinherits the composite's environment with the composite's resolvedenabledand size, not the valuescontent_envset.- A new body measures zero once. A container with no
LayoutMemoryentry measures zero in its first pass, records its real size, and the pass is discarded once. Ameasurethat returns the content size avoids the discard. - A roving group is one Tab stop. A container with
ContainerProps.rovingputs its group id in the body environment; its members join that stop, arrows move between them, and the group's pick arrives throughactivated_member(). - Reading a text outcome.
PartsCx::textreturns&TextOutcome<V>: an idle outcome for a part first registered in this pass. A key that was never registered panics, likepart. - Memory and animation share an owner. An animation slot is keyed by
("anim", name)under the component's id and goes with the owner's entries on eviction. A press entry is dropped when its press ends. - A face registers no parts. A component worn by
ui.face(KEY, ..)runs its ownaccessfor the wearing part's node. Itspaintcomputes what its parts would hold from the value, because the part registry is not read in face mode. - A story output has one edit kind at most, because
EditResponseholds one event. - A content painter's context owns its painter.
ContentPainterCxhas no lifetime parameter; its painter is clipped to the component's rect.