@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
|
@@ -0,0 +1,266 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Types for the `bb` global the dock injects into every mod page. Plain-JS mods get
|
|
3
|
+
* editor completion with:
|
|
4
|
+
*
|
|
5
|
+
* /// <reference types="@glazeen/mod-sdk/global" />
|
|
6
|
+
*/
|
|
7
|
+
/** Version of the mod API described by this package. See README, "API versions". */
|
|
8
|
+
declare const API_VERSION = 1;
|
|
9
|
+
/** Widget sizes a dock can render. */
|
|
10
|
+
type WidgetSize = "s" | "m" | "l";
|
|
11
|
+
declare const WIDGET_SIZES: readonly WidgetSize[];
|
|
12
|
+
declare const WIDGET_CATEGORIES: readonly ["Essentials", "System", "Productivity", "Weather", "Utilities", "Mods"];
|
|
13
|
+
type WidgetCategory = (typeof WIDGET_CATEGORIES)[number];
|
|
14
|
+
/** Properties every setting field has. */
|
|
15
|
+
interface SettingFieldBase {
|
|
16
|
+
/** Shown next to the control. */
|
|
17
|
+
label: string;
|
|
18
|
+
/** Help text shown under the control. */
|
|
19
|
+
description?: string;
|
|
20
|
+
/** Show the field only while another setting has this value. */
|
|
21
|
+
visibleWhen?: {
|
|
22
|
+
field: string;
|
|
23
|
+
equals: string | number | boolean;
|
|
24
|
+
};
|
|
25
|
+
}
|
|
26
|
+
interface TextField extends SettingFieldBase {
|
|
27
|
+
type: "text";
|
|
28
|
+
default?: string;
|
|
29
|
+
placeholder?: string;
|
|
30
|
+
}
|
|
31
|
+
interface NumberField extends SettingFieldBase {
|
|
32
|
+
type: "number";
|
|
33
|
+
default?: number;
|
|
34
|
+
min?: number;
|
|
35
|
+
max?: number;
|
|
36
|
+
step?: number;
|
|
37
|
+
}
|
|
38
|
+
interface ToggleField extends SettingFieldBase {
|
|
39
|
+
type: "toggle";
|
|
40
|
+
default?: boolean;
|
|
41
|
+
}
|
|
42
|
+
interface SelectOption<V extends string = string> {
|
|
43
|
+
value: V;
|
|
44
|
+
label: string;
|
|
45
|
+
}
|
|
46
|
+
interface SelectField<V extends string = string> extends SettingFieldBase {
|
|
47
|
+
type: "select";
|
|
48
|
+
/** One of the option values. */
|
|
49
|
+
default?: V;
|
|
50
|
+
options: readonly SelectOption<V>[];
|
|
51
|
+
}
|
|
52
|
+
/** One field of the generated settings popup. */
|
|
53
|
+
type SettingField = TextField | NumberField | ToggleField | SelectField;
|
|
54
|
+
/** Declarative settings: the dock generates the settings popup from this. */
|
|
55
|
+
type SettingsSchema = Record<string, SettingField>;
|
|
56
|
+
/**
|
|
57
|
+
* "net:<host>" (bb.fetch to that host over https; "net:*.example.com" covers subdomains),
|
|
58
|
+
* "system" (CPU and RAM usage), "open-url" (open http(s) links in the browser).
|
|
59
|
+
*/
|
|
60
|
+
type Permission = `net:${string}` | "system" | "open-url";
|
|
61
|
+
/** Mod ids: 2-64 chars of letters, digits, ".", "_" or "-", starting with a letter or digit. */
|
|
62
|
+
declare const MOD_ID_PATTERN: RegExp;
|
|
63
|
+
/** The contents of bearbar.mod.json. */
|
|
64
|
+
interface ModManifest {
|
|
65
|
+
/** Unique id. A mod in the user folder overrides a bundled mod with the same id. */
|
|
66
|
+
id: string;
|
|
67
|
+
/** Shown in the widget picker. */
|
|
68
|
+
name: string;
|
|
69
|
+
version: string;
|
|
70
|
+
/** Mod API version the mod targets. Missing means 1. */
|
|
71
|
+
apiVersion?: number;
|
|
72
|
+
/** Shown in the widget picker. */
|
|
73
|
+
description?: string;
|
|
74
|
+
author?: string;
|
|
75
|
+
/** Set by the dock (always "Mods" for third-party mods); a value in the file is ignored. */
|
|
76
|
+
category?: WidgetCategory;
|
|
77
|
+
/** Tile width in dock units for each supported size. Default `{ m: 2 }`. */
|
|
78
|
+
sizes?: Partial<Record<WidgetSize, number>>;
|
|
79
|
+
/** The tile page: an .html file, relative to the mod folder. */
|
|
80
|
+
tile: string;
|
|
81
|
+
/** Optional popup page, opened with `bb.panel.open()`. */
|
|
82
|
+
panel?: string;
|
|
83
|
+
/** Panel size in DIP. */
|
|
84
|
+
panelSize?: {
|
|
85
|
+
width: number;
|
|
86
|
+
height: number;
|
|
87
|
+
};
|
|
88
|
+
/** See {@link Permission}. Typed as strings so unknown permissions load (and are ignored). */
|
|
89
|
+
permissions?: readonly (Permission | (string & {}))[];
|
|
90
|
+
/** The settings popup is generated from this. Values arrive as `bb.config`. */
|
|
91
|
+
settings?: SettingsSchema;
|
|
92
|
+
}
|
|
93
|
+
/**
|
|
94
|
+
* Returns its argument unchanged, typed as a manifest with its literal values kept, so
|
|
95
|
+
* {@link InferConfig} can derive the config type. For mods that write bearbar.mod.json
|
|
96
|
+
* from TypeScript.
|
|
97
|
+
*
|
|
98
|
+
* @example
|
|
99
|
+
* const manifest = defineManifest({
|
|
100
|
+
* id: "weather", name: "Weather", version: "1.0.0", tile: "tile.html",
|
|
101
|
+
* settings: { unit: { type: "select", label: "Unit", default: "c",
|
|
102
|
+
* options: [{ value: "c", label: "Celsius" }, { value: "f", label: "Fahrenheit" }] } },
|
|
103
|
+
* });
|
|
104
|
+
* type Config = InferConfig<typeof manifest>; // { unit: "c" | "f" }
|
|
105
|
+
*/
|
|
106
|
+
declare function defineManifest<const M extends ModManifest>(manifest: M): M;
|
|
107
|
+
type FieldValue<F> = F extends {
|
|
108
|
+
type: "text";
|
|
109
|
+
} ? string : F extends {
|
|
110
|
+
type: "number";
|
|
111
|
+
} ? number : F extends {
|
|
112
|
+
type: "toggle";
|
|
113
|
+
} ? boolean : F extends {
|
|
114
|
+
type: "select";
|
|
115
|
+
options: readonly {
|
|
116
|
+
value: infer V;
|
|
117
|
+
}[];
|
|
118
|
+
} ? V : never;
|
|
119
|
+
type Simplify<T> = { [K in keyof T]: T[K]; } & {};
|
|
120
|
+
/**
|
|
121
|
+
* The `bb.config` type for a manifest or a settings schema. Fields with a `default` are
|
|
122
|
+
* always present; the others are optional until the user sets them.
|
|
123
|
+
*/
|
|
124
|
+
type InferConfig<T extends ModManifest | SettingsSchema> = T extends ModManifest ? T["settings"] extends SettingsSchema ? InferConfig<T["settings"]> : Record<string, never> : Simplify<{ -readonly [K in keyof T as T[K] extends {
|
|
125
|
+
default: unknown;
|
|
126
|
+
} ? K : never]: FieldValue<T[K]>; } & { -readonly [K in keyof T as T[K] extends {
|
|
127
|
+
default: unknown;
|
|
128
|
+
} ? never : K]?: FieldValue<T[K]>; }>;
|
|
129
|
+
/** Which page of the mod is running. */
|
|
130
|
+
type Surface = "tile" | "panel";
|
|
131
|
+
/** CSS custom properties the dock sets on `<html>` of every mod page. */
|
|
132
|
+
declare const THEME_TOKENS: readonly ["--bb-text", "--bb-text-dim", "--bb-accent", "--bb-accent-2", "--bb-green", "--bb-red", "--bb-orange", "--bb-surface", "--bb-surface-hover", "--bb-font", "--bb-font-display", "--bb-fs-xs", "--bb-fs-sm", "--bb-fs-lg", "--bb-card-radius"];
|
|
133
|
+
type ThemeToken = (typeof THEME_TOKENS)[number];
|
|
134
|
+
/** Size limit of `bb.storage`, per widget instance, measured as JSON text. */
|
|
135
|
+
declare const STORAGE_QUOTA: number;
|
|
136
|
+
/** `data-*` attributes the dock sets on `<html>` of every mod page. */
|
|
137
|
+
interface ThemeAttrs {
|
|
138
|
+
theme: "light" | "dark";
|
|
139
|
+
material: "solid" | "frost" | "glass";
|
|
140
|
+
/** The tone of the surface the page sits on. Style against this, not `theme`. */
|
|
141
|
+
tone: "light" | "dark";
|
|
142
|
+
surface: Surface;
|
|
143
|
+
/** @deprecated Pre-theming attribute, kept for older mods. Use `tone` and `material`. */
|
|
144
|
+
style: "black" | "white" | "frost" | "glass";
|
|
145
|
+
}
|
|
146
|
+
/** Theme pushed by the dock. Tokens and attributes are applied to `<html>` for you. */
|
|
147
|
+
interface Theme {
|
|
148
|
+
tokens: Record<ThemeToken, string>;
|
|
149
|
+
attrs: ThemeAttrs;
|
|
150
|
+
}
|
|
151
|
+
interface SystemStats {
|
|
152
|
+
/** CPU load, 0..1 */
|
|
153
|
+
cpu: number;
|
|
154
|
+
/** Memory in use, 0..1 */
|
|
155
|
+
ram: number;
|
|
156
|
+
ramUsedGb: number;
|
|
157
|
+
ramTotalGb: number;
|
|
158
|
+
}
|
|
159
|
+
/** Anything with `Headers`' forEach, so a `Headers` instance fits without the DOM.Iterable lib. */
|
|
160
|
+
interface HeadersLike {
|
|
161
|
+
forEach(callback: (value: string, name: string) => void): void;
|
|
162
|
+
}
|
|
163
|
+
interface BbFetchInit {
|
|
164
|
+
/** Default "GET". */
|
|
165
|
+
method?: string;
|
|
166
|
+
/** A plain object, a `Headers` instance or `[name, value]` pairs. */
|
|
167
|
+
headers?: Record<string, string> | HeadersLike | Iterable<readonly [string, string]>;
|
|
168
|
+
/** Text only. Use `JSON.stringify()` for JSON bodies. */
|
|
169
|
+
body?: string;
|
|
170
|
+
}
|
|
171
|
+
/**
|
|
172
|
+
* Result of `bb.fetch`. Network failures, timeouts (15 s), oversized responses (2 MB),
|
|
173
|
+
* undeclared hosts and preview mode all resolve with `ok: false`, `status: 0` and `error`.
|
|
174
|
+
*/
|
|
175
|
+
interface BbResponse {
|
|
176
|
+
ok: boolean;
|
|
177
|
+
/** HTTP status, or 0 when the request never got a response. */
|
|
178
|
+
status: number;
|
|
179
|
+
/** The response body as text. */
|
|
180
|
+
text: string;
|
|
181
|
+
/** Why the request failed, when `status` is 0. */
|
|
182
|
+
error?: string;
|
|
183
|
+
/** Parses `text`. Throws a SyntaxError on invalid JSON. */
|
|
184
|
+
json<T = unknown>(): T;
|
|
185
|
+
}
|
|
186
|
+
/** Events for `bb.on`. */
|
|
187
|
+
interface BbEvents<Config = Record<string, unknown>> {
|
|
188
|
+
/** The user changed a setting. */
|
|
189
|
+
config: Config;
|
|
190
|
+
/** The user resized the tile. */
|
|
191
|
+
size: WidgetSize;
|
|
192
|
+
/** The theme changed. Tokens are already applied; use this for canvas drawing. */
|
|
193
|
+
theme: Theme;
|
|
194
|
+
/** CPU and RAM usage every 2 s. Needs the "system" permission. */
|
|
195
|
+
system: SystemStats;
|
|
196
|
+
}
|
|
197
|
+
/**
|
|
198
|
+
* Declares the type of `bb.config` for the whole mod, through declaration merging:
|
|
199
|
+
*
|
|
200
|
+
* @example
|
|
201
|
+
* // bb-config.d.ts (any .d.ts file your tsconfig includes)
|
|
202
|
+
* export {};
|
|
203
|
+
* declare module "@glazeen/mod-sdk" {
|
|
204
|
+
* interface Register {
|
|
205
|
+
* config: { coin: "bitcoin" | "ethereum"; currency: string };
|
|
206
|
+
* }
|
|
207
|
+
* }
|
|
208
|
+
*/
|
|
209
|
+
interface Register {}
|
|
210
|
+
/** The config type declared through {@link Register}, or a plain record. */
|
|
211
|
+
type RegisteredConfig = Register extends {
|
|
212
|
+
config: infer C extends object;
|
|
213
|
+
} ? C : Record<string, unknown>;
|
|
214
|
+
/** The API the dock injects into every mod page as the global `bb`. */
|
|
215
|
+
interface Bb<Config extends object = RegisteredConfig> {
|
|
216
|
+
/**
|
|
217
|
+
* Resolves once the dock has sent config, size and theme. Read `bb.config` and `bb.size`
|
|
218
|
+
* after this.
|
|
219
|
+
*
|
|
220
|
+
* @example
|
|
221
|
+
* const { config, size } = await bb.ready;
|
|
222
|
+
*/
|
|
223
|
+
readonly ready: Promise<Bb<Config>>;
|
|
224
|
+
/** Settings values, with defaults applied. */
|
|
225
|
+
readonly config: Config;
|
|
226
|
+
readonly size: WidgetSize;
|
|
227
|
+
readonly surface: Surface;
|
|
228
|
+
/** True inside the widget picker: show sample data. `bb.fetch` is disabled there. */
|
|
229
|
+
readonly preview: boolean;
|
|
230
|
+
/**
|
|
231
|
+
* Listens for a dock event. Returns a function that removes the listener.
|
|
232
|
+
*
|
|
233
|
+
* @example
|
|
234
|
+
* const off = bb.on("config", (config) => render(config));
|
|
235
|
+
*/
|
|
236
|
+
on<E extends keyof BbEvents>(event: E, listener: (value: BbEvents<Config>[E]) => void): () => void;
|
|
237
|
+
/**
|
|
238
|
+
* HTTP request through the dock: https only, to hosts declared as "net:<host>"
|
|
239
|
+
* permissions. Resolves with `ok: false` instead of rejecting when the request fails.
|
|
240
|
+
*
|
|
241
|
+
* @example
|
|
242
|
+
* const res = await bb.fetch("https://api.example.com/price"); // needs "net:api.example.com"
|
|
243
|
+
* if (res.ok) render(res.json<{ price: number }>());
|
|
244
|
+
* else showError(res.error ?? `HTTP ${res.status}`);
|
|
245
|
+
*/
|
|
246
|
+
fetch(url: string | URL, init?: BbFetchInit): Promise<BbResponse>;
|
|
247
|
+
/**
|
|
248
|
+
* Key-value storage per widget instance. Values must be JSON-serialisable; the whole
|
|
249
|
+
* store is limited to {@link STORAGE_QUOTA} (256 KB). `set` rejects when it is full.
|
|
250
|
+
*/
|
|
251
|
+
readonly storage: {
|
|
252
|
+
/** The stored value, or undefined if the key was never set. */
|
|
253
|
+
get<T = unknown>(key: string): Promise<T | undefined>;
|
|
254
|
+
set(key: string, value: unknown): Promise<void>;
|
|
255
|
+
};
|
|
256
|
+
/** The popup declared as "panel" in the manifest. `open` rejects if there is none. */
|
|
257
|
+
readonly panel: {
|
|
258
|
+
open(): Promise<void>;
|
|
259
|
+
close(): Promise<void>;
|
|
260
|
+
};
|
|
261
|
+
/** Opens an http(s) link in the default browser. Needs the "open-url" permission. */
|
|
262
|
+
openUrl(url: string | URL): Promise<void>;
|
|
263
|
+
/** Opens this widget's settings popup. */
|
|
264
|
+
openSettings(): Promise<void>;
|
|
265
|
+
}
|
|
266
|
+
export { WidgetCategory as A, SettingField as C, ToggleField as D, TextField as E, defineManifest as M, WIDGET_CATEGORIES as O, SelectOption as S, SettingsSchema as T, MOD_ID_PATTERN as _, HeadersLike as a, Permission as b, STORAGE_QUOTA as c, THEME_TOKENS as d, Theme as f, InferConfig as g, API_VERSION as h, BbResponse as i, WidgetSize as j, WIDGET_SIZES as k, Surface as l, ThemeToken as m, BbEvents as n, Register as o, ThemeAttrs as p, BbFetchInit as r, RegisteredConfig as s, Bb as t, SystemStats as u, ModManifest as v, SettingFieldBase as w, SelectField as x, NumberField as y };
|