domma-cms 0.55.1 → 0.66.0

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

@@ -0,0 +1,594 @@
+/**
+ * Invoice plugin - the settings slideover.
+ *
+ * Opened from the cog in the plugin banner. It is a slideover rather than a
+ * screen on purpose: settings are read while looking at the list, and a route
+ * change would throw the list's filters away to show six form fields.
+ *
+ * Built as SECTIONS, each drawn the first time its tab is opened. The issuer
+ * and receiver tabs each carry a live CRUD table, so drawing all six up front
+ * would mean three API round trips for tabs nobody looked at - and the two
+ * tables would fight over the same T instance name.
+ *
+ * Each tab saves its OWN keys. The server treats PUT /settings as a patch over
+ * what is stored, which is what makes that safe; a PUT that merged over the
+ * shipped defaults instead would have Save on the Email tab silently reset the
+ * currency.
+ */
+import {ISSUER_FIELDS, RECEIVER_FIELDS, mountPartyPanel} from './party-view.js?v=8';
+import {billingProfile, contactsAvailable, openContactPicker} from './contacts-source.js?v=8';
+import {openMediaPicker} from './media.js?v=8';
+import {makeResizable} from '/plugins/_lib/admin/ui/resizable.js?v=8';
+import {openHelpPanel, scanHelp} from '/plugins/_lib/admin/ui/help.js?v=8';
+
+const BASE = '/api/plugins/invoice';
+
+/**
+ * A `<div>` with Domma classes on it, appended to a parent.
+ *
+ * @param   {HTMLElement} parent
+ * @param   {string} [className]
+ * @param   {string} [tag]
+ * @returns {HTMLElement}
+ */
+function box(parent, className = '', tag = 'div') {
+    const el = document.createElement(tag);
+    if (className) el.className = className;
+    parent.appendChild(el);
+    return el;
+}
+
+/**
+ * A line of explanation at the top of a section.
+ *
+ * @param   {HTMLElement} parent
+ * @param   {string} text
+ * @returns {HTMLElement}
+ */
+function note(parent, text) {
+    const el = box(parent, 'text-sm text-muted mb-3', 'p');
+    el.textContent = text;
+    return el;
+}
+
+/**
+ * The row of buttons at the foot of a section, with its status line.
+ *
+ * @param   {HTMLElement} parent
+ * @returns {{row: HTMLElement, say: Function, busy: Function}}
+ */
+function actionBar(parent) {
+    const row = box(parent, 'flex items-center gap-2 mt-3');
+    const status = box(row, 'flex-1 text-sm text-muted');
+
+    return {
+        row,
+        say(text, tone = 'quiet') {
+            status.textContent = text ?? '';
+            status.className = 'flex-1 text-sm '
+                + ({ ok: 'text-success', bad: 'text-danger' }[tone] ?? 'text-muted');
+        },
+        busy(on) {
+            for (const el of row.querySelectorAll('button')) el.disabled = on;
+        }
+    };
+}
+
+/**
+ * Render a Forma form into a section.
+ *
+ * Labels above and one column, because the panel is narrow and a two-column
+ * grid puts a hint under a field it does not belong to.
+ *
+ * @param   {HTMLElement} parent
+ * @param   {object} schema
+ * @param   {object} data
+ * @returns {object} the Forma instance
+ */
+function formIn(parent, schema, data) {
+    const host = box(parent, 'invoice-settings-form');
+    const form = F.create(schema, data, {
+        layout: 'stacked',
+        labelPosition: 'top',
+        // Forma adds its own Submit unless told not to, and every section here
+        // has a Save in its action bar.
+        showSubmitButton: false
+    });
+    form.renderTo(host);
+    return form;
+}
+
+/**
+ * Open the settings slideover.
+ *
+ * @param   {{onChange?: Function, tab?: string}} [options] - `onChange` is
+ *          called after anything is saved; `tab` opens on that section, which
+ *          is how "you need an issuer first" can take you straight to it
+ * @returns {Promise<void>}
+ */
+export async function openInvoiceSettings({ onChange, tab } = {}) {
+    let settings;
+    try {
+        const res = await H.get(`${BASE}/settings`);
+        settings = res.data ?? res;
+    } catch (err) {
+        E.toast(err?.message ?? 'Could not read the invoice settings.', { type: 'error' });
+        return;
+    }
+
+    let issuers = [];
+    try {
+        const res = await H.get(`${BASE}/issuers`);
+        issuers = res.data ?? (Array.isArray(res) ? res : []);
+    } catch { /* the Issuers tab will say so */ }
+
+    const haveContacts = await contactsAvailable();
+    const panels = [];
+
+    /**
+     * Save a subset of the settings and keep the local copy in step.
+     *
+     * @param   {object} patch
+     * @returns {Promise<void>}
+     */
+    async function save(patch) {
+        const res = await H.put(`${BASE}/settings`, patch);
+        const out = res?.data ?? res;
+        if (out?.error) throw new Error(out.error);
+        settings = out.settings ?? { ...settings, ...patch };
+        onChange?.(settings);
+    }
+
+    // ---- sections -------------------------------------------------------
+
+    /**
+     * Issuers: us. One profile per trading name, and which one a new invoice
+     * opens as.
+     */
+    function renderIssuers(panel) {
+        note(panel, 'An issuer is you - a trading name, its address, VAT number and the account an invoice is paid into. Add one profile per business you invoice as.');
+
+        const defaults = box(panel, 'invoice-settings-inline');
+        const label = box(defaults, 'form-label', 'label');
+        label.textContent = 'Invoice as';
+        label.setAttribute('for', 'invoice-default-issuer');
+
+        const select = box(defaults, 'form-select', 'select');
+        select.id = 'invoice-default-issuer';
+        const none = box(select, '', 'option');
+        none.value = '';
+        none.textContent = 'Ask every time';
+        for (const issuer of issuers) {
+            const option = box(select, '', 'option');
+            option.value = issuer.id;
+            option.textContent = issuer.name || '(unnamed)';
+        }
+        select.value = settings.defaultIssuerId ?? '';
+
+        const bar = actionBar(panel);
+        bar.say('A new invoice opens as this issuer.');
+        select.addEventListener('change', async () => {
+            try {
+                await save({ defaultIssuerId: select.value });
+                bar.say('Saved.', 'ok');
+            } catch (err) {
+                bar.say(err?.message ?? 'Could not save.', 'bad');
+            }
+        });
+
+        const host = box(panel, '');
+        panels.push(mountPartyPanel(host, {
+            kind: 'issuer',
+            endpoint: `${BASE}/issuers`,
+            label: 'Issuer',
+            fields: ISSUER_FIELDS
+        }));
+    }
+
+    /** Receivers: who we bill, importable from Contacts. */
+    function renderReceivers(panel) {
+        note(panel, haveContacts
+            ? 'Who you bill. Import one from Contacts and its company name, billing address, VAT number and reference come with it.'
+            : 'Who you bill - company name, billing address and VAT number.');
+
+        const host = box(panel, '');
+        const party = mountPartyPanel(host, {
+            kind: 'receiver',
+            endpoint: `${BASE}/receivers`,
+            label: 'Receiver',
+            fields: RECEIVER_FIELDS
+        });
+        panels.push(party);
+
+        if (!haveContacts) return;
+
+        const importBtn = document.createElement('button');
+        importBtn.type = 'button';
+        importBtn.className = 'btn btn-sm btn-outline';
+        importBtn.textContent = 'Import from Contacts';
+        importBtn.addEventListener('click', () => openContactPicker({
+            title: 'Import a receiver',
+            onPick: async (contact) => {
+                try {
+                    const profile = await billingProfile(contact.id);
+                    // The billing profile uses the receiver's own field names,
+                    // which is the whole point of that endpoint - it goes
+                    // straight to POST /receivers with nothing to translate.
+                    const res = await H.post(`${BASE}/receivers`, profile);
+                    if (res?.error) throw new Error(res.error);
+                    E.toast(`${profile.company || profile.name} imported.`, { type: 'success' });
+                    await party.reload();
+                } catch (err) {
+                    E.toast(err?.message ?? 'Could not import that contact.', { type: 'error' });
+                }
+            }
+        }));
+        host.querySelector('.invoice-panel-head')?.prepend(importBtn);
+    }
+
+    /** The values a new invoice starts with. */
+    function renderDefaults(panel) {
+        note(panel, 'What a new invoice starts with. Changing these never touches an invoice that already exists.');
+
+        const form = formIn(panel, {
+            defaultCurrency: { type: 'string', label: 'Currency', required: true,
+                formConfig: { hint: 'Three-letter ISO code - GBP, EUR, USD.' } },
+            defaultVatRate: { type: 'number', label: 'VAT rate (%)', min: 0, max: 100 },
+            vatEnabledByDefault: { type: 'boolean', label: 'VAT on by default' },
+            defaultPaymentTermsDays: { type: 'number', label: 'Payment terms (days)', min: 0, max: 365,
+                formConfig: { hint: 'Fills the due date on a new invoice. 0 leaves it blank.' } }
+        }, {
+            defaultCurrency: settings.defaultCurrency ?? 'GBP',
+            defaultVatRate: settings.defaultVatRate ?? 20,
+            vatEnabledByDefault: settings.vatEnabledByDefault !== false,
+            defaultPaymentTermsDays: settings.defaultPaymentTermsDays ?? 0
+        });
+
+        const bar = actionBar(panel);
+        const saveBtn = box(bar.row, 'btn btn-sm btn-primary', 'button');
+        saveBtn.type = 'button';
+        saveBtn.textContent = 'Save';
+        saveBtn.addEventListener('click', async () => {
+            if (!form.validate()) return;
+            bar.busy(true);
+            try {
+                await save(form.getData());
+                bar.say('Saved.', 'ok');
+            } catch (err) {
+                bar.say(err?.message ?? 'Could not save.', 'bad');
+            } finally {
+                bar.busy(false);
+            }
+        });
+    }
+
+    /** How invoice numbers are built. */
+    function renderNumbering(panel) {
+        note(panel, 'Numbers are allocated when an invoice is created, per prefix and per year, and never reused. Typing a number on an invoice yourself still wins.');
+
+        const form = formIn(panel, {
+            numberPrefix: { type: 'string', label: 'Prefix', required: true },
+            numberPadding: { type: 'number', label: 'Digits', min: 1, max: 10,
+                formConfig: { hint: 'The sequence is padded to this width.' } }
+        }, {
+            numberPrefix: settings.numberPrefix ?? 'INV',
+            numberPadding: settings.numberPadding ?? 4
+        });
+
+        const preview = box(panel, 'invoice-number-preview text-sm');
+
+        /** @returns {void} */
+        function paint() {
+            const values = form.getData();
+            const year = new Date().getFullYear();
+            const digits = Math.min(Math.max(Math.round(Number(values.numberPadding) || 1), 1), 10);
+            preview.textContent = `Next: ${values.numberPrefix || 'INV'}-${year}-${String(1).padStart(digits, '0')}`;
+        }
+        paint();
+        // Forma writes through the model on input, so reading getData() on the
+        // way past is enough - there is nothing to parse out of the DOM.
+        panel.addEventListener('input', paint);
+
+        const bar = actionBar(panel);
+        const saveBtn = box(bar.row, 'btn btn-sm btn-primary', 'button');
+        saveBtn.type = 'button';
+        saveBtn.textContent = 'Save';
+        saveBtn.addEventListener('click', async () => {
+            if (!form.validate()) return;
+            bar.busy(true);
+            try {
+                await save(form.getData());
+                bar.say('Saved.', 'ok');
+            } catch (err) {
+                bar.say(err?.message ?? 'Could not save.', 'bad');
+            } finally {
+                bar.busy(false);
+            }
+        });
+    }
+
+    /** The covering email, and the small print on the invoice itself. */
+    function renderEmail(panel) {
+        note(panel, 'Used when you send an invoice. {{number}}, {{issuer}}, {{total}} and {{dueDate}} are filled in per invoice.');
+
+        const form = formIn(panel, {
+            emailSubject: { type: 'string', label: 'Subject' },
+            emailIntro: { type: 'textarea', label: 'Covering note', formConfig: { rows: 3 } },
+            attachPdf: { type: 'boolean', label: 'Attach a PDF when the server can render one' },
+            footerNote: { type: 'textarea', label: 'Invoice footer', formConfig: { rows: 2,
+                hint: 'Printed at the foot of every invoice.' } }
+        }, {
+            emailSubject: settings.emailSubject ?? '',
+            emailIntro: settings.emailIntro ?? '',
+            attachPdf: settings.attachPdf !== false,
+            footerNote: settings.footerNote ?? ''
+        });
+
+        const bar = actionBar(panel);
+        const saveBtn = box(bar.row, 'btn btn-sm btn-primary', 'button');
+        saveBtn.type = 'button';
+        saveBtn.textContent = 'Save';
+        saveBtn.addEventListener('click', async () => {
+            if (!form.validate()) return;
+            bar.busy(true);
+            try {
+                await save(form.getData());
+                bar.say('Saved.', 'ok');
+            } catch (err) {
+                bar.say(err?.message ?? 'Could not save.', 'bad');
+            } finally {
+                bar.busy(false);
+            }
+        });
+    }
+
+    /** The house logo. */
+    function renderBranding(panel) {
+        note(panel, 'Printed at the top of every invoice. An issuer with a logo of its own uses that instead, so a single-company install sets this once and never thinks about it again.');
+
+        const frame = box(panel, 'invoice-logo-frame');
+        const img = box(frame, 'invoice-logo-preview', 'img');
+        const empty = box(frame, 'text-sm text-muted', 'span');
+
+        /** @param {string} url @returns {void} */
+        function show(url) {
+            if (url) {
+                img.src = url;
+                img.alt = 'Company logo';
+                img.classList.remove('invoice-hidden');
+                empty.textContent = '';
+            } else {
+                img.removeAttribute('src');
+                img.classList.add('invoice-hidden');
+                empty.textContent = 'No logo yet.';
+            }
+        }
+        show(settings.logoUrl ?? '');
+
+        const bar = actionBar(panel);
+        const chooseBtn = box(bar.row, 'btn btn-sm btn-primary', 'button');
+        chooseBtn.type = 'button';
+        chooseBtn.textContent = 'Upload or choose…';
+        chooseBtn.addEventListener('click', () => openMediaPicker(async (url) => {
+            bar.busy(true);
+            try {
+                await save({ logoUrl: url });
+                show(url);
+                bar.say(url ? 'Saved.' : 'Logo cleared.', 'ok');
+            } catch (err) {
+                bar.say(err?.message ?? 'Could not save.', 'bad');
+            } finally {
+                bar.busy(false);
+            }
+        }));
+    }
+
+    /**
+     * How a printed invoice is laid out, with a worked example of each.
+     *
+     * The preview is SAMPLE data rendered by the server in the real template,
+     * shown in an iframe. An iframe because a printed invoice is a whole
+     * document with its own stylesheet - dropped into the page it would fight
+     * the admin's CSS and show you something you will never receive.
+     */
+    async function renderTemplates(panel) {
+        note(panel, 'How a printed or emailed invoice is laid out. The preview is a worked example in your own name, not a picture - it is the same code that prints.');
+
+        let data;
+        try {
+            const res = await H.get(`${BASE}/templates`);
+            data = res.data ?? res;
+        } catch (err) {
+            const bad = box(panel, 'text-sm text-danger', 'p');
+            bad.textContent = err?.message ?? 'The templates could not be read.';
+            return;
+        }
+
+        let chosen = data.current || 'classic';
+        let withLogo = data.hasLogo;
+
+        const picker = box(panel, 'invoice-template-picker');
+        const frame = box(panel, 'invoice-template-preview', 'iframe');
+        frame.setAttribute('title', 'Invoice preview');
+        // No scripts, and nothing it could reach even if there were: the
+        // preview is for looking at.
+        frame.setAttribute('sandbox', '');
+
+        const bar = actionBar(panel);
+
+        const logoToggle = box(bar.row, 'invoice-check', 'label');
+        const logoBox = box(logoToggle, 'form-checkbox', 'input');
+        logoBox.type = 'checkbox';
+        logoBox.checked = withLogo;
+        logoBox.disabled = !data.hasLogo;
+        const logoText = box(logoToggle, '', 'span');
+        logoText.textContent = 'Show the logo';
+        logoToggle.setAttribute('data-help', data.hasLogo
+            ? 'Turn this off to see what an issuer with no logo gets - a layout built for having none, rather than this one with a gap where the logo would be.'
+            : 'There is no logo yet, so every invoice uses the no-logo layout. Upload one under Branding.');
+
+        const saveBtn = box(bar.row, 'btn btn-sm btn-primary', 'button');
+        saveBtn.type = 'button';
+        saveBtn.textContent = 'Use this template';
+
+        /**
+         * @param   {string} id
+         * @returns {Promise<void>}
+         */
+        async function preview(id) {
+            frame.classList.add('is-loading');
+            try {
+                const res = await H.get(`${BASE}/templates/${encodeURIComponent(id)}/preview?logo=${logoBox.checked ? '1' : '0'}`);
+                const out = res.data ?? res;
+                if (out?.error) throw new Error(out.error);
+                // srcdoc, not a document.write into the frame: the frame is
+                // sandboxed, so it has no same-origin handle to write through.
+                frame.srcdoc = out.html;
+            } catch (err) {
+                bar.say(err?.message ?? 'That template could not be rendered.', 'bad');
+            } finally {
+                frame.classList.remove('is-loading');
+            }
+        }
+
+        /** @returns {void} */
+        function paintChoice() {
+            for (const card of picker.children) {
+                card.classList.toggle('is-chosen', card.dataset.template === chosen);
+            }
+            saveBtn.disabled = chosen === (data.current || 'classic');
+            saveBtn.textContent = saveBtn.disabled ? 'In use' : 'Use this template';
+        }
+
+        for (const template of data.templates) {
+            const card = box(picker, 'invoice-template-card', 'button');
+            card.type = 'button';
+            card.dataset.template = template.id;
+
+            const name = box(card, 'invoice-template-name', 'strong');
+            name.textContent = template.name;
+
+            const desc = box(card, 'invoice-template-desc', 'span');
+            desc.textContent = template.description;
+
+            if (!template.hasNoLogoVariant) {
+                const tag = box(card, 'badge badge-secondary invoice-template-tag', 'span');
+                tag.textContent = 'no logo';
+                tag.title = 'This style has nowhere to put a logo, by design.';
+            }
+
+            card.addEventListener('click', () => {
+                chosen = template.id;
+                paintChoice();
+                preview(template.id);
+            });
+        }
+
+        logoBox.addEventListener('change', () => preview(chosen));
+
+        saveBtn.addEventListener('click', async () => {
+            bar.busy(true);
+            try {
+                await save({ template: chosen });
+                data.current = chosen;
+                bar.say('Saved. New printouts use this layout.', 'ok');
+            } catch (err) {
+                bar.say(err?.message ?? 'Could not save.', 'bad');
+            } finally {
+                bar.busy(false);
+                paintChoice();
+            }
+        });
+
+        paintChoice();
+        await preview(chosen);
+    }
+
+    const sections = [
+        { id: 'issuers',   label: 'Issuers',   render: renderIssuers },
+        { id: 'receivers', label: 'Receivers', render: renderReceivers },
+        { id: 'defaults',  label: 'Defaults',  render: renderDefaults },
+        { id: 'numbering', label: 'Numbering', render: renderNumbering },
+        { id: 'email',     label: 'Email',     render: renderEmail },
+        { id: 'branding',  label: 'Branding',  render: renderBranding },
+        // After Branding: a template is chosen by looking at it, and what it
+        // looks like depends on whether there is a logo yet.
+        { id: 'templates', label: 'Templates', render: renderTemplates }
+    ];
+
+    // ---- the panel ------------------------------------------------------
+
+    const slideover = E.slideover({
+        title: 'Invoice Settings',
+        size: 'lg',
+        position: 'right',
+        onClose: () => setTimeout(() => {
+            stopResize();
+            for (const panel of panels) panel.dispose();
+            slideover.destroy();
+            slideover.element?.remove();
+        }, 350)
+    });
+
+    // A table of issuers wants a different width to a two-field form, and which
+    // one someone is looking at changes by the minute - so the panel is dragged
+    // rather than sized here, and the width is remembered.
+    const stopResize = makeResizable(slideover, {
+        storageKey: 'domma-invoice.settings-width',
+        defaultWidth: 780,
+        handleClass: 'invoice-slideover-resizer'
+    });
+
+    const host = document.createElement('div');
+    host.className = 'invoice-settings';
+
+    const tabs = box(host, 'tabs');
+    const list = box(tabs, 'tab-list');
+    const drawn = [];
+
+    const startAt = Math.max(0, sections.findIndex(s => s.id === tab));
+
+    sections.forEach((section, index) => {
+        const trigger = box(list, 'tab-item' + (index === startAt ? ' active' : ''), 'button');
+        trigger.type = 'button';
+        trigger.textContent = section.label;
+
+        const panel = box(tabs, 'tab-panel' + (index === startAt ? ' active' : ''));
+        drawn.push({ section, panel, done: false });
+
+        trigger.addEventListener('click', () => {
+            const entry = drawn[index];
+            if (entry.done) return;
+            entry.done = true;
+            draw(entry);
+        });
+    });
+
+    /**
+     * Draw one section, tolerating one that throws.
+     *
+     * @param   {object} entry
+     * @returns {void}
+     */
+    async function draw(entry) {
+        entry.panel.textContent = '';
+        try {
+            // Awaited: the Templates section fetches before it can draw, and an
+            // unawaited rejection here would be an unhandled one rather than
+            // the message below.
+            await entry.section.render(entry.panel);
+        } catch (err) {
+            const message = box(entry.panel, 'text-sm text-danger', 'p');
+            message.textContent = err?.message || 'This section could not be loaded.';
+        }
+        Domma.icons.scan(entry.panel);
+        scanHelp(entry.panel);
+    }
+
+    slideover.element.appendChild(host);
+    // `active` is which tab to open on; E.tabs owns it from here.
+    E.tabs(tabs, { active: startAt });
+    drawn[startAt].done = true;
+    draw(drawn[startAt]);
+    slideover.open();
+}

package/plugins/invoice/admin/views/view-lifecycle.js

@@ -0,0 +1,33 @@
+/**
+ * Tearing a view's reactive graph down when the router replaces it.
+ *
+ * The admin has no unmount hook, so the only signal available is Domma's
+ * `router:afterChange`. That event also fires for the navigation that MOUNTED
+ * this view - subscribing in onMount and disposing on the first event kills the
+ * bindings the instant they were applied. It does not look like a crash: values
+ * written during activation stay on screen, so the screen reads correctly and
+ * nothing updates again, and a `data-each` whose item template was lifted at
+ * activation renders no rows at all.
+ *
+ * Keying on whether a node the view owns is still in the document is what
+ * separates "we have just arrived" from "we have been replaced": the router
+ * swaps the container's contents, so our node is detached exactly once.
+ */
+
+/**
+ * @param {Element}     owned      a node this view put in the container
+ * @param {...Function} disposers  M.effect disposers, or handles with dispose()
+ * @returns {void}
+ */
+export function disposeOnLeave(owned, ...disposers) {
+    const stop = M.subscribe('router:afterChange', () => {
+        if (owned && owned.isConnected) return;
+        for (const d of disposers) {
+            try {
+                if (typeof d === 'function') d();
+                else d?.dispose?.();
+            } catch { /* already torn down */ }
+        }
+        if (typeof stop === 'function') stop();
+    });
+}