flexdesk 0.17.18 → 0.18.0

package/src/ui/components/managed_window.js

@@ -18,6 +18,8 @@
  */
 
 import { getSetting } from '../../core/settings.js';
+import { isInAnchoredLayer } from './anchored_layer.js';
+import { collectFocusable } from '../utils/focusable.js';
 
 /** Where window geometry lives when the embedder names no key. An embedder
  *  that saved geometry under another key keeps it by passing that key to
@@ -70,29 +72,6 @@ let _activeWindows = new Map(); // id -> ManagedWindow instance
  *  the same event reaches it — one Esc must close one window. */
 const _escAnswered = new WeakSet();
 
-/** Collect the focusable elements inside `root`, in DOM order. Used
- *  by the modal focus trap so Tab cycles within the modal frame and
- *  can't escape into the underlying tiles. */
-function _collectFocusable(root) {
-    if (!root) return [];
-    const sel = [
-        'a[href]',
-        'button:not([disabled])',
-        'input:not([disabled]):not([type="hidden"])',
-        'select:not([disabled])',
-        'textarea:not([disabled])',
-        '[tabindex]:not([tabindex="-1"])',
-    ].join(',');
-    return Array.from(root.querySelectorAll(sel)).filter((el) => {
-        // Skip hidden / zero-size elements — Tab visits only what the
-        // user can actually see.
-        if (el.hidden) return false;
-        if (el.closest('[hidden]')) return false;
-        const r = el.getBoundingClientRect();
-        return r.width > 0 || r.height > 0;
-    });
-}
-
 // Global state cache
 let _stateCache = null;
 
@@ -548,12 +527,17 @@ export class ManagedWindow {
         // taskbar can filter on receipt: an in-panel taskbar shows only the
         // windows mounted in its own panel, and the viewport taskbar shows only
         // the ones with no container.
-        window.dispatchEvent(new CustomEvent('managed-window-closed', {
-            detail: { id: this.id, container: this.container }
-        }));
+        this._announce('managed-window-closed', { id: this.id, container: this.container });
         this._release();
     }
 
+    /** Every window event goes out on the page's window, and a window takes only
+     *  an event built by its own `CustomEvent`: Node's global one is refused
+     *  under jsdom, in the middle of the close that fired it. */
+    _announce(name, detail) {
+        window.dispatchEvent(new window.CustomEvent(name, { detail }));
+    }
+
     /** BUG-0053. A closed window leaves the registry and lets go of what it
      *  held: its content, its DOM and every consumer callback (an `onClose`
      *  typically captures its owner). Until now the registry kept all of it
@@ -607,12 +591,10 @@ export class ManagedWindow {
         }
 
         // Dispatch event first so the taskbar button is created synchronously
-        window.dispatchEvent(new CustomEvent('managed-window-minimized', {
-            detail: {
-                id: this.id, title: this.title, icon: this.icon,
-                container: this.container,
-            }
-        }));
+        this._announce('managed-window-minimized', {
+            id: this.id, title: this.title, icon: this.icon,
+            container: this.container,
+        });
 
         if (!this.element) return;
 
@@ -744,9 +726,7 @@ export class ManagedWindow {
         this.bringToFront();
 
         // Notify taskbar (removes the taskbar button)
-        window.dispatchEvent(new CustomEvent('managed-window-restored', {
-            detail: { id: this.id, container: this.container }
-        }));
+        this._announce('managed-window-restored', { id: this.id, container: this.container });
     }
 
     /**
@@ -825,7 +805,7 @@ export class ManagedWindow {
 
         // A CLASS THE STYLESHEET HAS ALWAYS KNOWN AND NOTHING EVER SET.
         // `.twm-managed-window--maximized .twm-managed-window__resize
-        // { display: none }` is in `css/base.css` — "a maximised window is not
+        // { display: none }` is in `css/flexdesk.css` — "a maximised window is not
         // resized by dragging its edges" — and it has never matched anything,
         // because no code path adds the modifier. So a maximised window keeps
         // eight live resize handles hanging 3px outside its edges. Exactly the
@@ -841,9 +821,7 @@ export class ManagedWindow {
         // tiles — had no edge to hang the rule on and would have had to poll.
         // Same detail shape as the other three window events, `container`
         // included, so a per-region consumer can filter on receipt.
-        window.dispatchEvent(new CustomEvent('managed-window-maximized', {
-            detail: { id: this.id, maximized: this.isMaximized, container: this.container },
-        }));
+        this._announce('managed-window-maximized', { id: this.id, maximized: this.isMaximized, container: this.container });
     }
 
     /**
@@ -965,7 +943,7 @@ export class ManagedWindow {
         }
         this.element.setAttribute('data-window-id', this.id);
         // BUG-0053. Focusable by script and by a press, never by Tab (the
-        // modal trap's `_collectFocusable` skips tabindex -1): a press on the
+        // modal trap's `collectFocusable` skips tabindex -1): a press on the
         // title bar or on empty content keeps focus in the window, where a
         // non-modal window's Esc looks for it.
         this.element.tabIndex = -1;
@@ -1274,9 +1252,7 @@ export class ManagedWindow {
             this.width = bounds.width; this.height = bounds.height;
         }
         this._applyPosition();
-        window.dispatchEvent(new CustomEvent('managed-window-moved', {
-            detail: { id: this.id, container },
-        }));
+        this._announce('managed-window-moved', { id: this.id, container });
         return true;
     }
 
@@ -1736,9 +1712,7 @@ export class ManagedWindow {
         this.height = rect.height;
         this._applyPosition();
         this.element?.classList.add('twm-managed-window--snapped');
-        window.dispatchEvent(new CustomEvent('managed-window-snapped', {
-            detail: { id: this.id, zone, container: this.container },
-        }));
+        this._announce('managed-window-snapped', { id: this.id, zone, container: this.container });
     }
 
     /** Restore the geometry a snap replaced. Called when a snapped window is
@@ -1850,7 +1824,10 @@ export class ManagedWindow {
         // active element into the background — bad UX, and a
         // genuine WCAG focus-trap violation for accessibility tools.
         if (e.key === 'Tab' && this.modal && this.element) {
-            const focusables = _collectFocusable(this.element);
+            // A popover opened from this modal is over it but outside its frame,
+            // and sees to its own Tab.
+            if (isInAnchoredLayer(document.activeElement)) return;
+            const focusables = collectFocusable(this.element);
             if (focusables.length === 0) {
                 e.preventDefault();
                 return;

package/src/ui/components/modal.js

@@ -77,7 +77,7 @@
  *   }
  *
  * Dependent-property pick-or-create — a `select` field that carries a
- * `create` spec renders as a **type-ahead combobox** instead of a
+ * `create` spec renders as a `createCombobox` instead of a
  * dropdown: the user picks an existing option OR types a new value.
  * On submit, a value that isn't an existing option is created via
  * `create.onCreate(value)` before the form resolves:
@@ -115,29 +115,11 @@ import { ToggleField } from '../../ui/components/toggle_field.js';
 import { ColorField } from './color_field.js';
 import { ColorListField } from './color_list_field.js';
 import { choiceList, findChoice, flatChoices, selectBox, toggleChips } from './choice_controls.js';
+import { createCombobox } from './combobox.js';
+import { modalHost, setModalHost } from '../utils/modal_host.js';
+import { fireEvent } from '../utils/fire_event.js';
 
-/**
- * C25. WHERE A DIALOG OPENS, when the application spans more than one window.
- *
- * Every modal here is a `ManagedWindow` with no `container`, so it mounts into
- * `document.body` — and "document" is the document this MODULE was loaded in.
- * A consumer that opens a second browser window with `window.open` and builds
- * its DOM from the opener's realm (which is how a pop-out grid works: same
- * modules, same JS context, a different document) therefore gets its dialogs in
- * the window it popped OUT of. The user presses "Add column" on their second
- * monitor and a dialog appears on the first, behind whatever is there.
- *
- * Passing a container at each call site was the other option and it is worse:
- * twenty-one of them across eleven files, every one of which would have to be
- * given a document it has no other reason to know about, and any one missed is
- * this bug again with no way to see it from here.
- *
- * So the HOST is ambient and the consumer sets it when its focus moves. Null —
- * every consumer today — means `document.body`, exactly as before.
- */
-let _modalHost = null;
-export function setModalHost(el) { _modalHost = el || null; }
-export function modalHost() { return _modalHost; }
+export { setModalHost, modalHost };
 
 let _modalSeq = 1;
 
@@ -198,7 +180,7 @@ export function openForm({ title, fields = [], defaults = {}, submitLabel = 'OK'
         `;
 
         const win = new ManagedWindow({
-            container: _modalHost,
+            container: modalHost(),
             id: `twm-modal-${_modalSeq++}`,
             title: title || 'Dialog',
             icon: 'edit_note',
@@ -237,12 +219,7 @@ export function openForm({ title, fields = [], defaults = {}, submitLabel = 'OK'
         // The options each field offers NOW — `setOptions` replaces them, the
         // caller's field object is never written to.
         const optionsOf = new Map(formFields.map((f) => [f.name, f.options]));
-        const comboHints = new Map();
         for (const f of formFields) {
-            if (f.type === 'select' && f.create) {
-                const update = _wireComboboxHint(body, f, () => optionsOf.get(f.name));
-                if (update) comboHints.set(f.name, update);
-            }
             if (f.type === 'picker') _wirePicker(body, f);
         }
         const rowHidden = (name) => !!body.querySelector(`[data-field-row="${name}"]`)?.hidden;
@@ -281,13 +258,7 @@ export function openForm({ title, fields = [], defaults = {}, submitLabel = 'OK'
          *  read a combobox through this, so they agree (`'2'` is option `2`). */
         const comboOption = (f, text) => findChoice(flatChoices(optionsOf.get(f.name)), text, true);
         /** A disabled option's reason ('' with none) when one is the value, else null. */
-        const unavailable = (f, value) => {
-            const c = controls.get(f.name);
-            if (c) return c.unavailable();
-            if (f.type !== 'select' || !f.create || value == null || value === '') return null;
-            const o = comboOption(f, value);
-            return o?.disabled ? (o.reason || '') : null;
-        };
+        const unavailable = (f) => controls.get(f.name)?.unavailable() ?? null;
 
         // Clear per-field errors on input so the user sees the row recover.
         for (const f of formFields) {
@@ -337,11 +308,6 @@ export function openForm({ title, fields = [], defaults = {}, submitLabel = 'OK'
                     const el = body.querySelector(`[name="${name}"]`);
                     if (!el) return undefined;
                     if (el.type === 'checkbox') return !!el.checked;
-                    const f = fieldOf(name);
-                    if (f?.type === 'select' && f.create) {
-                        const match = comboOption(f, el.value);
-                        return match ? match.value : el.value;
-                    }
                     return el.value;
                 },
                 set(name, value) {
@@ -350,29 +316,17 @@ export function openForm({ title, fields = [], defaults = {}, submitLabel = 'OK'
                     if (!el) return;
                     if (el.type === 'checkbox') { el.checked = !!value; return; }
                     const f = fieldOf(name);
-                    // A combobox does not take a disabled option's text either.
-                    const shut = f?.type === 'select' && f.create && comboOption(f, value)?.disabled;
-                    el.value = value == null || shut ? '' : String(value);
-                    comboHints.get(name)?.();
+                    el.value = value == null ? '' : String(value);
                     if (f?.type === 'picker') {
                         const display = body.querySelector(`[data-picker-display="${name}"]`);
                         if (display) display.value = _pickerLabel(f, el.value);
                     }
                 },
                 setOptions(name, options) {
-                    const f = fieldOf(name);
-                    if (!f) return;
                     const c = controls.get(name);
-                    if (c?.setOptions) {
-                        optionsOf.set(name, options);
-                        c.setOptions(options);
-                        return;
-                    }
-                    if (f.type !== 'select' || !f.create) return;
+                    if (!c?.setOptions) return;
                     optionsOf.set(name, options);
-                    const list = body.querySelector(`[data-datalist-for="${name}"]`);
-                    if (list) list.innerHTML = _datalistOptions(options);
-                    comboHints.get(name)?.();
+                    c.setOptions(options);
                 },
             };
             const fire = (name) => {
@@ -444,7 +398,7 @@ export function openForm({ title, fields = [], defaults = {}, submitLabel = 'OK'
                 if (rowHidden(f.name)) {
                     // Not asked about — but a disabled option is still never
                     // the value: a hidden row holding one submits no value.
-                    if (unavailable(f, data[f.name]) != null) data[f.name] = f.type === 'radio' ? null : '';
+                    if (unavailable(f) != null) data[f.name] = f.type === 'radio' ? null : '';
                     continue;
                 }
                 const v = data[f.name];
@@ -454,7 +408,7 @@ export function openForm({ title, fields = [], defaults = {}, submitLabel = 'OK'
                 let msg = f.required && _missing(f, v) ? 'Required.' : null;
                 if (!msg && _outOfRange(f, v)) msg = _rangeMessage(f);
                 if (!msg) {
-                    const reason = unavailable(f, v);
+                    const reason = unavailable(f);
                     if (reason != null) msg = reason ? `Not available: ${reason}` : 'Not available.';
                 }
                 if (!msg) msg = controls.get(f.name)?.error?.() ?? null;
@@ -527,7 +481,7 @@ export function openConfirm({
 
         let _resolved = false;
         const win = new ManagedWindow({
-            container: _modalHost,
+            container: modalHost(),
             id: `twm-confirm-${_modalSeq++}`,
             title: title || 'Confirm',
             icon: icon || (danger ? 'warning' : 'help'),
@@ -601,6 +555,9 @@ export function openConfirm({
  *                 existing caller has always got.
  *   - `onMaximizeChange` `(maximized, contentEl) => void`, called on each
  *                 flip. Only useful with `maximizable`.
+ *   - `beforeClose`      `() => boolean | Promise<boolean>`: asked when Esc or
+ *                 the X would dismiss; answering false keeps the modal open. An
+ *                 action button does not ask it.
  *
  * ══ C29. WHY A DIALOG'S MAXIMISE IS THE GEOMETRIC ONE ═══════════════════
  *
@@ -642,6 +599,7 @@ export function openModal({
     backdropOpacity = undefined,
     maximizable      = false,
     onMaximizeChange = null,
+    beforeClose      = null,
 } = {}) {
     return new Promise((resolve) => {
         const body = document.createElement('div');
@@ -726,7 +684,7 @@ export function openModal({
             _onMax = null;
         };
         const win = new ManagedWindow({
-            container: _modalHost,
+            container: modalHost(),
             id: `twm-modal-${_modalSeq++}`,
             title,
             icon,
@@ -747,6 +705,7 @@ export function openModal({
             canDrag: true,
             defaultWidth:  width,
             defaultHeight: height,
+            beforeClose,
             // Esc, the X and the backdrop all land here without passing through
             // `close`, so the listener is dropped here as well as there — the
             // three dismissals a user reaches for most are exactly the ones
@@ -953,14 +912,68 @@ function _offered(options) {
     return flatChoices(options).filter((o) => !o.disabled);
 }
 
-function _datalistOptions(options) {
-    return _offered(options).map((o) => `<option value="${_esc(o.value)}"></option>`).join('');
+/**
+ * A `select` with `create`: `createCombobox` over the enabled options. The box holds
+ * the text; `read` is the value of the option that text names, else the text. A
+ * disabled option is not offered, and a default or `write` naming one leaves the box
+ * empty; typed all the same, it is `unavailable`.
+ */
+function _mountCombobox(slot, f, value) {
+    let options = f.options;
+    const named = (text) => findChoice(flatChoices(options), text, true);
+    const shown = (v) => (v == null || named(v)?.disabled ? '' : String(v));
+
+    const hint = document.createElement('span');
+    hint.className = 'twm-combobox__hint';
+    hint.hidden = true;
+    // With `create: true` the typed value simply IS the value — there is no
+    // entity being made, so promising to "create" one is a lie that reads as
+    // a warning.
+    const noun = f.create === true ? null : _createSpec(f).hint || 'new entry';
+    const updateHint = () => {
+        const v = c.value.trim();
+        const isNew = noun && v && !flatChoices(options).some((o) => String(o.value) === v);
+        if (isNew) hint.textContent = `↳ will create ${noun} “${v}”`;
+        hint.hidden = !isNew;
+    };
+
+    const c = createCombobox({
+        options: _offered(options),
+        value: shown(value),
+        name: f.name,
+        placeholder: f.placeholder ?? 'type to pick or create…',
+        // Enter keeps what was typed: this field exists to accept a value nobody listed.
+        autoHighlight: false,
+        onChange: () => updateHint(),
+    });
+    if (f.required) c.input.required = true;
+    c.el.appendChild(hint);
+    slot.replaceWith(c.el);
+    updateHint();
+    return {
+        read() {
+            const o = named(c.value);
+            return o ? o.value : c.value;
+        },
+        write(v) { c.value = shown(v); updateHint(); },
+        focus: c.focus,
+        unavailable() {
+            const o = c.value === '' ? undefined : named(c.value);
+            return o?.disabled ? (o.reason || '') : null;
+        },
+        setOptions(next) {
+            options = next;
+            c.setOptions(_offered(next));
+            updateHint();
+        },
+        dispose: c.destroy,
+    };
 }
 
 /**
  * Mount a field that is a component rather than markup — a `toggle`, a
- * `select` (not a combobox), `checklist` or `radio` drawn by
- * `choice_controls.js`, or a `color` / `colorList` — into the
+ * `select`, `checklist` or `radio` drawn by `choice_controls.js`, a `select`
+ * with `create` drawn by `createCombobox`, or a `color` / `colorList` — into the
  * `data-control-slot` its row left, and hand back what the form needs of it:
  * `{ read(), write(v), focus(), unavailable(), submit?(), error?(),
  * setOptions?(options), dispose?() }`. `unavailable()` is the reason (or '')
@@ -1018,6 +1031,7 @@ function _mountControl(host, f, value, onChange) {
             dispose: () => c.dispose(),
         };
     }
+    if (f.type === 'select' && f.create) return _mountCombobox(slot, f, value);
     const common = { keepMissing: false, loose: true };
     const disabledReason = (entry) => (entry?.disabled ? (entry.reason || '') : null);
     if (f.type === 'select') {
@@ -1113,7 +1127,7 @@ function _wirePicker(host, f) {
             ? String(picked.label) : _pickerLabel(f, hidden.value);
         // A hidden input fires no `change` of its own; this is the one the
         // field-error clear and `onFieldChange` listen for.
-        hidden.dispatchEvent(new Event('change', { bubbles: true }));
+        fireEvent(hidden, 'change', { bubbles: true });
     };
     btn.addEventListener('click', open);
     // The read-only box is the obvious thing to click; make it work too.
@@ -1121,33 +1135,6 @@ function _wirePicker(host, f) {
 }
 
 
-/** Show / hide the "↳ will create …" hint as the user types into a
- *  create-capable combobox. */
-function _wireComboboxHint(host, f, optionsOf) {
-    const input = host.querySelector(`input[name="${f.name}"]`);
-    const hintEl = host.querySelector(`.twm-combobox__hint[data-for="${f.name}"]`);
-    if (!input || !hintEl) return;
-    // With `create: true` the typed value simply IS the value — there is no
-    // entity being made, so promising to "create" one is a lie that reads as
-    // a warning.
-    if (f.create === true) return;
-    const label = _createSpec(f).hint || 'new entry';
-    const update = () => {
-        const v = input.value.trim();
-        const known = new Set(flatChoices(optionsOf()).map((o) => String(o.value)));
-        if (v && !known.has(v)) {
-            hintEl.textContent = `↳ will create ${label} “${v}”`;
-            hintEl.hidden = false;
-        } else {
-            hintEl.hidden = true;
-        }
-    };
-    input.addEventListener('input', update);
-    update();
-    return update;
-}
-
-
 function _renderEntry(f, defaults) {
     if (f && f.section != null) {
         // A named section is addressable by `setVisible`, so a heading can be
@@ -1247,23 +1234,6 @@ function _renderField(f, value) {
             </div>
         `);
     }
-    if (f.type === 'select' && f.create) {
-        // A default naming a disabled option is not taken, as in a select.
-        const shown = findChoice(flatChoices(f.options), value, true)?.disabled ? '' : v;
-        const dlId = `ea-dl-${f.name}-${_modalSeq}`;
-        const opts = _datalistOptions(f.options);
-        const placeholder = f.placeholder
-            ? `placeholder="${_esc(f.placeholder)}"` : 'placeholder="type to pick or create…"';
-        return wrap(`
-            <div class="twm-combobox">
-                <input name="${f.name}" type="text" list="${dlId}"
-                       value="${_esc(shown)}" ${placeholder} ${required}
-                       autocomplete="off">
-                <datalist id="${dlId}" data-datalist-for="${f.name}">${opts}</datalist>
-                <span class="twm-combobox__hint" data-for="${f.name}" hidden></span>
-            </div>
-        `);
-    }
     if (f.type === 'select') return wrap(slot);
     const step = f.step != null ? `step="${f.step}"` : '';
     const placeholder = f.placeholder ? `placeholder="${_esc(f.placeholder)}"` : '';

package/src/ui/components/option_list.js

@@ -0,0 +1,160 @@
+/**
+ * THE ROWS `createSelect`, `createCombobox` AND `createTagInput`'s SUGGESTIONS
+ * DRAW: a `role="listbox"` of options, each with a glyph, a label, a second line,
+ * a hint at the end of the row and, when disabled, its reason; `{ group, options }`
+ * sections under a heading; one active row that the arrow keys walk.
+ *
+ * Focus never comes here. The text box or trigger that holds it names the active
+ * row with `aria-activedescendant` (`onActive`), and a press on a row is
+ * prevented from taking focus, so that a list row can be chosen with the box
+ * still holding the caret, and no blur closes the list under the pointer.
+ *
+ * `aria-selected` says which row IS the current value; the active row is a class.
+ * They are different things in a select, where the highlight walks away from the
+ * value and comes back. Every word is built with `textContent`: these lists carry
+ * text users wrote.
+ *
+ * An internal part: not exported from `@flexdesk/widgets`.
+ */
+
+let SEQ = 0;
+
+function node(tag, className, text) {
+    const n = document.createElement(tag);
+    if (className) n.className = className;
+    if (text !== undefined && text !== null) n.textContent = String(text);
+    return n;
+}
+
+/** `text` with the first run of `needle` in a `<mark>`, so it is plain why a row is offered. */
+function marked(target, text, needle) {
+    const at = needle ? text.toLowerCase().indexOf(needle.toLowerCase()) : -1;
+    if (at < 0) { target.textContent = text; return; }
+    target.append(text.slice(0, at), node('mark', 'twm-option-list__match', text.slice(at, at + needle.length)),
+                  text.slice(at + needle.length));
+}
+
+/**
+ * @param {object} o
+ * @param {(option: object) => void} o.onPick   A row was clicked. Never a disabled one.
+ * @param {(id: string|null) => void} [o.onActive]  The active row's id changed.
+ */
+export function createOptionList({ onPick, onActive = null }) {
+    const id = `twm-option-list-${++SEQ}`;
+    const el = node('div', 'twm-option-list');
+    el.id = id;
+    el.setAttribute('role', 'listbox');
+
+    /** Every row drawn: `{ option, row }`. */
+    let rows = [];
+    let active = -1;
+
+    const paintActive = () => {
+        rows.forEach(({ row }, i) => row.classList.toggle('twm-option-list__row--active', i === active));
+        const row = rows[active]?.row;
+        // jsdom does not implement it, and a test harness is no reason to drop it.
+        row?.scrollIntoView?.({ block: 'nearest' });
+        onActive?.(row ? row.id : null);
+    };
+
+    const rowFor = (option, { glyphs, mark, isCurrent }) => {
+        const row = node('div', 'twm-option-list__row');
+        row.id = `${id}-${rows.length}`;
+        row.setAttribute('role', 'option');
+        row.setAttribute('aria-selected', String(!!isCurrent?.(option)));
+        if (option.disabled) row.setAttribute('aria-disabled', 'true');
+        row.title = option.description ? `${option.label} — ${option.description}` : option.label;
+        if (glyphs) {
+            const glyph = node('span', 'twm-option-list__glyph material-symbols-outlined', option.icon || '');
+            glyph.setAttribute('aria-hidden', 'true');
+            row.appendChild(glyph);
+        }
+        const words = node('span', 'twm-option-list__words');
+        const label = node('span', 'twm-option-list__label');
+        marked(label, option.label, mark);
+        words.appendChild(label);
+        if (option.description) words.appendChild(node('span', 'twm-option-list__description', option.description));
+        if (option.disabled && option.reason) words.appendChild(node('span', 'twm-choice__reason', option.reason));
+        row.appendChild(words);
+        if (option.hint) row.appendChild(node('span', 'twm-option-list__hint', option.hint));
+        return row;
+    };
+
+    const enabled = () => rows.map((r, i) => (r.option.disabled ? -1 : i)).filter((i) => i >= 0);
+
+    // A press on the list leaves focus where it is. See the header.
+    el.addEventListener('mousedown', (ev) => ev.preventDefault());
+    el.addEventListener('click', (ev) => {
+        const row = ev.target.closest?.('[role="option"]');
+        const hit = rows.find((r) => r.row === row);
+        if (hit && !hit.option.disabled) onPick(hit.option);
+    });
+
+    return {
+        el,
+        id,
+        /**
+         * Draw `sections` (`[{ heading, items }]`, as `choiceSections` gives them).
+         * @param {object} [opts]
+         * @param {string} [opts.mark]  The text to mark in each label.
+         * @param {(option: object) => boolean} [opts.isCurrent]  Is this the current value?
+         */
+        setRows(sections, { mark = '', isCurrent = null } = {}) {
+            rows = [];
+            active = -1;
+            el.replaceChildren();
+            const glyphs = sections.some((s) => s.items.some((o) => o.icon));
+            for (const { heading, items } of sections) {
+                let parent = el;
+                if (heading != null) {
+                    parent = node('div', 'twm-option-list__section');
+                    parent.setAttribute('role', 'group');
+                    parent.setAttribute('aria-label', heading);
+                    const title = node('div', 'twm-choice__group', heading);
+                    title.setAttribute('aria-hidden', 'true');
+                    parent.appendChild(title);
+                    el.appendChild(parent);
+                }
+                for (const option of items) {
+                    const row = rowFor(option, { glyphs, mark, isCurrent });
+                    rows.push({ option, row });
+                    parent.appendChild(row);
+                }
+            }
+            paintActive();
+        },
+        /** One line of text in place of the rows: nothing matched, still loading, a failure. */
+        setMessage(text) {
+            rows = [];
+            active = -1;
+            el.replaceChildren(node('div', 'twm-option-list__message', text));
+            paintActive();
+        },
+        /** How many rows are drawn. */
+        get size() { return rows.length; },
+        /** The drawn options, in order. */
+        options: () => rows.map((r) => r.option),
+        /** The active row's option, or null. */
+        activeOption: () => rows[active]?.option ?? null,
+        /** Make row `index` active; -1, or a row that is disabled, makes none active. */
+        setActive(index) {
+            active = rows[index] && !rows[index].option.disabled ? index : -1;
+            paintActive();
+        },
+        /** The next row that may be chosen, by `step`, wrapping. From none: the first or the last. */
+        move(step) {
+            const stops = enabled();
+            if (!stops.length) return;
+            const at = stops.indexOf(active);
+            const next = at < 0 ? (step > 0 ? 0 : stops.length - 1) : (at + step + stops.length) % stops.length;
+            active = stops[next];
+            paintActive();
+        },
+        /** The first (`step` 1) or last (`step` -1) row that may be chosen. */
+        moveToEnd(step) {
+            const stops = enabled();
+            active = stops.length ? stops[step > 0 ? 0 : stops.length - 1] : -1;
+            paintActive();
+        },
+    };
+}