diff --git a/AGENTS.md b/AGENTS.md index 8c8b8eba9..ea5588e57 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,13 +1,16 @@ # radicle-gui -Monorepo for Radicle's graphical interfaces. It holds two independent -projects, each with its own npm package, Cargo workspace, toolchain files, -checks and conventions: +Monorepo for Radicle's graphical interfaces. It holds two projects, each with +its own Cargo workspace, toolchain files, checks and conventions, and the UI +code they share. One npm workspace at the root holds all three packages: - **Explorer** (`explorer/`): the Svelte web app for browsing Radicle repositories, its TypeScript HTTP client, and the `radicle-httpd` and `radicle-search` backends it talks to. See `explorer/AGENTS.md`. - **Desktop** (`desktop/`): the Tauri desktop app. See `desktop/AGENTS.md`. +- **Shared UI** (`shared/ui/`): the `@radicle-gui/ui` package with Svelte + components, helpers, design tokens and fonts used by both apps. See + `shared/ui/AGENTS.md`. This file covers what applies to both. Each project's `AGENTS.md` is the source of truth for anything inside it. @@ -18,20 +21,27 @@ source of truth for anything inside it. |---|---| | `explorer/` | Web app, HTTP client, `radicle-httpd` and `radicle-search` | | `desktop/` | Tauri app: Svelte frontend in `src/`, Rust in `crates/` | +| `shared/ui/` | UI code shared by both apps | +| `package.json`, `package-lock.json`, `.npmrc`, `.nvmrc` | The npm workspace, its lockfile and npm and Node settings | | `docs/adr/` | Decisions that affect the whole repository | -| `.github/workflows/` | GitHub CI: `explorer-*.yml` for explorer, `desktop-*.yml` for desktop | +| `.github/workflows/` | GitHub CI: `explorer-*.yml` for explorer, `desktop-*.yml` for desktop, `shared-ui.yml` for the shared UI | | `.buildkite/` | Radicle CI pipelines (explorer only) | | `.ryph/` | Dev machine image and setup for agents, see `.ryph/environment.md` | ## Working in this repo -- Work out which project a change belongs to first, and run every command - from that project's directory. There are no root `npm` or `cargo` - commands. +- Install npm dependencies at the root: `npm ci` for everything, or + `npm ci -w explorer` or `npm ci -w desktop` for one app. Run every other + command from the project's directory; there are no root `cargo` commands. +- Work out which project a change belongs to first. Changes to `shared/ui` + affect both apps: check `shared/ui` and both apps. - A change that touches both projects is two changes: check each project with its own commands. - Explorer's components use legacy Svelte syntax (`$:`, stores, - `export let`), desktop's use Svelte 5 runes. + `export let`), desktop's and the shared ones use Svelte 5 runes. +- Code in `shared/ui` must not import `@tauri-apps/*`, `@bindings`, + `@http-client` or anything else from one app. It takes plain props, and + each app adapts its own data to them. - Record a bigger architectural change as a new ADR, numbered after the last one and in the same format: in `docs/adr/` if it affects the whole repository, in the project's own `docs/adr/` otherwise. @@ -46,7 +56,7 @@ source of truth for anything inside it. use proper English sentences - Ask before adding new dependencies: each one is a supply-chain risk, and installs are gated by `min-release-age` and `strict-allow-scripts` -- Use npm, never `yarn` or `pnpm`: the lockfiles and `.npmrc` settings are +- Use npm, never `yarn` or `pnpm`: the lockfile and `.npmrc` settings are npm's - Updates and audit fixes must respect each project's 7-day cooldown, see "Updating dependencies" below @@ -66,8 +76,9 @@ source of truth for anything inside it. ## Updating dependencies Both projects only install releases that are at least 7 days old: npm through -`min-release-age` in `.npmrc`, Cargo through `cooldown.toml` and -`cargo-cooldown`. Run these from the project's directory: +`min-release-age` in the root `.npmrc`, Cargo through `cooldown.toml` and +`cargo-cooldown`. npm commands cover the whole workspace and change the root +lockfile; run Cargo commands from the project's directory: ```sh npm audit # list advisories @@ -77,11 +88,15 @@ cargo cooldown update -p # update a crate within the cooldown ``` - Never run plain `cargo update`: it ignores `cooldown.toml` +- `katex` is pinned for the whole workspace by an override in the root + `package.json`, so mermaid and both apps use one version. Bump it there as + well as in the apps, or the apps' bump has no effect - Never run `npm audit fix --force`: it takes major-version bumps. Ask first - If a fix is still cooling down, report when it clears and ask before taking it early. Taking it early means reviewing the release's diff against the previous version, then: - - npm: `npm install @ --min-release-age=0` + - npm: `npm install @ -w --min-release-age=0` at + the root - Cargo: add an `[[allow.exact]]` entry to `cooldown.toml` with a comment naming the advisory and the date it can be removed diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bde4e701d..8c83b1e81 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,8 @@ # Contributing This repository holds two projects, each with its own development guide: -`explorer/README.md` and `desktop/README.md`. This file covers what -applies to both. +`explorer/README.md` and `desktop/README.md`, and the UI code they share in +`shared/ui/`. This file covers what applies to all of them. * Before adding any code dependencies, check with the maintainers if this is okay. * Write properly formatted comments: they should be english sentences, eg: @@ -31,9 +31,10 @@ When proposing changes via a patch: Both projects only install releases that are at least 7 days old, to give the ecosystem time to catch compromised packages. npm enforces this through -`min-release-age` in each project's `.npmrc`; Cargo through its -`cooldown.toml`, which needs `cargo install cargo-cooldown cargo-audit`. -From the project's directory: +`min-release-age` in the root `.npmrc`; Cargo through each project's +`cooldown.toml`, which needs `cargo install cargo-cooldown cargo-audit`. npm +commands cover the whole workspace from anywhere in it; run Cargo commands +from the project's directory: ```sh npm audit @@ -46,8 +47,8 @@ Use `cargo cooldown update` rather than `cargo update`, which ignores the cooldown, and avoid `npm audit fix --force`, which takes major-version bumps. When a security fix is still cooling down and can't wait, review the release's -diff against the previous version first. Then install it with -`npm install @ --min-release-age=0`, or allow it in +diff against the previous version first. Then install it at the root with +`npm install @ -w --min-release-age=0`, or allow it in `cooldown.toml` with an `[[allow.exact]]` entry and a comment naming the advisory and the date it can be removed. @@ -107,7 +108,7 @@ filters can tell the projects apart: | `httpd` | `explorer/crates/radicle-httpd/` and `explorer/crates/radicle-search/` | A patch that touches several components gets several labels. Changes to -shared files (`.github/`, `.buildkite/`, `.ryph/`, root docs) get the labels +shared files (`shared/`, `.github/`, `.buildkite/`, `.ryph/`, root files) get the labels of the components they affect. `git push` can't set labels, so add them once the patch is open: diff --git a/README.md b/README.md index b87b072a8..9d29d8ac9 100644 --- a/README.md +++ b/README.md @@ -7,8 +7,12 @@ publishing stack. [radicle.network][app], with the `radicle-httpd` and `radicle-search` backends it talks to. * [`desktop/`](desktop/README.md): the desktop app. +* [`shared/ui/`](shared/ui/AGENTS.md): UI components, design tokens and fonts + used by both. -Each project is built, tested and released on its own; see its README. The +One npm workspace at the root holds all three: install the dependencies there, +with `npm ci -w explorer` or `npm ci -w desktop` for a single app. Each app is +built, tested and released on its own; see its README. The guidelines for contributing to either are in [CONTRIBUTING.md](CONTRIBUTING.md), and decisions that affect the whole repository are in [`docs/adr/`](docs/adr/). diff --git a/desktop/AGENTS.md b/desktop/AGENTS.md index e56751405..fd4fc7f98 100644 --- a/desktop/AGENTS.md +++ b/desktop/AGENTS.md @@ -4,10 +4,12 @@ Tauri desktop app for Radicle. Svelte 5 frontend communicates with a Rust backend via Tauri IPC commands. TypeScript types are generated from Rust structs using ts-rs (`crates/radicle-types/`). -The app lives in `desktop/` of the radicle-gui monorepo. It is its own npm -package and Cargo workspace: run every command here from `desktop/`, and all -paths in this file are relative to it. Conventions shared with explorer are in -the root `AGENTS.md`. +The app lives in `desktop/` of the radicle-gui monorepo. It is a package in the +root npm workspace and its own Cargo workspace: install npm dependencies at the +repository root with `npm ci -w desktop`, and run every other command here from +`desktop/`. All paths in this file are relative to it. Conventions shared with +explorer are in the root `AGENTS.md`, and UI code shared with it lives in +`shared/ui/`. ## Svelte syntax and aliases diff --git a/desktop/README.md b/desktop/README.md index 7313d2955..7bca2514b 100644 --- a/desktop/README.md +++ b/desktop/README.md @@ -4,7 +4,8 @@ This desktop application lets you interact with [Radicle][rad], a peer-to-peer code collaboration and publishing stack. It lives in the `desktop/` folder of the radicle-gui repository, next to the -Radicle web explorer. Run all commands below from `desktop/`. +Radicle web explorer. Install dependencies at the repository root, and run all +other commands below from `desktop/`. ## Installation @@ -29,8 +30,9 @@ Run the following commands to build the desktop app locally: ``` git clone https://seed.radicle.dev/z4V1sjrXqjvFdnCUbxPFqd5p4DtH5.git radicle-gui -cd radicle-gui/desktop -npm install +cd radicle-gui +npm ci -w desktop +cd desktop npm run tauri build ``` diff --git a/explorer/AGENTS.md b/explorer/AGENTS.md index d3b71f916..dbf1d0a1b 100644 --- a/explorer/AGENTS.md +++ b/explorer/AGENTS.md @@ -3,10 +3,12 @@ The Svelte web app for browsing Radicle repositories, its TypeScript HTTP client, and the `radicle-httpd` and `radicle-search` backends it talks to. -The project lives in `explorer/` of the radicle-gui monorepo. It is its own npm -package and Cargo workspace: run every command here from `explorer/`, and all -paths in this file are relative to it. Conventions shared with desktop are in -the root `AGENTS.md`. +The project lives in `explorer/` of the radicle-gui monorepo. It is a package in +the root npm workspace and its own Cargo workspace: install npm dependencies at +the repository root with `npm ci -w explorer`, and run every other command here +from `explorer/`. All paths in this file are relative to it. Conventions shared +with desktop are in the root `AGENTS.md`, and UI code shared with it lives in +`shared/ui/`. ## Checks and linting (tsc, svelte-check, eslint, prettier) diff --git a/explorer/README.md b/explorer/README.md index f4a0ba64b..b8b8e7def 100644 --- a/explorer/README.md +++ b/explorer/README.md @@ -4,8 +4,8 @@ This user interface lets you interact with [Radicle][rad], a peer-to-peer code collaboration and publishing stack, directly from your web browser. It lives in the `explorer/` folder of the radicle-gui repository, next to the -[Radicle desktop app](../desktop/README.md). Run all commands below from -`explorer/`. +[Radicle desktop app](../desktop/README.md). Install dependencies at the +repository root, and run all other commands below from `explorer/`. **Deployment Options:** @@ -24,8 +24,9 @@ Run the following commands to access the web UI locally: ```shell git clone https://seed.radicle.dev/z4V1sjrXqjvFdnCUbxPFqd5p4DtH5.git radicle-gui -cd radicle-gui/explorer -npm install +cd radicle-gui +npm ci -w explorer +cd explorer npm start ``` @@ -37,7 +38,8 @@ There are several ways to deploy the UI publicly. Here are two common options: **Using your own web server:** -1. Run `npm install && npm build` to create a build for deployment +1. Run `npm ci -w explorer` at the repository root, then `npm run build` in + `explorer/` to create a build for deployment 2. Configure your web server to serve the contents of the `/build` directory **Using Vercel (or similar static file hosting):** diff --git a/shared/ui/AGENTS.md b/shared/ui/AGENTS.md new file mode 100644 index 000000000..b1475b902 --- /dev/null +++ b/shared/ui/AGENTS.md @@ -0,0 +1,83 @@ +# @radicle-gui/ui + +UI code shared by explorer and desktop: Svelte components in `components/`, +TypeScript helpers in `lib/`, and the design tokens, stylesheets and fonts in +`public/`. Desktop is the source we extract shared code from. + +The package lives in `shared/ui/` of the radicle-gui monorepo, in the root npm +workspace: install dependencies at the repository root with `npm ci`, and run +every other command here from `shared/ui/`. All paths in this file are +relative to it. Conventions shared with both apps are in the root `AGENTS.md`. + +## Rules + +- Don't import `@tauri-apps/*`, `@bindings`, `@http-client` or anything else + from one app. Components take plain props, and each app adapts its own data + to them +- Write components with current Svelte 5 APIs: runes, callback props and + snippets. Explorer still uses legacy syntax and migrates to Svelte 5 + incrementally: when it adopts an extracted component, update the explorer + components that use it to runes too, rather than shaping the shared + component around legacy syntax +- Import within the package with relative paths. The apps import it as + `@radicle-gui/ui/components/.svelte` and `@radicle-gui/ui/lib/` +- Declare every package the shared code uses at runtime in `package.json`, + with `svelte` as a peer dependency, and ask before adding one + +## Component API + +Shared components take data in and report changes out. They can offer rich +interactions such as editing, but the app owns all data and I/O. + +- Props are plain data in types defined in `lib/types.ts`, never an app's + types, stores or class instances +- Writes are callback props such as `onEdit?: (body: string) => Promise`. + When a callback is absent, the component leaves out that control, which is + how explorer gets the read-only version +- Callbacks may return a promise: the component shows its own pending and + error states while the app does the actual work +- Anything app-specific comes in as a snippet or a string, such as an `href` or + a link snippet. Components never navigate on their own +- State that only the component cares about, such as whether a menu is open or + an unsaved draft, may be internal or `$bindable`. Everything else is passed + in, and never fetched, cached or persisted by the component +- No side effects: no `fetch`, `invoke`, `localStorage`, `location`, polling or + app context. Context defined in this package, such as the theme, is fine +- Style only with scoped CSS and the shared design tokens + +ESLint enforces the import and global restrictions. + +## Prop types + +Both apps' types come from heartwood, through different serializations, and +should converge over time. Keep shared types small so that this doesn't churn +the components: + +- Ask only for the fields a component uses: `UserAvatar` takes a `did`, not a + whole author +- Name and shape shared types after heartwood's types, not either app's. Where + the apps differ, such as explorer's author `id` and desktop's `did`, follow + heartwood +- Define them in `lib/types.ts`, named after domain concepts such as `Author` + or `Reaction`. The first extraction that needs a domain type creates the + file +- Apps pass their own objects when the shapes match, and map them in one place + where they don't. Never import an app's types here + +## Stylesheets and fonts + +The `sharedPublic()` Vite plugin in `vite.ts` serves `public/` at each app's +root URL in dev and adds it to their builds. The apps link the stylesheets in +`index.html` with `vite-ignore`, so Vite doesn't look for them in the app's +own `public/`. Don't add files at paths an app's own `public/` already uses. + +## Checks and tests + +```sh +npm run check # svelte-check, eslint, prettier +npm run format # auto-fix prettier and eslint issues +npm run test:unit +``` + +CI runs these in `.github/workflows/shared-ui.yml`. A change here affects both +apps, so also run explorer's `npm run check` and desktop's `npm run check-js`.