@opencorestack/opengridx 1.2.3 → 2.0.0

package/lib/types/index.ts

@@ -29,6 +29,7 @@ export interface GridRowMeta {
     treeDepth?: number;
     groupingField?: string;
     groupingValue?: unknown;
+    groupLabel?: string;
     descendantCount?: number;
     isExpanded?: boolean;
     isGroupRow?: boolean;
@@ -81,16 +82,22 @@ export interface GridColDef<R extends GridRowModel = GridRowModel> {
   field: string;
   /** Text displayed in the column header. */
   headerName?: string;
-  /** Tooltip or accessible description for the header. */
+  /** Tooltip shown on header hover — used as the column's accessibility label. */
   description?: string;
-
   /** If true, this column can be used as a grouping dimension. */
   groupable?: boolean;
 
+  /**
+   * Custom formatter for the group-header label when this column is used as a grouping field.
+   * Receives the field name and grouped value; return the string to display.
+   * Falls back to `"field: value"` when omitted.
+   */
+  groupingValueFormatter?: (params: { field: string; value: unknown }) => string;
+
   /** If true, this column can be summarized using aggregation functions. */
   aggregable?: boolean;
-  /** List of allowed aggregation functions (e.g., ['sum', 'avg']). */
-  availableAggregationFunctions?: string[]; 
+  /** Restricts which aggregation functions are offered for this column (e.g., ['sum', 'avg']). */
+  availableAggregationFunctions?: string[];
 
   /** Width in pixels or a percentage string. Defaults to automatic calculation. */
   width?: number | string;
@@ -376,6 +383,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';
@@ -581,6 +615,13 @@ export interface DataGridProps<R extends GridRowModel = GridRowModel> {
   sortModel?: GridSortItem[];
   /** Callback fired when the sorting model changes. */
   onSortModelChange?: (model: GridSortItem[]) => void;
+  /**
+   * When true, clicking any sortable column header appends/cycles that column in the
+   * sort model instead of replacing it — no Shift key required. Plain click still
+   * cycles asc → desc → removed for that column while all other active sort keys stay.
+   * Shift+click continues to work regardless of this prop.
+   */
+  multiSort?: boolean;
 
   /** Filtering mode: 'client' (default) or 'server'. */
   filterMode?: 'client' | 'server';
@@ -614,8 +655,6 @@ export interface DataGridProps<R extends GridRowModel = GridRowModel> {
 
   /** Defines which rows are pinned to the top or bottom. */
   pinnedRows?: GridRowPinning;
-  /** Callback fired when row pinning changes. */
-  onPinnedRowsChange?: (model: GridRowPinning) => void;
 
   /** If true, a column of checkboxes is added for row selection. */
   checkboxSelection?: boolean;
@@ -693,8 +732,6 @@ export interface DataGridProps<R extends GridRowModel = GridRowModel> {
 
   /** Controlled state for row grouping. */
   rowGroupingModel?: GridRowGroupingModel;
-  /** Callback fired when row grouping changes. */
-  onRowGroupingModelChange?: (model: GridRowGroupingModel) => void;
   /** Controlled state for data aggregation (e.g., { salary: 'sum' }). */
   aggregationModel?: GridAggregationModel;
   /** Callback fired when aggregation model changes. */
@@ -819,6 +856,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);
+    });
+});