Pivot

Module Extensions

PivotConfigTotals

interface PivotConfigTotals {
  /**
     * Show a grand total row and, when column dimensions exist, grand-total value columns.
     */
    grandTotal?: boolean;
  /**
     * Show subtotal rows and subtotal value columns for multi-level pivot hierarchies.
     */
    subtotals?: boolean;
  /**
     * Disable generated subtotal rows or columns for specific axis fields or
     * zero-based axis levels while keeping global subtotals enabled.
     */
    disabledSubtotals?: {
      rows?: PivotSubtotalDisableRule;
      columns?: PivotSubtotalDisableRule;
    };
  /**
     * Custom display label for the grand total row or value columns.
     */
    grandTotalLabel?: string;
  /**
     * Custom display label for subtotal rows or value columns.
     */
    subtotalLabel?: string;
  /**
     * Hide subtotal rows when a branch contains only one source-backed leaf and
     * the subtotal would duplicate that leaf.
     */
    suppressSingleChildSubtotals?: boolean;
  /**
     * Hide the grand-total row when the pivot contains only one source-backed
     * leaf and the total would duplicate that leaf.
     */
    suppressGrandTotalWhenSingleLeaf?: boolean
}

---

HTMLRevoGridElementEventMap (Extended from global)

interface HTMLRevoGridElementEventMap {
  /**
       * Event triggered when the pivot config is updated
       *
       * @example
       * ```typescript
       * grid.addEventListener(PIVOT_CFG_UPDATE_EVENT, (e) => {
       *   console.log(e);
       * });
       * ```
       */
      [PIVOT_CFG_UPDATE_EVENT]: PivotConfig
}

---

HTMLRevoGridElement (Extended from @revolist/revogrid)

interface HTMLRevoGridElement {
  /**
       * Direct Pivot configuration.
       */
      pivot?: Partial<PivotConfig>
}

---

AdditionalData (Extended from @revolist/revogrid)

interface AdditionalData {
  /**
       * Legacy additionalData property for Pivot.
       * @deprecated Use `grid.pivot` instead.
       *
       * @example
       * ```typescript
       * const grid = document.createElement('revo-grid');
       * grid.pivot = {
       *   dimensions: [
       *     { prop: 'name', aggregator: 'sum' },
       *   ],
       *   rows: ['name'],
       *   columns: ['age'],
       *   values: [{ prop: 'salary', aggregator: 'sum' }],
       * };
       * ```
       */
      pivot?: PivotConfig
}

Plugin API

PivotPlugin

The PivotPlugin is a RevoGrid plugin that enables dynamic creation and manipulation of pivot table structures within the grid. It provides users with the ability to configure and apply pivot transformations on grid data for enhanced reporting and analysis.

Key Features:

• Configurable Pivot Table – Allows users to define row, column, and value fields dynamically.
• Interactive Configurator – Integrates a pivot configurator panel to modify pivot settings in real-time.
• Drag-and-Drop Support – Enables users to rearrange fields via the configurator for a flexible pivot experience.
• Efficient Data Transformation – Utilizes optimized data processing to group and aggregate large datasets.
• Custom Aggregations – Supports multiple aggregation functions, including sum, count, avg, min, and max.
• Dynamic Theme Adaptation – Adjusts automatically to the applied RevoGrid theme.
• State Persistence – Observes direct grid.pivot and legacy additionalData.pivot configuration updates.

Usage:

• Instantiate the PivotPlugin in a RevoGrid instance and define a pivot configuration.
• Use applyPivot to generate a pivoted grid based on selected row, column, and value fields.
• Modify the pivot structure using the interactive configurator.
• Call clearPivot to restore the original grid state.

Example

import { PivotPlugin } from '@revolist/revogrid-pro';

const grid = document.createElement('revo-grid');
grid.plugins = [PivotPlugin];

grid.pivot = {
     dimensions: [{ prop: 'Age' }, { prop: 'City' }, { prop: 'Gender' }, { prop: 'Total Spend' }],
     rows: ['City', 'Age'],
     columns: ['Gender'],
     values: [
       { prop: 'Total Spend', aggregator: 'sum' },
     ],
     hasConfigurator: true,
};

This plugin is essential for users who require advanced pivot table functionalities within RevoGrid, offering comprehensive tools for data transformation and visualization.

Dependencies

• Required CorePlugin, PIVOT_CFG_UPDATE_EVENT, LOADER_EVENT: Uses Pro plugin infrastructure and events for lifecycle and loading state.
• Config integration direct-pivot-config: Reads direct pivot configuration from grid.pivot.
• Config integration additionalData.pivot: Reads legacy pivot configuration from additionalData.pivot.
• Optional sorting-capable-plugin: Integrates with sorting state when present for field panel and remote sorting.
• Optional pagination-capable-plugin: Integrates with pagination when present for remote pivot paging.
• Event integration groupexpandclick, column-collapse, column-expand, beforefilterapply, beforesortingapply: Listens to grid events to synchronize drill-down, collapsed groups, and server-mode requests.

class PivotPlugin {
  updateConfigurator(config?: Partial<PivotConfig>);

  updateFieldPanel(config?: Partial<PivotConfig>, resizedColumns?: ColumnResizeDetail);

  /**
     * Applies either the client or remote Pivot engine based on configuration.
     */
  applyPivot(config?: Partial<PivotConfig>);

  /**
     * Clears managed Pivot state and restores the original grid payload.
     */
  clearPivot();
}

---

PIVOT_VALUES_AXIS_FIELD

PIVOT_VALUES_AXIS_FIELD: string;

---

PivotAxisField

export type PivotAxisField = ColumnProp | typeof PIVOT_VALUES_AXIS_FIELD;

---

PivotConfigValue

interface PivotConfigValue {
  /** Source field used as the measure carrier. */
    prop: ColumnProp;
  /** Aggregator id resolved from the matching dimension definition. */
    aggregator: string;
  /** Optional display label used for generated measure row and column labels. */
    label?: string;
  /** Optional display name used when label is not provided. */
    name?: string
}

---

PivotSubtotalDisableRule

interface PivotSubtotalDisableRule {
  /** Axis fields whose generated subtotal should be skipped. */
    fields?: ColumnProp[];
  /** Zero-based axis levels whose generated subtotal should be skipped. */
    levels?: number[]
}

---

PivotColumnCollapseConfig

interface PivotColumnCollapseConfig {
  /**
     * Enable collapse for generated Pivot column groups.
     */
    enabled?: boolean;
  /**
     * Start all generated Pivot column groups collapsed by default.
     * Persisted group-specific state in `collapsedColumns` still takes precedence.
     */
    collapsed?: boolean;
  /**
     * Override the aggregator used for collapsed placeholder buckets.
     * A string applies to every value field, while a record can target a specific value prop.
     */
    aggregator?: string | Partial<Record<string, string>>;
  /**
     * Override the generated placeholder header or cell template used for collapsed groups.
     */
    placeholder?: string | ColumnTemplateFunc | ColumnCollapsePlaceholder
}

---

PivotGroupLabelConfig

interface PivotGroupLabelConfig {
  /** Display label for empty-string row and column group members. */
    empty?: string;
  /** Display label for null or undefined row and column group members. */
    null?: string
}

---

PivotGroupLabelColumnMode

export type PivotGroupLabelColumnMode = 'grouped' | 'firstVisible';

---

PivotFieldPanelTexts (Extended from index.ts)

interface PivotFieldPanelTexts {

}

---

PivotFieldPanelConfig

interface PivotFieldPanelConfig {
  /** Shows the in-grid Pivot field panel. */
    visible?: boolean;
  /** Enables drag-and-drop field movement between panel areas. */
    allowFieldDragging?: boolean;
  /** Enables removing fields from panel areas. Disabled by default to avoid losing recoverability in compact layout. */
    allowFieldRemoving?: boolean;
  /** Shows the Rows area. */
    showRowFields?: boolean;
  /** Shows the Columns area. */
    showColumnFields?: boolean;
  /** Shows the Values/Data area. */
    showDataFields?: boolean;
  /** Shows the Filters area. */
    showFilterFields?: boolean;
  /** UI strings for the field panel. */
    texts?: PivotFieldPanelTexts
}

---

PanelType

The type of the panel

/** The type of the panel */
export type PanelType = 'dimensions' | 'rows' | 'columns' | 'values' | 'filters';

---

PivotConfigDimension (Extended from index.ts)

interface PivotConfigDimension {
  prop: ColumnProp;
  /** Optional field description shown by Pivot configuration UI. */
    description?: string;
  /** Hides the field from Pivot field-list helpers unless show-hidden mode is enabled. */
    hidden?: boolean;
  /**
     * Custom aggregators or use common aggregators
     */
    aggregators?: { [name: string]: ((values: any[]) => any) };
  /**
     * Aggregator value for the column
     * set automatically
     */
    readonly aggregator?: string;
  /**
     * The type of the dimension: rows, values
     * set automatically
     */
    readonly dimension?: PanelType
}

---

PivotConfig

interface PivotConfig {
  dimensions?: PivotConfigDimension[];
  /** Ordered row dimensions used to build the pivot row hierarchy. */
    rows: ColumnProp[];
  /** Ordered column dimensions used to build generated pivot headers. */
    columns?: ColumnProp[];
  /** Measures rendered in the generated pivot cells. */
    values: PivotConfigValue[];
  /** Ordered filter fields shown in the Pivot field panel. */
    filters?: ColumnProp[];
  /** Enables the configurator side panel. */
    hasConfigurator?: boolean;
  /** Configures the in-grid Pivot field panel. */
    fieldPanel?: PivotFieldPanelConfig;
  /** Optional external mount target for the configurator. */
    mountTo?: HTMLElement;
  /** Flattens hierarchical column groups into single-label headers. */
    flatHeaders?: boolean;
  /** Merges generated value headers into the terminal Pivot column headers. */
    mergeValueHeaders?: boolean;
  /**
     * Render Pivot value measures as row members instead of generated value columns.
     */
    valuesOnRows?: boolean;
  /**
     * Advanced row hierarchy order. Use `$values` to place the measure pseudo-field
     * at a specific position in the row tree.
     */
    rowTree?: PivotAxisField[];
  /** Shows the legacy configurator columns zone. */
    showColumns?: boolean;
  /** Shows the legacy configurator rows zone. */
    showRows?: boolean;
  /** Shows the legacy configurator values zone. */
    showValues?: boolean;
  /** Shows the legacy configurator filters zone. */
    showFilters?: boolean;
  /** Configures grand totals and subtotals. */
    totals?: PivotConfigTotals;
  /** Configures display labels for empty or null row and column group members. */
    groupLabels?: PivotGroupLabelConfig;
  /**
     * Chooses which visible row cell renders the grouped-row label text.
     * `grouped` keeps label text in the grouped field column.
     * `firstVisible` renders label text in the first currently visible row cell.
     */
    groupLabelColumn?: PivotGroupLabelColumnMode;
  /**
     * Enable Pivot drill-down based on the current row hierarchy.
     * `true` starts collapsed, `false` starts expanded.
     * The feature is only applied when at least two row fields are configured.
     */
    collapsed?: boolean;
  /**
     * Persisted expand state for Pivot drill-down groups.
     * Keys use the same grouped path format as RevoGrid grouping rows.
     */
    expanded?: Record<string, boolean>;
  /**
     * Render aggregate values inside Pivot drill-down group rows.
     * The initial implementation applies to the client-side Pivot path.
     */
    groupAggregations?: boolean;
  /**
     * Enable column drill-down using the ColumnCollapse plugin on generated pivot groups.
     * `true` enables collapsible groups.
     * `{ collapsed: true }` enables collapsible groups and starts them collapsed.
     */
    columnCollapse?: boolean | PivotColumnCollapseConfig;
  /**
     * Initial or persisted collapsed state for generated pivot column groups.
     * `true` collapses all generated groups by default.
     */
    collapsedColumns?: boolean | Record<string, boolean>;
  /** UI strings for the configurator. */
    i18n?: typeof PIVOT_CONFIG_EN;
  /**
     * Optional engine selection. Omit it to keep the existing in-memory pivot behaviour.
     * Server mode uses the same row/column/value configuration but delegates computation
     * through an adapter or remote store.
     */
    engine?: {
      mode?: 'client' | 'server';
      adapter?: PivotEngineAdapter;
      remoteStore?: PivotRemoteStore;
      viewId?: string;
      fieldsVersion?: string;
      rowAxis?: Partial<PivotAxisViewport>;
      columnAxis?: Partial<PivotAxisViewport>;
    }
}

---

createPivotData

Builds the full client-side Pivot result set from raw source rows.

export function createPivotData(
  originalData: DataType[],
  config: Partial<PivotConfig>,
);

---

createPivotDataModel

Builds the full client-side Pivot result set together with grouped-row aggregate payloads keyed by RevoGrid grouped path values.

export function createPivotDataModel(
  originalData: DataType[],
  config: Partial<PivotConfig>,
): PivotDataModel;

---

PivotGroupAggregates

export type PivotGroupAggregates = Record<string, DataType>;

---

PivotDataModel

interface PivotDataModel {
  rows: DataType[];
  groupAggregatesByPath: PivotGroupAggregates
}

---

pivotColumns

Builds the generated RevoGrid column model for the current Pivot config. The source is only used to discover unique analytical column paths.

export function pivotColumns(
  config: Partial<PivotConfig>,
  source: DataType[] = [],
);

---

withPivotTotalLabelTemplates

export function withPivotTotalLabelTemplates(
  columns: Array<ColumnGrouping | ColumnRegular>,
  config: Partial<PivotConfig>,
  columnTypes: ColumnTypes =;

---

pivotColumnsFromPaths

export function pivotColumnsFromPaths(
  config: Partial<PivotConfig>,
  paths: Array<Array<string | number | boolean | null>>,
);

---

PIVOT_TOTAL_CELL_CLASS

PIVOT_TOTAL_CELL_CLASS: string;

---

PivotSummaryType

export type PivotSummaryType = 'sum' | 'min' | 'max' | 'avg' | 'count';

---

PivotFieldDataType

export type PivotFieldDataType = 'string' | 'number' | 'date' | 'boolean';

---

PivotLogicalOperator

export type PivotLogicalOperator = 'and' | 'or';

---

PivotSortDirection

export type PivotSortDirection = 'asc' | 'desc';

---

PivotSortBySummaryType

export type PivotSortBySummaryType = PivotSummaryType | `${string}_${PivotSummaryType}`;

---

PivotDateGroupInterval

export type PivotDateGroupInterval = 'year' | 'quarter' | 'month' | 'day' | 'dayOfWeek';

---

PivotGroupInterval

export type PivotGroupInterval =
  | PivotDateGroupInterval
  | {
      /** Numeric bucket grouping for OLAP-style measure banding. */
      type: 'numericBucket';
      /** Bucket width. A size of `100` yields buckets such as `0-99`, `100-199`, and so on. */
      size: number;
    };

---

PivotFilterOperation

export type PivotFilterOperation =
  | '='
  | '<>'
  | '>'
  | '>='
  | '<'
  | '<='
  | 'contains'
  | 'notcontains'
  | 'startswith'
  | 'endswith'
  | 'in'
  | 'notin';

---

PivotPath

export type PivotPath = Array<string | number | boolean | null>;

---

PivotFilterValue

export type PivotFilterValue =
  | string
  | number
  | boolean
  | null
  | Array<string | number | boolean | null>;

---

PivotFilterCondition

export type PivotFilterCondition = [selector: string, operation: PivotFilterOperation, value: PivotFilterValue];

---

PivotFilterExpression

export type PivotFilterExpression =
  | PivotFilterCondition
  | [left: PivotFilterExpression, operator: PivotLogicalOperator, right: PivotFilterExpression]
  | ['!', PivotFilterExpression];

---

PivotGroupDescriptor

interface PivotGroupDescriptor {
  /** Public field id resolved through the server-side field registry. */
    selector: string;
  /** Descending sort flag for the grouped members on this axis level. */
    desc?: boolean;
  /** Optional date or numeric-bucket grouping strategy for this selector. */
    groupInterval?: PivotGroupInterval
}

---

PivotSummaryDescriptor

interface PivotSummaryDescriptor {
  /** Public field id of the measure being aggregated. */
    selector: string;
  /** Stable summary function id returned by the analytical engine. */
    summaryType: PivotSummaryType
}

---

PivotSortDescriptor

interface PivotSortDescriptor {
  /** Public field id to sort by. */
    selector: string;
  /** Descending sort flag for the selector or summary. */
    desc?: boolean;
  /** Optional summary id used when the backend supports sort-by-summary semantics. */
    bySummary?: PivotSortBySummaryType
}

---

PivotAxisViewport

interface PivotAxisViewport {
  /** Zero-based analytical offset for this axis window. */
    offset: number;
  /** Requested analytical window size for this axis. */
    limit: number;
  /** Expanded analytical members represented as paths, never as UI indexes. */
    expandedPaths?: PivotPath[]
}

---

PivotUiStateHints

interface PivotUiStateHints {
  /** Preferred row-header presentation for engines that can shape tree metadata. */
    rowHeaderLayout?: 'tree' | 'flat';
  /** Preferred totals placement hint for the analytical engine. */
    showTotalsPrior?: 'rows' | 'columns' | 'none';
  /** Hint that the UI currently expects collapsed-by-default hierarchies. */
    collapsedByDefault?: boolean
}

---

PivotLoadOptions

interface PivotLoadOptions {
  /** Registry-backed filter expression tree. */
    filter?: PivotFilterExpression;
  /** Row-axis grouping descriptors. */
    rows?: PivotGroupDescriptor[];
  /** Column-axis grouping descriptors. */
    columns?: PivotGroupDescriptor[];
  /** Grand-total summary descriptors. */
    totalSummary?: PivotSummaryDescriptor[];
  /** Group-level summary descriptors. */
    groupSummary?: PivotSummaryDescriptor[];
  /** Analytical sorting directives. */
    sort?: PivotSortDescriptor[]
}

---

PivotLoadRequest

interface PivotLoadRequest {
  /** Client-generated correlation id for logs, tracing, and stale-response protection. */
    requestId: string;
  /** Dataset or semantic view identifier understood by the backend. */
    viewId: string;
  /** Version or checksum of the published field registry for this view. */
    fieldsVersion: string;
  /** Analytical layout, filters, summaries, and sort instructions. */
    loadOptions: PivotLoadOptions;
  /** Independent analytical windows for the row and column axes. */
    viewport: {
      rowAxis: PivotAxisViewport;
      columnAxis: PivotAxisViewport;
    };
  /** Optional UI hints that let a backend align with current Pivot presentation preferences. */
    uiState?: PivotUiStateHints
}

---

PivotAxisWindowMeta

interface PivotAxisWindowMeta {
  /** Total number of analytical members available on this axis. */
    totalCount?: number;
  /** Optional analytical paths used to materialize generated Pivot columns. */
    paths?: PivotPath[];
  /** Zero-based analytical offset for this axis window. */
    offset?: number;
  /** Requested analytical window size for this axis. */
    limit?: number;
  /** Expanded analytical members represented as paths. */
    expandedPaths?: PivotPath[];
  /** Actual number of members returned in this window. */
    returned?: number
}

---

PivotLoadResponseMeta

interface PivotLoadResponseMeta {
  /** Cache outcome for observability and UI diagnostics. */
    cacheStatus: 'hit' | 'miss' | 'warm' | 'bypass';
  /** Correlation cache key. */
    cacheKey?: string;
  /** Server-side generation timestamp. */
    generatedAt?: string;
  /** Elapsed processing time in milliseconds. */
    elapsedMs?: number;
  /** Optional warnings or diagnostic messages. */
    warnings?: string[]
}

---

PivotLoadResponse

interface PivotLoadResponse {
  /** Visible analytical payload or already materialized row records. */
    data: DataType[];
  /** Total or pinned summary rows for the current analytical request. */
    summary: unknown[];
  /** Row-axis window metadata. */
    rowAxis: PivotAxisWindowMeta;
  /** Column-axis window metadata. */
    columnAxis: PivotAxisWindowMeta;
  /** Optional grouped-row aggregate payloads keyed by grouped path values. */
    groupAggregates?: Record<string, DataType>;
  /** Cache and timing metadata for diagnostics. */
    meta: PivotLoadResponseMeta;
  /** Correlation id. */
    requestId?: string;
  /** Response format version. */
    version?: number
}

---

PivotDrilldownCellRef

interface PivotDrilldownCellRef {
  /** Row-axis path for the visible summary cell. */
    rowPath: PivotPath;
  /** Column-axis path for the visible summary cell. */
    columnPath: PivotPath;
  /** Optional measure index when multiple values are present. */
    dataIndex?: number
}

---

PivotDrilldownRequest

interface PivotDrilldownRequest {
  /** Client-generated correlation id for the drilldown request. */
    requestId: string;
  /** Dataset or semantic view identifier understood by the backend. */
    viewId: string;
  /** Version or checksum of the published field registry for this view. */
    fieldsVersion: string;
  /** Visible pivot cell that defines the drilldown scope. */
    cell: PivotDrilldownCellRef;
  /** Optional whitelist-validated columns to expose in the fact page. */
    customColumns?: string[];
  /** Zero-based fact-page offset. */
    offset: number;
  /** Requested fact-page size. */
    limit: number
}

---

PivotDrilldownResponse

interface PivotDrilldownResponse {
  /** Matching fact rows for the requested summary cell. */
    data: DataType[];
  /** Total number of matching facts. */
    totalCount: number;
  /** Optional cache metadata for drilldown responses. */
    meta?: Partial<PivotLoadResponseMeta>;
  /** Correlation id. */
    requestId?: string
}

---

PivotStateSaveRequest

interface PivotStateSaveRequest {
  /** Client-generated correlation id for persistence. */
    requestId: string;
  /** View identifier whose UI state is being persisted. */
    viewId: string;
  /** User identifier that owns the saved state. */
    userId: string;
  /** Arbitrary persisted Pivot UI state payload. */
    state: Record<string, unknown>
}

---

PivotStateResponse

interface PivotStateResponse {
  /** Optional echoed correlation id from the request. */
    requestId?: string;
  /** User identifier that owns the state. */
    userId: string;
  /** View identifier for the saved state. */
    viewId: string;
  /** Persisted Pivot UI state payload. */
    state: Record<string, unknown>;
  /** Optional schema version for persisted state. */
    version?: number
}

---

PivotCacheInvalidationRequest

interface PivotCacheInvalidationRequest {
  /** Client-generated correlation id for invalidation requests. */
    requestId: string;
  /** Tenant scope to invalidate. */
    tenantId?: string;
  /** Optional view scope within the tenant. */
    viewId?: string;
  /** Dataset watermark to invalidate. */
    datasetWatermark?: string;
  /** Optional field-registry version scope. */
    fieldsVersion?: string
}

---

PivotLimits

interface PivotLimits {
  /** Hard cap for row-axis windows. */
    maxRowWindowSize: number;
  /** Hard cap for column-axis windows. */
    maxColumnWindowSize: number;
  /** Hard cap for expanded analytical members. */
    maxExpandedPaths: number;
  /** Hard cap for analytical hierarchy depth. */
    maxExpansionDepth: number;
  /** Hard cap for drilldown page size. */
    maxDrilldownLimit: number;
  /** Hard cap for requested summary descriptors. */
    maxSummaryDescriptors: number;
  /** Hard cap for row or column grouping descriptors. */
    maxGroupDescriptors: number;
  /** Hard cap for nested filter-expression depth. */
    maxFilterDepth: number
}

---

PivotGridModel

interface PivotGridModel {
  /** Generated RevoGrid columns for the visible Pivot window. */
    columns: Array<ColumnGrouping | ColumnRegular>;
  /** Visible body rows to render in the grid viewport. */
    source: DataType[];
  /** Optional pinned grand-total rows. */
    pinnedBottomSource?: DataType[];
  /** Optional grouped-row metadata for Pivot drill-down. */
    grouping?: GroupingOptions;
  /** Response metadata forwarded to UI diagnostics if needed. */
    meta?: Partial<PivotLoadResponseMeta>
}

---

PivotEngineAdapter

Analytical engine boundary used by PivotPlugin.

Use this when your application wants to translate Pivot requests directly into OLAP, warehouse, or semantic-layer queries without going through HttpPivotRemoteStore.

interface PivotEngineAdapter {
  load(request: PivotLoadRequest, signal?: AbortSignal): Promise<PivotLoadResponse>;
  drilldown?(request: PivotDrilldownRequest, signal?: AbortSignal): Promise<PivotDrilldownResponse>
}

---

PivotAuthProvider

Async auth-header resolver used by HTTP-backed remote stores.

/** Async auth-header resolver used by HTTP-backed remote stores. */
export type PivotAuthProvider = () => Promise<Record<string, string>>;

---

PivotRemoteStore

Framework-agnostic client contract for server-side Pivot operations.

In production this should usually talk to an application API that owns auth, tenancy, selector validation, and query translation. It is not intended for direct browser-to-database connections.

interface PivotRemoteStore {
  load(request: PivotLoadRequest, signal?: AbortSignal): Promise<PivotLoadResponse>;
  drilldown(
      request: PivotDrilldownRequest,
      signal?: AbortSignal,
    ): Promise<PivotDrilldownResponse>;
  saveState(request: PivotStateSaveRequest, signal?: AbortSignal): Promise<void>;
  loadState(userId: string, viewId: string, signal?: AbortSignal): Promise<PivotStateResponse>
}

---

PivotRemoteStoreHooks

interface PivotRemoteStoreHooks {
  requestStarted?: (event: { key: string; type: 'load' | 'drilldown' | 'saveState' | 'loadState' }) => void;
  requestSucceeded?: (
      event: { key: string; type: 'load' | 'drilldown' | 'saveState' | 'loadState'; cacheStatus?: string },
    ) => void;
  requestFailed?: (
      event: { key: string; type: 'load' | 'drilldown' | 'saveState' | 'loadState'; error: unknown },
    ) => void;
  cacheStatusChanged?: (event: { key: string; cacheStatus: string }) => void
}

---

PivotRemoteStoreOptions

interface PivotRemoteStoreOptions {
  /** Base URL of the application API that exposes `/api/pivot/*` endpoints. */
    baseUrl?: string;
  /** Tenant scope used for cache keys and backend request routing. */
    tenantId?: string;
  /** Dataset or cube watermark used to separate stale and fresh cached results. */
    datasetWatermark?: string;
  /** Async auth-header provider, typically used for bearer tokens or session headers. */
    authProvider?: PivotAuthProvider;
  /** Custom fetch implementation for frameworks, SSR, tests, or mocked transports. */
    fetchImpl?: typeof fetch;
  /** Optional lifecycle hooks for request telemetry and cache diagnostics. */
    hooks?: PivotRemoteStoreHooks
}

---

HttpPivotRemoteStore

Default remote store backed by fetch and the public Pivot HTTP contract.

class HttpPivotRemoteStore {
  load(request: PivotLoadRequest, signal?: AbortSignal): Promise<PivotLoadResponse>;

  drilldown(request: PivotDrilldownRequest, signal?: AbortSignal): Promise<PivotDrilldownResponse>;

  async saveState(request: PivotStateSaveRequest, signal?: AbortSignal): Promise<void>;

  loadState(userId: string, viewId: string, signal?: AbortSignal): Promise<PivotStateResponse>;
}

---

createPivotDrilldownRequest

export function createPivotDrilldownRequest(
  input: PivotDrilldownRequestInput,
  createRequestId: () => string = createDefaultDrilldownRequestId,
): PivotDrilldownRequest;

---

createPivotDrilldownTableModel

export function createPivotDrilldownTableModel(
  response: PivotDrilldownResponse,
  request?: PivotDrilldownRequest,
): PivotDrilldownTableModel;

---

createPivotDrilldownColumns

export function createPivotDrilldownColumns(
  rows: DataType[],
  customColumns?: string[],
): ColumnRegular[];

---

PivotDrilldownStatus

export type PivotDrilldownStatus = 'idle' | 'loading' | 'success' | 'error';

---

PivotDrilldownRequestInput

interface PivotDrilldownRequestInput {
  /** Dataset or semantic view identifier understood by the adapter/backend. */
    viewId: string;
  /** Version or checksum of the field registry for this view. */
    fieldsVersion: string;
  /** Visible pivot cell that defines the source-row scope. */
    cell: PivotDrilldownCellRef;
  /** Optional whitelist-validated columns to expose in the fact page. */
    customColumns?: string[];
  /** Zero-based fact-page offset. Defaults to 0. */
    offset?: number;
  /** Requested fact-page size. Defaults to 100. */
    limit?: number;
  /** Optional caller-provided correlation id. */
    requestId?: string
}

---

PivotDrilldownTableModel

interface PivotDrilldownTableModel {
  /** RevoGrid/table-ready fact columns. */
    columns: ColumnRegular[];
  /** Fact rows returned by the adapter. */
    rows: DataType[];
  /** Total matching facts across all pages. */
    totalCount: number
}

---

PivotDrilldownState (Extended from index.ts)

interface PivotDrilldownState {
  status: PivotDrilldownStatus;
  loading: boolean;
  error?: unknown;
  request?: PivotDrilldownRequest;
  response?: PivotDrilldownResponse
}

---

PivotDrilldownControllerOptions

interface PivotDrilldownControllerOptions {
  /** Default page size used when `load` does not specify a limit. */
    defaultLimit?: number;
  /** Correlation id generator used by the request builder. */
    createRequestId?: () => string
}

---

PivotDrilldownStateListener

export type PivotDrilldownStateListener = (state: PivotDrilldownState) => void;

---

PivotDrilldownController

class PivotDrilldownController {
  getState();

  subscribe(listener: PivotDrilldownStateListener);

  async load(input: PivotDrilldownRequestInput, signal?: AbortSignal);

  abort();

  reset();
}

---

savePivotView

export async function savePivotView(
  store: PivotRemoteStore,
  options: PivotSaveViewOptions,
): Promise<PivotSavedView>;

---

loadPivotView

export async function loadPivotView(
  store: PivotRemoteStore,
  options: PivotLoadViewOptions,
): Promise<PivotSavedView>;

---

createPivotSavedViewState

export function createPivotSavedViewState(
  config: Partial<PivotConfig>,
  metadata:;

---

serializePivotConfig

export function serializePivotConfig(config: Partial<PivotConfig>): Partial<PivotConfig>;

---

pivotSavedViewFromState

export function pivotSavedViewFromState(response: PivotStateResponse): PivotSavedView;

---

renamePivotSavedView

export function renamePivotSavedView(
  views: readonly PivotSavedViewRecord[],
  options: PivotRenameViewOptions,
): PivotSavedViewRecord[];

---

duplicatePivotSavedView

export function duplicatePivotSavedView(
  views: readonly PivotSavedViewRecord[],
  options: PivotDuplicateViewOptions,
): PivotSavedViewRecord[];

---

deletePivotSavedView

export function deletePivotSavedView(
  views: readonly PivotSavedViewRecord[],
  options: PivotDeleteViewOptions,
): PivotSavedViewRecord[];

---

PIVOT_SAVED_VIEW_STATE_KIND

PIVOT_SAVED_VIEW_STATE_KIND: string;

---

PIVOT_SAVED_VIEW_STATE_VERSION

PIVOT_SAVED_VIEW_STATE_VERSION: 1;

---

PivotSavedViewRef

interface PivotSavedViewRef {
  /** User identifier that owns the saved view. */
    userId: string;
  /** View identifier used by the remote state store. */
    viewId: string
}

---

PivotSavedView (Extended from index.ts)

interface PivotSavedView {
  /** Serializable Pivot configuration restored from the saved view payload. */
    config: Partial<PivotConfig>;
  /** Optional display name supplied by the application. */
    name?: string;
  /** Optional ISO timestamp supplied by the application or backend. */
    savedAt?: string;
  /** Persisted state schema version. */
    version: number;
  /** Optional echoed correlation id from the remote state response. */
    requestId?: string
}

---

PivotSavedViewDeleteIntent (Extended from index.ts)

interface PivotSavedViewDeleteIntent {
  /** Marks a saved view for deletion by the application or remote state sync layer. */
    deleted: true;
  /** Optional ISO timestamp supplied by the application. */
    deletedAt?: string;
  /** Optional client-generated correlation id. */
    requestId?: string
}

---

PivotSavedViewRecord

export type PivotSavedViewRecord = PivotSavedView | PivotSavedViewDeleteIntent;

---

PivotSaveViewOptions (Extended from index.ts)

interface PivotSaveViewOptions {
  /** Active Pivot config to serialize into the remote state payload. */
    config: Partial<PivotConfig>;
  /** Optional display name supplied by the application. */
    name?: string;
  /** Optional client-generated correlation id. */
    requestId?: string;
  /** Optional ISO timestamp. Defaults to the current time. */
    savedAt?: string;
  /** Optional abort signal forwarded to the remote store. */
    signal?: AbortSignal
}

---

PivotRenameViewOptions (Extended from index.ts)

interface PivotRenameViewOptions {
  /** Next display name for the saved view. */
    name: string
}

---

PivotDuplicateViewOptions (Extended from index.ts)

interface PivotDuplicateViewOptions {
  /** Optional explicit identifier for the duplicated view. */
    newViewId?: string;
  /** Optional duplicated view name. Defaults to "<source name> Copy". */
    name?: string;
  /** Optional ISO timestamp copied into the duplicated view. */
    savedAt?: string;
  /** Optional client-generated correlation id. */
    requestId?: string;
  /** Stable id factory for deterministic tests and app-owned id schemes. */
    generateId?: (view: PivotSavedView, views: readonly PivotSavedViewRecord[]) => string
}

---

PivotDeleteViewOptions (Extended from index.ts)

interface PivotDeleteViewOptions {
  /** Optional ISO timestamp supplied by the application. */
    deletedAt?: string;
  /** Optional client-generated correlation id. */
    requestId?: string
}

---

PivotLoadViewOptions (Extended from index.ts)

interface PivotLoadViewOptions {
  /** Optional abort signal forwarded to the remote store. */
    signal?: AbortSignal
}

---

PivotSavedViewState (Extended from index.ts)

interface PivotSavedViewState {
  kind: typeof PIVOT_SAVED_VIEW_STATE_KIND;
  version: typeof PIVOT_SAVED_VIEW_STATE_VERSION;
  config: Partial<PivotConfig>;
  name?: string;
  savedAt?: string
}

---

createFieldRegistry

Converts a field entry list into an id-addressable registry map.

export function createFieldRegistry(entries: FieldRegistryEntry[]): PivotFieldRegistry;

---

getFieldRegistryEntry

Resolves a public selector or throws the stable invalid-selector error.

export function getFieldRegistryEntry(
  registry: PivotFieldRegistry,
  selector: string,
): FieldRegistryEntry;

---

assertSummaryAllowed

Validates that a requested summary is allowed for the selector.

export function assertSummaryAllowed(
  registry: PivotFieldRegistry,
  descriptor: PivotSummaryDescriptor,
);

---

assertGroupIntervalAllowed

Validates that a requested grouping interval is allowed for the selector.

export function assertGroupIntervalAllowed(
  registry: PivotFieldRegistry,
  descriptor: PivotGroupDescriptor,
);

---

assertDrilldownColumnsAllowed

Validates that requested drill-down columns are safe to expose.

export function assertDrilldownColumnsAllowed(
  registry: PivotFieldRegistry,
  columns: string[] = [],
);

---

BackendExpression

interface BackendExpression {
  kind: 'column' | 'sql';
  value: string
}

---

FieldRegistryEntry

interface FieldRegistryEntry {
  id: string;
  label: string;
  dataType: PivotFieldDataType;
  expression: BackendExpression;
  allowedOperations: PivotFilterOperation[];
  allowedSummaries?: PivotSummaryType[];
  allowedGroupIntervals?: PivotGroupInterval[];
  drilldownVisible?: boolean
}

---

PivotFieldRegistry

export type PivotFieldRegistry = Record<string, FieldRegistryEntry>;

---

createPivotErrorResponse

Serializes either a PivotError or a raw payload into the wire format.

export function createPivotErrorResponse(
  requestId: string,
  error: PivotError | PivotErrorPayload,
): PivotErrorResponse;

---

PivotErrorCode

Pivot errors define the stable, serializable error contract shared by local validation and remote endpoint implementations.

/**
 * Pivot errors define the stable, serializable error contract shared by local
 * validation and remote endpoint implementations.
 */

export type PivotErrorCode =
  | 'INVALID_SELECTOR'
  | 'INVALID_FILTER_OPERATION'
  | 'INVALID_SUMMARY_TYPE'
  | 'INVALID_GROUP_INTERVAL'
  | 'WINDOW_LIMIT_EXCEEDED'
  | 'EXPANSION_LIMIT_EXCEEDED'
  | 'AUTH_REQUIRED'
  | 'FORBIDDEN'
  | 'STATE_NOT_FOUND'
  | 'CACHE_INVALIDATION_FORBIDDEN'
  | 'INTERNAL_ERROR';

---

PivotErrorPayload

interface PivotErrorPayload {
  code: PivotErrorCode;
  message: string;
  details?: Record<string, unknown>
}

---

PivotErrorResponse

interface PivotErrorResponse {
  requestId: string;
  error: PivotErrorPayload
}

---

PivotError

Error class carrying the public Pivot error code and optional details.

class PivotError {}

---

normalizePivotLoadRequest

Normalizes and validates a pivot load request.

export function normalizePivotLoadRequest(
  request: PivotLoadRequest,
  registry: PivotFieldRegistry,
  limits: PivotLimits = DEFAULT_PIVOT_LIMITS,
): NormalizedPivotLoadRequest;

---

normalizePivotDrilldownRequest

Normalizes and validates a drill-down request.

export function normalizePivotDrilldownRequest(
  request: PivotDrilldownRequest,
  registry: PivotFieldRegistry,
  limits: PivotLimits = DEFAULT_PIVOT_LIMITS,
): NormalizedPivotDrilldownRequest;

---

normalizeFilterExpression

Validates and normalizes nested filter expressions recursively.

export function normalizeFilterExpression(
  filter: PivotFilterExpression,
  registry: PivotFieldRegistry,
  maxDepth: number,
  depth = 1,
): PivotFilterExpression;

---

normalizeExpandedPaths

Sorts and validates analytical expansion paths.

export function normalizeExpandedPaths(
  expandedPaths: PivotPath[] = [],
  limits: Pick<PivotLimits, 'maxExpandedPaths' | 'maxExpansionDepth'> = DEFAULT_PIVOT_LIMITS,
);

---

normalizeViewportAxis

Enforces viewport limits and normalized expansion state for one axis.

export function normalizeViewportAxis(
  viewport: PivotAxisViewport,
  maxWindowSize: number,
  limits: Pick<PivotLimits, 'maxExpandedPaths' | 'maxExpansionDepth'> = DEFAULT_PIVOT_LIMITS,
): PivotAxisViewport;

---

normalizeSummaries

Validates and canonicalizes summary descriptors.

export function normalizeSummaries(
  descriptors: PivotSummaryDescriptor[],
  registry: PivotFieldRegistry,
  limits: Pick<PivotLimits, 'maxSummaryDescriptors'> = DEFAULT_PIVOT_LIMITS,
);

---

normalizeGroups

Validates and canonicalizes grouping descriptors.

export function normalizeGroups(
  descriptors: PivotGroupDescriptor[],
  registry: PivotFieldRegistry,
  limits: Pick<PivotLimits, 'maxGroupDescriptors'> = DEFAULT_PIVOT_LIMITS,
);

---

getSummaryResultId

Builds the stable result-field name for a summary descriptor.

export function getSummaryResultId(summary: PivotSummaryDescriptor);

---

NormalizedPivotLoadRequest

export type NormalizedPivotLoadRequest = PivotLoadRequest;

---

NormalizedPivotDrilldownRequest

export type NormalizedPivotDrilldownRequest = PivotDrilldownRequest;

---

DEFAULT_PIVOT_LIMITS

DEFAULT_PIVOT_LIMITS: {
  maxRowWindowSize: number;
  maxColumnWindowSize: number;
  maxExpandedPaths: number;
  maxExpansionDepth: number;
  maxDrilldownLimit: number;
  maxSummaryDescriptors: number;
  maxGroupDescriptors: number;
  maxFilterDepth: number;
};

---

stableStringify

Stringifies nested values with stable object key ordering.

export function stableStringify(value: unknown): string;

---

createPivotCacheKey

Builds the canonical cache key for a pivot load window.

export function createPivotCacheKey(context: PivotCacheKeyContext): string;

---

PivotCacheKeyContext

interface PivotCacheKeyContext {
  tenantId: string;
  viewId: string;
  fieldsVersion: string;
  datasetWatermark?: string;
  request: Omit<PivotLoadRequest, 'requestId' | 'viewId' | 'fieldsVersion'>
}

---

PlannedPivotSummary (Extended from index.ts)

interface PlannedPivotSummary {
  resultId: string;
  execution:
      | {
          type: 'direct';
          field: FieldRegistryEntry;
        }
      | {
          type: 'composite';
          components: Array<{
            selector: string;
            summaryType: 'sum' | 'count';
          }>;
        }
}

---

PivotQueryPlan

interface PivotQueryPlan {
  request: PivotLoadRequest;
  filteredBaseDataset: {
      viewId: string;
      fieldsVersion: string;
      filter?: PivotLoadRequest['loadOptions']['filter'];
    };
  rowAxis: {
      groups: PivotGroupDescriptor[];
      viewport: PivotLoadRequest['viewport']['rowAxis'];
    };
  columnAxis: {
      groups: PivotGroupDescriptor[];
      viewport: PivotLoadRequest['viewport']['columnAxis'];
    };
  summaries: PlannedPivotSummary[];
  orderBy: PivotLoadRequest['loadOptions']['sort']
}

---

DrilldownQueryPlan

interface DrilldownQueryPlan {
  request: PivotDrilldownRequest;
  visibleFields: FieldRegistryEntry[]
}

---

PivotQueryPlanner

interface PivotQueryPlanner {
  planLoad(request: PivotLoadRequest): PivotQueryPlan;
  planDrilldown(request: PivotDrilldownRequest): DrilldownQueryPlan
}

---

SqlPivotQueryPlanner

SQL-oriented logical planner that resolves field metadata and summaries.

class SqlPivotQueryPlanner {
  planLoad(request: PivotLoadRequest): PivotQueryPlan;

  planDrilldown(request: PivotDrilldownRequest): DrilldownQueryPlan;
}

---

getPivotColumnPaths

Derives the visible analytical column paths used by the client adapter.

export function getPivotColumnPaths(
  source: DataType[],
  config: Partial<PivotConfig>,
);

---

ClientPivotEngineAdapter

Client adapter keeps the existing client-side pivot behaviour behind the same engine interface used by the remote path.

class ClientPivotEngineAdapter {
  async load(request: PivotLoadRequest): Promise<PivotLoadResponse>;

  async drilldown(request: PivotDrilldownRequest): Promise<PivotDrilldownResponse>;
}

---

ServerPivotEngineAdapter

Remote adapter forwards requests to a framework-agnostic PivotRemoteStore.

class ServerPivotEngineAdapter {
  load(request: PivotLoadRequest, signal?: AbortSignal);

  drilldown(request: PivotDrilldownRequest, signal?: AbortSignal);
}

---

createGridModelFromPivotResponse

Converts a pivot response into the visible source/columns payload consumed by the plugin.

export function createGridModelFromPivotResponse(
  config: Partial<PivotConfig>,
  response: PivotLoadResponse,
);

---

materializePivotRows

Materializes cell-level remote responses into row records keyed by row path. When the response already contains row-shaped records it is returned as-is.

export function materializePivotRows(
  config: Partial<PivotConfig>,
  response: PivotLoadResponse,
);

---

exportVisiblePivotToCsv

Exports the currently visible Pivot grid model to CSV.

export function exportVisiblePivotToCsv(input: PivotCsvExportInput): string;

---

flattenPivotCsvColumns

Flattens grouped Pivot headers into one leaf entry per visible value column.

export function flattenPivotCsvColumns(
  columns: Array<ColumnGrouping | ColumnRegular>,
  headerPathDelimiter = DEFAULT_HEADER_PATH_DELIMITER,
): PivotCsvLeafColumn[];

---

encodeDelimitedCell

export function encodeDelimitedCell(
  value: unknown,
  options: PivotDelimitedFormatOptions,
  force = false,
);

---

PivotCsvExportOptions

interface PivotCsvExportOptions {
  /** Cell delimiter. Defaults to comma. */
    columnDelimiter?: string;
  /** Row delimiter. Defaults to CRLF. */
    rowDelimiter?: string;
  /** Prefix the CSV with a UTF-8 BOM. Defaults to false. */
    bom?: boolean;
  /** Separator used when flattening grouped headers. Defaults to ` / `. */
    headerPathDelimiter?: string
}

---

PivotCsvExportInput (Extended from index.ts)

interface PivotCsvExportInput {
  /** Current visible Pivot columns. Grouped columns are flattened to leaves. */
    columns: Array<ColumnGrouping | ColumnRegular>;
  /** Current visible body rows. */
    source?: DataType[];
  /** Current visible pinned bottom rows, appended after body rows. */
    pinnedBottomSource?: DataType[]
}

---

PivotDelimitedFormatOptions

interface PivotDelimitedFormatOptions {
  columnDelimiter: string;
  rowDelimiter: string
}

---

buildPivotCopyTsv

Builds clipboard-ready TSV for the visible Pivot model.

export function buildPivotCopyTsv(input: PivotTsvCopyInput): string;

---

flattenPivotCopyColumns

export function flattenPivotCopyColumns(
  columns: Array<ColumnGrouping | ColumnRegular>,
): PivotCopyLeafColumn[];

---

PivotTsvCopyInput

interface PivotTsvCopyInput {
  /** Current visible Pivot columns. Grouped columns are treated as header levels. */
    columns: Array<ColumnGrouping | ColumnRegular>;
  /** Current visible body rows. */
    source?: DataType[];
  /** Current visible pinned bottom rows, appended after body rows. */
    pinnedBottomSource?: DataType[];
  /** Optional leaf props to include, in the requested order. */
    selectedProps?: ColumnProp[];
  /** Optional absolute row indexes from source + pinnedBottomSource to include. */
    selectedRowIndexes?: number[];
  /** Optional rows to include instead of source + pinnedBottomSource. */
    selectedRows?: DataType[];
  /** Cell delimiter. Defaults to tab. */
    columnDelimiter?: string;
  /** Row delimiter. Defaults to LF, matching clipboard text conventions. */
    rowDelimiter?: string
}

---

PivotCopyLeafColumn

interface PivotCopyLeafColumn {
  prop: ColumnProp;
  headers: string[];
  rowAxis: boolean
}

---

createPivotFilterChips

Converts RevoGrid and/or Pivot expression filters into render-ready chip models.

export function createPivotFilterChips(
  input: PivotFilterChipInput,
  options: PivotFilterChipOptions =;

---

createPivotFilterChipsFromCollection

Converts a RevoGrid filter collection into render-ready chip models.

export function createPivotFilterChipsFromCollection(
  collection?: Record<ColumnProp, FilterCollectionItem>,
  options: PivotFilterChipOptions =;

---

createPivotFilterChipsFromExpression

Converts a Pivot remote filter expression into render-ready chip models.

export function createPivotFilterChipsFromExpression(
  expression?: PivotFilterExpression,
  options: PivotFilterChipOptions =;

---

createPivotFilterClearOneIntent

Builds an intent payload for clearing a single visible filter chip.

export function createPivotFilterClearOneIntent(chip: PivotFilterChip): PivotFilterClearOneIntent;

---

createPivotFilterClearAllIntent

Builds an intent payload for clearing every visible filter chip.

export function createPivotFilterClearAllIntent(chips: readonly PivotFilterChip[] = []): PivotFilterClearAllIntent;

---

applyPivotFilterClearIntentToCollection

Applies clear intents to a RevoGrid filter collection without mutating caller state.

export function applyPivotFilterClearIntentToCollection(
  collection: Record<ColumnProp, FilterCollectionItem> | undefined,
  intent: PivotFilterClearIntent,
): Record<ColumnProp, FilterCollectionItem> | undefined;

---

PivotFilterChipSource

export type PivotFilterChipSource = 'revo-grid' | 'pivot-expression';

---

PivotFilterChipLabelResolver

interface PivotFilterChipLabelResolver {
  /** Optional field-label lookup used instead of raw field selectors. */
    fieldLabel?: (selector: string) => string | undefined;
  /** Optional operation-label lookup used instead of built-in operation labels. */
    operationLabel?: (operation: string) => string | undefined;
  /** Optional value formatter used instead of built-in value labels. */
    valueLabel?: (value: unknown, selector: string, operation: string) => string | undefined
}

---

PivotFilterChip

interface PivotFilterChip {
  /** Stable id for rendering and clear-one actions. */
    id: string;
  /** Original field selector. */
    selector: string;
  /** Human-readable field label. */
    fieldLabel: string;
  /** Filter operation id from RevoGrid or Pivot remote filters. */
    operation: string;
  /** Human-readable operation label. */
    operationLabel: string;
  /** Raw filter value, kept for caller-owned editor or telemetry needs. */
    value: unknown;
  /** Human-readable value label. */
    valueLabel: string;
  /** Complete visible chip label. */
    label: string;
  /** Source filter model used to build the chip. */
    source: PivotFilterChipSource;
  /** Path of the condition inside a Pivot filter expression tree. */
    expressionPath?: readonly number[]
}

---

PivotFilterChipOptions (Extended from index.ts)

interface PivotFilterChipOptions {
  /** Prefix included in generated chip ids when multiple Pivot views share UI. */
    idPrefix?: string
}

---

PivotFilterChipInput

interface PivotFilterChipInput {
  /** RevoGrid filter collection from `beforefilterapply`. */
    collection?: Record<ColumnProp, FilterCollectionItem>;
  /** Remote Pivot filter expression tree. */
    expression?: PivotFilterExpression
}

---

PivotFilterClearOneIntent

interface PivotFilterClearOneIntent {
  type: 'clear-one';
  chipId: string;
  selector: string;
  source: PivotFilterChipSource;
  expressionPath?: readonly number[]
}

---

PivotFilterClearAllIntent

interface PivotFilterClearAllIntent {
  type: 'clear-all';
  selectors: string[];
  sources: PivotFilterChipSource[]
}

---

PivotFilterClearIntent

export type PivotFilterClearIntent = PivotFilterClearOneIntent | PivotFilterClearAllIntent;

---

createPivotDiagnosticsModel

Converts remote Pivot response metadata into render-ready diagnostics rows and chips.

export function createPivotDiagnosticsModel(
  response: PivotDiagnosticsResponseInput,
  options: PivotDiagnosticsFormatterOptions =;

---

PivotDiagnosticTone

export type PivotDiagnosticTone = 'neutral' | 'success' | 'warning';

---

PivotDiagnosticRow

interface PivotDiagnosticRow {
  /** Stable id for row rendering and tests. */
    id: 'elapsed' | 'generatedAt' | 'visibleRows' | 'visibleColumns';
  /** Human-readable row label. */
    label: string;
  /** Human-readable row value. */
    value: string;
  /** Raw value kept for sorting, telemetry, or custom formatting. */
    rawValue?: string | number
}

---

PivotDiagnosticChip

interface PivotDiagnosticChip {
  /** Stable id for chip rendering and tests. */
    id: string;
  /** Human-readable chip label. */
    label: string;
  /** Chip visual tone hint. */
    tone: PivotDiagnosticTone;
  /** Raw value kept for telemetry or custom rendering. */
    rawValue?: string
}

---

PivotDiagnosticsModel

interface PivotDiagnosticsModel {
  rows: PivotDiagnosticRow[];
  chips: PivotDiagnosticChip[];
  warnings: string[];
  hasWarnings: boolean
}

---

PivotDiagnosticsFormatterLabels

interface PivotDiagnosticsFormatterLabels {
  elapsed: string;
  cache: string;
  generatedAt: string;
  visibleRows: string;
  visibleColumns: string;
  warning: string
}

---

PivotDiagnosticsFormatterOptions

interface PivotDiagnosticsFormatterOptions {
  labels?: Partial<PivotDiagnosticsFormatterLabels>;
  formatGeneratedAt?: (generatedAt: string) => string
}

---

createPivotValueFormatter

Creates a reusable formatter for Pivot aggregate and axis values.

export function createPivotValueFormatter(config: PivotValueFormatConfig): PivotValueFormatter;

---

formatPivotValue

Formats one Pivot value without keeping formatter state between calls.

export function formatPivotValue(value: unknown, config: PivotValueFormatConfig): string;

---

PivotValueFormatPreset

export type PivotValueFormatPreset = 'number' | 'currency' | 'percent' | 'date' | 'datetime';

---

PivotValueFormatBase

interface PivotValueFormatBase {
  /** Locale forwarded to the matching Intl formatter. */
    locale?: Intl.LocalesArgument;
  /** Display value for null or undefined input. Defaults to an empty string. */
    nullDisplay?: string;
  /** Display value for values that cannot be formatted by the selected preset. Defaults to an empty string. */
    invalidDisplay?: string
}

---

PivotNumberFormatConfig (Extended from index.ts)

interface PivotNumberFormatConfig {
  preset: 'number';
  options?: Intl.NumberFormatOptions
}

---

PivotCurrencyFormatConfig (Extended from index.ts)

interface PivotCurrencyFormatConfig {
  preset: 'currency';
  currency: string;
  options?: Omit<Intl.NumberFormatOptions, 'style' | 'currency'>
}

---

PivotPercentFormatConfig (Extended from index.ts)

interface PivotPercentFormatConfig {
  preset: 'percent';
  options?: Omit<Intl.NumberFormatOptions, 'style'>
}

---

PivotDateFormatConfig (Extended from index.ts)

interface PivotDateFormatConfig {
  preset: 'date';
  options?: Intl.DateTimeFormatOptions
}

---

PivotDateTimeFormatConfig (Extended from index.ts)

interface PivotDateTimeFormatConfig {
  preset: 'datetime';
  options?: Intl.DateTimeFormatOptions
}

---

PivotValueFormatConfig

export type PivotValueFormatConfig =
  | PivotNumberFormatConfig
  | PivotCurrencyFormatConfig
  | PivotPercentFormatConfig
  | PivotDateFormatConfig
  | PivotDateTimeFormatConfig;

---

PivotValueFormatter

export type PivotValueFormatter = (value: unknown) => string;

---

serializePivotStateJson

export function serializePivotStateJson(
  config: Partial<PivotConfig>,
  options: PivotStateJsonOptions =;

---

createPivotStateJsonEnvelope

export function createPivotStateJsonEnvelope(
  config: Partial<PivotConfig>,
  options: PivotStateJsonOptions =;

---

parsePivotStateJson

export function parsePivotStateJson(json: string): Partial<PivotConfig>;

---

parsePivotStateJsonEnvelope

export function parsePivotStateJsonEnvelope(json: string): PivotStateJsonEnvelope;

---

stableJsonStringify

export function stableJsonStringify(value: unknown): string;

---

PIVOT_STATE_JSON_KIND

PIVOT_STATE_JSON_KIND: string;

---

PIVOT_STATE_JSON_VERSION

PIVOT_STATE_JSON_VERSION: 1;

---

PivotStateJsonEnvelope

interface PivotStateJsonEnvelope {
  kind: typeof PIVOT_STATE_JSON_KIND;
  version: typeof PIVOT_STATE_JSON_VERSION;
  config: Partial<PivotConfig>;
  exportedAt?: string
}

---

PivotStateJsonOptions

interface PivotStateJsonOptions {
  /**
     * Timestamp to include in the exported state. Omit it for deterministic JSON
     * without a time field.
     */
    exportedAt?: string | Date;
  /**
     * Adds an export timestamp generated by this callback when `exportedAt` is
     * not provided. This keeps tests deterministic without mocking Date.
     */
    now?: () => string | Date
}

---

createPivotConditionalCellProperties

export function createPivotConditionalCellProperties(
  rules: PivotConditionalFormatRule[],
  options: PivotConditionalCellPropertiesOptions =;

---

getPivotConditionalCellProperties

export function getPivotConditionalCellProperties(
  params: CellTemplateProp,
  rules: PivotConditionalFormatRule[],
  options: PivotConditionalCellPropertiesOptions =;

---

evaluatePivotConditionalFormatRule

export function evaluatePivotConditionalFormatRule(
  value: unknown,
  rule: PivotConditionalFormatRule,
): boolean;

---

isPivotAnalyticalCell

export function isPivotAnalyticalCell(params: Pick<CellTemplateProp, 'column'>): boolean;

---

PivotConditionalFormatOperator

export type PivotConditionalFormatOperator =
  | 'gt'
  | 'lt'
  | 'between'
  | 'equal'
  | 'contains';

---

PivotConditionalFormatRule

interface PivotConditionalFormatRule {
  /** Comparison operation used against the rendered analytical cell value. */
    operator: PivotConditionalFormatOperator;
  /** Comparison value for `gt`, `lt`, `equal`, and `contains`; tuple bounds for `between`. */
    value?: unknown;
  /** Inclusive lower bound for `between` when `value` is not a tuple. */
    min?: unknown;
  /** Inclusive upper bound for `between` when `value` is not a tuple. */
    max?: unknown;
  /** Optional generated value field selector. Omit to target every analytical cell. */
    field?: ColumnProp | ColumnProp[];
  /** Optional class value merged into the returned RevoGrid cell props. */
    class?: CellClassValue;
  /** Optional style value merged into the returned RevoGrid cell props. */
    style?: CellStyleValue;
  /** Additional RevoGrid cell props to return when the rule matches. */
    props?: CellProps;
  /** Makes `equal` and `contains` string comparisons case-sensitive. */
    caseSensitive?: boolean
}

---

PivotConditionalCellPropertiesOptions

interface PivotConditionalCellPropertiesOptions {
  /**
     * Return only the first matching rule or merge all matching rules.
     * Defaults to `first` for predictable conditional-formatting priority.
     */
    match?: 'first' | 'all';
  /** Allows applying rules to non-generated row fields. Defaults to false. */
    includeNonAnalytical?: boolean
}

---

pivotConditionalFormattingPresets

pivotConditionalFormattingPresets: {
  gt: (value: unknown, props?: PivotConditionalFormatPresetProps) => PivotConditionalFormatRule;
  lt: (value: unknown, props?: PivotConditionalFormatPresetProps) => PivotConditionalFormatRule;
  between: (min: unknown, max: unknown, props?: PivotConditionalFormatPresetProps) => PivotConditionalFormatRule;
  equal: (value: unknown, props?: PivotConditionalFormatPresetProps) => PivotConditionalFormatRule;
  textContains: (value: unknown, props?: PivotConditionalFormatPresetProps) => PivotConditionalFormatRule;
};

---

bindPivotPluginEvents

Wires grid/plugin events to Pivot orchestration without owning UI rendering, request mapping, or grid mutations.

@param host - Controller facade used to react to RevoGrid events while

• keeping UI lifecycle, grid mutation, and remote request state isolated.

export function bindPivotPluginEvents(host: PivotEventBindingHost);

---

getPivotRowProps

Returns the effective leading row props, including values-on-rows metadata.

export function getPivotRowProps(config?: Partial<PivotConfig> | null): ColumnProp[];

---

isPivotRowDrillDownEnabled

Checks whether Pivot should enable grouped row expansion metadata.

export function isPivotRowDrillDownEnabled(config?: Partial<PivotConfig> | null);

---

getPivotGrouping

Converts Pivot row configuration into RevoGrid grouping options.

export function getPivotGrouping(config?: Partial<PivotConfig> | null): GroupingOptions | undefined;

---

isPivotColumnCollapseEnabled

Returns whether generated Pivot column groups should be collapsible.

export function isPivotColumnCollapseEnabled(config?: Partial<PivotConfig> | null);

---

getPivotColumnCollapsed

Resolves whether a generated Pivot column group should currently be collapsed.

export function getPivotColumnCollapsed(
  config: Partial<PivotConfig> | null | undefined,
  key: string,
);

---

markPivotRowGenerated

Marks synthetic Pivot rows so the plugin can distinguish managed source.

export function markPivotRowGenerated(row: DataType);

---

isPivotGeneratedSourceRow

Checks whether a source row was generated by Pivot rather than provided by the caller.

export function isPivotGeneratedSourceRow(row?: DataType);

---

isPivotGrandTotalRow

Checks whether a Pivot row is the synthetic grand total row.

export function isPivotGrandTotalRow(row?: DataType);

---

isPivotSubtotalRow

Checks whether a Pivot row is a generated subtotal row.

export function isPivotSubtotalRow(row?: DataType);

---

isPivotTotalRow

Checks whether a Pivot row is a generated subtotal or grand-total row.

export function isPivotTotalRow(row?: DataType);

---

isPivotLeafInSubtotal

Checks whether a Pivot leaf row belongs under a subtotal row.

export function isPivotLeafInSubtotal(row: DataType | undefined, subtotalRow: DataType | undefined);

---

markPivotColumnsGenerated

Marks all generated Pivot columns recursively.

export function markPivotColumnsGenerated(
  columns: Array<ColumnGrouping | ColumnRegular>,
): Array<ColumnGrouping | ColumnRegular>;

---

arePivotGeneratedColumns

Checks whether an entire column tree was generated by Pivot.

export function arePivotGeneratedColumns(
  columns: Array<ColumnGrouping | ColumnRegular> = [],
): boolean;

---

createPivotColumnGroupMeta

Adds column-collapse metadata to a generated Pivot group when it is useful.

export function createPivotColumnGroupMeta<T extends Record<string, any>>(
  group: T,
  key: ColumnProp,
  config?: Partial<PivotConfig> | null,
  collapsed = false,
  options:;

---

getPivotCollapsedAggregator

Resolves the measure aggregator used for collapsed placeholder cells.

export function getPivotCollapsedAggregator(
  config: Partial<PivotConfig> | null | undefined,
  prop: ColumnProp,
  fallback: string,
);

---

PIVOT_GENERATED

PIVOT_GENERATED: string;

---

PIVOT_GROUP_KEY

PIVOT_GROUP_KEY: string;

---

PIVOT_COLLAPSE_HIDDEN_COUNT

PIVOT_COLLAPSE_HIDDEN_COUNT: string;

---

PIVOT_GRAND_TOTAL_ROW_KEY

PIVOT_GRAND_TOTAL_ROW_KEY: string;

---

PIVOT_VALUE_LABEL

PIVOT_VALUE_LABEL: string;

---

PIVOT_VALUE_PROP

PIVOT_VALUE_PROP: string;

---

resolvePivotGroupLabels

export function resolvePivotGroupLabels(
  config?: Partial<PivotConfig> | null,
): ResolvedPivotGroupLabels;

---

getPivotGroupKey

export function getPivotGroupKey(value: PivotGroupValue);

---

getPivotGroupLabel

export function getPivotGroupLabel(
  value: PivotGroupValue,
  labels: ResolvedPivotGroupLabels,
);

---

getPivotGroupDisplayValue

export function getPivotGroupDisplayValue(
  value: PivotGroupValue,
  labels: ResolvedPivotGroupLabels,
);

---

createColumnLabelProp

export function createColumnLabelProp(prop: ColumnProp);

---

PivotGroupValue

export type PivotGroupValue = string | number | boolean | null | undefined;

---

DEFAULT_EMPTY_GROUP_LABEL

DEFAULT_EMPTY_GROUP_LABEL: string;

---

DEFAULT_NULL_GROUP_LABEL

DEFAULT_NULL_GROUP_LABEL: string;

---

ResolvedPivotGroupLabels

interface ResolvedPivotGroupLabels {
  empty: string;
  null: string
}

---

resolvePivotRowLayout

export function resolvePivotRowLayout(
  config?: Partial<PivotConfig> | null,
): PivotRowLayout;

---

getPivotValueLabel

export function getPivotValueLabel(;

---

PivotRowLayout

interface PivotRowLayout {
  /** Source row fields used to aggregate the analytical row path. */
    rowFields: ColumnProp[];
  /** Visible row props rendered in RevoGrid, including the value pseudo-field. */
    props: ColumnProp[];
  /** Whether value measures are materialized as synthetic row members. */
    valuesOnRows: boolean;
  /** True when the advanced rowTree API is controlling placement. */
    explicitRowTree: boolean
}

---

resolvePivotTotals

Resolves totals config into a complete object with defaults applied.

export function resolvePivotTotals(
  totals?: Partial<PivotConfig['totals']>,
): ResolvedPivotTotals;

---

isPivotSubtotalEnabled

export function isPivotSubtotalEnabled(
  totals: ResolvedPivotTotals,
  axis: keyof ResolvedPivotTotals['disabledSubtotals'],
  field: ColumnProp | undefined,
  level: number,
);

---

buildLeafColumnKey

Builds the synthetic column key for a leaf analytical path.

export function buildLeafColumnKey(path: PivotGroupValue[]);

---

buildSubtotalColumnKey

Builds the subtotal key for an intermediate analytical path.

export function buildSubtotalColumnKey(path: PivotGroupValue[]);

---

buildCollapsedColumnKey

Builds the collapsed placeholder key for an intermediate analytical path.

export function buildCollapsedColumnKey(path: PivotGroupValue[]);

---

PIVOT_GRAND_TOTAL

PIVOT_GRAND_TOTAL: string;

---

PIVOT_SUBTOTAL

PIVOT_SUBTOTAL: string;

---

PIVOT_COLLAPSE

PIVOT_COLLAPSE: string;

---

DEFAULT_GRAND_TOTAL_LABEL

DEFAULT_GRAND_TOTAL_LABEL: string;

---

DEFAULT_SUBTOTAL_LABEL

DEFAULT_SUBTOTAL_LABEL: string;

---

ResolvedPivotTotals

interface ResolvedPivotTotals {
  grandTotal: boolean;
  subtotals: boolean;
  disabledSubtotals: {
      rows: ResolvedPivotSubtotalDisableRule;
      columns: ResolvedPivotSubtotalDisableRule;
    };
  grandTotalLabel: string;
  subtotalLabel: string;
  suppressSingleChildSubtotals: boolean;
  suppressGrandTotalWhenSingleLeaf: boolean
}

---

ResolvedPivotSubtotalDisableRule

interface ResolvedPivotSubtotalDisableRule {
  fields: Set<ColumnProp>;
  levels: Set<number>
}

---

PivotRemoteController

Owns server/client-adapter Pivot loads: request state, cancellation, stale-response checks, and pagination synchronization.

Dependencies

• Config integration additionalData.pagination: Reads and writes legacy pagination config to synchronize remote pivot paging.
• Config integration direct-pagination-config: Reads and writes direct grid.pagination config to synchronize remote pivot paging.
• Optional pagination-capable-plugin: Calls setPage on a pagination-capable plugin when present.

class PivotRemoteController {
  setFilterCollection(collection?: Record<ColumnProp, FilterCollectionItem>);

  setSorting(sorting?: SortingOrder);

  getDisplaySorting(localSorting?: SortingOrder, isRemote = false);

  createLoadRequest(config: Partial<PivotConfig>): PivotLoadRequest;

  async apply(config: Partial<PivotConfig>, rowOffset?: number);

  resetPagination();

  invalidateLoad(clearDiagnostics = true);

  clearState();

  getPageRowOffset(detail: PageChangeEvent, config: Partial<PivotConfig>);

  createGridModel(config: Partial<PivotConfig>, response: PivotLoadResponse);
}

---

createPivotLoadRequest

export function createPivotLoadRequest(overrides: Partial<PivotLoadRequest> =;

---

pivotFieldRegistry

pivotFieldRegistry: PivotFieldRegistry;

---

PivotGridController

Owns the RevoGrid-facing state transitions for Pivot mode.

This class deliberately avoids event wiring, remote request construction, and panel rendering so grid mutation stays isolated from orchestration code.

class PivotGridController {
  setOriginalData(source: DataType[]);

  setOriginalColumns(columns: (ColumnRegular | ColumnGrouping)[]);

  isPivotManagedSource(source: DataType[] = []);

  isPivotManagedColumns(columns: (ColumnRegular | ColumnGrouping)[] = []);

  activate(config: Partial<PivotConfig>);

  clearGroupAggregates();

  applyClientPivot(config: Partial<PivotConfig>);

  applyRemotePivotModel(
    config: Partial<PivotConfig>,
    gridModel: PivotGridModel,
    groupAggregates: PivotGroupAggregates =;

  clearPivot();

  renderOriginalGrid(
    columns: (ColumnRegular | ColumnGrouping)[] = [],
  );
}

---

createPivotLoadRequestFromConfig

Builds a complete remote Pivot load request from config plus current UI state.

export function createPivotLoadRequestFromConfig(;

---

normalizePivotFilterCollection

Removes empty filter entries so server requests only include active predicates.

export function normalizePivotFilterCollection(collection?: Record<ColumnProp, FilterCollectionItem>);

---

normalizePivotSorting

Removes unset sort entries and returns undefined when no remote sorting remains.

export function normalizePivotSorting(sorting?: SortingOrder);

---

toPivotSummaryType

Converts public Pivot aggregator ids into the server-supported summary enum.

export function toPivotSummaryType(aggregator: string): PivotSummaryType;

---

PivotLoadRequestMapperOptions

interface PivotLoadRequestMapperOptions {
  /** Pivot configuration from direct `grid.pivot` or the active plugin state. */
    config: Partial<PivotConfig>;
  /** Current row-axis offset, usually derived from pagination. */
    rowOffset?: number;
  /** Current row-axis window size, usually pagination `itemsPerPage`. */
    rowLimit?: number;
  /** Current column-axis offset for server-side column virtualization. */
    columnOffset?: number;
  /** Current column-axis window size for server-side column virtualization. */
    columnLimit?: number;
  /** Normalized RevoGrid filter collection to forward as a Pivot filter tree. */
    filters?: Record<ColumnProp, FilterCollectionItem>;
  /** Normalized RevoGrid sorting state to forward as Pivot sort descriptors. */
    sorting?: SortingOrder;
  /** Optional stable request id for tests, tracing, or caller-managed correlation. */
    requestId?: string
}

---

createPivotGroupLabelTemplate

export function createPivotGroupLabelTemplate(
  groupAggregatesByPath: PivotGroupAggregates,
  options:;

---

PV_PARENT_CL

PV_PARENT_CL: string;

---

PV_PARENT_CFG_CL

PV_PARENT_CFG_CL: string;

---

PV_PARENT_FIELD_PANEL_CL

PV_PARENT_FIELD_PANEL_CL: string;

---

PivotUiController

Owns the optional Pivot configurator and compact field-panel DOM lifecycle.

class PivotUiController {
  attachRootClass();

  setTheme(theme: Theme = 'default');

  clear();

  setDiagnostics(diagnostics?: PivotUiDiagnostics);

  updateConfigurator(config?: Partial<PivotConfig>);

  updateFieldPanel(
    config?: Partial<PivotConfig>,
    resizedColumns?: ColumnResizeDetail,
  );
}