@thkl/agrid 0.1.10 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thkl/agrid",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "A signal-based, standalone data grid for Angular.",
   "keywords": [
     "angular",

package/types/thkl-agrid.d.ts

@@ -147,8 +147,23 @@ declare class AgridControl {
     private readonly _totalRows;
     private readonly _aggregates;
     private readonly _sortOrder;
+    private readonly _loading;
+    private readonly _readonly;
+    private readonly _autoAddRows;
     /** @param state Optional initial state, e.g. deserialized from storage. */
     constructor(state?: Partial<AgridControlState>);
+    /** Whether the grid displays its loading overlay. This transient state is not serialized. */
+    readonly loading: Signal<boolean>;
+    /** Show or hide the grid loading overlay. */
+    setLoading(value: boolean): void;
+    /** Whether all grid editing and mutation UI is disabled. This transient state is not serialized. */
+    readonly readonly: Signal<boolean>;
+    /** Enable or disable readonly mode at runtime. */
+    setReadonly(value: boolean): void;
+    /** Whether navigation beyond the final row automatically inserts a row. Not serialized. */
+    readonly autoAddRows: Signal<boolean>;
+    /** Enable or disable automatic row insertion at runtime. */
+    setAutoAddRows(value: boolean): void;
     /**
      * When `true`, the control column shows a drag handle and rows can be
      * reordered by dragging. Requires `showControlColumn` to be enabled on the grid.
@@ -353,6 +368,12 @@ declare class AgridControl {
     hasActiveFilter(field: string): boolean;
     /** Return `true` when the quick filter or ANY column has an active filter or sort. */
     hasAnyActiveFilter(): boolean;
+    /**
+     * Replace the live serializable state from a plain object.
+     * Missing properties reset to their defaults, making a loaded snapshot deterministic.
+     * Transient loading, readonly, auto-add, selection, and edit-history state are preserved.
+     */
+    loadState(state: Partial<AgridControlState>): void;
     /** Serialize current state to a plain object suitable for JSON storage. */
     toJSON(): AgridControlState;
     /** Restore an `AgridControl` from a previously serialized state. */
@@ -446,7 +467,83 @@ declare class AgridDataSource<T extends object = any> {
     /** Current number of rows (non-reactive snapshot). */
     get length(): number;
     private updateRows;
-    private setRows;
+    /** Replace the backing row array without copying. Intended for specialized datasource models. */
+    protected setRows(rows: T[]): void;
+}
+
+/** Sort entry sent to a server-side row datasource. */
+interface AgridServerSideSort {
+    field: string;
+    direction: 'asc' | 'desc';
+}
+/** Immutable request for one half-open row block (`startRow <= row < endRow`). */
+interface AgridServerSideRequest {
+    startRow: number;
+    endRow: number;
+    filters: Readonly<Record<string, ColumnFilter>>;
+    sort: readonly AgridServerSideSort[];
+    quickFilter: string;
+}
+/** Rows returned by a server-side datasource. Supply `rowCount` when the total is known. */
+interface AgridServerSideResult<T extends object> {
+    rows: T[];
+    rowCount?: number;
+}
+/** Fetches blocks for {@link AgridServerSideRowModel}. */
+interface AgridServerSideDatasource<T extends object> {
+    getRows(request: AgridServerSideRequest): Promise<AgridServerSideResult<T>>;
+}
+/** Configuration for the lazy, block-cached server-side row model. */
+interface AgridServerSideRowModelConfig<T extends object> {
+    datasource: AgridServerSideDatasource<T>;
+    /** Number of rows requested per block. @default 100 */
+    blockSize?: number;
+    /** Maximum loaded blocks retained in memory. @default 10 */
+    maxBlocksInCache?: number;
+    /** Known initial total. Omit when the server determines it from the first request. */
+    initialRowCount?: number;
+}
+/**
+ * Sparse datasource that lazy-loads row blocks while retaining global datasource indices.
+ * Attach it to an `AgridProvider` through `serverSideRowModel`.
+ */
+declare class AgridServerSideRowModel<T extends object = any> extends AgridDataSource<T> {
+    readonly blockSize: number;
+    readonly maxBlocksInCache: number;
+    private readonly remote;
+    private slots;
+    private readonly loadedBlocks;
+    private readonly loadingBlocks;
+    private query;
+    private queryKey;
+    private generation;
+    private accessSequence;
+    private knownRowCount;
+    private readonly _loading;
+    private readonly _error;
+    private readonly _rowCount;
+    /** Whether at least one block request is in flight. */
+    readonly loading: Signal<boolean>;
+    /** Most recent load error, cleared by the next successful request or refresh. */
+    readonly error: Signal<unknown | null>;
+    /** Current logical row count represented by the virtual scrollbar. */
+    readonly rowCount: Signal<number>;
+    constructor(config: AgridServerSideRowModelConfig<T>);
+    /** Update server query state. A changed query invalidates cached blocks and starts at row zero. */
+    setQuery(control: AgridControl | null, sortFields: readonly string[]): boolean;
+    /** Invalidate all cached blocks while preserving a known total row count. */
+    refresh(): void;
+    /** Ensure every block intersecting the requested half-open range is loaded. */
+    ensureRange(startRow: number, endRow: number): void;
+    /** Whether a logical datasource row has not been loaded yet. */
+    isPlaceholder(index: number): boolean;
+    private reset;
+    private loadBlock;
+    private applyBlock;
+    private evictBlocks;
+    private resize;
+    private replaceSlots;
+    private createPlaceholders;
 }
 
 /** Built-in locale identifiers supplied by the grid. */
@@ -458,6 +555,7 @@ interface AgridLocaleText {
     aggregate: string;
     aggregateAvg: string;
     aggregateCount: string;
+    aggregateCustom: string;
     aggregateMax: string;
     aggregateMin: string;
     aggregateSum: string;
@@ -511,6 +609,11 @@ interface AgridLocaleText {
     next: string;
     noRows: string;
     pagination: string;
+    pivot: string;
+    pivotDescription: string;
+    pivotRows: string;
+    pivotColumns: string;
+    pivotValues: string;
     pinColumn: string;
     pinColumnRight: string;
     unpinColumnRight: string;
@@ -535,20 +638,50 @@ type AgridLocaleTextOverrides = Partial<AgridLocaleText>;
 /** Built-in English and German grid translations. */
 declare const AGRID_LOCALE_TEXT: Record<AgridLocaleKey, AgridLocaleText>;
 
+/** JSON-safe pivot subset used by persisted grid settings. */
+interface AgridPivotSettings {
+    rowField: string;
+    columnField: string;
+    valueField: string;
+    aggregate: 'sum' | 'avg' | 'min' | 'max' | 'count';
+}
+/**
+ * Versioned, JSON-safe snapshot that can be stored in local storage or a backend.
+ * Functions, datasource rows, selection, loading state, and edit history are intentionally absent.
+ */
+interface AgridSettings {
+    version: 1;
+    control: AgridControlState;
+    pivotConfig: AgridPivotSettings | null;
+}
 /** Configuration used to create an {@link AgridProvider}. */
 interface AgridProviderConfig<T extends object = any> extends Partial<AGridOptions> {
     /** Row data source. A new empty data source is created when omitted. */
     datasource?: AgridDataSource<T>;
+    /**
+     * Lazy block-based server-side row model. When supplied it becomes the provider datasource and
+     * filtering, sorting, and quick filtering are included in block requests automatically.
+     */
+    serverSideRowModel?: AgridServerSideRowModel<T>;
     /** Stateful grid control. A default control is created when omitted. */
     control?: AgridControl;
     /** Initial column definitions in display order. */
     columns?: ColDef<T>[];
+    /**
+     * Derive a read-only client-side pivot table from the datasource.
+     * The first release supports one row field, one column field, and one value field.
+     * Enable `showSidebar` to let users change this configuration from the grid's Pivot tab.
+     */
+    pivotConfig?: AgridPivotConfig<T>;
     /** Labels used by columns with a matching `group` identifier. */
     headerGroups?: HeaderGroup[];
     /**
      * Render rows as a hierarchical tree. When set, rows are nested by the configured
      * parent/child accessors and an expand/collapse twisty is shown on `treeField`.
-     * Mutually exclusive with grouping and pagination.
+     *
+     * Set `aggregateTreeNodes` in this configuration to display each aggregate column's
+     * descendant-leaf rollup on expandable nodes. Tree mode is mutually exclusive with grouping
+     * and pagination.
      */
     treeConfig?: AgridTreeConfig<T>;
     /** Row height in pixels. Must be fixed for CDK virtual scroll. @default 32 */
@@ -571,7 +704,8 @@ interface AgridProviderConfig<T extends object = any> extends Partial<AGridOptio
     autoOpenDetail?: boolean;
     /**
      * Emit filter and sort changes for server processing instead of applying them locally.
-     * The Excel-style value picker is hidden in this mode. @default false
+     * The distinct-value picker is hidden unless the column supplies an explicit `values` list.
+     * @default false
      */
     serverSideFiltering?: boolean;
     /** Delay before emitting server-side text filter changes. Set to `0` to disable. @default 300 */
@@ -686,10 +820,19 @@ interface AgridProviderConfig<T extends object = any> extends Partial<AGridOptio
 declare class AgridProvider<T extends object = any> {
     /** Mutable row data consumed by the grid. */
     datasource: AgridDataSource<T>;
+    /** Lazy server-side model, or `null` for the regular client-side datasource. */
+    serverSideRowModel: AgridServerSideRowModel<T> | null;
     /** Runtime UI state and imperative grid controls. */
     control: AgridControl;
     /** Reactive column definitions in display order. */
     readonly columns: WritableSignal<ColDef<T>[]>;
+    private readonly _pivotConfig;
+    /**
+     * Client-side pivot configuration, or `null` for the normal row view.
+     * Assigning a new configuration reactively rebuilds the derived pivot rows and columns.
+     */
+    get pivotConfig(): AgridPivotConfig<T> | null;
+    set pivotConfig(config: AgridPivotConfig<T> | null);
     /** Header-group labels referenced by column definitions. */
     headerGroups: HeaderGroup[];
     /** Tree configuration, or `null` when the grid is not in tree mode. */
@@ -734,7 +877,7 @@ declare class AgridProvider<T extends object = any> {
     menuBarItems: AgridMenuBarItem<T>[];
     /** Enabled sorting mode. */
     sortOption: 'single' | 'multi' | 'none';
-    /** Toggle auto-add-rows without recreating the provider. @default signal(false) */
+    /** @deprecated Use `control.autoAddRows` and `control.setAutoAddRows()` instead. */
     readonly autoAddRows: WritableSignal<boolean>;
     /** Enabled row-selection mode. */
     rowSelection: 'single' | 'multi' | 'none';
@@ -771,18 +914,47 @@ declare class AgridProvider<T extends object = any> {
     }) => string;
     /** Fixed height in pixels of an expanded detail panel row. */
     detailRowHeight: number;
-    /** Toggle the loading overlay without recreating the provider. @default signal(false) */
+    /** @deprecated Use `control.loading` and `control.setLoading()` instead. */
     readonly loading: WritableSignal<boolean>;
-    /** Toggle readonly mode without recreating the provider. @default signal(false) */
+    /** @deprecated Use `control.readonly` and `control.setReadonly()` instead. */
     readonly readonlyGrid: WritableSignal<boolean>;
     /** Creates a provider from the supplied data, state, columns, and display options. */
     constructor(config?: AgridProviderConfig<T>);
     /** Returns the current reactive row array. */
     getGridData(): T[];
+    /**
+     * Return a detached, JSON-safe snapshot of persistent grid and pivot settings.
+     * Custom pivot aggregate functions cannot be serialized and produce an explicit error.
+     */
+    saveSettings(): AgridSettings;
+    /**
+     * Apply a previously saved snapshot to this live provider.
+     * Existing component instances update immediately because both control and pivot state are
+     * signal-backed. Unknown versions and pivot fields fail early with actionable errors.
+     */
+    loadSettings(settings: AgridSettings): void;
 }
 
 /** String-valued property names available on a row type. */
 type AgridField<T extends object> = Extract<keyof T, string>;
+/** Aggregate functions shared by footers, groups, tree rollups, and pivot values. */
+type AgridAggregate = 'sum' | 'avg' | 'min' | 'max' | 'count' | ((values: unknown[]) => unknown);
+/**
+ * Client-side pivot-table configuration.
+ *
+ * The initial pivot implementation supports one row dimension, one column dimension, and one
+ * value field. The resulting table is derived from the datasource and is always read-only.
+ */
+interface AgridPivotConfig<T extends object = any> {
+    /** Source field whose distinct values become pivot rows. */
+    rowField: AgridField<T>;
+    /** Source field whose distinct values become generated pivot columns. */
+    columnField: AgridField<T>;
+    /** Source field aggregated at each row/column intersection. */
+    valueField: AgridField<T>;
+    /** Aggregate applied to each intersection. Defaults to `'sum'`. */
+    aggregate?: AgridAggregate;
+}
 /** Behavior after pressing Enter while an inline cell editor is active. */
 type AgridEnterEditAction = 'nothing' | 'nextColumn' | 'nextRow';
 /** Parameters passed to a row-aware cell readonly resolver. */
@@ -796,6 +968,31 @@ interface CellReadonlyParams<T extends object = any, K extends AgridField<T> = A
     /** Zero-based index of the row in the datasource. */
     originalIndex: number;
 }
+/** Parameters passed to a row-aware cell formatting resolver. */
+type CellFormatParams<T extends object = any, K extends AgridField<T> = AgridField<T>> = CellReadonlyParams<T, K>;
+/** Supported visual overrides returned by {@link ColDefBase.cellFormat}. */
+interface CellFormat {
+    /** CSS background color, such as `'#fff4cc'` or `'var(--warning-bg)'`. */
+    backgroundColor?: string;
+    /** CSS border color. The cell's existing right and bottom borders use this color. */
+    borderColor?: string;
+    /** CSS text color. */
+    color?: string;
+    /** CSS `font` shorthand. Individual font properties below can override parts of it. */
+    font?: string;
+    /** CSS font family. */
+    fontFamily?: string;
+    /** CSS font size, including its unit (for example `'0.875rem'`). */
+    fontSize?: string;
+    /** CSS font style. */
+    fontStyle?: 'normal' | 'italic' | 'oblique' | string;
+    /** CSS font weight. */
+    fontWeight?: string | number;
+    /** CSS text decoration. */
+    textDecoration?: string;
+    /** CSS horizontal text alignment. */
+    textAlign?: 'left' | 'right' | 'center' | 'justify' | string;
+}
 /** Global options shared by grid providers. */
 interface AGridOptions {
     /**
@@ -855,6 +1052,8 @@ interface AgridMenuBarMenuItem<T extends object = any> {
     active?: AgridMenuBarState<T>;
     /** Whether the command is disabled. Defaults to `false`. */
     disabled?: AgridMenuBarState<T>;
+    /** Additional classes */
+    class?: string;
 }
 /** Top-level menu-bar button with optional additional dropdown commands. */
 interface AgridMenuBarItem<T extends object = any> extends AgridMenuBarMenuItem<T> {
@@ -926,6 +1125,22 @@ interface ColDefBase<T extends object, K extends AgridField<T>> {
      * ```
      */
     cellReadonly?: (params: CellReadonlyParams<T, K>) => boolean;
+    /**
+     * Return visual overrides for this specific cell at runtime.
+     * Runs with the current row, value, column definition, and original datasource index.
+     * Return `null` or `undefined` to use the grid's normal styling.
+     *
+     * @example
+     * ```ts
+     * {
+     *   field: 'balance',
+     *   cellFormat: ({ value }) => value < 0
+     *     ? { backgroundColor: '#fee2e2', color: '#991b1b', fontWeight: 600 }
+     *     : undefined,
+     * }
+     * ```
+     */
+    cellFormat?: (params: CellFormatParams<T, K>) => CellFormat | null | undefined;
     /**
      * Fixed list of allowed values shown in a `<select>` dropdown when editing.
      *
@@ -996,7 +1211,7 @@ interface ColDefBase<T extends object, K extends AgridField<T>> {
      * { field: 'score',  aggregate: values => values.filter(v => Number(v) > 90).length }
      * ```
      */
-    aggregate?: 'sum' | 'avg' | 'min' | 'max' | 'count' | ((values: unknown[]) => unknown);
+    aggregate?: AgridAggregate;
     /**
      * Return one or more CSS class names to apply to every cell in this column based on the
      * cell's value and row data. Useful for conditional highlighting without a custom renderer.
@@ -1082,6 +1297,9 @@ interface GroupAction {
 type GridItem<T extends object = Record<string, unknown>> = {
     row: T;
     originalIndex: number;
+} | {
+    loading: true;
+    originalIndex: number;
 } | null | 'ghost' | {
     groupLabel: string;
     count: number;
@@ -1102,6 +1320,13 @@ interface PathTreeNodeItem {
     expandable: true;
     /** Whether the branch's descendants are currently visible. */
     expanded: boolean;
+    /**
+     * Field-to-value rollups computed from all datasource leaves below this generated branch.
+     * Present only when the grid enables {@link AgridTreeConfig.aggregateTreeNodes}; standalone
+     * trees do not compute column aggregates.
+     * @internal
+     */
+    aggregates?: Record<string, unknown>;
 }
 /**
  * A master/detail panel row rendered immediately beneath its expanded parent data row.
@@ -1136,6 +1361,12 @@ interface TreeRowItem<T extends object = Record<string, unknown>> {
     expanded: boolean;
     /** Optional display-only label for the tree cell, used by path-based trees. */
     treeLabel?: string;
+    /**
+     * Field-to-value rollups computed from this node's descendant leaves. Parent rows are excluded
+     * so a stored subtotal is not counted again. Present only for expandable rows when enabled.
+     * @internal
+     */
+    aggregates?: Record<string, unknown>;
 }
 /**
  * Host-supplied configuration that turns the grid into a tree.
@@ -1169,6 +1400,35 @@ interface AgridTreeConfigBase<T extends object> {
      * Defaults to `true`. (Applied by the projection layer, not by {@link GridItem} flattening.)
      */
     keepAncestorsOnFilter?: boolean;
+    /**
+     * Display aggregate-column rollups on expandable nodes in `AgridComponent` tree mode.
+     *
+     * Parent/id trees aggregate descendant leaves and deliberately exclude intermediate parent
+     * values to avoid counting stored subtotals twice. Generated path branches aggregate every
+     * datasource leaf below that branch. Expansion does not affect the result, while active filters
+     * limit the contributing leaves. Aggregate cells on datasource-backed parents are display-only.
+     *
+     * The function comes from {@link ColDef.aggregate} or a runtime
+     * `AgridControl.setAggregate()` override. The standalone `AgridTreeComponent` has no columns and
+     * therefore ignores this option.
+     *
+     * @default false
+     * @example
+     * ```ts
+     * const columns = [
+     *   { field: 'name', header: 'Name' },
+     *   { field: 'amount', header: 'Amount', aggregate: 'sum' },
+     * ];
+     *
+     * const treeConfig = {
+     *   getId: row => row.id,
+     *   getParentId: row => row.parentId,
+     *   treeField: 'name',
+     *   aggregateTreeNodes: true,
+     * };
+     * ```
+     */
+    aggregateTreeNodes?: boolean;
 }
 /** Tree configuration for rows that already expose stable id and parent-id values. */
 interface AgridParentTreeConfig<T extends object = any> extends AgridTreeConfigBase<T> {
@@ -1568,6 +1828,8 @@ declare class AgridTreeController {
     collapseAll(): void;
 }
 
+/** Tabs available from the grid's vertical sidebar strip. @internal */
+type AgridSidebarTab = 'columns' | 'detail' | 'pivot';
 /** Field edit emitted by the sidebar detail form. @internal */
 interface AgridSidebarEdit {
     /** Data field being edited. */
@@ -1607,6 +1869,9 @@ interface AgridSidebarDetailField {
  * | Key | Action |
  * |-----|--------|
  * | Arrow keys | Move selection |
+ * | Page Up / Page Down | Move by one visible viewport page |
+ * | Home / End | Move to the first / last cell in the current row |
+ * | Ctrl/Cmd+Home / Ctrl/Cmd+End | Move to the first / last cell in the grid |
  * | Tab / Shift+Tab | Move right / left (wraps rows) |
  * | Enter | Enter edit mode |
  * | Ctrl/Cmd+Enter | Toggle an expandable tree node |
@@ -1641,6 +1906,8 @@ declare class AgridComponent<T extends object = any> {
     readonly cellMenuItems: Signal<(CellContextMenuItem<T> | null)[]>;
     readonly headerGroups: Signal<_thkl_agrid.HeaderGroup[]>;
     readonly treeConfig: Signal<_thkl_agrid.AgridTreeConfig<T> | null>;
+    /** Whether the provider is rendering a derived client-side pivot table. */
+    readonly pivotMode: Signal<boolean>;
     readonly zebraStripes: Signal<boolean>;
     readonly showChangedCellIndicator: Signal<boolean>;
     readonly confirmRowDelete: Signal<boolean>;
@@ -1655,6 +1922,8 @@ declare class AgridComponent<T extends object = any> {
     }) => string) | undefined>;
     /** Host callback designating pinned rows, or `undefined`. */
     readonly pinRowFn: Signal<((row: Record<string, unknown>, index: number) => "top" | "bottom" | undefined) | undefined>;
+    readonly pivotRowColumnField: Signal<Extract<keyof T, string> | undefined>;
+    readonly pivotHeaderLabel: Signal<string | undefined>;
     /**
      * Effective pin resolver fed to the projection: a runtime UI override wins (including an explicit
      * `null` unpin), otherwise the provider `pinRow` predicate decides. Returns `undefined` when
@@ -1665,10 +1934,17 @@ declare class AgridComponent<T extends object = any> {
     readonly masterDetail: Signal<boolean>;
     /** Fixed detail-panel height in pixels. */
     readonly detailRowHeight: Signal<number>;
-    /** Column definitions from the active provider. */
+    /** Read-only pivot rows and generated columns, or `null` in the normal datasource view. */
+    private readonly pivotResult;
+    /** Reactive row projection linked into a stable datasource instance for pivot mode. */
+    private readonly pivotRows;
+    private readonly pivotDataSource;
+    /** Column definitions from the active provider or generated by the active pivot. */
     readonly colDefs: Signal<ColDefBase<any, string>[]>;
-    /** Signal-based data container from the active provider. */
+    /** Signal-based source rows or a derived, read-only pivot datasource. */
     readonly dataSource: Signal<AgridDataSource<any>>;
+    /** Active lazy server-side row model, when configured on the provider. */
+    readonly serverSideRowModel: Signal<_thkl_agrid.AgridServerSideRowModel<T> | null>;
     private readonly treeParentIds;
     /** Grid UI state container from the active provider. */
     readonly control: Signal<AgridControl | null>;
@@ -1698,6 +1974,8 @@ declare class AgridComponent<T extends object = any> {
     rowClick: _angular_core.OutputEmitterRef<RowClickEvent<T>>;
     /** Emitted when the user single-clicks a generated path-tree branch node. */
     treeNodeClick: _angular_core.OutputEmitterRef<TreeNodeClickEvent>;
+    /** Emitted after sidebar changes produce a new persistable grid settings snapshot. */
+    settingsChange: _angular_core.OutputEmitterRef<AgridSettings>;
     /** Emitted when the user double-clicks a generated path-tree branch node. */
     treeNodeDoubleClicked: _angular_core.OutputEmitterRef<TreeNodeClickEvent>;
     /**
@@ -1763,7 +2041,15 @@ declare class AgridComponent<T extends object = any> {
     /** Toggle the sidebar open/closed. */
     toggleSidebar(): void;
     /** @internal */
-    onSidebarStripClick(tab: 'columns' | 'detail'): void;
+    onSidebarStripClick(tab: AgridSidebarTab): void;
+    /** @internal Replace the active pivot configuration from the sidebar controls. */
+    onSidebarPivotChange(config: AgridPivotConfig): void;
+    /** Return a detached, JSON-safe snapshot suitable for persistence by the host application. */
+    saveSettings(): AgridSettings;
+    /** Apply a saved settings snapshot to this live grid. */
+    loadSettings(settings: AgridSettings): void;
+    /** Emit when the active state is JSON-safe; custom function aggregates remain host-owned. */
+    private emitSettingsChange;
     /** @internal */
     onSidebarDetailEdit(event: AgridSidebarEdit): void;
     /** @internal Commit an edit made via the detail panel. */
@@ -1898,6 +2184,7 @@ declare class AgridComponent<T extends object = any> {
     private readonly destroyRef;
     private readonly _hostEl;
     private readonly browser;
+    private viewReady;
     private readonly rangeController;
     private readonly columnSizing;
     private readonly columnMenuController;
@@ -1935,9 +2222,11 @@ declare class AgridComponent<T extends object = any> {
     readonly sidebarOpen: _angular_core.WritableSignal<boolean>;
     /** @internal Per-field sidebar validation messages. */
     readonly sidebarValidationErrors: _angular_core.WritableSignal<Record<string, string>>;
-    readonly sidebarTab: _angular_core.WritableSignal<"columns" | "detail">;
+    readonly sidebarTab: _angular_core.WritableSignal<AgridSidebarTab>;
     readonly sidebarRow: Signal<Record<string, unknown> | null>;
     readonly sidebarHiddenColumns: Signal<ReadonlySet<string>>;
+    /** Original provider columns used as pivot field choices. */
+    readonly sidebarPivotColumns: Signal<ColDefBase<any, string>[]>;
     private readonly clipboardHandler;
     readonly dragHandler: AgridDragHandler;
     private readonly columnReorder;
@@ -1980,6 +2269,11 @@ declare class AgridComponent<T extends object = any> {
         row: Record<string, unknown>;
         originalIndex: number;
     };
+    /** @internal Whether this virtual row is waiting for a server-side block. */
+    isLoadingRow(item: GridItem): item is {
+        loading: true;
+        originalIndex: number;
+    };
     /** @internal */
     isGroupHeaderItem(item: GridItem): item is {
         groupLabel: string;
@@ -2023,8 +2317,20 @@ declare class AgridComponent<T extends object = any> {
     treeRowExpandable(item: GridItem): boolean;
     /** @internal Whether a tree row is currently expanded. */
     treeRowExpanded(item: GridItem): boolean;
-    /** @internal Display-only final path segment for a datasource-backed path-tree leaf. */
+    /**
+     * @internal Resolve the non-persistent value shown by a tree cell.
+     *
+     * A formatted path-leaf label wins in the tree column. In every other aggregate column, an
+     * expandable parent shows its descendant rollup instead of its stored value. Returning `null`
+     * delegates to the normal cell formatter. The source row is never mutated.
+     */
     treeCellDisplayOverride(item: GridItem, col: ColDef): string | null;
+    /**
+     * @internal True when a datasource-backed tree parent cell displays a computed rollup.
+     * The template uses this to prevent editing a display-only value into the source parent row.
+     * Generated path branches are not cell components and render their aggregates separately.
+     */
+    isTreeAggregateCell(item: GridItem, col: ColDef): boolean;
     /** @internal Whether the configured info action is visible for this cell. */
     showCellInfoIcon(col: ColDef, row: Record<string, unknown>): boolean;
     /** @internal Emits the typed cell information action. */
@@ -2263,6 +2569,7 @@ declare class AgridComponent<T extends object = any> {
     onSidebarToggleColumnGroup(fields: string[], visible: boolean): void;
     /** @internal Mirrors vertical scrolling from the main viewport into both pinned panes. */
     onBodyScroll(): void;
+    private ensureServerRowsVisible;
     /** @internal Keeps the row-delete prompt visible while columns scroll horizontally. */
     onHorizontalScroll(): void;
     /** @internal */
@@ -2299,7 +2606,7 @@ declare class AgridComponent<T extends object = any> {
     getColumnWidth(col: ColDef): number;
     private getColumnWidthToken;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<AgridComponent<any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<AgridComponent<any>, "agrid", never, { "provider": { "alias": "provider"; "required": false; "isSignal": true; }; }, { "cellEdit": "cellEdit"; "recordEdit": "recordEdit"; "rowRemoved": "rowRemoved"; "prepareAddRecord": "prepareAddRecord"; "rowReorder": "rowReorder"; "rowSelect": "rowSelect"; "rowDoubleClicked": "rowDoubleClicked"; "rowClick": "rowClick"; "treeNodeClick": "treeNodeClick"; "treeNodeDoubleClicked": "treeNodeDoubleClicked"; "rowChanged": "rowChanged"; "pageChange": "pageChange"; "filterChange": "filterChange"; "sortChange": "sortChange"; "quickFilterChange": "quickFilterChange"; "validationFailed": "validationFailed"; "cellInfo": "cellInfo"; "menuBarAction": "menuBarAction"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<AgridComponent<any>, "agrid", never, { "provider": { "alias": "provider"; "required": false; "isSignal": true; }; }, { "cellEdit": "cellEdit"; "recordEdit": "recordEdit"; "rowRemoved": "rowRemoved"; "prepareAddRecord": "prepareAddRecord"; "rowReorder": "rowReorder"; "rowSelect": "rowSelect"; "rowDoubleClicked": "rowDoubleClicked"; "rowClick": "rowClick"; "treeNodeClick": "treeNodeClick"; "settingsChange": "settingsChange"; "treeNodeDoubleClicked": "treeNodeDoubleClicked"; "rowChanged": "rowChanged"; "pageChange": "pageChange"; "filterChange": "filterChange"; "sortChange": "sortChange"; "quickFilterChange": "quickFilterChange"; "validationFailed": "validationFailed"; "cellInfo": "cellInfo"; "menuBarAction": "menuBarAction"; }, never, never, true, never>;
 }
 
 /** Identifier supported by the standalone page selector. */
@@ -2355,7 +2662,12 @@ declare class AgridPageSelectorComponent<TId extends AgridPageId = AgridPageId>
 
 /** Configuration accepted by {@link AgridTreeProvider}. */
 interface AgridTreeProviderConfig<T extends object> {
+    /** Flat datasource whose rows are linked by parent ids or path segments. */
     datasource: AgridDataSource<T>;
+    /**
+     * Hierarchy, identity, labeling, filtering, and initial-expansion configuration.
+     * `aggregateTreeNodes` is ignored because the standalone tree has no grid columns.
+     */
     treeConfig: AgridTreeConfig<T>;
     /** Label for parent-linked rows. Defaults to the configured `treeField` value. */
     getLabel?: (row: T) => string;
@@ -2372,14 +2684,23 @@ interface AgridTreeProviderConfig<T extends object> {
 }
 /** Provider-style configuration and datasource container for `<agrid-tree>`. */
 declare class AgridTreeProvider<T extends object = any> {
+    /** Rows projected into the standalone tree. */
     readonly datasource: AgridDataSource<T>;
+    /** Shared hierarchy configuration; column-specific aggregation is not used here. */
     readonly treeConfig: AgridTreeConfig<T>;
+    /** Optional host label resolver for parent-linked datasource rows. */
     readonly getLabel?: (row: T) => string;
+    /** Optional host resolver for secondary node text. */
     readonly getDescription?: (row: T) => string | undefined;
+    /** Effective node selection behavior. */
     readonly selection: AgridTreeSelectionMode;
+    /** Effective fixed node height in pixels. */
     readonly rowHeight: number;
+    /** Effective accessible name applied to the tree root. */
     readonly ariaLabel: string;
+    /** Effective empty-state message. */
     readonly emptyText: string;
+    /** Normalize optional standalone-tree settings and retain the reactive datasource. */
     constructor(config: AgridTreeProviderConfig<T>);
 }
 
@@ -2429,6 +2750,6 @@ declare class AgridTreeComponent<T extends object = any> {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<AgridTreeComponent<any>, "agrid-tree", never, { "provider": { "alias": "provider"; "required": true; "isSignal": true; }; }, { "nodeClick": "nodeClick"; "nodeDoubleClicked": "nodeDoubleClicked"; "selectionChange": "selectionChange"; }, never, never, true, never>;
 }
 
-export { AGRID_LOCALE_TEXT, AgridComponent, AgridControl, AgridDataSource, AgridPageSelectorComponent, AgridProvider, AgridTreeComponent, AgridTreeProvider, ColDefAutoSize };
-export type { AgridControlState, AgridEnterEditAction, AgridField, AgridLocaleKey, AgridLocaleText, AgridLocaleTextOverrides, AgridMenuBarContext, AgridMenuBarItem, AgridMenuBarMenuItem, AgridMenuBarState, AgridPageId, AgridPageItem, AgridParentTreeConfig, AgridPathSegmentParams, AgridPathTreeConfig, AgridProviderConfig, AgridTreeConfig, AgridTreeNodeEvent, AgridTreeProviderConfig, AgridTreeSelectionEvent, AgridTreeSelectionMode, CellContextMenuItem, CellInfoEvent, CellPosition, CellReadonlyParams, ColDef, ColumnFilter, DetailRowItem, FilterChangeEvent, FilterOperator, GridEditEvent, GroupAction, HeaderGroup, HistoryEntry, HistoryItem, InputMaskParams, NewRecord, PageChangeEvent, PathTreeNodeItem, RecordEditEvent, RowClickEvent, RowRemovedEvent, RowReorderEvent, RowSelectEvent, RowUpdateEvent, SortChangeEvent, TreeNodeClickEvent, TreeRowItem, ValidationFailedEvent, ValueOption };
+export { AGRID_LOCALE_TEXT, AgridComponent, AgridControl, AgridDataSource, AgridPageSelectorComponent, AgridProvider, AgridServerSideRowModel, AgridTreeComponent, AgridTreeProvider, ColDefAutoSize };
+export type { AgridAggregate, AgridControlState, AgridEnterEditAction, AgridField, AgridLocaleKey, AgridLocaleText, AgridLocaleTextOverrides, AgridMenuBarContext, AgridMenuBarItem, AgridMenuBarMenuItem, AgridMenuBarState, AgridPageId, AgridPageItem, AgridParentTreeConfig, AgridPathSegmentParams, AgridPathTreeConfig, AgridPivotConfig, AgridPivotSettings, AgridProviderConfig, AgridServerSideDatasource, AgridServerSideRequest, AgridServerSideResult, AgridServerSideRowModelConfig, AgridServerSideSort, AgridSettings, AgridTreeConfig, AgridTreeNodeEvent, AgridTreeProviderConfig, AgridTreeSelectionEvent, AgridTreeSelectionMode, CellContextMenuItem, CellFormat, CellFormatParams, CellInfoEvent, CellPosition, CellReadonlyParams, ColDef, ColumnFilter, DetailRowItem, FilterChangeEvent, FilterOperator, GridEditEvent, GroupAction, HeaderGroup, HistoryEntry, HistoryItem, InputMaskParams, NewRecord, PageChangeEvent, PathTreeNodeItem, RecordEditEvent, RowClickEvent, RowRemovedEvent, RowReorderEvent, RowSelectEvent, RowUpdateEvent, SortChangeEvent, TreeNodeClickEvent, TreeRowItem, ValidationFailedEvent, ValueOption };
 //# sourceMappingURL=thkl-agrid.d.ts.map