Plugin Lifecycle

PivotPlugin is the runtime layer that turns the direct grid.pivot config into rendered rows, generated columns, and grouped state. Understanding its lifecycle helps you persist user choices, avoid conflicting updates, and reason about when Pivot owns the grid payload.

Activation

Pivot activates when:

PivotPlugin is present in grid.plugins
grid.pivot contains a config

The plugin observes the direct pivot property and reapplies Pivot whenever the config changes. Legacy additionalData.pivot updates are still supported for compatibility.

What Happens On Apply

When applyPivot runs:

the plugin captures the original source, columns, grouping, and pinned-bottom rows on first activation
it decides whether to use the client or server execution path
it generates or loads Pivot rows and columns
it writes those generated structures back to the grid

This means Pivot is temporarily the owner of the rendered grid payload.

Client Path

In client mode:

raw grid source is read from the captured original data
createPivotData materializes Pivot rows
pivotColumns generates the column tree
grand total rows are moved to pinnedBottomSource

Server Path

In server mode:

the plugin resolves a PivotEngineAdapter
it builds a PivotLoadRequest
it aborts any stale in-flight remote request
only the latest response is allowed to update the grid

This is the last-write-wins behavior that protects the UI when filters or layouts change quickly.

Configurator Integration

If hasConfigurator is enabled, the plugin renders the configurator and wires its updates back into the Pivot state. Each configurator update:

emits pivot-config-update
applies the updated config unless the event was prevented

`pivot-config-update`

This event is the main integration point for external state ownership.

Use it to:

persist layout changes
sync Pivot state into a framework store
restore expanded or collapsedColumns later

Reapplication Triggers

Pivot recalculates when:

grid.pivot changes
legacy additionalData.pivot changes
the underlying non-Pivot source changes
the underlying non-Pivot columns change
row drill-down or column collapse state changes through plugin-managed interactions

The plugin intentionally avoids treating already-generated Pivot rows or columns as new base inputs.

Clearing Pivot

clearPivot():

aborts any remote load
removes managed Pivot state
restores the original source, columns, grouping, and pinned-bottom rows

Removing grid.pivot has the same practical effect. Removing legacy additionalData.pivot also clears Pivot when that legacy path is the active source.

Best Practices

Treat direct grid.pivot / framework pivot binding as the durable state you own.
Listen to pivot-config-update if user changes should persist.
Do not manually overwrite grid.source or grid.columns with Pivot active unless you mean to replace the base data and trigger a reapply.