@vanillabp/bc-module-kit 0.1.0-snapshot.0 → 0.1.0-snapshot.3
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/README.md +2 -2
- package/package.json +2 -2
- package/src/define-element.js +3 -2
- package/src/element-names.js +180 -0
- package/src/index.d.ts +31 -0
- package/src/index.js +1 -0
package/README.md
CHANGED
|
@@ -2,8 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
The module's side of the contract between a
|
|
4
4
|
[VanillaBP Business Cockpit](https://github.com/vanillabp/business-cockpit) and a workflow module:
|
|
5
|
-
`bc-manifest.json`, the build check `bc-check-entries`, the event protocol, `defineBcElement
|
|
6
|
-
names of the entries. Plain JavaScript, no dependencies.
|
|
5
|
+
`bc-manifest.json`, the build check `bc-check-entries`, the event protocol, `defineBcElement`, the
|
|
6
|
+
names of the entries and the names of the web components (`elementPrefix`, `createElementNames`). Plain JavaScript, no dependencies.
|
|
7
7
|
|
|
8
8
|
How to use it is in the
|
|
9
9
|
[README of the repository](https://github.com/vanillabp/business-cockpit-module-kit#readme).
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@vanillabp/bc-module-kit",
|
|
3
|
-
"version": "0.1.0-snapshot.
|
|
4
|
-
"description": "The module's side of the contract between a VanillaBP Business Cockpit and a workflow module: bc-manifest.json, bc-check-entries, the event protocol and the names of the
|
|
3
|
+
"version": "0.1.0-snapshot.3",
|
|
4
|
+
"description": "The module's side of the contract between a VanillaBP Business Cockpit and a workflow module: bc-manifest.json, bc-check-entries, the event protocol, the names of the entries and the names of the web components.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"author": "Phactum Softwareentwicklung GmbH (https://www.phactum.at/)",
|
|
7
7
|
"homepage": "https://www.vanillabp.io",
|
package/src/define-element.js
CHANGED
|
@@ -17,7 +17,8 @@ export const HOST_PROPERTIES = Object.freeze(['userTask', 'workflow', 'area', 'l
|
|
|
17
17
|
* `unmount`, stops every subscription the part made and rejects every open request with
|
|
18
18
|
* `DISCONNECTED`.
|
|
19
19
|
*
|
|
20
|
-
* @param {string} name the name of the web component;
|
|
20
|
+
* @param {string} name the name of the web component; build it with `createElementNames`, so it starts
|
|
21
|
+
* with the prefix of the module and holds the build id
|
|
21
22
|
* @param {import('./index.js').BcElementFunctions} functions
|
|
22
23
|
* @param {{ properties?: string[] }} [options] further properties an extension point of this cockpit sets
|
|
23
24
|
* @returns {CustomElementConstructor}
|
|
@@ -27,7 +28,7 @@ export function defineBcElement(name, { mount, update, unmount }, options = {})
|
|
|
27
28
|
throw new Error('defineBcElement needs a browser: customElements does not exist here');
|
|
28
29
|
}
|
|
29
30
|
if (customElements.get(name)) {
|
|
30
|
-
throw new Error(`The web component "${name}" is defined already.
|
|
31
|
+
throw new Error(`The web component "${name}" is defined already. Build its name with createElementNames, so it holds the prefix of the module and the build id. Two BPMN ids which differ only in case or in characters like _ or . give the same name, so give one of them another id.`);
|
|
31
32
|
}
|
|
32
33
|
const properties = [...HOST_PROPERTIES, ...(options.properties ?? [])];
|
|
33
34
|
|
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The names of a module's web components. All modules define their web components in the one
|
|
3
|
+
* `customElements` registry of the page, so every name has three parts:
|
|
4
|
+
*
|
|
5
|
+
* taxi-ride-mvaro4w0-taxi-ride--assess-risk--form
|
|
6
|
+
* prefix build short name
|
|
7
|
+
*
|
|
8
|
+
* The prefix comes from the module id and keeps the modules apart. The build id is new for every
|
|
9
|
+
* build and keeps the builds of one module apart: the browser can define a name only once per
|
|
10
|
+
* page, so a new build needs new names to load without a reload of the page. The short name holds
|
|
11
|
+
* the BPMN ids of the workflow or the user task, so it is unique within the module.
|
|
12
|
+
*
|
|
13
|
+
* @module @vanillabp/bc-module-kit/element-names
|
|
14
|
+
*/
|
|
15
|
+
|
|
16
|
+
/** Names the HTML standard does not allow for a custom element, although they have a hyphen. */
|
|
17
|
+
const RESERVED_NAMES = Object.freeze([
|
|
18
|
+
'annotation-xml',
|
|
19
|
+
'color-profile',
|
|
20
|
+
'font-face',
|
|
21
|
+
'font-face-src',
|
|
22
|
+
'font-face-uri',
|
|
23
|
+
'font-face-format',
|
|
24
|
+
'font-face-name',
|
|
25
|
+
'missing-glyph',
|
|
26
|
+
]);
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Turns a module id into the prefix of its web components. A module id can be any string, but a
|
|
30
|
+
* custom element name has to start with a lower case letter and must not have upper case letters.
|
|
31
|
+
* The cockpit uses the same function to check the names a module draws, so the two always agree.
|
|
32
|
+
*
|
|
33
|
+
* 1. A hyphen goes between a lower case letter or a digit and an upper case letter after it.
|
|
34
|
+
* 2. Every letter becomes lower case.
|
|
35
|
+
* 3. Each run of characters other than `a` to `z`, `0` to `9` and `-` becomes one hyphen, and
|
|
36
|
+
* hyphens at the start and at the end are removed.
|
|
37
|
+
* 4. If the result is empty or does not start with a letter, `wm-` goes in front of it.
|
|
38
|
+
*
|
|
39
|
+
* `taxi-ride` and `TaxiRide` give `taxi-ride`, `loan_approval.2` gives `loan-approval-2` and
|
|
40
|
+
* `4711` gives `wm-4711`.
|
|
41
|
+
*
|
|
42
|
+
* @param {string} workflowModuleId the id the module registers with at the cockpit
|
|
43
|
+
* @returns {string}
|
|
44
|
+
*/
|
|
45
|
+
export function elementPrefix(workflowModuleId) {
|
|
46
|
+
if (typeof workflowModuleId !== 'string') {
|
|
47
|
+
throw new TypeError(`The module id must be a string, but it is ${describe(workflowModuleId)}`);
|
|
48
|
+
}
|
|
49
|
+
const prefix = workflowModuleId
|
|
50
|
+
.replace(/([a-z0-9])([A-Z])/g, '$1-$2')
|
|
51
|
+
.toLowerCase()
|
|
52
|
+
.replace(/[^a-z0-9-]+/g, '-')
|
|
53
|
+
.replace(/^-+|-+$/g, '');
|
|
54
|
+
return /^[a-z]/.test(prefix) ? prefix : `wm-${prefix}`;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/** One id or part in a short name: words of lower case letters and digits, one hyphen between two words. */
|
|
58
|
+
const SEGMENT = /^[a-z0-9]+(-[a-z0-9]+)*$/;
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* Turns a BPMN id, like the id of a process or the task definition of a user task, into one
|
|
62
|
+
* segment of a short name. The rules are those of {@link elementPrefix}, with two differences:
|
|
63
|
+
* a run of hyphens becomes one hyphen as well, and there is no `wm-` in front, because the segment
|
|
64
|
+
* never starts the name. So the segment never has `--` and never starts or ends with a hyphen.
|
|
65
|
+
*
|
|
66
|
+
* `TaxiRide` gives `taxi-ride`, `assessRisk` and `assess_risk` give `assess-risk`.
|
|
67
|
+
*
|
|
68
|
+
* @param {unknown} bpmnId
|
|
69
|
+
* @param {string} what what the id is, for the message of the error
|
|
70
|
+
* @returns {string}
|
|
71
|
+
*/
|
|
72
|
+
function bpmnSegment(bpmnId, what) {
|
|
73
|
+
if (typeof bpmnId !== 'string') {
|
|
74
|
+
throw new TypeError(`The ${what} must be a string, but it is ${describe(bpmnId)}`);
|
|
75
|
+
}
|
|
76
|
+
const segment = bpmnId
|
|
77
|
+
.replace(/([a-z0-9])([A-Z])/g, '$1-$2')
|
|
78
|
+
.toLowerCase()
|
|
79
|
+
.replace(/[^a-z0-9]+/g, '-')
|
|
80
|
+
.replace(/^-+|-+$/g, '');
|
|
81
|
+
if (segment === '') {
|
|
82
|
+
throw new TypeError(
|
|
83
|
+
`The ${what} ${describe(bpmnId)} has no letter and no digit, so it cannot be part of the name of a web component`,
|
|
84
|
+
);
|
|
85
|
+
}
|
|
86
|
+
return segment;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* @param {unknown} value
|
|
91
|
+
* @param {string} what what the value is, for the message of the error
|
|
92
|
+
* @returns {string}
|
|
93
|
+
*/
|
|
94
|
+
function checkedSegment(value, what) {
|
|
95
|
+
if (typeof value !== 'string' || !SEGMENT.test(value)) {
|
|
96
|
+
throw new TypeError(
|
|
97
|
+
`The ${what} must be lower case letters and digits, with one hyphen between two words and no hyphen at the start or the end, but it is ${describe(value)}`,
|
|
98
|
+
);
|
|
99
|
+
}
|
|
100
|
+
return value;
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* @typedef {object} ElementNames
|
|
105
|
+
* @property {(bpmnProcessId: string, part: string) => string} workflow
|
|
106
|
+
* the name of a part which shows a workflow: `<prefix>-<build id>-<process>--<part>`
|
|
107
|
+
* @property {(bpmnProcessId: string, taskDefinition: string, part: string) => string} userTask
|
|
108
|
+
* the name of a part which shows a user task: `<prefix>-<build id>-<process>--<task>--<part>`
|
|
109
|
+
* @property {(shortName: string) => string} custom
|
|
110
|
+
* the name of anything else: `<prefix>-<build id>-<short name>`
|
|
111
|
+
*/
|
|
112
|
+
|
|
113
|
+
/**
|
|
114
|
+
* Returns the functions which build the names of a module's web components. Every name starts
|
|
115
|
+
* with `<prefix>-<build id>-`. The prefix comes from {@link elementPrefix}. The short name after it
|
|
116
|
+
* is made of segments, and `--` goes between two segments:
|
|
117
|
+
*
|
|
118
|
+
* - `workflow(bpmnProcessId, part)` gives `<process>--<part>`,
|
|
119
|
+
* - `userTask(bpmnProcessId, taskDefinition, part)` gives `<process>--<task>--<part>`,
|
|
120
|
+
* - `custom(shortName)` gives the short name as it is, for anything else.
|
|
121
|
+
*
|
|
122
|
+
* A segment is lower case letters and digits, with one hyphen between two words. It never has `--`
|
|
123
|
+
* and never starts or ends with a hyphen. The BPMN ids become segments by the rules of
|
|
124
|
+
* `elementPrefix`, see above. A part and a custom short name must be a segment already. So a name
|
|
125
|
+
* of a workflow has one `--` in its short name, a name of a user task two and a custom name none,
|
|
126
|
+
* and splitting the short name at `--` gives back the segments. That is why two different
|
|
127
|
+
* workflows, user tasks or parts never get the same name.
|
|
128
|
+
*
|
|
129
|
+
* Two BPMN ids which differ only in case or in the characters which become a hyphen, like
|
|
130
|
+
* `assess_risk` and `assessRisk`, give the same segment and so the same name. `defineBcElement`
|
|
131
|
+
* then says that the name is defined already.
|
|
132
|
+
*
|
|
133
|
+
* A module calls it once, in a small file of its own which its data entries and its visual entries
|
|
134
|
+
* import. The build script writes the module id and the build id before it starts the bundler:
|
|
135
|
+
*
|
|
136
|
+
* import { createElementNames } from "@vanillabp/bc-module-kit";
|
|
137
|
+
* import { WORKFLOW_MODULE_ID, BUILD_ID } from "./bc-build.js";
|
|
138
|
+
*
|
|
139
|
+
* export const names = createElementNames(WORKFLOW_MODULE_ID, BUILD_ID);
|
|
140
|
+
* // names.userTask('TaxiRide', 'assessRisk', 'form') === 'taxi-ride-mvaro4w0-taxi-ride--assess-risk--form'
|
|
141
|
+
* // names.workflow('TaxiRide', 'page') === 'taxi-ride-mvaro4w0-taxi-ride--page'
|
|
142
|
+
* // names.custom('price-chart') === 'taxi-ride-mvaro4w0-price-chart'
|
|
143
|
+
*
|
|
144
|
+
* @param {string} workflowModuleId the id the module registers with at the cockpit
|
|
145
|
+
* @param {string} buildId new for every build, only lower case letters and digits, for example
|
|
146
|
+
* `Date.now().toString(36)`
|
|
147
|
+
* @returns {Readonly<ElementNames>}
|
|
148
|
+
*/
|
|
149
|
+
export function createElementNames(workflowModuleId, buildId) {
|
|
150
|
+
const prefix = elementPrefix(workflowModuleId);
|
|
151
|
+
if (typeof buildId !== 'string' || !/^[a-z0-9]+$/.test(buildId)) {
|
|
152
|
+
throw new TypeError(
|
|
153
|
+
`The build id must be a string of lower case letters and digits, for example Date.now().toString(36), but it is ${describe(buildId)}`,
|
|
154
|
+
);
|
|
155
|
+
}
|
|
156
|
+
/** @param {string[]} segments */
|
|
157
|
+
const name = (...segments) => {
|
|
158
|
+
const whole = `${prefix}-${buildId}-${segments.join('--')}`;
|
|
159
|
+
if (RESERVED_NAMES.includes(whole)) {
|
|
160
|
+
throw new TypeError(`"${whole}" is a reserved name in HTML and cannot be the name of a web component`);
|
|
161
|
+
}
|
|
162
|
+
return whole;
|
|
163
|
+
};
|
|
164
|
+
return Object.freeze({
|
|
165
|
+
workflow: (bpmnProcessId, part) =>
|
|
166
|
+
name(bpmnSegment(bpmnProcessId, 'BPMN process id'), checkedSegment(part, 'part')),
|
|
167
|
+
userTask: (bpmnProcessId, taskDefinition, part) =>
|
|
168
|
+
name(
|
|
169
|
+
bpmnSegment(bpmnProcessId, 'BPMN process id'),
|
|
170
|
+
bpmnSegment(taskDefinition, 'task definition'),
|
|
171
|
+
checkedSegment(part, 'part'),
|
|
172
|
+
),
|
|
173
|
+
custom: (shortName) => name(checkedSegment(shortName, 'short name of a web component')),
|
|
174
|
+
});
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
/** @param {unknown} value */
|
|
178
|
+
function describe(value) {
|
|
179
|
+
return typeof value === 'string' ? `"${value}"` : String(value);
|
|
180
|
+
}
|
package/src/index.d.ts
CHANGED
|
@@ -221,3 +221,34 @@ export interface BcElementFunctions {
|
|
|
221
221
|
|
|
222
222
|
export declare const HOST_PROPERTIES: readonly string[];
|
|
223
223
|
export declare function defineBcElement(name: string, functions: BcElementFunctions, options?: { properties?: string[] }): CustomElementConstructor;
|
|
224
|
+
|
|
225
|
+
// --- names of the web components -------------------------------------------------------------
|
|
226
|
+
|
|
227
|
+
/** Turns a module id into the prefix of its web components: `TaxiRide` gives `taxi-ride`, `4711` gives `wm-4711`. */
|
|
228
|
+
export declare function elementPrefix(workflowModuleId: string): string;
|
|
229
|
+
/**
|
|
230
|
+
* The functions which build the names of a module's web components. Every name is
|
|
231
|
+
* `<prefix>-<build id>-<short name>`, and `--` goes between two segments of the short name.
|
|
232
|
+
* A segment is lower case letters and digits with one hyphen between two words.
|
|
233
|
+
*/
|
|
234
|
+
export interface ElementNames {
|
|
235
|
+
/**
|
|
236
|
+
* The name of a part which shows a workflow: `<prefix>-<build id>-<process>--<part>`.
|
|
237
|
+
* `workflow('TaxiRide', 'page')` gives `taxi-ride-mvaro4w0-taxi-ride--page`.
|
|
238
|
+
*/
|
|
239
|
+
workflow(bpmnProcessId: string, part: string): string;
|
|
240
|
+
/**
|
|
241
|
+
* The name of a part which shows a user task: `<prefix>-<build id>-<process>--<task>--<part>`.
|
|
242
|
+
* `userTask('TaxiRide', 'assessRisk', 'form')` gives `taxi-ride-mvaro4w0-taxi-ride--assess-risk--form`.
|
|
243
|
+
*/
|
|
244
|
+
userTask(bpmnProcessId: string, taskDefinition: string, part: string): string;
|
|
245
|
+
/** The name of anything else: `<prefix>-<build id>-<short name>`. The short name has no `--`. */
|
|
246
|
+
custom(shortName: string): string;
|
|
247
|
+
}
|
|
248
|
+
/**
|
|
249
|
+
* Returns the functions which build the names of a module's web components. The build id has only
|
|
250
|
+
* lower case letters and digits. BPMN ids become segments by the rules of `elementPrefix`; a run of
|
|
251
|
+
* hyphens becomes one hyphen. Two ids which differ only in those characters, like `assess_risk` and
|
|
252
|
+
* `assessRisk`, give the same name.
|
|
253
|
+
*/
|
|
254
|
+
export declare function createElementNames(workflowModuleId: string, buildId: string): Readonly<ElementNames>;
|
package/src/index.js
CHANGED