Pivot Grid API

Complete API reference for @oge-ui/pivot. The aggregation engine (PivotEngine, field configs, the remote OgePivotStore contract) is pure TypeScript in @oge-ui/core; live demos are on the overview and analytics pages.

Properties Methods Events Types

OgePivotGrid

oge-pivot-grid

Properties 12

Name	Type	Default	Description
`data`	`readonly T[] \| OgePivotStore<T>`	`[]`	Local rows, or any `OgePivotStore` for remote (pre-aggregated) data.
`fields`	`readonly OgePivotFieldDef<T>[]`	`[]`	Fields as data — the programmatic twin of `<oge-pivot-field>` children (same members), appended after them. Use it when the grid is wrapped in another component, where content queries cannot see projected children.
`virtualScrolling`	`boolean`	`false`	Two-axis fixed-track windowing.
`showRowTotals / showColumnTotals`	`boolean`	`true`	Sub-total lines per axis.
`showRowGrandTotals / showColumnGrandTotals`	`boolean`	`true`	Grand-total lines per axis.
`fieldPanel`	`boolean`	`true`	Collapsible drag & drop field panel. Chips move with a pointer drag (mouse, pen, touch after a ~300 ms long press); dropping on a chip inserts in front of it, Escape cancels.
`fieldChooser`	`OgePivotFieldChooserOptions`	`{}`	Field-chooser dialog behavior.
`customizeCell`	`(cell: OgePivotCellPrepared) => void`	—	Appearance hook: mutate `text` / `cssClass` per cell (the reference `cellPrepared` equivalent).
`calculatedFields`	`readonly OgePivotCalculatedField[]`	`[]`	Measures computed from the other measures of each cell — `{ name, caption, expression: (values) => number \| null, format, displayMode, runningTotal }`. Evaluated on every cell, subtotals and grand totals included, so a ratio stays a ratio of the totals. `displayMode` takes the measure display modes (percent of row / column / grand total, `absoluteVariation` = difference from the previous column, `percentVariation`); `runningTotal` accumulates along an axis. They follow the regular measures in cells, exports and chart data.
`rowHeaderLayout`	`'compact' \| 'outline' \| 'tabular'`	`'compact'`	`compact` indents every level in one column; `outline` gives each row field its own label column (a label only in its field’s column); `tabular` repeats the ancestors on every line so each reads on its own. The row header stays one `rowheader` cell per line, so the keyboard model does not change; the corner shows the row field captions.
`stateKey`	`string \| undefined`	—	Persists the field layout + expansion via `OGE_STATE_STORAGE`.
`messages`	`Partial<OgePivotMessages>`	`{}`	Per-instance overrides of the UI strings.

Methods 10

Name	Type	Description
`getResult(): PivotResult`	`PivotResult`	The materialized pivot exactly as rendered — for custom export integrations.
`getChartData(options?): OgePivotChartData`	`OgePivotChartData`	The current view as chart data — `{ dataSource, series }` for `<oge-chart>` / `<OgeChart>`: one argument per visible row line (the deepest expanded level), one series per column line × measure. Options: `argumentAxis`, `measures`, `includeTotals`, `includeGrandTotals`, `argumentIndexes` / `seriesIndexes` (a selection), `type`. The pivot does not depend on the charts package — the app binds the two.
`getPreparedCell(rowIndex, columnIndex, measureIndex): OgePivotCellPrepared`	`OgePivotCellPrepared`	A value cell exactly as rendered: text after formats, display modes and `customizeCell`.
`getRowFieldCaptions() / getRowHeaderLayout()`	`readonly string[] / 'compact' \| 'outline' \| 'tabular'`	The row field captions in layout order and the effective row-header layout — what the PDF export writes its row header from.
`drillDown(args: PivotDrillDownArgs): T[]`	`T[]`	Raw rows behind a cell (local data only).
`expandAll(area: 'row' \| 'column') / collapseAll(area)`	`void`	Axis-wide expansion; remote mode expands only what is loaded.
`getFieldLayout(): readonly PivotFieldConfig[]`	`readonly PivotFieldConfig[]`	Declared fields merged with user overrides.
`showFieldChooser(): void`	`void`	Opens the field-chooser dialog.
`state() / applyState(snapshot)`	`PivotGridStateSnapshot / void`	Field layout + expansion snapshot. `applyState` validates the snapshot first (`sanitize*StateSnapshot`): unknown keys are dropped, prototype keys rejected, wrong types skipped — invalid input is ignored, never thrown.
`getCsv(options?) / exportCsv(filename?)`	`string / void`	CSV of exactly what is on screen (multi-level headers flattened).Cells a spreadsheet would evaluate as a formula are apostrophe-prefixed (CSV formula injection); `formulaGuard: false` opts out.

Events 4

Name	Type	Description
`cellClick / cellDblClick`	`OgePivotCellClickEvent`	`{ rowPath, columnPath, measureIndex, value, event }`.
`fieldLayoutChange`	`readonly PivotFieldConfig[]`	The field layout changed (drag, chooser, menus).
`resultChange`	`PivotResult`	The materialized view changed (data, layout, expansion, filters, calculated fields) — the hook a linked chart re-reads `getChartData()` from.
`stateChange`	`PivotGridStateSnapshot`	Debounced — the persistable state changed.

Types 37

Cell & axis types

Name	Type	Default	Description
`OgePivotCellPrepared`	`{ rowPath, columnPath, measureId, isTotal, isGrandTotal, value; mutable text, cssClass? }`	—	Args of the `customizeCell` hook.
`OgePivotAxisLine`	`{ text, path, level, expanded, hasChildren, isTotal, isGrandTotal }`	—	One visible axis line, in matrix order.
`OgePivotHeaderCell`	`OgePivotAxisLine & { rowStart, rowEnd, columnStart, span }`	—	Header cell with 1-based matrix coordinates.
`OgePivotFieldDef`	`{ dataField; id?, caption?, area?, … every <oge-pivot-field> input }`	—	Element type of `fields` — one declared field as data, with the directive’s defaults.
`OgePivotFieldChooserOptions`	`{ applyChangesMode?: 'instantly' \| 'onDemand' }`	—	Field-chooser behavior; `'onDemand'` edits a draft that applies on Apply.
`OgePivotMenuItem`	`{ text, disabled?, active?, action? }`	—	One item of the header / field context menus.
`OGE_PIVOT_FIELD_DRAG_TYPE`	`'application/x-oge-pivot-field'`	—	Deprecated — field chips no longer use HTML5 drag and drop (pointer drag, touch included); kept so existing imports compile.
`OgePivotFieldDropTarget`	`{ area: PivotArea \| null, beforeId: string \| null }`	—	Where a dragged field chip would land: the area (`null` = the chooser list) and the chip it is inserted in front of (`null` = the end).
`OgePivotFieldPointerInput`	`{ button, clientX, clientY, pointerId, pointerType?, target, preventDefault() }`	—	The `pointerdown` facts the engine core reads to start a chip drag — the native or the React synthetic event.

Keyboard (WAI-ARIA APG grid + field chips)

Name	Type	Default	Description
`Tab`	`grid`	—	The matrix is one APG grid with a single tab stop shared by column headers, row headers and value cells (the first value cell until something is focused).
`Arrow keys`	`grid`	—	Move between headers and value cells; a spanning column header is one stop, and Down out of it keeps the column you came from. Left/Right are mirrored in RTL.
`Home / End · Ctrl+Home / Ctrl+End`	`grid`	—	First / last cell of the row · first column header / last value cell of the grid.
`Enter / Space (header)`	`grid`	—	Expands or collapses an expandable row or column header.
`Shift+F10 / ContextMenu (header)`	`grid`	—	Opens the header menu (sort, sort by summary, filter, remove, expand/collapse all, field chooser) — the keyboard right-click.
`Enter / Space / Shift+F10 (field chip)`	`field panel + chooser`	—	Every field chip is a focusable `role="button"` with `aria-haspopup="menu"`; these keys (and right-click) open its field menu: Move left / Move right, Move to Filters / Rows / Columns / Values, Remove field, and on a measure the summary-type and display-mode items. The single-pointer alternative to dragging (WCAG 2.5.7).
`Ctrl+Left / Ctrl+Right (field chip)`	`field panel + chooser`	—	Reorders the field within its area (mirrored in RTL); the new position is announced in a polite live region.
`Ctrl+Up / Ctrl+Down (field chip)`	`field panel + chooser`	—	Moves the field to the end of the previous / next area in panel order (Filters, Rows, Columns, Values).
`Delete (field chip)`	`field panel + chooser`	—	Removes the field from the layout. In the chooser’s `onDemand` mode every move edits the draft until Apply.
`Up / Down / Home / End / Escape / Tab (menu)`	`menu`	—	APG menu keys over the enabled items; Escape and Tab close it and return focus to the chip or header that opened it (a moved chip is re-focused in its new area).

Accessibility messages

Name	Type	Default	Description
`moveToAreaPattern`	`string`	`'Move to {0}'`	Field-menu item; `{0}` is the area label.
`moveFieldLeft / moveFieldRight`	`string`	`'Move left' / 'Move right'`	Field-menu items reordering a field within its area.
`fieldMenuLabelPattern`	`string`	`'{0} field actions'`	Accessible name of the field menu; `{0}` is the caption.
`fieldMovedPattern`	`string`	`'{0} moved to {1}, position {2} of {3}'`	Live announcement after a move: field, area label, 1-based position, fields in the area.
`fieldRemovedPattern`	`string`	`'{0} removed from the layout'`	Live announcement after a field left the layout.

Configuration & engine

Name	Type	Default	Description
`provideOgePivotMessages(messages)`	`Provider`	—	App-scoped overrides of `OgePivotMessages` (41 keys — areas, menus, chooser, export, field-move menu and announcements…).
`PivotFieldConfig / PivotResult / PivotLoadOptions / OgePivotStore…`	`from @oge-ui/core`	—	The serializable engine contract lives in `@oge-ui/core`, not in this package.
`OgePivotCalculatedField / OgePivotCalculatedCell`	`{ name; caption?; expression(values, cell); format?; displayMode?; runningTotal? }`	—	A calculated measure; `expression` receives the cell’s measure values keyed by measure id (as displayed) and where it is evaluated (`rowPath`, `columnPath`, `isTotal`, `isGrandTotal`). Non-finite results and throws become an empty cell.
`OgePivotChartData / OgePivotChartOptions / OgePivotChartPoint / OgePivotChartSeries`	`interfaces`	—	What `getChartData()` / `toChartSeries()` return and take; each series is `{ type, name, argumentField: 'argument', valueField, measureId, path }` — assignable to the charts’ series input.
`toChartSeries(result, options?)`	`from @oge-ui/pivot-engine`	—	The pure adapter behind `getChartData()`, for a `PivotResult` you hold yourself.
`OgePivotLabelFilter / OgePivotValueFilter / OgePivotTopNFilter`	`interfaces`	—	The member filters of a row or column field.
`OgePivotLabelFilterOperator / OgePivotValueFilterOperator / OgePivotRowHeaderLayout`	`string unions`	—	The filter operators and the row-header layouts.
`OgePivotCellTemplateContext`	`OgePivotCellPrepared & { rowIndex; columnIndex; measureIndex }`	—	What a value-cell template receives.
`ogePivotCellTemplate / ogePivotRowHeaderTemplate / *ogePivotColumnHeaderTemplate`	`OgePivotCellTemplate / OgePivotRowHeaderTemplate / OgePivotColumnHeaderTemplate`	—	Structural template slots placed inside `<oge-pivot-grid>`: `let cell` (an `OgePivotCellTemplateContext`), `let line; rowIndex as r; segments as s`, `let cell` (an `OgePivotHeaderCell`). The expander and the keyboard model stay the grid’s.
`OgePivotCellTemplateOutletContext / OgePivotRowHeaderTemplateContext / OgePivotColumnHeaderTemplateContext`	`interfaces`	—	The three template contexts.
`exportPivotToPdf(grid, options?)`	`@oge-ui/pivot/export-pdf`	—	Lazy PDF export (optional `jspdf` + `jspdf-autotable` peers): the multi-level column headers repeated on every page, the grid’s own cell text, its row-header layout and field captions, bold totals, `title`, `pageHeader` / `pageFooter`, `pageNumbers`, `customizeCell`. `buildPivotPdfDocument(result, options)` for custom pipelines. Text outside WinAnsi (Turkish `ğ ş ı İ`, Central European, Greek, Cyrillic) needs a Unicode TrueType `font` — per export, or once for every PDF via `setOgePdfDefaultFont({ family, normal, bold })` from `@oge-ui/behavior`; without one the built-in Helvetica cannot draw it (a dev-mode warning says so).
`OgePivotPdfExportOptions / OgePivotPdfCell / OgePdfPageInfo`	`interfaces`	—	The PDF helper’s options, the mutable value cell its `customizeCell` receives (`text`, `style`) and what a page callback is told.
`exportPivotToExcel(grid, options?)`	`@oge-ui/pivot/export-excel`	—	Lazy Excel export with merged multi-level headers; `buildPivotWorkbook(result)` for custom pipelines.

OgePivotField

oge-pivot-field

Properties 21

Internals — not a supported API

Name	Type	Default	Description
`OgePivotStateStore`	`component-scoped service`	—	UI state of a pivot grid: field-layout overrides on top of the declared `<oge-pivot-field>` configuration, the expansion of both axes (kept as key → path so remote contracts get real paths back) and the field-panel collapse flag. Injected by the grid — applications should use `stateKey` or `state()`/`applyState()`.

Placement

Name	Type	Default	Description
`dataField`	`string (required)`	—	Source field; dotted paths supported.
`id`	`string \| undefined`	—	Stable field id (defaults to `dataField`).
`caption`	`string \| undefined`	—	Chip/header label.
`area`	`PivotArea \| null`	`null`	row \| column \| data \| filter; `null` keeps the field available in the chooser only.
`areaIndex`	`number \| undefined`	—	Order within the area.
`dataType`	`'string' \| 'number' \| 'date' \| 'boolean' \| undefined`	—	Drives group intervals and formatting.
`groupInterval`	`PivotGroupInterval \| undefined`	—	year/quarter/month/day/dayOfWeek or a numeric bucket size.

Measures (area="data")

Name	Type	Default	Description
`summaryType`	`SummaryType`	`'sum'`	sum/avg/min/max/count/custom.
`summaryName`	`string \| undefined`	—	Registered custom-summary name.
`summaryDisplayMode`	`PivotSummaryDisplayMode`	`'none'`	percent-of/running-total/variation post-processing.
`runningTotal`	`PivotRunningTotal \| undefined`	—	Running totals with per-group reset.
`calculateCustomSummary`	`CustomSummaryFn<T> \| undefined`	—	Out-of-band custom reducer.

Row/column fields

Name	Type	Default	Description
`sortOrder`	`SortDirection \| undefined`	—	Label sort.
`sortBySummaryField / sortBySummaryPath`	`string / PivotPath`	—	Sort by a summary value at an opposite-axis path.
`filterValues / filterType`	`readonly unknown[] / 'include' \| 'exclude'`	—	Field filter.
`showTotals`	`boolean`	`true`	Sub-totals for this field.
`selector / format / customizeText`	`functions`	—	Out-of-band value selector, display formatter and text hook.
`labelFilter`	`OgePivotLabelFilter \| undefined`	—	Keeps the members whose label matches — `{ operator: 'contains' \| 'notContains' \| 'beginsWith' \| 'endsWith' \| 'equals' \| 'notEquals', value }`, case- and accent-insensitive.
`valueFilter`	`OgePivotValueFilter \| undefined`	—	Keeps the members whose total of a measure passes — `{ measure, operator: 'greaterThan' \| 'greaterThanOrEqual' \| 'lessThan' \| 'lessThanOrEqual' \| 'equals' \| 'notEquals' \| 'between' \| 'notBetween', value, value2? }` (`measure` is a data field id).
`topN`	`OgePivotTopNFilter \| undefined`	—	Keeps the `count` members with the highest (`direction: 'top'`, default) or lowest total of `measure`. Member filters run before aggregation — totals follow — in area order; value and Top-N filters compare a member’s grand total (local data only).

Notes

The pivot has no two-way models — the field layout flows through declarative <oge-pivot-field> directives (or the [fields] data twin) plus user overrides, observable via (fieldLayoutChange) and getFieldLayout().
The reference cellPrepared callback maps to the customizeCell input; chart binding awaits a charting package (see ROADMAP).