Class: PivotController<TRow>

Framework-agnostic pivot grid controller.

Orchestrates field management, engine computation (via Web Worker), state persistence, export, and event emission. Consumed by React/Angular adapters.

Type Parameters

TRow

TRow

Shape of source data rows.

Constructors

Constructor

new PivotController<TRow>(options): PivotController<TRow>

Parameters

options

PivotControllerOptions<TRow>

Returns

PivotController<TRow>

Properties

getSnapshot

getSnapshot: () => PivotControllerState<TRow>

Returns

PivotControllerState<TRow>

subscribe: (listener) => () => void

Parameters

listener

PivotStateListener

Returns

() => void

Methods

applyFilter()

applyFilter(fieldId, selectedValues, filterType): void

Parameters

fieldId

string

selectedValues

Set<any>

filterType

"include" | "exclude"

Returns

void

applyPersistedState()

applyPersistedState(state): boolean

Put a getPersistedState snapshot back. Fields the app no longer has are dropped (calculated fields the reader made stay); fields the app added since join as it defines them. Returns false and changes nothing when the snapshot cannot be read — another version, or not a state at all.

Parameters

state

unknown

Returns

boolean

applyTransaction()

applyTransaction(transaction): PivotTransactionResult

Add, update and remove rows without rebuilding the pivot (live updates).

Only the changed rows are encoded and sent to the worker, which regroups them and re-sums the groups they touched; the result is the pivot a rebuild from the new rows gives. Rows are matched by rowKey (by object identity without one). An update for a key the grid does not have is ignored; a remove wins over an update of the same row; adds go to the end — the DataGrid's semantics. getRawData() returns the new rows at once; the recomputed pivot follows (listen for engineCompleted).

Parameters

transaction

PivotRowTransaction<TRow>

Returns

PivotTransactionResult

applyTransactionAsync()

applyTransactionAsync(transaction, callback?): void

Queue a transaction for a feed that ticks faster than anyone can look. Every applyTransaction scans the rows for the keys it names and sends the worker a message; a hundred ticks in a moment is a hundred of each for one picture. Queued ones are merged and applied together after asyncTransactionWait ms (default 50), or at once on flushAsyncTransactions(). The callback runs when its batch has been applied. A synchronous applyTransaction or setData applies the queue first; dispose drops it.

Parameters

transaction

PivotRowTransaction<TRow>

callback?

() => void

Returns

void

calculateDropIntent()

calculateDropIntent(pointerX, pointerY, itemRect, previousIntent, isLastItem, orientation): DropIntent

Parameters

pointerX

number

pointerY

number

itemRect

cancelImport()

cancelImport(): void

Cancel an in-flight import started by importFile/importFiles/importFromUrl.

Returns

void

cancelImportPreview()

cancelImportPreview(): void

Discard a pending previewed import without applying it.

Returns

void

changeFieldArea()

changeFieldArea(fieldId, area): void

Parameters

fieldId

string

area

PivotArea

Returns

void

clearAllSorting()

clearAllSorting(): void

Returns

void

clearFilter()

clearFilter(fieldId): void

Parameters

collapseColPaths()

collapseColPaths(paths): void

Parameters

paths

string[]

Returns

void

collapsePaths()

collapsePaths(paths): void

Parameters

paths

string[]

Returns

void

commitDrag()

commitDrag(fieldId, overId): Promise<void>

Parameters

fieldId

string

overId

string | null

Returns

Promise<void>

commitImport()

commitImport(plan, labels): void

Commit a previewed import using the reviewed column plan (include/exclude, caption + type overrides). Columns whose type changed are re-coerced.

Parameters

plan

PivotImportField & object[] | undefined

labels

PivotImportLabels

Returns

void

deleteField()

deleteField(fieldId): void

Parameters

fieldId

string

Returns

void

deleteReport()

deleteReport(id): void

Parameters

id

string

Returns

void

dispose()

dispose(): void

Returns

void

expandAll()

expandAll(): Promise<void>

Expand one more level across the whole tree. A search or the column cap cuts the tree on screen, so then the uncut one is computed and walked: walking the cut one left every member the search hid closed, and every column past the cap. Resolves when the new paths are set.

Returns

Promise<void>

expandColPaths()

expandColPaths(paths): void

Parameters

paths

string[]

Returns

void

expandPaths()

expandPaths(paths): void

Parameters

paths

string[]

Returns

void

exportData()

exportData(format, options?): Promise<void>

Parameters

format

string

options?

ExportOptions

Returns

Promise<void>

flushAsyncTransactions()

flushAsyncTransactions(): void

Apply the queued transactions now, as one.

Returns

void

getAreaFields()

getAreaFields(area): PivotField<TRow, PivotCellTemplate, any>[]

Parameters

area

PivotArea

Returns

PivotField<TRow, PivotCellTemplate, any>[]

getCell()

getCell(rowPath, colPath): PivotCell<any> | null

Parameters

rowPath

string[]

colPath

string[]

Returns

PivotCell<any> | null

getEngineResult()

getEngineResult(): PivotEngineResult | null

Returns

PivotEngineResult | null

getPendingAsyncTransactionCount()

getPendingAsyncTransactionCount(): number

How many transactions are waiting to be applied.

Returns

number

getPersistedState()

getPersistedState(options?): PersistedPivotState

Everything the reader arranged, as plain JSON — fields and their areas, order, sorting, filters, summaries and calculated fields; totals, layout options and the chart type; open members; column widths — with a version. What stateStoring saves; keep it anywhere and hand it back to applyPersistedState.

Parameters

options?

importData()

importData(rows, labels): Promise<void>

Import an already-materialized array of rows (e.g. an API response).

Parameters

rows

any[]

labels

PivotImportLabels

Returns

Promise<void>

importFile()

importFile(file, labels): Promise<void>

Import a single uploaded file (worker-streamed for CSV/JSON/XML).

Parameters

file

File

labels

PivotImportLabels

Returns

Promise<void>

importFiles()

importFiles(files, labels): Promise<void>

Import one or more files at once, appending their rows (union fields).

Parameters

files

FileList | File[]

labels

PivotImportLabels

Returns

Promise<void>

importFromUrl()

importFromUrl(url, labels, fetchInit?): Promise<void>

Import data fetched from a URL / backend API endpoint.

Parameters

url

string

labels

PivotImportLabels

fetchInit?

RequestInit

Returns

Promise<void>

importText()

importText(text, labels): Promise<void>

Import delimited text pasted from the clipboard (auto-detects CSV/TSV).

Parameters

text

string

labels

PivotImportLabels

Returns

Promise<void>

isEnterpriseEdition()

isEnterpriseEdition(): boolean

Returns

boolean

loadReport()

loadReport(id): void

Parameters

id

string

Returns

void

moveField()

moveField(fieldId, direction): void

Parameters

fieldId

string

direction

"start" | "end" | "left" | "right"

Returns

void

notifyStatePartChanged()

notifyStatePartChanged(): void

A part registered with registerReportStatePart changed: save it with the state (stateStoring). The Enterprise chart panel's changes do this by themselves.

Returns

void

on()

on<K>(eventName, handler): () => void

Type Parameters

K

K extends keyof PivotControllerEvents<TRow>

Parameters

eventName

K

handler

(payload) => void

Returns

() => void

refreshEngine()

refreshEngine(): void

Returns

void

registerReportStatePart()

registerReportStatePart(key, part): () => void

Keep a piece of state owned outside the core inside saved reports — the Enterprise chart panel keeps its chart this way. Order-independent: the default report loads while the controller is constructed, BEFORE any Enterprise layer has mounted, so a part loaded before its owner registers is held and handed over on registration. Returns the unregister function.

Parameters

key

string

part

ReportStatePart

Returns

() => void

removeField()

removeField(fieldId): void

Parameters

fieldId

string

Returns

void

reportChartState()

reportChartState(state, chartId?): void

The chart panel's state, now. The controller turns it into chartOpened / chartChanged / chartClosed — call it after every change, as often as convenient: the same state twice is one event, and edits while the panel is closed arrive with the next chartOpened.

Parameters

state

PivotChartState

chartId?

string

Returns

void

reportScroll()

reportScroll(top, left): void

Where the renderer's body is scrolled — both renderers report it, so a snapshot with include: ['scroll'] can carry it.

Parameters

top

number

left

number

Returns

void

resetDrag()

resetDrag(): void

Returns

void

resolveCellClick()

resolveCellClick(event): CellClickEvent<TRow>

The click event with the source rows behind the cell as records.

Resolved on first READ, not on the click (6d-16): the rows are found by a scan of the whole dataset on the main thread, 0.3-0.5 s per click on a million rows, and a click handler that never reads them paid it anyway. The scan matches the cell's path first and runs the filters only on the rows that matched — every filter judges one row at a time, so the order does not change the result, and a cell is usually a sliver of the data.

Parameters

event

CellClickEvent<TRow>

Returns

CellClickEvent<TRow>

saveReport()

saveReport(name, isDefault): void

Parameters

name

string

isDefault

boolean

Returns

void

setColumnWidths()

setColumnWidths(widths): void

Parameters

widths

Record<string, number>

Returns

void

setData()

setData(data): void

DropIntent

Returns

void

setEnterpriseEdition()

setEnterpriseEdition(on): void

Which edition is driving this controller. Set by the React adapter from the flag EnterprisePivotGrid passes; Community never turns it on.

The engine keeps the capability either way — the pipeline is one piece and an edition boundary that tried to cut through it would be a fork, not a gate. What the flag decides is what the controller AGREES to do.

setSearchText(text): void

Quick search: show only the row members whose caption contains text (ignoring case and accents), with the members above them. A view on top of the reader's filters, not one of them — '' gives the view back.

Parameters

text

string

Returns

void

setSelectionStats()

setSelectionStats(selectionStats): void

Parameters

selectionStats

PivotSelectionStats | null

Returns

void

showFields()

showFields(fieldIds): void

Take several fields out of the chooser in ONE commit.

The routing rule is the field chooser's checkbox rule — a number is a measure, anything else describes a row — and it lives here so the vanilla chooser, the React chooser and the Angular one cannot drift on it.

Parameters

fieldIds

string[]

Returns

void

showImportStatus()

showImportStatus(status, title, messages): void

Show a terminal import status message (e.g. clipboard empty / permission denied).

Parameters

status

"success" | "error" | "warning"

title

string

messages

string[]

Returns

void

sortField()

sortField(fieldId, direction): void

Parameters

fieldId

string

direction

"asc" | "desc" | undefined

Returns

void

sortFieldBySummary()

sortFieldBySummary(rowFieldId, summaryFieldId, colPath): void

Parameters

rowFieldId

string

summaryFieldId

string

colPath

string

Returns

void

toggleColExpanded()

toggleColExpanded(path): void

Parameters

path

string

Returns

void

toggleExpanded()

toggleExpanded(path): void

Parameters

path

string

Returns

void

updateCurrentReport()

updateCurrentReport(): void

Returns

void

updateField()

updateField(updatedField): void

Parameters

updatedField

PivotField<TRow>

Returns

void

updateOptions()

updateOptions(options): void

Parameters

options

Partial<PivotControllerOptions<TRow>>

Returns

void