@kanunilabs/pivotgrid-core 1.2.0 → 1.4.0

package/dist/index.d.ts

@@ -43,6 +43,29 @@ interface PivotDictionary {
     rawDataFormats: string;
     customExports: string;
     customPlugin: string;
+    saveReport: string;
+    saveReportDescription: string;
+    reportName: string;
+    reportNamePlaceholder: string;
+    setAsDefault: string;
+    save: string;
+    enterFullscreen: string;
+    exitFullscreen: string;
+    print: string;
+    sendToPrinter: string;
+    copyToClipboard: string;
+    tabSeparatedValues: string;
+    enterpriseBadge: string;
+    enterpriseUpgradeHint: string;
+    dataImportUnsupported: string;
+    columnFilter: string;
+    percentOfColumnTotal: string;
+    percentOfRowTotal: string;
+    percentDifference: string;
+    filterField: string;
+    removeFromArea: string;
+    removeField: string;
+    deletePermanently: string;
     importSuccess: string;
     importWarning: string;
     importError: string;
@@ -105,7 +128,81 @@ interface PivotDictionary {
     moveToEnd: string;
     moveToLeft: string;
     moveToRight: string;
+    /** Field chip a11y: caption, area, 1-based index, count. */
+    fieldChipLabel: string;
+    /** Field chip a11y: the key bindings, read as a description. */
+    fieldChipKeys: string;
+    /** Context-menu submenu that moves a field to another area. */
+    moveToArea: string;
+    /** Prefilter operator labels (#210) — shared vocabulary with DataGrid. */
+    opEquals: string;
+    opNotEquals: string;
+    opGreater: string;
+    opGreaterOrEqual: string;
+    opLess: string;
+    opLessOrEqual: string;
+    opContains: string;
+    opNotContains: string;
+    opStartsWith: string;
+    opEndsWith: string;
+    opIsBlank: string;
+    opIsNotBlank: string;
+    /** Prefilter builder chrome (#210) — shared with DataGrid. */
+    builderCombine: string;
+    builderAddCondition: string;
+    builderAddGroup: string;
+    builderRemoveGroup: string;
+    builderRemoveCondition: string;
+    builderEmpty: string;
+    builderValuePlaceholder: string;
+    /** Drill-down modal (#212); the pager/CSV five are shared with DataGrid. */
+    exportCsv: string;
+    pagerPage: string;
+    pagerOf: string;
+    pagerPrevious: string;
+    pagerNext: string;
+    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). */
+    calcRowLevelHint: string;
+    calcSummaryLevelHint: string;
+    formulaValid: string;
+    calcFieldsHint: string;
+    /** `Uses: {fields}` — the captions the formula references. */
+    formulaUses: string;
     showFieldList: string;
+    /**
+     * License watermark reasons (1.3.0) — the badge shows the product name and
+     * one of these. Mapped to reason codes by `licenseLabelsFromDictionary`
+     * in @kanunilabs/licensing; the key names are that contract.
+     */
+    licenseMissing: string;
+    licenseExpired: string;
+    licenseReleaseNotCovered: string;
+    licenseDomainMismatch: string;
+    licenseRevoked: string;
+    licenseInvalidFormat: string;
+    licenseInvalidSignature: string;
+    licenseEngineUnavailable: string;
     editCalculation: string;
     [key: string]: string;
 }
@@ -547,7 +644,12 @@ declare function initPivotEngineAsync<TRow>(data: TRow[], rowFields: PivotField<
  * worker context, or the dataset changed) — the caller must fall back to a
  * full {@link initPivotEngineAsync}.
  */
-declare function reconfigurePivotEngineAsync<TRow>(data: TRow[], rowFields: PivotField<TRow>[], colFields: PivotField<TRow>[], dataFields: PivotField<TRow>[], registry?: PivotEngineRegistry): Promise<boolean>;
+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. */
+prefilterState?: {
+    fields: PivotField<TRow>[];
+    prefilter?: PivotPrefilter;
+}): Promise<boolean>;
 /**
  * Send filter specs to the worker. Converts field.filterValues to
  * dictionary-encoded integer IDs so the worker can do fast integer
@@ -555,7 +657,16 @@ declare function reconfigurePivotEngineAsync<TRow>(data: TRow[], rowFields: Pivo
  */
 declare function filterPivotEngineAsync(fields: PivotField<any>[], prefilter?: PivotPrefilter): Promise<void>;
 declare function computePivotMatrixAsync(expandedPaths: string[], expandedColPaths: string[]): Promise<PivotEngineResult>;
-declare function getFieldDistinctValues(fieldId: string): FieldDistinctEntry[] | null;
+/**
+ * Cached distinct values for a header filter.
+ *
+ * `gridId` is optional for backwards compatibility, but callers that know
+ * their own id MUST pass it: without it this resolves through the
+ * module-global `activeGridId` — whichever grid last ran an engine phase — so
+ * on a page with two grids sharing a field id, one grid's filter popup listed
+ * the OTHER grid's values (sweep #193).
+ */
+declare function getFieldDistinctValues(fieldId: string, gridId?: string): FieldDistinctEntry[] | null;
 
 interface PivotReportState {
     fields: PivotField<any>[];
@@ -585,10 +696,111 @@ interface PivotReport {
  * intersection (colId). Nodes missing from the index maps are kept as-is
  * (they cannot be safely evaluated).
  */
+/**
+ * How wide the frozen row-header block may get before it starves the data.
+ *
+ * Pinning every row-header column is fine until the block approaches the
+ * viewport, and then it collapses completely: the sticky headers cover the
+ * whole visible area and the crosstab is painted UNDERNEATH them, unreachable
+ * by scrolling because sticky boxes do not move (journal #201).
+ *
+ * The first attempt un-pinned the deep columns. That traded one broken rule
+ * for another — the row headers scrolled away with the data — and was
+ * rejected. The lever is WIDTH: every column stays frozen, and the block is
+ * compressed until the crosstab has somewhere to live.
+ *
+ * Both renderers call this. They must: the vanilla painter derives its sticky
+ * 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.
+ */
+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. */
+declare const ROW_HEADER_MIN_COL_WIDTH = 56;
+interface RowHeaderLayout {
+    /** Widths as PAINTED, one per row-header column. */
+    widths: number[];
+    /** Their sum — the width of the whole frozen block. */
+    total: number;
+}
+/**
+ * Row-header widths as painted: the configured widths, scaled down when the
+ * block would not leave room for the data.
+ *
+ * `viewport <= 0` means "not measured yet" — before the first layout, and in
+ * a hidden pane — and compresses nothing. Compressing on a guess would shrink
+ * every grid that has not been measured.
+ */
+declare function computeRowHeaderWidths(configured: number[], viewport: number): RowHeaderLayout;
+/**
+ * The configured width that, once the budget has compressed the block, paints
+ * column `index` at `targetPainted` — "what you drag is what you get".
+ *
+ * A resize grip lives on the PAINTED edge. Committing painted+delta as the
+ * CONFIGURED width is wrong under compression, and wrong in the worst way:
+ * eight columns configured 150 (painted 90) in a 1198px viewport, drag column
+ * 0 to 100, commit 100 → the configured total shrinks, the scale falls, and
+ * column 0 is painted 63. The user asked for wider and got narrower.
+ *
+ * The dragged column's painted width is c·budget/(c + rest), rounded, then
+ * floored — the scale comes from the CONFIGURED total, and the floor is
+ * applied per column afterwards, so the OTHER columns' floors never touch
+ * this one. That makes the inverse a closed form, c = t·rest/(budget − t),
+ * with a one-pixel correction for the rounding.
+ *
+ * What is stored matters beyond this viewport: the map persists through
+ * stateStoring and is painted again in wider containers. So the target is
+ * clamped to what a column can actually be painted at here — never below
+ * the floor, never past the point where the block no longer fits — and the
+ * returned width is the moderate one that paints there. (A first version
+ * bisected and returned the SMALLEST width in the floor band, i.e. 2px, and
+ * a ten-figure number for an unreachable target; both painted fine today
+ * and absurdly tomorrow.)
+ *
+ * Without compression this is the identity, so callers can use it always.
+ */
+declare function invertRowHeaderWidth(configured: number[], index: number, targetPainted: number, viewport: number): number;
 declare function filterEmptySummaryTree(engineResult: PivotEngineResult): [PivotNode[], PivotNode[]];
-declare function getVisibleLeafCount(node: PivotNode, expandedColPaths: Set<string>, allExpanded?: boolean): number;
+/**
+ * Column-axis subtotals: one extra leaf per EXPANDED node with children,
+ * holding that node's own aggregate.
+ *
+ * No second aggregation pass is needed and none is done. The engine already
+ * materialises a cell for every VISIBLE node, parents included — its
+ * ancestor walk keeps the parent in the chain when the parent is expanded
+ * (FlatPivotEngine.collectActiveAncestors), so `Electro` carries 420 while
+ * `Electro|Phone` carries 400 and `Electro|TV` carries 20. The column
+ * subtotal is therefore a LAYOUT concern: emit a leaf slot addressing the
+ * parent's own hash, in the right place.
+ *
+ * The three column functions below must agree cell for cell — the header
+ * builder, the leaf list the renderers index cells with, and the span count.
+ * A disagreement shifts every data cell under the wrong header, so they share
+ * this one options shape and a test asserts they produce the same count.
+ */
+interface ColumnSlotOptions {
+    /** `layout.showColumnTotals` — per-level subtotals on the column axis. */
+    subTotals?: boolean;
+    /** Before or after the children, matching `layout.totalsPosition`. */
+    totalsPosition?: 'top' | 'bottom';
+}
+declare function getVisibleLeafCount(node: PivotNode, expandedColPaths: Set<string>, allExpanded?: boolean, opts?: ColumnSlotOptions): number;
 declare function getVisibleMaxDepth(nodes: PivotNode[], expandedColPaths: Set<string>, allExpanded?: boolean): number;
-declare function getVisibleColLeaves(nodes: PivotNode[], expandedColPaths: Set<string>, allExpanded?: boolean): PivotNode[];
+/** One painted data column: the node whose hash addresses it, and why. */
+interface ColumnSlot {
+    node: PivotNode;
+    /** True for a subtotal slot — the node's OWN aggregate beside its children. */
+    isSubtotal: boolean;
+}
+/**
+ * The visible data columns, in paint order.
+ *
+ * This is the list renderers index cells with, and it must line up one-for-one
+ * with the leaf cells `buildColumnHeaders` emits.
+ */
+declare function getVisibleColSlots(nodes: PivotNode[], expandedColPaths: Set<string>, allExpanded?: boolean, opts?: ColumnSlotOptions): ColumnSlot[];
+/** The visible data columns as bare nodes — `getVisibleColSlots` without the flags. */
+declare function getVisibleColLeaves(nodes: PivotNode[], expandedColPaths: Set<string>, allExpanded?: boolean, opts?: ColumnSlotOptions): PivotNode[];
 interface ColHeaderCell {
     node: PivotNode | null;
     caption: string;
@@ -599,8 +811,26 @@ interface ColHeaderCell {
     colPath?: string;
     hasChildren?: boolean;
     isExpanded?: boolean;
+    /** A column-axis subtotal cell: the node's OWN aggregate beside its children. */
+    isSubtotal?: boolean;
+    /**
+     * Index of the first data column this cell sits above, in the FULL visible
+     * leaf order (already multiplied by the data-field count when measures are
+     * on the column axis).
+     *
+     * Renderers used to derive this by accumulating `colSpan` per header row,
+     * which is only correct when every row starts at leaf 0. A collapsed node
+     * at depth 0 appears in row 0 alone (it carries a rowSpan instead), so the
+     * next row holds only the expanded siblings' children — and their
+     * accumulator restarted at 0, addressing the collapsed sibling's column.
+     * The producer knows the true order, so it now states it (#194).
+     */
+    leafStart: number;
 }
-declare function buildColumnHeaders(colTree: PivotNode[], dataFields: PivotField[], layout: PivotLayoutState, expandedColPaths: Set<string>, allExpanded?: boolean): ColHeaderCell[][];
+declare function buildColumnHeaders(colTree: PivotNode[], dataFields: PivotField[], layout: PivotLayoutState, expandedColPaths: Set<string>, allExpanded?: boolean, labels?: {
+    grandTotal?: string;
+    subTotal?: string;
+}): ColHeaderCell[][];
 /**
  * A flattened row for rendering. Each row represents either:
  * - A leaf data row (values at each depth level column)
@@ -649,6 +879,52 @@ declare function flattenRowTreeTabular(nodes: PivotNode[], expandedPaths: Set<st
  */
 declare function flattenRowTreeTree(nodes: PivotNode[], expandedPaths: Set<string>, allExpanded: boolean, treeDepth: number, showRowTotals: boolean, totalsPosition: 'top' | 'bottom'): FlatRow[];
 
+interface ValueRange {
+    min: number;
+    max: number;
+}
+/** What a cell should look like once its rules have been applied. */
+interface ConditionalVisual {
+    /** Style properties to merge into the cell — the historical `style` object. */
+    style: Record<string, string | number>;
+    /**
+     * A data bar: how far to fill (0..1), in what colour, and which way. The
+     * renderer draws it; core will not pick a gradient syntax for everyone.
+     */
+    dataBar?: {
+        ratio: number;
+        color: string;
+        negative: boolean;
+    };
+    /** The icon a renderer should draw before the value, by name. */
+    icon?: string;
+}
+declare function fieldNeedsRange(field: PivotField): boolean;
+/**
+ * The min and max of each measure across the CURRENT matrix.
+ *
+ * TOTALS ARE EXCLUDED. A grand total is an order of magnitude above the cells
+ * beside it, and letting it set the top of the scale flattens every real value
+ * into the first colour stop — the scale would technically be correct and
+ * visually useless. A cell is a total when either index is 0 (the root row or
+ * root column), which is how the matrix already addresses them.
+ */
+declare function computeFieldRanges(engineResult: PivotEngineResult, dataFields: PivotField[]): Record<string, ValueRange>;
+/** #rgb / #rrggbb / rgb(...) → [r,g,b], or null when it cannot be parsed. */
+declare function parseColor(color: string | undefined): [number, number, number] | null;
+/** Position of `value` inside the range, 0..1. A flat range is all zero. */
+declare function rangeRatio(value: number, range: ValueRange | undefined): number;
+/** Blend across two or three stops, the way a spreadsheet colour scale does. */
+declare function scaleColor(ratio: number, stops: string[]): string | null;
+/**
+ * Apply every rule on a field to one cell.
+ *
+ * `expression` keeps its exact historical behaviour, evaluation errors and
+ * all: a throwing formula is skipped rather than breaking the paint, which is
+ * what both renderers already did.
+ */
+declare function resolveConditionalVisual(value: number | undefined, field: PivotField, cell: PivotCell | null, range?: ValueRange): ConditionalVisual;
+
 type ExportFormat = 'excel-list' | 'excel-pivot' | 'pdf' | 'json' | 'json-pivot' | 'json-snapshot' | 'xml' | 'csv' | 'print' | 'clipboard';
 /** Options passed to the export pipeline — all fields optional for backward compat. */
 interface ExportOptions {
@@ -704,7 +980,9 @@ declare function flattenExportRows(engineResult: PivotEngineResult, rowFields: P
  * single indented label (subtotals keep a "Total" marker so downstream
  * heuristics still recognize them); tabular mode returns one cell per depth.
  */
-declare function buildRowLabelCells(flatRow: FlatRow, rowFields: PivotField[], treeMode: boolean, rowLabelCols: number, locale: string): any[];
+declare function buildRowLabelCells(flatRow: FlatRow, rowFields: PivotField[], treeMode: boolean, rowLabelCols: number, locale: string, labels?: {
+    subTotal?: string;
+}): any[];
 /** Find the data field for a given column path entry. */
 declare function resolveColPath(cPathInfo: string[], dataFields: PivotField[]): {
     cHash: string;
@@ -717,7 +995,10 @@ declare function resolveColPath(cPathInfo: string[], dataFields: PivotField[]):
  * event loop every {@link AOA_CHUNK} rows, honors an AbortSignal, and reports
  * incremental progress. Returns `null` when the export was aborted mid-build.
  */
-declare function buildPivotAOA(engineResult: PivotEngineResult, rowFields: PivotField[], dataFields: PivotField[], layout: PivotLayoutState, expandedPaths: Set<string>, expandedColPaths: Set<string>, allExpanded?: boolean, locale?: string, applyFormatting?: boolean, colFields?: PivotField[], signal?: AbortSignal, onProgress?: (percent: number) => void): Promise<{
+declare function buildPivotAOA(engineResult: PivotEngineResult, rowFields: PivotField[], dataFields: PivotField[], layout: PivotLayoutState, expandedPaths: Set<string>, expandedColPaths: Set<string>, allExpanded?: boolean, locale?: string, applyFormatting?: boolean, colFields?: PivotField[], signal?: AbortSignal, onProgress?: (percent: number) => void, labels?: {
+    grandTotal?: string;
+    subTotal?: string;
+}): Promise<{
     aoa: any[][];
     styles: (ExportCellStyle | null)[][] | null;
 } | null>;
@@ -852,14 +1133,35 @@ interface PivotField<TRow = any, TCellTemplate = PivotCellTemplate, TStyle = any
 }
 /** Controls pivot grid layout, totals visibility, and structural options. */
 interface PivotLayoutState {
+    /** The grand total COLUMN, at the end of every row. */
     showColumnGrandTotals?: boolean;
+    /** 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.
+     */
     showColumnTotals?: boolean;
+    /** Per-level subtotals on the row axis. */
     showRowTotals?: boolean;
     /** Whether subtotals appear above or below their groups. */
     totalsPosition?: 'top' | 'bottom';
+    /**
+     * Coarse form of `showRowGrandTotals` + `showColumnGrandTotals`. Bridged to
+     * them at the controller boundary; an explicitly passed granular flag wins.
+     */
     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`.
+     */
     showSubTotals?: 'rows' | 'columns' | 'both' | 'none';
+    /** Alias of `totalsPosition`, bridged at the controller boundary. */
     totalsDisplayMode?: 'top' | 'bottom';
     /** Row header style: 'tabular' gives one column per row field, 'tree' nests all into one column. */
     rowHeaderLayout?: 'tabular' | 'tree';
@@ -1190,6 +1492,14 @@ declare class PivotController<TRow> {
     updateField(updatedField: PivotField<TRow>): void;
     deleteField(fieldId: string): void;
     changeFieldArea(fieldId: string, area: PivotArea): void;
+    /**
+     * Take several fields out of the chooser in ONE commit.
+     *
+     * The routing rule is the field chooser's checkbox rule — a number is a
+     * measure, anything else describes a row — and it lives here so the vanilla
+     * chooser, the React chooser and the Angular one cannot drift on it.
+     */
+    showFields(fieldIds: string[]): void;
     removeField(fieldId: string): void;
     moveField(fieldId: string, direction: 'start' | 'end' | 'left' | 'right'): void;
     sortField(fieldId: string, direction: 'asc' | 'desc' | undefined): void;
@@ -1198,6 +1508,14 @@ declare class PivotController<TRow> {
     applyFilter(fieldId: string, selectedValues: Set<any>, filterType: 'include' | 'exclude'): void;
     clearFilter(fieldId: string): void;
     setLayout(updates: Partial<PivotLayoutState>): void;
+    private readonly unsupportedReporter;
+    /**
+     * Translate a whole layout arriving from outside — the `layout` prop, or a
+     * controlled update — and report what could not be honoured.
+     *
+     * Returns `undefined` for `undefined` so callers can keep their `??` chain.
+     */
+    private normalizeIncomingLayout;
     toggleExpanded(path: string): void;
     expandPaths(paths: string[]): void;
     collapsePaths(paths: string[]): void;
@@ -1368,6 +1686,15 @@ declare class PivotEngineService<TRow> {
      * user expanded all nodes manually.
      */
     computeFullyExpandedSnapshot(): Promise<PivotEngineResult>;
+    /**
+     * Surface options the sort accepted but could not honour.
+     *
+     * Routed to `onError` rather than thrown: the pivot it just built is correct
+     * and useful, so failing the whole compute would be worse than the problem.
+     * See utils/unsupported.ts for why it is not a console warning.
+     */
+    private readonly unsupportedReporter;
+    private reportUnsupported;
     private startBuildProgress;
     private tickBuildProgress;
     private advanceBuildProgress;
@@ -1408,6 +1735,24 @@ declare class PivotFieldService {
     static removeField<TRow>(fields: PivotField<TRow>[], fieldId: string): PivotField<TRow>[];
     static deleteField<TRow>(fields: PivotField<TRow>[], fieldId: string): PivotField<TRow>[];
     static changeFieldArea<TRow>(fields: PivotField<TRow>[], fieldId: string, area: PivotArea): PivotField<TRow>[];
+    /**
+     * Move several fields into areas in ONE commit.
+     *
+     * `changeFieldArea` in a loop is the obvious way to write "show all these
+     * fields", and it is the wrong one: every call commits, which re-runs the
+     * engine. On the million-row demo that is one full rebuild per field.
+     *
+     * The areaIndex bookkeeping is the reason this cannot just be a `map`.
+     * `changeFieldArea` derives its index from CURRENT occupancy
+     * (`fields.filter(c => c.area === area).length`); doing that per field
+     * inside one pass would hand every arrival the same number, and
+     * `normalizeAreaIndexes` sorts on that key — so an all-equal key would drop
+     * the batch into whatever order `sort` happened to produce. Instead each
+     * area's counter is seeded from occupancy once and then advanced, so the
+     * newcomers land after the fields already there, in the order the CALLER
+     * listed them (which is the order the user was looking at).
+     */
+    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>[]>;
     static calculateDropIntent(pointerX: number, pointerY: number, itemRect: DropIntentRect, previousIntent: DropIntent, isLastItem: boolean, orientation?: 'horizontal' | 'vertical'): DropIntent;
@@ -1482,7 +1827,23 @@ declare function testSafeFormula(formulaString: string, fieldMap: Map<string, st
 declare function filterRecords<TRow>(records: TRow[], fields: PivotField<TRow>[], prefilter?: PivotPrefilter): TRow[];
 declare function filterRecordsAsync<TRow>(records: TRow[], fields: PivotField<TRow>[], prefilter?: PivotPrefilter): Promise<TRow[]>;
 
-declare function sortPivotTree(nodes: PivotNode[], fields: PivotField<any>[], engineResult: PivotEngineResult, dataFields: PivotField<any>[], isRowTree: boolean, locale?: string, cellMapCache?: Map<number, number>): void;
+/**
+ * Anything the sort accepted but could not honour, so the caller can surface it
+ * instead of the option being swallowed.
+ *
+ * `topNShowOthers` is the reason this exists. It used to report that the whole
+ * feature was missing; since #200 the Others node is built, and what is
+ * reported is narrower and exact: `avg` and `distinct` cannot be combined from
+ * already-aggregated cells (one needs the row counts behind each value, the
+ * other the values themselves), so those measures are left empty rather than
+ * filled with a plausible wrong number. `sum`, `count`, `min` and `max` are
+ * exact — the cut nodes are still fully aggregated in the matrix, so no second
+ * pass over the source data is involved.
+ */
+interface SortOutcome {
+    unsupported: string[];
+}
+declare function sortPivotTree(nodes: PivotNode[], fields: PivotField<any>[], engineResult: PivotEngineResult, dataFields: PivotField<any>[], isRowTree: boolean, locale?: string, cellMapCache?: Map<number, number>, outcome?: SortOutcome): void;
 
 declare function executePostAggregationPhase<TRow>(engineResult: PivotEngineResult, dataFields: PivotField<TRow>[], registry?: PivotEngineRegistry): void;
 declare function executeSummaryDisplayModesPhase<TRow>(engineResult: PivotEngineResult, dataFields: PivotField<TRow>[]): void;
@@ -1875,4 +2236,4 @@ 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 CsvParseProgress, CsvReader, type CustomSummaryOptions, DataNormalizer, type DateFormatContext, DateFormatter, type DateGranularity, 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, type ValidationResult, 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, computePivotMatrixAsync, conditionRuleToExcelStyle, cssColorToRgb, de, dedupeHeaders, defaultPivotLayout, destroyEngineWorker, detectDelimiter, en, es, escapeXmlText, executePostAggregationPhase, executeSummaryDisplayModesPhase, exportPivotData, extractGroupValue, filterEmptySummaryTree, filterPivotEngineAsync, filterRecords, filterRecordsAsync, flattenExportRows, flattenRowTree, flattenRowTreeTabular, flattenRowTreeTree, formatCellValue, formatCellValueCached, formatHeaderValue, fr, getAdvancedExporter, getCellVal, getFieldDistinctValues, getVisibleColLeaves, getVisibleLeafCount, getVisibleMaxDepth, inferColumnType, initPivotEngineAsync, intlFormatToExcelNumFmt, it, ja, ko, parseBoolean, parseCsvToRows, parseDelimited, parseFlexibleDate, parseLocaleNumber, pt, reconfigurePivotEngineAsync, registerAdvancedExporter, resolveColPath, ru, safeKey, sanitizeRows, setActiveEngineGrid, sortPivotTree, stripBom, testSafeFormula, tr, zhCN };
+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 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, 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 };