# 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: `/.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](craft-framework.md#32-the-ui-library-crates)). The file holds the type, its style, its words (`words!`) and a `stories` submodule: ```rust #[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//` (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: ```toml [lib] harness = false [features] ui = ["dep:craft-ui", "dep:egui"] screen-testing = ["ui", "craft-ui/testing"] [dev-dependencies] craft-ui = { workspace = true, features = ["testing"] } ``` ```rust // 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 ` builds and runs the executable with the feature set every build shares ([development.md](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 ```rust #[derive(Component, Props)] pub struct Badge { #[common] common: Common, /// The count shown beside the label. #[prop] count: Option, /// Working: shown dimmed. #[prop(flag)] busy: bool, } ``` - `Common` holds what every component has: label, id, variant, size, enabled, read-only, selected, tooltip. Its setters come from `Props`. A component adds no `enabled`, `id_salt` or `tooltip` field 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 `StyleKey`, the setters and the registration that lets the suite find the type. A type that implements `Component` by hand registers with `register_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`, 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")`. Read-only text the user can select and copy is a selection part: `parts` declares the run with `cx.selectable_text(KEY, &run)`, and `paint` shows it with `ui.selectable_text(KEY, rect, &run)` in place of `draw().text`, with the same run in the state's colours. A press focuses it; drag and double click select; Select All and Copy work; Tab, F6 and the arrows pass over it. A component may declare any number. The text has no node of its own, so the component's node carries it. A notice's title and message, a metadata table's values (`ListRow::cell_selectable`) and `SelectableText` are selection parts. ### Values A value component's `Output` is `EditResponse`. It binds with `Bind` and reports through `cx.propose`, `cx.commit` and `cx.adopt`; each gesture ends in one `EditEvent::Commit`. A part whose press sets the value under the pointer (a colour field, a point on a well) senses `Sense::SETS_ON_PRESS` and runs its gesture with `cx.follow_press`. Components with `Input::Editor` own their caret through `ImeSurface`. ## Looks A style is a plain struct deriving `ComponentStyle`: ```rust #[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::(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-pure` case runs each story's `show` twice 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: ```rust #[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//.toml`, with the rule `probe/exempt/` 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:` (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 ` writes the component's stories to PNG files, without building the gallery. - `cl build gallery` builds the gallery, which shows every registered story in both directions and both control sizes, in light or dark, with a filter. - `cl test ` runs the shared cases and the trials of one crate; `cl test -- ` runs some of them. - `cl cargo run -p craft-design-lint -- structure` checks the layer map, imports, exceptions and clones; `check` reports the source rules. - `cl cargo run -p craft-ui-gallery --bin components-index` rewrites `docs/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::Close` closes the layer and the press reaches the widget below; `Outside::Keep` ignores 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_env` reaches the body and the items only.** A child shown by `PaintUi` inherits the composite's environment with the composite's resolved `enabled` and size, not the values `content_env` set. - **A new body measures zero once.** A container with no `LayoutMemory` entry measures zero in its first pass, records its real size, and the pass is discarded once. A `measure` that returns the content size avoids the discard. - **A roving group is one Tab stop.** A container with `ContainerProps.roving` puts its group id in the body environment; its members join that stop, arrows move between them, and the group's pick arrives through `activated_member()`. - **Reading a text outcome.** `PartsCx::text` returns `&TextOutcome`: an idle outcome for a part first registered in this pass. A key that was never registered panics, like `part`. - **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 own `access` for the wearing part's node. Its `paint` computes 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 `EditResponse` holds one event. - **A content painter's context owns its painter.** `ContentPainterCx` has no lifetime parameter; its painter is clipped to the component's rect.