@managemint-solutions/sdk 0.56.0 → 0.65.0

package/dist/documents/render/html.d.ts

@@ -0,0 +1,64 @@
+import type { DocumentBlock, DocumentVariable, DocumentVariableValues } from '@managemint-solutions/entities/documents';
+import { DocumentStatus } from '@managemint-solutions/entities/documents/enum';
+/** What is printed: a document, or a template (saved, or unsaved in the builder). */
+export type PrintableDocument = {
+    title: string;
+    number: string | null;
+    /** Null for a template. */
+    status: DocumentStatus | null;
+    /** The document's currency, or the organization's when it has none. */
+    currency: string;
+    variables: DocumentVariable[];
+    /** Every value to print, the system values included. */
+    values: DocumentVariableValues;
+    blocks: DocumentBlock[];
+};
+/**
+ * Plain text with each `{{key}}` replaced by its value as the document prints it - money in its
+ * currency, dates written out - and a key with no value left empty: a stored email's subject and
+ * message, written before the document had a number, filled when it is sent. Text, not HTML, so
+ * nothing is escaped; the email template shows it as text.
+ */
+export declare const fillText: (text: string, document: Pick<PrintableDocument, "variables" | "values" | "currency" | "status">) => string;
+/** A running header or footer: its left and right text as HTML, escaped, page counters as spans. */
+export type DocumentBand = {
+    left: string;
+    right: string;
+};
+/** A document rendered: the page body, and the bands that repeat on every page. */
+export type RenderedDocument = {
+    /** Self-contained HTML: the first page's letterhead, then the blocks. Header and footer blocks are not in it. */
+    html: string;
+    /** The header block's text, or null without one (no header at all). */
+    header: DocumentBand | null;
+    /** The footer block's text - or, with none, the organization, title and number, and "Page X of Y". */
+    footer: DocumentBand;
+};
+/**
+ * The page geometry, in inches: the side and bottom margins, and the top margin - grown to make
+ * room when the document has a header. The api's PDF and the portal's paged preview use the same.
+ */
+export declare const DOCUMENT_PAGE_MARGINS: {
+    readonly top: 0.62;
+    readonly topWithHeader: 0.95;
+    readonly bottom: 0.7;
+    readonly side: 0.7;
+};
+/**
+ * One band as a styled block: left text left, right text right, in the footer's small grey type.
+ * The styles are inline (a placeholder's included) because Chromium's header and footer templates
+ * ignore the document's CSS; the side margins mirror the page's. The api hands it to Chromium as
+ * the header or footer template; the portal's preview places it on each page.
+ */
+export declare const renderBand: (band: DocumentBand, edge: "top" | "bottom") => string;
+/**
+ * A document's blocks and values as HTML, plus its running header and footer - the only way a
+ * document or template is shown, so what is seen is what prints. Styled as the subscription
+ * invoice is: the first page's letterhead - the organization top left against the title, number,
+ * issue date and status top right - then the blocks. Header and footer blocks print nothing in the
+ * body: their text is `header` / `footer`, with `{{key}}`s printed as in the body and
+ * `{{page_number}}` / `{{page_count}}` as page-counter spans. `imageUrls` maps the image blocks'
+ * paths to URLs the caller signed; a path without one prints as `[Image]` on a draft or template
+ * and as nothing once issued.
+ */
+export declare const renderDocument: (document: PrintableDocument, imageUrls: Record<string, string>) => RenderedDocument;

package/dist/documents/render/html.js

@@ -0,0 +1,413 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderDocument = exports.renderBand = exports.DOCUMENT_PAGE_MARGINS = exports.fillText = void 0;
+const enum_1 = require("@managemint-solutions/entities/documents/enum");
+const values_1 = require("./values");
+const STATUS_LABELS = {
+    [enum_1.DocumentStatus.DRAFT]: 'Draft',
+    [enum_1.DocumentStatus.ISSUED]: 'Issued',
+    [enum_1.DocumentStatus.VOID]: 'Void',
+};
+/**
+ * The page counters, which only the header and footer may use. Chromium fills these spans in its
+ * header and footer templates; the portal's preview fills them page by page.
+ */
+const PAGE_COUNTERS = {
+    [enum_1.DocumentSystemVariable.PAGE_NUMBER]: '<span class="pageNumber"></span>',
+    [enum_1.DocumentSystemVariable.PAGE_COUNT]: '<span class="totalPages"></span>',
+};
+const MARK_TAGS = { bold: 'strong', italic: 'em', underline: 'u' };
+/** A variable's value as text, formatted for its type; null when it has none. */
+const valueText = (key, ctx) => {
+    const value = ctx.values[key];
+    if (value === undefined || value === null || value === '')
+        return null;
+    switch (ctx.variables.get(key)?.type) {
+        case enum_1.DocumentVariableType.MONEY:
+            return typeof value === 'number' ? (0, values_1.money)(value, ctx.currency) : String(value);
+        case enum_1.DocumentVariableType.DATE:
+            return typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(value) ? (0, values_1.formatDocumentDate)(value) : String(value);
+        default:
+            return String(value);
+    }
+};
+/** "Reg. no. 2020/123456/07", or null when there is no value to label. */
+const prefixed = (label, value) => (value ? `${label} ${value}` : null);
+/** The muted "[Label]" a draft or template shows where something will print. */
+const placeholder = (label) => `<span class="placeholder">[${(0, values_1.escapeHtml)(label)}]</span>`;
+const valueHtml = (key, ctx) => {
+    if (PAGE_COUNTERS[key])
+        return PAGE_COUNTERS[key];
+    const text = valueText(key, ctx);
+    if (text !== null)
+        return (0, values_1.escapeHtml)(text);
+    if (!ctx.placeholders)
+        return '';
+    return placeholder(ctx.variables.get(key)?.label ?? key);
+};
+/** Plain text with each `{{key}}` replaced by its value as text, and a key with no value left empty. */
+const filledText = (text, ctx) => text.replace(values_1.DOCUMENT_VARIABLE_PATTERN, (_, key) => valueText(key, ctx) ?? '');
+/**
+ * Plain text with each `{{key}}` replaced by its value; everything else escaped, and every line
+ * break a `<br>`. A break left as a newline would hang on `white-space: pre-wrap`, and between two
+ * placeholders it is a text node of whitespace alone, which the portal's paged preview drops -
+ * the two lines then print as one. On an issued document a line whose variables are all empty
+ * is left out - "VAT no. {{client_vat_number}}" for a client with no VAT number, or
+ * `{{client_address}}` with no address - rather than printing its words with nothing after them;
+ * a line with one value filled, or with no variable at all (a blank line included), stays.
+ */
+const plainHtml = (text, ctx) => {
+    if (typeof text !== 'string')
+        return '';
+    return text
+        .split(/\r?\n/)
+        .flatMap((line) => {
+        let html = '';
+        let last = 0;
+        let variables = 0;
+        let filled = 0;
+        for (const match of line.matchAll(values_1.DOCUMENT_VARIABLE_PATTERN)) {
+            variables += 1;
+            if (PAGE_COUNTERS[match[1]] || valueText(match[1], ctx) !== null)
+                filled += 1;
+            html += (0, values_1.escapeHtml)(line.slice(last, match.index)) + valueHtml(match[1], ctx);
+            last = match.index + match[0].length;
+        }
+        html += (0, values_1.escapeHtml)(line.slice(last));
+        return !ctx.placeholders && variables > 0 && filled === 0 ? [] : [html];
+    })
+        .join('<br>');
+};
+/** Bold, italic, underline and links around `html`; any other mark is ignored. */
+const withMarks = (html, marks) => (Array.isArray(marks) ? marks : []).reduce((inner, mark) => {
+    if (!(0, values_1.isObject)(mark) || typeof mark.type !== 'string')
+        return inner;
+    const tag = MARK_TAGS[mark.type];
+    if (tag)
+        return `<${tag}>${inner}</${tag}>`;
+    const href = mark.type === 'link' && (0, values_1.isObject)(mark.attrs) ? (0, values_1.safeHref)(mark.attrs.href) : null;
+    return href ? `<a href="${(0, values_1.escapeHtml)(href)}">${inner}</a>` : inner;
+}, html);
+/**
+ * Rich text (the editor's ProseMirror JSON) as HTML. Only the node types the sdk accepts are
+ * printed; anything else prints nothing, and every text run is escaped.
+ */
+const richTextHtml = (node, ctx) => {
+    if (!(0, values_1.isObject)(node))
+        return '';
+    const attrs = (0, values_1.isObject)(node.attrs) ? node.attrs : {};
+    const children = () => (Array.isArray(node.content) ? node.content.map((child) => richTextHtml(child, ctx)).join('') : '');
+    switch (node.type) {
+        case 'doc':
+            return children();
+        case 'paragraph':
+            return `<p>${children() || '<br>'}</p>`;
+        case 'heading': {
+            const level = [1, 2, 3].includes(attrs.level) ? attrs.level : 3;
+            return `<h${level}>${children()}</h${level}>`;
+        }
+        case 'bulletList':
+            return `<ul>${children()}</ul>`;
+        case 'orderedList':
+            return `<ol>${children()}</ol>`;
+        case 'listItem':
+            return `<li>${children()}</li>`;
+        case 'text':
+            return typeof node.text === 'string' ? withMarks((0, values_1.escapeHtml)(node.text), node.marks) : '';
+        case 'hardBreak':
+            return '<br>';
+        case 'variable':
+            return typeof attrs.key === 'string' ? withMarks(valueHtml(attrs.key, ctx), node.marks) : '';
+        default:
+            return '';
+    }
+};
+/** An amount in cents in the document's currency, escaped. */
+const moneyHtml = (amountMinor, ctx) => (0, values_1.escapeHtml)((0, values_1.money)(amountMinor, ctx.currency));
+/** A line's quantity (a plain number) or unit price (money), written in or taken from its variable. */
+const lineAmountHtml = (amount, isMoney, ctx) => {
+    if (typeof amount !== 'number')
+        return valueHtml(amount.variable, ctx);
+    return isMoney ? moneyHtml(amount, ctx) : (0, values_1.escapeHtml)(String(amount));
+};
+const lineItemsHtml = (block, ctx) => {
+    const showDiscount = block.items.some((line) => line.discount_percent > 0);
+    const showTax = block.items.some((line) => line.tax_rate > 0);
+    const totals = (0, values_1.documentTotals)([block], ctx.values);
+    const rows = block.items
+        .map((line) => `
+        <tr>
+          <td class="item">${plainHtml(line.description, ctx)}</td>
+          <td class="num">${lineAmountHtml(line.quantity, false, ctx)}</td>
+          <td class="num">${lineAmountHtml(line.unit_price_minor, true, ctx)}</td>
+          ${showDiscount ? `<td class="num">${line.discount_percent}%</td>` : ''}
+          ${showTax ? `<td class="num">${line.tax_rate}%</td>` : ''}
+          <td class="num">${moneyHtml((0, values_1.lineAmounts)(line, ctx.values).net, ctx)}</td>
+        </tr>`)
+        .join('');
+    const totalRows = [
+        `<tr><td>Subtotal</td><td class="num">${moneyHtml(totals.subtotal_minor, ctx)}</td></tr>`,
+        totals.discount_minor > 0 ? `<tr><td>Discount</td><td class="num">-${moneyHtml(totals.discount_minor, ctx)}</td></tr>` : '',
+        totals.tax_minor > 0 ? `<tr><td>Tax</td><td class="num">${moneyHtml(totals.tax_minor, ctx)}</td></tr>` : '',
+        `<tr class="grand"><td>Total</td><td class="num">${moneyHtml(totals.total_minor, ctx)}</td></tr>`,
+    ].join('');
+    return `
+    <table class="items">
+      <thead><tr><th>Item</th><th>Qty</th><th>Unit price</th>${showDiscount ? '<th>Discount</th>' : ''}${showTax ? '<th>Tax</th>' : ''}<th>Amount</th></tr></thead>
+      <tbody>${rows}
+      </tbody>
+    </table>
+    <div class="totals-wrap"><table class="totals"><tbody>${totalRows}</tbody></table></div>`;
+};
+const blockHtml = (block, ctx, imageUrls) => {
+    switch (block.type) {
+        case enum_1.DocumentBlockType.TEXT:
+            return `<div class="block text">${richTextHtml(block.content, ctx)}</div>`;
+        case enum_1.DocumentBlockType.FIELDS: {
+            // A blank side shows where it prints on a template or draft; an issued document leaves out a
+            // row with no value - its label alone says nothing - and the block with no rows left.
+            const rows = block.fields.flatMap((field) => {
+                const label = plainHtml(field.label, ctx);
+                const value = plainHtml(field.value, ctx);
+                if (ctx.placeholders) {
+                    return [`<tr><th>${label.trim() || placeholder('Label')}</th><td>${value.trim() || placeholder('Value')}</td></tr>`];
+                }
+                return value.trim() ? [`<tr><th>${label}</th><td>${value}</td></tr>`] : [];
+            });
+            return rows.length > 0 ? `<div class="block"><table class="fields"><tbody>${rows.join('')}</tbody></table></div>` : '';
+        }
+        case enum_1.DocumentBlockType.LINE_ITEMS:
+            return `<div class="block">${lineItemsHtml(block, ctx)}</div>`;
+        case enum_1.DocumentBlockType.TABLE:
+            return `<div class="block"><table class="grid"><thead><tr>${block.columns
+                .map((column) => `<th>${plainHtml(column, ctx)}</th>`)
+                .join('')}</tr></thead><tbody>${block.rows
+                .map((row) => `<tr>${row.map((cell) => `<td>${plainHtml(cell, ctx)}</td>`).join('')}</tr>`)
+                .join('')}</tbody></table></div>`;
+        case enum_1.DocumentBlockType.SIGNATURE: {
+            // Two signers a row, laid out as a grid row by row - signature lines, their labels, date
+            // lines, "Date" - so each line sits level across the signers however long a label wraps.
+            const rows = Array.from({ length: Math.ceil(block.signers.length / 2) }, (_, index) => block.signers.slice(index * 2, index * 2 + 2));
+            return `<div class="block signatures">${rows
+                .map((pair) => `
+      <div class="signature-row">
+        ${pair.map(() => '<div class="sign-line"></div>').join('')}
+        ${pair.map((signer) => `<div class="sign-label">${plainHtml(signer.label, ctx)}</div>`).join('')}
+        ${pair.map(() => '<div class="sign-line date"></div>').join('')}
+        ${pair.map(() => '<div class="sign-label">Date</div>').join('')}
+      </div>`)
+                .join('')}</div>`;
+        }
+        case enum_1.DocumentBlockType.IMAGE: {
+            const url = imageUrls[block.path];
+            if (!url)
+                return ctx.placeholders ? '<div class="block image-missing">[Image]</div>' : '';
+            // An attribute takes text, not markup, so a missing value there is simply left out.
+            const alt = typeof block.alt === 'string' ? filledText(block.alt, ctx) : '';
+            return `<div class="block image"><img src="${(0, values_1.escapeHtml)(url)}" alt="${(0, values_1.escapeHtml)(alt)}"></div>`;
+        }
+        case enum_1.DocumentBlockType.COLUMNS: {
+            // Side by side, each a muted heading over its text, the text's first line as a name. Blank
+            // sides show where they print on a template or draft; an issued column with no text prints
+            // only when its heading has some, and the block with no column left prints nothing.
+            const columns = block.columns.flatMap((column) => {
+                const heading = plainHtml(column.heading, ctx).trim();
+                // Its lines with the blank ones at either end dropped (an issued column's empty last values).
+                const lines = plainHtml(column.text, ctx).split('<br>');
+                while (lines.length > 0 && !lines[0].trim())
+                    lines.shift();
+                while (lines.length > 0 && !lines[lines.length - 1].trim())
+                    lines.pop();
+                const [name = '', ...rest] = lines.map((line) => line.trim());
+                if (!ctx.placeholders && !name && !heading)
+                    return [];
+                const text = name || ctx.placeholders
+                    ? `<div class="column-name">${name || placeholder('Text')}</div>${rest.length > 0 ? `<div class="column-text">${rest.join('<br>')}</div>` : ''}`
+                    : '';
+                return [`<div class="column"><div class="column-heading">${heading || (ctx.placeholders ? placeholder('Heading') : '')}</div>${text}</div>`];
+            });
+            return columns.length > 0
+                ? `<div class="block columns" style="grid-template-columns: repeat(${columns.length}, 1fr);">${columns.join('')}</div>`
+                : '';
+        }
+        case enum_1.DocumentBlockType.PAGE_BREAK:
+            return '<div class="page-break"></div>';
+        // HEADER and FOOTER print in the PDF's running bands, not in the body.
+        default:
+            return '';
+    }
+};
+const contextOf = (document) => ({
+    variables: new Map([
+        ...Object.entries(values_1.SYSTEM_VARIABLES),
+        ...document.variables.map((variable) => [variable.key, variable]),
+    ]),
+    values: document.values,
+    currency: document.currency,
+    placeholders: document.status === null || document.status === enum_1.DocumentStatus.DRAFT,
+});
+/**
+ * Plain text with each `{{key}}` replaced by its value as the document prints it - money in its
+ * currency, dates written out - and a key with no value left empty: a stored email's subject and
+ * message, written before the document had a number, filled when it is sent. Text, not HTML, so
+ * nothing is escaped; the email template shows it as text.
+ */
+const fillText = (text, document) => filledText(text, contextOf(document));
+exports.fillText = fillText;
+/**
+ * The page geometry, in inches: the side and bottom margins, and the top margin - grown to make
+ * room when the document has a header. The api's PDF and the portal's paged preview use the same.
+ */
+exports.DOCUMENT_PAGE_MARGINS = { top: 0.62, topWithHeader: 0.95, bottom: 0.7, side: 0.7 };
+/**
+ * One band as a styled block: left text left, right text right, in the footer's small grey type.
+ * The styles are inline (a placeholder's included) because Chromium's header and footer templates
+ * ignore the document's CSS; the side margins mirror the page's. The api hands it to Chromium as
+ * the header or footer template; the portal's preview places it on each page.
+ */
+const renderBand = (band, edge) => `
+  <style>.placeholder { color: #8a6100; background: #fff4d6; border-radius: 2px; padding: 0 2px; -webkit-print-color-adjust: exact; }</style>
+  <div style="width:100%;margin:0 ${exports.DOCUMENT_PAGE_MARGINS.side}in;${edge === 'top' ? 'padding-top:0.32in;' : ''}font-size:8.5px;color:#6b6960;
+              font-family:-apple-system,'Segoe UI',Helvetica,Arial,sans-serif;
+              display:flex;justify-content:space-between;align-items:baseline;gap:24px;">
+    <span style="text-align:left;">${band.left}</span>
+    <span style="text-align:right;">${band.right}</span>
+  </div>`;
+exports.renderBand = renderBand;
+/**
+ * A document's blocks and values as HTML, plus its running header and footer - the only way a
+ * document or template is shown, so what is seen is what prints. Styled as the subscription
+ * invoice is: the first page's letterhead - the organization top left against the title, number,
+ * issue date and status top right - then the blocks. Header and footer blocks print nothing in the
+ * body: their text is `header` / `footer`, with `{{key}}`s printed as in the body and
+ * `{{page_number}}` / `{{page_count}}` as page-counter spans. `imageUrls` maps the image blocks'
+ * paths to URLs the caller signed; a path without one prints as `[Image]` on a draft or template
+ * and as nothing once issued.
+ */
+const renderDocument = (document, imageUrls) => {
+    const ctx = contextOf(document);
+    const title = (0, values_1.escapeHtml)(document.title || 'Document');
+    const status = document.status ? STATUS_LABELS[document.status] : 'Template';
+    const statusColour = document.status === enum_1.DocumentStatus.ISSUED ? '#1d6b4a'
+        : document.status === enum_1.DocumentStatus.VOID ? '#b3261e'
+            : '#6b6960';
+    const address = valueText(enum_1.DocumentSystemVariable.ORGANIZATION_ADDRESS, ctx);
+    const header = document.blocks.find((block) => block.type === enum_1.DocumentBlockType.HEADER);
+    const footer = document.blocks.find((block) => block.type === enum_1.DocumentBlockType.FOOTER);
+    const defaultLeft = [valueText(enum_1.DocumentSystemVariable.ORGANIZATION_NAME, ctx), [document.title, document.number].filter(Boolean).join(' ')]
+        .filter(Boolean)
+        .map((part) => (0, values_1.escapeHtml)(part))
+        .join(' · ');
+    const html = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>${title}</title>
+<style>
+  /* No @page rule: the PDF renderer's margins own the layout so every page gets them. */
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  html, body { background: #ffffff; }
+  body {
+    font-family: 'Instrument Sans', -apple-system, 'Segoe UI', Helvetica, Arial, sans-serif;
+    color: #1b1b18; font-size: 10.5pt; line-height: 1.5;
+  }
+  .top { display: flex; justify-content: space-between; align-items: flex-start; gap: 40px;
+         padding-bottom: 18px; border-bottom: 1px solid #dedcd4; }
+  .brand-name { font-size: 19px; font-weight: 700; letter-spacing: -0.3px; color: #1d6b4a; line-height: 1.2; }
+  .brand-lines { font-size: 10pt; line-height: 15px; color: #5f5d56; margin-top: 6px; max-width: 60ch; }
+  .brand-lines + .brand-lines { margin-top: 2px; }
+  .doc { text-align: right; }
+  .doc-title { font-size: 26px; font-weight: 700; letter-spacing: -0.6px; line-height: 1.1; }
+  .doc-number { font-family: ${values_1.MONO_FONT}; font-size: 10.5pt; color: #5f5d56; margin-top: 8px; }
+  .doc-date { font-size: 10pt; color: #5f5d56; margin-top: 4px; }
+  .doc-status { font-size: 11pt; font-weight: 700; letter-spacing: 0.3px; color: ${statusColour}; margin-top: 10px; }
+
+  .block { margin-top: 18px; }
+  .text p { margin: 0 0 8px; }
+  .text h1, .text h2, .text h3 { line-height: 1.25; margin: 14px 0 6px; break-after: avoid; }
+  .text h1 { font-size: 16pt; } .text h2 { font-size: 13pt; } .text h3 { font-size: 11pt; }
+  .text ul, .text ol { margin: 0 0 8px 22px; }
+  .text a { color: #1d6b4a; }
+
+  table { width: 100%; border-collapse: collapse; }
+  tr, .totals-wrap, .signatures, .image { break-inside: avoid; }
+  /* The small uppercase label every heading cell and column heading prints in. */
+  .fields th, .column-heading, .items th, .grid th {
+    font-size: 8pt; font-weight: 700; letter-spacing: 1.1px; text-transform: uppercase; color: #6b6960;
+  }
+  .fields th { width: 32%; text-align: left; vertical-align: top; padding: 5px 16px 5px 0; }
+  .fields td { padding: 4px 0; white-space: pre-wrap; vertical-align: top; }
+
+  .columns { display: grid; column-gap: 32px; break-inside: avoid; }
+  .column-heading { margin-bottom: 4px; }
+  .column-name { font-weight: 600; white-space: pre-wrap; }
+  .column-text { white-space: pre-wrap; color: #3a3a38; }
+
+  .items th, .grid th { text-align: left; padding: 0 0 9px 16px; border-bottom: 1px solid #1b1b18; white-space: nowrap; }
+  .items th:first-child, .grid th:first-child, .grid td:first-child { padding-left: 0; }
+  .items th:not(:first-child) { text-align: right; }
+  .items td, .grid td { padding: 9px 0 9px 16px; border-bottom: 1px solid #ebe9e1; vertical-align: top; }
+  .items td.item { padding-left: 0; white-space: pre-wrap; }
+  .items td.num { text-align: right; font-family: ${values_1.MONO_FONT}; font-size: 10pt; white-space: nowrap; }
+  .grid td { white-space: pre-wrap; }
+
+  .totals-wrap { display: flex; justify-content: flex-end; margin-top: 12px; }
+  table.totals { width: auto; min-width: 300px; }
+  .totals td { padding: 4px 0; color: #5f5d56; }
+  .totals td.num { padding-left: 32px; text-align: right; font-family: ${values_1.MONO_FONT}; font-size: 10pt; color: inherit; }
+  .totals tr.grand td { padding-top: 10px; border-top: 1px solid #1b1b18; font-size: 11pt; font-weight: 700; color: #1b1b18; }
+
+  .signatures { margin-top: 36px; }
+  .signature-row { display: grid; grid-template-columns: 1fr 1fr; column-gap: 48px; align-items: start; }
+  .signature-row + .signature-row { margin-top: 28px; }
+  .sign-line { border-bottom: 1px solid #1b1b18; height: 40px; }
+  .sign-line.date { height: 28px; width: 60%; }
+  .sign-label { font-size: 9pt; color: #5f5d56; margin-top: 4px; }
+
+  .image img { display: block; max-width: 100%; max-height: 120mm; }
+  .image-missing { padding: 24px; text-align: center; color: #8a6100; background: #fff4d6; border-radius: 6px; }
+  .placeholder { color: #8a6100; background: #fff4d6; border-radius: 3px; padding: 0 3px; }
+
+  .page-break { break-before: page; page-break-before: always; }
+</style>
+</head>
+<body>
+  <div class="top">
+    <div>
+      <div class="brand-name">${valueHtml(enum_1.DocumentSystemVariable.ORGANIZATION_NAME, ctx)}</div>
+      ${[
+        [address],
+        [
+            prefixed('Reg. no.', valueText(enum_1.DocumentSystemVariable.ORGANIZATION_REGISTRATION_NUMBER, ctx)),
+            prefixed('VAT no.', valueText(enum_1.DocumentSystemVariable.ORGANIZATION_VAT_NUMBER, ctx)),
+        ],
+        [valueText(enum_1.DocumentSystemVariable.ORGANIZATION_EMAIL, ctx), valueText(enum_1.DocumentSystemVariable.ORGANIZATION_PHONE, ctx)],
+    ]
+        .map((parts) => parts.filter(Boolean).join(' · '))
+        .filter(Boolean)
+        .map((line) => `<div class="brand-lines">${(0, values_1.escapeHtml)(line)}</div>`)
+        .join('')}
+    </div>
+    <div class="doc">
+      <div class="doc-title">${title}</div>
+      <!-- The number line is kept on drafts too, so issuing never reflows the pages. -->
+      <div class="doc-number">${document.number ? (0, values_1.escapeHtml)(document.number) : '&nbsp;'}</div>
+      <div class="doc-date">${valueHtml(enum_1.DocumentSystemVariable.ISSUE_DATE, ctx)}</div>
+      <div class="doc-status">${status}</div>
+    </div>
+  </div>
+  ${document.blocks.map((block) => blockHtml(block, ctx, imageUrls)).join('')}
+</body>
+</html>`;
+    return {
+        html,
+        header: header ? { left: plainHtml(header.left, ctx), right: plainHtml(header.right, ctx) } : null,
+        footer: footer
+            ? { left: plainHtml(footer.left, ctx), right: plainHtml(footer.right, ctx) }
+            : {
+                left: defaultLeft,
+                right: `Page ${PAGE_COUNTERS[enum_1.DocumentSystemVariable.PAGE_NUMBER]} of ${PAGE_COUNTERS[enum_1.DocumentSystemVariable.PAGE_COUNT]}`,
+            },
+    };
+};
+exports.renderDocument = renderDocument;

package/dist/documents/render/index.d.ts

@@ -0,0 +1,2 @@
+export { DOCUMENT_PAGE_MARGINS, fillText, renderBand, renderDocument, type DocumentBand, type PrintableDocument, type RenderedDocument, } from './html';
+export { documentTotals, escapeHtml, formatDocumentDate, johannesburgDate, money, MONO_FONT, printsMoney, startingValues, SYSTEM_VARIABLES, systemValues, type DocumentTotals, type SystemValueInputs, } from './values';

package/dist/documents/render/index.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.systemValues = exports.SYSTEM_VARIABLES = exports.startingValues = exports.printsMoney = exports.MONO_FONT = exports.money = exports.johannesburgDate = exports.formatDocumentDate = exports.escapeHtml = exports.documentTotals = exports.renderDocument = exports.renderBand = exports.fillText = exports.DOCUMENT_PAGE_MARGINS = void 0;
+// `@managemint-solutions/sdk/documents`: the document renderer and the values it prints, as pure
+// functions with no dependency beyond the shared entities - no Node, no Nest, no supabase-js, no
+// DOM - so the api's PDF and the portal's in-browser preview are one renderer. The caller loads
+// the organization and client and signs the image URLs; nothing here does I/O.
+var html_1 = require("./html");
+Object.defineProperty(exports, "DOCUMENT_PAGE_MARGINS", { enumerable: true, get: function () { return html_1.DOCUMENT_PAGE_MARGINS; } });
+Object.defineProperty(exports, "fillText", { enumerable: true, get: function () { return html_1.fillText; } });
+Object.defineProperty(exports, "renderBand", { enumerable: true, get: function () { return html_1.renderBand; } });
+Object.defineProperty(exports, "renderDocument", { enumerable: true, get: function () { return html_1.renderDocument; } });
+var values_1 = require("./values");
+Object.defineProperty(exports, "documentTotals", { enumerable: true, get: function () { return values_1.documentTotals; } });
+Object.defineProperty(exports, "escapeHtml", { enumerable: true, get: function () { return values_1.escapeHtml; } });
+Object.defineProperty(exports, "formatDocumentDate", { enumerable: true, get: function () { return values_1.formatDocumentDate; } });
+Object.defineProperty(exports, "johannesburgDate", { enumerable: true, get: function () { return values_1.johannesburgDate; } });
+Object.defineProperty(exports, "money", { enumerable: true, get: function () { return values_1.money; } });
+Object.defineProperty(exports, "MONO_FONT", { enumerable: true, get: function () { return values_1.MONO_FONT; } });
+Object.defineProperty(exports, "printsMoney", { enumerable: true, get: function () { return values_1.printsMoney; } });
+Object.defineProperty(exports, "startingValues", { enumerable: true, get: function () { return values_1.startingValues; } });
+Object.defineProperty(exports, "SYSTEM_VARIABLES", { enumerable: true, get: function () { return values_1.SYSTEM_VARIABLES; } });
+Object.defineProperty(exports, "systemValues", { enumerable: true, get: function () { return values_1.systemValues; } });

package/dist/documents/render/values.d.ts

@@ -0,0 +1,86 @@
+import type { DocumentBlock, DocumentLineItem, DocumentVariable, DocumentVariableValues } from '@managemint-solutions/entities/documents';
+import { DocumentSystemVariable } from '@managemint-solutions/entities/documents/enum';
+/**
+ * A variable in plain text (field values, table cells, line descriptions, signer labels, header
+ * and footer text): `{{key}}`, spaces inside the braces allowed. The content rules check with it
+ * and the renderer replaces with it, so what is checked is exactly what prints. Global: use it
+ * with `matchAll` or `replace`, never `test`.
+ */
+export declare const DOCUMENT_VARIABLE_PATTERN: RegExp;
+/** How each system variable is labelled where it is missing, and the type it prints as. */
+export declare const SYSTEM_VARIABLES: Record<DocumentSystemVariable, Pick<DocumentVariable, 'label' | 'type'>>;
+/** Stored block and rich-text JSON, read property by property. */
+export type Json = Record<string, unknown>;
+export declare const isObject: (value: unknown) => value is Json;
+/**
+ * A link's href, or null unless it is http, https or mailto. The protocol is read as a browser
+ * reads it: the URL parser drops the tabs and newlines a plain prefix check would let hide a
+ * javascript: link. The content rules refuse what this refuses, and the renderer prints only what
+ * it passes.
+ */
+export declare const safeHref: (href: unknown) => string | null;
+export declare const escapeHtml: (value: string) => string;
+/** Integer cents in `currency`, the en-ZA way: `R 1 299,00`. Subscription invoices print with it too. */
+export declare const money: (amountMinor: number, currency: string) => string;
+/** `2026-11-01` -> `1 November 2026`. */
+export declare const formatDocumentDate: (date: string) => string;
+/** The monospace stack for numbers - the design's JetBrains Mono, self-contained. */
+export declare const MONO_FONT = "ui-monospace, 'Cascadia Mono', 'Segoe UI Mono', Consolas, monospace";
+export type DocumentTotals = {
+    subtotal_minor: number;
+    discount_minor: number;
+    tax_minor: number;
+    total_minor: number;
+};
+/**
+ * One line's amounts in cents: gross = quantity x unit price, the discount a percentage of the
+ * gross, net = gross - discount, the tax a percentage of the net - each rounded to the cent.
+ */
+export declare const lineAmounts: (line: DocumentLineItem, values: DocumentVariableValues) => {
+    gross: number;
+    discount: number;
+    net: number;
+    tax: number;
+};
+/** The sums over every line of every line items block in `blocks`; all zero without one. */
+export declare const documentTotals: (blocks: DocumentBlock[], values: DocumentVariableValues) => DocumentTotals;
+/** Whether the content prints money - a line items block or a money variable - and so needs a currency. */
+export declare const printsMoney: (blocks: DocumentBlock[], variables: DocumentVariable[]) => boolean;
+/** A new draft's values: each variable's default, overlaid by the values given. */
+export declare const startingValues: (variables: DocumentVariable[], given?: DocumentVariableValues) => DocumentVariableValues;
+/** The calendar date (`YYYY-MM-DD`) `now` falls on in Africa/Johannesburg - a draft's issue date. */
+export declare const johannesburgDate: (now: Date) => string;
+/** What the system values are read from, as plain values - the caller loads them. */
+export type SystemValueInputs = {
+    organization: {
+        name: string | null | undefined;
+        trading_name: string | null | undefined;
+        /** The address parts in print order (line 1, line 2, city, state, post code, country); blanks are skipped. */
+        address: (string | null | undefined)[];
+        registration_number?: string | null;
+        vat_number?: string | null;
+        email?: string | null;
+        phone?: string | null;
+    };
+    client: {
+        name?: string | null;
+        email?: string | null;
+        phone?: string | null;
+        /** In the organization's print order; blanks are skipped. */
+        address?: (string | null | undefined)[];
+        registration_number?: string | null;
+        vat_number?: string | null;
+    } | null;
+    /** Null until the document is issued. */
+    number: string | null;
+    /** `YYYY-MM-DD`: today on a draft (`johannesburgDate(new Date())`), the issue date once issued. */
+    issueDate: string;
+};
+/**
+ * The values filled in for the system variables: the organization's name (its trading name
+ * first), address, registration and VAT numbers, email and phone; the client's name, email, phone,
+ * address, registration and VAT numbers; the document number; and the issue date with its month
+ * name and year. A value that is empty is left out, so it prints as missing. The
+ * page number and count are not values: they are counted page by page as the PDF prints.
+ */
+export declare const systemValues: ({ organization, client, number, issueDate }: SystemValueInputs) => DocumentVariableValues;