mirror of
https://github.com/storytold/craft-libs.git
synced 2026-11-16 23:24:24 +00:00
1819 lines
125 KiB
Markdown
1819 lines
125 KiB
Markdown
# Craft framework
|
||
|
||
The Craft framework is the shared layer under every Craft app: the design system, shells, canvas core, host convention and feature families, supplied by `craft-libs` as one dependency.
|
||
|
||
Porting an existing app onto the framework: [porting.md](porting.md).
|
||
|
||
## Contents
|
||
|
||
- [1. Overview](#1-overview)
|
||
- [1.1 What the Craft framework is](#11-what-the-craft-framework-is)
|
||
- [1.2 Framework and design system](#12-framework-and-design-system)
|
||
- [1.3 Principles](#13-principles)
|
||
- [2. Installation](#2-installation)
|
||
- [2.1 Run the component gallery](#21-run-the-component-gallery)
|
||
- [2.2 Depend on craft from an app](#22-depend-on-craft-from-an-app)
|
||
- [2.3 Build, test and render a component](#23-build-test-and-render-a-component)
|
||
- [3. Architecture](#3-architecture)
|
||
- [3.1 Crate tiers](#31-crate-tiers)
|
||
- [3.2 The UI library crates](#32-the-ui-library-crates)
|
||
- [3.3 The craft facade](#33-the-craft-facade)
|
||
- [3.4 Crate taxonomy](#34-crate-taxonomy)
|
||
- [3.5 The host convention: services in, edits out](#35-the-host-convention-services-in-edits-out)
|
||
- [3.6 Runs and passes](#36-runs-and-passes)
|
||
- [3.7 One egui revision](#37-one-egui-revision)
|
||
- [4. Design system](#4-design-system)
|
||
- [4.1 Component layers](#41-component-layers)
|
||
- [4.2 Ownership](#42-ownership)
|
||
- [4.3 Generic or family component](#43-generic-or-family-component)
|
||
- [4.4 Patterns and shells](#44-patterns-and-shells)
|
||
- [4.5 Per-app look and feel](#45-per-app-look-and-feel)
|
||
- [4.6 Customization ladder](#46-customization-ladder)
|
||
- [4.7 Themes](#47-themes)
|
||
- [5. Foundations](#5-foundations)
|
||
- [5.1 Colour](#51-colour)
|
||
- [5.2 Typography](#52-typography)
|
||
- [5.3 Iconography](#53-iconography)
|
||
- [5.4 Dimensions](#54-dimensions)
|
||
- [5.5 Elevation](#55-elevation)
|
||
- [5.6 Motion](#56-motion)
|
||
- [5.7 Appearance and contrast](#57-appearance-and-contrast)
|
||
- [6. Components](#6-components)
|
||
- [6.1 What every component provides](#61-what-every-component-provides)
|
||
- [6.2 Index](#62-index)
|
||
- [6.3 Family components](#63-family-components)
|
||
- [7. Accessibility and translation](#7-accessibility-and-translation)
|
||
- [7.1 Required for every component](#71-required-for-every-component)
|
||
- [7.2 Translation rules](#72-translation-rules)
|
||
- [7.3 Goals beyond the required list](#73-goals-beyond-the-required-list)
|
||
- [8. Tests and gates](#8-tests-and-gates)
|
||
- [8.1 What gets a test](#81-what-gets-a-test)
|
||
- [8.2 Gates](#82-gates)
|
||
- [8.3 Design lint](#83-design-lint)
|
||
- [9. Migration and landing](#9-migration-and-landing)
|
||
- [9.1 Migration strategy](#91-migration-strategy)
|
||
- [9.2 Acceptance checklist](#92-acceptance-checklist)
|
||
- [9.3 Steps](#93-steps)
|
||
- [9.4 Critical path](#94-critical-path)
|
||
- [9.5 What each step delivers](#95-what-each-step-delivers)
|
||
- [9.6 Documentation for each step](#96-documentation-for-each-step)
|
||
- [9.7 Landing strategy](#97-landing-strategy)
|
||
- [9.8 Breaking changes](#98-breaking-changes)
|
||
- [9.9 Status and open questions](#99-status-and-open-questions)
|
||
- [Appendix A. Component tokens](#appendix-a-component-tokens)
|
||
- [Semantic colour tokens](#semantic-colour-tokens)
|
||
- [Appearance settings](#appearance-settings)
|
||
- [Built-in themes](#built-in-themes)
|
||
- [Generic or family placement](#generic-or-family-placement)
|
||
- [Docking details](#docking-details)
|
||
- [Radius roles](#radius-roles)
|
||
- [Size roles](#size-roles)
|
||
- [Appendix B. Crate and module layout](#appendix-b-crate-and-module-layout)
|
||
- [Facade features](#facade-features)
|
||
- [Host service rules](#host-service-rules)
|
||
- [Where each concept lives](#where-each-concept-lives)
|
||
|
||
## 1. Overview
|
||
|
||
### 1.1 What the Craft framework is
|
||
|
||
The Craft framework is the shared layer under every Craft app, supplied by `craft-libs` as one library. It holds the design system, shells and canvas core, the host convention and the feature families. The framework builds each feature once and uses it everywhere, so copies cannot drift apart in look, behaviour, accessibility and translation.
|
||
|
||
### 1.2 Framework and design system
|
||
|
||
| Term | Meaning |
|
||
| --- | --- |
|
||
| Craft framework | The whole shared layer |
|
||
| Design system | Tokens, themes and component layers. One part of the framework |
|
||
| UI library | The design-system layers every family uses, with no document concept: six crates (`craft-ui-contract` to `craft-ui-shell`) and the `craft-ui` facade that re-exports them ([3.2](#32-the-ui-library-crates)) |
|
||
| Family | A set of features a developer looks for together (colour, layers, timeline). One crate each |
|
||
|
||
App engineers need the framework: sections 2 and 3. Component and theme authors need the design system: sections 4 to 8.
|
||
|
||
### 1.3 Principles
|
||
|
||
- **Apps ask for meaning.** A raised surface, a primary button, muted text. Never a colour or pixel size. A lint checks app code ([8](#8-tests-and-gates)).
|
||
- **Apps keep their layout and conventions.** The code and behaviour of the building blocks are shared ([4.5](#45-per-app-look-and-feel)).
|
||
- **Behaviour follows the industry original.** Without one, it follows the app's existing behaviour. Where an app draws one kind of component several ways, the library has one.
|
||
- **Apps own the document.** Features hold no document state or undo history.
|
||
- **Accessibility and translation are required** ([7](#7-accessibility-and-translation)). A missing translation never blocks.
|
||
- **Colour management goes through `craft-cms`.** A missing capability is added there.
|
||
|
||
## 2. Installation
|
||
|
||
### 2.1 Run the component gallery
|
||
|
||
The gallery shows every registered story of every crate with a `ui` feature, under every theme. Themes switch at run time. It needs Rust 1.95 or later.
|
||
|
||
```
|
||
git switch craft-framework
|
||
cargo run --profile gallery -p craft-ui-gallery
|
||
```
|
||
|
||
- The `gallery` profile is release optimisation with incremental builds; `cl build gallery` builds the debug gallery instead. Both are described in [development.md](development.md), with the story renderer (`cl render`), which writes one component's stories to PNG files without building the gallery.
|
||
- Update with `git pull` and rebuild.
|
||
- Candidate fonts are optional: check out a `craft-fonts` repository and set `CRAFT_FONTS_DIR=<absolute path>` before building ([craft-fonts-build](../crates/fonts-build/README.md)).
|
||
|
||
### 2.2 Depend on `craft` from an app
|
||
|
||
An app has one dependency, one pin and one import root.
|
||
|
||
```toml
|
||
[dependencies]
|
||
craft = { git = "https://github.com/storytold/craft-libs", rev = "...", features = [
|
||
"ui", "color", "layers", "theme-store", "platform-clipboard",
|
||
] }
|
||
```
|
||
|
||
```rust
|
||
use craft::prelude::*;
|
||
use craft::color::ui::{ColorPicker, SwatchPalette};
|
||
```
|
||
|
||
The facade's rules and features are in [3.3](#33-the-craft-facade).
|
||
|
||
An app that has no eframe `App` of its own implements `ShellApp` and starts with `shell::app::run` (`start_web` on the web), which installs the runtime and drives every frame. Both need the facade's `ui-app` feature.
|
||
|
||
#### Host the runtime from your own eframe `App`
|
||
|
||
An app with its own eframe `App` calls the hooks in `craft::ui::shell::embed`. `app::run`'s driver calls the same hooks, so both kinds of app run the same code.
|
||
|
||
| When | eframe method | Call |
|
||
| --- | --- | --- |
|
||
| Once, when the app is created | with the `CreationContext` | `embed::install(ctx, InstallSpec, &UiFonts)`: the runtime, then the app's fonts. Returns the font `Stack`. |
|
||
| Each frame | `raw_input_hook` | `embed::before_input(ctx, \|output\| { ...; input })`: the closure receives the `FrameOutput` of the frame before (fired commands, announcements, chrome toggles) and returns the `FrameInput` for this frame (`RootEnv`, command states, the `Host`). |
|
||
| Each frame | `logic`, after the app's own logic | `embed::logic(ctx, \|\| decision)`: the root window's close path. The closure runs only when the root window was asked to close, and returns `CloseDecision::Close` or `Hold`. |
|
||
| Each pass | `ui`, before the app's UI | `embed::before_ui(ctx, frame)`: hands the runtime the native window on Windows, and fits the root window to its monitor once. Needs `ui-app`. |
|
||
| Each pass | `ui`, where the app draws its own document canvas | Optional: `ui::runtime::focus::host_canvas(ctx, id, KeyUse::CANVAS)` declares it as the window's canvas (Tab row below). |
|
||
| Each pass | `ui`, last | Optional: `ui::runtime::keys::with_window_intents(ctx, rtl, \|intents\| ...)` reads the keys no component took (below). |
|
||
|
||
`install` takes over these parts of the context for the whole window, not only for framework components:
|
||
|
||
| What | Effect on the app's own egui code |
|
||
| --- | --- |
|
||
| Tab | Bare Tab moves framework focus and never reaches egui, unless the focused framework stop keeps Tab or an app's own widget has the focus (below), or nothing has the focus in a window that registered no focus stop: egui then moves its own focus into the app's widgets. A window with stops but no Tab entry (on the Mac, where Tab reaches only text fields by default) keeps the Tab from egui, which would otherwise focus framework controls the platform's rule skips. With `RootEnv::tab_toggles_chrome`, Tab toggles the chrome in a window that shows a document canvas, with nothing focused or the canvas focused, and arrives in `FrameOutput::chrome_toggles`. The canvas is a framework canvas, or the app's own egui canvas declared each pass with `ui::runtime::focus::host_canvas`. With nothing focused, the canvas is the key target: a canvas that keeps Tab (`KeyUse::CANVAS.with_keep(KeepKeys::Tab)`) gets the press in egui's input, as when it is focused, and nothing toggles. |
|
||
| F6 | F6 and Shift+F6 move between panes and never reach egui. They are the defaults of the commands `window.nextPane` and `window.previousPane` (`NavCommand`): a default chord that another command binds is that command's, and the overrides move or unbind them (`CommandInput::overrides`). An app whose own shortcut table keeps F6 unbinds them there. |
|
||
| Escape | Plain Escape (Alt and Shift may be held) goes to the focused framework stop and its scopes; with no framework stop focused, it goes to the window as `Intent::Cancel`. It reaches egui only while an app's own widget has the focus (below). An Escape the runtime takes outside a captured framework press also ends egui's own drag in that pass, as egui's Escape does. |
|
||
| F10, Alt+letter | Taken while a framework menu bar is registered: F10 (`window.focusMenuBar`, bound and yielded as F6 is) focuses the bar, Alt+letter opens a menu (not on macOS). |
|
||
| Edit chords | Taken while a framework editor is focused. With nothing focused, the edit chords and egui's copy, cut and paste events of the commands in the window canvas's edit set (`KeyUse::edits`, `host_canvas`) stay in egui's input for it, and no command fires with them. Otherwise egui's copy, cut and paste events become the ⌘C/X/V chord for the app's commands, unless an app's own widget has the focus (below). While egui holds a label text selection, copy and cut stay egui's, and egui copies the selection. |
|
||
| IME | Taken while a framework editor owns the IME: its events and `PlatformOutput.ime` are the runtime's. Otherwise they stay egui's, for the app's own `TextEdit` or IME code. |
|
||
| An app's own focused widget | While egui focus is on a widget no framework component made, or an egui popup is open, and no framework press or drag is captured, Tab, Shift+Tab, Escape and egui's clipboard events stay in egui's input for it, and the runtime routes nothing for them. While egui focus is on such a widget, the arrows and Tab move egui focus among the app's widgets as egui does; while a framework stop has the focus, egui's arrow moves are off. |
|
||
| Releases | The release of every key the runtime took is taken too. |
|
||
| Focus surrender | The runtime moves its own focus on press (8.3): a press a framework component takes moves focus to it; a press no component takes drops the framework's focus. egui's click-away never takes the framework's focus. egui's surrender option (`InputOptions::surrender_focus_on`) stays the app's and governs the focus of the app's own widgets, as in egui alone: a press no component takes leaves that focus to egui's rule. |
|
||
| Clicks | egui's click options (`InputOptions::max_click_dist`, `max_click_duration`) stay the app's, for its own widgets. A framework component clicks and drags by the framework's press lifecycle: a release within the slop (`HitSizes::slop`), whatever its duration. Read a component's click with `contract::clicked(&response)` or its output's `clicked()`; egui's `Response::clicked()` on a component's response also needs a click by egui's options. |
|
||
| Zoom keys | egui's keyboard zoom is off. The interface scale is `RootEnv::scale`. |
|
||
| Quit shortcuts | egui's quit shortcuts are cleared. Quit goes through the close path. |
|
||
| Close path | The runtime's window host owns the root window's close request. `embed::logic` asks the app through its closure, then hands the close to the platform quit where there is one (macOS). |
|
||
| Input pacing | One press per pass: extra presses in one frame wait for the next passes. A press outside an open framework menu closes the menu and goes no further. After an OS resize of the window, the held pointer is released. |
|
||
|
||
The window's keys are the ones the runtime routes to no component: an Escape or a plain Enter while no framework stop is focused, and the arrows' nudge. `with_window_intents` offers them to its closure while nothing has framework focus. The closure takes what it handles (`Intents::take(Intent::Cancel)`; `Intent` and the other types `Intents` reads are in `ui::runtime::keys`) and returns whether it took anything; the rest stays for later readers. A framework scope that ran earlier in the pass takes them first (an open dialog takes the Escape that closes it), so the app reads them last in its UI to see what no component took. App code that read `Key::Escape`, `Key::Tab`, F6 or F10 from egui while none of its own widgets had focus reads these intents and `FrameOutput::chrome_toggles` instead; its own focused widgets and popups keep reading Tab and Escape from egui.
|
||
|
||
Framework dialogs the app keeps as values run on a `DialogHost`: the app calls `run(ui)` once per pass after its own UI and reads results with `take`.
|
||
|
||
### 2.3 Build, test and render a component
|
||
|
||
Inside `craft-libs`, every local cargo command goes through `tools/cl`, which gives every build the same feature set so the framework is built once per target directory ([development.md](development.md)):
|
||
|
||
| What | Command |
|
||
| --- | --- |
|
||
| Check the crate you changed | `cl check <crate>` |
|
||
| Run its suite and trials | `cl test <crate>`, or `cl test <crate> -- <filter>` |
|
||
| One component's stories as PNG files | `cl render <crate> <Component>` (`ui` for the library's own components) |
|
||
| The gallery | `cl build gallery` (debug), or `cargo run --profile gallery -p craft-ui-gallery` |
|
||
|
||
Writing a component, its stories and its trials: [authoring.md](authoring.md). Moving an app's UI onto the framework: [porting.md](porting.md).
|
||
|
||
## 3. Architecture
|
||
|
||
### 3.1 Crate tiers
|
||
|
||
Tiers describe dependency direction. A crate depends only on lower tiers. They are separate from the design-system layers in [4.1](#41-component-layers).
|
||
|
||
```text
|
||
Tier 3 craft facade: re-exports and forwards features
|
||
|
|
||
Tier 2 families craft-color, craft-draw, craft-layers, ...
|
||
|
|
||
Tier 1 UI library craft-ui-contract, -widgets, -panels, -canvas, -patterns, -shell; the craft-ui facade
|
||
|
|
||
Tier 0 engines, services craft-behavior, craft-theme, craft-i18n, craft-settings, craft-cms, craft-host, ...
|
||
```
|
||
|
||
Rules:
|
||
|
||
- Tier 0 needs no egui. A tier-0 crate that converts to egui types does so behind a feature: `craft-theme`'s `ecolor`, `craft-host`'s `ui`, `craft-keymap`'s `egui`.
|
||
- The UI library names no document concept and never depends on a family.
|
||
- A family keeps core types at the crate root and egui UI in `ui` behind the `ui` feature, and may be UI-only.
|
||
- No family's `ui` depends on another family's `ui`, except on `craft-color`, the base family any family may use (`crates/craft/tests/families.rs` checks it). A widget two other families share moves down to the UI library.
|
||
|
||
### 3.2 The UI library crates
|
||
|
||
The UI library is six crates along the design-system layers ([4.1](#41-component-layers)), plus the `craft-ui` facade. An arrow points from a crate to a crate it depends on.
|
||
|
||
```mermaid
|
||
graph TD
|
||
ui["craft-ui (facade)"] --> shell & patterns & canvas
|
||
shell["craft-ui-shell<br/>app shell, title bar, eframe entry"] --> panels
|
||
patterns["craft-ui-patterns<br/>ready-made dialogs, presets, preferences, dock areas"] --> panels
|
||
canvas["craft-ui-canvas<br/>canvas, tools, canvas controls, full-window dialogs"] --> panels
|
||
panels["craft-ui-panels<br/>sections, dialogs, docking, rails"] --> widgets
|
||
widgets["craft-ui-widgets<br/>components: buttons to tables"] --> contract
|
||
contract["craft-ui-contract<br/>runtime, style, fonts, primitives, contract, layout, test kit"] --> behavior & theme
|
||
behavior["craft-behavior<br/>behaviour cores, no egui"] --> theme["craft-theme<br/>tokens and themes, no egui"]
|
||
```
|
||
|
||
| Crate | Layer | Holds | Also depends on |
|
||
| --- | --- | --- | --- |
|
||
| `craft-ui-contract` | 2 to 4 | The runtime (per-pass services and the one egui adapter), style, fonts, primitives, the component contract and its pipeline, layout services, and the test kit (`testing`) | `craft-host`, `craft-keymap`, `craft-window`, `craft-quit`, `craft-i18n`, `craft-font-catalog`, `craft-fonts-build`, `craft-ui-macros` |
|
||
| `craft-ui-widgets` | 5 | Components: buttons, choices, display, forms, lists, menus, notices, text fields, value drags, pickers, tabs, tables, graphs, bars, and the layout components `Stack`, `Row`, `Grid` | |
|
||
| `craft-ui-panels` | 5 | Sections, dialogs and the dialog host, docking, rails, and the canvas data patterns read without the canvas | `craft-quit` |
|
||
| `craft-ui-canvas` | 5 and 6 | `Canvas` with its tool host, tools, rulers and navigator; the canvas controls; the full-window dialogs that show a canvas | |
|
||
| `craft-ui-patterns` | 6 | Ready-made dialogs (form dialogs, PDF export), presets, preferences, dock areas and panels | `craft-pdf` (the PDF export dialog) |
|
||
| `craft-ui-shell` | 7 | `AppShell`, the title bar, and with `app` the eframe entry point | `craft-window` |
|
||
| `craft-ui` | | The facade: re-exports the six crates under one root, so `craft_ui::buttons` is `craft_ui_widgets::buttons`. With `testing`, `craft_ui::testing` gathers every crate's test helpers | the six crates |
|
||
|
||
- Each crate above the contract re-exports the modules of the crates below it at its root, so code inside the library writes `crate::contract::…` in any crate.
|
||
- Every crate outside the library that uses it (the families, the services with a `ui` feature, the gallery, the story renderer and the `craft` facade) depends on the facade `craft-ui`. Apps do too, through `craft::ui`.
|
||
- Each crate has its own `testing` feature and its own integration binary (`tests/it`), which runs the shared suite over the types that crate registers. The facade's `it` binary holds the checks that need every crate linked: the components index and the API map.
|
||
- `craft-ui-macros` holds the derives every crate uses; `craft-ui-test-kit` holds test kits the crates' integration binaries share.
|
||
|
||
### 3.3 The `craft` facade
|
||
|
||
- Every public UI type is re-exported at `<crate>::ui`; every core type at the crate root: `craft::color::ui::ColorPicker`, `craft::color::Palette`.
|
||
- `craft::prelude` holds `AppInfo`, `Host`, `Section`, `Tokens`, `DialogStack` and `Outcome`. There are no other preludes.
|
||
- A feature can move between crates as long as `craft::<family>` stays.
|
||
|
||
Feature names: `ui` is the only UI feature name in every crate, and `screen-testing` adds stories and snapshot tests. The full table is in [Appendix B](#facade-features).
|
||
|
||
Native-only modules use `#[cfg(not(target_arch = "wasm32"))]`. A crate that cannot build for wasm says so in its first doc line, and the facade gates it.
|
||
|
||
### 3.4 Crate taxonomy
|
||
|
||
| Kind | Role | Crates |
|
||
| --- | --- | --- |
|
||
| Facade | One dependency for apps | `craft` |
|
||
| UI library | Shared UI infrastructure ([3.2](#32-the-ui-library-crates)) | `craft-ui` (facade), `craft-ui-contract`, `craft-ui-widgets`, `craft-ui-panels`, `craft-ui-canvas`, `craft-ui-patterns`, `craft-ui-shell`, `craft-ui-macros`, `craft-behavior` |
|
||
| Domain families | Features with core logic and egui UI | `craft-color`, `craft-draw`, `craft-imaging`, `craft-layers`, `craft-browse`, `craft-text`, `craft-font-manager`, `craft-pages`, `craft-review`, `craft-table`, `craft-timeline`; planned: `craft-code` |
|
||
| Infrastructure services | Egui-free logic that families and apps share | `craft-theme`, `craft-theme-store`, `craft-host`, `craft-i18n`, `craft-settings`, `craft-keymap`, `craft-menu`, `craft-automation`, `craft-update`, `craft-cms`, `craft-ai-core`, `craft-atomic`, `craft-docpath`, `craft-font-catalog`, `craft-font-store`, `craft-font-subset`, `craft-pdf`, `craft-prepress`, `craft-proof` |
|
||
| Formats and codecs | Clean-room readers and writers | `craft-audio`, `craft-crw`, `craft-jpeg`, `craft-media`, `craft-doc`, `craft-ecproj-format`, `craft-pcraft-format`, `craft-vectorcraft-format` |
|
||
| Platform adapters | One operating-system, window-system or browser service each | `craft-platform`, `craft-dialogs`, `craft-window`, `craft-win32`, `craft-quit`, `craft-print`, `craft-web-api`, `craft-web-host`; next: `craft-gpu` |
|
||
| Tooling | Not shipped in apps | `craft-ui-gallery`, `story-render`, `feature-root`, `craft-ui-bench`, `craft-ui-test-kit`, `craft-design-lint`, `craft-plate-test`, `craft-fonts-build`, `craft-media-testkit` |
|
||
|
||
One crate allows `unsafe` code, wrapping foreign calls behind a safe API so no other crate needs `unsafe`: `craft-win32` (the Win32 window-procedure subclassing and window-handle calls). The workspace lint table sets `unsafe_code = "forbid"`; craft-win32 sets it to `deny` and allows it in `lib.rs`, and the design-lint rule `contract/unsafe-allow` names it. The benchmark's counting allocator (`craft-ui-bench`, `src/alloc.rs`) is the other allowed site. The HarfBuzz FFI behind `craft-font-subset` is outside the workspace ([craft-font-subset](#craft-font-subset)).
|
||
|
||
Services and adapters may carry a `ui` feature (`craft-keymap`, `craft-update`, `craft-dialogs`) but name no document concept. Module tables: [Appendix B](#appendix-b-crate-and-module-layout).
|
||
|
||
### 3.5 The host convention: services in, edits out
|
||
|
||
`craft-host` is a small egui-free crate. The app builds a `Host` once and installs it on the egui context. Every feature reads it with `Host::of(ui)`. No feature takes an i18n or settings parameter.
|
||
|
||
```rust
|
||
fn setup(ctx: &egui::Context, app: &App) {
|
||
Host::builder(app.info())
|
||
.i18n(app.i18n.clone())
|
||
.settings(app.settings.clone())
|
||
.commands(app.keymap.clone())
|
||
.files(app.files.clone())
|
||
.jobs(Arc::new(craft::host::ThreadJobs))
|
||
.install(ctx);
|
||
}
|
||
```
|
||
|
||
| Rule | Detail |
|
||
| --- | --- |
|
||
| Services in | Identity, language, settings sections, commands, files and jobs. Each is a trait the app or a library crate implements. |
|
||
| Document data in | Each feature defines one small trait (`TimelineModel`, `LayerTree`) that the app implements on its document view. Features own no document state |
|
||
| Edits out | Features return edit events (`Begin`, `Update`, `Commit`, `Cancel`, `Set`). The app applies them to its own undo stack |
|
||
| Dialogs | A feature dialog is a value the app opens on the library's `DialogHost`. Its result is a `DialogResult<T>` (`Ok(T)` or `Cancel`) the app takes on a later pass. No feature opens its own window |
|
||
|
||
The remaining service rules (settings keys, words, commands, files) are in [Appendix B](#host-service-rules). The examples show the shape, not settled APIs.
|
||
|
||
**Cancel and Escape.** Esc during a gesture ends it with `Cancel { reason: Escape }`. The app restores the value it held at `Begin` and makes no undo step.
|
||
|
||
```rust
|
||
match event {
|
||
EditEvent::Begin { id, .. } => self.mark = Some(doc.undo_mark(id)),
|
||
EditEvent::Update { value, .. } => doc.preview(FILL, value),
|
||
EditEvent::Commit { after, .. } => doc.apply(Edit::set(FILL, after)),
|
||
EditEvent::Cancel { reason, .. } => match self.mark.take() {
|
||
Some(m) if !reason.document_moved() => doc.restore(m),
|
||
_ => {}
|
||
},
|
||
EditEvent::Set { after, .. } => doc.apply(Edit::set(FILL, after)),
|
||
_ => {}
|
||
}
|
||
```
|
||
|
||
**Interrupted gesture.** Besides Esc, other events end a gesture with `Cancel`; the `CancelReason` says which: `Refused`, `Dismissed`, `Escape`, `Blur`, `Removed`, `HostChanged`, `UndoDuringGesture`. For `HostChanged` and `UndoDuringGesture`, `reason.document_moved()` is true: the document changed under the gesture, so the app keeps it as it is, because a restore would also take back that change. The handler above covers all of them.
|
||
|
||
**Error.** A failing service call returns a typed error, and the feature shows it in its own UI without an edit. File calls return `Result<_, FileError>`. A dismissed picker answers `Picked::Cancelled`, not an error; a picker that cannot open answers `Picked::Unavailable(cause)`.
|
||
|
||
**Async job.** Work runs on the host's `Jobs`, never on a thread a feature starts. `JobQueue` adds priorities, one job per key, replacement and cancellation. Dropping a key sets the job's cancel flag, and a cancelled job's result is never delivered.
|
||
|
||
```rust
|
||
queue.submit(photo_id, Priority::VISIBLE, move |cancel| decode(&path, cancel));
|
||
while let Some(Finished { key, result }) = queue.try_recv() { show(key, result) } // on a later pass
|
||
```
|
||
|
||
### 3.6 Runs and passes
|
||
|
||
A pass shows the whole UI once. egui may repeat a pass within a frame (a discard pass); only the frame's last pass is painted. Within a pass, a container's contents run twice: a measuring run, then the real run. Both runs of a pass give the same result.
|
||
|
||
Content runs in every pass, and its sizes come from this pass. Layouts also read some state earlier passes left, for example a scroll area's offset and its last view and extent (step 4 and the scroll bars read them) and the sizes layout memory keeps (`runtime::layout_memory`; a changed size asks for a discard pass). The one exception to running in every pass is out-of-view content.
|
||
|
||
**Layout memory.** A record of layout memory holds a measure or a text. A body whose inputs did not change takes its kept measurement instead of running a measuring run. A text that a measuring run found for content outside the body (a value readout beside a story, for example) is kept with the measurement: `layout_memory::emit_text` hands it forward, `layout_memory::text` reads it, and a body that takes its kept measurement gives the text its measuring run found. A real run that finds another text marks the kept transcript as changed.
|
||
|
||
**Out-of-view content.** Content inside a scroll area that is out of view this pass does not run. It keeps what it last showed: the extent it had in the last pass that showed it, which changes only in a pass that shows the content, and the stops it registered there. One mechanism (`runtime::lazy`, one store) serves every use:
|
||
|
||
- Only content that meets the view runs. A `Lazy` child out of view registers the focus records of its last real run again in its place (its stops, the scopes it pushed and the roving groups of its stops; `focus::Transcript`), so Tab and F6 reach its stops; Tab onto one runs the child and the reveal scrolls it in.
|
||
- `Lazy::new(key, estimate).show(ui, |ui| ..)` wraps a large child of a scroll body (a card, a section of an app panel). Out of view it takes its remembered extent, also after the scroll area's room changed, and its closure does not run. It is a child in flow: in a `Grid` or spread `Row` body it holds one cell, its content is the one child that takes the cell, and out of view it takes the cell at its remembered extent. A card keyed by itself, not by its row, keeps its extent when a change of the column count regroups the rows. A child no pass showed yet takes its estimate (that long along the axes the area scrolls, nothing across them), so a first show runs only the children in view. It runs when its extent meets the view, and while a stop from its last run holds keyboard focus or is the target of a focus request. `.reveal(true)` in a pass asks its scroll body to glide until the child starts at the view's start, whether it ran yet or not: the offset follows the child's place on the motion service's follow curve (a Travel motion, so reduced motion jumps), while estimates before it resolve; a wheel, drag or other move of the body ends the glide. The key names the child among every `Lazy` of its scroll area. Outside a scroll area a `Lazy` always runs.
|
||
- The first run of a pass decides which children run, so the measuring run and the real run lay out the same children.
|
||
- Every scroll input moves the offset at step 4, before the content runs, so the decision sees the offset the pass paints. Wheel, page keys and reveals arrive there directly. A thumb drag, a track press or an AccessKit scroll action is sensed after the content ran: the pass queues it for step 4 and asks for a discard pass, so the move shows in the same frame.
|
||
- A scroll position the framework holds is also named by content: the first child at or after the view's start and its place in the view (`lazy::Anchor`, kept with the offset). When extents before that child change (estimates replaced by real extents, rows regrouped), the offset follows the child and the pass runs again, so the content in view does not move. An offset bound to the app (`Component::scroll`) is the app's plain offset, and a region that follows its end follows the end.
|
||
- A scroll area that does not run (a tab switched away) keeps its children's entries, and its content extent lives beside its offset (`ScrollState`) with the same lifetime, so it shows again at the same offset after any length of hide; one that runs drops the entries of the children it did not reach.
|
||
- A collection builds the rows in view, plus its lead, anchor, renaming and grabbed rows. Its rows are no Tab entries (Tab moves past the collection, arrows move its lead), so a row out of view has no stops to keep. It places the rows it does not build by the extents they had when last built, from the same store, and its output lists the rows in view and the kept rows. Rows it never built take its item layout's estimate, as a `Lazy` takes its own, so a long list is never built whole. A reveal (a requested one, a key move, type-ahead, a rename) places the row by measured heights: before the rows are built, the collection builds and measures the rows that will share the view with the revealed row, up to it, that no pass built yet, and the build takes those measures, so the row shows wholly in the pass that reveals it.
|
||
- Each built row is a run of the collection's item component, or, for a collection that sets `Collection::MEMBERS` (a tab strip's tabs, a colour table's cells), a member of the collection's own run: sensed with its parts in its arena, updated, painted and finished at its row, and reported as an access sub-node of the collection with its parts' nodes under it, with no run of its own. Its output gives the item event, as a run's does. Selection, activation, drags and AccessKit requests on the row are the collection's either way.
|
||
- The access tree covers the view, by the same rule: content that runs reports its access nodes (a collection's built rows and their section headings included). A component that lays out section rows as its own parts (TileGrid's group headings and tail rows) reports the nodes of those in view. Content out of view (`Lazy` children and collection rows) is absent from the access tree until it scrolls in. AccessKit scroll actions still reach it, because they move the offset.
|
||
- Content that was never shown has only its estimate and no stops: Tab reaches it once it was shown. An app brings it into view with `.reveal(true)`.
|
||
|
||
### 3.7 One egui revision
|
||
|
||
`craft-libs` pins one revision of an egui fork for every egui crate (`[patch.crates-io]` in the root `Cargo.toml`). Two revisions in one build would give two incompatible `Tokens` and `Ui` types. `craft::egui_fork::{GIT, REV}` name the fork and revision, and `craft::egui_fork::check_lockfile` checks that an app's `Cargo.lock` takes every egui package from them; an app's `xtask` calls it. An app must also patch egui to the same fork, because `[patch]` applies only at the workspace root.
|
||
|
||
**The fork.** The library pins `github.com/storytold/egui` branch `next` at `dcd4de1f`. That revision is the storytold egui fork's revision on craft-libs `main` (`6d518fc7`) plus 28 commits the framework needs:
|
||
|
||
- `TextEditState::preedit`, and a new IME context ends the old composition
|
||
- `Event::ImeResetRetired`: the integration reports a reset request it dropped (native and web)
|
||
- `InteractOptions::enabled` (disable one widget of an enabled `Ui`) and `InteractOptions::activate_on_space`
|
||
- `Memory::request_focus_with_filter` and `Memory::set_focus_surrender` (a focused widget's own rule for a press or click elsewhere)
|
||
- `Response::describe_for_accessibility` public, accessible names for `ScrollArea` scroll bars, `Context::set_accesskit_focus`, `Context::register_accesskit_parent` public
|
||
- a pointer press goes to the widget under the press position
|
||
- `DragAndDrop::aborted_by_escape`
|
||
- `Popup` swallows the press outside it that closes it, and stays directly above the layer it opened from
|
||
- `Context::set_layer_order`, which moves unlisted sublayers with their listed parent
|
||
- OpenType features per text section (epaint)
|
||
- `IdTypeMap::insert_temp_boxed` keeps the allocation of a value taken out, and `Context::ptr_eq`
|
||
- `Context::pass_mark`, `pass_records_since` and `replay_pass_records`: a settled region replays its last pass's records
|
||
- `Event::SystemTheme` reports the OS's light or dark preference
|
||
- `egui_kittest`'s eframe harness runs `App::raw_input_hook` before each pass, as eframe does, so an app's `embed::before_input` runs in its tests
|
||
|
||
The fork's `PATCHES.md` describes each patch and whether it is proposed upstream.
|
||
|
||
**What it means for landing.** The fork's `next` branch moves with the framework's `next` branch: a framework change that needs an egui change lands on egui `next` first, and `craft::egui_fork::REV` names the new revision. When craft-libs `next` merges to `main`, `main` pins egui `next` as well.
|
||
|
||
## 4. Design system
|
||
|
||
The design system decides how apps look and how components compose. Its readers build components, themes and app looks.
|
||
|
||
### 4.1 Component layers
|
||
|
||
Each layer reads only the layer below it. The right column names the crate that holds the layer ([3.2](#32-the-ui-library-crates)); the crate docs number the layers from the bottom, with tokens and behaviour as layers 0 and 1 and the app as layer 8.
|
||
|
||
```text
|
||
Shells title bar, rails, body and bars as slots; presets per kind of app craft-ui-shell
|
||
^
|
||
Patterns panel, dialog, inspector, dock area, options bar, status bar, title bar craft-ui-patterns, craft-ui-canvas
|
||
^
|
||
Composites field rows, property rows, headers, lists, tabs, toasts, menus craft-ui-widgets, craft-ui-panels
|
||
^
|
||
Controls buttons, fields, sliders, checkboxes, selects, swatches, tooltips craft-ui-widgets
|
||
^
|
||
Primitives surface, state layer, focus ring, divider, stack, interactive area, text, icon, handle
|
||
(with the runtime, style and contract under them) craft-ui-contract
|
||
^
|
||
Tokens scales, ramps, seeds, contrast, size presets, themes craft-theme, no egui
|
||
```
|
||
|
||
### 4.2 Ownership
|
||
|
||
| Concern | Owner | Responsibility |
|
||
| --- | --- | --- |
|
||
| Token model, themes, resolution, validation | `craft-theme` | The design language as data, with no egui |
|
||
| Theme files, machine-local library, suite selection | `craft-theme-store` | `selection.json`, lock and revision protocol, watcher, client |
|
||
| Tokens to egui styles | `craft_ui::style` (craft-ui-contract) | The one place data becomes egui styling, stock widgets included |
|
||
| Behaviour | `craft-behavior`, `craft_ui::runtime::{focus, keys}` (craft-ui-contract), `craft_ui::edit` (craft-ui-widgets) | Press, drag, navigation and edit events with no egui; focus and keys per pass; undo adapters |
|
||
| Generic components and shells | The UI library crates | Reusable UI |
|
||
| Domain components | Family crates | Feature UI on the UI library |
|
||
| Gallery, story renderer, lint | `craft-ui-gallery`, `story-render`, `craft-design-lint` | Inspect and enforce the system ([8](#8-tests-and-gates)) |
|
||
|
||
### 4.3 Generic or family component
|
||
|
||
A component goes in the UI library when both hold:
|
||
|
||
1. Its inputs are general data: values, ranges, points, text, a list of rows, or a small trait.
|
||
2. It names no document concept: layer, colour model, gradient, path, clip, page.
|
||
|
||
Otherwise it goes in the family crate that owns the concept. A component that two families need moves down to the UI library once its inputs are general.
|
||
|
||
Inside the library, a component goes in the lowest crate whose layer it belongs to: a control or composite in `craft-ui-widgets`; a section, dialog, dock part or rail in `craft-ui-panels`; anything that needs `Canvas` in `craft-ui-canvas`; an assembly of other components (a pattern) in `craft-ui-patterns`.
|
||
|
||
Borderline cases (curve editor, histogram, preset browser, menus, canvas overlays) and where the code places them are in [Appendix A](#generic-or-family-placement).
|
||
|
||
### 4.4 Patterns and shells
|
||
|
||
A pattern is a reusable region of a window. It works in any shell and decides nothing about the rest of the window: panel, dialog, inspector, dock area, options bar, status bar, title bar, rails.
|
||
|
||
A shell composes a whole window. It orders slots (title bar, top bars, rails, body, bottom bars), decides which show, scopes ids and state per window, and draws no bar or panel itself. Slots take patterns.
|
||
|
||
| Shell | State |
|
||
| --- | --- |
|
||
| Canvas: fixed document canvas, document tabs, tool rail, panel dock. Photo, vector, design, figure, PDF and CAD apps | Built |
|
||
| Workspace: equal panels in named workspaces. Film, effects and sound apps | Planned |
|
||
| Office-style: ribbon in the top slot, backstage view, task panes | Planned |
|
||
|
||
Docking details are in [Appendix A](#docking-details).
|
||
|
||
### 4.5 Per-app look and feel
|
||
|
||
An app has one layout in every theme and size. A theme never changes the layout. Different arrangements are workspaces, which are separate from themes. Studio, for example, is Pro's layout with Studio colours and the Comfortable size.
|
||
|
||
| The app decides | The framework shares |
|
||
| --- | --- |
|
||
| Layout and placement, following its industry original | Components and their behaviour |
|
||
| Conventions: menus, shortcuts, tool behaviour | Family patterns: dock and tool rail, ribbon |
|
||
| Default density: Compact or Comfortable | Focus and Tab order, Esc cancels, one undo step per drag |
|
||
| Default theme and mode: dark for creative apps, light for office-style apps | Themes, high contrast, translation, screen-reader support |
|
||
| Colour overrides for its own look | The token model that carries them |
|
||
|
||
### 4.6 Customization ladder
|
||
|
||
Use the first step that works.
|
||
|
||
1. **Density.** Compact or Comfortable.
|
||
2. **Size overrides.** The app ships a `sizes.json` that overrides base sizes (for example `size.control.md`). A base override carries to every size derived from it. To change one component, pin that component's token. Overrides stay within the validator's limits.
|
||
3. **Component tokens.** One named value changes a component app-wide.
|
||
4. **Builder options.** Options cover structural differences. A new need gets a new option, not a new component.
|
||
5. **Per-app colour overrides.** A theme file can carry a section per app. Values are theme roles or literal colours, so themes, dark mode and high contrast keep working.
|
||
6. **One-off app components.** A last resort, built from shared pieces. Allowed and not policed.
|
||
|
||
### 4.7 Themes
|
||
|
||
Ten built-in themes with 17 mode variants; the suite default is ArtCraft. A two-mode theme is one theme with a variant per mode, and a mode can carry a partial `seeds` override so each mode derives its own colours. Picking a two-variant theme sets both modes. A theme can name an icon pack that replaces the base icons it covers. The gallery is also the base of a theme editor. The themes are listed in [Appendix A](#built-in-themes).
|
||
|
||
## 5. Foundations
|
||
|
||
Foundations are the values every component reads. This section holds concepts only. Which component uses which token is in [Appendix A](#appendix-a-component-tokens).
|
||
|
||
### 5.1 Colour
|
||
|
||
```text
|
||
seeds -> ramps -> semantic tokens -> pins -> contrast pass -> resolved Tokens -> theme bridge
|
||
```
|
||
|
||
- **Seeds.** Neutral, accent and four status hues (good, warn, bad, info).
|
||
- **Ramps.** 12 steps per seed per mode, in OKLCH, on a fixed lightness curve.
|
||
- **Semantic tokens.** Mapped to ramp steps by meaning (groups below).
|
||
- **Pins.** Any token can be set by hand.
|
||
- **Anchoring.** Unpinned background greys keep their distance from the theme's panel colour, so they follow a pinned panel. Text greys stay on the curve.
|
||
- **Contrast pass.** Derived colours move to the minimums in [5.7](#57-appearance-and-contrast).
|
||
|
||
Semantic tokens fall in eight groups: surface, text, line, accent, status, state, canvas overlay and data. The tokens of each group are in [Appendix A](#semantic-colour-tokens).
|
||
|
||
Accent fills that carry text use the strong pair: the accent moved in lightness only as far as white text needs.
|
||
|
||
A disabled component looks one of two ways (`Component::DISABLED`). A control whose look is chrome (a button, a field, a slider) takes its style's Disabled state: `text.disabled` ink and the disabled fills, and the data colours it shows (a tone dot on a picker, a swatch icon, a gradient ramp) paint at `Opacity::DISABLED`, so they dim and keep their hues: its `Draw` paints them so, and so do a content painter's data paths (`ContentPainterCx::data_shapes`, `picture`, `checker`, `ramp`). A component that shows data (a picture, a colour, a plot, a tile), or paints data with a content painter's bare `painter`, declares `DisabledLook::Faded`: step 13 paints its enabled look, faces included, at `Opacity::DISABLED`, so its data dims with the rest. The children it shows stay outside its fade and show their own disabled look.
|
||
|
||
### 5.2 Typography
|
||
|
||
App text maps to the nearest named role. A real new need gets a new role. No role serves a single use.
|
||
|
||
| Role | Use | Compact (size / line, pt) | Comfortable |
|
||
| --- | --- | --- | --- |
|
||
| Caption | Small print | 10.5 / 14 | 11.5 / 16 |
|
||
| Label | Control labels | 11.5 / 16 | 12.5 / 18 |
|
||
| Body | Body text | 12 / 16 | 13 / 18 |
|
||
| Body strong | Emphasised body text (semibold) | 12 / 16 | 13 / 18 |
|
||
| Title | Panel and dialog titles (semibold) | 13 / 18 | 14 / 20 |
|
||
| Heading | Section headings (semibold) | 15 / 20 | 17 / 24 |
|
||
| Body large | Large regular text, such as a prominent field | 15 / 20 | 16 / 22 |
|
||
| Mono | Code and numbers: number fields, timecodes, tables | 11.5 / 16 | 12.5 / 18 |
|
||
|
||
The Text size setting scales the roles only (0.83x, 1x, 1.17x, 1.33x), rounded to 0.5 pt. Control heights, icons and faces do not scale. The interface font setting can use the OS UI face; mono stays the suite's.
|
||
|
||
### 5.3 Iconography
|
||
|
||
- **Sets.** Phosphor is the base set. The gallery's active set defaults to Lucide. A theme may supply an icon pack that replaces the base icons it covers; missing icons fall back to the base set.
|
||
- **Strokes.** 1.25 pt at the small size, 1.5 pt at medium and large.
|
||
|
||
### 5.4 Dimensions
|
||
|
||
Sizes are runtime tokens. The rule runs from the general to the specific:
|
||
|
||
1. A **scale** holds the allowed values: spacing 0, 2, 4, 6, 8, 12, 16, 20, 24, 32; radius 0, 2, 3, 4, 6, 8, 12 and full; strokes hairline, 1, 1.5, 2, 3.
|
||
2. **Semantic role tokens** pick from the scale by meaning: control height, icon size, gap, padding, radius, bar height.
|
||
3. **Components** derive their own dimensions from the role tokens in their style: a role, or a role times a ratio named in the component's style with the rule it comes from. There are no component-specific theme values.
|
||
|
||
Components name semantic tokens and never a pixel value or shape of their own. [Appendix A](#appendix-a-component-tokens) says which component takes which role. Only drawing details (stroke widths, chevron geometry, dash lengths) stay constants.
|
||
|
||
**Semantic role tokens (pt).**
|
||
|
||
| Role | Compact | Comfortable |
|
||
| --- | --- | --- |
|
||
| Control height sm / md | 20 / 24 | 24 / 30 |
|
||
| Icon sm / md / lg | 12 / 16 / 20 | 14 / 18 / 22 |
|
||
| Gap inline / row / stack / section | 4 / 4 / 6 / 12 | 6 / 6 / 8 / 16 |
|
||
| Padding control / panel / dialog | 6 / 8 / 16 | 8 / 12 / 20 |
|
||
| Radius control / surface / window / panel | 3 / 4 / 6 / 0 | 6 / 8 / 12 / 0 |
|
||
| Stroke thin / medium / thick / heavy | 1 / 1.5 / 2 / 3 | 1 / 1.5 / 2 / 3 |
|
||
| Radius button / pill | full / full | full / full |
|
||
| Bar title / tab / status / options | 32 / 26 / 24 / 36 | 38 / 30 / 30 / 42 |
|
||
| Panel header | 28 | 34 |
|
||
| Rail width / button | 40 / 30 | 50 / 36 |
|
||
|
||
Push buttons take the button radius and the pill-shaped parts take the pill radius. Both are fully rounded by default and square in Classic, and each clamps to half the part's height.
|
||
|
||
Themes never set sizes. The Size preset sets them, and apps may override them within validator limits. Adwaita, Breeze, Soft and Classic define their own corner radii and edge style (flat or bevel; only the Surface primitive reads the edge). These change how a component is drawn, not its geometry, placement or the workspace structure.
|
||
|
||
### 5.5 Elevation
|
||
|
||
Shadow levels exist for popups, dialogs, floating panels and knobs. A bevel edge has none.
|
||
|
||
### 5.6 Motion
|
||
|
||
Durations are Fast (80 ms, hover and press feedback), Normal (150 ms, most state changes) and Slow (250 ms, large surfaces opening or moving). Easings are Standard, Enter and Exit. Reduced motion sets every duration to zero.
|
||
|
||
### 5.7 Appearance and contrast
|
||
|
||
#### 5.7.1 Settings
|
||
|
||
Nine settings: theme (per mode), mode, contrast, size, text size and reduced motion are suite settings; interface font, direction and UI scaling are app settings. Options, effects and storage are in [Appendix A](#appearance-settings).
|
||
|
||
#### 5.7.2 Precedence
|
||
|
||
Each field resolves on its own, in this order:
|
||
|
||
```text
|
||
app override -> suite choice (selection.json) -> app default
|
||
(preferences) (set once any app picks it) (shipped by the app)
|
||
```
|
||
|
||
- **Theme, mode, size.** An override replaces one field, not a whole profile: an app can override only its size and still follow the suite's theme and mode. An override of the theme replaces both slots of the theme pair; a slot may name the app default.
|
||
- **Contrast, reduced motion, text size.** Suite choice only, then the built-in default (system, system, 1x). The app has neither default nor override.
|
||
- **Interface font, direction, UI scaling.** App settings only.
|
||
- **System values.** `system` resolves against what the OS reports. Mode falls back to the app's fallback mode, contrast to standard and motion to full.
|
||
- **Unknown theme.** An unknown theme id falls back to the app default's slot, then to ArtCraft.
|
||
|
||
#### 5.7.3 Contrast
|
||
|
||
Standard contrast follows each theme's design. Derived colours reach the minimums. Pinned colours that fall short are kept and reported (`craft-theme check`, the gallery token browser, a "Low contrast" label in the theme picker), never rewritten. High contrast fixes every failing pair in the table, pinned or not.
|
||
|
||
| Class | Pairs | Standard | High |
|
||
| --- | --- | --- | --- |
|
||
| Text | Text normal, muted, faint on surfaces and state fills; text on selected fills; accent text; status foregrounds; text on accent, strong accent and status solids | 4.5:1 | 7:1 |
|
||
| Non-text cue | Focus line; accent solid, check and radio marks on control surfaces; overlay stroke on its halo; marquee on its dash | 3:1 | 4.5:1 |
|
||
| State cue | Accent border of selected controls; selected anchor outline on its fill; curve and channel colours on their plot | none | 4.5:1 |
|
||
| Control edge | Field and button borders, slider tracks | none | 3:1 |
|
||
| Active popup row | The active row of a menu or list popup | 1.12:1 | 3:1 |
|
||
| No rule | Dividers, hover and pressed fills, disabled text and fills | none | none |
|
||
| Exempt | Guides, smart guides, path outlines and box lines: bare lines in a colour the user chooses | none | none |
|
||
|
||
## 6. Components
|
||
|
||
This section points to the component index. Examples and every state of each component are in the gallery ([2.1](#21-run-the-component-gallery)). Which tokens a component reads is in [Appendix A](#appendix-a-component-tokens).
|
||
|
||
### 6.1 What every component provides
|
||
|
||
- A builder API with semantic props only: no colour, pixel size or corner shape of its own. The idiom is `Type::new(required).option(..).show(ui)`. Panels take `&mut Model` in `new`. A dialog's per-pass answer is an `Outcome`; on the host it returns a `DialogResult<T>`.
|
||
- Gallery stories for every state.
|
||
- Everything in the checklist in [7.1](#71-required-for-every-component).
|
||
|
||
### Fill and content sizing
|
||
|
||
Fill propagates down a column whose width is given: a content-sized container (a `Stack::new()`) shown in a `Stack` given its width passes that width on, so a child that fills takes it, and the container with it. Where the width comes from content (a menu, popover or dialog body, a `Row`, a `Grid`, a fill container held in such a column) the column is a content column: it holds the children that fill, they never set its width, and they are shown across the width it settles on. A leaf declares that it fills with `fills()`; a container declares it with `Sizing`. A content-sized container may name a least width (`ContainerProps::least_width`) and a wrap width (`ContainerProps::wrap_width`) from size roles: its content is at least the one, and a wrapping text inside breaks its lines at the other where its room is wider, so a dialog opens at one width and only content that cannot wrap widens it. A host that shows arbitrary components (the gallery, a dialog body) offers them fill width with `fill_width()`, and a story that fills both axes takes its room from `testing::stage`, and a canvas story as tall as its content (a text being edited) from `testing::stage_fitting`.
|
||
|
||
Along a height its parent sizes from its content, a container that fills takes its content height, at most the room it is offered. Content taller than that room takes the room, and the children that fill share it, so a list scrolls above the bar under it. Inside a scrolling body the room is unbounded; a host offers a finite one with `room_height` (a gallery card offers the view's height). A `Stack` body that scrolls along y and is given its height shares its view: the children that fill its height take what the view leaves while the content is shorter than the view, and their least where it is longer, past which the body scrolls.
|
||
|
||
### 6.2 Index
|
||
|
||
[components-index.md](components-index.md) lists every registered component and pattern of the UI library crates with its shape, module and purpose. It is generated from the component registry (`cl cargo run -p craft-ui-gallery --bin components-index`), and the facade's `components_index` trial fails when the file is out of date. [contract-api.md](contract-api.md) lists the public items of the shared modules (`contract`, `runtime`, `style`, `primitives`, `layout`, `layout_components`, `testing`) and of `craft-behavior`.
|
||
|
||
### 6.3 Family components
|
||
|
||
| Crate | Components |
|
||
| --- | --- |
|
||
| `craft-color` | ColorPicker, ColorArea, ColorWheel, ColorDisc, ColorRamp, ColorPopover, SwatchPair, SwatchPalette, GradientEditor, the gradient stop rules and the gradient model |
|
||
| `craft-draw` | GradientSwatch, GradientPalette, gradient line, TransformFields, transform box, bezier paths, crop frame, perspective crop quad, pen draft |
|
||
| `craft-imaging` | LevelsEditor, CurveEditor, Histogram, warp grid |
|
||
| `craft-layers` | Layers panel, rows, filter bar, thumbnails |
|
||
| `craft-browse` | Tile grid, media bin, places, thumbnails, relink |
|
||
|
||
Other families ([3.4](#34-crate-taxonomy)) add theirs as they land.
|
||
|
||
## 7. Accessibility and translation
|
||
|
||
### 7.1 Required for every component
|
||
|
||
A component is not complete until each item has a story or test.
|
||
|
||
- [ ] **Keyboard.** Every control works from the keyboard. Behaviour follows the suite's own apps first, WAI-ARIA authoring patterns where no app has a convention.
|
||
- [ ] **Visible focus.** A keyboard-only focus ring, always visible.
|
||
- [ ] **AccessKit.** Roles, names and values on every widget (button, spin button, slider, text input, combo box, list option, radio, dialog, menu item, tab, tree item).
|
||
- [ ] **RTL.** Chrome mirrors. Sliders, number fields and key chords never mirror.
|
||
- [ ] **Reduced motion.** Animations resolve to zero.
|
||
- [ ] **Translation.** Words come from the catalog ([7.2](#72-translation-rules)).
|
||
- [ ] **Edit lifecycle.** Value controls report begin, update, commit, cancel and set. Esc restores the value held before the gesture. A drag or typing run is one undo step.
|
||
|
||
Keyboard conventions:
|
||
|
||
- Tab visits fields only in dialogs and every control elsewhere.
|
||
- A swatch palette and a guide set are one Tab stop with arrow keys inside. A tab strip is one Tab stop.
|
||
- Ctrl+Tab focuses a dialog's title row.
|
||
- Cmd or Ctrl+] and [ move the focused row in every reorderable list. F2 renames. Enter runs the row's default action.
|
||
- A step over a closed list control (an arrow, Home, End, the wheel, an AccessKit increment or decrement on `Select` or `ComboBox`) stops on the enabled entries marked as stepped (`Entry::stepped`, on by default) and skips the rest, such as a "Load…" command row. A value on none of those entries (mixed, or an entry only the open list offers) offers both steps: forward lands on the first stop, back on the last. `contract::step_stops` and `contract::step_stop` are the one rule every list control uses.
|
||
|
||
### 7.2 Translation rules
|
||
|
||
- Library words (button labels, dialog text, error text) are rows in the shared `craft-i18n` catalog (`common.tsv`). App labels win. Apps do not translate library words themselves.
|
||
- The app installs its translator through the host once per language change.
|
||
- Lookup order: the language's row, the English row, the built-in English.
|
||
- A translation with a missing placeholder is ignored.
|
||
- No test requires a translation to exist.
|
||
|
||
### 7.3 Goals beyond the required list
|
||
|
||
These guide design where no rule exists. They are not acceptance criteria.
|
||
|
||
- Size and Text size let users enlarge the interface without changing layout.
|
||
|
||
## 8. Tests and gates
|
||
|
||
### 8.1 What gets a test
|
||
|
||
Every test names the regression it guards against: a plausible change to the code that would break something without anyone noticing. If no such change comes to mind, there is no test.
|
||
|
||
Test:
|
||
|
||
- Shared mechanisms that many components rely on: the contract pipeline, measuring, focus and key routing, undo grouping, the suite's own checks. Test each once, at the mechanism.
|
||
- Logic with real room for mistakes: layout and room sharing, state machines, gesture sequences, geometry, parsing and saving our own file formats.
|
||
- A bug that was hard to find, where the fix isn't obvious from the code.
|
||
|
||
Don't test:
|
||
|
||
- Code you can verify by reading it: a few lines, a single branch, a swap, a clamp, a short loop with no state.
|
||
- Wiring: a button runs its command, a key calls a model function, a modifier picks copy instead of move.
|
||
- Defaults, getters and mappings.
|
||
- What the type system already guarantees.
|
||
- Library behaviour: egui, std, serde or any other dependency.
|
||
- Exact strings, values or sizes.
|
||
- One test per combination of cases.
|
||
- Per-component repeats of what the shared suite already checks on that type. The suite runs its shared cases on every type registered as a component; a pattern gets only the pattern trial.
|
||
|
||
Where a test goes:
|
||
|
||
- A component gets its own trial only for behaviour that is unique to it and not trivial.
|
||
- Check behaviour at the level the user meets it, through the component, not in the helpers it calls. When a user-level test already goes through a helper's code path, the helper has no test of its own.
|
||
|
||
New code follows the same rule. A new feature adds tests only for logic with real room for mistakes. A bug fix adds a test only when the bug was hard to find. A review finding needs no test case of its own.
|
||
|
||
### 8.2 Gates
|
||
|
||
| Gate | What it holds | Where |
|
||
| --- | --- | --- |
|
||
| Shared suite | The shared cases (required states, shows, access, Tab, values, mixed, activation, text size, motion, language, text input, container and collection cases) on every type registered as a component; the pattern trial on every pattern | Each library and family crate's `tests/it` binary ([authoring.md](authoring.md)) |
|
||
| Trials | Behaviour unique to a component or mechanism ([8.1](#81-what-gets-a-test)) | The same binaries |
|
||
| Gallery | Stories for every state of every component of every crate with a `ui` feature. Keep it in step with the features each app enables | `craft-ui-gallery`; its own trials cover the viewer's saved layouts and the Overview's cards |
|
||
| Components index | `docs/components-index.md` matches the registrations | The facade's `components_index` trial |
|
||
| API map | `migration/api-map/*.toml` have the shape the migration tools read ([9.8](#98-breaking-changes)) | The facade's `api_map` trial |
|
||
| Token dumps | Text files of resolved tokens per theme-mode variant, contrast (standard, high) and size (Compact, Comfortable). Rewrite with `UPDATE_DUMPS=1`; the dumps of the workspace stay under a line budget | `crates/theme/tests/dumps` |
|
||
| Facade checks | The `craft` features table matches the member crates; no family's `ui` depends on another family's `ui`; the egui fork check | `crates/craft/tests` |
|
||
| Theme check | `craft-theme check <file>`: contrast report, adjustments, invalid fields | The `craft-theme` binary |
|
||
| Design lint | `craft-design-lint check` (syn), `check-clippy` and `structure` (layer map, imports, exceptions, clones) | [8.3](#83-design-lint) |
|
||
|
||
Text dumps of every token are the regression gate for the theme. The story renderer (`cl render`) writes a component's stories to PNG files for a before-and-after look; no test compares pictures.
|
||
|
||
How to run each locally, and which of them CI runs, is in [development.md](development.md).
|
||
|
||
### 8.3 Design lint
|
||
|
||
- Rules: `literal-size/*`, `raw-colour/const`, `style-mutation`, `tooltip/stock`, `clippy/inner-allow`.
|
||
- Exemption marker: `// design: allow(reason)`. Empty, invalid and unused markers are findings.
|
||
- Baselines and `--deny-unused` are supported.
|
||
- Exit 0 clean, 1 findings, 2 error.
|
||
|
||
## 9. Migration and landing
|
||
|
||
How apps move onto the Craft framework, and how the work lands in `craft-libs`. This is a procedure document. The design is in [1](#1-overview) to [8](#8-tests-and-gates).
|
||
|
||
### 9.1 Migration strategy
|
||
|
||
Everything is built in `craft-libs` first: build each feature once, in one place, and use it one way. A feature one app has today is built in the library even when no second app needs it yet. Work goes step by step, so each step ends in a library the apps can use. It does not go family by family.
|
||
|
||
- **PhotoCraft migrates first.** It has the most UI and features. Its port branch runs on the library while the library grows.
|
||
- **VectorCraft migrates second.** It shares the Canvas shell and most of PhotoCraft's skeleton. If the two ports look alike, the library is general enough.
|
||
- **Other apps follow**, each adopting the steps it needs.
|
||
- **One branch per port.** The port adopts each step as the framework provides it and deletes the code the step replaces. The app keeps pinning `craft-libs` `main` until the port is done; the app's main branch then switches to the framework's pin once, when the port merges.
|
||
- **A gap is library work.** A gap an app finds is fixed in the library first. The port then deletes its own code. No app workaround.
|
||
- **Review as data where it is data.** Treat generated dumps, icon assets and migration maps as reviewable data, not as hand-written architecture.
|
||
|
||
### 9.2 Acceptance checklist
|
||
|
||
Every app-port step passes all of these before it counts as done:
|
||
|
||
- [ ] Tests are green.
|
||
- [ ] Every story of the step's components is complete ([7.1](#71-required-for-every-component)).
|
||
- [ ] Screenshot comparison of the app's upstream build against the port covers each screen, and every difference a user would notice has a recorded decision. Users see no significant difference, or slightly more polish.
|
||
- [ ] Design lint is clean.
|
||
- [ ] The conformance test is clean.
|
||
- [ ] The app's duplicate implementation is removed. Where the app drew one kind of component several ways, the port uses one.
|
||
|
||
### 9.3 Steps
|
||
|
||
| Step | Delivers | Depends on | Status |
|
||
| --- | --- | --- | --- |
|
||
| 0 | PhotoCraft adopts the types the library already has; gaps become library work | none | done |
|
||
| 1 | Foundations: `ui` feature names, `craft-host`, module moves into family crates, the `craft` facade, gallery and word registry over every crate, one egui revision | 0 | done |
|
||
| 2 | Dialog framework: typed results, parameter and command dialogs, size dialogs, prompts, unsaved guard, startup modal queue; text and number control gaps | 1 | done |
|
||
| 3 | Shell (dock, panel menus, floating frames, workspaces, start screen, focus regions), keymap completion, canvas core, options bar cells, testing tools | 2 | done |
|
||
| 4 | Files, preferences, text and fonts, colour, previews and jobs | 2, 3 | done |
|
||
| 5 | Common controls, system services, value formatting, guides and About, align bars | 2 | done |
|
||
| 6 | 6a: layers, presets, history, navigator, browsing. 6b: pages, timeline, review, tables | 2, 3, 4 (6a); 2, 3, 5 (6b) | 6a done; 6b built, fix pass pending |
|
||
| 7 | Canvas tools and the image-editing workspaces | 3, 4, 6a | built |
|
||
| GPU | `craft-gpu`: GPU device, diagnostics, memory budget and the GPU canvas surface; PhotoCraft moves its GPU display onto it | 2, 3 | next |
|
||
| 8 | Office-style shell, audio, code editor and console, slideshow | 2, 3; 6b timeline for audio | planned |
|
||
|
||
Size: about 185 library tasks, plus about 28 PhotoCraft tasks and about 20 VectorCraft tasks. Step 3 is about 30 library tasks, step 4 about 35, step 6 about 44.
|
||
|
||
### 9.4 Critical path
|
||
|
||
```text
|
||
2 --> 3 --> 4 --> 6a --> 7 --> PhotoCraft full port --> VectorCraft full port
|
||
| |
|
||
| +--> 5 (off the path: PhotoCraft needs only guides and About)
|
||
+--> 6b, 8 (off the path for PhotoCraft)
|
||
```
|
||
|
||
- Step 2 gates every feature that opens a dialog.
|
||
- Step 3 gates the canvas tools (7), the colour droppers and text editor (4), and every panel (6) through the dock's panel-menu host.
|
||
- Step 4's colour and font pickers gate the stroke, shape and text work in 7.
|
||
- Step 6a gates PhotoCraft's panels and the brush presets in 7.
|
||
- Steps 5, 6b and 8 run beside the path when capacity is free. Their inputs are other apps' code.
|
||
|
||
### 9.5 What each step delivers
|
||
|
||
**Step 0: adopt existing types.** PhotoCraft swaps widgets it shares in kind with the library for the library's. Each difference becomes a gap row. The port has recorded 108 gap rows. At least 26 are closed with a merged library change and 34 are scheduled in a later step. They range from a missing option on a slider row to a floating frame with no title-bar move, which is why the shell and common controls come before the tools.
|
||
|
||
**Step 1: foundations.** No pixel changes.
|
||
|
||
- The UI feature is `ui` in every crate, plus `screen-testing`.
|
||
- `craft-host` carries the services every feature reads.
|
||
- Domain code moves out of the UI library into `craft-draw`, `craft-imaging`, `craft-color` and `craft-print`.
|
||
- The `craft` facade gives one dependency and one pin.
|
||
- The gallery and word registry cover every `ui` crate.
|
||
- Each app's `xtask` checks the egui revision.
|
||
|
||
**Step 2: dialog framework.** A feature dialog is one value an app pushes and one result it reads.
|
||
|
||
- Delivers: `DialogHost` with typed `DialogResult`, `ParamDialog`, command forms, image and canvas size dialogs, confirmation prompts, `UnsavedChangesDialog`, properties and report dialogs, `PointPicker`, `Remembered<T>`, `craft-update`'s dialogs on the stack.
|
||
- PhotoCraft adopts: the stack for every dialog, parameter dialogs for filters, size dialogs, prompts, the unsaved guard, remembered options.
|
||
- PhotoCraft deletes: its dialog host and routing, parameter-dialog builder, field map, size-dialog code and prompt helpers.
|
||
|
||
**Step 3: shell, testing tools, canvas core, options bar.**
|
||
|
||
- Delivers: dock host and commands, panel menus, floating frames, Window menu and Arrange, named workspaces, start screen, region focus, shortcuts dialog, the keymap catalog as source of truth, zoom and navigation, cursors, snapping, raster display, the on-canvas tool host, options bar cells with scrubbing, `craft-automation`, the render harness.
|
||
- PhotoCraft adopts: the library dock, workspaces, `ScreenMode`, the shortcut catalog and dialog, canvas navigation, the tool host, options bar cells, automation.
|
||
- PhotoCraft deletes: its dock, panel-menu popups, floating card frames, shortcuts table, zoom ladder, cursor host, momentary-key and snapping code, options bar cell code, screenshot queue and control channel.
|
||
- VectorCraft maps to library components during this step. Its gaps feed the specs of steps 4 to 7.
|
||
|
||
**Step 4: files, preferences, text and fonts, colour, previews.**
|
||
|
||
- Delivers: the file service, New Document, export dialogs, print, file intake; preferences over a settings document with `AppearancePage` and recovery; font picker, canvas text editor, style panels; colour picker dialog, droppers, samplers, screen picker, swatch panel, palettes, CMS additions; preview panes and job progress.
|
||
- PhotoCraft deletes: its file dialogs, most preferences code, recovery and path code, family picker, colour panel and picker bodies, job UI.
|
||
- VectorCraft adopts steps 1 to 4 on its port branch in one pass.
|
||
|
||
**Step 5: common controls, system services, value formatting, guides, About.** A small step for PhotoCraft.
|
||
|
||
- Delivers: sortable tables, chips, date and tree pickers, linked fields, mixed values, split button, breadcrumb, rating; clipboard, file watcher, default-app registration, temp files, Save flow; dates, byte sizes and elision; New Guide and Guide Layout dialogs, About, align bars.
|
||
- PhotoCraft adopts guides, About, align bars, linked size fields, clipboard and the Save flow.
|
||
|
||
**Step 6: layers, presets, history, browsing (6a); pages, timeline, review, tables (6b).** 6a is on PhotoCraft's path. 6b serves other apps.
|
||
|
||
- 6a delivers: `LayersPanel` over a `LayerTree` trait, channels, the preset model and menus, a history panel with one-edit steps and snapshots, navigator, scopes, actions, thumbnails, browsing. PhotoCraft's panels then all run in the library dock; it deletes its layer, history, navigator and histogram panels and its preset model.
|
||
- 6b delivers: paged documents, timeline, comments and versions, spreadsheet tables. VectorCraft adopts layers and presets after 6a, and artboard lists after 6b.
|
||
|
||
**Step 7: canvas tools and image-editing workspaces.** PhotoCraft's last large deletion.
|
||
|
||
- Delivers: transform, warp, selection and mask tools, vector and shape tools, crop, measure, brush, and the full-window editors (select and mask, liquify, filter gallery, fill from surroundings, perspective plane, wide-angle correction, layer style, adjustments).
|
||
- PhotoCraft adopts every tool through the library tool host. Its port then runs the lint clean and passes conformance and the render matrix.
|
||
- VectorCraft adopts the draw family and finishes its port.
|
||
|
||
**GPU canvas.** `craft-gpu` delivers the GPU device, diagnostics, memory budget and the GPU canvas surface. PhotoCraft's only task is to move its GPU display onto it. Nothing visible changes.
|
||
|
||
**Step 8: office-style shell, audio, code editor, slideshow.** Mostly other apps' code.
|
||
|
||
- Delivers: ribbon, backstage view, keytips and the office-style preset; audio engine and mixer UI; code editor and console; slideshow presenter.
|
||
|
||
### 9.6 Documentation for each step
|
||
|
||
Each step also adds its families to the library docs: a page per family with the out-of-the-box recipe (the `Host`, the trait the app implements, the builder call, the `Outcome`) and a migration table from old path to new path.
|
||
|
||
### 9.7 Landing strategy
|
||
|
||
The framework lands on one storytold branch, `next`, and reaches `main` in one pull request at the end.
|
||
|
||
- **`next`.** Finished work goes to `storytold/craft-libs` branch `next` by fast-forward. CI runs on pushes to `next` (the Linux jobs, [development.md](development.md)).
|
||
- **Apps pin `main`.** An app keeps its `craft-libs` pin on `main` until its port is done. It then moves its pin to a `next` commit, and to `main` after `next` merges.
|
||
- **`main` flows into `next`.** `main` is merged into `next` regularly with merge commits. `next` is never rebased or force-pushed.
|
||
- **egui.** The egui fork works the same way: `storytold/egui` branch `next` ([3.7](#37-one-egui-revision)).
|
||
- **One PR at the end.** When the apps that need the framework are ported, `next` merges to `main` through one pull request. It merges only when every check has finished green.
|
||
|
||
The size of the change, measured on 11 November 2026 as the difference between `next` (with the work due to land on it) and its merge base with storytold `craft-libs` `main` (`a8b996d2`):
|
||
|
||
| Measure | Value |
|
||
| --- | --- |
|
||
| Files changed | 4,371 |
|
||
| Lines added | about 508,000 |
|
||
| Lines removed | about 128,000, of which about 42,000 in the old `crates/ui` (moved into the library crates) |
|
||
| UI library, `craft-behavior` and `craft-theme`: lines added | about 228,000 |
|
||
| Generated token dumps (`crates/theme/tests/dumps`) | about 17,000 lines |
|
||
| Docs and migration maps (`docs/`, `migration/`) | about 38,000 lines |
|
||
| Icon set files | about 700 (four sets: Phosphor, Lucide, Tabler, Carbon) |
|
||
| New crates | 29 |
|
||
|
||
A review reads dumps, icons and the migration maps as data.
|
||
|
||
The layers reach `next` bottom-up, so each push builds and passes CI:
|
||
|
||
| Order | Layer | Contents |
|
||
| --- | --- | --- |
|
||
| 1 | egui patches | The fork's commits go to `storytold/egui` branch `next`; `craft-libs` moves its egui pin to it ([3.7](#37-one-egui-revision)). Everything else depends on this |
|
||
| 2 | Icon sets | Data only |
|
||
| 3 | Token model and themes | `craft-theme`, `craft-theme-store`, `craft-color`. New crates; nothing depends on them yet |
|
||
| 4 | Library core | `craft-behavior`, `craft-ui-macros`, `craft-ui-contract` (runtime, style, primitives, contract, test kit), `craft-ui-widgets` |
|
||
| 5 | Panels, canvas, patterns, shell | `craft-ui-panels`, `craft-ui-canvas`, `craft-ui-patterns`, `craft-ui-shell`, the `craft-ui` facade, with `craft-draw` and `craft-imaging` |
|
||
| 6 | Host, facade and changes to existing crates | `craft-host`, `craft`, and changes in `craft-menu`, `craft-keymap`, `craft-window` and `craft-platform` |
|
||
| 7 | Tooling | The gallery, the story renderer, `craft-design-lint` |
|
||
|
||
Layer 5 replaces upstream's `craft-ui` crate (egui controls and icon catalogs) with the facade; [9.8](#98-breaking-changes) covers what that breaks.
|
||
|
||
**Timing.** The first push to `next` carries every layer that is finished. Later work follows as it passes its checks. A layer's API is shared once it is on `next`, and changes to it need the same care as any breaking change.
|
||
|
||
### 9.8 Breaking changes
|
||
|
||
The library replaces upstream's `craft-ui` crate, and changes public items in `craft-menu`, `craft-keymap`, `craft-window` and `craft-platform`. An app meets these changes when it moves its pin from `main` to `next`. What exists for apps that move their pin:
|
||
|
||
- **The facade.** `crates/ui` is the `craft-ui` package, a re-export facade over the six library crates, so an app keeps one dependency and `craft_ui::…` paths. Upstream `craft-ui`'s modules `capture`, `combo`, `direction`, `icons`, `ime`, `localized`, `panes`, `printing` and `theme` are gone; `buttons`, `docking`, `fonts`, `layout`, `tabs`, `testing` and `text` keep their names and hold the library's types.
|
||
- **The API map.** `migration/api-map/*.toml`, one file per family, lists each public type and function an app calls today: its old path, its new path, setter renames, and a status (`same`, `moved`, `replaced` with a note, `removed`, or `pending`). About 2,900 entries; 19 are still `pending`. The facade's `api_map` trial checks the files' shape. `migration/check-crates.txt` lists the domain crates and features a compile check builds.
|
||
- **No deprecated aliases.** No old path is kept as a `#[deprecated]` alias or shim: an app's pin bump past layer 5 needs the app's code moved to the new paths in the same change.
|
||
|
||
### 9.9 Status and open questions
|
||
|
||
#### What exists
|
||
|
||
| Area | State |
|
||
| --- | --- |
|
||
| Token model, ten built-in themes, store, bridge | built |
|
||
| Primitives, controls, composites, patterns | built |
|
||
| Canvas shell, docking with iconic column and flyouts, title bar | built |
|
||
| Dialog frame, prompts, full-window dialogs, preferences window, typed dialog stack | built |
|
||
| `craft-color`, `craft-draw`, `craft-imaging`, `craft-layers`, `craft-browse`, `craft-automation`, `craft-pages`, `craft-review`, `craft-table`, `craft-timeline` | built |
|
||
| `craft-host`, the `craft` facade, one egui revision check | built |
|
||
| UI library as six crates and the `craft-ui` facade, the API map | built |
|
||
| Gallery with Components and Theme workspaces, Variants, app preview; the story renderer | built |
|
||
| `cl` build loop with one feature set, dev and `gallery` profiles ([development.md](development.md)) | built |
|
||
| Design lint, `craft-theme check` | built |
|
||
| PhotoCraft | Builds against the library through step 6a and is moving its dialogs onto it. Most panels, dialogs, canvas overlays and adjustment editors are still its own code, restyled by the theme |
|
||
| macOS | The port builds on macOS; window, title bar and menu bar checks pass |
|
||
| Comparison | Screenshots of 59 screens, current PhotoCraft beside the port, refreshed after each port batch |
|
||
|
||
#### What is next
|
||
|
||
1. The GPU canvas (`craft-gpu`).
|
||
2. PhotoCraft's dialogs on the library, completing its port.
|
||
3. VectorCraft's port, then the other apps.
|
||
4. The `next` pushes, starting with the egui commits.
|
||
|
||
#### Questions for the team
|
||
|
||
| Topic | Question |
|
||
| --- | --- |
|
||
| Deprecated aliases | No old path has a deprecated alias; apps move with the API map in the pin bump that takes the library. Should `next` add `#[deprecated]` aliases for the paths apps use (the icon-button and combo-box modules, the old rail and number-field types), and for how long: until every app has moved past them, or a fixed number of releases? |
|
||
| egui fork | The library builds against storytold egui `next` (28 commits over the fork's pin on `main`, [3.7](#37-one-egui-revision)). Which of them should go to upstream egui? |
|
||
| Facade name | `craft` is the facade's name. If it clashes with an app crate, the alternative is `craft-kit` |
|
||
| Crate granularity | The layout adds 29 crates to the workspace. Is there a family that should merge, or a crate that should split? |
|
||
|
||
## Appendix A. Component tokens
|
||
|
||
Maintainer reference. The rule is in [5.4 Dimensions](#54-dimensions): components name semantic tokens, and semantic tokens pick from the scale. This page lists which role each component takes.
|
||
|
||
### Semantic colour tokens
|
||
|
||
| Group | Tokens |
|
||
| --- | --- |
|
||
| Surface | background, canvas, canvas pattern, chrome, panel, raised, sunken, knob, scrim, shadow |
|
||
| Text | normal, muted, faint, disabled, on accent, on strong, on selected, on status |
|
||
| Line | divider, border, control edge, knob edge, mark, focus |
|
||
| Accent | solid, hover, pressed, strong (+ hover, pressed), soft, text |
|
||
| Status | good, warn, bad, info, each with fg, bg, border, solid |
|
||
| State | hover, pressed, selected, selected hover, disabled fill, stripe |
|
||
| Canvas overlay | stroke, halo, handle, marquee, guide, grid |
|
||
| Data | 8 series; histogram R, G, B, luma |
|
||
|
||
The strong accent pair fills the menu highlight, primary buttons and solid accent badges.
|
||
|
||
### Appearance settings
|
||
|
||
| Setting | Options | Changes | Stored |
|
||
| --- | --- | --- | --- |
|
||
| Theme | 10 built-ins or a JSON file, per mode (`theme_light`, `theme_dark`) | Colours; shape for four themes | Suite |
|
||
| Mode | light, dark, system | Palette | Suite |
|
||
| Contrast | standard, high, system (default) | Contrast minimums | Suite |
|
||
| Size | Compact, Comfortable | Heights, padding, gaps, type, corners | Suite |
|
||
| Text size | 0.83x, 1x, 1.17x, 1.33x | Type only | Suite |
|
||
| Reduced motion | full, reduced, system (default) | Animations to zero | Suite |
|
||
| Interface font | Suite face, System | UI face | App |
|
||
| Direction | Language (default), LTR, RTL | Mirroring; sliders, number fields and key chords never mirror | App |
|
||
| UI scaling | Auto, or 75 to 300 % (steps of 5 from 75 to 125, then 150, 175, 200, 250, 300) | Whole-interface zoom | App |
|
||
|
||
UI scaling omits sizes that would shrink the window below the app's minimum on the current screen; the size in use stays listed. Every app has a "Reset UI Scaling" command. Pointers an app draws grow with the scale.
|
||
|
||
### Built-in themes
|
||
|
||
Ten themes, 17 mode variants. The suite default is ArtCraft.
|
||
|
||
| Theme | Modes | Look |
|
||
| --- | --- | --- |
|
||
| ArtCraft | light, dark | Mid-grey panels; suite default |
|
||
| Pro | light, dark | Neutral greys |
|
||
| Pro Light Gray | light | Light grey panels |
|
||
| Graphite | light, dark | Near-black fields in dark |
|
||
| Studio | light, dark | PhotoCraft Studio colours |
|
||
| Solarized Dark | dark | Muted teal-tinted dark |
|
||
| Adwaita | light, dark | Rounded, light grey; radii 6 / 9 / 12 |
|
||
| Breeze | light, dark | Flat; 5 px corners |
|
||
| Soft | light, dark | Low contrast (declared); corners rounder by +1 / +2 / +2 |
|
||
| Classic | light | Square, bevelled; 1 pt bevel, all radii 0 |
|
||
|
||
### Generic or family placement
|
||
|
||
| Component | Placed in | Reason |
|
||
| --- | --- | --- |
|
||
| Button, Slider, List, Tab strip | `craft-ui-widgets` | General inputs |
|
||
| Menu | `craft-ui-widgets` (`menu`) | Takes rows and shortcuts; the app supplies the commands |
|
||
| Preset browser | `craft-ui-patterns` (`patterns::presets`) | Works on a generic preset library model |
|
||
| Canvas overlays: grid, guides, smart guides, marquee, rulers | `craft-ui-canvas` (`canvas`, `canvas_controls`) | Draw over any canvas; no document type |
|
||
| Crop frame, gradient overlay, transform box, bezier paths | `craft-draw` | Need shape and gradient types |
|
||
| Colour picker, wheel, swatch palette | `craft-color` | Need colour models |
|
||
| Levels editor, curve editor, histogram, warp grid | `craft-imaging` | Need image-adjustment types |
|
||
| Layers panel | `craft-layers` | Needs the `LayerTree` trait |
|
||
|
||
### Docking details
|
||
|
||
- Panels live as tabs in an expanded dock column or as icons in a collapsed (iconic) column, never both.
|
||
- A click on an icon opens its group in a flyout beside the column.
|
||
- Dialogs move by their title only.
|
||
- A floating panel group has square corners and the floating shadow.
|
||
|
||
### Radius roles
|
||
|
||
| Role | Components |
|
||
| --- | --- |
|
||
| `radius.control` | Fields, small controls, buttons that are not pills |
|
||
| `radius.surface` | Popups, menus, dialogs |
|
||
| `radius.window` | Windows, dialogs |
|
||
| `radius.panel` | Docked panels and side columns; themes round them or keep them square |
|
||
| `radius.button` | Push buttons. `full` in the built-in size sets; Classic sets it to 0 |
|
||
| `radius.pill` | Switch and slider tracks and knobs, progress bars, badges. Clamps to half the part's height; Classic sets it to 0 |
|
||
|
||
A theme with its own shape replaces the radii or adds an offset to control, surface and window. Panel, button and pill are not offset.
|
||
|
||
`shape.knob` is the shape of a value track's thumb (Slider, RangeSlider): `round`, the control's glyph across, or `tab`, an upright tab the control's icon side tall. Classic sets `tab`.
|
||
|
||
`shape.wells` is the shape of a colour well that stands on its own (SwatchPair's foreground and background): `square`, with the small radius, or `round`, a circle. Adwaita, Breeze and Soft set `round`.
|
||
|
||
### Size roles
|
||
|
||
| Role | Components |
|
||
| --- | --- |
|
||
| `size.control.sm`, `size.control.md` | Controls, fields, buttons |
|
||
| `size.icon.sm`, `size.icon.md`, `size.icon.lg` | Icons; `md` is the glyph of a tool strip and of a panel footer's actions (`GlyphRole::Tool`), `lg` of a tool rail (`GlyphRole::ToolRail`). A stroke-set icon draws its line `stroke.icon` of its side |
|
||
| `size.icon.glyph_sm`, `size.icon.glyph_md` | The glyph in an icon-only button (`GlyphRole::Control`, the default; a container sets another with `ContainerProps::child_glyphs`) |
|
||
| `size.bar.title`, `size.bar.tab`, `size.bar.status`, `size.bar.options`, `size.bar.options_narrow` | Title bar, document tab bar, status bar, options bar |
|
||
| `size.panel_header` | Panel headers |
|
||
| `size.popup_min` | Least width of a popup surface (menus only; popup lists such as Select and ComboBox take their anchor's width) |
|
||
| `size.scroll_fade` | Length of the fade at an edge of a scroll region past which its content continues |
|
||
| `size.groove` | Groove of a value track |
|
||
| `size.ramp.bar` | Colour band: a gradient ramp drawn as a bar of its own (levels output bar, gradient thumb row) or as the face of a triangle-pointer channel slider |
|
||
| `size.ramp.groove` | Gradient drawn as the groove of a value track (faced sliders) and the span between two thumbs of a gradient's thumb row |
|
||
| `size.rail.width`, `size.rail.button` | Tool rail and panel rail |
|
||
| `size.length.field.sm`, `size.length.field.md` | Text or value field, one width per control size: a field in a small options bar is narrower than one in a dialog |
|
||
| `size.length.number.sm`, `size.length.number.md` | Number field and the number cell over a slider, one width per control size |
|
||
| `size.length.track`, `size.length.short` | Value track, short field |
|
||
| `size.row.text` | A row that shows text only: one body line and `space.gap.tight`; read-only display tables take it, lists the user picks from keep control-high rows |
|
||
| `size.notice.width` | Width of a toast card where the room allows |
|
||
| `size.dialog.least`, `size.dialog.wrap` | A dialog's content: the least width it opens at, and the line length its paragraphs wrap at (`LeastWidth::Dialog`, `WrapWidth::Dialog`); content that cannot wrap widens it past that |
|
||
| `size.dialog.button`, `size.dialog.side_button` | Least width of a dialog's footer button and of a button in its column beside the body |
|
||
| `size.story.height`, `size.story.width_min`, `size.story.width_max` | The stage a story of a canvas control draws its canvas on: its height and the range of its width; `width_min` is also the least width of a column of a story grid |
|
||
| `size.hit.edge` | The band inside the edge of a canvas's view in which a tool that autoscrolls on hover scrolls the view (a Polygonal Lasso's rubber band), at most a quarter of the view's shorter side |
|
||
| `size.thumb.card` | The picture side of a tile card at zoom 1 (tile grids, preset browsers, the start screen) |
|
||
| `size.thumb.sample.sm`, `size.thumb.sample.md`, `size.thumb.sample.lg` | The sample beside each thumbnail size choice in a panel's options dialog (Layers, Channels, Paths): larger than the panel's thumbnails, so the choices read apart (`PictureSize::Sample`) |
|
||
| `space.gap.*`, `space.pad.*` | Gaps between and padding inside components |
|
||
|
||
Both size sets (`crates/theme/sizes/compact.json` and `comfortable.json`) hold every role above. A field holds a number of characters, so `size.length.field`, `size.length.number` and `size.length.short` grow with the text size by the same factor as the type; `size.length.track` holds no text and keeps its length. NumberField is at least `size.length.number` at its control size wide; apps set other widths per field.
|
||
|
||
## Appendix B. Crate and module layout
|
||
|
||
Maintainer reference. The concepts are in [3. Architecture](#3-architecture). Crates are alphabetical, and modules are alphabetical inside each crate. The State column says whether a module exists in the repository, is planned, or is next, and in which migration step (see [Migration and landing](#9-migration-and-landing)). Crates without an entry (the file-format envelopes, `craft-doc`, `craft-proof`, `craft-web-api`, `craft-web-host`, `craft-media-testkit`) are described in their README.
|
||
|
||
Conventions:
|
||
|
||
- Crates are `craft-<family>`, one word where possible. No `-ui` or `-core` suffix on a family. The UI library's crates are `craft-ui-<layer>`.
|
||
- Modules are nouns, one level below the crate root. `ui` is the only module that nests a second level (`craft_pages::ui::table`).
|
||
- Types carry their full name (`LayersPanel`, not `layers::Panel`), so they read the same wherever they are imported.
|
||
- In a family crate, a module `ui::x` is the egui side and a bare `x` is core.
|
||
|
||
29 crates are new relative to storytold main: `craft`, `craft-automation`, `craft-behavior`, `craft-browse`, `craft-color`, `craft-design-lint`, `craft-draw`, `craft-font-subset`, `craft-host`, `craft-imaging`, `craft-layers`, `craft-pages`, `craft-review`, `craft-table`, `craft-theme`, `craft-theme-store`, `craft-timeline`, `craft-ui-bench`, `craft-ui-canvas`, `craft-ui-contract`, `craft-ui-gallery`, `craft-ui-macros`, `craft-ui-panels`, `craft-ui-patterns`, `craft-ui-shell`, `craft-ui-test-kit`, `craft-ui-widgets`, `craft-win32` and `story-render`. `craft-ui` keeps upstream's package name as the library's facade. `craft-gpu` is the next step, and `craft-code` is planned.
|
||
|
||
### Facade features
|
||
|
||
| Feature | Meaning |
|
||
| --- | --- |
|
||
| `ui` | The family's egui side, on `craft-ui`. The only UI feature name in every crate. The facade's `ui` turns on `?/ui` for every enabled family |
|
||
| `screen-testing` | Stories and snapshot tests; implies `ui` |
|
||
| `egui` | Converts a crate's types to egui's without `craft-ui`, where that is the whole feature (the model is `craft-theme`'s `ecolor`) |
|
||
| `serde`, `collab`, per-service features | Keep their names. `craft-platform` has one feature per service (`job`, `clipboard`, ...) |
|
||
|
||
### Host service rules
|
||
|
||
| Rule | Detail |
|
||
| --- | --- |
|
||
| Settings keys | Each feature exports a `serde` struct with a `const KEY`, which the app embeds in its settings file through `craft-settings` |
|
||
| Words | Library words are rows in the shared `craft-i18n` catalog, looked up through the host |
|
||
| Commands | A feature exports its command catalog. The app registers it with `craft-keymap` |
|
||
| Files | Features ask the host to pick, read and write. Native apps implement the service natively; web apps implement it over the browser |
|
||
|
||
### Where each concept lives
|
||
|
||
| Concept | Crate | Module (facade path) | More |
|
||
| --- | --- | --- | --- |
|
||
| Tokens, themes, contrast | `craft-theme` | `craft_theme` | [suite-themes.md](suite-themes.md) |
|
||
| Tokens to egui styling | `craft-ui-contract` | `craft_ui::style` | [4.2](#42-ownership) |
|
||
| Component contract, pipeline, `Lazy`, list entries | `craft-ui-contract` | `craft_ui::contract` | [authoring.md](authoring.md), [contract-api.md](contract-api.md) |
|
||
| Passes, focus, keys, layout memory, out-of-view content | `craft-ui-contract` | `craft_ui::runtime` | [3.6](#36-runs-and-passes) |
|
||
| Behaviour cores, edit events, dock model | `craft-behavior` | `craft_behavior` | [ui-docking.md](ui-docking.md) |
|
||
| Services an app installs | `craft-host` | `craft_host` (`craft::host`) | [3.5](#35-the-host-convention-services-in-edits-out) |
|
||
| Components | `craft-ui-widgets` | `craft_ui::{buttons, pickers, list, …}` | [components-index.md](components-index.md) |
|
||
| Dialogs and the dialog stack | `craft-ui-panels`, `craft-ui-canvas` (full-window) | `craft_ui::dialog` | [ui-dialogs.md](ui-dialogs.md) |
|
||
| Docking parts; dock areas and task panes | `craft-ui-panels`; `craft-ui-patterns` | `craft_ui::docking`; `craft_ui::patterns::dock` | [ui-docking.md](ui-docking.md) |
|
||
| Canvas, tools, canvas controls | `craft-ui-canvas` | `craft_ui::{canvas, canvas_controls}` | |
|
||
| Ready-made dialogs, presets, preferences | `craft-ui-patterns` | `craft_ui::patterns` | |
|
||
| App shell, title bar, eframe entry | `craft-ui-shell` | `craft_ui::shell` | [4.4](#44-patterns-and-shells) |
|
||
| Test kit: fixture, suite, stories, snapshots | `craft-ui-contract` (and each crate's helpers) | `craft_ui::testing` | [authoring.md](authoring.md), [8](#8-tests-and-gates) |
|
||
| Story viewer; story renderer | `craft-ui-gallery`; `story-render` | | [development.md](development.md) |
|
||
| Lint rules | `craft-design-lint` | | [8.3](#83-design-lint) |
|
||
| egui fork check | `craft` | `craft::egui_fork` | [3.7](#37-one-egui-revision) |
|
||
|
||
#### craft
|
||
|
||
The facade. New on the branch (step 1).
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `egui_fork` | Lockfile check: the egui revision matches the library's | exists |
|
||
| `prelude` | `AppInfo`, `Host`, `Section`, `Tokens`, `DialogStack`, `Outcome` | exists |
|
||
| crate re-exports | One module per crate, features forwarded | exists |
|
||
|
||
#### craft-ai-core
|
||
|
||
Shared data model for AI connections, roles, requests and jobs. No egui.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `capability` | Modalities and what can be done to data | exists |
|
||
| `catalog`, `model`, `picks` | Models, what each can do, which to suggest for a job | exists |
|
||
| `connection`, `consent`, `endpoint`, `secret` | Where work is sent, what leaves the machine and whether the user agreed, secrets that cannot print | exists |
|
||
| `conformance`, `mock` | Checks every provider must pass; a scripted provider for tests | exists |
|
||
| `draft`, `store` | The "add a connection" form model; the shared versioned store | exists |
|
||
| `error`, `ids`, `job`, `history` | Error type, validated ids, job progress, request history | exists |
|
||
| `models` | Downloadable model manager | planned, step 4 |
|
||
| `payload`, `provider`, `request`, `role`, `spec` | The provider trait, requests and payloads, roles, declarative routes | exists |
|
||
| `ui::models`, `ui::settings` | Model download UI; AI settings page | planned, step 4 |
|
||
|
||
#### craft-atomic
|
||
|
||
Crash-safe atomic file writing. One module at the root; exists.
|
||
|
||
#### craft-audio
|
||
|
||
Audio file I/O and codecs (WAV and AIFF read and write, FLAC encoding) and waveform peaks, from upstream ([README](../crates/audio/README.md)). Step 8 adds the audio device, meter ballistics and the mixer UI.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `buffer`, `layout`, `pcm`, `read`, `track`, `wav`, `write` | Sample buffers, channel layouts, file reading and writing | exists |
|
||
| `peaks` | Waveform peaks | exists |
|
||
| `db` | dB value text | planned, step 8 |
|
||
| `meter` | Meter ballistics | planned, step 8 |
|
||
| `output` | Output stream and device setup | planned, step 8 |
|
||
| `ui::controls` | Fader and pan knob | planned, step 8 |
|
||
| `ui::meter` | Level meter | planned, step 8 |
|
||
| `ui::mixer` | Channel strip mixer | planned, step 8 |
|
||
| `ui::panner` | Surround panner | planned, step 8 |
|
||
| `ui::piano_roll` | Piano-roll note editor | planned, step 8 |
|
||
| `ui::response` | Frequency response plot and editor | planned, step 8 |
|
||
| `ui::waveform` | Waveform view | planned, step 8 |
|
||
|
||
#### craft-automation
|
||
|
||
Control channel, screenshot queue, profiler and recorded actions for tests and scripting. Native only. New on the branch.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `actions`, `ui::actions` | Recorded actions and the actions list | exists |
|
||
| `control` | Automation control channel | exists |
|
||
| `args` | Command-line values and environment fallbacks of the control channel | exists |
|
||
| `protocol` | JSON-lines wire format and parameter validators | exists |
|
||
| `security` | Tokens, the authentication handshake (challenge or one-frame token) and transport limits | exists |
|
||
| `server` | Loopback JSON-lines TCP transport (native): `listen`, `serve`, stopped by dropping its `Listening` | exists |
|
||
| `agents`, `ui::agents` | AI agents in the open window: the agent settings, the ArtCraft Launcher's switch, the connection file, the link host and the Agents page of Preferences | exists |
|
||
| `client` | JSON-lines client for tests and command-line tools (native) | exists |
|
||
| `synthetic` | Synthetic pointer and keyboard input: `ui.click`, `ui.move`, `ui.key`, `ui.type` | exists |
|
||
| `dialogs` | `ui.dialog.set`, `ui.dialog.confirm` and `ui.dialog.cancel` over a `DialogHost` | exists |
|
||
| `profiler` | Frame profiler | exists |
|
||
| `screenshot` | Screenshot request queue | exists |
|
||
| `trace` | Frame timing trace | exists |
|
||
|
||
Agents in the open window. The ArtCraft Launcher's *Settings › AI agents › Let AI agents use Craft apps* is the one switch for every Craft app: with the suite's `AI-MCP` flag on, an app lets agents in when the launcher's app list (`craft-ai-agents`) names it, which `AgentSwitch` watches on a thread; without the flag, the app's own earlier consent decides. While agents may connect, the app's `AgentLink` runs a control server on loopback with the settings' port and the token kept in the settings folder, and publishes `agent-connection.json` there (port, process id, token file, app version). The app's `<id>-cli mcp` reads that file on every tool call and authenticates with the challenge handshake, so an MCP client's configuration holds no port and no token. The handshake's proof labels are `photocraft-control-v1 server` and `photocraft-control-v1 client`, the wire label of version 1 of the protocol. The Agents page of Preferences (`AgentsPage`) is a custom page over the same settings; it has no switch of its own.
|
||
|
||
#### craft-behavior
|
||
|
||
The behaviour cores of the UI library (layer 1), with no egui and no `Context`: press lifecycle, `ValueDrag`, navigation, item layouts, edit events, overlay placement, fitting and the dock model ([ui-docking.md](ui-docking.md)). Public modules, with the main types at the crate root: `anchor`, `arrangement`, `canvas`, `codec`, `columns`, `command`, `cursor`, `divider`, `doc_key`, `dock`, `edit_history`, `editor`, `eviction`, `fit`, `flow`, `focus`, `geometry`, `grid`, `hit`, `input`, `intent`, `item_layout`, `item_marquee`, `item_source`, `keys`, `label_column`, `layout_memory`, `monitor`, `motion`, `nav`, `one_press`, `overlay`, `part`, `pixel_size`, `placement`, `press`, `quantity`, `role_rule`, `scroll`, `selection`, `sense`, `sizing`, `typing`, `value`, `value_drag`, `wheel`. Every public item is listed in [contract-api.md](contract-api.md).
|
||
|
||
#### craft-browse
|
||
|
||
Thumbnails, media bin, tile grid, places and in-app file browsing. New on the branch.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `browser`, `ui::browser` | In-app file browser | planned, step 4 |
|
||
| `places`, `ui::places` | Folder places tree | exists |
|
||
| `thumbs` | Thumbnail loader and cache | exists |
|
||
| `ui::bin` | Media bin browser | exists |
|
||
| `ui::compare` | Image compare tile | exists |
|
||
| `ui::grid` | Thumbnail tile grid | exists |
|
||
| `ui::relink` | Linked files and relink dialog | exists |
|
||
|
||
#### craft-cms
|
||
|
||
Colour management: ICC v2 and v4 profiles, transforms, rendering intents. No egui.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `builtin`, `synth` | Built-in and synthetic CMYK profiles | exists |
|
||
| `clut`, `curve`, `lut3d`, `lutfile` | Lookup tables, tone curves, display LUTs, creative LUT files | exists |
|
||
| `convert` | CMYK models and gamut conversions the colour dialogs need | exists |
|
||
| `gamut` | Gamut checks against a proof profile | exists |
|
||
| `math` | Matrices, XYZ and Lab, chromatic adaptation | exists |
|
||
| `pipeline`, `transform` | Evaluation pipelines; transforms with intents and black point compensation | exists |
|
||
| `profile`, `write` | ICC profile model and reader; v4.3 writer | exists |
|
||
|
||
#### craft-code
|
||
|
||
Code editor field and console. UI-only family. New crate.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `ui::console` | Script console panel | planned, step 8 |
|
||
| `ui::editor` | Syntax-coloured code field (syntax colours as a `data.code.*` token family) | planned, step 8 |
|
||
|
||
#### craft-color
|
||
|
||
Colour for apps: picker, wells, swatch tables, ramps, hex field. New on the branch.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `display` | Display transform on `craft-cms` | exists |
|
||
| `gray` | Grey level of a colour | exists |
|
||
| `harmony` | Colour harmony and saved themes | exists |
|
||
| `hex` | Hex text for colours | exists |
|
||
| `mode` | What a colour area and its strip show | exists |
|
||
| `palette` | Palette data | exists |
|
||
| `ui::area`, `ui::strip` | 2D colour area and its strip | exists |
|
||
| `ui::choice` | Colour choice: named colours plus Custom | exists |
|
||
| `ui::disc`, `ui::wheel`, `ui::ramp` | Colour disc, wheel and ramp | exists |
|
||
| `ui::droppers`, `ui::eyedropper`, `ui::samplers`, `ui::screen_picker` | Dialog droppers, eyedropper tool, sample points, screen picker | exists |
|
||
| `ui::gradient` | `GradientEditor`, the stop rules and the gradient model | exists |
|
||
| `ui::harmony` | Harmony wheel | exists |
|
||
| `ui::hex`, `ui::readout` | Hex field and channel readout | exists |
|
||
| `ui::lut_picker` | LUT picker | exists |
|
||
| `ui::paint_chip` | Paint chip | exists |
|
||
| `ui::paints` | Paint list | planned, step 4 |
|
||
| `ui::pair` | Foreground and background swatch pair | exists |
|
||
| `ui::palette` | Swatch palette | exists |
|
||
| `ui::panel` | Colour panel modes and menus | exists |
|
||
| `ui::picker`, `ui::popover` | The colour picker and its popover | exists |
|
||
| `ui::picker_dialog` | The complete colour picker dialog | exists |
|
||
| `ui::profile_prompts` | Profile mismatch prompts | exists |
|
||
| `ui::swatches` | Swatch panel | exists |
|
||
| `web` | Web-safe colours | exists |
|
||
|
||
#### craft-crw
|
||
|
||
Clean-room decoder for one camera raw format. `tables` holds frozen entropy-code data. Exists; no change.
|
||
|
||
#### craft-design-lint
|
||
|
||
Lint for app UI code: the clippy template that blocks stock egui widgets and raw colours, and the `syn` checker for literal sizes. New on the branch.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `baseline` | Baseline files for existing findings | exists |
|
||
| `clippy` | Check that an app's `clippy.toml` carries the template | exists |
|
||
| `config` | Lint configuration | exists |
|
||
| `markers` | `// design: allow(reason)` markers | exists |
|
||
| `report` | Findings output | exists |
|
||
| `rules` | Rule implementations | exists |
|
||
|
||
#### craft-dialogs
|
||
|
||
Native file and message dialogs that never block the event loop.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `filter` | File-type filters matching any letter case | exists |
|
||
| `macos` | macOS presentation | exists |
|
||
| `native` | Native dialogs on a worker thread | exists |
|
||
| `save` | Save and Save As flow with guards | exists |
|
||
| `service` | File dialog service behind the host's files | exists |
|
||
| `ui::path_field` | Path field with Browse | exists |
|
||
|
||
#### craft-docpath
|
||
|
||
Decides whether a stored path or URL refers to a local file. Exists.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `links` | Linked files, for relink | exists |
|
||
| `names` | Safe file names | exists |
|
||
|
||
#### craft-draw
|
||
|
||
Vector and shape tools, pen, stroke, gradient, crop, measure, symmetry, brush presets and free transform. UI-only family. New on the branch (step 1).
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `ui::add_beside`, `ui::artboard` | Add-beside buttons; artboard tool, bar and properties | exists |
|
||
| `ui::brush_presets`, `ui::brush_settings` | Brush preset picker, cards and chip; brush settings panel | exists |
|
||
| `ui::connector` | Connector tool, overlay and bar | exists |
|
||
| `ui::corner` | Corner radius widgets | exists |
|
||
| `ui::crop` | Crop frame and crop tool | exists |
|
||
| `ui::gradient` | Gradient swatch, palette and on-canvas gradient line | exists |
|
||
| `ui::measure` | Ruler tool, bar and box distances | exists |
|
||
| `ui::pattern`, `ui::picture_fill` | Pattern fill picker; picture fill options | exists |
|
||
| `ui::pen` | Pen draft and bezier paths | exists |
|
||
| `ui::shape`, `ui::shape_drag` | Shape properties panel and options bar; shape drag tool and Create Shape dialog | exists |
|
||
| `ui::slice` | Slice tool, overlay, bar and dialogs | exists |
|
||
| `ui::stroke` | Stroke editor, button and preview | exists |
|
||
| `ui::symmetry` | Paint symmetry guides, menu and transform | exists |
|
||
| `ui::transform` | Free transform box and transform fields | exists |
|
||
|
||
#### craft-font-catalog
|
||
|
||
Installed fonts: discovery on every platform, family and style lookup, shared loading. Exists.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `catalog` | Every installed face, found by any of its names | exists |
|
||
| `env`, `fontconfig`, `registry` | Font folders, fontconfig folders, registry-listed faces | exists |
|
||
| `scan` | Face records from font files | exists |
|
||
| `suitcase` | Classic suitcase font files | exists |
|
||
| `system` | The platform's font service | exists |
|
||
|
||
#### craft-font-manager
|
||
|
||
Search and filters over font indexes, installed fonts by family, and the font manager panel.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `axes` | Variable font axes | exists |
|
||
| `filter` | Search by family, category, language, script | exists |
|
||
| `glyphs` | Glyphs panel | exists |
|
||
| `index` | The font indexes | exists |
|
||
| `installed` | Installed fonts grouped by family | exists |
|
||
| `missing` | Document fonts and missing-fonts dialog | exists |
|
||
| `panel`, `ui` | The egui `FontsPanel` and its story | exists |
|
||
| `picker` | Font picker: families, filters, previews, stars, recents, similar fonts (feature `font-picker`) | exists |
|
||
| `store` | What the panel needs from the font store | exists |
|
||
|
||
#### craft-font-store
|
||
|
||
The font store: indexes, exact lookup, verified installs into the suite's font folder. Exists.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `http` | The one HTTPS client | exists |
|
||
| `index`, `source`, `sources` | Font indexes, one source's file and URLs, built-in sources | exists |
|
||
| `pin` | The index commit and hash this build trusts | exists |
|
||
| `store` | Store folder, consent, installs, manifest, removal | exists |
|
||
| `verify` | Checks a file against its index entry | exists |
|
||
|
||
#### craft-font-subset
|
||
|
||
The one font subsetter, on HarfBuzz: glyph closure, CFF and CFF2, variable-font instancing, licence-aware renaming and WOFF2. Native only. New on the branch. The HarfBuzz calls go through `harfbuzz-subset-sys`, a Rust package on storytold's HarfBuzz fork ([storytold/harfbuzz](https://github.com/storytold/harfbuzz), branch `rust-subset-15.0.0`, `rust/harfbuzz-subset-sys`): it compiles the fork's own HarfBuzz 15.0.0 `src/` and holds the raw declarations and their safe wrappers. The workspace pins it by commit.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| crate root | `subset` (renamed WOFF2 for previews), `subset_renamed`, `encode_woff2`; `cut_face` (one face cut to a character set, every feature kept, for build-time interface faces); `embed_permission` (what the OS/2 `fsType` lets an exported document embed) | exists |
|
||
| `closure` | Characters a shaper may need beyond the text | exists |
|
||
| `codepoints` | The canonical codepoint list of on-demand preview URLs | exists |
|
||
|
||
#### craft-fonts-build
|
||
|
||
Build-script support that embeds optional faces from an app's `build.rs`. Exists.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `cmap`, `coverage` | Which characters a face maps | exists |
|
||
| `embed`, `manifest` | Face selection and the generated table; with `subset`, interface faces cut to the catalogs' characters by `craft-font-subset` | exists |
|
||
| `sha256` | Hash for served file names | exists |
|
||
|
||
#### craft-gpu
|
||
|
||
GPU device, diagnostics and memory budget, plus the GPU canvas surface. New crate; native.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `budget` | Memory budget and probes | next |
|
||
| `canvas` | GPU canvas display surface | next |
|
||
| `device` | Device setup and diagnostics | next |
|
||
| `health` | Device loss, fallback and upload guard | next |
|
||
| `vector` | Vector canvas renderer | next |
|
||
|
||
#### craft-host
|
||
|
||
The `Host` bundle and service traits. Egui-free (egui only under `ui`, for `install`). New on the branch (step 1).
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| root | `Host`, `HostBuilder`, `Host::of`, `install` | exists |
|
||
| `services` | `AppInfo`, `SectionStore`, `Section`, `Commands`, `Jobs`, `ThreadJobs`, `InlineJobs` and defaults | exists |
|
||
| `files` | File service | exists |
|
||
|
||
#### craft-i18n
|
||
|
||
Translations: embedded catalogs, lookup with fallback, plurals, numbers for a region, language names, locale, search folding, collation. No egui.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `catalog` | Reading a catalog (the shared `common.tsv` holds library words) | exists |
|
||
| `collate` | Locale sorting for lists people see | exists |
|
||
| `fold` | Case- and accent-insensitive search matching | exists |
|
||
| `format` | Numbers, percentages and counts for a region | exists |
|
||
| `number` | Reading numbers people type | exists |
|
||
| `region`, `scripts` | Formatting region; scripts, direction and Han forms of a language | exists |
|
||
| `size` | Sizes and measures with a unit | exists |
|
||
|
||
#### craft-imaging
|
||
|
||
Raster image editing. New on the branch (step 1). Core at the root, widgets in `ui`.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `layer_style` | Layer style blending model | exists |
|
||
| `selection` | Selection model | exists |
|
||
| `trace` | Mask outline tracing | exists |
|
||
| `ui::adjust` | Levels editor and the colour adjustment editors | exists |
|
||
| `ui::live_preview` | Live preview of an adjustment: keys, lanes, proxy plan |
|
||
| `ui::blur_pins` | Blur pins on the canvas | exists |
|
||
| `ui::channels` | Channels panel | exists |
|
||
| `ui::fill` | Fill-from-surroundings workspace | exists |
|
||
| `ui::filter_gallery` | Filter gallery workspace | exists |
|
||
| `ui::layer_style` | Layer style page and effect list | exists |
|
||
| `ui::liquify` | Push-and-warp (liquify) workspace | exists |
|
||
| `ui::mask_view` | Mask and selection overlay views | exists |
|
||
| `ui::scopes` | Scope panel: histogram, vectorscope, clipping | exists |
|
||
| `ui::select`, `ui::select_mask`, `ui::selection` | Outline selection tools; select-and-mask workspace; ants, matte and quick-mask overlay | exists |
|
||
| `ui::transform_preview` | Live transform preview | exists |
|
||
| `ui::vanishing_point`, `ui::wide_angle` | Perspective plane and wide-angle correction workspaces | exists |
|
||
| `ui::warp` | Warp grid; mesh, pin and perspective warp | exists |
|
||
|
||
#### craft-jpeg
|
||
|
||
Clean-room decoder for 12-bit and arithmetic-coded JPEG. Exists.
|
||
|
||
#### craft-keymap
|
||
|
||
Chords, keymaps, conflicts, overrides and shortcut-set import; the Keyboard Shortcuts dialog under `ui`.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `chord` | Keys, modifiers, chords and text forms | exists |
|
||
| `command`, `commands` | Commands with parameters; command words for the host | exists |
|
||
| `editor` | Shortcut editor model with undo, recorder, conflicts | exists |
|
||
| `egui` | Key conversion and dispatch | exists |
|
||
| `import` | Import of another application's shortcut set | exists |
|
||
| `keymap` | Catalog with defaults, overrides, dispatch | exists |
|
||
| `layout` | Chord meaning on the active keyboard layout | exists |
|
||
| `profiles` | Named override sets | exists |
|
||
| `reserved` | Chords the OS takes first | exists |
|
||
| `scope` | Where a binding works | exists |
|
||
| `ui` | Shortcuts dialog | exists |
|
||
| `ui::import_offer` | First-launch import offer | exists |
|
||
| `ui::router` | Focus gate and key owners | exists |
|
||
|
||
#### craft-layers
|
||
|
||
Layers panel and its parts. UI-only family. New on the branch.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `ui::filter` | Layer filter bar | exists |
|
||
| `ui::options` | Layers panel options dialog | exists |
|
||
| `ui::panel` | `LayersPanel` over a `LayerTree` trait | exists |
|
||
| `ui::rows` | Blend, opacity and lock rows | exists |
|
||
| `ui::thumbs` | Layer and mask thumbnails | exists |
|
||
|
||
#### craft-media
|
||
|
||
Bit-level I/O and clean-room MP4/MOV and Matroska/WebM demuxers and muxers. Exists.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `bitstream` | Bit reading and writing | exists |
|
||
| `isobmff` | MP4 and MOV (ISO base media) | exists |
|
||
| `matroska` | MKV and WebM | exists |
|
||
|
||
#### craft-menu
|
||
|
||
Menus for macOS, Windows, Linux and the web, with shortcuts from `craft-keymap`.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `bar` | The menu bar drawn with egui | exists |
|
||
| `context` | Panel and context menus from command entries | exists |
|
||
| `driver` | Events from the platform menu in, menu bars out | exists |
|
||
| `help`, `language` | Help menu kit; language menu | exists |
|
||
| `keymap` | Shortcuts and checked states from the keymap | exists |
|
||
| `keytips` | Alt keytips | planned, step 8 |
|
||
| `layout` | Platform layouts of an app's menus | exists |
|
||
| `mac` | macOS menu bar | exists |
|
||
| `model` | Menu tree and flat rows | exists |
|
||
| `palette` | Menu commands as command-palette entries | exists |
|
||
| `recent` | Recent files, over the host's files | planned, step 3 |
|
||
| `ribbon` | Ribbon with backstage, gallery, customize dialog and quick access toolbar | planned, step 8 |
|
||
|
||
#### craft-pages
|
||
|
||
Page geometry, setup, ranges, numbering and paged-document UI. New crate.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `layout` | Paged layout: rectangles, columns, facing pages | exists |
|
||
| `numbering` | Page numbering styles | exists |
|
||
| `range` | Page range parsing | exists |
|
||
| `setup` | Page setup model | exists |
|
||
| `show` | Slideshow playback | planned, step 8 |
|
||
| `ui::access` | Accessibility bridge for a canvas of pages | exists |
|
||
| `ui::column_bar` | Column width bar | exists |
|
||
| `ui::flatten_preview` | Transparency flattener options and preview | planned, step 4 |
|
||
| `ui::grid` | Page grid overlay | exists |
|
||
| `ui::header_footer` | Header and footer zones | exists |
|
||
| `ui::list` | Page and artboard list | exists |
|
||
| `ui::margins` | Margin handles on rulers | exists |
|
||
| `ui::marks` | Text frame marks overlay | exists |
|
||
| `ui::preview` | Page preview overlay | exists |
|
||
| `ui::range` | Page range field | exists |
|
||
| `ui::reading` | Reading view | exists |
|
||
| `ui::setup` | Page setup dialog | exists |
|
||
| `ui::show` | Presenter window, transitions, timer, pen and laser | planned, step 8 |
|
||
| `ui::sync_views` | Synchronised side-by-side views | exists |
|
||
| `ui::table` | Document tables: edges, properties, size picker, cell selection | exists |
|
||
| `ui::text_selection` | Text selection layer over rendered pages | exists |
|
||
| `ui::thumbnails` | Page thumbnail strip | exists |
|
||
| `ui::view` | Paged document view | exists |
|
||
|
||
#### craft-pdf
|
||
|
||
Shared PDF reading, rendering and optional writing. Exists.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `link` | Which link targets may become clickable links | exists |
|
||
| `raster` | Bounded RGBA8 raster output | exists |
|
||
| `read` | Bounded opening and interpreter guards | exists |
|
||
| `write` | PDF authoring | exists |
|
||
|
||
#### craft-plate-test
|
||
|
||
Print-colour test scenes and PDF structure checks. Exists (`gs`, `judge`, `reference`, `report`, `scene`, `structure`, `tiff`).
|
||
|
||
#### craft-platform
|
||
|
||
Small platform lifecycle services, one cargo feature per service. No craft-ui.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `appearance` | Desktop colour, contrast and motion preferences | exists |
|
||
| `autosave` | Autosave | exists |
|
||
| `clock` | Clock service | exists |
|
||
| `ui::recovery` | Crash recovery | planned, step 4 |
|
||
| `browser` | Browser downloads | exists |
|
||
| `clipboard` | Clipboard with synthetic input and size limits | exists |
|
||
| `clock` | Injectable clock | exists |
|
||
| `default_app` | Default app registration | exists |
|
||
| `dialog_outcome`, `dialogs` | Dialog results with evidence; picker creation on the UI thread | exists |
|
||
| `job` | Background jobs and preview jobs | planned, step 4 |
|
||
| `logs` | Crash and command logs | exists |
|
||
| `open` | OS open requests, drops, open and reveal | exists |
|
||
| `pacing` | Frame pacing and work budgeting | exists |
|
||
| `pen` | Pen input: pressure, tilt, eraser end | planned, step 3 |
|
||
| `process` | Bounded output capture for one-shot programs | exists |
|
||
| `screen` | Screen colour sampling | exists |
|
||
| `session` | Reopen last session | exists |
|
||
| `temp` | Private temp files | exists |
|
||
| `usage` | Resource usage readout | exists |
|
||
| `watch` | File change watcher | exists |
|
||
|
||
#### craft-prepress
|
||
|
||
Ink model, plates from a PDF, coverage, ink limits, composite preview. Exists.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `cms`, `composite` | Process colour conversion; composite from plates | exists |
|
||
| `coverage`, `ink`, `plates` | Ink coverage, ink model, page separation | exists |
|
||
| `flatten` | Display list for the transparency flattener | exists |
|
||
|
||
#### craft-print
|
||
|
||
System PDF print spooler (Unix and Windows) and the print dialog.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `browser` | Browser print | planned, step 4 |
|
||
| `progress`, `sheets`, `ticket`, `windows` | Worker events, sheets of a print-ready PDF, print ticket, Windows spooler | exists |
|
||
| `spool` | Spooler front end for the print dialog | planned, step 4 |
|
||
| `ui` | Printer selection and job feedback | exists |
|
||
| `ui::layout` | Print layout sheet | planned, step 4 |
|
||
|
||
#### craft-quit
|
||
|
||
Quits an app the platform's way.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `close` | Routes an egui window close through the platform quit | exists |
|
||
| `macos`, `menu` | `terminate:` on macOS; the app menu with a Quit that asks first | exists |
|
||
|
||
#### craft-review
|
||
|
||
Comments, annotations, signatures, versions and revisions; collaboration behind `collab`. New crate.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `annotate`, `ui::annotate` | Page annotation tool | exists |
|
||
| `collab` (feature) | Presence, voting, chat, join by code, with `ui::chat`, `ui::presence`, `ui::vote` | exists |
|
||
| `comments`, `ui::comments`, `ui::thread` | Comments panel and threads | exists |
|
||
| `revisions`, `ui::revisions` | Revision compare list | exists |
|
||
| `signature`, `ui::signature` | Signature pad | exists |
|
||
| `versions`, `ui::versions` | Version history panel | exists |
|
||
|
||
#### craft-settings
|
||
|
||
Shared settings storage: platform folders, `config.toml`, atomic saves, recovery, migration. No egui.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `document` | TOML documents, per-section parsing, comment-preserving merges | exists |
|
||
| `error` | Reports and errors | exists |
|
||
| `migrate` | Schema migrations and import of older files | exists |
|
||
| `paths` | Choosing the configuration folder | exists |
|
||
| `profiles` | Settings profiles | exists |
|
||
| `recovery` | Keeping damaged and previous files | exists |
|
||
| `remember` | `Remembered<T>`: last-used options for dialogs, panels and tools | exists |
|
||
| `store` | In-memory store | exists |
|
||
|
||
#### craft-table
|
||
|
||
Spreadsheet grid and related UI. UI-only family. New crate.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `ui::chart` | Chart painting | exists |
|
||
| `ui::conditions` | Condition builder | exists |
|
||
| `ui::error_tag` | Error-checking tag | exists |
|
||
| `ui::fields` | Field list pane | exists |
|
||
| `ui::filter` | Filter buttons | exists |
|
||
| `ui::grid` | Spreadsheet cell grid | exists |
|
||
| `ui::outline` | Row and column outline | exists |
|
||
| `ui::refpick` | Cell reference picking | exists |
|
||
| `ui::slicer` | Slicer filter chips | exists |
|
||
| `ui::stats` | Selection statistics | exists |
|
||
|
||
#### craft-text
|
||
|
||
Text processing below the composer, and text UI.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `bidi` | Bidirectional text (UAX #9) | exists |
|
||
| `find` | Find and replace | exists |
|
||
| `hyphen` | Hyphenation | exists |
|
||
| `linebreak` | Knuth-Plass line breaking | exists |
|
||
| `lists` | Bullet paragraph layout | exists |
|
||
| `quotes` | Smart quotes | exists |
|
||
| `segment` | Line-break opportunities | exists |
|
||
| `spell` | Spelling check | exists |
|
||
| `styles` | Named style list | exists |
|
||
| `ui::character`, `ui::style_panel` | Character format controls; text style panel | exists |
|
||
| `ui::columns`, `ui::hyperlink`, `ui::notes` | Columns dialog, hyperlink dialog, rich-text notes | exists |
|
||
| `ui::paragraph` | Paragraph format dialog | planned, step 6 |
|
||
| `ui::editor` | Canvas text editor | exists |
|
||
| `ui::find` | Find bar | exists |
|
||
| `ui::styles` | Named styles panel | planned, step 6 |
|
||
| `ui::ruler`, `ui::tabs_dialog` | Text ruler with tab stops; tab stops dialog | exists |
|
||
| `ui::spelling` | Spelling dialog | exists |
|
||
|
||
#### craft-theme
|
||
|
||
The theme model: colour, scale and token primitives, semantic tokens, contrast rules, the theme file format, built-in themes, and the `craft-theme check` command. No egui. New on the branch.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `app_sizes` | An app's size overrides (`sizes.json`) | exists |
|
||
| `builtins` | The ten built-in themes | exists |
|
||
| `color`, `color_model` | sRGB, OKLab and OKLCH with gamut mapping; colour models a picker edits in; hex helpers | exists |
|
||
| `components` | Component tokens, one struct per family | exists |
|
||
| `contrast` | WCAG contrast and repair | exists |
|
||
| `derive`, `ramp` | Seeds to ramps to tokens; 12-step ramps | exists |
|
||
| `dump`, `explain`, `report` | Token text dump, why each colour has its value, contrast sweep | exists |
|
||
| `format` | Theme file schema version 1: parse, validate, write | exists |
|
||
| `resolve` | Theme and appearance to concrete tokens | exists |
|
||
| `scale` | Space, radius, stroke, elevation, motion, opacity | exists |
|
||
| `selection` | The user's pick: theme per mode, mode, contrast, motion, size, text size | exists |
|
||
| `sizes` | Size sets | exists |
|
||
| `theme`, `tokens`, `values` | What a theme supplies; semantic tokens; tunable numbers | exists |
|
||
|
||
#### craft-theme-store
|
||
|
||
The suite's theme files, machine-local library and shared selection, with a lock and revision protocol for concurrent apps. New on the branch.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `backend`, `dir`, `disk` | Where the files live; atomic-rename disk store | exists |
|
||
| `client`, `watch` | App side of the selection protocol; folder watcher | exists |
|
||
| `copy` | Import as copy | exists |
|
||
| `selection`, `store` | `selection.json` and the lock and revision protocol; the theme library | exists |
|
||
| `testing` | Fixtures for adapter tests | exists |
|
||
| `ui::appearance` | `AppearancePage`: the whole appearance settings page | planned, step 4 |
|
||
|
||
#### craft-timeline
|
||
|
||
Time, clips, keyframes, markers, frame cache, playback clock, and timeline UI. New crate.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `cache` | Frame cache with prefetch | exists |
|
||
| `clips` | Clip editing model | exists |
|
||
| `clock` | Playback clock and follow modes | exists |
|
||
| `frames` | Playback frame server | exists |
|
||
| `markers` | Markers | exists |
|
||
| `rates` | Media format presets | exists |
|
||
| `timecode` | Timecode and durations | exists |
|
||
| `ui::clips` | Clip editing UI | exists |
|
||
| `ui::graph` | Keyframe graph editor | exists |
|
||
| `ui::keyframes` | Keyframe lane | exists |
|
||
| `ui::markers` | Marker UI | exists |
|
||
| `ui::overview` | Overview strip | exists |
|
||
| `ui::panel` | Timeline panel with track headers | exists |
|
||
| `ui::preview` | Video frame painter and preview panel | exists |
|
||
| `ui::render_queue` | Render queue list | exists |
|
||
| `ui::ruler` | Time ruler | exists |
|
||
| `ui::timecode` | Timecode fields and readout | exists |
|
||
| `ui::transport` | Transport bar | exists |
|
||
|
||
#### craft-ui
|
||
|
||
The facade of the UI library ([3.2](#32-the-ui-library-crates)). It re-exports the modules of the six library crates under one root: every `craft_ui::<module>` path below names the module of the crate listed. `patterns::canvas` adds `NavigatorPanel` from craft-ui-canvas. With `testing`, `craft_ui::testing` gathers the test helpers of every crate and `library_registrations` lists the registrations of the library's own crates; `app` turns on craft-ui-shell's `app`.
|
||
|
||
#### craft-ui-bench
|
||
|
||
Release-mode benchmark of the library's performance scenarios: the scenario list, the measurement and the report, with a counting allocator. Not published.
|
||
|
||
#### craft-ui-canvas
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `canvas` | The `Canvas` container: tool host, tools, pasteboard, split views, rulers, navigator and `NavigatorPanel`, cursors, raster display, and its test helpers (`ToolFixture`, `tool_story`, `canvas_story`) | exists |
|
||
| `canvas_controls` | Leaves a `Canvas` body shows: brush cursor, grid, pixel grid, guides, smart guides, marquee, outline, line preview | exists |
|
||
| `dialog` | craft-ui-panels' `dialog`, plus `FullWindowDialog` and its parts | exists |
|
||
|
||
#### craft-ui-contract
|
||
|
||
The base of the library (layers 2 to 4). The `testing` feature adds `testing`, with the snapshot renderer.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `contract` | The component traits, context types, `PaintUi`, `Looks`, the pipeline and its steps, the mount and overlay hosts, `Lazy`, `Entry` and the list step rule | exists |
|
||
| `fonts` | Font definitions and the script coverage policy | exists |
|
||
| `layout` | Layout services: `LabelColumn`, `ColumnGroup`, the `Grid` cursor, `arrange` | exists |
|
||
| `primitives` | Painters, `Draw`, the sensing core, the text adapter, `ImeSurface` | exists |
|
||
| `runtime` | Per-pass and per-frame services (focus, keys, layout memory, lazy content, overlays, windows) and the one egui adapter | exists |
|
||
| `style` | The state set and its resolver, style parts, `ComponentStyle`, `UiTokens`, `StyleCx`, the style cache | exists |
|
||
| `testing` | The fixture, the suite runner, the story types, dumps and the snapshot renderer | exists |
|
||
| `words` | The `words!` macro, from craft-ui-macros | exists |
|
||
|
||
#### craft-ui-gallery
|
||
|
||
The story viewer (desktop and web) over the registered stories of every `ui` crate. Not published. One cargo feature per domain crate whose stories it links; `apps`, the default, links them all.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `chrome` | The options bar, the dock of panels and the window that holds them; the Overview (the cards of one level), a component's tab (one card per story group) and the Variants view; `StoryBody`, a story in its embedded shell | exists |
|
||
| `viewer` | The viewer's state and the data its chrome shows: the catalog of components by level, their story groups (a story's `group = ".."`, shown under its `title = ".."`), the saved dock layouts | exists |
|
||
| `theme` | The theme workspace: panels that explain a theme and its appearance | exists |
|
||
| `mock` | The mock editor window: shell, title bar, rails, dock, document tabs, canvas and dialogs | exists |
|
||
| `bin/components-index`, `bin/contract-api` | Write [components-index.md](components-index.md) and [contract-api.md](contract-api.md) | exists |
|
||
| `story-render` (crate `crates/story-render`) | Renders a component's stories to PNG files, offscreen, linking only the crates its features name | exists |
|
||
|
||
#### craft-ui-macros
|
||
|
||
The derives and macros of the UI library: `Component`, `Props`, `ComponentStyle`, `Pattern`, `CommandSet`, `EnvValue`, `TokenGroup`, words, stories and trials. Apps use them through `craft-ui`.
|
||
|
||
#### craft-ui-panels
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `canvas_data` | The canvas data patterns read and write without the canvas: guides and the navigator's panel options | exists |
|
||
| `dialog` | `Dialog`, `DialogFrame`, `BlockingOverlay`, `Prompt` and its configurations, `DialogStack`, `DialogHost` ([ui-dialogs.md](ui-dialogs.md)) | exists |
|
||
| `docking` | `SplitArea`, `Splitter`, `DockGroup`, floating groups, the dock column, drop resolution and the dock commands ([ui-docking.md](ui-docking.md)) | exists |
|
||
| `rails` | `PanelRail`, `ToolRail`, `FlyoutButton`, `ToolbarDrawer` | exists |
|
||
| `sections` | `TitleRow`, `FooterBar`, `Section`, `GroupBox`, `Panel` | exists |
|
||
|
||
#### craft-ui-patterns
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `patterns::dock` | `DockArea`, `DockPanels`, `PaneArea`, `WorkspaceSwitcher` | exists |
|
||
| `patterns::blend_keys` | Blend-mode key picker | exists |
|
||
| `patterns::form_dialogs` | Form dialogs, among them `PdfExportDialog` over `craft-pdf`'s settings; `FileListPicker`, `FileList`, `FileListMode`, `FileListPickerOutput`, `FileListWords` | exists |
|
||
| `patterns::panels` | `Inspector`, `CommandPalette`, `Tour`, `HistoryPanel`, `ModifierKeysPanel` | exists |
|
||
| `patterns::preferences` | `PreferencesWindow` and its pages | exists |
|
||
| `patterns::presets` | The preset browser over a generic preset library model | exists |
|
||
|
||
#### craft-ui-shell
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `shell` | `AppShell` and its presets, `TitleBar`, captions, `ScreenMode`, `ToastHost`; with `app`, `app::run` | exists; office-style preset planned, step 8 |
|
||
|
||
#### craft-ui-test-kit
|
||
|
||
Test kits the library crates' integration binaries share: components written with the derives, and a frame driver for child viewports. Its registrations are its own, so no library suite runs them. Not published.
|
||
|
||
#### craft-ui-widgets
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `bars` | `Bar` and `BarItems`: the bar container and its strip of command items; `AlignBar`, `BreadcrumbBar`, `ConstraintFields`, the status readout | exists |
|
||
| `buttons` | `Button`, `IconButton`, `ToggleButton`, `SplitButton`, `Link` | exists |
|
||
| `choice` | `Checkbox`, `Switch`, `RadioGroup`, `Segmented`, `Rating` | exists |
|
||
| `controls` | `Disclosure` | exists |
|
||
| `display` | `Badge`, `Kbd`, `Progress`, `Spinner`, `Text`, `Icon`, `Picture`, `Divider` | exists |
|
||
| `edit` | Undo adapters over `EditHistory`, panel events and `DialogValue` | exists |
|
||
| `form` | `Field`, `FieldGroup`, `SliderField` | exists |
|
||
| `graph` | `NodeGraph`, `Node`, `NodeKind` | exists |
|
||
| `layout_components` | `Stack`, `Row`, `Grid` | exists |
|
||
| `list` | `List` and its rows: `ListRow`, `FindingsList`, `EventList`, `UndoList` | exists |
|
||
| `menu` | Menu presets with `MenuItem` rows, menu-bar keys and mnemonics | exists |
|
||
| `notices` | `Notice`, the settings notices and the notice center | exists |
|
||
| `pickers` | `Select`, `ComboBox`, `TreePicker`, `Autocomplete`, `DatePicker`, `IconPicker` | exists |
|
||
| `popover` | `Popover`, `PopupList`, `Tooltip`, `DropVeil` | exists |
|
||
| `story_kit` | Story helpers that show components (`props`, `story_props`) | exists |
|
||
| `table` | `Table` and `MetadataTable` | exists |
|
||
| `tabs` | `TabStrip`, `Tab`, `DocumentTabs` | exists |
|
||
| `text` | `TextField<C>` and `NumberField` on the text part | exists |
|
||
| `tile_grid` | `Tile` and `ThumbnailSlider` | exists |
|
||
| `value_drag` | `Slider`, `RangeSlider`, `AngleDial`, `PointPicker`, `ThumbRow`, on `ValueDrag` | exists |
|
||
|
||
#### craft-update
|
||
|
||
Release checking, downloading, installing and self-updating for the app suite and the launcher.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `app`, `suite`, `version`, `pins` | Apps, releases and versions | exists |
|
||
| `desktop_entry`, `detect`, `distro`, `folders`, `install`, `manifest`, `msi_*`, `packages`, `paths`, `platform`, `portable`, `process`, `queue`, `status` | Installing, detecting and removing apps | exists |
|
||
| `dialog` | Startup update prompt | exists |
|
||
| `http`, `proxy`, `release`, `source`, `time` | Network access and release lookup | exists |
|
||
| `protocol` | Vocabulary jobs and results report in | exists |
|
||
| `self_update`, `updater` | Launcher self-update; the update flow of an egui app | exists |
|
||
|
||
#### craft-win32
|
||
|
||
The Win32 window-procedure subclassing and window-handle calls that need `unsafe`, behind a safe API; empty on other platforms. It is the one crate that allows `unsafe` code ([3.4](#34-crate-taxonomy)).
|
||
|
||
#### craft-window
|
||
|
||
Decides who draws the window frame, makes an app-drawn strip act as the title bar, and keeps the window list, placement and restore.
|
||
|
||
| Module | Holds | State |
|
||
| --- | --- | --- |
|
||
| `desktop` | Desktop and backend detection | exists |
|
||
| `layout` | Window button layout per desktop | exists |
|
||
| `list`, `menu` | Open windows; the Window menu | exists |
|
||
| `mac` | macOS traffic lights, measured | exists |
|
||
| `place` | Cascaded placement kept on screen | exists |
|
||
| `policy` | Frame policy | exists |
|
||
| `restore` | Window restore | exists |
|
||
| `title_bar` | An app strip as the title bar | exists |
|
||
| `viewports` | Immediate viewports per window | exists |
|