@vanillabp/bc-module-kit 0.1.0-snapshot.2 → 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 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` and the
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.2",
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 entries.",
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",
@@ -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; by convention it starts with the module id
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. Its name must start with the module id, so it is unique.`);
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
@@ -8,3 +8,4 @@ export * from './entries.js';
8
8
  export * from './manifest.js';
9
9
  export * from './protocol.js';
10
10
  export * from './define-element.js';
11
+ export * from './element-names.js';