@thkl/agrid 0.1.12 → 0.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thkl/agrid",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "A signal-based, standalone data grid for Angular.",
   "keywords": [
     "angular",
@@ -23,9 +23,9 @@
   },
   "sideEffects": false,
   "peerDependencies": {
-    "@angular/cdk": "21.2.14",
-    "@angular/common": "21.2.17",
-    "@angular/core": "21.2.17"
+    "@angular/cdk": ">=21.0.0 <23.0.0",
+    "@angular/common": ">=21.0.0 <23.0.0",
+    "@angular/core": ">=21.0.0 <23.0.0"
   },
   "dependencies": {
     "tslib": "^2.3.0"

package/types/thkl-agrid.d.ts

@@ -127,6 +127,15 @@ interface AgridControlState {
     /** Per-field aggregate function set via the column menu. Only built-in string values are serializable. */
     aggregates?: Record<string, 'sum' | 'avg' | 'min' | 'max' | 'count'>;
 }
+/** Detached, JSON-safe filter/search/sort state for {@link AgridControl}. */
+interface AgridFilterModel {
+    /** Per-field column filter and sort state. */
+    filters: Record<string, ColumnFilter>;
+    /** Global quick-filter text. Empty or omitted means inactive. */
+    quickFilter?: string;
+    /** Ordered sorted fields, from highest to lowest priority. */
+    sortOrder?: string[];
+}
 /**
  * Signal-based container for mutable grid UI state such as column widths and active filters.
  *
@@ -162,6 +171,8 @@ declare class AgridControl {
     private readonly _loading;
     private readonly _readonly;
     private readonly _autoAddRows;
+    private readonly _filterReapplyRevision;
+    private readonly _filterReapplyNeeded;
     private readonly _rowIndications;
     private readonly _changedCells;
     private readonly rowIndicationTimers;
@@ -202,6 +213,20 @@ declare class AgridControl {
     readonly autoAddRows: Signal<boolean>;
     /** Enable or disable automatic row insertion at runtime. */
     setAutoAddRows(value: boolean): void;
+    /**
+     * Reapply active filters to rows that were inserted while filters were already active.
+     * By default, newly inserted rows stay visible until this method is called.
+     */
+    reapplyFilters(): void;
+    /**
+     * `true` when inserted rows are currently bypassing active filters or sorts.
+     * Bind this to visual feedback for a "Reapply filters" action.
+     */
+    readonly filterReapplyNeeded: Signal<boolean>;
+    /** @internal Updates {@link filterReapplyNeeded} from the rendered grid projection. */
+    ɵsetFilterReapplyNeeded(value: boolean): void;
+    /** @internal Emits whenever {@link reapplyFilters} is called. */
+    readonly ɵfilterReapplyRevision: Signal<number>;
     /**
      * When `true`, the control column shows a drag handle and rows can be
      * reordered by dragging. Requires `showControlColumn` to be enabled on the grid.
@@ -360,6 +385,15 @@ declare class AgridControl {
      * Returns a default (inactive) filter when no state is stored for the field.
      */
     getFilter(field: string): ColumnFilter;
+    /** Replace the complete filter/sort state for one field. */
+    setFilter(field: string, filter: ColumnFilter): void;
+    /** Return a detached JSON-safe snapshot of active column filters, quick filter, and sort order. */
+    getFilterModel(): AgridFilterModel;
+    /**
+     * Replace active column filters, quick filter, and sort order from a filter model.
+     * Pass `null` to clear all filters and sorts.
+     */
+    setFilterModel(model: AgridFilterModel | null): void;
     /**
      * Set the free-text filter for a column.
      * An empty string removes the text filter for that column.
@@ -416,6 +450,7 @@ declare class AgridControl {
     toJSON(): AgridControlState;
     /** Restore an `AgridControl` from a previously serialized state. */
     static fromJSON(state: Partial<AgridControlState>): AgridControl;
+    private cloneFilters;
 }
 
 /**
@@ -439,6 +474,7 @@ declare class AgridDataSource<T extends object = any> {
     private readonly _rows;
     private _writableLinkedRows;
     private readonly _rowAdded;
+    private readonly _unfilteredAddedRows;
     private _changeSequence;
     /**
      * @param initialData Rows to seed the data source with.
@@ -455,6 +491,12 @@ declare class AgridDataSource<T extends object = any> {
         index: number;
         sequence: number;
     } | null>;
+    /**
+     * Rows inserted since filters were last explicitly reapplied.
+     * Attached grids include these rows even when they do not match active filters.
+     * @internal
+     */
+    readonly ɵunfilteredAddedRows: Signal<ReadonlySet<number>>;
     /**
      * Link an external row signal to this data source.
      *
@@ -507,6 +549,8 @@ declare class AgridDataSource<T extends object = any> {
     private updateRows;
     /** Replace the backing row array without copying. Intended for specialized datasource models. */
     protected setRows(rows: T[]): void;
+    /** @internal Clears the transient filter bypass applied to newly inserted rows. */
+    ɵreapplyFiltersToAddedRows(): void;
 }
 
 /** Sort entry sent to a server-side row datasource. */
@@ -541,6 +585,11 @@ interface AgridServerSideRowModelConfig<T extends object> {
     /** Known initial total. Omit when the server determines it from the first request. */
     initialRowCount?: number;
 }
+/** Refresh behavior for server-side block cache invalidation. */
+interface AgridServerSideRefreshOptions {
+    /** When `true`, clear all cached rows and replace them with placeholders. @default true */
+    purge?: boolean;
+}
 /**
  * Sparse datasource that lazy-loads row blocks while retaining global datasource indices.
  * Attach it to an `AgridProvider` through `serverSideRowModel`.
@@ -552,6 +601,7 @@ declare class AgridServerSideRowModel<T extends object = any> extends AgridDataS
     private slots;
     private readonly loadedBlocks;
     private readonly loadingBlocks;
+    private readonly failedBlocks;
     private query;
     private queryKey;
     private generation;
@@ -569,8 +619,14 @@ declare class AgridServerSideRowModel<T extends object = any> extends AgridDataS
     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;
+    /** Invalidate cached blocks while preserving the current query and known total row count. */
+    refresh(options?: AgridServerSideRefreshOptions): void;
+    /** Clear the block cache and show placeholders until requested blocks are reloaded. */
+    purgeCache(): void;
+    /** Retry the most recently failed block, or a specific block index when supplied. */
+    retryFailedBlock(block?: number): void;
+    /** Failed block indices that can be passed to {@link retryFailedBlock}. */
+    failedBlockIndices(): number[];
     /** 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. */
@@ -742,6 +798,8 @@ interface AgridProviderConfig<T extends object = any> extends Partial<AGridOptio
     autoAddRows?: boolean;
     /** Show a 24 px control column with a drag handle and right-click context menu. */
     showControlColumn?: boolean;
+    /** Show automatic row numbers in the control column instead of the drag-handle glyph. @default false */
+    showRowNumbers?: boolean;
     /** Show row-marking checkboxes in a 48 px control column for clipboard inclusion. @default false */
     enableRowMarking?: boolean;
     /** Allow clicking column headers to mark complete columns. @default false */
@@ -764,6 +822,12 @@ interface AgridProviderConfig<T extends object = any> extends Partial<AGridOptio
      * instead of filtering locally. @default false
      */
     enableQuickFilter?: boolean;
+    /**
+     * Show an Excel-style formula/input bar above the grid body. It displays the selected cell's raw
+     * value and lets users edit it in a wider input. Useful for formula and long text cells.
+     * @default false
+     */
+    showFormulaBar?: boolean;
     /**
      * Optional command bar rendered above the column headers. Buttons and dropdown items emit
      * their id through the grid's single `(menuBarAction)` output.
@@ -831,6 +895,14 @@ interface AgridProviderConfig<T extends object = any> extends Partial<AGridOptio
         row: T;
         index: number;
     }) => string;
+    /**
+     * Optional application-owned predicate applied after built-in client-side filters and quick
+     * filter. Use this for filters that live outside the column menu.
+     */
+    externalFilter?: (params: {
+        row: T;
+        index: number;
+    }) => boolean;
     /**
      * Designate rows to pin to the top or bottom of the grid body. Pinned rows stay visible during
      * vertical scroll and are excluded from grouping and pagination, but remain fully interactive
@@ -915,18 +987,27 @@ declare class AgridProvider<T extends object = any> {
     private readonly _localizations;
     private exportBridge;
     private readonly _visibleRows;
+    private readonly _serverQuery;
     /**
      * The grid's currently filtered and sorted rows, as published by the rendered grid component.
      * Falls back to every datasource row when no grid is attached. Link a chart to this signal to
      * keep it in sync with the grid's filters and sorting.
      */
     readonly visibleRows: Signal<readonly T[]>;
+    /**
+     * Complete server-side filter/sort/page query published by the rendered grid.
+     * Useful for signal-backed stores that fetch data from an API. `null` means the grid is not in
+     * server-side filtering or pagination mode.
+     */
+    readonly serverQuery: Signal<AgridServerQuery | null>;
     /**
      * @internal Published by the rendered grid whenever its filtered/sorted projection changes.
      * Pass `null` on teardown so {@link visibleRows} falls back to the raw datasource. The grid works
      * in terms of record rows; the public {@link visibleRows} re-types them as `T`.
      */
     ɵsetVisibleRows(rows: readonly Record<string, unknown>[] | null): void;
+    /** @internal Published by the rendered grid whenever the server-side query state changes. */
+    ɵsetServerQuery(query: AgridServerQuery | null): void;
     /** Read-only view of registered per-locale text overrides. Used by the grid to resolve locale text. */
     get localizations(): ReadonlyMap<string, AgridLocaleTextOverrides>;
     /**
@@ -948,6 +1029,8 @@ declare class AgridProvider<T extends object = any> {
     allowAddRows: boolean;
     /** Whether the control column is rendered. */
     showControlColumn: boolean;
+    /** Whether the control column displays automatic row numbers. */
+    showRowNumbers: boolean;
     /** Whether rows can be marked for inclusion in clipboard copies. */
     enableRowMarking: boolean;
     /** Whether complete columns can be marked from their headers. */
@@ -962,6 +1045,8 @@ declare class AgridProvider<T extends object = any> {
     filterDebounceMs: number;
     /** Whether the global quick-filter box is shown above the grid. */
     enableQuickFilter: boolean;
+    /** Whether the formula/input bar is shown above the grid body. */
+    showFormulaBar: boolean;
     /** Commands rendered in the optional menu bar above the column headers. */
     menuBarItems: AgridMenuBarItem<T>[];
     /** Enabled sorting mode. */
@@ -995,6 +1080,11 @@ declare class AgridProvider<T extends object = any> {
         row: T;
         index: number;
     }) => string;
+    /** Optional application-owned row predicate applied by the client-side projection. */
+    externalFilter?: (params: {
+        row: T;
+        index: number;
+    }) => boolean;
     /** Optional callback designating rows pinned to the top or bottom of the body. */
     pinRow?: (row: T, index: number) => 'top' | 'bottom' | undefined;
     /** Whether master/detail expandable detail rows are enabled. */
@@ -1206,6 +1296,34 @@ interface ValueOption<TValue = unknown> {
     /** Human-readable label shown in the cell, dropdown, and filter menu. */
     label: string;
 }
+/**
+ * Built-in editor surfaces available without registering a custom Angular component.
+ *
+ * - `'text'` uses the default single-line input.
+ * - `'largeText'` uses a multiline textarea for longer content.
+ * - `'richSelect'` uses a searchable select surface backed by `values` or `asyncValues`.
+ * - `'formula'` uses a formula-friendly input. Pair it with {@link ColDefBase.formula} to
+ *   evaluate strings that start with `=`.
+ */
+type AgridBuiltInEditor = 'text' | 'largeText' | 'richSelect' | 'formula';
+/** Parameters passed to {@link ColDefBase.asyncValues} when the rich-select editor opens. */
+interface AsyncValueOptionsParams<T extends object = any, K extends AgridField<T> = AgridField<T>> {
+    /** Row currently being edited. */
+    row: T;
+    /** Current raw value stored in the edited cell. */
+    value: T[K];
+    /** Column definition for the edited cell. */
+    column: ColDef<T, K>;
+    /** Original datasource index for the edited row. */
+    originalIndex: number;
+}
+/**
+ * Sync or async value options used by the built-in rich-select editor.
+ *
+ * Strings are stored and displayed as-is. {@link ValueOption} entries display `label` while
+ * committing `value` into the datasource.
+ */
+type AgridAsyncValues<TValue = unknown> = readonly (string | ValueOption<TValue>)[] | Promise<readonly (string | ValueOption<TValue>)[]>;
 /** Width sentinel that makes a column fill the remaining horizontal space. */
 declare const ColDefAutoSize = -1;
 /** Label definition for a group displayed above contiguous column headers. */
@@ -1312,6 +1430,24 @@ interface ColDefBase<T extends object, K extends AgridField<T>> {
      *   displayed label (`label`). Useful when the dataset stores IDs but should show names.
      */
     values?: string[] | ValueOption<T[K]>[];
+    /**
+     * Built-in editor to use for this column.
+     * - `'richSelect'` renders a searchable select surface and can load async values.
+     * - `'largeText'` renders a multiline textarea for longer notes.
+     * - `'formula'` renders a formula input. Pair with `formula: true` to evaluate formulas.
+     * - `'text'` forces the default text input.
+     */
+    editor?: AgridBuiltInEditor;
+    /**
+     * Values loaded when the built-in rich-select editor opens. Use this for large or remote option
+     * lists. Static `values` are used immediately; `asyncValues` can return a Promise.
+     */
+    asyncValues?: (params: AsyncValueOptionsParams<T, K>) => AgridAsyncValues<T[K]>;
+    /**
+     * Evaluate strings beginning with `=` as row-local formulas for display, filtering, and export.
+     * Formulas support arithmetic, parentheses, and field-name references from the same row.
+     */
+    formula?: boolean;
     /**
      * Optional display formatter applied when the column has no `values` list.
      * Receives the raw cell value and returns the string to display in the cell.
@@ -1346,6 +1482,16 @@ interface ColDefBase<T extends object, K extends AgridField<T>> {
      * At least one filterable column must exist for the filter row to appear.
      */
     filterable?: boolean;
+    /**
+     * Custom component rendered inside this column's filter menu.
+     * The component injects `AGRID_FILTER_CONTEXT` to read and update the field filter.
+     */
+    filterComponent?: Type<unknown>;
+    /**
+     * Maximum number of value-filter choices rendered at once. Search still runs against the full
+     * value list, then caps the displayed matches. Defaults to `250`.
+     */
+    filterValueLimit?: number;
     /**
      * Set to `true` to allow grouping the grid by this column.
      * When set, the filter dropdown shows a "Group by" toggle for this column.
@@ -1747,6 +1893,32 @@ type CellInfoEvent<T extends object = any> = {
         column: ColDef<T, K>;
     };
 }[AgridField<T>];
+/** Current selected row returned by {@link AgridComponent.getCurrentRow}. */
+interface AgridCurrentRow<T extends object = any> {
+    /** Selected datasource row. */
+    row: T;
+    /** Zero-based row index in the datasource. */
+    originalIndex: number;
+}
+/** Current selected cell returned by {@link AgridComponent.getCurrentCell} and emitted by `(cellSelect)`. */
+type AgridCurrentCell<T extends object = any> = {
+    [K in AgridField<T>]: {
+        /** Selected cell position. */
+        position: CellPosition;
+        /** Datasource row containing the selected cell. */
+        row: T;
+        /** Zero-based row index in the datasource. */
+        originalIndex: number;
+        /** Selected column field. */
+        field: K;
+        /** Current raw field value. */
+        value: T[K];
+        /** Column definition for the selected cell. */
+        column: ColDef<T, K>;
+    };
+}[AgridField<T>];
+/** Emitted when the selected cell changes. `null` means the cell selection was cleared. */
+type CellSelectEvent<T extends object = any> = AgridCurrentCell<T>;
 /**
  * Emitted asynchronously after an edit changes a row and the data source has been updated.
  *
@@ -1889,12 +2061,49 @@ interface PageChangeEvent {
     /** Zero-based index of the last row on this page (inclusive). */
     endRow: number;
 }
-/** Emitted when a header text filter or column-menu condition changes server-side. */
+/** Sort entry used by server-side query snapshots. */
+interface AgridServerSort {
+    /** Field name of the sorted column. */
+    field: string;
+    /** Sort direction for this field. */
+    direction: 'asc' | 'desc';
+}
+/**
+ * Complete server-side query snapshot derived from `AgridControl`.
+ *
+ * It is emitted by `(serverQueryChange)` and published as `AgridProvider.serverQuery` whenever
+ * `serverSideFiltering` is enabled or `AgridControl.totalRows` enables server-side pagination.
+ * `endRow` follows the existing `(pageChange)` event: it is inclusive. Server totals are not part
+ * of the query so updating `control.setTotalRows(...)` after a response does not itself trigger a
+ * second fetch.
+ */
+interface AgridServerQuery {
+    /** Active column filters keyed by field. */
+    filters: Readonly<Record<string, ColumnFilter>>;
+    /** Ordered sort stack after the grid's `sortOption` is applied. */
+    sort: readonly AgridServerSort[];
+    /** Global quick-filter text. Empty string when inactive. */
+    quickFilter: string;
+    /** Current page number (1-based). */
+    page: number;
+    /** Rows per page. `0` means no page size is configured. */
+    pageSize: number;
+    /** Zero-based index of the first requested row. */
+    startRow: number;
+    /** Zero-based index of the last requested row (inclusive), or `-1` when no rows are known. */
+    endRow: number;
+}
+/** Emitted when a header text, value, or column-menu condition changes server-side. */
 interface FilterChangeEvent {
     /** Field name of the filtered column. */
     field: string;
     /** Current free-text filter value. An empty string clears the text filter. */
     value: string;
+    /**
+     * Current value-checklist selection.
+     * `null` means all values are selected / no value filter is active.
+     */
+    selectedValues?: readonly string[] | null;
     /**
      * Text, number, or date condition operator from the column-menu UI.
      * `null` clears the condition.
@@ -2178,7 +2387,7 @@ interface AgridSidebarDetailField {
 }
 
 /**
- * Excel-like data grid for Angular 21.
+ * Excel-like data grid for Angular 21 and 22.
  *
  * ## Minimal setup
  * ```html
@@ -2211,13 +2420,15 @@ declare class AgridComponent<T extends object = any> implements OnChanges {
     readonly autoAddRows: Signal<boolean>;
     readonly enableRowMarking: Signal<boolean>;
     readonly enableColumnMarking: Signal<boolean>;
+    readonly showRowNumbers: Signal<boolean>;
     readonly showControlColumn: Signal<boolean>;
-    readonly controlColumnWidth: Signal<24 | 48>;
+    readonly controlColumnWidth: Signal<number>;
     readonly showSidebar: Signal<boolean>;
     readonly autoOpenDetail: Signal<boolean>;
     readonly serverSideFiltering: Signal<boolean>;
     readonly filterDebounceMs: Signal<number>;
     readonly enableQuickFilter: Signal<boolean>;
+    readonly showFormulaBar: Signal<boolean>;
     readonly menuBarItems: Signal<_thkl_agrid.AgridMenuBarItem<T>[]>;
     readonly quickFilterValue: Signal<string>;
     readonly sortOption: Signal<"single" | "multi" | "none">;
@@ -2243,6 +2454,10 @@ declare class AgridComponent<T extends object = any> implements OnChanges {
         row: Record<string, unknown>;
         index: number;
     }) => string) | undefined>;
+    readonly externalFilterFn: Signal<((params: {
+        row: Record<string, unknown>;
+        index: number;
+    }) => boolean) | 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>;
@@ -2330,6 +2545,8 @@ declare class AgridComponent<T extends object = any> implements OnChanges {
     filterChange: _angular_core.OutputEmitterRef<FilterChangeEvent>;
     /** Emitted when a column sort changes in server-side filtering mode. */
     sortChange: _angular_core.OutputEmitterRef<SortChangeEvent>;
+    /** Emitted with the complete server-side filter/sort/page query snapshot. */
+    serverQueryChange: _angular_core.OutputEmitterRef<AgridServerQuery>;
     /**
      * Emitted (debounced) when the global quick-filter text changes in server-side filtering mode.
      * The host should refetch rows matching the text. Not emitted in client mode, where the grid
@@ -2340,12 +2557,15 @@ declare class AgridComponent<T extends object = any> implements OnChanges {
     validationFailed: _angular_core.OutputEmitterRef<ValidationFailedEvent<any>>;
     /** Emitted when a column's optional cell information button is clicked. */
     cellInfo: _angular_core.OutputEmitterRef<CellInfoEvent<T>>;
+    /** Emitted when the selected cell changes. `null` = cell selection cleared. */
+    cellSelect: _angular_core.OutputEmitterRef<CellSelectEvent<T> | null>;
     /** Emitted for every enabled menu-bar button or dropdown item, carrying its configured id. */
     menuBarAction: _angular_core.OutputEmitterRef<string>;
     /** Emitted if there is a Detail pane Action without text property */
     detailAction: _angular_core.OutputEmitterRef<RowDetailActionEvent<T>>;
     /** Currently focused cell, or `null`. */
     readonly selectedCell: _angular_core.WritableSignal<CellPosition | null>;
+    private lastEmittedCell;
     /** Original indices of rows whose master/detail panel is currently expanded. */
     private readonly _expandedDetailIds;
     /**
@@ -2354,9 +2574,13 @@ declare class AgridComponent<T extends object = any> implements OnChanges {
      * provider predicate by {@link effectivePinRow}.
      */
     private readonly _pinnedRows;
+    readonly formulaBarDraft: _angular_core.WritableSignal<string>;
+    private readonly formulaBarFocused;
+    private formulaBarEditCell;
     private readonly markedIndices;
     private readonly markedFields;
     private firstDataRenderedEmitted;
+    private serverQueryProvider;
     /** Original datasource indices marked for inclusion in copy operations. */
     readonly markedRowIndices: Signal<ReadonlySet<number>>;
     /** Fields currently marked as complete columns. */
@@ -2375,6 +2599,13 @@ declare class AgridComponent<T extends object = any> implements OnChanges {
     get editSeedChar(): _angular_core.WritableSignal<string>;
     /** Whether the active text editor should select all text when it opens. */
     get selectTextOnEdit(): _angular_core.WritableSignal<boolean>;
+    /** Return the first currently selected row, or `null` when no row is selected. */
+    getCurrentRow(): AgridCurrentRow<T> | null;
+    /** Return the currently selected cell with row, field, value, and column metadata. */
+    getCurrentCell(): AgridCurrentCell<T> | null;
+    readonly formulaBarLabel: Signal<string>;
+    private resolveCurrentCell;
+    private sameCell;
     /** Toggle the sidebar open/closed. */
     toggleSidebar(): void;
     /** @internal */
@@ -2468,6 +2699,10 @@ declare class AgridComponent<T extends object = any> implements OnChanges {
     readonly pinnedBodyColumns: Signal<AgridBodyColumn[]>;
     readonly scrollableBodyColumns: Signal<AgridBodyColumn[]>;
     readonly rightBodyColumns: Signal<AgridBodyColumn[]>;
+    /** @internal Whether a pane needs per-cell span resolution. */
+    readonly pinnedPaneHasSpans: Signal<boolean>;
+    readonly scrollablePaneHasSpans: Signal<boolean>;
+    readonly rightPaneHasSpans: Signal<boolean>;
     /**
      * Resolves the per-column bindings shared by every data, footer, and ghost cell. Reads only
      * layout/drag/pinning signals, so the result is reused across all rows and recomputes only
@@ -2531,6 +2766,10 @@ declare class AgridComponent<T extends object = any> implements OnChanges {
     /** Virtual scroll source — injects ghost row during a reorder drag. */
     /** Maps originalIndex → true if the data row should receive the odd-row stripe. Counts only data rows, so group headers don't shift the pattern. */
     readonly dataRowIsOdd: Signal<Map<number, boolean>>;
+    /** Maps originalIndex → 1-based filtered/sorted row number for the control column. */
+    readonly rowNumbers: Signal<Map<number, number>>;
+    /** Width needed for the largest currently rendered row number. */
+    readonly rowNumberColumnWidth: Signal<number>;
     readonly displayItems: Signal<GridItem[]>;
     /** Rows pinned to the top of the body (rendered in a fixed container, outside virtual scroll). */
     readonly pinnedTopItems: Signal<{
@@ -2654,15 +2893,20 @@ declare class AgridComponent<T extends object = any> implements OnChanges {
     private readonly dirtyInlineRows;
     private dirtyRowsDataSource;
     private changedCellsDataSource;
+    private dirtyInlineRowsIdleTimer;
+    private readonly dirtyInlineRowsIdleFlushMs;
     private emitEditEvents;
     private emitSidebarEditEvents;
     private emitRecordEdit;
     private markInlineRowDirty;
     private markCellChanged;
     private flushDirtyInlineRows;
+    private scheduleDirtyInlineRowsIdleFlush;
+    private clearDirtyInlineRowsIdleFlush;
     private reconcileDirtyInlineRowsAfterRemoval;
     private emitRowChanged;
     private createRecordEvent;
+    private buildServerQuery;
     constructor();
     /** @internal */
     isDataRowItem(item: GridItem): item is {
@@ -2684,6 +2928,8 @@ declare class AgridComponent<T extends object = any> implements OnChanges {
     isPathTreeNodeItem(item: GridItem): boolean;
     /** @internal */
     getItemOriginalIndex(item: GridItem): number | null;
+    /** @internal 1-based row number for visible data rows. */
+    visibleRowNumber(item: GridItem): number | null;
     /** @internal True when the item is a master/detail panel row. */
     isDetailRowItem(item: GridItem): item is DetailRowItem;
     /** @internal Rendered pixel height of a virtual-scroll item (detail panels are taller). */
@@ -2786,6 +3032,8 @@ declare class AgridComponent<T extends object = any> implements OnChanges {
     /** @internal Whether more than one column is currently sorted. */
     hasMultiSort(): boolean;
     getTextFilter(field: string): string;
+    /** @internal Complete filter snapshot for custom filter components. */
+    getColumnFilter(field: string): ColumnFilter;
     /** @internal Condition input type for a column, or `null` when unsupported. */
     getMenuFilterType(field: string): 'text' | 'number' | 'date' | null;
     /** @internal Short label for an active header condition. */
@@ -2845,6 +3093,18 @@ declare class AgridComponent<T extends object = any> implements OnChanges {
     onStartEdit(originalIndex: number, ci: number): void;
     /** @internal */
     onDraftChange(value: unknown): void;
+    /** @internal */
+    onFormulaBarFocus(): void;
+    /** @internal */
+    onFormulaBarInput(event: Event): void;
+    /** @internal */
+    onFormulaBarBlur(): void;
+    /** @internal */
+    onFormulaBarKeydown(event: KeyboardEvent): void;
+    /** @internal */
+    commitFormulaBar(targetCell?: CellPosition | null): boolean;
+    private finishFormulaBarInteraction;
+    private resetFormulaBarDraft;
     /** @internal A custom cell editor requested a commit (e.g. picking a value). */
     onEditorCommit(): void;
     /** @internal A custom cell editor requested cancellation. */
@@ -2865,6 +3125,7 @@ declare class AgridComponent<T extends object = any> implements OnChanges {
     onCellPointerDown(event: PointerEvent, originalIndex: number, colIndex: number): void;
     /** @internal Main keyboard handler delegated from the wrapper div. */
     onKeyDown(event: KeyboardEvent): void;
+    private isToolbarInputEvent;
     /** @internal Clears cell navigation while a header filter control owns focus. */
     onGridFocusIn(event: FocusEvent): void;
     /** Open the find panel and focus its input. */
@@ -2979,12 +3240,19 @@ declare class AgridComponent<T extends object = any> implements OnChanges {
     /** @internal */
     onMenuToggleValue(field: string, rawStr: string): void;
     /** @internal */
+    onMenuReplaceFilter(field: string, filter: ColumnFilter): void;
+    /** @internal */
     onSidebarToggleColumn(field: string): void;
     /** @internal Sets every column in a sidebar header group to the requested visibility. */
     onSidebarToggleColumnGroup(fields: string[], visible: boolean): void;
     /** @internal Mirrors vertical scrolling from the main viewport into both pinned panes. */
     onBodyScroll(): void;
     private ensureServerRowsVisible;
+    /** Refresh the attached server-side row model and optionally reset vertical scroll to row zero. */
+    refreshServerSideRows(options?: {
+        purge?: boolean;
+        resetScroll?: boolean;
+    }): void;
     /** @internal Keeps the row-delete prompt visible while columns scroll horizontally. */
     onHorizontalScroll(): void;
     /** @internal Refreshes the scroll offset / viewport width driving column virtualization. */
@@ -3023,7 +3291,7 @@ declare class AgridComponent<T extends object = any> implements OnChanges {
     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"; "rowMark": "rowMark"; "columnMark": "columnMark"; "columnHeaderAction": "columnHeaderAction"; "firstDataRendered": "firstDataRendered"; "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"; "detailAction": "detailAction"; }, 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"; "rowMark": "rowMark"; "columnMark": "columnMark"; "columnHeaderAction": "columnHeaderAction"; "firstDataRendered": "firstDataRendered"; "rowDoubleClicked": "rowDoubleClicked"; "rowClick": "rowClick"; "treeNodeClick": "treeNodeClick"; "settingsChange": "settingsChange"; "treeNodeDoubleClicked": "treeNodeDoubleClicked"; "rowChanged": "rowChanged"; "pageChange": "pageChange"; "filterChange": "filterChange"; "sortChange": "sortChange"; "serverQueryChange": "serverQueryChange"; "quickFilterChange": "quickFilterChange"; "validationFailed": "validationFailed"; "cellInfo": "cellInfo"; "cellSelect": "cellSelect"; "menuBarAction": "menuBarAction"; "detailAction": "detailAction"; }, never, never, true, never>;
 }
 
 /** Identifier supported by the standalone page selector. */
@@ -3250,6 +3518,42 @@ interface AgridRendererContext<TValue = unknown> {
 /** DI token a custom {@link ColDef.cellRendererComponent} component injects to read cell data. */
 declare const AGRID_RENDERER_CONTEXT: InjectionToken<AgridRendererContext<unknown>>;
 
+/**
+ * Runtime context handed to a custom column-filter component through dependency injection.
+ *
+ * Custom filters should write normal {@link ColumnFilter} state through {@link setFilter}. That
+ * keeps filter persistence, server query generation, and the active-filter header state aligned
+ * with built-in filters.
+ *
+ * @example
+ * ```ts
+ * const ctx = inject(AGRID_FILTER_CONTEXT);
+ * ctx.setFilter({ ...ctx.filter(), text: 'active' });
+ * ```
+ */
+interface AgridFilterContext {
+    /** Field currently being filtered. */
+    readonly field: string;
+    /** Column definition for the active filter menu. */
+    readonly column: ColDef;
+    /** Shared grid control that owns filter state. */
+    readonly control: AgridControl | null;
+    /** Current filter snapshot for this field. */
+    readonly filter: Signal<ColumnFilter>;
+    /** Replace this field's filter state, preserving any fields the component copies forward. */
+    setFilter(filter: ColumnFilter): void;
+    /** Clear this field's filter state. */
+    clear(): void;
+    /** Close the column menu. */
+    close(): void;
+}
+/**
+ * DI token a custom {@link ColDef.filterComponent} injects to control column filtering.
+ *
+ * The token is only available while the component is rendered inside an aGrid column menu.
+ */
+declare const AGRID_FILTER_CONTEXT: InjectionToken<AgridFilterContext>;
+
 /**
  * Zero-dependency chart geometry. Pure math that turns a typed dataset + a diagram type into flat
  * SVG primitives (bars, line/area paths, pie slices, gridlines, labels), so the chart component
@@ -3440,6 +3744,6 @@ declare class AgridChartComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<AgridChartComponent, "agrid-chart", never, { "provider": { "alias": "provider"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
-export { AGRID_CHART_PALETTE, AGRID_EDITOR_CONTEXT, AGRID_LOCALE_TEXT, AGRID_RENDERER_CONTEXT, AgridBrowserAdapter, AgridChartComponent, AgridChartProvider, AgridComponent, AgridControl, AgridDataSource, AgridPageSelectorComponent, AgridProvider, AgridServerSideRowModel, AgridTreeComponent, AgridTreeProvider, ColDefAutoSize, buildChart };
-export type { AgridAggregate, AgridChartData, AgridChartLayout, AgridChartOptions, AgridChartProviderConfig, AgridChartSeries, AgridChartType, AgridColumnHeaderMenuItem, AgridControlState, AgridEditorContext, AgridEnterEditAction, AgridField, AgridLocaleKey, AgridLocaleText, AgridLocaleTextOverrides, AgridMenuBarContext, AgridMenuBarItem, AgridMenuBarMenuItem, AgridMenuBarState, AgridPageId, AgridPageItem, AgridParentTreeConfig, AgridPathSegmentParams, AgridPathTreeConfig, AgridPivotConfig, AgridPivotSettings, AgridProviderConfig, AgridRendererContext, AgridRowIndication, AgridSelectionSummary, AgridServerSideDatasource, AgridServerSideRequest, AgridServerSideResult, AgridServerSideRowModelConfig, AgridServerSideSort, AgridSettings, AgridTreeConfig, AgridTreeNodeEvent, AgridTreeProviderConfig, AgridTreeSelectionEvent, AgridTreeSelectionMode, CellContextMenuItem, CellFormat, CellFormatParams, CellInfoEvent, CellPosition, CellReadonlyParams, CellSpanParams, ColDef, ColumnFilter, ColumnHeaderActionEvent, ColumnMarkEvent, DetailAction, DetailActionParams, DetailRowItem, FilterChangeEvent, FilterOperator, FirstDataRenderedEvent, GridEditEvent, GroupAction, HeaderGroup, HistoryEntry, HistoryItem, InputMaskParams, NewRecord, PageChangeEvent, PathTreeNodeItem, RecordEditEvent, RowClickEvent, RowMarkEvent, RowRemovedEvent, RowReorderEvent, RowSelectEvent, RowUpdateEvent, SortChangeEvent, TreeNodeClickEvent, TreeRowItem, ValidationFailedEvent, ValueOption };
+export { AGRID_CHART_PALETTE, AGRID_EDITOR_CONTEXT, AGRID_FILTER_CONTEXT, AGRID_LOCALE_TEXT, AGRID_RENDERER_CONTEXT, AgridBrowserAdapter, AgridChartComponent, AgridChartProvider, AgridComponent, AgridControl, AgridDataSource, AgridPageSelectorComponent, AgridProvider, AgridServerSideRowModel, AgridTreeComponent, AgridTreeProvider, ColDefAutoSize, buildChart };
+export type { AgridAggregate, AgridAsyncValues, AgridBuiltInEditor, AgridChartData, AgridChartLayout, AgridChartOptions, AgridChartProviderConfig, AgridChartSeries, AgridChartType, AgridColumnHeaderMenuItem, AgridControlState, AgridCurrentCell, AgridCurrentRow, AgridEditorContext, AgridEnterEditAction, AgridField, AgridFilterContext, AgridLocaleKey, AgridLocaleText, AgridLocaleTextOverrides, AgridMenuBarContext, AgridMenuBarItem, AgridMenuBarMenuItem, AgridMenuBarState, AgridPageId, AgridPageItem, AgridParentTreeConfig, AgridPathSegmentParams, AgridPathTreeConfig, AgridPivotConfig, AgridPivotSettings, AgridProviderConfig, AgridRendererContext, AgridRowIndication, AgridSelectionSummary, AgridServerQuery, AgridServerSideDatasource, AgridServerSideRefreshOptions, AgridServerSideRequest, AgridServerSideResult, AgridServerSideRowModelConfig, AgridServerSideSort, AgridServerSort, AgridSettings, AgridTreeConfig, AgridTreeNodeEvent, AgridTreeProviderConfig, AgridTreeSelectionEvent, AgridTreeSelectionMode, AsyncValueOptionsParams, CellContextMenuItem, CellFormat, CellFormatParams, CellInfoEvent, CellPosition, CellReadonlyParams, CellSelectEvent, CellSpanParams, ColDef, ColumnFilter, ColumnHeaderActionEvent, ColumnMarkEvent, DetailAction, DetailActionParams, DetailRowItem, FilterChangeEvent, FilterOperator, FirstDataRenderedEvent, GridEditEvent, GroupAction, HeaderGroup, HistoryEntry, HistoryItem, InputMaskParams, NewRecord, PageChangeEvent, PathTreeNodeItem, RecordEditEvent, RowClickEvent, RowMarkEvent, RowRemovedEvent, RowReorderEvent, RowSelectEvent, RowUpdateEvent, SortChangeEvent, TreeNodeClickEvent, TreeRowItem, ValidationFailedEvent, ValueOption };
 //# sourceMappingURL=thkl-agrid.d.ts.map