@peter.prib/renderengine 0.0.0-stage → 0.2.0

package/src/charting/FormDialog.js

@@ -0,0 +1,385 @@
+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' } },
+                            { 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('. ') }),
+            };
+        });
+    }
+}

package/src/charting/Gauge.js

@@ -0,0 +1,58 @@
+import { ColorPalette } from './ColorPalette.js';
+
+/**
+ * Gauge — pure helpers shared by barGauge and dialGauge.
+ */
+export class Gauge {
+    /**
+     * Resolves a gauge `color` option to a single hex color for the given
+     * 0-100 value. A plain string or function passes through unchanged. An
+     * array is treated as a heat-map gradient, either plain hex strings evenly
+     * spaced across 0-100 or `{stop, color}` pairs at explicit percentages.
+     */
+    static resolveColor(color, percent) {
+        if (typeof color === 'function') return color(percent);
+        if (!Array.isArray(color)) return color;
+        if (color.length === 0) return '#5352ed';
+        if (color.length === 1) return typeof color[0] === 'string' ? color[0] : color[0].color;
+
+        const stops = typeof color[0] === 'string'
+            ? color.map((c, i) => ({ stop: (i / (color.length - 1)) * 100, color: c }))
+            : [...color].sort((a, b) => a.stop - b.stop);
+
+        const p = Math.min(100, Math.max(0, percent));
+        if (p <= stops[0].stop) return stops[0].color;
+        if (p >= stops[stops.length - 1].stop) return stops[stops.length - 1].color;
+        for (let i = 0; i < stops.length - 1; i++) {
+            const a = stops[i], b = stops[i + 1];
+            if (p >= a.stop && p <= b.stop) {
+                const t = b.stop === a.stop ? 0 : (p - a.stop) / (b.stop - a.stop);
+                return ColorPalette.interpolate(a.color, b.color, t);
+            }
+        }
+        return stops[stops.length - 1].color;
+    }
+
+    /**
+     * Builds an SVG arc path `d` string for a gauge background or progress arc.
+     * Angles are in radians.
+     */
+    static arcPath(cx, cy, r, startAngle, endAngle) {
+        // A whole circle starts and ends on one point, which an SVG arc draws as nothing: two halves.
+        if (endAngle - startAngle >= 2 * Math.PI - 1e-9) {
+            const mid = startAngle + Math.PI;
+            const at = (a) => `${cx + r * Math.cos(a)} ${cy + r * Math.sin(a)}`;
+            return `M ${at(startAngle)} A ${r} ${r} 0 0 1 ${at(mid)} A ${r} ${r} 0 0 1 ${at(startAngle)}`;
+        }
+        const largeArcFlag = endAngle - startAngle <= Math.PI ? '0' : '1';
+        const start = {
+            x: cx + r * Math.cos(startAngle),
+            y: cy + r * Math.sin(startAngle),
+        };
+        const end = {
+            x: cx + r * Math.cos(endAngle),
+            y: cy + r * Math.sin(endAngle),
+        };
+        return `M ${start.x} ${start.y} A ${r} ${r} 0 ${largeArcFlag} 1 ${end.x} ${end.y}`;
+    }
+}

package/src/charting/Hierarchy.js

@@ -0,0 +1,175 @@
+/**
+ * Hierarchy — pure, DOM-free helpers for hierarchical charts.
+ *
+ * Value computation, tree depth, squarified treemap layout, and sunburst
+ * angular layout used to be private methods on RenderEngine. Moving them here
+ * lets TreemapChart, SunburstChart, and OutlineChart stay focused on rendering.
+ */
+export class Hierarchy {
+    /**
+     * A leaf's own value, or a branch's value computed as the sum of its
+     * children (recursively). Non-finite or non-positive values are treated as 0.
+     */
+    static value(node) {
+        if (node.children?.length) return node.children.reduce((sum, c) => sum + Hierarchy.value(c), 0);
+        return Number.isFinite(node.value) && node.value > 0 ? node.value : 0;
+    }
+
+    /** Tree depth: 1 for a leaf, 1 + the deepest child for a branch. */
+    static depth(node) {
+        if (!node.children?.length) return 1;
+        return 1 + Math.max(...node.children.map(c => Hierarchy.depth(c)));
+    }
+
+    /**
+     * The worst (largest) width:height aspect ratio among `row`'s rectangles
+     * if laid out along a strip of the given `side` length. Assumes every
+     * item's `.area` is already computed.
+     */
+    static squarifyWorstRatio(row, side) {
+        const sum = row.reduce((s, item) => s + item.area, 0);
+        if (sum <= 0 || side <= 0) return Infinity;
+        const thickness = sum / side;
+        let worst = 1;
+        for (const item of row) {
+            const length = item.area / thickness;
+            if (length <= 0) return Infinity;
+            worst = Math.max(worst, Math.max(thickness / length, length / thickness));
+        }
+        return worst;
+    }
+
+    /**
+     * Squarified treemap layout. Lays `items` (each `{value, ref}`, pre-sorted
+     * descending by value) into the rect `x,y,width,height`, area-proportional
+     * to value.
+     * @returns {Array<{ref: *, x: number, y: number, width: number, height: number}>}
+     */
+    static squarify(items, x, y, width, height) {
+        const total = items.reduce((s, it) => s + it.value, 0);
+        if (!items.length || total <= 0 || width <= 0 || height <= 0) return [];
+        const scale = (width * height) / total;
+        const scaled = items.map(it => ({ ref: it.ref, area: it.value * scale }));
+
+        const result = [];
+        let rectX = x, rectY = y, rectW = width, rectH = height;
+        let i = 0;
+        while (i < scaled.length) {
+            const isWide = rectW >= rectH;
+            const side = isWide ? rectH : rectW;
+            let row = [scaled[i]];
+            let bestRatio = Hierarchy.squarifyWorstRatio(row, side);
+            let j = i + 1;
+            while (j < scaled.length) {
+                const testRow = [...row, scaled[j]];
+                const testRatio = Hierarchy.squarifyWorstRatio(testRow, side);
+                if (testRatio > bestRatio) break;
+                row = testRow;
+                bestRatio = testRatio;
+                j++;
+            }
+
+            const rowSum = row.reduce((s, it) => s + it.area, 0);
+            const thickness = rowSum / side;
+            let offset = 0;
+            for (const item of row) {
+                const length = item.area / thickness;
+                if (isWide) result.push({ ref: item.ref, x: rectX, y: rectY + offset, width: thickness, height: length });
+                else result.push({ ref: item.ref, x: rectX + offset, y: rectY, width: length, height: thickness });
+                offset += length;
+            }
+
+            if (isWide) { rectX += thickness; rectW -= thickness; }
+            else { rectY += thickness; rectH -= thickness; }
+            i += row.length;
+        }
+        return result;
+    }
+
+    /**
+     * Recursive layout over a treemap node tree. Computes each node's value,
+     * squarifies this level, and for a branch reserves a fixed-height header
+     * band before recursing into the remaining content rect.
+     * @param {number} [headerH=16]
+     * @returns {Array<{node: object, x: number, y: number, width: number, height: number, depth: number, isLeaf: boolean, topAncestor: object}>}
+     */
+    static treemapLayout(nodes, x, y, width, height, depth = 0, topAncestors = null, headerH = 16) {
+        const items = nodes
+            .map(node => ({ ref: node, value: Hierarchy.value(node) }))
+            .filter(it => it.value > 0)
+            .sort((a, b) => b.value - a.value);
+        const rects = Hierarchy.squarify(items, x, y, width, height);
+
+        const result = [];
+        for (const r of rects) {
+            const node = r.ref;
+            const isLeaf = !node.children?.length;
+            const topAncestor = topAncestors ? topAncestors.get(node) : node;
+            result.push({ node, x: r.x, y: r.y, width: r.width, height: r.height, depth, isLeaf, topAncestor });
+            if (!isLeaf) {
+                const bandH = Math.min(r.height, headerH);
+                const childTopAncestors = new Map(node.children.map(c => [c, topAncestor]));
+                result.push(...Hierarchy.treemapLayout(node.children, r.x, r.y + bandH, r.width, r.height - bandH, depth + 1, childTopAncestors, headerH));
+            }
+        }
+        return result;
+    }
+
+    /**
+     * Recursive angular layout over a node tree. Partitions angle instead of
+     * area, one ring per depth. Input order is preserved.
+     * @returns {Array<{node: object, cx: number, cy: number, rInner: number, rOuter: number, startAngle: number, endAngle: number, depth: number, isLeaf: boolean, topAncestor: object}>}
+     */
+    static sunburstLayout(nodes, cx, cy, innerRadius, ringWidth, startAngle, endAngle, depth = 0, topAncestors = null) {
+        const items = nodes
+            .map(node => ({ node, value: Hierarchy.value(node) }))
+            .filter(it => it.value > 0);
+        const total = items.reduce((s, it) => s + it.value, 0) || 1;
+        const rOuter = innerRadius + ringWidth;
+
+        const result = [];
+        let angle = startAngle;
+        for (const it of items) {
+            const { node } = it;
+            const sliceAngle = (it.value / total) * (endAngle - startAngle);
+            const isLeaf = !node.children?.length;
+            const topAncestor = topAncestors ? topAncestors.get(node) : node;
+            const sliceStart = angle, sliceEnd = angle + sliceAngle;
+            result.push({ node, cx, cy, rInner: innerRadius, rOuter, startAngle: sliceStart, endAngle: sliceEnd, depth, isLeaf, topAncestor });
+            if (!isLeaf) {
+                const childTopAncestors = new Map(node.children.map(c => [c, topAncestor]));
+                result.push(...Hierarchy.sunburstLayout(node.children, cx, cy, rOuter, ringWidth, sliceStart, sliceEnd, depth + 1, childTopAncestors));
+            }
+            angle = sliceEnd;
+        }
+        return result;
+    }
+
+    /**
+     * Flat, pre-order list of *visible* rows for an outline view. A branch
+     * present in `collapsed` contributes its own row but none of its
+     * descendants'.
+     * @returns {Array<{node: object, depth: number, hasChildren: boolean, topAncestor: object}>}
+     */
+    static outlineLayout(nodes, depth, collapsed, topAncestors = null) {
+        const rows = [];
+        for (const node of nodes) {
+            const hasChildren = !!node.children?.length;
+            const topAncestor = topAncestors ? topAncestors.get(node) : node;
+            rows.push({ node, depth, hasChildren, topAncestor });
+            if (hasChildren && !collapsed.has(node)) {
+                const childTopAncestors = new Map(node.children.map(c => [c, topAncestor]));
+                rows.push(...Hierarchy.outlineLayout(node.children, depth + 1, collapsed, childTopAncestors));
+            }
+        }
+        return rows;
+    }
+
+    /** Extracts descriptive extra fields from an outline row node. */
+    static outlineExtraText(node, structuralKeys) {
+        return Object.entries(node)
+            .filter(([k, v]) => !structuralKeys.has(k) && v !== undefined && typeof v !== 'function')
+            .map(([, v]) => Array.isArray(v) ? v.join(', ') : v)
+            .join(' · ');
+    }
+}