flexdesk 0.16.1 → 0.17.0

package/src/ui/components/table_structure.js

@@ -0,0 +1,182 @@
+/**
+ * table_structure.js — STORY-0066. DataTable's STRUCTURAL EDITS: the
+ * consumer's action buttons on the column headers (`columnActions`), renaming
+ * a column in place (`onColumnRename`, through `attachInlineRenamer`), and the
+ * menu items that add and delete columns and rows (`onColumnDelete`,
+ * `onRowAdd`, `onRowDelete`). INTERNAL to the table: imported by
+ * `data_table.js` only, and not part of the widgets barrel.
+ *
+ * THE CONSUMER OWNS THE DATA. Nothing here changes `headers` or `rows`: each
+ * edit is a call, and the consumer answers it with `setData`. A rename shows
+ * the new name in the header until then.
+ *
+ * Where the items go: the header's right-click menu (the STORY-0003
+ * `headerMenu` path) gets "Rename column", "Delete column" and "Add row" after
+ * the consumer's `headerMenu` items, and the body's right-click menu (the
+ * STORY-0010 `contextMenuItems` path) "Insert row below" and "Delete row"
+ * after the consumer's `contextMenuItems`. "Add row" is in the header's menu
+ * so a table with no rows can still get its first.
+ *
+ * A table without any of these options never builds this.
+ */
+
+import { callOption, headerActionButton } from './header_actions.js';
+import { attachInlineRenamer } from './inline_renamer.js';
+
+/** The options that build this module. */
+export const STRUCTURE_OPTIONS = ['columnActions', 'onColumnRename', 'onColumnDelete', 'onRowAdd', 'onRowDelete'];
+
+export class TableStructure {
+    /** @param {import('./data_table.js').DataTable} table */
+    constructor(table) {
+        this.table = table;
+        this._renamer = null;
+    }
+
+    _cfg() {
+        return this.table.config;
+    }
+
+    _has(name) {
+        return typeof this._cfg()[name] === 'function';
+    }
+
+    _call(name, ...args) {
+        return callOption(this._cfg(), name, ...args);
+    }
+
+    /** Whether the header's right-click has items of this module's. */
+    hasHeaderItems() {
+        return this._has('onColumnRename') || this._has('onColumnDelete') || this._has('onRowAdd');
+    }
+
+    /** Whether a row's right-click has items of this module's. */
+    hasRowItems() {
+        return this._has('onRowAdd') || this._has('onRowDelete');
+    }
+
+    /** The header menu's items for the data column `colIdx` (null off one). */
+    headerItems(colIdx) {
+        const items = [];
+        if (colIdx !== null && this._has('onColumnRename')) {
+            items.push({ label: 'Rename column', icon: 'edit', onChoose: () => this.rename(colIdx) });
+        }
+        if (colIdx !== null && this._has('onColumnDelete')) {
+            items.push({ label: 'Delete column', icon: 'delete', danger: true,
+                         onChoose: () => this._call('onColumnDelete', colIdx) });
+        }
+        if (this._has('onRowAdd')) {
+            items.push({ label: 'Add row', icon: 'add', onChoose: () => this._call('onRowAdd', null) });
+        }
+        return items;
+    }
+
+    /** The body menu's items for the row `rowIdx` (its original index). */
+    rowItems(rowIdx) {
+        const items = [];
+        if (this._has('onRowAdd')) {
+            items.push({ label: 'Insert row below', icon: 'add', onChoose: () => this._call('onRowAdd', rowIdx) });
+        }
+        if (this._has('onRowDelete')) {
+            items.push({ label: 'Delete row', icon: 'delete', danger: true,
+                         onChoose: () => this._call('onRowDelete', rowIdx) });
+        }
+        return items;
+    }
+
+    /**
+     * After the header is built: each data column's label in a span the
+     * renamer can take over, and the consumer's action buttons.
+     */
+    decorate(headerTable) {
+        this._renamer?.destroy();
+        this._renamer = null;
+        const labelRow = headerTable?.querySelector('thead > tr');
+        if (!labelRow) return;
+        const headers = this._cfg().headers || [];
+        const rename = this._has('onColumnRename');
+        const actions = this._has('columnActions');
+        if (!rename && !actions) return;
+        for (let colIdx = 0; colIdx < headers.length; colIdx++) {
+            const th = labelRow.children[this.table._domIdxOf(colIdx)];
+            if (!th) continue;
+            if (rename) this._wrapLabel(th, colIdx);
+            if (actions) this._addActions(th, colIdx, headers[colIdx]);
+        }
+    }
+
+    _wrapLabel(th, colIdx) {
+        const text = [...th.childNodes].find((n) => n.nodeType === 3);
+        if (!text) return;
+        const label = document.createElement('span');
+        label.className = 'twm-dt-col-label';
+        th.insertBefore(label, text);
+        label.appendChild(text);
+        // The renamer's keys stay its own: no Escape or Enter it handles
+        // reaches the table or the page. (On the label, not added per rename:
+        // the renamer's Escape removes its input before the key bubbles here.)
+        label.addEventListener('keydown', (ev) => ev.stopPropagation());
+        // A double-click on the label renames — on a table whose header click
+        // does not sort (there, the first click redraws the header).
+        if (!this._cfg().sortable) {
+            label.addEventListener('dblclick', (ev) => {
+                ev.preventDefault();
+                ev.stopPropagation();
+                this.rename(colIdx);
+            });
+        }
+    }
+
+    _addActions(th, colIdx, header) {
+        const items = this._call('columnActions', colIdx, { colIdx, header, table: this.table });
+        const list = Array.isArray(items) ? items.filter(Boolean) : [];
+        if (!list.length) return;
+        const box = document.createElement('span');
+        box.className = 'twm-dt-col-actions';
+        for (const item of list) {
+            box.appendChild(headerActionButton('twm-dt-col-action', item,
+                                               () => this._call('onColumnAction', item.action, colIdx)));
+        }
+        th.appendChild(box);
+    }
+
+    /**
+     * Open the renamer on the data column's header. Enter (or the focus
+     * leaving) with a different, non-empty name calls
+     * `onColumnRename(colIdx, name)`; Escape, or the name left as it was,
+     * restores the header and calls nothing. Returns whether it opened.
+     */
+    rename(colIdx) {
+        if (!this._has('onColumnRename')) return false;
+        const labelRow = this.table._headerTableEl?.querySelector('thead > tr');
+        const dom = this.table._domIdxOf(colIdx);
+        const label = dom < 0 ? null : labelRow?.children[dom]?.querySelector('.twm-dt-col-label');
+        if (!label) return false;
+        this._renamer?.cancel();
+        const before = label.textContent || '';
+        const done = () => {
+            if (this._renamer === renamer) this._renamer = null;
+        };
+        const renamer = attachInlineRenamer({
+            label,
+            inputClass: 'twm-dt-col-rename',
+            onCommit: async (raw) => {
+                const name = String(raw ?? '').trim();
+                if (!name || name === before) return { success: false };
+                const answer = await this._call('onColumnRename', colIdx, name);
+                if (answer === false || (answer && answer.ok === false)) return { success: false };
+                return { newValue: name };
+            },
+            onCancel: done,
+            onFinish: done,
+        });
+        this._renamer = renamer;
+        renamer.start();
+        return true;
+    }
+
+    dispose() {
+        this._renamer?.destroy();
+        this._renamer = null;
+    }
+}

package/src/ui/components/tabs.js

@@ -0,0 +1,497 @@
+/**
+ * ══ ONE TAB STRIP, WITH AN OPTIONAL PANE HOST ════════════════════════════
+ *
+ * Three strips grew apart: the window manager's (`../../tiling/tab_strip.js`,
+ * internal, over `NotebookTabBar`), the editor's (`NotebookTabBar`, keyed by
+ * FILE PATH) and the bottom panel's (`createBottomPanelTabs`, tied to its bus
+ * event). This one is keyed by whatever id the caller gives, knows no event
+ * name and no file, and the bottom panel is built on it (FlexDesk STORY-0048).
+ *
+ *     const tabs = createTabs(el, {
+ *         items: [{ id: 'a', label: 'Inputs', icon: 'tune' }, { id: 'b', label: 'Results', badge: 3 }],
+ *         active: 'a',
+ *         onSelect: (id, item) => …,
+ *         mountPane: (item, el, tabs) => ({ onShow() {…}, destroy() {…} }),   // omit: strip only
+ *     });
+ *     tabs.update(nextItems, 'b');
+ *     tabs.setBadge('b', 7, 'warning');
+ *
+ * AN ITEM is `{ id, label, icon?, title?, badge?, indicator?, closable?, dirty?, eager? }`:
+ *   badge      a count (`n`, or `{ count, level }`); none at zero, `99+` above 99
+ *   indicator  a dot: `true`, or a level (`info` | `warning` | `alert`)
+ *   closable   draws a close mark (and `{block}__tab--closable`) and lets Delete
+ *              close — both call `onClose(id)`; without an `onClose` there is
+ *              nothing to close and none is drawn
+ *   dirty      the unsaved dot
+ *   eager      mount this item's pane at once instead of on first selection —
+ *              at creation, or when an `update` brings the item in
+ *
+ * PANES are optional. Without `mountPane` this is a strip and nothing else.
+ * With it, an item's pane is mounted the FIRST time it is selected — the tab in
+ * front at creation counts — and never again; `eager` items mount at once, in
+ * order, before it, and an eager item that an `update` adds mounts in that
+ * `update`, before the tab in front is settled. `mountPane(item, el, tabs)`
+ * answers an instance or nothing; the strip calls its `onShow()` each time its
+ * tab comes to the front and its `destroy()` when the item goes (an `update`
+ * without it, or `destroy`). Panes mount INSIDE `createTabs` before it has
+ * answered, so a pane reaches the strip through its third argument, not the
+ * variable being assigned.
+ *
+ * `onSelect(id, item)` hears every change of the tab in front AFTER creation —
+ * a click, a key, `select`, the bus, an `update` that had to move it — but not
+ * the tab chosen at creation, which the caller already knows. An `update` that
+ * leaves no items empties the front, and that is a change too: it is heard as
+ * `onSelect(null, null)`. A click on the
+ * tab ALREADY in front changes nothing, so it is not a select; a caller that
+ * acts on it anyway (the bottom panel re-shows its pane) passes
+ * `onReselect(id, item)`, which hears exactly that click.
+ *
+ * THE BUS IS OPT-IN. Pass `eventBus` AND `selectEvent` (a name) and that event
+ * selects a tab: the id is `selectFrom(payload)`, by default `payload.id`. No
+ * event name, no subscription — whatever bus is passed.
+ *
+ * KEYS are the ARIA tabs pattern with automatic activation: ArrowLeft/Right move
+ * the selection (wrapping), Home and End go to the ends, Delete closes a
+ * closable tab. One tab is in the tab order — the one in front. When an
+ * `update` removes the tab that has focus (Delete, then the caller drops the
+ * item), focus moves to the tab now in front, so the keyboard keeps its place;
+ * focus that the update put somewhere else (a pane focusing itself) stays.
+ *
+ * OVERFLOW scrolls, never wraps: a vertical wheel moves the strip sideways and a
+ * tab that comes to the front is scrolled into it (`../utils/strip_scroll.js`).
+ *
+ * CLASSES are BEM under `block` (default `twm-tabs`): `{block}` root,
+ * `{block}--compact`, `{block}__tabs`, `{block}__tab`, `{block}__tab--on`,
+ * `{block}__tab--dirty`, `{block}__tab--closable`, `{block}__icon`, `{block}__label`, `{block}__badge`
+ * (`--{level}`), `{block}__indicator` (`--{level}`), `{block}__dirty`,
+ * `{block}__close`, `{block}__body`, `{block}-pane`. The bottom panel passes
+ * `twm-bp` and gets its existing markup. Tabs and panes carry the item id in
+ * `data-{dataKey}` (default `tab-id`), as a string; the strip never reads it
+ * back, so every callback and `ids()` hand out the id as given (`1` stays `1`).
+ *
+ * The strip is never rebuilt: a select toggles classes on the same buttons and
+ * an `update` keeps the button of every id it keeps, so a click that lands
+ * while a tab is being selected keeps its target.
+ */
+
+import { DragReorder } from './drag_reorder.js';
+import { revealInStrip, wheelStripSideways } from '../utils/strip_scroll.js';
+
+/** Badge and indicator levels, worst last. Any other value draws the neutral one. */
+export const TAB_LEVELS = Object.freeze(['info', 'warning', 'alert']);
+
+let stripCount = 0;
+
+/**
+ * @param {HTMLElement} container
+ * @param {object}    opts
+ * @param {Array}     opts.items           see AN ITEM above
+ * @param {string}   [opts.active]         the tab in front at creation; the first by default
+ * @param {Function} [opts.onSelect]       `(id, item)`; `(null, null)` when an `update` empties the strip
+ * @param {Function} [opts.onReselect]     `(id, item)` on a click on the tab already in front
+ * @param {Function} [opts.onClose]        `(id, item)` — the caller removes it with `update`
+ * @param {Function} [opts.onReorder]      `(ids)` after a drag; omit and tabs do not drag
+ * @param {Function} [opts.onContextMenu]  `(id, event, item)` on right-click
+ * @param {Function} [opts.mountPane]      `(item, el, tabs)`; omit for a strip only
+ * @param {object}   [opts.eventBus]
+ * @param {string}   [opts.selectEvent]    the bus event that selects a tab
+ * @param {Function} [opts.selectFrom]     `(payload) => id`; `payload.id` by default
+ * @param {boolean}  [opts.compact]        the dense variant
+ * @param {string}   [opts.label]          the tablist's accessible name
+ * @param {string}   [opts.block]          the BEM block
+ * @param {string}   [opts.dataKey]        the `data-*` key carrying an item's id
+ */
+export function createTabs(container, {
+    items = [], active = null, onSelect = null, onReselect = null, onClose = null, onReorder = null,
+    onContextMenu = null, mountPane = null, eventBus = null, selectEvent = null,
+    selectFrom = (payload) => payload?.id, compact = false, label = null,
+    block = 'twm-tabs', dataKey = 'tab-id',
+} = {}) {
+    const doc = container.ownerDocument;
+    const uid = `${block}-${++stripCount}`;
+    const datasetKey = dataKey.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    const cls = (part) => `${block}__${part}`;
+
+    const root = doc.createElement('div');
+    root.className = compact ? `${block} ${block}--compact` : block;
+    const strip = doc.createElement('div');
+    strip.className = cls('tabs');
+    strip.setAttribute('role', 'tablist');
+    strip.setAttribute('aria-orientation', 'horizontal');
+    if (label) strip.setAttribute('aria-label', label);
+    root.appendChild(strip);
+    let body = null;
+    if (mountPane) {
+        body = doc.createElement('div');
+        body.className = cls('body');
+        root.appendChild(body);
+    }
+    container.appendChild(root);
+
+    /** id → the caller's item, as last given (setBadge/setIndicator write here). */
+    let order = [];
+    const byId = new Map();
+    /** id → { el } for every tab drawn. */
+    const tabs = new Map();
+    /** A tab's button → its id, unchanged: `data-*` holds only a string. */
+    const idByEl = new WeakMap();
+    /** id → { el, instance } for every pane mounted. */
+    const panes = new Map();
+    let current = null;
+    let serial = 0;
+    let destroyed = false;
+    /** The bus subscription, made last; a pane may destroy the strip first. */
+    let subscription = null;
+
+    // ── a tab ───────────────────────────────────────────────────────────
+
+    function tabFor(id) {
+        let entry = tabs.get(id);
+        if (entry) return entry;
+        const el = doc.createElement('button');
+        el.type = 'button';
+        el.className = cls('tab');
+        el.dataset[datasetKey] = id;
+        el.id = `${uid}-tab-${++serial}`;
+        el.setAttribute('role', 'tab');
+        el.setAttribute('aria-selected', 'false');
+        el.tabIndex = -1;
+        idByEl.set(el, id);
+        entry = { el };
+        tabs.set(id, entry);
+        return entry;
+    }
+
+    function badgeOf(item) {
+        const b = item.badge;
+        if (b && typeof b === 'object') return { count: Number(b.count) || 0, level: b.level ?? null };
+        return { count: Number(b) || 0, level: null };
+    }
+
+    function drawBadge(span, { count, level }) {
+        span.hidden = count <= 0;
+        span.textContent = count > 99 ? '99+' : String(Math.max(count, 0));
+        span.className = cls('badge') + (TAB_LEVELS.includes(level) ? ` ${cls('badge')}--${level}` : '');
+    }
+
+    function drawIndicator(span, value) {
+        span.hidden = !value;
+        span.className = cls('indicator')
+            + (TAB_LEVELS.includes(value) ? ` ${cls('indicator')}--${value}` : '');
+    }
+
+    function draw(id) {
+        const item = byId.get(id);
+        const { el } = tabFor(id);
+        const closable = !!(item.closable && onClose);
+        el.classList.toggle(`${cls('tab')}--dirty`, !!item.dirty);
+        el.classList.toggle(`${cls('tab')}--closable`, closable);
+        if (item.title) el.title = item.title; else el.removeAttribute('title');
+        const parts = [];
+        if (item.icon) {
+            const icon = doc.createElement('span');
+            icon.className = `material-symbols-outlined ${cls('icon')}`;
+            icon.setAttribute('aria-hidden', 'true');
+            icon.textContent = item.icon;
+            parts.push(icon);
+        }
+        const text = doc.createElement('span');
+        text.className = cls('label');
+        text.textContent = item.label ?? String(id);
+        parts.push(text);
+        const badge = doc.createElement('span');
+        drawBadge(badge, badgeOf(item));
+        parts.push(badge);
+        const dot = doc.createElement('span');
+        dot.setAttribute('aria-hidden', 'true');
+        drawIndicator(dot, item.indicator);
+        parts.push(dot);
+        if (item.dirty) {
+            const dirty = doc.createElement('span');
+            dirty.className = cls('dirty');
+            dirty.setAttribute('aria-label', 'unsaved');
+            dirty.textContent = '●';
+            parts.push(dirty);
+        }
+        if (closable) {
+            // A mark, not a button: a button inside the tab's button is not
+            // HTML. The keyboard closes with Delete.
+            const close = doc.createElement('span');
+            close.className = cls('close');
+            close.setAttribute('aria-hidden', 'true');
+            close.title = 'Close';
+            close.textContent = '×';
+            parts.push(close);
+        }
+        el.replaceChildren(...parts);
+    }
+
+    // ── panes ───────────────────────────────────────────────────────────
+
+    function mount(id) {
+        if (destroyed || !mountPane || panes.has(id)) return panes.get(id) ?? null;
+        const el = doc.createElement('div');
+        el.className = `${block}-pane`;
+        el.dataset[datasetKey] = id;
+        el.id = `${tabFor(id).el.id}-pane`;
+        el.setAttribute('role', 'tabpanel');
+        el.setAttribute('aria-labelledby', tabFor(id).el.id);
+        el.hidden = id !== current;
+        body.appendChild(el);
+        tabFor(id).el.setAttribute('aria-controls', el.id);
+        const entry = { el, instance: null };
+        panes.set(id, entry);
+        // ONE PANE THAT THROWS IS ONE EMPTY TAB, not a dead strip: the strip
+        // and every other pane go on working.
+        let instance = null;
+        try {
+            instance = mountPane(byId.get(id), el, api) ?? null;
+        } catch (err) {
+            console.error(`[tabs] pane "${id}" failed to mount`, err);
+        }
+        // The pane let go of its own entry while it mounted (it destroyed the
+        // strip, or an update dropped its item): it was never anyone's, so it
+        // is destroyed now and never shown.
+        if (panes.get(id) !== entry) {
+            try { instance?.destroy?.(); } catch (err) {
+                console.warn(`[tabs] pane "${id}" destroy failed`, err);
+            }
+            return null;
+        }
+        entry.instance = instance;
+        return entry;
+    }
+
+    /** Every eager item not mounted yet, in strip order. */
+    function mountEager() {
+        for (const id of order) if (byId.get(id).eager && !panes.has(id)) mount(id);
+    }
+
+    function unmount(id) {
+        const entry = panes.get(id);
+        if (!entry) return;
+        panes.delete(id);
+        try { entry.instance?.destroy?.(); } catch (err) {
+            console.warn(`[tabs] pane "${id}" destroy failed`, err);
+        }
+        entry.el.remove();
+    }
+
+    // ── the tab in front ────────────────────────────────────────────────
+
+    /** Classes, ARIA and pane visibility, for the tab in front. */
+    function paint() {
+        for (const [key, { el }] of tabs) {
+            const on = key === current;
+            el.classList.toggle(`${cls('tab')}--on`, on);
+            el.setAttribute('aria-selected', String(on));
+            el.tabIndex = on ? 0 : -1;
+        }
+        for (const [key, entry] of panes) entry.el.hidden = key !== current;
+    }
+
+    /** Make `id` the tab in front. `notify` is false only at creation. */
+    function show(id, notify) {
+        current = id;
+        paint();
+        if (id != null) {
+            mount(id)?.instance?.onShow?.();
+            if (destroyed) return;   // a pane destroyed the strip as it mounted
+            if (tabs.has(id)) revealInStrip(strip, tabs.get(id).el);
+        }
+        if (notify) onSelect?.(id, id == null ? null : byId.get(id));
+    }
+
+    function select(id, { focus = false } = {}) {
+        if (destroyed || !byId.has(id)) return false;
+        if (id !== current) show(id, true);
+        if (focus && !destroyed) tabs.get(id)?.el.focus();
+        return true;
+    }
+
+    // ── items ───────────────────────────────────────────────────────────
+
+    function setItems(next) {
+        const seen = new Set();
+        order = [];
+        byId.clear();
+        for (const item of next) {
+            if (item?.id == null || seen.has(item.id)) continue;
+            seen.add(item.id);
+            order.push(item.id);
+            byId.set(item.id, { ...item });
+        }
+        for (const id of [...tabs.keys()]) {
+            if (byId.has(id)) continue;
+            tabs.get(id).el.remove();
+            tabs.delete(id);
+            unmount(id);
+        }
+        for (const id of order) {
+            draw(id);
+            strip.appendChild(tabs.get(id).el);   // moves a kept one into its place
+        }
+        dragReorder?.attach();
+    }
+
+    // ── events ──────────────────────────────────────────────────────────
+
+    const idOf = (target) => {
+        const el = target?.closest?.(`.${cls('tab')}`);
+        return el && strip.contains(el) && idByEl.has(el) ? idByEl.get(el) : null;
+    };
+
+    function onClick(e) {
+        const id = idOf(e.target);
+        if (id == null) return;
+        if (e.target.closest(`.${cls('close')}`)) { onClose?.(id, byId.get(id)); return; }
+        if (id === current && !destroyed) { onReselect?.(id, byId.get(id)); return; }
+        select(id);
+    }
+
+    function onAuxClick(e) {
+        const id = idOf(e.target);
+        if (e.button !== 1 || id == null || !byId.get(id)?.closable || !onClose) return;
+        e.preventDefault();
+        onClose(id, byId.get(id));
+    }
+
+    function onKeyDown(e) {
+        const id = idOf(e.target);
+        if (id == null || e.altKey || e.ctrlKey || e.metaKey) return;
+        const at = order.indexOf(id);
+        let to = null;
+        if (e.key === 'ArrowRight') to = order[(at + 1) % order.length];
+        else if (e.key === 'ArrowLeft') to = order[(at - 1 + order.length) % order.length];
+        else if (e.key === 'Home') to = order[0];
+        else if (e.key === 'End') to = order[order.length - 1];
+        else if (e.key === 'Delete' && byId.get(id)?.closable && onClose) {
+            e.preventDefault();
+            onClose(id, byId.get(id));
+            return;
+        }
+        if (to == null) return;
+        e.preventDefault();
+        select(to, { focus: true });
+    }
+
+    function onMenu(e) {
+        const id = idOf(e.target);
+        if (id == null || !onContextMenu) return;
+        e.preventDefault();
+        onContextMenu(id, e, byId.get(id));
+    }
+
+    const onWheel = (e) => wheelStripSideways(strip, e);
+
+    strip.addEventListener('click', onClick);
+    strip.addEventListener('auxclick', onAuxClick);
+    strip.addEventListener('keydown', onKeyDown);
+    strip.addEventListener('contextmenu', onMenu);
+    strip.addEventListener('wheel', onWheel, { passive: false });
+
+    const dragReorder = onReorder ? new DragReorder({
+        container: strip,
+        itemSelector: `.${cls('tab')}`,
+        keyAttr: datasetKey,
+        axis: 'x',
+        draggableGuard: (e) => !e.target.closest?.(`.${cls('close')}`),
+        // DragReorder answers the `data-*` strings; the buttons, now in their
+        // new order, give the caller's ids back unchanged.
+        onReorder: () => {
+            order = [...strip.querySelectorAll(`.${cls('tab')}`)]
+                .filter((el) => idByEl.has(el)).map((el) => idByEl.get(el))
+                .filter((id) => byId.has(id));
+            onReorder(order.slice());
+        },
+    }) : null;
+
+    // ── the api ─────────────────────────────────────────────────────────
+
+    const api = {
+        root,
+        /** Bring a tab to the front. False for an id it does not have. */
+        select: (id) => select(id),
+        /** The tab in front, or null. */
+        active: () => current,
+        /** Whether a tab with this id is in the strip. */
+        has: (id) => byId.has(id),
+        /** The ids, in strip order. */
+        ids: () => order.slice(),
+        /**
+         * Replace the items. The tab in front is `activeId` when given and
+         * present, else the one in front now if it is still there, else the
+         * first. Panes of items that went are destroyed; eager items that
+         * came are mounted, in order, before the tab in front is settled.
+         * No items left: nothing is in front, heard as `onSelect(null, null)`.
+         * Focus on a tab that went moves to the tab in front, unless the
+         * update put it somewhere else (a pane that focuses itself on show).
+         */
+        update(next = [], activeId = undefined) {
+            if (destroyed) return;
+            const focused = doc.activeElement;
+            const focusedTab = idByEl.has(focused) && strip.contains(focused);
+            setItems(next);
+            mountEager();
+            if (destroyed) return;
+            const want = activeId !== undefined && byId.has(activeId) ? activeId
+                : byId.has(current) ? current
+                : order[0] ?? null;
+            if (want !== current) show(want, true);
+            else paint();   // a new button is drawn off; the kept ones keep their state
+            if (destroyed) return;
+            // The focused tab went with its item and focus fell to <body>:
+            // it goes to the tab in front. Focus that landed anywhere else stays.
+            const fell = doc.activeElement == null || doc.activeElement === doc.body;
+            if (focusedTab && !strip.contains(focused) && fell && current != null) {
+                tabs.get(current).el.focus();
+            }
+        },
+        /** `count` on a tab, coloured by `level`; nothing at zero. */
+        setBadge(id, count, level = null) {
+            const item = byId.get(id);
+            if (!item) return;
+            item.badge = { count: Number(count) || 0, level };
+            const span = tabs.get(id).el.querySelector(`.${cls('badge')}`);
+            if (span) drawBadge(span, badgeOf(item));
+        },
+        /** The dot on a tab: a level, `true` for the neutral one, falsy for none. */
+        setIndicator(id, value) {
+            const item = byId.get(id);
+            if (!item) return;
+            item.indicator = value;
+            const span = tabs.get(id).el.querySelector(`.${cls('indicator')}`);
+            if (span) drawIndicator(span, value);
+        },
+        /** A mounted pane's instance, or null. */
+        instance: (id) => panes.get(id)?.instance ?? null,
+        /** Every mounted pane's instance, in mount order. */
+        instances: () => [...panes.values()].map((p) => p.instance).filter(Boolean),
+        /** Gone for good: panes are destroyed, the bus is let go, the markup removed. */
+        destroy() {
+            if (destroyed) return;
+            destroyed = true;
+            try { subscription?.dispose?.(); } catch { /* bus gone */ }
+            strip.removeEventListener('click', onClick);
+            strip.removeEventListener('auxclick', onAuxClick);
+            strip.removeEventListener('keydown', onKeyDown);
+            strip.removeEventListener('contextmenu', onMenu);
+            strip.removeEventListener('wheel', onWheel);
+            dragReorder?.destroy();
+            for (const id of [...panes.keys()]) unmount(id);
+            root.remove();
+        },
+    };
+
+    setItems(items);
+    current = byId.has(active) ? active : order[0] ?? null;
+    mountEager();
+    show(current, false);
+
+    // A pane that destroyed the strip while it mounted leaves nothing to subscribe.
+    if (eventBus && selectEvent && !destroyed) {
+        subscription = eventBus.on?.(selectEvent, (payload) => select(selectFrom(payload))) ?? null;
+    }
+
+    return api;
+}