@kanunilabs/pivotgrid-core 1.9.0 → 1.10.0

package/dist/index.d.cts

@@ -69,6 +69,8 @@ interface PivotDictionary {
     removeFromArea: string;
     removeField: string;
     deletePermanently: string;
+    /** The column cap's notice (`maxColumns`); `{shown}` and `{total}` are numbers. */
+    columnsTruncated: string;
     importSuccess: string;
     importWarning: string;
     importError: string;
@@ -1205,6 +1207,14 @@ interface PivotEngineResult {
      * removed) by `applyCustomSummaries` before any other post-phase.
      */
     customSummary?: CustomSummaryInputs;
+    /**
+     * Set when `maxColumns` cut the column members: `shown` of `total` leaf
+     * columns are in `colTree`. The matrix and every total still hold all the data.
+     */
+    columnsTruncated?: {
+        shown: number;
+        total: number;
+    };
 }
 interface FieldDistinctEntry {
     rawStr: string;
@@ -2107,6 +2117,13 @@ interface PivotControllerState<TRow = any> {
     /** Pending import awaiting preview/column-mapping review (null when none). */
     importPreview: PivotImportPreviewState | null;
     drag: PivotDragIntentState;
+    /**
+     * The quick search (`setSearchText`): only the row members whose caption
+     * (as the header draws it — a month by its name) contains it are shown,
+     * with the members above them. Not saved with the
+     * layout or in reports; totals still count every row.
+     */
+    searchText?: string;
 }
 interface PivotControllerCallbacks<TRow = any> {
     onRefresh?: () => void;
@@ -2169,6 +2186,14 @@ interface PivotControllerOptions<TRow = any> extends PivotControllerCallbacks<TR
     rowKey?: PivotRowKeyResolver<TRow>;
     /** How long `applyTransactionAsync` collects transactions before applying them together. Default 50 ms. */
     asyncTransactionWait?: number;
+    /**
+     * Most column members shown (default 1000). A field with a value per row on
+     * columns makes tens of thousands of them and freezes the page; past the cap
+     * only the first ones are drawn, totals still count all the data, and the
+     * result says so in `columnsTruncated`. Exports are never cut: they keep
+     * every column. `0` or `Infinity` turns it off.
+     */
+    maxColumns?: number;
 }
 /**
  * Starting widths, in pixels, for every column of a kind — the renderer's
@@ -2530,6 +2555,12 @@ declare class PivotController<TRow> {
     clearAllSorting(): void;
     applyFilter(fieldId: string, selectedValues: Set<any>, filterType: 'include' | 'exclude'): void;
     clearFilter(fieldId: string): void;
+    /**
+     * Quick search: show only the row members whose caption contains `text`
+     * (ignoring case and accents), with the members above them. A view on top
+     * of the reader's filters, not one of them — `''` gives the view back.
+     */
+    setSearchText(text: string): void;
     setLayout(updates: Partial<PivotLayoutState>): void;
     private readonly unsupportedReporter;
     /**
@@ -2547,7 +2578,13 @@ declare class PivotController<TRow> {
     expandColPaths(paths: string[]): void;
     collapseColPaths(paths: string[]): void;
     setExpandedColPaths(paths: string[]): void;
-    expandAll(): void;
+    /**
+     * Expand one more level across the whole tree. A search or the column cap
+     * cuts the tree on screen, so then the uncut one is computed and walked:
+     * walking the cut one left every member the search hid closed, and every
+     * column past the cap. Resolves when the new paths are set.
+     */
+    expandAll(): Promise<void>;
     collapseAll(): void;
     setColumnWidths(widths: Record<string, number>): void;
     setSelectionStats(selectionStats: PivotSelectionStats | null): void;
@@ -2700,6 +2737,7 @@ declare class PivotEngineService<TRow> {
     private drainQueued;
     private computing;
     private recomputeAfter;
+    private phaseVersion;
     private hashes;
     constructor(config: PivotEngineServiceConfig<TRow>);
     refresh(): void;
@@ -2741,6 +2779,7 @@ declare class PivotEngineService<TRow> {
     private runReconfigure;
     private scheduleFilter;
     private runFilter;
+    private endPhase;
     private scheduleComputeIfReady;
     private runCompute;
     private serverTimeout;
@@ -2756,17 +2795,26 @@ declare class PivotEngineService<TRow> {
     private postPhases;
     private runServerCompute;
     /**
-     * Produce a fully-expanded engine snapshot on demand, WITHOUT mutating the
-     * grid's live state. Used by `expandAll` exports: the cached engineResult
-     * only contains nodes visible under the current expand/collapse state (the
-     * worker prunes collapsed subtrees and their cells), so a naive
-     * "expand everything" over that snapshot would silently drop collapsed rows.
-     * This requests a fresh worker compute with every path expanded and re-runs
-     * the same post-aggregation, sort and display-mode phases as {@link runCompute}
-     * so the result is identical in shape to what the grid would render if the
-     * user expanded all nodes manually.
-     */
-    computeFullyExpandedSnapshot(): Promise<PivotEngineResult>;
+     * Produce an engine snapshot for an export on demand, WITHOUT mutating the
+     * grid's live state, and without the column cap (see postPhases).
+     *
+     * `all` (an `expandAll` export): the cached engineResult only contains nodes
+     * visible under the current expand/collapse state (the worker prunes
+     * collapsed subtrees and their cells), so a naive "expand everything" over
+     * that snapshot would silently drop collapsed rows. This requests a fresh
+     * compute with every path expanded and re-runs the same post-aggregation,
+     * sort and display-mode phases as {@link runCompute} so the result is
+     * identical in shape to what the grid would render if the user expanded all
+     * nodes manually. Otherwise: the current expansion, as on screen.
+     */
+    computeSnapshot(all: boolean): Promise<PivotEngineResult>;
+    /**
+     * The tree under the current expansion before the search and the column cap
+     * cut it — what `expandAll` walks. Walking the result on screen expanded only
+     * the matches and the first `maxColumns` columns, so clearing the search
+     * left every other member closed. Members only: no post phases.
+     */
+    computeUncut(): Promise<PivotEngineResult>;
     /**
      * Surface options the sort accepted but could not honour.
      *

package/dist/index.d.ts

@@ -69,6 +69,8 @@ interface PivotDictionary {
     removeFromArea: string;
     removeField: string;
     deletePermanently: string;
+    /** The column cap's notice (`maxColumns`); `{shown}` and `{total}` are numbers. */
+    columnsTruncated: string;
     importSuccess: string;
     importWarning: string;
     importError: string;
@@ -1205,6 +1207,14 @@ interface PivotEngineResult {
      * removed) by `applyCustomSummaries` before any other post-phase.
      */
     customSummary?: CustomSummaryInputs;
+    /**
+     * Set when `maxColumns` cut the column members: `shown` of `total` leaf
+     * columns are in `colTree`. The matrix and every total still hold all the data.
+     */
+    columnsTruncated?: {
+        shown: number;
+        total: number;
+    };
 }
 interface FieldDistinctEntry {
     rawStr: string;
@@ -2107,6 +2117,13 @@ interface PivotControllerState<TRow = any> {
     /** Pending import awaiting preview/column-mapping review (null when none). */
     importPreview: PivotImportPreviewState | null;
     drag: PivotDragIntentState;
+    /**
+     * The quick search (`setSearchText`): only the row members whose caption
+     * (as the header draws it — a month by its name) contains it are shown,
+     * with the members above them. Not saved with the
+     * layout or in reports; totals still count every row.
+     */
+    searchText?: string;
 }
 interface PivotControllerCallbacks<TRow = any> {
     onRefresh?: () => void;
@@ -2169,6 +2186,14 @@ interface PivotControllerOptions<TRow = any> extends PivotControllerCallbacks<TR
     rowKey?: PivotRowKeyResolver<TRow>;
     /** How long `applyTransactionAsync` collects transactions before applying them together. Default 50 ms. */
     asyncTransactionWait?: number;
+    /**
+     * Most column members shown (default 1000). A field with a value per row on
+     * columns makes tens of thousands of them and freezes the page; past the cap
+     * only the first ones are drawn, totals still count all the data, and the
+     * result says so in `columnsTruncated`. Exports are never cut: they keep
+     * every column. `0` or `Infinity` turns it off.
+     */
+    maxColumns?: number;
 }
 /**
  * Starting widths, in pixels, for every column of a kind — the renderer's
@@ -2530,6 +2555,12 @@ declare class PivotController<TRow> {
     clearAllSorting(): void;
     applyFilter(fieldId: string, selectedValues: Set<any>, filterType: 'include' | 'exclude'): void;
     clearFilter(fieldId: string): void;
+    /**
+     * Quick search: show only the row members whose caption contains `text`
+     * (ignoring case and accents), with the members above them. A view on top
+     * of the reader's filters, not one of them — `''` gives the view back.
+     */
+    setSearchText(text: string): void;
     setLayout(updates: Partial<PivotLayoutState>): void;
     private readonly unsupportedReporter;
     /**
@@ -2547,7 +2578,13 @@ declare class PivotController<TRow> {
     expandColPaths(paths: string[]): void;
     collapseColPaths(paths: string[]): void;
     setExpandedColPaths(paths: string[]): void;
-    expandAll(): void;
+    /**
+     * Expand one more level across the whole tree. A search or the column cap
+     * cuts the tree on screen, so then the uncut one is computed and walked:
+     * walking the cut one left every member the search hid closed, and every
+     * column past the cap. Resolves when the new paths are set.
+     */
+    expandAll(): Promise<void>;
     collapseAll(): void;
     setColumnWidths(widths: Record<string, number>): void;
     setSelectionStats(selectionStats: PivotSelectionStats | null): void;
@@ -2700,6 +2737,7 @@ declare class PivotEngineService<TRow> {
     private drainQueued;
     private computing;
     private recomputeAfter;
+    private phaseVersion;
     private hashes;
     constructor(config: PivotEngineServiceConfig<TRow>);
     refresh(): void;
@@ -2741,6 +2779,7 @@ declare class PivotEngineService<TRow> {
     private runReconfigure;
     private scheduleFilter;
     private runFilter;
+    private endPhase;
     private scheduleComputeIfReady;
     private runCompute;
     private serverTimeout;
@@ -2756,17 +2795,26 @@ declare class PivotEngineService<TRow> {
     private postPhases;
     private runServerCompute;
     /**
-     * Produce a fully-expanded engine snapshot on demand, WITHOUT mutating the
-     * grid's live state. Used by `expandAll` exports: the cached engineResult
-     * only contains nodes visible under the current expand/collapse state (the
-     * worker prunes collapsed subtrees and their cells), so a naive
-     * "expand everything" over that snapshot would silently drop collapsed rows.
-     * This requests a fresh worker compute with every path expanded and re-runs
-     * the same post-aggregation, sort and display-mode phases as {@link runCompute}
-     * so the result is identical in shape to what the grid would render if the
-     * user expanded all nodes manually.
-     */
-    computeFullyExpandedSnapshot(): Promise<PivotEngineResult>;
+     * Produce an engine snapshot for an export on demand, WITHOUT mutating the
+     * grid's live state, and without the column cap (see postPhases).
+     *
+     * `all` (an `expandAll` export): the cached engineResult only contains nodes
+     * visible under the current expand/collapse state (the worker prunes
+     * collapsed subtrees and their cells), so a naive "expand everything" over
+     * that snapshot would silently drop collapsed rows. This requests a fresh
+     * compute with every path expanded and re-runs the same post-aggregation,
+     * sort and display-mode phases as {@link runCompute} so the result is
+     * identical in shape to what the grid would render if the user expanded all
+     * nodes manually. Otherwise: the current expansion, as on screen.
+     */
+    computeSnapshot(all: boolean): Promise<PivotEngineResult>;
+    /**
+     * The tree under the current expansion before the search and the column cap
+     * cut it — what `expandAll` walks. Walking the result on screen expanded only
+     * the matches and the first `maxColumns` columns, so clearing the search
+     * left every other member closed. Members only: no post phases.
+     */
+    computeUncut(): Promise<PivotEngineResult>;
     /**
      * Surface options the sort accepted but could not honour.
      *