@ignite-ember/extension-bridge 0.0.0-stage → 0.2.1
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 +202 -0
- package/NOTICE +5 -0
- package/README.md +364 -2
- package/dist/bridge.d.ts +37 -0
- package/dist/bridge.d.ts.map +1 -0
- package/dist/bridge.js +96 -0
- package/dist/bridge.js.map +1 -0
- package/dist/channel.d.ts +26 -0
- package/dist/channel.d.ts.map +1 -0
- package/dist/channel.js +36 -0
- package/dist/channel.js.map +1 -0
- package/dist/contract.d.ts +137 -0
- package/dist/contract.d.ts.map +1 -0
- package/dist/contract.js +9 -0
- package/dist/contract.js.map +1 -0
- package/dist/correlator.d.ts +37 -0
- package/dist/correlator.d.ts.map +1 -0
- package/dist/correlator.js +75 -0
- package/dist/correlator.js.map +1 -0
- package/dist/guestBridge.d.ts +63 -0
- package/dist/guestBridge.d.ts.map +1 -0
- package/dist/guestBridge.js +156 -0
- package/dist/guestBridge.js.map +1 -0
- package/dist/hostModel.d.ts +159 -0
- package/dist/hostModel.d.ts.map +1 -0
- package/dist/hostModel.generated.d.ts +2373 -0
- package/dist/hostModel.generated.d.ts.map +1 -0
- package/dist/hostModel.generated.js +1746 -0
- package/dist/hostModel.generated.js.map +1 -0
- package/dist/hostModel.js +172 -0
- package/dist/hostModel.js.map +1 -0
- package/dist/index.d.ts +12 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +12 -0
- package/dist/index.js.map +1 -0
- package/dist/protocol.d.ts +348 -0
- package/dist/protocol.d.ts.map +1 -0
- package/dist/protocol.js +145 -0
- package/dist/protocol.js.map +1 -0
- package/dist/service.d.ts +168 -0
- package/dist/service.d.ts.map +1 -0
- package/dist/service.js +196 -0
- package/dist/service.js.map +1 -0
- package/dist/signals.d.ts +21 -0
- package/dist/signals.d.ts.map +1 -0
- package/dist/signals.js +52 -0
- package/dist/signals.js.map +1 -0
- package/dist/tokens.d.ts +101 -0
- package/dist/tokens.d.ts.map +1 -0
- package/dist/tokens.js +164 -0
- package/dist/tokens.js.map +1 -0
- package/dist/watchers.d.ts +12 -0
- package/dist/watchers.d.ts.map +1 -0
- package/dist/watchers.js +18 -0
- package/dist/watchers.js.map +1 -0
- package/package.json +53 -4
- package/src/bridge.ts +116 -0
- package/src/channel.ts +48 -0
- package/src/contract.ts +157 -0
- package/src/correlator.ts +88 -0
- package/src/guestBridge.ts +261 -0
- package/src/hostModel.generated.ts +3155 -0
- package/src/hostModel.ts +213 -0
- package/src/index.ts +11 -0
- package/src/protocol.ts +485 -0
- package/src/service.ts +278 -0
- package/src/signals.ts +65 -0
- package/src/tokens.ts +171 -0
- package/src/watchers.ts +18 -0
package/src/service.ts
ADDED
|
@@ -0,0 +1,278 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `bridge.service`: the extension's own service, from its page, as the
|
|
3
|
+
* signed-in person.
|
|
4
|
+
*
|
|
5
|
+
* const notes = await bridge.service.fetch("/v1/notes");
|
|
6
|
+
* const room = await bridge.service.websocket("/v1/rooms/runbook");
|
|
7
|
+
*
|
|
8
|
+
* The page talks to its service directly — the host is for host things.
|
|
9
|
+
* What the host does is the one thing a page cannot: trade the person's
|
|
10
|
+
* igni session for a ten-minute token whose audience is **this
|
|
11
|
+
* extension's service and nothing else**. The page asks for "my token";
|
|
12
|
+
* igni decides whose service that is, from which extension the frame
|
|
13
|
+
* is. The same exchange the extension's process uses (`ext.service`),
|
|
14
|
+
* and the same cache.
|
|
15
|
+
*
|
|
16
|
+
* The token never leaves for anywhere but the service: `fetch` and
|
|
17
|
+
* `websocket` refuse a path that resolves to another origin, so a page
|
|
18
|
+
* cannot hand it to an egress host by accident. The frame's CSP admits
|
|
19
|
+
* the service's origin (`https`/`wss`) and the hosts the manifest
|
|
20
|
+
* declared in `permissions.egress`, and nothing else.
|
|
21
|
+
*
|
|
22
|
+
* `fetch` is a cross-origin call from igni's window. It sends the token
|
|
23
|
+
* and never credentials (`credentials: "omit"`); the service answers it
|
|
24
|
+
* because its route takes a person's token (igni-service's `BearerCors`,
|
|
25
|
+
* which every service gets from `igni.install`).
|
|
26
|
+
*/
|
|
27
|
+
|
|
28
|
+
/** Why `bridge.service` could not do what was asked. */
|
|
29
|
+
export class ServiceError extends Error {
|
|
30
|
+
/**
|
|
31
|
+
* Why the service could not do what was asked.
|
|
32
|
+
*
|
|
33
|
+
* @param code — why it failed: `no_service`, `refused`,
|
|
34
|
+
* `other_origin`, `closed` or `failed`.
|
|
35
|
+
* @param message — a sentence for a person to read.
|
|
36
|
+
*/
|
|
37
|
+
constructor(
|
|
38
|
+
/**
|
|
39
|
+
* `no_service` (none a page may reach), `refused` (igni gave no
|
|
40
|
+
* token — nobody signed in, say), `other_origin`, `closed`, `failed`.
|
|
41
|
+
*/
|
|
42
|
+
readonly code: string,
|
|
43
|
+
message: string,
|
|
44
|
+
) {
|
|
45
|
+
super(message);
|
|
46
|
+
this.name = "ServiceError";
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/** What the host hands back for one token request. */
|
|
51
|
+
export interface IssuedToken {
|
|
52
|
+
/** The bearer token itself. */
|
|
53
|
+
token: string;
|
|
54
|
+
/** Seconds it has left. */
|
|
55
|
+
expiresIn: number;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/** How a socket says who it is, once it is open. */
|
|
59
|
+
export interface ServiceSocketOptions {
|
|
60
|
+
/**
|
|
61
|
+
* The first frame, carrying the token. A browser's WebSocket cannot
|
|
62
|
+
* set an `Authorization` header, and a token in the URL ends up in
|
|
63
|
+
* access logs, so the token goes in the first frame. The default is
|
|
64
|
+
* `{"type": "auth", "token": …}` — what igni's services read (the
|
|
65
|
+
* Artifacts document room, for one).
|
|
66
|
+
*/
|
|
67
|
+
authFrame?: (token: string) => string;
|
|
68
|
+
/** Sub-protocols, passed to the WebSocket as they are. */
|
|
69
|
+
protocols?: string | string[];
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/** `bridge.service`, as a page uses it. */
|
|
73
|
+
export interface ServiceBridge {
|
|
74
|
+
/**
|
|
75
|
+
* The service's URL, or `null` when this extension has none a page
|
|
76
|
+
* may reach — then every other member rejects with `no_service`.
|
|
77
|
+
*/
|
|
78
|
+
readonly url: string | null;
|
|
79
|
+
/**
|
|
80
|
+
* A bearer token for the service. Kept until shortly before it
|
|
81
|
+
* expires and fetched again then; concurrent asks share one fetch.
|
|
82
|
+
*/
|
|
83
|
+
token(): Promise<string>;
|
|
84
|
+
/**
|
|
85
|
+
* `fetch` against the service, with the token. `path` is relative
|
|
86
|
+
* to {@link url}. A `401` fetches a new token and is sent once more.
|
|
87
|
+
*
|
|
88
|
+
* @param path — where to go, relative to the service's URL.
|
|
89
|
+
* @param init — what to send, as `fetch` takes it.
|
|
90
|
+
*/
|
|
91
|
+
fetch(path: string, init?: RequestInit): Promise<Response>;
|
|
92
|
+
/**
|
|
93
|
+
* A WebSocket to `path` on the service (`https` → `wss`), resolved
|
|
94
|
+
* once it is open and has said who it is (see
|
|
95
|
+
* {@link ServiceSocketOptions.authFrame}).
|
|
96
|
+
*
|
|
97
|
+
* @param path — where to open the socket, relative to the service's
|
|
98
|
+
* URL.
|
|
99
|
+
* @param options — how the socket says who it is: the first frame,
|
|
100
|
+
* and the sub-protocols.
|
|
101
|
+
*/
|
|
102
|
+
websocket(path: string, options?: ServiceSocketOptions): Promise<WebSocket>;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/** Fetch a new token when the held one has less than this left. */
|
|
106
|
+
export const RENEW_BEFORE_MS = 60_000;
|
|
107
|
+
|
|
108
|
+
/**
|
|
109
|
+
* The default first frame: `{"type": "auth", "token": …}`.
|
|
110
|
+
*
|
|
111
|
+
* @param token — the bearer token the frame carries.
|
|
112
|
+
*/
|
|
113
|
+
export function authMessage(token: string): string {
|
|
114
|
+
return JSON.stringify({ type: "auth", token });
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/** `bridge.service`'s implementation; the bridge builds one per frame. */
|
|
118
|
+
export class ServiceLink implements ServiceBridge {
|
|
119
|
+
/** The token this link is holding, and when it stops being valid. */
|
|
120
|
+
private held: { token: string; expiresAt: number } | null = null;
|
|
121
|
+
/** The fetch in flight, so two asks share one request to the host. */
|
|
122
|
+
private fetching: Promise<string> | null = null;
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* One link, for one frame.
|
|
126
|
+
*
|
|
127
|
+
* @param url — the service's URL, or `null` when there is none.
|
|
128
|
+
* @param ask — how a token is asked of the host.
|
|
129
|
+
* @param env — what the browser is asked for, when it is not this one.
|
|
130
|
+
*/
|
|
131
|
+
constructor(
|
|
132
|
+
readonly url: string | null,
|
|
133
|
+
private readonly ask: () => Promise<IssuedToken>,
|
|
134
|
+
private readonly env: {
|
|
135
|
+
now?: () => number;
|
|
136
|
+
fetch?: typeof fetch;
|
|
137
|
+
WebSocket?: typeof WebSocket;
|
|
138
|
+
} = {},
|
|
139
|
+
) {}
|
|
140
|
+
|
|
141
|
+
/**
|
|
142
|
+
* A bearer token for the service.
|
|
143
|
+
*
|
|
144
|
+
* @returns — the token, fetched if it is not held or is nearly spent.
|
|
145
|
+
*/
|
|
146
|
+
token(): Promise<string> {
|
|
147
|
+
return this.fresh(false);
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
/**
|
|
151
|
+
* `fetch` against the service, with the token.
|
|
152
|
+
*
|
|
153
|
+
* @param path — where to go, relative to the service's URL.
|
|
154
|
+
* @param init — what to send, as `fetch` takes it.
|
|
155
|
+
* @returns — the service's answer.
|
|
156
|
+
*/
|
|
157
|
+
async fetch(path: string, init: RequestInit = {}): Promise<Response> {
|
|
158
|
+
const target = this.resolve(path, false);
|
|
159
|
+
const send = async (token: string) => {
|
|
160
|
+
const headers = new Headers(init.headers);
|
|
161
|
+
headers.set("Authorization", `Bearer ${token}`);
|
|
162
|
+
const doFetch = this.env.fetch ?? globalThis.fetch.bind(globalThis);
|
|
163
|
+
// The token and nothing else: no cookies, whatever the caller
|
|
164
|
+
// asked, so the service's own website sessions never ride along.
|
|
165
|
+
return doFetch(target, { ...init, headers, credentials: "omit" });
|
|
166
|
+
};
|
|
167
|
+
const first = await send(await this.fresh(false));
|
|
168
|
+
if (first.status !== 401) return first;
|
|
169
|
+
// Revoked or expired early: one new token, one more try.
|
|
170
|
+
return send(await this.fresh(true));
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
/**
|
|
174
|
+
* A socket to the service, with the token in the first frame.
|
|
175
|
+
*
|
|
176
|
+
* @param path — where to open it, relative to the service's URL.
|
|
177
|
+
* @param options — how the socket says who it is.
|
|
178
|
+
* @returns — the open socket.
|
|
179
|
+
*/
|
|
180
|
+
async websocket(
|
|
181
|
+
path: string,
|
|
182
|
+
options: ServiceSocketOptions = {},
|
|
183
|
+
): Promise<WebSocket> {
|
|
184
|
+
const target = this.resolve(path, true);
|
|
185
|
+
const token = await this.fresh(false);
|
|
186
|
+
const Socket = this.env.WebSocket ?? globalThis.WebSocket;
|
|
187
|
+
const frame = (options.authFrame ?? authMessage)(token);
|
|
188
|
+
return new Promise<WebSocket>((resolve, reject) => {
|
|
189
|
+
const socket = new Socket(target, options.protocols);
|
|
190
|
+
const opened = () => {
|
|
191
|
+
socket.removeEventListener("open", opened);
|
|
192
|
+
socket.removeEventListener("close", failed);
|
|
193
|
+
socket.send(frame);
|
|
194
|
+
resolve(socket);
|
|
195
|
+
};
|
|
196
|
+
const failed = () => {
|
|
197
|
+
socket.removeEventListener("open", opened);
|
|
198
|
+
socket.removeEventListener("close", failed);
|
|
199
|
+
reject(
|
|
200
|
+
new ServiceError("closed", `the service closed ${path} before it opened`),
|
|
201
|
+
);
|
|
202
|
+
};
|
|
203
|
+
socket.addEventListener("open", opened);
|
|
204
|
+
// `error` is always followed by `close`; one rejection is enough.
|
|
205
|
+
socket.addEventListener("close", failed);
|
|
206
|
+
});
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
/**
|
|
210
|
+
* A token that is worth handing out: the held one if it has time
|
|
211
|
+
* left, a new one otherwise.
|
|
212
|
+
*
|
|
213
|
+
* @param force — fetch a new one even when the held one is good.
|
|
214
|
+
* @returns — the token.
|
|
215
|
+
*/
|
|
216
|
+
private async fresh(force: boolean): Promise<string> {
|
|
217
|
+
if (this.url === null) {
|
|
218
|
+
throw new ServiceError(
|
|
219
|
+
"no_service",
|
|
220
|
+
"this extension has no service its page may reach",
|
|
221
|
+
);
|
|
222
|
+
}
|
|
223
|
+
const now = (this.env.now ?? Date.now)();
|
|
224
|
+
if (!force && this.held && this.held.expiresAt - now > RENEW_BEFORE_MS) {
|
|
225
|
+
return this.held.token;
|
|
226
|
+
}
|
|
227
|
+
if (this.fetching) return this.fetching;
|
|
228
|
+
this.fetching = this.ask()
|
|
229
|
+
.then((issued) => {
|
|
230
|
+
this.held = {
|
|
231
|
+
token: issued.token,
|
|
232
|
+
expiresAt: (this.env.now ?? Date.now)() + issued.expiresIn * 1000,
|
|
233
|
+
};
|
|
234
|
+
return issued.token;
|
|
235
|
+
})
|
|
236
|
+
.finally(() => {
|
|
237
|
+
this.fetching = null;
|
|
238
|
+
});
|
|
239
|
+
return this.fetching;
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
/**
|
|
243
|
+
* `path` on the service, or a refusal if it is anywhere else.
|
|
244
|
+
*
|
|
245
|
+
* @param path — the path on the service, relative to its URL.
|
|
246
|
+
* @param socket — whether the path is opened as a socket, which turns
|
|
247
|
+
* `https` into `wss`.
|
|
248
|
+
*/
|
|
249
|
+
private resolve(path: string, socket: boolean): string {
|
|
250
|
+
if (this.url === null) {
|
|
251
|
+
throw new ServiceError(
|
|
252
|
+
"no_service",
|
|
253
|
+
"this extension has no service its page may reach",
|
|
254
|
+
);
|
|
255
|
+
}
|
|
256
|
+
const base = new URL(this.url);
|
|
257
|
+
const joined = new URL(
|
|
258
|
+
`${base.pathname.replace(/\/$/, "")}/${path.replace(/^\//, "")}`,
|
|
259
|
+
base,
|
|
260
|
+
);
|
|
261
|
+
// Something like `//elsewhere.example/x` or a full URL would land
|
|
262
|
+
// on another origin, and the token goes only to the service.
|
|
263
|
+
if (
|
|
264
|
+
/^[a-z][a-z0-9+.-]*:/i.test(path) ||
|
|
265
|
+
path.startsWith("//") ||
|
|
266
|
+
joined.origin !== base.origin
|
|
267
|
+
) {
|
|
268
|
+
throw new ServiceError(
|
|
269
|
+
"other_origin",
|
|
270
|
+
`'${path}' is not on this extension's service; its token goes nowhere else`,
|
|
271
|
+
);
|
|
272
|
+
}
|
|
273
|
+
if (socket) {
|
|
274
|
+
joined.protocol = joined.protocol === "https:" ? "wss:" : "ws:";
|
|
275
|
+
}
|
|
276
|
+
return joined.toString();
|
|
277
|
+
}
|
|
278
|
+
}
|
package/src/signals.ts
ADDED
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The host signals a page handles: `bridge.on(signal, fn)`.
|
|
3
|
+
*
|
|
4
|
+
* The first handler of a signal subscribes to it; removing the last one
|
|
5
|
+
* unsubscribes. A refused subscription is reported, not swallowed: to
|
|
6
|
+
* the handler's `onRefused` when it gave one, to the console otherwise.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
import type { HostError, Signal } from "./hostModel.js";
|
|
10
|
+
import type { HostSignalMessage } from "./protocol.js";
|
|
11
|
+
|
|
12
|
+
/** Asks the host to start or stop sending one signal. */
|
|
13
|
+
export type SignalRequest = (
|
|
14
|
+
op: "subscribe" | "unsubscribe",
|
|
15
|
+
signal: string,
|
|
16
|
+
) => Promise<unknown>;
|
|
17
|
+
|
|
18
|
+
export class SignalSubscriptions {
|
|
19
|
+
private readonly handlers = new Map<string, Set<(value: unknown) => void>>();
|
|
20
|
+
|
|
21
|
+
constructor(private readonly request: SignalRequest) {}
|
|
22
|
+
|
|
23
|
+
on<T>(
|
|
24
|
+
signal: Signal<T>,
|
|
25
|
+
fn: (value: T) => void,
|
|
26
|
+
onRefused?: (error: HostError) => void,
|
|
27
|
+
): () => void {
|
|
28
|
+
const wire = signal.name;
|
|
29
|
+
let handlers = this.handlers.get(wire);
|
|
30
|
+
if (handlers === undefined) {
|
|
31
|
+
handlers = new Set();
|
|
32
|
+
this.handlers.set(wire, handlers);
|
|
33
|
+
this.request("subscribe", wire).catch((error: HostError) => {
|
|
34
|
+
if (onRefused) onRefused(error);
|
|
35
|
+
else
|
|
36
|
+
console.warn(
|
|
37
|
+
`igni bridge: subscribing to ${wire} failed: ${error.message}`,
|
|
38
|
+
);
|
|
39
|
+
});
|
|
40
|
+
}
|
|
41
|
+
const handler = fn as (value: unknown) => void;
|
|
42
|
+
handlers.add(handler);
|
|
43
|
+
return () => this.off(wire, handler);
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/** Hand a signal the host sent to everything handling it. */
|
|
47
|
+
deliver(message: HostSignalMessage): void {
|
|
48
|
+
const handlers = this.handlers.get(message.signal);
|
|
49
|
+
if (handlers === undefined) return;
|
|
50
|
+
for (const fn of handlers) fn(message.value);
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
private off(wire: string, handler: (value: unknown) => void): void {
|
|
54
|
+
const current = this.handlers.get(wire);
|
|
55
|
+
if (current === undefined) return;
|
|
56
|
+
current.delete(handler);
|
|
57
|
+
if (current.size > 0) return;
|
|
58
|
+
this.handlers.delete(wire);
|
|
59
|
+
this.request("unsubscribe", wire).catch((error: HostError) => {
|
|
60
|
+
console.warn(
|
|
61
|
+
`igni bridge: unsubscribing from ${wire} failed: ${error.message}`,
|
|
62
|
+
);
|
|
63
|
+
});
|
|
64
|
+
}
|
|
65
|
+
}
|
package/src/tokens.ts
ADDED
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The design tokens an extension may rely on, and how they travel.
|
|
3
|
+
*
|
|
4
|
+
* An extension's page is a different origin, so it cannot read this
|
|
5
|
+
* app's stylesheet — and the CSP on its own origin would block
|
|
6
|
+
* fetching one. So the values are **pushed**, over the bridge, at
|
|
7
|
+
* handshake and again whenever they change.
|
|
8
|
+
*
|
|
9
|
+
* Pushed rather than copied into the package on purpose. A static
|
|
10
|
+
* copy is a second description of the theme, and a second description
|
|
11
|
+
* drifts: `theme.css` defines these across forty-five blocks — a
|
|
12
|
+
* ``:root``, a light override, and a ``prefers-color-scheme`` block
|
|
13
|
+
* per feature. Anything duplicating that is wrong within a release.
|
|
14
|
+
* This reads the live computed values instead, so an extension
|
|
15
|
+
* follows dark mode, light mode, and whatever a group's policy pack
|
|
16
|
+
* has branded, without knowing any of those exist.
|
|
17
|
+
*
|
|
18
|
+
* **This list is the floor.** A token named here is one an extension
|
|
19
|
+
* may build against, and removing or repurposing one is a breaking
|
|
20
|
+
* change under the compatibility policy. A token *not* named here is
|
|
21
|
+
* ours to change freely — which is why the list is curated rather
|
|
22
|
+
* than "every custom property in the stylesheet". Layout internals
|
|
23
|
+
* like ``--rail-width`` and ``--crumb-row-h`` are deliberately absent:
|
|
24
|
+
* they describe this app's chrome, and an extension that positioned
|
|
25
|
+
* itself against them would break the first time we moved something.
|
|
26
|
+
*/
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Published tokens, by what they are for.
|
|
30
|
+
*
|
|
31
|
+
* Grouped because the groups are how an author reads them: pick a
|
|
32
|
+
* surface, pick the text that goes on it, pick a tone for the
|
|
33
|
+
* meaning. Names match the app's own so a reader moving between the
|
|
34
|
+
* two is not translating.
|
|
35
|
+
*/
|
|
36
|
+
export const PUBLISHED_TOKENS = {
|
|
37
|
+
/** Surfaces, back to front. */
|
|
38
|
+
surface: ["--bg", "--bg-inset", "--bg-surface", "--bg-raised"],
|
|
39
|
+
/** Text, in descending prominence. */
|
|
40
|
+
text: ["--fg", "--fg-muted", "--fg-faint"],
|
|
41
|
+
/** Lines between things. */
|
|
42
|
+
line: ["--border", "--border-soft"],
|
|
43
|
+
/** Meaning. ``*-text`` variants are the contrast-safe ones for type. */
|
|
44
|
+
tone: [
|
|
45
|
+
"--success",
|
|
46
|
+
"--warning",
|
|
47
|
+
"--danger",
|
|
48
|
+
"--danger-text",
|
|
49
|
+
"--accent-blue",
|
|
50
|
+
"--accent-blue-text",
|
|
51
|
+
"--accent-green-text",
|
|
52
|
+
"--accent-orange-text",
|
|
53
|
+
"--accent-red-text",
|
|
54
|
+
],
|
|
55
|
+
/** The product's own colour. Use sparingly; it means igni. */
|
|
56
|
+
brand: [
|
|
57
|
+
"--igni-orange",
|
|
58
|
+
"--igni-orange-hover",
|
|
59
|
+
"--igni-red",
|
|
60
|
+
"--igni-gradient",
|
|
61
|
+
],
|
|
62
|
+
/** Shape. */
|
|
63
|
+
form: [
|
|
64
|
+
"--radius-sm",
|
|
65
|
+
"--radius",
|
|
66
|
+
"--radius-lg",
|
|
67
|
+
"--radius-pill",
|
|
68
|
+
"--radius-circle",
|
|
69
|
+
"--font-ui",
|
|
70
|
+
"--font-mono",
|
|
71
|
+
"--shadow-pop",
|
|
72
|
+
],
|
|
73
|
+
/**
|
|
74
|
+
* The type scale. Nine steps, by role rather than by ratio.
|
|
75
|
+
*
|
|
76
|
+
* It replaced hardcoded sizes that included every half-step from
|
|
77
|
+
* 9px to 15px — 11.5px, 12px and 12.5px were one size written
|
|
78
|
+
* three ways. Build against the role, not the pixel.
|
|
79
|
+
*/
|
|
80
|
+
type: [
|
|
81
|
+
"--text-2xs",
|
|
82
|
+
"--text-xs",
|
|
83
|
+
"--text-sm",
|
|
84
|
+
"--text-md",
|
|
85
|
+
"--text-lg",
|
|
86
|
+
"--text-xl",
|
|
87
|
+
"--text-2xl",
|
|
88
|
+
"--text-3xl",
|
|
89
|
+
"--text-4xl",
|
|
90
|
+
],
|
|
91
|
+
/**
|
|
92
|
+
* The spacing scale. Published so an extension's layout sits on the
|
|
93
|
+
* same rhythm as the app around it rather than next to it.
|
|
94
|
+
*
|
|
95
|
+
* These steps are the ones igni already used — they were written as
|
|
96
|
+
* literals in three hundred and seventy-five places, which is why
|
|
97
|
+
* adopting them changed nothing on screen.
|
|
98
|
+
*/
|
|
99
|
+
space: [
|
|
100
|
+
"--space-1",
|
|
101
|
+
"--space-2",
|
|
102
|
+
"--space-3",
|
|
103
|
+
"--space-4",
|
|
104
|
+
"--space-5",
|
|
105
|
+
"--space-6",
|
|
106
|
+
"--space-7",
|
|
107
|
+
"--space-8",
|
|
108
|
+
"--space-10",
|
|
109
|
+
"--space-12",
|
|
110
|
+
"--space-16",
|
|
111
|
+
],
|
|
112
|
+
} as const;
|
|
113
|
+
|
|
114
|
+
/**
|
|
115
|
+
* Every published token name, flat.
|
|
116
|
+
*
|
|
117
|
+
* Derived rather than listed. A second list would be a second place
|
|
118
|
+
* to forget — and the groups above are an object literal, where a
|
|
119
|
+
* repeated key silently keeps only the last one. That happened: the
|
|
120
|
+
* type scale was added as `text`, which was already the foreground
|
|
121
|
+
* colours, and `--fg` disappeared without a word.
|
|
122
|
+
*/
|
|
123
|
+
export const TOKEN_NAMES: readonly string[] =
|
|
124
|
+
Object.values(PUBLISHED_TOKENS).flat();
|
|
125
|
+
|
|
126
|
+
/** Token name → current value. */
|
|
127
|
+
export type ThemeTokens = Record<string, string>;
|
|
128
|
+
|
|
129
|
+
/**
|
|
130
|
+
* Read the published tokens as they are right now.
|
|
131
|
+
*
|
|
132
|
+
* Computed values, not declared ones: a token defined in a media
|
|
133
|
+
* query or overridden by a `data-theme` attribute resolves here to
|
|
134
|
+
* what the user is actually looking at, which is the only answer
|
|
135
|
+
* worth sending.
|
|
136
|
+
*
|
|
137
|
+
* @param root — the element whose computed styles are read; the
|
|
138
|
+
* document's own root by default.
|
|
139
|
+
*/
|
|
140
|
+
export function readThemeTokens(
|
|
141
|
+
root: Element = document.documentElement,
|
|
142
|
+
): ThemeTokens {
|
|
143
|
+
const computed = getComputedStyle(root);
|
|
144
|
+
const out: ThemeTokens = {};
|
|
145
|
+
for (const name of TOKEN_NAMES) {
|
|
146
|
+
const value = computed.getPropertyValue(name).trim();
|
|
147
|
+
// A token the host has not defined is omitted rather than sent
|
|
148
|
+
// empty: the guest's stylesheet carries a fallback for each, and
|
|
149
|
+
// an empty string would override it with nothing.
|
|
150
|
+
if (value) out[name] = value;
|
|
151
|
+
}
|
|
152
|
+
return out;
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/**
|
|
156
|
+
* Apply tokens inside the extension's own document.
|
|
157
|
+
*
|
|
158
|
+
* Called by the guest bridge. Separate from reading them so the two
|
|
159
|
+
* halves can be tested without a frame between them.
|
|
160
|
+
*
|
|
161
|
+
* @param tokens — what to apply: each published name and the value it
|
|
162
|
+
* takes.
|
|
163
|
+
* @param root — the element they are applied to.
|
|
164
|
+
*/
|
|
165
|
+
export function applyThemeTokens(tokens: ThemeTokens, root: HTMLElement): void {
|
|
166
|
+
for (const [name, value] of Object.entries(tokens)) {
|
|
167
|
+
// Only published names, even though the host is trusted: a typo
|
|
168
|
+
// on our side should not silently define something in theirs.
|
|
169
|
+
if (TOKEN_NAMES.includes(name)) root.style.setProperty(name, value);
|
|
170
|
+
}
|
|
171
|
+
}
|
package/src/watchers.ts
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/** Functions following one value: added, removed, and told of a change. */
|
|
2
|
+
export class Watchers<T> {
|
|
3
|
+
private readonly fns = new Set<(value: T) => void>();
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Follow the value. Returns an unsubscribe, which answers whether it
|
|
7
|
+
* stopped anything: true the first time, false after.
|
|
8
|
+
*/
|
|
9
|
+
add(fn: (value: T) => void): () => void {
|
|
10
|
+
this.fns.add(fn);
|
|
11
|
+
return () => this.fns.delete(fn);
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
/** Tell every watcher the value is now `value`. */
|
|
15
|
+
emit(value: T): void {
|
|
16
|
+
for (const fn of this.fns) fn(value);
|
|
17
|
+
}
|
|
18
|
+
}
|