13 KiB
Writing a component
A component is a Rust type on the contract in craft_ui::contract (crate 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 in crates/ui-widgets. A library component goes in the lowest library crate of its layer: controls and composites in craft-ui-widgets, sections, dialogs, docking and rails in craft-ui-panels, anything on a Canvas in craft-ui-canvas, assemblies of components in craft-ui-patterns (craft-framework.md 3.2). 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 the crate's integration binary, tests/it/<family>/ (for example crates/ui-widgets/tests/it/pickers/), as #[craft_ui::testing::trial] functions. A check that needs every library crate linked (the components index, the API map) goes in the facade's binary, crates/ui/tests/it.
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 outside the library that holds contract types (a family crate) runs its suite and trials from one test executable, its library's test target, with screen-testing turning on its stories. crates/color is the model:
[lib]
harness = false
[features]
ui = ["dep:craft-ui", "dep:egui"]
screen-testing = ["ui", "craft-ui/testing"]
[dev-dependencies]
craft-ui = { workspace = true, features = ["testing"] }
// src/lib.rs
#[cfg(all(test, feature = "screen-testing"))]
extern crate self as craft_color;
#[cfg(all(test, feature = "screen-testing"))]
#[path = "../tests/it/main.rs"]
mod integration;
#[cfg(test)]
fn main() {
craft_ui::testing::run(module_path!(), env!("CARGO_PKG_NAME"), &craft_ui::testing::registered_in(env!("CARGO_PKG_NAME")));
}
craft_ui::testing::run runs the #[trial] functions of the executable and the suite's shared cases over the types the package's library crate registers. The library's own crates each have an integration binary instead (tests/it/main.rs with harness = false), whose main makes the same call with the crate's testing::registered(), which craft_ui::testing_registered!() writes. The derive writes registrations and stories only under feature = "testing", so release builds carry none. cl test <crate> builds and runs the executable with the feature set every build shares (development.md).
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. title = ".." is the caption a viewer shows over the story (by default one made from its name), and group = ".." puts it in a named group with the type's other stories that name it, in declaration order: the gallery shows a group in one card, each story under its caption. 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-contract/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
cl render <crate> <Component>writes the component's stories to PNG files, without building the gallery.cl build gallerybuilds the gallery, which shows every registered story in both directions and both control sizes, in light or dark, with a filter.cl test <crate>runs the shared cases and the trials of one crate;cl test <crate> -- <filter>runs some of them.cl cargo run -p craft-design-lint -- structurechecks the layer map, imports, exceptions and clones;checkreports the source rules.cl 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.