@opencorestack/opengridx 2.0.3 → 2.1.0

package/lib/hooks/useTreeData.test.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect, vi } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { useTreeData } from './useTreeData';
+import type { GridRowModel, GridRowId } from '../types';
+
+type Row = GridRowModel & { id: number; path: string[]; name: string };
+
+const ROWS: Row[] = [
+    { id: 1, path: ['CEO'], name: 'Ada' },
+    { id: 2, path: ['CEO', 'CTO'], name: 'Bo' },
+    { id: 3, path: ['CEO', 'CTO', 'Dev'], name: 'Cy' },
+    { id: 4, path: ['CEO', 'CFO'], name: 'Di' },
+];
+
+const getRowId = (r: Row) => r.id;
+const getTreeDataPath = (r: Row) => r.path;
+
+const visibleIds = (rows: GridRowModel[] | null) => (rows ?? []).map(r => r.id as GridRowId);
+
+describe('useTreeData — expansion state', () => {
+    it('expands to defaultGroupingExpansionDepth on the first render (no effect flash)', () => {
+        const { result } = renderHook(() =>
+            useTreeData({ rows: ROWS, getRowId, getTreeDataPath, treeData: true, defaultGroupingExpansionDepth: 1 })
+        );
+        expect(result.current.isGroupExpanded(1)).toBe(true);
+        expect(result.current.isGroupExpanded(2)).toBe(false);
+        expect(visibleIds(result.current.getVisibleRows())).toEqual([1, 2, 4]);
+    });
+
+    it('keeps a user collapse when rows are replaced with edited copies', () => {
+        const { result, rerender } = renderHook(
+            ({ rows }) => useTreeData({ rows, getRowId, getTreeDataPath, treeData: true, defaultGroupingExpansionDepth: -1 }),
+            { initialProps: { rows: ROWS } }
+        );
+        act(() => { result.current.toggleExpansion(2); });
+        expect(result.current.isGroupExpanded(2)).toBe(false);
+
+        rerender({ rows: ROWS.map(r => (r.id === 4 ? { ...r, name: 'Dee' } : r)) });
+        expect(result.current.isGroupExpanded(2)).toBe(false);
+    });
+
+    it('keeps a lazily expanded node open after its children arrive', () => {
+        const lazyRows: Row[] = [
+            { id: 1, path: ['CEO'], name: 'Ada' },
+            { id: 2, path: ['CEO', 'CTO'], name: 'Bo', serverChildrenCount: 1 },
+        ];
+        const { result, rerender } = renderHook(
+            ({ rows }) => useTreeData({ rows, getRowId, getTreeDataPath, treeData: true, defaultGroupingExpansionDepth: 1 }),
+            { initialProps: { rows: lazyRows } }
+        );
+        act(() => { result.current.toggleExpansion(2); });
+        expect(result.current.isGroupExpanded(2)).toBe(true);
+
+        rerender({ rows: [...lazyRows, { id: 3, path: ['CEO', 'CTO', 'Dev'], name: 'Cy' }] });
+        expect(result.current.isGroupExpanded(2)).toBe(true);
+        expect(visibleIds(result.current.getVisibleRows())).toContain(3);
+    });
+
+    it('calls onRowExpansionChange exactly once per expand and never on collapse', () => {
+        const onRowExpansionChange = vi.fn();
+        const { result } = renderHook(() =>
+            useTreeData({ rows: ROWS, getRowId, getTreeDataPath, treeData: true, onRowExpansionChange })
+        );
+        act(() => { result.current.toggleExpansion(1); });
+        expect(onRowExpansionChange).toHaveBeenCalledTimes(1);
+        expect(onRowExpansionChange).toHaveBeenCalledWith(expect.objectContaining({ id: 1 }));
+
+        act(() => { result.current.toggleExpansion(1); });
+        expect(onRowExpansionChange).toHaveBeenCalledTimes(1);
+    });
+
+    it('discards user overrides when defaultGroupingExpansionDepth changes', () => {
+        const { result, rerender } = renderHook(
+            ({ depth }) => useTreeData({ rows: ROWS, getRowId, getTreeDataPath, treeData: true, defaultGroupingExpansionDepth: depth }),
+            { initialProps: { depth: -1 } }
+        );
+        act(() => { result.current.toggleExpansion(1); });
+        expect(result.current.isGroupExpanded(1)).toBe(false);
+
+        rerender({ depth: 1 });
+        expect(result.current.isGroupExpanded(1)).toBe(true);
+    });
+});

package/lib/hooks/useTreeData.ts

@@ -1,9 +1,16 @@
-import { useMemo, useState, useCallback, useEffect } from 'react';
+import { useMemo, useState, useCallback } from 'react';
 import { GridRowModel, GridRowId, GridTreeNode, GridFilterModel, GridSortItem } from '../types';
 import type { GridRowMeta } from '../types';
 import { isRowMatchingFilter } from '../utils/filtering';
 import { compareValues } from '../utils/sorting';
 
+const EMPTY_OVERRIDES: Map<GridRowId, boolean> = new Map();
+
+interface ExpansionOverrides {
+    configKey: string;
+    overrides: Map<GridRowId, boolean>;
+}
+
 interface UseTreeDataProps<R extends GridRowModel> {
     rows: R[];
     getRowId: (row: R) => GridRowId;
@@ -157,49 +164,45 @@ export function useTreeData<R extends GridRowModel>(props: UseTreeDataProps<R>)
 
     }, [rows, getTreeDataPath, treeData, getRowId]);
 
-    const initialExpandedIds = useMemo(() => {
-        if (!treeData) return new Set<GridRowId>();
-
-        const initialExpanded = new Set<GridRowId>();
-        treeNodes.forEach(node => {
-            if (node.children && node.children.length > 0) {
-                 if (defaultGroupingExpansionDepth === -1 || node.depth < defaultGroupingExpansionDepth) {
-                     initialExpanded.add(node.id);
-                 }
-            }
+    // Same model as useRowGrouping: depth-based default plus user overrides keyed by config.
+    // Rebuilding the tree (row edits, lazily loaded children) keeps the user's choices.
+    const configKey = `${treeData}|${defaultGroupingExpansionDepth}`;
+    const [expansionState, setExpansionState] = useState<ExpansionOverrides>(() => ({
+        configKey,
+        overrides: new Map(),
+    }));
+    const overrides = expansionState.configKey === configKey ? expansionState.overrides : EMPTY_OVERRIDES;
+
+    const isDefaultExpanded = useCallback((node: GridTreeNode | undefined) => (
+        Boolean(node?.children && node.children.length > 0) &&
+        (defaultGroupingExpansionDepth === -1 || (node?.depth ?? 0) < defaultGroupingExpansionDepth)
+    ), [defaultGroupingExpansionDepth]);
+
+    const expandedGroupIds = useMemo<Set<GridRowId>>(() => {
+        const ids = new Set<GridRowId>();
+        if (!treeData) return ids;
+        treeNodes.forEach((node, id) => {
+            // A lazily loaded node can be expanded before it has any children, so an
+            // explicit override counts even when children is still empty.
+            if (overrides.get(id) ?? isDefaultExpanded(node)) ids.add(id);
         });
-        return initialExpanded;
-    }, [treeNodes, treeData, defaultGroupingExpansionDepth]);
-
-    const [expandedGroupIds, setExpandedGroupIds] = useState<Set<GridRowId>>(new Set());
-
-    useEffect(() => {
-        if (initialExpandedIds.size > 0) {
-            setExpandedGroupIds(initialExpandedIds);
-        }
-    }, [initialExpandedIds]);
+        return ids;
+    }, [treeData, treeNodes, overrides, isDefaultExpanded]);
 
     const toggleExpansion = useCallback((id: GridRowId) => {
-        setExpandedGroupIds(prev => {
-            const next = new Set(prev);
-            const isExpanding = !next.has(id);
-
-            if (next.has(id)) {
-                next.delete(id);
-            } else {
-                next.add(id);
-            }
-
-            if (isExpanding && onRowExpansionChange) {
-                 const node = treeNodes.get(id);
-                 if (node) {
-                     onRowExpansionChange(node);
-                 }
-            }
-
-            return next;
+        const isExpanding = !expandedGroupIds.has(id);
+        setExpansionState(prev => {
+            const base = prev.configKey === configKey ? prev.overrides : EMPTY_OVERRIDES;
+            const next = new Map(base);
+            next.set(id, isExpanding);
+            return { configKey, overrides: next };
         });
-    }, [treeNodes, onRowExpansionChange]);
+        // Called outside the state updater: updaters may run twice, and this can trigger a server fetch.
+        if (isExpanding && onRowExpansionChange) {
+            const node = treeNodes.get(id);
+            if (node) onRowExpansionChange(node);
+        }
+    }, [expandedGroupIds, configKey, treeNodes, onRowExpansionChange]);
 
     const getVisibleRows = useCallback(() => {
 
@@ -209,9 +212,7 @@ export function useTreeData<R extends GridRowModel>(props: UseTreeDataProps<R>)
         rows.forEach(r => rowLookup.set(getRowId(r), r));
         groupingRows.forEach(r => rowLookup.set(r.id, r));
 
-        const matchesFilter = (row: GridRowModel) => {
-             return isRowMatchingFilter(row, filterModel!);
-        };
+        const matchesFilter = (row: GridRowModel) => (filterModel ? isRowMatchingFilter(row, filterModel) : true);
 
         const filterCache = new Map<GridRowId, boolean>();
 

package/lib/index.ts

@@ -11,6 +11,8 @@ export { FilterPanel } from './components/FilterPanel';
 export { GridToolbar } from './components/Toolbar/GridToolbar';
 export type { GridToolbarProps, ToolbarButtonRenderProps, ToolbarQuickFilterRenderProps } from './components/Toolbar/GridToolbar';
 export { GridTooltip } from './components/Tooltip/Tooltip';
+export { ColumnVisibilityPanel } from './components/ColumnVisibilityPanel/ColumnVisibilityPanel';
+export type { ColumnVisibilityPanelProps } from './components/ColumnVisibilityPanel/ColumnVisibilityPanel';
 
 export { useGridApiRef } from './hooks/core/useGridApiRef';
 export { Button, Input, Checkbox } from './components/ui';

package/lib/types/index.ts

@@ -21,8 +21,9 @@ export interface GridRowModel {
  *
  * @since v1.1 — replaces the `_hasChildren` / `_treeDepth` / `_groupingField` etc.
  * properties that were previously (and incorrectly) typed on `GridRowModel`.
- * Those underscore fields remain on the row object at runtime in v1.1 for
- * backward compatibility; they will be removed from the runtime in v2.0.
+ * Those underscore fields remain on the row object at runtime for backward
+ * compatibility; removal was deferred past v2.0 (still present as of v2.1.0)
+ * to a future major version. Do not rely on them being absent yet.
  */
 export interface GridRowMeta {
     hasChildren?: boolean;
@@ -235,6 +236,11 @@ export interface GridValueFormatterParams<R extends GridRowModel = GridRowModel>
 export interface GridRenderCellParams<R extends GridRowModel = GridRowModel> {
   /** The current cell value. */
   value: unknown;
+  /**
+   * The value after `colDef.valueFormatter` (or `String(value)` when no formatter is set; `''` for null/undefined).
+   * @since v2.1
+   */
+  formattedValue?: string;
   /** The row object. */
   row: R;
   /** The field name and unique ID. */
@@ -608,6 +614,13 @@ export interface DataGridProps<R extends GridRowModel = GridRowModel> {
   headerHeight?: number;
   /** If true, the grid height will adjust to match the total height of its rows. */
   autoHeight?: boolean;
+  /**
+   * Minimum number of rows to render outside the visible viewport (overscan buffer).
+   * The grid adapts this value upward automatically based on scroll velocity to prevent
+   * blank flashes during fast scrolling. This prop sets the floor — the buffer never
+   * drops below this value regardless of scroll speed. Defaults to `3`.
+   */
+  overscanRowCount?: number;
 
   /** Sorting mode: 'client' (default) or 'server'. */
   sortingMode?: 'client' | 'server';
@@ -697,6 +710,13 @@ export interface DataGridProps<R extends GridRowModel = GridRowModel> {
 
   /** Callback fired when a row is clicked. */
   onRowClick?: (params: GridRowParams<R>) => void;
+  /**
+   * Callback fired when a row is double-clicked. Also fires for group rows; check
+   * `apiRef` / `rowMeta` if you only want leaf rows. Not fired when the double-click
+   * lands on the checkbox, expand icon, drag handle, or an open cell editor.
+   * @since v2.1
+   */
+  onRowDoubleClick?: (params: GridRowParams<R>) => void;
   /** Callback fired when a cell is clicked. */
   onCellClick?: (params: GridCellParams<R>) => void;
 

package/lib/utils/aggregation/aggregation.test.ts

@@ -0,0 +1,16 @@
+import { describe, it, expect } from 'vitest';
+import { AGGREGATION_FUNCTIONS } from './index';
+
+describe('AGGREGATION_FUNCTIONS', () => {
+    it('computes min / max over more values than a spread argument list allows', () => {
+        const values = Array.from({ length: 300_000 }, (_, i) => i);
+        expect(AGGREGATION_FUNCTIONS.min(values)).toBe(0);
+        expect(AGGREGATION_FUNCTIONS.max(values)).toBe(299_999);
+    });
+
+    it('returns null for min / max / avg when there are no numeric values', () => {
+        expect(AGGREGATION_FUNCTIONS.min([null, undefined])).toBeNull();
+        expect(AGGREGATION_FUNCTIONS.max([])).toBeNull();
+        expect(AGGREGATION_FUNCTIONS.avg(['x'])).toBeNull();
+    });
+});

package/lib/utils/aggregation/index.ts

@@ -0,0 +1,62 @@
+import type { GridAggregationModel, GridAggregationResult, GridColDef, GridRowModel } from '../../types';
+
+export type BuiltInAggFn = 'sum' | 'avg' | 'count' | 'min' | 'max' | 'unique';
+
+const toNumbers = (values: unknown[]): number[] => {
+    const nums: number[] = [];
+    for (const v of values) {
+        if (v == null) continue;
+        const n = Number(v);
+        if (!isNaN(n)) nums.push(n);
+    }
+    return nums;
+};
+
+// Loops instead of Math.min(...nums): spreading >~120k arguments throws RangeError.
+const minOf = (nums: number[]): number | null => {
+    if (nums.length === 0) return null;
+    let m = nums[0];
+    for (let i = 1; i < nums.length; i++) if (nums[i] < m) m = nums[i];
+    return m;
+};
+
+const maxOf = (nums: number[]): number | null => {
+    if (nums.length === 0) return null;
+    let m = nums[0];
+    for (let i = 1; i < nums.length; i++) if (nums[i] > m) m = nums[i];
+    return m;
+};
+
+export const AGGREGATION_FUNCTIONS: Record<BuiltInAggFn, (values: unknown[]) => unknown> = {
+    sum: (values) => toNumbers(values).reduce((acc, n) => acc + n, 0),
+    avg: (values) => {
+        const nums = toNumbers(values);
+        return nums.length ? nums.reduce((acc, n) => acc + n, 0) / nums.length : null;
+    },
+    count: (values) => values.filter((v) => v != null).length,
+    min: (values) => minOf(toNumbers(values)),
+    max: (values) => maxOf(toNumbers(values)),
+    unique: (values) => new Set(values.filter((v) => v != null)).size,
+};
+
+export function computeAggregations<R extends GridRowModel>(
+    rows: R[],
+    aggregationModel: GridAggregationModel,
+    columnsLookup: Map<string, GridColDef<R>>,
+    warnPrefix: string,
+): GridAggregationResult {
+    const result: GridAggregationResult = {};
+    for (const [field, fnName] of Object.entries(aggregationModel)) {
+        const colDef = columnsLookup.get(field);
+        if (colDef?.availableAggregationFunctions && !colDef.availableAggregationFunctions.includes(fnName)) {
+            continue;
+        }
+        const fn = AGGREGATION_FUNCTIONS[fnName as BuiltInAggFn];
+        if (!fn) {
+            console.warn(`[${warnPrefix}] Unknown aggregation function: "${fnName}"`);
+            continue;
+        }
+        result[field] = fn(rows.map((row) => row[field]));
+    }
+    return result;
+}

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

@@ -0,0 +1,109 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import ExcelJS from 'exceljs';
+import { exportToExcelAdvanced } from './exportToExcelAdvanced';
+import type { GridColDef, GridGroupedExportRow, GridRowModel } from '../../types';
+
+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: flatRows[0] },
+    { type: 'leaf', depth: 1, row: flatRows[1] },
+    { 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: flatRows[2] },
+    { type: 'group-subtotal', depth: 0, groupField: 'dept', groupValue: 'Marketing', aggregatedValues: { salary: 70000 } },
+    { type: 'grand-total', depth: 0, aggregatedValues: { salary: 245000 } },
+];
+
+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;
+});
+
+async function readSheet(): Promise<ExcelJS.Worksheet> {
+    const wb = new ExcelJS.Workbook();
+    await wb.xlsx.load(await capturedBlob!.arrayBuffer());
+    return wb.worksheets[0];
+}
+
+const rowValues = (ws: ExcelJS.Worksheet) =>
+    ws.getSheetValues().slice(1).map(r => (Array.isArray(r) ? r.slice(1) : []));
+
+describe('exportToExcelAdvanced — flat', () => {
+    it('writes a header row and one row per record when groupedRows is absent', async () => {
+        await exportToExcelAdvanced(flatRows, columns);
+        const ws = await readSheet();
+        expect(rowValues(ws)).toEqual([
+            ['Department', 'Salary'],
+            ['Engineering', 90000],
+            ['Engineering', 85000],
+            ['Marketing', 70000],
+        ]);
+    });
+});
+
+describe('exportToExcelAdvanced — grouped', () => {
+    it('writes group headers, leaves, subtotals and a single grand total in order', async () => {
+        await exportToExcelAdvanced(flatRows, columns, {
+            groupedRows,
+            aggregationModel: { salary: 'sum' },
+            aggregationResult: { salary: 245000 },
+            sheets: [{ name: 'Data', includeSummary: true }],
+        });
+        const ws = await readSheet();
+        expect(rowValues(ws)).toEqual([
+            ['Department', 'Salary'],
+            ['Department: Engineering'],
+            ['Engineering', 90000],
+            ['Engineering', 85000],
+            ['Subtotal', 175000],
+            ['Department: Marketing'],
+            ['Marketing', 70000],
+            ['Subtotal', 70000],
+            ['Grand Total', 245000],
+        ]);
+    });
+
+    it('outlines leaf rows one level below their group header', async () => {
+        await exportToExcelAdvanced(flatRows, columns, { groupedRows });
+        const ws = await readSheet();
+        expect(ws.getRow(2).outlineLevel ?? 0).toBe(0);
+        expect(ws.getRow(3).outlineLevel).toBe(1);
+        expect(ws.getRow(4).outlineLevel).toBe(1);
+    });
+
+    it('uses groupingValueFormatter for group-header labels', async () => {
+        const cols: GridColDef<Row>[] = [
+            { ...columns[0], groupingValueFormatter: ({ value }) => `Dept ${String(value)}` },
+            columns[1],
+        ];
+        await exportToExcelAdvanced(flatRows, cols, { groupedRows });
+        const ws = await readSheet();
+        expect(ws.getRow(2).getCell(1).value).toBe('Dept Engineering');
+    });
+});

package/lib/utils/export/exportToExcelAdvanced.ts

@@ -1,5 +1,5 @@
 
-import type { GridColDef, GridRowModel, GridAggregationModel } from '../../types';
+import type { GridColDef, GridRowModel, GridAggregationModel, GridGroupedExportRow } from '../../types';
 import { formatAggregationValue } from '../../hooks/features/useAggregation';
 
 // ─── Types ────────────────────────────────────────────────────────────────────
@@ -68,6 +68,19 @@ export interface ExcelAdvancedExportOptions {
     aggregationModel?: GridAggregationModel | null;
     /** Currently selected row IDs */
     selectedRows?: (string | number)[];
+    /**
+     * Grouped row structure, typically from `apiRef.current.getGroupedExportRows()`.
+     * When provided, sheets with `rows: 'all'` are written in grouped order: group-header,
+     * leaf, group-subtotal and grand-total rows, using Excel row outlining so groups
+     * collapse natively. A `grand-total` entry replaces the sheet's `includeSummary` row.
+     * Ignored for `rows: 'selected'` sheets.
+     * @since v2.1
+     */
+    groupedRows?: GridGroupedExportRow[];
+    /** Fill color for group-header rows in grouped export (default: '#e8eaf6') */
+    groupHeaderFillColor?: string;
+    /** Fill color for group-subtotal rows in grouped export (default: '#f0f4ff') */
+    groupSubtotalFillColor?: string;
 }
 
 // ─── Cell type inference ──────────────────────────────────────────────────────
@@ -187,6 +200,9 @@ export async function exportToExcelAdvanced<R extends GridRowModel>(
         aggregationResult = null,
         aggregationModel = null,
         selectedRows,
+        groupedRows,
+        groupHeaderFillColor = '#e8eaf6',
+        groupSubtotalFillColor = '#f0f4ff',
     } = options;
 
     // Lazy-load ExcelJS to keep initial bundle lean
@@ -270,7 +286,12 @@ export async function exportToExcelAdvanced<R extends GridRowModel>(
             alternateRowColor = '#f8fafc',
         } = def;
 
-        const rowsToExport = rowScope === 'selected' ? sRows : allRows;
+        const useGrouped = rowScope === 'all' && Boolean(groupedRows && groupedRows.length > 0);
+        const rowsToExport = rowScope === 'selected'
+            ? sRows
+            : useGrouped
+                ? groupedRows!.flatMap(e => (e.type === 'leaf' && e.row ? [e.row] : []))
+                : allRows;
 
         // ─ Pre-fetch images for this sheet ──────────────────────────────────────────
         const imageColumns = exportColumns.filter(col => columnStyles[col.field]?.embedImage);
@@ -343,7 +364,7 @@ export async function exportToExcelAdvanced<R extends GridRowModel>(
         // Header occupies index 0 when present; first data row is at index 1.
         let excelRowIdx = includeHeaders ? 1 : 0;
 
-        rowsToExport.forEach((row, rowIdx) => {
+        const writeDataRow = (row: GridRowModel, rowIdx: number, outlineLevel: number) => {
             const cellValues = exportColumns.map(col => {
                 // Image columns: write empty string; image placed below
                 if (columnStyles[col.field]?.embedImage) return '';
@@ -361,6 +382,7 @@ export async function exportToExcelAdvanced<R extends GridRowModel>(
 
             const dataRow = ws.addRow(cellValues);
             dataRow.font = { size: bodyFontSize };
+            if (outlineLevel > 0) dataRow.outlineLevel = outlineLevel;
 
             // Alternate row background
             if (alternateRowColor && rowIdx % 2 === 1) {
@@ -440,10 +462,72 @@ export async function exportToExcelAdvanced<R extends GridRowModel>(
             }
 
             excelRowIdx++;
-        });
+        };
+
+        const groupLabel = (entry: GridGroupedExportRow): string => {
+            const colDef = exportColumns.find(c => c.field === entry.groupField);
+            if (colDef?.groupingValueFormatter && entry.groupField) {
+                return colDef.groupingValueFormatter({ field: entry.groupField, value: entry.groupValue });
+            }
+            return `${colDef?.headerName ?? entry.groupField ?? ''}: ${String(entry.groupValue ?? '')}`;
+        };
+
+        // Numbers are written raw so the column numFmt applies; other values use the formatter.
+        const aggregateCell = (col: GridColDef<GridRowModel>, values: Record<string, unknown>): unknown => {
+            const val = values[col.field];
+            if (val == null) return '';
+            if (typeof val === 'number') return val;
+            if (col.valueFormatter) return col.valueFormatter({ value: val, row: {} as GridRowModel, field: col.field });
+            return formatAggregationValue(val, aggregationModel?.[col.field] ?? '');
+        };
+
+        const writeSummaryRow = (label: string, values: Record<string, unknown>, fill: string, outlineLevel: number, bold: boolean) => {
+            const cells = exportColumns.map((col, i) => (i === 0 && values[col.field] == null ? label : aggregateCell(col, values)));
+            const summaryRow = ws.addRow(cells);
+            summaryRow.height = 18;
+            if (outlineLevel > 0) summaryRow.outlineLevel = outlineLevel;
+            summaryRow.font = { bold, italic: !bold, size: bodyFontSize, color: { argb: argb(headerTextColor) } };
+            summaryRow.eachCell((cell, colIndex) => {
+                cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: argb(fill) } };
+                const colDef = exportColumns[colIndex - 1];
+                cell.alignment = { horizontal: colIndex === 1 ? 'left' : (colDef?.type === 'number' ? 'right' : 'left'), vertical: 'middle' };
+                cell.border = topBorder();
+            });
+            excelRowIdx++;
+        };
+
+        let wroteGrandTotal = false;
+
+        if (useGrouped) {
+            let stripe = 0;
+            groupedRows!.forEach(entry => {
+                if (entry.type === 'group-header') {
+                    const groupHeaderRow = ws.addRow([groupLabel(entry)]);
+                    groupHeaderRow.height = 18;
+                    if (entry.depth > 0) groupHeaderRow.outlineLevel = entry.depth;
+                    groupHeaderRow.font = { bold: true, size: bodyFontSize, color: { argb: argb(headerTextColor) } };
+                    for (let c = 1; c <= exportColumns.length; c++) {
+                        groupHeaderRow.getCell(c).fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: argb(groupHeaderFillColor) } };
+                    }
+                    groupHeaderRow.getCell(1).alignment = { horizontal: 'left', vertical: 'middle', indent: entry.depth };
+                    excelRowIdx++;
+                    stripe = 0;
+                } else if (entry.type === 'leaf' && entry.row) {
+                    writeDataRow(entry.row, stripe++, entry.depth);
+                } else if (entry.type === 'group-subtotal' && entry.aggregatedValues) {
+                    writeSummaryRow('Subtotal', entry.aggregatedValues, groupSubtotalFillColor, entry.depth, false);
+                } else if (entry.type === 'grand-total' && entry.aggregatedValues) {
+                    writeSummaryRow('Grand Total', entry.aggregatedValues, headerFillColor, 0, true);
+                    wroteGrandTotal = true;
+                }
+            });
+            ws.properties.outlineProperties = { summaryBelow: true, summaryRight: false };
+        } else {
+            rowsToExport.forEach((row, rowIdx) => writeDataRow(row, rowIdx, 0));
+        }
 
         // ── Aggregation totals row ────────────────────────────────────────────
-        if (includeSummary && aggregationResult && aggregationModel) {
+        if (includeSummary && !wroteGrandTotal && aggregationResult && aggregationModel) {
             // Label row
             const labelValues = exportColumns.map(col => {
                 const fn = aggregationModel![col.field];

package/lib/utils/scroll/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Vertically scrolls the grid viewport so the center (unpinned) row at `centerIndex`
+ * is fully visible below the sticky header / top-pinned rows and above the
+ * bottom-pinned rows. `cumulativeHeights` is the unpinned-row layout.
+ */
+export function scrollRowIntoView(
+    viewport: HTMLElement,
+    centerIndex: number,
+    cumulativeHeights: number[],
+    pinnedBottomHeight: number,
+): void {
+    if (centerIndex < 0 || centerIndex >= cumulativeHeights.length) return;
+    const virtualContainer = viewport.querySelector<HTMLElement>('.ogx__virtual-container');
+    if (!virtualContainer) return;
+
+    const { scrollTop, clientHeight } = viewport;
+    // Everything above the center rows is sticky, so it covers exactly this many
+    // pixels at the top of the viewport at any scroll position.
+    const stickyTop = virtualContainer.getBoundingClientRect().top - viewport.getBoundingClientRect().top + scrollTop;
+    const rowTop = stickyTop + (centerIndex === 0 ? 0 : cumulativeHeights[centerIndex - 1]);
+    const rowBottom = stickyTop + cumulativeHeights[centerIndex];
+
+    if (rowTop < scrollTop + stickyTop) {
+        viewport.scrollTop = Math.max(0, rowTop - stickyTop);
+    } else if (rowBottom > scrollTop + clientHeight - pinnedBottomHeight) {
+        viewport.scrollTop = rowBottom - clientHeight + pinnedBottomHeight;
+    }
+}