domma-cms 0.55.1 → 0.66.0

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

@@ -0,0 +1,199 @@
+/**
+ * Invoice plugin - saving invoices as a file.
+ *
+ * Domma's table can export what it is showing, but it exports the RENDERED
+ * columns: a receiver id instead of a name, an HTML badge instead of a status,
+ * and no line items at all, because they are not in the table. An accountant
+ * asking for "the invoices as a spreadsheet" wants neither of those, so the
+ * rows are built here from the data and the table's own exporter is left off.
+ *
+ * Excel is an HTML table served as `application/vnd.ms-excel`, which is what
+ * Domma's own exporter does and what Excel and LibreOffice both open without
+ * a converter. It is not a real .xlsx, and it does not need to be - nothing
+ * here has formulas, merged cells or more than one sheet.
+ */
+function escapeHtml(s) {
+    return String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+}
+
+/**
+ * @param   {Array<Array<string|number>>} rows
+ * @returns {string}
+ */
+function toCsv(rows) {
+    return rows.map((row) => row.map((cell) => {
+        const text = cell === null || cell === undefined ? '' : String(cell);
+        return `"${text.replace(/"/g, '""')}"`;
+    }).join(',')).join('\r\n');
+}
+
+/**
+ * @param   {string} title
+ * @param   {Array<Array<string|number>>} rows
+ * @param   {number} headerRows - how many leading rows to render as <th>
+ * @returns {string}
+ */
+function toExcel(title, rows, headerRows = 1) {
+    const body = rows.map((row, index) => {
+        const tag = index < headerRows ? 'th' : 'td';
+        return '<tr>' + row.map((cell) => `<${tag}>${escapeHtml(cell)}</${tag}>`).join('') + '</tr>';
+    }).join('');
+
+    return `<html xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:x="urn:schemas-microsoft-com:office:excel">
+<head><meta charset="UTF-8">
+<!--[if gte mso 9]><xml><x:ExcelWorkbook><x:ExcelWorksheets><x:ExcelWorksheet>
+<x:Name>${escapeHtml(title).slice(0, 31)}</x:Name>
+<x:WorksheetOptions><x:DisplayGridlines/></x:WorksheetOptions>
+</x:ExcelWorksheet></x:ExcelWorksheets></x:ExcelWorkbook></xml><![endif]-->
+<style>table{border-collapse:collapse}th,td{border:1px solid #999;padding:6px}th{background:#eee;font-weight:bold;text-align:left}</style>
+</head><body><table>${body}</table></body></html>`;
+}
+
+/**
+ * @param   {string} content
+ * @param   {string} mime
+ * @param   {string} filename
+ * @returns {void}
+ */
+function save(content, mime, filename) {
+    // A BOM, because Excel reads a CSV without one as the system codepage and
+    // turns every pound sign into £.
+    const blob = new Blob([mime.startsWith('text/csv') ? '' + content : content], { type: mime });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    a.rel = 'noopener';
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+    // Revoked on the next tick: revoking synchronously races the download in
+    // Firefox, which has not necessarily read the blob by the time click()
+    // returns.
+    setTimeout(() => URL.revokeObjectURL(url), 1000);
+}
+
+/** A filename component that no filesystem will argue about. */
+function safeName(text, fallback) {
+    const cleaned = String(text ?? '').replace(/[^\w.-]+/g, '_').replace(/^_+|_+$/g, '');
+    return cleaned || fallback;
+}
+
+function money(amount) {
+    return (Number(amount) || 0).toFixed(2);
+}
+
+function dateText(value) {
+    return value ? D(value).format('DD MMM YYYY') : '';
+}
+
+/**
+ * One invoice as a small worksheet: the facts, then the lines, then the totals.
+ *
+ * @param   {object} invoice
+ * @param   {{issuerName: string, receiverName: string}} names
+ * @returns {Array<Array<string|number>>}
+ */
+export function invoiceRows(invoice, { issuerName = '', receiverName = '' } = {}) {
+    const currency = invoice.currency || 'GBP';
+    const totals = invoice.totals ?? {};
+    const rows = [
+        ['Invoice', invoice.number || ''],
+        ['Status', invoice.overdue ? 'overdue' : (invoice.status || 'draft')],
+        ['From', issuerName],
+        ['To', receiverName],
+        ['Issued', dateText(invoice.issueDate)],
+        ['Due', dateText(invoice.dueDate)],
+        ['Currency', currency],
+        [],
+        ['Description', 'Quantity', 'Unit price', 'Line total']
+    ];
+
+    for (const line of invoice.lineItems ?? []) {
+        const quantity = Number(line.quantity) || 0;
+        const unit = Number(line.unitPrice) || 0;
+        rows.push([line.description || '', quantity, money(unit), money(quantity * unit)]);
+    }
+
+    rows.push([]);
+    rows.push(['', '', 'Subtotal', money(totals.subtotal)]);
+    if (invoice.vatEnabled) rows.push(['', '', `VAT (${totals.vatRate ?? invoice.vatRate ?? 0}%)`, money(totals.vat)]);
+    rows.push(['', '', 'Total', money(totals.total)]);
+    if (Number(totals.paid) > 0) {
+        rows.push(['', '', 'Paid', money(totals.paid)]);
+        rows.push(['', '', 'Balance', money(Math.max(0, Number(totals.balance) || 0))]);
+    }
+
+    if (invoice.notes) {
+        rows.push([]);
+        rows.push(['Notes', invoice.notes]);
+    }
+    return rows;
+}
+
+/**
+ * A list of invoices, one per row.
+ *
+ * @param   {object[]} invoices
+ * @param   {(invoice: object) => {issuerName: string, receiverName: string}} names
+ * @returns {Array<Array<string|number>>}
+ */
+export function listRows(invoices, names) {
+    const rows = [[
+        'Number', 'Status', 'From', 'To', 'Issued', 'Due',
+        'Currency', 'Subtotal', 'VAT', 'Total', 'Paid', 'Balance'
+    ]];
+
+    for (const invoice of invoices) {
+        const totals = invoice.totals ?? {};
+        const { issuerName = '', receiverName = '' } = names(invoice) ?? {};
+        rows.push([
+            invoice.number || '',
+            invoice.overdue ? 'overdue' : (invoice.status || 'draft'),
+            issuerName,
+            receiverName,
+            dateText(invoice.issueDate),
+            dateText(invoice.dueDate),
+            invoice.currency || 'GBP',
+            money(totals.subtotal),
+            money(totals.vat),
+            money(totals.total),
+            money(totals.paid),
+            money(totals.balance)
+        ]);
+    }
+    return rows;
+}
+
+/**
+ * @param {object} invoice
+ * @param {'csv'|'excel'} format
+ * @param {object} names
+ * @returns {void}
+ */
+export function exportInvoice(invoice, format, names) {
+    const rows = invoiceRows(invoice, names);
+    const stem = safeName(invoice.number, 'invoice');
+    if (format === 'excel') {
+        save(toExcel(stem, rows, 0), 'application/vnd.ms-excel', `${stem}.xls`);
+    } else {
+        save(toCsv(rows), 'text/csv;charset=utf-8', `${stem}.csv`);
+    }
+}
+
+/**
+ * @param {object[]} invoices
+ * @param {'csv'|'excel'} format
+ * @param {Function} names
+ * @param {string} [stem]
+ * @returns {void}
+ */
+export function exportList(invoices, format, names, stem = 'invoices') {
+    const rows = listRows(invoices, names);
+    const filename = `${safeName(stem, 'invoices')}-${D().format('YYYY-MM-DD')}`;
+    if (format === 'excel') {
+        save(toExcel('Invoices', rows, 1), 'application/vnd.ms-excel', `${filename}.xls`);
+    } else {
+        save(toCsv(rows), 'text/csv;charset=utf-8', `${filename}.csv`);
+    }
+}

package/plugins/invoice/admin/views/help-content.js

@@ -0,0 +1,61 @@
+/**
+ * What the Invoices plugin's Help panel says.
+ *
+ * Kept as data rather than markup so the same words can be shown in the panel,
+ * quoted in a tooltip, or lifted into the docs without being re-typed - and so
+ * that changing how help LOOKS never means editing what it SAYS.
+ *
+ * Written for someone who has not used the screen before, in the order they
+ * will meet it: make an issuer, make a receiver, make an invoice, send it, get
+ * paid, file it away.
+ */
+export const INVOICE_HELP = {
+    title: 'Invoices - how it works',
+    intro: 'An invoice is raised BY an issuer (you) FOR a receiver (your customer). Both live in Settings, behind the cog.',
+    sections: [
+        {
+            title: 'Before your first invoice',
+            body: [
+                'Add an issuer: your trading name, address, VAT number and the account you are paid into. Add one per business you invoice as; "Invoice as" picks which one a new invoice opens with.',
+                'Add a receiver: who you are billing. If you use the Contacts plugin, Import from Contacts brings the company name, billing address, VAT number and reference across for you.',
+                'Until there is at least one of each, New Invoice stays switched off - an invoice with nobody on either end cannot be saved.'
+            ]
+        },
+        {
+            title: 'Numbers, dates and VAT',
+            body: [
+                'Numbers are allocated when an invoice is created, per prefix and per year, and are never reused. Typing your own number still wins.',
+                'The due date is filled in from your payment terms, and an invoice past its due date reports itself overdue without anything having to run - the stored status stays whatever you set.',
+                'VAT is one rate per invoice, applied to the total. Line item prices are net.'
+            ]
+        },
+        {
+            title: 'Sending and getting paid',
+            body: [
+                'Send emails the invoice, attaching a PDF where the server can render one. Recipients can be typed, or picked from your contacts - including everybody in a group.',
+                'Record a payment against an invoice and the balance follows; settle it in full and the status moves to paid on its own.'
+            ]
+        },
+        {
+            title: 'Filing',
+            body: [
+                'Archive is a shelf, not a status: an archived invoice keeps whatever it was and simply stops appearing in the list. Show archived swaps the list over to the shelf.',
+                'Delete is permanent. For anything you might need again - and an invoice you have sent is exactly that - archive it instead.'
+            ]
+        },
+        {
+            title: 'How it looks',
+            body: [
+                'Settings > Templates chooses the layout, with a worked example in your own name. An issuer with no logo gets a layout built for having none rather than the same one with a gap in it.',
+                'Settings > Branding holds the house logo, used for any issuer that has not got one of its own.'
+            ]
+        },
+        {
+            title: 'Getting it out',
+            body: [
+                'Right-click any row (or use the ⋯ button) to print, send, download a PDF, export that one invoice as CSV or Excel, duplicate it, change its status, archive or delete it.',
+                'The CSV and Excel buttons above the table export what the filters are currently showing, not everything.'
+            ]
+        }
+    ]
+};