@peter.prib/renderengine 0.5.0 → 0.8.0

package/src/charting/diagrams/MergeElementsCommand.js

@@ -1,101 +1,124 @@
-import { Command } from '../CommandHistory.js';
-import { structuredCopy } from './ElementInstance.js';
-
-/**
- * MergeElementsCommand — elements that are one thing twice made into one
- * (Archi's merge): the one kept takes the others' relationships, their boxes
- * on every view, the documentation it lacks and the properties it lacks; the
- * others go. A relationship left joining the kept element to itself, or the
- * same as another (kind and ends), goes too, its lines drawn as the other.
- * Undo puts everything back as it was.
- */
-export class MergeElementsCommand extends Command {
-    /**
-     * @param {ArchimateModel} model
-     * @param {string} keepId - The element kept
-     * @param {Array<string>} otherIds - The elements merged into it
-     */
-    constructor(model, keepId, otherIds, label = `Merge ${otherIds.length + 1} elements into "${model.getElement(keepId)?.name || keepId}"`) {
-        super(label);
-        this.model = model;
-        this.keepId = keepId;
-        this.otherIds = otherIds.filter(id => id !== keepId && model.getElement(id));
-        this._before = null;
-    }
-
-    execute() {
-        const { model, keepId } = this;
-        const keep = model.getElement(keepId);
-        if (!keep || !this.otherIds.length) return;
-        this._before = this._snapshot();
-        const merged = new Set(this.otherIds);
-        const into = (id) => (merged.has(id) ? keepId : id);
-        for (const other of this.otherIds.map(id => model.getElement(id))) {
-            if (other.documentation && !(keep.documentation ?? '').includes(other.documentation)) {
-                keep.documentation = keep.documentation ? `${keep.documentation}\n\n${other.documentation}` : other.documentation;
-            }
-            const own = new Set((keep.properties ?? []).map(p => p.name ?? p.key));
-            const added = (other.properties ?? []).filter(p => !own.has(p.name ?? p.key));
-            if (added.length) keep.properties = [...(keep.properties ?? []), ...added.map(p => ({ ...p }))];
-            if (!keep.specialization && other.specialization) keep.specialization = other.specialization;
-        }
-        // Relationships end at the kept element; one left joining it to itself, or doubling another, goes.
-        const seen = new Map();
-        const replaced = new Map();   // removed relationship id -> the one its lines now draw
-        for (const rel of model.relationships()) {
-            const touched = merged.has(rel.source) || merged.has(rel.target);
-            rel.source = into(rel.source);
-            rel.target = into(rel.target);
-            if (touched && rel.source === keepId && rel.target === keepId) { replaced.set(rel.id, null); continue; }
-            const key = `${rel.kind} ${rel.source} ${rel.target} ${rel.name ?? ''}`;
-            if (touched && seen.has(key)) replaced.set(rel.id, seen.get(key));
-            else if (!seen.has(key)) seen.set(key, rel.id);
-        }
-        for (const id of replaced.keys()) model.removeRelationship(id);
-        for (const view of model.views()) {
-            if (Array.isArray(view.elementIds)) view.elementIds = [...new Set(view.elementIds.map(into))];
-            for (const inst of view.elementInstances?.values() ?? []) if (merged.has(inst.elementId)) inst.elementId = keepId;
-            for (const inst of [...(view.relationshipInstances?.values() ?? [])]) {
-                if (!replaced.has(inst.relationshipId)) continue;
-                const now = replaced.get(inst.relationshipId);
-                if (now) inst.relationshipId = now;
-                else view.relationshipInstances.delete(inst.id);
-            }
-        }
-        for (const id of this.otherIds) model.removeElement(id);
-    }
-
-    undo() {
-        if (!this._before) return;
-        const { model } = this;
-        const b = this._before;
-        model._elements = new Map(b.elements.map(([id, el]) => [id, el]));
-        const keep = model._elements.get(this.keepId);
-        Object.keys(keep).forEach(k => delete keep[k]);   // what the merge added too
-        Object.assign(keep, structuredCopy(b.keep));
-        model._elementFolder = new Map(b.folders);
-        model._relationships = new Map(b.relationships.map(([id, rel, ends]) => [id, Object.assign(rel, ends)]));
-        for (const v of b.views) {
-            v.view.elementIds = v.elementIds;
-            for (const [inst, elementId] of v.instances) inst.elementId = elementId;
-            v.view.relationshipInstances = new Map(v.lines.map(([inst, relationshipId]) => { inst.relationshipId = relationshipId; return [inst.id, inst]; }));
-        }
-    }
-
-    /** Everything the merge changes, to put back. @private */
-    _snapshot() {
-        const { model } = this;
-        return {
-            elements: [...model._elements],
-            keep: structuredCopy(model.getElement(this.keepId)),
-            folders: [...model._elementFolder],
-            relationships: [...model._relationships].map(([id, rel]) => [id, rel, { source: rel.source, target: rel.target }]),
-            views: model.views().map(view => ({
-                view,
-                elementIds: Array.isArray(view.elementIds) ? [...view.elementIds] : view.elementIds,
-                instances: [...(view.elementInstances?.values() ?? [])].map(inst => [inst, inst.elementId]),
-                lines: [...(view.relationshipInstances?.values() ?? [])].map(inst => [inst, inst.relationshipId]),
-            })),
-        };
-    }
-}
+import { Command } from '../CommandHistory.js';
+import { structuredCopy } from './ElementInstance.js';
+
+/**
+ * MergeElementsCommand — elements that are one thing twice made into one
+ * (Archi's merge): the one kept takes the others' relationships, their boxes
+ * on every view, the documentation it lacks and the properties it lacks; the
+ * others go. A relationship left joining the kept element to itself, or the
+ * same as another (kind and ends), goes too, its lines drawn as the other.
+ * What differs can be chosen instead: the documentation (one of them, or all
+ * joined), a property's value, the specialization.
+ * Undo puts everything back as it was.
+ */
+export class MergeElementsCommand extends Command {
+    /**
+     * @param {ArchimateModel} model
+     * @param {string} keepId - The element kept
+     * @param {Array<string>} otherIds - The elements merged into it
+     * @param {Object} [choices] - What the kept element ends with, where they differ
+     * @param {string} [choices.documentation] - Its documentation (else its own, with the others' it lacks joined on)
+     * @param {Object<string, string>} [choices.properties] - A value for each property named
+     * @param {string} [choices.specialization] - Its specialization (else its own, or the first other's)
+     * @param {string} [choices.label] - The undo step's name
+     */
+    constructor(model, keepId, otherIds, { documentation, properties = {}, specialization, label } = {}) {
+        super(label ?? `Merge ${otherIds.length + 1} elements into "${model.getElement(keepId)?.name || keepId}"`);
+        this.model = model;
+        this.keepId = keepId;
+        this.otherIds = otherIds.filter(id => id !== keepId && model.getElement(id));
+        this.choices = { documentation, properties, specialization };
+        this._before = null;
+    }
+
+    execute() {
+        const { model, keepId } = this;
+        const keep = model.getElement(keepId);
+        if (!keep || !this.otherIds.length) return;
+        this._before = this._snapshot();
+        const merged = new Set(this.otherIds);
+        const into = (id) => (merged.has(id) ? keepId : id);
+        for (const other of this.otherIds.map(id => model.getElement(id))) {
+            if (other.documentation && !(keep.documentation ?? '').includes(other.documentation)) {
+                keep.documentation = keep.documentation ? `${keep.documentation}\n\n${other.documentation}` : other.documentation;
+            }
+            const own = new Set((keep.properties ?? []).map(p => p.name ?? p.key));
+            const added = (other.properties ?? []).filter(p => !own.has(p.name ?? p.key));
+            if (added.length) keep.properties = [...(keep.properties ?? []), ...added.map(p => ({ ...p }))];
+            if (!keep.specialization && other.specialization) keep.specialization = other.specialization;
+        }
+        this._applyChoices(keep);
+        // Relationships end at the kept element; one left joining it to itself, or doubling another, goes.
+        // A re-pointed one doubling one there (untouched, or re-pointed before it) goes; doubles there before stay.
+        const key = (rel) => `${rel.kind} ${rel.source} ${rel.target} ${rel.name ?? ''}`;
+        const touched = model.relationships().filter(rel => merged.has(rel.source) || merged.has(rel.target));
+        const seen = new Map();
+        for (const rel of model.relationships()) if (!touched.includes(rel) && !seen.has(key(rel))) seen.set(key(rel), rel.id);
+        const replaced = new Map();   // removed relationship id -> the one its lines now draw
+        for (const rel of touched) {
+            rel.source = into(rel.source);
+            rel.target = into(rel.target);
+            if (rel.source === keepId && rel.target === keepId) { replaced.set(rel.id, null); continue; }
+            if (seen.has(key(rel))) replaced.set(rel.id, seen.get(key(rel)));
+            else seen.set(key(rel), rel.id);
+        }
+        for (const id of replaced.keys()) model.removeRelationship(id);
+        for (const view of model.views()) {
+            if (Array.isArray(view.elementIds)) view.elementIds = [...new Set(view.elementIds.map(into))];
+            for (const inst of view.elementInstances?.values() ?? []) if (merged.has(inst.elementId)) inst.elementId = keepId;
+            for (const inst of [...(view.relationshipInstances?.values() ?? [])]) {
+                if (!replaced.has(inst.relationshipId)) continue;
+                const now = replaced.get(inst.relationshipId);
+                if (now) inst.relationshipId = now;
+                else view.relationshipInstances.delete(inst.id);
+            }
+        }
+        for (const id of this.otherIds) model.removeElement(id);
+    }
+
+    /** What was chosen where the elements differ, on the kept one. @private */
+    _applyChoices(keep) {
+        const { documentation, properties, specialization } = this.choices;
+        if (documentation !== undefined) keep.documentation = documentation;
+        if (specialization !== undefined) keep.specialization = specialization;
+        for (const [name, value] of Object.entries(properties)) {
+            const own = (keep.properties ?? []).find(p => (p.name ?? p.key) === name);
+            if (own) own.value = value;
+            else keep.properties = [...(keep.properties ?? []), { key: name, value }];
+        }
+    }
+
+    undo() {
+        if (!this._before) return;
+        const { model } = this;
+        const b = this._before;
+        model._elements = new Map(b.elements.map(([id, el]) => [id, el]));
+        const keep = model._elements.get(this.keepId);
+        Object.keys(keep).forEach(k => delete keep[k]);   // what the merge added too
+        Object.assign(keep, structuredCopy(b.keep));
+        model._elementFolder = new Map(b.folders);
+        model._relationships = new Map(b.relationships.map(([id, rel, ends]) => [id, Object.assign(rel, ends)]));
+        for (const v of b.views) {
+            v.view.elementIds = v.elementIds;
+            for (const [inst, elementId] of v.instances) inst.elementId = elementId;
+            v.view.relationshipInstances = new Map(v.lines.map(([inst, relationshipId]) => { inst.relationshipId = relationshipId; return [inst.id, inst]; }));
+        }
+    }
+
+    /** Everything the merge changes, to put back. @private */
+    _snapshot() {
+        const { model } = this;
+        return {
+            elements: [...model._elements],
+            keep: structuredCopy(model.getElement(this.keepId)),
+            folders: [...model._elementFolder],
+            relationships: [...model._relationships].map(([id, rel]) => [id, rel, { source: rel.source, target: rel.target }]),
+            views: model.views().map(view => ({
+                view,
+                elementIds: Array.isArray(view.elementIds) ? [...view.elementIds] : view.elementIds,
+                instances: [...(view.elementInstances?.values() ?? [])].map(inst => [inst, inst.elementId]),
+                lines: [...(view.relationshipInstances?.values() ?? [])].map(inst => [inst, inst.relationshipId]),
+            })),
+        };
+    }
+}

package/src/charting/diagrams/SvgZoom.js

@@ -8,8 +8,16 @@ import { ViewFit } from '../ViewFit.js';
  * without going through the engine façade.
  */
 export class SvgZoom {
-    constructor(container, svg, { clientToSvgPoint, hitTest, is3D } = {}) {
+    /**
+     * @param {HTMLElement} container
+     * @param {SVGSVGElement} svg
+     * @param {Object} [options]
+     * @param {'ctrl'|'alt'|'shift'|null} [options.wheelModifier] - Zoom only with this key held (ctrl
+     *   also takes ⌘), so a plain wheel scrolls the page; null: any wheel zooms
+     */
+    constructor(container, svg, { clientToSvgPoint, hitTest, is3D, wheelModifier = null } = {}) {
         this.container = container;
+        this.wheelModifier = wheelModifier;
         this.svg = svg;
         this.clientToSvgPoint = clientToSvgPoint;
         this.hitTest = hitTest;
@@ -72,8 +80,19 @@ export class SvgZoom {
         viewBox.height = this._initialViewBox.height;
     }
 
+    /** Whether `event` has the wheel modifier held (always, when there is none). */
+    wheelZooms(event) {
+        switch (this.wheelModifier) {
+            case 'ctrl':  return !!(event.ctrlKey || event.metaKey);
+            case 'alt':   return !!event.altKey;
+            case 'shift': return !!event.shiftKey;
+            default:      return true;
+        }
+    }
+
     _onWheel(event) {
         if (this.is3D?.()) return;
+        if (!this.wheelZooms(event)) return;
         event.preventDefault();
 
         const scaleFactor = event.deltaY > 0 ? 1.1 : 1 / 1.1;

package/src/charting/diagrams/duplicates.js

@@ -1,35 +1,117 @@
 /**
  * When two elements are probably one thing twice: one definition for the
- * model check (likely duplicates) and whatever offers to merge them.
+ * model check (likely duplicates), Find likely duplicates… and whatever
+ * offers to merge them.
  *
- * Names are compared by their words, ignoring case, punctuation, word order
- * and filler words ("of", "and", "the", ...): "Order Management System",
- * "order-management system" and "System of Order Management" match. A name
- * that is only filler is compared as it is.
+ * Text is compared by its words, ignoring case, punctuation, word order and
+ * noise words ("of", "and", "the", ...): "Order Management System",
+ * "order-management system" and "System of Order Management" match, and so
+ * do a word and its plural ("Customer", "Customers"; "Process", "Processes").
+ * A name that is only noise is compared as it is. How much is noise, and what
+ * is compared (the names, the documentation, a property's value), are options
+ * (DUPLICATE_OPTIONS), as the jArchi dedupe scripts have them.
  */
 
 /** Words that do not tell two names apart. */
 export const FILLER_WORDS = Object.freeze(['a', 'an', 'and', 'the', 'of', 'on', 'for', 'to', 'in', 'at', 'by', 'with', '&']);
 
-/** The words a name is compared by, as one key ('' for no name). */
-export function nameKey(name) {
-    const words = String(name ?? '').toLowerCase().replace(/[^\p{L}\p{N}&]+/gu, ' ').trim().split(/\s+/).filter(Boolean);
-    const meaningful = words.filter(w => !FILLER_WORDS.includes(w));
+/** More words that say little in a name or a description: the jArchi scripts' noise words. */
+export const NOISE_WORDS = Object.freeze([...FILLER_WORDS, 'as', 'was', 'from', 'is', 'then', 'into', 'be', 'tbc', 'tba']);
+
+/**
+ * What Find likely duplicates… compares, and what it ignores. The model check
+ * uses these as they are.
+ * - `by`: 'name', 'documentation', 'property' (the value of `property`), or any
+ *   other field of the items holding text or a list of names (a data model's 'attributes')
+ * - `match`: 'words' (by their words, with the options below) or 'exact' (the same
+ *   text, case and spacing aside)
+ * - `noiseWords`: words left out
+ * - `ignorePattern`: a regular expression; words matching it are left out (an id code: ^[Aa][0-9A-Fa-f]{5}$)
+ * - `ignoreNumbers`: numbers and version numbers ("2", "1.2.3") are left out
+ * - `ignoreShortWords`: one-letter words are left out
+ * - `plurals`: a word and its plural are one word
+ * - `acrossTypes`: elements of different types may be one thing
+ * - `skipSpecializations`: elements of these specializations are left out (Decommissioned)
+ */
+export const DUPLICATE_OPTIONS = Object.freeze({
+    by: 'name',
+    match: 'words',
+    property: '',
+    noiseWords: FILLER_WORDS,
+    ignorePattern: '',
+    ignoreNumbers: false,
+    ignoreShortWords: false,
+    plurals: true,
+    acrossTypes: false,
+    skipSpecializations: Object.freeze([]),
+});
+
+/** A word as its singular, roughly: "processes" → "process", "customers" → "customer" ("process", "status" stay). */
+export function singular(word) {
+    if (word.length > 4 && /(ss|x|ch|sh)es$/.test(word)) return word.slice(0, -2);
+    if (word.length > 3 && /[^su]s$/.test(word)) return word.slice(0, -1);
+    return word;
+}
+
+/** A number or a version number: "2", "1.2.3", "v2". */
+const NUMBER = /^v?\d+(\.\d+)*$/;
+
+/**
+ * The words some text is compared by, as one key ('' for none). Text that is
+ * all noise is compared by all its words, unless `allNoiseIsEmpty` (a
+ * description of only noise says nothing).
+ */
+export function wordKey(text, options = {}, { allNoiseIsEmpty = false } = {}) {
+    const { noiseWords, ignorePattern, ignoreNumbers, ignoreShortWords, plurals } = { ...DUPLICATE_OPTIONS, ...options };
+    const ignore = ignorePattern ? new RegExp(ignorePattern, 'i') : null;
+    const words = String(text ?? '').toLowerCase().replace(/[^\p{L}\p{N}&.]+/gu, ' ').replace(/\.(?!\d)/g, ' ').trim().split(/\s+/).filter(Boolean);
+    const meaningful = words
+        .filter(w => !noiseWords.includes(w))
+        .filter(w => !(ignoreNumbers && NUMBER.test(w)))
+        .filter(w => !(ignoreShortWords && w.length < 2))
+        .filter(w => !ignore?.test(w))
+        .map(w => (plurals ? singular(w) : w));
+    if (!meaningful.length && allNoiseIsEmpty) return '';
     return [...new Set(meaningful.length ? meaningful : words)].sort().join(' ');
 }
 
+/** The words a name is compared by, as one key ('' for no name): wordKey with the model check's options. */
+export function nameKey(name) {
+    return wordKey(name);
+}
+
+/** Text as it is, case and spacing aside. */
+const exactKey = (text) => String(text ?? '').trim().replace(/\s+/g, ' ').toLowerCase();
+
+/** What of an element is compared, as a key ('' when it has nothing to compare). */
+export function duplicateKey(element, options = {}) {
+    const o = { ...DUPLICATE_OPTIONS, ...options };
+    if (o.by === 'property') {
+        const prop = (element.properties ?? []).find(p => (p.name ?? p.key) === o.property);
+        return exactKey(prop?.value);
+    }
+    if (o.by === 'name') return o.match === 'exact' ? exactKey(element.name) : wordKey(element.name, o);
+    // Documentation, or another field: a list is its items' names (or the items) together.
+    const field = element[o.by];
+    const text = Array.isArray(field) ? field.map(f => f?.name ?? f).join(' ') : field;
+    return o.match === 'exact' ? exactKey(text) : wordKey(text, o, { allNoiseIsEmpty: true });
+}
+
 /**
  * The elements that are probably the same thing twice: groups of two or more
- * of one type whose names have the same key.
+ * (of one type, unless `acrossTypes`) with the same key (duplicateKey).
  * @param {Array<Object>} elements
+ * @param {Object} [options] - DUPLICATE_OPTIONS
  * @returns {Array<Array<Object>>}
  */
-export function duplicateGroups(elements) {
+export function duplicateGroups(elements, options = {}) {
+    const o = { ...DUPLICATE_OPTIONS, ...options };
     const groups = new Map();
     for (const e of elements) {
-        const key = nameKey(e.name);
+        if (o.skipSpecializations.includes(e.specialization)) continue;
+        const key = duplicateKey(e, o);
         if (!key) continue;
-        const k = `${e.type} ${key}`;
+        const k = o.acrossTypes ? key : `${e.type} ${key}`;
         if (!groups.has(k)) groups.set(k, []);
         groups.get(k).push(e);
     }

package/src/charting/duplicateSearchForm.js

@@ -0,0 +1,58 @@
+import { DUPLICATE_OPTIONS, NOISE_WORDS } from './diagrams/duplicates.js';
+
+/**
+ * The Find likely duplicates… form, for any model: one definition of its
+ * fields (FormDialog field specs) and of reading them back into the options
+ * duplicateGroups takes (DUPLICATE_OPTIONS). A modeller gives what is
+ * particular to it: where to look (`scope`: the whole model, a view, a level),
+ * what can be compared (`compare`), the property names and specializations its
+ * items have.
+ */
+
+/**
+ * The form's fields.
+ * @param {Object} [options]
+ * @param {{label: string, choices: Array<[string, string]>, value?: string}} [options.scope] - Where to look
+ * @param {Array<[string, string]>} [options.compare] - What can be compared: [by, label] (names and documentation unless given)
+ * @param {string[]} [options.properties] - Property names: comparing a property's value is offered with any
+ * @param {string[]} [options.specializations] - Specializations: leaving one out is offered with any
+ * @returns {Array<Object>}
+ */
+export function duplicateSearchFields({ scope = null, compare = [['name', 'Names'], ['documentation', 'Documentation']], properties = [], specializations = [] } = {}) {
+    const o = DUPLICATE_OPTIONS;
+    return [
+        ...(scope ? [{ key: 'scope', label: scope.label, type: 'select', value: scope.value ?? scope.choices[0][0], choices: scope.choices }] : []),
+        { key: 'by', label: 'Compare', type: 'select', value: compare[0][0], choices: [...compare, ...(properties.length ? [['property', 'A property’s value']] : [])] },
+        ...(properties.length ? [{ key: 'property', label: 'Property', type: 'select', value: properties[0], choices: properties.map(n => [n, n]) }] : []),
+        { key: 'match', label: 'Match', type: 'select', value: o.match, choices: [['words', 'The same words (as below)'], ['exact', 'Exactly (case and spacing aside)']] },
+        { key: 'noiseWords', label: 'Noise words', type: 'text', value: NOISE_WORDS.join(', ') },
+        { key: 'ignorePattern', label: 'Ignore words matching', type: 'text', value: o.ignorePattern, placeholder: '^[Aa][0-9A-Fa-f]{5}$' },
+        { key: 'ignoreNumbers', label: 'Ignore numbers and versions', type: 'checkbox', value: true },
+        { key: 'ignoreShortWords', label: 'Ignore one-letter words', type: 'checkbox', value: true },
+        { key: 'plurals', label: 'A word and its plural are one', type: 'checkbox', value: o.plurals },
+        { key: 'acrossTypes', label: 'Across types', type: 'checkbox', value: o.acrossTypes },
+        ...(specializations.length ? [{ key: 'skip', label: 'Leave out specialization', type: 'select', value: '', choices: [['', '(none)'], ...specializations.map(n => [n, n])] }] : []),
+    ];
+}
+
+/** A message when the form's values will not do (a pattern that is not a regular expression), else null. */
+export function validateDuplicateSearch({ ignorePattern } = {}) {
+    try {
+        new RegExp(ignorePattern || '');
+        return null;
+    } catch {
+        return 'Ignore words matching: not a regular expression';
+    }
+}
+
+/** The form's values as duplicateGroups' options, and where to look (`scope`, when the form asked). */
+export function duplicateSearchOptions({ noiseWords, skip, scope, ...rest } = {}) {
+    return {
+        options: {
+            ...rest,
+            noiseWords: String(noiseWords ?? '').split(/[\s,]+/).map(w => w.trim().toLowerCase()).filter(Boolean),
+            skipSpecializations: skip ? [skip] : [],
+        },
+        scope,
+    };
+}