@peter.prib/renderengine 0.2.5 → 0.2.7

package/package.json

@@ -1,68 +1,70 @@
-{
-  "name": "@peter.prib/renderengine",
-  "version": "0.2.5",
-  "description": "ArchiMate modeller, diagram editor and chart library for the browser, with no runtime dependencies.",
-  "type": "module",
-  "main": "src/index.js",
-  "module": "src/index.js",
-  "browser": "dist/renderengine.umd.js",
-  "exports": {
-    ".": "./src/index.js",
-    "./workspace": "./src/workspace/index.js",
-    "./src/*": "./src/*",
-    "./dist/*": "./dist/*",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "src/",
-    "dist/*.umd.js",
-    "examples/archimate.html",
-    "examples/diagram-editor.html",
-    "README.md",
-    "REFERENCE.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "start": "node scripts/open.mjs examples/archimate.html",
-    "archimate": "node scripts/open.mjs examples/archimate.html",
-    "diagram": "node scripts/open.mjs examples/diagram-editor.html",
-    "test": "node --test --test-timeout=10000 ./test/*.js ./test/charting/*.js ./test/charting/charts/*.js ./test/charting/diagrams/*.js ./test/charting/shapes/*.js",
-    "build": "rollup -c",
-    "prepublishOnly": "npm test && npm run build",
-    "screenshots": "node scripts/screenshots/screenshots.mjs"
-  },
-  "keywords": [
-    "archimate",
-    "archi",
-    "diagram",
-    "diagram-editor",
-    "modelling",
-    "charts",
-    "svg",
-    "canvas",
-    "render",
-    "engine",
-    "graphics"
-  ],
-  "author": "Peter Prib <peter.prib@gmail.com>",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://gitlab.com/peter.prib/renderengine.git"
-  },
-  "homepage": "https://gitlab.com/peter.prib/renderengine#readme",
-  "bugs": {
-    "url": "https://gitlab.com/peter.prib/renderengine/-/issues"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "devDependencies": {
-    "@rollup/plugin-commonjs": "^25.0.8",
-    "@rollup/plugin-node-resolve": "^15.3.1",
-    "rollup": "^3.30.0"
-  }
-}
+{
+  "name": "@peter.prib/renderengine",
+  "version": "0.2.7",
+  "description": "ArchiMate modeller, diagram editor and chart library for the browser, with no runtime dependencies.",
+  "type": "module",
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "browser": "dist/renderengine.umd.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./workspace": "./src/workspace/index.js",
+    "./src/*": "./src/*",
+    "./dist/*": "./dist/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src/",
+    "dist/*.umd.js",
+    "examples/archimate.html",
+    "examples/diagram-editor.html",
+    "examples/data-model.html",
+    "README.md",
+    "REFERENCE.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node scripts/open.mjs examples/archimate.html",
+    "archimate": "node scripts/open.mjs examples/archimate.html",
+    "diagram": "node scripts/open.mjs examples/diagram-editor.html",
+    "datamodel": "node scripts/open.mjs examples/data-model.html",
+    "test": "node --test --test-timeout=10000 ./test/*.js ./test/charting/*.js ./test/charting/charts/*.js ./test/charting/diagrams/*.js ./test/charting/shapes/*.js",
+    "build": "rollup -c",
+    "prepublishOnly": "npm test && npm run build",
+    "screenshots": "node scripts/screenshots/screenshots.mjs"
+  },
+  "keywords": [
+    "archimate",
+    "archi",
+    "diagram",
+    "diagram-editor",
+    "modelling",
+    "charts",
+    "svg",
+    "canvas",
+    "render",
+    "engine",
+    "graphics"
+  ],
+  "author": "Peter Prib <peter.prib@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/peter.prib/renderengine.git"
+  },
+  "homepage": "https://gitlab.com/peter.prib/renderengine#readme",
+  "bugs": {
+    "url": "https://gitlab.com/peter.prib/renderengine/-/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^25.0.8",
+    "@rollup/plugin-node-resolve": "^15.3.1",
+    "rollup": "^3.30.0"
+  }
+}

package/src/bian.js

@@ -0,0 +1,182 @@
+/**
+ * BIAN vocabulary — the Banking Industry Architecture Network's service
+ * domain terms, as one registry (as src/archimate.js and src/datamodel.js are)
+ * that pickers, dialogs and service domains read rather than restate.
+ *
+ * Sources: the BIAN Semantic API Practitioner Guide V8.1 (December 2024) for the
+ * functional patterns' descriptions and the action terms in their four groups;
+ * BIAN's v14 model as its service landscape portal publishes it
+ * (bian.org/servicelandscape-14-0-0) for each pattern's generic artifact, its
+ * behaviour qualifier type (the type the artifact aggregates) and the creating
+ * action term it aggregates; BIAN's release 14.0.0 semantic APIs
+ * (github.com/bian-official/public, Apache-2.0) for the names control records
+ * have and, where a pattern aggregates two creating terms (Monitor: evaluate
+ * and initiate), the one its APIs use. Every value is BIAN's; `inferred` is
+ * kept for a value that is not. See BIAN_ALIGNMENT.md.
+ */
+
+/** One way a service domain behaves: what it does to its asset, and the record it keeps of it. */
+export class BianFunctionalPattern {
+    /**
+     * @param {string} name - 'Fulfill'
+     * @param {Object} spec
+     * @param {string} spec.artifact - The generic artifact a control record is ('Facility')
+     * @param {string} spec.description
+     * @param {string} spec.creates - The action term that makes a new control record ('initiate')
+     * @param {string} spec.qualifierType - How the control record is broken down ('Fulfillment')
+     * @param {string[]} [spec.inferred] - Which of creates/qualifierType are inferred, not confirmed
+     * @param {string[]} [spec.formerArtifacts] - Names the artifact had before ('Arrangement' for Fulfill's)
+     */
+    constructor(name, { artifact, description, creates, qualifierType, inferred = [], formerArtifacts = [] }) {
+        this.name = name;
+        this.artifact = artifact;
+        this.formerArtifacts = Object.freeze([...formerArtifacts]);
+        this.description = description;
+        this.creates = creates;
+        this.qualifierType = qualifierType;
+        this.inferred = Object.freeze([...inferred]);
+    }
+
+    /** The control record's name for an asset: 'Current Account' gives 'Current Account Facility'. */
+    controlRecordName(asset) {
+        return [asset, this.artifact].filter(Boolean).join(' ');
+    }
+}
+
+/** An action term: what a service operation does, and to what. */
+export class BianActionTerm {
+    /**
+     * @param {string} name - 'initiate'
+     * @param {'service-domain'|'create'|'instance'|'read'} group
+     * @param {string} description
+     */
+    constructor(name, group, description) {
+        this.name = name;
+        this.group = group;
+        this.description = description;
+    }
+}
+
+const fp = (name, artifact, description, creates, qualifierType, inferred = [], formerArtifacts = []) =>
+    [name, new BianFunctionalPattern(name, { artifact, description, creates, qualifierType, inferred, formerArtifacts })];
+
+/**
+ * The nineteen functional patterns, each with its artifact, creating action term
+ * and behaviour qualifier type as BIAN's v14 model has them.
+ */
+const FUNCTIONAL_PATTERNS = new Map([
+    fp('Direct', 'Strategy', 'Define the policies, goals and objectives and strategies for an organizational entity or unit.', 'create', 'Goal'),
+    fp('Manage', 'Management Plan', 'Oversee the working of a business unit, assign work, manage against a plan and troubleshoot issues.', 'create', 'Duty'),
+    fp('Administer', 'Administrative Plan', 'Handle and assign the day to day activities, capture time worked, costs and income for an operational unit.', 'create', 'Routine'),
+    fp('Design', 'Specification', 'Create and maintain a design for a procedure, product/service model or other such entity.', 'create', 'Aspect'),
+    fp('Develop', 'Development', 'Build or enhance something, typically an IT production system: development, assessment and deployment.', 'create', 'Deliverable'),
+    fp('Process', 'Procedure', 'Complete work tasks following a procedure in support of general office activities and product and service delivery.', 'initiate', 'Workstep'),
+    fp('Operate', 'Operating Session', 'Operate equipment and/or a largely automated facility.', 'initiate', 'Function'),
+    fp('Maintain', 'Maintenance Arrangement', 'Provide a maintenance service and repair devices/equipment as necessary.', 'initiate', 'Item'),
+    fp('Fulfill', 'Facility', 'Fulfill scheduled and ad-hoc obligations under a service arrangement, most typically for a financial product or facility.', 'initiate', 'Fulfillment', [], ['Arrangement']),
+    fp('Transact', 'Transaction', 'Execute a well bounded financial transaction/task, typically largely automated, structured fulfillment processing.', 'initiate', 'Task'),
+    fp('Agree Terms', 'Agreement', 'Maintain the terms and conditions that apply to a commercial relationship.', 'evaluate', 'Term'),
+    fp('Assess', 'Assessment', 'Test or assess an entity, possibly against some formal qualification or certification requirement.', 'evaluate', 'Test'),
+    fp('Analyze', 'Analysis', 'Analyze the performance or behavior of some on-going activity or entity.', 'evaluate', 'Algorithm'),
+    fp('Monitor', 'State', 'Monitor and define the state/rating of some entity.', 'initiate', 'Indicator'),
+    fp('Track', 'Log', 'Maintain a log of transactions or activity, typically a financial account/journal or a log of activity.', 'initiate', 'Event', [], ['Log Record']),
+    fp('Catalog', 'Directory Entry', 'Capture and maintain reference information about some type of entity.', 'register', 'Property'),
+    fp('Enroll', 'Membership', 'Maintain a membership for some group or related collection of parties.', 'register', 'Clause'),
+    fp('Allocate', 'Allocation', 'Maintain an inventory or holding of some resource and make assignments/allocations as requested.', 'provide', 'Criteria'),
+    fp('Advise', 'Advice', 'Provide specialist advice and/or support as an ongoing service or for a specific task/event.', 'initiate', 'Topic'),
+]);
+
+/** Names a pattern has had ('Analyse', the guide's; BIAN's model has 'Analyze'). */
+const PATTERN_ALIASES = new Map([['Analyse', 'Analyze']]);
+
+const at = (name, group, description) => [name, new BianActionTerm(name, group, description)];
+
+/** The seventeen action terms in their four groups (Practitioner Guide V8.1, Figure 14 and after). */
+const ACTION_TERMS = new Map([
+    at('activate', 'service-domain', 'Start the service domain operating as a service center.'),
+    at('configure', 'service-domain', 'Change how the service domain operates.'),
+    at('feedback', 'service-domain', 'Give feedback on how the service domain operates.'),
+    at('create', 'create', 'Make a new control record (a plan, a design, a solution).'),
+    at('initiate', 'create', 'Create and start a new control record, or a behaviour qualifier of one.'),
+    at('register', 'create', 'Add a new entry: catalogue or enroll.'),
+    at('evaluate', 'create', 'Start a test, check or analysis.'),
+    at('provide', 'create', 'Provide a new instance (an allocation, a log record).'),
+    at('update', 'instance', 'Change the values of an active control record.'),
+    at('control', 'instance', 'Change the state of an active control record (suspend, resume, terminate).'),
+    at('exchange', 'instance', 'Accept, reject, verify or otherwise exchange about an active control record.'),
+    at('capture', 'instance', 'Take in information about an active control record from outside.'),
+    at('execute', 'instance', 'Run an automated task on an active control record or one of its behaviour qualifiers.'),
+    at('request', 'instance', 'Ask for a task on an active control record that needs a decision or manual work.'),
+    at('grant', 'instance', 'Give an authorization or permission against an active control record.'),
+    at('retrieve', 'read', 'Get details of one or more control records, without changing them.'),
+    at('notify', 'read', 'Subscribe to changes of control records, without changing them.'),
+]);
+
+/** The behaviour qualifier types, as BIAN v14.0 rationalised them (release notes, section 7.2). */
+const QUALIFIER_TYPES = Object.freeze([
+    'Fulfillment', 'Term', 'Duty', 'Aspect', 'Clause', 'Algorithm', 'Task', 'Property', 'Routine', 'Criteria',
+    'Deliverable', 'Indicator', 'Topic', 'Workstep', 'Event', 'Goal', 'Function', 'Test', 'Item',
+]);
+
+/** The action terms that act on an existing control record or behaviour qualifier, or read one. */
+const ON_INSTANCE = Object.freeze(['instance', 'read']);
+
+export const BianNotation = {
+    /** Every functional pattern, in the guide's order. */
+    functionalPatterns() { return [...FUNCTIONAL_PATTERNS.values()]; },
+    /** A functional pattern by name, or null. */
+    functionalPattern(name) { return FUNCTIONAL_PATTERNS.get(name) ?? FUNCTIONAL_PATTERNS.get(PATTERN_ALIASES.get(name)) ?? null; },
+    /** A pattern by its name as written anywhere: any case, extra spaces, a former name ('analyse'); null for none. */
+    findPattern(text) {
+        const word = String(text ?? '').trim().replace(/\s+/g, ' ').toLowerCase();
+        if (!word) return null;
+        const alias = [...PATTERN_ALIASES].find(([old]) => old.toLowerCase() === word)?.[1];
+        return [...FUNCTIONAL_PATTERNS.values()].find(p => p.name.toLowerCase() === word || p.name === alias) ?? null;
+    },
+    /**
+     * The pattern a control record's name says it has, by the artifact it ends
+     * with ('CurrentAccountFacility' or 'Current Account Facility': Fulfill;
+     * a former artifact name too), the longest match first; null for none.
+     */
+    patternOfControlRecord(name) {
+        const words = String(name ?? '').replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2').toLowerCase().split(/\s+/).filter(Boolean).join(' ');
+        const ends = [...FUNCTIONAL_PATTERNS.values()]
+            .flatMap(p => [p.artifact, ...p.formerArtifacts].map(a => [a.toLowerCase(), p]))
+            .sort(([a], [b]) => b.length - a.length);
+        return ends.find(([a]) => words === a || words.endsWith(` ${a}`))?.[1] ?? null;
+    },
+    /** Every action term. */
+    actionTerms() { return [...ACTION_TERMS.values()]; },
+    actionTerm(name) { return ACTION_TERMS.get(name) ?? null; },
+    /** The behaviour qualifier types. */
+    qualifierTypes() { return [...QUALIFIER_TYPES]; },
+    isQualifierType(type) { return QUALIFIER_TYPES.includes(type); },
+
+    /**
+     * A service domain's default service operations for a functional pattern
+     * (the starting point BIAN gives; a deployment may drop or add some): the
+     * service-domain-wide terms on the service domain; the pattern's creating
+     * term on the control record and on each behaviour qualifier; and each
+     * instance and read term on the control record and each behaviour qualifier.
+     * @param {string} patternName
+     * @param {{serviceDomain: string, controlRecord: string, qualifiers?: string[]}} names
+     *   'Current Account', 'Current Account Arrangement', ['Interest', 'Payments']
+     * @returns {Array<{actionTerm: string, target: string, qualifier: string|null, name: string}>}
+     */
+    serviceOperations(patternName, { serviceDomain, controlRecord, qualifiers = [] }) {
+        const pattern = FUNCTIONAL_PATTERNS.get(patternName);
+        if (!pattern) return [];
+        const op = (term, target, qualifier = null) => ({
+            actionTerm: term, target, qualifier,
+            name: `${term} ${target}${qualifier ? ` | ${qualifier}` : ''}`,
+        });
+        const terms = (group) => [...ACTION_TERMS.values()].filter(t => group(t.group)).map(t => t.name);
+        const onInstance = terms(g => ON_INSTANCE.includes(g));
+        return [
+            ...terms(g => g === 'service-domain').map(t => op(t, serviceDomain)),
+            op(pattern.creates, controlRecord),
+            ...onInstance.map(t => op(t, controlRecord)),
+            ...qualifiers.flatMap(q => [op(pattern.creates, controlRecord, q), ...onInstance.map(t => op(t, controlRecord, q))]),
+        ];
+    },
+};