@kanunilabs/pivotgrid-core 1.1.0 → 1.2.0

package/dist/index.d.cts

@@ -1046,10 +1046,37 @@ interface PivotControllerOptions<TRow = any> extends PivotControllerCallbacks<TR
      * step instead of applying immediately. Defaults to false (apply directly).
      */
     previewImport?: boolean;
+    /**
+     * Where the grid's layout is persisted between sessions.
+     *
+     * Omitted, it is localStorage keyed by `gridId` — the historical behaviour,
+     * kept so an upgrade does not lose anyone's saved layout.
+     */
+    stateStoring?: PivotStateStoringConfig;
+    /**
+     * Turns on the Enterprise edition for this controller.
+     *
+     * `BasePivotGrid` sets it from the `advancedExport` prop, which is what
+     * `EnterprisePivotGrid` passes — so a normal React app never touches this.
+     * It exists because `usePivotController`, `PivotGridBody` and `PivotFooter`
+     * are all public: building your own shell is supported, and without a
+     * documented way in, that path would go from "exports a file" to "throws"
+     * with nothing to set.
+     */
+    enterpriseEdition?: boolean;
 }
 /** Imperative API handle exposed via React ref or Angular adapter. */
 interface PivotGridRef {
-    exportData: (format: ExportFormat | string, options?: ExportOptions) => void;
+    /**
+     * Returns a promise so a caller can handle a refusal.
+     *
+     * It used to be `void`. That was harmless while an unavailable format was a
+     * `console.warn` and a resolved promise; the controller now REJECTS for the
+     * three Enterprise formats, and a `void` return meant the caller could not
+     * catch it even if they wanted to. Widening `void` to `Promise<void>` is
+     * source-compatible — existing callers ignore the return either way.
+     */
+    exportData: (format: ExportFormat | string, options?: ExportOptions) => Promise<void>;
     expandAll: () => void;
     collapseAll: () => void;
     getState: () => PivotControllerState;
@@ -1062,13 +1089,37 @@ interface PivotGridRef {
 declare const defaultPivotLayout: PivotLayoutState;
 
 type PivotStateListener = () => void;
-/** Immutable-snapshot state store with debounced localStorage persistence. */
+/**
+ * Where the store reads and writes.
+ *
+ * It used to be `localStorage`, unconditionally. `PivotStateStoringConfig`
+ * declared `enabled`, `type`, `onSave` and `onLoad`, and NONE of them were
+ * read — only `storageKey`, and only as a `gridId` fallback. So
+ * `enabled: false` did not disable anything, `type: 'sessionStorage'` still
+ * wrote to localStorage, and the `type: 'custom'` + `onSave`/`onLoad` pair
+ * documented on the features page as "persist to your own backend" was a hook
+ * that nothing ever called.
+ */
+/** What actually goes in and out of storage. */
+interface PersistedPivotState {
+    fields?: unknown[];
+    layout?: Partial<PivotLayoutState>;
+    columnWidths?: Record<string, number>;
+    expandedPaths?: string[];
+    expandedColPaths?: string[];
+}
+interface PivotStatePersistence {
+    load(): PersistedPivotState | null;
+    save(state: PersistedPivotState): void;
+}
+/** Immutable-snapshot state store with debounced persistence. */
 declare class PivotStateStore<TRow> {
     private snapshot;
     private listeners;
     private storageKey;
     private persistScheduled;
-    constructor(gridId: string, initialFields: PivotField<TRow>[]);
+    private persistence;
+    constructor(gridId: string, initialFields: PivotField<TRow>[], persistence?: PivotStatePersistence);
     getSnapshot: () => PivotControllerState<TRow>;
     subscribe: (listener: PivotStateListener) => (() => void);
     setState(updates: Partial<PivotControllerState<TRow>>): void;
@@ -1207,6 +1258,43 @@ declare class PivotController<TRow> {
     deleteReport(id: string): void;
     setDefaultReport(id: string): void;
     refreshEngine(): void;
+    /**
+     * Which edition is driving this controller. Set by the React adapter from the
+     * flag `EnterprisePivotGrid` passes; Community never turns it on.
+     *
+     * The engine keeps the capability either way — the pipeline is one piece and
+     * an edition boundary that tried to cut through it would be a fork, not a
+     * gate. What the flag decides is what the controller AGREES to do.
+     *
+     * This mirrors `DataGridController.setEnterpriseEdition` deliberately: the two
+     * products should not have two different answers to the same question.
+     */
+    setEnterpriseEdition(on: boolean): void;
+    isEnterpriseEdition(): boolean;
+    private enterpriseEdition;
+    /** Seeded from the options so a headless caller has a documented way in. */
+    private applyEditionOption;
+    /**
+     * Refuse an Enterprise-only call in a clear voice.
+     *
+     * Throws rather than resolving empty: an export that silently returns nothing
+     * looks like a bug in the caller's data, and they would go looking there
+     * first. That is not hypothetical here — until this existed, a Community
+     * grid asking for `excel-pivot` got a `console.warn` and a resolved promise,
+     * AFTER `onExporting` had already fired, so an app showing a spinner on that
+     * event span forever.
+     */
+    private requireEnterprise;
+    /**
+     * The formats that need the Enterprise package.
+     *
+     * The exporter itself is registered globally by a side-effect import, so
+     * before this gate existed, one Enterprise import anywhere in a bundle
+     * enabled styled export for EVERY grid in it — including a Community
+     * `BasePivotGrid`. The registry is a module-level `let` and cannot tell who
+     * is asking; the controller can.
+     */
+    private static readonly ENTERPRISE_FORMATS;
     exportData(format: ExportFormat | string, options?: ExportOptions): Promise<void>;
     getRawData(): TRow[];
     getEngineResult(): PivotEngineResult | null;

package/dist/index.d.ts

@@ -1046,10 +1046,37 @@ interface PivotControllerOptions<TRow = any> extends PivotControllerCallbacks<TR
      * step instead of applying immediately. Defaults to false (apply directly).
      */
     previewImport?: boolean;
+    /**
+     * Where the grid's layout is persisted between sessions.
+     *
+     * Omitted, it is localStorage keyed by `gridId` — the historical behaviour,
+     * kept so an upgrade does not lose anyone's saved layout.
+     */
+    stateStoring?: PivotStateStoringConfig;
+    /**
+     * Turns on the Enterprise edition for this controller.
+     *
+     * `BasePivotGrid` sets it from the `advancedExport` prop, which is what
+     * `EnterprisePivotGrid` passes — so a normal React app never touches this.
+     * It exists because `usePivotController`, `PivotGridBody` and `PivotFooter`
+     * are all public: building your own shell is supported, and without a
+     * documented way in, that path would go from "exports a file" to "throws"
+     * with nothing to set.
+     */
+    enterpriseEdition?: boolean;
 }
 /** Imperative API handle exposed via React ref or Angular adapter. */
 interface PivotGridRef {
-    exportData: (format: ExportFormat | string, options?: ExportOptions) => void;
+    /**
+     * Returns a promise so a caller can handle a refusal.
+     *
+     * It used to be `void`. That was harmless while an unavailable format was a
+     * `console.warn` and a resolved promise; the controller now REJECTS for the
+     * three Enterprise formats, and a `void` return meant the caller could not
+     * catch it even if they wanted to. Widening `void` to `Promise<void>` is
+     * source-compatible — existing callers ignore the return either way.
+     */
+    exportData: (format: ExportFormat | string, options?: ExportOptions) => Promise<void>;
     expandAll: () => void;
     collapseAll: () => void;
     getState: () => PivotControllerState;
@@ -1062,13 +1089,37 @@ interface PivotGridRef {
 declare const defaultPivotLayout: PivotLayoutState;
 
 type PivotStateListener = () => void;
-/** Immutable-snapshot state store with debounced localStorage persistence. */
+/**
+ * Where the store reads and writes.
+ *
+ * It used to be `localStorage`, unconditionally. `PivotStateStoringConfig`
+ * declared `enabled`, `type`, `onSave` and `onLoad`, and NONE of them were
+ * read — only `storageKey`, and only as a `gridId` fallback. So
+ * `enabled: false` did not disable anything, `type: 'sessionStorage'` still
+ * wrote to localStorage, and the `type: 'custom'` + `onSave`/`onLoad` pair
+ * documented on the features page as "persist to your own backend" was a hook
+ * that nothing ever called.
+ */
+/** What actually goes in and out of storage. */
+interface PersistedPivotState {
+    fields?: unknown[];
+    layout?: Partial<PivotLayoutState>;
+    columnWidths?: Record<string, number>;
+    expandedPaths?: string[];
+    expandedColPaths?: string[];
+}
+interface PivotStatePersistence {
+    load(): PersistedPivotState | null;
+    save(state: PersistedPivotState): void;
+}
+/** Immutable-snapshot state store with debounced persistence. */
 declare class PivotStateStore<TRow> {
     private snapshot;
     private listeners;
     private storageKey;
     private persistScheduled;
-    constructor(gridId: string, initialFields: PivotField<TRow>[]);
+    private persistence;
+    constructor(gridId: string, initialFields: PivotField<TRow>[], persistence?: PivotStatePersistence);
     getSnapshot: () => PivotControllerState<TRow>;
     subscribe: (listener: PivotStateListener) => (() => void);
     setState(updates: Partial<PivotControllerState<TRow>>): void;
@@ -1207,6 +1258,43 @@ declare class PivotController<TRow> {
     deleteReport(id: string): void;
     setDefaultReport(id: string): void;
     refreshEngine(): void;
+    /**
+     * Which edition is driving this controller. Set by the React adapter from the
+     * flag `EnterprisePivotGrid` passes; Community never turns it on.
+     *
+     * The engine keeps the capability either way — the pipeline is one piece and
+     * an edition boundary that tried to cut through it would be a fork, not a
+     * gate. What the flag decides is what the controller AGREES to do.
+     *
+     * This mirrors `DataGridController.setEnterpriseEdition` deliberately: the two
+     * products should not have two different answers to the same question.
+     */
+    setEnterpriseEdition(on: boolean): void;
+    isEnterpriseEdition(): boolean;
+    private enterpriseEdition;
+    /** Seeded from the options so a headless caller has a documented way in. */
+    private applyEditionOption;
+    /**
+     * Refuse an Enterprise-only call in a clear voice.
+     *
+     * Throws rather than resolving empty: an export that silently returns nothing
+     * looks like a bug in the caller's data, and they would go looking there
+     * first. That is not hypothetical here — until this existed, a Community
+     * grid asking for `excel-pivot` got a `console.warn` and a resolved promise,
+     * AFTER `onExporting` had already fired, so an app showing a spinner on that
+     * event span forever.
+     */
+    private requireEnterprise;
+    /**
+     * The formats that need the Enterprise package.
+     *
+     * The exporter itself is registered globally by a side-effect import, so
+     * before this gate existed, one Enterprise import anywhere in a bundle
+     * enabled styled export for EVERY grid in it — including a Community
+     * `BasePivotGrid`. The registry is a module-level `let` and cannot tell who
+     * is asking; the controller can.
+     */
+    private static readonly ENTERPRISE_FORMATS;
     exportData(format: ExportFormat | string, options?: ExportOptions): Promise<void>;
     getRawData(): TRow[];
     getEngineResult(): PivotEngineResult | null;