@peter.prib/renderengine 0.7.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peter.prib/renderengine",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "ArchiMate modeller, diagram editor and chart library for the browser, with no runtime dependencies.",
   "type": "module",
   "main": "src/index.js",
@@ -28,7 +28,7 @@
     "archimate": "node scripts/open.mjs examples/archimate.html",
     "diagram": "node scripts/open.mjs examples/diagram-editor.html",
     "datamodel": "node scripts/open.mjs examples/data-model.html",
-    "test": "node --test --test-timeout=10000 ./test/*.js ./test/charting/*.js ./test/charting/charts/*.js ./test/charting/diagrams/*.js ./test/charting/shapes/*.js",
+    "test": "node --test --test-timeout=10000 ./test/*.js ./test/charting/*.js ./test/charting/charts/*.js ./test/charting/table/*.js ./test/charting/diagrams/*.js ./test/charting/shapes/*.js",
     "build": "rollup -c",
     "prepublishOnly": "npm test && npm run build",
     "screenshots": "node scripts/screenshots/screenshots.mjs"

package/src/chartCatalog.js

@@ -457,6 +457,16 @@ export const CHART_CATALOG = [
     dataShape: 'Array<{label, value?, children?}> — same hierarchical shape as treemap/sunburst (shares _hierarchyValue); drawn as an indented, collapsible list instead of nested rectangles/rings — a branch\'s value is auto-summed from its descendants and shown as a trailing count, a leaf\'s own extra fields (anything beyond label/value/children) shown as trailing descriptive text instead',
     streamShape: 'flat',
   },
+  {
+    key: 'table', label: 'Table', method: 'tableChart', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.NONE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'row',   kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_ORDER, required: false },
+      { role: 'value', kind: AXIS_KIND.NUMERIC,     channel: ENCODING_CHANNEL.TEXT_VALUE,     required: false },
+    ],
+    dataShape: 'Array<object> — one row per object, a column per key (options.columns: names or {key, label?, align?}; every key of the first row when absent); values shown exactly as text, numeric columns right-aligned; options.maxRows, options.nullText',
+    streamShape: 'flat',
+  },
   {
     key: 'gauge-dial', label: 'Gauge (Dial)', method: 'dialGauge', category: 'gauge',
     coordSystem: COORD_SYSTEM.RADIAL, title: true, legend: false, colorMode: COLOR_MODE.SINGLE, camera: CAMERA_MODE.NONE,

package/src/charting/ChartChooser.js

@@ -0,0 +1,243 @@
+import { AXIS_KIND, chartRegistry } from '../chartCatalog.js';
+
+/**
+ * ChartChooser — which catalog chart types fit a set of result rows, best first, each with the rows
+ * already shaped as that chart's `dataShape`. A table always fits, so it is always offered, last.
+ *
+ * The caller may describe the columns (hints). `kind` is `'categorical'`, `'numeric'` or `'time'`; a
+ * column with no hint is numeric when every value it holds is a number, else categorical. `measure`
+ * is renderengine's measure kind (`'additive'`, `'semi-additive'`, `'non-additive'`), as a data model
+ * gives it. The hints change the choice: a time column is drawn along a line, and only an additive
+ * measure is offered as shares of a whole (a pie), since a part-of-a-whole slice of an average or a
+ * balance means nothing.
+ *
+ * Every suggestion is checked against CHART_CATALOG: a chart type is offered only when the catalog
+ * has it and every axis it requires is one the result's shape provides — so the catalog stays the
+ * single source of truth for what each chart needs.
+ *
+ *     const [best, ...others] = new ChartChooser().choose(rows, [{ name: 'Day', kind: 'time' }]);
+ *     engine.renderChartType(best.key, best.data, { title: best.label });
+ */
+export class ChartChooser {
+    /** @param {ChartRegistry} [registry] — the built-in chart types, or another registry to choose from */
+    constructor(registry = chartRegistry) {
+        this.registry = registry;
+    }
+
+    /**
+     * @param {Array<object>} rows
+     * @param {Array<{name:string, kind?:string, measure?:string}>} [columns] — hints; every key of the
+     *   first row when absent, in that order
+     * @param {{complete?:boolean}} [options] — `complete: false` when the rows are only part of the
+     *   answer (a top N, a first page): then nothing is offered as shares of a whole, since the
+     *   slices would claim to be all of it
+     * @returns {Array<{key:string, label:string, data:*, reason:string}>} best first; the table last
+     */
+    choose(rows, columns = null, { complete = true } = {}) {
+        const described = ChartChooser.describe(rows, columns);
+        const shape = RESULT_SHAPES.map(S => S.of(described, rows)).find(s => s !== null) ?? null;
+        if (shape !== null) shape.complete = complete;
+        const charts = shape === null ? [] : shape.candidates()
+            .filter(({ key }) => this.fits(key, shape))
+            .map(({ key, reason, data }) => ({ key, label: this.registry.get(key).label, data, reason }));
+        return [...charts, this.table(rows, described, charts.length === 0)];
+    }
+
+    /** A catalog entry fits a shape when every axis it requires is one the shape provides. */
+    fits(key, shape) {
+        const entry = this.registry.get(key);
+        if (!entry) return false;
+        if (shape.needsSeries && !entry.seriesCapable && !entry.axes.some(a => a.role === 'series')) return false;
+        return entry.axes.filter(a => a.required).every(a => shape.provides[a.role] === a.kind);
+    }
+
+    table(rows, described, only) {
+        return {
+            key: 'table', label: this.registry.get('table')?.label ?? 'Table',
+            data: rows, columns: described.map(c => c.name),
+            reason: only ? 'no chart fits these columns' : 'every value, exactly',
+        };
+    }
+
+    /** The columns with their kinds settled: the hint's, else derived from the rows' values. */
+    static describe(rows, columns) {
+        const given = columns ?? Object.keys(rows[0] ?? {}).map(name => ({ name }));
+        return given.map(c => ({
+            name: c.name,
+            kind: c.kind ?? (rows.length > 0 && rows.every(r => r[c.name] == null || typeof r[c.name] === 'number') ? 'numeric' : 'categorical'),
+            measure: c.measure ?? null,
+        }));
+    }
+}
+
+/** The label a category value is drawn with. */
+function label(value) {
+    return value == null ? '—' : value instanceof Date ? value.toISOString().slice(0, 10) : String(value);
+}
+
+/** Rows in time order by `column` (numbers, dates and ISO strings all sort correctly this way). */
+function inOrder(rows, column) {
+    return [...rows].sort((a, b) => (a[column] < b[column] ? -1 : a[column] > b[column] ? 1 : 0));
+}
+
+/**
+ * ResultShape — what a result's columns look like: how many category, time and numeric columns.
+ * Each subclass recognises one shape (`static of`), says which catalog axes it provides, and lists
+ * the chart types that suit it, best first, with the rows shaped for each.
+ */
+class ResultShape {
+    constructor() {
+        /** Whether the rows are all of the answer (ChartChooser.choose's `complete`). */
+        this.complete = true;
+    }
+
+    /** The axes this shape can fill, role → AXIS_KIND. */
+    get provides() { return {}; }
+    /** Whether a chart must draw several series (one per numeric column). */
+    get needsSeries() { return false; }
+    /** @returns {Array<{key, reason, data}>} */
+    candidates() { return []; }
+
+    static split(columns) {
+        return {
+            categories: columns.filter(c => c.kind !== 'numeric'),
+            numbers: columns.filter(c => c.kind === 'numeric'),
+        };
+    }
+
+    /**
+     * Whether each row has its own value of the category columns. Rows that repeat a category
+     * (rows of orders, not totals per region) would be drawn as one bar per row with the same
+     * label over and over — or, for two categories, one repeated pair would replace another's value
+     * unseen. A chart of a value per category needs one row per category: a GROUP BY first.
+     */
+    static oneRowEach(rows, categories) {
+        const keys = new Set(rows.map(r => JSON.stringify(categories.map(c => r[c.name] ?? null))));
+        return keys.size === rows.length;
+    }
+}
+
+/** One number and nothing to group it by: a single figure. */
+class SingleFigure extends ResultShape {
+    static of(columns, rows) {
+        const { categories, numbers } = ResultShape.split(columns);
+        return categories.length === 0 && numbers.length === 1 && rows.length === 1 ? new SingleFigure(numbers[0], rows) : null;
+    }
+    constructor(number, rows) { super(); this.number = number; this.rows = rows; }
+    get provides() { return { value: AXIS_KIND.NUMERIC }; }
+    candidates() {
+        return [{ key: 'kpi-tile', reason: 'a single figure', data: { value: this.rows[0][this.number.name] } }];
+    }
+}
+
+/** One category (or time) column and one number: a value per category. */
+class CategoryValue extends ResultShape {
+    static of(columns, rows) {
+        const { categories, numbers } = ResultShape.split(columns);
+        return categories.length === 1 && numbers.length === 1 && ResultShape.oneRowEach(rows, categories)
+            ? new CategoryValue(categories[0], numbers[0], rows) : null;
+    }
+    constructor(category, number, rows) { super(); this.category = category; this.number = number; this.rows = rows; }
+    get provides() { return { category: AXIS_KIND.CATEGORICAL, value: AXIS_KIND.NUMERIC }; }
+
+    candidates() {
+        const { category, number } = this;
+        const time = category.kind === 'time';
+        const rows = time ? inOrder(this.rows, category.name) : this.rows;
+        const data = rows.filter(r => r[number.name] != null).map(r => ({ label: label(r[category.name]), value: r[number.name] }));
+        if (time) {
+            return [
+                { key: 'line', reason: `${number.name} over ${category.name}`, data },
+                { key: 'area', reason: `${number.name} over ${category.name}, filled`, data },
+                { key: 'bar', reason: `${number.name} for each ${category.name}`, data },
+            ];
+        }
+        const options = [{ key: 'bar', reason: `${number.name} for each ${category.name}`, data }];
+        if (this.isShareOfWhole(data)) {
+            options.push({ key: 'pie', reason: `each ${category.name}'s share of the total ${number.name}`, data });
+            options.push({ key: 'donut', reason: `each ${category.name}'s share of the total ${number.name}`, data });
+        }
+        return options;
+    }
+
+    /**
+     * Shares of a whole make sense only for an additive measure, over all of the rows (not a top N),
+     * with no negatives, in few slices.
+     */
+    isShareOfWhole(data) {
+        return this.complete && this.number.measure === 'additive' && data.length >= 2 && data.length <= CategoryValue.MAX_SLICES
+            && data.every(d => d.value >= 0);
+    }
+}
+CategoryValue.MAX_SLICES = 8;
+
+/** One category (or time) column and several numbers: a series per number. */
+class CategorySeries extends ResultShape {
+    static of(columns, rows) {
+        const { categories, numbers } = ResultShape.split(columns);
+        return categories.length === 1 && numbers.length >= 2 && ResultShape.oneRowEach(rows, categories)
+            ? new CategorySeries(categories[0], numbers, rows) : null;
+    }
+    constructor(category, numbers, rows) { super(); this.category = category; this.numbers = numbers; this.rows = rows; }
+    get provides() { return { category: AXIS_KIND.CATEGORICAL, value: AXIS_KIND.NUMERIC, series: AXIS_KIND.CATEGORICAL }; }
+    get needsSeries() { return true; }
+
+    candidates() {
+        const { category } = this;
+        const time = category.kind === 'time';
+        const rows = time ? inOrder(this.rows, category.name) : this.rows;
+        // lineChart and groupedBarChart have no gap for a missing value: a null would have to be drawn
+        // as 0, a figure the data does not hold. So a result with one is not offered as series.
+        if (rows.some(r => this.numbers.some(n => r[n.name] == null))) return [];
+        const data = this.numbers.map(n => ({
+            name: n.name,
+            values: rows.map(r => ({ label: label(r[category.name]), value: r[n.name] })),
+        }));
+        const names = this.numbers.map(n => n.name).join(', ');
+        return time
+            ? [{ key: 'line', reason: `${names} over ${category.name}`, data }, { key: 'groupedBar', reason: `${names} for each ${category.name}`, data }]
+            : [{ key: 'groupedBar', reason: `${names} for each ${category.name}`, data }, { key: 'line', reason: `${names} across ${category.name}`, data }];
+    }
+}
+
+/** Two category (or time) columns and one number: a value per pair. */
+class TwoCategories extends ResultShape {
+    static of(columns, rows) {
+        const { categories, numbers } = ResultShape.split(columns);
+        return categories.length === 2 && numbers.length === 1 && ResultShape.oneRowEach(rows, categories)
+            ? new TwoCategories(categories, numbers[0], rows) : null;
+    }
+    constructor(categories, number, rows) {
+        super();
+        // A time column goes along the x axis, whichever order the columns came in.
+        this.across = categories.find(c => c.kind === 'time') ?? categories[0];
+        this.down = categories.find(c => c !== this.across);
+        this.number = number;
+        this.rows = rows;
+    }
+    get provides() {
+        return { x: AXIS_KIND.CATEGORICAL, y: AXIS_KIND.CATEGORICAL, category: AXIS_KIND.CATEGORICAL, value: AXIS_KIND.NUMERIC, series: AXIS_KIND.CATEGORICAL };
+    }
+
+    candidates() {
+        const { across, down, number } = this;
+        const rows = across.kind === 'time' ? inOrder(this.rows, across.name) : this.rows;
+        const heat = rows.filter(r => r[number.name] != null)
+            .map(r => ({ x: label(r[across.name]), y: label(r[down.name]), value: r[number.name] }));
+        const heatmap = { key: 'heatmap', reason: `${number.name} for each ${across.name} and ${down.name}`, data: heat };
+        // A series needs a value for every label; where a pair is missing (or null) only the heatmap,
+        // which draws just the cells present, shows the data without inventing a 0.
+        const labels = [...new Set(rows.map(r => label(r[across.name])))];
+        const value = new Map(rows.map(r => [`${label(r[across.name])}\u0000${label(r[down.name])}`, r[number.name]]));
+        const names = [...new Set(rows.map(r => label(r[down.name])))];
+        if (names.some(name => labels.some(l => value.get(`${l}\u0000${name}`) == null))) return [heatmap];
+        const series = names.map(name => ({ name, values: labels.map(l => ({ label: l, value: value.get(`${l}\u0000${name}`) })) }));
+        const grouped = { key: 'groupedBar', reason: `${number.name} for each ${across.name}, by ${down.name}`, data: series };
+        return across.kind === 'time'
+            ? [{ key: 'line', reason: `${number.name} over ${across.name}, a line per ${down.name}`, data: series }, heatmap, grouped]
+            : [grouped, heatmap];
+    }
+}
+
+/** Shapes in the order they are tried; the first that recognises the columns wins. */
+const RESULT_SHAPES = [SingleFigure, CategoryValue, CategorySeries, TwoCategories];

package/src/charting/PopupMenu.js

@@ -1,150 +1,152 @@
-import { el } from '../workspace/dom.js';
-
-/**
- * PopupMenu — the one popup/context menu: a small menu at a screen position,
- * closed by choosing an item, clicking elsewhere, Escape, or scrolling (it
- * would no longer be beside what it was opened on). One is open at a time.
- * Editor menus, the graph engine's ContextMenu and the model tree's menus all
- * render through it.
- *
- * Items: `{ label, action, danger?, checked?, disabled? }`,
- * `{ label, items: [...] }` for a submenu, or `{ separator: true }`.
- */
-export class PopupMenu {
-    static _open = null;
-
-    static show(x, y, items, doc = document) {
-        PopupMenu.close();
-        if (!items.length) return null;
-        const menu = el({
-            ...PopupMenu._panel(items, doc),
-            style: { ...PopupMenu._panelStyle, position: 'fixed', left: `${x}px`, top: `${y}px` },
-        }, doc);
-        doc.body.appendChild(menu);
-        // Opened near the window's right or bottom edge, it moves back into the window.
-        const win = doc.defaultView;
-        const box = menu.getBoundingClientRect?.();
-        if (win && box?.width) {
-            const at = PopupMenu.fit(x, y, box.width, box.height, win.innerWidth, win.innerHeight);
-            Object.assign(menu.style, { left: `${at.x}px`, top: `${at.y}px` });
-        }
-        // Registered after the opening click has finished propagating.
-        const dismiss = () => PopupMenu.close();
-        const onKey = (e) => { if (e.key === 'Escape') PopupMenu.close(); };
-        setTimeout(() => {
-            if (PopupMenu._open?.menu !== menu) return;   // closed meanwhile
-            doc.addEventListener('click', dismiss, { once: true });
-            doc.addEventListener('scroll', dismiss, { once: true, capture: true });
-            doc.addEventListener('keydown', onKey);
-        }, 0);
-        PopupMenu._open = { menu, dismiss, onKey, doc };
-        return menu;
-    }
-
-    /**
-     * Where a menu of a size goes, asked for at (x, y), to be all inside a
-     * window of a size: left of the point when it would pass the right edge,
-     * above it when it would pass the bottom, never past the top-left.
-     */
-    static fit(x, y, width, height, windowWidth, windowHeight, margin = 4) {
-        const left = x + width + margin > windowWidth ? x - width : x;
-        const top = y + height + margin > windowHeight ? y - height : y;
-        return {
-            x: Math.max(margin, Math.min(left, windowWidth - width - margin)),
-            y: Math.max(margin, Math.min(top, windowHeight - height - margin)),
-        };
-    }
-
-    /**
-     * Where a submenu opens beside its item (the item's box `{left, right, top}`),
-     * to be all inside the window: to the right, or to the left when the right
-     * would pass the edge (and there is more room on the left); level with the
-     * item, or lifted by as much as it would pass the bottom. `top` is relative
-     * to the item, as the submenu is positioned.
-     */
-    static submenuPlacement(item, width, height, windowWidth, windowHeight, margin = 4) {
-        const fitsRight = item.right + width + margin <= windowWidth;
-        const side = fitsRight || item.left < windowWidth - item.right ? 'right' : 'left';
-        const top = -4;
-        const overflow = item.top + top + height + margin - windowHeight;
-        return { side, top: overflow > 0 ? Math.max(top - overflow, margin - item.top) : top };
-    }
-
-    static close() {
-        const open = PopupMenu._open;
-        if (!open) return;
-        open.menu.remove();
-        open.doc.removeEventListener('click', open.dismiss);
-        open.doc.removeEventListener('scroll', open.dismiss, { capture: true });
-        open.doc.removeEventListener('keydown', open.onKey);
-        PopupMenu._open = null;
-    }
-
-    static get isOpen() {
-        return !!PopupMenu._open;
-    }
-
-    static _panelStyle = {
-        background: '#fff', border: '1px solid #ccc', borderRadius: '3px', boxShadow: '0 2px 8px rgba(0,0,0,0.2)',
-        zIndex: '10000', minWidth: '170px', fontSize: '12px', fontFamily: 'sans-serif', padding: '4px 0',
-    };
-
-    static _panel(items, doc) {
-        return { attrs: { role: 'menu' }, children: items.map(item => PopupMenu._item(item, doc)) };
-    }
-
-    static _item(item, doc) {
-        if (item.separator) return { attrs: { role: 'separator' }, style: { borderTop: '1px solid #ddd', margin: '4px 0' } };
-        const hover = item.danger ? '#ffe8e8' : '#f0f0f0';
-        const base = {
-            attrs: { role: 'menuitem', 'aria-disabled': item.disabled ? 'true' : null, 'aria-checked': item.checked != null ? String(!!item.checked) : null },
-            style: {
-                padding: '7px 14px', cursor: item.disabled ? 'default' : 'pointer', position: 'relative', whiteSpace: 'nowrap',
-                color: item.disabled ? '#aaa' : item.danger ? '#cc3333' : '', background: item.checked ? '#e3f2fd' : '',
-            },
-        };
-        if (item.items) {
-            let sub;
-            return {
-                ...base,
-                attrs: { ...base.attrs, 'aria-haspopup': 'menu' },
-                on: {
-                    mouseenter: (e) => {
-                        e.currentTarget.style.background = hover;
-                        sub.style.display = 'block';
-                        // Opened near the window's right or bottom edge, it opens left, or lifts.
-                        const win = e.currentTarget.ownerDocument.defaultView;
-                        const box = sub.getBoundingClientRect?.();
-                        if (!win || !box?.width) return;
-                        const at = PopupMenu.submenuPlacement(e.currentTarget.getBoundingClientRect(), box.width, box.height, win.innerWidth, win.innerHeight);
-                        Object.assign(sub.style, at.side === 'left' ? { left: 'auto', right: '100%' } : { left: '100%', right: 'auto' }, { top: `${at.top}px` });
-                    },
-                    mouseleave: (e) => { e.currentTarget.style.background = ''; sub.style.display = 'none'; },
-                    click: (e) => e.stopPropagation(),
-                },
-                children: [
-                    `${item.label} ▸`,
-                    {
-                        ...PopupMenu._panel(item.items, doc),
-                        style: { ...PopupMenu._panelStyle, position: 'absolute', left: '100%', top: '-4px', display: 'none' },
-                        ref: (n) => { sub = n; },
-                    },
-                ],
-            };
-        }
-        return {
-            ...base,
-            text: item.label,
-            on: {
-                mouseenter: (e) => { if (!item.disabled) e.currentTarget.style.background = hover; },
-                mouseleave: (e) => { e.currentTarget.style.background = item.checked ? '#e3f2fd' : ''; },
-                click: (e) => {
-                    e.stopPropagation();
-                    if (item.disabled) return;
-                    PopupMenu.close();
-                    item.action();
-                },
-            },
-        };
-    }
-}
+import { el } from '../workspace/dom.js';
+
+/**
+ * PopupMenu — the one popup/context menu: a small menu at a screen position,
+ * closed by choosing an item, clicking elsewhere, Escape, or scrolling (it
+ * would no longer be beside what it was opened on). One is open at a time.
+ * Editor menus, the graph engine's ContextMenu and the model tree's menus all
+ * render through it.
+ *
+ * Items: `{ label, action, danger?, checked?, disabled? }`,
+ * `{ label, items: [...] }` for a submenu, or `{ separator: true }`.
+ */
+export class PopupMenu {
+    static _open = null;
+
+    static show(x, y, items, doc = document) {
+        PopupMenu.close();
+        if (!items.length) return null;
+        const menu = el({
+            ...PopupMenu._panel(items, doc),
+            style: { ...PopupMenu._panelStyle, position: 'fixed', left: `${x}px`, top: `${y}px` },
+        }, doc);
+        doc.body.appendChild(menu);
+        // Opened near the window's right or bottom edge, it moves back into the window.
+        const win = doc.defaultView;
+        const box = menu.getBoundingClientRect?.();
+        if (win && box?.width) {
+            const at = PopupMenu.fit(x, y, box.width, box.height, win.innerWidth, win.innerHeight);
+            Object.assign(menu.style, { left: `${at.x}px`, top: `${at.y}px` });
+        }
+        // Registered after the opening click has finished propagating.
+        const dismiss = () => PopupMenu.close();
+        const onKey = (e) => { if (e.key === 'Escape') PopupMenu.close(); };
+        setTimeout(() => {
+            if (PopupMenu._open?.menu !== menu) return;   // closed meanwhile
+            doc.addEventListener('click', dismiss, { once: true });
+            doc.addEventListener('scroll', dismiss, { once: true, capture: true });
+            doc.addEventListener('keydown', onKey);
+        }, 0);
+        PopupMenu._open = { menu, dismiss, onKey, doc };
+        return menu;
+    }
+
+    /**
+     * Where a menu of a size goes, asked for at (x, y), to be all inside a
+     * window of a size: left of the point when it would pass the right edge,
+     * above it when it would pass the bottom, never past the top-left.
+     */
+    static fit(x, y, width, height, windowWidth, windowHeight, margin = 4) {
+        const left = x + width + margin > windowWidth ? x - width : x;
+        const top = y + height + margin > windowHeight ? y - height : y;
+        return {
+            x: Math.max(margin, Math.min(left, windowWidth - width - margin)),
+            y: Math.max(margin, Math.min(top, windowHeight - height - margin)),
+        };
+    }
+
+    /**
+     * Where a submenu opens beside its item (the item's box `{left, right, top}`),
+     * to be all inside the window: to the right, or to the left when the right
+     * would pass the edge (and there is more room on the left); level with the
+     * item, or lifted by as much as it would pass the bottom. `top` is relative
+     * to the item, as the submenu is positioned.
+     */
+    static submenuPlacement(item, width, height, windowWidth, windowHeight, margin = 4) {
+        const fitsRight = item.right + width + margin <= windowWidth;
+        const side = fitsRight || item.left < windowWidth - item.right ? 'right' : 'left';
+        const top = -4;
+        const overflow = item.top + top + height + margin - windowHeight;
+        return { side, top: overflow > 0 ? Math.max(top - overflow, margin - item.top) : top };
+    }
+
+    static close() {
+        const open = PopupMenu._open;
+        if (!open) return;
+        open.menu.remove();
+        open.doc.removeEventListener('click', open.dismiss);
+        open.doc.removeEventListener('scroll', open.dismiss, { capture: true });
+        open.doc.removeEventListener('keydown', open.onKey);
+        PopupMenu._open = null;
+    }
+
+    static get isOpen() {
+        return !!PopupMenu._open;
+    }
+
+    // The text colour is set with the background: inherited from a dark-themed page it was light
+    // grey on this white panel, and every item but a disabled or danger one was unreadable.
+    static _panelStyle = {
+        background: '#fff', color: '#222', border: '1px solid #ccc', borderRadius: '3px', boxShadow: '0 2px 8px rgba(0,0,0,0.2)',
+        zIndex: '10000', minWidth: '170px', fontSize: '12px', fontFamily: 'sans-serif', padding: '4px 0',
+    };
+
+    static _panel(items, doc) {
+        return { attrs: { role: 'menu' }, children: items.map(item => PopupMenu._item(item, doc)) };
+    }
+
+    static _item(item, doc) {
+        if (item.separator) return { attrs: { role: 'separator' }, style: { borderTop: '1px solid #ddd', margin: '4px 0' } };
+        const hover = item.danger ? '#ffe8e8' : '#f0f0f0';
+        const base = {
+            attrs: { role: 'menuitem', 'aria-disabled': item.disabled ? 'true' : null, 'aria-checked': item.checked != null ? String(!!item.checked) : null },
+            style: {
+                padding: '7px 14px', cursor: item.disabled ? 'default' : 'pointer', position: 'relative', whiteSpace: 'nowrap',
+                color: item.disabled ? '#aaa' : item.danger ? '#cc3333' : '', background: item.checked ? '#e3f2fd' : '',
+            },
+        };
+        if (item.items) {
+            let sub;
+            return {
+                ...base,
+                attrs: { ...base.attrs, 'aria-haspopup': 'menu' },
+                on: {
+                    mouseenter: (e) => {
+                        e.currentTarget.style.background = hover;
+                        sub.style.display = 'block';
+                        // Opened near the window's right or bottom edge, it opens left, or lifts.
+                        const win = e.currentTarget.ownerDocument.defaultView;
+                        const box = sub.getBoundingClientRect?.();
+                        if (!win || !box?.width) return;
+                        const at = PopupMenu.submenuPlacement(e.currentTarget.getBoundingClientRect(), box.width, box.height, win.innerWidth, win.innerHeight);
+                        Object.assign(sub.style, at.side === 'left' ? { left: 'auto', right: '100%' } : { left: '100%', right: 'auto' }, { top: `${at.top}px` });
+                    },
+                    mouseleave: (e) => { e.currentTarget.style.background = ''; sub.style.display = 'none'; },
+                    click: (e) => e.stopPropagation(),
+                },
+                children: [
+                    `${item.label} ▸`,
+                    {
+                        ...PopupMenu._panel(item.items, doc),
+                        style: { ...PopupMenu._panelStyle, position: 'absolute', left: '100%', top: '-4px', display: 'none' },
+                        ref: (n) => { sub = n; },
+                    },
+                ],
+            };
+        }
+        return {
+            ...base,
+            text: item.label,
+            on: {
+                mouseenter: (e) => { if (!item.disabled) e.currentTarget.style.background = hover; },
+                mouseleave: (e) => { e.currentTarget.style.background = item.checked ? '#e3f2fd' : ''; },
+                click: (e) => {
+                    e.stopPropagation();
+                    if (item.disabled) return;
+                    PopupMenu.close();
+                    item.action();
+                },
+            },
+        };
+    }
+}