@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/dist/tokens.d.ts
ADDED
|
@@ -0,0 +1,101 @@
|
|
|
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
|
+
* Published tokens, by what they are for.
|
|
29
|
+
*
|
|
30
|
+
* Grouped because the groups are how an author reads them: pick a
|
|
31
|
+
* surface, pick the text that goes on it, pick a tone for the
|
|
32
|
+
* meaning. Names match the app's own so a reader moving between the
|
|
33
|
+
* two is not translating.
|
|
34
|
+
*/
|
|
35
|
+
export declare const PUBLISHED_TOKENS: {
|
|
36
|
+
/** Surfaces, back to front. */
|
|
37
|
+
readonly surface: readonly ["--bg", "--bg-inset", "--bg-surface", "--bg-raised"];
|
|
38
|
+
/** Text, in descending prominence. */
|
|
39
|
+
readonly text: readonly ["--fg", "--fg-muted", "--fg-faint"];
|
|
40
|
+
/** Lines between things. */
|
|
41
|
+
readonly line: readonly ["--border", "--border-soft"];
|
|
42
|
+
/** Meaning. ``*-text`` variants are the contrast-safe ones for type. */
|
|
43
|
+
readonly tone: readonly ["--success", "--warning", "--danger", "--danger-text", "--accent-blue", "--accent-blue-text", "--accent-green-text", "--accent-orange-text", "--accent-red-text"];
|
|
44
|
+
/** The product's own colour. Use sparingly; it means igni. */
|
|
45
|
+
readonly brand: readonly ["--igni-orange", "--igni-orange-hover", "--igni-red", "--igni-gradient"];
|
|
46
|
+
/** Shape. */
|
|
47
|
+
readonly form: readonly ["--radius-sm", "--radius", "--radius-lg", "--radius-pill", "--radius-circle", "--font-ui", "--font-mono", "--shadow-pop"];
|
|
48
|
+
/**
|
|
49
|
+
* The type scale. Nine steps, by role rather than by ratio.
|
|
50
|
+
*
|
|
51
|
+
* It replaced hardcoded sizes that included every half-step from
|
|
52
|
+
* 9px to 15px — 11.5px, 12px and 12.5px were one size written
|
|
53
|
+
* three ways. Build against the role, not the pixel.
|
|
54
|
+
*/
|
|
55
|
+
readonly type: readonly ["--text-2xs", "--text-xs", "--text-sm", "--text-md", "--text-lg", "--text-xl", "--text-2xl", "--text-3xl", "--text-4xl"];
|
|
56
|
+
/**
|
|
57
|
+
* The spacing scale. Published so an extension's layout sits on the
|
|
58
|
+
* same rhythm as the app around it rather than next to it.
|
|
59
|
+
*
|
|
60
|
+
* These steps are the ones igni already used — they were written as
|
|
61
|
+
* literals in three hundred and seventy-five places, which is why
|
|
62
|
+
* adopting them changed nothing on screen.
|
|
63
|
+
*/
|
|
64
|
+
readonly space: readonly ["--space-1", "--space-2", "--space-3", "--space-4", "--space-5", "--space-6", "--space-7", "--space-8", "--space-10", "--space-12", "--space-16"];
|
|
65
|
+
};
|
|
66
|
+
/**
|
|
67
|
+
* Every published token name, flat.
|
|
68
|
+
*
|
|
69
|
+
* Derived rather than listed. A second list would be a second place
|
|
70
|
+
* to forget — and the groups above are an object literal, where a
|
|
71
|
+
* repeated key silently keeps only the last one. That happened: the
|
|
72
|
+
* type scale was added as `text`, which was already the foreground
|
|
73
|
+
* colours, and `--fg` disappeared without a word.
|
|
74
|
+
*/
|
|
75
|
+
export declare const TOKEN_NAMES: readonly string[];
|
|
76
|
+
/** Token name → current value. */
|
|
77
|
+
export type ThemeTokens = Record<string, string>;
|
|
78
|
+
/**
|
|
79
|
+
* Read the published tokens as they are right now.
|
|
80
|
+
*
|
|
81
|
+
* Computed values, not declared ones: a token defined in a media
|
|
82
|
+
* query or overridden by a `data-theme` attribute resolves here to
|
|
83
|
+
* what the user is actually looking at, which is the only answer
|
|
84
|
+
* worth sending.
|
|
85
|
+
*
|
|
86
|
+
* @param root — the element whose computed styles are read; the
|
|
87
|
+
* document's own root by default.
|
|
88
|
+
*/
|
|
89
|
+
export declare function readThemeTokens(root?: Element): ThemeTokens;
|
|
90
|
+
/**
|
|
91
|
+
* Apply tokens inside the extension's own document.
|
|
92
|
+
*
|
|
93
|
+
* Called by the guest bridge. Separate from reading them so the two
|
|
94
|
+
* halves can be tested without a frame between them.
|
|
95
|
+
*
|
|
96
|
+
* @param tokens — what to apply: each published name and the value it
|
|
97
|
+
* takes.
|
|
98
|
+
* @param root — the element they are applied to.
|
|
99
|
+
*/
|
|
100
|
+
export declare function applyThemeTokens(tokens: ThemeTokens, root: HTMLElement): void;
|
|
101
|
+
//# sourceMappingURL=tokens.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB;IAC3B,+BAA+B;;IAE/B,sCAAsC;;IAEtC,4BAA4B;;IAE5B,wEAAwE;;IAYxE,8DAA8D;;IAO9D,aAAa;;IAWb;;;;;;OAMG;;IAYH;;;;;;;OAOG;;CAcK,CAAC;AAEX;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,EAAE,SAAS,MAAM,EACD,CAAC;AAEzC,kCAAkC;AAClC,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEjD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,IAAI,GAAE,OAAkC,GACvC,WAAW,CAWb;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAM7E"}
|
package/dist/tokens.js
ADDED
|
@@ -0,0 +1,164 @@
|
|
|
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
|
+
* Published tokens, by what they are for.
|
|
29
|
+
*
|
|
30
|
+
* Grouped because the groups are how an author reads them: pick a
|
|
31
|
+
* surface, pick the text that goes on it, pick a tone for the
|
|
32
|
+
* meaning. Names match the app's own so a reader moving between the
|
|
33
|
+
* two is not translating.
|
|
34
|
+
*/
|
|
35
|
+
export const PUBLISHED_TOKENS = {
|
|
36
|
+
/** Surfaces, back to front. */
|
|
37
|
+
surface: ["--bg", "--bg-inset", "--bg-surface", "--bg-raised"],
|
|
38
|
+
/** Text, in descending prominence. */
|
|
39
|
+
text: ["--fg", "--fg-muted", "--fg-faint"],
|
|
40
|
+
/** Lines between things. */
|
|
41
|
+
line: ["--border", "--border-soft"],
|
|
42
|
+
/** Meaning. ``*-text`` variants are the contrast-safe ones for type. */
|
|
43
|
+
tone: [
|
|
44
|
+
"--success",
|
|
45
|
+
"--warning",
|
|
46
|
+
"--danger",
|
|
47
|
+
"--danger-text",
|
|
48
|
+
"--accent-blue",
|
|
49
|
+
"--accent-blue-text",
|
|
50
|
+
"--accent-green-text",
|
|
51
|
+
"--accent-orange-text",
|
|
52
|
+
"--accent-red-text",
|
|
53
|
+
],
|
|
54
|
+
/** The product's own colour. Use sparingly; it means igni. */
|
|
55
|
+
brand: [
|
|
56
|
+
"--igni-orange",
|
|
57
|
+
"--igni-orange-hover",
|
|
58
|
+
"--igni-red",
|
|
59
|
+
"--igni-gradient",
|
|
60
|
+
],
|
|
61
|
+
/** Shape. */
|
|
62
|
+
form: [
|
|
63
|
+
"--radius-sm",
|
|
64
|
+
"--radius",
|
|
65
|
+
"--radius-lg",
|
|
66
|
+
"--radius-pill",
|
|
67
|
+
"--radius-circle",
|
|
68
|
+
"--font-ui",
|
|
69
|
+
"--font-mono",
|
|
70
|
+
"--shadow-pop",
|
|
71
|
+
],
|
|
72
|
+
/**
|
|
73
|
+
* The type scale. Nine steps, by role rather than by ratio.
|
|
74
|
+
*
|
|
75
|
+
* It replaced hardcoded sizes that included every half-step from
|
|
76
|
+
* 9px to 15px — 11.5px, 12px and 12.5px were one size written
|
|
77
|
+
* three ways. Build against the role, not the pixel.
|
|
78
|
+
*/
|
|
79
|
+
type: [
|
|
80
|
+
"--text-2xs",
|
|
81
|
+
"--text-xs",
|
|
82
|
+
"--text-sm",
|
|
83
|
+
"--text-md",
|
|
84
|
+
"--text-lg",
|
|
85
|
+
"--text-xl",
|
|
86
|
+
"--text-2xl",
|
|
87
|
+
"--text-3xl",
|
|
88
|
+
"--text-4xl",
|
|
89
|
+
],
|
|
90
|
+
/**
|
|
91
|
+
* The spacing scale. Published so an extension's layout sits on the
|
|
92
|
+
* same rhythm as the app around it rather than next to it.
|
|
93
|
+
*
|
|
94
|
+
* These steps are the ones igni already used — they were written as
|
|
95
|
+
* literals in three hundred and seventy-five places, which is why
|
|
96
|
+
* adopting them changed nothing on screen.
|
|
97
|
+
*/
|
|
98
|
+
space: [
|
|
99
|
+
"--space-1",
|
|
100
|
+
"--space-2",
|
|
101
|
+
"--space-3",
|
|
102
|
+
"--space-4",
|
|
103
|
+
"--space-5",
|
|
104
|
+
"--space-6",
|
|
105
|
+
"--space-7",
|
|
106
|
+
"--space-8",
|
|
107
|
+
"--space-10",
|
|
108
|
+
"--space-12",
|
|
109
|
+
"--space-16",
|
|
110
|
+
],
|
|
111
|
+
};
|
|
112
|
+
/**
|
|
113
|
+
* Every published token name, flat.
|
|
114
|
+
*
|
|
115
|
+
* Derived rather than listed. A second list would be a second place
|
|
116
|
+
* to forget — and the groups above are an object literal, where a
|
|
117
|
+
* repeated key silently keeps only the last one. That happened: the
|
|
118
|
+
* type scale was added as `text`, which was already the foreground
|
|
119
|
+
* colours, and `--fg` disappeared without a word.
|
|
120
|
+
*/
|
|
121
|
+
export const TOKEN_NAMES = Object.values(PUBLISHED_TOKENS).flat();
|
|
122
|
+
/**
|
|
123
|
+
* Read the published tokens as they are right now.
|
|
124
|
+
*
|
|
125
|
+
* Computed values, not declared ones: a token defined in a media
|
|
126
|
+
* query or overridden by a `data-theme` attribute resolves here to
|
|
127
|
+
* what the user is actually looking at, which is the only answer
|
|
128
|
+
* worth sending.
|
|
129
|
+
*
|
|
130
|
+
* @param root — the element whose computed styles are read; the
|
|
131
|
+
* document's own root by default.
|
|
132
|
+
*/
|
|
133
|
+
export function readThemeTokens(root = document.documentElement) {
|
|
134
|
+
const computed = getComputedStyle(root);
|
|
135
|
+
const out = {};
|
|
136
|
+
for (const name of TOKEN_NAMES) {
|
|
137
|
+
const value = computed.getPropertyValue(name).trim();
|
|
138
|
+
// A token the host has not defined is omitted rather than sent
|
|
139
|
+
// empty: the guest's stylesheet carries a fallback for each, and
|
|
140
|
+
// an empty string would override it with nothing.
|
|
141
|
+
if (value)
|
|
142
|
+
out[name] = value;
|
|
143
|
+
}
|
|
144
|
+
return out;
|
|
145
|
+
}
|
|
146
|
+
/**
|
|
147
|
+
* Apply tokens inside the extension's own document.
|
|
148
|
+
*
|
|
149
|
+
* Called by the guest bridge. Separate from reading them so the two
|
|
150
|
+
* halves can be tested without a frame between them.
|
|
151
|
+
*
|
|
152
|
+
* @param tokens — what to apply: each published name and the value it
|
|
153
|
+
* takes.
|
|
154
|
+
* @param root — the element they are applied to.
|
|
155
|
+
*/
|
|
156
|
+
export function applyThemeTokens(tokens, root) {
|
|
157
|
+
for (const [name, value] of Object.entries(tokens)) {
|
|
158
|
+
// Only published names, even though the host is trusted: a typo
|
|
159
|
+
// on our side should not silently define something in theirs.
|
|
160
|
+
if (TOKEN_NAMES.includes(name))
|
|
161
|
+
root.style.setProperty(name, value);
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
//# sourceMappingURL=tokens.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,+BAA+B;IAC/B,OAAO,EAAE,CAAC,MAAM,EAAE,YAAY,EAAE,cAAc,EAAE,aAAa,CAAC;IAC9D,sCAAsC;IACtC,IAAI,EAAE,CAAC,MAAM,EAAE,YAAY,EAAE,YAAY,CAAC;IAC1C,4BAA4B;IAC5B,IAAI,EAAE,CAAC,UAAU,EAAE,eAAe,CAAC;IACnC,wEAAwE;IACxE,IAAI,EAAE;QACJ,WAAW;QACX,WAAW;QACX,UAAU;QACV,eAAe;QACf,eAAe;QACf,oBAAoB;QACpB,qBAAqB;QACrB,sBAAsB;QACtB,mBAAmB;KACpB;IACD,8DAA8D;IAC9D,KAAK,EAAE;QACL,eAAe;QACf,qBAAqB;QACrB,YAAY;QACZ,iBAAiB;KAClB;IACD,aAAa;IACb,IAAI,EAAE;QACJ,aAAa;QACb,UAAU;QACV,aAAa;QACb,eAAe;QACf,iBAAiB;QACjB,WAAW;QACX,aAAa;QACb,cAAc;KACf;IACD;;;;;;OAMG;IACH,IAAI,EAAE;QACJ,YAAY;QACZ,WAAW;QACX,WAAW;QACX,WAAW;QACX,WAAW;QACX,WAAW;QACX,YAAY;QACZ,YAAY;QACZ,YAAY;KACb;IACD;;;;;;;OAOG;IACH,KAAK,EAAE;QACL,WAAW;QACX,WAAW;QACX,WAAW;QACX,WAAW;QACX,WAAW;QACX,WAAW;QACX,WAAW;QACX,WAAW;QACX,YAAY;QACZ,YAAY;QACZ,YAAY;KACb;CACO,CAAC;AAEX;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,WAAW,GACtB,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,IAAI,EAAE,CAAC;AAKzC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAgB,QAAQ,CAAC,eAAe;IAExC,MAAM,QAAQ,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,GAAG,GAAgB,EAAE,CAAC;IAC5B,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,QAAQ,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;QACrD,+DAA+D;QAC/D,iEAAiE;QACjE,kDAAkD;QAClD,IAAI,KAAK;YAAE,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IAC/B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAmB,EAAE,IAAiB;IACrE,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACnD,gEAAgE;QAChE,8DAA8D;QAC9D,IAAI,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACtE,CAAC;AACH,CAAC"}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/** Functions following one value: added, removed, and told of a change. */
|
|
2
|
+
export declare class Watchers<T> {
|
|
3
|
+
private readonly fns;
|
|
4
|
+
/**
|
|
5
|
+
* Follow the value. Returns an unsubscribe, which answers whether it
|
|
6
|
+
* stopped anything: true the first time, false after.
|
|
7
|
+
*/
|
|
8
|
+
add(fn: (value: T) => void): () => void;
|
|
9
|
+
/** Tell every watcher the value is now `value`. */
|
|
10
|
+
emit(value: T): void;
|
|
11
|
+
}
|
|
12
|
+
//# sourceMappingURL=watchers.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"watchers.d.ts","sourceRoot":"","sources":["../src/watchers.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,qBAAa,QAAQ,CAAC,CAAC;IACrB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAiC;IAErD;;;OAGG;IACH,GAAG,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI;IAKvC,mDAAmD;IACnD,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;CAGrB"}
|
package/dist/watchers.js
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/** Functions following one value: added, removed, and told of a change. */
|
|
2
|
+
export class Watchers {
|
|
3
|
+
fns = new Set();
|
|
4
|
+
/**
|
|
5
|
+
* Follow the value. Returns an unsubscribe, which answers whether it
|
|
6
|
+
* stopped anything: true the first time, false after.
|
|
7
|
+
*/
|
|
8
|
+
add(fn) {
|
|
9
|
+
this.fns.add(fn);
|
|
10
|
+
return () => this.fns.delete(fn);
|
|
11
|
+
}
|
|
12
|
+
/** Tell every watcher the value is now `value`. */
|
|
13
|
+
emit(value) {
|
|
14
|
+
for (const fn of this.fns)
|
|
15
|
+
fn(value);
|
|
16
|
+
}
|
|
17
|
+
}
|
|
18
|
+
//# sourceMappingURL=watchers.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"watchers.js","sourceRoot":"","sources":["../src/watchers.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,MAAM,OAAO,QAAQ;IACF,GAAG,GAAG,IAAI,GAAG,EAAsB,CAAC;IAErD;;;OAGG;IACH,GAAG,CAAC,EAAsB;QACxB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACjB,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACnC,CAAC;IAED,mDAAmD;IACnD,IAAI,CAAC,KAAQ;QACX,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,GAAG;YAAE,EAAE,CAAC,KAAK,CAAC,CAAC;IACvC,CAAC;CACF"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,55 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ignite-ember/extension-bridge",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.2.1",
|
|
4
|
+
"description": "The guest half of the bridge between an igni extension's page and igni: connect(), RPC, navigation, theme. The host imports the same protocol, so there is one description of the wire.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"igni",
|
|
7
|
+
"extension",
|
|
8
|
+
"bridge",
|
|
9
|
+
"iframe",
|
|
10
|
+
"postmessage"
|
|
11
|
+
],
|
|
12
|
+
"license": "Apache-2.0",
|
|
13
|
+
"author": "Ignite Ember (https://igni.sh/)",
|
|
14
|
+
"homepage": "https://igni.sh/docs/sdk/extension-bridge",
|
|
15
|
+
"documentation": "https://igni.sh/docs/sdk/extension-bridge",
|
|
16
|
+
"bugs": {
|
|
17
|
+
"url": "https://github.com/ignite-ember/igni-sdk/issues"
|
|
18
|
+
},
|
|
19
|
+
"repository": {
|
|
20
|
+
"type": "git",
|
|
21
|
+
"url": "git+https://github.com/ignite-ember/igni-sdk.git",
|
|
22
|
+
"directory": "packages/extension-bridge"
|
|
23
|
+
},
|
|
24
|
+
"type": "module",
|
|
25
|
+
"main": "./dist/index.js",
|
|
26
|
+
"types": "./dist/index.d.ts",
|
|
27
|
+
"exports": {
|
|
28
|
+
".": {
|
|
29
|
+
"types": "./dist/index.d.ts",
|
|
30
|
+
"node": "./dist/index.js",
|
|
31
|
+
"default": "./src/index.ts"
|
|
32
|
+
},
|
|
33
|
+
"./protocol": {
|
|
34
|
+
"types": "./dist/protocol.d.ts",
|
|
35
|
+
"node": "./dist/protocol.js",
|
|
36
|
+
"default": "./src/protocol.ts"
|
|
37
|
+
},
|
|
38
|
+
"./tokens": {
|
|
39
|
+
"types": "./dist/tokens.d.ts",
|
|
40
|
+
"node": "./dist/tokens.js",
|
|
41
|
+
"default": "./src/tokens.ts"
|
|
42
|
+
}
|
|
43
|
+
},
|
|
44
|
+
"files": [
|
|
45
|
+
"src",
|
|
46
|
+
"dist",
|
|
47
|
+
"!src/**/*.test.ts",
|
|
48
|
+
"README.md",
|
|
49
|
+
"LICENSE",
|
|
50
|
+
"NOTICE"
|
|
51
|
+
],
|
|
52
|
+
"publishConfig": {
|
|
53
|
+
"access": "public"
|
|
54
|
+
}
|
|
55
|
+
}
|
package/src/bridge.ts
ADDED
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The guest half: what an extension's page imports to reach igni.
|
|
3
|
+
*
|
|
4
|
+
* This is the file that becomes a published package. Nothing in it
|
|
5
|
+
* imports from the rest of the app, and nothing in it is trusted by
|
|
6
|
+
* the host — every check is on the other side. What it owes an
|
|
7
|
+
* extension author is an object that behaves like the client they
|
|
8
|
+
* would have had if their panel were part of the app, so that porting
|
|
9
|
+
* one is not a rewrite.
|
|
10
|
+
*
|
|
11
|
+
* The shape it presents is `rpc(method, args, timeoutMs)`, which is
|
|
12
|
+
* the whole surface the first panel ported behind it used. Everything else here —
|
|
13
|
+
* navigate, close, theme, params — is what a panel needed from the
|
|
14
|
+
* app around it and used to get by being inside it.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
import { HostChannel } from "./channel.js";
|
|
18
|
+
import type { Bridge } from "./contract.js";
|
|
19
|
+
import { DEFAULT_TIMEOUT_MS, GuestBridge } from "./guestBridge.js";
|
|
20
|
+
import {
|
|
21
|
+
type ExtensionSettings,
|
|
22
|
+
type LaunchParams,
|
|
23
|
+
type RpcArgs,
|
|
24
|
+
isHostMessage,
|
|
25
|
+
} from "./protocol.js";
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Wait for the host's `hello`, then hand back the bridge.
|
|
29
|
+
*
|
|
30
|
+
* Connecting is asynchronous because the host issues the nonce, and
|
|
31
|
+
* without one there is nothing to say. An extension that renders
|
|
32
|
+
* before awaiting this is rendering before it knows which extension
|
|
33
|
+
* it is.
|
|
34
|
+
*
|
|
35
|
+
* `P` and `S` name the extension's own launch parameters and settings;
|
|
36
|
+
* the bridge passes on what the host sent without checking it against
|
|
37
|
+
* them.
|
|
38
|
+
*
|
|
39
|
+
* @param options — how long to wait for the host's `hello` before
|
|
40
|
+
* giving up: `timeoutMs`, in milliseconds, and thirty seconds by
|
|
41
|
+
* default.
|
|
42
|
+
*/
|
|
43
|
+
export function connect<
|
|
44
|
+
P extends LaunchParams = LaunchParams,
|
|
45
|
+
S extends ExtensionSettings = ExtensionSettings,
|
|
46
|
+
>(options: { timeoutMs?: number } = {}): Promise<Bridge<P, S>> {
|
|
47
|
+
const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
|
|
48
|
+
const host = window.parent;
|
|
49
|
+
if (host === window) {
|
|
50
|
+
return Promise.reject(
|
|
51
|
+
new Error(
|
|
52
|
+
"igni bridge: this page is not framed by a host, so there is nothing to connect to",
|
|
53
|
+
),
|
|
54
|
+
);
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
return new Promise<Bridge<P, S>>((resolve, reject) => {
|
|
58
|
+
const timer = setTimeout(() => {
|
|
59
|
+
window.removeEventListener("message", onHello);
|
|
60
|
+
reject(
|
|
61
|
+
new Error(`igni bridge: no hello from the host within ${timeoutMs}ms`),
|
|
62
|
+
);
|
|
63
|
+
}, timeoutMs);
|
|
64
|
+
|
|
65
|
+
function onHello(event: MessageEvent) {
|
|
66
|
+
if (event.source !== host) return;
|
|
67
|
+
if (!isHostMessage(event.data) || event.data.kind !== "hello") return;
|
|
68
|
+
clearTimeout(timer);
|
|
69
|
+
window.removeEventListener("message", onHello);
|
|
70
|
+
const channel = new HostChannel(host, event.data.nonce);
|
|
71
|
+
const bridge = new GuestBridge<P, S>(channel, event.data);
|
|
72
|
+
window.addEventListener("message", (message: MessageEvent) => {
|
|
73
|
+
if (!channel.isFrom(message) || !isHostMessage(message.data)) return;
|
|
74
|
+
bridge.receive(message.data);
|
|
75
|
+
});
|
|
76
|
+
resolve(expose(bridge));
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
window.addEventListener("message", onHello);
|
|
80
|
+
});
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* The bridge as the page holds it: a plain object whose members close
|
|
85
|
+
* over the one that does the work. So `const { rpc } = bridge`,
|
|
86
|
+
* `onClick={bridge.close}` and `{ ...bridge }` behave as they did before
|
|
87
|
+
* the bridge was a class, and nothing the page did not ask for — the
|
|
88
|
+
* nonce, the requests in flight — is one of its properties.
|
|
89
|
+
*/
|
|
90
|
+
function expose<P extends LaunchParams, S extends ExtensionSettings>(
|
|
91
|
+
bridge: GuestBridge<P, S>,
|
|
92
|
+
): Bridge<P, S> {
|
|
93
|
+
return {
|
|
94
|
+
extensionId: bridge.extensionId,
|
|
95
|
+
host: bridge.host,
|
|
96
|
+
service: bridge.service,
|
|
97
|
+
on: (signal, fn, onRefused) => bridge.on(signal, fn, onRefused),
|
|
98
|
+
get params() {
|
|
99
|
+
return bridge.params;
|
|
100
|
+
},
|
|
101
|
+
settings: bridge.settings,
|
|
102
|
+
get theme() {
|
|
103
|
+
return bridge.theme;
|
|
104
|
+
},
|
|
105
|
+
get tokens() {
|
|
106
|
+
return bridge.tokens;
|
|
107
|
+
},
|
|
108
|
+
rpc: <T>(method: string, args?: RpcArgs, timeoutMs?: number) =>
|
|
109
|
+
bridge.rpc<T>(method, args, timeoutMs),
|
|
110
|
+
navigate: (to) => bridge.navigate(to),
|
|
111
|
+
close: () => bridge.close(),
|
|
112
|
+
onTheme: (fn) => bridge.onTheme(fn),
|
|
113
|
+
onParams: (fn) => bridge.onParams(fn),
|
|
114
|
+
setLocation: (state) => bridge.setLocation(state),
|
|
115
|
+
};
|
|
116
|
+
}
|
package/src/channel.ts
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The guest's line to the window it is framed in: who that window is,
|
|
3
|
+
* and the nonce every message to it must carry.
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
import { BRIDGE_VERSION, type GuestMessage } from "./protocol.js";
|
|
7
|
+
|
|
8
|
+
/** A guest message without the envelope `HostChannel` adds. */
|
|
9
|
+
export type GuestBody = {
|
|
10
|
+
[K in GuestMessage["kind"]]: Omit<
|
|
11
|
+
Extract<GuestMessage, { kind: K }>,
|
|
12
|
+
"igni" | "nonce"
|
|
13
|
+
>;
|
|
14
|
+
}[GuestMessage["kind"]];
|
|
15
|
+
|
|
16
|
+
export class HostChannel {
|
|
17
|
+
constructor(
|
|
18
|
+
private readonly host: Window,
|
|
19
|
+
private readonly nonce: string,
|
|
20
|
+
) {}
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Did this event come from the host? The host is the only window that
|
|
24
|
+
* can reach this frame's parent slot, so the source is the check that
|
|
25
|
+
* matters. The origin is not pinned: the guest does not know which
|
|
26
|
+
* origin the app is served from, and learning it from the message
|
|
27
|
+
* would make the check circular.
|
|
28
|
+
*/
|
|
29
|
+
isFrom(event: MessageEvent): boolean {
|
|
30
|
+
return event.source === this.host;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
post(body: GuestBody): void {
|
|
34
|
+
// Targeted at "*" deliberately: the guest does not know the host's
|
|
35
|
+
// origin, and guessing one would mean a message silently going
|
|
36
|
+
// nowhere the first time the app is served from somewhere else.
|
|
37
|
+
// Nothing secret travels in this direction — the host authorises,
|
|
38
|
+
// the guest only asks.
|
|
39
|
+
// `kind` before `nonce`, as the guest always posted them: the fields
|
|
40
|
+
// are the same either way, but a host or a log that compares the
|
|
41
|
+
// serialised message sees the order.
|
|
42
|
+
const { kind, ...rest } = body;
|
|
43
|
+
this.host.postMessage(
|
|
44
|
+
{ igni: BRIDGE_VERSION, kind, nonce: this.nonce, ...rest },
|
|
45
|
+
"*",
|
|
46
|
+
);
|
|
47
|
+
}
|
|
48
|
+
}
|