@@ -1,109 +1,114 @@
11 # Widget library
22
3-This repo is the user's whole app. The conveyor window draws `widgets/root.rs`, and `widgets/status.rs` over it (build status: what's building, and Keep or Discard for a build on trial), and nothing else. So everything the user sees is a widget here: the title bar, the canvas, panes, lists, boards, build status. Conveyor only adds the building tool on top: the user holds Ctrl, clicks any widget, and types what they want. Each ticket is those words.
3+This repo is the user's whole app. The conveyor window draws `widgets/root.rs`, and `widgets/status.rs` over it, and nothing else. `status` shows what's building, with Keep and Discard for a build on trial. Conveyor adds one tool on top: the user holds Ctrl, clicks any widget, and types what they want. Those words are your ticket.
44
5-## What the ticket tells you
5+## Look before you change anything
66
77 Below the user's words, after `---`, conveyor says what they clicked:
88
9-- the widget kind (`widgets/<kind>.rs`) and its instance id, and the point inside it;
10-- the element under the pointer, as a key path inside that widget (`col-done/card-12`): grep for the key to find the code;
9+- the widget kind (`widgets/<kind>.rs`), its instance id, and the point inside it;
10+- the element under the pointer, as a key path inside that widget (`col-done/card-12`). Grep for the key to find the code;
1111 - its parents, innermost first (`root.canvas.clock1` is `clock1` inside `root.canvas` inside `root`);
1212 - every instance on screen, and the conversation so far about that kind.
1313
14-**Look before you change anything.** `~/ticket/files/app` is a copy of the user's app as it was when they clicked: its data, shared values and every instance's folder. The ticket gives the exact command; it renders their window with what they clicked outlined in orange. Read the PNG. Render it again after your change, with the same state, and compare: that's what they will see.
14+`~/ticket/files/app` is a copy of the user's app as it was when they clicked. Render it with the command the ticket gives, and read the PNG: it's their window, with what they clicked outlined in orange.
1515
16-Read the words against that. "Make this purple" means the clicked kind. "Put a list of my projects here" means a new kind, or a change to the parent that lays this area out. "Add a sidebar" on the title bar or the canvas usually means changing `root.rs`. Change as many widgets as it takes; keep each file one widget.
16+Read the words against that. "Make this purple" means the clicked kind. "Put a list of my projects here" means a new kind, or a change to the parent that lays out this area. "Add a sidebar" on the title bar or the canvas usually means a change to `root.rs`. Change as many widgets as it takes.
1717
18-## What's yours to change
18+## Change only `widgets/`
1919
20-Only `widgets/`. Everything else is conveyor's (`api.rs`, `gen.rs`, `preview/`, `Cargo.*`, `.gitignore`, this file), and a branch that changes it is rejected.
20+Everything else is conveyor's: `api.rs`, `gen.rs`, `preview/`, `Cargo.*`, `.gitignore`, and this file. Conveyor rejects a branch that changes them.
2121
22-A file in `widgets/` with `pub const WIDGET` is a widget kind. One without it is a helper module the widgets share (`use super::highlight;`): put code two widgets need, or a big piece of one, there instead of growing a widget file.
22+Keep each file one widget. A file with `pub const WIDGET` is a widget kind. A file without it is a helper module that widgets share (`use super::highlight;`). Put code that two widgets need, or a big piece of one widget, in a helper.
2323
24-## A widget is a real program
24+## Write widgets against `api.rs`
2525
26-A widget is a struct with its own state that renders itself (`api::View`). Read `api.rs`: it's short and it's the whole contract.
26+`api.rs` is short and it's the whole contract, so read it first. A widget is a struct with its own state that renders itself (`View`). Handlers reach that state with `on`, `edit`, and `get`, and act on conveyor with the free functions such as `set_state` and `new_ticket`. Outside a handler, `cx.act(|l| ...)` calls the `Live` methods of the same names.
2727
28-- **Compose.** `cx.child("kind", "key")` renders another widget inside this one, with its own state and folder. Keep keys stable. A layout widget (root is one) is mostly children.
29-- **Place new widgets yourself.** For "put an X here", either render X with `cx.child` in the parent you change, or, where a parent holds a free list of children (the canvas), run `conveyor place <kind> --in <instance>`: the app offers it to that instance's `View::mount`, at the user's click when the click was inside it. Nothing is placed unless you say so, so don't do both. A widget that keeps a list of children skips kinds the library no longer has (`cx.kinds()`): a discarded build's widgets g …
30-- **Conveyor's data.** `cx.data` has the projects, every ticket (with its text, times, attached files and conversation) and the latest activity, refreshed every second. Never read conveyor's own files: if something is missing from `cx.data`, say so with `conveyor deviate`.
31-- **Act on conveyor.** From a handler: `set_state(h, project, id, "ready")` moves a ticket and shows the move at once (ready starts an agent when the project has a free slot; conveyor owns running), `new_ticket(h, project, title, body, state, &files)` writes one with files attached (the agent gets them), `edit_ticket(h, project, id, title, body)` rewrites one in place, `add_project(h, slug, &path)` adds a project, `set_slots(h, project, n)` sets how many tickets run at once (0 pauses it), `keep_ …
32-- **Act from anywhere.** In `view`, `update` or `event`, where there's no handler, `cx.act(move |l| l.new_ticket(...))` does the same: the `Live` methods of the same names.
33-- **Draw.** Rune draws vector shapes (`rune::Shape`: lines, paths, arcs) with `.shape(...)`, blurs what's behind an element with `.backdrop_blur(sigma)`, and stacks absolute elements in the order you add them.
34-- **Share.** `share(h, "project", "dotfiles")` in a handler (or `cx.act(|l| l.share(..))` anywhere), and `cx.shared("project")` in any widget's view: a sidebar picks, a board follows. Shared values survive restarts.
35-- **Input.** Buttons, fields, keys, drags, file drops on an element (`on_drop_files`). Reach the widget's state from a handler with `on`, `edit` or `get`.
36-- **Window-wide events.** A paste with no text field focused, or files dropped on the window, arrive at `View::event` (pasted images are saved as PNGs first). Every instance is offered it, innermost first.
37-- **Writable state each frame.** `View::update(&mut self, cx)` runs before every render, for every instance, shown or not: note what changed in `cx.data`, step an animation's state. Keep `view` a pure drawing of state.
38-- **New code, same window.** When the library changes, the app keeps running and swaps in the new build: every instance is dropped and made again with `new`, from its folder. So save what the user typed or arranged as it changes, and stop your threads and child processes in `Drop` (a flag the thread checks, a `kill`), or the old build's keep running beside the new one's. A widget that holds a process the user would notice stopping, such as music, can leave it running detached and adopt it again …
39-- **Work that goes on off screen.** An instance exists once something renders it. If it must keep going while hidden, such as music playing, call `cx.keep_running()` in `update` while it does: the app then brings it back after a reload or a restart even when no parent shows it.
40-- **Key what a user can point at.** Give cards, buttons, columns and panes stable, meaningful keys (`card-{id}`, `col-done`, `add-project`). The Ctrl+click outline and the ticket's element path come from keys; unkeyed parts are invisible to the builder.
41-- **Animate.** Call `cx.animate()` in `view` while something moves, and draw from `cx.now`. Without it the app renders once a second.
42-- **Files.** `cx.dir` is the instance's own folder and survives reloads and restarts.
43-- **Secrets.** The user keeps API keys, tokens and passwords in one keychain, by name. `cx.secrets()` lists the names, `cx.secret("openrouter")` reads one, and `set_secret(h, "openrouter", &key)` in a handler (or `cx.act(|l| l.set_secret(..))`) sets one; empty forgets it. A widget that needs a key lets the user pick one of those names, not type the key again. Never keep a key in `cx.dir`, a shared value or any file you write: the app state is copied into every build ticket. Pass a key to `curl` …
44-- **Say what it is.** The first paragraph of a widget file's `//!` comment is its description: the library shows it to the user picking widgets (`cx.about(kind)`). One or two plain sentences on what it shows and does.
45-- **A panic stops only that instance.** It draws a red card with the message until the next build, and the user can Ctrl+click it to have it fixed. If `root` or `status` stops, the app opens safe mode, where no widget runs.
46-- **Background work.** `std::thread`, and the system's programs with `std::process::Command` (`curl` for the network: std has no HTTPS).
47-- **Images.** `cx.images()` is the app's image cache: `.load(bytes)`, `.file(path, ..)` and `.svg(..)` decode off the UI thread, and the app redraws when one is ready. Keep the handle in your state to load from handlers. Don't make your own `ImageCache`. `rune::Pixels` streams raw frames.
48-- **Crates.** `rune`, `rune_kit`, `serde` (with derive) and `serde_json`, and std. Nothing else links: a widget that needs another crate is a block.
49-- **Components.** `rune_kit` is there too: syntax highlighting (`rune_kit::syntax`), Markdown, menus, popovers, tables, trees, dialogs, toasts and more. Use them before writing your own. Its source is next to rune's (`~/.cargo/git/checkouts/rune-*/*/crates/rune-kit/`).
28+`api.rs` doesn't say these:
5029
51-## When to block instead
30+- **Place new widgets yourself.** For "put an X here", render X with `cx.child` in the parent you change. Where a parent keeps a free list of children (the canvas), run `conveyor place <kind> --in <instance>` instead. Do one, not both. A parent that keeps a list of children skips kinds missing from `cx.kinds()`, so a discarded build's widgets go away and come back if it's built again.
31+- **Key what the user can point at.** Give cards, buttons, columns, and panes stable keys (`card-{id}`, `col-done`, `add-project`). The Ctrl+click outline and the ticket's element path come from keys. The builder can't see unkeyed parts.
32+- **Survive a reload.** When the library changes, the app drops every instance and makes it again with `new`, from its folder. Save what the user types or arranges as it changes. Stop threads and child processes in `Drop` (a flag the thread checks, a `kill`), or the old build's keep running beside the new one's. A process the user would notice stopping, such as music, can run detached: adopt it again in `new`, and call `cx.keep_running()` while it plays.
33+- **Keep `view` a pure drawing of state.** Change state in `update`, `event`, and handlers.
34+- **Read conveyor only through `cx.data`.** Never read or write conveyor's files. If something you need is missing from `cx.data`, say so with `conveyor deviate`.
35+- **Never store a secret.** A widget that needs a key lets the user pick a name from `cx.secrets()`, instead of asking for the key again. Keep keys out of `cx.dir`, shared values, and every file you write, because conveyor copies the app state into every build ticket. Pass a key to `curl` on stdin, not in its arguments.
36+- **Describe the widget.** The user reads the first paragraph of the file's `//!` comment when they pick widgets. Write one or two plain sentences on what it shows and does.
37+- **Keep `root` and `status` from panicking.** A panic in any other widget stops only that instance: it draws a red card until the next build, and the user can Ctrl+click it to have it fixed. A panic in `root` or `status` opens safe mode, where no widget runs.
5238
53-Run `conveyor block --reason "<...>" --recommend "<...>"` and stop, without guessing, when:
39+## Use what links
5440
55-- the words don't ask for anything, such as a keyboard mash or a stray word;
56-- it needs something no widget can reach with `rune`, `std`, the API and the system's programs, such as a new crate. Say exactly what's missing: that's how the API grows.
41+The crates are `rune`, `rune_kit`, `serde` (with derive), `serde_json`, and std. Nothing else links, so a widget that needs another crate is a block. For background work, use `std::thread`, and run the system's programs with `std::process::Command`. Use `curl` for the network, since std has no HTTPS.
5742
58-When the API covers most of it, build that part and name the rest with `conveyor deviate` instead of blocking. Don't work around the API by reading or writing conveyor's files.
43+Look in `rune_kit` before you write a component. It has syntax highlighting (`rune_kit::syntax`), Markdown, menus, popovers, tables, trees, dialogs, toasts, and more. Rune itself also has these:
5944
60-## Make or change widgets
45+- vector shapes (`rune::Shape`: lines, paths, arcs) with `.shape(...)`;
46+- a blur of what's behind an element, with `.backdrop_blur(sigma)`;
47+- file drops on an element (`on_drop_files`), and the system's file dialogs (`tx.open_folder(...)`, `tx.open_file(...)`);
48+- raw frames, streamed with `rune::Pixels`.
6149
62-1. A new kind gets a short snake_case file name, such as `clock` or `project_list`, that isn't taken in `widgets/`.
63-2. Write `widgets/<kind>.rs`. This shape has state, a handler and a saved file:
50+Absolute elements stack in the order you add them. Load images through `cx.images()`, not an `ImageCache` of your own. Use Rune's dark theme (`tok::theme(true)`), and fill the box the parent gives you.
6451
65- ```rust
66- use super::api::*;
67- use rune::{El, col, text, tok};
68- use std::path::PathBuf;
52+Rune's docs are in the cargo git checkout: `~/.cargo/git/checkouts/rune-*/*/crates/rune/README.md`, with `rune_kit` beside it in `crates/rune-kit/`.
6953
70- pub const WIDGET: Widget = Widget { title: "Counter", size: (240.0, 120.0), new: |cx| Box::new(Counter::load(cx)) };
54+## When to block
7155
72- pub struct Counter { n: u32, file: PathBuf }
56+Run `conveyor block --reason "<...>" --recommend "<...>"` and stop, without guessing, in two cases:
7357
74- impl Counter {
75- fn load(cx: &Cx) -> Self {
76- let file = cx.dir.join("n");
77- Counter { n: std::fs::read_to_string(&file).ok().and_then(|s| s.parse().ok()).unwrap_or(0), file }
78- }
79- }
58+- The words don't ask for anything, such as a keyboard mash or a stray word.
59+- The ticket needs something no widget can reach with the crates above, the API, and the system's programs. Say exactly what's missing: that's how the API grows.
8060
81- impl View for Counter {
82- fn view(&self, cx: &Cx) -> El {
83- let t = tok::theme(true);
84- col().w_full().h_full().center().role("button").label("Count")
85- .on_press_tx(on(cx.id, |c: &mut Counter, _| { c.n += 1; let _ = std::fs::write(&c.file, c.n.to_string()); }))
86- .child(text(format!("{}", self.n)).color(t.text))
87- }
88- }
89- ```
61+When the API covers most of the ticket, build that part, and name the rest with `conveyor deviate`.
9062
91- A text field binds with `.on_edit(edit(cx.id, |w: &mut MyWidget| &mut w.text))`. `size` is what the canvas gives it when it's placed there. A widget that only fills what its parent gives it (a layout) has size `(0.0, 0.0)`, and is never placed.
92-3. Use Rune's dark theme (`tok::theme(true)`) and fill the box the parent gives you.
63+## Make a widget
9364
94-## Check it
65+A new kind gets a short snake_case file name that isn't taken in `widgets/`, such as `clock` or `project_list`. This widget has state, a handler, and a saved file:
66+
67+```rust
68+use super::api::*;
69+use rune::{El, col, text, tok};
70+use std::path::PathBuf;
71+
72+pub const WIDGET: Widget = Widget { title: "Counter", size: (240.0, 120.0), new: |cx| Box::new(Counter::load(cx)) };
73+
74+pub struct Counter { n: u32, file: PathBuf }
75+
76+impl Counter {
77+ fn load(cx: &Cx) -> Self {
78+ let file = cx.dir.join("n");
79+ Counter { n: std::fs::read_to_string(&file).ok().and_then(|s| s.parse().ok()).unwrap_or(0), file }
80+ }
81+}
82+
83+impl View for Counter {
84+ fn view(&self, cx: &Cx) -> El {
85+ let t = tok::theme(true);
86+ col().w_full().h_full().center().role("button").label("Count")
87+ .on_press_tx(on(cx.id, |c: &mut Counter, _| { c.n += 1; let _ = std::fs::write(&c.file, c.n.to_string()); }))
88+ .child(text(format!("{}", self.n)).color(t.text))
89+ }
90+}
91+```
92+
93+`size` is what the canvas gives the widget when it's placed there. A layout widget only fills what its parent gives it, so its size is `(0.0, 0.0)` and it's never placed.
94+
95+## Check it in the preview
9596
9697 ```sh
97-cargo build --release -p preview
9898 cargo run --release -p preview -- --state ~/ticket/files/app root --size 1400x900 --snap /tmp/a.png --tree /tmp/a.json --at 1
9999 ```
100100
101-The preview is the app's own host. With `--state` it replays the user's app; without it, it runs on sample projects and tickets. The first name is rendered as the whole window. Names after it are mounted as the app would, so `root clock` shows the clock on the canvas. To see one widget alone, pass only its name. Give it `--at 1` (or later, for animation) so the snap waits for the widgets to load. Use `--script` to press, drag and type, and look at the PNG until it does what the ticket asks. `--t …
101+The preview is the app's own host. Render with the same `--state` as before your change, and look at the PNG until it does what the ticket asks: that's what the user will see.
102102
103-Rune's docs are in the cargo git checkout: `~/.cargo/git/checkouts/rune-*/*/crates/rune/README.md`.
103+- The first name is rendered as the whole window. Names after it are mounted as the app would, so `root clock` shows the clock on the canvas. Pass one name alone to see that widget alone.
104+- Without `--state`, the preview runs on sample projects and tickets.
105+- `--at 1` waits a second before the snap, so the widgets load. Pass a later time for animation.
106+- `--tree` lists every element with its rect, so you can catch clipped content.
107+- `--script` presses, drags, and types. Rune's README documents it and the other flags.
108+- The preview prints the requests a widget sends to conveyor. Instance folders live under `/tmp/preview/w/`, and `--state` resets them.
104109
105110 ## Finish
106111
107-Commit your changes to `widgets/`, then run `conveyor done "<kinds>: <one line>"`. Your branch then goes on trial: the user's app runs with it, and they keep it (it's merged) or discard it. You started from what they see, builds still on trial included.
112+Commit your changes to `widgets/`, then run `conveyor done "<kinds>: <one line>"`. Your branch then goes on trial: the user's app runs with it, and they keep it (which merges it) or discard it. You started from what they see, builds still on trial included.
108113
109114 The user reads your last message in a small toast. Write two short lines at most: what they'll see, and anything they should know. No headings, no lists.