ag-grid-community 35.3.0 → 36.0.0

package/dist/types/src/entities/colDef-showValuesAs.d.ts

@@ -0,0 +1,228 @@
+import type { Column } from '../interfaces/iColumn';
+import type { AgGridCommon } from '../interfaces/iCommon';
+import type { IRowNode } from '../interfaces/iRowNode';
+import type { MenuItemDef } from '../interfaces/menuItem';
+import type { ValueFormatterParams } from './colDef';
+import type { BaseCellDataType } from './dataType';
+/** Built-in "Show Values As" mode names. */
+export type ShowValuesAsBuiltInType = 'percentOfGrandTotal' | 'percentOfColumnTotal' | 'percentOfRowTotal' | 'percentOfParentRowTotal' | 'percentOfParentColumnTotal';
+/** A built-in mode name. The open string form is retained so a serialised column-state value round-trips. */
+export type ShowValuesAsType = ShowValuesAsBuiltInType | (string & {});
+/**
+ * Whether a mode applies in the current view (the result of {@link ShowValuesAsModeDef.applicability}). Drives both the
+ * transform (an inapplicable mode shows the raw value) and how the mode appears in the column menu.
+ * - `true` / `'enabled'` (default `true`): applicable - the transform runs and the menu shows it normally.
+ * - `'inapplicable'`: not applicable in this view - shown greyed and non-interactive (it shows the raw value).
+ *   An active selection that becomes inapplicable still shows checked, but is changed away from by choosing an
+ *   applicable mode.
+ * - `'disabled'`: not applicable - shown greyed and non-interactive (the menu item is disabled altogether).
+ * - `'hide'` / `false`: not applicable - omitted from the menu, except the active selection, which is kept (greyed
+ *   but still selectable) so it stays visible and changeable.
+ */
+export type ShowValuesAsApplicability = boolean | 'enabled' | 'inapplicable' | 'disabled' | 'hide';
+/** Output of a transform; `null` renders a blank cell. */
+export type ShowValuesAsResult = number | bigint | string | boolean | Date | object;
+/**
+ * Object form of the `showValuesAs` selector. Use the bare string form for modes that need no input.
+ */
+export type ShowValuesAs = {
+    /** The mode name. */
+    type: ShowValuesAsType;
+    /** Mode input. */
+    params?: any;
+    /** Decimal places for the built-in formatters; overrides `showValuesAsDef.precision`. */
+    precision?: number;
+};
+/** A column-state `showValuesAs` value: a mode name, the object form, or `null` for no active mode. */
+export type ShowValuesAsStateValue = ShowValuesAsType | ShowValuesAs | null;
+/** A custom transform: maps the cell's raw value (`TValue`) to the output (`TOut`), or `null` for a blank cell. */
+export type ShowValuesAsTransform<TData = any, TValue = any, TOut extends ShowValuesAsResult = ShowValuesAsResult, TParams = any> = (params: ShowValuesAsTransformParams<TData, TValue, TParams>) => TOut | null;
+/** Params passed to a mode's {@link ShowValuesAsTransform}. Beyond the raw value it exposes the totals and the
+ *  base/sibling value accessors the built-in modes are built from. */
+export interface ShowValuesAsTransformParams<TData = any, TValue = any, TParams = any> extends AgGridCommon<TData, any> {
+    /** The cell's value (the numerator), resolved to a scalar - agg wrappers (e.g. `avg`) unwrapped. */
+    rawValue: TValue | null | undefined;
+    /** The raw aggregation value before unwrapping (e.g. `{ value, count }` for `avg`); else equal to `rawValue`. */
+    aggValue: any;
+    /** The row node the cell belongs to. */
+    node: IRowNode<TData>;
+    /** The column the cell belongs to. */
+    column: Column<TValue>;
+    /** The mode's input - the def's `params` overlaid with the selector's. */
+    params: TParams;
+    /** Column grand total. */
+    grandTotal(): number | null;
+    /** Equal to `grandTotal()` unless pivoting, where it is this pivot column's overall total. */
+    columnTotal(): number | null;
+    /** The immediate row-axis parent's value. */
+    parentTotal(): number | null;
+    /** The immediate pivot-column-axis parent's value; `null` when not pivoting. */
+    parentColumnTotal(): number | null;
+    /** Sum of value columns on this row. */
+    rowTotal(): number | null;
+}
+/** Context for a mode's {@link ShowValuesAsModeDef.applicability} callback - the current grouping / tree / pivot state. */
+export interface ShowValuesAsApplicabilityParams<TData = any, TValue = any, TContext = any> extends AgGridCommon<TData, TContext> {
+    /** The column the mode is offered on. */
+    column: Column<TValue>;
+    /** Whether row grouping is active; `undefined` when the Row Grouping module is not registered. */
+    rowGroupActive: boolean | undefined;
+    /** Whether tree data is active; `undefined` when the Tree Data module is not registered. */
+    treeData: boolean | undefined;
+    /** Whether pivot mode is active; `undefined` when the Pivot module is not registered. */
+    pivotActive: boolean | undefined;
+}
+/** Params passed to a mode's {@link ShowValuesAsModeDef.formatter}. The column's {@link ValueFormatterParams} with
+ *  the transformed `value` plus the pre-transform `rawValue` / `aggValue`. */
+export interface ShowValuesAsFormatterParams<TData = any, TValue = any, TOut extends ShowValuesAsResult = ShowValuesAsResult> extends Omit<ValueFormatterParams<TData, TValue>, 'value'> {
+    /** The transformed value being formatted. */
+    value: TOut | null | undefined;
+    /** The active mode's name. */
+    showValuesAsType: ShowValuesAsType;
+    /** The pre-transform value, resolved to a scalar. */
+    rawValue: TValue | null | undefined;
+    /** The raw aggregation value before unwrapping; else equal to `rawValue`. */
+    aggValue: any;
+    /** Effective decimal places (selection's, else `showValuesAsDef.precision`). */
+    precision?: number;
+    /** The transform did not run - the mode is the active selection but either not applicable in the current view
+     *  or awaiting input ({@link ShowValuesAsModeDef.ready}) - so `value` is the raw value. The built-in formatters
+     *  return `#N/A`; a custom formatter can honour or ignore it. */
+    notApplicable: boolean;
+}
+/** The candidate columns a "Show Values As" mode can offer in its menu - the active row-group / pivot / value
+ *  columns, each excluding the mode's own column - plus the {@link getColumn} / {@link dimensionItems} helpers. */
+export interface ShowValuesAsColumnLists {
+    /** The column the menu is for. */
+    readonly column: Column;
+    /** Active row-group fields. */
+    readonly rowGroups: Column[];
+    /** Active dimension fields - the row-group fields, plus the pivot fields while pivoting. */
+    readonly dimensions: Column[];
+    /** Value (aggregated) columns other than this one - e.g. to compare one measure against another. */
+    readonly valueColumns: Column[];
+    /** Distinct items (display order) of a dimension field - its pivot keys while pivoting, else its row-group
+     *  keys. */
+    dimensionItems(field: string | Column): string[];
+    /** Returns the column for the given id, or `null` if not found. */
+    getColumn(colId: string): Column | null;
+}
+/**
+ * Params for {@link ShowValuesAsModeDef.menu} - build a mode's column-menu submenu imperatively, returning
+ * `(MenuItemDef | string)[]` like `getMainMenuItems`. Call {@link apply} from a menu item's `action` (or from
+ * your own dialog) to select the mode and commit its params. {@link columnLists} provides the candidate
+ * columns and the `getColumn` / `dimensionItems` helpers the built-in modes use.
+ */
+export interface ShowValuesAsMenuParams<TData = any, TValue = any, TParams = any, TContext = any> extends AgGridCommon<TData, TContext> {
+    /** The column the menu is for. */
+    readonly column: Column<TValue>;
+    /** This mode's current selection params, when it is the active selection (else `undefined`). */
+    readonly currentParams: TParams | undefined;
+    /** Whether this mode is the active selection. */
+    readonly active: boolean;
+    /** The candidate columns for the mode's menu, plus the `getColumn` / `dimensionItems` helpers. */
+    readonly columnLists: ShowValuesAsColumnLists;
+    /** The mode's type. */
+    readonly type: ShowValuesAsType;
+    /** Select this mode and commit its params (omit to clear them); updates the selection and re-renders. Call
+     *  it from a menu item's `action` or after your own dialog commits. */
+    apply(params?: TParams): void;
+}
+/** A "Show Values As" mode. `TValue` is the input type, `TOut` the output. */
+export interface ShowValuesAsModeDef<TData = any, TValue = any, TOut extends ShowValuesAsResult = ShowValuesAsResult, TParams = any> {
+    /** Maps the cell's raw value to the displayed value. Omit it for a pass-through mode that shows the raw
+     *  value but overrides the formatter / `transformedDataType`. */
+    transform?: ShowValuesAsTransform<TData, TValue, TOut, TParams>;
+    /** Agg func name used to aggregate the column for this mode (it shows a value relative to an aggregated
+     *  total). Selecting it on a not-yet-aggregated column promotes the column to a value column with this func;
+     *  a column with its own agg func keeps it. Unset ⇒ the mode needs no aggregation. */
+    defaultAggFunc?: string;
+    /** Default params, overlaid by the selector's. */
+    params?: TParams;
+    /** Label for the column menu, falling back to the mode name. A callback is re-evaluated on each menu/header
+     *  render — use it to return localised text so the label follows a runtime locale change. */
+    displayName?: string | (() => string);
+    /** Explains the calculation; shown as the menu item's and the header indicator's tooltip. A callback is
+     *  re-evaluated on render (see {@link displayName}). */
+    description?: string | (() => string);
+    /** Formats this mode's transformed value; falls back to the transformed data type's default formatter. */
+    formatter?: (params: ShowValuesAsFormatterParams<TData, TValue, TOut>) => string;
+    /** Data type of the transformed value (default `'number'`) - selects its default formatter, regardless of
+     *  the column's raw `cellDataType`. */
+    transformedDataType?: BaseCellDataType | (string & {});
+    /** Whether this mode applies in the current view - a constant or a per-view test. `true` (the default) means
+     *  applicable: the transform runs and the menu shows it. Otherwise the raw value is shown; the value chooses
+     *  how the menu presents it (`'inapplicable'` greys it but keeps it selectable, `'disabled'` greys it and
+     *  disables it, `'hide'`/`false` omit it) - see {@link ShowValuesAsApplicability}. */
+    applicability?: ShowValuesAsApplicability | ((params: ShowValuesAsApplicabilityParams<TData, TValue>) => ShowValuesAsApplicability);
+    /** Whether the mode's input is configured enough to transform. `false` leaves `value` untransformed (raw) and
+     *  the formatter still runs with `notApplicable` set - so the built-in formatters show `#N/A` until input is
+     *  chosen. The mode stays selectable; its menu is how you configure it. Unlike {@link applicability}, this is
+     *  about input, not the view. E.g. `% Of` is not ready until a base is chosen. Defaults to ready. */
+    ready?: (params: TParams) => boolean;
+    /** Builds this mode's column-menu submenu, returning `(MenuItemDef | string)[]` like `getMainMenuItems`.
+     *  Called when the submenu is built (not on click). Return a single item to collapse to its `action` (e.g.
+     *  open a dialog and `apply` on click), or nothing for a mode that just applies when selected. Use
+     *  `params.apply(modeParams)` to commit a selection. See {@link ShowValuesAsMenuParams}. */
+    menu?: (params: ShowValuesAsMenuParams<TData, TValue, TParams>) => (MenuItemDef | string)[] | void;
+}
+/** Registry for user-provided "Show Values As" modes and overrides of the built-ins (`showValuesAsDef.modes`).
+ *  A partial entry deep-merges over the built-in of the same name (a new mode without a `transform` shows the raw
+ *  value); `true` re-enables a disabled mode; `false`/`null` disables one. A function receives the built-in def
+ *  (or `undefined` for a new mode) and returns the override - use it to wrap a default, e.g. call the original
+ *  `transform`. */
+export type ShowValuesAsModesDef<TData = any, TValue = any> = {
+    [name: string]: Partial<ShowValuesAsModeDef<TData, TValue>> | boolean | null | ((base: ShowValuesAsModeDef<TData, TValue> | undefined) => Partial<ShowValuesAsModeDef<TData, TValue>>);
+};
+/** Per-column config (`colDef.showValuesAsDef`); deep-merges from `defaultColDef`. The active mode is the
+ *  separate `colDef.showValuesAs` selector. */
+export interface ShowValuesAsDef<TData = any, TValue = any> {
+    /** Default decimal places for the built-in formatters (default `2`); overridable per selection. */
+    precision?: number;
+    /** Suppress the column-header indicator shown while a mode is active. */
+    suppressHeaderIndicator?: boolean;
+    /** User-provided modes and overrides of the built-ins, deep-merged over them (grid-wide when set on
+     *  `defaultColDef.showValuesAsDef`). */
+    modes?: ShowValuesAsModesDef<TData, TValue>;
+}
+/** One mode resolved for a column: the merged def with its formatter and transformed data type. */
+export interface ShowValuesAsModeDefResolved<TData = any, TValue = any, TOut extends ShowValuesAsResult = ShowValuesAsResult> {
+    /** The mode name. */
+    type: ShowValuesAsType;
+    /** The mode's effective definition (built-in defaults with the column's overrides applied). */
+    def: ShowValuesAsModeDef<TData, TValue, TOut>;
+    /** Transformed-value formatter; `null` uses the cell's default rendering. */
+    formatter: ((params: ShowValuesAsFormatterParams<TData, TValue, TOut>) => string) | null;
+    /** Resolved data type of the transformed value; `'number'` by default. */
+    transformedDataType: BaseCellDataType | (string & {});
+}
+/** A column's resolved config: every available mode plus the default precision. Not parameterised by output
+ *  type - each mode in {@link modes} carries its own. */
+export interface ShowValuesAsDefResolved<TData = any, TValue = any> {
+    /** Every available mode, keyed by name. */
+    modes: {
+        [type: string]: ShowValuesAsModeDefResolved<TData, TValue>;
+    };
+    /** Default formatter precision (decimal places); `2` when unset. */
+    precision: number;
+    /** Suppress the column-header indicator while a mode is active. */
+    suppressHeaderIndicator: boolean | undefined;
+}
+/** The column's active "Show Values As": the resolved mode plus the selection's params and precision. */
+export interface ShowValuesAsResolved<TData = any, TValue = any, TOut extends ShowValuesAsResult = ShowValuesAsResult, TParams = any> extends ShowValuesAsModeDefResolved<TData, TValue, TOut> {
+    /** The selection's params, passed to the transform verbatim. */
+    params: TParams | undefined;
+    /** Effective formatter precision (decimal places): the selection's, else the config default. */
+    precision: number;
+}
+/** Internal view of {@link ShowValuesAsResolved} stored on `AgColumn` - adds a transient applicability memo not
+ *  exposed on the public `Column.getShowValuesAs()` surface.
+ *  @internal AG_GRID_INTERNAL - Not for public use. Can change / be removed at any time. */
+export interface AgShowValuesAsResolved<TData = any, TValue = any, TOut extends ShowValuesAsResult = ShowValuesAsResult, TParams = any> extends ShowValuesAsResolved<TData, TValue, TOut, TParams> {
+    /** Grouping/pivot/tree-data signature the memoised {@link _applyingValue} was computed under; cleared
+     *  whenever the mode is re-resolved, so a stale value never matches the current signature. */
+    _applyingSig: number;
+    /** Memoised applicability of {@link ShowValuesAsModeDef.applicability} for {@link _applyingSig}; valid only while
+     *  the signatures match. */
+    _applyingValue: boolean;
+}

package/dist/types/src/entities/colDef.d.ts

@@ -1,4 +1,3 @@
-import type { SortDef, SortDirection, SortType } from '../agStack/utils/aria';
 import type { CellClickedEvent, CellContextMenuEvent, CellDoubleClickedEvent } from '../events';
 import type { ICellEditorParams } from '../interfaces/iCellEditor';
 import type { Column, ColumnGroup, ColumnGroupShowType, ProvidedColumnGroup } from '../interfaces/iColumn';
@@ -7,15 +6,16 @@ import type { IFilterDef } from '../interfaces/iFilter';
 import type { ILoadingCellRendererParams } from '../interfaces/iLoadingCellRenderer';
 import type { RowDragTextFunc } from '../interfaces/iRowDragItem';
 import type { IRowNode } from '../interfaces/iRowNode';
+import type { SortDef, SortDirection, SortType } from '../interfaces/iSort';
 import type { DefaultMenuItem, MenuItemDef } from '../interfaces/menuItem';
 import type { ICellRendererParams } from '../rendering/cellRenderers/iCellRenderer';
 import type { ITooltipParams } from '../tooltip/tooltipComponent';
 import type { Icons } from '../utils/icon';
 import type { BaseColDefOptionalDataParams, BaseColDefParams, ChangedValueParams, ColumnFunctionCallbackParams } from './colDef-base';
 import type { GroupRowEditableCallback, GroupRowValueSetterFunc, GroupRowValueSetterOptions } from './colDef-groupRowValueSetter';
+import type { ShowValuesAs, ShowValuesAsDef, ShowValuesAsType } from './colDef-showValuesAs';
 import type { GetContextMenuItems, GetMainMenuItems, RowClassParams } from './gridOptions';
 export type { BaseColDefParams, ColumnFunctionCallbackParams } from './colDef-base';
-export type { SortDirection, SortType, SortDef, DisplaySortDef } from '../agStack/utils/aria';
 /** AbstractColDef can be a group or a column definition */
 export interface AbstractColDef<TData = any, TValue = any> {
     /** The name to render in the column header. If not specified and field is specified, the field name will be used as the header name. */
@@ -24,6 +24,7 @@ export interface AbstractColDef<TData = any, TValue = any> {
     headerValueGetter?: string | HeaderValueGetterFunc<TData, TValue>;
     /**
      * Tooltip for the column header, `headerTooltipValueGetter` takes precedence if set.
+     * When the column is grouped with `groupDisplayType: 'multipleColumns'`, the generated group column header inherits this value.
      * @agModule `TooltipModule`
      */
     headerTooltip?: string;
@@ -60,6 +61,7 @@ export interface AbstractColDef<TData = any, TValue = any> {
     /**
      * Provide your own tooltip component for the column.
      * See [Tooltip Component](https://www.ag-grid.com/javascript-data-grid/tooltips/) for framework specific implementation details.
+     * When the column is grouped, group rows in the generated group column inherit this component.
      * @agModule `TooltipModule`
      */
     tooltipComponent?: any;
@@ -116,7 +118,7 @@ export interface ColGroupDef<TData = any> extends AbstractColDef<TData> {
     suppressStickyLabel?: boolean;
     /**
      * The custom header group component to be used for rendering the component header. If none specified the default AG Grid is used.
-     * See [Header Group Component](https://www.ag-grid.com/javascript-data-grid/component-header/#header-group-components) for framework specific implementation details.
+     * See [Header Group Component](https://www.ag-grid.com/javascript-data-grid/column-headers/#header-group-components) for framework specific implementation details.
      */
     headerGroupComponent?: any;
     /** The params used to configure the `headerGroupComponent`. */
@@ -138,6 +140,7 @@ export type IAggFunc<TData = any, TValue = any, TContext = any> = (params: IAggF
 export type IAggFuncs<TData = any, TValue = any, TContext = any> = {
     [key: string]: IAggFunc<TData, TValue, TContext>;
 };
+export type ColAggFunc<TData = any, TValue = any> = string | IAggFunc<TData, TValue> | null | undefined;
 /**
  * Wrapper returned by the built-in `avg` and `count` aggregation functions, and the recommended
  * shape for custom agg functions that expose a scalar value alongside metadata (e.g. a count, used
@@ -253,6 +256,13 @@ export interface ColDef<TData = any, TValue = any> extends AbstractColDef<TData,
      * @agModule `FormulaModule`
      */
     allowFormula?: boolean;
+    /**
+     * Expression used to calculate this column's value from other columns in the same row.
+     * Use bracket references to read other columns by `colId`, e.g. `[revenue] - [cost]`.
+     * Calculated columns are read-only.
+     * @agModule `CalculatedColumnsModule`
+     */
+    calculatedExpression?: string;
     /** Function or expression. Gets the value from your data for display. */
     valueGetter?: string | ValueGetterFunc<TData, TValue>;
     /** A function or expression to format a value, should return a string. */
@@ -272,12 +282,14 @@ export interface ColDef<TData = any, TValue = any> extends AbstractColDef<TData,
     equals?: EqualsFunc<TValue>;
     /**
      * The field of the tooltip to apply to the cell.
+     * When the column is grouped, group rows in the generated group column inherit this value.
      * @agModule `TooltipModule`
      */
     tooltipField?: ColDefField<TData>;
     /**
      * Callback that should return the string to use for a tooltip, `tooltipField` takes precedence if set.
      * If using a custom `tooltipComponent` you may return any custom value to be passed to your tooltip component.
+     * When the column is grouped, group rows in the generated group column inherit this callback.
      * @agModule `TooltipModule`
      */
     tooltipValueGetter?: TooltipValueGetterFunc<TData, TValue>;
@@ -376,7 +388,7 @@ export interface ColDef<TData = any, TValue = any> extends AbstractColDef<TData,
      * the built-in {@link distributeGroupValue | distributeGroupValue} is used automatically.
      *
      * Columns with `groupRowEditable` or `groupRowValueSetter` do not require `field` or
-     * `valueSetter` — the group row value setter handles the edit entirely.
+     * `valueSetter` - the group row value setter handles the edit entirely.
      *
      * Note: if `groupRowValueSetter` resolves to `false` or `null` (via `distribution: false`,
      * a per-aggFunc record entry, or `groupRowValueSetter: false`), the cell is treated as not
@@ -393,7 +405,7 @@ export interface ColDef<TData = any, TValue = any> extends AbstractColDef<TData,
      * - **`false`**: Explicitly disables group row value distribution and makes the cell not editable,
      *   even if `groupRowEditable` is defined.
      * - **Function**: A custom callback that receives a {@link GroupRowValueSetterParams} and pushes
-     *   edits down to descendants. The column does not need `field` or `valueSetter` — the callback
+     *   edits down to descendants. The column does not need `field` or `valueSetter` - the callback
      *   handles the edit entirely.
      * - **Options object**: Uses the built-in distribution logic with a {@link GroupRowValueSetterOptions}
      *   configuration. When `distribution` resolves to `false` or `null` for the column's aggFunc,
@@ -488,7 +500,7 @@ export interface ColDef<TData = any, TValue = any> extends AbstractColDef<TData,
     getFindText?: GetFindTextFunc<TData, TValue>;
     /**
      * The custom header component to be used for rendering the component header. If none specified the default AG Grid header component is used.
-     * See [Header Component](https://www.ag-grid.com/javascript-data-grid/component-header/) for framework specific implementation detail.
+     * See [Header Component](https://www.ag-grid.com/javascript-data-grid/column-headers/) for framework specific implementation detail.
      */
     headerComponent?: any;
     /** The parameters to be passed to the `headerComponent`. */
@@ -724,6 +736,19 @@ export interface ColDef<TData = any, TValue = any> extends AbstractColDef<TData,
      * @agModule `RowGroupingModule` / `PivotModule` / `TreeDataModule` / `ServerSideRowModelModule`
      */
     initialAggFunc?: string | IAggFunc<TData, TValue>;
+    /**
+     * The position of this column in the order of value columns when aggregating in pivot mode.
+     * When aggregating by a single column, any number can be used. When aggregating by multiple
+     * columns, this determines the order (e.g. `0` for first, `1` for second).
+     * @agModule `RowGroupingModule` / `PivotModule`
+     */
+    valueIndex?: number;
+    /**
+     * Same as `valueIndex`, except only applied when creating a new column. Not applied when updating column definitions.
+     * @initial
+     * @agModule `RowGroupingModule` / `PivotModule`
+     */
+    initialValueIndex?: number;
     /**
      * The name of the aggregation function to use for this column when it is enabled via the GUI.
      * Note that this does not immediately apply the aggregation function like `aggFunc`
@@ -738,6 +763,43 @@ export interface ColDef<TData = any, TValue = any> extends AbstractColDef<TData,
      * @agModule `RowGroupingModule` / `PivotModule` / `TreeDataModule` / `ServerSideRowModelModule`
      */
     allowedAggFuncs?: string[];
+    /**
+     * The active "Show Values As" mode for this column.
+     * <br /><br />
+     * Shows the column's aggregated value relative to another total, for example as a percentage of the grand total,
+     * column total, row total or parent total. This changes only the displayed value; the underlying value used by
+     * `getDataValue` and charts is unchanged.
+     * <br /><br />
+     * Use a built-in mode name, or the object form `{ type, params, precision }`. Set `null` for no active mode.
+     * @agModule `ShowValuesAsModule`
+     */
+    showValuesAs?: ShowValuesAsType | ShowValuesAs | null;
+    /**
+     * Same as `showValuesAs`, except only applied when creating a new column.
+     * @initial
+     * @agModule `ShowValuesAsModule`
+     */
+    initialShowValuesAs?: ShowValuesAsType | ShowValuesAs;
+    /**
+     * Per-column "Show Values As" configuration: `precision`, `suppressHeaderIndicator`, and user-provided
+     * `modes` (custom modes / overrides of the built-ins). Deep-merges from `defaultColDef`. The active mode is
+     * the `showValuesAs` selector. `null` disables the feature for the column (useful to opt a column out via
+     * `defaultColDef`).
+     * @agModule `ShowValuesAsModule`
+     */
+    showValuesAsDef?: ShowValuesAsDef<TData, TValue> | null;
+    /**
+     * Shows the "Show Values As" submenu in the column menu.
+     * <br /><br />
+     * On `defaultColDef`, `true` shows the submenu only for value columns and numeric columns. On an individual
+     * column, `true` always shows it; use this when the grid cannot infer that the column returns numbers, for
+     * example with a `valueGetter` or custom `aggFunc`. `false` hides the submenu.
+     * <br /><br />
+     * This controls menu visibility only. Modes set through `showValuesAs` or Column State still apply.
+     * @default false
+     * @agModule `ShowValuesAsModule`
+     */
+    enableShowValuesAs?: boolean;
     /**
      * Specify a grouping hierarchy for this column. This generates one or more virtual columns to group or pivot by when this column is grouped or pivoted.
      *

package/dist/types/src/entities/gridOptions.d.ts

@@ -2,10 +2,10 @@
  * If you change the GridOptions interface, you must also update PropertyKeys to be consistent. *
  ************************************************************************************************/
 import type { AgChartTheme, AgChartThemeOverrides } from 'ag-charts-types';
-import type { Theme } from '../agStack/theming/theme';
+import type { Theme } from 'ag-stack';
 import type { IsRowValidDropPositionCallback } from '../dragAndDrop/rowDragTypes';
 import type { AgPublicEventType } from '../eventTypes';
-import type { AdvancedFilterBuilderVisibleChangedEvent, AsyncTransactionsFlushedEvent, BatchEditingStartedEvent, BatchEditingStoppedEvent, BodyScrollEndEvent, BodyScrollEvent, BulkEditingStartedEvent, BulkEditingStoppedEvent, CellClickedEvent, CellContextMenuEvent, CellDoubleClickedEvent, CellEditRequestEvent, CellEditingStartedEvent, CellEditingStoppedEvent, CellFocusedEvent, CellKeyDownEvent, CellMouseDownEvent, CellMouseOutEvent, CellMouseOverEvent, CellSelectionChangedEvent, CellSelectionDeleteEndEvent, CellSelectionDeleteStartEvent, CellValueChangedEvent, ChartCreatedEvent, ChartDestroyedEvent, ChartOptionsChangedEvent, ChartRangeSelectionChangedEvent, ColumnEverythingChangedEvent, ColumnGroupOpenedEvent, ColumnHeaderClickedEvent, ColumnHeaderContextMenuEvent, ColumnHeaderMouseLeaveEvent, ColumnHeaderMouseOverEvent, ColumnMenuVisibleChangedEvent, ColumnMovedEvent, ColumnPinnedEvent, ColumnPivotChangedEvent, ColumnPivotModeChangedEvent, ColumnResizedEvent, ColumnRowGroupChangedEvent, ColumnValueChangedEvent, ColumnVisibleEvent, ColumnsResetEvent, ComponentStateChangedEvent, ContextMenuVisibleChangedEvent, CutEndEvent, CutStartEvent, DisplayedColumnsChangedEvent, DragCancelledEvent, DragStartedEvent, DragStoppedEvent, ExpandOrCollapseAllEvent, FillEndEvent, FillStartEvent, FilterChangedEvent, FilterModifiedEvent, FilterOpenedEvent, FilterUiChangedEvent, FindChangedEvent, FirstDataRenderedEvent, FloatingFilterUiChangedEvent, FullWidthCellKeyDownEvent, GridColumnsChangedEvent, GridPreDestroyedEvent, GridReadyEvent, GridSizeChangedEvent, HeaderFocusedEvent, ModelUpdatedEvent, NewColumnsLoadedEvent, PaginationChangedEvent, PasteEndEvent, PasteStartEvent, PinnedRowDataChangedEvent, PinnedRowsChangedEvent, PivotMaxColumnsExceededEvent, RangeDeleteEndEvent, RangeDeleteStartEvent, RangeSelectionChangedEvent, RedoEndedEvent, RedoStartedEvent, RowClickedEvent, RowDataUpdatedEvent, RowDoubleClickedEvent, RowDragCancelEvent, RowDragEndEvent, RowDragEnterEvent, RowDragLeaveEvent, RowDragMoveEvent, RowEditingStartedEvent, RowEditingStoppedEvent, RowGroupOpenedEvent, RowResizeEndedEvent, RowResizeStartedEvent, RowSelectedEvent, RowValueChangedEvent, SelectionChangedEvent, SortChangedEvent, StateUpdatedEvent, StoreRefreshedEvent, ToolPanelSizeChangedEvent, ToolPanelVisibleChangedEvent, TooltipHideEvent, TooltipShowEvent, UndoEndedEvent, UndoStartedEvent, ViewportChangedEvent, VirtualColumnsChangedEvent, VirtualRowRemovedEvent } from '../events';
+import type { AdvancedFilterBuilderVisibleChangedEvent, AsyncTransactionsFlushedEvent, BatchEditingStartedEvent, BatchEditingStoppedEvent, BodyScrollEndEvent, BodyScrollEvent, BulkEditingStartedEvent, BulkEditingStoppedEvent, CalculatedColumnCreatedEvent, CalculatedColumnExpressionChangedEvent, CalculatedColumnRemovedEvent, CalculatedColumnValidationStateChangedEvent, CellClickedEvent, CellContextMenuEvent, CellDoubleClickedEvent, CellEditRequestEvent, CellEditingStartedEvent, CellEditingStoppedEvent, CellFocusedEvent, CellKeyDownEvent, CellMouseDownEvent, CellMouseOutEvent, CellMouseOverEvent, CellSelectionChangedEvent, CellSelectionDeleteEndEvent, CellSelectionDeleteStartEvent, CellValueChangedEvent, ChartCreatedEvent, ChartDestroyedEvent, ChartOptionsChangedEvent, ChartRangeSelectionChangedEvent, ColumnEverythingChangedEvent, ColumnGroupOpenedEvent, ColumnHeaderClickedEvent, ColumnHeaderContextMenuEvent, ColumnHeaderMouseLeaveEvent, ColumnHeaderMouseOverEvent, ColumnMenuVisibleChangedEvent, ColumnMovedEvent, ColumnPinnedEvent, ColumnPivotChangedEvent, ColumnPivotModeChangedEvent, ColumnResizedEvent, ColumnRowGroupChangedEvent, ColumnValueChangedEvent, ColumnVisibleEvent, ColumnsResetEvent, ComponentStateChangedEvent, ContextMenuVisibleChangedEvent, CutEndEvent, CutStartEvent, DisplayedColumnsChangedEvent, DragCancelledEvent, DragStartedEvent, DragStoppedEvent, ExpandOrCollapseAllEvent, FillEndEvent, FillStartEvent, FilterChangedEvent, FilterModifiedEvent, FilterOpenedEvent, FilterUiChangedEvent, FindChangedEvent, FirstDataRenderedEvent, FloatingFilterUiChangedEvent, FullWidthCellKeyDownEvent, GridColumnsChangedEvent, GridPreDestroyedEvent, GridReadyEvent, GridSizeChangedEvent, HeaderFocusedEvent, ModelUpdatedEvent, NewColumnsLoadedEvent, PaginationChangedEvent, PasteEndEvent, PasteStartEvent, PinnedRowDataChangedEvent, PinnedRowsChangedEvent, PivotMaxColumnsExceededEvent, RangeDeleteEndEvent, RangeDeleteStartEvent, RangeSelectionChangedEvent, RedoEndedEvent, RedoStartedEvent, RowClickedEvent, RowDataUpdatedEvent, RowDoubleClickedEvent, RowDragCancelEvent, RowDragEndEvent, RowDragEnterEvent, RowDragLeaveEvent, RowDragMoveEvent, RowEditingStartedEvent, RowEditingStoppedEvent, RowGroupOpenedEvent, RowResizeEndedEvent, RowResizeStartedEvent, RowSelectedEvent, RowValueChangedEvent, SelectionChangedEvent, SortChangedEvent, StateUpdatedEvent, StoreRefreshedEvent, ToolPanelSizeChangedEvent, ToolPanelVisibleChangedEvent, TooltipHideEvent, TooltipShowEvent, UndoEndedEvent, UndoStartedEvent, ViewportChangedEvent, VirtualColumnsChangedEvent, VirtualRowRemovedEvent } from '../events';
 import type { AutoSizeStrategy } from '../interfaces/autoSize';
 import type { EditStrategyType } from '../interfaces/editStrategyType';
 import type { EditValidationCommitType } from '../interfaces/editValidationCommitType';
@@ -15,11 +15,13 @@ import type { GridState } from '../interfaces/gridState';
 import type { IAdvancedFilterBuilderParams } from '../interfaces/iAdvancedFilterBuilderParams';
 import type { IAdvancedFilterParams } from '../interfaces/iAdvancedFilterParams';
 import type { AlignedGrid } from '../interfaces/iAlignedGrid';
+import type { CalculatedColumnsGridOption } from '../interfaces/iCalculatedColumns';
 import type { DoesExternalFilterPass, FillOperation, FillOperationParams, FocusGridInnerElement, FullRowEditValidationParams, GetBusinessKeyForNode, GetChartMenuItemsParams, GetChartToolbarItemsParams, GetChildCount, GetContextMenuItemsParams, GetGroupAggFilteringParams, GetGroupIncludeFooterParams, GetGroupIncludeTotalRowParams, GetGroupRowAgg, GetLocaleText, GetMainMenuItemsParams, GetRowHeight, GetRowIdParams, GetServerSideGroupLevelParams, InitialGroupOrderComparator, IsApplyServerSideTransactionParams, IsExternalFilterPresent, IsFullWidthRow, IsGroupOpenByDefault, IsServerSideGroupOpenByDefault, NavigateToNextCell, NavigateToNextHeader, PaginationNumberFormatter, PostProcessPopup, PostSortRows, ProcessDataFromClipboard, ProcessRowPostCreate, ProcessUnpinnedColumns, SendToClipboard, TabToNextCell, TabToNextGridContainer, TabToNextHeader } from '../interfaces/iCallbackParams';
 import type { ChartToolPanelsDef, ChartToolbarMenuItemOptions, DefaultChartMenuItem } from '../interfaces/iChartOptions';
 import type { AgGridCommon } from '../interfaces/iCommon';
 import type { IDatasource } from '../interfaces/iDatasource';
 import type { ExcelExportParams, ExcelStyle } from '../interfaces/iExcelCreator';
+import type { ProcessFileInputParams } from '../interfaces/iFileProcessor';
 import type { AlwaysPassFilter, FilterHandlers, QuickFilterMatcher, QuickFilterParser } from '../interfaces/iFilter';
 import type { FindOptions } from '../interfaces/iFind';
 import type { ILoadingCellRendererParams } from '../interfaces/iLoadingCellRenderer';
@@ -28,6 +30,7 @@ import type { RowModelType } from '../interfaces/iRowModel';
 import type { IRowNode, RowPinnedType } from '../interfaces/iRowNode';
 import type { IServerSideDatasource } from '../interfaces/iServerSideDatasource';
 import type { SideBarDef } from '../interfaces/iSideBar';
+import type { SortDirection } from '../interfaces/iSort';
 import type { StatusBar } from '../interfaces/iStatusPanel';
 import type { Toolbar } from '../interfaces/iToolbar';
 import type { IViewportDatasource } from '../interfaces/iViewportDatasource';
@@ -36,7 +39,7 @@ import type { FullWidthNotesDataSource, NotesDataSource } from '../interfaces/no
 import type { RowNumbersOptions } from '../interfaces/rowNumbers';
 import type { OverlaySelectorFunc, OverlayType } from '../rendering/overlays/overlayComponent';
 import type { Icons } from '../utils/icon';
-import type { CheckboxSelectionCallback, ColDef, ColGroupDef, ColTypeDefs, GroupHierarchyConfig, IAggFuncs, SortDirection } from './colDef';
+import type { CheckboxSelectionCallback, ColDef, ColGroupDef, ColTypeDefs, GroupHierarchyConfig, IAggFuncs } from './colDef';
 import type { DataTypeDefinitions } from './dataType';
 export interface GridOptions<TData = any> {
     /**
@@ -229,6 +232,11 @@ export interface GridOptions<TData = any> {
      * or can be custom data types.
      */
     dataTypeDefinitions?: DataTypeDefinitions<TData>;
+    /**
+     * Enables and configures Calculated Columns.
+     * @agModule `CalculatedColumnsModule`
+     */
+    calculatedColumns?: CalculatedColumnsGridOption;
     /**
      * Keeps the order of Columns maintained after new Column Definitions are updated.
      *
@@ -815,7 +823,7 @@ export interface GridOptions<TData = any> {
      */
     suppressNoRowsOverlay?: boolean;
     /**
-     * List of provided overlay names to suppress. One of `loading`, `noRows`, `noMatchingRows`, `exporting`.
+     * List of provided overlay names to suppress. One of `loading`, `noRows`, `noMatchingRows`, `exporting`, `fileInput`.
      */
     suppressOverlays?: OverlayType[];
     /**
@@ -846,6 +854,13 @@ export interface GridOptions<TData = any> {
      * Custom parameters to be supplied to the `activeOverlay` component in addition to `IOverlayParams`. Updating the params will trigger a refresh of the active overlay.
      */
     activeOverlayParams?: any;
+    /**
+     * Callback to handle files received via the file input overlay (drag-and-drop or file browser).
+     * When provided, the file input overlay is shown when there is no row data.
+     * Call `params.success(rowData)` to load parsed data into the grid, or `params.fail(message)` to show an error.
+     * @agModule `FileInputOverlayModule`
+     */
+    processFileInput?: (params: ProcessFileInputParams<TData>) => void;
     /**
      * Set whether pagination is enabled.
      * @default false
@@ -890,10 +905,11 @@ export interface GridOptions<TData = any> {
     suppressPaginationPanel?: boolean;
     /**
      * Controls which built-in components appear in the pagination panel and in what order.
-     * Accepts an array of names: `'pageSize'`, `'rowSummary'`, `'pageSummary'`.
+     * Accepts an array of panel names (`'pageSize'`, `'rowSummary'`, `'pageSummary'`) or config objects.
      * Components render in the order they appear in the array. Omitted components are hidden.
      * An empty array hides the pagination panel entirely.
      * When not set, all three components render in the default order: [`pageSize`, `rowSummary`, `pageSummary`].
+     * Use `{ type: 'pageSummary', suppressPageInput: true }` to render a read-only page summary.
      * @agModule `PaginationModule`
      */
     paginationPanels?: PaginationPanel[];
@@ -1195,6 +1211,7 @@ export interface GridOptions<TData = any> {
     groupDefaultExpanded?: number;
     /**
      * Allows specifying the group 'auto column' if you are not happy with the default. If grouping, this column definition is included as the first column in the grid. If not grouping, this column is not included.
+     * Cell tooltip properties set here (`tooltipField`, `tooltipValueGetter`, `tooltipComponent`) apply to leaf rows only; group rows inherit cell tooltips from their underlying column `colDef`. `headerTooltip` continues to apply to the group column header.
      * @agModule `RowGroupingModule` / `TreeDataModule`
      */
     autoGroupColumnDef?: AutoGroupColumnDef<TData>;
@@ -1754,8 +1771,8 @@ export interface GridOptions<TData = any> {
      */
     suppressRowTransform?: boolean;
     /**
-     * Set to `true` to suppress `content-visibility: auto` on the grid wrapper element. This degrades performance by causing the browser to render grids even when they are off screen, but may be necessary if your application depends on receiving resize events from hidden grids.
-     * @default false
+     * Set to `false` to enable `content-visibility: auto` on the grid wrapper element. This improves performance by allowing the browser to skip rendering grids that are off screen, but may cause issues if your application depends on receiving resize events from hidden grids.
+     * @default true
      * @initial
      */
     suppressContentVisibilityAuto?: boolean;
@@ -2069,6 +2086,20 @@ export interface GridOptions<TData = any> {
      * @agModule `ClientSideRowModelModule`
      */
     resetRowDataOnUpdate?: boolean;
+    /**
+     * When enabled, column definitions are generated automatically from the first row of `rowData` whenever row data is set or updated.
+     * Set to `true` to use default settings, or provide an `AutoGenerateColumnDefsOptions` object to customise how values are handled.
+     * @default false
+     * @agModule `AutoGenerateColumnsModule`
+     */
+    autoGenerateColumnDefs?: boolean | AutoGenerateColumnDefsOptions;
+    /**
+     * Callback fired after auto-generating column definitions and before they are applied to the grid.
+     * Return the final `(ColDef | ColGroupDef)[]` to use or void if only mutations of generated columnDefs are required.
+     *
+     * @agModule `AutoGenerateColumnsModule`
+     */
+    processAutoGeneratedColumnDefs?: ProcessAutoGeneratedColumnDefs<TData>;
     /**
      * Callback fired after the row is rendered into the DOM. Should not be used to initiate side effects.
      */
@@ -2144,6 +2175,22 @@ export interface GridOptions<TData = any> {
      * Paste operation has ended.
      */
     onPasteEnd?(event: PasteEndEvent<TData>): void;
+    /**
+     * A calculated column has been created.
+     */
+    onCalculatedColumnCreated?(event: CalculatedColumnCreatedEvent<TData>): void;
+    /**
+     * A calculated column expression has changed.
+     */
+    onCalculatedColumnExpressionChanged?(event: CalculatedColumnExpressionChangedEvent<TData>): void;
+    /**
+     * A calculated column has been removed.
+     */
+    onCalculatedColumnRemoved?(event: CalculatedColumnRemovedEvent<TData>): void;
+    /**
+     * A calculated column expression has changed between valid and invalid.
+     */
+    onCalculatedColumnValidationStateChanged?(event: CalculatedColumnValidationStateChangedEvent<TData>): void;
     /**
      * A column, or group of columns, was hidden / shown.
      */
@@ -2830,7 +2877,45 @@ export type MasterSelectionMode = NonNullable<CommonRowSelectionOptions['masterS
 export type AgPublicEventHandlerType = `on${Capitalize<AgPublicEventType>}` & keyof GridOptions;
 export type ProcessPivotResultColDef<TData = any, TValue = any> = (colDef: ColDef<TData, TValue>) => void;
 export type ProcessPivotResultColGroupDef<TData = any> = (colDef: ColGroupDef<TData>) => void;
-export type PaginationPanel = 'pageSize' | 'rowSummary' | 'pageSummary';
+export interface AutoGenerateColumnDefsOptions {
+    /** How to handle plain-object values. `'group'` recurses into the object and creates a column group, `'flatten'` recurses and creates flat leaf columns using dotted field paths, `'skip'` ignores the field entirely.
+     * @default 'group'
+     */
+    objectValues?: 'group' | 'flatten' | 'skip';
+    /** How to handle array values. `'primitives'` creates a leaf column only when the first element is a primitive value, `'include'` creates a leaf column for all arrays, `'skip'` ignores them.
+     * @default 'primitives'
+     */
+    arrayValues?: 'primitives' | 'include' | 'skip';
+    /** How to handle `null` and `undefined` values. `'include'` creates a leaf column, `'skip'` ignores them.
+     * @default 'include'
+     */
+    nullishValues?: 'include' | 'skip';
+}
+export interface ProcessAutoGeneratedColumnDefsParams<TData = any, TContext = any> extends AgGridCommon<TData, TContext> {
+    /**
+     * The generated column definitions.
+     * May include `ColGroupDef` entries when row data contains nested objects. Use the `forEachColDef` helper function to iterate safely over all leaf columns only.  */
+    columnDefs: (ColDef | ColGroupDef)[];
+    /** Row data that the columns were generated from */
+    rowData: TData[];
+}
+export type ProcessAutoGeneratedColumnDefs<TData = any, TContext = any> = (params: ProcessAutoGeneratedColumnDefsParams<TData, TContext>) => (ColDef | ColGroupDef)[] | void;
+export interface PageSummaryPanelParams {
+    type: 'pageSummary';
+    suppressPageInput?: boolean;
+}
+export interface PageSizePanelParams {
+    type: 'pageSize';
+    /** Panel-level page size. Takes precedence over the grid-level `paginationPageSize` option. */
+    paginationPageSize?: number;
+    /** Panel-level page size selector. Takes precedence over the grid-level `paginationPageSizeSelector` option. */
+    paginationPageSizeSelector?: number[] | boolean;
+}
+export interface RowSummaryPanelParams {
+    type: 'rowSummary';
+}
+export type PaginationPanelParams = PageSummaryPanelParams | PageSizePanelParams | RowSummaryPanelParams;
+export type PaginationPanel = 'pageSize' | 'rowSummary' | 'pageSummary' | PaginationPanelParams;
 export type PivotColumnGroupTotals = 'before' | 'after';
 export type PivotRowTotals = 'before' | 'after';
 export {};