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
b676cca861
commit
965a85f359
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 |
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
{
|
||||
"name": "waybetter",
|
||||
"version": "0.1.1",
|
||||
"version": "0.2.0",
|
||||
"license": "GPL-3.0-or-later",
|
||||
"type": "module",
|
||||
"description": "wayBetter: the framework for apps that run the apps you already use in a light native (Tauri) window and extend them in place. Page runtime (DOM/request hubs, plugins, theme color model, link routing, account reporting) and shell models (address bar, panes, profiles, palette, updates). No dependencies.",
|
||||
"description": "wayBetter: the framework for apps that run the apps you already use in a light native (Tauri) window and extend them in place. Page runtime (DOM/request hubs, plugins, plugin UI kit with themed dialogs and toasts, theme API and theme JSON Schema, theme color model, link routing, account reporting) and shell models (address bar, panes, profiles, palette, updates). No dependencies.",
|
||||
"keywords": [
|
||||
"waybetter",
|
||||
"tauri",
|
||||
|
|
@ -52,10 +52,18 @@
|
|||
"types": "./dist/runtime/site.d.ts",
|
||||
"import": "./dist/runtime/site.js"
|
||||
},
|
||||
"./runtime/themeApi": {
|
||||
"types": "./dist/runtime/themeApi.d.ts",
|
||||
"import": "./dist/runtime/themeApi.js"
|
||||
},
|
||||
"./runtime/themeTokens": {
|
||||
"types": "./dist/runtime/themeTokens.d.ts",
|
||||
"import": "./dist/runtime/themeTokens.js"
|
||||
},
|
||||
"./runtime/ui": {
|
||||
"types": "./dist/runtime/ui.d.ts",
|
||||
"import": "./dist/runtime/ui.js"
|
||||
},
|
||||
"./runtime/*": {
|
||||
"types": "./dist/runtime/*.d.ts",
|
||||
"import": "./dist/runtime/*.js"
|
||||
|
|
@ -95,10 +103,13 @@
|
|||
"./shell/*": {
|
||||
"types": "./dist/shell/*.d.ts",
|
||||
"import": "./dist/shell/*.js"
|
||||
}
|
||||
},
|
||||
"./theme.schema.json": "./theme.schema.json",
|
||||
"./package.json": "./package.json"
|
||||
},
|
||||
"files": [
|
||||
"dist",
|
||||
"theme.schema.json",
|
||||
"README.md",
|
||||
"LICENSE"
|
||||
],
|
||||
|
|
|
|||
156
packages/waybetter/theme.schema.json
Normal file
156
packages/waybetter/theme.schema.json
Normal file
|
|
@ -0,0 +1,156 @@
|
|||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://unpkg.com/waybetter/theme.schema.json",
|
||||
"title": "wayBetter theme",
|
||||
"description": "A wayBetter theme document (data, not a stylesheet). Only `name` is required. Apps sanitize every field before use: values out of range are clamped and unknown values fall back to the default, so this schema describes what is kept unchanged.",
|
||||
"type": "object",
|
||||
"required": ["name"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"$schema": { "type": "string" },
|
||||
"id": { "type": "string", "pattern": "^[a-z0-9-]{1,40}$", "description": "Derived from the name when missing." },
|
||||
"name": { "type": "string", "minLength": 1, "maxLength": 60, "pattern": "\\S" },
|
||||
"description": { "type": "string", "maxLength": 200 },
|
||||
"author": { "type": "string", "maxLength": 60 },
|
||||
"version": { "const": 1 },
|
||||
"mode": { "enum": ["light", "dark", "auto"], "default": "auto", "description": "Which way scrollbars and form controls lean." },
|
||||
"colors": {
|
||||
"description": "bg, text and accent are required; every other role is derived from them when missing. null keeps the site's own colors.",
|
||||
"oneOf": [
|
||||
{ "type": "null" },
|
||||
{
|
||||
"type": "object",
|
||||
"required": ["bg", "text", "accent"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"bg": { "$ref": "#/$defs/hex", "description": "Column background." },
|
||||
"surface": { "$ref": "#/$defs/hex", "description": "Raised surface (cards, inputs)." },
|
||||
"elevated": { "$ref": "#/$defs/hex", "description": "Hover / selected surface." },
|
||||
"border": { "$ref": "#/$defs/hex" },
|
||||
"text": { "$ref": "#/$defs/hex" },
|
||||
"muted": { "$ref": "#/$defs/hex", "description": "Secondary text." },
|
||||
"accent": { "$ref": "#/$defs/hex", "description": "Links, focus, selected tabs." },
|
||||
"inverse": { "$ref": "#/$defs/hex", "description": "The filled primary button." },
|
||||
"onInverse": { "$ref": "#/$defs/hex", "description": "The filled primary button's label." },
|
||||
"page": { "$ref": "#/$defs/hex", "description": "The canvas behind the columns (defaults to bg)." }
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"font": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"family": { "$ref": "#/$defs/fontStack", "description": "Interface font stack; empty keeps the site's font." },
|
||||
"tweet": { "$ref": "#/$defs/fontStack", "description": "Optional stack for post text only." },
|
||||
"scale": { "type": "number", "minimum": 0.85, "maximum": 1.2, "default": 1 },
|
||||
"weight": { "type": "integer", "minimum": 300, "maximum": 500, "default": 400 },
|
||||
"bold": { "type": "integer", "minimum": 500, "maximum": 800, "default": 700 },
|
||||
"tracking": { "type": "number", "minimum": -0.03, "maximum": 0.06, "default": 0, "description": "Letter spacing in em." },
|
||||
"leading": {
|
||||
"description": "Post line height; 0 keeps the site's.",
|
||||
"anyOf": [{ "const": 0 }, { "type": "number", "minimum": 1.2, "maximum": 1.8 }],
|
||||
"default": 0
|
||||
}
|
||||
}
|
||||
},
|
||||
"shape": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"radius": { "type": "integer", "minimum": 0, "maximum": 28, "default": 16, "description": "Card radius in px." },
|
||||
"button": { "type": "integer", "minimum": 0, "maximum": 9999, "default": 9999, "description": "Button radius in px (9999 = pill)." },
|
||||
"avatar": { "enum": ["circle", "rounded", "square"], "default": "circle" }
|
||||
}
|
||||
},
|
||||
"layout": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"column": { "type": "integer", "minimum": 520, "maximum": 820, "default": 600 },
|
||||
"sidebar": { "type": "integer", "minimum": 290, "maximum": 400, "default": 350 },
|
||||
"density": { "enum": ["compact", "default", "comfortable"], "default": "default" },
|
||||
"cards": { "type": "boolean", "default": false },
|
||||
"frame": { "type": "boolean", "default": false }
|
||||
}
|
||||
},
|
||||
"background": {
|
||||
"oneOf": [
|
||||
{
|
||||
"type": "object",
|
||||
"required": ["kind"],
|
||||
"additionalProperties": false,
|
||||
"properties": { "kind": { "const": "none" } }
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"required": ["kind", "from", "to"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"kind": { "const": "gradient" },
|
||||
"from": { "$ref": "#/$defs/hex" },
|
||||
"to": { "$ref": "#/$defs/hex" },
|
||||
"angle": { "type": "integer", "minimum": 0, "maximum": 360, "default": 180 },
|
||||
"glow": { "$ref": "#/$defs/hex" }
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"required": ["kind", "ink"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"kind": { "const": "pattern" },
|
||||
"pattern": { "enum": ["dots", "grid", "diagonal", "scanlines", "paper", "clouds"], "default": "dots" },
|
||||
"ink": { "$ref": "#/$defs/hex" },
|
||||
"opacity": { "type": "number", "minimum": 0, "maximum": 0.6, "default": 0.1 },
|
||||
"size": { "type": "integer", "minimum": 2, "maximum": 400, "default": 24 }
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"required": ["kind", "url"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"kind": { "const": "image" },
|
||||
"url": {
|
||||
"type": "string",
|
||||
"maxLength": 1100000,
|
||||
"pattern": "^data:image/(png|jpeg|webp|gif|avif);base64,[A-Za-z0-9+/]+={0,2}$",
|
||||
"description": "An embedded image (about 800 KB at most). Remote URLs are never loaded."
|
||||
},
|
||||
"fit": { "enum": ["cover", "tile"], "default": "cover" },
|
||||
"dim": { "type": "number", "minimum": 0.35, "maximum": 0.95, "default": 0.6 }
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"effects": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"motion": { "type": "integer", "minimum": 0, "maximum": 400, "default": 0, "description": "Transition length in ms." },
|
||||
"hover": { "enum": ["none", "tint", "lift", "glow"], "default": "none" },
|
||||
"shadow": { "enum": ["none", "soft", "deep"], "default": "none" },
|
||||
"crt": { "type": "boolean", "default": false }
|
||||
}
|
||||
},
|
||||
"css": {
|
||||
"type": "string",
|
||||
"maxLength": 60000,
|
||||
"description": "Free-form CSS appended last. Same trust level as the owner's own Custom CSS; import dialogs say so."
|
||||
}
|
||||
},
|
||||
"$defs": {
|
||||
"hex": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" },
|
||||
"fontStack": {
|
||||
"type": "array",
|
||||
"maxItems": 8,
|
||||
"items": {
|
||||
"anyOf": [
|
||||
{ "enum": ["system-ui", "sans-serif", "serif", "monospace", "cursive", "ui-sans-serif", "ui-serif", "ui-monospace", "ui-rounded", "-apple-system", "BlinkMacSystemFont"] },
|
||||
{ "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9 .\\-]{0,47}$" }
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue