@vanillabp/bc-module-kit 0.1.0-snapshot.2 → 0.1.0-snapshot.4

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).
@@ -9,7 +9,9 @@ const usage = `Usage: bc-check-entries <path to bc-manifest.json> [options]
9
9
 
10
10
  Fails when an entry of the manifest has no file, or when a data entry, with
11
11
  every file it imports, is larger than the limit, imports a bare name or
12
- contains framework code.
12
+ contains framework code. The data entries are the four the kit knows
13
+ (UserTaskList, WorkflowList, UserTaskForm, WorkflowPage) and those named by
14
+ --data-entry.
13
15
 
14
16
  Options:
15
17
  --limit <size> the limit of a data entry, like 32kb (default ${DEFAULT_LIMIT_BYTES / 1024}kb)
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.4",
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/check.js CHANGED
@@ -6,7 +6,7 @@
6
6
 
7
7
  import { existsSync, readFileSync, statSync } from 'node:fs';
8
8
  import { dirname, resolve, sep } from 'node:path';
9
- import { DATA_ENTRIES } from './entries.js';
9
+ import { EXPORT_NAMES } from './entries.js';
10
10
  import { readManifest } from './manifest.js';
11
11
 
12
12
  /** The limit of a data entry with every file it imports: 32 KB before compression. */
@@ -125,13 +125,16 @@ function frameworkOfInput(input) {
125
125
  * file it imports, must stay below the limit, must import nothing by a bare name, and must hold no
126
126
  * framework code.
127
127
  *
128
+ * The data entries are the keys of `EXPORT_NAMES`, together with `options.dataEntries`: the
129
+ * entries of the module's own, for example `Header`. A visual entry is only checked for its file.
130
+ *
128
131
  * @param {string} manifestPath
129
132
  * @param {{ limit?: number | string, dataEntries?: string[], metafile?: string }} [options]
130
133
  * @returns {{ problems: string[], dataEntries: Array<{ entry: string, files: string[], bytes: number }> }}
131
134
  */
132
135
  export function checkEntries(manifestPath, options = {}) {
133
136
  const limit = parseLimit(options.limit ?? DEFAULT_LIMIT_BYTES);
134
- const dataEntryNames = new Set([...DATA_ENTRIES, ...(options.dataEntries ?? [])]);
137
+ const dataEntryNames = new Set([...Object.keys(EXPORT_NAMES), ...(options.dataEntries ?? [])]);
135
138
  const inputsOf = options.metafile ? readMetafile(resolve(options.metafile)) : () => undefined;
136
139
  const base = dirname(resolve(manifestPath));
137
140
  const problems = [];
@@ -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/entries.js CHANGED
@@ -20,18 +20,11 @@ export const USER_TASK_FORM = 'UserTaskForm';
20
20
  export const WORKFLOW_PAGE = 'WorkflowPage';
21
21
 
22
22
  /**
23
- * The entries which carry no framework. `bc-check-entries` checks their size and their content.
24
- * A module with entries of its own, for example `Header`, names them with the option
25
- * `--data-entry` of `bc-check-entries`.
23
+ * For each data entry, the name of the function it exports. This map is the one source of the
24
+ * data entries: an entry which exports a function is a data entry, and a visual entry exports no
25
+ * function. A cockpit with entries of its own, for example `Header`, extends this map in its
26
+ * types library: `{ ...EXPORT_NAMES, Header: 'header' }`.
26
27
  */
27
- export const DATA_ENTRIES = Object.freeze([
28
- USER_TASK_LIST,
29
- WORKFLOW_LIST,
30
- USER_TASK_FORM,
31
- WORKFLOW_PAGE,
32
- ]);
33
-
34
- /** For each data entry, the name of the function it exports. */
35
28
  export const EXPORT_NAMES = Object.freeze({
36
29
  [USER_TASK_LIST]: 'userTaskListColumns',
37
30
  [WORKFLOW_LIST]: 'workflowListColumns',
@@ -39,6 +32,14 @@ export const EXPORT_NAMES = Object.freeze({
39
32
  [WORKFLOW_PAGE]: 'workflowPage',
40
33
  });
41
34
 
35
+ /**
36
+ * The entries which carry no framework: the keys of `EXPORT_NAMES`, in the same order. It is
37
+ * derived from that map, so never list a data entry here. `bc-check-entries` checks their size
38
+ * and their content. A module with entries of its own, for example `Header`, names them with
39
+ * the option `--data-entry` of `bc-check-entries`.
40
+ */
41
+ export const DATA_ENTRIES = Object.freeze(Object.keys(EXPORT_NAMES));
42
+
42
43
  /**
43
44
  * The area of the one web component which shows the whole page. Every cockpit knows it. A
44
45
  * cockpit without areas of its own shows this web component.
package/src/index.d.ts CHANGED
@@ -11,13 +11,19 @@ export declare const USER_TASK_LIST: 'UserTaskList';
11
11
  export declare const WORKFLOW_LIST: 'WorkflowList';
12
12
  export declare const USER_TASK_FORM: 'UserTaskForm';
13
13
  export declare const WORKFLOW_PAGE: 'WorkflowPage';
14
- export declare const DATA_ENTRIES: readonly ['UserTaskList', 'WorkflowList', 'UserTaskForm', 'WorkflowPage'];
14
+ /**
15
+ * For each data entry, the name of the function it exports. The one source of the data entries.
16
+ * A cockpit with entries of its own extends it in its types library, for example
17
+ * `{ ...EXPORT_NAMES, Header: 'header' }`.
18
+ */
15
19
  export declare const EXPORT_NAMES: Readonly<{
16
20
  UserTaskList: 'userTaskListColumns';
17
21
  WorkflowList: 'workflowListColumns';
18
22
  UserTaskForm: 'userTaskForm';
19
23
  WorkflowPage: 'workflowPage';
20
24
  }>;
25
+ /** The keys of `EXPORT_NAMES`, in the same order. Derived from that map. */
26
+ export declare const DATA_ENTRIES: ReadonlyArray<keyof typeof EXPORT_NAMES>;
21
27
  export declare const AREA_ALL: 'all';
22
28
 
23
29
  /** A text per language. The keys are language codes like 'en' or 'de'. */
@@ -221,3 +227,34 @@ export interface BcElementFunctions {
221
227
 
222
228
  export declare const HOST_PROPERTIES: readonly string[];
223
229
  export declare function defineBcElement(name: string, functions: BcElementFunctions, options?: { properties?: string[] }): CustomElementConstructor;
230
+
231
+ // --- names of the web components -------------------------------------------------------------
232
+
233
+ /** Turns a module id into the prefix of its web components: `TaxiRide` gives `taxi-ride`, `4711` gives `wm-4711`. */
234
+ export declare function elementPrefix(workflowModuleId: string): string;
235
+ /**
236
+ * The functions which build the names of a module's web components. Every name is
237
+ * `<prefix>-<build id>-<short name>`, and `--` goes between two segments of the short name.
238
+ * A segment is lower case letters and digits with one hyphen between two words.
239
+ */
240
+ export interface ElementNames {
241
+ /**
242
+ * The name of a part which shows a workflow: `<prefix>-<build id>-<process>--<part>`.
243
+ * `workflow('TaxiRide', 'page')` gives `taxi-ride-mvaro4w0-taxi-ride--page`.
244
+ */
245
+ workflow(bpmnProcessId: string, part: string): string;
246
+ /**
247
+ * The name of a part which shows a user task: `<prefix>-<build id>-<process>--<task>--<part>`.
248
+ * `userTask('TaxiRide', 'assessRisk', 'form')` gives `taxi-ride-mvaro4w0-taxi-ride--assess-risk--form`.
249
+ */
250
+ userTask(bpmnProcessId: string, taskDefinition: string, part: string): string;
251
+ /** The name of anything else: `<prefix>-<build id>-<short name>`. The short name has no `--`. */
252
+ custom(shortName: string): string;
253
+ }
254
+ /**
255
+ * Returns the functions which build the names of a module's web components. The build id has only
256
+ * lower case letters and digits. BPMN ids become segments by the rules of `elementPrefix`; a run of
257
+ * hyphens becomes one hyphen. Two ids which differ only in those characters, like `assess_risk` and
258
+ * `assessRisk`, give the same name.
259
+ */
260
+ 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';