@peter.prib/renderengine 0.0.0-stage → 0.2.0

package/src/propertiesDialog.js

@@ -0,0 +1,463 @@
+/**
+ * propertiesDialog — the "Show/Edit Properties" dialog, as a shipped feature.
+ *
+ * `graphDiagram` has always had the HOOKS for this (`onNodeDoubleClick`,
+ * `contextMenuItems`, `NODE_STRUCTURAL_KEYS`) but not the dialog, which lived
+ * only in `test/charts.html`. A consumer wanting double-click-to-edit therefore
+ * had to copy 400 lines out of a demo page — so nobody did, and diagrams that
+ * could have been editable were read-only. This is that dialog, generalized.
+ *
+ * Two halves, split on testability:
+ *
+ *  - The DECISIONS are pure functions over plain objects — which fields a
+ *    subject has, which section each belongs to, which control type edits it,
+ *    how a typed value is read back out of a string, and whether a derived
+ *    colour/icon may be refreshed silently. No DOM.
+ *  - The dialog itself is a FormDialog built from those: a thin shell.
+ *
+ * Nothing here runs at import time, so this module loads under node.
+ */
+
+import { LabelHelper } from './charting/diagrams/LabelHelper.js';
+import { ArchimateDiagram } from './charting/diagrams/ArchimateDiagram.js';
+import { ArchimateSpecializationSelector } from './charting/ArchimateSpecializationSelector.js';
+import { FormDialog } from './charting/FormDialog.js';
+import { el } from './workspace/dom.js';
+import { TextStyle } from './charting/TextStyle.js';
+import { PropertyListEditor, PROPERTY_TYPES, coercePropertyValue, stringifyPropertyValue } from './charting/PropertyListEditor.js';
+
+export { PROPERTY_TYPES, coercePropertyValue, stringifyPropertyValue };
+
+/** ArchiMate's own layers plus the engine's catch-all — a closed list. */
+export const LAYER_CHOICES = [
+    'strategy', 'business', 'application', 'technology',
+    'physical', 'motivation', 'implementation', 'other',
+];
+
+/**
+ * Which section of the form a node field belongs to.
+ *
+ * OBJECT is the concept itself — the same whatever diagram draws it. DIAGRAM is
+ * this view's own presentation of it. Both live on the one flat node object
+ * `graphDiagram` renders (there is no model/view split under the hood); the
+ * grouping keeps the distinction visible while editing, which is the whole
+ * point of an architecture tool.
+ */
+export const NODE_SECTIONS = {
+    object: ['name', 'description', 'type', 'specialization'],
+    diagram: ['label', 'layer', 'color', 'strokeColor', 'textColor', 'icon', 'group', 'size', 'useDistinctShape'],
+};
+
+/** What a field is called in the dialog, where its key would not read well. */
+export const FIELD_LABELS = {
+    color: 'Fill colour', strokeColor: 'Line colour', textColor: 'Text colour',
+    useDistinctShape: 'Distinct shape',
+};
+
+/** Which control edits which field. Anything unlisted is a plain text box. */
+const FIELD_TYPES = {
+    description: 'textarea',
+    documentation: 'textarea',
+    notes: 'textarea',
+    tooltip: 'textarea',
+    color: 'color',
+    strokeColor: 'color',
+    textColor: 'color',
+    layer: 'select',
+    icon: 'select',
+    type: 'select-editable',
+    specialization: 'select-editable',
+    useDistinctShape: 'checkbox',
+};
+
+/**
+ * The rows a dialog should show, in order, already sectioned and typed.
+ *
+ * @param {object} subject  the node or edge being edited
+ * @param {'node'|'edge'} kind
+ * @param {object} [ctx]
+ * @param {string[]} [ctx.typeChoices]  suggestions for `type`
+ * @param {string[]} [ctx.iconChoices]  options for `icon`
+ * @param {string[]} [ctx.extraKeys]    caller-added fields, from the engine's
+ *        own "extra data" reckoning — shown under Other/Extra
+ * @returns {Array<{key, value, section, type, choices?, readOnly?}>}
+ */
+export function propertyRowsFor(subject = {}, kind = 'node', ctx = {}) {
+    const { typeChoices = [], iconChoices = [], relationshipChoices = [], specializationChoices = [], extraKeys = [] } = ctx;
+    const rows = [];
+    const seen = new Set();
+    const push = (key, section, over = {}) => {
+        if (seen.has(key)) return;
+        seen.add(key);
+        rows.push({
+            key, section, value: subject[key],
+            type: over.type ?? FIELD_TYPES[key] ?? 'text',
+            ...(over.choices ? { choices: over.choices } : {}),
+            ...(over.readOnly ? { readOnly: true } : {}),
+        });
+    };
+
+    if (kind === 'edge') {
+        // The ends are identity, not a property — renaming one would silently
+        // re-wire the diagram, which is a different (and destructive) action
+        // from editing what the relationship IS.
+        push('source', 'edge', { readOnly: true });
+        push('target', 'edge', { readOnly: true });
+        push('label', 'edge');
+        push('kind', 'edge', { type: 'select', choices: relationshipChoices });
+        push('weight', 'edge');
+        push('color', 'edge');
+        push('tooltip', 'edge');
+    } else {
+        for (const key of NODE_SECTIONS.object) {
+            push(key, 'object',
+                key === 'type' ? { choices: typeChoices }
+                    : key === 'specialization' ? { choices: specializationChoices }
+                        : {});
+        }
+        for (const key of NODE_SECTIONS.diagram) {
+            push(key, 'diagram',
+                key === 'layer' ? { choices: LAYER_CHOICES }
+                    : key === 'icon' ? { choices: iconChoices }
+                        : {});
+        }
+    }
+    for (const key of extraKeys) push(key, 'other');
+    return rows;
+}
+
+/**
+ * Read an edited string back as the type the field originally held.
+ *
+ * A field that was a number must not come back as the string "3" — the diagram
+ * sizes and scales off it. Invalid JSON in an array field leaves the value
+ * alone rather than destroying it.
+ */
+export function coerceFieldValue(raw, { wasArray = false, wasNumber = false, wasBoolean = false, previous } = {}) {
+    if (wasArray) {
+        try { return JSON.parse(raw); } catch { return previous; }
+    }
+    if (wasNumber) return raw === '' ? undefined : Number(raw);
+    if (wasBoolean) return raw === 'true';
+    return raw;
+}
+
+/**
+ * After a layer/type change, may the derived colour and icon be refreshed
+ * WITHOUT asking?
+ *
+ * Only when they were never customised — still exactly what auto-derivation
+ * gave the OLD layer/type, and not something typed in this same edit. There is
+ * nothing of the user's to lose in that case. Anything they chose deliberately
+ * is theirs, and gets a prompt instead.
+ *
+ * @returns {{color: boolean, icon: boolean, changed: boolean}}
+ */
+export function derivedRefreshPlan({
+    layerChanged = false, typeChanged = false,
+    colorWasAuto = false, iconWasAuto = false,
+    colorFieldUntouched = true, iconFieldUntouched = true,
+} = {}) {
+    const changed = !!(layerChanged || typeChanged);
+    return {
+        changed,
+        color: changed && colorWasAuto && colorFieldUntouched,
+        icon: changed && iconWasAuto && iconFieldUntouched,
+    };
+}
+
+/* ── DOM side ────────────────────────────────────────────────────────────── */
+
+/**
+ * Show the properties of one node or edge, editable.
+ *
+ * @param {object} subject   the node/edge object the diagram is rendering
+ * @param {RenderEngine} engine
+ * @param {'node'|'edge'} kind
+ * @param {object} [options]
+ * @param {Function} [options.onSave]  (subject, changedKeys) — persist here.
+ *        The subject is already updated and the diagram already re-rendered.
+ * @param {Document} [options.document]
+ */
+export function showPropertiesDialog(subject, engine, kind = 'node', options = {}) {
+    // A context-menu action's exception is otherwise swallowed by the menu's
+    // own click listener — nothing visibly happens, with no clue why.
+    try {
+        return showPropertiesDialogUnsafe(subject, engine, kind, options);
+    } catch (err) {
+        console.error('showPropertiesDialog failed:', err);
+        // eslint-disable-next-line no-alert
+        (options.document ?? document).defaultView?.alert?.(`Properties failed: ${err?.message ?? err}`);
+        return null;
+    }
+}
+
+const SECTION_LABELS = { object: 'Object', diagram: 'Diagram', other: 'Other', edge: null };
+
+function showPropertiesDialogUnsafe(subject, engine, kind, options = {}) {
+    const doc = options.document ?? document;
+    const RenderEngineClass = engine.constructor;
+    const notation = RenderEngineClass.ArchimateNotation;
+    const structuralKeys = engine._graphDiagram?.structuralKeys(kind === 'edge' ? 'edge' : 'node')
+        ?? (kind === 'edge' ? RenderEngineClass.EDGE_STRUCTURAL_KEYS : RenderEngineClass.NODE_STRUCTURAL_KEYS);
+    const isNode = kind === 'node';
+    // The SAME catalog version the diagram itself was built with, so the
+    // dropdown offers exactly what is actually resolvable.
+    const version = engine._archimateOptions?.archimateVersion || '4';
+
+    const typeChoices = isNode && notation
+        ? [...new Set([
+            ...notation.elementTypeNames(version),
+            ...(engine._chartState?.nodes ?? []).map(n => n.type).filter(Boolean),
+        ])].sort()
+        : [];
+    const iconChoices = isNode && notation ? notation.iconChoices(subject.type, version) : [];
+    const relationshipChoices = !isNode && notation ? notation.relationshipTypeNames() : [];
+    const specializationChoices = isNode && notation
+        ? RenderEngineClass.ArchimateSpecializationRegistry?.list().map(s => s.name).sort() ?? []
+        : [];
+    const extraKeys = (LabelHelper.nodeExtraDataLines(subject, structuralKeys))
+        .map(line => line.slice(0, line.indexOf(':')))
+        .filter(Boolean);
+
+    const rows = propertyRowsFor(subject, kind, { typeChoices, iconChoices, relationshipChoices, specializationChoices, extraKeys });
+
+    const specSelect = isNode && RenderEngineClass.ArchimateSpecializationRegistry
+        ? new ArchimateSpecializationSelector(RenderEngineClass.ArchimateSpecializationRegistry, { doc })
+            .buildSelect({ value: subject.specialization ?? '', elementType: subject.type || null, onTypeChange: () => {} })
+        : null;
+    const propertyList = new PropertyListEditor(subject.properties ?? [], doc);
+
+    const fields = [];
+    let sectionShown = null;
+    for (const row of rows) {
+        if (row.section !== sectionShown) {
+            sectionShown = row.section;
+            if (SECTION_LABELS[row.section]) fields.push({ type: 'heading', label: SECTION_LABELS[row.section] });
+        }
+        fields.push(fieldForRow(row, specSelect));
+    }
+    // How a node's text is set: TextStyle's fields (the graph renderer draws no underline).
+    if (isNode) fields.push({ type: 'heading', label: 'Text' }, ...TextStyle.fields(TextStyle.fromNode(subject), { underline: false }));
+    // User-defined typed properties — a structured array rather than flat extra
+    // data, so it gets its own editable section.
+    fields.push({ type: 'heading', label: 'Properties' });
+    fields.push({ key: '__properties', label: '', type: 'custom', element: propertyList.element, read: () => propertyList.collect() });
+
+    // `id` (a GUID in a real app) is deliberately not shown — it has little
+    // value to a person; name/label are the human-facing identity.
+    const subjectName = kind === 'edge'
+        ? `${subject.source} → ${subject.target}`
+        : (subject.name || subject.label || subject.id);
+    const dialog = new FormDialog({
+        title: options.title ?? `${isNode ? 'Node' : 'Edge'} properties — ${subjectName}`,
+        fields,
+        submitLabel: 'Save',
+        idPrefix: 'properties-',
+        document: doc,
+        onApply: (values) => {
+            const edited = rows.filter(r => !r.readOnly).map(r => ({
+                key: r.key, input: dialog.controls[r.key], previous: r.value,
+                wasArray: Array.isArray(r.value),
+                wasNumber: typeof r.value === 'number',
+                wasBoolean: typeof r.value === 'boolean' || r.type === 'checkbox',
+            }));
+            applyEdits(subject, engine, kind, edited, notation, version);
+            // The Text section, in the node's own names.
+            const text = isNode ? TextStyle.toNode(TextStyle.fromValues(values)) : {};
+            Object.assign(subject, text);
+            const textKeys = Object.keys(text);
+            if (values.__properties.length) subject.properties = values.__properties;
+            else delete subject.properties;
+            engine._rerenderGraph?.();
+            options.onSave?.(subject, [...edited.map(e => e.key), ...textKeys, 'properties']);
+        },
+    }).open();
+
+    const { layer, type, icon } = dialog.controls;
+    if (layer && type && notation) wireLayerTypeCascade(layer, type, icon, notation, version);
+    if (type && specSelect) {
+        type.addEventListener('change', () => specSelect._onTypeChanged?.(type.value.trim()));
+    }
+    return { overlay: dialog.overlay, close: () => dialog.close() };
+}
+
+/** The FormDialog field for one property row. */
+function fieldForRow({ key, value, type, choices, readOnly }, specSelect) {
+    const base = { key, label: FIELD_LABELS[key] ?? key, value, readOnly };
+    // Text needs a colour: "No colour" is for fills and lines.
+    if (type === 'color') return { ...base, type, allowNone: key !== 'textColor' };
+    if (type === 'select-editable' && key === 'specialization' && specSelect) {
+        return { ...base, type: 'custom', element: specSelect, read: () => specSelect.value };
+    }
+    if (type === 'select-editable') return { ...base, type: 'text', suggestions: choices?.length ? choices : undefined };
+    if (type === 'select' && choices?.length) return { ...base, type: 'select', choices: choices.map(c => [c, c]), allowEmpty: true };
+    if (type === 'select') return { ...base, type: 'text' };
+    if (type === 'textarea') return { ...base, type: 'textarea', rows: key === 'description' ? 2 : 4 };
+    return { ...base, type };
+}
+
+/**
+ * The editable list of user-defined typed properties: name, type, value rows
+ * with add/remove. `collect()` reads them back, dropping unnamed rows.
+ */
+/**
+ * The category/type dependency, reflected both ways.
+ *
+ * Picking a layer narrows type's suggestions to that layer's official types AND
+ * clears type — every official type belongs to exactly one layer, so the old
+ * one essentially never still applies. Picking a recognised type snaps layer to
+ * match, and refreshes icon's options to that type's own.
+ */
+function wireLayerTypeCascade(layerInput, typeInput, iconInput, notation, version) {
+    layerInput.addEventListener('change', () => {
+        const list = typeInput.list;
+        if (!list) return;
+        list.replaceChildren(...notation.typesInLayer(layerInput.value, version).map(t => t.name).sort().map(name => new Option(name)));
+        typeInput.value = '';
+        delete typeInput.dataset.prevValue;
+        typeInput.focus();
+    });
+    typeInput.addEventListener('change', () => {
+        const known = notation.elementType(typeInput.value.trim(), version);
+        // A v4 Common Domain type has no fixed layer of its own, so there is
+        // nothing to snap to for one of those.
+        if (known?.layer) layerInput.value = known.layer.name;
+        if (!iconInput) return;
+        const current = iconInput.value;
+        const choices = notation.iconChoices(typeInput.value.trim(), version);
+        iconInput.replaceChildren(...choices.map(choice => new Option(choice, choice, false, choice === current)));
+        if (!choices.includes(current)) iconInput.value = choices[0];
+    });
+}
+
+function applyEdits(subject, engine, kind, fields, notation, version) {
+    // Captured BEFORE mutating, so "did layer/type change" and "was the colour
+    // still auto-derived from the OLD layer/type" both compare against the
+    // pre-edit state.
+    const originalLayer = subject.layer;
+    const originalType = subject.type;
+    const originalSpecialization = subject.specialization;
+    const isNode = kind === 'node';
+    const colorWasAuto = isNode && subject.color === engine._archimateLayerColor?.(originalLayer);
+    const iconWasAuto = isNode && !subject.iconUrl
+        && subject.icon === engine._archimateDefaultIcon?.(subject, originalLayer, undefined, 0, version);
+    const colorInput = fields.find(f => f.key === 'color')?.input;
+    const iconInput = fields.find(f => f.key === 'icon')?.input;
+    // Case-insensitive: a native colour input normalises to lowercase hex,
+    // which would otherwise read as a hand-edit even when nothing changed.
+    const colorFieldUntouched = !colorInput
+        || colorInput.value.toLowerCase() === String(subject.color ?? '').toLowerCase();
+    const iconFieldUntouched = !iconInput || iconInput.value === (subject.icon ?? '');
+
+    const originalKind = subject.kind;
+    for (const f of fields) {
+        const raw = f.input.type === 'checkbox' ? String(f.input.checked) : f.input.value;
+        subject[f.key] = coerceFieldValue(raw, f);
+    }
+
+    if (!isNode) {
+        if (notation && subject.kind !== originalKind) {
+            const relationshipStyles = engine._archimateOptions?.relationshipStyles;
+            const style = relationshipStyles?.[subject.kind] ?? notation.relationshipType(subject.kind);
+            subject.lineStyle = style.lineStyle;
+            subject.arrowhead = style.arrowhead || 'none';
+            subject.arrowheadStart = style.arrowheadStart;
+        }
+        return;
+    }
+    const plan = derivedRefreshPlan({
+        layerChanged: subject.layer !== originalLayer,
+        typeChanged: subject.type !== originalType,
+        colorWasAuto, iconWasAuto, colorFieldUntouched, iconFieldUntouched,
+    });
+    if (!plan.changed) return;
+
+    const freshColor = engine._archimateLayerColor?.(subject.layer);
+    const freshIcon = subject.iconUrl ? undefined
+        : engine._archimateDefaultIcon?.(subject, subject.layer, undefined, 0, version);
+    if (plan.color) subject.color = freshColor;
+    if (plan.icon) subject.icon = freshIcon;
+    if (!plan.color || !plan.icon) {
+        const what = [!plan.color && 'colour', !plan.icon && 'icon'].filter(Boolean).join(' and ');
+        // eslint-disable-next-line no-alert
+        if (globalThis.confirm?.(`Layer/type changed to "${subject.type || subject.layer}". `
+            + `Update this element's customised ${what} to match?`)) {
+            if (!plan.color) subject.color = freshColor;
+            if (!plan.icon) subject.icon = freshIcon;
+        }
+    }
+    if (engine._archimateCornerStyle) {
+        subject.cornerStyle = engine._archimateCornerStyle(subject, subject.layer, version);
+    }
+
+    // Specialization changed -> apply the specialization's own icon/colour,
+    // but ask before overwriting a customised value.
+    if (isNode && subject.specialization !== originalSpecialization && engine.constructor.ArchimateSpecializationRegistry) {
+        const spec = engine.constructor.ArchimateSpecializationRegistry.resolve(subject.specialization);
+        if (spec) {
+            const defaultColor = engine._archimateLayerColor?.(subject.layer);
+            const defaultIcon = !subject.iconUrl
+                ? engine._archimateDefaultIcon?.(subject, subject.layer, undefined, 0, version)
+                : undefined;
+            const colorIsDefault = !subject.color
+                || String(subject.color).toLowerCase() === String(defaultColor ?? '').toLowerCase();
+            const iconIsDefault = !subject.icon && !subject.iconUrl;
+
+            if (spec.color && subject.color !== spec.color) {
+                if (colorIsDefault || globalThis.confirm?.(`Reset colour to specialization "${spec.name}" (${spec.color})?`)) {
+                    subject.color = spec.color;
+                }
+            }
+            if (spec.iconUrl && subject.iconUrl !== spec.iconUrl) {
+                if (iconIsDefault || globalThis.confirm?.(`Reset icon image to specialization "${spec.name}"?`)) {
+                    subject.iconUrl = spec.iconUrl;
+                    delete subject.icon;
+                }
+            } else if (spec.icon && subject.icon !== spec.icon && !subject.iconUrl) {
+                if (iconIsDefault || globalThis.confirm?.(`Reset icon to specialization "${spec.name}" (${spec.icon})?`)) {
+                    subject.icon = spec.icon;
+                    delete subject.iconUrl;
+                }
+            }
+        }
+    }
+}
+
+/**
+ * Settings for the diagram/view itself rather than any one object on it —
+ * what double-clicking empty canvas opens.
+ */
+export function showDiagramPropertiesDialog(engine, options = {}) {
+    try {
+        const chartOptions = engine._chartState?.options;
+        if (!chartOptions) return null;
+        // Only for an ArchiMate diagram: which of each type's own icon choices
+        // is the default. Applied live, and only to nodes that never had their
+        // icon customised.
+        const archimate = engine._archimateOptions;
+        const dialog = new FormDialog({
+            title: options.title ?? 'Diagram properties',
+            fields: [
+                {
+                    key: 'edgeRouting', label: 'edgeRouting', type: 'select', value: chartOptions.edgeRouting ?? 'straight',
+                    choices: ['straight', 'curved', 'orthogonal', 'polyline'].map(c => [c, c]),
+                },
+                ...(archimate ? [{ key: 'iconChoiceIndex', label: 'iconChoiceIndex', type: 'number', value: archimate.iconChoiceIndex ?? 0, min: 0 }] : []),
+            ],
+            submitLabel: 'Save',
+            idPrefix: 'diagram-properties-',
+            document: options.document ?? document,
+            onApply: ({ edgeRouting, iconChoiceIndex }) => {
+                chartOptions.edgeRouting = edgeRouting;
+                engine._rerenderGraph?.();
+                if (archimate && Number.isFinite(iconChoiceIndex)) ArchimateDiagram.setIconChoiceIndex(engine, iconChoiceIndex);
+                options.onSave?.(chartOptions);
+            },
+        }).open();
+        return { overlay: dialog.overlay, close: () => dialog.close() };
+    } catch (err) {
+        console.error('showDiagramPropertiesDialog failed:', err);
+        return null;
+    }
+}