Angular migration to version 1.0

This guide covers migrating @gp-grid/angular from 0.23.x to 1.0. It focuses on the component integration; use the shared core migration reference for custom adapters and the complete imperative API mapping.

Upgrade packages

bun add @gp-grid/angular@^1.0.0

Upgrade any other installed @gp-grid/* packages together. Keep importing the stylesheet once:

import "@gp-grid/angular/dist/styles.css";

Angular >=18 remains supported. Use the standalone GpGridComponent.

The package no longer exports internal components: GridHeaderComponent, GridBodyComponent, GridOverlaysComponent, FilterPopupComponent, CellPeekComponent, and ResizeHandleComponent. Their pointer/sort event types, ActiveFilterPopup, EditingCellState, ResizeAxis, RowClassFn, and CellClassFn are also removed.

For custom renderers, keep using GroupLabelComponent, GroupToggleComponent, and the public template and registry types. GpGridComponent renders its internal components itself.

Events carry identity

Interaction callbacks now receive one object with stable identity and named view indices. There is no compatibility adapter for positional arguments or the old payloads.

Keep the existing output bindings: (onColumnResized), (onColumnMoved), and (onRowDragEnd). Change the handler payloads.

handleColumnResized({ colIndex, newWidth }: { colIndex: number; newWidth: number }) {
  persistWidth(colIndex, newWidth);
}
handleColumnMoved({ fromIndex, toIndex }: { fromIndex: number; toIndex: number }) {
  persistOrder(fromIndex, toIndex);
}
handleRowDragEnd({ source, target }: { source: number; target: number }) {
  this.dataSource.moveRow?.(source, target);
}

import type { ColumnResizedEvent, ColumnMovedEvent, RowDragEndEvent } from "@gp-grid/angular";

handleColumnResized({ columnId, width, viewIndex }: ColumnResizedEvent) {
  persistWidth(columnId, width, viewIndex);
}
handleColumnMoved({ columnId, fromViewIndex, toViewIndex }: ColumnMovedEvent) {
  persistOrder(columnId, fromViewIndex, toViewIndex);
}
handleRowDragEnd({ fromViewIndex, toViewIndex }: RowDragEndEvent) {
  this.dataSource.moveRow?.(fromViewIndex, toViewIndex);
}

RowDragEndEvent also includes rowId. Column indices describe the resolved layout; persist state by identity. CellValueChangedEvent now includes columnId. A resize with no committed change fires no event.

Column definitions and column state

Definitions are immutable inputs. The core owns live order, widths, visibility, and pins by colId ?? field. Remove code that depends on the grid mutating a definition or requires you to reorder the columns array after a drag. A column-move callback is a notification of the committed move.

Use the controlled columnState input for explicit overrides:

<gp-grid [columns]="columns" [columnState]="[{ columnId: 'city', width: 240 }]" [rowData]="data" [rowHeight]="36" />

Replacing columns keeps the core instance and retains state, sorting, and filtering for surviving column ids. Removed ids lose their state. Definition changes apply only where no user override exists.

To save state, read core.columns.getState(). To restore a saved snapshot after further edits, call core.columns.resetState() before core.columns.setState(savedState). width is an explicit override; resolvedWidth is output-only and is zero while hidden. Invalid widths fall back to 50 px.

Imperative API access

Access the component through a template ref or view query, then use its public core getter.

grid.core?.setSort("name", "asc");
grid.core?.startEdit(0, 1);

grid.core?.sortFilter.setSort("name", "asc");
grid.core?.edit.start(0, 1);

Other common moves are getRowCount() → rows.getCount(), getRowData(i) → rows.getData(i), and setCellValue(row, col, value) → cells.setValue(row, col, value). There are no root-level forwarding methods. See the complete namespace mapping.

Editing, writes, and refresh

• Editor commits are coerced by cellDataType: a number-column draft "60000" stores 60000. An invalid draft writes nothing and reports type-mismatch through (onWriteRejected).
• (onWriteCommitted) reports one event per edit, paste, fill, or programmatic write, including skipped targets. It requires getRowId; the [history] input with { maxEntries } enables bounded undo and redo and also requires getRowId.
• Columnar sources are read-only. Group and total rows cannot be edited; writes report not-a-record. Row dragging is disabled while a hierarchy is bound.
• core.rows.getData(i) returns a resident source record only. Use getViewRow(i) and narrow on kind before reading a hierarchical record; columnar rows have no materialized record.
• Mutable source subscriptions are handled by the wrapper. Update-only transactions redraw changed rows without a query, preserving row position even if a sorted or filtered field changes. Call core.refresh() to re-sort or re-filter immediately. Adds, removes, and clearing reload the view.

Labels, sizing, and server rendering

GridLabelOverrides remains partial. A full GridLabels object must add pinLeftColumn, pinRightColumn, unpinColumn, frozenRowsLimited, columnSchemaErrors, and rowGroups including loadFailed.

The header stays fixed. Cells fill their row height through the shipped stylesheet; remove custom inline cell heights that conflict with the row box. Rows resize only through application commands, gestures, or one-shot fit, rather than growing automatically with content.

Pass initialWidth and initialHeight for server rendering. Controlled columnState and columnLayout seed the initial layout. Header bands use configured heights until client measurements refine them.

ARIA row indices include header bands, and aria-rowcount includes the headers. Hierarchical views use role="treegrid", and core.rows.getCount() includes groups and totals. Sort, filter-popup, and pin header controls remain pointer-only.

Shared core changes

Review the core migration reference if you consume geometry, instructions, complete label objects, saved filters, or custom adapter types. It covers exclusive window ends, required slot heights and row regions, removed exports, schema command return values, and legacy filter normalization.

Source: upstream migration guide.