From c49f9329d458aaa143aa629a6ead294c71d630ba Mon Sep 17 00:00:00 2001 From: aiongg Date: Wed, 11 Nov 2026 16:15:31 +0000 Subject: [PATCH] docs(authoring): which library crate a component goes in, the test executables of library and family crates, story groups and titles, cl commands --- docs/authoring.md | 50 ++++++++++++++++++++++++++++++----------------- 1 file changed, 32 insertions(+), 18 deletions(-) diff --git a/docs/authoring.md b/docs/authoring.md index a93f34a4f..1653ee606 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -1,10 +1,10 @@ # 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. +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`. The file holds the type, its style, its words (`words!`) and a `stories` submodule: +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")] @@ -19,28 +19,41 @@ mod stories { } ``` -Tests that need more than the shared cases go in `crates/ui/tests/it//` as `#[craft_ui::testing::trial]` functions. +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 that holds contract types has its own `testing` feature, enables it on itself, and runs the suite from one integration binary: +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] -testing = ["craft-ui/testing"] +ui = ["dep:craft-ui", "dep:egui"] +screen-testing = ["ui", "craft-ui/testing"] [dev-dependencies] -my-crate = { path = ".", features = ["testing"] } - -[[test]] -name = "it" -path = "tests/it/main.rs" -harness = false +craft-ui = { workspace = true, features = ["testing"] } ``` -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. +```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 @@ -124,7 +137,7 @@ A component reads only semantic tokens. It has no tokens of its own and no unnam ## 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: +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 | |---|---| @@ -134,7 +147,7 @@ A story shows one registered type in one state. `#[story(Type, covers = [..])]` | `#[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. +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: @@ -150,10 +163,11 @@ Each exemption is an entry of kind `probe` in `design/exceptions// ` 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