DocsAPI reference

Pivot designer state

The fields, layouts and presets behind the pivot designer, and the pure functions that change a layout.

rowpine 1.0.3Generated from the package's type definitions

`PivotField<T = Record<string, unknown>>`

type

One field the designer offers. Dimensions land in Rows by default; measures in Values.

Properties

Name	Type	Description
`field`	`keyof T & string`	Key of the field in each data row.
`label`	`string`	Name shown in the field list and on chips.
`kind`	`"dimension" \| "measure"`	'dimension' may go to Rows, Columns or Filters; 'measure' to Values or Filters.
`group`optional	`string`	Optional group heading in the field list, e.g. 'Customer'.
`format`optional	`((value: unknown) => string)`	Display text for this field's values when it is a measure.
`defaultAgg`optional	`PivotAggregatorId`	Aggregation used when the field is added to Values. Default 'sum' for measures.

`PivotLayout`

type

The whole designer state, as plain JSON.

Properties

Name	Type	Description
`rows`	`string[]`	Fields in the Rows well, outer-most first.
`cols`	`string[]`	Fields in the Columns well, outer-most first.
`values`	`PivotValueChip[]`	Chips in the Values well, in column order.
`filters`	`PivotFilterChip[]`	Chips in the Filters well.
`hideSubtotals`optional	`boolean`	Show no numbers on group rows. The group rows stay and still expand and collapse.
`hideGrandTotals`optional	`boolean`	Hide the grand-total row and column.

`PivotPreset`

type

A saved layout offered in the designer's Presets menu.

Properties

Name	Type	Description
`name`	`string`	Name shown in the Presets menu.
`layout`	`PivotLayout`	The layout applied when the preset is picked.

`PivotValueChip`

type

A chip in the Values well.

Properties

Name	Type	Description
`field`	`string`	The field it aggregates.
`agg`	`PivotAggregatorId`	How it aggregates the field.
`label`optional	`string`	Column header. The designer functions set it to e.g. 'Sum of Amount'; when missing, the pivot uses that form.

`PivotFilterChip`

type

A chip in the Filters well. allowed: null lets every value through.

Properties

Name	Type	Description
`field`	`string`	The field it filters on.
`allowed`	`string[] \| null`	Values that pass, compared as text (`String(value)`). An empty array lets nothing through.

`Well`

type

One of the designer's four wells.

Type

type Well = 'rows'
  | 'cols'
  | 'values'
  | 'filters'

`EMPTY_LAYOUT`

constant

A layout with every well empty.

Type PivotLayout

`ALL_AGGREGATORS`

constant

Every built-in aggregator id, in the order the designer lists them.

Type PivotAggregatorId[]

`AGG_LABEL`

constant

Display name of each aggregator, e.g. 'Average' for 'avg'. Value chip labels are built from it.

Type Record<PivotAggregatorId, string>

`KIND_WELLS`

constant

Which wells each kind of field may go to.

Type Record<"dimension" | "measure", Well[]>

`WELL_LABEL`

constant

Display name of each well: 'Rows', 'Columns', 'Values', 'Filters'.

Type Record<Well, string>

`defaultLayoutFor`

function

First dimension in Rows, first measure in Values (with its defaultAgg, else 'sum').

Signature

defaultLayoutFor<T>(fields: ReadonlyArray<PivotField<T>>) => PivotLayout

Parameters

Name	Type	Description
`fields`	`readonly PivotField<T>[]`	The fields the designer offers.

Returns

PivotLayout

`defaultWellFor`

function

The well a field goes to when added without one: Values for a measure, Rows otherwise.

Signature

defaultWellFor(field: Pick<PivotField, "kind">) => Well

Parameters

Name	Type	Description
`field`	`Pick<PivotField<Record<string, unknown>>, "kind">`	The field, or anything with its `kind`.

Returns

Well

`layoutToConfig`

function

The engine config for a layout. Value labels come from the chips, and a measure's format is used except on count and distinct count. hideSubtotals and hideGrandTotals turn off the matching config switches.

Signature

layoutToConfig<T>(
  layout: PivotLayout,
  fields: ReadonlyArray<PivotField<T>>,
) => PivotConfig<T>

Parameters

Name	Type	Description
`layout`	`PivotLayout`	The layout.
`fields`	`readonly PivotField<T>[]`	The fields the designer offers, for labels and formats.

Returns

PivotConfig<T>

`pivotFromLayout`

function

Filter, pivot and label in one step. Returns null when the layout has no values yet, which a UI shows as an empty state. Runs createPivot, so without a license key it logs a notice once.

Signature

pivotFromLayout<T>(
  data: ReadonlyArray<T>,
  layout: PivotLayout,
  fields: ReadonlyArray<PivotField<T>>,
  opts?: ToColumnsOptions,
) => PivotTable | null

Parameters

Name	Type	Description
`data`	`readonly T[]`	The source rows. Not changed.
`layout`	`PivotLayout`	The layout to build.
`fields`	`readonly PivotField<T>[]`	The fields the designer offers. Their labels name the row-header column.
`opts`optional	`ToColumnsOptions`	Settings for every value column, such as an Excel number format.

Returns

PivotTable | null

`applyLayoutFilters`

function

The rows that pass the layout's filters. Returns a new array.

Signature

applyLayoutFilters<T>(data: ReadonlyArray<T>, layout: PivotLayout) => T[]

Parameters

Name	Type	Description
`data`	`readonly T[]`	The source rows. Not changed.
`layout`	`PivotLayout`	The layout whose Filters well applies.

Returns

T[]

`addToWell`

function

Add a field to a well at index (default: the end). In Rows, Columns and Filters a field appears at most once, so adding it moves it. In Values the same field may appear with different aggregations (sum and average of one amount), but not twice with the same one. sourceIndex is the chip's position in Values when it is being moved out of that well. Returns the layout unchanged when field is not in fields.

Signature

addToWell<T>(
  layout: PivotLayout,
  fields: ReadonlyArray<PivotField<T>>,
  field: string,
  well: Well,
  index?: number,
  sourceIndex?: number,
) => PivotLayout

Parameters

Name	Type	Description
`layout`	`PivotLayout`	The current layout. Not changed.
`fields`	`readonly PivotField<T>[]`	The fields the designer offers.
`field`	`string`	Key of the field to add.
`well`	`Well`	The well to add it to.
`index`optional	`number`	Position in the well. Default: the end.
`sourceIndex`optional	`number`	When moving a chip out of Values, its position there. A chip moved within Values keeps its aggregation.

Returns

PivotLayout

`removeFromWell`

function

Remove a field from a well. In Values, valueIndex picks the one chip.

Signature

removeFromWell(
  layout: PivotLayout,
  field: string,
  well: Well,
  valueIndex?: number,
) => PivotLayout

Parameters

Name	Type	Description
`layout`	`PivotLayout`	The current layout. Not changed.
`field`	`string`	Key of the field to remove.
`well`	`Well`	The well to remove it from.
`valueIndex`optional	`number`	In Values, the chip's position. Without it every chip of the field is removed.

Returns

PivotLayout

`clearWell`

function

Empty one well.

Signature

clearWell(layout: PivotLayout, well: Well) => PivotLayout

Parameters

Name	Type	Description
`layout`	`PivotLayout`	The current layout. Not changed.
`well`	`Well`	The well to empty.

Returns

PivotLayout

`toggleField`

function

Field-list checkbox: take the field out of every well, or add it to its default well.

Signature

toggleField<T>(
  layout: PivotLayout,
  fields: ReadonlyArray<PivotField<T>>,
  field: string,
) => PivotLayout

Parameters

Name	Type	Description
`layout`	`PivotLayout`	The current layout. Not changed.
`fields`	`readonly PivotField<T>[]`	The fields the designer offers. A field not in it leaves the layout unchanged.
`field`	`string`	Key of the field to toggle.

Returns

PivotLayout

`isFieldInLayout`

function

True when the field is in any well.

Signature

isFieldInLayout(layout: PivotLayout, field: string) => boolean

Parameters

Name	Type	Description
`layout`	`PivotLayout`	The current layout.
`field`	`string`	The field key.

Returns

boolean

`setAggregatorAt`

function

Change a value chip's aggregation. A change that would duplicate another chip removes this one. The chip's label is rebuilt from the new aggregation.

Signature

setAggregatorAt<T>(
  layout: PivotLayout,
  fields: ReadonlyArray<PivotField<T>>,
  index: number,
  agg: PivotAggregatorId,
) => PivotLayout

Parameters

Name	Type	Description
`layout`	`PivotLayout`	The current layout. Not changed.
`fields`	`readonly PivotField<T>[]`	The fields the designer offers, for the label.
`index`	`number`	The chip's position in Values. Out of range leaves the layout unchanged.
`agg`	`PivotAggregatorId`	The new aggregation.

Returns

PivotLayout

`setFilterAllowed`

function

Set which values of a filter field pass. null lets everything through.

Signature

setFilterAllowed(
  layout: PivotLayout,
  field: string,
  allowed: string[] | null,
) => PivotLayout

Parameters

Name	Type	Description
`layout`	`PivotLayout`	The current layout. Not changed.
`field`	`string`	Key of a field in the Filters well. Any other field has no effect.
`allowed`	`string[] \| null`	The values that pass, as text, or null for all.

Returns

PivotLayout

`distinctValues`

function

Every distinct value of a field in the full data, as text, sorted.

Signature

distinctValues<T>(data: ReadonlyArray<T>, field: string) => string[]

Parameters

Name	Type	Description
`data`	`readonly T[]`	The source rows.
`field`	`string`	The field key.

Returns

string[]

Was this page helpful?