@glazeen/mod-sdk 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +221 -2
- package/bin/bearbar-mod.js +3 -0
- package/client/bb.css +58 -0
- package/client/bb.js +157 -0
- package/dist/bb-JW737zq0.d.ts +266 -0
- package/dist/cli.js +457 -0
- package/dist/global.d.ts +19 -0
- package/dist/global.js +0 -0
- package/dist/index.d.ts +33 -0
- package/dist/index.js +267 -0
- package/docs/api.md +229 -0
- package/docs/guide.md +200 -0
- package/docs/manifest.md +187 -0
- package/docs/runtime.md +144 -0
- package/docs/styling.md +118 -0
- package/package.json +66 -3
- package/schema/bearbar.mod.schema.json +276 -0
package/docs/manifest.md
ADDED
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
# bearbar.mod.json reference
|
|
2
|
+
|
|
3
|
+
Every mod folder has a `bearbar.mod.json` at its root. It is plain JSON (a UTF-8 BOM is
|
|
4
|
+
allowed). The [JSON Schema](../schema/bearbar.mod.schema.json) describes it for editors, and
|
|
5
|
+
`bearbar-mod validate` checks it, including the rules the schema can't express.
|
|
6
|
+
|
|
7
|
+
```json
|
|
8
|
+
{
|
|
9
|
+
"$schema": "https://unpkg.com/@glazeen/mod-sdk/schema/bearbar.mod.schema.json",
|
|
10
|
+
"id": "weather-lite",
|
|
11
|
+
"name": "Weather lite",
|
|
12
|
+
"version": "1.0.0",
|
|
13
|
+
"apiVersion": 1,
|
|
14
|
+
"description": "Temperature for one city.",
|
|
15
|
+
"author": "you",
|
|
16
|
+
"sizes": { "s": 1, "m": 2 },
|
|
17
|
+
"tile": "tile.html",
|
|
18
|
+
"panel": "panel.html",
|
|
19
|
+
"panelSize": { "width": 300, "height": 240 },
|
|
20
|
+
"permissions": ["net:api.example.com", "open-url"],
|
|
21
|
+
"settings": {
|
|
22
|
+
"city": { "type": "text", "label": "City", "placeholder": "Milan" },
|
|
23
|
+
"unit": {
|
|
24
|
+
"type": "select",
|
|
25
|
+
"label": "Unit",
|
|
26
|
+
"default": "c",
|
|
27
|
+
"options": [
|
|
28
|
+
{ "value": "c", "label": "Celsius" },
|
|
29
|
+
{ "value": "f", "label": "Fahrenheit" }
|
|
30
|
+
]
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## Fields
|
|
37
|
+
|
|
38
|
+
| Field | Type | Required | Notes |
|
|
39
|
+
| ------------- | -------- | -------- | ----------------------------------------------------------- |
|
|
40
|
+
| `$schema` | string | | Schema URL, for editors. Ignored by the dock. |
|
|
41
|
+
| `id` | string | yes | See [id](#id). |
|
|
42
|
+
| `name` | string | yes | Shown in the widget picker and as the frame title. |
|
|
43
|
+
| `version` | string | yes | Semantic version, like `"1.2.0"`. Shown in the picker. |
|
|
44
|
+
| `apiVersion` | integer | | Mod API version the mod targets. Missing means `1`. |
|
|
45
|
+
| `description` | string | | One line for the widget picker. |
|
|
46
|
+
| `author` | string | | Shown in the picker when there is no description. |
|
|
47
|
+
| `sizes` | object | | See [sizes](#sizes). Default `{ "m": 2 }`. |
|
|
48
|
+
| `tile` | string | yes | The tile page. See [pages](#tile-and-panel). |
|
|
49
|
+
| `panel` | string | | The popup page, opened with `bb.panel.open()`. |
|
|
50
|
+
| `panelSize` | object | | `{ "width", "height" }` in pixels. Default `320 × 360`. |
|
|
51
|
+
| `permissions` | string[] | | See [permissions](#permissions). |
|
|
52
|
+
| `settings` | object | | See [settings](#settings). |
|
|
53
|
+
| `category` | string | | Ignored: mods are always listed under Mods. |
|
|
54
|
+
|
|
55
|
+
Unknown top-level properties are a warning (with a suggestion when they look like a typo), so
|
|
56
|
+
a manifest written for a newer dock still loads.
|
|
57
|
+
|
|
58
|
+
### id
|
|
59
|
+
|
|
60
|
+
2 to 64 characters: letters, digits, `.`, `_` and `-`, starting with a letter or digit
|
|
61
|
+
(`MOD_ID_PATTERN`). Pick something unique, such as `yourname.weather`.
|
|
62
|
+
|
|
63
|
+
- The id names the widget in the user's saved dock layout. Changing it orphans every placed
|
|
64
|
+
tile of the mod.
|
|
65
|
+
- A mod in the user folder replaces a bundled mod with the same id.
|
|
66
|
+
- An id that matches a built-in widget's is ignored.
|
|
67
|
+
|
|
68
|
+
When the manifest has no valid id, the dock falls back to the folder name and shows an error
|
|
69
|
+
on the tile.
|
|
70
|
+
|
|
71
|
+
### sizes
|
|
72
|
+
|
|
73
|
+
The tile width in dock units for each size the mod supports. One unit is one square tile;
|
|
74
|
+
fractions are allowed.
|
|
75
|
+
|
|
76
|
+
```json
|
|
77
|
+
"sizes": { "s": 1, "m": 2.5, "l": 4 }
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
- Keys are `s`, `m` and `l`; values are positive numbers.
|
|
81
|
+
- The user picks the size from the widget menu, among the sizes you list. New tiles start at
|
|
82
|
+
`m` if you list it, otherwise at the first listed size.
|
|
83
|
+
- Without `sizes`, the mod has one size, `m`, two units wide.
|
|
84
|
+
- The current size is `bb.size`, and `bb.on("size")` reports changes.
|
|
85
|
+
|
|
86
|
+
### tile and panel
|
|
87
|
+
|
|
88
|
+
Paths to `.html` files inside the mod folder, relative to it (`"tile.html"`,
|
|
89
|
+
`"pages/panel.html"`). Absolute paths, drive letters, URLs and `..` are rejected. The file
|
|
90
|
+
must exist, or the tile shows an error.
|
|
91
|
+
|
|
92
|
+
`panelSize` only matters when there is a `panel`.
|
|
93
|
+
|
|
94
|
+
### permissions
|
|
95
|
+
|
|
96
|
+
| Permission | What it allows |
|
|
97
|
+
| ------------------- | ----------------------------------------------------------------------- |
|
|
98
|
+
| `net:<host>` | `bb.fetch()` to that host, over https. |
|
|
99
|
+
| `net:*.example.com` | `bb.fetch()` to `example.com` and all its subdomains. |
|
|
100
|
+
| `open-url` | `bb.openUrl()` opens http(s) links in the default browser. |
|
|
101
|
+
| `system` | `bb.on("system")` receives CPU and RAM usage every 2 seconds. |
|
|
102
|
+
|
|
103
|
+
- Hosts are matched case-insensitively and without a port or path: `net:api.example.com`, not
|
|
104
|
+
`net:https://api.example.com/v1`.
|
|
105
|
+
- Duplicates are an error. Unknown permissions are an error for the validator; the dock ignores
|
|
106
|
+
them.
|
|
107
|
+
- Without a permission, the matching call fails: `bb.fetch` resolves with `ok: false`, the
|
|
108
|
+
others reject.
|
|
109
|
+
|
|
110
|
+
There is no permission for file system, clipboard, notifications or other native access.
|
|
111
|
+
|
|
112
|
+
### settings
|
|
113
|
+
|
|
114
|
+
An object mapping each setting key to a field. The dock generates the settings popup from it,
|
|
115
|
+
in the order you declare the fields, and passes the values to the page as `bb.config`.
|
|
116
|
+
|
|
117
|
+
```json
|
|
118
|
+
"settings": {
|
|
119
|
+
"city": { "type": "text", "label": "City", "placeholder": "Milan" },
|
|
120
|
+
"count": { "type": "number", "label": "Items", "default": 5, "min": 1, "max": 20 },
|
|
121
|
+
"compact": { "type": "toggle", "label": "Compact", "default": false },
|
|
122
|
+
"unit": { "type": "select", "label": "Unit", "default": "c",
|
|
123
|
+
"options": [{ "value": "c", "label": "Celsius" }, { "value": "f", "label": "Fahrenheit" }] }
|
|
124
|
+
}
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Every field has:
|
|
128
|
+
|
|
129
|
+
| Property | Type | Required | Notes |
|
|
130
|
+
| ------------- | ------ | -------- | -------------------------------------------------------- |
|
|
131
|
+
| `type` | string | yes | `text`, `number`, `toggle` or `select`. |
|
|
132
|
+
| `label` | string | yes | Shown next to the control. |
|
|
133
|
+
| `description` | string | | Help text under the control. |
|
|
134
|
+
| `visibleWhen` | object | | `{ "field", "equals" }`. See below. |
|
|
135
|
+
| `default` | varies | | The value until the user changes it. |
|
|
136
|
+
|
|
137
|
+
Per type:
|
|
138
|
+
|
|
139
|
+
| Type | Value in `bb.config` | Extra properties |
|
|
140
|
+
| -------- | -------------------- | ----------------------------------------------------- |
|
|
141
|
+
| `text` | string | `placeholder` (string) |
|
|
142
|
+
| `number` | number | `min`, `max`, `step` (numbers; `step` > 0) |
|
|
143
|
+
| `toggle` | boolean | |
|
|
144
|
+
| `select` | string | `options`: `[{ "value", "label" }]`, at least one |
|
|
145
|
+
|
|
146
|
+
Rules the validator enforces:
|
|
147
|
+
|
|
148
|
+
- Properties that don't belong to the field's type are errors (with a suggestion for typos).
|
|
149
|
+
- `default` must have the field's type. A select default must be one of the option values.
|
|
150
|
+
- Select option values must be unique, and options have only `value` and `label`.
|
|
151
|
+
- `min` can't be greater than `max`. A number default outside `min..max` is a warning.
|
|
152
|
+
|
|
153
|
+
**Defaults.** `bb.config` holds every field that has a `default`, overridden by what the user
|
|
154
|
+
set. A field without a default is missing from `bb.config` until the user sets it.
|
|
155
|
+
|
|
156
|
+
**visibleWhen.** Shows a field only while another setting has a given value. `field` must name
|
|
157
|
+
another setting in the same manifest; `equals` is a string, number or boolean compared with
|
|
158
|
+
`===`.
|
|
159
|
+
|
|
160
|
+
```json
|
|
161
|
+
"source": { "type": "select", "label": "Source", "default": "auto",
|
|
162
|
+
"options": [{ "value": "auto", "label": "Automatic" }, { "value": "city", "label": "City" }] },
|
|
163
|
+
"city": { "type": "text", "label": "City", "visibleWhen": { "field": "source", "equals": "city" } }
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
Hiding a field doesn't remove its value from `bb.config`.
|
|
167
|
+
|
|
168
|
+
**Typing settings in TypeScript.** `InferConfig<typeof manifest>` derives the `bb.config` type
|
|
169
|
+
from settings declared with `defineManifest`. See the
|
|
170
|
+
[package README](../README.md#typed-config).
|
|
171
|
+
|
|
172
|
+
## What the dock does with a broken manifest
|
|
173
|
+
|
|
174
|
+
The dock is lenient so a small mistake doesn't remove a widget from someone's dock:
|
|
175
|
+
|
|
176
|
+
- Invalid JSON: the mod is listed under its folder name, with the parse error on the tile.
|
|
177
|
+
- Missing `name`, `version` or `tile`: filled in from the id, `"0.0.0"` and `"tile.html"`.
|
|
178
|
+
- Invalid `id` or a missing page: the mod is listed with an error on the tile.
|
|
179
|
+
- Other mistakes (a bad setting, an unknown permission) are not checked when loading.
|
|
180
|
+
|
|
181
|
+
The validator is strict about all of these. Run it before you share a mod.
|
|
182
|
+
|
|
183
|
+
## Versioning
|
|
184
|
+
|
|
185
|
+
`version` is your mod's version; the dock shows it but doesn't compare it. `apiVersion` is the
|
|
186
|
+
version of the mod API you wrote against. See
|
|
187
|
+
[API versions](../README.md#api-versions).
|
package/docs/runtime.md
ADDED
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
# Sandbox and runtime
|
|
2
|
+
|
|
3
|
+
How the dock loads and isolates mods, and the message protocol between a mod page and the
|
|
4
|
+
dock. Mod authors need the [sandbox rules](#the-sandbox); the [protocol](#the-protocol) matters
|
|
5
|
+
only if you work on the `bb` runtime or host mods in another app.
|
|
6
|
+
|
|
7
|
+
## Loading
|
|
8
|
+
|
|
9
|
+
- The dock scans two folders: the mods bundled with bearbar, and `%APPDATA%\bearbar\mods`.
|
|
10
|
+
Each subfolder with a `bearbar.mod.json` is a mod. A user mod replaces a bundled mod with the
|
|
11
|
+
same id.
|
|
12
|
+
- The user folder is watched. Any change rescans both folders after 300 ms and reloads the
|
|
13
|
+
mod pages on the dock.
|
|
14
|
+
- Pages are served from `bbmod://mods/<id>/<path>`. The dock adds the runtime to each HTML
|
|
15
|
+
page by inserting `<link rel="stylesheet" href="bbmod://mods/_sdk/sdk.css">` and
|
|
16
|
+
`<script src="bbmod://mods/_sdk/sdk.js">` right after `<head>` (or at the start of the
|
|
17
|
+
file when there is no `<head>`). So `bb` exists before your own scripts run.
|
|
18
|
+
- Files are served with `Cache-Control: no-cache`. Paths outside the mod folder get `403`.
|
|
19
|
+
|
|
20
|
+
Served file types:
|
|
21
|
+
|
|
22
|
+
| Extension | Content type |
|
|
23
|
+
| ------------------------------- | ------------------------ |
|
|
24
|
+
| `.html` | `text/html` |
|
|
25
|
+
| `.js`, `.mjs` | `text/javascript` |
|
|
26
|
+
| `.css` | `text/css` |
|
|
27
|
+
| `.json` | `application/json` |
|
|
28
|
+
| `.svg`, `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp` | images |
|
|
29
|
+
| `.woff2`, `.woff` | fonts |
|
|
30
|
+
|
|
31
|
+
Any other extension gets `415 Unsupported Media Type`.
|
|
32
|
+
|
|
33
|
+
## The sandbox
|
|
34
|
+
|
|
35
|
+
Each page runs in an `<iframe sandbox="allow-scripts">`. That means:
|
|
36
|
+
|
|
37
|
+
- **Opaque origin.** No cookies, `localStorage`, `sessionStorage` or `IndexedDB` (they throw).
|
|
38
|
+
Use [`bb.storage`](api.md#bbstorage).
|
|
39
|
+
- **No navigation, popups, forms or dialogs.** Links don't open, `window.open` and form
|
|
40
|
+
submission do nothing, `alert`/`confirm`/`prompt` are blocked. Use
|
|
41
|
+
[`bb.openUrl`](api.md#bbopenurlurl) for links.
|
|
42
|
+
- **No access to the dock.** No Node, no Electron, no access to the dock's DOM or other mods.
|
|
43
|
+
|
|
44
|
+
Every response also carries this Content Security Policy:
|
|
45
|
+
|
|
46
|
+
```
|
|
47
|
+
default-src 'none';
|
|
48
|
+
script-src bbmod: 'unsafe-inline';
|
|
49
|
+
style-src bbmod: 'unsafe-inline';
|
|
50
|
+
img-src bbmod: data:;
|
|
51
|
+
font-src bbmod: data:;
|
|
52
|
+
connect-src 'none';
|
|
53
|
+
frame-src 'none';
|
|
54
|
+
form-action 'none'
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
- Inline and local scripts and styles work. Scripts and styles from the web don't: copy
|
|
58
|
+
libraries into the mod folder.
|
|
59
|
+
- `eval` and `new Function` are blocked, so libraries that compile code at runtime (some
|
|
60
|
+
template engines, some chart libraries' "unsafe" builds) won't work.
|
|
61
|
+
- `fetch`, `XMLHttpRequest`, `WebSocket` and `EventSource` are blocked. All network traffic goes
|
|
62
|
+
through [`bb.fetch`](api.md#bbfetchurl-init).
|
|
63
|
+
- Images and fonts load from the mod folder or `data:` URLs only.
|
|
64
|
+
- Prefer classic `<script src>` tags. Module scripts aren't a supported setup.
|
|
65
|
+
|
|
66
|
+
**Right-click** belongs to the dock: the runtime cancels the page's context menu and asks the
|
|
67
|
+
dock to open the widget menu (Settings, Size, Remove) instead.
|
|
68
|
+
|
|
69
|
+
All mods share the `bbmod://mods` origin for serving, so however many mods are on the dock they
|
|
70
|
+
cost one extra renderer process together, not one each. Isolation between them comes from the
|
|
71
|
+
sandbox, not from separate origins.
|
|
72
|
+
|
|
73
|
+
## Permission checks
|
|
74
|
+
|
|
75
|
+
Permissions are checked by the dock, outside the page, against the manifest on disk:
|
|
76
|
+
|
|
77
|
+
- `bb.fetch` runs in the main process. It requires `https:`, matches the URL's host against
|
|
78
|
+
the `net:` permissions, sends no cookies or credentials, times out after 15 seconds and
|
|
79
|
+
refuses responses over 2 MB.
|
|
80
|
+
- `bb.openUrl` checks `open-url` and only opens `http:` and `https:` URLs.
|
|
81
|
+
- The `system` subscription checks `system`.
|
|
82
|
+
|
|
83
|
+
The runtime in the page is a convenience: bypassing it gains nothing, since every privileged
|
|
84
|
+
action goes through these checks.
|
|
85
|
+
|
|
86
|
+
## The protocol
|
|
87
|
+
|
|
88
|
+
The runtime ([`client/bb.js`](../client/bb.js)) talks to the dock with `postMessage`. Every
|
|
89
|
+
message is a plain object with `bb: true`. The page posts to `parent` with target origin
|
|
90
|
+
`"*"` (its own origin is opaque); each side accepts messages only from the other window.
|
|
91
|
+
|
|
92
|
+
### Handshake
|
|
93
|
+
|
|
94
|
+
1. The runtime posts `{ bb: true, type: "hello" }` as soon as it loads.
|
|
95
|
+
2. The dock answers:
|
|
96
|
+
|
|
97
|
+
```js
|
|
98
|
+
{ bb: true, type: "init", size, config, preview, surface, theme }
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
The runtime stores the state, applies the theme (CSS variables and `data-*` attributes on
|
|
102
|
+
`<html>`) and resolves `bb.ready`.
|
|
103
|
+
|
|
104
|
+
### Calls
|
|
105
|
+
|
|
106
|
+
The page sends `{ bb: true, type: "call", id, method, args }` with a numeric `id` that
|
|
107
|
+
increases per page. The dock answers `{ bb: true, type: "reply", id, ok: true, value }` or
|
|
108
|
+
`{ bb: true, type: "reply", id, ok: false, error }`, and the runtime resolves or rejects the
|
|
109
|
+
matching promise.
|
|
110
|
+
|
|
111
|
+
| `method` | `args` | `value` |
|
|
112
|
+
| ------------------ | ----------------------------------- | ------------------------------- |
|
|
113
|
+
| `fetch` | `[{ url, method?, headers?, body? }]` | `{ ok, status, text, error? }` |
|
|
114
|
+
| `storage.get` | `[key]` | the stored value |
|
|
115
|
+
| `storage.set` | `[key, value]` | `true` |
|
|
116
|
+
| `panel.open` | `[]` | `true` |
|
|
117
|
+
| `panel.close` | `[]` | `true` |
|
|
118
|
+
| `openUrl` | `[url]` | `true` |
|
|
119
|
+
| `settings.open` | `[]` | `true` |
|
|
120
|
+
| `system.subscribe` | `[]` | `true` |
|
|
121
|
+
|
|
122
|
+
`headers` is normalised to a plain object before sending. An unknown method fails with
|
|
123
|
+
`unknown method <name>`.
|
|
124
|
+
|
|
125
|
+
### Pushes from the dock
|
|
126
|
+
|
|
127
|
+
| `type` | Fields | Runtime effect |
|
|
128
|
+
| -------- | -------- | --------------------------------------------------- |
|
|
129
|
+
| `config` | `config` | Updates `bb.config`, emits `config`. |
|
|
130
|
+
| `size` | `size` | Updates `bb.size`, emits `size`. |
|
|
131
|
+
| `theme` | `theme` | Applies the theme, emits `theme`. |
|
|
132
|
+
| `system` | `stats` | Emits `system` (after `system.subscribe`). |
|
|
133
|
+
|
|
134
|
+
### From the page
|
|
135
|
+
|
|
136
|
+
| `type` | Meaning |
|
|
137
|
+
| ------------- | ------------------------------------------------------------- |
|
|
138
|
+
| `hello` | The runtime loaded; send `init`. |
|
|
139
|
+
| `call` | See [calls](#calls). |
|
|
140
|
+
| `contextmenu` | The user right-clicked; open the widget menu (tiles only). |
|
|
141
|
+
|
|
142
|
+
Changing the protocol in a way an older runtime or dock can't handle is a breaking change of
|
|
143
|
+
the mod API (see [API versions](../README.md#api-versions)). New methods, pushes and fields are
|
|
144
|
+
additive.
|
package/docs/styling.md
ADDED
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
# Styling a mod
|
|
2
|
+
|
|
3
|
+
The dock gives every mod page its look through CSS variables and `data-*` attributes on
|
|
4
|
+
`<html>`, plus a small base stylesheet. Use them and your mod follows the user's theme,
|
|
5
|
+
material and accent colour without extra code.
|
|
6
|
+
|
|
7
|
+
## The base stylesheet
|
|
8
|
+
|
|
9
|
+
Injected before your own styles ([`client/bb.css`](../client/bb.css)). It:
|
|
10
|
+
|
|
11
|
+
- sets a transparent background, so the dock's material shows through,
|
|
12
|
+
- uses the dock's text colour, font and small font size,
|
|
13
|
+
- removes body margins and scrolling (`overflow: hidden`) and fills the frame,
|
|
14
|
+
- turns off text selection and sets `box-sizing: border-box` everywhere,
|
|
15
|
+
- makes buttons inherit the font and colour.
|
|
16
|
+
|
|
17
|
+
Override any of it in your own CSS.
|
|
18
|
+
|
|
19
|
+
## Helper classes
|
|
20
|
+
|
|
21
|
+
These match the built-in tiles:
|
|
22
|
+
|
|
23
|
+
| Class | Use |
|
|
24
|
+
| ---------- | --------------------------------------------------------------------- |
|
|
25
|
+
| `bb-tile` | Root of a tile: full height, centred row with padding. |
|
|
26
|
+
| `bb-stack` | A column of lines, tight line height. |
|
|
27
|
+
| `bb-label` | Small uppercase caption in the dim colour. |
|
|
28
|
+
| `bb-value` | Large display number, tabular figures. |
|
|
29
|
+
| `bb-dim` | Secondary text colour. |
|
|
30
|
+
| `bb-up` | Green, for rising values. |
|
|
31
|
+
| `bb-down` | Red, for falling values. |
|
|
32
|
+
|
|
33
|
+
```html
|
|
34
|
+
<div class="bb-tile">
|
|
35
|
+
<div class="bb-stack">
|
|
36
|
+
<span class="bb-label">BTC</span>
|
|
37
|
+
<span class="bb-value">64,250</span>
|
|
38
|
+
</div>
|
|
39
|
+
<span class="bb-up">+2.4%</span>
|
|
40
|
+
</div>
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## CSS variables
|
|
44
|
+
|
|
45
|
+
| Variable | What |
|
|
46
|
+
| -------------------- | ------------------------------------------------------------- |
|
|
47
|
+
| `--bb-text` | Main text colour. |
|
|
48
|
+
| `--bb-text-dim` | Secondary text colour. |
|
|
49
|
+
| `--bb-accent` | The user's accent colour, for fills. |
|
|
50
|
+
| `--bb-accent-2` | The accent tuned for text and thin strokes. |
|
|
51
|
+
| `--bb-green` | Positive values. |
|
|
52
|
+
| `--bb-red` | Negative values and errors. |
|
|
53
|
+
| `--bb-orange` | Warnings. |
|
|
54
|
+
| `--bb-surface` | Background of a control or card on the tile. |
|
|
55
|
+
| `--bb-surface-hover` | The same, hovered. |
|
|
56
|
+
| `--bb-font` | UI font family. |
|
|
57
|
+
| `--bb-font-display` | Font family for large numbers. |
|
|
58
|
+
| `--bb-fs-xs` | Extra-small font size (captions). |
|
|
59
|
+
| `--bb-fs-sm` | Small font size (body text). |
|
|
60
|
+
| `--bb-fs-lg` | Large font size (values). |
|
|
61
|
+
| `--bb-card-radius` | Corner radius of cards. |
|
|
62
|
+
|
|
63
|
+
Values are resolved where the page sits: a tile gets the dock's colours, a panel gets the
|
|
64
|
+
popup's. They change at runtime, so use the variables rather than copying their values.
|
|
65
|
+
|
|
66
|
+
The list is exported as `THEME_TOKENS`. Removing or renaming a variable is a breaking change
|
|
67
|
+
of the mod API; new ones may be added.
|
|
68
|
+
|
|
69
|
+
## Attributes
|
|
70
|
+
|
|
71
|
+
```html
|
|
72
|
+
<html data-theme="dark" data-material="glass" data-tone="dark" data-surface="tile">
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
| Attribute | Values | Meaning |
|
|
76
|
+
| -------------- | ---------------------------- | --------------------------------------------- |
|
|
77
|
+
| `data-tone` | `light`, `dark` | The tone of the surface the page is on. |
|
|
78
|
+
| `data-theme` | `light`, `dark` | The user's theme. |
|
|
79
|
+
| `data-material`| `solid`, `frost`, `glass` | The dock material. |
|
|
80
|
+
| `data-surface` | `tile`, `panel` | Same as `bb.surface`. |
|
|
81
|
+
| `data-style` | `black`, `white`, `frost`, `glass` | Deprecated: kept for older mods. |
|
|
82
|
+
|
|
83
|
+
Style against `data-tone`, not `data-theme`: they can differ. Liquid glass keeps the dock dark
|
|
84
|
+
in light theme, so a tile can be dark while the theme is light.
|
|
85
|
+
|
|
86
|
+
```css
|
|
87
|
+
.chart-line { stroke: var(--bb-accent-2); }
|
|
88
|
+
[data-tone="light"] .shadow { opacity: 0.4; }
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
## The theme event
|
|
92
|
+
|
|
93
|
+
The dock updates the variables and attributes for you when the user changes the theme,
|
|
94
|
+
material or accent, so CSS needs nothing more. For canvas or SVG you draw from script, listen
|
|
95
|
+
for the change and read the values:
|
|
96
|
+
|
|
97
|
+
```js
|
|
98
|
+
bb.on("theme", (theme) => {
|
|
99
|
+
// theme.tokens["--bb-accent"], theme.attrs.tone, ...
|
|
100
|
+
redraw();
|
|
101
|
+
});
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
`Theme` is `{ tokens: Record<ThemeToken, string>, attrs: ThemeAttrs }`, where `attrs` has
|
|
105
|
+
`theme`, `material`, `tone`, `surface` and the deprecated `style`.
|
|
106
|
+
|
|
107
|
+
## Fonts and images
|
|
108
|
+
|
|
109
|
+
- Bundle fonts (`.woff2`, `.woff`) and images (`.png`, `.jpg`, `.gif`, `.webp`, `.svg`) in the
|
|
110
|
+
mod folder and reference them with relative URLs. `data:` URLs work too.
|
|
111
|
+
- Web fonts and images from the internet are blocked by the sandbox.
|
|
112
|
+
|
|
113
|
+
## Sizing
|
|
114
|
+
|
|
115
|
+
The page fills the tile: its width follows the [`sizes`](manifest.md#sizes) entry for the
|
|
116
|
+
current size, and its height is the dock's. Design for the narrowest size you list. To adapt,
|
|
117
|
+
read `bb.size` (and listen for `size`) or use width media queries in CSS. A panel page is
|
|
118
|
+
exactly `panelSize`.
|
package/package.json
CHANGED
|
@@ -1,6 +1,69 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@glazeen/mod-sdk",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Types, manifest schema, validator and CLI for bearbar dock mods, plus the bb runtime the dock injects.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"bearbar",
|
|
7
|
+
"glazeen",
|
|
8
|
+
"dock",
|
|
9
|
+
"taskbar",
|
|
10
|
+
"widget",
|
|
11
|
+
"mod",
|
|
12
|
+
"sdk",
|
|
13
|
+
"windows"
|
|
14
|
+
],
|
|
15
|
+
"homepage": "https://github.com/glazeen/bearbar/tree/main/packages/mod-sdk#readme",
|
|
16
|
+
"bugs": "https://github.com/glazeen/bearbar/issues",
|
|
17
|
+
"license": "MIT",
|
|
18
|
+
"repository": {
|
|
19
|
+
"type": "git",
|
|
20
|
+
"url": "git+https://github.com/glazeen/bearbar.git",
|
|
21
|
+
"directory": "packages/mod-sdk"
|
|
22
|
+
},
|
|
23
|
+
"type": "module",
|
|
24
|
+
"sideEffects": false,
|
|
25
|
+
"exports": {
|
|
26
|
+
".": {
|
|
27
|
+
"types": "./dist/index.d.ts",
|
|
28
|
+
"default": "./dist/index.js"
|
|
29
|
+
},
|
|
30
|
+
"./global": {
|
|
31
|
+
"types": "./dist/global.d.ts"
|
|
32
|
+
},
|
|
33
|
+
"./client.js": "./client/bb.js",
|
|
34
|
+
"./client.css": "./client/bb.css",
|
|
35
|
+
"./schema.json": "./schema/bearbar.mod.schema.json",
|
|
36
|
+
"./package.json": "./package.json"
|
|
37
|
+
},
|
|
38
|
+
"types": "./dist/index.d.ts",
|
|
39
|
+
"bin": {
|
|
40
|
+
"bearbar-mod": "./bin/bearbar-mod.js"
|
|
41
|
+
},
|
|
42
|
+
"files": [
|
|
43
|
+
"bin",
|
|
44
|
+
"dist",
|
|
45
|
+
"client",
|
|
46
|
+
"docs",
|
|
47
|
+
"schema"
|
|
48
|
+
],
|
|
49
|
+
"engines": {
|
|
50
|
+
"node": ">=20"
|
|
51
|
+
},
|
|
52
|
+
"devDependencies": {
|
|
53
|
+
"@arethetypeswrong/cli": "^0.18.5",
|
|
54
|
+
"@types/node": "^26.6.6",
|
|
55
|
+
"ajv": "^8.20.0",
|
|
56
|
+
"publint": "^0.3.25",
|
|
57
|
+
"tsdown": "^0.23.7",
|
|
58
|
+
"typescript": "^7.0.2"
|
|
59
|
+
},
|
|
60
|
+
"publishConfig": {
|
|
61
|
+
"access": "public"
|
|
62
|
+
},
|
|
63
|
+
"scripts": {
|
|
64
|
+
"build": "tsdown",
|
|
65
|
+
"typecheck": "tsc -p tsconfig.json",
|
|
66
|
+
"test": "node --test \"test/*.test.ts\"",
|
|
67
|
+
"publint": "publint --strict && attw --pack . --profile esm-only --exclude-entrypoints client.js client.css"
|
|
68
|
+
}
|
|
6
69
|
}
|