@svgrid/enterprise 3.1.26 → 3.1.28

package/dist/export-pdf.js

@@ -73,6 +73,50 @@ export function registerPdfFonts(pdfMake, vfsModule) {
     pdfMake.vfs = vfs;
     return true;
 }
+const ROBOTO = { normal: 'Roboto-Regular.ttf', bold: 'Roboto-Medium.ttf', italics: 'Roboto-Italic.ttf', bolditalics: 'Roboto-MediumItalic.ttf' };
+/**
+ * Register `font` with pdfmake next to Roboto. Base64 files go into the
+ * virtual file system, merged with what is there (`addVirtualFileSystem`
+ * replaces the map rather than adding to it); URLs are passed through for
+ * pdfmake to fetch.
+ */
+export function registerPdfFont(pdfMake, font) {
+    const files = {};
+    const isUrl = (s) => /^(https?:|blob:|data:|\/|\.\.?\/)/i.test(s);
+    const file = (style, src) => {
+        if (!src)
+            return undefined;
+        if (isUrl(src))
+            return src;
+        const key = `svgrid-${font.name}-${style}.ttf`;
+        files[key] = src;
+        return key;
+    };
+    const normal = file('normal', font.normal);
+    const bold = file('bold', font.bold) ?? normal;
+    const entry = {
+        normal,
+        bold,
+        italics: file('italics', font.italics) ?? normal,
+        bolditalics: file('bolditalics', font.bolditalics) ?? bold,
+    };
+    if (Object.keys(files).length) {
+        const vfs = { ...(pdfMake.vfs ?? {}), ...files };
+        if (typeof pdfMake.addVirtualFileSystem === 'function')
+            pdfMake.addVirtualFileSystem(vfs);
+        pdfMake.vfs = vfs;
+    }
+    const fonts = { Roboto: ROBOTO, ...(pdfMake.fonts ?? {}), [font.name]: entry };
+    if (typeof pdfMake.addFonts === 'function')
+        pdfMake.addFonts(fonts);
+    pdfMake.fonts = fonts;
+}
+/**
+ * Text Roboto has no glyphs for: CJK, Hangul, Arabic, Hebrew, Thai, the Indic
+ * scripts, dingbats (check marks, stars) and emoji. Exported so an export can
+ * warn that it needs `pdf.font`.
+ */
+export const PDF_ROBOTO_MISSING = /[֐-ࣿऀ-෿฀-๿ᄀ-ᇿ☀-➿⺀-鿿가-힯豈-﫿＀-￯\u{1f000}-\u{1faff}]/u;
 /** `rgb(...)` / `rgba(...)` / `#hex` -> `#rrggbb`, or null for transparent and anything else. */
 export function cssColorToHex(value) {
     if (!value)
@@ -193,10 +237,39 @@ export async function resolvePdfCharts(charts, rasterize) {
     return out;
 }
 /**
- * Build a pdfmake docDefinition from resolved columns + formatted string rows.
- * `now` is injected for a deterministic footer date in tests.
+ * The conditional-format icon sets as shapes. Their glyphs (arrows,
+ * triangles, coloured circles) are not in Roboto and printed as empty boxes,
+ * so they are drawn instead, in the red / amber / green the sets mean.
  */
-export function buildPdfDocDefinition(params) {
+const ICON_RED = '#dc2626';
+const ICON_AMBER = '#d97706';
+const ICON_YELLOW = '#eab308';
+const ICON_GREEN = '#16a34a';
+const poly = (points, color) => ({ type: 'polyline', points, closePath: true, lineWidth: 0.1, lineColor: color, color });
+const arrowUp = (s) => [
+    { x: s / 2, y: 0 }, { x: s, y: s * 0.5 }, { x: s * 0.68, y: s * 0.5 }, { x: s * 0.68, y: s },
+    { x: s * 0.32, y: s }, { x: s * 0.32, y: s * 0.5 }, { x: 0, y: s * 0.5 },
+];
+const PDF_ICON_SHAPES = {
+    '↑': (s) => [poly(arrowUp(s), ICON_GREEN)],
+    '↓': (s) => [poly(arrowUp(s).map((p) => ({ x: p.x, y: s - p.y })), ICON_RED)],
+    '→': (s) => [poly(arrowUp(s).map((p) => ({ x: s - p.y, y: p.x })), ICON_AMBER)],
+    '▲': (s) => [poly([{ x: 0, y: s }, { x: s / 2, y: 0 }, { x: s, y: s }], ICON_GREEN)],
+    '▼': (s) => [poly([{ x: 0, y: 0 }, { x: s, y: 0 }, { x: s / 2, y: s }], ICON_RED)],
+    '◆': (s) => [poly([{ x: s / 2, y: 0 }, { x: s, y: s / 2 }, { x: s / 2, y: s }, { x: 0, y: s / 2 }], ICON_AMBER)],
+    '🔴': (s) => [{ type: 'ellipse', x: s / 2, y: s / 2, r1: s / 2, r2: s / 2, color: ICON_RED }],
+    '🟡': (s) => [{ type: 'ellipse', x: s / 2, y: s / 2, r1: s / 2, r2: s / 2, color: ICON_YELLOW }],
+    '🟢': (s) => [{ type: 'ellipse', x: s / 2, y: s / 2, r1: s / 2, r2: s / 2, color: ICON_GREEN }],
+    // A true boolean, where the grid draws a ticked checkbox.
+    '✓': (s) => [{ type: 'polyline', points: [{ x: 0, y: s * 0.55 }, { x: s * 0.38, y: s * 0.92 }, { x: s, y: s * 0.08 }], lineWidth: Math.max(1, s * 0.16), lineColor: '#334155' }],
+};
+/**
+ * Build the pdfmake document from resolved columns + formatted string rows,
+ * as plain data: no functions, so it can be posted to a worker. Hand it to
+ * {@link hydratePdfDoc} before pdfmake sees it, or use
+ * {@link buildPdfDocDefinition}, which does both.
+ */
+export function buildPdfDocData(params) {
     const { columns } = params;
     const o = params.opts ?? {};
     const st = params.styles ?? {};
@@ -255,9 +328,10 @@ export function buildPdfDocDefinition(params) {
     }
     const orientation = o.pageOrientation ??
         (columns.length > (o.autoLandscapeThreshold ?? 8) ? 'landscape' : 'portrait');
-    const widths = Array.isArray(o.columnWidths)
-        ? o.columnWidths
-        : columns.map(() => (o.columnWidths === 'auto' ? 'auto' : '*'));
+    const margins = o.margins ?? [28, 34, 28, 34];
+    const [pw, ph] = PAGE_PT[o.pageSize ?? 'A4'];
+    const contentWidth = (orientation === 'landscape' ? ph : pw) - margins[0] - margins[2];
+    const contentHeight = (orientation === 'landscape' ? pw : ph) - margins[1] - margins[3];
     // Header row.
     const headerRow = columns.map((c, ci) => {
         const cell = {
@@ -280,6 +354,9 @@ export function buildPdfDocDefinition(params) {
     const dataCellLink = params.dataCellLink;
     let dataOrdinal = 0;
     const dataRowIdx = new Set();
+    const groupRowIdx = new Set();
+    /** Cells with a drawn icon: [body row, column, icon]. Drawn after the layout is measured. */
+    const icons = [];
     const bodyCells = [headerRow];
     model.forEach((row, i) => {
         const bi = i + 1; // +1 for the header row
@@ -293,6 +370,7 @@ export function buildPdfDocDefinition(params) {
                 margin: [(row.level ?? 0) * 12, 2, 0, 2],
             };
             const rest = Array.from({ length: Math.max(0, columns.length - 1) }, () => ({ text: '' }));
+            groupRowIdx.add(bi);
             bodyCells.push([first, ...rest]);
         }
         else if (row.kind === 'subtotal') {
@@ -323,6 +401,12 @@ export function buildPdfDocDefinition(params) {
                         cell.color = s.color;
                     if (s.bold)
                         cell.bold = true;
+                    if (s.icon && s.iconOnly)
+                        cell.text = '';
+                    if (s.icon && PDF_ICON_SHAPES[s.icon])
+                        icons.push([bi, ci, s.icon]);
+                    else if (s.icon)
+                        cell.text = s.iconOnly ? s.icon : `${s.icon} ${cell.text ?? ''}`;
                 }
                 const href = dataCellLink?.(ord, ci);
                 if (href) {
@@ -366,26 +450,188 @@ export function buildPdfDocDefinition(params) {
             }
         }
     }
-    const table = {
-        table: {
-            headerRows: repeatHeader ? 1 : 0,
-            dontBreakRows: true,
-            widths,
-            body: bodyCells,
-        },
-        layout: {
-            // Zebra fill: only plain data rows (group / subtotal have their own).
-            fillColor: (rowIndex) => zebra && rowIndex > 0 && rowIndex % 2 === 0 && dataRowIdx.has(rowIndex) ? zebraColor : null,
-            hLineWidth: () => 0.5,
-            vLineWidth: () => 0.5,
-            hLineColor: () => borderColor,
-            vLineColor: () => borderColor,
-            paddingTop: () => 3,
-            paddingBottom: () => 3,
-            paddingLeft: () => 5,
-            paddingRight: () => 5,
-        },
+    // ---- Layout -------------------------------------------------------------
+    // pdfmake sizes a '*' column no narrower than its longest word, so a wide
+    // grid ran off the right edge and its last columns were never printed. The
+    // widths are worked out here instead, from the text, against the page:
+    // shrink the type, or split the columns over pages, so every column prints.
+    // Measured with Roboto's average advance, on the wide side so a column is
+    // never narrower than its text.
+    const n = columns.length;
+    const PAD = 10.5; // padding left + right, and one vertical line
+    const emOf = (bold) => (bold ? 0.62 : 0.56);
+    const iconAt = new Set(icons.map(([bi, ci]) => `${bi}:${ci}`));
+    // Widths at a 1 pt font: the longest word (a column cannot be narrower) and
+    // the longest line (what it would like). Spanning cells are left out.
+    const minAt1 = new Array(n).fill(0);
+    const natAt1 = new Array(n).fill(0);
+    bodyCells.forEach((row, bi) => {
+        if (groupRowIdx.has(bi))
+            return;
+        row.forEach((cell, ci) => {
+            if ((cell.colSpan ?? 1) > 1 || ci >= n)
+                return;
+            const k = emOf(cell.bold) * (cell.fontSize ?? fontSize) / fontSize;
+            const extra = iconAt.has(`${bi}:${ci}`) ? 2 : 0;
+            let word = 0;
+            let line = 0;
+            for (const l of (cell.text ?? '').split('\n')) {
+                line = Math.max(line, l.length);
+                for (const w of l.split(/\s+/))
+                    word = Math.max(word, w.length);
+            }
+            // A 60-character URL should not claim a third of the page; past 28
+            // characters a word is left to wrap or overflow its cell.
+            minAt1[ci] = Math.max(minAt1[ci], (Math.min(word, 28) + extra) * k);
+            natAt1[ci] = Math.max(natAt1[ci], (line + extra) * k);
+        });
+    });
+    const budget = (count) => contentWidth - count * PAD - 2;
+    const sumMin = (cols, f) => cols.reduce((a, ci) => a + Math.max(minAt1[ci] * f, f), 0);
+    const fit = o.fit ?? 'auto';
+    const explicitWidths = Array.isArray(o.columnWidths) ? o.columnWidths : null;
+    const all = columns.map((_, i) => i);
+    let tableFont = fontSize;
+    let chunks = [all];
+    if (fit !== 'none' && !explicitWidths && n > 0 && sumMin(all, fontSize) > budget(n)) {
+        const room = budget(n);
+        const fitFont = room > 0 ? (fontSize * room) / sumMin(all, fontSize) : 0;
+        const floor = fit === 'shrink' ? 4 : Math.max(5, fontSize * 0.75);
+        if (fit !== 'split' && fitFont >= floor)
+            tableFont = Math.floor(fitFont * 10) / 10;
+        else if (fit === 'shrink')
+            tableFont = floor;
+        else {
+            // Split: the leading columns on every page, the rest packed in order.
+            const keep = Math.max(0, Math.min(o.repeatColumns ?? 1, n - 1));
+            const lead = all.slice(0, keep);
+            chunks = [];
+            let cur = [];
+            for (let ci = keep; ci < n; ci++) {
+                if (cur.length && sumMin([...lead, ...cur, ci], fontSize) > budget(lead.length + cur.length + 1)) {
+                    chunks.push([...lead, ...cur]);
+                    cur = [];
+                }
+                cur.push(ci);
+            }
+            if (cur.length)
+                chunks.push([...lead, ...cur]);
+        }
+    }
+    const widthsFor = (cols) => {
+        if (explicitWidths) {
+            // Explicit numbers are kept unless together they run off the page.
+            const nums = explicitWidths.filter((w) => typeof w === 'number');
+            const total = nums.reduce((a, b) => a + b, 0);
+            const room = budget(explicitWidths.length);
+            return total > room && fit !== 'none'
+                ? explicitWidths.map((w) => (typeof w === 'number' ? Math.floor((w * room) / total) : w))
+                : explicitWidths;
+        }
+        if (fit === 'none')
+            return cols.map(() => (o.columnWidths === 'auto' ? 'auto' : '*'));
+        const min = cols.map((ci) => Math.max(minAt1[ci] * tableFont, tableFont));
+        const nat = cols.map((ci, i) => Math.max(min[i], natAt1[ci] * tableFont));
+        const room = budget(cols.length);
+        const sumNat = nat.reduce((a, b) => a + b, 0);
+        let out;
+        if (o.columnWidths === 'auto' && sumNat <= room)
+            out = nat;
+        else if (sumNat <= room)
+            out = nat.map((w) => w + (room - sumNat) / cols.length);
+        else {
+            // Every column gets its longest word; what is left goes to the
+            // columns that want more, in proportion, so a notes column takes the
+            // room an id column does not need.
+            const sumMinW = min.reduce((a, b) => a + b, 0);
+            const spare = Math.max(0, room - sumMinW);
+            const want = nat.reduce((a, w, i) => a + (w - min[i]), 0);
+            out = min.map((m, i) => m + (want > 0 ? (spare * (nat[i] - m)) / want : spare / cols.length));
+        }
+        return out.map((w) => Math.floor(w * 100) / 100);
+    };
+    // A row taller than the page cannot be kept whole, and pdfmake drops it
+    // without a word when told not to break rows. So rows stay whole unless one
+    // would come near a page's height; then rows may break.
+    const lineHeight = tableFont * 1.25;
+    const rowHeight = (row, cols, widths) => {
+        let h = 0;
+        cols.forEach((ci, i) => {
+            const cell = row[ci];
+            const w = widths[i];
+            if (!cell || (cell.rowSpan ?? 1) > 1 || typeof w !== 'number')
+                return;
+            const k = emOf(cell.bold) * (cell.fontSize ?? tableFont);
+            let lines = 0;
+            for (const l of (cell.text ?? '').split('\n'))
+                lines += Math.max(1, Math.ceil((l.length * k) / Math.max(w, 1)));
+            h = Math.max(h, lines * lineHeight * ((cell.fontSize ?? tableFont) / tableFont));
+        });
+        return h + 6;
     };
+    // The icons, drawn next to the text now that the widths are known.
+    for (const [bi, ci, icon] of icons) {
+        const cell = bodyCells[bi]?.[ci];
+        if (!cell)
+            continue;
+        const size = tableFont * 0.8;
+        const { text, alignment, color, bold, italics, fontSize: fs, link, decoration } = cell;
+        delete cell.text;
+        const shape = { width: size + 3, canvas: PDF_ICON_SHAPES[icon](size), margin: [0, tableFont * 0.2, 0, 0] };
+        const gap = { width: '*', text: '' };
+        // An icon with text beside it leads the cell; one on its own (a ticked
+        // boolean) sits where the column aligns its values.
+        cell.columns = text
+            ? [shape, { width: '*', text, alignment, color, bold, italics, fontSize: fs, link, decoration }]
+            : alignment === 'center' ? [gap, shape, gap] : alignment === 'right' ? [gap, shape] : [shape, gap];
+        cell.columnGap = 0;
+        for (const key of ['alignment', 'color', 'bold', 'italics', 'fontSize', 'link', 'decoration'])
+            delete cell[key];
+    }
+    // One table per chunk of columns. Group rows span the chunk; a merge is
+    // cut to the columns the chunk holds.
+    const sliceRow = (row, bi, cols) => {
+        if (cols.length === n && cols.every((c, i) => c === i))
+            return row;
+        if (groupRowIdx.has(bi))
+            return [{ ...row[0], colSpan: cols.length }, ...cols.slice(1).map(() => ({ text: '' }))];
+        return cols.map((ci, k) => {
+            const cell = row[ci];
+            const span = cell.colSpan ?? 1;
+            if (span <= 1)
+                return cell;
+            let run = 1;
+            while (run < span && cols[k + run] === ci + run)
+                run += 1;
+            return { ...cell, colSpan: run };
+        });
+    };
+    // The table's look as data (see hydratePdfDoc): zebra fill on every other
+    // plain data row (group / subtotal rows carry their own fill).
+    const svgridLayout = {
+        kind: 'table',
+        stripes: zebra ? [...dataRowIdx].filter((r) => r > 0 && r % 2 === 0) : [],
+        zebraColor,
+        lineColor: borderColor,
+    };
+    const tables = chunks.map((cols, i) => {
+        const widths = widthsFor(cols);
+        const body = bodyCells.map((row, bi) => sliceRow(row, bi, cols));
+        const headerHeight = repeatHeader ? rowHeight(body[0], cols.map((_, k) => k), widths) : 0;
+        const room = contentHeight - headerHeight;
+        const tall = body.some((row, bi) => bi > 0 && !groupRowIdx.has(bi) && rowHeight(row, cols.map((_, k) => k), widths) > room * 0.7);
+        return {
+            ...(i > 0 ? { pageBreak: 'before' } : {}),
+            ...(tableFont !== fontSize ? { fontSize: tableFont } : {}),
+            table: {
+                headerRows: repeatHeader ? 1 : 0,
+                dontBreakRows: !tall,
+                widths,
+                body,
+            },
+            svgridLayout,
+        };
+    });
     // The lines `ExportOptions.header` / `footer` carry: text with a style, an
     // image, or a left / centre / right triple, above and below the table the
     // way the xlsx writer puts them in rows around it.
@@ -433,22 +679,11 @@ export function buildPdfDocDefinition(params) {
                     })),
                 ],
             },
-            layout: {
-                hLineWidth: () => 0,
-                vLineWidth: () => 4,
-                vLineColor: () => '#ffffff',
-                paddingLeft: () => 0,
-                paddingRight: () => 0,
-                paddingTop: () => 0,
-                paddingBottom: () => 0,
-            },
+            svgridLayout: { kind: 'kpi' },
             margin: [0, 0, 0, 10],
         });
     }
     // Charts: the resolved images, at the content width unless told otherwise.
-    const margins = o.margins ?? [28, 34, 28, 34];
-    const [pw, ph] = PAGE_PT[o.pageSize ?? 'A4'];
-    const contentWidth = (orientation === 'landscape' ? ph : pw) - margins[0] - margins[2];
     const chartImages = params.charts ?? (o.charts ?? []).filter((c) => 'image' in c);
     const chartBlocks = chartImages.map((c) => ({
         stack: [
@@ -461,7 +696,7 @@ export function buildPdfDocDefinition(params) {
     }));
     if (o.chartsPosition !== 'below')
         content.push(...chartBlocks);
-    content.push(table);
+    content.push(...tables);
     if (o.chartsPosition === 'below') {
         if (chartBlocks.length)
             content.push({ text: '', margin: [0, 0, 0, 12] });
@@ -471,19 +706,108 @@ export function buildPdfDocDefinition(params) {
     const def = {
         pageSize: o.pageSize ?? 'A4',
         pageOrientation: orientation,
-        pageMargins: o.margins ?? [28, 34, 28, 34],
-        defaultStyle: { fontSize },
+        pageMargins: margins,
+        defaultStyle: o.font ? { fontSize, font: o.font.name } : { fontSize },
         content,
+        info: {
+            ...(o.title ? { title: o.title } : {}),
+            ...(o.author ? { author: o.author } : {}),
+            ...(o.subtitle ? { subject: o.subtitle } : {}),
+            creator: 'SvGrid',
+            creationDate: now,
+        },
     };
+    if (o.watermark) {
+        const w = typeof o.watermark === 'string' ? { text: o.watermark } : o.watermark;
+        def.watermark = { text: w.text, color: w.color ?? '#94a3b8', opacity: w.opacity ?? 0.15, bold: true };
+    }
     if (o.showPageNumbers ?? true) {
-        const dateStr = now.toISOString().slice(0, 10);
+        // The date where the export ran, not in UTC: toISOString() printed
+        // yesterday for anyone east of Greenwich exporting after midnight.
+        const pad = (v) => String(v).padStart(2, '0');
+        const dateStr = o.labels?.date?.(now) ?? `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+        // The page label travels as a template, for a worker that cannot be
+        // handed the function: it is called once with stand-in numbers, which are
+        // then swapped for placeholders. A label that formats its numbers (a
+        // thousands separator) loses them, and the default text is used instead.
+        let page = 'Page {page} of {pages}';
+        if (o.labels?.page) {
+            const sample = o.labels.page(PAGE_STAND_IN, PAGES_STAND_IN);
+            if (sample.includes(String(PAGE_STAND_IN)) && sample.includes(String(PAGES_STAND_IN))) {
+                page = sample.split(String(PAGE_STAND_IN)).join('{page}').split(String(PAGES_STAND_IN)).join('{pages}');
+            }
+        }
+        def.svgridFooter = { margin: [margins[0], 6, margins[2], 0], date: dateStr, page };
+    }
+    return def;
+}
+const PAGE_STAND_IN = 86421;
+const PAGES_STAND_IN = 97531;
+/**
+ * Build the pdfmake document for a table and hand it over ready to render.
+ * Same as {@link buildPdfDocData}, with its layouts and footer turned into
+ * the functions pdfmake calls.
+ */
+export function buildPdfDocDefinition(params) {
+    return hydratePdfDoc(buildPdfDocData(params), { page: params.opts?.labels?.page });
+}
+/**
+ * Give a document from {@link buildPdfDocData} the functions pdfmake calls:
+ * each table's fill and line callbacks and the page footer. Runs where the
+ * PDF is rendered, which may be a worker the functions could not be sent to.
+ * `page` overrides the footer's page template with the caller's own function.
+ */
+export function hydratePdfDoc(doc, opts = {}) {
+    const visit = (node) => {
+        if (Array.isArray(node)) {
+            node.forEach(visit);
+            return;
+        }
+        if (!node || typeof node !== 'object')
+            return;
+        const n = node;
+        if (n.svgridLayout)
+            n.layout = layoutFor(n.svgridLayout);
+        if (n.stack)
+            visit(n.stack);
+    };
+    visit(doc.content);
+    const def = doc;
+    const footer = doc.svgridFooter;
+    if (footer) {
+        const page = opts.page ?? ((p, n) => footer.page.split('{page}').join(String(p)).split('{pages}').join(String(n)));
         def.footer = (currentPage, pageCount) => ({
-            margin: [28, 6, 28, 0],
+            margin: footer.margin,
             columns: [
-                { text: dateStr, alignment: 'left', fontSize: 7, color: '#94a3b8' },
-                { text: `Page ${currentPage} of ${pageCount}`, alignment: 'right', fontSize: 7, color: '#94a3b8' },
+                { text: footer.date, alignment: 'left', fontSize: 7, color: '#94a3b8' },
+                { text: page(currentPage, pageCount), alignment: 'right', fontSize: 7, color: '#94a3b8' },
             ],
         });
     }
     return def;
 }
+function layoutFor(spec) {
+    if (spec.kind === 'kpi') {
+        return {
+            hLineWidth: () => 0,
+            vLineWidth: () => 4,
+            vLineColor: () => '#ffffff',
+            paddingLeft: () => 0,
+            paddingRight: () => 0,
+            paddingTop: () => 0,
+            paddingBottom: () => 0,
+        };
+    }
+    const stripes = new Set(spec.stripes);
+    return {
+        fillColor: (rowIndex) => (stripes.has(rowIndex) ? spec.zebraColor : null),
+        hLineWidth: () => 0.5,
+        vLineWidth: () => 0.5,
+        hLineColor: () => spec.lineColor,
+        vLineColor: () => spec.lineColor,
+        paddingTop: () => 3,
+        paddingBottom: () => 3,
+        paddingLeft: () => 5,
+        paddingRight: () => 5,
+    };
+}

package/dist/export.d.ts

@@ -1,4 +1,4 @@
-import type { CellFormatConfig, RowData, TableFeatures } from '@svgrid/grid';
+import type { CellFormatConfig, GroupAggregator, RowData, TableFeatures } from '@svgrid/grid';
 import type { SvGridApi } from '@svgrid/grid';
 import { type CsvOptions, type SerializeProgress } from './export-serialize.js';
 import { type PdfBodyRow, type PdfExportOptions } from './export-pdf.js';
@@ -41,6 +41,12 @@ export type ExportColumn<TData = RowData> = {
      * `format`. Return a number / Date to keep it typed in xlsx.
      */
     exportValue?: (row: TData) => string | number | Date | null | undefined;
+    /**
+     * How the column totals in a grouped PDF's subtotal and total rows: the
+     * grid's `GroupAggregator`. Taken from the grid's column when you don't pass
+     * `columns`. Without one, number and currency columns sum.
+     */
+    aggregate?: GroupAggregator<TData>;
 };
 /** Progress reported during an export. `phase` is 'project' while building
  *  rows, 'serialize' while writing text formats, 'write' around the xlsx/pdf
@@ -298,12 +304,24 @@ export declare function projectRows<TData extends RowData>(sourceRows: ReadonlyA
 /** A `(rowIdx, colIdx) => url` resolver from column `link` hooks, or undefined
  *  when no column defines links. */
 export declare function buildLinkResolver<TData extends RowData>(cols: ReadonlyArray<ExportColumn<TData>>, rows: ReadonlyArray<TData>): ((rowIdx: number, colIdx: number) => string | undefined) | undefined;
+/** The words a grouped PDF prints around its totals; see `PdfExportOptions.labels`. */
+export type GroupedPdfLabels = {
+    subtotal?: (group: string) => string;
+    total?: string;
+};
 /**
  * Build a grouped PDF body: a bold group header per cluster (nested for
- * multi-level grouping), the cluster's data rows, then a subtotal row summing
- * the numeric / currency columns. Values use the same formatting as the grid.
+ * multi-level grouping), the cluster's data rows, a subtotal row, and a grand
+ * total at the end. A column totals with its own `aggregate` (avg, min, max,
+ * count, ...), as the grid's group rows do; without one, number and currency
+ * columns sum. Values and group names use the same formatting as the grid.
+ * Each data row carries its index in `rows`, so conditional formatting and
+ * links can find their row.
  */
-export declare function buildGroupedPdfBody<TData extends RowData>(cols: ReadonlyArray<ExportColumn<TData>>, rows: ReadonlyArray<TData>, groupBy: ReadonlyArray<string>): PdfBodyRow[];
+export declare function buildGroupedPdfBody<TData extends RowData>(cols: ReadonlyArray<ExportColumn<TData>>, rows: ReadonlyArray<TData>, groupBy: ReadonlyArray<string>, opts?: {
+    grandTotal?: boolean;
+    labels?: GroupedPdfLabels;
+}): PdfBodyRow[];
 /**
  * Export a grid's rows to a file: xlsx, xls, pdf, csv, tsv, html, json, xml
  * or md, picked by `opts.format`. It reads the columns and rows through the