@opencorestack/opengridx 1.2.3 → 1.3.0

package/lib/components/DataGrid/DataGrid.tsx

@@ -27,7 +27,7 @@ import { GridListView } from './GridListView';
 import { GridPinnedRows } from './GridPinnedRows';
 import { GridVirtualRows } from './GridVirtualRows';
 import { GridStandaloneColumnPanel } from './GridStandaloneColumnPanel';
-import type { DataGridProps, GridRowModel, GridRowId, GridSortDirection, GridColDef, GridRowParams, GridCellParams, GridDataSource, GridAggregationResult, GridFilterModel, GridTreeNode, GridSortItem, GridRowMeta } from '../../types';
+import type { DataGridProps, GridRowModel, GridRowId, GridSortDirection, GridColDef, GridRowParams, GridCellParams, GridDataSource, GridAggregationResult, GridFilterModel, GridTreeNode, GridSortItem, GridRowMeta, GridGroupedExportRow } from '../../types';
 
 const EMPTY_ROW_META_MAP: Map<GridRowId, GridRowMeta> = new Map();
 
@@ -499,7 +499,53 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
     useEffect(() => {
         gridData.apiRef.current.getAggregationResult = () => hasAggregation ? aggregationResult : null;
         gridData.apiRef.current.getAggregationModel = () => hasAggregation ? aggregationModel : null;
-    }, [aggregationResult, aggregationModel, hasAggregation, gridData.apiRef]);
+        gridData.apiRef.current.getGroupedExportRows = (): GridGroupedExportRow[] | null => {
+            if (!isRowGrouping) return null;
+            const { treeNodes, groupingRows } = rowGroupingHandlers;
+            const rowLookup = new Map<GridRowId, GridRowModel>();
+            sortedUnpinnedRows.forEach(r => rowLookup.set((r as GridRowModel).id as GridRowId, r as GridRowModel));
+
+            const result: GridGroupedExportRow[] = [];
+
+            const traverse = (ids: GridRowId[]) => {
+                ids.forEach(id => {
+                    const node = treeNodes.get(id);
+                    if (!node) return;
+                    const isGroup = Boolean(node.children && node.children.length > 0);
+                    if (isGroup) {
+                        result.push({
+                            type: 'group-header',
+                            depth: node.depth,
+                            groupField: node.groupingField,
+                            groupValue: node.groupingValue,
+                        });
+                        traverse(node.children!);
+                        if (hasAggregation && node.aggregatedValues) {
+                            result.push({
+                                type: 'group-subtotal',
+                                depth: node.depth,
+                                groupField: node.groupingField,
+                                groupValue: node.groupingValue,
+                                aggregatedValues: node.aggregatedValues,
+                            });
+                        }
+                    } else {
+                        const row = rowLookup.get(id) ?? groupingRows.get(id);
+                        if (row) {
+                            result.push({ type: 'leaf', depth: node.depth, row });
+                        }
+                    }
+                });
+            };
+
+            traverse(Array.from(treeNodes.keys()).filter(id => treeNodes.get(id)?.parentId === null));
+
+            if (hasAggregation && aggregationResult) {
+                result.push({ type: 'grand-total', depth: 0, aggregatedValues: aggregationResult });
+            }
+            return result;
+        };
+    }, [aggregationResult, aggregationModel, hasAggregation, gridData.apiRef, isRowGrouping, rowGroupingHandlers, sortedUnpinnedRows]);
 
     const layout = useLayout({
         rowHeight,

package/lib/hooks/core/useDataGrid.ts

@@ -300,6 +300,7 @@ export function useDataGrid<R extends GridRowModel = GridRowModel>(params: UseDa
     getAllRows: () => Array.from(stateRef.current.rows.idRowsLookup.values()),
     getVisibleRows: () => Array.from(stateRef.current.rows.idRowsLookup.values()),
     getAllFilteredRows: () => Array.from(stateRef.current.rows.idRowsLookup.values()),
+    getGroupedExportRows: () => null,
     getAggregationResult: () => null,
     getAggregationModel: () => null,
     getColumn: (field: string) => stateRef.current.columns.lookup.get(field) || null,

package/lib/types/index.ts

@@ -376,6 +376,33 @@ export interface PdfExportOptions {
    * Base font size in points for table body. Default: 9
    */
   fontSize?: number;
+
+  /**
+   * Pre-built grouped export rows from `apiRef.current.getGroupedExportRows()`.
+   * When provided, the PDF table reflects the grouping structure (group headers,
+   * leaf rows, per-group subtotals, grand total) instead of a flat row list.
+   * Has no effect when the grid has no active `rowGroupingModel`.
+   */
+  groupedRows?: GridGroupedExportRow[];
+}
+
+/**
+ * A single entry in the ordered list returned by `GridApi.getGroupedExportRows()`.
+ * Traverse in array order to reproduce the on-screen grouping structure.
+ */
+export interface GridGroupedExportRow {
+  /** Discriminator: the kind of row this entry represents. */
+  type: 'group-header' | 'leaf' | 'group-subtotal' | 'grand-total';
+  /** Nesting depth (0 = top-level group, 1 = nested group, etc.). */
+  depth: number;
+  /** The grouping field for this level (absent on 'leaf' and 'grand-total'). */
+  groupField?: string;
+  /** The raw grouping value for this level (absent on 'leaf' and 'grand-total'). */
+  groupValue?: unknown;
+  /** Per-group aggregation results (present on 'group-subtotal' and 'grand-total'). */
+  aggregatedValues?: Record<string, unknown>;
+  /** The original data row (only present when `type === 'leaf'`). */
+  row?: GridRowModel;
 }
 
 export type GridPinnedPosition = 'left' | 'right';
@@ -819,6 +846,13 @@ export interface GridApi {
   getVisibleRows: () => GridRowModel[];
   /** Returns all filtered and sorted rows, ignoring pagination. Use this for full-dataset exports. */
   getAllFilteredRows: () => GridRowModel[];
+  /**
+   * Returns an ordered flat list of `GridGroupedExportRow` entries that mirrors the
+   * on-screen grouping tree: group-headers, leaf rows, per-group subtotals, and a
+   * grand-total entry at the end. Returns `null` when no `rowGroupingModel` is active.
+   * Pass the result to export functions that accept a `groupedRows` option.
+   */
+  getGroupedExportRows: () => GridGroupedExportRow[] | null;
   /** Returns the current aggregation results. */
   getAggregationResult: () => Record<string, unknown> | null;
   /** Returns the active aggregation configuration. */

package/lib/utils/export/exportToPdf.ts

@@ -3,6 +3,7 @@ import type {
     GridRowModel,
     GridFilterModel,
     PdfExportOptions,
+    GridGroupedExportRow,
 } from '../../types';
 import { formatAggregationValue } from '../../hooks/features/useAggregation';
 
@@ -137,6 +138,7 @@ export async function exportToPdf<R extends GridRowModel>(
         headerBackgroundColor = '#4f46e5',
         headerTextColor = '#ffffff',
         fontSize = 9,
+        groupedRows,
     } = options;
 
     const doc = new JsPDF({ orientation, unit: 'mm', format: 'a4' });
@@ -157,7 +159,6 @@ export async function exportToPdf<R extends GridRowModel>(
         let cursorX = MARGIN;
         let cursorY = MARGIN + 8;
 
-        // Logo
         if (logoUrl) {
             try {
                 doc.addImage(logoUrl, 'PNG', cursorX, MARGIN, 10, 10);
@@ -167,26 +168,26 @@ export async function exportToPdf<R extends GridRowModel>(
             }
         }
 
-        // Title
         doc.setFontSize(16);
         doc.setFont('helvetica', 'bold');
-        doc.setTextColor(30, 41, 59); // #1e293b
+        doc.setTextColor(30, 41, 59);
         doc.text(title, cursorX, cursorY);
         cursorY += 6;
 
-        // Subtitle: date + row count
         doc.setFontSize(8);
         doc.setFont('helvetica', 'normal');
-        doc.setTextColor(100, 116, 139); // #64748b
+        doc.setTextColor(100, 116, 139);
         const exportedAt = new Date().toLocaleDateString('en-US', { year: 'numeric', month: 'short', day: 'numeric' });
+        const rowCount = groupedRows
+            ? groupedRows.filter(e => e.type === 'leaf').length
+            : rowsToExport.length;
         doc.text(
-            `Exported: ${exportedAt}  •  ${rowsToExport.length} row${rowsToExport.length !== 1 ? 's' : ''}`,
+            `Exported: ${exportedAt}  •  ${rowCount} row${rowCount !== 1 ? 's' : ''}`,
             cursorX,
             cursorY
         );
         cursorY += 5;
 
-        // Filter summary
         if (filterModel) {
             const summary = formatFilterSummary(filterModel, columns);
             if (summary) {
@@ -195,8 +196,7 @@ export async function exportToPdf<R extends GridRowModel>(
             }
         }
 
-        // Separator line
-        doc.setDrawColor(226, 232, 240); // #e2e8f0
+        doc.setDrawColor(226, 232, 240);
         doc.setLineWidth(0.3);
         doc.line(MARGIN, cursorY + 2, pageWidth - MARGIN, cursorY + 2);
         startY = cursorY + 6;
@@ -205,30 +205,67 @@ export async function exportToPdf<R extends GridRowModel>(
     // --- Build table data ---
     const head = [exportColumns.map(col => col.headerName ?? col.field)];
 
-    const body = rowsToExport.map(row =>
-        exportColumns.map(col => resolveValue(row, col))
-    );
-
-    // --- Aggregation footer ---
+    let body: string[][];
     let foot: string[][] | undefined;
-    if (aggregationResult && aggregationModel) {
-        const footRow = exportColumns.map((col, i) => {
-            if (i === 0) {
-                // First column shows TOTAL label if any aggregation exists
-                const hasAgg = exportColumns.some(c => aggregationModel[c.field]);
-                return hasAgg ? 'TOTAL' : '';
-            }
-            const aggVal = aggregationResult[col.field];
-            if (aggVal === undefined || aggVal === null) return '';
-            let formatted: unknown = aggVal;
-            if (col.valueFormatter) {
-                formatted = col.valueFormatter({ value: aggVal, row: {} as R, field: col.field });
-            } else if (aggregationModel[col.field]) {
-                formatted = formatAggregationValue(aggVal, aggregationModel[col.field] as string);
+
+    if (groupedRows && groupedRows.length > 0) {
+        // Grouped export: flatten the ordered list into body rows with indentation
+        body = [];
+        const aggMod = aggregationModel || {};
+        groupedRows.forEach((entry: GridGroupedExportRow) => {
+            if (entry.type === 'group-header') {
+                const indent = '  '.repeat(entry.depth * 2);
+                const label = `${indent}${entry.groupField ?? ''}: ${String(entry.groupValue ?? '')}`;
+                body.push(exportColumns.map((_, i) => i === 0 ? label : ''));
+            } else if (entry.type === 'leaf' && entry.row) {
+                const row = entry.row as R;
+                const indent = '  '.repeat(entry.depth * 2);
+                body.push(exportColumns.map((col, i) => (i === 0 ? indent : '') + resolveValue(row, col)));
+            } else if (entry.type === 'group-subtotal' && entry.aggregatedValues) {
+                const indent = '  '.repeat(entry.depth * 2);
+                body.push(exportColumns.map((col, i) => {
+                    if (i === 0) return `${indent}Subtotal`;
+                    const aggVal = entry.aggregatedValues![col.field];
+                    if (aggVal === undefined || aggVal === null) return '';
+                    let formatted: unknown = aggVal;
+                    if (col.valueFormatter) formatted = col.valueFormatter({ value: aggVal, row: {} as R, field: col.field });
+                    else if (aggMod[col.field]) formatted = formatAggregationValue(aggVal, aggMod[col.field] as string);
+                    return String(formatted);
+                }));
+            } else if (entry.type === 'grand-total' && entry.aggregatedValues) {
+                const footRow = exportColumns.map((col, i) => {
+                    if (i === 0) return 'Grand Total';
+                    const aggVal = entry.aggregatedValues![col.field];
+                    if (aggVal === undefined || aggVal === null) return '';
+                    let formatted: unknown = aggVal;
+                    if (col.valueFormatter) formatted = col.valueFormatter({ value: aggVal, row: {} as R, field: col.field });
+                    else if (aggMod[col.field]) formatted = formatAggregationValue(aggVal, aggMod[col.field] as string);
+                    return String(formatted);
+                });
+                foot = [footRow];
             }
-            return String(formatted);
         });
-        foot = [footRow];
+    } else {
+        body = rowsToExport.map(row => exportColumns.map(col => resolveValue(row, col)));
+
+        if (aggregationResult && aggregationModel) {
+            const footRow = exportColumns.map((col, i) => {
+                if (i === 0) {
+                    const hasAgg = exportColumns.some(c => aggregationModel[c.field]);
+                    return hasAgg ? 'TOTAL' : '';
+                }
+                const aggVal = aggregationResult[col.field];
+                if (aggVal === undefined || aggVal === null) return '';
+                let formatted: unknown = aggVal;
+                if (col.valueFormatter) {
+                    formatted = col.valueFormatter({ value: aggVal, row: {} as R, field: col.field });
+                } else if (aggregationModel[col.field]) {
+                    formatted = formatAggregationValue(aggVal, aggregationModel[col.field] as string);
+                }
+                return String(formatted);
+            });
+            foot = [footRow];
+        }
     }
 
     // --- Column widths ---

package/lib/utils/export/groupedExport.test.ts

@@ -0,0 +1,144 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { exportToCsv, exportToJson } from './index';
+import type { GridColDef, GridGroupedExportRow, GridRowModel } from '../../types';
+
+// --- shared fixtures ---
+
+type Row = GridRowModel & { id: number; dept: string; salary: number };
+
+const columns: GridColDef<Row>[] = [
+    { field: 'dept', headerName: 'Department' },
+    { field: 'salary', headerName: 'Salary', type: 'number' },
+];
+
+const flatRows: Row[] = [
+    { id: 1, dept: 'Engineering', salary: 90000 },
+    { id: 2, dept: 'Engineering', salary: 85000 },
+    { id: 3, dept: 'Marketing',   salary: 70000 },
+];
+
+const groupedRows: GridGroupedExportRow[] = [
+    { type: 'group-header', depth: 0, groupField: 'dept', groupValue: 'Engineering' },
+    { type: 'leaf', depth: 1, row: { id: 1, dept: 'Engineering', salary: 90000 } },
+    { type: 'leaf', depth: 1, row: { id: 2, dept: 'Engineering', salary: 85000 } },
+    { type: 'group-subtotal', depth: 0, groupField: 'dept', groupValue: 'Engineering', aggregatedValues: { salary: 175000 } },
+    { type: 'group-header', depth: 0, groupField: 'dept', groupValue: 'Marketing' },
+    { type: 'leaf', depth: 1, row: { id: 3, dept: 'Marketing', salary: 70000 } },
+    { type: 'group-subtotal', depth: 0, groupField: 'dept', groupValue: 'Marketing', aggregatedValues: { salary: 70000 } },
+    { type: 'grand-total', depth: 0, aggregatedValues: { salary: 245000 } },
+];
+
+// --- intercept URL.createObjectURL so we can read Blob content ---
+
+let capturedBlob: Blob | null = null;
+const origCreateObjectURL = URL.createObjectURL;
+const origRevokeObjectURL = URL.revokeObjectURL;
+const origClick = HTMLAnchorElement.prototype.click;
+
+beforeEach(() => {
+    capturedBlob = null;
+    URL.createObjectURL = (blob: Blob) => { capturedBlob = blob; return 'blob:mock'; };
+    URL.revokeObjectURL = () => {};
+    HTMLAnchorElement.prototype.click = () => {};
+});
+
+afterEach(() => {
+    URL.createObjectURL = origCreateObjectURL;
+    URL.revokeObjectURL = origRevokeObjectURL;
+    HTMLAnchorElement.prototype.click = origClick;
+});
+
+// --- CSV tests ---
+
+describe('exportToCsv — flat (no groupedRows)', () => {
+    it('produces a header row followed by one row per data record', async () => {
+        exportToCsv(flatRows, columns, { fileName: 'test.csv' });
+        const text = await capturedBlob!.text();
+        const lines = text.split('\n').filter(Boolean);
+        expect(lines[0]).toBe('Department,Salary');
+        expect(lines.length).toBe(4); // header + 3 data rows
+    });
+
+    it('does not emit group-header markers or Subtotal labels', async () => {
+        exportToCsv(flatRows, columns, { fileName: 'flat.csv' });
+        const text = await capturedBlob!.text();
+        expect(text).not.toContain('dept:');
+        expect(text).not.toContain('Subtotal');
+        expect(text).not.toContain('Grand Total');
+    });
+});
+
+describe('exportToCsv — grouped', () => {
+    it('emits group-header rows, leaf rows, subtotals, and grand total', async () => {
+        exportToCsv(flatRows, columns, {
+            fileName: 'grouped.csv',
+            groupedRows,
+            aggregationModel: { salary: 'sum' },
+        });
+        const text = await capturedBlob!.text();
+        const lines = text.split('\n').filter(Boolean);
+
+        // Header
+        expect(lines[0]).toBe('Department,Salary');
+        // Group header for Engineering (depth 0 → no leading spaces, just "dept: Engineering")
+        expect(lines[1]).toContain('dept: Engineering');
+        // Leaf rows: salary values present
+        expect(lines[2]).toContain('90000');
+        expect(lines[3]).toContain('85000');
+        // Subtotal row for Engineering (formatAggregationValue adds commas: "175,000")
+        expect(lines[4]).toContain('Subtotal');
+        expect(lines[4]).toContain('175');
+        // Grand total
+        const last = lines[lines.length - 1];
+        expect(last).toContain('Grand Total');
+        expect(last).toContain('245');
+    });
+
+    it('total line count matches structure (1 header + 2 group-headers + 3 leaves + 2 subtotals + 1 grand-total)', async () => {
+        exportToCsv(flatRows, columns, { groupedRows, aggregationModel: { salary: 'sum' } });
+        const text = await capturedBlob!.text();
+        const lines = text.split('\n').filter(Boolean);
+        expect(lines.length).toBe(9);
+    });
+});
+
+// --- JSON tests ---
+
+describe('exportToJson — flat (no groupedRows)', () => {
+    it('emits a plain array with one entry per row', async () => {
+        exportToJson(flatRows, columns, {});
+        const text = await capturedBlob!.text();
+        const parsed = JSON.parse(text) as unknown[];
+        expect(Array.isArray(parsed)).toBe(true);
+        expect(parsed.length).toBe(3);
+    });
+});
+
+describe('exportToJson — grouped', () => {
+    it('emits { groups, grandTotal } with two top-level groups', async () => {
+        exportToJson(flatRows, columns, {
+            groupedRows,
+            aggregationModel: { salary: 'sum' },
+        });
+        const text = await capturedBlob!.text();
+        const parsed = JSON.parse(text) as {
+            groups: { group: string; rows: unknown[]; subtotals?: Record<string, unknown> }[];
+            grandTotal?: Record<string, unknown>;
+        };
+        expect(parsed.groups).toHaveLength(2);
+        expect(parsed.groups[0].group).toBe('dept: Engineering');
+        expect(parsed.groups[0].rows).toHaveLength(2);
+        expect(parsed.groups[0].subtotals?.salary).toBe(175000);
+        expect(parsed.groups[1].group).toBe('dept: Marketing');
+        expect(parsed.groups[1].rows).toHaveLength(1);
+        expect(parsed.grandTotal?.salary).toBe(245000);
+    });
+
+    it('falls through to flat array when groupedRows is absent', async () => {
+        exportToJson(flatRows, columns, {});
+        const text = await capturedBlob!.text();
+        const parsed = JSON.parse(text) as unknown[];
+        expect(Array.isArray(parsed)).toBe(true);
+        expect(parsed.length).toBe(3);
+    });
+});