@kanunilabs/pivotgrid-core 1.8.0 → 1.9.0

package/dist/index.d.cts

@@ -320,6 +320,35 @@ declare function percentAxisTicks(min: number): number[];
  * nearer the axis.
  */
 declare function stackSeries(series: ReadonlyArray<ArrayLike<number>>, mode: Exclude<ChartStacking, 'grouped'>, include?: (index: number) => boolean): Array<StackedSegment | null>;
+/**
+ * `count` colours derived from `accent`, index-stable.
+ *
+ * Falls back to the packaged eight when the accent cannot be read — an unthemed
+ * grid, or a custom theme whose `--dg-primary` is something this cannot parse
+ * (a named colour, `color-mix()`, `oklch()`). Falling back is deliberate: a
+ * chart with the wrong-but-readable palette beats a chart of black shapes.
+ *
+ * A near-grey accent also falls back. Rotating the hue of something with almost
+ * no saturation produces eight indistinguishable greys, which is worse than an
+ * off-theme palette that can actually be told apart.
+ */
+declare function chartPalette(accent: string | null | undefined, count: number): string[];
+/** The series palettes a chart offers by name. */
+type ChartPaletteName = 'theme' | 'classic' | 'colorblind' | 'vivid' | 'monochrome';
+declare const CHART_PALETTE_NAMES: readonly ChartPaletteName[];
+/**
+ * The series colours for a chart, `count` long and index-stable.
+ *
+ * @param choice  the chart format's `palette` and `colors` (both optional)
+ * @param accent  the grid's accent, as read from its tokens (`theme` derives from it)
+ * @param surface the chart's background, as read from its tokens — the floor
+ *                named palettes keep their contrast against; without it they
+ *                are used as listed
+ */
+declare function resolveChartPalette(choice: {
+    palette?: ChartPaletteName;
+    colors?: readonly string[];
+} | null | undefined, accent: string | null | undefined, surface: string | null | undefined, count: number): string[];
 
 /** Where the legend sits around the plot, or `'none'` to hide it. */
 type ChartLegendPosition = 'top' | 'bottom' | 'left' | 'right' | 'none';
@@ -378,6 +407,19 @@ interface ChartFormat {
      * browser. Absent: the grouping's own labels ("2026-03", "2026-Q1").
      */
     dateFormat?: ChartDateFormat;
+    /**
+     * Series colours by name (rival analysis, charts §E.4 #54): `'theme'` (the
+     * default — derived from the grid's accent), `'classic'`, `'colorblind'`,
+     * `'vivid'` or `'monochrome'`. Named palettes keep 3:1 contrast against the
+     * chart background.
+     */
+    palette?: ChartPaletteName;
+    /**
+     * The app's own series colours, as `#rgb` / `#rrggbb`, used in order and
+     * repeated — they win over `palette`. Set it through `defaultFormat` to give
+     * every chart a brand palette.
+     */
+    colors?: string[];
 }
 /**
  * The date presets an axis offers. Each is an `Intl.DateTimeFormat` shape, so
@@ -420,19 +462,6 @@ interface ChartImageRequest {
     /** Background colour; `null` keeps transparency (not for JPEG). Default white. */
     background?: string | null;
 }
-/**
- * `count` colours derived from `accent`, index-stable.
- *
- * Falls back to the packaged eight when the accent cannot be read — an unthemed
- * grid, or a custom theme whose `--dg-primary` is something this cannot parse
- * (a named colour, `color-mix()`, `oklch()`). Falling back is deliberate: a
- * chart with the wrong-but-readable palette beats a chart of black shapes.
- *
- * A near-grey accent also falls back. Rotating the hue of something with almost
- * no saturation produces eight indistinguishable greys, which is worse than an
- * off-theme palette that can actually be told apart.
- */
-declare function chartPalette(accent: string | null | undefined, count: number): string[];
 
 interface WaterfallStep {
     /** Running total before and after this step. */
@@ -1344,6 +1373,20 @@ declare function resolveColumnWidthDefaults(defaults?: PivotColumnWidthDefaults)
     rowHeader: number;
     data: number;
 };
+/**
+ * The body row height a `density` paints at — the number BOTH renderers'
+ * virtualizers run on (window, spacers, keyboard scroll). The stylesheet's
+ * `kanuni-pivot-density-*` rules set the matching cell line heights; the two
+ * must agree or the frozen row headers drift away from the data rows. Anything
+ * but `compact` / `comfortable` (unset, `normal`, a typo from plain JS) is the
+ * historical 28px.
+ */
+declare function pivotRowHeight(density?: PivotDensity): number;
+/**
+ * The class a density puts on the grid root (and its popups' hosts). `normal`
+ * and unset add nothing, so a grid without `density` keeps its exact markup.
+ */
+declare function pivotDensityClass(density?: PivotDensity): string;
 declare const ROW_HEADER_MIN_DATA_STRIP = 160;
 declare const ROW_HEADER_MAX_PINNED_FRACTION = 0.6;
 /** However tight it gets, a row-header column stays wide enough to read. */
@@ -1701,11 +1744,21 @@ interface PivotTheme {
     background?: string;
     surface?: string;
     surfaceHover?: string;
+    /** Panels (filter area, field areas, footer, dialog headers) — and the column-header band unless `headerBackground` is set. */
     surfaceHeader?: string;
     border?: string;
     text?: string;
     textMuted?: string;
+    /** Header text — on the panels, and on the column-header band unless `headerText` is set. */
     textHeader?: string;
+    /**
+     * The column-header band alone, apart from the panels: an ink band over light
+     * panels (`headerBackground: '#1e293b', headerText: '#f8fafc'`). Unset, the
+     * band follows `surfaceHeader` / `textHeader` as it always has.
+     */
+    headerBackground?: string;
+    /** Text on the column-header band; see `headerBackground`. */
+    headerText?: string;
     primary?: string;
     primaryForeground?: string;
     success?: string;
@@ -1717,6 +1770,12 @@ interface PivotTheme {
     groupBorder?: string;
     iconActive?: string;
 }
+/**
+ * Row rhythm of the grid: `compact` 24px body rows, `normal` 28px (the
+ * default, and what an unset value means), `comfortable` 36px. Independent of
+ * the colours (`theme`).
+ */
+type PivotDensity = 'compact' | 'normal' | 'comfortable';
 interface CustomSummaryOptions {
     summaryProcess: 'start' | 'calculate' | 'finalize';
     value: number | null;
@@ -2581,7 +2640,18 @@ declare class PivotController<TRow> {
     getRawData(): TRow[];
     getEngineResult(): PivotEngineResult | null;
     getCell(rowPath: string[], colPath: string[]): PivotCell | null;
+    /**
+     * The click event with the source rows behind the cell as `records`.
+     *
+     * Resolved on first READ, not on the click (6d-16): the rows are found by a
+     * scan of the whole dataset on the main thread, 0.3-0.5 s per click on a
+     * million rows, and a click handler that never reads them paid it anyway.
+     * The scan matches the cell's path first and runs the filters only on the
+     * rows that matched — every filter judges one row at a time, so the order
+     * does not change the result, and a cell is usually a sliver of the data.
+     */
     resolveCellClick(event: CellClickEvent<TRow>): CellClickEvent<TRow>;
+    private recordsAt;
     getAreaFields(area: PivotArea): PivotField<TRow>[];
     private cellIndexLookups;
     private getCellIndexLookup;
@@ -2887,6 +2957,49 @@ declare function sortPivotTree(nodes: PivotNode[], fields: PivotField<any>[], en
  */
 declare function collatorFor(locale?: string, numeric?: boolean): Intl.Collator;
 
+/** One row of the popup's list: the value as text (the row's key) and as stored. */
+interface HeaderFilterOption {
+    rawStr: string;
+    rawVal: unknown;
+}
+/** The part of a field the popup reads. */
+interface HeaderFilterState {
+    filterValues?: Set<unknown>;
+    filterType?: 'include' | 'exclude';
+}
+/** What OK writes back. */
+type HeaderFilterWrite = {
+    kind: 'keep';
+} | {
+    kind: 'clear';
+} | {
+    kind: 'apply';
+    values: Set<unknown>;
+    filterType: 'include' | 'exclude';
+};
+/** The `rawStr` of every option the report shows now — the boxes to tick on open. */
+declare function headerFilterShown(options: readonly HeaderFilterOption[], field: HeaderFilterState): Set<string>;
+/**
+ * The write that makes the shown set exactly the ticked set.
+ *
+ * - Nothing changed → `keep`: OK without touching anything must leave the
+ *   filter as it was, including values no current row holds (a live update
+ *   may still bring them).
+ * - Nothing ticked → `keep`: an empty list cannot be expressed (an empty
+ *   `filterValues` means "no filter"), so the popup disables OK instead.
+ * - All ticked → `clear`.
+ * - A field that already has a filter keeps its mode: exclude lists the
+ *   unticked values, include the ticked ones.
+ * - A field with no filter yet gets whichever list is SHORTER — exclude when
+ *   fewer values are unticked than ticked, include otherwise (ties: include).
+ *   Unticking three fee rows out of thousands of products stores three
+ *   values, not thousands.
+ *
+ * Each listed option contributes its `rawStr` and its `rawVal`, as the popup
+ * always wrote (a number field stores both `'10'` and `10`).
+ */
+declare function headerFilterWrite(options: readonly HeaderFilterOption[], ticked: ReadonlySet<string>, field: HeaderFilterState): HeaderFilterWrite;
+
 declare function executePostAggregationPhase<TRow>(engineResult: PivotEngineResult, dataFields: PivotField<TRow>[], registry?: PivotEngineRegistry): void;
 declare function executeSummaryDisplayModesPhase<TRow>(engineResult: PivotEngineResult, dataFields: PivotField<TRow>[]): void;
 
@@ -3514,4 +3627,4 @@ declare function rollupInMemory<TRow>(rows: readonly TRow[], request: PivotServe
 /** Every value of a field in rows held in memory — the reference `loadFieldValues`. */
 declare function fieldValuesInMemory<TRow>(rows: readonly TRow[], field: PivotServerField): unknown[];
 
-export { type AdvancedExportRequest, type AdvancedExporter, CHART_LEGEND_POSITIONS, type CalculatedFieldTextKey, type CellClickEvent, type CellPreparedEvent, type CellType, type ChartCategoryKeyAction, type ChartFont, type ChartFormat, type ChartGridLines, type ChartImageRequest, type ChartKeyTextKey, type ChartLabelAngle, type ChartLegendPosition, type ChartMark, type ChartStacking, type ChartStyle, type ChartStyleDefaults, type ColHeaderCell, type ColumnSlot, type ColumnSlotOptions, type ConditionalVisual, type CsvParseProgress, CsvReader, type CustomSummaryOptions, DEFAULT_DATA_COLUMN_WIDTH, DEFAULT_ROW_HEADER_WIDTH, DataNormalizer, type DateFormatContext, DateFormatter, type DateGranularity, type DimensionFieldInfo, type DrillDownTextKey, 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 FloatingFrame, type FrameRect, type FrameSize, type FunnelStage, type HistogramBin, type IFileReader, type ImportFormat, ImportManager, type ImportManagerOptions, type ImportProgress, type ImportResult, type ImportSnapshot, ImportStreamController, type ImportWorkerKind, type ImportWorkerResult, MAX_C, type MarkTone, PIVOT_AI_FEATURES, type ParseFileOptions, type PivotAiApplyResult, type PivotAiCondition, type PivotAiFeature, type PivotAiFieldOptions, type PivotAiFilter, type PivotAiOptions, type PivotAiSort, type PivotAiState, type PivotAiTotals, type PivotAiValue, type PivotArea, type PivotCell, PivotCellAggregator, type PivotCellTemplate, type PivotCellTextAccessor, type PivotCellValueAccessor, type PivotChartChange, type PivotChartChangedEvent, type PivotChartClosedEvent, type PivotChartOpenedEvent, type PivotChartReportPart, type PivotChartState, type PivotChartWindowState, type PivotColumnWidthDefaults, type PivotConditionRule, PivotController, type PivotControllerCallbacks, type PivotControllerEvents, type PivotControllerOptions, type PivotControllerState, type PivotDataSource, type PivotDictionary, type PivotDragIntentState, PivotEngineRegistry, type PivotEngineResult, PivotEngineService, type PivotEngineServiceConfig, PivotEventEmitter, type PivotEventHandler, type PivotEventMap, PivotExportService, type PivotField, PivotFieldService, type PivotGridRef, type PivotGroupInterval, type PivotImportField, type PivotImportLabels, type PivotImportPreviewState, type PivotImportStatus, type PivotLabelFilter, type PivotLayoutProfile, type PivotLayoutState, type PivotLocale, type PivotNode, type PivotPlugin, type PivotPrefilter, type PivotReport, PivotReportManager, PivotReportService, type PivotReportState, type PivotRowKey, type PivotRowKeyResolver, type PivotRowSparkline, type PivotRowTransaction, type PivotSelectionMode, PivotSelectionModel, type PivotSelectionRange, type PivotSelectionState, type PivotSelectionStats, type PivotServerCell, type PivotServerField, type PivotServerInput, type PivotServerRequest, type PivotServerResponse, type PivotServerSource, type PivotServerSourceOptions, type PivotServerValue, type PivotStateListener, PivotStateStore, type PivotStateStoringConfig, type PivotSummaryDisplayMode, type PivotSummaryType, type PivotTheme, type PivotToolbarConfig, type PivotTransactionResult, type PivotValue, type PivotValueFilter, type PrefilterConditionSpec, type PrefilterGroupSpec, type ProcessFileStreamingOptions, type ProcessFromUrlOptions, ROW_HEADER_MAX_PINNED_FRACTION, ROW_HEADER_MIN_COL_WIDTH, ROW_HEADER_MIN_DATA_STRIP, type ReportStatePart, type RowHeaderLayout, SHAPE_CHART_TYPES, type ShapeChartInput, type ShapeChartType, type StackedSegment, type TreemapCell, type TrendShape, type ValidationResult, type ValueRange, type WaterfallStep, type WorkerComputeRequest, type WorkerFilterRequest, type WorkerFilterSpec, type WorkerInitRequest, type WorkerResponse, type WorkerTransactionRequest, type XYPair, type XYPairInput, XmlReader, applyPivotAiState, ar, attachFloatingFrame, buildCellLookup, buildColPathsList, buildColumnHeaders, buildEngineResult, buildPivotAOA, buildRowLabelCells, calculatedFieldText, cellHash, cellHashCol, cellHashRow, centredFrame, chartCategoryKey, chartKeyText, chartPalette, chartWindowFrame, classifyValue, clearFormatCache, coerceRecords, coerceValue, collatorFor, compileSafeFormula, computeFieldRanges, computePivotMatrixAsync, computeRowHeaderWidths, conditionRuleToExcelStyle, cssColorToRgb, de, dedupeHeaders, defaultPivotLayout, destroyEngineWorker, detectDelimiter, diffPivotChartState, drillDownText, en, es, escapeXmlText, executePostAggregationPhase, executeSummaryDisplayModesPhase, exportPivotData, extractGroupValue, fieldNeedsRange, fieldValuesInMemory, filterEmptySummaryTree, filterPivotEngineAsync, filterRecords, filterRecordsAsync, flattenExportRows, flattenRowTree, flattenRowTreeTabular, flattenRowTreeTree, formatCellValue, formatCellValueCached, formatDimensionValue, formatHeaderValue, fr, funnelMarks, funnelStages, getAdvancedExporter, getCellVal, getFieldDistinctValues, getPivotAiSchema, getPivotAiState, getVisibleColLeaves, getVisibleColSlots, getVisibleLeafCount, getVisibleMaxDepth, heatColor, heatTextColor, heatmapMarks, histogramBins, histogramMarks, inferColumnType, initPivotEngineAsync, intlFormatToExcelNumFmt, invertRowHeaderWidth, it, ja, ko, logAxisTicks, nextChartWindowId, nextLiveText, pairSeriesForXY, parseBoolean, parseColor, parseCsvToRows, parseDelimited, parseFlexibleDate, parseLocaleNumber, percentAxisTicks, percentModeExcelNumFmt, percentModeText, pivotChangeAnnouncement, pivotRowTrend, pivotServerSource, pt, rangeBarMarks, rangeRatio, readChartFormat, readFrameRect, readPivotChartState, reconfigurePivotEngineAsync, registerAdvancedExporter, resolveChartStyle, resolveColPath, resolveColumnWidthDefaults, resolveConditionalVisual, rollupInMemory, ru, safeKey, sanitizeRows, scaleColor, serverRequestFor, setActiveEngineGrid, sortPivotTree, squarify, stackSeries, stripBom, sunburstMarks, testSafeFormula, tr, treemapMarks, trendColumnPaths, trendShape, waterfallDomain, waterfallMarks, waterfallSteps, windowStartFor, zhCN };
+export { type AdvancedExportRequest, type AdvancedExporter, CHART_LEGEND_POSITIONS, CHART_PALETTE_NAMES, type CalculatedFieldTextKey, type CellClickEvent, type CellPreparedEvent, type CellType, type ChartCategoryKeyAction, type ChartFont, type ChartFormat, type ChartGridLines, type ChartImageRequest, type ChartKeyTextKey, type ChartLabelAngle, type ChartLegendPosition, type ChartMark, type ChartPaletteName, type ChartStacking, type ChartStyle, type ChartStyleDefaults, type ColHeaderCell, type ColumnSlot, type ColumnSlotOptions, type ConditionalVisual, type CsvParseProgress, CsvReader, type CustomSummaryOptions, DEFAULT_DATA_COLUMN_WIDTH, DEFAULT_ROW_HEADER_WIDTH, DataNormalizer, type DateFormatContext, DateFormatter, type DateGranularity, type DimensionFieldInfo, type DrillDownTextKey, 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 FloatingFrame, type FrameRect, type FrameSize, type FunnelStage, type HeaderFilterOption, type HeaderFilterState, type HeaderFilterWrite, type HistogramBin, type IFileReader, type ImportFormat, ImportManager, type ImportManagerOptions, type ImportProgress, type ImportResult, type ImportSnapshot, ImportStreamController, type ImportWorkerKind, type ImportWorkerResult, MAX_C, type MarkTone, PIVOT_AI_FEATURES, type ParseFileOptions, type PivotAiApplyResult, type PivotAiCondition, type PivotAiFeature, type PivotAiFieldOptions, type PivotAiFilter, type PivotAiOptions, type PivotAiSort, type PivotAiState, type PivotAiTotals, type PivotAiValue, type PivotArea, type PivotCell, PivotCellAggregator, type PivotCellTemplate, type PivotCellTextAccessor, type PivotCellValueAccessor, type PivotChartChange, type PivotChartChangedEvent, type PivotChartClosedEvent, type PivotChartOpenedEvent, type PivotChartReportPart, type PivotChartState, type PivotChartWindowState, type PivotColumnWidthDefaults, type PivotConditionRule, PivotController, type PivotControllerCallbacks, type PivotControllerEvents, type PivotControllerOptions, type PivotControllerState, type PivotDataSource, type PivotDensity, 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 PivotLabelFilter, type PivotLayoutProfile, type PivotLayoutState, type PivotLocale, type PivotNode, type PivotPlugin, type PivotPrefilter, type PivotReport, PivotReportManager, PivotReportService, type PivotReportState, type PivotRowKey, type PivotRowKeyResolver, type PivotRowSparkline, type PivotRowTransaction, type PivotSelectionMode, PivotSelectionModel, type PivotSelectionRange, type PivotSelectionState, type PivotSelectionStats, type PivotServerCell, type PivotServerField, type PivotServerInput, type PivotServerRequest, type PivotServerResponse, type PivotServerSource, type PivotServerSourceOptions, type PivotServerValue, type PivotStateListener, PivotStateStore, type PivotStateStoringConfig, type PivotSummaryDisplayMode, type PivotSummaryType, type PivotTheme, type PivotToolbarConfig, type PivotTransactionResult, type PivotValue, type PivotValueFilter, type PrefilterConditionSpec, type PrefilterGroupSpec, type ProcessFileStreamingOptions, type ProcessFromUrlOptions, ROW_HEADER_MAX_PINNED_FRACTION, ROW_HEADER_MIN_COL_WIDTH, ROW_HEADER_MIN_DATA_STRIP, type ReportStatePart, type RowHeaderLayout, SHAPE_CHART_TYPES, type ShapeChartInput, type ShapeChartType, type StackedSegment, type TreemapCell, type TrendShape, type ValidationResult, type ValueRange, type WaterfallStep, type WorkerComputeRequest, type WorkerFilterRequest, type WorkerFilterSpec, type WorkerInitRequest, type WorkerResponse, type WorkerTransactionRequest, type XYPair, type XYPairInput, XmlReader, applyPivotAiState, ar, attachFloatingFrame, buildCellLookup, buildColPathsList, buildColumnHeaders, buildEngineResult, buildPivotAOA, buildRowLabelCells, calculatedFieldText, cellHash, cellHashCol, cellHashRow, centredFrame, chartCategoryKey, chartKeyText, chartPalette, chartWindowFrame, classifyValue, clearFormatCache, coerceRecords, coerceValue, collatorFor, compileSafeFormula, computeFieldRanges, computePivotMatrixAsync, computeRowHeaderWidths, conditionRuleToExcelStyle, cssColorToRgb, de, dedupeHeaders, defaultPivotLayout, destroyEngineWorker, detectDelimiter, diffPivotChartState, drillDownText, en, es, escapeXmlText, executePostAggregationPhase, executeSummaryDisplayModesPhase, exportPivotData, extractGroupValue, fieldNeedsRange, fieldValuesInMemory, filterEmptySummaryTree, filterPivotEngineAsync, filterRecords, filterRecordsAsync, flattenExportRows, flattenRowTree, flattenRowTreeTabular, flattenRowTreeTree, formatCellValue, formatCellValueCached, formatDimensionValue, formatHeaderValue, fr, funnelMarks, funnelStages, getAdvancedExporter, getCellVal, getFieldDistinctValues, getPivotAiSchema, getPivotAiState, getVisibleColLeaves, getVisibleColSlots, getVisibleLeafCount, getVisibleMaxDepth, headerFilterShown, headerFilterWrite, heatColor, heatTextColor, heatmapMarks, histogramBins, histogramMarks, inferColumnType, initPivotEngineAsync, intlFormatToExcelNumFmt, invertRowHeaderWidth, it, ja, ko, logAxisTicks, nextChartWindowId, nextLiveText, pairSeriesForXY, parseBoolean, parseColor, parseCsvToRows, parseDelimited, parseFlexibleDate, parseLocaleNumber, percentAxisTicks, percentModeExcelNumFmt, percentModeText, pivotChangeAnnouncement, pivotDensityClass, pivotRowHeight, pivotRowTrend, pivotServerSource, pt, rangeBarMarks, rangeRatio, readChartFormat, readFrameRect, readPivotChartState, reconfigurePivotEngineAsync, registerAdvancedExporter, resolveChartPalette, resolveChartStyle, resolveColPath, resolveColumnWidthDefaults, resolveConditionalVisual, rollupInMemory, ru, safeKey, sanitizeRows, scaleColor, serverRequestFor, setActiveEngineGrid, sortPivotTree, squarify, stackSeries, stripBom, sunburstMarks, testSafeFormula, tr, treemapMarks, trendColumnPaths, trendShape, waterfallDomain, waterfallMarks, waterfallSteps, windowStartFor, zhCN };

package/dist/index.d.ts

@@ -320,6 +320,35 @@ declare function percentAxisTicks(min: number): number[];
  * nearer the axis.
  */
 declare function stackSeries(series: ReadonlyArray<ArrayLike<number>>, mode: Exclude<ChartStacking, 'grouped'>, include?: (index: number) => boolean): Array<StackedSegment | null>;
+/**
+ * `count` colours derived from `accent`, index-stable.
+ *
+ * Falls back to the packaged eight when the accent cannot be read — an unthemed
+ * grid, or a custom theme whose `--dg-primary` is something this cannot parse
+ * (a named colour, `color-mix()`, `oklch()`). Falling back is deliberate: a
+ * chart with the wrong-but-readable palette beats a chart of black shapes.
+ *
+ * A near-grey accent also falls back. Rotating the hue of something with almost
+ * no saturation produces eight indistinguishable greys, which is worse than an
+ * off-theme palette that can actually be told apart.
+ */
+declare function chartPalette(accent: string | null | undefined, count: number): string[];
+/** The series palettes a chart offers by name. */
+type ChartPaletteName = 'theme' | 'classic' | 'colorblind' | 'vivid' | 'monochrome';
+declare const CHART_PALETTE_NAMES: readonly ChartPaletteName[];
+/**
+ * The series colours for a chart, `count` long and index-stable.
+ *
+ * @param choice  the chart format's `palette` and `colors` (both optional)
+ * @param accent  the grid's accent, as read from its tokens (`theme` derives from it)
+ * @param surface the chart's background, as read from its tokens — the floor
+ *                named palettes keep their contrast against; without it they
+ *                are used as listed
+ */
+declare function resolveChartPalette(choice: {
+    palette?: ChartPaletteName;
+    colors?: readonly string[];
+} | null | undefined, accent: string | null | undefined, surface: string | null | undefined, count: number): string[];
 
 /** Where the legend sits around the plot, or `'none'` to hide it. */
 type ChartLegendPosition = 'top' | 'bottom' | 'left' | 'right' | 'none';
@@ -378,6 +407,19 @@ interface ChartFormat {
      * browser. Absent: the grouping's own labels ("2026-03", "2026-Q1").
      */
     dateFormat?: ChartDateFormat;
+    /**
+     * Series colours by name (rival analysis, charts §E.4 #54): `'theme'` (the
+     * default — derived from the grid's accent), `'classic'`, `'colorblind'`,
+     * `'vivid'` or `'monochrome'`. Named palettes keep 3:1 contrast against the
+     * chart background.
+     */
+    palette?: ChartPaletteName;
+    /**
+     * The app's own series colours, as `#rgb` / `#rrggbb`, used in order and
+     * repeated — they win over `palette`. Set it through `defaultFormat` to give
+     * every chart a brand palette.
+     */
+    colors?: string[];
 }
 /**
  * The date presets an axis offers. Each is an `Intl.DateTimeFormat` shape, so
@@ -420,19 +462,6 @@ interface ChartImageRequest {
     /** Background colour; `null` keeps transparency (not for JPEG). Default white. */
     background?: string | null;
 }
-/**
- * `count` colours derived from `accent`, index-stable.
- *
- * Falls back to the packaged eight when the accent cannot be read — an unthemed
- * grid, or a custom theme whose `--dg-primary` is something this cannot parse
- * (a named colour, `color-mix()`, `oklch()`). Falling back is deliberate: a
- * chart with the wrong-but-readable palette beats a chart of black shapes.
- *
- * A near-grey accent also falls back. Rotating the hue of something with almost
- * no saturation produces eight indistinguishable greys, which is worse than an
- * off-theme palette that can actually be told apart.
- */
-declare function chartPalette(accent: string | null | undefined, count: number): string[];
 
 interface WaterfallStep {
     /** Running total before and after this step. */
@@ -1344,6 +1373,20 @@ declare function resolveColumnWidthDefaults(defaults?: PivotColumnWidthDefaults)
     rowHeader: number;
     data: number;
 };
+/**
+ * The body row height a `density` paints at — the number BOTH renderers'
+ * virtualizers run on (window, spacers, keyboard scroll). The stylesheet's
+ * `kanuni-pivot-density-*` rules set the matching cell line heights; the two
+ * must agree or the frozen row headers drift away from the data rows. Anything
+ * but `compact` / `comfortable` (unset, `normal`, a typo from plain JS) is the
+ * historical 28px.
+ */
+declare function pivotRowHeight(density?: PivotDensity): number;
+/**
+ * The class a density puts on the grid root (and its popups' hosts). `normal`
+ * and unset add nothing, so a grid without `density` keeps its exact markup.
+ */
+declare function pivotDensityClass(density?: PivotDensity): string;
 declare const ROW_HEADER_MIN_DATA_STRIP = 160;
 declare const ROW_HEADER_MAX_PINNED_FRACTION = 0.6;
 /** However tight it gets, a row-header column stays wide enough to read. */
@@ -1701,11 +1744,21 @@ interface PivotTheme {
     background?: string;
     surface?: string;
     surfaceHover?: string;
+    /** Panels (filter area, field areas, footer, dialog headers) — and the column-header band unless `headerBackground` is set. */
     surfaceHeader?: string;
     border?: string;
     text?: string;
     textMuted?: string;
+    /** Header text — on the panels, and on the column-header band unless `headerText` is set. */
     textHeader?: string;
+    /**
+     * The column-header band alone, apart from the panels: an ink band over light
+     * panels (`headerBackground: '#1e293b', headerText: '#f8fafc'`). Unset, the
+     * band follows `surfaceHeader` / `textHeader` as it always has.
+     */
+    headerBackground?: string;
+    /** Text on the column-header band; see `headerBackground`. */
+    headerText?: string;
     primary?: string;
     primaryForeground?: string;
     success?: string;
@@ -1717,6 +1770,12 @@ interface PivotTheme {
     groupBorder?: string;
     iconActive?: string;
 }
+/**
+ * Row rhythm of the grid: `compact` 24px body rows, `normal` 28px (the
+ * default, and what an unset value means), `comfortable` 36px. Independent of
+ * the colours (`theme`).
+ */
+type PivotDensity = 'compact' | 'normal' | 'comfortable';
 interface CustomSummaryOptions {
     summaryProcess: 'start' | 'calculate' | 'finalize';
     value: number | null;
@@ -2581,7 +2640,18 @@ declare class PivotController<TRow> {
     getRawData(): TRow[];
     getEngineResult(): PivotEngineResult | null;
     getCell(rowPath: string[], colPath: string[]): PivotCell | null;
+    /**
+     * The click event with the source rows behind the cell as `records`.
+     *
+     * Resolved on first READ, not on the click (6d-16): the rows are found by a
+     * scan of the whole dataset on the main thread, 0.3-0.5 s per click on a
+     * million rows, and a click handler that never reads them paid it anyway.
+     * The scan matches the cell's path first and runs the filters only on the
+     * rows that matched — every filter judges one row at a time, so the order
+     * does not change the result, and a cell is usually a sliver of the data.
+     */
     resolveCellClick(event: CellClickEvent<TRow>): CellClickEvent<TRow>;
+    private recordsAt;
     getAreaFields(area: PivotArea): PivotField<TRow>[];
     private cellIndexLookups;
     private getCellIndexLookup;
@@ -2887,6 +2957,49 @@ declare function sortPivotTree(nodes: PivotNode[], fields: PivotField<any>[], en
  */
 declare function collatorFor(locale?: string, numeric?: boolean): Intl.Collator;
 
+/** One row of the popup's list: the value as text (the row's key) and as stored. */
+interface HeaderFilterOption {
+    rawStr: string;
+    rawVal: unknown;
+}
+/** The part of a field the popup reads. */
+interface HeaderFilterState {
+    filterValues?: Set<unknown>;
+    filterType?: 'include' | 'exclude';
+}
+/** What OK writes back. */
+type HeaderFilterWrite = {
+    kind: 'keep';
+} | {
+    kind: 'clear';
+} | {
+    kind: 'apply';
+    values: Set<unknown>;
+    filterType: 'include' | 'exclude';
+};
+/** The `rawStr` of every option the report shows now — the boxes to tick on open. */
+declare function headerFilterShown(options: readonly HeaderFilterOption[], field: HeaderFilterState): Set<string>;
+/**
+ * The write that makes the shown set exactly the ticked set.
+ *
+ * - Nothing changed → `keep`: OK without touching anything must leave the
+ *   filter as it was, including values no current row holds (a live update
+ *   may still bring them).
+ * - Nothing ticked → `keep`: an empty list cannot be expressed (an empty
+ *   `filterValues` means "no filter"), so the popup disables OK instead.
+ * - All ticked → `clear`.
+ * - A field that already has a filter keeps its mode: exclude lists the
+ *   unticked values, include the ticked ones.
+ * - A field with no filter yet gets whichever list is SHORTER — exclude when
+ *   fewer values are unticked than ticked, include otherwise (ties: include).
+ *   Unticking three fee rows out of thousands of products stores three
+ *   values, not thousands.
+ *
+ * Each listed option contributes its `rawStr` and its `rawVal`, as the popup
+ * always wrote (a number field stores both `'10'` and `10`).
+ */
+declare function headerFilterWrite(options: readonly HeaderFilterOption[], ticked: ReadonlySet<string>, field: HeaderFilterState): HeaderFilterWrite;
+
 declare function executePostAggregationPhase<TRow>(engineResult: PivotEngineResult, dataFields: PivotField<TRow>[], registry?: PivotEngineRegistry): void;
 declare function executeSummaryDisplayModesPhase<TRow>(engineResult: PivotEngineResult, dataFields: PivotField<TRow>[]): void;
 
@@ -3514,4 +3627,4 @@ declare function rollupInMemory<TRow>(rows: readonly TRow[], request: PivotServe
 /** Every value of a field in rows held in memory — the reference `loadFieldValues`. */
 declare function fieldValuesInMemory<TRow>(rows: readonly TRow[], field: PivotServerField): unknown[];
 
-export { type AdvancedExportRequest, type AdvancedExporter, CHART_LEGEND_POSITIONS, type CalculatedFieldTextKey, type CellClickEvent, type CellPreparedEvent, type CellType, type ChartCategoryKeyAction, type ChartFont, type ChartFormat, type ChartGridLines, type ChartImageRequest, type ChartKeyTextKey, type ChartLabelAngle, type ChartLegendPosition, type ChartMark, type ChartStacking, type ChartStyle, type ChartStyleDefaults, type ColHeaderCell, type ColumnSlot, type ColumnSlotOptions, type ConditionalVisual, type CsvParseProgress, CsvReader, type CustomSummaryOptions, DEFAULT_DATA_COLUMN_WIDTH, DEFAULT_ROW_HEADER_WIDTH, DataNormalizer, type DateFormatContext, DateFormatter, type DateGranularity, type DimensionFieldInfo, type DrillDownTextKey, 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 FloatingFrame, type FrameRect, type FrameSize, type FunnelStage, type HistogramBin, type IFileReader, type ImportFormat, ImportManager, type ImportManagerOptions, type ImportProgress, type ImportResult, type ImportSnapshot, ImportStreamController, type ImportWorkerKind, type ImportWorkerResult, MAX_C, type MarkTone, PIVOT_AI_FEATURES, type ParseFileOptions, type PivotAiApplyResult, type PivotAiCondition, type PivotAiFeature, type PivotAiFieldOptions, type PivotAiFilter, type PivotAiOptions, type PivotAiSort, type PivotAiState, type PivotAiTotals, type PivotAiValue, type PivotArea, type PivotCell, PivotCellAggregator, type PivotCellTemplate, type PivotCellTextAccessor, type PivotCellValueAccessor, type PivotChartChange, type PivotChartChangedEvent, type PivotChartClosedEvent, type PivotChartOpenedEvent, type PivotChartReportPart, type PivotChartState, type PivotChartWindowState, type PivotColumnWidthDefaults, type PivotConditionRule, PivotController, type PivotControllerCallbacks, type PivotControllerEvents, type PivotControllerOptions, type PivotControllerState, type PivotDataSource, type PivotDictionary, type PivotDragIntentState, PivotEngineRegistry, type PivotEngineResult, PivotEngineService, type PivotEngineServiceConfig, PivotEventEmitter, type PivotEventHandler, type PivotEventMap, PivotExportService, type PivotField, PivotFieldService, type PivotGridRef, type PivotGroupInterval, type PivotImportField, type PivotImportLabels, type PivotImportPreviewState, type PivotImportStatus, type PivotLabelFilter, type PivotLayoutProfile, type PivotLayoutState, type PivotLocale, type PivotNode, type PivotPlugin, type PivotPrefilter, type PivotReport, PivotReportManager, PivotReportService, type PivotReportState, type PivotRowKey, type PivotRowKeyResolver, type PivotRowSparkline, type PivotRowTransaction, type PivotSelectionMode, PivotSelectionModel, type PivotSelectionRange, type PivotSelectionState, type PivotSelectionStats, type PivotServerCell, type PivotServerField, type PivotServerInput, type PivotServerRequest, type PivotServerResponse, type PivotServerSource, type PivotServerSourceOptions, type PivotServerValue, type PivotStateListener, PivotStateStore, type PivotStateStoringConfig, type PivotSummaryDisplayMode, type PivotSummaryType, type PivotTheme, type PivotToolbarConfig, type PivotTransactionResult, type PivotValue, type PivotValueFilter, type PrefilterConditionSpec, type PrefilterGroupSpec, type ProcessFileStreamingOptions, type ProcessFromUrlOptions, ROW_HEADER_MAX_PINNED_FRACTION, ROW_HEADER_MIN_COL_WIDTH, ROW_HEADER_MIN_DATA_STRIP, type ReportStatePart, type RowHeaderLayout, SHAPE_CHART_TYPES, type ShapeChartInput, type ShapeChartType, type StackedSegment, type TreemapCell, type TrendShape, type ValidationResult, type ValueRange, type WaterfallStep, type WorkerComputeRequest, type WorkerFilterRequest, type WorkerFilterSpec, type WorkerInitRequest, type WorkerResponse, type WorkerTransactionRequest, type XYPair, type XYPairInput, XmlReader, applyPivotAiState, ar, attachFloatingFrame, buildCellLookup, buildColPathsList, buildColumnHeaders, buildEngineResult, buildPivotAOA, buildRowLabelCells, calculatedFieldText, cellHash, cellHashCol, cellHashRow, centredFrame, chartCategoryKey, chartKeyText, chartPalette, chartWindowFrame, classifyValue, clearFormatCache, coerceRecords, coerceValue, collatorFor, compileSafeFormula, computeFieldRanges, computePivotMatrixAsync, computeRowHeaderWidths, conditionRuleToExcelStyle, cssColorToRgb, de, dedupeHeaders, defaultPivotLayout, destroyEngineWorker, detectDelimiter, diffPivotChartState, drillDownText, en, es, escapeXmlText, executePostAggregationPhase, executeSummaryDisplayModesPhase, exportPivotData, extractGroupValue, fieldNeedsRange, fieldValuesInMemory, filterEmptySummaryTree, filterPivotEngineAsync, filterRecords, filterRecordsAsync, flattenExportRows, flattenRowTree, flattenRowTreeTabular, flattenRowTreeTree, formatCellValue, formatCellValueCached, formatDimensionValue, formatHeaderValue, fr, funnelMarks, funnelStages, getAdvancedExporter, getCellVal, getFieldDistinctValues, getPivotAiSchema, getPivotAiState, getVisibleColLeaves, getVisibleColSlots, getVisibleLeafCount, getVisibleMaxDepth, heatColor, heatTextColor, heatmapMarks, histogramBins, histogramMarks, inferColumnType, initPivotEngineAsync, intlFormatToExcelNumFmt, invertRowHeaderWidth, it, ja, ko, logAxisTicks, nextChartWindowId, nextLiveText, pairSeriesForXY, parseBoolean, parseColor, parseCsvToRows, parseDelimited, parseFlexibleDate, parseLocaleNumber, percentAxisTicks, percentModeExcelNumFmt, percentModeText, pivotChangeAnnouncement, pivotRowTrend, pivotServerSource, pt, rangeBarMarks, rangeRatio, readChartFormat, readFrameRect, readPivotChartState, reconfigurePivotEngineAsync, registerAdvancedExporter, resolveChartStyle, resolveColPath, resolveColumnWidthDefaults, resolveConditionalVisual, rollupInMemory, ru, safeKey, sanitizeRows, scaleColor, serverRequestFor, setActiveEngineGrid, sortPivotTree, squarify, stackSeries, stripBom, sunburstMarks, testSafeFormula, tr, treemapMarks, trendColumnPaths, trendShape, waterfallDomain, waterfallMarks, waterfallSteps, windowStartFor, zhCN };
+export { type AdvancedExportRequest, type AdvancedExporter, CHART_LEGEND_POSITIONS, CHART_PALETTE_NAMES, type CalculatedFieldTextKey, type CellClickEvent, type CellPreparedEvent, type CellType, type ChartCategoryKeyAction, type ChartFont, type ChartFormat, type ChartGridLines, type ChartImageRequest, type ChartKeyTextKey, type ChartLabelAngle, type ChartLegendPosition, type ChartMark, type ChartPaletteName, type ChartStacking, type ChartStyle, type ChartStyleDefaults, type ColHeaderCell, type ColumnSlot, type ColumnSlotOptions, type ConditionalVisual, type CsvParseProgress, CsvReader, type CustomSummaryOptions, DEFAULT_DATA_COLUMN_WIDTH, DEFAULT_ROW_HEADER_WIDTH, DataNormalizer, type DateFormatContext, DateFormatter, type DateGranularity, type DimensionFieldInfo, type DrillDownTextKey, 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 FloatingFrame, type FrameRect, type FrameSize, type FunnelStage, type HeaderFilterOption, type HeaderFilterState, type HeaderFilterWrite, type HistogramBin, type IFileReader, type ImportFormat, ImportManager, type ImportManagerOptions, type ImportProgress, type ImportResult, type ImportSnapshot, ImportStreamController, type ImportWorkerKind, type ImportWorkerResult, MAX_C, type MarkTone, PIVOT_AI_FEATURES, type ParseFileOptions, type PivotAiApplyResult, type PivotAiCondition, type PivotAiFeature, type PivotAiFieldOptions, type PivotAiFilter, type PivotAiOptions, type PivotAiSort, type PivotAiState, type PivotAiTotals, type PivotAiValue, type PivotArea, type PivotCell, PivotCellAggregator, type PivotCellTemplate, type PivotCellTextAccessor, type PivotCellValueAccessor, type PivotChartChange, type PivotChartChangedEvent, type PivotChartClosedEvent, type PivotChartOpenedEvent, type PivotChartReportPart, type PivotChartState, type PivotChartWindowState, type PivotColumnWidthDefaults, type PivotConditionRule, PivotController, type PivotControllerCallbacks, type PivotControllerEvents, type PivotControllerOptions, type PivotControllerState, type PivotDataSource, type PivotDensity, 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 PivotLabelFilter, type PivotLayoutProfile, type PivotLayoutState, type PivotLocale, type PivotNode, type PivotPlugin, type PivotPrefilter, type PivotReport, PivotReportManager, PivotReportService, type PivotReportState, type PivotRowKey, type PivotRowKeyResolver, type PivotRowSparkline, type PivotRowTransaction, type PivotSelectionMode, PivotSelectionModel, type PivotSelectionRange, type PivotSelectionState, type PivotSelectionStats, type PivotServerCell, type PivotServerField, type PivotServerInput, type PivotServerRequest, type PivotServerResponse, type PivotServerSource, type PivotServerSourceOptions, type PivotServerValue, type PivotStateListener, PivotStateStore, type PivotStateStoringConfig, type PivotSummaryDisplayMode, type PivotSummaryType, type PivotTheme, type PivotToolbarConfig, type PivotTransactionResult, type PivotValue, type PivotValueFilter, type PrefilterConditionSpec, type PrefilterGroupSpec, type ProcessFileStreamingOptions, type ProcessFromUrlOptions, ROW_HEADER_MAX_PINNED_FRACTION, ROW_HEADER_MIN_COL_WIDTH, ROW_HEADER_MIN_DATA_STRIP, type ReportStatePart, type RowHeaderLayout, SHAPE_CHART_TYPES, type ShapeChartInput, type ShapeChartType, type StackedSegment, type TreemapCell, type TrendShape, type ValidationResult, type ValueRange, type WaterfallStep, type WorkerComputeRequest, type WorkerFilterRequest, type WorkerFilterSpec, type WorkerInitRequest, type WorkerResponse, type WorkerTransactionRequest, type XYPair, type XYPairInput, XmlReader, applyPivotAiState, ar, attachFloatingFrame, buildCellLookup, buildColPathsList, buildColumnHeaders, buildEngineResult, buildPivotAOA, buildRowLabelCells, calculatedFieldText, cellHash, cellHashCol, cellHashRow, centredFrame, chartCategoryKey, chartKeyText, chartPalette, chartWindowFrame, classifyValue, clearFormatCache, coerceRecords, coerceValue, collatorFor, compileSafeFormula, computeFieldRanges, computePivotMatrixAsync, computeRowHeaderWidths, conditionRuleToExcelStyle, cssColorToRgb, de, dedupeHeaders, defaultPivotLayout, destroyEngineWorker, detectDelimiter, diffPivotChartState, drillDownText, en, es, escapeXmlText, executePostAggregationPhase, executeSummaryDisplayModesPhase, exportPivotData, extractGroupValue, fieldNeedsRange, fieldValuesInMemory, filterEmptySummaryTree, filterPivotEngineAsync, filterRecords, filterRecordsAsync, flattenExportRows, flattenRowTree, flattenRowTreeTabular, flattenRowTreeTree, formatCellValue, formatCellValueCached, formatDimensionValue, formatHeaderValue, fr, funnelMarks, funnelStages, getAdvancedExporter, getCellVal, getFieldDistinctValues, getPivotAiSchema, getPivotAiState, getVisibleColLeaves, getVisibleColSlots, getVisibleLeafCount, getVisibleMaxDepth, headerFilterShown, headerFilterWrite, heatColor, heatTextColor, heatmapMarks, histogramBins, histogramMarks, inferColumnType, initPivotEngineAsync, intlFormatToExcelNumFmt, invertRowHeaderWidth, it, ja, ko, logAxisTicks, nextChartWindowId, nextLiveText, pairSeriesForXY, parseBoolean, parseColor, parseCsvToRows, parseDelimited, parseFlexibleDate, parseLocaleNumber, percentAxisTicks, percentModeExcelNumFmt, percentModeText, pivotChangeAnnouncement, pivotDensityClass, pivotRowHeight, pivotRowTrend, pivotServerSource, pt, rangeBarMarks, rangeRatio, readChartFormat, readFrameRect, readPivotChartState, reconfigurePivotEngineAsync, registerAdvancedExporter, resolveChartPalette, resolveChartStyle, resolveColPath, resolveColumnWidthDefaults, resolveConditionalVisual, rollupInMemory, ru, safeKey, sanitizeRows, scaleColor, serverRequestFor, setActiveEngineGrid, sortPivotTree, squarify, stackSeries, stripBom, sunburstMarks, testSafeFormula, tr, treemapMarks, trendColumnPaths, trendShape, waterfallDomain, waterfallMarks, waterfallSteps, windowStartFor, zhCN };