Migrating v1 to v2

📝 Generated from docs/migration/v1-to-v2.md. Edit it there; changes made in the wiki are overwritten.

Migrating from v1 to v2

This guide covers every change that requires action when upgrading @opencorestack/opengridx from any v1.x release to v2.0.0.

---

1. Remove two dead callback props

These props existed in v1 but their callbacks were never called — no UI existed to trigger them. They have been removed from DataGridProps in v2.

Removed prop	Why	Fix
onPinnedRowsChange	No pin/unpin-row UI exists	Delete the prop from your JSX
onRowGroupingModelChange	No drag-to-group UI exists	Delete the prop from your JSX

TypeScript will give a compile error at every call site. Runtime behavior is unchanged — these callbacks were never invoked, so removing them has no effect.

// v1 — remove these props:
<DataGrid
  onPinnedRowsChange={handlePinnedRowsChange}      // ❌ delete
  onRowGroupingModelChange={handleGroupingChange}  // ❌ delete
/>

// v2:
<DataGrid />

---

2. Audit columns with groupable: false

In v1 the groupable: false flag on a GridColDef was silently ignored — the column was still grouped if it appeared in rowGroupingModel. In v2 the flag is enforced: that field is skipped entirely when building the group tree.

Action required only if you have a column with groupable: false that also appears in rowGroupingModel.

// If you have this in v1 and the column was grouping:
{ field: 'id', groupable: false }
// ...and rowGroupingModel includes 'id'

// v2: 'id' is now silently skipped from grouping.
// Either remove 'id' from rowGroupingModel, or remove groupable:false.

---

3. Audit columns with availableAggregationFunctions

In v1 availableAggregationFunctions on a GridColDef was silently ignored — all configured aggregation functions ran regardless. In v2 this list is enforced: any function in aggregationModel that is not in availableAggregationFunctions for that field is skipped.

Action required only if you have availableAggregationFunctions set AND the active aggregationModel for that field uses a function not in that list.

// v1: both 'sum' and 'avg' aggregations ran, regardless of this list
{ field: 'salary', availableAggregationFunctions: ['sum'] }
// ...with aggregationModel: { salary: 'avg' }

// v2: 'avg' is skipped for 'salary' because it is not in the allowed list.
// Fix: either add 'avg' to availableAggregationFunctions, or change aggregationModel.

---

4. groupingColDef now creates a real column

In v1 passing groupingColDef had no runtime effect. In v2, when rowGroupingModel is active, groupingColDef creates a dedicated __group__ column at position 0, auto-pinned left.

Action required only if you were passing groupingColDef expecting it to be a no-op.

// v1: this prop was accepted but did nothing
<DataGrid groupingColDef={{ headerName: 'Group', width: 200 }} rowGroupingModel={['dept']} />

// v2: this creates a pinned __group__ column at position 0.
// If you don't want the dedicated column, remove groupingColDef.

---

5. No action needed: legacy underscore row fields are still present

v3.0 update: the underscore fields are removed at runtime in 3.0.0. See Migrating from v2 to v3.

Earlier drafts of docs/architecture/grid-row-meta.md and docs/roadmap.md stated that the _hasChildren / _treeDepth / _isExpanded / _groupingField / _groupingValue / _descendantCount / _isGroupRow runtime shim was removed in v2.0. That was incorrect — it was never scheduled for v2.0 and nothing in this release touches it. useTreeData and useRowGrouping still inject these fields onto every row exactly as they did in v1.x.

No migration action is required. If you were already using params.rowMeta (recommended since v1.1), nothing changes. If you were still reading the underscore fields directly, they continue to work in v2.0 — but treat them as deprecated and migrate to params.rowMeta before they're removed in a future major version. See docs/architecture/grid-row-meta.md for the full field mapping.

---

New features (no migration needed)

These are purely additive — existing v1 code continues to work unchanged.

Feature	Prop	Notes
Multi-sort single-click	multiSort	false by default; Shift+click always worked
Multi-sort shift-click	(built-in)	Shift+click now appends; previously behaved like a plain click
Row density wired	density	Was accepted but ignored in v1
Click-to-select control	disableRowSelectionOnClick	Was accepted but ignored in v1; onRowSelectionModelChange now fires correctly
Single-row selection cap	disableMultipleRowSelection	Was accepted but ignored in v1
Group label formatter	groupingValueFormatter on GridColDef	New field, no v1 code has it
Header tooltip	description on GridColDef	Was in types but not rendered in v1; now renders as title attribute
Pagination fixed	(bug fix)	Uncontrolled pagination navigation now works; controlled usage unchanged

---

Quick checklist

• Search codebase for onPinnedRowsChange — delete every occurrence
• Search codebase for onRowGroupingModelChange — delete every occurrence
• Search codebase for groupable: false — verify those fields are not in rowGroupingModel
• Search codebase for availableAggregationFunctions — verify the list covers what aggregationModel actually uses
• Search codebase for groupingColDef — verify you want the __group__ column it now creates
• Run TypeScript (tsc --noEmit) — compiler will flag any remaining type errors