@ignite-ember/extension-bridge 0.2.0 → 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/src/hostModel.ts CHANGED
@@ -52,7 +52,7 @@ export interface HostLink {
52
52
  * Send one request to the host.
53
53
  *
54
54
  * @param op — what to do: read a property, write one, or call a method.
55
- * @param path — where in the model, as `host.chat.processing`.
55
+ * @param path — where in the model, as `chat.processing`: the path without the leading `host.`.
56
56
  * @param options — the window or session it is about, the arguments
57
57
  * of a call, and the value of a write.
58
58
  * @returns — whatever the host answered with.
@@ -89,7 +89,7 @@ export class HostObject {
89
89
  constructor(
90
90
  /** How requests reach the host. */
91
91
  protected readonly link: HostLink,
92
- /** Where in the model this object sits: `host.chat`. */
92
+ /** Where in the model this object sits: `chat`, without the leading `host.`. */
93
93
  readonly path: string,
94
94
  /** The window it belongs to, when it belongs to one. */
95
95
  protected readonly window: string | null = null,
@@ -158,7 +158,7 @@ export class Property<T> {
158
158
  readonly writable: boolean,
159
159
  ) {}
160
160
 
161
- /** Where in the model this value sits: `host.chat.processing`. */
161
+ /** Where in the model this value sits: `chat.processing`, without the leading `host.`. */
162
162
  get path(): string {
163
163
  return this.owner.memberPath(this.name);
164
164
  }
@@ -175,7 +175,11 @@ export class Property<T> {
175
175
  })) as T;
176
176
  }
177
177
 
178
- /** Write it, as the person's UI would. Refused where theirs would be. */
178
+ /**
179
+ * Write it, as the person's UI would. Refused where theirs would be.
180
+ *
181
+ * @param value — what the host should hold for it from now on.
182
+ */
179
183
  async set(value: T): Promise<void> {
180
184
  if (!this.writable) {
181
185
  throw new HostError("read_only", `host.${this.path} cannot be set`);
package/src/protocol.ts CHANGED
@@ -347,6 +347,8 @@ export type GuestMessage =
347
347
  * the answer has to be "no" for everything that is not exactly right.
348
348
  * A message that fails here is dropped without a reply: a guest that
349
349
  * can tell malformed from unauthorised has learned something.
350
+ *
351
+ * @param data — the message as it arrived, in whatever shape it is.
350
352
  */
351
353
  export function isGuestMessage(data: unknown): data is GuestMessage {
352
354
  if (typeof data !== "object" || data === null) return false;
@@ -407,7 +409,11 @@ export function isGuestMessage(data: unknown): data is GuestMessage {
407
409
  }
408
410
  }
409
411
 
410
- /** Is this a message from the host, shaped the way the guest requires? */
412
+ /**
413
+ * Is this a message from the host, shaped the way the guest requires?
414
+ *
415
+ * @param data — the message as it arrived, in whatever shape it is.
416
+ */
411
417
  export function isHostMessage(data: unknown): data is HostMessage {
412
418
  if (typeof data !== "object" || data === null) return false;
413
419
  const m = data as Record<string, unknown>;
@@ -462,6 +468,10 @@ export function isHostMessage(data: unknown): data is HostMessage {
462
468
  * `*` anywhere but the end: a permission list is read by whoever
463
469
  * approves an install, and a pattern language it cannot be read in is
464
470
  * a permission nobody actually granted.
471
+ *
472
+ * @param method — the method the extension wants to call.
473
+ * @param allow — the methods it was granted, as exact names or as
474
+ * `*`-suffixed prefixes.
465
475
  */
466
476
  export function methodAllowed(
467
477
  method: string,
package/src/service.ts CHANGED
@@ -27,6 +27,13 @@
27
27
 
28
28
  /** Why `bridge.service` could not do what was asked. */
29
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
+ */
30
37
  constructor(
31
38
  /**
32
39
  * `no_service` (none a page may reach), `refused` (igni gave no
@@ -77,12 +84,20 @@ export interface ServiceBridge {
77
84
  /**
78
85
  * `fetch` against the service, with the token. `path` is relative
79
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.
80
90
  */
81
91
  fetch(path: string, init?: RequestInit): Promise<Response>;
82
92
  /**
83
93
  * A WebSocket to `path` on the service (`https` → `wss`), resolved
84
94
  * once it is open and has said who it is (see
85
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.
86
101
  */
87
102
  websocket(path: string, options?: ServiceSocketOptions): Promise<WebSocket>;
88
103
  }
@@ -90,7 +105,11 @@ export interface ServiceBridge {
90
105
  /** Fetch a new token when the held one has less than this left. */
91
106
  export const RENEW_BEFORE_MS = 60_000;
92
107
 
93
- /** The default first frame: `{"type": "auth", "token": …}`. */
108
+ /**
109
+ * The default first frame: `{"type": "auth", "token": …}`.
110
+ *
111
+ * @param token — the bearer token the frame carries.
112
+ */
94
113
  export function authMessage(token: string): string {
95
114
  return JSON.stringify({ type: "auth", token });
96
115
  }
@@ -220,7 +239,13 @@ export class ServiceLink implements ServiceBridge {
220
239
  return this.fetching;
221
240
  }
222
241
 
223
- /** `path` on the service, or a refusal if it is anywhere else. */
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
+ */
224
249
  private resolve(path: string, socket: boolean): string {
225
250
  if (this.url === null) {
226
251
  throw new ServiceError(
package/src/tokens.ts CHANGED
@@ -73,9 +73,8 @@ export const PUBLISHED_TOKENS = {
73
73
  /**
74
74
  * The type scale. Nine steps, by role rather than by ratio.
75
75
  *
76
- * It replaced twenty-two hardcoded sizes that included every
77
- * half-step from 9px to 15px — 11.5px, 12px and 12.5px between
78
- * them accounted for 272 declarations, which is one size written
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
79
78
  * three ways. Build against the role, not the pixel.
80
79
  */
81
80
  type: [
@@ -134,6 +133,9 @@ export type ThemeTokens = Record<string, string>;
134
133
  * query or overridden by a `data-theme` attribute resolves here to
135
134
  * what the user is actually looking at, which is the only answer
136
135
  * worth sending.
136
+ *
137
+ * @param root — the element whose computed styles are read; the
138
+ * document's own root by default.
137
139
  */
138
140
  export function readThemeTokens(
139
141
  root: Element = document.documentElement,
@@ -155,6 +157,10 @@ export function readThemeTokens(
155
157
  *
156
158
  * Called by the guest bridge. Separate from reading them so the two
157
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.
158
164
  */
159
165
  export function applyThemeTokens(tokens: ThemeTokens, root: HTMLElement): void {
160
166
  for (const [name, value] of Object.entries(tokens)) {