mirror of
https://seed.radicle.dev/rad:z4V1sjrXqjvFdnCUbxPFqd5p4DtH5.git
synced 2026-11-21 14:20:42 +08:00
Core holds the keys of the data both apps read and maps a node's ref updates to the keys they affect. The query cache wraps TanStack Query for runes, as decided in ADRs 4 and 5.
107 lines
5.1 KiB
Markdown
107 lines
5.1 KiB
Markdown
# @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/<Name>.svelte` and `@radicle-gui/ui/lib/<name>`
|
|
- 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<void>`.
|
|
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
|
|
- Props can change at any time when newer data arrives. Keep local state such
|
|
as drafts, scroll position, selection and expanded threads across such
|
|
updates, and key lists by stable ids so items update instead of being
|
|
recreated
|
|
- 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. ADR 4 moves them to `@radicle-gui/core`
|
|
- 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
|
|
|
|
## Query cache
|
|
|
|
`lib/query.svelte.ts` wraps TanStack Query for the apps' views, as decided in
|
|
`docs/adr/0005-reactivity.md`. Only the apps use it; shared components keep
|
|
taking props.
|
|
|
|
- `createQuery` observes one key in the cache. `onInvalidate` runs a
|
|
component's own refresh when its key is invalidated, for data the cache
|
|
doesn't hold, and several components may listen on one key
|
|
- A route loader calls `markLoading` on a key before reading what a component
|
|
then refreshes with `onInvalidate`, so that an invalidation during the load
|
|
refreshes it at mount. `invalidatedSinceLoading` tells whether one came
|
|
- Invalidate with `invalidate` rather than the client's
|
|
`invalidateQueries`, so that a fetch in flight doesn't leave data from
|
|
before the change looking fresh. Use the client's only to join a refetch
|
|
already in flight
|
|
- `pinned` holds a value the user is reading until they ask for the latest
|
|
- Keys come from `@radicle-gui/core/keys`, never ad-hoc arrays
|
|
|
|
## 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`.
|