@peter.prib/renderengine 0.0.0-stage → 0.2.0

package/src/charting/templates/outline.js

@@ -0,0 +1,59 @@
+/**
+ * Pure outline geometry for templates: curve sampling and ray/outline exits.
+ * Outlines are closed polygons given as [[x, y], ...]; curves are sampled
+ * finely enough (sub-pixel at diagram sizes) for edge attachment.
+ */
+
+/** Points along an elliptical arc from angle `from` to `to` (radians), endpoints included. */
+export function sampleArc(cx, cy, rx, ry, from, to, segments) {
+    return Array.from({ length: segments + 1 }, (_, i) => {
+        const a = from + ((to - from) * i) / segments;
+        return [cx + rx * Math.cos(a), cy + ry * Math.sin(a)];
+    });
+}
+
+/** Points along a cubic bezier, excluding the start point. */
+export function sampleCubic([x0, y0], [x1, y1], [x2, y2], [x3, y3], segments = 8) {
+    return Array.from({ length: segments }, (_, i) => {
+        const t = (i + 1) / segments, m = 1 - t;
+        const a = m * m * m, b = 3 * m * m * t, c = 3 * m * t * t, d = t * t * t;
+        return [a * x0 + b * x1 + c * x2 + d * x3, a * y0 + b * y1 + c * y2 + d * y3];
+    });
+}
+
+/** Points along a quadratic bezier, excluding the start point. */
+export function sampleQuad([x0, y0], [x1, y1], [x2, y2], segments = 8) {
+    return Array.from({ length: segments }, (_, i) => {
+        const t = (i + 1) / segments, m = 1 - t;
+        return [m * m * x0 + 2 * m * t * x1 + t * t * x2, m * m * y0 + 2 * m * t * y1 + t * t * y2];
+    });
+}
+
+/** Rotate vector (x, y) by `degrees`, clockwise on screen (the SVG `rotate()` sense). */
+export function rotateVector(x, y, degrees) {
+    if (!degrees) return [x, y];
+    const r = (degrees * Math.PI) / 180, c = Math.cos(r), s = Math.sin(r);
+    return [x * c - y * s, x * s + y * c];
+}
+
+/**
+ * Distance from (cx, cy) along unit direction (ux, uy) to where the ray last
+ * crosses the polygon — the point a line arriving from outside first touches,
+ * which for concave outlines (star, cloud) is the outermost crossing. 0 if the
+ * ray never crosses it.
+ */
+export function rayExitDistance(points, cx, cy, ux, uy) {
+    let best = 0;
+    for (let i = 0; i < points.length; i++) {
+        const [ax, ay] = points[i];
+        const [bx, by] = points[(i + 1) % points.length];
+        const ex = bx - ax, ey = by - ay;
+        const denom = ux * ey - uy * ex;
+        if (Math.abs(denom) < 1e-12) continue;
+        const qx = ax - cx, qy = ay - cy;
+        const t = (qx * ey - qy * ex) / denom;
+        const s = (qx * uy - qy * ux) / denom;
+        if (t > best && s >= -1e-9 && s <= 1 + 1e-9) best = t;
+    }
+    return best;
+}

package/src/charting/templates/svg.js

@@ -0,0 +1,19 @@
+const SVG_NS = 'http://www.w3.org/2000/svg';
+
+/** Create an SVG element; null/undefined attribute values are skipped. */
+export function svgEl(tag, attrs = {}, doc = document) {
+    const node = doc.createElementNS(SVG_NS, tag);
+    for (const [k, v] of Object.entries(attrs)) {
+        if (v != null) node.setAttribute(k, String(v));
+    }
+    return node;
+}
+
+/** Serialize [[x, y], ...] into an SVG `points` attribute value. */
+export function pointsAttr(points) {
+    return points.map(([x, y]) => `${round(x)},${round(y)}`).join(' ');
+}
+
+export function round(n) {
+    return Math.round(n * 100) / 100;
+}

package/src/charting/textToShapes.js

@@ -0,0 +1,61 @@
+/**
+ * Text to shapes: a list of names (pasted from a document, a spreadsheet, a
+ * mail) read as shapes to add, one definition for every editor.
+ *
+ * - One name per line; a tab after it starts its documentation. Blank lines
+ *   are skipped, and bullets and numbering ("- ", "* ", "• ", "1. ", "2) ")
+ *   taken off.
+ * - A first line `types=<type>,<type>,...` makes each tab-separated column
+ *   that type, a line being a row of shapes (as from a spreadsheet's columns).
+ *
+ * `parseShapeText(text, { defaultType })` returns `{ items, rows }`: every
+ * item `{ name, type, documentation? }`, and with `types=` the rows they came
+ * in (else null: the editor lays them out in a grid).
+ */
+
+const BULLET = /^\s*(?:[-*•▪◦]\s+|\d+[.)]\s+)/;
+
+/**
+ * @param {string} text
+ * @param {Object} [options]
+ * @param {string} [options.defaultType] - The type of a shape from a plain list
+ * @param {(type: string) => (string|null)} [options.resolveType] - A `types=` name as the editor's type key, or null if unknown
+ * @returns {{items: Array<{name: string, type: string, documentation?: string}>, rows: (Array<Array<Object>>|null), unknownTypes: Array<string>}}
+ */
+export function parseShapeText(text, { defaultType = null, resolveType = (t) => t } = {}) {
+    const lines = String(text ?? '').split(/\r?\n/).map(l => l.replace(/\s+$/, '')).filter(l => l.trim());
+    const header = lines[0]?.trim().match(/^types\s*=\s*(.+)$/i);
+    if (header) {
+        const named = header[1].split(',').map(t => t.trim()).filter(Boolean);
+        const types = named.map(t => resolveType(t));
+        const unknownTypes = named.filter((t, i) => !types[i]);
+        const rows = lines.slice(1).map(line => line.split('\t')
+            .map((cell, i) => ({ name: cell.replace(BULLET, '').trim(), type: types[i] }))
+            .filter(item => item.name && item.type));
+        return { items: rows.flat(), rows: rows.filter(r => r.length), unknownTypes };
+    }
+    const items = lines.map(line => {
+        const [name, ...rest] = line.replace(BULLET, '').split('\t');
+        const documentation = rest.join('\t').trim();
+        return { name: name.trim(), type: defaultType, ...(documentation && { documentation }) };
+    }).filter(item => item.name);
+    return { items, rows: null, unknownTypes: [] };
+}
+
+/**
+ * Where the parsed shapes go, their top-left corner at `at`: rows as they
+ * came, or a grid as square as it goes. Each item gains `x` and `y`, its
+ * centre.
+ * @param {{items, rows}} parsed
+ * @param {{x: number, y: number}} at
+ * @param {{width?: number, height?: number, gap?: number}} [size] - Each shape's size
+ */
+export function placeShapes({ items, rows }, at, { width = 120, height = 55, gap = 30 } = {}) {
+    const grid = rows ?? (() => {
+        const columns = Math.ceil(Math.sqrt(items.length));
+        const out = [];
+        items.forEach((item, i) => { (out[Math.floor(i / columns)] ??= []).push(item); });
+        return out;
+    })();
+    return grid.flatMap((row, r) => row.map((item, c) => ({ ...item, x: at.x + c * (width + gap) + width / 2, y: at.y + r * (height + gap) + height / 2 })));
+}

package/src/charting/toolbar/ToolbarButton.js

@@ -0,0 +1,38 @@
+import { ToolbarItem } from './ToolbarItem.js';
+
+/** ToolbarButton — runs an action; with `active` it renders as a toggle. */
+export class ToolbarButton extends ToolbarItem {
+    /**
+     * @param {string} label
+     * @param {() => void} action
+     * @param {Object} [options]
+     * @param {string} [options.title]
+     * @param {() => boolean} [options.active] - Toggle state, shown pressed when true
+     */
+    constructor(label, action, { title, active } = {}) {
+        super();
+        this.label = label;
+        this.action = action;
+        this.title = title;
+        this.active = active;
+    }
+
+    spec(bar) {
+        return {
+            tag: 'button',
+            text: this.label,
+            attrs: { type: 'button', title: this.title, 'aria-pressed': this.active ? String(!!this.active()) : null },
+            style: ToolbarItem.buttonStyle,
+            on: { click: () => bar.run(this.action) },
+            ref: (n) => this.refresh(n),
+        };
+    }
+
+    refresh(node) {
+        if (!this.active) return;
+        const on = !!this.active();
+        node.setAttribute('aria-pressed', String(on));
+        node.style.background = on ? '#e3f2fd' : '#fff';
+        node.style.borderColor = on ? '#0066cc' : '#ccc';
+    }
+}

package/src/charting/toolbar/ToolbarCheckbox.js

@@ -0,0 +1,31 @@
+import { ToolbarItem } from './ToolbarItem.js';
+
+/** ToolbarCheckbox — a labelled on/off switch. */
+export class ToolbarCheckbox extends ToolbarItem {
+    /**
+     * @param {string} label
+     * @param {() => boolean} checked
+     * @param {(checked: boolean) => void} onChange
+     */
+    constructor(label, checked, onChange) {
+        super();
+        this.label = label;
+        this.checked = checked;
+        this.onChange = onChange;
+    }
+
+    spec(bar) {
+        return {
+            tag: 'label',
+            style: { display: 'flex', alignItems: 'center', gap: '6px', cursor: 'pointer' },
+            children: [
+                {
+                    tag: 'input',
+                    attrs: { type: 'checkbox', checked: !!this.checked() },
+                    on: { change: (e) => bar.run(() => this.onChange(e.target.checked)) },
+                },
+                this.label,
+            ],
+        };
+    }
+}

package/src/charting/toolbar/ToolbarItem.js

@@ -0,0 +1,19 @@
+/**
+ * ToolbarItem — one control in a MenuBar. Subclasses return an el() spec; the
+ * bar re-renders after an item acts, and calls refresh() on live items when the
+ * editor re-renders, so labels can track state (zoom %, toggles).
+ */
+export class ToolbarItem {
+    /** @returns {Object} el() spec */
+    spec(bar) {
+        throw new Error(`${this.constructor.name} must implement spec()`);
+    }
+
+    /** Update an already-rendered node from current state. */
+    refresh(node) {}
+
+    static buttonStyle = {
+        padding: '4px 10px', border: '1px solid #ccc', borderRadius: '3px', background: '#fff',
+        cursor: 'pointer', fontSize: '13px',
+    };
+}

package/src/charting/toolbar/ToolbarMenu.js

@@ -0,0 +1,36 @@
+import { ToolbarItem } from './ToolbarItem.js';
+import { PopupMenu } from '../PopupMenu.js';
+
+/**
+ * ToolbarMenu — a button that opens a PopupMenu. `items` may be a function,
+ * evaluated each time the menu opens, so labels can reflect current state.
+ */
+export class ToolbarMenu extends ToolbarItem {
+    /**
+     * @param {string} label
+     * @param {Array|(() => Array)} items - PopupMenu items: `{label, action, danger?}` or `{separator: true}`
+     */
+    constructor(label, items) {
+        super();
+        this.label = label;
+        this.items = items;
+    }
+
+    spec(bar) {
+        return {
+            tag: 'button',
+            text: `${this.label} ▾`,
+            attrs: { type: 'button', 'aria-haspopup': 'menu' },
+            style: ToolbarItem.buttonStyle,
+            on: {
+                click: (e) => {
+                    e.stopPropagation();
+                    const r = e.currentTarget.getBoundingClientRect();
+                    const items = (typeof this.items === 'function' ? this.items() : this.items)
+                        .map(item => (item.separator ? item : { ...item, action: () => bar.run(item.action) }));
+                    PopupMenu.show(r.left, r.bottom + 2, items, e.currentTarget.ownerDocument);
+                },
+            },
+        };
+    }
+}

package/src/charting/toolbar/ToolbarSelect.js

@@ -0,0 +1,38 @@
+import { ToolbarItem } from './ToolbarItem.js';
+
+/** ToolbarSelect — a labelled dropdown. */
+export class ToolbarSelect extends ToolbarItem {
+    /**
+     * @param {string} label
+     * @param {() => Array<[string, string, string?]>} choices - `[value, text, title?]`
+     * @param {() => string} value
+     * @param {(value: string) => void} onChange
+     */
+    constructor(label, choices, value, onChange) {
+        super();
+        this.label = label;
+        this.choices = choices;
+        this.value = value;
+        this.onChange = onChange;
+    }
+
+    spec(bar) {
+        const current = this.value();
+        return {
+            tag: 'label',
+            style: { display: 'flex', alignItems: 'center', gap: '6px' },
+            children: [
+                `${this.label}:`,
+                {
+                    tag: 'select',
+                    attrs: { 'aria-label': this.label },
+                    style: { ...ToolbarItem.buttonStyle, padding: '3px 6px', maxWidth: '220px' },
+                    on: { change: (e) => bar.run(() => this.onChange(e.target.value)) },
+                    children: this.choices().map(([v, text, title]) => ({
+                        tag: 'option', attrs: { value: v, title, selected: v === current }, text,
+                    })),
+                },
+            ],
+        };
+    }
+}

package/src/charting/toolbar/ToolbarSeparator.js

@@ -0,0 +1,7 @@
+import { ToolbarItem } from './ToolbarItem.js';
+
+export class ToolbarSeparator extends ToolbarItem {
+    spec() {
+        return { attrs: { role: 'separator' }, style: { width: '1px', alignSelf: 'stretch', background: '#ddd', margin: '0 2px' } };
+    }
+}

package/src/charting/toolbar/ToolbarText.js

@@ -0,0 +1,22 @@
+import { ToolbarItem } from './ToolbarItem.js';
+
+/** ToolbarText — read-only text, recomputed whenever the editor re-renders. */
+export class ToolbarText extends ToolbarItem {
+    /**
+     * @param {() => string} text
+     * @param {Object} [style]
+     */
+    constructor(text, style = {}) {
+        super();
+        this.text = text;
+        this.style = style;
+    }
+
+    spec() {
+        return { tag: 'span', text: this.text(), style: { fontSize: '12px', color: '#555', ...this.style } };
+    }
+
+    refresh(node) {
+        node.textContent = this.text();
+    }
+}

package/src/charting/toolbar/index.js

@@ -0,0 +1,8 @@
+export { ToolbarItem } from './ToolbarItem.js';
+export { ToolbarButton } from './ToolbarButton.js';
+export { ToolbarMenu } from './ToolbarMenu.js';
+export { ToolbarSelect } from './ToolbarSelect.js';
+export { ToolbarCheckbox } from './ToolbarCheckbox.js';
+export { ToolbarText } from './ToolbarText.js';
+export { ToolbarSeparator } from './ToolbarSeparator.js';
+export { pickFile } from './pickFile.js';

package/src/charting/toolbar/pickFile.js

@@ -0,0 +1,14 @@
+/**
+ * Ask the user for one file. Resolves with the File, or null if they cancel
+ * (browsers that report cancel) — callers just stop when there is no file.
+ */
+export function pickFile(accept, doc = document) {
+    return new Promise((resolve) => {
+        const input = doc.createElement('input');
+        input.type = 'file';
+        input.accept = accept;
+        input.addEventListener('change', () => resolve(input.files?.[0] ?? null), { once: true });
+        input.addEventListener('cancel', () => resolve(null), { once: true });
+        input.click();
+    });
+}

package/src/charting/viewDecorations.js

@@ -0,0 +1,85 @@
+import { el } from '../workspace/dom.js';
+
+const DECORATION_CLASSES = ['view-title', 'view-watermark', 'view-watermark-container', 'view-watermark-bg'];
+
+/**
+ * Decorate a diagram's container: background colour/image, a title band and a
+ * watermark. Re-applying replaces the previous title and watermark.
+ *
+ * @param {HTMLElement} container
+ * @param {Object} d
+ * @param {string} [d.background]
+ * @param {string} [d.backgroundImage] - URL
+ * @param {string} [d.title]
+ * @param {'none'|'top'|'bottom'} [d.titlePosition]
+ * @param {string} [d.watermark] - Text
+ * @param {string} [d.watermarkRotation] - e.g. '-45°'
+ * @param {number} [d.watermarkOpacity] - 0–100
+ * @param {'none'|'repeat'|'tile'} [d.watermarkRepeat]
+ * @param {Document} [doc]
+ */
+export function applyViewDecorations(container, d = {}, doc = container.ownerDocument) {
+    // Unset: back to the page's own (another view's are not kept).
+    container.style.backgroundColor = d.background || '';
+    if (d.backgroundImage) {
+        Object.assign(container.style, { backgroundImage: `url('${d.backgroundImage}')`, backgroundSize: 'cover', backgroundPosition: 'center' });
+    } else {
+        container.style.backgroundImage = '';
+    }
+
+    container.querySelectorAll(DECORATION_CLASSES.map(c => `.${c}`).join(', ')).forEach(n => n.remove());
+
+    if (d.title && d.titlePosition && d.titlePosition !== 'none') {
+        const title = el({
+            cls: 'view-title', text: d.title,
+            style: { padding: '8px 12px', textAlign: 'center', fontSize: '16px', fontWeight: 'bold', background: 'rgba(255,255,255,0.95)', borderBottom: '1px solid #ddd' },
+        }, doc);
+        if (d.titlePosition === 'top') container.insertBefore(title, container.firstChild);
+        else container.appendChild(title);
+    }
+
+    if (d.watermark) container.appendChild(watermark(container, d, doc));
+}
+
+function watermark(container, d, doc) {
+    const rotation = d.watermarkRotation || '-45°';
+    const color = `rgba(0,0,0,${(d.watermarkOpacity ?? 20) / 100})`;
+    const layer = { position: 'absolute', pointerEvents: 'none', zIndex: '10' };
+    container.style.position = 'relative';
+
+    if (d.watermarkRepeat === 'repeat') {
+        const spacing = 200;
+        const width = container.offsetWidth || 1000;
+        const height = container.offsetHeight || 1000;
+        const marks = [];
+        for (let y = -height; y < height * 2; y += spacing) {
+            for (let x = -width; x < width * 2; x += spacing) {
+                marks.push({
+                    text: d.watermark,
+                    style: { position: 'absolute', top: `${y}px`, left: `${x}px`, transform: `rotate(${rotation})`, fontSize: '36px', color, fontWeight: 'bold', whiteSpace: 'nowrap' },
+                });
+            }
+        }
+        return el({ cls: 'view-watermark-container', style: { ...layer, inset: '0', overflow: 'hidden' }, children: marks }, doc);
+    }
+
+    if (d.watermarkRepeat === 'tile') {
+        const canvas = doc.createElement('canvas');
+        canvas.width = 200;
+        canvas.height = 200;
+        const ctx = canvas.getContext('2d');
+        ctx.translate(100, 100);
+        ctx.rotate(parseFloat(rotation) * Math.PI / 180);
+        Object.assign(ctx, { fillStyle: color, font: 'bold 24px sans-serif', textAlign: 'center', textBaseline: 'middle' });
+        ctx.fillText(d.watermark, 0, 0);
+        return el({
+            cls: 'view-watermark-bg',
+            style: { ...layer, inset: '0', backgroundImage: `url('${canvas.toDataURL()}')`, backgroundRepeat: 'repeat' },
+        }, doc);
+    }
+
+    return el({
+        cls: 'view-watermark', text: d.watermark,
+        style: { ...layer, top: '50%', left: '50%', transform: `translate(-50%, -50%) rotate(${rotation})`, fontSize: '48px', color, fontWeight: 'bold', whiteSpace: 'nowrap' },
+    }, doc);
+}

package/src/charting/zOrder.js

@@ -0,0 +1,57 @@
+/**
+ * zOrder — one stacking-order algorithm for every diagram editor.
+ *
+ * Items are anything with `id` and `zIndex`. They are drawn in ascending
+ * zIndex, ties in their given order (a stable sort), so that is the order these
+ * functions reason about. Each operation returns the new zIndex of every item
+ * as consecutive integers, which keeps raise/lower exact (no fractional
+ * squeezing) and lets a command undo by restoring the previous values.
+ */
+
+/** Items in drawing order: ascending zIndex, ties in their given order (Array#sort is stable). */
+export function stackingOrder(items) {
+    return [...items].sort((a, b) => (a.zIndex || 0) - (b.zIndex || 0));
+}
+
+/** The four ordering operations, as moves within the drawing order. */
+export const Z_ORDER_OPS = Object.freeze({
+    front: (order, i) => [...order.slice(0, i), ...order.slice(i + 1), order[i]],
+    back: (order, i) => [order[i], ...order.slice(0, i), ...order.slice(i + 1)],
+    raise: (order, i) => (i >= order.length - 1 ? order : [...order.slice(0, i), order[i + 1], order[i], ...order.slice(i + 2)]),
+    lower: (order, i) => (i <= 0 ? order : [...order.slice(0, i - 1), order[i], order[i - 1], ...order.slice(i + 1)]),
+});
+
+/**
+ * New zIndex for every item after applying `op` to the item with `id`.
+ * Pinned items (a background) stay behind every other item: an item moves
+ * within its own layer, so "send to back" stops just above the pinned ones.
+ * @param {Array<{id: string, zIndex?: number}>} items
+ * @param {string} id
+ * @param {'front'|'back'|'raise'|'lower'} op
+ * @param {Object} [options]
+ * @param {(id: string) => boolean} [options.pinned] - Whether an item is pinned to the back
+ * @returns {Map<string, number>|null} null when `id` is not among the items
+ */
+export function reorderedZ(items, id, op, { pinned = () => false } = {}) {
+    const move = Z_ORDER_OPS[op];
+    if (!move) throw new TypeError(`Unknown z-order operation "${op}"`);
+    const order = stackingOrder(items);
+    const back = order.filter(item => pinned(item.id));
+    const rest = order.filter(item => !pinned(item.id));
+    const layer = pinned(id) ? back : rest;
+    const at = layer.findIndex(item => item.id === id);
+    if (at < 0) return null;
+    const moved = move(layer, at);
+    const all = layer === back ? [...moved, ...rest] : [...back, ...moved];
+    return new Map(all.map((item, z) => [item.id, z]));
+}
+
+/**
+ * New zIndex for every item with the pinned ones behind the rest, each layer
+ * keeping its own order: what a view does when items become its background.
+ * @returns {Map<string, number>}
+ */
+export function pinnedBehind(items, pinned) {
+    const order = stackingOrder(items);
+    return new Map([...order.filter(i => pinned(i.id)), ...order.filter(i => !pinned(i.id))].map((item, z) => [item.id, z]));
+}

package/src/csvTable.js

@@ -0,0 +1,61 @@
+/**
+ * CSV as a table: the one CSV reader (archimateCSV.js and the mapped CSV
+ * import both use it). Quoted cells may hold the delimiter, quotes ("") and
+ * line breaks; a byte-order mark is dropped; the delimiter (comma,
+ * semicolon or tab, as spreadsheets in different places write them) is
+ * the one the header line uses most, unless given.
+ */
+
+/** A byte-order mark at the start (spreadsheets write one), dropped. */
+const BOM = new RegExp('^' + String.fromCharCode(0xfeff));
+
+/** The delimiter a header line uses most (outside quotes): ',', ';' or tab. */
+export function guessDelimiter(text) {
+    const counts = { ',': 0, ';': 0, '\t': 0 };
+    let quoted = false;
+    for (const ch of String(text)) {
+        if (ch === '"') quoted = !quoted;
+        else if (!quoted && ch === '\n') break;
+        else if (!quoted && ch in counts) counts[ch]++;
+    }
+    return Object.entries(counts).sort((a, b) => b[1] - a[1])[0][1] ? Object.entries(counts).sort((a, b) => b[1] - a[1])[0][0] : ',';
+}
+
+/**
+ * Every record of a CSV text, as arrays of cells.
+ * @param {string} text
+ * @param {string} [delimiter] - Default: guessDelimiter(text)
+ * @returns {Array<Array<string>>}
+ */
+export function parseCsvRecords(text, delimiter = guessDelimiter(text)) {
+    const s = String(text ?? '').replace(BOM, '');
+    const records = [];
+    let record = [], cell = '', quoted = false, i = 0;
+    const endCell = () => { record.push(cell); cell = ''; };
+    const endRecord = () => { endCell(); if (record.length > 1 || record[0] !== '') records.push(record); record = []; };
+    while (i < s.length) {
+        const ch = s[i];
+        if (quoted) {
+            if (ch === '"' && s[i + 1] === '"') { cell += '"'; i += 2; continue; }
+            if (ch === '"') { quoted = false; i++; continue; }
+            cell += ch; i++; continue;
+        }
+        if (ch === '"' && cell === '') { quoted = true; i++; continue; }
+        if (ch === delimiter) { endCell(); i++; continue; }
+        if (ch === '\r' || ch === '\n') { endRecord(); i += ch === '\r' && s[i + 1] === '\n' ? 2 : 1; continue; }
+        cell += ch; i++;
+    }
+    if (cell !== '' || record.length) endRecord();
+    return records;
+}
+
+/**
+ * A CSV text as its header's columns and a row object per record (a cell a
+ * record lacks is '').
+ * @returns {{columns: Array<string>, rows: Array<Object<string, string>>}}
+ */
+export function parseCsvTable(text, { delimiter } = {}) {
+    const [header = [], ...records] = parseCsvRecords(text, delimiter);
+    const columns = header.map(c => c.trim());
+    return { columns, rows: records.map(cells => Object.fromEntries(columns.map((c, i) => [c, cells[i] ?? '']))) };
+}