@kanunilabs/pivotgrid-react 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,465 @@
+import * as React$1 from 'react';
+import React__default, { Component, ErrorInfo } from 'react';
+import * as _kanunilabs_pivotgrid_core from '@kanunilabs/pivotgrid-core';
+import { PivotField as PivotField$1, PivotCellTemplate as PivotCellTemplate$1, CellClickEvent as CellClickEvent$1, CellPreparedEvent as CellPreparedEvent$1, PivotConditionRule as PivotConditionRule$1, PivotCell, PivotEngineResult, PivotLayoutState, PivotTheme, PivotStateStoringConfig, PivotToolbarConfig, PivotEngineRegistry, PivotLocale, PivotDictionary, FieldMoveEvent, ExportingEvent, PivotGridRef, ExportFormat, PivotReport, PivotControllerOptions, PivotController, PivotControllerState } from '@kanunilabs/pivotgrid-core';
+export { CustomSummaryOptions, DropIntent, ExportingEvent, FieldMoveEvent, FilterCondition, FilterGroup, FilterOperator, PivotArea, PivotCell, PivotCellTextAccessor, PivotCellValueAccessor, PivotControllerCallbacks, PivotControllerOptions, PivotControllerState, PivotDataSource, PivotDictionary, PivotDragIntentState, PivotGridRef, PivotGroupInterval, PivotImportStatus, PivotLayoutProfile, PivotLayoutState, PivotLocale, PivotNode, PivotPrefilter, PivotSelectionMode, PivotSelectionRange, PivotSelectionState, PivotSelectionStats, PivotStateStoringConfig, PivotSummaryDisplayMode, PivotSummaryType, PivotTheme, PivotToolbarConfig, defaultPivotLayout } from '@kanunilabs/pivotgrid-core';
+import * as _dnd_kit_core from '@dnd-kit/core';
+import { DragMoveEvent, DragEndEvent } from '@dnd-kit/core';
+
+type PivotCellTemplate = (props: Parameters<PivotCellTemplate$1>[0]) => React$1.ReactNode;
+type PivotConditionRule = PivotConditionRule$1<React$1.CSSProperties>;
+type PivotField<TRow = any> = PivotField$1<TRow, PivotCellTemplate, React$1.CSSProperties>;
+type CellClickEvent<TRow = any> = CellClickEvent$1<TRow, React$1.MouseEvent | React$1.KeyboardEvent>;
+type CellPreparedEvent<TRow = any> = CellPreparedEvent$1<TRow, React$1.ReactNode, React$1.CSSProperties>;
+
+interface PivotChartIntegrationOptions {
+    inverted?: boolean;
+    hideTotals?: boolean;
+    maxPoints?: number;
+    dataFieldsDisplayMode?: 'singleAxis' | 'splitAxes';
+    processCell?: (cell: PivotCell) => boolean;
+    transformer?: (engineResult: PivotEngineResult, fields: PivotField[], expandedPaths: Set<string>, locale: string, options: any) => ChartSyncResult;
+}
+interface ChartSeriesDef {
+    dataKey: string;
+    name: string;
+    color: string;
+    yAxisId?: string;
+}
+interface ChartSyncResult {
+    chartData: any[];
+    chartSeries: ChartSeriesDef[];
+}
+declare function usePivotChartSync(engineResult: PivotEngineResult | null, fields: PivotField[], expandedPaths: Set<string>, options?: PivotChartIntegrationOptions): ChartSyncResult;
+
+/**
+ * Props for the BasePivotGrid component.
+ * This is the enterprise-grade data orchestration layer for analytics.
+ */
+interface BasePivotGridProps<TRow> {
+    /** Optional identifier for the grid instance. Used for report storing and caching. */
+    gridId?: string;
+    /**
+     * Explicit URL for the engine Web Worker script. Required in bundlers that
+     * cannot statically resolve the default `new URL('./pivot.worker.js',
+     * import.meta.url)` (e.g. Next.js). Copy the worker from
+     * `@kanunilabs/pivotgrid-core/dist/pivot.worker.js` into a served path and
+     * point this at it, e.g. `/kanunilabs/pivot.worker.js`.
+     */
+    workerUrl?: string | URL;
+    /** The raw tabular data array. */
+    data: TRow[];
+    /** Initial field configuration (Uncontrolled mode). */
+    initialFields?: PivotField<TRow>[];
+    /** Controlled field configuration. If provided, component acts as controlled. */
+    fields?: PivotField<TRow>[];
+    /** Controlled layout configuration. */
+    layout?: PivotLayoutState;
+    /** Custom theme configuration. */
+    theme?: PivotTheme;
+    /** Callback fired when the refresh button is clicked. */
+    onRefresh?: () => void;
+    /** Callback fired when data is imported via the UI. */
+    onImportData?: (data: TRow[]) => void;
+    /** When true, UI imports open a preview + column-mapping step before applying. */
+    previewImport?: boolean;
+    /** Configuration for state storing (localStorage, sessionStorage, etc). */
+    stateStoring?: PivotStateStoringConfig;
+    /** Configuration for keyboard navigation and accessibility. */
+    keyboardNavigation?: {
+        enabled: boolean;
+    };
+    /** Configuration for the toolbar visibility and features. */
+    toolbar?: PivotToolbarConfig;
+    /** The plugin registry containing custom functions and formatters. */
+    registry?: PivotEngineRegistry;
+    /** Locale for the grid (tr, en, ar). Defaults to tr. */
+    locale?: PivotLocale;
+    /** Right-to-Left (RTL) mode. Defaults to false (except for 'ar'). */
+    rtl?: boolean;
+    /** Dictionary for localized strings (i18n). */
+    dictionary?: Partial<PivotDictionary>;
+    /** Apply zebra striping to the data rows. */
+    striped?: boolean;
+    /**
+     * Fired when any cell is clicked (data cells, row headers, grand totals).
+     * Replaces the deprecated onDrillDown handler.
+     * This is the single source of truth for cell interactions.
+     */
+    onCellClick?: (e: CellClickEvent<TRow>) => void;
+    /**
+     * Fired when a field is moved within the PivotGrid (drag & drop).
+     * Provides a validate/cancel hybrid model. If it returns a Promise,
+     * the component awaits validation before committing the DND state.
+     */
+    onFieldMove?: (e: FieldMoveEvent) => void | Promise<void>;
+    /** Fired immediately before the Pivot matrix compute cycle begins. */
+    onBeforePivotCalculate?: () => void;
+    /** Fired after the Pivot matrix compute cycle completes successfully. */
+    onAfterPivotCalculate?: (result: PivotEngineResult) => void;
+    /** Fired when an export action is initiated. Can be canceled. */
+    onExporting?: (e: ExportingEvent) => void;
+    /** Fired after a cell is prepared to allow modifications. */
+    onCellPrepared?: (e: CellPreparedEvent<TRow>) => void;
+    /** Fired when fields configuration changes. */
+    onFieldsChange?: (fields: PivotField<TRow>[]) => void;
+    /** Fired when layout options change. */
+    onLayoutChange?: (layout: PivotLayoutState) => void;
+    /** Customize the context menu items for a specific field. */
+    customContextMenuItems?: (field: PivotField<TRow>) => {
+        label: string;
+        action: () => void;
+        icon?: React__default.ReactNode;
+    }[];
+    /** Configuration for chart synchronization. */
+    chartIntegrationOptions?: PivotChartIntegrationOptions & {
+        chartType?: string;
+    };
+    /** Callback to receive chart integration payload. */
+    onChartSync?: (syncResult: ChartSyncResult) => void;
+    /** Callback fired when chart toggle is clicked. */
+    onToggleChart?: () => void;
+    /**
+     * Callback fired when full screen chart icon is clicked.
+     * @deprecated This prop will be removed in a future major version. Use chartIntegrationOptions instead.
+     */
+    onOpenFullScreenChart?: () => void;
+    /** Callback to receive loaded chart state. */
+    onChartStateLoaded?: (chartState: PivotChartIntegrationOptions & {
+        chartType?: string;
+    }) => void;
+    /** Fired when a critical engine error occurs. */
+    onError?: (error: Error) => void;
+    /** Disables all interactive features (drag & drop, expand/collapse, context menu, filtering, etc.) */
+    disabled?: boolean;
+    /** Slot for injecting Enterprise Calculated Field Modal */
+    renderCalculatedFieldModal?: (props: any) => React__default.ReactNode;
+    /** Slot for injecting Enterprise Prefilter Builder */
+    renderPrefilterBuilder?: (props: any) => React__default.ReactNode;
+    /** Slot for injecting Enterprise Node Context Menu */
+    renderNodeContextMenu?: (props: any) => React__default.ReactNode;
+    /**
+     * Enables the Enterprise-only styled Excel & PDF export items in the footer.
+     * Set by `EnterprisePivotGrid`; in the Community build those items render locked.
+     */
+    advancedExport?: boolean;
+    /**
+     * URL opened when a Community user clicks a locked Enterprise export item
+     * (e.g. your pricing / Enterprise sales page).
+     */
+    upgradeUrl?: string;
+}
+declare const BasePivotGridInner: <TRow>(props: BasePivotGridProps<TRow>, ref: React__default.ForwardedRef<PivotGridRef>) => React__default.JSX.Element;
+declare const BasePivotGrid: <TRow>(props: BasePivotGridProps<TRow> & {
+    ref?: React__default.ForwardedRef<PivotGridRef>;
+}) => ReturnType<typeof BasePivotGridInner>;
+
+interface PivotGridBodyProps {
+    engineResult: PivotEngineResult;
+    isBuilding: boolean;
+    buildProgress?: number;
+    rowFields: PivotField[];
+    colFields: PivotField[];
+    dataFields: PivotField[];
+    layout: PivotLayoutState;
+    expandedPaths: Set<string>;
+    allExpanded: boolean;
+    onToggleExpand: (path: string) => void;
+    onExpandPaths: (paths: string[]) => void;
+    onCollapsePaths: (paths: string[]) => void;
+    expandedColPaths: Set<string>;
+    allColExpanded: boolean;
+    onToggleColExpand: (path: string) => void;
+    onExpandColPaths: (paths: string[]) => void;
+    onCollapseColPaths: (paths: string[]) => void;
+    onCellClick?: (e: CellClickEvent) => void;
+    onContextMenu?: (x: number, y: number, fieldId: string, colPath?: string) => void;
+    onFilterClick?: (x: number, y: number, fieldId: string) => void;
+    onRemoveField: (id: string) => void;
+    onSort?: (id: string, dir: 'asc' | 'desc' | undefined) => void;
+    onGlobalContextMenu?: (x: number, y: number) => void;
+    columnWidths?: Record<string, number>;
+    onColumnWidthsChange?: (widths: Record<string, number>) => void;
+    onSelectionStatsChange?: (stats: {
+        count: number;
+        sum: number;
+        avg: number;
+        min: number;
+        max: number;
+    } | null) => void;
+    registry?: _kanunilabs_pivotgrid_core.PivotEngineRegistry;
+    keyboardNavigation?: {
+        enabled: boolean;
+    };
+    onCellPrepared?: (e: CellPreparedEvent<any>) => void;
+    disabled?: boolean;
+    renderNodeContextMenu?: (props: any) => React.ReactNode;
+}
+declare function PivotGridBody({ engineResult, isBuilding, buildProgress, rowFields, colFields: _colFields, dataFields, layout, expandedPaths, allExpanded, onToggleExpand, onExpandPaths, onCollapsePaths, expandedColPaths, allColExpanded, onToggleColExpand, onExpandColPaths, onCollapseColPaths, onCellClick, onContextMenu, onFilterClick, onRemoveField, onSort, onGlobalContextMenu, columnWidths, onColumnWidthsChange, onSelectionStatsChange, registry, keyboardNavigation, onCellPrepared, renderNodeContextMenu }: PivotGridBodyProps): React$1.JSX.Element;
+
+interface PivotFooterProps {
+    onToggleFieldChooser: () => void;
+    fieldChooserOpen: boolean;
+    onRefresh?: () => void;
+    onExport: (format: ExportFormat | string) => void;
+    onImportFile?: (file: File) => void;
+    /** Multi-file import (drag-drop / file picker with multiple selection). */
+    onImportFiles?: (files: File[]) => void;
+    /** Import delimited text from the clipboard. */
+    onPasteImport?: () => void;
+    onExpandAll: () => void;
+    onCollapseAll: () => void;
+    onAddCalculatedField?: () => void;
+    onOpenPrefilter?: () => void;
+    onToggleChart?: () => void;
+    isFullscreen?: boolean;
+    onToggleFullscreen?: () => void;
+    reports?: PivotReport[];
+    activeReportId?: string | null;
+    onSaveNewReport?: () => void;
+    onUpdateCurrentReport?: () => void;
+    onSaveAsReport?: () => void;
+    onLoadReport?: (id: string) => void;
+    onDeleteReport?: (id: string) => void;
+    onSetDefaultReport?: (id: string) => void;
+    onGlobalContextMenu?: (x: number, y: number) => void;
+    selectionStats?: {
+        count: number;
+        sum: number;
+        avg: number;
+        min: number;
+        max: number;
+    } | null;
+    toolbarConfig?: PivotToolbarConfig;
+    registry?: _kanunilabs_pivotgrid_core.PivotEngineRegistry;
+    /**
+     * Enables the Enterprise-only styled Excel & PDF export items. Set by
+     * `EnterprisePivotGrid`; in the Community build they render locked.
+     */
+    advancedExport?: boolean;
+    /**
+     * URL opened (new tab) when a Community user clicks a locked Enterprise export
+     * item — e.g. your pricing / Enterprise sales page.
+     */
+    upgradeUrl?: string;
+}
+declare function PivotFooter({ onToggleFieldChooser, fieldChooserOpen, onRefresh, onExport, onImportFile, onImportFiles, onPasteImport, onExpandAll, onCollapseAll, onAddCalculatedField, onOpenPrefilter, onToggleChart, isFullscreen, onToggleFullscreen, reports, activeReportId, onSaveNewReport, onUpdateCurrentReport, onSaveAsReport, onLoadReport, onDeleteReport, onSetDefaultReport, onGlobalContextMenu, selectionStats, toolbarConfig, registry, advancedExport, upgradeUrl }: PivotFooterProps): React$1.JSX.Element;
+
+interface PivotAreaStripsProps {
+    filterFields: PivotField[];
+    onRemoveField: (id: string) => void;
+    onFilterClick: (x: number, y: number, fieldId: string) => void;
+    onContextMenu?: (x: number, y: number, fieldId: string, colPath?: string) => void;
+    onSort?: (id: string, dir: 'asc' | 'desc' | undefined) => void;
+    onGlobalContextMenu?: (x: number, y: number) => void;
+}
+declare function PivotAreaStrips({ filterFields, onRemoveField, onFilterClick, onContextMenu, onSort, onGlobalContextMenu }: PivotAreaStripsProps): React__default.JSX.Element;
+
+interface PivotFieldListProps {
+    area: string;
+    fields: PivotField[];
+    title?: string;
+    emptyText?: string;
+    onRemoveField: (id: string) => void;
+    onDeleteField?: (id: string) => void;
+    maxHeight?: number | string;
+    showCheckboxes?: boolean;
+    onToggleCheckbox?: (field: PivotField, checked: boolean) => void;
+    onFilterClick?: (e: React.MouseEvent, field: PivotField) => void;
+}
+declare function PivotFieldList({ area, fields, title, emptyText, onRemoveField, onDeleteField, maxHeight, showCheckboxes, onToggleCheckbox, onFilterClick }: PivotFieldListProps): React$1.JSX.Element;
+
+interface PivotFieldSettingsDialogProps {
+    field: PivotField;
+    onClose: () => void;
+    onSave: (field: PivotField) => void;
+}
+declare function PivotFieldSettingsDialog({ field, onClose, onSave }: PivotFieldSettingsDialogProps): React$1.JSX.Element;
+
+interface PivotHeaderFilterPopupProps {
+    field: PivotField;
+    data: any[];
+    onApply: (fieldId: string, selectedValues: Set<any>, filterType: 'include' | 'exclude') => void;
+    onClear: (fieldId: string) => void;
+    onClose: () => void;
+    x: number;
+    y: number;
+}
+declare const PivotHeaderFilterPopup: React__default.FC<PivotHeaderFilterPopupProps>;
+
+interface PivotContextMenuProps {
+    x: number;
+    y: number;
+    field: PivotField;
+    onClose: () => void;
+    onSort: (direction: 'asc' | 'desc' | undefined) => void;
+    onHide: () => void;
+    onSettings: () => void;
+    onMoveField?: (direction: 'start' | 'end' | 'left' | 'right') => void;
+    onShowFieldChooser?: () => void;
+    colPath?: string;
+    rowFields?: PivotField[];
+    onSortBySummary?: (rowFieldId: string, colPath: string) => void;
+    onClearAllSorting?: () => void;
+    customContextMenuItems?: {
+        label: string;
+        action: () => void;
+        icon?: any;
+    }[];
+    onEditCalculatedField?: () => void;
+}
+declare function PivotContextMenu({ x, y, field, colPath, rowFields, onClose, onSort, onSortBySummary, onClearAllSorting, onHide, onSettings, onMoveField, onShowFieldChooser, customContextMenuItems, onEditCalculatedField }: PivotContextMenuProps): React$1.JSX.Element;
+
+interface PivotPortalProps {
+    children: React__default.ReactNode;
+}
+declare function PivotPortal({ children }: PivotPortalProps): React__default.ReactPortal | null;
+
+interface PivotImportStatusModalProps {
+    isOpen: boolean;
+    onClose: () => void;
+    status: 'loading' | 'success' | 'error' | 'warning';
+    title: string;
+    messages: string[];
+    /** Overall parse progress 0..100 while a large file streams in. */
+    progress?: number;
+    /** Coarse pipeline stage label (reading | parsing | typing | finalizing). */
+    phase?: string;
+    /** Whether the in-flight import can be cancelled. */
+    cancellable?: boolean;
+    /** Invoked when the user clicks Cancel during a loading import. */
+    onCancel?: () => void;
+}
+declare function PivotImportStatusModal({ isOpen, onClose, status, title, messages, progress, phase, cancellable, onCancel, }: PivotImportStatusModalProps): React$1.JSX.Element | null;
+
+interface PivotReportMenuProps {
+    reports: PivotReport[];
+    activeReportId: string | null;
+    onSaveNew: () => void;
+    onUpdateCurrent: () => void;
+    onSaveAs: () => void;
+    onLoadReport: (id: string) => void;
+    onDeleteReport: (id: string) => void;
+    onSetDefault: (id: string) => void;
+}
+declare function PivotReportMenu({ reports, activeReportId, onSaveNew, onUpdateCurrent, onSaveAs, onLoadReport, onDeleteReport, onSetDefault }: PivotReportMenuProps): React$1.JSX.Element;
+
+interface PivotReportSaveModalProps {
+    isOpen: boolean;
+    onClose: () => void;
+    onSave: (name: string, isDefault: boolean) => void;
+    defaultName?: string;
+    title?: string;
+}
+declare function PivotReportSaveModal({ isOpen, onClose, onSave, defaultName, title }: PivotReportSaveModalProps): React$1.JSX.Element | null;
+
+interface Props {
+    children: React__default.ReactNode;
+    fallback?: React__default.ReactNode;
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+}
+interface State {
+    hasError: boolean;
+    error: Error | null;
+}
+declare class PivotErrorBoundary extends Component<Props, State> {
+    state: State;
+    static getDerivedStateFromError(error: Error): State;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    private handleReset;
+    render(): string | number | bigint | boolean | Iterable<React__default.ReactNode> | Promise<string | number | bigint | boolean | React__default.ReactPortal | React__default.ReactElement<unknown, string | React__default.JSXElementConstructor<any>> | Iterable<React__default.ReactNode> | null | undefined> | React__default.JSX.Element | null | undefined;
+}
+
+declare const PivotPortalContext: React$1.Context<HTMLElement | null>;
+
+declare function usePivotController<TRow>(options: PivotControllerOptions<TRow>): PivotController<TRow>;
+
+declare function usePivotControllerStore<TRow, TSelected>(controller: PivotController<TRow>, selector: (state: PivotControllerState<TRow>) => TSelected, isEqual?: (previous: TSelected, next: TSelected) => boolean): TSelected;
+
+interface UsePivotDnDProps<TRow> {
+    fields: PivotField<TRow>[];
+    controller: PivotController<TRow>;
+}
+declare function usePivotDnD<TRow>({ fields, controller }: UsePivotDnDProps<TRow>): {
+    activeDragId: string | null;
+    sensors: _dnd_kit_core.SensorDescriptor<_dnd_kit_core.SensorOptions>[];
+    handleDragStart: (event: any) => void;
+    handleDragMove: (event: DragMoveEvent) => void;
+    handleDragEnd: (event: DragEndEvent) => Promise<void>;
+    handleRemoveField: (id: string) => void;
+    handleMoveField: (fieldId: string, direction: "start" | "end" | "left" | "right") => void;
+};
+
+declare function usePivotFullscreen(): {
+    isFullscreen: boolean;
+    containerRef: React$1.RefObject<HTMLDivElement | null>;
+    toggleFullscreen: () => void;
+};
+
+declare function usePivotContextMenu(): {
+    chooserOpen: boolean;
+    setChooserOpen: React$1.Dispatch<React$1.SetStateAction<boolean>>;
+    settingsFieldId: string | null;
+    setSettingsFieldId: React$1.Dispatch<React$1.SetStateAction<string | null>>;
+    contextMenu: {
+        x: number;
+        y: number;
+        fieldId: string;
+        colPath?: string;
+    } | null;
+    setContextMenu: React$1.Dispatch<React$1.SetStateAction<{
+        x: number;
+        y: number;
+        fieldId: string;
+        colPath?: string;
+    } | null>>;
+    filterPopup: {
+        x: number;
+        y: number;
+        fieldId: string;
+    } | null;
+    setFilterPopup: React$1.Dispatch<React$1.SetStateAction<{
+        x: number;
+        y: number;
+        fieldId: string;
+    } | null>>;
+    isPrefilterOpen: boolean;
+    setIsPrefilterOpen: React$1.Dispatch<React$1.SetStateAction<boolean>>;
+    globalContextMenu: {
+        x: number;
+        y: number;
+    } | null;
+    setGlobalContextMenu: React$1.Dispatch<React$1.SetStateAction<{
+        x: number;
+        y: number;
+    } | null>>;
+    isCalcModalOpen: boolean;
+    setIsCalcModalOpen: React$1.Dispatch<React$1.SetStateAction<boolean>>;
+    editingCalcField: PivotField | undefined;
+    setEditingCalcField: React$1.Dispatch<React$1.SetStateAction<PivotField | undefined>>;
+};
+
+interface PivotLocalizationContextProps {
+    locale: PivotLocale;
+    dictionary: PivotDictionary;
+    t: (key: keyof PivotDictionary | string) => string;
+    rtl: boolean;
+}
+interface PivotConfigProviderProps {
+    children: React__default.ReactNode;
+    locale?: PivotLocale;
+    dictionary?: Partial<PivotDictionary>;
+    rtl?: boolean;
+}
+declare const PivotConfigProvider: React__default.FC<PivotConfigProviderProps>;
+declare const usePivotConfig: () => PivotLocalizationContextProps;
+
+interface PivotThemeProviderProps {
+    theme?: PivotTheme;
+    className?: string;
+    style?: React__default.CSSProperties;
+    children: React__default.ReactNode;
+}
+declare function PivotThemeProvider({ theme, className, style, children }: PivotThemeProviderProps): React__default.JSX.Element;
+
+export { BasePivotGrid, type BasePivotGridProps, type CellClickEvent, type CellPreparedEvent, type ChartSeriesDef, type ChartSyncResult, PivotAreaStrips, type PivotCellTemplate, type PivotChartIntegrationOptions, type PivotConditionRule, PivotConfigProvider, PivotContextMenu, PivotErrorBoundary, type PivotField, PivotFieldList, PivotFieldSettingsDialog, PivotFooter, PivotGridBody, PivotHeaderFilterPopup, PivotImportStatusModal, PivotPortal, PivotPortalContext, PivotReportMenu, PivotReportSaveModal, PivotThemeProvider, usePivotChartSync, usePivotConfig, usePivotContextMenu, usePivotController, usePivotControllerStore, usePivotDnD, usePivotFullscreen };