@kanunilabs/pivotgrid-core 1.0.0

package/dist/pivot.worker-DQFl4fMu.d.cts

@@ -0,0 +1,1001 @@
+interface PivotPlugin {
+    id: string;
+    version?: string;
+    type: 'expression' | 'summary' | 'sort' | 'custom' | 'exporter' | 'cellRender' | 'aggregator' | 'headerRender' | 'toolbar';
+    execute?: Function;
+    workerCode?: string;
+    exportFunction?: (data: any[], options: any) => Promise<void>;
+    renderCell?: (value: any, displayValue: string, cellContext: any, field: any) => any;
+    renderHeader?: (field: any, defaultLabel: string) => any;
+    aggregate?: (values: number[]) => number;
+}
+declare class PivotEngineRegistry {
+    private plugins;
+    /**
+     * Registers a new plugin into this instance.
+     * If a plugin with the same ID exists, it issues a warning before overwriting.
+     */
+    register(plugin: PivotPlugin): void;
+    /**
+     * Unregisters a plugin.
+     */
+    unregister(id: string): void;
+    /**
+     * Retrieves a plugin by its ID.
+     */
+    get(id: string): PivotPlugin | undefined;
+    /**
+     * Retrieves all plugins of a specific type.
+     */
+    getPluginsByType(type: PivotPlugin['type']): PivotPlugin[];
+    /**
+     * Safe getter that logs a warning and returns a fallback mock if the plugin is missing.
+     * This guarantees that UI loops do not crash.
+     */
+    resolveSafe(id: string, fallbackType: 'expression' | 'summary'): Function;
+    /**
+     * Returns a snapshot of plugins that have worker code, ready for Worker Bootstrap.
+     */
+    getWorkerBootstrapPayload(): Pick<PivotPlugin, 'id' | 'type' | 'workerCode'>[];
+    /**
+     * Register a custom aggregator function (e.g., median, weighted average).
+     * Used by the engine when summaryType === 'custom' and field references this aggregator.
+     */
+    registerAggregator(id: string, aggregateFn: (values: number[]) => number, version?: string): void;
+    /**
+     * Register a custom export format plugin.
+     * The exportFunction receives the data array and an options bag with fields, layout, etc.
+     */
+    registerExporter(id: string, exportFn: (data: any[], options: any) => Promise<void>, version?: string): void;
+    /**
+     * Register a custom cell renderer plugin.
+     * Applied globally to cells matching the plugin criteria.
+     */
+    registerCellRenderer(id: string, renderFn: (value: any, displayValue: string, cellContext: any, field: any) => any, version?: string): void;
+    /**
+     * Register a custom header renderer plugin.
+     */
+    registerHeaderRenderer(id: string, renderFn: (field: any, defaultLabel: string) => any, version?: string): void;
+    /** Get all registered custom exporters. */
+    getExporters(): PivotPlugin[];
+    /** Get all registered cell renderers. */
+    getCellRenderers(): PivotPlugin[];
+    /** Get all registered aggregators. */
+    getAggregators(): PivotPlugin[];
+    /** Get all registered header renderers. */
+    getHeaderRenderers(): PivotPlugin[];
+}
+
+/** Message sent to the worker to initialize the engine with columnar data. */
+interface WorkerInitRequest {
+    action: 'init';
+    id: string;
+    rowCount: number;
+    columnarData: Record<string, {
+        type: 'int32' | 'float64';
+        buffer: ArrayBuffer;
+    }>;
+    dictionary: string[];
+    rowFields: PivotField<any>[];
+    colFields: PivotField<any>[];
+    dataFields: PivotField<any>[];
+    workerBootstrap?: {
+        id: string;
+        type: string;
+        workerCode: string;
+    }[];
+    /**
+     * Skip the initial unfiltered build. Used by the worker pipeline, where a
+     * filter request (which rebuilds) always follows init — avoids building the
+     * tries twice. compute() self-heals if no build happened yet.
+     */
+    deferBuild?: boolean;
+}
+interface WorkerFilterSpec {
+    fieldId: string;
+    filterType: 'include' | 'exclude';
+    dictIds: number[];
+}
+interface PrefilterConditionSpec {
+    fieldId: string;
+    operator: string;
+    value: string | number | boolean | null | undefined | (string | number | boolean | null | undefined)[];
+}
+interface PrefilterGroupSpec {
+    logicalOperator: 'and' | 'or';
+    conditions: (PrefilterConditionSpec | PrefilterGroupSpec)[];
+}
+interface WorkerFilterRequest {
+    action: 'filter';
+    id: string;
+    filters: WorkerFilterSpec[];
+    prefilter?: PrefilterGroupSpec;
+}
+interface WorkerComputeRequest {
+    action: 'compute';
+    id: string;
+    expandedPaths: string[];
+    expandedColPaths: string[];
+}
+/**
+ * Include/exclude filter carried INTO the incremental init pipeline as raw
+ * value strings. The worker resolves them to dictionary ids incrementally as
+ * dictionary chunks arrive (a value string that is not yet in the dictionary
+ * cannot match any row of the chunks seen so far, so per-chunk resolution is
+ * exact).
+ */
+interface WorkerInitFilterSpec {
+    fieldId: string;
+    filterType: 'include' | 'exclude';
+    valueStrings: string[];
+}
+/**
+ * Opens an incremental (chunked) init pipeline. Column buffers arrive via
+ * {@link WorkerInitChunkRequest} and are grouped/aggregated as they arrive,
+ * overlapping worker-side build with main-thread encoding. Filters are
+ * applied during the build (no separate rebuild needed afterwards). The final
+ * engine state is identical to a monolithic init + applyFilter.
+ */
+interface WorkerInitStartRequest {
+    action: 'initStart';
+    id: string;
+    rowCountTotal: number;
+    /** Column kind per field id — full-size arrays are preallocated up front. */
+    columnTypes: Record<string, 'int32' | 'float64'>;
+    /** Initial dictionary (index 0 = ''); the rest arrives via chunk appends. */
+    dictionary: string[];
+    rowFields: PivotField<any>[];
+    colFields: PivotField<any>[];
+    dataFields: PivotField<any>[];
+    filters?: WorkerInitFilterSpec[];
+    prefilter?: PrefilterGroupSpec;
+    workerBootstrap?: {
+        id: string;
+        type: string;
+        workerCode: string;
+    }[];
+}
+interface WorkerInitChunkRequest {
+    action: 'initChunk';
+    id: string;
+    start: number;
+    end: number;
+    columns: Record<string, ArrayBuffer>;
+    /** Dictionary entries appended (in order) since the previous message. */
+    dictionaryAppend?: string[];
+}
+/**
+ * Reassigns field roles (row/column/data) over the columnar data already
+ * stored in the worker — the fast path for field drag & drop. The raw data is
+ * NOT re-encoded or re-transferred; only missing columns (fields entering an
+ * area for the first time, or whose encoding definition changed) are shipped
+ * via `newColumns` together with any dictionary entries appended while
+ * encoding them.
+ */
+interface WorkerReconfigureRequest {
+    action: 'reconfigure';
+    id: string;
+    rowFields: PivotField<any>[];
+    colFields: PivotField<any>[];
+    dataFields: PivotField<any>[];
+    /** Freshly encoded columns to merge into stored columnar data. */
+    newColumns?: Record<string, {
+        type: 'int32' | 'float64';
+        buffer: ArrayBuffer;
+    }>;
+    /** Dictionary entries appended (in order) since the worker's dictionary was last synced. */
+    dictionaryAppend?: string[];
+}
+/**
+ * Flat cell matrix returned by the engine.
+ * `keys[i]` = `rowId * MAX_C + colId` hash; `sums[i * numDF + df]` = finalized aggregated value.
+ */
+interface FlatCellMatrix {
+    keys: Float64Array;
+    /** Finalized values per cell per data field (sum, avg, min, max, count, or distinct count). */
+    sums: Float64Array;
+    counts: Int32Array;
+    /** Post-processed display values after summary display modes are applied. */
+    displaySums?: Float64Array;
+}
+interface WorkerResponse {
+    id: string;
+    rowTree: PivotNode[];
+    colTree: PivotNode[];
+    cellMatrix: FlatCellMatrix;
+    rowIndexMap: Record<string, number>;
+    columnIndexMap: Record<string, number>;
+    cardinalityMap: Record<string, number>;
+    /** Monotonic version of the trie build that produced the index maps. */
+    indexMapsVersion?: number;
+    /**
+     * Wire-level flag: index/cardinality maps were omitted because they are
+     * unchanged since the previous compute response; the receiver must reuse
+     * its cached copies.
+     */
+    indexMapsOmitted?: boolean;
+    error?: string;
+    isInitComplete?: boolean;
+    isFilterComplete?: boolean;
+    isReconfigureComplete?: boolean;
+}
+/**
+ * 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).
+ * Uses {@link FastTrie} for hierarchical grouping and pre-aggregates leaf groups
+ * into flat TypedArrays supporting SUM, COUNT, AVG, MIN, MAX, and DISTINCT.
+ */
+declare class FlatPivotEngine {
+    private dictionary;
+    private rowFields;
+    private colFields;
+    private dataFields;
+    private storedColumns;
+    private storedRowCount;
+    private lastMask;
+    private isBuilt;
+    private buildState;
+    private incrementalFilters;
+    private incrementalPrefilter;
+    private rowTrie;
+    private colTrie;
+    private cardinalityMap;
+    private rowPathStrs;
+    private colPathStrs;
+    private rowIndexMapCache;
+    private columnIndexMapCache;
+    private buildVersion;
+    private groupCount;
+    private leafGroupRowIds;
+    private leafGroupColIds;
+    private leafGroupMeasures;
+    private leafGroupCounts;
+    private leafGroupMins;
+    private leafGroupMaxes;
+    private leafGroupDistinctSets;
+    init(req: WorkerInitRequest): void;
+    /**
+     * Swap field roles and regroup the already-stored columnar data under the
+     * current filter mask. Skips data encoding/transfer entirely — aggregation
+     * results are identical to a fresh init + filter with the same fields.
+     */
+    reconfigure(req: WorkerReconfigureRequest): void;
+    /**
+     * Open a chunked init: preallocate full-size columns and the build state.
+     * Filters (as raw value strings) are applied DURING the chunked build, so
+     * no separate rebuild is needed afterwards — the final state is identical
+     * to a monolithic init + applyFilter with the same inputs.
+     */
+    initStart(req: WorkerInitStartRequest): void;
+    /** Merge a column chunk, mask its rows under the init filters, and aggregate it. */
+    initChunk(req: WorkerInitChunkRequest): void;
+    /** Close the chunked init and commit the accumulated build. */
+    initEnd(): void;
+    /**
+     * Resolve pending filter value strings against dictionary entries from
+     * `fromIndex` on. A string that is not yet in the dictionary cannot match
+     * any already-processed row, so incremental resolution stays exact.
+     */
+    private resolveIncrementalFilterStrings;
+    /** applyFilter semantics over a row range, writing into lastMask. */
+    private computeMaskRange;
+    applyFilter(req: WorkerFilterRequest): void;
+    private evaluatePrefilterGroup;
+    private evaluatePrefilterCondition;
+    private buildFromMask;
+    /** Allocate the state of a build pass (full rebuild or chunked init). */
+    private beginBuild;
+    /** Cardinality bitmaps must cover the (growing) dictionary id space. */
+    private ensureCardCapacity;
+    /**
+     * Single fused pass over rows [start, end): cardinality + trie grouping +
+     * leaf aggregation. `mask` (when present) is indexed by absolute row index.
+     */
+    private processRange;
+    /** Commit the build state into the engine + rebuild per-build caches. */
+    private finalizeBuild;
+    private buildPathStrs;
+    private buildIndexMap;
+    compute(req: WorkerComputeRequest): WorkerResponse;
+}
+
+interface PivotEngineResult {
+    rowTree: PivotNode[];
+    colTree: PivotNode[];
+    cellMatrix: FlatCellMatrix;
+    rowIndexMap: Record<string, number>;
+    columnIndexMap: Record<string, number>;
+    cardinalityMap: Record<string, number>;
+}
+interface FieldDistinctEntry {
+    rawStr: string;
+    rawVal: PivotValue;
+}
+/** Set the active grid context for subsequent init/compute calls. */
+declare function setActiveEngineGrid(gridId: string): void;
+/**
+ * Release a grid's worker when the grid unmounts. Termination is deferred by
+ * a short keep-alive window: a grid that remounts quickly (rebuilds, config
+ * driven remounts, React StrictMode double mount) re-claims the worker and —
+ * when the dataset identity is unchanged — skips the entire re-encode and
+ * re-transfer of its data.
+ */
+declare function destroyEngineWorker(gridId: string): void;
+interface InitFilterState {
+    /** All fields — those carrying filterValues become include/exclude specs. */
+    fields: PivotField<any>[];
+    prefilter?: PivotPrefilter;
+}
+declare function initPivotEngineAsync<TRow>(data: TRow[], rowFields: PivotField<TRow>[], colFields: PivotField<TRow>[], dataFields: PivotField<TRow>[], registry?: PivotEngineRegistry, workerUrl?: string | URL, options?: {
+    /**
+     * Skip the same-dataset reuse fast path and re-encode unconditionally.
+     * Used by explicit refresh (refreshEngine): callers may have mutated the
+     * data array in place, so stored columns cannot be trusted.
+     */
+    forceReencode?: boolean;
+    /**
+     * Current filter state; when provided, filters are applied DURING the
+     * chunked init build (single build instead of init-build + filter-build).
+     * `filtersApplied: true` in the result means the caller can skip its
+     * follow-up filter request.
+     */
+    filterState?: InitFilterState;
+}): Promise<{
+    filtersApplied: boolean;
+}>;
+/**
+ * Fast path for field drag & drop / reorder / settings changes: reassigns
+ * field roles over the columnar data already stored in the worker instead of
+ * re-encoding and re-transferring the whole dataset. Only fields that have no
+ * matching column worker-side (entering an area for the first time, or whose
+ * encode-relevant definition changed) are encoded and shipped individually.
+ *
+ * Returns `false` when the fast path is not applicable (no initialized
+ * 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>;
+/**
+ * Send filter specs to the worker. Converts field.filterValues to
+ * dictionary-encoded integer IDs so the worker can do fast integer
+ * set lookups on columnar data instead of string comparisons.
+ */
+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;
+
+interface PivotReportState {
+    fields: PivotField<any>[];
+    layout: PivotLayoutState;
+    expandedPaths: string[];
+    expandedColPaths?: string[];
+    chartState?: Record<string, unknown>;
+}
+interface PivotReport {
+    id: string;
+    name: string;
+    createdAt: string;
+    updatedAt: string;
+    isDefault?: boolean;
+    schemaVersion?: number;
+    state: PivotReportState;
+}
+
+/**
+ * Prune row/column tree nodes that have no data cells — the shared
+ * implementation of `layout.hideEmptySummaryCells`. Used by BOTH the on-screen
+ * grid and the export pipeline so a hidden-empty configuration produces
+ * identical structure in the UI and in exported files.
+ *
+ * A row node is kept if the cell matrix contains its grand-total intersection
+ * (rowId × MAX_C); a column node is kept if it contains the column's root-row
+ * intersection (colId). Nodes missing from the index maps are kept as-is
+ * (they cannot be safely evaluated).
+ */
+declare function filterEmptySummaryTree(engineResult: PivotEngineResult): [PivotNode[], PivotNode[]];
+declare function getVisibleLeafCount(node: PivotNode, expandedColPaths: Set<string>, allExpanded?: boolean): number;
+declare function getVisibleMaxDepth(nodes: PivotNode[], expandedColPaths: Set<string>, allExpanded?: boolean): number;
+declare function getVisibleColLeaves(nodes: PivotNode[], expandedColPaths: Set<string>, allExpanded?: boolean): PivotNode[];
+interface ColHeaderCell {
+    node: PivotNode | null;
+    caption: string;
+    colSpan: number;
+    rowSpan: number;
+    isTotal: boolean;
+    fieldId?: string;
+    colPath?: string;
+    hasChildren?: boolean;
+    isExpanded?: boolean;
+}
+declare function buildColumnHeaders(colTree: PivotNode[], dataFields: PivotField[], layout: PivotLayoutState, expandedColPaths: Set<string>, allExpanded?: boolean): ColHeaderCell[][];
+/**
+ * A flattened row for rendering. Each row represents either:
+ * - A leaf data row (values at each depth level column)
+ * - A subtotal row (after a group's children end)
+ * - A grand total row
+ */
+interface FlatRow {
+    /** The node path segments (value at each depth) */
+    pathValues: (string | null)[];
+    /** Which depth level this row "belongs to" (for expand/collapse) */
+    depth: number;
+    /** The full key/path hash for this node */
+    key: string;
+    /** Whether this is a subtotal row */
+    isSubtotal: boolean;
+    /** Whether this row's group has children that can be expanded */
+    hasChildren: boolean;
+    /** Whether this row's group is currently expanded */
+    isExpanded: boolean;
+    /** The actual PivotNode reference (the deepest node for this row) */
+    node: PivotNode;
+    /** rowSpan hints: for tabular layout, parent cells that span multiple rows */
+    rowSpans: number[];
+    /** Whether this is the first row of its parent group (used for rowSpan rendering) */
+    isFirstInGroup: boolean[];
+}
+declare function flattenRowTree(nodes: PivotNode[], expandedPaths: Set<string>, allExpanded: boolean): PivotNode[];
+/**
+ * Flatten the row tree for spreadsheet-style tabular rendering.
+ *
+ * In this layout:
+ * - Each row field gets its own column
+ * - Parent group values appear in their respective columns
+ * - When a group is expanded, children appear below with their values
+ *   in the NEXT column to the right
+ * - Subtotal rows appear after each group's children (if showRowTotals is true)
+ * - Parent cells span multiple rows (rowSpan) to avoid repetition
+ */
+declare function flattenRowTreeTabular(nodes: PivotNode[], expandedPaths: Set<string>, allExpanded: boolean, maxDepth: number, showRowTotals: boolean, totalsPosition: 'top' | 'bottom'): FlatRow[];
+/**
+ * Flatten the row tree for compact tree rendering.
+ * In this layout:
+ * - All row headers share a single column (spanning maxDepth).
+ * - Each node is its own row.
+ * - Indentation is used to show hierarchy.
+ */
+declare function flattenRowTreeTree(nodes: PivotNode[], expandedPaths: Set<string>, allExpanded: boolean, treeDepth: number, showRowTotals: boolean, totalsPosition: 'top' | 'bottom'): FlatRow[];
+
+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 {
+    /** Apply prefilter to raw data before export. */
+    applyFilters?: boolean;
+    /** Custom file name (without extension). */
+    fileName?: string;
+    /** Expand all nodes before export regardless of current state. */
+    expandAll?: boolean;
+    /** AbortSignal for cancellation support. */
+    signal?: AbortSignal;
+    /** Progress callback: 0–100. */
+    onProgress?: (percent: number) => void;
+    /** Include hidden/chooser fields in list export. */
+    includeHiddenFields?: boolean;
+    /** Locale for formatting. */
+    locale?: string;
+}
+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>;
+declare function escapeXmlText(value: string): string;
+declare function getCellVal(engineResult: PivotEngineResult, rHash: string, cHash: string, dfId: string, dataFields: PivotField[], cellLookup: Map<number, number>, preferDisplay?: boolean): number | "";
+/** Per-cell style resolved from a data field's conditional-formatting rules. */
+interface ExportCellStyle {
+    fillColor?: string;
+    textColor?: string;
+    bold?: boolean;
+}
+/** Parse a CSS color (#rgb, #rrggbb, rgb(...)) into an [r,g,b] tuple, or null. */
+declare function cssColorToRgb(color: string | undefined): [number, number, number] | null;
+/** Build cellLookup Map from engine result — shared across export functions. */
+declare function buildCellLookup(engineResult: PivotEngineResult): Map<number, number>;
+/** Build column paths list from visible column leaves and data fields. */
+declare function buildColPathsList(engineResult: PivotEngineResult, dataFields: PivotField[], layout: PivotLayoutState, expandedColPaths: Set<string>, allExpanded: boolean): string[][];
+/**
+ * Format a date-typed row/column header value exactly as the on-screen grid
+ * does (`DateFormatter.format(value, 'grid', …)`), honoring the field's
+ * groupInterval. Non-date fields and total/blank cells pass through unchanged.
+ */
+declare function formatHeaderValue(value: any, field: PivotField | undefined, locale: string): any;
+/**
+ * Flatten row nodes for export, honoring `rowHeaderLayout`. In `tree` mode all
+ * row fields collapse into a single indented column (matching the grid's tree
+ * renderer); otherwise each row field gets its own column (tabular). Returns
+ * the flat rows plus the effective row-header column count.
+ */
+declare function flattenExportRows(engineResult: PivotEngineResult, rowFields: PivotField[], layout: PivotLayoutState, expandedPaths: Set<string>, allExpanded: boolean): {
+    flatRows: FlatRow[];
+    treeMode: boolean;
+    rowLabelCols: number;
+};
+/**
+ * Produce the row-header label cell(s) for one flat row. Tree mode returns a
+ * 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[];
+/** Find the data field for a given column path entry. */
+declare function resolveColPath(cPathInfo: string[], dataFields: PivotField[]): {
+    cHash: string;
+    dfId: string;
+};
+/**
+ * Build the array-of-arrays used by the PDF/Print/Clipboard exporters.
+ *
+ * Async + cancellable: the (potentially large) data-row loop yields to the
+ * 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<{
+    aoa: any[][];
+    styles: (ExportCellStyle | null)[][] | null;
+} | null>;
+
+/** 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. */
+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';
+/** Union of all value types a pivot cell, node, or filter can hold. */
+type PivotValue = string | number | boolean | Date | null | undefined;
+/** Comparison operators for filter conditions. */
+type FilterOperator = '=' | '<>' | '>' | '>=' | '<' | '<=' | 'contains' | 'notcontains' | 'startswith' | 'endswith' | 'in' | 'notin' | 'isnull' | 'isnotnull';
+/** A single filter predicate targeting one field. */
+interface FilterCondition {
+    fieldId: string;
+    operator: FilterOperator;
+    value?: PivotValue | PivotValue[];
+}
+/** Composable filter tree — conditions joined by AND/OR, nestable. */
+interface FilterGroup {
+    logicalOperator: 'and' | 'or';
+    conditions: (FilterCondition | FilterGroup)[];
+}
+/** Top-level prefilter applied before pivot computation. */
+type PivotPrefilter = FilterGroup;
+interface PivotDictionary {
+    ok: string;
+    cancel: string;
+    apply: string;
+    close: string;
+    search: string;
+    selectAll: string;
+    clearAll: string;
+    show: string;
+    hide: string;
+    filterArea: string;
+    columnArea: string;
+    rowArea: string;
+    dataArea: string;
+    footerArea: string;
+    allFields: string;
+    dropHere: string;
+    actions: string;
+    saveNewView: string;
+    saveAsView: string;
+    saveChanges: string;
+    savedViews: string;
+    viewOptions: string;
+    viewsAndReports: string;
+    views: string;
+    saveChangesOverwrite: string;
+    saveAsCopy: string;
+    makeDefault: string;
+    deleteReport: string;
+    deleteReportConfirm: string;
+    export: string;
+    importFile: string;
+    excelExport: string;
+    pivotView: string;
+    listView: string;
+    preservesGridLayout: string;
+    rawFlatData: string;
+    document: string;
+    pdfDocument: string;
+    printReadyLayout: string;
+    fullSnapshot: string;
+    saveSessionState: string;
+    rawDataFormats: string;
+    customExports: string;
+    customPlugin: string;
+    importSuccess: string;
+    importWarning: string;
+    importError: string;
+    initializing: string;
+    emptyData: string;
+    noItems: string;
+    blanks: string;
+    loadingData: string;
+    processing: string;
+    fieldSettings: string;
+    caption: string;
+    summaryType: string;
+    displayMode: string;
+    groupInterval: string;
+    sum: string;
+    count: string;
+    avg: string;
+    min: string;
+    max: string;
+    grandTotal: string;
+    subTotal: string;
+    absoluteValue: string;
+    runningTotal: string;
+    difference: string;
+    percentOfTotal: string;
+    none: string;
+    year: string;
+    quarter: string;
+    month: string;
+    day: string;
+    and: string;
+    or: string;
+    noConditionsAdded: string;
+    calculatedMeasureDesigner: string;
+    createFormulasWithoutCode: string;
+    measureName: string;
+    format: string;
+    numericStandard: string;
+    numericDecimal: string;
+    currencyTRY: string;
+    currencyUSD: string;
+    percent: string;
+    expand: string;
+    collapse: string;
+    expandAll: string;
+    collapseAll: string;
+    sortByThisColumn: string;
+    sortFieldByThisColumn: string;
+    removeAllSorting: string;
+    sortAsc: string;
+    sortDesc: string;
+    clearSort: string;
+    order: string;
+    moveToStart: string;
+    moveToEnd: string;
+    moveToLeft: string;
+    moveToRight: string;
+    showFieldList: string;
+    editCalculation: string;
+    [key: string]: string;
+}
+/** CSS custom-property overrides for theming the pivot grid. */
+interface PivotTheme {
+    id?: string;
+    name?: string;
+    background?: string;
+    surface?: string;
+    surfaceHover?: string;
+    surfaceHeader?: string;
+    border?: string;
+    text?: string;
+    textMuted?: string;
+    textHeader?: string;
+    primary?: string;
+    primaryForeground?: string;
+    success?: string;
+    danger?: string;
+    warning?: string;
+    info?: string;
+    totalBackground?: string;
+    stripeBackground?: string;
+    groupBorder?: string;
+    iconActive?: string;
+}
+interface CustomSummaryOptions {
+    summaryProcess: 'start' | 'calculate' | 'finalize';
+    value: number | null;
+    totalValue: number | null;
+}
+interface PivotConditionRule<TStyle = any> {
+    type: 'colorScale' | 'dataBar' | 'iconSet' | 'expression';
+    formula?: (value: number, cellContext: PivotCell) => boolean;
+    style: TStyle;
+}
+type PivotCellTemplate = (props: {
+    value: PivotValue;
+    displayValue: string;
+    cell?: PivotCell;
+    field: PivotField;
+}) => any;
+/**
+ * Describes a single field (dimension or measure) in the pivot grid.
+ *
+ * @typeParam TRow - Shape of source data rows.
+ * @typeParam TCellTemplate - Custom cell render function type.
+ * @typeParam TStyle - Style object type for conditional formatting rules.
+ */
+interface PivotField<TRow = any, TCellTemplate = PivotCellTemplate, TStyle = any> {
+    /** Unique identifier for this field. */
+    id: string;
+    /** Source property name in the data row. */
+    dataField?: Extract<keyof TRow, string> | string;
+    /** Display label shown in headers and field chooser. */
+    caption: string;
+    /** Data type used for encoding, formatting, and grouping. */
+    dataType: 'string' | 'number' | 'date' | 'boolean';
+    /** Which pivot area this field belongs to. */
+    area?: PivotArea;
+    /** Position index within the area. */
+    areaIndex?: number;
+    /** Whether the field is visible in the field chooser. */
+    visible?: boolean;
+    /** Aggregation type — computed in the Web Worker for all types. */
+    summaryType?: PivotSummaryType;
+    /** Post-aggregation display transformation (e.g. percent of total). */
+    summaryDisplayMode?: PivotSummaryDisplayMode;
+    calculateCustomSummary?: string | ((options: CustomSummaryOptions) => void);
+    /** True for calculated (virtual) fields that derive from other fields. */
+    isCalculated?: boolean;
+    formulaString?: string;
+    formulaType?: 'row' | 'summary';
+    /** Row-level expression evaluated via CSP-safe engine. */
+    calculateExpression?: string | ((row: TRow) => number | string);
+    /** Summary-level expression combining other data field values. */
+    calculateSummaryExpression?: string | ((cellValues: Record<string, number>) => number);
+    /** Intl format options or custom formatter for cell display values. */
+    format?: Intl.NumberFormatOptions | Intl.DateTimeFormatOptions | ((value: number) => string);
+    /** Conditional formatting rules evaluated per cell. */
+    conditionalFormatting?: PivotConditionRule<TStyle>[];
+    /** Custom cell render function. */
+    cellTemplate?: TCellTemplate;
+    /** Date/numeric grouping interval. */
+    groupInterval?: PivotGroupInterval | number;
+    /** Active filter values for header filter (include/exclude mode). */
+    filterValues?: Set<any>;
+    /** Whether filterValues is an include list or exclude list. */
+    filterType?: 'include' | 'exclude';
+    /** Sort direction for this field's header values. */
+    sortOrder?: 'asc' | 'desc';
+    /** Data field ID to sort rows by summary value. */
+    sortBySummaryField?: string;
+    /** Column path key for sort-by-summary targeting. */
+    sortBySummaryPath?: string;
+    /** Custom sort comparator for header values. */
+    calculateCustomSort?: (a: any, b: any, cellA?: PivotCell, cellB?: PivotCell) => number;
+    /** Show only top N values; requires sortBySummaryField. */
+    topN?: number;
+    /** Whether to aggregate remaining values into an "Others" row. */
+    topNShowOthers?: boolean;
+    /** Custom caption for the "Others" row when topN is active. */
+    topNOthersCaption?: string;
+}
+/** Controls pivot grid layout, totals visibility, and structural options. */
+interface PivotLayoutState {
+    showColumnGrandTotals?: boolean;
+    showRowGrandTotals?: boolean;
+    showColumnTotals?: boolean;
+    showRowTotals?: boolean;
+    /** Whether subtotals appear above or below their groups. */
+    totalsPosition?: 'top' | 'bottom';
+    showGrandTotals?: 'rows' | 'columns' | 'both' | 'none';
+    showSubTotals?: 'rows' | 'columns' | 'both' | 'none';
+    totalsDisplayMode?: 'top' | 'bottom';
+    /** Row header style: 'tabular' gives one column per row field, 'tree' nests all into one column. */
+    rowHeaderLayout?: 'tabular' | 'tree';
+    /** Hide rows/columns that have no data. */
+    hideEmptySummaryCells?: boolean;
+    /** Place data field labels in row headers or column headers. */
+    dataFieldPosition?: 'rows' | 'columns';
+    /** Server-side or computed prefilter applied before aggregation. */
+    prefilter?: PivotPrefilter;
+    showFooter?: boolean;
+    showFilterArea?: boolean;
+    /** Chart integration type when rendering in chart mode. */
+    chartType?: string;
+}
+interface PivotLayoutProfile {
+    id: string;
+    name: string;
+    fields: PivotField[];
+    layout: PivotLayoutState;
+    isDefault: boolean;
+}
+interface PivotStateStoringConfig {
+    enabled: boolean;
+    type?: 'localStorage' | 'sessionStorage' | 'custom';
+    storageKey?: string;
+    onSave?: (state: any) => void;
+    onLoad?: () => any;
+}
+interface PivotToolbarConfig {
+    showSaveReport?: boolean;
+    showImportFile?: boolean;
+    showExportButton?: boolean;
+    showCalculatedFields?: boolean;
+    showFullscreenToggle?: boolean;
+    showFieldChooserToggle?: boolean;
+    showExpandCollapseAll?: boolean;
+    showRefreshButton?: boolean;
+}
+/** A node in the row or column tree hierarchy returned by the engine. */
+interface PivotNode {
+    key: string;
+    value: PivotValue;
+    fieldId: string;
+    children: PivotNode[];
+    isExpanded: boolean;
+    isTotal: boolean;
+    depth: number;
+    hasChildren?: boolean;
+}
+/** Represents a single cell at the intersection of a row path and column path. */
+interface PivotCell<TRow = any> {
+    rowPath: string[];
+    colPath: string[];
+    values: Record<string, number>;
+    displayValues: Record<string, string>;
+    records?: TRow[];
+    isTotalCell: boolean;
+}
+/** Minimal data source shape: field definitions + row array. */
+interface PivotDataSource<TRow = any> {
+    fields: PivotField<TRow>[];
+    store: TRow[];
+}
+/** Fired when a user clicks a data cell, header, or total. */
+interface CellClickEvent<TRow = any, TNativeEvent = unknown> {
+    event: TNativeEvent;
+    cellType: 'data' | 'rowHeader' | 'colHeader' | 'grandTotal';
+    value?: number;
+    rowPath: string[];
+    colPath: string[];
+    records?: TRow[];
+}
+interface FieldMoveEvent {
+    fieldId: string;
+    sourceArea: string;
+    targetArea: string;
+    newIndex: number;
+    cancel: () => void;
+    isCanceled: boolean;
+}
+/** Fired before each cell renders — mutate `cellConfig` to customize appearance. */
+interface CellPreparedEvent<TRow = any, TNode = unknown, TStyle = unknown> {
+    area: 'row' | 'column' | 'data';
+    cell: PivotCell<TRow> | null;
+    rowIndex: number;
+    columnIndex: number;
+    cellConfig: {
+        text?: TNode;
+        style?: TStyle;
+        className?: string;
+    };
+}
+interface ExportingEvent {
+    format: string;
+    cancel: boolean;
+}
+interface PivotSelectionStats {
+    count: number;
+    sum: number;
+    avg: number;
+    min: number;
+    max: number;
+}
+type PivotSelectionMode = 'row' | 'data';
+interface PivotSelectionRange {
+    startRow: number;
+    startColumn: number;
+    endRow: number;
+    endColumn: number;
+}
+interface PivotSelectionState {
+    range: PivotSelectionRange;
+    isSelecting: boolean;
+    mode: PivotSelectionMode;
+}
+type PivotCellValueAccessor = (row: number, column: number) => number | null | undefined;
+type PivotCellTextAccessor = (row: number, column: number) => string;
+interface PivotImportStatus {
+    isOpen: boolean;
+    status: 'loading' | 'success' | 'error' | 'warning';
+    title: string;
+    messages: string[];
+    /** Overall parse progress 0..100 (present only while streaming a large file). */
+    progress?: number;
+    /** Coarse pipeline stage label (reading | parsing | typing | finalizing). */
+    phase?: string;
+    /** Whether the in-flight import can be cancelled by the user. */
+    cancellable?: boolean;
+}
+/** One detected column in the import preview / column-mapping step. */
+interface PivotImportField {
+    /** Source data key. */
+    dataField: string;
+    /** Display caption (editable in the mapping UI). */
+    caption: string;
+    /** Detected data type (editable in the mapping UI). */
+    dataType: 'string' | 'number' | 'date' | 'boolean';
+}
+/**
+ * Parsed-but-not-yet-committed import awaiting user review (preview + column
+ * mapping). Held in observable state; the full row set is kept privately by the
+ * controller and applied on commit.
+ */
+interface PivotImportPreviewState {
+    fields: PivotImportField[];
+    /** First-N rows for the preview table. */
+    sample: Record<string, unknown>[];
+    /** Total parsed row count. */
+    rowCount: number;
+    warnings: string[];
+}
+type DropIntent = 'before' | 'after' | 'append' | null;
+interface PivotDragIntentState {
+    activeId: string | null;
+    targetId: string | null;
+    targetArea: string | null;
+    intent: DropIntent;
+}
+/** Full observable state of the pivot controller — consumed by UI frameworks. */
+interface PivotControllerState<TRow = any> {
+    gridId: string;
+    fields: PivotField<TRow>[];
+    layout: PivotLayoutState;
+    expandedPaths: Set<string>;
+    expandedColPaths: Set<string>;
+    columnWidths: Record<string, number>;
+    engineResult: PivotEngineResult | null;
+    isBuilding: boolean;
+    /** Monotonic engine build progress shown by UI loaders. 0..100, simulated when exact worker progress is unavailable. */
+    buildProgress?: number;
+    engineError: Error | null;
+    selectionStats: PivotSelectionStats | null;
+    reports: PivotReport[];
+    activeReportId: string | null;
+    importStatus: PivotImportStatus;
+    /** Pending import awaiting preview/column-mapping review (null when none). */
+    importPreview: PivotImportPreviewState | null;
+    drag: PivotDragIntentState;
+}
+interface PivotControllerCallbacks<TRow = any> {
+    onRefresh?: () => void;
+    onImportData?: (data: TRow[]) => void;
+    onFieldsChange?: (fields: PivotField<TRow>[]) => void;
+    onLayoutChange?: (layout: PivotLayoutState) => void;
+    onFieldMove?: (e: FieldMoveEvent) => void | Promise<void>;
+    onBeforePivotCalculate?: () => void;
+    onAfterPivotCalculate?: (result: PivotEngineResult) => void;
+    onExporting?: (e: ExportingEvent) => void;
+    onError?: (error: Error) => void;
+    onChartStateLoaded?: (chartState: any) => void;
+}
+/** Options for initializing a {@link PivotController}. */
+interface PivotControllerOptions<TRow = any> extends PivotControllerCallbacks<TRow> {
+    gridId: string;
+    data: TRow[];
+    initialFields: PivotField<TRow>[];
+    controlledFields?: PivotField<TRow>[];
+    controlledLayout?: PivotLayoutState;
+    chartIntegrationOptions?: Record<string, any>;
+    registry?: PivotEngineRegistry;
+    locale?: string;
+    workerUrl?: string | URL;
+    /**
+     * When true, file/URL/paste imports first open a preview + column-mapping
+     * step instead of applying immediately. Defaults to false (apply directly).
+     */
+    previewImport?: boolean;
+}
+/** Imperative API handle exposed via React ref or Angular adapter. */
+interface PivotGridRef {
+    exportData: (format: ExportFormat | string, options?: ExportOptions) => void;
+    expandAll: () => void;
+    collapseAll: () => void;
+    getState: () => PivotControllerState;
+    setFields: (fields: PivotField[]) => void;
+    refreshEngine: () => void;
+    getRawData: () => unknown[];
+    getEngineResult: () => PivotEngineResult | null;
+    getCell: (rowPath: string[], colPath: string[]) => PivotCell | null;
+}
+declare const defaultPivotLayout: PivotLayoutState;
+
+export { type PrefilterConditionSpec as $, type FieldDistinctEntry as A, type FilterCondition as B, type CellClickEvent as C, type DropIntent as D, type ExportingEvent as E, type FieldMoveEvent as F, type FilterGroup as G, type FilterOperator as H, type FlatCellMatrix as I, FlatPivotEngine as J, type FlatRow as K, type PivotCellTemplate as L, type PivotControllerCallbacks as M, type PivotDataSource as N, type PivotGridRef as O, type PivotField as P, type PivotGroupInterval as Q, type PivotImportPreviewState as R, type PivotLayoutProfile as S, type PivotLocale as T, type PivotPlugin as U, type PivotSelectionRange as V, type PivotStateStoringConfig as W, type PivotSummaryDisplayMode as X, type PivotSummaryType as Y, type PivotTheme as Z, type PivotToolbarConfig as _, type PivotControllerState as a, type PrefilterGroupSpec as a0, type WorkerComputeRequest as a1, type WorkerFilterRequest as a2, type WorkerFilterSpec as a3, type WorkerInitRequest as a4, type WorkerResponse as a5, buildCellLookup as a6, buildColPathsList as a7, buildColumnHeaders as a8, buildPivotAOA as a9, buildRowLabelCells as aa, computePivotMatrixAsync as ab, cssColorToRgb as ac, defaultPivotLayout as ad, destroyEngineWorker as ae, escapeXmlText as af, exportPivotData as ag, filterEmptySummaryTree as ah, filterPivotEngineAsync as ai, flattenExportRows as aj, flattenRowTree as ak, flattenRowTreeTabular as al, flattenRowTreeTree as am, formatHeaderValue as an, getCellVal as ao, getFieldDistinctValues as ap, getVisibleColLeaves as aq, getVisibleLeafCount as ar, getVisibleMaxDepth as as, initPivotEngineAsync as at, reconfigurePivotEngineAsync as au, resolveColPath as av, setActiveEngineGrid as aw, type WorkerReconfigureRequest as ax, type PivotLayoutState as b, type PivotSelectionStats as c, type PivotImportStatus as d, type PivotControllerOptions as e, type PivotEngineResult as f, type PivotArea as g, type PivotImportField as h, type ExportFormat as i, type ExportOptions as j, type PivotCell as k, type PivotDragIntentState as l, type PivotReport as m, type PivotReportState as n, type PivotSelectionMode as o, type PivotSelectionState as p, type PivotCellValueAccessor as q, type PivotCellTextAccessor as r, type PivotPrefilter as s, type PivotNode as t, PivotEngineRegistry as u, type PivotValue as v, type PivotConditionRule as w, type PivotDictionary as x, type CellPreparedEvent as y, type CustomSummaryOptions as z };