@opencorestack/opengridx 3.1.0 → 3.2.0

package/docs/API_REFERENCE.md

@@ -1446,6 +1446,15 @@ interface PdfExportOptions {
     headerTextColor?: string;
     fontSize?: number;
     font?: { name: string; data: string; boldData?: string }; // v3.0+
+    onProgress?: (p: PdfExportProgress) => void; // v3.2+
+    signal?: AbortSignal; // v3.2+
+    maxRows?: number; // v3.2+, default 20000
+}
+
+interface PdfExportProgress {
+    phase: 'prepare' | 'render' | 'save';
+    done: number;
+    total: number;
 }
 ```
 
@@ -1466,3 +1475,8 @@ interface PdfExportOptions {
 | `headerTextColor` | `string` | `'#ffffff'` | Column header cell text color (`#rrggbb` / `#rgb`) |
 | `fontSize` | `number` | `9` | Body cell font size in points |
 | `font` | `{ name, data, boldData? }` | — | Base64 TrueType font for text outside Latin-1 (₹, CJK, Cyrillic…). Without it, such characters are replaced with `?` (v3.0+) |
+| `onProgress` | `(p: PdfExportProgress) => void` | — | Called per slice with `{ phase, done, total }`; phases `prepare` → `render` → `save`, `done` monotonic per phase and ending at `total` (v3.2+) |
+| `signal` | `AbortSignal` | — | Abort → the promise rejects with `DOMException` `'AbortError'`, no file saved. The final jsPDF save step cannot be interrupted (v3.2+) |
+| `maxRows` | `number` | `20000` | Above this many table rows a dev-mode `console.warn` recommends `exportToCsv` / `exportToExcelAdvanced`. Never throws; `Infinity` silences it (v3.2+) |
+
+The export yields to the event loop between ~30 ms slices while formatting and drawing (v3.2+), so the page stays responsive; only jsPDF's final save is one synchronous step. See [PDF Export › Large exports](./features/pdf-export.md#large-exports).

package/docs/features/pdf-export.md

@@ -16,7 +16,7 @@ npm install jspdf jspdf-autotable
 > await exportToPdf(rows, columns, { fileName: 'invoices', font: { name: 'NotoSans', data: notoSansBase64 } });
 > ```
 
-> **Large datasets:** PDF generation runs on the main thread, and time and file size grow with every row: 50,000 grouped rows took 10–16 s (the page is unresponsive meanwhile) and produced a file of about 120 MB. For more than a few thousand rows, export CSV (`exportToCsv`) or `.xlsx` (`exportToExcelAdvanced`) instead, or export a filtered subset.
+> **Large datasets:** time and file size grow with every row (50,000 grouped rows: several seconds and a file of 75–120 MB). Since v3.2 the export is sliced so the page stays responsive, and it reports progress and can be cancelled, but for more than a few thousand rows CSV (`exportToCsv`) or `.xlsx` (`exportToExcelAdvanced`) is still the better format. See [Large exports](#large-exports).
 
 ## Basic Usage
 
@@ -97,6 +97,42 @@ await exportToPdf(
 | `headerTextColor` | `string` | `'#ffffff'` | Column header cell text color (`#rrggbb` or `#rgb`). Invalid values fall back to the default |
 | `fontSize` | `number` | `9` | Body cell font size in points |
 | `font` | `{ name: string; data: string; boldData?: string }` | — | A TrueType font (base64 `.ttf`) for text outside Latin-1 (v3.0+). See [Non-Latin text](#non-latin-text-and-unicode-fonts) |
+| `onProgress` | `(p: PdfExportProgress) => void` | — | Progress: `{ phase: 'prepare' \| 'render' \| 'save', done, total }` (v3.2+). See [Large exports](#large-exports) |
+| `signal` | `AbortSignal` | — | Cancels the export: the promise rejects with a `DOMException` named `'AbortError'` and nothing is saved (v3.2+) |
+| `maxRows` | `number` | `20000` | Table-row count above which a development-mode warning recommends CSV / `.xlsx`. The export still runs; `Infinity` silences it (v3.2+) |
+
+## Large exports
+
+`exportToPdf` returns a `Promise<void>`. Since v3.2 it works in slices of about 30 ms and yields to the event loop between them, both while formatting the rows and while drawing the table, so the page keeps painting and handling input. Pass `onProgress` for a progress bar and `signal` for a Cancel button:
+
+```tsx
+const controllerRef = useRef<AbortController | null>(null);
+const [progress, setProgress] = useState<PdfExportProgress | null>(null);
+
+const onExport = async () => {
+    const controller = new AbortController();
+    controllerRef.current = controller;
+    try {
+        await exportToPdf(rows, columns, {
+            groupedRows: apiRef.current.getGroupedExportRows() ?? undefined,
+            signal: controller.signal,
+            onProgress: setProgress,
+        });
+    } catch (error) {
+        if (!(error instanceof DOMException && error.name === 'AbortError')) throw error;
+    } finally {
+        setProgress(null);
+    }
+};
+// <button onClick={() => controllerRef.current?.abort()}>Cancel</button>
+```
+
+- **Phases.** `prepare` formats the rows (`total` = rows, or grouped entries with `groupedRows`); `render` draws the table (`total` = table body rows); `save` is reported as `0/1` before the file is written and `1/1` after. Within a phase `done` never decreases and ends at `total`.
+- **Cancel.** When `signal` aborts, the promise rejects with `DOMException` `'AbortError'` at the next slice boundary and no file is saved. An already aborted signal rejects before jsPDF is loaded.
+- **The last step still blocks.** jsPDF builds the whole file in one synchronous call when saving; that step cannot be split or cancelled. It is short next to the rest (about 0.4–0.6 s for 50,000 grouped rows in Chromium), but it grows with the file.
+- **Same output.** The table is drawn as a series of `jspdf-autotable` calls that continue on the same page, with fixed column widths, the header repeated on every page and the footer only at the end. Pages, row positions, shading and page breaks are the same as a single call; the file is marginally larger (repeated style operators).
+- **`maxRows` (default 20,000).** Above it a console warning in development recommends `exportToCsv` or `exportToExcelAdvanced`; nothing is thrown, so existing exports keep working. 20,000 rows is roughly where a PDF passes 30 MB and a few seconds to build, and where viewers start to struggle to open it. Pass a larger value (or `Infinity`) to silence the warning when a large PDF is intended.
+- **Total time.** Slicing makes an export slightly slower overall, not faster. Formatting is a small part of the work; drawing the table dominates.
 
 ## Totals and filter summary
 
@@ -148,7 +184,7 @@ Pass the `font` option with a Unicode TrueType font. See [Non-Latin text](#non-l
 
 **Export is slow or the file is huge**
 
-PDF is not suited to tens of thousands of rows (see Installation above). Use CSV or `.xlsx` for large exports.
+PDF is not suited to tens of thousands of rows. Show progress and a Cancel button (see [Large exports](#large-exports)), or use CSV or `.xlsx` for large exports.
 
 **Error: "exportToPdf requires 'jspdf' and 'jspdf-autotable'"**
 

package/lib/index.ts

@@ -136,4 +136,5 @@ export type {
     GridRowMeta,
     GridLocaleText,
     PdfExportOptions,
+    PdfExportProgress,
 } from './types';

package/lib/types/index.ts

@@ -527,6 +527,37 @@ export interface PdfExportOptions<R extends GridValidRowModel = GridRowModel> {
    * Has no effect when the grid has no active `rowGroupingModel`, or when `selectedRows` is non-empty.
    */
   groupedRows?: GridGroupedExportRow[];
+
+  /**
+   * Called as the export advances: `prepare` (formatting rows; `total` = source rows or grouped
+   * entries), `render` (drawing table rows; `total` = table body rows) and `save` (`0/1` before the
+   * file is written, `1/1` after). `done` never decreases within a phase and ends at `total`.
+   * @since v3.2
+   */
+  onProgress?: (progress: PdfExportProgress) => void;
+
+  /**
+   * Cancels the export. When aborted, the returned promise rejects with a `DOMException` named
+   * `'AbortError'` and no file is saved. Checked between slices of work, so cancellation takes
+   * effect within one slice; the final save step cannot be interrupted once started.
+   * @since v3.2
+   */
+  signal?: AbortSignal;
+
+  /**
+   * Table-row count above which a development-mode warning recommends `exportToCsv` or
+   * `exportToExcelAdvanced`. The export still runs (nothing is thrown). Pass `Infinity` to silence it.
+   * Default: 20000
+   * @since v3.2
+   */
+  maxRows?: number;
+}
+
+/** Progress reported by `PdfExportOptions.onProgress`. @since v3.2 */
+export interface PdfExportProgress {
+  phase: 'prepare' | 'render' | 'save';
+  done: number;
+  total: number;
 }
 
 /**

package/lib/utils/export/exportToPdf.ts

@@ -57,8 +57,49 @@ interface AutoTableOptions {
     showFoot?: string;
     showHead?: string;
     margin?: { top: number; left: number; right: number; bottom: number };
+    willDrawPage?: (data: AutoTableHookData) => void;
 }
 
+/** The part of jspdf-autotable's hook data used here; `settings` and `cursor` are the table's live objects. */
+interface AutoTableHookData {
+    settings: { showHead: string };
+    cursor: { y: number } | null;
+}
+
+type AutoTableFn = (doc: JsPDFDoc, opts: AutoTableOptions) => void;
+
+/** How the work is sliced. Output does not depend on these values; tests shrink them. */
+export interface PdfExportTuning {
+    /** Longest stretch of synchronous work before yielding to the event loop, in ms. */
+    sliceMs: number;
+    /** Table rows drawn by the first autoTable call; later calls adapt to `sliceMs`. Rounded to even. */
+    renderChunkRows: number;
+    /** Resize later chunks to fit `sliceMs` (default behaviour); false keeps every chunk at `renderChunkRows`. */
+    adaptive: boolean;
+}
+
+const DEFAULT_TUNING: PdfExportTuning = { sliceMs: 30, renderChunkRows: 40, adaptive: true };
+
+/** Default `maxRows`: above this a PDF is tens of MB and takes seconds to build and open. */
+export const PDF_MAX_ROWS_DEFAULT = 20_000;
+
+/**
+ * Let the browser paint and run other tasks. A macrotask on purpose: `scheduler.yield()` resumes
+ * ahead of queued tasks, which starves timers and React's scheduler (a progress bar would not
+ * update until the export finished).
+ */
+function yieldToEventLoop(): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, 0));
+}
+
+function abortError(): DOMException {
+    return new DOMException('PDF export was aborted', 'AbortError');
+}
+
+const now = (): number => (typeof performance !== 'undefined' ? performance.now() : Date.now());
+
+const evenAtLeast2 = (n: number): number => Math.max(2, Math.floor(n / 2) * 2);
+
 type Rgb = [number, number, number];
 
 const DEFAULT_HEADER_BACKGROUND: Rgb = [79, 70, 229];
@@ -144,21 +185,37 @@ const LINE_HEIGHT_MM_PER_PT = 1.15 * 0.3528;
 
 export function exportToPdf<R extends GridValidRowModel = GridRowModel>(rows: R[], columns: GridColDef<R>[], options?: PdfExportOptions<R>): Promise<void>;
 export function exportToPdf<R extends GridValidRowModel = GridRowModel>(rows: R[], columns: GridColDef[], options?: PdfExportOptions<R>): Promise<void>;
-export async function exportToPdf<R extends GridRowModel>(
+export function exportToPdf<R extends GridRowModel>(
     rows: R[],
     columns: GridColDef<R>[],
     options: PdfExportOptions<R> = {}
 ): Promise<void> {
+    return runPdfExport(rows, columns, options, DEFAULT_TUNING);
+}
+
+/** `exportToPdf` with explicit slicing. Internal: not part of the public API. */
+export async function runPdfExport<R extends GridRowModel>(
+    rows: R[],
+    columns: GridColDef<R>[],
+    options: PdfExportOptions<R>,
+    tuning: PdfExportTuning,
+): Promise<void> {
+    const { signal, onProgress } = options;
+    const checkAbort = (): void => {
+        if (signal?.aborted) throw abortError();
+    };
+    checkAbort();
+
     // Lazy-load peer deps — provides a clear error if not installed
     let JsPDF: new (opts: Record<string, unknown>) => JsPDFDoc;
-    let autoTable: (doc: JsPDFDoc, opts: AutoTableOptions) => void;
+    let autoTable: AutoTableFn;
     try {
         const [jspdfMod, autoTableMod] = await Promise.all([
             import('jspdf'),
             import('jspdf-autotable'),
         ]);
         JsPDF = jspdfMod.default as unknown as new (opts: Record<string, unknown>) => JsPDFDoc;
-        autoTable = autoTableMod.default as unknown as (doc: JsPDFDoc, opts: AutoTableOptions) => void;
+        autoTable = autoTableMod.default as unknown as AutoTableFn;
     } catch {
         throw new Error(
             "exportToPdf requires 'jspdf' and 'jspdf-autotable'. Run: npm install jspdf jspdf-autotable"
@@ -181,7 +238,21 @@ export async function exportToPdf<R extends GridRowModel>(
         fontSize = 9,
         groupedRows,
         font,
+        maxRows = PDF_MAX_ROWS_DEFAULT,
     } = options;
+    checkAbort();
+
+    // Time-sliced work: `maybeYield` yields once the current slice has run for `sliceMs`.
+    let sliceStart = now();
+    const maybeYield = async (): Promise<void> => {
+        if (now() - sliceStart < tuning.sliceMs) return;
+        await yieldToEventLoop();
+        checkAbort();
+        sliceStart = now();
+    };
+    const report = (phase: 'prepare' | 'render' | 'save', done: number, total: number): void => {
+        onProgress?.({ phase, done, total });
+    };
 
     const doc = new JsPDF({ orientation, unit: 'mm', format: 'a4' });
     const pageWidth = doc.internal.pageSize.getWidth();
@@ -274,30 +345,48 @@ export async function exportToPdf<R extends GridRowModel>(
     const aggregateTexts = (values: Record<string, unknown>): string[] =>
         exportColumns.map(col => formatExportAggregate(col, aggMod[col.field], values[col.field], values));
 
-    let body: string[][];
+    const body: string[][] = [];
     let foot: string[][] | undefined;
+    const pushRow = (cells: string[]): void => {
+        body.push(cells.map(pdfText));
+    };
 
     if (useGrouped) {
         // Grouped export: flatten the ordered list into body rows with indentation
-        body = [];
-        groupedRows.forEach((entry: GridGroupedExportRow) => {
+        const total = groupedRows.length;
+        report('prepare', 0, total);
+        for (let index = 0; index < total; index++) {
+            const entry: GridGroupedExportRow = groupedRows[index];
             const indent = '  '.repeat(entry.depth * 2);
             if (entry.type === 'group-header') {
                 const label = `${indent}${groupHeaderLabel(entry, columns)}`;
-                body.push(exportColumns.map((_, i) => i === 0 ? label : ''));
+                pushRow(exportColumns.map((_, i) => i === 0 ? label : ''));
             } else if (entry.type === 'leaf' && entry.row) {
                 const row = entry.row as R;
-                body.push(exportColumns.map((col, i) => (i === 0 ? indent : '') + resolveValue(row, col)));
+                pushRow(exportColumns.map((col, i) => (i === 0 ? indent : '') + resolveValue(row, col)));
             } else if (entry.type === 'group-subtotal' && entry.aggregatedValues) {
                 const texts = aggregateTexts(entry.aggregatedValues);
-                body.push(texts.map((text, i) => (i === 0 ? `${indent}${summaryLabelText('Subtotal', text)}` : text)));
+                pushRow(texts.map((text, i) => (i === 0 ? `${indent}${summaryLabelText('Subtotal', text)}` : text)));
             } else if (entry.type === 'grand-total' && entry.aggregatedValues) {
                 const texts = aggregateTexts(entry.aggregatedValues);
-                foot = [texts.map((text, i) => (i === 0 ? summaryLabelText('Grand Total', text) : text))];
+                foot = [texts.map((text, i) => (i === 0 ? summaryLabelText('Grand Total', text) : text)).map(pdfText)];
             }
-        });
+            if ((index & 63) === 63) {
+                report('prepare', index + 1, total);
+                await maybeYield();
+            }
+        }
+        report('prepare', total, total);
     } else {
-        body = rowsToExport.map(row => exportColumns.map(col => resolveValue(row, col)));
+        const total = rowsToExport.length;
+        report('prepare', 0, total);
+        for (let index = 0; index < total; index++) {
+            pushRow(exportColumns.map(col => resolveValue(rowsToExport[index], col)));
+            if ((index & 63) === 63) {
+                report('prepare', index + 1, total);
+                await maybeYield();
+            }
+        }
 
         const totals = aggregationModel
             ? aggregationForExport(rowsToExport, hasSelection(selectedRows), columns, aggregationResult, aggregationModel)
@@ -305,12 +394,19 @@ export async function exportToPdf<R extends GridRowModel>(
         if (totals && aggregationModel) {
             const hasAgg = exportColumns.some(c => aggregationModel[c.field]);
             const texts = aggregateTexts(totals);
-            foot = [texts.map((text, i) => (i === 0 && hasAgg ? summaryLabelText('TOTAL', text) : text))];
+            foot = [texts.map((text, i) => (i === 0 && hasAgg ? summaryLabelText('TOTAL', text) : text)).map(pdfText)];
         }
+        report('prepare', total, total);
     }
+    checkAbort();
 
-    body = body.map(cells => cells.map(pdfText));
-    if (foot) foot = foot.map(cells => cells.map(pdfText));
+    if (body.length > maxRows && process.env.NODE_ENV !== 'production') {
+        console.warn(
+            `[exportToPdf] Exporting ${body.length} table rows (maxRows: ${maxRows}). PDFs this large are slow to build ` +
+            'and open and can reach tens of MB. Prefer exportToCsv or exportToExcelAdvanced for full-dataset exports, ' +
+            'or pass a larger `maxRows` to silence this warning.'
+        );
+    }
 
     if (replacedCharacters) {
         console.warn(
@@ -325,11 +421,8 @@ export async function exportToPdf<R extends GridRowModel>(
     const [hr, hg, hb] = hexToRgb(headerBackgroundColor, DEFAULT_HEADER_BACKGROUND);
     const [tr, tg, tb] = hexToRgb(headerTextColor, DEFAULT_HEADER_TEXT);
 
-    autoTable(doc, {
+    const baseTableOptions: Omit<AutoTableOptions, 'body' | 'startY'> = {
         head,
-        body,
-        ...(foot ? { foot } : {}),
-        startY,
         styles: { fontSize, cellPadding: 3, font: fontName, overflow: 'linebreak' },
         headStyles: {
             fillColor: [hr, hg, hb],
@@ -343,10 +436,59 @@ export async function exportToPdf<R extends GridRowModel>(
             ? { footStyles: { fillColor: [241, 245, 249], fontStyle: 'bold', textColor: [0, 0, 0] } }
             : {}),
         columnStyles,
-        showFoot: foot ? 'lastPage' : 'never',
         showHead: 'everyPage',
         margin: { top: MARGIN, left: MARGIN, right: MARGIN, bottom: MARGIN + 6 },
-    });
+    };
+
+    // The body is drawn as a series of autoTable calls, each continuing where the previous one
+    // ended, so the drawing phase yields too. Column widths are fixed (columnStyles), chunks hold
+    // an even number of rows (alternate shading keeps its parity), only the last chunk carries the
+    // footer, and a continuation chunk skips the header on the page it starts on but repeats it on
+    // every page it adds: the same pages a single call would produce.
+    const totalRows = body.length;
+    report('render', 0, totalRows);
+    let drawn = 0;
+    let chunkRows = evenAtLeast2(tuning.renderChunkRows);
+    do {
+        const chunk = body.slice(drawn, drawn + chunkRows);
+        const isFirst = drawn === 0;
+        const isLast = drawn + chunk.length >= totalRows;
+        const continueY = isFirst ? startY : doc.lastAutoTable.finalY;
+        let firstPageOfChunk = true;
+        const started = now();
+        autoTable(doc, {
+            ...baseTableOptions,
+            body: chunk,
+            ...(isLast && foot ? { foot } : {}),
+            // A continuation starts at the top margin so autoTable's "does the table fit below
+            // startY" check never adds a page; the hook then moves the cursor to where the previous
+            // chunk ended, and each row breaks the page exactly as it would in a single table.
+            startY: isFirst ? startY : MARGIN,
+            showFoot: isLast && foot ? 'lastPage' : 'never',
+            ...(isFirst ? {} : {
+                willDrawPage: (data: AutoTableHookData) => {
+                    if (firstPageOfChunk) {
+                        firstPageOfChunk = false;
+                        // Same page as the previous chunk: its header is already drawn.
+                        data.settings.showHead = 'never';
+                        if (data.cursor) data.cursor.y = continueY;
+                    } else {
+                        data.settings.showHead = 'everyPage';
+                    }
+                },
+            }),
+        });
+        drawn += chunk.length;
+        report('render', drawn, totalRows);
+        const elapsed = now() - started;
+        // Aim each call at one slice; grow at most 4x at a time.
+        if (tuning.adaptive) chunkRows = evenAtLeast2(elapsed > 0 ? Math.min(chunkRows * 4, chunkRows * (tuning.sliceMs / elapsed)) : chunkRows * 4);
+        if (!isLast) {
+            await yieldToEventLoop();
+            checkAbort();
+            sliceStart = now();
+        }
+    } while (drawn < totalRows);
 
     // Two-pass page numbering — stamp all pages after the table is fully rendered
     // so each stamp reads the correct final total (not the running count during draw)
@@ -361,7 +503,11 @@ export async function exportToPdf<R extends GridRowModel>(
             pageHeight - 8,
             { align: 'right' }
         );
+        await maybeYield();
     }
 
+    checkAbort();
+    report('save', 0, 1);
     doc.save(`${fileName}.pdf`);
+    report('save', 1, 1);
 }

package/lib/utils/export/index.ts

@@ -690,4 +690,4 @@ function downloadFile(content: string, fileName: string, mimeType: string): void
 }
 
 export { exportToPdf } from './exportToPdf';
-export type { PdfExportOptions } from '../../types';
+export type { PdfExportOptions, PdfExportProgress } from '../../types';

package/llms.txt

@@ -1,6 +1,6 @@
 # OpenGridX — AI Agent Context
 # Package: @opencorestack/opengridx
-# Version: 3.1.0
+# Version: 3.2.0
 # Docs: https://opencorestack.github.io/OpenGridX/
 # This file is machine-readable. AI developers: start here.
 
@@ -497,10 +497,13 @@ await exportToExcelAdvanced(rows, columns, {
 });
 exportToJson(rows, columns, { fileName: 'export.json' });
 await exportToPdf(rows, columns, { fileName: 'export', title: 'My Report' });
+// 3.2.0+: large PDFs — progress, cancel, size warning (never throws)
+await exportToPdf(rows, columns, { onProgress: ({ phase, done, total }) => {}, signal: controller.signal, maxRows: 20000 });
 await printGrid(rows, columns, 'My Report Title');
 ```
 
 - Every export accepts `selectedRows`, `getRowId` (pass the grid's getRowId so ids match), `aggregationResult` + `aggregationModel` (totals row) and `groupedRows` from `apiRef.current.getGroupedExportRows()`.
+- exportToPdf (3.2.0+) works in ~30 ms slices and yields between them (prepare and render phases), so the page stays responsive; only jsPDF's final save is one synchronous step. `onProgress({ phase: 'prepare'|'render'|'save', done, total })`; `signal` abort rejects with DOMException 'AbortError' and saves nothing; above `maxRows` (default 20000) a dev console.warn recommends exportToCsv / exportToExcelAdvanced. Output (pages, positions) is the same as before.
 - CSV and exportToExcel neutralise formulas: text starting with = + - @ tab or CR gets a leading `'` (`escapeFormulas: false` opts out).
 - exportToExcel writes HTML: a `.xlsx` fileName is saved as `.xls` with a console warning.
 - Columns with `exportable: false` are left out everywhere; `valueGetter` and `valueFormatter` are applied.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencorestack/opengridx",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "OpenGridX: High-performance React data infrastructure. Unlock advanced Row Grouping, Excel Export, and Column Pinning without the usual \"Pro\" gatekeeping. Built for speed, scale, and complete architectural freedom. Fully open, virtualization-ready, and feature-complete.",
   "type": "module",
   "main": "./dist/opengridx.umd.js",