@peter.prib/renderengine 0.2.7 → 0.2.11

package/src/charting/FormDialog.js

@@ -1,385 +1,398 @@
-import { el } from '../workspace/dom.js';
-import { ColorField } from './ColorField.js';
-
-const INHERIT = '__inherit__';
-
-/**
- * FormDialog — the one modal form, built from field descriptions, so every
- * editor dialog shares one layout, keyboard handling and value reading.
- *
- * Field: `{ key, label, type, value?, choices?, min?, max?, step?, rows?, placeholder?,
- *           suggestions?, accept?, hint?, readOnly?, allowEmpty?, inherit?, element?, read? }`
- * - type: 'text' | 'textarea' | 'number' | 'color' | 'select' | 'checkbox' | 'checklist' | 'file' | 'custom'
- *   | 'heading' (a section title; no value)
- * - checklist: a box per choice, `choices` `[[value, text, group?], ...]` (grouped under their group's
- *   name), `value` the chosen values; reads as the chosen values, in choice order
- * - choices (select): `[[value, text], ...]`. A current value that is not a
- *   choice is kept as its own option (never silently blanked); `allowEmpty`
- *   adds a "(none)" option for an empty value.
- * - suggestions (text): values offered as you type (a datalist). The box empties
- *   on focus so every suggestion shows, and restores its value if left empty.
- * - readOnly: shown but not editable, and not read back
- * - accept (file): file types; reads as the chosen File or null
- * - custom: `element` (a Node to place) and `read()` (its value)
- * - color: a ColorField (the value as text, `#rrggbb` or `none`, a picker and preset
- *   swatches); `presets` (`[{value, name}]`) replaces ColorField.PRESETS, and
- *   `allowNone: false` leaves out "No colour"
- * - hint: small explanatory text under the field
- * - inherit: `{ text, short?, value }` — the field may be left unset. Selects get
- *   a first option labelled `text`; other types (checkboxes too) get an "Inherit"
- *   checkbox (`short` renames it) that greys the control out showing `value`. An
- *   inherited field reads as `undefined`. `FormDialog.many` uses it for a form
- *   that edits several items at once.
- *
- * The dialog fits the window: its fields scroll between the title and the
- * buttons, which stay in view, and it moves by dragging its title. A textarea
- * scrolls inside its own box and can be resized taller.
- *
- * `validate(values)` may return a message to show inline instead of closing.
- * After open(), `controls[key]` is each field's control, for wiring fields that
- * depend on one another.
- */
-export class FormDialog {
-    /**
-     * @param {Object} options
-     * @param {string} options.title
-     * @param {string} [options.description] - Text under the title
-     * @param {Array<Object>} options.fields
-     * @param {(values: Object) => void} options.onApply
-     * @param {(values: Object) => (string|null|undefined)} [options.validate]
-     * @param {string} [options.submitLabel]
-     * @param {string} [options.cancelLabel]
-     * @param {string} [options.idPrefix] - Field element ids are `${idPrefix}${key}`
-     * @param {Document} [options.document]
-     * @param {(applied: boolean) => void} [options.onClose] - Once, when the dialog closes: whether it was
-     *   applied (false for Cancel, Escape or a click outside)
-     */
-    constructor({ title, description, fields, onApply, validate, submitLabel = 'Apply', cancelLabel = 'Cancel', idPrefix = 'form-dialog-', document: doc = document, onClose = null }) {
-        this.title = title;
-        this.description = description;
-        this.fields = fields;
-        this.onApply = onApply;
-        this.validate = validate;
-        this.submitLabel = submitLabel;
-        this.cancelLabel = cancelLabel;
-        this.idPrefix = idPrefix;
-        this.doc = doc;
-        this.onClose = onClose;
-        this._applied = false;
-        this.overlay = null;
-        /** @type {Object<string, HTMLElement>} */
-        this.controls = {};
-        this._readers = [];
-        this._error = null;
-    }
-
-    open() {
-        this._readers = [];
-        this.controls = {};
-        const rows = this.fields.map(f => this._row(f));
-        this.overlay = el({
-            style: {
-                position: 'fixed', inset: '0', background: 'rgba(0,0,0,0.25)', zIndex: '10001',
-                display: 'flex', alignItems: 'center', justifyContent: 'center', fontFamily: 'sans-serif',
-            },
-            on: { mousedown: (e) => { if (e.target === this.overlay) this.close(); } },
-            children: [{
-                tag: 'form',
-                attrs: { role: 'dialog', 'aria-label': this.title },
-                style: {
-                    background: '#fff', color: '#222', border: '1px solid #bbb', borderRadius: '6px', padding: '16px 18px',
-                    minWidth: '360px', maxWidth: '90vw', maxHeight: '90vh', boxSizing: 'border-box',
-                    display: 'flex', flexDirection: 'column',
-                    boxShadow: '0 6px 24px rgba(0,0,0,0.2)', fontSize: '12px',
-                },
-                ref: (n) => { this.form = n; },
-                on: {
-                    submit: (e) => { e.preventDefault(); this._apply(); },
-                    keydown: (e) => { if (e.key === 'Escape') this.close(); },
-                },
-                children: [
-                    {
-                        // The title is the handle that moves the dialog.
-                        tag: 'h3', text: this.title, attrs: { title: 'Drag to move' },
-                        style: { margin: '0 0 8px', fontSize: '14px', cursor: 'move', userSelect: 'none', flex: '0 0 auto' },
-                        on: { mousedown: (e) => this._startMove(e) },
-                    },
-                    {
-                        // The fields scroll; the title and the buttons stay in view.
-                        style: { overflowY: 'auto', flex: '1 1 auto', minHeight: '0', paddingRight: '4px' },
-                        ref: (n) => { this.body = n; },
-                        children: [
-                            this.description && { text: this.description, style: { fontSize: '11px', color: '#666', margin: '0 0 10px', whiteSpace: 'pre-line' } },
-                            { style: { display: 'grid', gridTemplateColumns: 'auto 1fr', gap: '8px 12px', alignItems: 'center' }, children: rows.flat() },
-                            { attrs: { role: 'alert' }, style: { color: '#c0392b', fontSize: '12px', marginTop: '8px', display: 'none' }, ref: (n) => { this._error = n; } },
-                        ].filter(Boolean),
-                    },
-                    {
-                        style: { display: 'flex', justifyContent: 'flex-end', gap: '8px', marginTop: '16px', flex: '0 0 auto' },
-                        children: [
-                            { tag: 'button', attrs: { type: 'button' }, text: this.cancelLabel, on: { click: () => this.close() } },
-                            {
-                                tag: 'button', attrs: { type: 'submit' }, text: this.submitLabel,
-                                style: { background: '#0066cc', color: '#fff', border: '1px solid #0066cc', borderRadius: '3px', padding: '4px 14px' },
-                            },
-                        ],
-                    },
-                ].filter(Boolean),
-            }],
-        }, this.doc);
-        this.doc.body.appendChild(this.overlay);
-        this.overlay.querySelector('input:not([type=checkbox]), select, textarea')?.focus();
-        return this;
-    }
-
-    /**
-     * Move the dialog by its title: from then on it sits where it was dropped
-     * (fixed position), kept inside the window.
-     * @protected
-     */
-    _startMove(e) {
-        if (e.button !== 0 || !this.form) return;
-        e.preventDefault();
-        const view = this.doc.defaultView;
-        const box = this.form.getBoundingClientRect();
-        const grab = { x: e.clientX - box.left, y: e.clientY - box.top };
-        Object.assign(this.form.style, { position: 'fixed', margin: '0', left: `${box.left}px`, top: `${box.top}px` });
-        const move = (ev) => {
-            const width = view?.innerWidth ?? Infinity, height = view?.innerHeight ?? Infinity;
-            const left = Math.min(Math.max(0, ev.clientX - grab.x), Math.max(0, width - box.width));
-            const top = Math.min(Math.max(0, ev.clientY - grab.y), Math.max(0, height - 40));
-            this.form.style.left = `${left}px`;
-            this.form.style.top = `${top}px`;
-        };
-        const end = () => {
-            this.doc.removeEventListener('mousemove', move);
-            this.doc.removeEventListener('mouseup', end);
-        };
-        this.doc.addEventListener('mousemove', move);
-        this.doc.addEventListener('mouseup', end);
-    }
-
-    close() {
-        if (!this.overlay) return;
-        this.overlay.remove();
-        this.overlay = null;
-        this.onClose?.(this._applied);
-    }
-
-    values() {
-        return Object.fromEntries(this._readers.map(read => read()));
-    }
-
-    _apply() {
-        const values = this.values();
-        const problem = this.validate?.(values);
-        if (problem) {
-            this._error.textContent = problem;
-            this._error.style.display = 'block';
-            return;
-        }
-        this._applied = true;
-        this.close();
-        this.onApply(values);
-    }
-
-    _id(f) {
-        return `${this.idPrefix}${f.key}`;
-    }
-
-    _keep(f) {
-        return (n) => { this.controls[f.key] = n; };
-    }
-
-    _row(f) {
-        if (f.type === 'heading') {
-            return [{
-                text: f.label, style: {
-                    gridColumn: '1 / -1', fontSize: '11px', fontWeight: 'bold', textTransform: 'uppercase',
-                    color: '#999', letterSpacing: '0.04em', marginTop: '6px',
-                },
-            }];
-        }
-        const label = { tag: 'label', text: f.label, attrs: { for: this._id(f) }, style: { color: '#333' } };
-        let control;
-        if (f.type === 'select') control = this._select(f);
-        else if (f.type === 'checkbox') control = this._checkbox(f);
-        else if (f.type === 'checklist') control = this._checklist(f);
-        else if (f.type === 'custom') control = this._custom(f);
-        else control = f.inherit ? this._inheritableInput(f) : this._input(f);
-        // No label: the control takes the whole row (e.g. an editable list).
-        const row = f.label ? [label, control] : [{ style: { gridColumn: '1 / -1' }, children: [control] }];
-        if (f.hint) row.push({}, { text: f.hint, style: { fontSize: '11px', color: '#888', marginTop: '-4px' } });
-        return row;
-    }
-
-    _select(f) {
-        let select;
-        if (!f.readOnly) this._readers.push(() => [f.key, select.value === INHERIT ? undefined : select.value]);
-        const unset = f.inherit && f.value === undefined;
-        const current = f.value == null ? '' : String(f.value);
-        const known = f.choices.some(([v]) => v === current);
-        const extra = unset ? []
-            : current && !known ? [[current, current]]
-                : !current && f.allowEmpty ? [['', '(none)']]
-                    : [];
-        return {
-            tag: 'select', attrs: { id: this._id(f), disabled: !!f.readOnly }, ref: (n) => { select = n; this._keep(f)(n); },
-            children: [
-                ...(f.inherit ? [{ tag: 'option', attrs: { value: INHERIT, selected: unset }, text: f.inherit.text }] : []),
-                ...[...extra, ...f.choices].map(([v, text]) => ({ tag: 'option', attrs: { value: v, selected: !unset && v === current }, text })),
-            ],
-        };
-    }
-
-    _checkbox(f) {
-        if (f.inherit) return this._inheritableInput(f);
-        let box;
-        if (!f.readOnly) this._readers.push(() => [f.key, box.checked]);
-        return {
-            tag: 'input', attrs: { id: this._id(f), type: 'checkbox', checked: !!f.value, disabled: !!f.readOnly }, style: { justifySelf: 'start' },
-            ref: (n) => { box = n; this._keep(f)(n); },
-        };
-    }
-
-    _checklist(f) {
-        const boxes = [];
-        const chosen = new Set(f.value ?? []);
-        if (!f.readOnly) this._readers.push(() => [f.key, boxes.filter(b => b.checked).map(b => b.value)]);
-        const groups = new Map();
-        for (const [value, text, group = ''] of f.choices) {
-            if (!groups.has(group)) groups.set(group, []);
-            groups.get(group).push([value, text]);
-        }
-        return {
-            attrs: { id: this._id(f) }, ref: this._keep(f),
-            style: { maxHeight: '220px', overflowY: 'auto', border: '1px solid #ccc', borderRadius: '3px', padding: '4px 8px', background: '#fff' },
-            children: [...groups].map(([group, items]) => ({
-                children: [
-                    ...(group ? [{ text: group, style: { fontSize: '11px', fontWeight: 'bold', color: '#777', marginTop: '4px' } }] : []),
-                    ...items.map(([value, text]) => ({
-                        tag: 'label', style: { display: 'block', whiteSpace: 'nowrap' },
-                        children: [
-                            { tag: 'input', attrs: { type: 'checkbox', value, checked: chosen.has(value), disabled: !!f.readOnly }, ref: (n) => boxes.push(n) },
-                            ` ${text}`,
-                        ],
-                    })),
-                ],
-            })),
-        };
-    }
-
-    _custom(f) {
-        this._readers.push(() => [f.key, f.read()]);
-        if (f.element && !f.element.id) f.element.id = this._id(f);
-        this.controls[f.key] = f.element;
-        return f.element;
-    }
-
-    _controlSpec(f, ref) {
-        const keep = (n) => { ref(n); this._keep(f)(n); };
-        const readOnlyStyle = f.readOnly ? { background: '#f2f2f2', color: '#888' } : {};
-        if (f.type === 'textarea') {
-            return {
-                tag: 'textarea', attrs: { id: this._id(f), rows: f.rows ?? 4, placeholder: f.placeholder, readonly: !!f.readOnly },
-                text: f.value ?? '',
-                // Long text scrolls inside the box, which can be dragged taller.
-                style: { width: '100%', minWidth: '260px', boxSizing: 'border-box', maxHeight: '40vh', overflowY: 'auto', resize: 'vertical', ...readOnlyStyle },
-                ref: keep,
-            };
-        }
-        // A colour: its value as text (#rrggbb or none), a picker and preset swatches.
-        if (f.type === 'color') return ColorField.spec(f, { id: this._id(f), ref: keep, style: readOnlyStyle });
-        const value = f.type === 'file' ? null : (f.value == null ? '' : (Array.isArray(f.value) ? JSON.stringify(f.value) : String(f.value)));
-        const listId = f.suggestions ? `${this._id(f)}-suggestions` : null;
-        const input = {
-            tag: 'input',
-            attrs: {
-                id: this._id(f), type: f.type ?? 'text', value,
-                min: f.min, max: f.max, step: f.step, placeholder: f.placeholder, accept: f.accept, list: listId,
-                readonly: !!f.readOnly,
-            },
-            style: { ...(f.type === 'number' ? { width: '70px' } : { width: '100%', boxSizing: 'border-box' }), ...readOnlyStyle },
-            on: f.suggestions ? {
-                // A datalist filters against the text already typed, so an existing
-                // value can look like the only option. Emptying on focus shows them all.
-                focus: (e) => { e.target.dataset.prevValue = e.target.value; e.target.value = ''; },
-                blur: (e) => { if (e.target.value === '' && e.target.dataset.prevValue) e.target.value = e.target.dataset.prevValue; },
-            } : undefined,
-            ref: keep,
-        };
-        if (!listId) return input;
-        return {
-            children: [input, { tag: 'datalist', attrs: { id: listId }, children: f.suggestions.map(v => ({ tag: 'option', attrs: { value: v } })) }],
-        };
-    }
-
-    _read(f, input) {
-        if (f.type === 'file') return input.files?.[0] ?? null;
-        if (f.type === 'checkbox') return input.checked;
-        return f.type === 'number' ? Number(input.value) : input.value;
-    }
-
-    _input(f) {
-        let input;
-        if (!f.readOnly) this._readers.push(() => [f.key, this._read(f, input)]);
-        return this._controlSpec(f, (n) => { input = n; });
-    }
-
-    /** The control plus an "Inherit" checkbox that greys it out showing the inherited value. */
-    _inheritableInput(f) {
-        let input, inherit;
-        const sync = () => {
-            input.disabled = inherit.checked;
-            if (inherit.checked && f.type === 'checkbox') input.checked = !!f.inherit.value;
-            else if (inherit.checked) input.value = f.inherit.value;
-        };
-        this._readers.push(() => [f.key, inherit.checked ? undefined : this._read(f, input)]);
-        return {
-            style: { display: 'flex', alignItems: 'center', gap: '10px' },
-            children: [
-                f.type === 'checkbox'
-                    ? { tag: 'input', attrs: { id: this._id(f), type: 'checkbox', checked: !!(f.value ?? f.inherit.value) }, ref: (n) => { input = n; this._keep(f)(n); } }
-                    : this._controlSpec({ ...f, value: f.value ?? f.inherit.value }, (n) => { input = n; }),
-                {
-                    tag: 'label', style: { display: 'flex', alignItems: 'center', gap: '4px', color: '#555' },
-                    attrs: { title: f.inherit.text },
-                    children: [
-                        { tag: 'input', attrs: { type: 'checkbox', checked: f.value === undefined }, on: { change: sync }, ref: (n) => { inherit = n; } },
-                        f.inherit.short ?? 'Inherit',
-                    ],
-                },
-            ],
-            // el() runs a parent's ref after its children's, so input/inherit are bound here.
-            ref: () => sync(),
-        };
-    }
-
-    /**
-     * One form for several items: each item's fields (the same keys, in the
-     * same order) merged into one list in which every field starts as "keep
-     * each item's own" (`inherit`, reading as undefined) showing the value
-     * they share, or empty with a hint when they differ. Set a field and it
-     * applies to them all; read-only fields are left out.
-     * @param {Array<Array<Object>>} fieldLists - One list of fields per item
-     * @param {Object} [options]
-     * @param {string} [options.short] - The keep checkbox's label
-     * @param {string} [options.text] - Its tooltip (and a select's first option)
-     * @returns {Array<Object>} fields
-     */
-    static many(fieldLists, { short = 'Keep', text = 'As each one is' } = {}) {
-        const [first = [], ...rest] = fieldLists;
-        const same = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
-        return first.filter(f => !f.readOnly).map((f, i) => {
-            if (f.type === 'heading' || !f.key) return f;
-            const values = [f.value, ...rest.map(list => list.find(g => g.key === f.key)?.value)];
-            const shared = values.every(v => same(v, values[0]));
-            const blank = f.type === 'checkbox' ? false : '';
-            return {
-                ...f, value: undefined,
-                inherit: { short, text, value: shared ? (values[0] ?? blank) : blank },
-                ...(!shared && { hint: [f.hint, 'Differs between them'].filter(Boolean).join('. ') }),
-            };
-        });
-    }
-}
+import { el } from '../workspace/dom.js';
+import { ColorField } from './ColorField.js';
+import { RowsField } from './RowsField.js';
+
+const INHERIT = '__inherit__';
+
+/**
+ * FormDialog — the one modal form, built from field descriptions, so every
+ * editor dialog shares one layout, keyboard handling and value reading.
+ *
+ * Field: `{ key, label, type, value?, choices?, min?, max?, step?, rows?, placeholder?,
+ *           suggestions?, accept?, hint?, readOnly?, allowEmpty?, inherit?, element?, read? }`
+ * - type: 'text' | 'textarea' | 'number' | 'color' | 'select' | 'checkbox' | 'checklist' | 'file' | 'custom'
+ *   | 'rows' | 'heading' (a section title; no value)
+ * - rows: a list edited as a table (RowsField): `columns` `[{ key, label, type?, choices?, suggestions? }]`,
+ *   `value` the items, `addLabel`; reads as the items in order, each keeping what no column shows
+ * - checklist: a box per choice, `choices` `[[value, text, group?], ...]` (grouped under their group's
+ *   name), `value` the chosen values; reads as the chosen values, in choice order
+ * - choices (select): `[[value, text], ...]`. A current value that is not a
+ *   choice is kept as its own option (never silently blanked); `allowEmpty`
+ *   adds a "(none)" option for an empty value.
+ * - suggestions (text): values offered as you type (a datalist). The box empties
+ *   on focus so every suggestion shows, and restores its value if left empty.
+ * - readOnly: shown but not editable, and not read back
+ * - accept (file): file types; reads as the chosen File or null
+ * - custom: `element` (a Node to place) and `read()` (its value)
+ * - color: a ColorField (the value as text, `#rrggbb` or `none`, a picker and preset
+ *   swatches); `presets` (`[{value, name}]`) replaces ColorField.PRESETS, and
+ *   `allowNone: false` leaves out "No colour"
+ * - hint: small explanatory text under the field
+ * - inherit: `{ text, short?, value }` — the field may be left unset. Selects get
+ *   a first option labelled `text`; other types (checkboxes too) get an "Inherit"
+ *   checkbox (`short` renames it) that greys the control out showing `value`. An
+ *   inherited field reads as `undefined`. `FormDialog.many` uses it for a form
+ *   that edits several items at once.
+ *
+ * The dialog fits the window: its fields scroll between the title and the
+ * buttons, which stay in view, and it moves by dragging its title. A textarea
+ * scrolls inside its own box and can be resized taller.
+ *
+ * `validate(values)` may return a message to show inline instead of closing.
+ * After open(), `controls[key]` is each field's control, for wiring fields that
+ * depend on one another.
+ */
+export class FormDialog {
+    /**
+     * @param {Object} options
+     * @param {string} options.title
+     * @param {string} [options.description] - Text under the title
+     * @param {Array<Object>} options.fields
+     * @param {(values: Object) => void} options.onApply
+     * @param {(values: Object) => (string|null|undefined)} [options.validate]
+     * @param {string} [options.submitLabel]
+     * @param {string} [options.cancelLabel]
+     * @param {string} [options.idPrefix] - Field element ids are `${idPrefix}${key}`
+     * @param {Document} [options.document]
+     * @param {(applied: boolean) => void} [options.onClose] - Once, when the dialog closes: whether it was
+     *   applied (false for Cancel, Escape or a click outside)
+     */
+    constructor({ title, description, fields, onApply, validate, submitLabel = 'Apply', cancelLabel = 'Cancel', idPrefix = 'form-dialog-', document: doc = document, onClose = null }) {
+        this.title = title;
+        this.description = description;
+        this.fields = fields;
+        this.onApply = onApply;
+        this.validate = validate;
+        this.submitLabel = submitLabel;
+        this.cancelLabel = cancelLabel;
+        this.idPrefix = idPrefix;
+        this.doc = doc;
+        this.onClose = onClose;
+        this._applied = false;
+        this.overlay = null;
+        /** @type {Object<string, HTMLElement>} */
+        this.controls = {};
+        this._readers = [];
+        this._error = null;
+    }
+
+    open() {
+        this._readers = [];
+        this.controls = {};
+        const rows = this.fields.map(f => this._row(f));
+        this.overlay = el({
+            style: {
+                position: 'fixed', inset: '0', background: 'rgba(0,0,0,0.25)', zIndex: '10001',
+                display: 'flex', alignItems: 'center', justifyContent: 'center', fontFamily: 'sans-serif',
+            },
+            on: { mousedown: (e) => { if (e.target === this.overlay) this.close(); } },
+            children: [{
+                tag: 'form',
+                attrs: { role: 'dialog', 'aria-label': this.title },
+                style: {
+                    background: '#fff', color: '#222', border: '1px solid #bbb', borderRadius: '6px', padding: '16px 18px',
+                    minWidth: '360px', maxWidth: '90vw', maxHeight: '90vh', boxSizing: 'border-box',
+                    display: 'flex', flexDirection: 'column',
+                    boxShadow: '0 6px 24px rgba(0,0,0,0.2)', fontSize: '12px',
+                },
+                ref: (n) => { this.form = n; },
+                on: {
+                    submit: (e) => { e.preventDefault(); this._apply(); },
+                    keydown: (e) => { if (e.key === 'Escape') this.close(); },
+                },
+                children: [
+                    {
+                        // The title is the handle that moves the dialog.
+                        tag: 'h3', text: this.title, attrs: { title: 'Drag to move' },
+                        style: { margin: '0 0 8px', fontSize: '14px', cursor: 'move', userSelect: 'none', flex: '0 0 auto' },
+                        on: { mousedown: (e) => this._startMove(e) },
+                    },
+                    {
+                        // The fields scroll; the title and the buttons stay in view.
+                        style: { overflowY: 'auto', flex: '1 1 auto', minHeight: '0', paddingRight: '4px' },
+                        ref: (n) => { this.body = n; },
+                        children: [
+                            this.description && { text: this.description, style: { fontSize: '11px', color: '#666', margin: '0 0 10px', whiteSpace: 'pre-line' } },
+                            { style: { display: 'grid', gridTemplateColumns: 'auto 1fr', gap: '8px 12px', alignItems: 'center' }, children: rows.flat() },
+                            { attrs: { role: 'alert' }, style: { color: '#c0392b', fontSize: '12px', marginTop: '8px', display: 'none' }, ref: (n) => { this._error = n; } },
+                        ].filter(Boolean),
+                    },
+                    {
+                        style: { display: 'flex', justifyContent: 'flex-end', gap: '8px', marginTop: '16px', flex: '0 0 auto' },
+                        children: [
+                            { tag: 'button', attrs: { type: 'button' }, text: this.cancelLabel, on: { click: () => this.close() } },
+                            {
+                                tag: 'button', attrs: { type: 'submit' }, text: this.submitLabel,
+                                style: { background: '#0066cc', color: '#fff', border: '1px solid #0066cc', borderRadius: '3px', padding: '4px 14px' },
+                            },
+                        ],
+                    },
+                ].filter(Boolean),
+            }],
+        }, this.doc);
+        this.doc.body.appendChild(this.overlay);
+        this.overlay.querySelector('input:not([type=checkbox]), select, textarea')?.focus();
+        return this;
+    }
+
+    /**
+     * Move the dialog by its title: from then on it sits where it was dropped
+     * (fixed position), kept inside the window.
+     * @protected
+     */
+    _startMove(e) {
+        if (e.button !== 0 || !this.form) return;
+        e.preventDefault();
+        const view = this.doc.defaultView;
+        const box = this.form.getBoundingClientRect();
+        const grab = { x: e.clientX - box.left, y: e.clientY - box.top };
+        Object.assign(this.form.style, { position: 'fixed', margin: '0', left: `${box.left}px`, top: `${box.top}px` });
+        const move = (ev) => {
+            const width = view?.innerWidth ?? Infinity, height = view?.innerHeight ?? Infinity;
+            const left = Math.min(Math.max(0, ev.clientX - grab.x), Math.max(0, width - box.width));
+            const top = Math.min(Math.max(0, ev.clientY - grab.y), Math.max(0, height - 40));
+            this.form.style.left = `${left}px`;
+            this.form.style.top = `${top}px`;
+        };
+        const end = () => {
+            this.doc.removeEventListener('mousemove', move);
+            this.doc.removeEventListener('mouseup', end);
+        };
+        this.doc.addEventListener('mousemove', move);
+        this.doc.addEventListener('mouseup', end);
+    }
+
+    close() {
+        if (!this.overlay) return;
+        this.overlay.remove();
+        this.overlay = null;
+        this.onClose?.(this._applied);
+    }
+
+    values() {
+        return Object.fromEntries(this._readers.map(read => read()));
+    }
+
+    _apply() {
+        const values = this.values();
+        const problem = this.validate?.(values);
+        if (problem) {
+            this._error.textContent = problem;
+            this._error.style.display = 'block';
+            return;
+        }
+        this._applied = true;
+        this.close();
+        this.onApply(values);
+    }
+
+    _id(f) {
+        return `${this.idPrefix}${f.key}`;
+    }
+
+    _keep(f) {
+        return (n) => { this.controls[f.key] = n; };
+    }
+
+    _row(f) {
+        if (f.type === 'heading') {
+            return [{
+                text: f.label, style: {
+                    gridColumn: '1 / -1', fontSize: '11px', fontWeight: 'bold', textTransform: 'uppercase',
+                    color: '#999', letterSpacing: '0.04em', marginTop: '6px',
+                },
+            }];
+        }
+        const label = { tag: 'label', text: f.label, attrs: { for: this._id(f) }, style: { color: '#333' } };
+        let control;
+        if (f.type === 'select') control = this._select(f);
+        else if (f.type === 'checkbox') control = this._checkbox(f);
+        else if (f.type === 'checklist') control = this._checklist(f);
+        else if (f.type === 'custom') control = this._custom(f);
+        else if (f.type === 'rows') control = this._rowsField(f);
+        else control = f.inherit ? this._inheritableInput(f) : this._input(f);
+        // No label, or a table of rows: the control takes the whole row, its label above it.
+        const row = f.label && f.type !== 'rows' ? [label, control]
+            : [{ style: { gridColumn: '1 / -1' }, children: [...(f.label ? [{ ...label, style: { color: '#333', display: 'block', marginBottom: '2px' } }] : []), control] }];
+        if (f.hint) row.push({}, { text: f.hint, style: { fontSize: '11px', color: '#888', marginTop: '-4px' } });
+        return row;
+    }
+
+    _select(f) {
+        let select;
+        if (!f.readOnly) this._readers.push(() => [f.key, select.value === INHERIT ? undefined : select.value]);
+        const unset = f.inherit && f.value === undefined;
+        const current = f.value == null ? '' : String(f.value);
+        const known = f.choices.some(([v]) => v === current);
+        const extra = unset ? []
+            : current && !known ? [[current, current]]
+                : !current && f.allowEmpty ? [['', '(none)']]
+                    : [];
+        return {
+            tag: 'select', attrs: { id: this._id(f), disabled: !!f.readOnly }, ref: (n) => { select = n; this._keep(f)(n); },
+            children: [
+                ...(f.inherit ? [{ tag: 'option', attrs: { value: INHERIT, selected: unset }, text: f.inherit.text }] : []),
+                ...[...extra, ...f.choices].map(([v, text]) => ({ tag: 'option', attrs: { value: v, selected: !unset && v === current }, text })),
+            ],
+        };
+    }
+
+    _checkbox(f) {
+        if (f.inherit) return this._inheritableInput(f);
+        let box;
+        if (!f.readOnly) this._readers.push(() => [f.key, box.checked]);
+        return {
+            tag: 'input', attrs: { id: this._id(f), type: 'checkbox', checked: !!f.value, disabled: !!f.readOnly }, style: { justifySelf: 'start' },
+            ref: (n) => { box = n; this._keep(f)(n); },
+        };
+    }
+
+    _checklist(f) {
+        const boxes = [];
+        const chosen = new Set(f.value ?? []);
+        if (!f.readOnly) this._readers.push(() => [f.key, boxes.filter(b => b.checked).map(b => b.value)]);
+        const groups = new Map();
+        for (const [value, text, group = ''] of f.choices) {
+            if (!groups.has(group)) groups.set(group, []);
+            groups.get(group).push([value, text]);
+        }
+        return {
+            attrs: { id: this._id(f) }, ref: this._keep(f),
+            style: { maxHeight: '220px', overflowY: 'auto', border: '1px solid #ccc', borderRadius: '3px', padding: '4px 8px', background: '#fff' },
+            children: [...groups].map(([group, items]) => ({
+                children: [
+                    ...(group ? [{ text: group, style: { fontSize: '11px', fontWeight: 'bold', color: '#777', marginTop: '4px' } }] : []),
+                    ...items.map(([value, text]) => ({
+                        tag: 'label', style: { display: 'block', whiteSpace: 'nowrap' },
+                        children: [
+                            { tag: 'input', attrs: { type: 'checkbox', value, checked: chosen.has(value), disabled: !!f.readOnly }, ref: (n) => boxes.push(n) },
+                            ` ${text}`,
+                        ],
+                    })),
+                ],
+            })),
+        };
+    }
+
+    _custom(f) {
+        this._readers.push(() => [f.key, f.read()]);
+        if (f.element && !f.element.id) f.element.id = this._id(f);
+        this.controls[f.key] = f.element;
+        return f.element;
+    }
+
+    _rowsField(f) {
+        const field = new RowsField(f, this.doc, this._id(f));
+        const node = field.element();
+        if (!f.readOnly) this._readers.push(() => [f.key, field.read()]);
+        this.controls[f.key] = node;
+        return node;
+    }
+
+    _controlSpec(f, ref) {
+        const keep = (n) => { ref(n); this._keep(f)(n); };
+        const readOnlyStyle = f.readOnly ? { background: '#f2f2f2', color: '#888' } : {};
+        if (f.type === 'textarea') {
+            return {
+                tag: 'textarea', attrs: { id: this._id(f), rows: f.rows ?? 4, placeholder: f.placeholder, readonly: !!f.readOnly },
+                text: f.value ?? '',
+                // Long text scrolls inside the box, which can be dragged taller.
+                style: { width: '100%', minWidth: '260px', boxSizing: 'border-box', maxHeight: '40vh', overflowY: 'auto', resize: 'vertical', ...readOnlyStyle },
+                ref: keep,
+            };
+        }
+        // A colour: its value as text (#rrggbb or none), a picker and preset swatches.
+        if (f.type === 'color') return ColorField.spec(f, { id: this._id(f), ref: keep, style: readOnlyStyle });
+        const value = f.type === 'file' ? null : (f.value == null ? '' : (Array.isArray(f.value) ? JSON.stringify(f.value) : String(f.value)));
+        const listId = f.suggestions ? `${this._id(f)}-suggestions` : null;
+        const input = {
+            tag: 'input',
+            attrs: {
+                id: this._id(f), type: f.type ?? 'text', value,
+                min: f.min, max: f.max, step: f.step, placeholder: f.placeholder, accept: f.accept, list: listId,
+                readonly: !!f.readOnly,
+            },
+            style: { ...(f.type === 'number' ? { width: '70px' } : { width: '100%', boxSizing: 'border-box' }), ...readOnlyStyle },
+            on: f.suggestions ? {
+                // A datalist filters against the text already typed, so an existing
+                // value can look like the only option. Emptying on focus shows them all.
+                focus: (e) => { e.target.dataset.prevValue = e.target.value; e.target.value = ''; },
+                blur: (e) => { if (e.target.value === '' && e.target.dataset.prevValue) e.target.value = e.target.dataset.prevValue; },
+            } : undefined,
+            ref: keep,
+        };
+        if (!listId) return input;
+        return {
+            children: [input, { tag: 'datalist', attrs: { id: listId }, children: f.suggestions.map(v => ({ tag: 'option', attrs: { value: v } })) }],
+        };
+    }
+
+    _read(f, input) {
+        if (f.type === 'file') return input.files?.[0] ?? null;
+        if (f.type === 'checkbox') return input.checked;
+        return f.type === 'number' ? Number(input.value) : input.value;
+    }
+
+    _input(f) {
+        let input;
+        if (!f.readOnly) this._readers.push(() => [f.key, this._read(f, input)]);
+        return this._controlSpec(f, (n) => { input = n; });
+    }
+
+    /** The control plus an "Inherit" checkbox that greys it out showing the inherited value. */
+    _inheritableInput(f) {
+        let input, inherit;
+        const sync = () => {
+            input.disabled = inherit.checked;
+            if (inherit.checked && f.type === 'checkbox') input.checked = !!f.inherit.value;
+            else if (inherit.checked) input.value = f.inherit.value;
+        };
+        this._readers.push(() => [f.key, inherit.checked ? undefined : this._read(f, input)]);
+        return {
+            style: { display: 'flex', alignItems: 'center', gap: '10px' },
+            children: [
+                f.type === 'checkbox'
+                    ? { tag: 'input', attrs: { id: this._id(f), type: 'checkbox', checked: !!(f.value ?? f.inherit.value) }, ref: (n) => { input = n; this._keep(f)(n); } }
+                    : this._controlSpec({ ...f, value: f.value ?? f.inherit.value }, (n) => { input = n; }),
+                {
+                    tag: 'label', style: { display: 'flex', alignItems: 'center', gap: '4px', color: '#555' },
+                    attrs: { title: f.inherit.text },
+                    children: [
+                        { tag: 'input', attrs: { type: 'checkbox', checked: f.value === undefined }, on: { change: sync }, ref: (n) => { inherit = n; } },
+                        f.inherit.short ?? 'Inherit',
+                    ],
+                },
+            ],
+            // el() runs a parent's ref after its children's, so input/inherit are bound here.
+            ref: () => sync(),
+        };
+    }
+
+    /**
+     * One form for several items: each item's fields (the same keys, in the
+     * same order) merged into one list in which every field starts as "keep
+     * each item's own" (`inherit`, reading as undefined) showing the value
+     * they share, or empty with a hint when they differ. Set a field and it
+     * applies to them all; read-only fields are left out.
+     * @param {Array<Array<Object>>} fieldLists - One list of fields per item
+     * @param {Object} [options]
+     * @param {string} [options.short] - The keep checkbox's label
+     * @param {string} [options.text] - Its tooltip (and a select's first option)
+     * @returns {Array<Object>} fields
+     */
+    static many(fieldLists, { short = 'Keep', text = 'As each one is' } = {}) {
+        const [first = [], ...rest] = fieldLists;
+        const same = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+        return first.filter(f => !f.readOnly).map((f, i) => {
+            if (f.type === 'heading' || !f.key) return f;
+            const values = [f.value, ...rest.map(list => list.find(g => g.key === f.key)?.value)];
+            const shared = values.every(v => same(v, values[0]));
+            const blank = f.type === 'checkbox' ? false : '';
+            return {
+                ...f, value: undefined,
+                inherit: { short, text, value: shared ? (values[0] ?? blank) : blank },
+                ...(!shared && { hint: [f.hint, 'Differs between them'].filter(Boolean).join('. ') }),
+            };
+        });
+    }
+}