domma-cms 0.54.2 → 0.66.0

package/plugins/invoice/admin/views/index.js

@@ -1,6 +1,30 @@
 /**
  * Invoice plugin - list view.
+ *
+ * The page is bound: every filter control is an observable, the filtered list
+ * and the KPIs are computeds over them, and one M.effect pushes the result into
+ * Domma's table. There is no applyFilters()/refreshKpis() pass and no
+ * hand-rolled debounce - the search box is `.extend({rateLimit})`, which holds
+ * the NOTIFICATION back without ever delaying the write.
+ *
+ * The table itself stays imperative: T owns that markup and re-renders it on
+ * setData, so bindings placed inside it would not survive. The effect is the
+ * seam between the two.
+ *
+ * Per-row actions live in a CONTEXT MENU rather than in a column of buttons.
+ * There are eleven of them now - print, send, PDF, two spreadsheet formats,
+ * duplicate, two status moves, archive, delete - and a row of eleven icons is
+ * not a table any more. The same menu opens from the row's ⋯ button, so the
+ * gesture is discoverable without a right-click.
  */
+import {canDownloadPdf, downloadPdf, downloadPdfBatch, openPrintWindow} from './print.js?v=9';
+import {disposeOnLeave} from './view-lifecycle.js?v=8';
+import {openSendDialog} from './send.js?v=8';
+import {openInvoiceSettings} from './settings.js?v=8';
+import {exportInvoice, exportList} from './export.js?v=8';
+import {INVOICE_HELP} from './help-content.js?v=8';
+import {openHelpPanel, scanHelp} from '/plugins/_lib/admin/ui/help.js?v=8';
+
 function escapeHtml(s) {
     return String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;');
 }
@@ -15,141 +39,605 @@ const STATUS_BADGE = {
     cancelled: 'badge-secondary'
 };
 
+/**
+ * What the row should SAY its status is.
+ *
+ * `overdue` is derived server-side on every read rather than stored, so a
+ * sent invoice past its due date reports overdue without anything having had
+ * to run a job to flip it. The stored status is still `sent`, which is why the
+ * editor's dropdown does not suddenly disagree with the list.
+ *
+ * @param {object} row
+ * @returns {string}
+ */
+function displayStatus(row) {
+    return row?.overdue ? 'overdue' : (row?.status || 'draft');
+}
+
+function money(amount, currency) {
+    try {
+        return new Intl.NumberFormat('en-GB', { style: 'currency', currency: currency || 'GBP' }).format(Number(amount) || 0);
+    } catch {
+        return `${currency || 'GBP'} ${(Number(amount) || 0).toFixed(2)}`;
+    }
+}
+
 export const indexView = {
     templateUrl: '/plugins/invoice/admin/templates/index.html',
 
     async onMount($container) {
-        let invoices = [];
-        let receivers = [];
-        let table = null;
+        const state = {
+            invoices:  M.observable([]),
+            receivers: M.observable([]),
+            issuers:   M.observable([]),
+            canPdf:    M.observable(false),
+
+            status:       M.observable(''),
+            issuerId:     M.observable(''),
+            from:         M.observable(''),
+            to:           M.observable(''),
+            showArchived: M.observable(false),
+            sortBy:       M.observable('issueDate:desc'),
+            // The write lands immediately; only the announcement waits for the
+            // typing to stop, so the filter runs once per pause, not per key.
+            query:        M.observable('').extend({ rateLimit: 200 })
+        };
+
+        const receiverOf = (id) => state.receivers.value.find((x) => x.id === id) ?? null;
+        const issuerOf   = (id) => state.issuers.value.find((x) => x.id === id) ?? null;
+
+        const receiverName = (id) => {
+            const r = receiverOf(id);
+            return r ? (r.company || r.name || id) : '-';
+        };
+        const issuerName = (id) => {
+            const i = issuerOf(id);
+            return i ? (i.name || id) : '-';
+        };
+
+        state.issuerOptions = M.computed(() => state.issuers.value
+            .map((i) => ({ id: i.id, label: i.name || '(unnamed)' })));
+
+        /**
+         * The rows the table works on.
+         *
+         * The scalar `_` fields exist so T can SORT them: its comparator reads
+         * `row[column.key]`, and `totals` is an object and `receiverId` is an
+         * id, so sorting either column sorted by something nobody can see.
+         */
+        const rows = M.computed(() => state.invoices.value.map((inv) => ({
+            ...inv,
+            _number:   inv.number ?? '',
+            _issuer:   issuerName(inv.issuerId),
+            _receiver: receiverName(inv.receiverId),
+            _status:   displayStatus(inv),
+            _total:    Number(inv.totals?.total) || 0,
+            _balance:  Number(inv.totals?.balance) || 0
+        })));
+
+        state.filtered = M.computed(() => {
+            const status = state.status.value;
+            const issuer = state.issuerId.value;
+            const from   = state.from.value;
+            const to     = state.to.value;
+            const archived = state.showArchived.value;
+            const q = String(state.query.value || '').toLowerCase().trim();
+
+            return rows.value.filter((inv) => {
+                // Archived is a shelf: it is hidden unless asked for, and when
+                // it IS asked for the shelf is all you get - mixing the two
+                // makes "show archived" look like it did nothing.
+                if (Boolean(inv.archived) !== archived) return false;
+                if (status && inv._status !== status) return false;
+                if (issuer && inv.issuerId !== issuer) return false;
+                if (from && String(inv.issueDate ?? '') < from) return false;
+                if (to   && String(inv.issueDate ?? '') > to)   return false;
+                if (!q) return true;
+
+                const receiver = receiverOf(inv.receiverId);
+                return [inv._number, inv._receiver, inv._issuer, receiver?.reference, receiver?.email, inv.notes]
+                    .some((v) => String(v ?? '').toLowerCase().includes(q));
+            });
+        });
+
+        // ---- KPIs -----------------------------------------------------------
+        //
+        // Counted over the LIVE invoices rather than the filtered list: a KPI
+        // that moved with the search box would answer a different question
+        // every keystroke, and the one being asked here is "how is the ledger".
+
+        const live = M.computed(() => state.invoices.value.filter((i) => !i.archived));
+        const countBy = (test) => M.computed(() => live.value.filter(test).length);
+
+        state.kpiTotal       = M.computed(() => live.value.length);
+        state.kpiPaid        = countBy((i) => i.status === 'paid');
+        state.kpiDrafts      = countBy((i) => i.status === 'draft');
+        state.kpiOverdue     = countBy((i) => displayStatus(i) === 'overdue');
+        state.kpiOutstanding = M.computed(() => {
+            const owed = live.value
+                .filter((i) => ['sent', 'overdue'].includes(displayStatus(i)))
+                .reduce((sum, i) => sum + (Number(i.totals?.balance) || 0), 0);
+            return owed;
+        });
+        state.kpiOutstandingText = M.computed(() => {
+            // Whatever the first outstanding invoice is billed in. Mixing
+            // currencies into one total would be a lie, so the count carries
+            // the meaning when they differ.
+            const outstanding = live.value.filter((i) => ['sent', 'overdue'].includes(displayStatus(i)));
+            const currencies = new Set(outstanding.map((i) => i.currency || 'GBP'));
+            if (currencies.size > 1) return `${outstanding.length} invoices`;
+            return money(state.kpiOutstanding.value, [...currencies][0] || 'GBP');
+        });
+
+        state.hasFilters = M.computed(() => Boolean(
+            state.status.value || state.issuerId.value || state.from.value
+            || state.to.value || state.query.value || state.showArchived.value
+        ));
+
+        state.matchesText = M.computed(() => {
+            const shown = state.filtered.value.length;
+            const all   = rows.value.filter((i) => Boolean(i.archived) === state.showArchived.value).length;
+            if (!all) return '';
+            return shown === all ? `${all} shown` : `${shown} of ${all} shown`;
+        });
+
+        state.hasRows = M.computed(() => state.filtered.value.length > 0);
+        state.isEmpty = M.computed(() => state.filtered.value.length === 0);
+
+        // Three different nothings, and saying which one it is saves a hunt:
+        // an empty ledger, an empty shelf, or a filter that matches nothing.
+        state.emptyText = M.computed(() => {
+            if (!state.invoices.value.length) return 'No invoices yet. Click “New Invoice” to create your first.';
+            if (state.showArchived.value
+                && !state.invoices.value.some((i) => i.archived)) return 'Nothing has been archived.';
+            return 'No invoice matches those filters.';
+        });
+
+        // ---- can we invoice at all? ----------------------------------------
+        //
+        // An invoice needs somebody at both ends, and the server refuses one
+        // without them. A button that leads to a screen whose Save can only
+        // fail is worse than a button that is plainly off, so this is computed
+        // from the same two lists the editor's pickers are built from.
+
+        // Each of these reads the OBSERVABLES, not each other. A computed built
+        // on another computed updated when something read it through a third
+        // computed (`newInvoiceTitle` was correct all along) but the `data-if`
+        // and `data-bind-disabled` hung off it never re-ran - the element stayed
+        // and the button stayed disabled with the right title on it. One level
+        // of derivation, and all three agree.
+        const noIssuers   = () => state.issuers.value.length === 0;
+        const noReceivers = () => state.receivers.value.length === 0;
+
+        state.needsIssuer   = M.computed(noIssuers);
+        state.needsReceiver = M.computed(noReceivers);
+        state.needsSetup    = M.computed(() => noIssuers() || noReceivers());
+        state.cannotCreate  = M.computed(() => noIssuers() || noReceivers());
+
+        state.newInvoiceTitle = M.computed(() => {
+            if (!noIssuers() && !noReceivers()) return 'Create a new invoice';
+            const missing = [noIssuers() ? 'an issuer' : '', noReceivers() ? 'a receiver' : '']
+                .filter(Boolean).join(' and ');
+            return `Add ${missing} first - an invoice needs somebody at both ends.`;
+        });
+
+        state.setupTitle = M.computed(() => (noIssuers() && noReceivers()
+            ? 'Two things first'
+            : 'One thing first'));
+
+        state.setupText = M.computed(() => {
+            if (noIssuers() && noReceivers()) {
+                return 'An invoice is raised by an issuer (you) for a receiver (your customer). Add one of each and New Invoice switches on.';
+            }
+            if (noIssuers()) {
+                return 'An issuer is you - the trading name, address and bank details an invoice is paid into.';
+            }
+            return 'A receiver is who you are billing. If you use Contacts, you can import one.';
+        });
+
+        state.addIssuer   = () => openSettings('issuers');
+        state.addReceiver = () => openSettings('receivers');
+        state.openHelp    = () => openHelpPanel(INVOICE_HELP);
+
+        // ---- the KPI tiles are filters -------------------------------------
+        //
+        // A number you cannot act on is a poster. Clicking one puts the list
+        // into the state it counts, which is what somebody wanted the moment
+        // they read it.
+
+        // Assigned once the pickers exist; the KPI tiles and Clear both reset
+        // the date range and are wired before them.
+        let clearPickers = () => {};
+
+        const filterTo = (status) => {
+            state.showArchived.value = false;
+            state.query.value = '';
+            state.issuerId.value = '';
+            state.from.value = '';
+            state.to.value = '';
+            state.status.value = status;
+            clearPickers();
+        };
+
+        state.showAll         = () => filterTo('');
+        state.showOutstanding = () => filterTo('sent');
+        state.showOverdue     = () => filterTo('overdue');
+        state.showPaid        = () => filterTo('paid');
+        state.showDrafts      = () => filterTo('draft');
+
+        state.newInvoice = () => {
+            if (noIssuers() || noReceivers()) {
+                E.toast(state.newInvoiceTitle.value, { type: 'error' });
+                return;
+            }
+            R.navigate('#/plugins/invoice/new');
+        };
+
+        state.clearFilters = () => {
+            state.status.value = '';
+            state.issuerId.value = '';
+            state.from.value = '';
+            state.to.value = '';
+            state.query.value = '';
+            state.showArchived.value = false;
+            // The pickers own their inputs' text, so clearing the observable is
+            // not enough - the field would still read as a date it no longer
+            // filters by.
+            clearPickers();
+        };
+
+        const exportNames = (inv) => ({
+            issuerName: issuerName(inv.issuerId),
+            receiverName: receiverName(inv.receiverId)
+        });
+
+        state.exportCsv   = () => exportList(state.filtered.value, 'csv', exportNames);
+        state.exportExcel = () => exportList(state.filtered.value, 'excel', exportNames);
+        // The spreadsheet exports describe the invoices; this one IS them - the
+        // same documents a client receives, one per page. It goes through the
+        // server because that is where the renderer is, so unlike CSV and Excel
+        // it is offered only where a PDF can actually be made.
+        state.exportPdf   = () => downloadPdfBatch(state.filtered.value.map((inv) => inv.id));
+
+        // ---- mutations ------------------------------------------------------
+
+        /** Replace one invoice in the list, in place. */
+        function replace(updated) {
+            if (!updated?.id) return;
+            state.invoices.value = state.invoices.value.map((x) => (x.id === updated.id ? updated : x));
+        }
+
+        async function setStatus(inv, status) {
+            try {
+                const res = await H.put(`${BASE}/invoices/${inv.id}`, { status });
+                const out = res?.data ?? res;
+                if (out?.error) throw new Error(out.error);
+                replace(out);
+                E.toast(`Marked ${status}.`, { type: 'success' });
+            } catch (err) {
+                E.toast(err?.message ?? 'Could not update that invoice.', { type: 'error' });
+            }
+        }
+
+        async function setArchived(inv, archived) {
+            try {
+                const res = await H.put(`${BASE}/invoices/${inv.id}`, { archived });
+                const out = res?.data ?? res;
+                if (out?.error) throw new Error(out.error);
+                replace(out);
+                E.toast(archived ? 'Archived.' : 'Restored.', { type: 'success' });
+            } catch (err) {
+                E.toast(err?.message ?? 'Could not archive that invoice.', { type: 'error' });
+            }
+        }
 
-        function receiverName(id) {
-            const r = receivers.find((x) => x.id === id);
-            if (!r) return '-';
-            return r.company || r.name || id;
+        async function duplicate(inv) {
+            try {
+                const res = await H.post(`${BASE}/invoices/${inv.id}/duplicate`, {});
+                const out = res?.data ?? res;
+                if (out?.error) throw new Error(out.error);
+                state.invoices.value = [out, ...state.invoices.value];
+                E.toast(`Copied to ${out.number}.`, { type: 'success' });
+                R.navigate(`#/plugins/invoice/edit/${out.id}`);
+            } catch (err) {
+                E.toast(err?.message ?? 'Could not copy that invoice.', { type: 'error' });
+            }
         }
 
-        function fmt(amount, currency) {
+        async function remove(inv) {
+            const ok = await E.confirm(`Delete invoice ${inv.number ?? ''}? Archiving keeps it and hides it.`);
+            if (!ok) return;
             try {
-                return new Intl.NumberFormat('en-GB', { style: 'currency', currency: currency || 'GBP' }).format(Number(amount) || 0);
+                await H.delete(`${BASE}/invoices/${inv.id}`);
+                E.toast('Invoice deleted.', { type: 'success' });
+                // One write; the KPIs, the count and the table follow.
+                state.invoices.value = state.invoices.value.filter((x) => x.id !== inv.id);
             } catch {
-                return `${currency || 'GBP'} ${Number(amount).toFixed(2)}`;
+                E.toast('Delete failed.', { type: 'error' });
             }
         }
 
-        function buildTable(data) {
-            const el = $container.find('#invoices-table').get(0);
-            if (!el) return;
+        // ---- the table ------------------------------------------------------
+
+        const tableEl = $container.find('#invoices-table').get(0);
+        let table = null;
+        // Declared before renderTable, which closes over it: T's onSort fires
+        // from inside the table, and a `let` read before its initialiser is a
+        // ReferenceError rather than `undefined`.
+        let syncingSort = false;
+
+        function renderTable(data) {
+            if (!tableEl) return;
             if (table) {
                 table.setData(data);
-                Domma.icons.scan(el);
+                Domma.icons.scan(tableEl);
                 return;
             }
-            table = T.create(el, {
+            table = T.create(tableEl, {
                 data,
                 columns: [
                     {
-                        key: 'number', title: 'Number', sortable: true,
-                        render: (v, row) => `<a href="#/plugins/invoice/edit/${escapeHtml(row.id)}" style="font-weight:600;">${escapeHtml(v || '-')}</a>`
+                        key: '_number', title: 'Number', sortable: true,
+                        render: (v, row) => `<a class="invoice-number-link" data-id="${escapeHtml(row.id)}" href="#/plugins/invoice/edit/${escapeHtml(row.id)}">${escapeHtml(v || '-')}</a>`
                     },
-                    { key: 'receiverId', title: 'Billed To', sortable: false,
-                        render: (v) => escapeHtml(receiverName(v))
-                    },
-                    { key: 'issueDate', title: 'Issue Date', sortable: true,
+                    { key: '_receiver', title: 'Billed To', sortable: true, render: (v) => escapeHtml(v) },
+                    { key: 'issueDate', title: 'Issued', sortable: true,
                         render: (v) => v ? escapeHtml(D(v).format('DD MMM YYYY')) : '-'
                     },
-                    { key: 'totals', title: 'Total', sortable: false,
-                        render: (totals, row) => `<span style="font-variant-numeric:tabular-nums;">${escapeHtml(fmt(totals?.total ?? 0, row.currency))}</span>`
+                    { key: 'dueDate', title: 'Due', sortable: true,
+                        render: (v, row) => {
+                            if (!v) return '-';
+                            const late = row._status === 'overdue';
+                            return `<span class="${late ? 'text-danger' : ''}">${escapeHtml(D(v).format('DD MMM YYYY'))}</span>`;
+                        }
+                    },
+                    { key: '_total', title: 'Total', sortable: true,
+                        render: (v, row) => `<span class="invoice-num">${escapeHtml(money(v, row.currency))}</span>`
                     },
-                    { key: 'status', title: 'Status', sortable: true,
-                        render: (v) => `<span class="badge ${STATUS_BADGE[v] || 'badge-secondary'}">${escapeHtml(v || 'draft')}</span>`
+                    { key: '_status', title: 'Status', sortable: true,
+                        render: (v, row) => {
+                            const archived = row.archived ? ' <span class="badge badge-secondary">archived</span>' : '';
+                            return `<span class="badge ${STATUS_BADGE[v] || 'badge-secondary'}">${escapeHtml(v)}</span>${archived}`;
+                        }
                     },
-                    { key: 'id', title: 'Actions', sortable: false,
-                        render: (id) => `<div style="display:flex;gap:.4rem;">
-  <button class="btn btn-sm btn-outline edit-btn" data-id="${escapeHtml(id)}"><span data-icon="edit" data-icon-size="14"></span></button>
-  <a class="btn btn-sm btn-outline" href="${BASE}/invoices/${escapeHtml(id)}/print" target="_blank" title="Print / PDF"><span data-icon="printer" data-icon-size="14"></span></a>
-  <button class="btn btn-sm btn-danger delete-btn" data-id="${escapeHtml(id)}"><span data-icon="trash" data-icon-size="14"></span></button>
-</div>`
+                    // A space, not '': T falls back to the column KEY for a
+                    // falsy title, which printed a column headed "id".
+                    { key: 'id', title: ' ', sortable: false,
+                        render: (id) => `<button class="btn btn-sm btn-ghost invoice-row-menu" data-id="${escapeHtml(id)}" title="Actions" aria-label="Actions">⋯</button>`
                     }
                 ],
-                emptyMessage: 'No invoices yet. Click “New Invoice” to create your first.'
+                // Domma's table ships its own search box. This view already has
+                // one, and its filter also matches the receiver NAME, the
+                // reference and the notes - which a search over the raw row
+                // cannot. Two boxes, one of them worse, is not a feature.
+                searchable: false,
+                pagination: true,
+                pageSize: 25,
+                defaultSort: { column: 'issueDate', direction: 'desc' },
+                // Clicking a header is the other half of the Sort control; this
+                // keeps the two showing the same answer.
+                onSort: ({ sorts }) => {
+                    const first = sorts?.[0];
+                    if (!first) return;
+                    const value = `${first.column}:${first.direction}`;
+                    if (state.sortBy.value !== value) {
+                        syncingSort = true;
+                        state.sortBy.value = value;
+                        syncingSort = false;
+                    }
+                },
+                // NB: Domma's table has no empty-state option, so the "nothing
+                // here" line is in the template, bound to `isEmpty`.
+                pageSizeOptions: [25, 50, 100]
             });
 
-            el.addEventListener('click', async (e) => {
-                const editBtn = e.target.closest('.edit-btn');
-                const delBtn  = e.target.closest('.delete-btn');
-                if (editBtn) R.navigate('#/plugins/invoice/edit/' + editBtn.dataset.id);
-                if (delBtn) {
-                    const id = delBtn.dataset.id;
-                    const inv = invoices.find((x) => x.id === id);
-                    const ok = await E.confirm(`Delete invoice ${inv?.number ?? ''}?`);
-                    if (!ok) return;
-                    try {
-                        await H.delete(`${BASE}/invoices/${id}`);
-                        E.toast('Invoice deleted.', { type: 'success' });
-                        await reload();
-                    } catch {
-                        E.toast('Delete failed.', { type: 'error' });
-                    }
-                }
+            tableEl.addEventListener('click', (e) => {
+                const menuBtn = e.target.closest('.invoice-row-menu');
+                if (!menuBtn) return;
+                e.preventDefault();
+                const rect = menuBtn.getBoundingClientRect();
+                rowMenu?.open(rect.left, rect.bottom, menuBtn.closest('tr'));
             });
 
-            Domma.icons.scan(el);
+            Domma.icons.scan(tableEl);
         }
 
-        function refreshKpis() {
-            const counts = { total: invoices.length, outstanding: 0, paid: 0, drafts: 0 };
-            for (const i of invoices) {
-                if (i.status === 'paid') counts.paid++;
-                else if (i.status === 'draft') counts.drafts++;
-                else if (i.status === 'sent' || i.status === 'overdue') counts.outstanding++;
-            }
-            $container.find('#kpi-total').text(counts.total);
-            $container.find('#kpi-outstanding').text(counts.outstanding);
-            $container.find('#kpi-paid').text(counts.paid);
-            $container.find('#kpi-drafts').text(counts.drafts);
+        // The seam: tracked read of the filtered list, untracked write to the
+        // table, so T's own DOM reads never become dependencies of this effect.
+        // M.effect returns its disposer, not a handle.
+        const stopFeed = M.effect(() => {
+            const data = state.filtered.value;
+            M.untracked(() => renderTable(data));
+        });
+
+        // The Sort select drives T's own sort rather than re-ordering the data,
+        // so there is ONE sort in play and a header click cannot disagree with
+        // the select. `syncingSort` stops the round trip from looping.
+        const stopSort = M.effect(() => {
+            const [column, direction] = String(state.sortBy.value || '').split(':');
+            if (syncingSort || !column) return;
+            M.untracked(() => table?.sort(column, direction === 'asc' ? 'asc' : 'desc'));
+        });
+
+        // ---- the row menu ---------------------------------------------------
+
+        /**
+         * The invoice a gesture landed on.
+         *
+         * T does not put the row key on its `<tr>`, so the id is read off the
+         * only thing in the row that carries one - the number link.
+         *
+         * @param   {Element} target
+         * @returns {object|null}
+         */
+        function invoiceFor(target) {
+            const id = target?.querySelector?.('[data-id]')?.dataset?.id
+                ?? target?.closest?.('[data-id]')?.dataset?.id;
+            if (!id) return null;
+            return state.filtered.value.find((x) => x.id === id) ?? null;
         }
 
-        function applyFilters() {
-            const status = $container.find('#filter-status').val() || '';
-            const q = ($container.find('#filter-search').val() || '').toString().toLowerCase().trim();
-            let filtered = invoices;
-            if (status) filtered = filtered.filter((i) => i.status === status);
-            if (q) {
-                filtered = filtered.filter((i) =>
-                    (i.number ?? '').toLowerCase().includes(q) ||
-                    receiverName(i.receiverId).toLowerCase().includes(q)
+        const rowMenu = E.contextMenu('#invoices-table', {
+            match: 'tbody tr',
+            // A row menu that also offered whatever an ancestor had bound would
+            // be a different menu depending on where the table was mounted.
+            inherit: false,
+            items: (target) => {
+                const inv = invoiceFor(target);
+                if (!inv) return [];
+                const status = inv._status;
+
+                const items = [
+                    { header: inv.number || 'Invoice' },
+                    { label: 'Open', icon: 'edit', action: () => R.navigate(`#/plugins/invoice/edit/${inv.id}`) },
+                    { label: 'Print / preview', icon: 'printer', action: () => openPrintWindow(inv.id) },
+                    { label: 'Send by email', icon: 'mail',
+                        action: () => openSendDialog(inv.id, replace) }
+                ];
+
+                if (state.canPdf.value) {
+                    items.push({ label: 'Download PDF', icon: 'download', action: () => downloadPdf(inv.id) });
+                }
+
+                items.push(
+                    { type: 'divider' },
+                    { label: 'Export', icon: 'file-text', submenu: [
+                        { label: 'CSV', action: () => exportInvoice(inv, 'csv', exportNames(inv)) },
+                        { label: 'Excel', action: () => exportInvoice(inv, 'excel', exportNames(inv)) }
+                    ] },
+                    { label: 'Duplicate', icon: 'copy', action: () => duplicate(inv) },
+                    { type: 'divider' }
+                );
+
+                if (status === 'draft') {
+                    items.push({ label: 'Mark as sent', icon: 'send', action: () => setStatus(inv, 'sent') });
+                }
+                if (status !== 'paid' && status !== 'cancelled') {
+                    items.push({ label: 'Mark as paid', icon: 'check-circle', action: () => setStatus(inv, 'paid') });
+                }
+                if (status !== 'cancelled') {
+                    items.push({ label: 'Cancel invoice', icon: 'x-circle', action: () => setStatus(inv, 'cancelled') });
+                }
+
+                items.push(
+                    { type: 'divider' },
+                    inv.archived
+                        ? { label: 'Restore', icon: 'archive', action: () => setArchived(inv, false) }
+                        : { label: 'Archive', icon: 'archive', action: () => setArchived(inv, true) },
+                    { label: 'Delete', icon: 'trash', danger: true, action: () => remove(inv) }
                 );
+
+                return items;
             }
-            buildTable(filtered);
-        }
+        });
 
-        async function reload() {
-            try {
-                const [invRes, recRes] = await Promise.all([
-                    H.get(`${BASE}/invoices`),
-                    H.get(`${BASE}/receivers`).catch(() => ({ data: [] }))
-                ]);
-                invoices  = invRes.data ?? invRes ?? [];
-                receivers = recRes.data ?? recRes ?? [];
-            } catch {
-                invoices = [];
-                receivers = [];
-                E.toast('Could not load invoices.', { type: 'error' });
+        // ---- settings -------------------------------------------------------
+
+        /**
+         * @param {string} [tab] open straight onto a section
+         * @returns {void}
+         */
+        const openSettings = (tab) => openInvoiceSettings({
+            tab,
+            // Issuers and receivers are edited in there, and this screen gates
+            // New Invoice on both - so it has to hear about it.
+            onChange: async () => {
+                try {
+                    const [recRes, issRes] = await Promise.all([
+                        H.get(`${BASE}/receivers`).catch(() => []),
+                        H.get(`${BASE}/issuers`).catch(() => [])
+                    ]);
+                    state.receivers.value = recRes.data ?? recRes ?? [];
+                    state.issuers.value   = issRes.data ?? issRes ?? [];
+                } catch { /* the list still shows what it had */ }
+            }
+        });
+
+        // The cog belongs in the admin's plugin banner, which this view does
+        // not own - so the helper is imported at RUN time and its absence is
+        // survivable. An older admin simply has no banner to put it in, and the
+        // fallback puts it in the toolbar instead of losing the screen.
+        try {
+            const chrome = await import('/admin/js/lib/plugin-chrome.js');
+            // Help first, settings second: they read left to right, and the
+            // one you need when you are lost should not be the further away.
+            chrome.addBannerAction?.($container, {
+                id: 'invoice-help',
+                icon: 'help-circle',
+                title: 'How invoicing works',
+                onClick: () => openHelpPanel(INVOICE_HELP)
+            });
+            const placed = chrome.addBannerAction?.($container, {
+                id: 'invoice-settings',
+                icon: 'settings',
+                title: 'Invoice settings',
+                onClick: () => openSettings()
+            });
+            if (!placed) throw new Error('no banner');
+        } catch {
+            const toolbar = $container.find('.invoice-toolbar-row').get(0);
+            if (toolbar) {
+                const cog = document.createElement('button');
+                cog.type = 'button';
+                cog.className = 'btn btn-sm btn-ghost';
+                cog.title = 'Invoice settings';
+                const glyph = document.createElement('span');
+                glyph.setAttribute('data-icon', 'settings');
+                glyph.setAttribute('data-icon-size', '16');
+                cog.appendChild(glyph);
+                cog.addEventListener('click', () => openSettings());
+                toolbar.appendChild(cog);
             }
-            refreshKpis();
-            applyFilters();
         }
 
-        $container.find('#btn-new-invoice').on('click', () => R.navigate('#/plugins/invoice/new'));
-        $container.find('#filter-status').on('change', applyFilters);
-        let timer = null;
-        $container.find('#filter-search').on('input', () => {
-            clearTimeout(timer);
-            timer = setTimeout(applyFilters, 200);
+        const handle = M.applyBindings(state, $container.get(0));
+
+        // ---- data -----------------------------------------------------------
+
+        try {
+            const [invRes, recRes, issRes] = await Promise.all([
+                H.get(`${BASE}/invoices`),
+                H.get(`${BASE}/receivers`).catch(() => []),
+                H.get(`${BASE}/issuers`).catch(() => [])
+            ]);
+            state.receivers.value = recRes.data ?? recRes ?? [];
+            state.issuers.value   = issRes.data ?? issRes ?? [];
+            state.invoices.value  = invRes.data ?? invRes ?? [];
+        } catch {
+            E.toast('Could not load invoices.', { type: 'error' });
+        }
+
+        // Only offered where the host can actually render one; a menu item that
+        // always answers "not installed" is worse than no menu item.
+        canDownloadPdf().then((ok) => { state.canPdf.value = ok; });
+
+        // The same calendar the editor uses, on the two range filters. Each
+        // bounds the other, so the range cannot be typed backwards.
+        const fromPicker = E.datePicker($container.find('#filter-from').get(0), {
+            placeholder: 'Any',
+            onChange: (iso) => toPicker?.setOptions({min: iso || null})
         });
+        const toPicker = E.datePicker($container.find('#filter-to').get(0), {
+            placeholder: 'Any',
+            onChange: (iso) => fromPicker?.setOptions({max: iso || null})
+        });
+
+        clearPickers = () => {
+            fromPicker?.setValue('', {silent: true});
+            toPicker?.setValue('', {silent: true});
+            fromPicker?.setOptions({max: null});
+            toPicker?.setOptions({min: null});
+        };
+
+        disposeOnLeave(tableEl, stopFeed, stopSort, handle,
+            () => rowMenu?.destroy?.(),
+            () => fromPicker?.destroy?.(),
+            () => toPicker?.destroy?.());
 
-        await reload();
-        Domma.icons.scan();
+        Domma.icons.scan($container.get(0));
+        // After the bindings, so a control inside a data-if that has just been
+        // put into the document is wired too.
+        M.flush();
+        scanHelp($container.get(0));
     }
 };