@vanillabp/bc-module-kit 0.0.0-stage → 0.1.0-snapshot.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 +202 -0
- package/NOTICE +17 -0
- package/README.md +8 -2
- package/bin/bc-check-entries.js +67 -0
- package/package.json +47 -4
- package/schema/bc-manifest.schema.json +42 -0
- package/src/check.d.ts +10 -0
- package/src/check.js +194 -0
- package/src/define-element.js +128 -0
- package/src/entries.js +46 -0
- package/src/index.d.ts +223 -0
- package/src/index.js +10 -0
- package/src/manifest.js +135 -0
- package/src/protocol.js +288 -0
package/src/protocol.js
ADDED
|
@@ -0,0 +1,288 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The module's side of the event protocol between a part of a workflow module and the cockpit.
|
|
3
|
+
* A part calls a function, the helper dispatches a `bc-request` on the part's web component, and
|
|
4
|
+
* the cockpit answers with a `bc-response` on the same element.
|
|
5
|
+
*
|
|
6
|
+
* @module @vanillabp/bc-module-kit/protocol
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
/** The event a part dispatches on its own web component to ask the cockpit for something. */
|
|
10
|
+
export const REQUEST_EVENT = 'bc-request';
|
|
11
|
+
|
|
12
|
+
/** The event the cockpit dispatches on the same web component to answer a request. */
|
|
13
|
+
export const RESPONSE_EVENT = 'bc-response';
|
|
14
|
+
|
|
15
|
+
/** The event the cockpit dispatches on the web component of an area to deliver a message. */
|
|
16
|
+
export const MESSAGE_EVENT = 'bc-message';
|
|
17
|
+
|
|
18
|
+
/** The actions every cockpit knows. */
|
|
19
|
+
export const ACTIONS = Object.freeze({
|
|
20
|
+
USER_TASK_OPEN: 'userTask.open',
|
|
21
|
+
USER_TASK_NAVIGATE_TO_WORKFLOW: 'userTask.navigateToWorkflow',
|
|
22
|
+
USER_TASK_CLAIM: 'userTask.claim',
|
|
23
|
+
USER_TASK_UNCLAIM: 'userTask.unclaim',
|
|
24
|
+
USER_TASK_ASSIGN: 'userTask.assign',
|
|
25
|
+
USER_TASK_UNASSIGN: 'userTask.unassign',
|
|
26
|
+
WORKFLOW_NAVIGATE_TO_WORKFLOW: 'workflow.navigateToWorkflow',
|
|
27
|
+
WORKFLOW_GET_USER_TASKS: 'workflow.getUserTasks',
|
|
28
|
+
PAGE_SEND_TO: 'page.sendTo',
|
|
29
|
+
PAGE_SUBSCRIBE: 'page.subscribe',
|
|
30
|
+
PAGE_UNSUBSCRIBE: 'page.unsubscribe',
|
|
31
|
+
COCKPIT_SHOW_NOTIFICATION: 'cockpit.showNotification',
|
|
32
|
+
COCKPIT_OPEN_DIALOG: 'cockpit.openDialog',
|
|
33
|
+
COCKPIT_CLOSE_DIALOG: 'cockpit.closeDialog',
|
|
34
|
+
});
|
|
35
|
+
|
|
36
|
+
/** The codes of a failed request. The cockpit sets the first four, the helper sets the last two. */
|
|
37
|
+
export const ERROR_CODES = Object.freeze({
|
|
38
|
+
UNKNOWN_ACTION: 'UNKNOWN_ACTION',
|
|
39
|
+
REFUSED: 'REFUSED',
|
|
40
|
+
FAILED: 'FAILED',
|
|
41
|
+
NO_TARGET: 'NO_TARGET',
|
|
42
|
+
TIMEOUT: 'TIMEOUT',
|
|
43
|
+
DISCONNECTED: 'DISCONNECTED',
|
|
44
|
+
});
|
|
45
|
+
|
|
46
|
+
/** How long the helper waits for an answer, in milliseconds. */
|
|
47
|
+
export const DEFAULT_TIMEOUT_MS = 30_000;
|
|
48
|
+
|
|
49
|
+
/** Actions which wait for the user and so have no timeout. */
|
|
50
|
+
export const ACTIONS_WITHOUT_TIMEOUT = Object.freeze([ACTIONS.COCKPIT_OPEN_DIALOG]);
|
|
51
|
+
|
|
52
|
+
/** A request the cockpit did not carry out, or one which got no answer. */
|
|
53
|
+
export class BcRequestError extends Error {
|
|
54
|
+
/**
|
|
55
|
+
* @param {{ code: string, message?: string, status?: number, action: string }} details
|
|
56
|
+
*/
|
|
57
|
+
constructor({ code, message, status, action }) {
|
|
58
|
+
super(message || `The cockpit answered "${action}" with ${code}`);
|
|
59
|
+
this.name = 'BcRequestError';
|
|
60
|
+
this.code = code;
|
|
61
|
+
this.status = status;
|
|
62
|
+
this.action = action;
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/** @type {WeakMap<EventTarget, Map<string, (error: BcRequestError) => void>>} */
|
|
67
|
+
const openRequests = new WeakMap();
|
|
68
|
+
|
|
69
|
+
let counter = 0;
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* A correlation id. `crypto.randomUUID()` exists only in a secure context, so a page served over
|
|
73
|
+
* plain http on another host than localhost gets a counter with a random part instead.
|
|
74
|
+
*/
|
|
75
|
+
function newRequestId() {
|
|
76
|
+
if (typeof globalThis.crypto?.randomUUID === 'function') return globalThis.crypto.randomUUID();
|
|
77
|
+
counter += 1;
|
|
78
|
+
return `${Date.now().toString(36)}-${counter}-${Math.random().toString(36).slice(2)}`;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* Asks the cockpit to run an action and waits for its answer.
|
|
83
|
+
*
|
|
84
|
+
* @param {EventTarget} element the web component of the part
|
|
85
|
+
* @param {string} action for example `userTask.claim`
|
|
86
|
+
* @param {Record<string, unknown>} [args]
|
|
87
|
+
* @param {number} [timeoutMs] 0 waits for ever; by default 30 seconds, and no limit for `cockpit.openDialog`
|
|
88
|
+
* @returns {Promise<unknown>} the `result` of the answer
|
|
89
|
+
*/
|
|
90
|
+
export function requestFromCockpit(element, action, args = {}, timeoutMs) {
|
|
91
|
+
const limit = timeoutMs ?? (ACTIONS_WITHOUT_TIMEOUT.includes(action) ? 0 : DEFAULT_TIMEOUT_MS);
|
|
92
|
+
const requestId = newRequestId();
|
|
93
|
+
return new Promise((resolve, reject) => {
|
|
94
|
+
let timer;
|
|
95
|
+
let pending = openRequests.get(element);
|
|
96
|
+
if (!pending) {
|
|
97
|
+
pending = new Map();
|
|
98
|
+
openRequests.set(element, pending);
|
|
99
|
+
}
|
|
100
|
+
const finish = () => {
|
|
101
|
+
clearTimeout(timer);
|
|
102
|
+
element.removeEventListener(RESPONSE_EVENT, onResponse);
|
|
103
|
+
pending.delete(requestId);
|
|
104
|
+
};
|
|
105
|
+
const onResponse = (/** @type {CustomEvent} */ event) => {
|
|
106
|
+
const detail = event.detail;
|
|
107
|
+
if (!detail || detail.requestId !== requestId) return;
|
|
108
|
+
finish();
|
|
109
|
+
if (detail.ok) {
|
|
110
|
+
resolve(detail.result);
|
|
111
|
+
} else {
|
|
112
|
+
const error = detail.error ?? {};
|
|
113
|
+
reject(new BcRequestError({ code: error.code ?? ERROR_CODES.FAILED, message: error.message, status: error.status, action }));
|
|
114
|
+
}
|
|
115
|
+
};
|
|
116
|
+
pending.set(requestId, (error) => {
|
|
117
|
+
finish();
|
|
118
|
+
reject(error);
|
|
119
|
+
});
|
|
120
|
+
element.addEventListener(RESPONSE_EVENT, onResponse);
|
|
121
|
+
if (limit > 0) {
|
|
122
|
+
timer = setTimeout(() => {
|
|
123
|
+
finish();
|
|
124
|
+
reject(new BcRequestError({ code: ERROR_CODES.TIMEOUT, message: `No answer to "${action}" within ${limit} ms`, action }));
|
|
125
|
+
}, limit);
|
|
126
|
+
}
|
|
127
|
+
element.dispatchEvent(new CustomEvent(REQUEST_EVENT, {
|
|
128
|
+
bubbles: false,
|
|
129
|
+
composed: false,
|
|
130
|
+
detail: { requestId, action, args },
|
|
131
|
+
}));
|
|
132
|
+
});
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
/**
|
|
136
|
+
* Rejects every open request of an element with `DISCONNECTED`. A web component calls it when it
|
|
137
|
+
* leaves the page, in `disconnectedCallback`. `defineBcElement` does that by itself.
|
|
138
|
+
*
|
|
139
|
+
* @param {EventTarget} element
|
|
140
|
+
*/
|
|
141
|
+
export function rejectOpenRequests(element) {
|
|
142
|
+
const pending = openRequests.get(element);
|
|
143
|
+
if (!pending) return;
|
|
144
|
+
for (const reject of [...pending.values()]) {
|
|
145
|
+
reject(new BcRequestError({ code: ERROR_CODES.DISCONNECTED, message: 'The element left the page before the answer came', action: '' }));
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
/**
|
|
150
|
+
* Sends a message to the web component of another area of the same page.
|
|
151
|
+
*
|
|
152
|
+
* @param {EventTarget} element
|
|
153
|
+
* @param {string} target the area, for example `actions`
|
|
154
|
+
* @param {unknown} message any value that survives `structuredClone`
|
|
155
|
+
* @returns {Promise<void>}
|
|
156
|
+
*/
|
|
157
|
+
export function sendTo(element, target, message) {
|
|
158
|
+
return /** @type {Promise<void>} */ (requestFromCockpit(element, ACTIONS.PAGE_SEND_TO, { target, message }));
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/**
|
|
162
|
+
* Asks the cockpit to deliver the messages for this element's area to `handler`.
|
|
163
|
+
* Messages which arrive before the cockpit has answered are kept and handed over once the
|
|
164
|
+
* subscription id is known, so none gets lost.
|
|
165
|
+
*
|
|
166
|
+
* @param {EventTarget} element
|
|
167
|
+
* @param {(message: unknown, from: string) => void} handler
|
|
168
|
+
* @returns {import('./index.js').BcSubscription}
|
|
169
|
+
*/
|
|
170
|
+
export function receiveMessage(element, handler) {
|
|
171
|
+
/** @type {string | undefined} */
|
|
172
|
+
let subscriptionId;
|
|
173
|
+
let stopped = false;
|
|
174
|
+
/** @type {Array<{ subscriptionId: string, from: string, message: unknown }>} */
|
|
175
|
+
const early = [];
|
|
176
|
+
const onMessage = (/** @type {CustomEvent} */ event) => {
|
|
177
|
+
const detail = event.detail;
|
|
178
|
+
if (!detail || stopped) return;
|
|
179
|
+
if (subscriptionId === undefined) {
|
|
180
|
+
early.push(detail);
|
|
181
|
+
} else if (detail.subscriptionId === subscriptionId) {
|
|
182
|
+
handler(detail.message, detail.from);
|
|
183
|
+
}
|
|
184
|
+
};
|
|
185
|
+
element.addEventListener(MESSAGE_EVENT, onMessage);
|
|
186
|
+
const ready = requestFromCockpit(element, ACTIONS.PAGE_SUBSCRIBE, {}).then((result) => {
|
|
187
|
+
subscriptionId = /** @type {any} */ (result)?.subscriptionId;
|
|
188
|
+
for (const detail of early.splice(0)) {
|
|
189
|
+
if (!stopped && detail.subscriptionId === subscriptionId) handler(detail.message, detail.from);
|
|
190
|
+
}
|
|
191
|
+
});
|
|
192
|
+
ready.catch(() => element.removeEventListener(MESSAGE_EVENT, onMessage));
|
|
193
|
+
return {
|
|
194
|
+
ready,
|
|
195
|
+
unsubscribe: async () => {
|
|
196
|
+
if (stopped) return;
|
|
197
|
+
stopped = true;
|
|
198
|
+
element.removeEventListener(MESSAGE_EVENT, onMessage);
|
|
199
|
+
await ready.catch(() => undefined);
|
|
200
|
+
if (subscriptionId !== undefined) {
|
|
201
|
+
await requestFromCockpit(element, ACTIONS.PAGE_UNSUBSCRIBE, { subscriptionId });
|
|
202
|
+
}
|
|
203
|
+
},
|
|
204
|
+
};
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
/**
|
|
208
|
+
* Shows a toast in the cockpit.
|
|
209
|
+
*
|
|
210
|
+
* @param {EventTarget} element
|
|
211
|
+
* @param {import('./index.js').BcNotification} notification
|
|
212
|
+
* @returns {Promise<void>}
|
|
213
|
+
*/
|
|
214
|
+
export function showNotification(element, { level, text, sticky = false }) {
|
|
215
|
+
return /** @type {Promise<void>} */ (requestFromCockpit(element, ACTIONS.COCKPIT_SHOW_NOTIFICATION, { level, text, sticky }));
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
/**
|
|
219
|
+
* Asks the cockpit to show a web component in a modal dialog. Resolves with what the dialog
|
|
220
|
+
* closed with. It has no timeout, because it waits for the user.
|
|
221
|
+
*
|
|
222
|
+
* @param {EventTarget} element
|
|
223
|
+
* @param {import('./index.js').BcElementRef} dialog
|
|
224
|
+
* @param {unknown} [data] handed to the dialog's web component as the property `data`
|
|
225
|
+
* @returns {Promise<unknown>}
|
|
226
|
+
*/
|
|
227
|
+
export function openDialog(element, { element: name, entry }, data) {
|
|
228
|
+
return requestFromCockpit(element, ACTIONS.COCKPIT_OPEN_DIALOG, { element: name, entry, data });
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
/**
|
|
232
|
+
* Closes the dialog this element is shown in.
|
|
233
|
+
*
|
|
234
|
+
* @param {EventTarget} element the web component of the dialog
|
|
235
|
+
* @param {unknown} [result] what `openDialog` resolves with
|
|
236
|
+
* @returns {Promise<void>}
|
|
237
|
+
*/
|
|
238
|
+
export function closeDialog(element, result) {
|
|
239
|
+
return /** @type {Promise<void>} */ (requestFromCockpit(element, ACTIONS.COCKPIT_CLOSE_DIALOG, { result }));
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
/**
|
|
243
|
+
* Adds the functions of a user task to its plain data from the GUI API.
|
|
244
|
+
*
|
|
245
|
+
* @param {EventTarget} element
|
|
246
|
+
* @param {Record<string, any>} data
|
|
247
|
+
* @returns {import('./index.js').BcUserTask}
|
|
248
|
+
*/
|
|
249
|
+
export function toBcUserTask(element, data) {
|
|
250
|
+
const userTaskId = data.id;
|
|
251
|
+
const request = (action, args = {}) => requestFromCockpit(element, action, { userTaskId, ...args });
|
|
252
|
+
return {
|
|
253
|
+
...data,
|
|
254
|
+
open: () => request(ACTIONS.USER_TASK_OPEN),
|
|
255
|
+
navigateToWorkflow: () => request(ACTIONS.USER_TASK_NAVIGATE_TO_WORKFLOW),
|
|
256
|
+
claim: () => request(ACTIONS.USER_TASK_CLAIM),
|
|
257
|
+
unclaim: () => request(ACTIONS.USER_TASK_UNCLAIM),
|
|
258
|
+
assign: (userId) => request(ACTIONS.USER_TASK_ASSIGN, { userId }),
|
|
259
|
+
unassign: (userId) => request(ACTIONS.USER_TASK_UNASSIGN, { userId }),
|
|
260
|
+
sendTo: (target, message) => sendTo(element, target, message),
|
|
261
|
+
receiveMessage: (handler) => receiveMessage(element, handler),
|
|
262
|
+
};
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
/**
|
|
266
|
+
* Adds the functions of a case to its plain data from the GUI API.
|
|
267
|
+
*
|
|
268
|
+
* @param {EventTarget} element
|
|
269
|
+
* @param {Record<string, any>} data
|
|
270
|
+
* @returns {import('./index.js').BcWorkflow}
|
|
271
|
+
*/
|
|
272
|
+
export function toBcWorkflow(element, data) {
|
|
273
|
+
const workflowId = data.id;
|
|
274
|
+
return {
|
|
275
|
+
...data,
|
|
276
|
+
navigateToWorkflow: () => requestFromCockpit(element, ACTIONS.WORKFLOW_NAVIGATE_TO_WORKFLOW, { workflowId }),
|
|
277
|
+
getUserTasks: async (activeOnly, limitListAccordingToCurrentUsersPermissions) => {
|
|
278
|
+
const userTasks = await requestFromCockpit(element, ACTIONS.WORKFLOW_GET_USER_TASKS, {
|
|
279
|
+
workflowId,
|
|
280
|
+
activeOnly,
|
|
281
|
+
limitListAccordingToCurrentUsersPermissions,
|
|
282
|
+
});
|
|
283
|
+
return (/** @type {any[]} */ (userTasks) ?? []).map((userTask) => toBcUserTask(element, userTask));
|
|
284
|
+
},
|
|
285
|
+
sendTo: (target, message) => sendTo(element, target, message),
|
|
286
|
+
receiveMessage: (handler) => receiveMessage(element, handler),
|
|
287
|
+
};
|
|
288
|
+
}
|