@peter.prib/renderengine 0.0.0-stage → 0.2.0

package/src/charting/archimate/elementProperties.js

@@ -0,0 +1,146 @@
+import { ArchimateNotation } from '../../archimate.js';
+import { ArchimateSpecializationRegistry } from '../../archimateSpecializations.js';
+import { PropertyListEditor } from '../PropertyListEditor.js';
+import { EditViewItemCommand } from '../diagrams/EditViewItemCommand.js';
+import { FormDialog } from '../FormDialog.js';
+import { typeTitle } from './archimateNames.js';
+
+/**
+ * What a model element is, as dialog fields and an edit: its own name, type,
+ * specialization (those registered for its type, and its own), icon (its
+ * type's choices), documentation and typed properties, the same on every
+ * view. One definition for the canvas editor's shape dialog (its Element
+ * section) and the model tree's Properties….
+ *
+ * Field keys are `element.<key>`, so they sit beside other fields in one form.
+ */
+
+/**
+ * The fields for an element.
+ * @param {Object} element - A model element
+ * @param {Object} [options]
+ * @param {string} [options.version] - Whose types and icons to offer
+ * @param {Document} [options.document]
+ * @returns {Array<Object>} FormDialog fields (headings included)
+ */
+export function elementPropertyFields(element, { version = '4', document: doc = globalThis.document } = {}) {
+    return [
+        { key: 'element.name', label: 'Name', type: 'text', value: element.name ?? '' },
+        ...elementKindFields(element, { version }),
+        {
+            key: 'element.icon', label: 'Icon', type: 'select', value: element.icon ?? '',
+            choices: [['', '(the type default)'], ...[...new Set([...ArchimateNotation.iconChoices(element.type, version), element.icon].filter(Boolean))].map(i => [i, i])],
+        },
+        { key: 'element.documentation', label: 'Documentation', type: 'textarea', rows: 4, value: element.documentation ?? '' },
+        { type: 'heading', label: 'Properties' },
+        PropertyListEditor.field(element.properties, { key: 'element.properties', document: doc }),
+    ];
+}
+
+/** An element's type and specialization (those registered for its type, and its own), as fields. */
+export function elementKindFields(element, { version = '4' } = {}) {
+    const types = [...new Set([...ArchimateNotation.elementTypeNames(version), element.type].filter(Boolean))];
+    return [
+        { key: 'element.type', label: 'Type', type: 'select', value: element.type, choices: types.map(t => [t, typeTitle(t)]) },
+        {
+            key: 'element.specialization', label: 'Specialization', type: 'select', value: element.specialization ?? '',
+            choices: [['', '(none)'], ...[...new Set([...ArchimateSpecializationRegistry.forBaseType(element.type).map(s => s.name), element.specialization].filter(Boolean))].map(n => [n, n])],
+        },
+    ];
+}
+
+/**
+ * The fields for several elements edited together (see FormDialog.many):
+ * their type, their specialization when they share a type (each type has its
+ * own), and one property to give them all (set where they have it, added where
+ * they don't).
+ */
+export function manyElementsFields(elements, { version = '4' } = {}) {
+    const oneType = new Set(elements.map(e => e.type)).size === 1;
+    return [
+        { type: 'heading', label: `Elements (${elements.length}, on every view)` },
+        ...FormDialog.many(elements.map(e => elementKindFields(e, { version }).filter(f => oneType || f.key === 'element.type'))),
+        { key: 'element.property.name', label: 'Set property', type: 'text', value: '', placeholder: 'name (empty: none)' },
+        { key: 'element.property.value', label: 'To', type: 'text', value: '' },
+        ...(() => {
+            const names = [...new Set(elements.flatMap(e => (e.properties ?? []).map(p => p.name ?? p.key)).filter(Boolean))].sort();
+            return names.length ? [{ key: 'element.property.remove', label: 'Remove property', type: 'select', value: '', choices: [['', '(none)'], ...names.map(n => [n, n])] }] : [];
+        })(),
+    ];
+}
+
+/**
+ * `manyElementsFields`' values as each element's edit (fields left on Keep are
+ * undefined): EditViewItemCommands, only for the elements that change.
+ * `instanceOf(element)` is the occurrence edited with it, if any.
+ */
+export function manyElementsEditCommands(elements, values, { instanceOf = () => null } = {}) {
+    const name = String(values['element.property.name'] ?? '').trim();
+    const kind = Object.fromEntries(['element.type', 'element.specialization'].filter(k => values[k] !== undefined).map(k => [k, values[k]]));
+    return elements.map(element => {
+        const own = element.properties ?? [];
+        const property = { name, type: own.find(p => p.name === name)?.type ?? 'string', value: String(values['element.property.value'] ?? '') };
+        const remove = String(values['element.property.remove'] ?? '');
+        let list = !name ? own : own.some(p => p.name === name) ? own.map(p => (p.name === name ? property : p)) : [...own, property];
+        if (remove) list = list.filter(p => (p.name ?? p.key) !== remove);
+        const properties = list === own ? {} : { 'element.properties': list };
+        return elementEditCommand(element, { ...kind, ...properties }, { instance: instanceOf(element) });
+    }).filter(Boolean);
+}
+
+/**
+ * The changed `<prefix>.<key>` values as an edit of a concept (an element or
+ * relationship): one EditViewItemCommand, or null when nothing changed. An
+ * empty text or list is unset. `instance` is the occurrence edited with it
+ * (none from the model tree).
+ */
+export function conceptEditCommand(concept, values, { prefix, instance = null, adjust = () => {} }) {
+    const unset = (v) => v === undefined || v === null || v === '' || (Array.isArray(v) && !v.length);
+    const changes = {};
+    for (const [field, value] of Object.entries(values)) {
+        if (!field.startsWith(`${prefix}.`)) continue;
+        const key = field.slice(prefix.length + 1);
+        const before = concept[key];
+        if ((unset(before) && unset(value)) || JSON.stringify(before) === JSON.stringify(value)) continue;
+        changes[key] = unset(value) ? undefined : value;
+    }
+    if (!Object.keys(changes).length) return null;
+    adjust(changes);
+    return new EditViewItemCommand({ concept, instance }, { concept: changes, appearance: {} }, `Edit ${concept.name || concept.label || concept.id}`);
+}
+
+/** An element's edit (elementPropertyFields' values): a new type drops a stored layer, which then follows the type. */
+export function elementEditCommand(element, values, { instance = null } = {}) {
+    return conceptEditCommand(element, values, {
+        prefix: 'element', instance,
+        adjust: (changes) => { if ('type' in changes && element.layer) changes.layer = undefined; },
+    });
+}
+
+/**
+ * Edit a model element in its own dialog (from the model tree): its
+ * properties, saved as one undo step on `history`.
+ * @param {Object} element
+ * @param {Object} options
+ * @param {CommandHistory} options.history - Where the edit goes (the current view's)
+ * @param {() => void} [options.onSaved] - After a change (redraw, refresh the tree)
+ * @param {string} [options.version]
+ * @param {Document} [options.document]
+ */
+export function editElementProperties(element, { history, onSaved = () => {}, version = '4', document: doc = globalThis.document }) {
+    return new FormDialog({
+        title: `Properties: ${element.name || element.id}`,
+        description: 'The element itself: these show on every view it is on.',
+        fields: elementPropertyFields(element, { version, document: doc }),
+        submitLabel: 'Save',
+        idPrefix: 'element-props-',
+        document: doc,
+        onApply: (values) => {
+            const cmd = elementEditCommand(element, values);
+            if (!cmd) return;
+            if (history) history.execute(cmd);
+            else cmd.execute();
+            onSaved(cmd);
+        },
+    }).open();
+}

package/src/charting/archimate/elementTypeChoices.js

@@ -0,0 +1,7 @@
+import { elementTypeGroups } from './elementTypeGroups.js';
+import { typeTitle } from './archimateNames.js';
+
+/** Every element type of a version as checklist choices, grouped by layer as the palette groups them. */
+export function elementTypeChoices(version = '4') {
+    return elementTypeGroups(version).flatMap(group => group.types.map(type => [type.name, typeTitle(type.name), group.label]));
+}

package/src/charting/archimate/elementTypeGroups.js

@@ -0,0 +1,19 @@
+import { ArchimateNotation } from '../../archimate.js';
+import { typeTitle } from './archimateNames.js';
+
+/**
+ * The element types of a version, grouped as people look for them: each layer
+ * that has types (the notation's order), then ArchiMate 4's common behaviour
+ * types (no layer of their own). The palette's groups, and the type lists of
+ * the specialization and viewpoint dialogs.
+ * @returns {Array<{key: string, label: string, types: ArchimateElementType[]}>}
+ */
+export function elementTypeGroups(version = '4') {
+    const groups = ArchimateNotation.layers()
+        .map(layer => ({ key: layer.name, label: typeTitle(layer.name), types: ArchimateNotation.typesInLayer(layer.name, version) }))
+        .filter(g => g.types.length);
+    const grouped = new Set(groups.flatMap(g => g.types.map(t => t.name)));
+    const common = ArchimateNotation.elementTypeNames(version).filter(n => !grouped.has(n)).map(n => ArchimateNotation.elementType(n, version));
+    if (common.length) groups.push({ key: 'common', label: 'Common behaviour', types: common });
+    return groups;
+}

package/src/charting/archimate/index.js

@@ -0,0 +1,17 @@
+export { ArchimateElementTemplate } from './ArchimateElementTemplate.js';
+export { ArchimateEdge } from './ArchimateEdge.js';
+export { ViewLineEdge } from './ViewLineEdge.js';
+export { ArchimateCanvasEditor, ARCHIMATE_TYPE_MIME, KIND_PREFERENCE, typeTitle } from './ArchimateCanvasEditor.js';
+export { ArchimatePalette } from './ArchimatePalette.js';
+export { ArchiFileFormat } from './ArchiFileFormat.js';
+export { ExchangeFileFormat } from './ExchangeFileFormat.js';
+export { ArchimateCsvFileFormat } from './ArchimateCsvFileFormat.js';
+export { ARCHIMATE_FILE_FORMATS } from './archimateFileFormats.js';
+export { DrawioFileFormat } from './DrawioFileFormat.js';
+export { ViewpointRule } from './ViewpointRule.js';
+export { ElementFilterRule } from './ElementFilterRule.js';
+export { DerivedEdge } from './DerivedEdge.js';
+export { ViewGroupTemplate, GROUP_FILL } from './ViewGroupTemplate.js';
+export { CustomViewpoints, CUSTOM_VIEWPOINTS_STORE } from './CustomViewpoints.js';
+export { specializationCatalogDialog } from './specializationCatalogDialog.js';
+export { elementTypeChoices } from './elementTypeChoices.js';

package/src/charting/archimate/specializationCatalogDialog.js

@@ -0,0 +1,64 @@
+import { CatalogDialog } from '../CatalogDialog.js';
+import { ArchimateSpecializationRegistry, SPECIALIZATIONS_STORE } from '../../archimateSpecializations.js';
+import { elementTypeChoices } from './elementTypeChoices.js';
+
+/**
+ * Edit the specialization catalog (ArchimateSpecializationRegistry): name,
+ * the element types it applies to, its icon, colour and description. Every
+ * change is saved to `store` (this browser's catalog), which both editors
+ * load.
+ * @param {Object} [options]
+ * @param {string} [options.version] - Whose element types to offer
+ * @param {LocalJsonStore} [options.store]
+ * @param {() => void} [options.onChange] - After a change (redraw)
+ * @param {Document} [options.document]
+ * @returns {CatalogDialog}
+ */
+export function specializationCatalogDialog({ version = '4', store = SPECIALIZATIONS_STORE, onChange = () => {}, document: doc = globalThis.document } = {}) {
+    const R = ArchimateSpecializationRegistry;
+    const keep = () => store.save(R.serialize());
+    return new CatalogDialog({
+        title: 'Specializations',
+        description: 'Kinds of element of your own (a Firewall is a Node): their icon and colour show on every element given one.',
+        noun: 'specialization',
+        items: () => R.list().sort((a, b) => a.name.localeCompare(b.name)),
+        label: (spec) => `${spec.icon ? `${spec.icon} ` : ''}${spec.name}`,
+        fields: (spec) => [
+            { key: 'name', label: 'Name', type: 'text', value: spec?.name ?? '' },
+            { key: 'icon', label: 'Icon', type: 'text', value: spec?.icon ?? '', hint: 'An emoji or a short text, drawn in the corner' },
+            { key: 'color', label: 'Colour', type: 'color', value: spec?.color ?? '' },
+            { key: 'description', label: 'Description', type: 'textarea', rows: 2, value: spec?.description ?? '' },
+            { key: 'baseTypes', label: 'For types', type: 'checklist', value: spec?.baseTypes ?? [], choices: elementTypeChoices(version), hint: 'None chosen: every type' },
+        ],
+        validate: (spec, { name }) => {
+            const wanted = String(name ?? '').trim();
+            if (!wanted) return 'A specialization needs a name.';
+            const other = R.resolve(wanted);
+            if (other && other.id !== spec?.id) return `There is already a specialization called "${wanted}".`;
+            return null;
+        },
+        save: (spec, { name, icon, color, description, baseTypes }) => {
+            R.register({
+                id: spec?.id ?? uniqueId(name.trim(), (id) => !!R.get(id)),
+                name: name.trim(),
+                baseTypes,
+                icon: icon?.trim() || undefined,
+                iconUrl: spec?.iconUrl,
+                color: color && color !== 'none' ? color : undefined,
+                description: description?.trim() || undefined,
+            });
+            keep();
+        },
+        remove: (spec) => { R.unregister(spec.id); keep(); },
+        onChange,
+        document: doc,
+    });
+}
+
+/** An id made from a name, not yet `taken`. */
+export function uniqueId(name, taken) {
+    const base = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'item';
+    let id = base;
+    for (let n = 2; taken(id); n++) id = `${base}-${n}`;
+    return id;
+}

package/src/charting/archimate/typeGlyph.js

@@ -0,0 +1,29 @@
+import { ArchimateDiagram } from '../diagrams/ArchimateDiagram.js';
+import { ArchimateNotation } from '../../archimate.js';
+import { Glyph } from '../glyphs/Glyph.js';
+import { glyphFor } from '../glyphs/index.js';
+import { glyphToSvg } from '../glyphs/glyphSvg.js';
+import { svgEl } from '../templates/svg.js';
+
+/**
+ * A small picture of an element type: its notation glyph in its layer
+ * colour, as an <svg> (a type of the other ArchiMate version as that version draws it). One drawing for every place a type is shown small:
+ * the palette's tiles and the model tree's elements and type folders.
+ * @param {string} typeName - An element type ('business-actor', ...)
+ * @param {Object} [options]
+ * @param {number} [options.size] - Its height in pixels (it is 1.4 times as wide)
+ * @param {string} [options.version] - ArchiMate version
+ * @param {Document} [options.document]
+ * @returns {SVGElement}
+ */
+export function typeGlyph(typeName, { size = 22, version = '4', document: doc = globalThis.document } = {}) {
+    // A type of the other version (3.2's business-process under 4) is drawn as that version draws it.
+    const own = ArchimateNotation.elementType(typeName, version) ? version : (ArchimateNotation.elementType(typeName, '3.2') ? '3.2' : version);
+    const type = ArchimateNotation.elementType(typeName, own);
+    const node = ArchimateDiagram.buildNode({ id: typeName, name: '', type: typeName }, { archimateVersion: own });
+    const glyph = glyphFor(type?.notationShape ?? 'rect');
+    const ctx = Glyph.context({ R: size / 2, size: { w: size * 1.3, h: size }, color: node.color, cornerStyle: node.cornerStyle, strokeColor: '#333', strokeWidth: 1 });
+    const svg = svgEl('svg', { width: size * 1.4, height: size + 4, viewBox: `${-size * 0.7} ${-size / 2 - 2} ${size * 1.4} ${size + 4}` }, doc);
+    svg.appendChild(glyphToSvg(glyph.parts(ctx), doc));
+    return svg;
+}

package/src/charting/arrangement/Arrangement.js

@@ -0,0 +1,112 @@
+import { ItemGroup } from './ItemGroup.js';
+import './BackgroundGroup.js';   // registers its kind, so fromJSON makes it
+
+/**
+ * Arrangement — how the items on one view hold together: which are grouped
+ * (an ItemGroup moves as one) and which are locked (fixed in place: not moved,
+ * resized or rotated). An item or a whole group can be locked; a locked group
+ * locks every member. Items are known by id only, so the same arrangement
+ * serves a template diagram's templates and an ArchiMate view's instances.
+ *
+ * A group may be pinned to the back (a BackgroundGroup, what a canvas takes
+ * from its template): its members stack behind every other item.
+ *
+ * Change it through the commands (GroupCommand, UngroupCommand, LockCommand,
+ * BackgroundCommand), so each change is one undo step on the view's history.
+ */
+export class Arrangement {
+    /**
+     * @param {Object} [spec]
+     * @param {Array<ItemGroup|Object>} [spec.groups]
+     * @param {Iterable<string>} [spec.locked] - Ids of locked items and groups
+     */
+    constructor({ groups = [], locked = [] } = {}) {
+        /** @type {Map<string, ItemGroup>} */
+        this.groups = new Map(groups.map(g => {
+            const group = g instanceof ItemGroup ? g : ItemGroup.fromJSON(g);
+            return [group.id, group];
+        }));
+        /** @type {Set<string>} ids of locked items and groups */
+        this.locked = new Set(locked);
+    }
+
+    /** The group an item belongs to, or null. */
+    groupOf(itemId) {
+        for (const group of this.groups.values()) if (group.has(itemId)) return group;
+        return null;
+    }
+
+    /** The ids that move when `itemId` moves: its group's members, or itself. */
+    movingWith(itemId) {
+        const group = this.groupOf(itemId);
+        return group ? new Set(group.memberIds) : new Set([itemId]);
+    }
+
+    /** Everything that moves when these items move, groups included. */
+    movers(itemIds) {
+        const all = new Set();
+        for (const id of itemIds) for (const m of this.movingWith(id)) all.add(m);
+        return all;
+    }
+
+    /** Whether an item is fixed in place: locked itself, or in a locked group. */
+    isLocked(itemId) {
+        if (this.locked.has(itemId)) return true;
+        const group = this.groupOf(itemId);
+        return !!group && this.locked.has(group.id);
+    }
+
+    /** Whether these items (with their groups) may move: none of them is locked. */
+    canMove(itemIds) {
+        return [...this.movers(itemIds)].every(id => !this.isLocked(id));
+    }
+
+    /** Whether an item stays behind every item not pinned (it is in a BackgroundGroup). */
+    isPinnedToBack(itemId) {
+        return !!this.groupOf(itemId)?.pinnedToBack;
+    }
+
+    /** What locking `itemId` locks: its group if it has one, else the item. */
+    lockTargetOf(itemId) {
+        return this.groupOf(itemId)?.id ?? itemId;
+    }
+
+    /**
+     * The arrangement of some of the items only (what a part of a view takes
+     * with it): groups keep the members among them (a group left with none
+     * goes), and their locks.
+     * @param {Iterable<string>} itemIds
+     * @returns {Arrangement}
+     */
+    only(itemIds) {
+        const keep = new Set(itemIds);
+        const groups = [...this.groups.values()]
+            .map(g => g.withMembers([...g.memberIds].filter(id => keep.has(id))))
+            .filter(g => g.memberIds.size > 0);
+        const groupIds = new Set(groups.map(g => g.id));
+        return new Arrangement({ groups, locked: [...this.locked].filter(id => keep.has(id) || groupIds.has(id)) });
+    }
+
+    /** A copy with item ids mapped (for a copied view whose items have new ids). */
+    copy(mapId = (id) => id) {
+        return new Arrangement({
+            groups: [...this.groups.values()].map(g => g.withMembers([...g.memberIds].map(mapId))),
+            locked: [...this.locked].map(id => (this.groups.has(id) ? id : mapId(id))),
+        });
+    }
+
+    toJSON() {
+        return { groups: [...this.groups.values()].map(g => g.toJSON()), locked: [...this.locked] };
+    }
+
+    static fromJSON(data) {
+        return new Arrangement(data ?? {});
+    }
+
+    /** Replace this arrangement's state with a snapshot (toJSON). Used by undo. @protected */
+    restore(snapshot) {
+        const again = Arrangement.fromJSON(snapshot);
+        this.groups = again.groups;
+        this.locked = again.locked;
+    }
+}

package/src/charting/arrangement/ArrangementCommand.js

@@ -0,0 +1,29 @@
+import { Command } from '../CommandHistory.js';
+
+/**
+ * ArrangementCommand — one undoable change to an Arrangement. Undo puts back
+ * the arrangement exactly as it was (a snapshot taken when first applied);
+ * redo applies the change again. Subclasses implement apply().
+ */
+export class ArrangementCommand extends Command {
+    constructor(arrangement, label) {
+        super(label);
+        if (new.target === ArrangementCommand) throw new TypeError('ArrangementCommand is abstract — subclass it');
+        this.arrangement = arrangement;
+        this._before = null;
+    }
+
+    execute() {
+        this._before ??= this.arrangement.toJSON();
+        this.apply();
+    }
+
+    undo() {
+        this.arrangement.restore(this._before);
+    }
+
+    /** Change the arrangement. @abstract */
+    apply() {
+        throw new Error(`${this.constructor.name} must implement apply()`);
+    }
+}

package/src/charting/arrangement/BackgroundCommand.js

@@ -0,0 +1,41 @@
+import { ArrangementCommand } from './ArrangementCommand.js';
+import { BackgroundGroup } from './BackgroundGroup.js';
+
+let nextBackground = 1;
+
+/**
+ * BackgroundCommand — make items the view's background: one BackgroundGroup
+ * (their old groups dissolved into it), locked. Their stacking is the view's
+ * to settle (DiagramEditorState#arrangeAsBackground puts them behind).
+ */
+export class BackgroundCommand extends ArrangementCommand {
+    /**
+     * @param {Arrangement} arrangement
+     * @param {Iterable<string>} itemIds
+     * @param {Object} [options]
+     * @param {string} [options.id] - The group's id (default: generated)
+     * @param {string} [options.name]
+     * @param {boolean} [options.locked] - Lock it (default true)
+     */
+    constructor(arrangement, itemIds, { id = `background-${Date.now().toString(36)}-${nextBackground++}`, name = 'Background', locked = true } = {}) {
+        super(arrangement, 'Make background');
+        this.itemIds = [...itemIds];
+        this.groupId = id;
+        this.name = name;
+        this.lockedValue = locked;
+    }
+
+    apply() {
+        const arrangement = this.arrangement;
+        const members = arrangement.movers(this.itemIds);
+        for (const id of this.itemIds) {
+            const old = arrangement.groupOf(id);
+            if (!old) continue;
+            arrangement.locked.delete(old.id);
+            arrangement.groups.delete(old.id);
+        }
+        for (const id of members) arrangement.locked.delete(id);
+        arrangement.groups.set(this.groupId, new BackgroundGroup({ id: this.groupId, name: this.name, memberIds: members }));
+        if (this.lockedValue) arrangement.locked.add(this.groupId);
+    }
+}

package/src/charting/arrangement/BackgroundGroup.js

@@ -0,0 +1,18 @@
+import { ItemGroup } from './ItemGroup.js';
+
+/**
+ * BackgroundGroup — a group pinned behind everything else on its view: what a
+ * canvas takes from its template. Its members always stack below every other
+ * item, whatever is sent to the back; it is made locked (BackgroundCommand),
+ * so it is neither moved nor changed until unlocked. Unlocked, it moves as
+ * one like any group; ungrouped, its items are ordinary items again.
+ */
+export class BackgroundGroup extends ItemGroup {
+    static kind = 'background';
+
+    get pinnedToBack() {
+        return true;
+    }
+}
+
+ItemGroup.register(BackgroundGroup);

package/src/charting/arrangement/GroupCommand.js

@@ -0,0 +1,46 @@
+import { ArrangementCommand } from './ArrangementCommand.js';
+import { ItemGroup } from './ItemGroup.js';
+
+let nextGroup = 1;
+
+/**
+ * GroupCommand — group items so they move as one. Groups do not nest: an item
+ * already in a group brings its whole group into the new one, and the old
+ * group goes. A locked group's lock passes to the new group, and so does a
+ * background group's kind (the new group is pinned to the back too).
+ */
+export class GroupCommand extends ArrangementCommand {
+    /**
+     * @param {Arrangement} arrangement
+     * @param {Iterable<string>} itemIds - At least two items (with their groups)
+     * @param {Object} [options]
+     * @param {string} [options.id] - The new group's id (default: generated)
+     * @param {string} [options.name]
+     */
+    constructor(arrangement, itemIds, { id = `group-${Date.now().toString(36)}-${nextGroup++}`, name = '' } = {}) {
+        super(arrangement, 'Group');
+        this.itemIds = [...itemIds];
+        this.groupId = id;
+        this.name = name;
+    }
+
+    apply() {
+        const arrangement = this.arrangement;
+        const members = arrangement.movers(this.itemIds);
+        let locked = false;
+        let kindOf = null;
+        for (const id of this.itemIds) {
+            const old = arrangement.groupOf(id);
+            if (!old) continue;
+            locked ||= arrangement.locked.has(old.id);
+            if (old.pinnedToBack) kindOf = old;
+            arrangement.locked.delete(old.id);
+            arrangement.groups.delete(old.id);
+        }
+        const group = kindOf
+            ? new kindOf.constructor({ id: this.groupId, name: this.name || kindOf.name, memberIds: members })
+            : new ItemGroup({ id: this.groupId, name: this.name, memberIds: members });
+        arrangement.groups.set(this.groupId, group);
+        if (locked) arrangement.locked.add(this.groupId);
+    }
+}

package/src/charting/arrangement/ItemGroup.js

@@ -0,0 +1,62 @@
+/**
+ * ItemGroup — items on a view grouped logically: they move as one. It draws
+ * nothing of its own (not a container); a dashed outline shows it while one of
+ * its members is selected.
+ *
+ * A kind of group is a subclass (BackgroundGroup: pinned behind everything);
+ * each names its `kind`, which its JSON carries, and registers itself so
+ * `ItemGroup.fromJSON` makes the right class.
+ */
+export class ItemGroup {
+    /** The kind of group, as its JSON names it. */
+    static kind = 'group';
+
+    /** Group classes by kind (see register). */
+    static TYPES = new Map();
+
+    /** Make `GroupClass` the class for its `kind` when read from JSON. */
+    static register(GroupClass) {
+        ItemGroup.TYPES.set(GroupClass.kind, GroupClass);
+    }
+
+    /**
+     * @param {Object} spec
+     * @param {string} spec.id
+     * @param {Iterable<string>} spec.memberIds - Ids of the items in the group
+     * @param {string} [spec.name]
+     */
+    constructor({ id, memberIds, name = '' }) {
+        if (!id) throw new TypeError('ItemGroup needs an id');
+        this.id = id;
+        this.name = name;
+        /** @type {Set<string>} */
+        this.memberIds = new Set(memberIds);
+    }
+
+    /** Whether its members stay behind every other item (a BackgroundGroup's do). */
+    get pinnedToBack() {
+        return false;
+    }
+
+    has(itemId) {
+        return this.memberIds.has(itemId);
+    }
+
+    /** The same kind of group, with other members (a copied view's, say). */
+    withMembers(memberIds) {
+        return new this.constructor({ id: this.id, name: this.name, memberIds });
+    }
+
+    toJSON() {
+        const kind = this.constructor.kind;
+        return { id: this.id, ...(kind !== ItemGroup.kind && { kind }), ...(this.name && { name: this.name }), memberIds: [...this.memberIds] };
+    }
+
+    /** The group its JSON describes, of the class registered for its `kind`. */
+    static fromJSON(data) {
+        const GroupClass = ItemGroup.TYPES.get(data.kind) ?? ItemGroup;
+        return new GroupClass(data);
+    }
+}
+
+ItemGroup.register(ItemGroup);

package/src/charting/arrangement/LockCommand.js

@@ -0,0 +1,32 @@
+import { ArrangementCommand } from './ArrangementCommand.js';
+
+/**
+ * LockCommand — fix items in place, or free them. An item in a group locks or
+ * frees its whole group. Freeing also frees any member locked on its own, so
+ * after "Unlock" the group moves.
+ */
+export class LockCommand extends ArrangementCommand {
+    /**
+     * @param {Arrangement} arrangement
+     * @param {Iterable<string>} itemIds
+     * @param {boolean} locked - true to fix in place, false to free
+     */
+    constructor(arrangement, itemIds, locked) {
+        super(arrangement, locked ? 'Lock' : 'Unlock');
+        this.itemIds = [...itemIds];
+        this.lockedValue = !!locked;
+    }
+
+    apply() {
+        const arrangement = this.arrangement;
+        for (const id of this.itemIds) {
+            const target = arrangement.lockTargetOf(id);
+            if (this.lockedValue) {
+                arrangement.locked.add(target);
+            } else {
+                arrangement.locked.delete(target);
+                for (const member of arrangement.movingWith(id)) arrangement.locked.delete(member);
+            }
+        }
+    }
+}

package/src/charting/arrangement/UngroupCommand.js

@@ -0,0 +1,27 @@
+import { ArrangementCommand } from './ArrangementCommand.js';
+
+/**
+ * UngroupCommand — dissolve the group an item is in: its members move on
+ * their own again. A locked group's lock passes to each member, so nothing
+ * that was fixed comes loose.
+ */
+export class UngroupCommand extends ArrangementCommand {
+    /**
+     * @param {Arrangement} arrangement
+     * @param {string} itemId - A member of the group (or the group's id)
+     */
+    constructor(arrangement, itemId) {
+        super(arrangement, 'Ungroup');
+        this.itemId = itemId;
+    }
+
+    apply() {
+        const arrangement = this.arrangement;
+        const group = arrangement.groups.get(this.itemId) ?? arrangement.groupOf(this.itemId);
+        if (!group) return;
+        if (arrangement.locked.delete(group.id)) {
+            for (const id of group.memberIds) arrangement.locked.add(id);
+        }
+        arrangement.groups.delete(group.id);
+    }
+}