@svgrid/enterprise 2.5.2 → 2.6.0

package/dist/export-ooxml.js

@@ -0,0 +1,385 @@
+/**
+ * Native OOXML (.xlsx) writer. The vendored Smart exporter only applies uniform
+ * header/row styles - it ignores per-cell styles, and can't do color scales /
+ * data bars - so conditional-formatting colors never reached Excel. This writer
+ * builds a real xlsx workbook from scratch (styles.xml + sheet.xml, zipped with
+ * jszip) so we get, together, in one file:
+ *   - typed number / date cells with a number format (Excel sums + sorts them),
+ *   - true PER-CELL fills / font color / bold (conditional formatting),
+ *   - a frozen header (and optional frozen columns),
+ *   - auto-fit / explicit column widths,
+ *   - real cell hyperlinks.
+ *
+ * It's split into a pure `buildXlsxParts` (returns the XML parts - fully unit
+ * testable) and `packageXlsx` (zips them into a Blob via a provided JSZip).
+ */
+const XML_ESCAPE = {
+    '&': '&',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&apos;',
+};
+// Control chars that are illegal in XML 1.0 (would make Excel reject the file).
+// XML 1.0 forbids these control characters outright, so they are stripped
+// rather than escaped - a stray \x00 from a data source would otherwise
+// produce a workbook Excel refuses to open.
+// eslint-disable-next-line no-control-regex
+const INVALID_XML = /[\x00-\x08\x0B\x0C\x0E-\x1F]/g;
+function esc(s) {
+    return s.replace(INVALID_XML, '').replace(/[&<>"']/g, (c) => XML_ESCAPE[c]);
+}
+/** 0-based column index -> Excel letter (0 -> A, 26 -> AA). */
+export function colName(index) {
+    let n = index;
+    let s = '';
+    do {
+        s = String.fromCharCode(65 + (n % 26)) + s;
+        n = Math.floor(n / 26) - 1;
+    } while (n >= 0);
+    return s;
+}
+/** '#rrggbb' -> 'FFRRGGBB' (ARGB) for OOXML; null when unparseable. */
+function argb(hex) {
+    if (!hex)
+        return null;
+    const m = /^#?([0-9a-f]{6})$/i.exec(hex.trim());
+    return m ? 'FF' + m[1].toUpperCase() : null;
+}
+/** Excel serial date (days since 1899-12-30), UTC-based. */
+function toSerialDate(d) {
+    const epoch = Date.UTC(1899, 11, 30);
+    return (d.getTime() - epoch) / 86400000;
+}
+// Static package parts that never change.
+const CONTENT_TYPES = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n` +
+    `<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">` +
+    `<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>` +
+    `<Default Extension="xml" ContentType="application/xml"/>` +
+    `<Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>` +
+    `<Override PartName="/xl/worksheets/sheet1.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>` +
+    `<Override PartName="/xl/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml"/>` +
+    `</Types>`;
+const ROOT_RELS = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n` +
+    `<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">` +
+    `<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="xl/workbook.xml"/>` +
+    `</Relationships>`;
+/** Excel forbids \ / ? * [ ] : in a sheet name and caps it at 31 chars. */
+function safeSheetName(name) {
+    return name.replace(/[\\/?*[\]:]/g, ' ').trim().slice(0, 31) || 'Sheet1';
+}
+function workbookXml(sheetName) {
+    return (`<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n` +
+        `<workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" ` +
+        `xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">` +
+        `<sheets><sheet name="${esc(safeSheetName(sheetName))}" sheetId="1" r:id="rId1"/></sheets>` +
+        `</workbook>`);
+}
+const WORKBOOK_RELS = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n` +
+    `<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">` +
+    `<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="worksheets/sheet1.xml"/>` +
+    `<Relationship Id="rId2" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/>` +
+    `</Relationships>`;
+/**
+ * Build a style registry from the cell styles used, and return `styles.xml`
+ * plus a `styleIndexOf(cell)` that maps each cell to its `s=` index.
+ */
+function buildStyles(header, rows) {
+    // numFmts (custom codes start at 164), fonts, fills, and cellXfs are deduped.
+    const numFmts = new Map(); // code -> id
+    let nextNumFmtId = 164;
+    const numFmtIdOf = (code) => {
+        if (!code)
+            return 0;
+        const existing = numFmts.get(code);
+        if (existing != null)
+            return existing;
+        const id = nextNumFmtId++;
+        numFmts.set(code, id);
+        return id;
+    };
+    // Font 0 = default. Header font (bold) is font 1.
+    const fonts = ['<font><sz val="11"/><name val="Calibri"/></font>', '<font><b/><sz val="11"/><name val="Calibri"/></font>'];
+    const fontKey = new Map();
+    const fontIdOf = (bold, color) => {
+        const c = argb(color);
+        if (!bold && !c)
+            return 0;
+        const key = `${bold ? 'b' : ''}|${c ?? ''}`;
+        const existing = fontKey.get(key);
+        if (existing != null)
+            return existing;
+        const id = fonts.length;
+        fonts.push(`<font>${bold ? '<b/>' : ''}<sz val="11"/><name val="Calibri"/>${c ? `<color rgb="${c}"/>` : ''}</font>`);
+        fontKey.set(key, id);
+        return id;
+    };
+    // Fill 0 = none, fill 1 = gray125 (Excel requires both first).
+    const fills = ['<fill><patternFill patternType="none"/></fill>', '<fill><patternFill patternType="gray125"/></fill>'];
+    const fillKey = new Map();
+    const fillIdOf = (bg) => {
+        const c = argb(bg);
+        if (!c)
+            return 0;
+        const existing = fillKey.get(c);
+        if (existing != null)
+            return existing;
+        const id = fills.length;
+        fills.push(`<fill><patternFill patternType="solid"><fgColor rgb="${c}"/><bgColor indexed="64"/></patternFill></fill>`);
+        fillKey.set(c, id);
+        return id;
+    };
+    // cellXfs: xf 0 = default. Header xf (bold) is 1.
+    const xfs = ['<xf numFmtId="0" fontId="0" fillId="0" borderId="0" xfId="0"/>', '<xf numFmtId="0" fontId="1" fillId="0" borderId="0" xfId="0" applyFont="1"/>'];
+    const xfKey = new Map();
+    const xfIdOf = (numFmtId, fontId, fillId, align) => {
+        const key = `${numFmtId}|${fontId}|${fillId}|${align ?? ''}`;
+        const existing = xfKey.get(key);
+        if (existing != null)
+            return existing;
+        const id = xfs.length;
+        const alignXml = align && align !== 'left' ? `<alignment horizontal="${align}"/>` : '';
+        xfs.push(`<xf numFmtId="${numFmtId}" fontId="${fontId}" fillId="${fillId}" borderId="0" xfId="0"` +
+            `${numFmtId ? ' applyNumberFormat="1"' : ''}${fontId ? ' applyFont="1"' : ''}` +
+            `${fillId ? ' applyFill="1"' : ''}${alignXml ? ' applyAlignment="1"' : ''}>${alignXml}</xf>`);
+        xfKey.set(key, id);
+        return id;
+    };
+    const styleIndexOf = (cell) => {
+        const numFmtId = numFmtIdOf(cell.numFmt);
+        const fontId = fontIdOf(cell.bold === true, cell.color);
+        const fillId = fillIdOf(cell.fill);
+        if (numFmtId === 0 && fontId === 0 && fillId === 0 && (!cell.align || cell.align === 'left'))
+            return 0;
+        return xfIdOf(numFmtId, fontId, fillId, cell.align);
+    };
+    // Pre-register every cell's style so the registry is complete before we emit.
+    for (const row of rows)
+        for (const cell of row)
+            styleIndexOf(cell);
+    const build = () => {
+        const numFmtXml = numFmts.size > 0
+            ? `<numFmts count="${numFmts.size}">${[...numFmts.entries()]
+                .map(([code, id]) => `<numFmt numFmtId="${id}" formatCode="${esc(code)}"/>`)
+                .join('')}</numFmts>`
+            : '';
+        return (`<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n` +
+            `<styleSheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">` +
+            numFmtXml +
+            `<fonts count="${fonts.length}">${fonts.join('')}</fonts>` +
+            `<fills count="${fills.length}">${fills.join('')}</fills>` +
+            `<borders count="1"><border><left/><right/><top/><bottom/><diagonal/></border></borders>` +
+            `<cellStyleXfs count="1"><xf numFmtId="0" fontId="0" fillId="0" borderId="0"/></cellStyleXfs>` +
+            `<cellXfs count="${xfs.length}">${xfs.join('')}</cellXfs>` +
+            `<cellStyles count="1"><cellStyle name="Normal" xfId="0" builtinId="0"/></cellStyles>` +
+            `</styleSheet>`);
+    };
+    return { styleIndexOf, build };
+}
+/**
+ * Build the OOXML package parts for a single-sheet workbook. Returns a map of
+ * `path -> xml string` ready to be zipped by {@link packageXlsx}.
+ */
+export function buildXlsxParts(model) {
+    const { header, rows } = model;
+    const styles = buildStyles(header, rows);
+    // Collect hyperlinks (ref -> url) for the sheet rels + <hyperlinks> block.
+    const links = [];
+    // Header row (row 1), style index 1 (bold).
+    const headerCells = header
+        .map((h, c) => `<c r="${colName(c)}1" s="1" t="inlineStr"><is><t xml:space="preserve">${esc(h)}</t></is></c>`)
+        .join('');
+    const sheetRows = [`<row r="1">${headerCells}</row>`];
+    for (let r = 0; r < rows.length; r++) {
+        const rowNum = r + 2;
+        const cells = rows[r];
+        const cellXml = [];
+        for (let c = 0; c < cells.length; c++) {
+            const cell = cells[c];
+            const ref = `${colName(c)}${rowNum}`;
+            const s = styles.styleIndexOf(cell);
+            const sAttr = s ? ` s="${s}"` : '';
+            if (cell.link)
+                links.push({ ref, url: cell.link, id: `rId${links.length + 1}` });
+            if (cell.value == null || cell.value === '') {
+                cellXml.push(`<c r="${ref}"${sAttr}/>`);
+            }
+            else if (cell.t === 'n') {
+                cellXml.push(`<c r="${ref}"${sAttr}><v>${Number(cell.value)}</v></c>`);
+            }
+            else if (cell.t === 'd') {
+                const d = cell.value instanceof Date ? cell.value : new Date(String(cell.value));
+                cellXml.push(`<c r="${ref}"${sAttr}><v>${toSerialDate(d)}</v></c>`);
+            }
+            else if (cell.t === 'b') {
+                cellXml.push(`<c r="${ref}"${sAttr} t="b"><v>${cell.value ? 1 : 0}</v></c>`);
+            }
+            else {
+                cellXml.push(`<c r="${ref}"${sAttr} t="inlineStr"><is><t xml:space="preserve">${esc(String(cell.value))}</t></is></c>`);
+            }
+        }
+        sheetRows.push(`<row r="${rowNum}">${cellXml.join('')}</row>`);
+    }
+    // <cols> widths (px -> Excel char width ~ px/7).
+    const colsXml = model.widths
+        ? `<cols>${model.widths
+            .map((px, i) => `<col min="${i + 1}" max="${i + 1}" width="${Math.max(4, Math.round((px / 7) * 100) / 100)}" customWidth="1"/>`)
+            .join('')}</cols>`
+        : '';
+    // Freeze panes.
+    const fCols = Math.max(0, Math.floor(model.freezeColumns ?? 0));
+    const fRow = model.freezeHeader ? 1 : 0;
+    let sheetView = '<sheetView workbookViewId="0"/>';
+    if (fRow > 0 || fCols > 0) {
+        const topLeft = `${colName(fCols)}${fRow + 1}`;
+        const activePane = fCols > 0 && fRow > 0 ? 'bottomRight' : fCols > 0 ? 'topRight' : 'bottomLeft';
+        sheetView =
+            `<sheetView workbookViewId="0">` +
+                `<pane${fCols > 0 ? ` xSplit="${fCols}"` : ''}${fRow > 0 ? ` ySplit="${fRow}"` : ''} topLeftCell="${topLeft}" activePane="${activePane}" state="frozen"/>` +
+                `<selection pane="${activePane}" activeCell="${topLeft}" sqref="${topLeft}"/>` +
+                `</sheetView>`;
+    }
+    // Native conditional formatting (data bars / color scales) over each targeted
+    // column's data range. Only when there are data rows to cover.
+    const cfXml = rows.length > 0
+        ? (model.condFormats ?? [])
+            .map((cf, i) => {
+            const col = colName(cf.colIdx);
+            const sqref = `${col}2:${col}${rows.length + 1}`;
+            if (cf.kind === 'dataBar') {
+                const c = argb(cf.color) ?? 'FF638EC6';
+                return (`<conditionalFormatting sqref="${sqref}"><cfRule type="dataBar" priority="${i + 1}">` +
+                    `<dataBar><cfvo type="min"/><cfvo type="max"/><color rgb="${c}"/></dataBar>` +
+                    `</cfRule></conditionalFormatting>`);
+            }
+            const stops = cf.colors.map((c) => argb(c) ?? 'FFFFFFFF');
+            const cfvo = stops.length >= 3
+                ? '<cfvo type="min"/><cfvo type="percentile" val="50"/><cfvo type="max"/>'
+                : '<cfvo type="min"/><cfvo type="max"/>';
+            const colors = stops.map((c) => `<color rgb="${c}"/>`).join('');
+            return (`<conditionalFormatting sqref="${sqref}"><cfRule type="colorScale" priority="${i + 1}">` +
+                `<colorScale>${cfvo}${colors}</colorScale></cfRule></conditionalFormatting>`);
+        })
+            .join('')
+        : '';
+    const hyperlinksXml = links.length
+        ? `<hyperlinks>${links.map((l) => `<hyperlink ref="${l.ref}" r:id="${l.id}"/>`).join('')}</hyperlinks>`
+        : '';
+    // Excel Table (ListObject), optionally with a totals row of SUBTOTAL formulas.
+    let tablePartXml = '';
+    let tablePartsXml = '';
+    let tableRelId = '';
+    if (model.table && header.length > 0) {
+        const t = model.table;
+        // Unique, non-empty column names (Excel requires distinct table columns).
+        const seen = new Set();
+        const colNames = header.map((h, i) => {
+            const bn = (h ?? '').trim() || `Column${i + 1}`;
+            let n = bn;
+            let k = 1;
+            while (seen.has(n.toLowerCase()))
+                n = `${bn}${++k}`;
+            seen.add(n.toLowerCase());
+            return n;
+        });
+        const lastCol = colName(header.length - 1);
+        const dataLastRow = rows.length + 1; // header (row 1) + data
+        const totalRowNum = dataLastRow + 1;
+        const hasTotals = t.totalsRow && rows.length > 0;
+        const labelIdx = t.totalsFns.findIndex((fn) => !fn);
+        if (hasTotals) {
+            const totalCells = header.map((_, c) => {
+                const ref = `${colName(c)}${totalRowNum}`;
+                const fn = t.totalsFns[c];
+                if (fn) {
+                    let sum = 0;
+                    for (const row of rows) {
+                        const cell = row[c];
+                        if (cell?.t === 'n' && typeof cell.value === 'number')
+                            sum += cell.value;
+                    }
+                    const numFmt = rows.find((r) => r[c]?.t === 'n')?.[c]?.numFmt;
+                    const s = styles.styleIndexOf({ t: 'n', value: sum, numFmt, bold: true });
+                    const fnNum = fn === 'average' ? 101 : fn === 'count' ? 103 : 109;
+                    const value = fn === 'count' ? rows.length : sum;
+                    return `<c r="${ref}"${s ? ` s="${s}"` : ''}><f>SUBTOTAL(${fnNum},${t.name}[${esc(colNames[c])}])</f><v>${value}</v></c>`;
+                }
+                if (c === labelIdx) {
+                    const s = styles.styleIndexOf({ t: 's', value: 'Total', bold: true });
+                    return `<c r="${ref}"${s ? ` s="${s}"` : ''} t="inlineStr"><is><t>Total</t></is></c>`;
+                }
+                return `<c r="${ref}"/>`;
+            });
+            sheetRows.push(`<row r="${totalRowNum}">${totalCells.join('')}</row>`);
+        }
+        const tableColsXml = colNames
+            .map((n, i) => {
+            const fn = hasTotals ? t.totalsFns[i] : undefined;
+            const totalsAttr = hasTotals
+                ? fn
+                    ? ` totalsRowFunction="${fn}"`
+                    : i === labelIdx
+                        ? ` totalsRowLabel="Total"`
+                        : ''
+                : '';
+            return `<tableColumn id="${i + 1}" name="${esc(n)}"${totalsAttr}/>`;
+        })
+            .join('');
+        tablePartXml =
+            `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n` +
+                `<table xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" id="1" ` +
+                `name="${esc(t.name)}" displayName="${esc(t.name)}" ref="A1:${lastCol}${hasTotals ? totalRowNum : dataLastRow}"` +
+                `${hasTotals ? ' totalsRowCount="1"' : ' totalsRowShown="0"'}>` +
+                `<autoFilter ref="A1:${lastCol}${dataLastRow}"/>` +
+                `<tableColumns count="${header.length}">${tableColsXml}</tableColumns>` +
+                `<tableStyleInfo name="${esc(t.style ?? 'TableStyleMedium2')}" showFirstColumn="0" showLastColumn="0" showRowStripes="1" showColumnStripes="0"/>` +
+                `</table>`;
+        tableRelId = `rId${links.length + 1}`;
+        tablePartsXml = `<tableParts count="1"><tablePart r:id="${tableRelId}"/></tableParts>`;
+    }
+    const sheetXml = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n` +
+        `<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" ` +
+        `xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">` +
+        `<sheetViews>${sheetView}</sheetViews>` +
+        `<sheetFormatPr defaultRowHeight="15"/>` +
+        colsXml +
+        `<sheetData>${sheetRows.join('')}</sheetData>` +
+        cfXml +
+        hyperlinksXml +
+        tablePartsXml +
+        `</worksheet>`;
+    const parts = {
+        '[Content_Types].xml': tablePartXml
+            ? CONTENT_TYPES.replace('</Types>', '<Override PartName="/xl/tables/table1.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.table+xml"/></Types>')
+            : CONTENT_TYPES,
+        '_rels/.rels': ROOT_RELS,
+        'xl/workbook.xml': workbookXml(model.sheetName),
+        'xl/_rels/workbook.xml.rels': WORKBOOK_RELS,
+        'xl/styles.xml': styles.build(),
+        'xl/worksheets/sheet1.xml': sheetXml,
+    };
+    if (tablePartXml)
+        parts['xl/tables/table1.xml'] = tablePartXml;
+    if (links.length || tableRelId) {
+        const rels = links.map((l) => `<Relationship Id="${l.id}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink" Target="${esc(l.url)}" TargetMode="External"/>`);
+        if (tableRelId) {
+            rels.push(`<Relationship Id="${tableRelId}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/table" Target="../tables/table1.xml"/>`);
+        }
+        parts['xl/worksheets/_rels/sheet1.xml.rels'] =
+            `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n` +
+                `<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">` +
+                rels.join('') +
+                `</Relationships>`;
+    }
+    return parts;
+}
+/** Zip the parts into an xlsx Blob using a provided JSZip constructor. */
+export async function packageXlsx(parts, JSZip) {
+    const zip = new JSZip();
+    for (const [path, content] of Object.entries(parts))
+        zip.file(path, content);
+    return zip.generateAsync({
+        type: 'blob',
+        mimeType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    });
+}

package/dist/export-pdf.d.ts

@@ -0,0 +1,107 @@
+/**
+ * PDF export via our own pdfmake document definition, instead of the vendored
+ * Smart exporter's basic table dump. This gives real control over the page:
+ * size / orientation / margins, a repeated header row on every page, automatic
+ * "Page X of Y" + generated-date footer, per-column alignment and widths, an
+ * optional title / subtitle / logo, and theme colors (header fill + zebra).
+ *
+ * `buildPdfDocDefinition` is a PURE function (no pdfmake, no DOM) returning the
+ * docDefinition object, so it's fully unit-testable; `exportGrid` feeds the
+ * result to `pdfMake.createPdf(def).download(...)`.
+ */
+export type PdfPageSize = 'A4' | 'A3' | 'A5' | 'LETTER' | 'LEGAL';
+export type PdfExportOptions = {
+    pageSize?: PdfPageSize;
+    pageOrientation?: 'portrait' | 'landscape';
+    /** [left, top, right, bottom] in pt. Default [28, 34, 28, 34]. */
+    margins?: [number, number, number, number];
+    /** Document title rendered above the table. */
+    title?: string;
+    /** Smaller line under the title. */
+    subtitle?: string;
+    /** Logo as a data URL, rendered top-left above the title. */
+    logo?: string;
+    /** Logo width in pt (height auto). Default 90. */
+    logoWidth?: number;
+    /** Base font size in pt. Default 8. */
+    fontSize?: number;
+    /** Header row fill color. Default '#334155'. */
+    headerColor?: string;
+    /** Header row text color. Default '#ffffff'. */
+    headerTextColor?: string;
+    /** Zebra-stripe alternate rows. Default true. */
+    zebra?: boolean;
+    /** Zebra fill color. Default '#f1f5f9'. */
+    zebraColor?: string;
+    /** Repeat the header row on every page. Default true. */
+    repeatHeader?: boolean;
+    /** Show the "Page X of Y" + date footer. Default true. */
+    showPageNumbers?: boolean;
+    /**
+     * Column widths: '*' (fill, default), 'auto', or an explicit array of
+     * pt numbers / 'auto' / '*' per column.
+     */
+    columnWidths?: '*' | 'auto' | Array<number | 'auto' | '*'>;
+    /** Switch to landscape automatically when column count exceeds this (and no
+     *  explicit orientation was set). Default 8. */
+    autoLandscapeThreshold?: number;
+    /** Group header row fill color. Default '#e2e8f0'. */
+    groupColor?: string;
+    /** Group header row text color. Default '#0f172a'. */
+    groupTextColor?: string;
+    /** Subtotal row fill color. Default '#f8fafc'. */
+    subtotalColor?: string;
+};
+/**
+ * A body row for the PDF table. `data` is a normal row; `group` is a bold,
+ * full-width group header (from grid grouping); `subtotal` is a per-group
+ * summary row (bold, aligned like the data).
+ */
+export type PdfBodyRow = {
+    kind: 'data';
+    cells: ReadonlyArray<string>;
+} | {
+    kind: 'group';
+    label: string;
+    level?: number;
+} | {
+    kind: 'subtotal';
+    cells: ReadonlyArray<string>;
+};
+export type PdfDocDefinition = {
+    pageSize: PdfPageSize;
+    pageOrientation: 'portrait' | 'landscape';
+    pageMargins: [number, number, number, number];
+    defaultStyle: {
+        fontSize: number;
+    };
+    content: unknown[];
+    footer?: (currentPage: number, pageCount: number) => unknown;
+};
+/**
+ * Build a pdfmake docDefinition from resolved columns + formatted string rows.
+ * `now` is injected for a deterministic footer date in tests.
+ */
+export declare function buildPdfDocDefinition(params: {
+    columns: ReadonlyArray<{
+        header: string;
+        align?: 'left' | 'center' | 'right';
+    }>;
+    /** Data rows as pre-formatted strings, in column order (no header row).
+     *  Convenience for the flat (ungrouped) case. */
+    rows?: ReadonlyArray<ReadonlyArray<string>>;
+    /** Structured body with group headers + subtotals. Takes precedence over
+     *  `rows` when provided (used for grouped exports). */
+    body?: ReadonlyArray<PdfBodyRow>;
+    /** Per-data-cell visual override (conditional formatting). `dataRowIdx` is
+     *  the 0-based index among data rows. */
+    dataCellStyle?: (dataRowIdx: number, colIdx: number) => {
+        fill?: string;
+        color?: string;
+        bold?: boolean;
+    } | undefined;
+    /** Per-data-cell hyperlink URL. */
+    dataCellLink?: (dataRowIdx: number, colIdx: number) => string | undefined;
+    opts?: PdfExportOptions;
+    now?: Date;
+}): PdfDocDefinition;

package/dist/export-pdf.js

@@ -0,0 +1,144 @@
+/**
+ * PDF export via our own pdfmake document definition, instead of the vendored
+ * Smart exporter's basic table dump. This gives real control over the page:
+ * size / orientation / margins, a repeated header row on every page, automatic
+ * "Page X of Y" + generated-date footer, per-column alignment and widths, an
+ * optional title / subtitle / logo, and theme colors (header fill + zebra).
+ *
+ * `buildPdfDocDefinition` is a PURE function (no pdfmake, no DOM) returning the
+ * docDefinition object, so it's fully unit-testable; `exportGrid` feeds the
+ * result to `pdfMake.createPdf(def).download(...)`.
+ */
+/**
+ * Build a pdfmake docDefinition from resolved columns + formatted string rows.
+ * `now` is injected for a deterministic footer date in tests.
+ */
+export function buildPdfDocDefinition(params) {
+    const { columns } = params;
+    const o = params.opts ?? {};
+    const now = params.now ?? new Date(0);
+    const fontSize = o.fontSize ?? 8;
+    const headerColor = o.headerColor ?? '#334155';
+    const headerTextColor = o.headerTextColor ?? '#ffffff';
+    const zebra = o.zebra ?? true;
+    const zebraColor = o.zebraColor ?? '#f1f5f9';
+    const groupColor = o.groupColor ?? '#e2e8f0';
+    const groupTextColor = o.groupTextColor ?? '#0f172a';
+    const subtotalColor = o.subtotalColor ?? '#f8fafc';
+    const repeatHeader = o.repeatHeader ?? true;
+    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' : '*'));
+    // Header row.
+    const headerRow = columns.map((c) => ({
+        text: c.header,
+        bold: true,
+        alignment: c.align ?? 'left',
+        color: headerTextColor,
+        fillColor: headerColor,
+    }));
+    // Normalize to a structured body: `body` wins, else wrap flat `rows`.
+    const model = params.body ?? (params.rows ?? []).map((cells) => ({ kind: 'data', cells }));
+    // Track which body-row indices are plain data rows, so zebra striping only
+    // hits those (group / subtotal rows carry their own fill).
+    const dataCellStyle = params.dataCellStyle;
+    const dataCellLink = params.dataCellLink;
+    let dataOrdinal = 0;
+    const dataRowIdx = new Set();
+    const bodyCells = [headerRow];
+    model.forEach((row, i) => {
+        const bi = i + 1; // +1 for the header row
+        if (row.kind === 'group') {
+            const first = {
+                text: row.label,
+                bold: true,
+                color: groupTextColor,
+                fillColor: groupColor,
+                colSpan: columns.length,
+                margin: [(row.level ?? 0) * 12, 2, 0, 2],
+            };
+            const rest = Array.from({ length: Math.max(0, columns.length - 1) }, () => ({ text: '' }));
+            bodyCells.push([first, ...rest]);
+        }
+        else if (row.kind === 'subtotal') {
+            bodyCells.push(columns.map((c, ci) => ({
+                text: row.cells[ci] ?? '',
+                bold: true,
+                alignment: c.align ?? 'left',
+                fillColor: subtotalColor,
+            })));
+        }
+        else {
+            dataRowIdx.add(bi);
+            const ord = dataOrdinal++;
+            bodyCells.push(columns.map((c, ci) => {
+                const cell = { text: row.cells[ci] ?? '', alignment: c.align ?? 'left' };
+                const s = dataCellStyle?.(ord, ci);
+                if (s) {
+                    if (s.fill)
+                        cell.fillColor = s.fill;
+                    if (s.color)
+                        cell.color = s.color;
+                    if (s.bold)
+                        cell.bold = true;
+                }
+                const href = dataCellLink?.(ord, ci);
+                if (href) {
+                    cell.link = href;
+                    cell.decoration = 'underline';
+                    if (!s?.color)
+                        cell.color = '#2563eb';
+                }
+                return cell;
+            }));
+        }
+    });
+    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: () => '#e2e8f0',
+            vLineColor: () => '#e2e8f0',
+            paddingTop: () => 3,
+            paddingBottom: () => 3,
+            paddingLeft: () => 5,
+            paddingRight: () => 5,
+        },
+    };
+    const content = [];
+    if (o.logo)
+        content.push({ image: o.logo, width: o.logoWidth ?? 90, margin: [0, 0, 0, 8] });
+    if (o.title)
+        content.push({ text: o.title, fontSize: fontSize + 8, bold: true, margin: [0, 0, 0, 2] });
+    if (o.subtitle)
+        content.push({ text: o.subtitle, fontSize: fontSize + 1, color: '#64748b', margin: [0, 0, 0, 8] });
+    content.push(table);
+    const def = {
+        pageSize: o.pageSize ?? 'A4',
+        pageOrientation: orientation,
+        pageMargins: o.margins ?? [28, 34, 28, 34],
+        defaultStyle: { fontSize },
+        content,
+    };
+    if (o.showPageNumbers ?? true) {
+        const dateStr = now.toISOString().slice(0, 10);
+        def.footer = (currentPage, pageCount) => ({
+            margin: [28, 6, 28, 0],
+            columns: [
+                { text: dateStr, alignment: 'left', fontSize: 7, color: '#94a3b8' },
+                { text: `Page ${currentPage} of ${pageCount}`, alignment: 'right', fontSize: 7, color: '#94a3b8' },
+            ],
+        });
+    }
+    return def;
+}