8447
Co
conveyor / files
conveyor / templates / library / CLAUDE.md
8.3 KB
1# Widget library 2 3This 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. 4 5## Look before you change anything 6 7Below the user's words, after `---`, conveyor says what they clicked: 8 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; 11- its parents, innermost first (`root.canvas.clock1` is `clock1` inside `root.canvas` inside `root`); 12- every instance on screen, and the conversation so far about that kind. 13 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. 15 16Read 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. 17 18## Change only `widgets/` 19 20Everything else is conveyor's: `api.rs`, `gen.rs`, `preview/`, `Cargo.*`, `.gitignore`, and this file. Conveyor rejects a branch that changes them. 21 22Keep 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. 23 24## Write widgets against `api.rs` 25 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. 27 28`api.rs` doesn't say these: 29 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. 38 39## Use what links 40 41The 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. 42 43Look 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: 44 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`. 49 50Absolute 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. 51 52Rune'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/`. 53 54## When to block 55 56Run `conveyor block --reason "<...>" --recommend "<...>"` and stop, without guessing, in two cases: 57 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. 60 61When the API covers most of the ticket, build that part, and name the rest with `conveyor deviate`. 62 63## Make a widget 64 65A 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 68use super::api::*; 69use rune::{El, col, text, tok}; 70use std::path::PathBuf; 71 72pub const WIDGET: Widget = Widget { title: "Counter", size: (240.0, 120.0), new: |cx| Box::new(Counter::load(cx)) }; 73 74pub struct Counter { n: u32, file: PathBuf } 75 76impl 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 83impl 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 96 97```sh 98cargo run --release -p preview -- --state ~/ticket/files/app root --size 1400x900 --snap /tmp/a.png --tree /tmp/a.json --at 1 99``` 100 101The 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. 102 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. 109 110## Finish 111 112Commit 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. 113 114The 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.