flexdesk 0.17.18 → 0.18.1

package/src/charts/plot_config_editor.js

@@ -28,6 +28,14 @@
  * added. A 2D chart type removes the z axis (`zAxis: null`, as in
  * makeDefaultSubplot).
  *
+ * `hide` takes parts of the editor away, for an embedder whose plots never use
+ * them: '3d' (the 3D chart types and the z axis), 'stackGroup' (a series' stack
+ * group), 'xAxis' (the x axis section; the subplot then plots against time).
+ *
+ * A reference line's value is a number. With `constantsProvider` it may also name
+ * a constant: the box offers the names, and stores a name as a string, which
+ * renderPlotGrid's `resolveConstant` turns into a value at each draw.
+ *
  * Series names come from `seriesProvider`, through an AutocompleteField per
  * picker: it is asked `{ value, role, subplot }` (`role` is 'series', 'x' or
  * 'z') and answers AutocompleteField items (`{ label, insertText?, type? }`)
@@ -43,6 +51,7 @@
  */
 
 import { AutocompleteField } from '../ui/components/autocomplete_field.js';
+import { attachInputOptions } from '../ui/components/combobox.js';
 import { ColorField } from '../ui/components/color_field.js';
 import { ToggleField } from '../ui/components/toggle_field.js';
 import { selectBox } from '../ui/components/choice_controls.js';
@@ -55,6 +64,7 @@ const CHART_TYPE_OPTIONS = Object.freeze([
     { group: '2D', options: CHART_TYPES_2D },
     { group: '3D', options: CHART_TYPES_3D },
 ]);
+const HIDEABLE = Object.freeze(['3d', 'stackGroup', 'xAxis']);
 const SCALES = Object.freeze([{ value: 'linear', label: 'Linear' }, { value: 'log', label: 'Log' }]);
 const POSITIONS = Object.freeze([{ value: 'left', label: 'Left' }, { value: 'right', label: 'Right' }]);
 const DASHES = Object.freeze([
@@ -200,6 +210,10 @@ let editorCount = 0;
  *        or return an ARRAY of field specs `{ label: string, control: HTMLElement,
  *        hint? }` / `{ label: string, render(slot) => { dispose? } | void, hint? }`,
  *        laid out after anything drawn into `el`. A bad spec is skipped with a warning.
+ * @param {Array<'3d'|'stackGroup'|'xAxis'>} [options.hide] - Parts of the editor not to
+ *        draw. See the file's header. Any other name throws.
+ * @param {Function} [options.constantsProvider] - `() => [{ name, value, label?, group? }]`:
+ *        the names a reference line's value may take, asked each time the list is drawn.
  * @param {Object} [options.logger] - Given to every AutocompleteField (provider errors);
  *   its `warn` also hears a part (an `extraSeriesFields` handle, say) that throws on dispose.
  * @returns {{ dispose: Function, refresh: Function, selectSubplot: Function,
@@ -212,9 +226,15 @@ function renderPlotConfigEditor(container, config, options = {}) {
         overlaySources: null,
         seriesTransforms: null,
         extraSeriesFields: null,
+        hide: [],
+        constantsProvider: null,
         logger: null,
         ...options,
     };
+    for (const part of opts.hide) {
+        if (!HIDEABLE.includes(part)) throw new TypeError(`[plot config editor] cannot hide "${part}"`);
+    }
+    const hidden = new Set(opts.hide);
     const editorId = `twm-plot-config-${++editorCount}`;
     let fieldCount = 0;
     let active = 0;
@@ -380,6 +400,7 @@ function renderPlotConfigEditor(container, config, options = {}) {
 
     function normalise(sp) {
         if (!sp.xAxis) sp.xAxis = { useTime: true, variable: '' };
+        if (hidden.has('xAxis')) sp.xAxis.useTime = true;
         if (!Array.isArray(sp.yAxes) || !sp.yAxes.length) sp.yAxes = [makeDefaultYAxis(0)];
         for (const axis of sp.yAxes) if (!Array.isArray(axis.series)) axis.series = [];
         if (is3DChart(sp.chartType) && !sp.zAxis) sp.zAxis = makeZAxis();
@@ -403,9 +424,9 @@ function renderPlotConfigEditor(container, config, options = {}) {
             section('Subplot', field('Title', textInput(sp.displayName, (v) => { sp.displayName = v; notify(); },
                                                         { placeholder: 'Untitled' }))),
             section('Display', ...displayFields(sp)),
-            section('X axis', ...xAxisFields(sp)),
+            hidden.has('xAxis') ? null : section('X axis', ...xAxisFields(sp)),
             section('Y axes', yAxesEditor(sp, is3D, overlaySources)),
-            is3D ? section('Z axis', ...zAxisFields(sp)) : null,
+            is3D && !hidden.has('3d') ? section('Z axis', ...zAxisFields(sp)) : null,
             section('Reference lines', referenceLinesEditor(sp)),
             section('Shaded bands', shadedBandsEditor(sp)),
             transformsSection(sp),
@@ -414,7 +435,7 @@ function renderPlotConfigEditor(container, config, options = {}) {
 
     function displayFields(sp) {
         return [
-            field('Chart type', select(CHART_TYPE_OPTIONS, sp.chartType ?? 'line', (v) => {
+            field('Chart type', select(hidden.has('3d') ? CHART_TYPES_2D : CHART_TYPE_OPTIONS, sp.chartType ?? 'line', (v) => {
                 const was3D = is3DChart(sp.chartType);
                 sp.chartType = v;
                 const now3D = is3DChart(v);
@@ -543,9 +564,11 @@ function renderPlotConfigEditor(container, config, options = {}) {
             field('Width', numberInput(s.lineWidth ?? 2, (v) => { s.lineWidth = v ?? 2; notify(); },
                                        { placeholder: '2', label: 'Line width', min: 1, max: 10, step: 1 })),
             field('Dash', select(DASHES, s.lineStyle ?? 'solid', (v) => { s.lineStyle = v; notify(); }, { label: 'Dash' })),
-            field('Stack group', textInput(s.stackGroup, (v) => { s.stackGroup = v || null; notify(); },
-                                           { placeholder: 'None', label: 'Stack group' })),
         );
+        if (!hidden.has('stackGroup')) {
+            fields.appendChild(field('Stack group', textInput(s.stackGroup, (v) => { s.stackGroup = v || null; notify(); },
+                                                              { placeholder: 'None', label: 'Stack group' })));
+        }
         if (opts.extraSeriesFields) fields.appendChild(extraFields(sp, axis, s));
         if (opts.overlaySources) fields.appendChild(overlayEditor(s, overlaySources));
         row.append(head, fields);
@@ -655,6 +678,67 @@ function renderPlotConfigEditor(container, config, options = {}) {
         return wrap;
     }
 
+    /**
+     * A reference line's value as a number or a constant's name. What was typed
+     * settles on change, on Enter or Tab, or on a pick; a typed number stays a number
+     * even when it is part of a constant's name, so Enter does not take that row.
+     */
+    function constantValueField(line) {
+        const wrap = el('div', 'twm-plot-config__constant');
+        const input = el('input', 'twm-plot-config__input');
+        input.type = 'text';
+        input.spellcheck = false;
+        input.placeholder = 'Number or name';
+        input.setAttribute('aria-label', 'Value');
+        input.value = line.value ?? '';
+        const now = el('span', 'twm-plot-config__constant-value');
+        wrap.append(input, now);
+
+        const isNumber = (text) => text !== '' && Number.isFinite(Number(text));
+        const sayValue = () => {
+            const named = opts.constantsProvider().find((c) => c.name === input.value.trim());
+            now.textContent = named ? `= ${named.value}` : '';
+        };
+        const settle = () => {
+            const text = input.value.trim();
+            const next = isNumber(text) ? Number(text) : text || null;
+            sayValue();
+            if (next === (line.value ?? null)) return;
+            line.value = next;
+            notify();
+        };
+        const offered = (query) => {
+            const words = (query ?? '').trim().toLowerCase();
+            const groups = new Map();
+            for (const c of opts.constantsProvider()) {
+                const text = c.label ?? c.name;
+                if (words && !`${c.name} ${text}`.toLowerCase().includes(words)) continue;
+                if (!groups.has(c.group)) groups.set(c.group, []);
+                groups.get(c.group).push({ value: c.name, label: text, hint: `= ${c.value}` });
+            }
+            return [...groups].flatMap(([group, rows]) => (group ? [{ group, options: rows }] : rows));
+        };
+        const list = attachInputOptions(input, {
+            options: offered,
+            debounce: 0,
+            autoHighlight: true,
+            isCandidate: (typed) => isNumber(typed.trim()),
+            openOnFocus: true,
+            isCurrent: (option) => option.value === input.value.trim(),
+            onPick: (option) => {
+                input.value = option.value;
+                settle();
+            },
+            onSettle: settle,
+        });
+        input.addEventListener('change', settle);
+        // After the list's own keys, which take Enter while a row is active.
+        input.addEventListener('keydown', (event) => { if (event.key === 'Enter') settle(); });
+        track(() => list.destroy());
+        sayValue();
+        return wrap;
+    }
+
     function referenceLinesEditor(sp) {
         const axisOptions = sp.yAxes.map((a, i) => ({ value: a.id, label: a.label || `Y axis ${i + 1}` }));
         return listEditor(sp, 'referenceLines', {
@@ -663,7 +747,9 @@ function renderPlotConfigEditor(container, config, options = {}) {
             fields: (line) => [
                 select(axisOptions, line.yAxisId ?? sp.yAxes[0].id, (v) => { line.yAxisId = v; notify(); },
                        { label: 'Axis' }),
-                numberInput(line.value, (v) => { line.value = v; notify(); }, { placeholder: 'Value', label: 'Value' }),
+                opts.constantsProvider
+                    ? constantValueField(line)
+                    : numberInput(line.value, (v) => { line.value = v; notify(); }, { placeholder: 'Value', label: 'Value' }),
                 textInput(line.label, (v) => { line.label = v; notify(); }, { placeholder: 'Label', label: 'Label' }),
                 colorField(line.color, (v) => { if (v) line.color = v; else delete line.color; }, 'Colour'),
                 select(DASHES, line.lineStyle ?? 'dashed', (v) => { line.lineStyle = v; notify(); }, { label: 'Dash' }),

package/src/charts/plot_grid.js

@@ -91,6 +91,9 @@ function emptyMessageFor(message, subplot, results, index) {
  * @param {Object} [options]
  * @param {Function} [options.resolveSeries] - `(series, results, subplot) => { y, x? } | null`;
  *        default resolveSeriesData. Also resolves the x variable, as `{ variable }`.
+ * @param {Function} [options.resolveConstant] - `(name) => number | undefined`: the value of a
+ *        reference line that stores a name (renderPlotConfigEditor's `constantsProvider`),
+ *        asked at each draw. A name it does not know draws no line; so does any name without it.
  * @param {Object} [options.overlays] - `{ [series.id]: { years, values } }`, drawn for
  *        every series with an `overlay` description.
  * @param {Object} [options.seriesTransforms] - `{ [id]: transform }` (series_transforms.js).
@@ -326,7 +329,9 @@ function renderPlotGrid(container, plotConfig, results, options = {}) {
             ? 'top' : (sp.legendPosition ?? 'hidden');
         const xRange = !useX && time.length >= 2 ? [time[0], time[time.length - 1]] : undefined;
         const { shapes, annotations } = buildOverlayShapes({
-            referenceLines: sp.referenceLines,
+            referenceLines: (sp.referenceLines ?? []).map((line) => (typeof line.value === 'string'
+                ? { ...line, value: opts.resolveConstant?.(line.value) }
+                : line)),
             shadedBands: sp.shadedBands,
             yRefByAxisId,
         });

package/src/flow/kit/dom.js

@@ -1,27 +1,16 @@
 /**
- * THE KIT'S SMALL DOM HELPERS, AND ITS ONE POPOVER.
+ * THE KIT'S SMALL DOM HELPERS, AND ITS POPOVER.
  *
  * Everything here builds elements; nothing here reads the network, storage or
- * a consumer's vocabulary. The popover is the step picker's and *Insert a
- * value*'s shell (36 §3.5, §3.7):
- *
- *  - it is appended to FlexDesk's modal host (`modalHost()`, C25) or to
- *    `document.body` — the same question a modal and a context menu ask, so a
- *    consumer spanning two browser windows gets it in the window it set;
- *  - it is `position: fixed`, placed under its anchor (above when there is no
- *    room below) and CLAMPED to the viewport;
- *  - it is dismissed by a press outside it, by Escape, or by `close()`, and
- *    **it returns focus to its anchor** when it closes with focus inside it —
- *    a picker that drops focus on `<body>` drops it where an editor's keys
- *    never arrive — except when focus has just left it by Tab, which the
- *    pickers close it for (`'blur'`): that focus is going where it was sent;
- *  - there is ONE at a time: opening a second closes the first, and opening one
- *    from the anchor that holds the open one closes it (a toggle);
- *  - `closeFlowPopovers()` closes whichever is open, which is what an editor's
- *    `destroy()` calls so that nothing it opened outlives it.
+ * a consumer's vocabulary. The popover, the step picker's and *Insert a value*'s
+ * shell (36 §3.5, §3.7), is FlexDesk's `openPopover`, which says how it is placed,
+ * dismissed and toggled and that it returns focus to its anchor: a picker that
+ * drops focus on `<body>` drops it where an editor's keys never arrive. What the
+ * kit adds is `closeFlowPopovers()`, which closes whichever of its own is open:
+ * what an editor's `destroy()` calls so that nothing it opened outlives it.
  */
 
-import { modalHost } from '../../ui/components/modal.js';
+import { openPopover as openAnchoredPopover } from '../../ui/components/popover.js';
 
 /** The category tones (36 §3.1, §3.12); the stylesheet maps each to tokens. */
 export const TONES = Object.freeze(['violet', 'teal', 'amber', 'grey', 'blue', 'indigo']);
@@ -81,118 +70,38 @@ export function uid(stem = 'flow') {
 
 // ── the popover ──────────────────────────────────────────────────────────
 
-const EDGE = 8;
-const GAP = 4;
-let ACTIVE = null;
+/** The kit's open popovers, oldest first. */
+const OPEN = [];
 
-/** Close whichever kit popover is open. */
+/** Close every kit popover that is open. */
 export function closeFlowPopovers() {
-    ACTIVE?.close('closed');
+    OPEN[0]?.close('closed');
 }
 
-/** The open popover's element, or null — for a test. */
+/** The open popover's element (the innermost's), or null — for a test. */
 export function openFlowPopover() {
-    return ACTIVE ? ACTIVE.el : null;
+    return OPEN.length ? OPEN[OPEN.length - 1].el : null;
 }
 
 /**
- * Put `content` in a popover under `anchor`.
+ * FlexDesk's popover (`openPopover` in `ui/components/popover.js`), wearing the
+ * kit's class and remembered so that an editor can close what it opened.
  *
- * @param {object} o
- * @param {HTMLElement} o.anchor     what opened it; focus returns here
- * @param {HTMLElement} o.content    the popover's body
- * @param {string} o.label           its accessible name (`role="dialog"`)
- * @param {string} [o.className]     an extra block class
- * @param {(reason: string) => void} [o.onClose]  after it is gone
- * @param {HTMLElement} [o.focus]    what takes focus on open
- * @returns {{el: HTMLElement, close: (reason?: string) => void, reposition: () => void, toggled: boolean}}
- *          `toggled` is true when the call only CLOSED the popover its anchor held.
+ * @param {object} o  What `openPopover` takes.
+ * @returns {{el: HTMLElement|null, close: (reason?: string) => void, reposition: () => void, toggled: boolean}}
+ *          `el` is null when nothing opened; `toggled` is true when the call only
+ *          CLOSED the popover its anchor held.
  */
-export function openPopover({ anchor, content, label, className = '', onClose = null, focus = null }) {
-    if (ACTIVE && anchor && ACTIVE.anchor === anchor) {
-        ACTIVE.close('toggle');
-        return { el: null, close() {}, reposition() {}, toggled: true };
-    }
-    ACTIVE?.close('replaced');
-
-    const pop = el('div', `twm-flow-popover${className ? ` ${className}` : ''}`);
-    pop.setAttribute('role', 'dialog');
-    pop.setAttribute('aria-label', label || '');
-    pop.tabIndex = -1;
-    pop.appendChild(content);
-    (modalHost() || document.body).appendChild(pop);
-
-    let closed = false;
-    const place = () => {
-        if (closed) return;
-        // The CLIENT width: a page scrollbar is not room to draw in.
-        const view = { w: document.documentElement.clientWidth || window.innerWidth || 1024,
-                       h: document.documentElement.clientHeight || window.innerHeight || 768 };
-        const a = anchor?.getBoundingClientRect?.() || { left: 0, top: 0, bottom: 0, right: 0 };
-        const box = pop.getBoundingClientRect();
-        // Under the anchor, its left edge on the anchor's; an anchor near the
-        // right edge gets the popover's RIGHT edge on its own instead.
-        let left = a.left;
-        if (left + box.width > view.w - EDGE && a.right - box.width >= EDGE) left = a.right - box.width;
-        let top = a.bottom + GAP;
-        if (top + box.height > view.h - EDGE && a.top - GAP - box.height >= EDGE) top = a.top - GAP - box.height;
-        left = Math.max(EDGE, Math.min(left, view.w - box.width - EDGE));
-        top = Math.max(EDGE, Math.min(top, view.h - box.height - EDGE));
-        pop.style.left = `${Math.round(left)}px`;
-        pop.style.top = `${Math.round(top)}px`;
-    };
-
-    const onPress = (ev) => {
-        if (pop.contains(ev.target)) return;
-        if (anchor && anchor.contains?.(ev.target)) return;   // the anchor's own click toggles
-        handle.close('outside');
-    };
-    const onKey = (ev) => {
-        if (ev.key !== 'Escape') return;
-        ev.preventDefault();
-        ev.stopPropagation();
-        handle.close('escape');
-    };
-    const onResize = () => place();
-    // Placed before its content is drawn — a picker fills its list after this
-    // returns — so it is placed again whenever its size changes, or it would
-    // run past the window's edge.
-    const sized = typeof ResizeObserver === 'function' ? new ResizeObserver(() => place()) : null;
-
-    const handle = {
-        el: pop,
-        anchor,
-        toggled: false,
-        reposition: place,
-        close(reason = 'closed') {
-            if (closed) return;
-            closed = true;
-            const held = pop.contains(document.activeElement) || document.activeElement === document.body;
-            document.removeEventListener('pointerdown', onPress, true);
-            document.removeEventListener('mousedown', onPress, true);
-            pop.removeEventListener('keydown', onKey);
-            window.removeEventListener('resize', onResize);
-            sized?.disconnect();
-            pop.remove();
-            if (ACTIVE === handle) ACTIVE = null;
-            // Focus that LEFT the popover (a Tab out of it) is going somewhere the
-            // reader sent it; taking it back to the anchor would fight that move.
-            if (held && reason !== 'blur' && anchor?.isConnected) anchor.focus?.({ preventScroll: true });
+export function openPopover({ className = '', onClose = null, ...rest }) {
+    const handle = openAnchoredPopover({
+        ...rest,
+        className: `twm-flow-popover${className ? ` ${className}` : ''}`,
+        onClose(reason) {
+            OPEN.splice(OPEN.indexOf(handle), 1);
             onClose?.(reason);
         },
-    };
-    ACTIVE = handle;
-    // The press that OPENED it is still being dispatched; listen from the next turn.
-    setTimeout(() => {
-        if (closed) return;
-        document.addEventListener('pointerdown', onPress, true);
-        document.addEventListener('mousedown', onPress, true);
-    }, 0);
-    pop.addEventListener('keydown', onKey);
-    window.addEventListener('resize', onResize);
-    sized?.observe(pop);
-    place();
-    (focus || pop).focus?.({ preventScroll: true });
+    });
+    if (handle.el) OPEN.push(handle);
     return handle;
 }
 

package/src/flow/kit/step_picker.js

@@ -202,7 +202,7 @@ export function openStepPicker({ anchor, entries = [], categories = [], where =
         anchor, content: root, label: title ?? say(S, 'addStep'), className: 'twm-flow-popover--picker',
         focus: search, onClose: () => settle(result),
     });
-    if (handle.toggled) settle(null);
+    if (!handle.el) settle(null);
     else filter();
     done.close = () => handle.close('closed');
     return done;

package/src/flow/kit/value_picker.js

@@ -231,7 +231,7 @@ export function openValuePicker({ anchor, groups = [], note = null, onPick = nul
         anchor, content: root, label: title ?? say(S, 'insertValue'), className: 'twm-flow-popover--values',
         focus: search, onClose: () => settle(result),
     });
-    if (handle.toggled) settle(null);
+    if (!handle.el) settle(null);
     else paint();
     done.close = () => handle.close('closed');
     return done;

package/src/flow/outline/menu.js

@@ -150,5 +150,5 @@ export function openStepMenu({ anchor, label, items, strings = null, onClose = n
         anchor, content: root, label: label || '', className: 'twm-flow-popover--menu',
         focus: enabled(root)[0] || root, onClose: () => onClose?.(),
     });
-    return { el: root, close: () => handle.close('closed'), toggled: handle.toggled };
+    return { el: handle.el ? root : null, close: () => handle.close('closed'), toggled: handle.toggled };
 }

package/src/git/diff_viewer.js

@@ -0,0 +1,212 @@
+/**
+ * diff_viewer.js — what changed, drawn three ways. Usable alone: it needs no
+ * adapter and knows nothing of git beyond reading a unified diff.
+ *
+ *     FIELDS  named values, `Priority  low → high`. The consumer parses them;
+ *             they arrive as `{ name, from, to }`
+ *     TEXT    line by line, with old and new line numbers and no diff headers,
+ *             from `before`/`after` (compared here) or else from `diff` (read)
+ *     RAW     the `diff` text as it came
+ *
+ *     const viewer = createDiffViewer(el, { before, after, diff, fields });
+ *     viewer.update({ before, after });
+ *     viewer.setView('raw');
+ *     viewer.destroy();
+ *
+ * A view is offered only when its data is there, and the buttons that switch
+ * between views only when there are two or more. Which view shows: the one set
+ * by `view`, `setView` or a click while it stays on offer, else Fields when a
+ * field changed, else Text, else Raw. `setView(null)` hands the choice back.
+ */
+
+import { computeLineDiff, parseUnifiedDiff } from './line_diff.js';
+
+const DEFAULT_LABELS = Object.freeze({
+    fields: 'Fields',
+    text: 'Text',
+    raw: 'Raw',
+    noChanges: 'No differences.',
+    noFields: 'No field changes.',
+    tooLong: 'Too long to compare here.',
+    gap: (hidden) => `${hidden} unchanged line${hidden === 1 ? '' : 's'}`,
+});
+
+function el(tag, className, text) {
+    const n = document.createElement(tag);
+    if (className) n.className = className;
+    if (text !== undefined) n.textContent = text;
+    return n;
+}
+
+/** A field's value as drawn: an absent or empty one reads as a dash. */
+const shownField = (v) => {
+    const s = v === null || v === undefined ? '' : String(v);
+    return s === '' ? '—' : s;
+};
+
+function lineRow(line, labels) {
+    const row = el('div', `twm-diff__line twm-diff__line--${line.kind}`);
+    if (line.kind === 'gap' || line.kind === 'hunk' || line.kind === 'meta' || line.kind === 'file') {
+        row.textContent = line.kind === 'gap' ? labels.gap(line.hidden) : line.text;
+        return row;
+    }
+    row.append(
+        el('span', 'twm-diff__n', line.oldLine === null ? '' : String(line.oldLine)),
+        el('span', 'twm-diff__n', line.newLine === null ? '' : String(line.newLine)),
+        el('span', 'twm-diff__sign', line.kind === 'add' ? '+' : line.kind === 'del' ? '-' : ''),
+        el('span', 'twm-diff__text', line.text),
+    );
+    return row;
+}
+
+/**
+ * @param {HTMLElement} host
+ * @param {Object} [options]
+ * @param {string} [options.before] - The old text. With `after`, drawn by comparing the two.
+ * @param {string} [options.after] - The new text.
+ * @param {string} [options.diff] - A unified diff: the Raw view, and the Text view when there is no `before`/`after`.
+ * @param {Array<{name: string, from?: *, to?: *}>} [options.fields] - The Fields view's rows.
+ * @param {number} [options.beforeStart=1] - The line number of `before`'s first line.
+ * @param {number} [options.afterStart=1] - The line number of `after`'s first line.
+ * @param {number} [options.context=3] - Unchanged lines kept around each change.
+ * @param {number} [options.maxLines] - Past this many differing lines a side, the texts are not compared.
+ * @param {'fields'|'text'|'raw'} [options.view] - The view to show while it is on offer.
+ * @param {Object} [options.labels] - Words to replace: `fields`, `text`, `raw`, `noChanges`, `noFields`, `tooLong`, `gap(hidden)`.
+ * @param {(view: string) => void} [options.onViewChange] - Told when a click changes the view.
+ * @returns {{ el: HTMLElement, update(data: Object): void, setView(view: string|null): void,
+ *   view(): string|null, showMessage(text: string): void, destroy(): void }}
+ */
+export function createDiffViewer(host, options = {}) {
+    const { context = 3, maxLines, onViewChange = null } = options;
+    const labels = { ...DEFAULT_LABELS, ...options.labels };
+
+    const root = el('div', 'twm-diff');
+    const switcher = el('div', 'twm-diff__views');
+    switcher.setAttribute('role', 'group');
+    switcher.setAttribute('aria-label', 'Diff view');
+    const body = el('div', 'twm-diff__body');
+    root.append(switcher, body);
+    host.appendChild(root);
+
+    let data = {};
+    let chosen = options.view ?? null;
+    let textLines;     // this data's Text view; undefined until first drawn
+    let current = null;
+
+    const hasPair = () => typeof data.before === 'string' || typeof data.after === 'string';
+
+    const linesOfText = () => {
+        if (textLines !== undefined) return textLines;
+        textLines = hasPair()
+            ? computeLineDiff(data.before, data.after, {
+                context,
+                ...(maxLines === undefined ? {} : { maxLines }),
+                beforeStart: data.beforeStart ?? 1,
+                afterStart: data.afterStart ?? 1,
+            })
+            : parseUnifiedDiff(data.diff);
+        return textLines;
+    };
+
+    const offered = () => {
+        const out = [];
+        if (Array.isArray(data.fields)) out.push('fields');
+        if (hasPair() || (typeof data.diff === 'string' && linesOfText().length > 0)) out.push('text');
+        if (typeof data.diff === 'string') out.push('raw');
+        return out;
+    };
+
+    const pick = (views) => {
+        if (chosen && views.includes(chosen)) return chosen;
+        if (views.includes('fields') && data.fields.length > 0) return 'fields';
+        if (views.includes('text')) return 'text';
+        return views[0] ?? null;
+    };
+
+    const message = (text) => {
+        body.replaceChildren(el('div', 'twm-diff__message', text));
+    };
+
+    const drawFields = () => {
+        if (data.fields.length === 0) { message(labels.noFields); return; }
+        const grid = el('div', 'twm-diff__fields');
+        for (const field of data.fields) {
+            const values = el('span', 'twm-diff__field-values');
+            const arrow = el('span', 'material-symbols-outlined twm-diff__field-arrow', 'arrow_forward');
+            arrow.setAttribute('aria-hidden', 'true');
+            values.append(
+                el('span', 'twm-diff__field-from', shownField(field.from)),
+                arrow,
+                el('span', 'twm-diff__field-to', shownField(field.to)),
+            );
+            grid.append(el('span', 'twm-diff__field-name', String(field.name)), values);
+        }
+        body.replaceChildren(grid);
+    };
+
+    const drawText = () => {
+        const lines = linesOfText();
+        if (lines === null) {
+            message(typeof data.diff === 'string' ? `${labels.tooLong} See ${labels.raw}.` : labels.tooLong);
+            return;
+        }
+        if (lines.length === 0) { message(labels.noChanges); return; }
+        const list = el('div', 'twm-diff__lines');
+        list.append(...lines.map((line) => lineRow(line, labels)));
+        body.replaceChildren(list);
+    };
+
+    const drawRaw = () => {
+        if (data.diff === '') { message(labels.noChanges); return; }
+        body.replaceChildren(el('pre', 'twm-diff__raw', data.diff));
+    };
+
+    const draw = () => {
+        const views = offered();
+        current = pick(views);
+        switcher.replaceChildren(...(views.length > 1 ? views.map((v) => {
+            const b = el('button', 'twm-diff__view', labels[v]);
+            b.type = 'button';
+            b.setAttribute('aria-pressed', String(v === current));
+            b.addEventListener('click', () => {
+                chosen = v;
+                draw();
+                onViewChange?.(v);
+            });
+            return b;
+        }) : []));
+        switcher.hidden = views.length <= 1;
+        if (current === 'fields') drawFields();
+        else if (current === 'text') drawText();
+        else if (current === 'raw') drawRaw();
+        else message(labels.noChanges);
+    };
+
+    const update = (next) => {
+        data = next ?? {};
+        textLines = undefined;
+        draw();
+    };
+
+    update(options);
+
+    return {
+        el: root,
+        update,
+        setView(view) {
+            chosen = view;
+            draw();
+        },
+        view: () => current,
+        /** Words in place of the diff, while it loads or when it could not be read. The next update replaces them. */
+        showMessage(text) {
+            switcher.replaceChildren();
+            switcher.hidden = true;
+            current = null;
+            message(text);
+        },
+        destroy() {
+            root.remove();
+        },
+    };
+}