flexdesk 0.13.0 → 0.14.1

package/src/ui/components/alert_log.js

@@ -0,0 +1,274 @@
+/**
+ * ══ THE ALERT LOG ═════════════════════════════════════════════════════════
+ *
+ * What an application told its user, kept: every entry, newest first, read or
+ * not, until it is dismissed or falls off the end (FlexDesk STORY-0019, from
+ * bugdesk's `alerts.js`). NotificationCenter's toasts are the moment; this is
+ * the history the Alerts pane (`alerts_pane.js`) and the bell
+ * (NotificationHistory's `alertLog` option) read.
+ *
+ * An ENTRY is `{ id, at, level, title, body?, ref?, read, ruleId?, rule? }`.
+ * `at` is a Date; `level` is one of `info`, `warning`, `alert` (`normalizeLevel`
+ * maps the toast's `warn`/`error` and the server's `danger` onto them).
+ *
+ * WHERE ENTRIES LIVE IS THE EMBEDDER'S — a pluggable SOURCE:
+ *
+ *     load({ offset, limit })  → { entries, more?, unread? }   a page, newest first
+ *     markRead(ids | null)     → null is "all"
+ *     dismiss(ids | null)      → optional; without it nothing can be dismissed
+ *
+ * bugdesk keeps the whole log in its workspace state (`localSource`: one
+ * blob, read once, written on every change); Tables pages its server's
+ * notifications and has no dismiss. A source's `unread` is the count beyond
+ * the loaded page — the server knows it, the page does not.
+ *
+ * CHANGES ARE APPLIED HERE FIRST and the source told after, so a click marks
+ * read at once; a source that refuses is logged and the log re-read, rather
+ * than the click being made to wait on a round trip.
+ */
+
+/** The three levels, worst last; `icon` is a Material Symbols name. */
+export const ALERT_LEVELS = Object.freeze({
+    info: Object.freeze({ label: 'Info', icon: 'info' }),
+    warning: Object.freeze({ label: 'Warning', icon: 'warning' }),
+    alert: Object.freeze({ label: 'Alert', icon: 'notifications_active' }),
+});
+
+const LEVEL_ALIASES = { warn: 'warning', error: 'alert', danger: 'alert', critical: 'alert', success: 'info' };
+
+/** One of `info`, `warning`, `alert`, whatever the caller spelt. */
+export function normalizeLevel(level) {
+    const l = String(level ?? '').toLowerCase();
+    if (ALERT_LEVELS[l]) return l;
+    return LEVEL_ALIASES[l] ?? 'info';
+}
+
+/** The worst level among these entries — a badge's colour — or null for none. */
+export function worstLevel(entries) {
+    let worst = null;
+    for (const e of entries || []) {
+        const l = normalizeLevel(e?.level);
+        if (l === 'alert') return 'alert';
+        if (l === 'warning') worst = 'warning';
+        else if (!worst) worst = 'info';
+    }
+    return worst;
+}
+
+/** "just now", "5 min ago", "3 h ago"; older than a day, the clock time (the day header has the date). */
+export function ago(at, now = new Date()) {
+    const s = Math.max(0, (now - at) / 1000);
+    if (s < 60) return 'just now';
+    if (s < 3600) return `${Math.floor(s / 60)} min ago`;
+    if (s < 86400) return `${Math.floor(s / 3600)} h ago`;
+    return at.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+}
+
+/** TODAY, YESTERDAY, or the date — the Alerts pane's day header. */
+export function dayLabel(at, now = new Date()) {
+    const d = new Date(at.getFullYear(), at.getMonth(), at.getDate());
+    const t = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+    const days = Math.round((t - d) / 86400000);
+    if (days === 0) return 'TODAY';
+    if (days === 1) return 'YESTERDAY';
+    return at.toLocaleDateString([], { weekday: 'short', day: 'numeric', month: 'short', year: 'numeric' })
+        .toUpperCase();
+}
+
+let _seq = 0;
+
+/** An entry in the shape the log keeps, from whatever a source or a caller handed in. */
+function normalizeEntry(raw) {
+    const at = raw.at instanceof Date ? raw.at : new Date(raw.at ?? Date.now());
+    return {
+        ...raw,
+        id: String(raw.id ?? `${Date.now().toString(36)}-${(_seq++).toString(36)}`),
+        at: Number.isNaN(at.getTime()) ? new Date() : at,
+        level: normalizeLevel(raw.level),
+        title: String(raw.title ?? ''),
+        read: !!raw.read,
+    };
+}
+
+/**
+ * A source that keeps the whole log in one stored value — bugdesk's workspace
+ * state, or localStorage. `read()` answers the saved array (or a promise of
+ * it); `write(array)` stores one. Dates are written as ISO strings.
+ */
+export function localSource({ read, write, limit = 300 } = {}) {
+    let all = null;
+    const save = () => {
+        try {
+            write?.(all.map((e) => ({ ...e, at: e.at.toISOString() })));
+        } catch (err) { console.warn('[alert-log] the log could not be saved', err); }
+    };
+    const ensure = async () => {
+        if (all) return all;
+        let saved = [];
+        try { saved = (await read?.()) ?? []; } catch (err) {
+            console.warn('[alert-log] the log could not be read', err);
+        }
+        all = (Array.isArray(saved) ? saved : []).filter((e) => e && typeof e === 'object')
+            .map(normalizeEntry).sort((a, b) => b.at - a.at).slice(0, limit);
+        return all;
+    };
+    return {
+        local: true,
+        async load({ offset = 0, limit: n = limit } = {}) {
+            const list = await ensure();
+            return { entries: list.slice(offset, offset + n), more: offset + n < list.length };
+        },
+        async add(entry) {
+            const list = await ensure();
+            list.unshift(entry);
+            if (list.length > limit) list.length = limit;
+            save();
+        },
+        async markRead(ids) {
+            const want = ids ? new Set(ids) : null;
+            for (const e of await ensure()) if (!want || want.has(e.id)) e.read = true;
+            save();
+        },
+        async dismiss(ids) {
+            const want = ids ? new Set(ids) : null;
+            all = (await ensure()).filter((e) => want && !want.has(e.id));
+            save();
+        },
+    };
+}
+
+/**
+ * @param {object}  [opts]
+ * @param {object}  [opts.source]  where entries live; none keeps them in memory only
+ * @param {number}  [opts.limit]   most entries held, and a page's size
+ * @returns the log
+ */
+export function createAlertLog({ source = null, limit = 300 } = {}) {
+    let entries = [];
+    let more = false;
+    let remoteUnread = null;
+    let loaded = false;
+    let loading = null;
+    const listeners = new Set();
+
+    const changed = () => {
+        for (const fn of [...listeners]) {
+            try { fn(log); } catch (err) { console.warn('[alert-log] listener failed', err); }
+        }
+    };
+    const tell = (verb, ...args) => {
+        const fn = source?.[verb];
+        if (typeof fn !== 'function') return;
+        Promise.resolve().then(() => fn.apply(source, args)).catch((err) => {
+            console.warn(`[alert-log] the source refused ${verb}`, err);
+            log.refresh();
+        });
+    };
+    const page = async (offset) => {
+        const res = (await source?.load?.({ offset, limit })) ?? {};
+        const got = (res.entries ?? []).map(normalizeEntry);
+        return { got, more: !!res.more, unread: Number.isFinite(res.unread) ? res.unread : null };
+    };
+
+    const log = {
+        /** Loaded entries, newest first. */
+        entries: () => entries,
+        loaded: () => loaded,
+        /** Whether the source has older entries than those loaded. */
+        hasMore: () => more,
+        /** Whether entries can be dismissed: a log with no source, or a source that can. */
+        canDismiss: () => !source || typeof source.dismiss === 'function',
+        /** Unread entries: the source's count when it knows one, else the loaded ones. */
+        unreadCount() {
+            const here = entries.filter((e) => !e.read).length;
+            return remoteUnread === null ? here : Math.max(remoteUnread, here);
+        },
+        /** The worst level among unread entries, or null. */
+        worstUnread: () => worstLevel(entries.filter((e) => !e.read)),
+        get: (id) => entries.find((e) => e.id === String(id)) ?? null,
+
+        /** `fn(log)` after every change; answers the unsubscribe. */
+        subscribe(fn) {
+            listeners.add(fn);
+            return () => listeners.delete(fn);
+        },
+
+        /** The first page, again. */
+        refresh() {
+            if (!source?.load) { loaded = true; changed(); return Promise.resolve(log); }
+            loading = page(0).then(({ got, more: m, unread }) => {
+                entries = got;
+                more = m;
+                remoteUnread = unread;
+                loaded = true;
+                changed();
+                return log;
+            }).catch((err) => {
+                console.warn('[alert-log] the log could not be loaded', err);
+                loaded = true;
+                changed();
+                return log;
+            }).finally(() => { loading = null; });
+            return loading;
+        },
+        /** Load once; later calls answer the same promise or nothing. */
+        load() { return loading ?? (loaded ? Promise.resolve(log) : log.refresh()); },
+        /** The next page, after the loaded ones. */
+        async loadMore() {
+            if (!more || !source?.load) return log;
+            const { got, more: m, unread } = await page(entries.length);
+            const seen = new Set(entries.map((e) => e.id));
+            entries = [...entries, ...got.filter((e) => !seen.has(e.id))];
+            more = m;
+            if (unread !== null) remoteUnread = unread;
+            changed();
+            return log;
+        },
+
+        /** A new entry raised HERE (bugdesk's rules): kept, and handed to the source to save. */
+        add(raw) {
+            const entry = normalizeEntry(raw);
+            entries = [entry, ...entries.filter((e) => e.id !== entry.id)];
+            if (entries.length > limit) entries.length = limit;
+            if (remoteUnread !== null && !entry.read) remoteUnread += 1;
+            tell('add', entry);
+            changed();
+            return entry;
+        },
+        /** Entries that arrived from the source's side (a push): shown, not saved back. */
+        receive(raws) {
+            const got = (Array.isArray(raws) ? raws : [raws]).map(normalizeEntry);
+            const ids = new Set(got.map((e) => e.id));
+            const fresh = got.filter((e) => !entries.some((x) => x.id === e.id));
+            entries = [...got, ...entries.filter((e) => !ids.has(e.id))]
+                .sort((a, b) => b.at - a.at).slice(0, limit);
+            if (remoteUnread !== null) remoteUnread += fresh.filter((e) => !e.read).length;
+            changed();
+        },
+        /** Mark these read — all of them when `ids` is omitted. */
+        markRead(ids = null) {
+            const want = ids ? new Set(ids.map(String)) : null;
+            let n = 0;
+            for (const e of entries) if (!e.read && (!want || want.has(e.id))) { e.read = true; n++; }
+            if (remoteUnread !== null) remoteUnread = want ? Math.max(0, remoteUnread - n) : 0;
+            if (!n && want) return;
+            tell('markRead', want ? [...want] : null);
+            changed();
+        },
+        /** Remove these — all of them when `ids` is omitted. Nothing, when the source cannot. */
+        dismiss(ids = null) {
+            if (!log.canDismiss()) return;
+            const want = ids ? new Set(ids.map(String)) : null;
+            const gone = entries.filter((e) => !want || want.has(e.id));
+            if (!gone.length) return;
+            entries = want ? entries.filter((e) => !want.has(e.id)) : [];
+            if (remoteUnread !== null) {
+                remoteUnread = want ? Math.max(0, remoteUnread - gone.filter((e) => !e.read).length) : 0;
+            }
+            tell('dismiss', want ? [...want] : null);
+            changed();
+        },
+    };
+    if (!source?.load) loaded = true;
+    return log;
+}

package/src/ui/components/alerts_pane.js

@@ -0,0 +1,294 @@
+/**
+ * ══ THE ALERTS PANE ═══════════════════════════════════════════════════════
+ *
+ * An alert log (`alert_log.js`) drawn as the bottom panel's Alerts tab: level
+ * chips with counts, a text filter, entries grouped by day with relative
+ * times, an unread mark, Open and Dismiss on each row, Mark all read and Clear
+ * for the lot (FlexDesk STORY-0019, from bugdesk's `alerts.js`). The same
+ * layout whether the log is local or pages a server: *Load older* appears
+ * when the source has more.
+ *
+ *     mountAlertsPane(el, { log, onOpen: (entry) => …, onBadge: ({ unread, level }) => … })
+ *
+ * OPTIONAL, for an embedder with rules of its own (bugdesk): `rules` is
+ * `{ list() → [{ id, name, level, meta?, off? }], onEdit?, foot? }` — a column
+ * of them on the left that narrows the log to one rule (entries carry
+ * `ruleId`) — and `stillMatches(entry)` → true / false / null, drawn as "still
+ * matches" or "no longer matches" on each row.
+ *
+ * NEVER REBUILT UNDER THE POINTER. A log changes on its own — a push from the
+ * server, a rule firing, the minute tick — and a row repainted between a
+ * mousedown and its click loses the click (Tables' recorded trap). While a
+ * button is down inside the pane a repaint waits, and runs once it is up.
+ * The bar (chips, the filter, the buttons) is built once and updated in
+ * place, so typing in the filter never loses the caret either.
+ */
+
+import { ALERT_LEVELS, ago, dayLabel, normalizeLevel } from './alert_log.js';
+
+const CHIPS = [['all', 'All'], ['alert', 'Alert'], ['warning', 'Warning'], ['info', 'Info']];
+
+/**
+ * @param {HTMLElement} host
+ * @param {object}   opts
+ * @param {object}   opts.log           `createAlertLog(…)`
+ * @param {Function}[opts.onOpen]       `(entry)` — Open; the entry is marked read first
+ * @param {Function}[opts.onBadge]      `({ unread, level })` after every change — a tab's badge
+ * @param {object}  [opts.rules]        `{ list, onEdit?, foot? }`
+ * @param {Function}[opts.stillMatches] `(entry) → boolean | null`
+ * @param {Function}[opts.describe]     `(entry) → string` — a small chip on the row (bugdesk: the store)
+ * @param {string}  [opts.status]       the footer line
+ * @param {object}  [opts.empty]        `{ none, filtered }` — the two empty texts
+ * @returns {{ refresh, destroy, root }}
+ */
+export function mountAlertsPane(host, {
+    log, onOpen = null, onBadge = null, rules = null, stillMatches = null, describe = null,
+    status = '', empty = {},
+} = {}) {
+    const doc = host.ownerDocument;
+    const el = (tag, cls, text) => {
+        const n = doc.createElement(tag);
+        if (cls) n.className = cls;
+        if (text !== undefined) n.textContent = text;
+        return n;
+    };
+    const icon = (name) => el('span', 'material-symbols-outlined', name);
+
+    let level = 'all';
+    let rule = null;
+    let q = '';
+    let pointerDown = false;
+    let pending = false;
+    let destroyed = false;
+
+    // ── the frame, built once ────────────────────────────────────────────
+    const root = el('div', 'twm-alerts');
+    let ruleList = null;
+    if (rules) {
+        const side = el('div', 'twm-alerts__rules');
+        const head = el('div', 'twm-alerts__head');
+        head.append(el('span', 'twm-alerts__caps', 'RULES'), el('span', 'twm-alerts__spacer'));
+        if (rules.onEdit) {
+            const edit = el('button', 'twm-alerts__link', 'Edit rules');
+            edit.type = 'button';
+            edit.dataset.act = 'edit-rules';
+            head.append(edit);
+        }
+        ruleList = el('div', 'twm-alerts__rulelist');
+        side.append(head, ruleList);
+        if (rules.foot) side.append(el('div', 'twm-alerts__foot', rules.foot));
+        root.append(side);
+    }
+    const main = el('div', 'twm-alerts__main');
+    const bar = el('div', 'twm-alerts__bar');
+    const chips = el('div', 'twm-alerts__chips');
+    chips.setAttribute('role', 'group');
+    chips.setAttribute('aria-label', 'Level');
+    const chipEls = new Map();
+    for (const [key, label] of CHIPS) {
+        const chip = el('button', 'twm-alerts__chip');
+        chip.type = 'button';
+        chip.dataset.level = key;
+        chip.append(doc.createTextNode(`${label} `), el('span', 'twm-alerts__count', '0'));
+        chips.append(chip);
+        chipEls.set(key, chip);
+    }
+    const input = el('input', 'twm-alerts__q');
+    input.type = 'text';
+    input.autocomplete = 'off';
+    input.spellcheck = false;
+    input.placeholder = 'Filter';
+    input.setAttribute('aria-label', 'Filter alerts');
+    const readAll = el('button', 'twm-btn twm-alerts__btn', 'Mark all read');
+    readAll.type = 'button';
+    readAll.dataset.act = 'read-all';
+    const clear = el('button', 'twm-btn twm-alerts__btn', 'Clear');
+    clear.type = 'button';
+    clear.dataset.act = 'clear';
+    bar.append(chips, input, el('span', 'twm-alerts__spacer'), readAll, clear);
+    const list = el('div', 'twm-alerts__log');
+    const foot = el('div', 'twm-alerts__status', status);
+    foot.hidden = !status;
+    main.append(bar, list, foot);
+    root.append(main);
+    host.append(root);
+
+    // ── what is shown ───────────────────────────────────────────────────
+    const byRule = () => (rule ? log.entries().filter((e) => String(e.ruleId) === rule) : log.entries());
+    const shown = () => {
+        const needle = q.trim().toLowerCase();
+        return byRule()
+            .filter((e) => level === 'all' || e.level === level)
+            .filter((e) => !needle || `${e.ref ?? ''} ${e.title} ${e.body ?? ''} ${e.rule ?? ''}`
+                .toLowerCase().includes(needle));
+    };
+
+    function row(entry, now) {
+        const lv = ALERT_LEVELS[normalizeLevel(entry.level)];
+        const r = el('div', `twm-alerts__row twm-alerts__row--${entry.level}${entry.read ? '' : ' twm-alerts__row--unread'}`);
+        r.dataset.id = entry.id;
+        const mark = el('span', 'twm-alerts__unread');
+        mark.setAttribute('aria-label', entry.read ? 'Read' : 'Unread');
+        const ic = icon(lv.icon);
+        ic.classList.add('twm-alerts__icon');
+        ic.title = lv.label;
+        const time = el('span', 'twm-alerts__time', ago(entry.at, now));
+        time.title = entry.at.toLocaleString();
+        const text = el('span', 'twm-alerts__text');
+        text.append(el('span', 'twm-alerts__title', entry.title));
+        if (entry.body) text.append(el('span', 'twm-alerts__body', entry.body));
+        const cells = [mark, ic, time];
+        if (rules) cells.push(el('span', 'twm-alerts__rule', entry.rule ?? ''));
+        const tag = describe?.(entry);
+        cells.push(el('span', tag ? 'twm-alerts__tag' : 'twm-alerts__tag twm-alerts__tag--none', tag ?? ''));
+        const ref = el(entry.ref && onOpen ? 'button' : 'span', 'twm-alerts__ref', entry.ref ?? '');
+        if (ref.tagName === 'BUTTON') { ref.type = 'button'; ref.dataset.open = entry.id; }
+        cells.push(ref, text);
+        if (stillMatches) {
+            const still = stillMatches(entry);
+            cells.push(el('span', `twm-alerts__state${still === false ? ' twm-alerts__state--gone' : ''}`,
+                still === true ? 'still matches' : still === false ? 'no longer matches' : ''));
+        }
+        const acts = el('span', 'twm-alerts__acts');
+        if (onOpen) {
+            const open = el('button', 'twm-alerts__icon-btn');
+            open.type = 'button';
+            open.dataset.open = entry.id;
+            open.title = 'Open';
+            open.setAttribute('aria-label', 'Open');
+            open.append(icon('open_in_new'));
+            acts.append(open);
+        }
+        if (log.canDismiss()) {
+            const dis = el('button', 'twm-alerts__icon-btn');
+            dis.type = 'button';
+            dis.dataset.dismiss = entry.id;
+            dis.title = 'Dismiss';
+            dis.setAttribute('aria-label', 'Dismiss');
+            dis.append(icon('close'));
+            acts.append(dis);
+        }
+        cells.push(acts);
+        r.append(...cells);
+        return r;
+    }
+
+    function paint() {
+        if (destroyed) return;
+        if (pointerDown) { pending = true; return; }
+        pending = false;
+        const now = new Date();
+        const all = log.entries();
+        const scoped = byRule();
+
+        for (const [key, chip] of chipEls) {
+            const on = level === key;
+            chip.classList.toggle('twm-alerts__chip--on', on);
+            chip.setAttribute('aria-pressed', String(on));
+            chip.querySelector('.twm-alerts__count').textContent =
+                String(scoped.filter((e) => key === 'all' || e.level === key).length);
+        }
+        readAll.disabled = !all.some((e) => !e.read) && log.unreadCount() === 0;
+        clear.hidden = !log.canDismiss();
+        clear.disabled = !all.length;
+
+        if (ruleList) {
+            const items = [{ id: null, name: 'All alerts', meta: String(all.length) }, ...(rules.list?.() ?? [])];
+            ruleList.replaceChildren(...items.map((r) => {
+                const key = r.id === null ? null : String(r.id);
+                const b = el('button', `twm-alerts__rulebtn${rule === key ? ' twm-alerts__rulebtn--on' : ''}${r.off ? ' twm-alerts__rulebtn--off' : ''}`);
+                b.type = 'button';
+                b.dataset.rule = key ?? '';
+                b.setAttribute('aria-pressed', String(rule === key));
+                b.append(el('span', `twm-alerts__dot${r.level ? ` twm-alerts__dot--${normalizeLevel(r.level)}` : ''}`),
+                         el('span', 'twm-alerts__rulename', r.name || 'Unnamed rule'),
+                         el('span', 'twm-alerts__meta', r.meta ?? ''));
+                return b;
+            }));
+        }
+
+        const rows = [];
+        let lastDay = '';
+        for (const entry of shown()) {
+            const day = dayLabel(entry.at, now);
+            if (day !== lastDay) rows.push(el('div', 'twm-alerts__day', day));
+            lastDay = day;
+            rows.push(row(entry, now));
+        }
+        if (!rows.length) {
+            rows.push(el('div', 'twm-alerts__none', !log.loaded() ? 'Loading…'
+                : all.length ? (empty.filtered ?? 'No alerts match.') : (empty.none ?? 'Nothing yet.')));
+        }
+        if (log.hasMore()) {
+            const older = el('button', 'twm-btn twm-alerts__more', 'Load older');
+            older.type = 'button';
+            older.dataset.act = 'more';
+            rows.push(older);
+        }
+        const scroll = list.scrollTop;
+        list.replaceChildren(...rows);
+        list.scrollTop = scroll;
+        onBadge?.({ unread: log.unreadCount(), level: log.worstUnread() });
+    }
+
+    // ── input ───────────────────────────────────────────────────────────
+    const onDown = () => { pointerDown = true; };
+    const onUp = () => {
+        if (!pointerDown) return;
+        // After the click this mouseup belongs to has been dispatched.
+        setTimeout(() => {
+            pointerDown = false;
+            if (pending) paint();
+        }, 0);
+    };
+    root.addEventListener('mousedown', onDown, true);
+    root.addEventListener('pointerdown', onDown, true);
+    doc.addEventListener('mouseup', onUp, true);
+    doc.addEventListener('pointerup', onUp, true);
+    doc.addEventListener('pointercancel', onUp, true);
+
+    root.addEventListener('click', (event) => {
+        const t = event.target;
+        const chip = t.closest('[data-level]');
+        if (chip) { level = chip.dataset.level; paint(); return; }
+        const r = t.closest('[data-rule]');
+        if (r) { rule = r.dataset.rule || null; paint(); return; }
+        const open = t.closest('[data-open]');
+        if (open) {
+            const entry = log.get(open.dataset.open);
+            if (!entry) return;
+            log.markRead([entry.id]);
+            onOpen?.(entry);
+            return;
+        }
+        const dis = t.closest('[data-dismiss]');
+        if (dis) { log.dismiss([dis.dataset.dismiss]); return; }
+        const act = t.closest('[data-act]')?.dataset.act;
+        if (act === 'read-all') log.markRead();
+        else if (act === 'clear') log.dismiss();
+        else if (act === 'more') log.loadMore();
+        else if (act === 'edit-rules') rules?.onEdit?.();
+    });
+    input.addEventListener('input', () => { q = input.value; paint(); });
+
+    const unsubscribe = log.subscribe(() => paint());
+    // "5 min ago" moves on its own.
+    const timer = setInterval(paint, 60000);
+    paint();
+    log.load?.();
+
+    return {
+        root,
+        refresh: paint,
+        destroy() {
+            if (destroyed) return;
+            destroyed = true;
+            clearInterval(timer);
+            unsubscribe();
+            doc.removeEventListener('mouseup', onUp, true);
+            doc.removeEventListener('pointerup', onUp, true);
+            doc.removeEventListener('pointercancel', onUp, true);
+            root.remove();
+        },
+    };
+}

package/src/ui/components/data_table.js

@@ -327,7 +327,8 @@ const AUTOSIZE_MAX_PX = 520;
  * @property {Function} [onRowClick] - Row click handler: (rowIdx, row, ev) => void. Receives the original (unfiltered) row index.
  * @property {Function} [onRowContextMenu] - Row right-click handler: (rowIdx, row, ev) => void. Fires before the default context menu; call ev.preventDefault() to suppress the default.
  * @property {Function} [onCellContextMenu] - Cell right-click handler: (colIdx, rowIdx, value, td, ev) => void. Fires before onRowContextMenu; same suppression semantics.
- * @property {boolean} [showExportButton=false] - Adds a "CSV" download button to the pagination strip that invokes `downloadCSV()`.
+ * @property {boolean} [showExportButton=false] - Adds a "CSV" download button to the pagination strip that invokes `downloadCSV()`. The strip is drawn for it even when the table fits on one page (0.14.1).
+ * @property {string|function(DataTable): string} [exportFilename='data.csv'] - The file the export button saves (0.14.1); in a desktop host, the name the Save dialog suggests.
  * @property {Object} [host] - A Host (see ui/js/host/host.js). Its `dialogs` capability backs `downloadCSV()`'s native save dialog; without it CSV export falls back to a Blob download.
  * @property {Object} [stateStore] - `{ ready(), get(key), set(key, state) }` — REQUIRED when `persistKey` is set. Built by `createTableStateStore()`.
  * @property {'container'|'content'} [columnFit='container'] - How the automatic fit pass sizes a column the user has NOT dragged. 'container' squeezes every column into the wrap: a 360px cap, a more generous one for the first column, and water-fill-shrink toward the 40px floor when they do not fit. 'content' sizes each column to its own content through the same `_autoWidth` a grip double-click uses (520px cap) and lets the body scroll sideways rather than squeezing. A pinned column is honoured verbatim under both.
@@ -466,6 +467,7 @@ export class DataTable {
             onRowContextMenu: null,
             onCellContextMenu: null,
             showExportButton: false,
+            exportFilename: null,
             // The host port. TOP LEVEL, deliberately — NOT inside `services`,
             // which most call sites never pass. Supplies the native save
             // dialog for downloadCSV(); absent => Blob fallback.
@@ -2623,7 +2625,7 @@ export class DataTable {
         // Don't render the strip when there's only one page — the row
         // count is uninformative (the table itself shows every row) and
         // the nav buttons would all be disabled.
-        if (totalPages <= 1 && !isFiltered) return null;
+        if (totalPages <= 1 && !isFiltered) return this._createExportOnlyStrip();
         const currentPage = Math.floor(offset / pageSize) + 1;
         const hasPrev = offset > 0;
         const hasNext = offset + pageSize < effectiveTotal;
@@ -2719,16 +2721,35 @@ export class DataTable {
         // CSV export button (opt-in). Re-uses the existing downloadCSV
         // method which already handles the host save dialog + browser
         // fallback.
-        if (this.config.showExportButton) {
-            const exportBtn = this._createPaginationBtn(
-                'download', 'Download visible rows as CSV', false,
-                () => this.downloadCSV('data.csv'));
-            el.appendChild(exportBtn);
-        }
+        if (this.config.showExportButton) el.appendChild(this._createExportBtn());
 
         return el;
     }
 
+    /** The export button: downloadCSV() under the configured file name. */
+    _createExportBtn() {
+        const name = this.config.exportFilename;
+        const filename = (typeof name === 'function' ? name(this) : name) || 'data.csv';
+        return this._createPaginationBtn('download', 'Download visible rows as CSV', false,
+                                         () => this.downloadCSV(filename));
+    }
+
+    /**
+     * The strip on a table with one page: nothing, as always, unless the export
+     * button needs somewhere to be. Then the button alone, with no page
+     * buttons (0.14.1).
+     */
+    _createExportOnlyStrip() {
+        if (!this.config.showExportButton) return null;
+        const el = document.createElement('div');
+        el.className = 'twm-pagination-controls twm-pagination-controls--export-only';
+        el.style.cssText = 'display:flex; align-items:center; gap:6px; padding:2px 8px; border-bottom:1px solid #2a2a2a; font-size:11px;';
+        const spacer = document.createElement('div');
+        spacer.style.flex = '1';
+        el.append(spacer, this._createExportBtn());
+        return el;
+    }
+
     _createPaginationBtn(icon, tooltip, disabled, onClick, textLabel = null) {
         const btn = document.createElement('button');
         btn.type = 'button';
@@ -4738,8 +4759,8 @@ export class DataTable {
         const pn = this._pageNav({ offset, held: drawn, total, hasMore: hasMoreKnown, pageSize });
         const { hasPrev, hasNext, page } = pn;
         const totalPages = pn.pages;
-        if (known && totalPages <= 1 && !isFiltered && !hasPrev) return null;
-        if (!known && !hasPrev && !hasNext) return null;
+        if (known && totalPages <= 1 && !isFiltered && !hasPrev) return this._createExportOnlyStrip();
+        if (!known && !hasPrev && !hasNext) return this._createExportOnlyStrip();
         const maxJump = Number.isFinite(c.maxJumpOffset) ? c.maxJumpOffset : null;
 
         const go = (newOffset) => {
@@ -4817,10 +4838,7 @@ export class DataTable {
         jumpBtn.dataset.pager = 'go';
 
         el.append(info, spacer, firstBtn, prevBtn, pageInfo, nextBtn, lastBtn, jumpInput, jumpBtn);
-        if (c.showExportButton) {
-            el.appendChild(this._createPaginationBtn('download', 'Download visible rows as CSV', false,
-                                                     () => this.downloadCSV('data.csv')));
-        }
+        if (c.showExportButton) el.appendChild(this._createExportBtn());
         return el;
     }