runtime: plugin UI kit (api.ui: toast, alert, confirm, prompt, dialog, modal) and theme API (api.theme, --wb-* vars); theme JSON Schema; waybetter 0.2.0
The kit draws in one shadow DOM host in the active theme's colors, corners and font and repaints live; accessible dialogs (focus trap and return, Esc/Enter rules, alertdialog for alerts and confirms), stacking with inert, toasts with actions, reduced motion, text-only content (ui.h), and scope.ui closes a plugin's dialogs on dispose. api.toast routes to it.
This commit is contained in:
parent
1eab4a9de5
commit
f6d52512a0
8 changed files with 1627 additions and 25 deletions
|
|
@ -5,8 +5,10 @@ window, extended in place the way BetterDiscord extends Discord. Websites and se
|
|||
heavy Electron client alike: every wayBetter app is the same shell, runtime and one small adapter.
|
||||
|
||||
- **`waybetter/runtime/*`**: the page runtime. One DOM-mutation/animation-frame hub, one
|
||||
fetch/XHR hub, a plugin API core, an OKLab theme color model, split-pane rail hiding, link
|
||||
routing and account change reporting.
|
||||
fetch/XHR hub, a plugin API core with a themed UI kit (toasts, alerts, confirmations, prompts,
|
||||
dialogs), a theme API, an OKLab theme color model, split-pane rail hiding, link routing and
|
||||
account change reporting.
|
||||
- **`waybetter/theme.schema.json`**: the JSON Schema of wayBetter theme files.
|
||||
- **`waybetter/shell/*`**: pure models for the app chrome around the pages: address bar chips,
|
||||
dock/split-pane rules, dragged links, account profiles, the update chip, command palette
|
||||
ranking and window controls. The Tauri window API is passed in by the caller, never imported.
|
||||
|
|
@ -43,9 +45,11 @@ pieces. The source comments document each module's contract.
|
|||
- `linkRouting`: routes clicks on the app's own links per the "links to app pages" setting.
|
||||
- `netHub`: one shared fetch/XHR hook for URL rewrites, gates and passive JSON taps.
|
||||
- `paneNav`: hides a redundant navigation rail when two panes show the same account.
|
||||
- `pluginApi`: small helpers shared by user JS plugins.
|
||||
- `pluginApi`: small helpers shared by user JS plugins, including `ui` and `theme`.
|
||||
- `site`: the page-side composition root for an adapter.
|
||||
- `themeApi`: the active theme as values (`ResolvedTheme`), `--wb-*` CSS variables, contrast helpers.
|
||||
- `themeTokens`: the OKLab color model themes are built on.
|
||||
- `ui`: the plugin UI kit (see below).
|
||||
|
||||
**Shell**
|
||||
|
||||
|
|
@ -58,6 +62,62 @@ pieces. The source comments document each module's contract.
|
|||
- `updateModel`: the titlebar update chip model.
|
||||
- `windowControls`: native window calls for the titlebar, resize grips and caption buttons.
|
||||
|
||||
## Plugin UI kit (`runtime/ui`)
|
||||
|
||||
Plugins get it as `api.ui` (and `scope.ui`, which closes whatever it opened on `scope.dispose()`).
|
||||
Everything is drawn in one Shadow DOM host, so the site's CSS cannot restyle it, and it takes its
|
||||
colors, corners and font from the active theme (`api.theme`), live.
|
||||
|
||||
```js
|
||||
const ui = this.scope.ui;
|
||||
ui.toast('Link copied'); // tones: neutral, info, success, warning, danger
|
||||
ui.toast('Post hidden', { action: { label: 'Undo', onClick: undo } });
|
||||
await ui.alert({ title: 'Saved', message: 'Kept on this device only.', tone: 'success' });
|
||||
if (await ui.confirm({ title: 'Delete this note?', confirmLabel: 'Delete', danger: true })) remove();
|
||||
const name = await ui.prompt({ title: 'Rename', value: 'Reading', validate: v => v.trim() ? null : 'Required' });
|
||||
const dialog = ui.dialog({
|
||||
title: 'Settings',
|
||||
content: body => body.append(ui.h('label', { class: 'wb-check' }, ui.h('input', { type: 'checkbox' }), 'Hide trends')),
|
||||
actions: [{ label: 'Cancel' }, { label: 'Save', tone: 'primary', default: true, onClick: save }],
|
||||
});
|
||||
```
|
||||
|
||||
- `modal(options)` is the primitive under all of them; `dialog` is a `role="dialog"`, `alert` /
|
||||
`confirm` are `role="alertdialog"`. All are `aria-modal`, labelled by their title and described
|
||||
by their message.
|
||||
- Focus moves in, Tab/Shift+Tab wrap inside, and focus returns to where it was. Esc dismisses;
|
||||
Enter in a single-line field (Ctrl/Cmd+Enter in a textarea) runs the `default` action. A
|
||||
destructive `confirm` starts on Cancel.
|
||||
- Backdrop clicks dismiss alerts and confirmations only (a press that started in a field and ended
|
||||
on the backdrop does not count). Keys typed in a dialog never reach the page's own shortcuts.
|
||||
- Dialogs stack (lower ones become `inert`); toasts stack (four at most), pause while hovered or
|
||||
focused and are a polite live region (`role="alert"` for danger).
|
||||
- `prefers-reduced-motion` turns off the animations. Text is always set as text; `ui.h(tag,
|
||||
props, ...children)` builds content without `innerHTML`, string handlers or `javascript:` URLs.
|
||||
- Classes for content: `wb-field`, `wb-label`, `wb-hint`, `wb-check`, `wb-input`, `wb-mono`,
|
||||
`wb-divider`, `wb-row`, `wb-muted`; per-dialog CSS goes in `css`.
|
||||
|
||||
`createUiKit(window, { theme })` builds a kit outside the plugin API; `theme` is a `ThemeApi` from
|
||||
`createThemeApi(window, source)`, where `source` is the site's `{ current(), onChange() }`.
|
||||
|
||||
## Themes
|
||||
|
||||
`api.theme.current()` returns the active theme resolved: `colors` (`bg`, `surface`, `elevated`,
|
||||
`border`, `text`, `muted`, `accent`, `onAccent`, `inverse`, `onInverse`, `page`), `radius`,
|
||||
`buttonRadius`, `font`, `mode` and `siteDefault` (true when the site's own colors show).
|
||||
`api.theme.onChange(fn)` fires after it changes. The same values are CSS custom properties on
|
||||
`:root` (`--wb-bg`, `--wb-text`, `--wb-accent`, `--wb-radius`, `--wb-font`, …), so plugin CSS can
|
||||
use `var(--wb-accent)`.
|
||||
|
||||
Theme files are JSON; `theme.schema.json` describes every field and its limits (the app clamps
|
||||
out-of-range values when it imports a file). Point a theme at it for editor completion and checks:
|
||||
|
||||
```json
|
||||
{ "$schema": "https://unpkg.com/waybetter/theme.schema.json", "name": "Midnight Mint", "colors": { "bg": "#0b1110", "text": "#e8f3ef", "accent": "#3ddc97" } }
|
||||
```
|
||||
|
||||
or, in a project that installs the package, `"$schema": "./node_modules/waybetter/theme.schema.json"`.
|
||||
|
||||
## Projects using wayBetter
|
||||
|
||||
| Project | Target | What it is |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue