API Reference

import { createPivotStore } from '@pivotblitz/svelte';

const store = createPivotStore(
  data: DataRecord[],
  config?: PartialPivotConfig,
  options?: PivotStoreOptions
): PivotStore;

const store = createPivotStore(
  salesData,
  {
    rows: ['region', 'product'],
    cols: ['quarter'],
    vals: [{ field: 'revenue', aggregator: 'Sum' }],
    aggregatorName: 'Sum',
  },
  {
    enableHistory: true,
    historyOptions: { maxDepth: 50 },
  }
);

import { PivotTable } from '@pivotblitz/svelte';

<PivotTable store={store} layout="compact" enableDrillDown />

import { PivotToolbar } from '@pivotblitz/svelte';

<PivotToolbar store={store} showUndoRedo showChart bind:layout />

import { FieldChooser } from '@pivotblitz/svelte';

<FieldChooser store={store} />

import { PivotChart } from '@pivotblitz/svelte';

<PivotChart store={store} type="bar" showLegend height={500} />

import { SlicerPanel } from '@pivotblitz/svelte';

<SlicerPanel
  store={store}
  slicers={[
    { attribute: 'region', style: 'buttons', multiSelect: true },
    { attribute: 'product', style: 'checkboxes', searchable: true },
  ]}
/>

import { ThemeProvider } from '@pivotblitz/svelte';

<ThemeProvider mode="dark" customTheme={{  accentPrimary: '#8b5cf6' }{'}' }>
  <PivotTable store={store} />
</ThemeProvider>

interface PivotConfig {
  rows: string[];
  cols: string[];
  vals: ValField[];
  aggregatorName: string;
  rendererName: string;
  rowOrder: 'key_a_to_z' | 'key_z_to_a' | 'value_a_to_z' | 'value_z_to_a';
  colOrder: 'key_a_to_z' | 'key_z_to_a' | 'value_a_to_z' | 'value_z_to_a';
  derivedAttributes: Record<string, (record: DataRecord) => unknown>;
  valueFilter: Record<string, (value: unknown) => boolean>;
  sorters: Record<string, (a: string, b: string) => number>;
  inclusionsInfo: Record<string, string[]>;
  exclusionsInfo: Record<string, string[]>;
  locale: string;
  hideZeroRows?: boolean;
  topN?: TopNConfig;
  filterRules?: Record<string, FilterRule[]>;
  dateGroupings?: DateGroupingConfig[];
  binnings?: BinningConfig[];
}

interface ValConfig {
  field: string;
  aggregator?: string;
  displayMode?: SummaryDisplayMode;
}

type SummaryDisplayMode =
  | 'normal'           // Raw aggregated value
  | 'pctOfGrandTotal'  // % of grand total
  | 'pctOfRowTotal'    // % of row total
  | 'pctOfColTotal'    // % of column total
  | 'pctOfParentRow'   // % of parent row
  | 'pctOfParentCol'   // % of parent column
  | 'runningTotal'     // Cumulative running total
  | 'difference'       // Difference from previous
  | 'pctDifference'    // % difference from previous
  | 'rank';            // Rank within group

interface TopNConfig {
  type: 'none' | 'top' | 'bottom';
  count: number;
  showOthers?: boolean;  // Aggregate remaining items into "Others"
}

interface SparklineConfig {
  type: 'line' | 'bar' | 'area';
  height?: number;        // Default: 20
  color?: string;         // Stroke/bar color
  showMinMax?: boolean;   // Show min/max dots
  negativeColor?: string; // Color for negative bars
  fillOpacity?: number;   // Area fill opacity (default: 0.2)
}

interface MasterDetailConfig {
  enabled: boolean;
  renderer: 'records' | 'pivot' | 'custom';
  getDetailData?: (rowKey: string[]) => Promise<Record<string, unknown>[]>;
  height?: number;  // Default: 200
}

type FormattingRule =
  | ConditionalRule
  | HeatmapRule
  | DataBarRule
  | IconSetRule;

interface ConditionalRule {
  id: string;
  name?: string;
  applyTo?: string[];
  operator: ComparisonOperator;  // 'gt' | 'gte' | 'lt' | 'between' | 'top' | ...
  value?: number | string;
  value2?: number;
  style: CellStyle;
  priority?: number;
  stopIfTrue?: boolean;
}

interface HeatmapRule {
  id: string;
  type: 'heatmap';
  applyTo?: string[];
  minColor: string;
  midColor?: string;
  maxColor: string;
  usePercentile?: boolean;
}

interface DataBarRule {
  id: string;
  type: 'dataBar';
  applyTo?: string[];
  color: string;
  backgroundColor?: string;
  showValue?: boolean;
  minValue?: number;
  maxValue?: number;
}

interface IconSetRule {
  id: string;
  type: 'iconSet';
  applyTo?: string[];
  icons: IconDefinition[];
  reverseOrder?: boolean;
}

interface FilterRule {
  type: 'label' | 'value';
  operator: LabelFilterOperator | ValueFilterOperator;
  compareTo?: string | number;
  compareToEnd?: string | number;  // For 'between'/'dateBetween'
  measureField?: string;              // For value filters
  relativeDatePreset?: RelativeDatePreset;
}

interface StatusBarConfig {
  enabled: boolean;
  panels?: StatusBarPanel[];
}

interface StatusBarPanel {
  type: 'totalRowCount' | 'totalColumnCount' | 'filteredRowCount' | 'selectedRangeStats' | 'custom';
  position?: 'left' | 'center' | 'right';
  label?: string;
  value?: string;
}

interface PrintConfig {
  title?: string;
  subtitle?: string;
  pageSize?: 'a4' | 'a3' | 'letter' | 'legal';
  orientation?: 'portrait' | 'landscape';
  showTimestamp?: boolean;
  maxRows?: number;  // Default: 10000
}

interface CellFlashConfig {
  enabled?: boolean;     // Default: false
  duration?: number;    // Flash duration in ms (default: 500)
  upColor?: string;     // Color for increased values
  downColor?: string;   // Color for decreased values
}

interface SavedPivotConfig {
  id: string;
  name: string;
  description?: string;
  config: PivotConfig;
  createdAt: string;
  updatedAt: string;
  userId?: string;
  tenantId?: string;
}

interface DataDelta {
  inserts?: DataRecord[];  // New records to append
  updates?: DataRecord[];  // Records to replace (matched by ID)
  deletes?: string[];      // Record IDs to remove
}

interface CellRendererContext {
  rowKey: string[];
  colKey: string[];
  value: AggregatorValue;
  formattedValue: string;
  rawValue: number | null;
  rowIndex: number;
  colIndex: number;
  valIndex: number;
}

import { exportToCSV } from '@pivotblitz/core';

exportToCSV(pivotResult, options?: CSVExportOptions): void

interface CSVExportOptions {
  filename?: string;       // Default: 'pivot-export'
  delimiter?: string;      // Default: ','
  includeHeaders?: boolean; // Default: true
  encoding?: string;
}

import { exportToJSON } from '@pivotblitz/core';

exportToJSON(pivotResult, options?: JSONExportOptions): void

interface JSONExportOptions {
  filename?: string;          // Default: 'pivot-export'
  pretty?: boolean;           // Default: true
  includeMetadata?: boolean;  // Default: true
}

import { exportToHTML } from '@pivotblitz/core';

exportToHTML(pivotResult, options?: HTMLExportOptions): void

interface HTMLExportOptions {
  filename?: string;            // Default: 'pivot-export'
  title?: string;              // Default: 'Pivot Table Export'
  includeStyles?: boolean;     // Default: true
  theme?: 'light' | 'dark';  // Default: 'light'
  responsive?: boolean;        // Default: true
  includeSparklines?: boolean; // Default: false
  sparklineConfig?: SparklineConfig;
  sparklineData?: Map<string, number[]>;
}

import {
  setLocale,
  getLocale,
  t,
  getSupportedLocales,
  formatLocalizedNumber,
  formatLocalizedCurrency,
  isRTL,
  getDirection,
} from '@pivotblitz/core';

setLocale('de');
t('total');                    // 'Gesamt'
formatLocalizedNumber(1234.56);  // '1.234,56'
formatLocalizedCurrency(99.9);  // '99,90 EUR'
isRTL('ar');                    // true
getDirection('he');              // 'rtl'

import { createCalculatedField } from '@pivotblitz/core';

const profitMargin = createCalculatedField({
  name: 'Profit Margin',
  formula: 'ROUND(([revenue] - [cost]) / [revenue] * 100, 1)',
});