@kanunilabs/pivotgrid-core 1.5.0 → 1.7.0

package/dist/index.d.cts

@@ -164,22 +164,6 @@ interface PivotDictionary {
     drillDown: string;
     /** `Label: {count}` — no plural engine, so no locale is ever ungrammatical. */
     drillDownRecords: string;
-    /** Chart panel (#214); the eleven shared strings come from DataGrid. */
-    chart: string;
-    chartClose: string;
-    chartFullscreen: string;
-    chartExitFullscreen: string;
-    chartEmpty: string;
-    /** `Showing {shown} of {total}.` — used for categories AND for series. */
-    chartWindowed: string;
-    chartTypeColumn: string;
-    chartTypeBar: string;
-    chartTypeLine: string;
-    chartTypeArea: string;
-    chartTypePie: string;
-    chartTypeScatter: string;
-    chartTypePolar: string;
-    chartTypeCombination: string;
     /** PDF export header (#215). */
     exportGeneratedOn: string;
     /** Designer level tiles and live formula verdict (#220). */
@@ -316,6 +300,310 @@ declare class PivotSelectionModel {
     private static getBounds;
 }
 
+/** How a cartesian chart lays out several series: beside, on top, or as shares of 100. */
+type ChartStacking = 'grouped' | 'stacked' | 'normalized';
+interface StackedSegment {
+    /** Where the segment starts, per category. NaN where the series has no value. */
+    low: Float64Array;
+    /** Where it ends; a line is drawn through these. NaN where the series has no value. */
+    high: Float64Array;
+    /**
+     * The value's percentage of its category's absolute total (`normalized`
+     * only; NaN otherwise and where there is no value) — what a tooltip prints
+     * next to the raw number.
+     */
+    share: Float64Array;
+}
+/**
+ * Value-axis ticks for a 100% stack: every 25%, ending exactly at 100.
+ *
+ * A general "nice ticks" routine rounds the domain OUTWARD, and on a 100%
+ * stack that drew an axis running to 150% above bars that cannot pass 100
+ * (seen in the first visual check, 2026-10-02). `min` is the lowest segment
+ * edge — below zero only when some values are negative.
+ */
+declare function percentAxisTicks(min: number): number[];
+/**
+ * Lay series out on top of one another.
+ *
+ * `series[s][c]` is the value of series `s` in category `c`. The result is
+ * index-aligned with `series`; an excluded series (hidden from the legend)
+ * comes back as `null` and takes no room in the stack. Earlier series sit
+ * nearer the axis.
+ */
+declare function stackSeries(series: ReadonlyArray<ArrayLike<number>>, mode: Exclude<ChartStacking, 'grouped'>, include?: (index: number) => boolean): Array<StackedSegment | null>;
+
+/** Where the legend sits around the plot, or `'none'` to hide it. */
+type ChartLegendPosition = 'top' | 'bottom' | 'left' | 'right' | 'none';
+interface ChartFormat {
+    /** Shown above the chart, and written into an exported image. */
+    title?: string;
+    /** Caption under the category axis (the left one for horizontal bars). */
+    categoryAxisTitle?: string;
+    /** Caption beside the value axis. */
+    valueAxisTitle?: string;
+    /** Default `'top'`. */
+    legend?: ChartLegendPosition;
+    /** Print each value on its mark. Default `false`. */
+    dataLabels?: boolean;
+    /**
+     * The value axis: `'linear'` (default) or `'log'` — for values spanning
+     * several orders of magnitude, where a linear axis flattens all but the
+     * largest. A log axis cannot show zero or a negative value; those marks are
+     * left out. It does not apply to a stacked layout, whose segments add up.
+     */
+    valueScale?: 'linear' | 'log';
+}
+/**
+ * Value-axis ticks for a log scale: every power of ten from just below `min`
+ * to just above `max` (both > 0). With fewer than two decades the 2 and 5
+ * steps in between are added so the axis still has something to read.
+ */
+declare function logAxisTicks(min: number, max: number): number[];
+declare const CHART_LEGEND_POSITIONS: readonly ChartLegendPosition[];
+/**
+ * A saved format read back defensively — from storage, a report or an older
+ * build — keeping only fields of the right kind. Key order is fixed, so two
+ * formats with the same content serialise the same.
+ */
+declare function readChartFormat(value: unknown): ChartFormat;
+/**
+ * What a chart API's image calls take — `getImageDataUrl` and `download` on
+ * the DataGrid chart API, `getChartImageDataUrl` and `downloadChart` on the
+ * PivotGrid one.
+ */
+interface ChartImageRequest {
+    /** `'png'` (default), `'jpeg'` or `'svg'`. */
+    format?: 'png' | 'jpeg' | 'svg';
+    /** File name without extension (`download` only). Defaults to one naming what the chart shows. */
+    fileName?: string;
+    /**
+     * Image size in CSS pixels. One side keeps the chart's proportions; both fix
+     * the box and centre the chart in it. Ignored for SVG, which scales anyway.
+     */
+    width?: number;
+    height?: number;
+    /** JPEG quality, 0–1. Default `0.92`. */
+    quality?: number;
+    /** Raster pixel ratio. Default `2`. */
+    pixelRatio?: number;
+    /** Background colour; `null` keeps transparency (not for JPEG). Default white. */
+    background?: string | null;
+}
+/**
+ * `count` colours derived from `accent`, index-stable.
+ *
+ * Falls back to the packaged eight when the accent cannot be read — an unthemed
+ * grid, or a custom theme whose `--dg-primary` is something this cannot parse
+ * (a named colour, `color-mix()`, `oklch()`). Falling back is deliberate: a
+ * chart with the wrong-but-readable palette beats a chart of black shapes.
+ *
+ * A near-grey accent also falls back. Rotating the hue of something with almost
+ * no saturation produces eight indistinguishable greys, which is worse than an
+ * off-theme palette that can actually be told apart.
+ */
+declare function chartPalette(accent: string | null | undefined, count: number): string[];
+
+interface WaterfallStep {
+    /** Running total before and after this step. */
+    start: number;
+    end: number;
+    /** An increase, a decrease, or the closing total bar (which starts at zero). */
+    kind: 'up' | 'down' | 'total';
+    /** The step's own value (the total's value is the running total). */
+    value: number;
+}
+/**
+ * Each category moves the running total by its value; the bar floats from the
+ * old total to the new one. With `total`, a last bar shows where it ended,
+ * standing on zero. NaN ("nothing to total") moves nothing and draws a step
+ * of zero height, so the categories stay aligned.
+ */
+declare function waterfallSteps(values: ArrayLike<number>, total?: boolean): WaterfallStep[];
+/** Lowest and highest point a waterfall reaches, zero included. */
+declare function waterfallDomain(steps: readonly WaterfallStep[]): {
+    min: number;
+    max: number;
+};
+interface FunnelStage {
+    /** Index into the input values. */
+    index: number;
+    value: number;
+    /** Bar width as a share of the widest stage, 0..1. */
+    ratio: number;
+    /** Share of the FIRST stage (the funnel's conversion so far), 0..1. */
+    ofFirst: number;
+}
+/**
+ * Stages in the order given — a funnel's order is the process, not the
+ * magnitude, so it is never re-sorted. Negative and NaN values are stages of
+ * zero width: a funnel stage cannot hold less than nothing.
+ */
+declare function funnelStages(values: ArrayLike<number>): FunnelStage[];
+interface TreemapCell {
+    /** Index into the input values. */
+    index: number;
+    value: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Squarified treemap (Bruls, Huizing, van Wijk): rectangles with areas
+ * proportional to the values, laid out to stay as close to square as the
+ * values allow — a long thin sliver is hard to compare and to label. Only
+ * positive values take area; the rest are left out (a negative area has no
+ * meaning). Largest first.
+ */
+declare function squarify(values: ArrayLike<number>, x: number, y: number, width: number, height: number): TreemapCell[];
+/**
+ * A heatmap cell's colour: `t` in 0..1 between `from` and `to` (hex colours),
+ * as an `rgb()` literal — a presentation attribute cannot hold `var()`.
+ */
+declare function heatColor(t: number, from?: string, to?: string): string;
+/** Text that stays readable on a heat colour: dark on light cells, white on dark. */
+declare function heatTextColor(t: number): string;
+
+type MarkTone = 'muted' | 'border' | 'text';
+type ChartMark = {
+    kind: 'rect';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    fill: string;
+    /** Category / series index, for tooltips and clicks (absent on chrome). */
+    ci?: number;
+    si?: number;
+    /** Native tooltip text. */
+    title?: string;
+    rx?: number;
+    opacity?: number;
+} | {
+    kind: 'text';
+    x: number;
+    y: number;
+    text: string;
+    anchor: 'start' | 'middle' | 'end';
+    size?: number;
+    weight?: number;
+    /** A literal colour, or a chrome role. */
+    fill?: string;
+    tone?: MarkTone;
+    /** Degrees, about (x, y). */
+    rotate?: number;
+} | {
+    kind: 'line';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    dashed?: boolean;
+    tone: MarkTone;
+} | {
+    /** An SVG path — the arcs of a sunburst. */
+    kind: 'path';
+    d: string;
+    fill: string;
+    ci?: number;
+    si?: number;
+    title?: string;
+    opacity?: number;
+};
+interface ShapeChartInput {
+    /** Category labels, blanks already captioned. */
+    categories: string[];
+    /** The series to draw (hidden ones already left out), each with its ORIGINAL index. */
+    series: Array<{
+        index: number;
+        label: string;
+        values: ArrayLike<number>;
+        color: string;
+    }>;
+    width: number;
+    height: number;
+    /** A value as the series' column or measure prints it. */
+    format: (seriesIndex: number, value: number) => string;
+    /** Compact axis captions ("5.5M"). */
+    compact: (value: number) => string;
+    /** Caption of the waterfall's closing bar. */
+    totalLabel?: string;
+    /** Category / value axis titles (waterfall). */
+    categoryAxisTitle?: string;
+    valueAxisTitle?: string;
+    /** Colours: waterfall up / down / total, heatmap ramp ends. Defaults are neutral. */
+    colors?: {
+        up?: string;
+        down?: string;
+        total?: string;
+        heatFrom?: string;
+        heatTo?: string;
+    };
+    rtl?: boolean;
+}
+/**
+ * The first series as a waterfall: each category moves the running total,
+ * increases and decreases coloured apart, a closing total bar on zero.
+ * Connector lines run from each bar's end to the next bar's start.
+ */
+declare function waterfallMarks(input: ShapeChartInput): ChartMark[];
+/**
+ * The first series as a funnel: one centred bar per category, in the given
+ * order (the order is the process), each labelled with its value and its
+ * share of the first stage.
+ */
+declare function funnelMarks(input: ShapeChartInput, percentText: (share: number) => string): ChartMark[];
+/**
+ * The first series as a treemap: a rectangle per category with area
+ * proportional to its value (positive values only), labelled where the
+ * label fits. Colours run through the given palette by category.
+ */
+declare function treemapMarks(input: ShapeChartInput, palette: readonly string[]): ChartMark[];
+/**
+ * Categories across, series down, each cell coloured by its value on one ramp
+ * over all the visible cells — a matrix read at a glance. Values print in the
+ * cells that have room; a cell with nothing to total stays blank.
+ */
+declare function heatmapMarks(input: ShapeChartInput): ChartMark[];
+/**
+ * The first two series as a RANGE per category: one floating bar from the
+ * lower of the two values to the higher — a day's low and high, a price band,
+ * a planned-versus-actual span. Which series is "low" does not matter: each
+ * category draws from its own smaller value to its larger one. A category
+ * missing either value draws nothing (a span needs both ends).
+ */
+declare function rangeBarMarks(input: ShapeChartInput): ChartMark[];
+interface SunburstInput {
+    /**
+     * The leaves, each with its path from the outermost level in (`['EMEA',
+     * 'Berlin']`), its value and the category index a click or tooltip names.
+     * Inner rings are the sums of the leaves under them.
+     */
+    leaves: Array<{
+        path: readonly string[];
+        value: number;
+        ci: number;
+    }>;
+    width: number;
+    height: number;
+    /** One colour per outermost-level node; deeper rings take their parent's, lighter. */
+    colors: readonly string[];
+    format: (value: number) => string;
+    /** The share of the whole, as the reader's locale prints a percentage. */
+    percentText: (share: number) => string;
+}
+/**
+ * A hierarchy as rings: the outermost level in the middle ring, each level
+ * further out, every arc's angle its share of the whole. The leaves sum up
+ * into their parents, so the picture answers "what is this made of, and of
+ * what is that made". Zero, negative and missing leaves take no angle.
+ */
+declare function sunburstMarks(input: SunburstInput): ChartMark[];
+/** The chart types laid out here. */
+declare const SHAPE_CHART_TYPES: readonly ["waterfall", "funnel", "treemap", "heatmap", "rangeBar", "sunburst"];
+type ShapeChartType = (typeof SHAPE_CHART_TYPES)[number];
+
 type DateFormatContext = 'grid' | 'chart' | 'export';
 type DateGranularity = 'year' | 'quarter' | 'month' | 'day' | 'dayOfWeek' | string | number;
 declare class DateFormatter {
@@ -382,6 +670,12 @@ interface WorkerFilterSpec {
     fieldId: string;
     filterType: 'include' | 'exclude';
     dictIds: number[];
+    /**
+     * Filter values the dictionary does not hold yet. No stored row can match
+     * them, but a row added by a later transaction can — a rebuild would include
+     * it, so the engine keeps them and resolves them as the dictionary grows.
+     */
+    valueStrings?: string[];
 }
 interface PrefilterConditionSpec {
     fieldId: string;
@@ -473,6 +767,23 @@ interface WorkerReconfigureRequest {
     /** Dictionary entries appended (in order) since the worker's dictionary was last synced. */
     dictionaryAppend?: string[];
 }
+/**
+ * Live update (G-PIV-02): replace, remove and append rows of the stored
+ * columns. Positions are those BEFORE the transaction; `update` and `remove`
+ * never share a position. `columns` carries, for EVERY stored column, the
+ * values of the updated rows (in `update` order) followed by the added rows —
+ * encoded by the main thread with the same field definitions as the column.
+ */
+interface WorkerTransactionRequest {
+    action: 'transaction';
+    id: string;
+    update: Int32Array;
+    /** Ascending. */
+    remove: Int32Array;
+    addCount: number;
+    columns: Record<string, ArrayBuffer>;
+    dictionaryAppend?: string[];
+}
 /**
  * Flat cell matrix returned by the engine.
  * `keys[i]` = `rowId * MAX_C + colId` hash; `sums[i * numDF + df]` = finalized aggregated value.
@@ -485,11 +796,31 @@ interface FlatCellMatrix {
     /** Post-processed display values after summary display modes are applied. */
     displaySums?: Float64Array;
 }
+/**
+ * What the main thread needs to run `summaryType: 'custom'` measures.
+ *
+ * A custom summary is the customer's own function (or a registry aggregator),
+ * and functions cannot be posted to a worker — so the worker groups and the
+ * main thread summarises. Each stored row is mapped to its leaf group, and
+ * each leaf group to the visible cells it rolls up into, so the main thread
+ * feeds every cell exactly the rows that cell covers, in source-row order.
+ */
+interface CustomSummaryInputs {
+    /** Leaf group of each stored row; -1 for a row the filters removed. */
+    rowGroupOf: Int32Array;
+    /** Cells of leaf group g are `groupCells[groupCellOffsets[g] .. groupCellOffsets[g + 1])` (cell flat indexes). */
+    groupCellOffsets: Int32Array;
+    groupCells: Int32Array;
+    /** Per-row value of each custom data field, by field id, as encoded for the worker. */
+    values: Record<string, Float64Array>;
+}
 interface WorkerResponse {
     id: string;
     rowTree: PivotNode[];
     colTree: PivotNode[];
     cellMatrix: FlatCellMatrix;
+    /** Present only when a data field has `summaryType: 'custom'`. */
+    customSummary?: CustomSummaryInputs;
     rowIndexMap: Record<string, number>;
     columnIndexMap: Record<string, number>;
     cardinalityMap: Record<string, number>;
@@ -505,13 +836,18 @@ interface WorkerResponse {
     isInitComplete?: boolean;
     isFilterComplete?: boolean;
     isReconfigureComplete?: boolean;
+    isTransactionComplete?: boolean;
+    /** Rows stored after a transaction — the main thread checks it against its own array. */
+    rowCount?: number;
 }
 /**
  * TypedArray-based pivot computation engine designed to run inside a Web Worker.
  *
  * Pipelines: monolithic `init()` → `applyFilter()` → `compute()`, or the
  * chunked `initStart()` → `initChunk()`× → `initEnd()` → `compute()` (filters
- * applied during the chunked build; result state is identical).
+ * applied during the chunked build; result state is identical). Either may be
+ * followed by any number of `applyTransaction()` (live updates) — the state
+ * after each is the one a fresh init over the resulting rows would reach.
  * Uses {@link FastTrie} for hierarchical grouping and pre-aggregates leaf groups
  * into flat TypedArrays supporting SUM, COUNT, AVG, MIN, MAX, and DISTINCT.
  */
@@ -525,8 +861,13 @@ declare class FlatPivotEngine {
     private lastMask;
     private isBuilt;
     private buildState;
-    private incrementalFilters;
-    private incrementalPrefilter;
+    private activeFilters;
+    private activePrefilter;
+    private tracking;
+    private groupRows;
+    private groupMap;
+    private rowLive;
+    private colLive;
     private rowTrie;
     private colTrie;
     private cardinalityMap;
@@ -543,6 +884,7 @@ declare class FlatPivotEngine {
     private leafGroupMins;
     private leafGroupMaxes;
     private leafGroupDistinctSets;
+    private rowGroupOf;
     init(req: WorkerInitRequest): void;
     /**
      * Swap field roles and regroup the already-stored columnar data under the
@@ -561,6 +903,10 @@ declare class FlatPivotEngine {
     initChunk(req: WorkerInitChunkRequest): void;
     /** Close the chunked init and commit the accumulated build. */
     initEnd(): void;
+    /** Append dictionary entries and resolve pending filter strings against them. */
+    private appendDictionary;
+    /** Put filters in force and size the mask for them (null when nothing filters). */
+    private setFilters;
     /**
      * Resolve pending filter value strings against dictionary entries from
      * `fromIndex` on. A string that is not yet in the dictionary cannot match
@@ -584,8 +930,42 @@ declare class FlatPivotEngine {
     private processRange;
     /** Commit the build state into the engine + rebuild per-build caches. */
     private finalizeBuild;
+    /** Path string per trie node; `known` (from an earlier pass) is extended, not redone. */
     private buildPathStrs;
     private buildIndexMap;
+    /**
+     * Live update (G-PIV-02): replace, remove and append rows, then bring the
+     * groups up to date — without re-reading the rows that did not change.
+     *
+     * What it costs, and why each part is there:
+     * - Each changed row is regrouped (two trie walks, one group lookup).
+     * - Every leaf group a changed row left or joined is RE-SUMMED from its
+     *   rows, in row order, in one pass over the row→group column. Not patched
+     *   by subtracting the old value: for floats that drifts (0.1 + 0.2 - 0.2 is
+     *   0.10000000000000003) and the error walks with every tick; min, max and
+     *   distinct cannot be un-applied at all. A re-sum in row order produces the
+     *   very value a rebuild produces.
+     * - Removing rows compacts the stored columns (a memmove per column), so
+     *   rows stay in the order of the array the main thread holds.
+     * - Only when a group appears, empties or comes back is node visibility,
+     *   the index maps and the cardinality redone — O(groups + nodes), never
+     *   O(rows).
+     * The first transaction turns tracking on with one regroup of the stored
+     * columns (no re-encode, no transfer), and once empty groups outnumber live
+     * ones the engine regroups again rather than carry them through every
+     * compute. Returns the number of rows stored afterwards.
+     */
+    applyTransaction(req: WorkerTransactionRequest): number;
+    /** Reset the touched groups and fold their rows back in — the same arithmetic, in the same order, as processRange. */
+    private resumGroups;
+    /**
+     * One trie, after a transaction reshaped the groups: which nodes a live
+     * group still reaches, each node's live child count (what `hasChildren`
+     * reads), the path strings for nodes it created, the index map without the
+     * dead nodes, and the fields' cardinality counted over live nodes — what
+     * the build's seen-bitmaps count over rows.
+     */
+    private relive;
     compute(req: WorkerComputeRequest): WorkerResponse;
 }
 
@@ -596,6 +976,11 @@ interface PivotEngineResult {
     rowIndexMap: Record<string, number>;
     columnIndexMap: Record<string, number>;
     cardinalityMap: Record<string, number>;
+    /**
+     * Worker grouping for `summaryType: 'custom'` measures, consumed (and then
+     * removed) by `applyCustomSummaries` before any other post-phase.
+     */
+    customSummary?: CustomSummaryInputs;
 }
 interface FieldDistinctEntry {
     rawStr: string;
@@ -645,7 +1030,7 @@ declare function initPivotEngineAsync<TRow>(data: TRow[], rowFields: PivotField<
  * full {@link initPivotEngineAsync}.
  */
 declare function reconfigurePivotEngineAsync<TRow>(data: TRow[], rowFields: PivotField<TRow>[], colFields: PivotField<TRow>[], dataFields: PivotField<TRow>[], registry?: PivotEngineRegistry, 
-/** All fields + the active prefilter, so its columns are encoded too. */
+/** All fields + the active prefilter, so the filters' columns are encoded too. */
 prefilterState?: {
     fields: PivotField<TRow>[];
     prefilter?: PivotPrefilter;
@@ -656,6 +1041,17 @@ prefilterState?: {
  * set lookups on columnar data instead of string comparisons.
  */
 declare function filterPivotEngineAsync(fields: PivotField<any>[], prefilter?: PivotPrefilter): Promise<void>;
+/**
+ * Live update (G-PIV-02): a resolved transaction, in positions of the array
+ * the engine holds. See controller/rowTransaction.ts.
+ */
+interface EngineRowChange<TRow> {
+    data: TRow[];
+    updateIndex: number[];
+    updateRows: TRow[];
+    removeIndex: number[];
+    addRows: TRow[];
+}
 declare function computePivotMatrixAsync(expandedPaths: string[], expandedColPaths: string[]): Promise<PivotEngineResult>;
 /**
  * Cached distinct values for a header filter.
@@ -674,6 +1070,19 @@ interface PivotReportState {
     expandedPaths: string[];
     expandedColPaths?: string[];
     chartState?: Record<string, unknown>;
+    /**
+     * State kept by layers above the core, by name — the Enterprise chart panel
+     * keeps its chart under `chart`. A report saved before a part existed has
+     * none, and loading it leaves that part as it is.
+     */
+    parts?: Record<string, unknown>;
+}
+/** A piece of a saved report owned outside the core (see `registerReportStatePart`). */
+interface ReportStatePart {
+    /** A JSON-safe snapshot of the part. */
+    get(): unknown;
+    /** Restore a snapshot `get` produced (or an older build's — validate it). */
+    apply(value: unknown): void;
 }
 interface PivotReport {
     id: string;
@@ -713,6 +1122,23 @@ interface PivotReport {
  * insets from these numbers and React sizes its left pane from them, and two
  * copies of the arithmetic would be two copies to keep in step.
  */
+/** A row-header column's width when neither the app nor the user set one. */
+declare const DEFAULT_ROW_HEADER_WIDTH = 150;
+/** A data column's width when neither the app nor the user set one. */
+declare const DEFAULT_DATA_COLUMN_WIDTH = 95;
+/**
+ * `defaultColumnWidths` with every hole filled: what the renderers paint a
+ * column at when `columnWidths` has no entry for it.
+ *
+ * A value that is not a positive finite number falls back to the built-in
+ * default rather than painting a zero-width or NaN column; the row-header
+ * value is capped like a stored one, and the frozen-block budget below still
+ * compresses it when the viewport is narrow.
+ */
+declare function resolveColumnWidthDefaults(defaults?: PivotColumnWidthDefaults): {
+    rowHeader: number;
+    data: number;
+};
 declare const ROW_HEADER_MIN_DATA_STRIP = 160;
 declare const ROW_HEADER_MAX_PINNED_FRACTION = 0.6;
 /** However tight it gets, a row-header column stays wide enough to read. */
@@ -1003,13 +1429,34 @@ declare function buildPivotAOA(engineResult: PivotEngineResult, rowFields: Pivot
     styles: (ExportCellStyle | null)[][] | null;
 } | null>;
 
+type PivotRowKey = string | number;
+/** A field name, or a function returning the key — the DataGrid `rowKey` contract. */
+type PivotRowKeyResolver<TRow> = keyof TRow | ((row: TRow) => PivotRowKey);
+interface PivotRowTransaction<TRow> {
+    /** Rows appended after the existing ones. */
+    add?: TRow[];
+    /** Replace the row with the same key, in place. A key the grid does not have is ignored. */
+    update?: TRow[];
+    /** Keys, or rows (matched by their key), to take out. */
+    remove?: (PivotRowKey | TRow)[];
+}
+interface PivotTransactionResult {
+    added: number;
+    updated: number;
+    removed: number;
+}
+
 /** Area where a {@link PivotField} can be placed. */
 type PivotArea = 'row' | 'column' | 'data' | 'filter' | 'chooser';
 /** Aggregation function applied to data fields in worker pre-aggregation. */
 type PivotSummaryType = 'sum' | 'count' | 'avg' | 'min' | 'max' | 'distinct' | 'custom';
 /** Post-aggregation display transformation applied after cell values are computed. */
 type PivotSummaryDisplayMode = 'absolute' | 'percentOfTotal' | 'percentOfColumnTotal' | 'percentOfRowTotal' | 'runningTotal' | 'difference' | 'percentDifference';
-/** Temporal or numeric grouping interval for date/number fields. */
+/**
+ * Date grouping interval. `'numeric'` and `'custom'` are accepted for
+ * compatibility and have no effect (the grid reports them): numeric bins are
+ * set with a number on {@link PivotField.groupInterval}.
+ */
 type PivotGroupInterval = 'year' | 'quarter' | 'month' | 'day' | 'numeric' | 'custom';
 /** Supported UI locale identifiers. */
 type PivotLocale = 'tr' | 'en' | 'ar' | 'de' | 'fr' | 'es' | 'it' | 'pt' | 'ru' | 'zh-CN' | 'ja' | 'ko';
@@ -1091,10 +1538,27 @@ interface PivotField<TRow = any, TCellTemplate = PivotCellTemplate, TStyle = any
     areaIndex?: number;
     /** Whether the field is visible in the field chooser. */
     visible?: boolean;
-    /** Aggregation type — computed in the Web Worker for all types. */
+    /**
+     * Aggregation type. The built-ins are computed in the Web Worker; `'custom'`
+     * runs {@link PivotField.calculateCustomSummary} on the main thread over
+     * rows the worker grouped.
+     */
     summaryType?: PivotSummaryType;
     /** Post-aggregation display transformation (e.g. percent of total). */
     summaryDisplayMode?: PivotSummaryDisplayMode;
+    /**
+     * The summary for `summaryType: 'custom'`, run once per cell (leaf,
+     * subtotal and grand total alike) over that cell's own rows.
+     *
+     * - A function gets one options object per cell through three phases:
+     *   `'start'` (once), `'calculate'` (once per row, in source order, with the
+     *   row's value in `value`) and `'finalize'` (once). The cell shows
+     *   `totalValue` after finalize; other properties you set on the object
+     *   persist between phases.
+     * - A string names an aggregator registered with
+     *   `registry.registerAggregator(id, fn)`; `fn` receives the cell's values.
+     *   An unregistered name is an engine error, not a silent sum.
+     */
     calculateCustomSummary?: string | ((options: CustomSummaryOptions) => void);
     /** True for calculated (virtual) fields that derive from other fields. */
     isCalculated?: boolean;
@@ -1110,7 +1574,11 @@ interface PivotField<TRow = any, TCellTemplate = PivotCellTemplate, TStyle = any
     conditionalFormatting?: PivotConditionRule<TStyle>[];
     /** Custom cell render function. */
     cellTemplate?: TCellTemplate;
-    /** Date/numeric grouping interval. */
+    /**
+     * Grouping interval: `'year' | 'quarter' | 'month' | 'day'` for a date
+     * field, or a bin width as a number for a number field (`100` → 0–99,
+     * 100–199, …). `'numeric'` and `'custom'` have no effect.
+     */
     groupInterval?: PivotGroupInterval | number;
     /** Active filter values for header filter (include/exclude mode). */
     filterValues?: Set<any>;
@@ -1138,12 +1606,9 @@ interface PivotLayoutState {
     /** The grand total ROW, at the end of the grid. */
     showRowGrandTotals?: boolean;
     /**
-     * @deprecated NOT IMPLEMENTED. Subtotals on the column axis do not exist:
-     * row subtotals are inserted while flattening the row tree, and the column
-     * axis has no equivalent pass in the renderer. Setting this to `true`
-     * explicitly reports through `onError`; it is left in the type because it
-     * has always had a default of `true`, so removing it would be a breaking
-     * change for a value that never did anything.
+     * Per-level subtotals on the column axis: an expanded column group gets a
+     * total column (before or after its children, per `totalsPosition`).
+     * Default `true`.
      */
     showColumnTotals?: boolean;
     /** Per-level subtotals on the row axis. */
@@ -1156,9 +1621,8 @@ interface PivotLayoutState {
      */
     showGrandTotals?: 'rows' | 'columns' | 'both' | 'none';
     /**
-     * Coarse form of `showRowTotals`. Bridged for the ROW axis only — asking for
-     * `'columns'` or `'both'` reports through `onError`, because column subtotals
-     * are not implemented. See `showColumnTotals`.
+     * Coarse form of `showRowTotals` + `showColumnTotals`. Bridged at the
+     * controller boundary; an explicitly passed granular flag wins.
      */
     showSubTotals?: 'rows' | 'columns' | 'both' | 'none';
     /** Alias of `totalsPosition`, bridged at the controller boundary. */
@@ -1306,6 +1770,22 @@ interface PivotControllerState<TRow = any> {
     layout: PivotLayoutState;
     expandedPaths: Set<string>;
     expandedColPaths: Set<string>;
+    /**
+     * Column widths in pixels that the user dragged or `setColumnWidths` wrote.
+     * Persisted with the layout (`stateStoring`). Keys:
+     *
+     * - `row-<i>` — row-header column `i`, counted from the outer row field
+     *   (`row-0`); in the tree layout `row-0` is the single row-header column.
+     *   With `dataFieldPosition: 'rows'` the column of measure names comes
+     *   last, at `row-<number of row-header columns>`.
+     * - `leaf-<i>` — data column `i`, counted left to right across the whole
+     *   crosstab, totals included.
+     *
+     * A column with no entry is painted at `defaultColumnWidths` (150 for row
+     * headers, 95 for data columns, when that is not set either). Row-header
+     * widths may be painted narrower than stored when the frozen block would
+     * leave the data less than its share of the viewport.
+     */
     columnWidths: Record<string, number>;
     engineResult: PivotEngineResult | null;
     isBuilding: boolean;
@@ -1341,6 +1821,12 @@ interface PivotControllerOptions<TRow = any> extends PivotControllerCallbacks<TR
     controlledLayout?: PivotLayoutState;
     chartIntegrationOptions?: Record<string, any>;
     registry?: PivotEngineRegistry;
+    /**
+     * Server-side pivot (A4 / G-PIV-01, Enterprise): the server aggregates and
+     * the grid lays the answer out. With it, `data` is not read; build one with
+     * `pivotServerSource` from an Enterprise package.
+     */
+    serverSource?: PivotServerSource;
     locale?: string;
     workerUrl?: string | URL;
     /**
@@ -1366,6 +1852,33 @@ interface PivotControllerOptions<TRow = any> extends PivotControllerCallbacks<TR
      * with nothing to set.
      */
     enterpriseEdition?: boolean;
+    /**
+     * What identifies a row for `applyTransaction`: a field name, or a function
+     * returning a string or number — the DataGrid's `rowKey`. Without it rows
+     * are matched by object identity, so an update must pass the very object
+     * that is in `data` (mutated in place) and a remove cannot name a bare key.
+     */
+    rowKey?: PivotRowKeyResolver<TRow>;
+}
+/**
+ * Starting widths, in pixels, for every column of a kind — the renderer's
+ * `defaultColumnWidths` option.
+ *
+ * Configuration, not state: it is not persisted, and a width in
+ * `columnWidths` (a user's drag, or `setColumnWidths`) wins over it. That is
+ * also why it is a separate option rather than seeded `columnWidths` entries:
+ * the number of data columns is only known once the data is pivoted, and a
+ * default written into the persisted map would outlive a later change of the
+ * default in the app's code.
+ */
+interface PivotColumnWidthDefaults {
+    /**
+     * Every row-header column: one per row field in the tabular layout, the
+     * single column in the tree layout. Default 150.
+     */
+    rowHeader?: number;
+    /** Every data column. Default 95. */
+    data?: number;
 }
 /** Imperative API handle exposed via React ref or Angular adapter. */
 interface PivotGridRef {
@@ -1389,6 +1902,94 @@ interface PivotGridRef {
     getCell: (rowPath: string[], colPath: string[]) => PivotCell | null;
 }
 declare const defaultPivotLayout: PivotLayoutState;
+/** One field as a server-side pivot request names it. */
+interface PivotServerField {
+    fieldId: string;
+    /** The source column, when the field reads one (calculated fields do not). */
+    dataField?: string;
+    dataType: PivotField['dataType'];
+    groupInterval?: PivotField['groupInterval'];
+}
+/**
+ * What a server-side pivot asks for: the layout and the filters, and which
+ * groups are open — so the server can answer only the levels on screen.
+ */
+interface PivotServerRequest {
+    /** Row fields, outermost first. */
+    rows: PivotServerField[];
+    /** Column fields, outermost first. */
+    columns: PivotServerField[];
+    /** Measures, in the order the cells carry them. */
+    values: Array<PivotServerField & {
+        summaryType: PivotSummaryType;
+    }>;
+    /** Value filters (header filter, filter area): keep or drop the listed values. */
+    filters: Array<PivotServerField & {
+        type: 'include' | 'exclude';
+        values: unknown[];
+    }>;
+    prefilter: PivotPrefilter | null;
+    /** Open row groups by path, or `'all'`. A closed group's children are not wanted. */
+    expandedRows: string[][] | 'all';
+    expandedColumns: string[][] | 'all';
+}
+/** What the grid hands its server source on each compute. */
+interface PivotServerInput<TRow = any> {
+    gridId: string;
+    fields: PivotField<TRow>[];
+    prefilter: PivotPrefilter | null;
+    /** Open row / column group keys (`'A|B'`); `'*'` for all. */
+    expandedRows: Set<string>;
+    expandedColumns: Set<string>;
+}
+/**
+ * The grid side of a server-side pivot; `pivotServerSource` (Enterprise)
+ * builds one. Kept to two calls so the Community bundle carries only the
+ * scheduling — the request, the answer's translation and the field values
+ * are the source's.
+ */
+interface PivotServerSource {
+    /** The pivot for the grid's current state, as the engine would produce it. */
+    compute(input: PivotServerInput): Promise<PivotEngineResult>;
+    /** Forget cached answers (an explicit refresh: the server's data changed). */
+    reset?(): void;
+}
+
+interface PivotChartState {
+    /** Bumped when the shape changes, so an old snapshot is refused rather than misread. */
+    version: 1;
+    /** Whether the chart panel is showing. */
+    open: boolean;
+    /** Chart type id (`'column'`, `'line'`, `'heatmap'`…). */
+    type: string;
+    stacking: ChartStacking;
+    /** Title, axis titles, legend position, data labels and value scale. */
+    format: ChartFormat;
+    /** Series switched off in the legend, by series key (a chart series' `dataKey`). */
+    hiddenSeries: string[];
+}
+/** Which part of the state a `chartChanged` event moved. */
+type PivotChartChange = 'type' | 'stacking' | 'format' | 'hiddenSeries';
+interface PivotChartOpenedEvent {
+    state: PivotChartState;
+}
+interface PivotChartChangedEvent {
+    state: PivotChartState;
+    changes: PivotChartChange[];
+}
+interface PivotChartClosedEvent {
+    state: PivotChartState;
+}
+/**
+ * Read a saved chart state defensively — it came from storage, a report or an
+ * older build. Fields of the wrong kind fall back to their defaults; `null`
+ * only for something that is not a chart state of this version at all. The
+ * type is not checked against a list: which types exist is the renderer's
+ * business, and an unknown one draws the panel's empty state, not an error.
+ */
+declare function readPivotChartState(input: unknown): PivotChartState | null;
+/** Which parts differ between two states (the `changes` of `chartChanged`). */
+declare function diffPivotChartState(previous: PivotChartState, next: PivotChartState): PivotChartChange[];
 
 type PivotStateListener = () => void;
 /**
@@ -1450,6 +2051,13 @@ interface PivotControllerEvents<TRow> {
         activeReportId: string | null;
     };
     exporting: ExportingEvent;
+    /**
+     * The Enterprise chart panel opened, changed or closed — each with the
+     * panel's whole `PivotChartState`. A Community grid never fires them.
+     */
+    chartOpened: PivotChartOpenedEvent;
+    chartChanged: PivotChartChangedEvent;
+    chartClosed: PivotChartClosedEvent;
 }
 interface PivotImportLabels {
     initializing: string;
@@ -1474,6 +2082,10 @@ interface PivotImportLabels {
 declare class PivotController<TRow> {
     private store;
     private events;
+    /** Saved-report parts owned above the core, and loaded ones still waiting for their owner. */
+    private readonly reportParts;
+    private pendingReportParts;
+    private readonly chartReporter;
     private options;
     private reportService;
     private engineService;
@@ -1482,13 +2094,54 @@ declare class PivotController<TRow> {
     /** Full row set of a parsed import awaiting preview commit (kept out of observable state). */
     private pendingImportRows;
     private disposed;
+    /**
+     * The array the application last handed in. After a transaction the
+     * controller's rows are a NEW array; a binding that re-sends every option
+     * (React's usePivotController does, on every render) would otherwise hand
+     * back this one and undo every transaction. Same array: not a change.
+     */
+    private externalData;
     constructor(options: PivotControllerOptions<TRow>);
     subscribe: (listener: PivotStateListener) => (() => void);
     getSnapshot: () => PivotControllerState<TRow>;
     getState(): PivotControllerState<TRow>;
     on<K extends keyof PivotControllerEvents<TRow>>(eventName: K, handler: (payload: PivotControllerEvents<TRow>[K]) => void): () => void;
+    /**
+     * The chart panel's state, now. The controller turns it into `chartOpened` /
+     * `chartChanged` / `chartClosed` — call it after every change, as often as
+     * convenient: the same state twice is one event, and edits while the panel
+     * is closed arrive with the next `chartOpened`.
+     */
+    reportChartState(state: PivotChartState): void;
+    /**
+     * Keep a piece of state owned outside the core inside saved reports — the
+     * Enterprise chart panel keeps its chart this way. Order-independent: the
+     * default report loads while the controller is constructed, BEFORE any
+     * Enterprise layer has mounted, so a part loaded before its owner registers
+     * is held and handed over on registration. Returns the unregister function.
+     */
+    registerReportStatePart(key: string, part: ReportStatePart): () => void;
+    private collectReportParts;
     updateOptions(options: Partial<PivotControllerOptions<TRow>>): void;
     setFields(fields: PivotField<TRow>[]): void;
+    /**
+     * Replace every row — a full rebuild, transactions included. Unlike
+     * `updateOptions({ data })`, passing the array the grid started from still
+     * replaces: an explicit call means what it says.
+     */
+    setData(data: TRow[]): void;
+    /**
+     * Add, update and remove rows without rebuilding the pivot (live updates).
+     *
+     * Only the changed rows are encoded and sent to the worker, which regroups
+     * them and re-sums the groups they touched; the result is the pivot a
+     * rebuild from the new rows gives. Rows are matched by `rowKey` (by object
+     * identity without one). An update for a key the grid does not have is
+     * ignored; a remove wins over an update of the same row; adds go to the end
+     * — the DataGrid's semantics. `getRawData()` returns the new rows at once;
+     * the recomputed pivot follows (listen for `engineCompleted`).
+     */
+    applyTransaction(transaction: PivotRowTransaction<TRow>): PivotTransactionResult;
     updateField(updatedField: PivotField<TRow>): void;
     deleteField(fieldId: string): void;
     changeFieldArea(fieldId: string, area: PivotArea): void;
@@ -1660,20 +2313,67 @@ declare class PivotEngineService<TRow> {
     private disposed;
     private isInitComplete;
     private forceNextReencode;
+    private engineLock;
+    private busy;
+    private pendingChanges;
+    private drainQueued;
+    private computing;
+    private recomputeAfter;
     private hashes;
     constructor(config: PivotEngineServiceConfig<TRow>);
     refresh(): void;
+    /**
+     * A transaction changed the rows from `previous` to `change.data` (already
+     * the controller's data). Applied incrementally when the engine holds
+     * `previous`; otherwise the change is just new data and takes the normal path.
+     */
+    applyRowChange(change: EngineRowChange<TRow>, previous: TRow[]): void;
+    /**
+     * Run an engine phase alone. Inits, reconfigures and live updates all
+     * encode against the rows the worker holds, and the first two are async
+     * (encoding yields to the main thread): interleaved, one would hand the
+     * worker columns of a length the other just changed, or a second init's
+     * chunks would land inside the first one's build.
+     */
+    private exclusive;
+    private scheduleDrain;
+    /**
+     * Recompute for a live update without ever pushing a picture back. A compute
+     * already due includes the change (the worker takes messages in order), so
+     * it is joined, not restarted; one in flight does not include it, so another
+     * follows it — and the one in flight is still shown. Restarting the debounce
+     * and bumping the version, as view changes do, would let a feed that ticks
+     * faster than a compute keep the grid on its first picture indefinitely.
+     */
+    private computeAfterChange;
+    /** Post one change; on refusal or failure, rebuild from the current data. */
+    private pushRowChange;
+    /** Send the queued changes, in order. False = one was refused and a rebuild is on its way. */
+    private drainRowChanges;
     refreshData(): void;
     computeIfReady(): void;
     dispose(): void;
     private scheduleInit;
     private runInit;
+    private initPhase;
     private scheduleReconfigure;
     private runReconfigure;
     private scheduleFilter;
     private runFilter;
     private scheduleComputeIfReady;
     private runCompute;
+    private serverTimeout;
+    /** What the last scheduled server compute was for; an identical one is skipped. */
+    private serverKey;
+    private serverInput;
+    private scheduleServerCompute;
+    /**
+     * Everything after the aggregation, on the main thread: custom summaries,
+     * calculated summary fields, sorting and top-N, display modes. One copy for
+     * the three ways a result arrives (worker, fully-expanded snapshot, server).
+     */
+    private postPhases;
+    private runServerCompute;
     /**
      * Produce a fully-expanded engine snapshot on demand, WITHOUT mutating the
      * grid's live state. Used by `expandAll` exports: the cached engineResult
@@ -1704,6 +2404,7 @@ declare class PivotEngineService<TRow> {
     private progressCapFor;
     private estimateProgressDuration;
     private handleEngineError;
+    private unplacedFilteredFieldIds;
     private createStructuralFieldsHash;
     private createFieldsHash;
     private createFilterHash;
@@ -1755,6 +2456,8 @@ declare class PivotFieldService {
     static placeFields<TRow>(fields: PivotField<TRow>[], fieldIds: string[], pick: (field: PivotField<TRow>) => PivotArea): PivotField<TRow>[];
     static moveFieldByDirection<TRow>(fields: PivotField<TRow>[], fieldId: string, direction: 'start' | 'end' | 'left' | 'right'): PivotField<TRow>[];
     static moveFieldFromDrop<TRow>(fields: PivotField<TRow>[], command: FieldDropCommand): Promise<PivotField<TRow>[]>;
+    /** The field list after the drop, or `fields` itself when the drop changes nothing. */
+    private static applyDrop;
     static calculateDropIntent(pointerX: number, pointerY: number, itemRect: DropIntentRect, previousIntent: DropIntent, isLastItem: boolean, orientation?: 'horizontal' | 'vertical'): DropIntent;
     private static isArea;
 }
@@ -1786,6 +2489,28 @@ declare function cellHash(rId: number, cId: number): number;
 declare function cellHashRow(hash: number): number;
 declare function cellHashCol(hash: number): number;
 
+interface XYPairInput {
+    name: string;
+    fieldId?: string;
+    seriesKey?: string;
+    seriesLabel?: string;
+}
+interface XYPair {
+    /** Legend caption: the column path, or the y measure when there is none. */
+    label: string;
+    /** Indexes into the input series. */
+    x: number;
+    y: number;
+    size: number | null;
+}
+/**
+ * Group series by column path (in first-seen order) and pair each group's
+ * measures. A group with fewer measures than the type needs is left out —
+ * there is nothing to plot it against. An empty result means the pivot does
+ * not have enough measures at all; the caller says so.
+ */
+declare function pairSeriesForXY(series: readonly XYPairInput[], sized: boolean): XYPair[];
+
 declare class PivotCellAggregator<TRow> {
     private accumulators;
     private dataFields;
@@ -2242,4 +2967,186 @@ declare function coerceRecords(records: Record<string, unknown>[], onProgress?:
  */
 declare function parseCsvToRows(text: string, onProgress?: (p: CsvParseProgress) => void): Record<string, unknown>[];
 
-export { type AdvancedExportRequest, type AdvancedExporter, type CellClickEvent, type CellPreparedEvent, type CellType, type ColHeaderCell, type ColumnSlot, type ColumnSlotOptions, type ConditionalVisual, type CsvParseProgress, CsvReader, type CustomSummaryOptions, DataNormalizer, type DateFormatContext, DateFormatter, type DateGranularity, type DimensionFieldInfo, type DropIntent, type ExportFormat, type ExportOptions, ExportStreamController, type ExportingEvent, FastTrie, type FieldDistinctEntry, type FieldMoveEvent, type FilterCondition, type FilterGroup, type FilterOperator, type FlatCellMatrix, FlatPivotEngine, type FlatRow, type IFileReader, type ImportFormat, ImportManager, type ImportManagerOptions, type ImportProgress, type ImportResult, type ImportSnapshot, ImportStreamController, type ImportWorkerKind, type ImportWorkerResult, MAX_C, type ParseFileOptions, type PivotArea, type PivotCell, PivotCellAggregator, type PivotCellTemplate, type PivotCellTextAccessor, type PivotCellValueAccessor, type PivotConditionRule, PivotController, type PivotControllerCallbacks, type PivotControllerEvents, type PivotControllerOptions, type PivotControllerState, type PivotDataSource, type PivotDictionary, type PivotDragIntentState, PivotEngineRegistry, type PivotEngineResult, PivotEngineService, type PivotEngineServiceConfig, PivotEventEmitter, type PivotEventHandler, type PivotEventMap, PivotExportService, type PivotField, PivotFieldService, type PivotGridRef, type PivotGroupInterval, type PivotImportField, type PivotImportLabels, type PivotImportPreviewState, type PivotImportStatus, type PivotLayoutProfile, type PivotLayoutState, type PivotLocale, type PivotNode, type PivotPlugin, type PivotPrefilter, type PivotReport, PivotReportManager, PivotReportService, type PivotReportState, type PivotSelectionMode, PivotSelectionModel, type PivotSelectionRange, type PivotSelectionState, type PivotSelectionStats, type PivotStateListener, PivotStateStore, type PivotStateStoringConfig, type PivotSummaryDisplayMode, type PivotSummaryType, type PivotTheme, type PivotToolbarConfig, type PivotValue, type PrefilterConditionSpec, type PrefilterGroupSpec, type ProcessFileStreamingOptions, type ProcessFromUrlOptions, ROW_HEADER_MAX_PINNED_FRACTION, ROW_HEADER_MIN_COL_WIDTH, ROW_HEADER_MIN_DATA_STRIP, type RowHeaderLayout, type ValidationResult, type ValueRange, type WorkerComputeRequest, type WorkerFilterRequest, type WorkerFilterSpec, type WorkerInitRequest, type WorkerResponse, XmlReader, ar, buildCellLookup, buildColPathsList, buildColumnHeaders, buildPivotAOA, buildRowLabelCells, cellHash, cellHashCol, cellHashRow, classifyValue, clearFormatCache, coerceRecords, coerceValue, compileSafeFormula, computeFieldRanges, computePivotMatrixAsync, computeRowHeaderWidths, conditionRuleToExcelStyle, cssColorToRgb, de, dedupeHeaders, defaultPivotLayout, destroyEngineWorker, detectDelimiter, en, es, escapeXmlText, executePostAggregationPhase, executeSummaryDisplayModesPhase, exportPivotData, extractGroupValue, fieldNeedsRange, filterEmptySummaryTree, filterPivotEngineAsync, filterRecords, filterRecordsAsync, flattenExportRows, flattenRowTree, flattenRowTreeTabular, flattenRowTreeTree, formatCellValue, formatCellValueCached, formatDimensionValue, formatHeaderValue, fr, getAdvancedExporter, getCellVal, getFieldDistinctValues, getVisibleColLeaves, getVisibleColSlots, getVisibleLeafCount, getVisibleMaxDepth, inferColumnType, initPivotEngineAsync, intlFormatToExcelNumFmt, invertRowHeaderWidth, it, ja, ko, parseBoolean, parseColor, parseCsvToRows, parseDelimited, parseFlexibleDate, parseLocaleNumber, pt, rangeRatio, reconfigurePivotEngineAsync, registerAdvancedExporter, resolveColPath, resolveConditionalVisual, ru, safeKey, sanitizeRows, scaleColor, setActiveEngineGrid, sortPivotTree, stripBom, testSafeFormula, tr, zhCN };
+/** The parts of the pivot a model may read and change. */
+type PivotAiFeature = 'fields' | 'filter' | 'sort' | 'totals';
+declare const PIVOT_AI_FEATURES: readonly PivotAiFeature[];
+interface PivotAiFieldOptions {
+    /** Plain-language meaning: "Net revenue in EUR". */
+    description?: string;
+    /**
+     * List the field's distinct values in the schema so "only Izmir" can be
+     * matched to what is stored. Off by default: the values travel to whatever
+     * model the application uses. An answer's filter values are checked against
+     * the data either way, locally.
+     */
+    includeValues?: boolean;
+    /** Leave the field out entirely; it keeps its place and the model never sees it. */
+    exclude?: boolean;
+}
+interface PivotAiOptions {
+    /** Parts the model may not change (and is not told about). */
+    exclude?: readonly PivotAiFeature[];
+    /** Per-field descriptions, value lists and exclusions, by field id. */
+    fields?: Readonly<Record<string, PivotAiFieldOptions>>;
+    /** Most values listed per field with `includeValues`. Default 100. */
+    maxValues?: number;
+}
+interface PivotAiValue {
+    fieldId: string;
+    summaryType: PivotSummaryType;
+    displayMode: PivotSummaryDisplayMode;
+}
+interface PivotAiFilter {
+    fieldId: string;
+    type: 'include' | 'exclude';
+    values: Array<string | number | boolean>;
+}
+interface PivotAiSort {
+    fieldId: string;
+    direction: 'asc' | 'desc';
+    /** Order by this measure's grand total instead of by the field's own values. */
+    byValueField: string | null;
+    /** Keep only the first N after sorting (needs `byValueField`). */
+    top: number | null;
+}
+interface PivotAiTotals {
+    grandTotalRow: boolean;
+    grandTotalColumn: boolean;
+    subtotalRows: boolean;
+    subtotalColumns: boolean;
+    rowHeaderLayout: 'tabular' | 'tree';
+}
+/** The pivot's layout in the schema's shape; a part left out is left as it is. */
+interface PivotAiState {
+    /** Row dimensions, outermost first. */
+    rows?: string[];
+    /** Column dimensions, outermost first. */
+    columns?: string[];
+    /** Measures in the cells. */
+    values?: PivotAiValue[];
+    /** Every value filter; [] clears them. */
+    filters?: PivotAiFilter[];
+    /** Every dimension sort; a dimension not listed keeps its data order. */
+    sort?: PivotAiSort[];
+    totals?: PivotAiTotals;
+}
+interface PivotAiApplyResult {
+    applied: PivotAiFeature[];
+    dropped: string[];
+}
+/**
+ * The JSON Schema of this pivot's layout, as narrow as its fields allow.
+ * Send it to your own model as the structured-output format together with
+ * `getPivotAiState()` and the user's request; pass the answer to
+ * `applyPivotAiState`. No model ships with the grid and nothing is sent.
+ */
+declare function getPivotAiSchema<TRow>(controller: PivotController<TRow>, options?: PivotAiOptions): Record<string, unknown>;
+/** The current layout in the schema's shape — what the model should start from. */
+declare function getPivotAiState<TRow>(controller: PivotController<TRow>, options?: PivotAiOptions): PivotAiState;
+/**
+ * Apply a model's answer, object or JSON text. What is valid is applied in one
+ * field commit (plus one layout update when totals changed); what is not is
+ * listed in `dropped`. Never throws on a bad answer. Pass the options the
+ * schema was built with.
+ */
+declare function applyPivotAiState<TRow>(controller: PivotController<TRow>, answer: unknown, options?: PivotAiOptions): PivotAiApplyResult;
+
+/**
+ * The column paths a row's trend runs over: the columns ON SCREEN, left to
+ * right, totals left out. A collapsed column group is one step (its subtotal
+ * is what the row shows there); an expanded one is its children.
+ */
+declare function trendColumnPaths(colTree: readonly PivotNode[]): string[][];
+/** One measure's values for a row across those columns; NaN where there is no cell. */
+declare function pivotRowTrend(getCell: (rowPath: string[], colPath: string[]) => PivotCell | null, colPaths: readonly string[][], rowPath: string[], fieldId: string): number[];
+interface TrendShape {
+    /** `points` for an SVG polyline over the present values, in order. */
+    line: string;
+    /** One bar per value from the zero line (or the floor); NaN values have none. */
+    bars: Array<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        negative: boolean;
+    }>;
+    /** The last present value — the dot the eye goes to. */
+    last: {
+        x: number;
+        y: number;
+    } | null;
+}
+/**
+ * Lay the values out in a `width` × `height` box. The scale is the row's own
+ * (a sparkline shows SHAPE, not size — the total beside it gives the size);
+ * a flat row sits in the middle. Fewer than two values draw no line.
+ */
+declare function trendShape(values: readonly number[], width: number, height: number, pad?: number): TrendShape;
+/** Options for the row sparkline, shared by both Enterprise renderers. */
+interface PivotRowSparkline {
+    /** The measure to draw, by field id. Default: the first measure. */
+    field?: string;
+    /** `'line'` (default) or `'bar'`. */
+    type?: 'line' | 'bar';
+    /** Drawing size in px. Default 60 × 16. */
+    width?: number;
+    height?: number;
+}
+
+/** A header value as it travels: what the engine would have grouped by. */
+type PivotServerValue = string | number | boolean | null;
+/** One cell of the answer: a row path, a column path, the measures there. */
+interface PivotServerCell {
+    /** Row values from the outermost field in; `[]` is the grand-total row. */
+    row: PivotServerValue[];
+    /** Column values from the outermost field in; `[]` is the grand-total column. */
+    col: PivotServerValue[];
+    /** Each measure's value by field id; null or missing for "no value". */
+    values: Record<string, number | null>;
+}
+interface PivotServerResponse {
+    /**
+     * Every (row path, column path) pair the request's open groups make
+     * visible — each level's subtotals and the grand totals included. Cells
+     * deeper than the open groups are ignored, so a server may send more than
+     * was asked.
+     */
+    cells: PivotServerCell[];
+}
+interface PivotServerSourceOptions {
+    /** Answer a request — usually one call to your API. */
+    load: (request: PivotServerRequest) => Promise<PivotServerResponse>;
+    /** Every value of a field, for the header filter's checklist. Optional. */
+    loadFieldValues?: (field: PivotServerField) => Promise<unknown[]>;
+    /**
+     * Answers kept per distinct request, so closing a group and opening it
+     * again, or switching totals, does not ask again. Default 16; 0 turns the
+     * cache off.
+     */
+    cacheSize?: number;
+}
+/** The request for the grid's state: the layout, the filters, the open groups. */
+declare function serverRequestFor(input: PivotServerInput): PivotServerRequest;
+/** The grid side of a server-side pivot: pass it as `serverSource`. */
+declare function pivotServerSource(options: PivotServerSourceOptions): PivotServerSource & {
+    clearCache(): void;
+};
+/**
+ * The cells as a PivotEngineResult: the row and column trees (open groups
+ * only), the index maps, and the flat cell matrix the renderers read.
+ */
+declare function buildEngineResult(request: PivotServerRequest, response: PivotServerResponse): PivotEngineResult;
+/**
+ * Answer a request from rows held in memory — the specification a real server
+ * implements, and what tests and demos run against. For each open row group
+ * and open column group (the grand totals included), one cell per pair, the
+ * filters and the prefilter applied first.
+ *
+ * `fields` resolves the fields a prefilter names that the request does not
+ * carry (it only names the fields it lays out and filters by).
+ */
+declare function rollupInMemory<TRow>(rows: readonly TRow[], request: PivotServerRequest, fields?: readonly PivotField<TRow>[]): PivotServerResponse;
+/** Every value of a field in rows held in memory — the reference `loadFieldValues`. */
+declare function fieldValuesInMemory<TRow>(rows: readonly TRow[], field: PivotServerField): unknown[];
+
+export { type AdvancedExportRequest, type AdvancedExporter, CHART_LEGEND_POSITIONS, type CellClickEvent, type CellPreparedEvent, type CellType, type ChartFormat, type ChartImageRequest, type ChartLegendPosition, type ChartMark, type ChartStacking, type ColHeaderCell, type ColumnSlot, type ColumnSlotOptions, type ConditionalVisual, type CsvParseProgress, CsvReader, type CustomSummaryOptions, DEFAULT_DATA_COLUMN_WIDTH, DEFAULT_ROW_HEADER_WIDTH, DataNormalizer, type DateFormatContext, DateFormatter, type DateGranularity, type DimensionFieldInfo, type DropIntent, type ExportFormat, type ExportOptions, ExportStreamController, type ExportingEvent, FastTrie, type FieldDistinctEntry, type FieldMoveEvent, type FilterCondition, type FilterGroup, type FilterOperator, type FlatCellMatrix, FlatPivotEngine, type FlatRow, type FunnelStage, type IFileReader, type ImportFormat, ImportManager, type ImportManagerOptions, type ImportProgress, type ImportResult, type ImportSnapshot, ImportStreamController, type ImportWorkerKind, type ImportWorkerResult, MAX_C, type MarkTone, PIVOT_AI_FEATURES, type ParseFileOptions, type PivotAiApplyResult, type PivotAiFeature, type PivotAiFieldOptions, type PivotAiFilter, type PivotAiOptions, type PivotAiSort, type PivotAiState, type PivotAiTotals, type PivotAiValue, type PivotArea, type PivotCell, PivotCellAggregator, type PivotCellTemplate, type PivotCellTextAccessor, type PivotCellValueAccessor, type PivotChartChange, type PivotChartChangedEvent, type PivotChartClosedEvent, type PivotChartOpenedEvent, type PivotChartState, type PivotColumnWidthDefaults, type PivotConditionRule, PivotController, type PivotControllerCallbacks, type PivotControllerEvents, type PivotControllerOptions, type PivotControllerState, type PivotDataSource, type PivotDictionary, type PivotDragIntentState, PivotEngineRegistry, type PivotEngineResult, PivotEngineService, type PivotEngineServiceConfig, PivotEventEmitter, type PivotEventHandler, type PivotEventMap, PivotExportService, type PivotField, PivotFieldService, type PivotGridRef, type PivotGroupInterval, type PivotImportField, type PivotImportLabels, type PivotImportPreviewState, type PivotImportStatus, type PivotLayoutProfile, type PivotLayoutState, type PivotLocale, type PivotNode, type PivotPlugin, type PivotPrefilter, type PivotReport, PivotReportManager, PivotReportService, type PivotReportState, type PivotRowKey, type PivotRowKeyResolver, type PivotRowSparkline, type PivotRowTransaction, type PivotSelectionMode, PivotSelectionModel, type PivotSelectionRange, type PivotSelectionState, type PivotSelectionStats, type PivotServerCell, type PivotServerField, type PivotServerInput, type PivotServerRequest, type PivotServerResponse, type PivotServerSource, type PivotServerSourceOptions, type PivotServerValue, type PivotStateListener, PivotStateStore, type PivotStateStoringConfig, type PivotSummaryDisplayMode, type PivotSummaryType, type PivotTheme, type PivotToolbarConfig, type PivotTransactionResult, type PivotValue, type PrefilterConditionSpec, type PrefilterGroupSpec, type ProcessFileStreamingOptions, type ProcessFromUrlOptions, ROW_HEADER_MAX_PINNED_FRACTION, ROW_HEADER_MIN_COL_WIDTH, ROW_HEADER_MIN_DATA_STRIP, type ReportStatePart, type RowHeaderLayout, SHAPE_CHART_TYPES, type ShapeChartInput, type ShapeChartType, type StackedSegment, type TreemapCell, type TrendShape, type ValidationResult, type ValueRange, type WaterfallStep, type WorkerComputeRequest, type WorkerFilterRequest, type WorkerFilterSpec, type WorkerInitRequest, type WorkerResponse, type WorkerTransactionRequest, type XYPair, type XYPairInput, XmlReader, applyPivotAiState, ar, buildCellLookup, buildColPathsList, buildColumnHeaders, buildEngineResult, buildPivotAOA, buildRowLabelCells, cellHash, cellHashCol, cellHashRow, chartPalette, classifyValue, clearFormatCache, coerceRecords, coerceValue, compileSafeFormula, computeFieldRanges, computePivotMatrixAsync, computeRowHeaderWidths, conditionRuleToExcelStyle, cssColorToRgb, de, dedupeHeaders, defaultPivotLayout, destroyEngineWorker, detectDelimiter, diffPivotChartState, en, es, escapeXmlText, executePostAggregationPhase, executeSummaryDisplayModesPhase, exportPivotData, extractGroupValue, fieldNeedsRange, fieldValuesInMemory, filterEmptySummaryTree, filterPivotEngineAsync, filterRecords, filterRecordsAsync, flattenExportRows, flattenRowTree, flattenRowTreeTabular, flattenRowTreeTree, formatCellValue, formatCellValueCached, formatDimensionValue, formatHeaderValue, fr, funnelMarks, funnelStages, getAdvancedExporter, getCellVal, getFieldDistinctValues, getPivotAiSchema, getPivotAiState, getVisibleColLeaves, getVisibleColSlots, getVisibleLeafCount, getVisibleMaxDepth, heatColor, heatTextColor, heatmapMarks, inferColumnType, initPivotEngineAsync, intlFormatToExcelNumFmt, invertRowHeaderWidth, it, ja, ko, logAxisTicks, pairSeriesForXY, parseBoolean, parseColor, parseCsvToRows, parseDelimited, parseFlexibleDate, parseLocaleNumber, percentAxisTicks, pivotRowTrend, pivotServerSource, pt, rangeBarMarks, rangeRatio, readChartFormat, readPivotChartState, reconfigurePivotEngineAsync, registerAdvancedExporter, resolveColPath, resolveColumnWidthDefaults, resolveConditionalVisual, rollupInMemory, ru, safeKey, sanitizeRows, scaleColor, serverRequestFor, setActiveEngineGrid, sortPivotTree, squarify, stackSeries, stripBom, sunburstMarks, testSafeFormula, tr, treemapMarks, trendColumnPaths, trendShape, waterfallDomain, waterfallMarks, waterfallSteps, zhCN };