@kanunilabs/pivotgrid-core 1.0.3 → 1.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1,5 +1,1060 @@
1
- import { P as PivotField, a as PivotControllerState, b as PivotLayoutState, c as PivotSelectionStats, d as PivotImportStatus, e as PivotControllerOptions, f as PivotEngineResult, F as FieldMoveEvent, C as CellClickEvent, E as ExportingEvent, g as PivotArea, D as DropIntent, h as PivotImportField, i as ExportFormat, j as ExportOptions, k as PivotCell, l as PivotDragIntentState, m as PivotReport, n as PivotReportState, o as PivotSelectionMode, p as PivotSelectionState, q as PivotCellValueAccessor, r as PivotCellTextAccessor, s as PivotPrefilter, t as PivotNode, u as PivotEngineRegistry, v as PivotValue, w as PivotConditionRule, x as PivotDictionary } from './pivot.worker-DQFl4fMu.js';
2
- export { y as CellPreparedEvent, z as CustomSummaryOptions, A as FieldDistinctEntry, B as FilterCondition, G as FilterGroup, H as FilterOperator, I as FlatCellMatrix, J as FlatPivotEngine, K as FlatRow, L as PivotCellTemplate, M as PivotControllerCallbacks, N as PivotDataSource, O as PivotGridRef, Q as PivotGroupInterval, R as PivotImportPreviewState, S as PivotLayoutProfile, T as PivotLocale, U as PivotPlugin, V as PivotSelectionRange, W as PivotStateStoringConfig, X as PivotSummaryDisplayMode, Y as PivotSummaryType, Z as PivotTheme, _ as PivotToolbarConfig, $ as PrefilterConditionSpec, a0 as PrefilterGroupSpec, a1 as WorkerComputeRequest, a2 as WorkerFilterRequest, a3 as WorkerFilterSpec, a4 as WorkerInitRequest, a5 as WorkerResponse, a6 as buildCellLookup, a7 as buildColPathsList, a8 as buildColumnHeaders, a9 as buildPivotAOA, aa as buildRowLabelCells, ab as computePivotMatrixAsync, ac as cssColorToRgb, ad as defaultPivotLayout, ae as destroyEngineWorker, af as escapeXmlText, ag as exportPivotData, ah as filterEmptySummaryTree, ai as filterPivotEngineAsync, aj as flattenExportRows, ak as flattenRowTree, al as flattenRowTreeTabular, am as flattenRowTreeTree, an as formatHeaderValue, ao as getCellVal, ap as getFieldDistinctValues, aq as getVisibleColLeaves, ar as getVisibleLeafCount, as as getVisibleMaxDepth, at as initPivotEngineAsync, au as reconfigurePivotEngineAsync, av as resolveColPath, aw as setActiveEngineGrid } from './pivot.worker-DQFl4fMu.js';
1
+ interface PivotDictionary {
2
+ ok: string;
3
+ cancel: string;
4
+ apply: string;
5
+ close: string;
6
+ search: string;
7
+ selectAll: string;
8
+ clearAll: string;
9
+ show: string;
10
+ hide: string;
11
+ filterArea: string;
12
+ columnArea: string;
13
+ rowArea: string;
14
+ dataArea: string;
15
+ footerArea: string;
16
+ allFields: string;
17
+ dropHere: string;
18
+ actions: string;
19
+ saveNewView: string;
20
+ saveAsView: string;
21
+ saveChanges: string;
22
+ savedViews: string;
23
+ viewOptions: string;
24
+ viewsAndReports: string;
25
+ views: string;
26
+ saveChangesOverwrite: string;
27
+ saveAsCopy: string;
28
+ makeDefault: string;
29
+ deleteReport: string;
30
+ deleteReportConfirm: string;
31
+ export: string;
32
+ importFile: string;
33
+ excelExport: string;
34
+ pivotView: string;
35
+ listView: string;
36
+ preservesGridLayout: string;
37
+ rawFlatData: string;
38
+ document: string;
39
+ pdfDocument: string;
40
+ printReadyLayout: string;
41
+ fullSnapshot: string;
42
+ saveSessionState: string;
43
+ rawDataFormats: string;
44
+ customExports: string;
45
+ customPlugin: string;
46
+ importSuccess: string;
47
+ importWarning: string;
48
+ importError: string;
49
+ initializing: string;
50
+ emptyData: string;
51
+ noItems: string;
52
+ blanks: string;
53
+ loadingData: string;
54
+ processing: string;
55
+ fieldSettings: string;
56
+ caption: string;
57
+ summaryType: string;
58
+ displayMode: string;
59
+ groupInterval: string;
60
+ sum: string;
61
+ count: string;
62
+ avg: string;
63
+ min: string;
64
+ max: string;
65
+ grandTotal: string;
66
+ subTotal: string;
67
+ absoluteValue: string;
68
+ runningTotal: string;
69
+ difference: string;
70
+ percentOfTotal: string;
71
+ none: string;
72
+ year: string;
73
+ quarter: string;
74
+ month: string;
75
+ day: string;
76
+ and: string;
77
+ or: string;
78
+ noConditionsAdded: string;
79
+ calculatedMeasureDesigner: string;
80
+ createFormulasWithoutCode: string;
81
+ measureName: string;
82
+ format: string;
83
+ numericStandard: string;
84
+ numericDecimal: string;
85
+ currencyTRY: string;
86
+ currencyUSD: string;
87
+ percent: string;
88
+ expand: string;
89
+ collapse: string;
90
+ expandAll: string;
91
+ collapseAll: string;
92
+ sortByThisColumn: string;
93
+ sortFieldByThisColumn: string;
94
+ removeAllSorting: string;
95
+ sortAsc: string;
96
+ sortDesc: string;
97
+ clearSort: string;
98
+ order: string;
99
+ moveToStart: string;
100
+ moveToEnd: string;
101
+ moveToLeft: string;
102
+ moveToRight: string;
103
+ showFieldList: string;
104
+ editCalculation: string;
105
+ [key: string]: string;
106
+ }
107
+ interface PivotSelectionStats {
108
+ count: number;
109
+ sum: number;
110
+ avg: number;
111
+ min: number;
112
+ max: number;
113
+ }
114
+ type PivotSelectionMode = 'row' | 'data';
115
+ interface PivotSelectionRange {
116
+ startRow: number;
117
+ startColumn: number;
118
+ endRow: number;
119
+ endColumn: number;
120
+ }
121
+ interface PivotSelectionState {
122
+ range: PivotSelectionRange;
123
+ isSelecting: boolean;
124
+ mode: PivotSelectionMode;
125
+ }
126
+ type PivotCellValueAccessor = (row: number, column: number) => number | null | undefined;
127
+ type PivotCellTextAccessor = (row: number, column: number) => string;
128
+
129
+ type PivotEventMap = Record<string, any>;
130
+ type PivotEventHandler<TPayload> = (payload: TPayload) => void;
131
+ declare class PivotEventEmitter<TEvents extends PivotEventMap> {
132
+ private handlers;
133
+ on<K extends keyof TEvents>(eventName: K, handler: PivotEventHandler<TEvents[K]>): () => void;
134
+ off<K extends keyof TEvents>(eventName: K, handler: PivotEventHandler<TEvents[K]>): void;
135
+ emit<K extends keyof TEvents>(eventName: K, payload: TEvents[K]): void;
136
+ clear(): void;
137
+ }
138
+
139
+ interface PivotPlugin {
140
+ id: string;
141
+ version?: string;
142
+ type: 'expression' | 'summary' | 'sort' | 'custom' | 'exporter' | 'cellRender' | 'aggregator' | 'headerRender' | 'toolbar';
143
+ execute?: Function;
144
+ workerCode?: string;
145
+ exportFunction?: (data: any[], options: any) => Promise<void>;
146
+ renderCell?: (value: any, displayValue: string, cellContext: any, field: any) => any;
147
+ renderHeader?: (field: any, defaultLabel: string) => any;
148
+ aggregate?: (values: number[]) => number;
149
+ }
150
+ declare class PivotEngineRegistry {
151
+ private plugins;
152
+ /**
153
+ * Registers a new plugin into this instance.
154
+ * If a plugin with the same ID exists, it issues a warning before overwriting.
155
+ */
156
+ register(plugin: PivotPlugin): void;
157
+ /**
158
+ * Unregisters a plugin.
159
+ */
160
+ unregister(id: string): void;
161
+ /**
162
+ * Retrieves a plugin by its ID.
163
+ */
164
+ get(id: string): PivotPlugin | undefined;
165
+ /**
166
+ * Retrieves all plugins of a specific type.
167
+ */
168
+ getPluginsByType(type: PivotPlugin['type']): PivotPlugin[];
169
+ /**
170
+ * Safe getter that logs a warning and returns a fallback mock if the plugin is missing.
171
+ * This guarantees that UI loops do not crash.
172
+ */
173
+ resolveSafe(id: string, fallbackType: 'expression' | 'summary'): Function;
174
+ /**
175
+ * Returns a snapshot of plugins that have worker code, ready for Worker Bootstrap.
176
+ */
177
+ getWorkerBootstrapPayload(): Pick<PivotPlugin, 'id' | 'type' | 'workerCode'>[];
178
+ /**
179
+ * Register a custom aggregator function (e.g., median, weighted average).
180
+ * Used by the engine when summaryType === 'custom' and field references this aggregator.
181
+ */
182
+ registerAggregator(id: string, aggregateFn: (values: number[]) => number, version?: string): void;
183
+ /**
184
+ * Register a custom export format plugin.
185
+ * The exportFunction receives the data array and an options bag with fields, layout, etc.
186
+ */
187
+ registerExporter(id: string, exportFn: (data: any[], options: any) => Promise<void>, version?: string): void;
188
+ /**
189
+ * Register a custom cell renderer plugin.
190
+ * Applied globally to cells matching the plugin criteria.
191
+ */
192
+ registerCellRenderer(id: string, renderFn: (value: any, displayValue: string, cellContext: any, field: any) => any, version?: string): void;
193
+ /**
194
+ * Register a custom header renderer plugin.
195
+ */
196
+ registerHeaderRenderer(id: string, renderFn: (field: any, defaultLabel: string) => any, version?: string): void;
197
+ /** Get all registered custom exporters. */
198
+ getExporters(): PivotPlugin[];
199
+ /** Get all registered cell renderers. */
200
+ getCellRenderers(): PivotPlugin[];
201
+ /** Get all registered aggregators. */
202
+ getAggregators(): PivotPlugin[];
203
+ /** Get all registered header renderers. */
204
+ getHeaderRenderers(): PivotPlugin[];
205
+ }
206
+
207
+ declare class PivotSelectionModel {
208
+ static start(row: number, column: number, mode: PivotSelectionMode): PivotSelectionState;
209
+ static extend(state: PivotSelectionState | null, row: number, column: number, mode: PivotSelectionMode): PivotSelectionState | null;
210
+ static finish(state: PivotSelectionState | null): PivotSelectionState | null;
211
+ static containsCell(state: PivotSelectionState | null, row: number, column: number): boolean;
212
+ static calculateStats(state: PivotSelectionState | null, valueAccessor: PivotCellValueAccessor): PivotSelectionStats | null;
213
+ static toTsv(state: PivotSelectionState | null, textAccessor: PivotCellTextAccessor): string;
214
+ private static getBounds;
215
+ }
216
+
217
+ type DateFormatContext = 'grid' | 'chart' | 'export';
218
+ type DateGranularity = 'year' | 'quarter' | 'month' | 'day' | 'dayOfWeek' | string | number;
219
+ declare class DateFormatter {
220
+ private static intlCache;
221
+ private static stringCache;
222
+ /**
223
+ * Formats a raw grouped date value into a human-readable string.
224
+ * Cached to ensure 0 FPS drop on 500k+ rows.
225
+ */
226
+ static format(rawValue: any, context: DateFormatContext, locale: string, granularity?: DateGranularity): string;
227
+ static clearCache(): void;
228
+ }
229
+
230
+ declare const tr: PivotDictionary;
231
+
232
+ declare const en: PivotDictionary;
233
+
234
+ declare const de: PivotDictionary;
235
+
236
+ declare const fr: PivotDictionary;
237
+
238
+ declare const es: PivotDictionary;
239
+
240
+ declare const it: PivotDictionary;
241
+
242
+ declare const pt: PivotDictionary;
243
+
244
+ declare const ru: PivotDictionary;
245
+
246
+ declare const ar: PivotDictionary;
247
+
248
+ declare const zhCN: PivotDictionary;
249
+
250
+ declare const ja: PivotDictionary;
251
+
252
+ declare const ko: PivotDictionary;
253
+
254
+ /** Message sent to the worker to initialize the engine with columnar data. */
255
+ interface WorkerInitRequest {
256
+ action: 'init';
257
+ id: string;
258
+ rowCount: number;
259
+ columnarData: Record<string, {
260
+ type: 'int32' | 'float64';
261
+ buffer: ArrayBuffer;
262
+ }>;
263
+ dictionary: string[];
264
+ rowFields: PivotField<any>[];
265
+ colFields: PivotField<any>[];
266
+ dataFields: PivotField<any>[];
267
+ workerBootstrap?: {
268
+ id: string;
269
+ type: string;
270
+ workerCode: string;
271
+ }[];
272
+ /**
273
+ * Skip the initial unfiltered build. Used by the worker pipeline, where a
274
+ * filter request (which rebuilds) always follows init — avoids building the
275
+ * tries twice. compute() self-heals if no build happened yet.
276
+ */
277
+ deferBuild?: boolean;
278
+ }
279
+ interface WorkerFilterSpec {
280
+ fieldId: string;
281
+ filterType: 'include' | 'exclude';
282
+ dictIds: number[];
283
+ }
284
+ interface PrefilterConditionSpec {
285
+ fieldId: string;
286
+ operator: string;
287
+ value: string | number | boolean | null | undefined | (string | number | boolean | null | undefined)[];
288
+ }
289
+ interface PrefilterGroupSpec {
290
+ logicalOperator: 'and' | 'or';
291
+ conditions: (PrefilterConditionSpec | PrefilterGroupSpec)[];
292
+ }
293
+ interface WorkerFilterRequest {
294
+ action: 'filter';
295
+ id: string;
296
+ filters: WorkerFilterSpec[];
297
+ prefilter?: PrefilterGroupSpec;
298
+ }
299
+ interface WorkerComputeRequest {
300
+ action: 'compute';
301
+ id: string;
302
+ expandedPaths: string[];
303
+ expandedColPaths: string[];
304
+ }
305
+ /**
306
+ * Include/exclude filter carried INTO the incremental init pipeline as raw
307
+ * value strings. The worker resolves them to dictionary ids incrementally as
308
+ * dictionary chunks arrive (a value string that is not yet in the dictionary
309
+ * cannot match any row of the chunks seen so far, so per-chunk resolution is
310
+ * exact).
311
+ */
312
+ interface WorkerInitFilterSpec {
313
+ fieldId: string;
314
+ filterType: 'include' | 'exclude';
315
+ valueStrings: string[];
316
+ }
317
+ /**
318
+ * Opens an incremental (chunked) init pipeline. Column buffers arrive via
319
+ * {@link WorkerInitChunkRequest} and are grouped/aggregated as they arrive,
320
+ * overlapping worker-side build with main-thread encoding. Filters are
321
+ * applied during the build (no separate rebuild needed afterwards). The final
322
+ * engine state is identical to a monolithic init + applyFilter.
323
+ */
324
+ interface WorkerInitStartRequest {
325
+ action: 'initStart';
326
+ id: string;
327
+ rowCountTotal: number;
328
+ /** Column kind per field id — full-size arrays are preallocated up front. */
329
+ columnTypes: Record<string, 'int32' | 'float64'>;
330
+ /** Initial dictionary (index 0 = ''); the rest arrives via chunk appends. */
331
+ dictionary: string[];
332
+ rowFields: PivotField<any>[];
333
+ colFields: PivotField<any>[];
334
+ dataFields: PivotField<any>[];
335
+ filters?: WorkerInitFilterSpec[];
336
+ prefilter?: PrefilterGroupSpec;
337
+ workerBootstrap?: {
338
+ id: string;
339
+ type: string;
340
+ workerCode: string;
341
+ }[];
342
+ }
343
+ interface WorkerInitChunkRequest {
344
+ action: 'initChunk';
345
+ id: string;
346
+ start: number;
347
+ end: number;
348
+ columns: Record<string, ArrayBuffer>;
349
+ /** Dictionary entries appended (in order) since the previous message. */
350
+ dictionaryAppend?: string[];
351
+ }
352
+ /**
353
+ * Reassigns field roles (row/column/data) over the columnar data already
354
+ * stored in the worker — the fast path for field drag & drop. The raw data is
355
+ * NOT re-encoded or re-transferred; only missing columns (fields entering an
356
+ * area for the first time, or whose encoding definition changed) are shipped
357
+ * via `newColumns` together with any dictionary entries appended while
358
+ * encoding them.
359
+ */
360
+ interface WorkerReconfigureRequest {
361
+ action: 'reconfigure';
362
+ id: string;
363
+ rowFields: PivotField<any>[];
364
+ colFields: PivotField<any>[];
365
+ dataFields: PivotField<any>[];
366
+ /** Freshly encoded columns to merge into stored columnar data. */
367
+ newColumns?: Record<string, {
368
+ type: 'int32' | 'float64';
369
+ buffer: ArrayBuffer;
370
+ }>;
371
+ /** Dictionary entries appended (in order) since the worker's dictionary was last synced. */
372
+ dictionaryAppend?: string[];
373
+ }
374
+ /**
375
+ * Flat cell matrix returned by the engine.
376
+ * `keys[i]` = `rowId * MAX_C + colId` hash; `sums[i * numDF + df]` = finalized aggregated value.
377
+ */
378
+ interface FlatCellMatrix {
379
+ keys: Float64Array;
380
+ /** Finalized values per cell per data field (sum, avg, min, max, count, or distinct count). */
381
+ sums: Float64Array;
382
+ counts: Int32Array;
383
+ /** Post-processed display values after summary display modes are applied. */
384
+ displaySums?: Float64Array;
385
+ }
386
+ interface WorkerResponse {
387
+ id: string;
388
+ rowTree: PivotNode[];
389
+ colTree: PivotNode[];
390
+ cellMatrix: FlatCellMatrix;
391
+ rowIndexMap: Record<string, number>;
392
+ columnIndexMap: Record<string, number>;
393
+ cardinalityMap: Record<string, number>;
394
+ /** Monotonic version of the trie build that produced the index maps. */
395
+ indexMapsVersion?: number;
396
+ /**
397
+ * Wire-level flag: index/cardinality maps were omitted because they are
398
+ * unchanged since the previous compute response; the receiver must reuse
399
+ * its cached copies.
400
+ */
401
+ indexMapsOmitted?: boolean;
402
+ error?: string;
403
+ isInitComplete?: boolean;
404
+ isFilterComplete?: boolean;
405
+ isReconfigureComplete?: boolean;
406
+ }
407
+ /**
408
+ * TypedArray-based pivot computation engine designed to run inside a Web Worker.
409
+ *
410
+ * Pipelines: monolithic `init()` → `applyFilter()` → `compute()`, or the
411
+ * chunked `initStart()` → `initChunk()`× → `initEnd()` → `compute()` (filters
412
+ * applied during the chunked build; result state is identical).
413
+ * Uses {@link FastTrie} for hierarchical grouping and pre-aggregates leaf groups
414
+ * into flat TypedArrays supporting SUM, COUNT, AVG, MIN, MAX, and DISTINCT.
415
+ */
416
+ declare class FlatPivotEngine {
417
+ private dictionary;
418
+ private rowFields;
419
+ private colFields;
420
+ private dataFields;
421
+ private storedColumns;
422
+ private storedRowCount;
423
+ private lastMask;
424
+ private isBuilt;
425
+ private buildState;
426
+ private incrementalFilters;
427
+ private incrementalPrefilter;
428
+ private rowTrie;
429
+ private colTrie;
430
+ private cardinalityMap;
431
+ private rowPathStrs;
432
+ private colPathStrs;
433
+ private rowIndexMapCache;
434
+ private columnIndexMapCache;
435
+ private buildVersion;
436
+ private groupCount;
437
+ private leafGroupRowIds;
438
+ private leafGroupColIds;
439
+ private leafGroupMeasures;
440
+ private leafGroupCounts;
441
+ private leafGroupMins;
442
+ private leafGroupMaxes;
443
+ private leafGroupDistinctSets;
444
+ init(req: WorkerInitRequest): void;
445
+ /**
446
+ * Swap field roles and regroup the already-stored columnar data under the
447
+ * current filter mask. Skips data encoding/transfer entirely — aggregation
448
+ * results are identical to a fresh init + filter with the same fields.
449
+ */
450
+ reconfigure(req: WorkerReconfigureRequest): void;
451
+ /**
452
+ * Open a chunked init: preallocate full-size columns and the build state.
453
+ * Filters (as raw value strings) are applied DURING the chunked build, so
454
+ * no separate rebuild is needed afterwards — the final state is identical
455
+ * to a monolithic init + applyFilter with the same inputs.
456
+ */
457
+ initStart(req: WorkerInitStartRequest): void;
458
+ /** Merge a column chunk, mask its rows under the init filters, and aggregate it. */
459
+ initChunk(req: WorkerInitChunkRequest): void;
460
+ /** Close the chunked init and commit the accumulated build. */
461
+ initEnd(): void;
462
+ /**
463
+ * Resolve pending filter value strings against dictionary entries from
464
+ * `fromIndex` on. A string that is not yet in the dictionary cannot match
465
+ * any already-processed row, so incremental resolution stays exact.
466
+ */
467
+ private resolveIncrementalFilterStrings;
468
+ /** applyFilter semantics over a row range, writing into lastMask. */
469
+ private computeMaskRange;
470
+ applyFilter(req: WorkerFilterRequest): void;
471
+ private evaluatePrefilterGroup;
472
+ private evaluatePrefilterCondition;
473
+ private buildFromMask;
474
+ /** Allocate the state of a build pass (full rebuild or chunked init). */
475
+ private beginBuild;
476
+ /** Cardinality bitmaps must cover the (growing) dictionary id space. */
477
+ private ensureCardCapacity;
478
+ /**
479
+ * Single fused pass over rows [start, end): cardinality + trie grouping +
480
+ * leaf aggregation. `mask` (when present) is indexed by absolute row index.
481
+ */
482
+ private processRange;
483
+ /** Commit the build state into the engine + rebuild per-build caches. */
484
+ private finalizeBuild;
485
+ private buildPathStrs;
486
+ private buildIndexMap;
487
+ compute(req: WorkerComputeRequest): WorkerResponse;
488
+ }
489
+
490
+ interface PivotEngineResult {
491
+ rowTree: PivotNode[];
492
+ colTree: PivotNode[];
493
+ cellMatrix: FlatCellMatrix;
494
+ rowIndexMap: Record<string, number>;
495
+ columnIndexMap: Record<string, number>;
496
+ cardinalityMap: Record<string, number>;
497
+ }
498
+ interface FieldDistinctEntry {
499
+ rawStr: string;
500
+ rawVal: PivotValue;
501
+ }
502
+ /** Set the active grid context for subsequent init/compute calls. */
503
+ declare function setActiveEngineGrid(gridId: string): void;
504
+ /**
505
+ * Release a grid's worker when the grid unmounts. Termination is deferred by
506
+ * a short keep-alive window: a grid that remounts quickly (rebuilds, config
507
+ * driven remounts, React StrictMode double mount) re-claims the worker and —
508
+ * when the dataset identity is unchanged — skips the entire re-encode and
509
+ * re-transfer of its data.
510
+ */
511
+ declare function destroyEngineWorker(gridId: string): void;
512
+ interface InitFilterState {
513
+ /** All fields — those carrying filterValues become include/exclude specs. */
514
+ fields: PivotField<any>[];
515
+ prefilter?: PivotPrefilter;
516
+ }
517
+ declare function initPivotEngineAsync<TRow>(data: TRow[], rowFields: PivotField<TRow>[], colFields: PivotField<TRow>[], dataFields: PivotField<TRow>[], registry?: PivotEngineRegistry, workerUrl?: string | URL, options?: {
518
+ /**
519
+ * Skip the same-dataset reuse fast path and re-encode unconditionally.
520
+ * Used by explicit refresh (refreshEngine): callers may have mutated the
521
+ * data array in place, so stored columns cannot be trusted.
522
+ */
523
+ forceReencode?: boolean;
524
+ /**
525
+ * Current filter state; when provided, filters are applied DURING the
526
+ * chunked init build (single build instead of init-build + filter-build).
527
+ * `filtersApplied: true` in the result means the caller can skip its
528
+ * follow-up filter request.
529
+ */
530
+ filterState?: InitFilterState;
531
+ }): Promise<{
532
+ filtersApplied: boolean;
533
+ }>;
534
+ /**
535
+ * Fast path for field drag & drop / reorder / settings changes: reassigns
536
+ * field roles over the columnar data already stored in the worker instead of
537
+ * re-encoding and re-transferring the whole dataset. Only fields that have no
538
+ * matching column worker-side (entering an area for the first time, or whose
539
+ * encode-relevant definition changed) are encoded and shipped individually.
540
+ *
541
+ * Returns `false` when the fast path is not applicable (no initialized
542
+ * worker context, or the dataset changed) — the caller must fall back to a
543
+ * full {@link initPivotEngineAsync}.
544
+ */
545
+ declare function reconfigurePivotEngineAsync<TRow>(data: TRow[], rowFields: PivotField<TRow>[], colFields: PivotField<TRow>[], dataFields: PivotField<TRow>[], registry?: PivotEngineRegistry): Promise<boolean>;
546
+ /**
547
+ * Send filter specs to the worker. Converts field.filterValues to
548
+ * dictionary-encoded integer IDs so the worker can do fast integer
549
+ * set lookups on columnar data instead of string comparisons.
550
+ */
551
+ declare function filterPivotEngineAsync(fields: PivotField<any>[], prefilter?: PivotPrefilter): Promise<void>;
552
+ declare function computePivotMatrixAsync(expandedPaths: string[], expandedColPaths: string[]): Promise<PivotEngineResult>;
553
+ declare function getFieldDistinctValues(fieldId: string): FieldDistinctEntry[] | null;
554
+
555
+ interface PivotReportState {
556
+ fields: PivotField<any>[];
557
+ layout: PivotLayoutState;
558
+ expandedPaths: string[];
559
+ expandedColPaths?: string[];
560
+ chartState?: Record<string, unknown>;
561
+ }
562
+ interface PivotReport {
563
+ id: string;
564
+ name: string;
565
+ createdAt: string;
566
+ updatedAt: string;
567
+ isDefault?: boolean;
568
+ schemaVersion?: number;
569
+ state: PivotReportState;
570
+ }
571
+
572
+ /**
573
+ * Prune row/column tree nodes that have no data cells — the shared
574
+ * implementation of `layout.hideEmptySummaryCells`. Used by BOTH the on-screen
575
+ * grid and the export pipeline so a hidden-empty configuration produces
576
+ * identical structure in the UI and in exported files.
577
+ *
578
+ * A row node is kept if the cell matrix contains its grand-total intersection
579
+ * (rowId × MAX_C); a column node is kept if it contains the column's root-row
580
+ * intersection (colId). Nodes missing from the index maps are kept as-is
581
+ * (they cannot be safely evaluated).
582
+ */
583
+ declare function filterEmptySummaryTree(engineResult: PivotEngineResult): [PivotNode[], PivotNode[]];
584
+ declare function getVisibleLeafCount(node: PivotNode, expandedColPaths: Set<string>, allExpanded?: boolean): number;
585
+ declare function getVisibleMaxDepth(nodes: PivotNode[], expandedColPaths: Set<string>, allExpanded?: boolean): number;
586
+ declare function getVisibleColLeaves(nodes: PivotNode[], expandedColPaths: Set<string>, allExpanded?: boolean): PivotNode[];
587
+ interface ColHeaderCell {
588
+ node: PivotNode | null;
589
+ caption: string;
590
+ colSpan: number;
591
+ rowSpan: number;
592
+ isTotal: boolean;
593
+ fieldId?: string;
594
+ colPath?: string;
595
+ hasChildren?: boolean;
596
+ isExpanded?: boolean;
597
+ }
598
+ declare function buildColumnHeaders(colTree: PivotNode[], dataFields: PivotField[], layout: PivotLayoutState, expandedColPaths: Set<string>, allExpanded?: boolean): ColHeaderCell[][];
599
+ /**
600
+ * A flattened row for rendering. Each row represents either:
601
+ * - A leaf data row (values at each depth level column)
602
+ * - A subtotal row (after a group's children end)
603
+ * - A grand total row
604
+ */
605
+ interface FlatRow {
606
+ /** The node path segments (value at each depth) */
607
+ pathValues: (string | null)[];
608
+ /** Which depth level this row "belongs to" (for expand/collapse) */
609
+ depth: number;
610
+ /** The full key/path hash for this node */
611
+ key: string;
612
+ /** Whether this is a subtotal row */
613
+ isSubtotal: boolean;
614
+ /** Whether this row's group has children that can be expanded */
615
+ hasChildren: boolean;
616
+ /** Whether this row's group is currently expanded */
617
+ isExpanded: boolean;
618
+ /** The actual PivotNode reference (the deepest node for this row) */
619
+ node: PivotNode;
620
+ /** rowSpan hints: for tabular layout, parent cells that span multiple rows */
621
+ rowSpans: number[];
622
+ /** Whether this is the first row of its parent group (used for rowSpan rendering) */
623
+ isFirstInGroup: boolean[];
624
+ }
625
+ declare function flattenRowTree(nodes: PivotNode[], expandedPaths: Set<string>, allExpanded: boolean): PivotNode[];
626
+ /**
627
+ * Flatten the row tree for spreadsheet-style tabular rendering.
628
+ *
629
+ * In this layout:
630
+ * - Each row field gets its own column
631
+ * - Parent group values appear in their respective columns
632
+ * - When a group is expanded, children appear below with their values
633
+ * in the NEXT column to the right
634
+ * - Subtotal rows appear after each group's children (if showRowTotals is true)
635
+ * - Parent cells span multiple rows (rowSpan) to avoid repetition
636
+ */
637
+ declare function flattenRowTreeTabular(nodes: PivotNode[], expandedPaths: Set<string>, allExpanded: boolean, maxDepth: number, showRowTotals: boolean, totalsPosition: 'top' | 'bottom'): FlatRow[];
638
+ /**
639
+ * Flatten the row tree for compact tree rendering.
640
+ * In this layout:
641
+ * - All row headers share a single column (spanning maxDepth).
642
+ * - Each node is its own row.
643
+ * - Indentation is used to show hierarchy.
644
+ */
645
+ declare function flattenRowTreeTree(nodes: PivotNode[], expandedPaths: Set<string>, allExpanded: boolean, treeDepth: number, showRowTotals: boolean, totalsPosition: 'top' | 'bottom'): FlatRow[];
646
+
647
+ type ExportFormat = 'excel-list' | 'excel-pivot' | 'pdf' | 'json' | 'json-pivot' | 'json-snapshot' | 'xml' | 'csv' | 'print' | 'clipboard';
648
+ /** Options passed to the export pipeline — all fields optional for backward compat. */
649
+ interface ExportOptions {
650
+ /** Apply prefilter to raw data before export. */
651
+ applyFilters?: boolean;
652
+ /** Custom file name (without extension). */
653
+ fileName?: string;
654
+ /** Expand all nodes before export regardless of current state. */
655
+ expandAll?: boolean;
656
+ /** AbortSignal for cancellation support. */
657
+ signal?: AbortSignal;
658
+ /** Progress callback: 0–100. */
659
+ onProgress?: (percent: number) => void;
660
+ /** Include hidden/chooser fields in list export. */
661
+ includeHiddenFields?: boolean;
662
+ /** Locale for formatting. */
663
+ locale?: string;
664
+ }
665
+ declare function exportPivotData<TRow>(format: ExportFormat, data: TRow[], fields: PivotField<TRow>[], engineResult: PivotEngineResult, layout: PivotLayoutState, expandedPaths: Set<string>, expandedColPaths: Set<string>, fileName?: string, locale?: string, options?: ExportOptions): Promise<void>;
666
+ declare function escapeXmlText(value: string): string;
667
+ declare function getCellVal(engineResult: PivotEngineResult, rHash: string, cHash: string, dfId: string, dataFields: PivotField[], cellLookup: Map<number, number>, preferDisplay?: boolean): number | "";
668
+ /** Per-cell style resolved from a data field's conditional-formatting rules. */
669
+ interface ExportCellStyle {
670
+ fillColor?: string;
671
+ textColor?: string;
672
+ bold?: boolean;
673
+ }
674
+ /** Parse a CSS color (#rgb, #rrggbb, rgb(...)) into an [r,g,b] tuple, or null. */
675
+ declare function cssColorToRgb(color: string | undefined): [number, number, number] | null;
676
+ /** Build cellLookup Map from engine result — shared across export functions. */
677
+ declare function buildCellLookup(engineResult: PivotEngineResult): Map<number, number>;
678
+ /** Build column paths list from visible column leaves and data fields. */
679
+ declare function buildColPathsList(engineResult: PivotEngineResult, dataFields: PivotField[], layout: PivotLayoutState, expandedColPaths: Set<string>, allExpanded: boolean): string[][];
680
+ /**
681
+ * Format a date-typed row/column header value exactly as the on-screen grid
682
+ * does (`DateFormatter.format(value, 'grid', …)`), honoring the field's
683
+ * groupInterval. Non-date fields and total/blank cells pass through unchanged.
684
+ */
685
+ declare function formatHeaderValue(value: any, field: PivotField | undefined, locale: string): any;
686
+ /**
687
+ * Flatten row nodes for export, honoring `rowHeaderLayout`. In `tree` mode all
688
+ * row fields collapse into a single indented column (matching the grid's tree
689
+ * renderer); otherwise each row field gets its own column (tabular). Returns
690
+ * the flat rows plus the effective row-header column count.
691
+ */
692
+ declare function flattenExportRows(engineResult: PivotEngineResult, rowFields: PivotField[], layout: PivotLayoutState, expandedPaths: Set<string>, allExpanded: boolean): {
693
+ flatRows: FlatRow[];
694
+ treeMode: boolean;
695
+ rowLabelCols: number;
696
+ };
697
+ /**
698
+ * Produce the row-header label cell(s) for one flat row. Tree mode returns a
699
+ * single indented label (subtotals keep a "Total" marker so downstream
700
+ * heuristics still recognize them); tabular mode returns one cell per depth.
701
+ */
702
+ declare function buildRowLabelCells(flatRow: FlatRow, rowFields: PivotField[], treeMode: boolean, rowLabelCols: number, locale: string): any[];
703
+ /** Find the data field for a given column path entry. */
704
+ declare function resolveColPath(cPathInfo: string[], dataFields: PivotField[]): {
705
+ cHash: string;
706
+ dfId: string;
707
+ };
708
+ /**
709
+ * Build the array-of-arrays used by the PDF/Print/Clipboard exporters.
710
+ *
711
+ * Async + cancellable: the (potentially large) data-row loop yields to the
712
+ * event loop every {@link AOA_CHUNK} rows, honors an AbortSignal, and reports
713
+ * incremental progress. Returns `null` when the export was aborted mid-build.
714
+ */
715
+ 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<{
716
+ aoa: any[][];
717
+ styles: (ExportCellStyle | null)[][] | null;
718
+ } | null>;
719
+
720
+ /** Area where a {@link PivotField} can be placed. */
721
+ type PivotArea = 'row' | 'column' | 'data' | 'filter' | 'chooser';
722
+ /** Aggregation function applied to data fields in worker pre-aggregation. */
723
+ type PivotSummaryType = 'sum' | 'count' | 'avg' | 'min' | 'max' | 'distinct' | 'custom';
724
+ /** Post-aggregation display transformation applied after cell values are computed. */
725
+ type PivotSummaryDisplayMode = 'absolute' | 'percentOfTotal' | 'percentOfColumnTotal' | 'percentOfRowTotal' | 'runningTotal' | 'difference' | 'percentDifference';
726
+ /** Temporal or numeric grouping interval for date/number fields. */
727
+ type PivotGroupInterval = 'year' | 'quarter' | 'month' | 'day' | 'numeric' | 'custom';
728
+ /** Supported UI locale identifiers. */
729
+ type PivotLocale = 'tr' | 'en' | 'ar' | 'de' | 'fr' | 'es' | 'it' | 'pt' | 'ru' | 'zh-CN' | 'ja' | 'ko';
730
+ /** Union of all value types a pivot cell, node, or filter can hold. */
731
+ type PivotValue = string | number | boolean | Date | null | undefined;
732
+ /** Comparison operators for filter conditions. */
733
+ type FilterOperator = '=' | '<>' | '>' | '>=' | '<' | '<=' | 'contains' | 'notcontains' | 'startswith' | 'endswith' | 'in' | 'notin' | 'isnull' | 'isnotnull';
734
+ /** A single filter predicate targeting one field. */
735
+ interface FilterCondition {
736
+ fieldId: string;
737
+ operator: FilterOperator;
738
+ value?: PivotValue | PivotValue[];
739
+ }
740
+ /** Composable filter tree — conditions joined by AND/OR, nestable. */
741
+ interface FilterGroup {
742
+ logicalOperator: 'and' | 'or';
743
+ conditions: (FilterCondition | FilterGroup)[];
744
+ }
745
+ /** Top-level prefilter applied before pivot computation. */
746
+ type PivotPrefilter = FilterGroup;
747
+ /** CSS custom-property overrides for theming the pivot grid. */
748
+ interface PivotTheme {
749
+ id?: string;
750
+ name?: string;
751
+ background?: string;
752
+ surface?: string;
753
+ surfaceHover?: string;
754
+ surfaceHeader?: string;
755
+ border?: string;
756
+ text?: string;
757
+ textMuted?: string;
758
+ textHeader?: string;
759
+ primary?: string;
760
+ primaryForeground?: string;
761
+ success?: string;
762
+ danger?: string;
763
+ warning?: string;
764
+ info?: string;
765
+ totalBackground?: string;
766
+ stripeBackground?: string;
767
+ groupBorder?: string;
768
+ iconActive?: string;
769
+ }
770
+ interface CustomSummaryOptions {
771
+ summaryProcess: 'start' | 'calculate' | 'finalize';
772
+ value: number | null;
773
+ totalValue: number | null;
774
+ }
775
+ interface PivotConditionRule<TStyle = any> {
776
+ type: 'colorScale' | 'dataBar' | 'iconSet' | 'expression';
777
+ formula?: (value: number, cellContext: PivotCell) => boolean;
778
+ style: TStyle;
779
+ }
780
+ type PivotCellTemplate = (props: {
781
+ value: PivotValue;
782
+ displayValue: string;
783
+ cell?: PivotCell;
784
+ field: PivotField;
785
+ }) => any;
786
+ /**
787
+ * Describes a single field (dimension or measure) in the pivot grid.
788
+ *
789
+ * @typeParam TRow - Shape of source data rows.
790
+ * @typeParam TCellTemplate - Custom cell render function type.
791
+ * @typeParam TStyle - Style object type for conditional formatting rules.
792
+ */
793
+ interface PivotField<TRow = any, TCellTemplate = PivotCellTemplate, TStyle = any> {
794
+ /** Unique identifier for this field. */
795
+ id: string;
796
+ /** Source property name in the data row. */
797
+ dataField?: Extract<keyof TRow, string> | string;
798
+ /** Display label shown in headers and field chooser. */
799
+ caption: string;
800
+ /** Data type used for encoding, formatting, and grouping. */
801
+ dataType: 'string' | 'number' | 'date' | 'boolean';
802
+ /** Which pivot area this field belongs to. */
803
+ area?: PivotArea;
804
+ /** Position index within the area. */
805
+ areaIndex?: number;
806
+ /** Whether the field is visible in the field chooser. */
807
+ visible?: boolean;
808
+ /** Aggregation type — computed in the Web Worker for all types. */
809
+ summaryType?: PivotSummaryType;
810
+ /** Post-aggregation display transformation (e.g. percent of total). */
811
+ summaryDisplayMode?: PivotSummaryDisplayMode;
812
+ calculateCustomSummary?: string | ((options: CustomSummaryOptions) => void);
813
+ /** True for calculated (virtual) fields that derive from other fields. */
814
+ isCalculated?: boolean;
815
+ formulaString?: string;
816
+ formulaType?: 'row' | 'summary';
817
+ /** Row-level expression evaluated via CSP-safe engine. */
818
+ calculateExpression?: string | ((row: TRow) => number | string);
819
+ /** Summary-level expression combining other data field values. */
820
+ calculateSummaryExpression?: string | ((cellValues: Record<string, number>) => number);
821
+ /** Intl format options or custom formatter for cell display values. */
822
+ format?: Intl.NumberFormatOptions | Intl.DateTimeFormatOptions | ((value: number) => string);
823
+ /** Conditional formatting rules evaluated per cell. */
824
+ conditionalFormatting?: PivotConditionRule<TStyle>[];
825
+ /** Custom cell render function. */
826
+ cellTemplate?: TCellTemplate;
827
+ /** Date/numeric grouping interval. */
828
+ groupInterval?: PivotGroupInterval | number;
829
+ /** Active filter values for header filter (include/exclude mode). */
830
+ filterValues?: Set<any>;
831
+ /** Whether filterValues is an include list or exclude list. */
832
+ filterType?: 'include' | 'exclude';
833
+ /** Sort direction for this field's header values. */
834
+ sortOrder?: 'asc' | 'desc';
835
+ /** Data field ID to sort rows by summary value. */
836
+ sortBySummaryField?: string;
837
+ /** Column path key for sort-by-summary targeting. */
838
+ sortBySummaryPath?: string;
839
+ /** Custom sort comparator for header values. */
840
+ calculateCustomSort?: (a: any, b: any, cellA?: PivotCell, cellB?: PivotCell) => number;
841
+ /** Show only top N values; requires sortBySummaryField. */
842
+ topN?: number;
843
+ /** Whether to aggregate remaining values into an "Others" row. */
844
+ topNShowOthers?: boolean;
845
+ /** Custom caption for the "Others" row when topN is active. */
846
+ topNOthersCaption?: string;
847
+ }
848
+ /** Controls pivot grid layout, totals visibility, and structural options. */
849
+ interface PivotLayoutState {
850
+ showColumnGrandTotals?: boolean;
851
+ showRowGrandTotals?: boolean;
852
+ showColumnTotals?: boolean;
853
+ showRowTotals?: boolean;
854
+ /** Whether subtotals appear above or below their groups. */
855
+ totalsPosition?: 'top' | 'bottom';
856
+ showGrandTotals?: 'rows' | 'columns' | 'both' | 'none';
857
+ showSubTotals?: 'rows' | 'columns' | 'both' | 'none';
858
+ totalsDisplayMode?: 'top' | 'bottom';
859
+ /** Row header style: 'tabular' gives one column per row field, 'tree' nests all into one column. */
860
+ rowHeaderLayout?: 'tabular' | 'tree';
861
+ /** Hide rows/columns that have no data. */
862
+ hideEmptySummaryCells?: boolean;
863
+ /** Place data field labels in row headers or column headers. */
864
+ dataFieldPosition?: 'rows' | 'columns';
865
+ /** Server-side or computed prefilter applied before aggregation. */
866
+ prefilter?: PivotPrefilter;
867
+ showFooter?: boolean;
868
+ showFilterArea?: boolean;
869
+ /** Chart integration type when rendering in chart mode. */
870
+ chartType?: string;
871
+ }
872
+ interface PivotLayoutProfile {
873
+ id: string;
874
+ name: string;
875
+ fields: PivotField[];
876
+ layout: PivotLayoutState;
877
+ isDefault: boolean;
878
+ }
879
+ interface PivotStateStoringConfig {
880
+ enabled: boolean;
881
+ type?: 'localStorage' | 'sessionStorage' | 'custom';
882
+ storageKey?: string;
883
+ onSave?: (state: any) => void;
884
+ onLoad?: () => any;
885
+ }
886
+ interface PivotToolbarConfig {
887
+ showSaveReport?: boolean;
888
+ showImportFile?: boolean;
889
+ showExportButton?: boolean;
890
+ showCalculatedFields?: boolean;
891
+ showFullscreenToggle?: boolean;
892
+ showFieldChooserToggle?: boolean;
893
+ showExpandCollapseAll?: boolean;
894
+ showRefreshButton?: boolean;
895
+ }
896
+ /** A node in the row or column tree hierarchy returned by the engine. */
897
+ interface PivotNode {
898
+ key: string;
899
+ value: PivotValue;
900
+ fieldId: string;
901
+ children: PivotNode[];
902
+ isExpanded: boolean;
903
+ isTotal: boolean;
904
+ depth: number;
905
+ hasChildren?: boolean;
906
+ }
907
+ /** Represents a single cell at the intersection of a row path and column path. */
908
+ interface PivotCell<TRow = any> {
909
+ rowPath: string[];
910
+ colPath: string[];
911
+ values: Record<string, number>;
912
+ displayValues: Record<string, string>;
913
+ records?: TRow[];
914
+ isTotalCell: boolean;
915
+ }
916
+ /** Minimal data source shape: field definitions + row array. */
917
+ interface PivotDataSource<TRow = any> {
918
+ fields: PivotField<TRow>[];
919
+ store: TRow[];
920
+ }
921
+ /** Fired when a user clicks a data cell, header, or total. */
922
+ interface CellClickEvent<TRow = any, TNativeEvent = unknown> {
923
+ event: TNativeEvent;
924
+ cellType: 'data' | 'rowHeader' | 'colHeader' | 'grandTotal';
925
+ value?: number;
926
+ rowPath: string[];
927
+ colPath: string[];
928
+ records?: TRow[];
929
+ }
930
+ interface FieldMoveEvent {
931
+ fieldId: string;
932
+ sourceArea: string;
933
+ targetArea: string;
934
+ newIndex: number;
935
+ cancel: () => void;
936
+ isCanceled: boolean;
937
+ }
938
+ /** Fired before each cell renders — mutate `cellConfig` to customize appearance. */
939
+ interface CellPreparedEvent<TRow = any, TNode = unknown, TStyle = unknown> {
940
+ area: 'row' | 'column' | 'data';
941
+ cell: PivotCell<TRow> | null;
942
+ rowIndex: number;
943
+ columnIndex: number;
944
+ cellConfig: {
945
+ text?: TNode;
946
+ style?: TStyle;
947
+ className?: string;
948
+ };
949
+ }
950
+ interface ExportingEvent {
951
+ format: string;
952
+ cancel: boolean;
953
+ }
954
+ interface PivotImportStatus {
955
+ isOpen: boolean;
956
+ status: 'loading' | 'success' | 'error' | 'warning';
957
+ title: string;
958
+ messages: string[];
959
+ /** Overall parse progress 0..100 (present only while streaming a large file). */
960
+ progress?: number;
961
+ /** Coarse pipeline stage label (reading | parsing | typing | finalizing). */
962
+ phase?: string;
963
+ /** Whether the in-flight import can be cancelled by the user. */
964
+ cancellable?: boolean;
965
+ }
966
+ /** One detected column in the import preview / column-mapping step. */
967
+ interface PivotImportField {
968
+ /** Source data key. */
969
+ dataField: string;
970
+ /** Display caption (editable in the mapping UI). */
971
+ caption: string;
972
+ /** Detected data type (editable in the mapping UI). */
973
+ dataType: 'string' | 'number' | 'date' | 'boolean';
974
+ }
975
+ /**
976
+ * Parsed-but-not-yet-committed import awaiting user review (preview + column
977
+ * mapping). Held in observable state; the full row set is kept privately by the
978
+ * controller and applied on commit.
979
+ */
980
+ interface PivotImportPreviewState {
981
+ fields: PivotImportField[];
982
+ /** First-N rows for the preview table. */
983
+ sample: Record<string, unknown>[];
984
+ /** Total parsed row count. */
985
+ rowCount: number;
986
+ warnings: string[];
987
+ }
988
+ type DropIntent = 'before' | 'after' | 'append' | null;
989
+ interface PivotDragIntentState {
990
+ activeId: string | null;
991
+ targetId: string | null;
992
+ targetArea: string | null;
993
+ intent: DropIntent;
994
+ }
995
+ /** Full observable state of the pivot controller — consumed by UI frameworks. */
996
+ interface PivotControllerState<TRow = any> {
997
+ gridId: string;
998
+ fields: PivotField<TRow>[];
999
+ layout: PivotLayoutState;
1000
+ expandedPaths: Set<string>;
1001
+ expandedColPaths: Set<string>;
1002
+ columnWidths: Record<string, number>;
1003
+ engineResult: PivotEngineResult | null;
1004
+ isBuilding: boolean;
1005
+ /** Monotonic engine build progress shown by UI loaders. 0..100, simulated when exact worker progress is unavailable. */
1006
+ buildProgress?: number;
1007
+ engineError: Error | null;
1008
+ selectionStats: PivotSelectionStats | null;
1009
+ reports: PivotReport[];
1010
+ activeReportId: string | null;
1011
+ importStatus: PivotImportStatus;
1012
+ /** Pending import awaiting preview/column-mapping review (null when none). */
1013
+ importPreview: PivotImportPreviewState | null;
1014
+ drag: PivotDragIntentState;
1015
+ }
1016
+ interface PivotControllerCallbacks<TRow = any> {
1017
+ onRefresh?: () => void;
1018
+ onImportData?: (data: TRow[]) => void;
1019
+ onFieldsChange?: (fields: PivotField<TRow>[]) => void;
1020
+ onLayoutChange?: (layout: PivotLayoutState) => void;
1021
+ onFieldMove?: (e: FieldMoveEvent) => void | Promise<void>;
1022
+ onBeforePivotCalculate?: () => void;
1023
+ onAfterPivotCalculate?: (result: PivotEngineResult) => void;
1024
+ onExporting?: (e: ExportingEvent) => void;
1025
+ onError?: (error: Error) => void;
1026
+ onChartStateLoaded?: (chartState: any) => void;
1027
+ }
1028
+ /** Options for initializing a {@link PivotController}. */
1029
+ interface PivotControllerOptions<TRow = any> extends PivotControllerCallbacks<TRow> {
1030
+ gridId: string;
1031
+ data: TRow[];
1032
+ initialFields: PivotField<TRow>[];
1033
+ controlledFields?: PivotField<TRow>[];
1034
+ controlledLayout?: PivotLayoutState;
1035
+ chartIntegrationOptions?: Record<string, any>;
1036
+ registry?: PivotEngineRegistry;
1037
+ locale?: string;
1038
+ workerUrl?: string | URL;
1039
+ /**
1040
+ * When true, file/URL/paste imports first open a preview + column-mapping
1041
+ * step instead of applying immediately. Defaults to false (apply directly).
1042
+ */
1043
+ previewImport?: boolean;
1044
+ }
1045
+ /** Imperative API handle exposed via React ref or Angular adapter. */
1046
+ interface PivotGridRef {
1047
+ exportData: (format: ExportFormat | string, options?: ExportOptions) => void;
1048
+ expandAll: () => void;
1049
+ collapseAll: () => void;
1050
+ getState: () => PivotControllerState;
1051
+ setFields: (fields: PivotField[]) => void;
1052
+ refreshEngine: () => void;
1053
+ getRawData: () => unknown[];
1054
+ getEngineResult: () => PivotEngineResult | null;
1055
+ getCell: (rowPath: string[], colPath: string[]) => PivotCell | null;
1056
+ }
1057
+ declare const defaultPivotLayout: PivotLayoutState;
3
1058
 
4
1059
  type PivotStateListener = () => void;
5
1060
  /** Immutable-snapshot state store with debounced localStorage persistence. */
@@ -288,26 +1343,6 @@ declare class PivotReportService {
288
1343
  setDefaultReport(id: string): PivotReport[];
289
1344
  }
290
1345
 
291
- declare class PivotSelectionModel {
292
- static start(row: number, column: number, mode: PivotSelectionMode): PivotSelectionState;
293
- static extend(state: PivotSelectionState | null, row: number, column: number, mode: PivotSelectionMode): PivotSelectionState | null;
294
- static finish(state: PivotSelectionState | null): PivotSelectionState | null;
295
- static containsCell(state: PivotSelectionState | null, row: number, column: number): boolean;
296
- static calculateStats(state: PivotSelectionState | null, valueAccessor: PivotCellValueAccessor): PivotSelectionStats | null;
297
- static toTsv(state: PivotSelectionState | null, textAccessor: PivotCellTextAccessor): string;
298
- private static getBounds;
299
- }
300
-
301
- type PivotEventMap = Record<string, any>;
302
- type PivotEventHandler<TPayload> = (payload: TPayload) => void;
303
- declare class PivotEventEmitter<TEvents extends PivotEventMap> {
304
- private handlers;
305
- on<K extends keyof TEvents>(eventName: K, handler: PivotEventHandler<TEvents[K]>): () => void;
306
- off<K extends keyof TEvents>(eventName: K, handler: PivotEventHandler<TEvents[K]>): void;
307
- emit<K extends keyof TEvents>(eventName: K, payload: TEvents[K]): void;
308
- clear(): void;
309
- }
310
-
311
1346
  declare const MAX_C = 67108864;
312
1347
  declare function cellHash(rId: number, cId: number): number;
313
1348
  declare function cellHashRow(hash: number): number;
@@ -361,19 +1396,6 @@ declare function executeSummaryDisplayModesPhase<TRow>(engineResult: PivotEngine
361
1396
 
362
1397
  declare function extractGroupValue<TRow>(row: TRow, field: PivotField<TRow>): PivotValue;
363
1398
 
364
- type DateFormatContext = 'grid' | 'chart' | 'export';
365
- type DateGranularity = 'year' | 'quarter' | 'month' | 'day' | 'dayOfWeek' | string | number;
366
- declare class DateFormatter {
367
- private static intlCache;
368
- private static stringCache;
369
- /**
370
- * Formats a raw grouped date value into a human-readable string.
371
- * Cached to ensure 0 FPS drop on 500k+ rows.
372
- */
373
- static format(rawValue: any, context: DateFormatContext, locale: string, granularity?: DateGranularity): string;
374
- static clearCache(): void;
375
- }
376
-
377
1399
  declare class ExportStreamController {
378
1400
  private worker;
379
1401
  private static sharedWorker;
@@ -760,28 +1782,4 @@ declare function coerceRecords(records: Record<string, unknown>[], onProgress?:
760
1782
  */
761
1783
  declare function parseCsvToRows(text: string, onProgress?: (p: CsvParseProgress) => void): Record<string, unknown>[];
762
1784
 
763
- declare const tr: PivotDictionary;
764
-
765
- declare const en: PivotDictionary;
766
-
767
- declare const de: PivotDictionary;
768
-
769
- declare const fr: PivotDictionary;
770
-
771
- declare const es: PivotDictionary;
772
-
773
- declare const it: PivotDictionary;
774
-
775
- declare const pt: PivotDictionary;
776
-
777
- declare const ru: PivotDictionary;
778
-
779
- declare const ar: PivotDictionary;
780
-
781
- declare const zhCN: PivotDictionary;
782
-
783
- declare const ja: PivotDictionary;
784
-
785
- declare const ko: PivotDictionary;
786
-
787
- export { type AdvancedExportRequest, type AdvancedExporter, CellClickEvent, type CellType, type CsvParseProgress, CsvReader, DataNormalizer, type DateFormatContext, DateFormatter, type DateGranularity, DropIntent, ExportFormat, ExportOptions, ExportStreamController, ExportingEvent, FastTrie, FieldMoveEvent, type IFileReader, type ImportFormat, ImportManager, type ImportManagerOptions, type ImportProgress, type ImportResult, type ImportSnapshot, ImportStreamController, type ImportWorkerKind, type ImportWorkerResult, MAX_C, type ParseFileOptions, PivotArea, PivotCell, PivotCellAggregator, PivotCellTextAccessor, PivotCellValueAccessor, PivotConditionRule, PivotController, type PivotControllerEvents, PivotControllerOptions, PivotControllerState, PivotDictionary, PivotDragIntentState, PivotEngineRegistry, PivotEngineResult, PivotEngineService, type PivotEngineServiceConfig, PivotEventEmitter, type PivotEventHandler, type PivotEventMap, PivotExportService, PivotField, PivotFieldService, PivotImportField, type PivotImportLabels, PivotImportStatus, PivotLayoutState, PivotNode, PivotPrefilter, PivotReport, PivotReportManager, PivotReportService, PivotReportState, PivotSelectionMode, PivotSelectionModel, PivotSelectionState, PivotSelectionStats, type PivotStateListener, PivotStateStore, PivotValue, type ProcessFileStreamingOptions, type ProcessFromUrlOptions, type ValidationResult, XmlReader, ar, cellHash, cellHashCol, cellHashRow, classifyValue, clearFormatCache, coerceRecords, coerceValue, compileSafeFormula, conditionRuleToExcelStyle, de, dedupeHeaders, detectDelimiter, en, es, executePostAggregationPhase, executeSummaryDisplayModesPhase, extractGroupValue, filterRecords, filterRecordsAsync, formatCellValue, formatCellValueCached, fr, getAdvancedExporter, inferColumnType, intlFormatToExcelNumFmt, it, ja, ko, parseBoolean, parseCsvToRows, parseDelimited, parseFlexibleDate, parseLocaleNumber, pt, registerAdvancedExporter, ru, safeKey, sanitizeRows, sortPivotTree, stripBom, testSafeFormula, tr, zhCN };
1785
+ 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 };