domma-cms 0.55.1 → 0.66.0

package/plugins/invoice/admin/templates/index.html

@@ -1,33 +1,75 @@
-<div class="view-header d-flex align-items-center justify-content-between mb-4">
-  <h1 class="h3 mb-0"><span data-icon="file-text"></span> Invoices</h1>
-  <button id="btn-new-invoice" class="btn btn-primary">
-    <span data-icon="plus"></span> New Invoice
-  </button>
-</div>
+<!--
+  The KPI numbers, the filter controls and the "n of m" line are bound; the
+  table is Domma's T, fed from one M.effect. Nothing on this page is refreshed
+  by hand.
 
-<div class="grid grid-cols-4 gap-3 mb-4">
-  <div class="card"><div class="card-body">
-    <div class="text-muted small">Total invoices</div>
-    <div class="h3 mb-0" id="kpi-total">-</div>
+  There is no page heading here on purpose - the admin wraps every plugin view
+  in its own banner, which carries the name, the version and (from this plugin)
+  the settings cog. A second <h1> underneath it would just be the same words
+  twice.
+-->
+<div class="grid grid-cols-5 gap-3 mb-4">
+  <div class="card stat-card invoice-kpi" data-on-click="showAll"
+       data-help="Everything not archived. Click any tile to filter the list by it.">
+    <div class="card-body">
+    <div class="stat-icon"><span data-icon="file-text"></span></div>
+    <div>
+      <div class="stat-value" id="kpi-total" data-bind-text="kpiTotal.value">-</div>
+      <div class="stat-label">Total invoices</div>
+    </div>
   </div></div>
-  <div class="card"><div class="card-body">
-    <div class="text-muted small">Outstanding</div>
-    <div class="h3 mb-0" id="kpi-outstanding">-</div>
+  <div class="card stat-card invoice-kpi" data-on-click="showOutstanding"
+       data-help="What you are still owed on invoices you have sent, less anything already paid against them.">
+    <div class="card-body">
+    <div class="stat-icon stat-icon--warning"><span data-icon="clock"></span></div>
+    <div>
+      <div class="stat-value" id="kpi-outstanding" data-bind-text="kpiOutstandingText.value">-</div>
+      <div class="stat-label">Outstanding</div>
+    </div>
   </div></div>
-  <div class="card"><div class="card-body">
-    <div class="text-muted small">Paid</div>
-    <div class="h3 mb-0" id="kpi-paid">-</div>
+  <div class="card stat-card invoice-kpi" data-on-click="showOverdue"
+       data-help="Sent invoices past their due date. Worked out on every read, so nothing has to run to keep it true.">
+    <div class="card-body">
+    <div class="stat-icon stat-icon--danger"><span data-icon="alert-triangle"></span></div>
+    <div>
+      <div class="stat-value" id="kpi-overdue" data-bind-text="kpiOverdue.value">-</div>
+      <div class="stat-label">Overdue</div>
+    </div>
   </div></div>
-  <div class="card"><div class="card-body">
-    <div class="text-muted small">Drafts</div>
-    <div class="h3 mb-0" id="kpi-drafts">-</div>
+  <div class="card stat-card invoice-kpi" data-on-click="showPaid"
+       data-help="Invoices marked paid, either by hand or by a payment that settled the balance.">
+    <div class="card-body">
+    <div class="stat-icon stat-icon--success"><span data-icon="check-circle"></span></div>
+    <div>
+      <div class="stat-value" id="kpi-paid" data-bind-text="kpiPaid.value">-</div>
+      <div class="stat-label">Paid</div>
+    </div>
+  </div></div>
+  <div class="card stat-card invoice-kpi" data-on-click="showDrafts"
+       data-help="Started but not sent. A draft moves to sent the first time you email it.">
+    <div class="card-body">
+    <div class="stat-icon"><span data-icon="edit"></span></div>
+    <div>
+      <div class="stat-value" id="kpi-drafts" data-bind-text="kpiDrafts.value">-</div>
+      <div class="stat-label">Drafts</div>
+    </div>
   </div></div>
 </div>
 
-<div class="card mb-3">
+<div class="card mb-3 invoice-toolbar">
   <div class="card-body">
-    <div class="d-flex gap-2 flex-wrap">
-      <select id="filter-status" class="form-select" style="width:auto;">
+
+    <div class="invoice-toolbar-row">
+      <label class="invoice-search"
+             data-help="Matches the invoice number, the company or contact billed, the issuer, the customer reference and the notes.">
+        <span data-icon="search" data-icon-size="15"></span>
+        <input id="filter-search" type="search" class="form-input"
+               data-model="query.value" placeholder="Search number, company or reference…">
+      </label>
+
+      <select id="filter-status" class="form-select invoice-filter-narrow" data-model="status.value"
+              aria-label="Filter by status"
+              data-help="Overdue is worked out from the due date rather than stored, so it appears here without anything having changed the invoice.">
         <option value="">All statuses</option>
         <option value="draft">Draft</option>
         <option value="sent">Sent</option>
@@ -35,9 +77,97 @@
         <option value="overdue">Overdue</option>
         <option value="cancelled">Cancelled</option>
       </select>
-      <input id="filter-search" type="search" class="form-control" style="width:240px;" placeholder="Search number or receiver…">
+
+      <select id="filter-issuer" class="form-select invoice-filter-narrow" data-model="issuerId.value"
+              data-options="issuerOptions.value" data-options-value="id" data-options-text="label"
+              data-options-caption="'All issuers'" aria-label="Filter by issuer"
+              data-help="Which of your own businesses raised the invoice. Manage these under the cog, in Issuers."></select>
+
+      <select id="sort-by" class="form-select invoice-filter-narrow" data-model="sortBy.value"
+              aria-label="Sort by"
+              data-help="Clicking a column heading does the same thing, and the two always agree.">
+        <option value="issueDate:desc">Newest first</option>
+        <option value="issueDate:asc">Oldest first</option>
+        <option value="_number:asc">Number A-Z</option>
+        <option value="_number:desc">Number Z-A</option>
+        <option value="_receiver:asc">Billed to A-Z</option>
+        <option value="_total:desc">Largest first</option>
+        <option value="_total:asc">Smallest first</option>
+        <option value="dueDate:asc">Due soonest</option>
+      </select>
+
+      <button id="btn-new-invoice" class="btn btn-primary" data-on-click="newInvoice"
+              data-bind-disabled="cannotCreate.value"
+              data-bind-title="newInvoiceTitle.value">
+        <span data-icon="plus"></span> New Invoice
+      </button>
+    </div>
+
+    <div class="invoice-toolbar-row invoice-toolbar-row--sub">
+      <label class="invoice-field">
+        <span>Issued from</span>
+        <input id="filter-from" type="text" class="form-input" data-model="from.value">
+      </label>
+      <label class="invoice-field">
+        <span>to</span>
+        <input id="filter-to" type="text" class="form-input" data-model="to.value">
+      </label>
+
+      <label class="invoice-check"
+             data-help="Archived invoices are kept but hidden. This swaps the list over to them - it does not add them to the live list.">
+        <input type="checkbox" class="form-checkbox" data-model="showArchived.value">
+        <span>Show archived</span>
+      </label>
+
+      <button class="btn btn-sm btn-ghost" data-on-click="clearFilters" data-if="hasFilters.value">
+        Clear filters
+      </button>
+
+      <span class="invoice-toolbar-spacer"></span>
+
+      <span class="text-muted text-sm invoice-matches" data-bind-text="matchesText.value"></span>
+
+      <button class="btn btn-sm btn-outline" data-on-click="exportCsv"
+              data-help="Exports the rows currently shown - the filters apply. For one invoice with its line items, use its row menu instead.">
+        CSV
+      </button>
+      <button class="btn btn-sm btn-outline" data-on-click="exportExcel"
+              data-help="The same rows, as a spreadsheet Excel and LibreOffice both open.">
+        Excel
+      </button>
+      <button class="btn btn-sm btn-outline" data-on-click="exportPdf" data-if="canPdf.value"
+              data-help="Every invoice currently shown as one PDF, a page each - the documents themselves rather than a summary of them. Large batches take a few seconds to build.">
+        PDF
+      </button>
+    </div>
+
+  </div>
+</div>
+
+<div class="card invoice-setup" data-if="needsSetup.value">
+  <div class="card-body">
+    <strong data-bind-text="setupTitle.value"></strong>
+    <p class="text-sm text-muted" data-bind-text="setupText.value"></p>
+    <div class="flex gap-2">
+      <button class="btn btn-sm btn-primary" data-if="needsIssuer.value" data-on-click="addIssuer">
+        Add an issuer
+      </button>
+      <button class="btn btn-sm btn-primary" data-if="needsReceiver.value" data-on-click="addReceiver">
+        Add a receiver
+      </button>
+      <button class="btn btn-sm btn-ghost" data-on-click="openHelp">What are these?</button>
     </div>
   </div>
 </div>
 
+<p class="text-muted text-sm invoice-hint" data-if="hasRows.value">Right-click a row (or use <strong>⋯</strong>) to print, send, export, duplicate or archive it.</p>
+
 <div id="invoices-table"></div>
+
+<!--
+  Domma's table has no empty-state option - `emptyMessage` was being passed and
+  silently ignored, so an empty list rendered a header row, a pager and nothing
+  in between, which reads as a screen that has broken rather than one with
+  nothing in it.
+-->
+<p class="text-muted invoice-empty" data-if="isEmpty.value" data-bind-text="emptyText.value"></p>

package/plugins/invoice/admin/templates/issuers.html

@@ -1,5 +1,2 @@
-<div class="view-header d-flex align-items-center justify-content-between mb-4">
-  <h1 class="h3 mb-0"><span data-icon="briefcase"></span> Issuers</h1>
-  <button id="btn-new" class="btn btn-primary"><span data-icon="plus"></span> New Issuer</button>
-</div>
-<div id="party-table"></div>
+<!-- The banner carries the heading; this view only supplies the panel host. -->
+<div id="party-host"></div>

package/plugins/invoice/admin/templates/receivers.html

@@ -1,5 +1,2 @@
-<div class="view-header d-flex align-items-center justify-content-between mb-4">
-  <h1 class="h3 mb-0"><span data-icon="users"></span> Receivers</h1>
-  <button id="btn-new" class="btn btn-primary"><span data-icon="plus"></span> New Receiver</button>
-</div>
-<div id="party-table"></div>
+<!-- The banner carries the heading; this view only supplies the panel host. -->
+<div id="party-host"></div>

package/plugins/invoice/admin/views/contacts-source.js

@@ -0,0 +1,266 @@
+/**
+ * Invoice plugin - the seam to the Contacts plugin.
+ *
+ * Contacts already holds company name, billing address, VAT number, payment
+ * terms and a billing email, and it exposes `GET /contacts/:id/billing` which
+ * returns exactly the field names a receiver has. So a receiver is imported
+ * rather than retyped, and the mapping lives at the end that owns the data.
+ *
+ * Everything here is OPTIONAL. Contacts can be disabled, or not licensed, and
+ * the invoice screens must not lose a button over it - so `contactsAvailable()`
+ * probes once and every caller hides its control when the answer is no.
+ */
+const CONTACTS = '/api/plugins/contacts';
+
+/** Asked once per page load; enabling a plugin reloads the admin anyway. */
+let available = null;
+
+/**
+ * @returns {Promise<boolean>}
+ */
+export async function contactsAvailable() {
+    if (available !== null) return available;
+    try {
+        await H.get(`${CONTACTS}/groups`, { silent: true });
+        available = true;
+    } catch {
+        available = false;
+    }
+    return available;
+}
+
+/**
+ * @returns {Promise<object[]>} contacts, name-sorted, as the plugin sends them
+ */
+export async function listContacts() {
+    const res = await H.get(`${CONTACTS}/contacts`);
+    return res.data ?? (Array.isArray(res) ? res : []);
+}
+
+/**
+ * @returns {Promise<string[]>} group names
+ */
+export async function listGroups() {
+    const res = await H.get(`${CONTACTS}/groups`);
+    return res.data ?? (Array.isArray(res) ? res : []);
+}
+
+/**
+ * One contact as a receiver body.
+ *
+ * @param   {string} id
+ * @returns {Promise<object>}
+ */
+export async function billingProfile(id) {
+    const res = await H.get(`${CONTACTS}/contacts/${encodeURIComponent(id)}/billing`);
+    return res.data ?? res;
+}
+
+/**
+ * Every address a contact can be reached at, billing first.
+ *
+ * @param   {object} contact
+ * @returns {string[]}
+ */
+export function addressesFor(contact) {
+    const all = [contact?.billingEmail, contact?.email, ...(contact?.emails ?? [])];
+    const seen = new Set();
+    const out = [];
+    for (const item of all) {
+        const address = String(item ?? '').trim();
+        if (!address || seen.has(address.toLowerCase())) continue;
+        seen.add(address.toLowerCase());
+        out.push(address);
+    }
+    return out;
+}
+
+/**
+ * A searchable list of contacts in a slideover.
+ *
+ * Multi-select mode is what "send to a group" is built out of: the group
+ * filter narrows the list, and Select all takes what is showing.
+ *
+ * @param   {{title?: string, multiple?: boolean, onPick: Function}} options
+ * @returns {Promise<void>}
+ */
+export async function openContactPicker({title = 'Choose a contact', multiple = false, onPick}) {
+    let contacts = [];
+    let groups = [];
+    try {
+        [contacts, groups] = await Promise.all([listContacts(), listGroups().catch(() => [])]);
+    } catch (err) {
+        E.toast(err?.message ?? 'Could not read your contacts.', { type: 'error' });
+        return;
+    }
+
+    const query    = M.observable('').extend({ rateLimit: 150 });
+    const group    = M.observable('');
+    const selected = M.observable([]);
+
+    const shown = M.computed(() => {
+        const q = String(query.value || '').toLowerCase().trim();
+        const g = group.value;
+        return contacts.filter((c) => {
+            if (g && !(c.groups ?? []).includes(g)) return false;
+            if (!q) return true;
+            return [c.name, c.company, c.email, c.billingEmail]
+                .some((v) => String(v ?? '').toLowerCase().includes(q));
+        });
+    });
+
+    const slideover = E.slideover({
+        title,
+        size: 'md',
+        position: 'right',
+        onClose: () => setTimeout(() => {
+            stop();
+            slideover.destroy();
+            slideover.element?.remove();
+        }, 350)
+    });
+
+    const wrapper = document.createElement('div');
+    wrapper.className = 'invoice-party-form';
+
+    const filters = document.createElement('div');
+    filters.className = 'invoice-picker-filters';
+
+    const search = document.createElement('input');
+    search.type = 'search';
+    search.className = 'form-input';
+    search.placeholder = 'Search name, company or email…';
+    search.addEventListener('input', () => { query.value = search.value; });
+    filters.appendChild(search);
+
+    if (groups.length) {
+        const groupSelect = document.createElement('select');
+        groupSelect.className = 'form-select';
+        const any = document.createElement('option');
+        any.value = '';
+        any.textContent = 'All groups';
+        groupSelect.appendChild(any);
+        for (const name of groups) {
+            const option = document.createElement('option');
+            option.value = name;
+            option.textContent = name;
+            groupSelect.appendChild(option);
+        }
+        groupSelect.addEventListener('change', () => { group.value = groupSelect.value; });
+        filters.appendChild(groupSelect);
+    }
+
+    wrapper.appendChild(filters);
+
+    const list = document.createElement('div');
+    list.className = 'invoice-picker-list';
+    wrapper.appendChild(list);
+
+    const actions = document.createElement('div');
+    actions.className = 'invoice-party-actions';
+    const count = document.createElement('span');
+    count.className = 'text-sm text-muted invoice-picker-count';
+    actions.appendChild(count);
+
+    const cancelBtn = document.createElement('button');
+    cancelBtn.type = 'button';
+    cancelBtn.className = 'btn btn-ghost';
+    cancelBtn.textContent = 'Cancel';
+    cancelBtn.addEventListener('click', () => slideover.close());
+    actions.appendChild(cancelBtn);
+
+    let selectAllBtn = null;
+    let useBtn = null;
+    if (multiple) {
+        selectAllBtn = document.createElement('button');
+        selectAllBtn.type = 'button';
+        selectAllBtn.className = 'btn btn-outline';
+        selectAllBtn.textContent = 'Select all shown';
+        selectAllBtn.addEventListener('click', () => {
+            selected.value = shown.value.map((c) => c.id);
+        });
+        actions.appendChild(selectAllBtn);
+
+        useBtn = document.createElement('button');
+        useBtn.type = 'button';
+        useBtn.className = 'btn btn-primary';
+        useBtn.textContent = 'Use these';
+        useBtn.addEventListener('click', () => {
+            const chosen = contacts.filter((c) => selected.value.includes(c.id));
+            slideover.close();
+            onPick(chosen);
+        });
+        actions.appendChild(useBtn);
+    }
+
+    wrapper.appendChild(actions);
+    slideover.element.appendChild(wrapper);
+
+    /**
+     * The list is rebuilt rather than bound, because each row is a plain
+     * button and there is no per-row state worth a binding - the only thing
+     * that moves is which ids are in `selected`.
+     *
+     * @returns {void}
+     */
+    function paint() {
+        const rows = shown.value;
+        const chosen = new Set(selected.value);
+
+        list.textContent = '';
+        if (!rows.length) {
+            const empty = document.createElement('p');
+            empty.className = 'text-sm text-muted';
+            empty.textContent = contacts.length
+                ? 'No contact matches that.'
+                : 'You have no contacts yet.';
+            list.appendChild(empty);
+        }
+
+        for (const contact of rows) {
+            const row = document.createElement('button');
+            row.type = 'button';
+            row.className = 'invoice-picker-row' + (chosen.has(contact.id) ? ' is-chosen' : '');
+
+            const name = document.createElement('span');
+            name.className = 'invoice-picker-name';
+            name.textContent = contact.company
+                ? `${contact.name} · ${contact.company}`
+                : contact.name;
+            row.appendChild(name);
+
+            const mail = document.createElement('span');
+            mail.className = 'invoice-picker-mail';
+            mail.textContent = addressesFor(contact)[0] || 'no email';
+            row.appendChild(mail);
+
+            row.addEventListener('click', () => {
+                if (!multiple) {
+                    slideover.close();
+                    onPick(contact);
+                    return;
+                }
+                selected.value = chosen.has(contact.id)
+                    ? selected.value.filter((id) => id !== contact.id)
+                    : [...selected.value, contact.id];
+            });
+
+            list.appendChild(row);
+        }
+
+        count.textContent = multiple
+            ? `${selected.value.length} selected`
+            : `${rows.length} of ${contacts.length}`;
+        if (useBtn) useBtn.disabled = selected.value.length === 0;
+    }
+
+    const stop = M.effect(() => {
+        // Tracked reads first, then the DOM work untracked, so the rebuild's
+        // own reads never become dependencies of this effect.
+        const deps = [shown.value, selected.value];
+        M.untracked(() => { void deps; paint(); });
+    });
+
+    slideover.open();
+    search.focus();
+}