ag-grid-community 35.2.0 → 35.3.0

package/dist/types/src/interfaces/iFrameworkOverrides.d.ts

@@ -30,4 +30,6 @@ export interface IFrameworkOverrides extends AgFrameworkOverrides {
      * Required for React to work with StrictMode from v19 with the current implementation of the CtrlsService.
      */
     runWhenReadyAsync?(): boolean;
+    /** True when modules are provided via AgGridProvider React context, used for accurate missing module error messages */
+    readonly usesAgGridProvider?: boolean;
 }

package/dist/types/src/interfaces/iModule.d.ts

@@ -67,18 +67,18 @@ export type _ModuleWithoutApi = Module & {
 export type _ModuleWithLicenseManager = {
     setLicenseKey: (licenseKey: string) => void;
 };
-type InternalModuleName = 'Aggregation' | 'AnimationFrame' | 'Aria' | 'AutoWidth' | 'CellRendererFunction' | 'ChangedPath' | 'ChangeDetection' | 'CheckboxCellRenderer' | 'ClientSideRowModelFilter' | 'ClientSideRowModelHierarchy' | 'ColumnDelayRender' | 'ColumnFilter' | 'ColumnFlex' | 'ColumnGroupHeaderComp' | 'ColumnGroup' | 'ColumnHeaderComp' | 'ColumnMove' | 'ColumnResize' | 'CommunityCore' | 'CsrmSsrmSharedApi' | 'RowModelSharedApi' | 'DataType' | 'Drag' | 'EditCore' | 'EnterpriseCore' | 'Expression' | 'FilterCore' | 'FilterValue' | 'FindCore' | 'GroupEdit' | 'GroupCellRenderer' | 'GroupColumn' | 'GroupHierarchy' | 'HorizontalResize' | 'InfiniteRowModelCore' | 'KeyboardNavigation' | 'LoadingCellRenderer' | 'MenuCore' | 'MenuItem' | 'Overlay' | 'PinnedColumn' | 'Popup' | 'QuickFilterCore' | 'SharedAggregation' | 'SharedColumnStateUpdateStrategy' | 'SharedDragAndDrop' | 'SharedExport' | 'SharedMasterDetail' | 'SharedMenu' | 'SharedPivot' | 'SharedRowGrouping' | 'SharedRowSelection' | 'SharedTreeData' | 'SideBarShared' | 'SkeletonCellRenderer' | 'Sort' | 'SsrmInfiniteSharedApi' | 'StickyRow' | 'Touch' | 'Testing';
+type InternalModuleName = 'Aggregation' | 'AnimationFrame' | 'Aria' | 'AutoWidth' | 'CellRendererFunction' | 'ChangedPath' | 'ChangeDetection' | 'CheckboxCellRenderer' | 'CsrmFilter' | 'CsrmHierarchy' | 'CsrmGroupStages' | 'ColumnDelayRender' | 'ColumnFilter' | 'ColumnFlex' | 'ColumnGroupHeaderComp' | 'ColumnGroup' | 'ColumnHeaderComp' | 'ColumnMove' | 'ColumnResize' | 'CommunityCore' | 'CsrmSsrmSharedApi' | 'RowModelSharedApi' | 'DataType' | 'Drag' | 'EditCore' | 'EnterpriseCore' | 'Expression' | 'FilterCore' | 'FilterValue' | 'FindCore' | 'GroupEdit' | 'GroupCellRenderer' | 'GroupColumn' | 'GroupHierarchy' | 'HorizontalResize' | 'InfiniteRowModelCore' | 'KeyboardNavigation' | 'LoadingCellRenderer' | 'MenuCore' | 'MenuItem' | 'Overlay' | 'PinnedColumn' | 'Popup' | 'QuickFilterCore' | 'SharedAggregation' | 'SharedColumnStateUpdateStrategy' | 'SharedDragAndDrop' | 'SharedExport' | 'SharedMasterDetail' | 'SharedMenu' | 'SharedPivot' | 'SharedRowGrouping' | 'SharedRowSelection' | 'SharedTreeData' | 'SideBarShared' | 'SkeletonCellRenderer' | 'Sort' | 'SsrmInfiniteSharedApi' | 'StickyRow' | 'Touch' | 'Testing';
 export type CommunityModuleName = 'AlignedGrids' | 'AllCommunity' | 'CellApi' | 'CellStyle' | 'CheckboxEditor' | 'ClientSideRowModelApi' | 'ClientSideRowModel' | 'ColumnApi' | 'ColumnAutoSize' | 'ColumnHover' | 'CsvExport' | 'CustomEditor' | 'CustomFilter' | 'DateEditor' | 'DateFilter' | 'DragAndDrop' | 'EventApi' | 'ExternalFilter' | 'GridState' | 'HighlightChanges' | 'InfiniteRowModel' | 'LargeTextEditor' | 'Locale' | 'NumberEditor' | 'NumberFilter' | 'BigIntFilter' | 'Pagination' | 'PinnedRow' | 'QuickFilter' | 'RenderApi' | 'RowApi' | 'RowAutoHeight' | 'RowDrag' | 'RowSelection' | 'RowStyle' | 'ScrollApi' | 'SelectEditor' | 'TextEditor' | 'TextFilter' | 'Tooltip' | 'UndoRedoEdit' | 'Validation' | 'ValueCache' | 'CellSpan';
-export type EnterpriseModuleName = 'AdvancedFilter' | 'AiToolkit' | 'AllEnterprise' | 'BatchEdit' | 'CellSelection' | 'Clipboard' | 'ColumnMenu' | 'ColumnsToolPanel' | 'ContextMenu' | 'ExcelExport' | 'FiltersToolPanel' | 'Find' | 'GridCharts' | 'IntegratedCharts' | 'GroupFilter' | 'MasterDetail' | 'Menu' | 'MultiFilter' | 'NewFiltersToolPanel' | 'Pivot' | 'RangeSelection' | 'RichSelect' | 'RowNumbers' | 'RowGrouping' | 'RowGroupingPanel' | 'ServerSideRowModelApi' | 'ServerSideRowModel' | 'SetFilter' | 'SideBar' | 'Sparklines' | 'StatusBar' | 'TreeData' | 'ViewportRowModel' | 'Formula' | 'RowGroupingEdit';
+export type EnterpriseModuleName = 'AdvancedFilter' | 'AiToolkit' | 'AllEnterprise' | 'BatchEdit' | 'CellSelection' | 'Clipboard' | 'ColumnMenu' | 'ColumnsToolPanel' | 'ContextMenu' | 'ExcelExport' | 'FiltersToolPanel' | 'Find' | 'GridCharts' | 'IntegratedCharts' | 'GroupFilter' | 'MasterDetail' | 'Menu' | 'MultiFilter' | 'NewFiltersToolPanel' | 'Pivot' | 'RangeSelection' | 'RichSelect' | 'RowNumbers' | 'RowGrouping' | 'RowGroupingPanel' | 'ServerSideRowModelApi' | 'ServerSideRowModel' | 'SetFilter' | 'SideBar' | 'Sparklines' | 'StatusBar' | 'Toolbar' | 'TreeData' | 'ViewportRowModel' | 'Formula' | 'Notes' | 'RowGroupingEdit';
 /** The names of all publicly available AG Grid modules */
-export type AgModuleName = 'AiToolkitModule' | 'AlignedGridsModule' | 'AllCommunityModule' | 'CellApiModule' | 'CellStyleModule' | 'CheckboxEditorModule' | 'ClientSideRowModelApiModule' | 'ClientSideRowModelModule' | 'ColumnApiModule' | 'ColumnAutoSizeModule' | 'ColumnHoverModule' | 'CsvExportModule' | 'CustomEditorModule' | 'CustomFilterModule' | 'DateEditorModule' | 'DateFilterModule' | 'DragAndDropModule' | 'EventApiModule' | 'ExternalFilterModule' | 'GridStateModule' | 'RowGroupingEditModule' | 'HighlightChangesModule' | 'InfiniteRowModelModule' | 'LargeTextEditorModule' | 'LocaleModule' | 'NumberEditorModule' | 'NumberFilterModule' | 'BigIntFilterModule' | 'PaginationModule' | 'PinnedRowModule' | 'QuickFilterModule' | 'RenderApiModule' | 'RowApiModule' | 'RowAutoHeightModule' | 'RowDragModule' | 'RowSelectionModule' | 'RowStyleModule' | 'ScrollApiModule' | 'SelectEditorModule' | 'TextEditorModule' | 'TextFilterModule' | 'TooltipModule' | 'UndoRedoEditModule' | 'ValidationModule' | 'ValueCacheModule' | 'CellSpanModule' | 'AdvancedFilterModule' | 'AllEnterpriseModule' | 'BatchEditModule' | 'CellSelectionModule' | 'ClipboardModule' | 'ColumnMenuModule' | 'ColumnsToolPanelModule' | 'ContextMenuModule' | 'ExcelExportModule' | 'FiltersToolPanelModule' | 'FindModule' | 'GridChartsModule' | 'IntegratedChartsModule' | 'GroupFilterModule' | 'MasterDetailModule' | 'MenuModule' | 'MultiFilterModule' | 'NewFiltersToolPanelModule' | 'PivotModule' | 'RangeSelectionModule' | 'RichSelectModule' | 'RowNumbersModule' | 'RowGroupingModule' | 'RowGroupingPanelModule' | 'ServerSideRowModelApiModule' | 'ServerSideRowModelModule' | 'SetFilterModule' | 'SideBarModule' | 'SparklinesModule' | 'StatusBarModule' | 'TreeDataModule' | 'ViewportRowModelModule' | 'FormulaModule';
+export type AgModuleName = 'AiToolkitModule' | 'AlignedGridsModule' | 'AllCommunityModule' | 'CellApiModule' | 'CellStyleModule' | 'CheckboxEditorModule' | 'ClientSideRowModelApiModule' | 'ClientSideRowModelModule' | 'ColumnApiModule' | 'ColumnAutoSizeModule' | 'ColumnHoverModule' | 'CsvExportModule' | 'CustomEditorModule' | 'CustomFilterModule' | 'DateEditorModule' | 'DateFilterModule' | 'DragAndDropModule' | 'EventApiModule' | 'ExternalFilterModule' | 'GridStateModule' | 'RowGroupingEditModule' | 'HighlightChangesModule' | 'InfiniteRowModelModule' | 'LargeTextEditorModule' | 'LocaleModule' | 'NumberEditorModule' | 'NumberFilterModule' | 'BigIntFilterModule' | 'PaginationModule' | 'PinnedRowModule' | 'QuickFilterModule' | 'RenderApiModule' | 'RowApiModule' | 'RowAutoHeightModule' | 'RowDragModule' | 'RowSelectionModule' | 'RowStyleModule' | 'ScrollApiModule' | 'SelectEditorModule' | 'TextEditorModule' | 'TextFilterModule' | 'TooltipModule' | 'UndoRedoEditModule' | 'ValidationModule' | 'ValueCacheModule' | 'CellSpanModule' | 'AdvancedFilterModule' | 'AllEnterpriseModule' | 'BatchEditModule' | 'CellSelectionModule' | 'ClipboardModule' | 'ColumnMenuModule' | 'ColumnsToolPanelModule' | 'ContextMenuModule' | 'ExcelExportModule' | 'FiltersToolPanelModule' | 'FindModule' | 'GridChartsModule' | 'IntegratedChartsModule' | 'GroupFilterModule' | 'MasterDetailModule' | 'MenuModule' | 'MultiFilterModule' | 'NewFiltersToolPanelModule' | 'PivotModule' | 'RangeSelectionModule' | 'RichSelectModule' | 'RowNumbersModule' | 'RowGroupingModule' | 'RowGroupingPanelModule' | 'ServerSideRowModelApiModule' | 'ServerSideRowModelModule' | 'SetFilterModule' | 'SideBarModule' | 'SparklinesModule' | 'StatusBarModule' | 'ToolbarModule' | 'TreeDataModule' | 'ViewportRowModelModule' | 'FormulaModule' | 'NotesModule';
 /**
  * INTERNAL: All public and internal module names
  * @internal AG_GRID_INTERNAL - Not for public use. Can change / be removed at any time.
  */
 export type ModuleName = InternalModuleName | CommunityModuleName | EnterpriseModuleName;
 /** These are the internal modules that we have mappings for to convert into exported modules */
-export type ResolvableModuleName = Extract<InternalModuleName, 'EditCore' | 'MenuCore' | 'EnterpriseCore' | 'ColumnHeaderComp' | 'ColumnFilter' | 'ColumnGroupHeaderComp' | 'SharedDragAndDrop' | 'GroupCellRenderer' | 'MenuItem' | 'CommunityCore' | 'LoadingCellRenderer' | 'Sort' | 'SharedRowSelection' | 'KeyboardNavigation' | 'SharedMenu' | 'ColumnMove' | 'ColumnResize' | 'FilterCore' | 'CsrmSsrmSharedApi' | 'RowModelSharedApi' | 'SsrmInfiniteSharedApi' | 'SharedMasterDetail' | 'SharedRowGrouping' | 'SharedAggregation' | 'SharedPivot' | 'ColumnGroup' | 'Overlay' | 'PinnedColumn' | 'ClientSideRowModelHierarchy' | 'SkeletonCellRenderer' | 'CheckboxCellRenderer' | 'SharedTreeData'>;
+export type ResolvableModuleName = Extract<InternalModuleName, 'EditCore' | 'MenuCore' | 'EnterpriseCore' | 'ColumnHeaderComp' | 'ColumnFilter' | 'ColumnGroupHeaderComp' | 'SharedDragAndDrop' | 'GroupCellRenderer' | 'MenuItem' | 'CommunityCore' | 'LoadingCellRenderer' | 'Sort' | 'SharedRowSelection' | 'KeyboardNavigation' | 'SharedMenu' | 'ColumnMove' | 'ColumnResize' | 'FilterCore' | 'CsrmSsrmSharedApi' | 'RowModelSharedApi' | 'SsrmInfiniteSharedApi' | 'SharedMasterDetail' | 'SharedRowGrouping' | 'SharedAggregation' | 'SharedPivot' | 'ColumnGroup' | 'Overlay' | 'PinnedColumn' | 'CsrmHierarchy' | 'CsrmGroupStages' | 'SkeletonCellRenderer' | 'CheckboxCellRenderer' | 'SharedTreeData'>;
 /**
  * These are the types that we can display validations for
  * @internal AG_GRID_INTERNAL - Not for public use. Can change / be removed at any time.

package/dist/types/src/interfaces/iRowGroupPanelBuilder.d.ts

@@ -0,0 +1,11 @@
+import type { Component } from '../widgets/component';
+/** @internal AG_GRID_INTERNAL - Not for public use. Can change / be removed at any time. */
+export interface IRowGroupPanelBuilder {
+    /**
+     * @param horizontal  rendered as a header drop zone vs. embedded in the tool panel.
+     * @param embedded    true when the drop zone is hosted inside another focus container
+     *                    (e.g. the Toolbar) and should not register its own tab hand-off.
+     */
+    createRowGroupDropZone(horizontal: boolean, embedded?: boolean): Component;
+    createPivotDropZone(horizontal: boolean, embedded?: boolean): Component;
+}

package/dist/types/src/interfaces/iRowNode.d.ts

@@ -208,6 +208,14 @@ interface GroupRowNode<TData = any> {
     /** If using footers, reference to the footer node for this group. */
     sibling: IRowNode<TData>;
 }
+/** The row ID of the root node (`'ROOT_NODE_ID'`). Use with `api.getRowNode(ROOT_NODE_ID)`. */
+export declare const ROOT_NODE_ID = "ROOT_NODE_ID";
+/** Prefix for group total (footer) row IDs (`'rowGroupFooter_'`). A group total row ID is `GROUP_TOTAL_ROW_ID_PREFIX + groupRowNode.id`. */
+export declare const GROUP_TOTAL_ROW_ID_PREFIX = "rowGroupFooter_";
+/** Prefix for detail row IDs in master-detail grids (`'detail_'`). A detail row ID is `DETAIL_ROW_ID_PREFIX + masterRowNode.id`. */
+export declare const DETAIL_ROW_ID_PREFIX = "detail_";
+/** The row ID of the grand total row (`'rowGroupFooter_ROOT_NODE_ID'`). Use with `api.getRowNode(GRAND_TOTAL_ROW_ID)`. */
+export declare const GRAND_TOTAL_ROW_ID: string;
 export interface IRowNode<TData = any> extends BaseRowNode<TData>, GroupRowNode<TData> {
     /**
      * The primary (canonical) row node, resolving footer and pinned sibling relationships.
@@ -320,7 +328,9 @@ export interface IRowNode<TData = any> extends BaseRowNode<TData>, GroupRowNode<
      * Returns the data value from the `rowNode` for the specified column.
      *
      * By default, returns committed data ignoring any pending edits. For group rows, returns
-     * aggregated values or the group key. For formula cells, returns the computed result.
+     * aggregated values or the group key. For formula cells in `'data'` / `'value'` modes,
+     * returns the **computed result**; in `'edit'` / `'batch'` / `'data-raw'` modes, returns
+     * the **raw formula string** (so the edit pipeline can round-trip it).
      *
      * To get the **displayed** value (with formatting and value formatter applied), use `api.getCellValue()` instead.
      *
@@ -330,12 +340,16 @@ export interface IRowNode<TData = any> extends BaseRowNode<TData>, GroupRowNode<
      *
      * - `'data'` (default) — Returns the aggregated value for group rows, otherwise committed data.
      *   May return an `IAggFuncResult<TValue>` wrapper for aggregation columns; use `'value'` to unwrap.
+     *   Formulas are resolved to their computed value.
      * - `'edit'` — Returns the active editor's value if editing, or the pending batch value if not editing,
-     *   then falls back to aggregation and committed data.
-     * - `'batch'` — Returns the pending batch value if batching, then falls back to aggregation and committed data.
-     * - `'value'` — Same as `'data'` but unwraps `IAggFuncResult` (e.g. from `avg` or `count`) to its scalar value.
-     * - `'data-raw'` — Always returns committed data, skipping aggregation results (`rowNode.aggData`).
-     *   For group rows this is typically `undefined` since group rows do not hold leaf data.
+     *   then falls back to aggregation and committed data. **Formulas are NOT resolved** — returns the raw
+     *   formula string to mirror the edit-pipeline buffer.
+     * - `'batch'` — Returns the pending batch value if batching, then falls back to aggregation and committed
+     *   data. **Formulas are NOT resolved** — returns the raw formula string to mirror the edit-pipeline buffer.
+     * - `'value'` — Same as `'data'` but unwraps `IAggFuncResult` (e.g. from `avg` or `count`) to its scalar
+     *   value. Formulas are resolved to their computed value.
+     * - `'data-raw'` — Always returns committed data, skipping aggregation results (`rowNode.aggData`) and
+     *   formula resolution. For group rows this is typically `undefined` since group rows do not hold leaf data.
      *
      * @param colKey The column to read (field name, `colId`, or `Column` object)
      * @param from Controls value resolution. Defaults to `'data'`.

package/dist/types/src/interfaces/iRowNodeStage.d.ts

@@ -3,20 +3,23 @@ import type { GridOptions } from '../entities/gridOptions';
 import type { RowNode } from '../entities/rowNode';
 import type { ChangedPath } from '../utils/changedPath';
 import type { ClientSideRowModelStage, RefreshModelParams } from './iClientSideRowModel';
+/** @internal AG_GRID_INTERNAL - Not for public use. Can change / be removed at any time. */
 export interface IRowNodeStage<TData = any> {
     readonly step: ClientSideRowModelStage;
-    readonly refreshProps: (keyof GridOptions<TData>)[];
+    readonly refreshProps: (keyof GridOptions<TData>)[] | null;
 }
+/** @internal AG_GRID_INTERNAL - Not for public use. Can change / be removed at any time. */
 export interface IRowNodeSortStage<TData = any> extends IRowNodeStage<TData> {
     execute(changedPath: ChangedPath | undefined, changedRowNodes: ChangedRowNodes<TData> | undefined): void;
 }
+/** @internal AG_GRID_INTERNAL - Not for public use. Can change / be removed at any time. */
 export interface IRowNodeFilterStage<TData = any> extends IRowNodeStage<TData> {
     execute(changedPath: ChangedPath | undefined): void;
 }
 /** @internal AG_GRID_INTERNAL - Not for public use. Can change / be removed at any time. */
 export interface IRowNodePivotStage<TData = any> extends IRowNodeStage<TData> {
     /** Returns `true` if the changedPath should be deactivated (e.g. pivot columns changed). */
-    execute(changedPath: ChangedPath | undefined): boolean;
+    execute(changedPath: ChangedPath | undefined, changedProps: Set<keyof GridOptions> | undefined): boolean;
 }
 /** @internal AG_GRID_INTERNAL - Not for public use. Can change / be removed at any time. */
 export interface IRowNodeAggregationStage<TData = any> extends IRowNodeStage<TData> {
@@ -46,7 +49,7 @@ export interface IRowNodeGroupStage<TData = any> extends IRowNodeStage<TData> {
     loadLeafs(node: RowNode<TData>): RowNode<TData>[] | null;
     /** Used to lazily compute and store groupData for a row node - not for siblings */
     loadGroupData(node: RowNode<TData>): Record<string, any> | null;
-    /** Clears all stored group rows / tree data fillers */
+    /** Clears all stored group rows / tree data fillers without dispatching position events. */
     clearNonLeafs(): void;
     /** Called when row group columns might have changed */
     invalidateGroupCols(): void;

package/dist/types/src/interfaces/iServerSideDatasource.d.ts

@@ -39,6 +39,16 @@ export interface IServerSideGetRowsParams<TData = any, TContext = any> extends A
      * This is NOT part fo the request as it cannot be serialised to JSON (a rowNode has methods).
      */
     parentNode: IRowNode<TData>;
+    /**
+     * A hint indicating the grid does not yet have grand total data cached.
+     * When `true`, the server should include grand total data in the response via `grandTotalData`
+     * or as a row in `rowData` whose `getRowId` returns `'rowGroupFooter_ROOT_NODE_ID'`.
+     *
+     * This is only a hint — the server may always provide updated grand total data regardless of
+     * this flag, and the grid will accept it. Providing grand total data when this is `false`
+     * will update the existing grand total row.
+     */
+    needsGrandTotal: boolean;
     /**
      * Success callback, pass the rows back to the grid that were requested.
      */

package/dist/types/src/interfaces/iServerSideRowModel.d.ts

@@ -53,4 +53,10 @@ export interface LoadSuccessParams<TData = any> {
      * The pivot fields in the response - if provided the grid will attempt to generate secondary columns.
      */
     pivotResultFields?: string[];
+    /**
+     * Data for the grand total row. When provided, the grid will display or update the grand total footer row.
+     * Set to `null` to remove an existing grand total row. Takes priority over a grand total row found in `rowData`.
+     * Only the fields you want to display need to be provided; the grid assigns the row ID automatically.
+     */
+    grandTotalData?: Partial<TData> | null;
 }

package/dist/types/src/interfaces/iToolbar.d.ts

@@ -0,0 +1,178 @@
+import type { IComponent } from '../agStack/interfaces/iComponent';
+import type { ToolbarItemComponentName } from '../context/context';
+import type { IconName } from '../utils/icon';
+import type { AgGridCommon } from './iCommon';
+import type { DefaultMenuItem, MenuItemDef } from './menuItem';
+/**
+ * Configure the [Quick Access Toolbar](https://ag-grid.com/javascript-data-grid/toolbar/)
+ */
+export type Toolbar = {
+    /** Default alignment for items in the toolbar. Defaults to `'left'`. Item-level `alignment` takes precedence. */
+    alignment?: 'left' | 'right';
+    /** Items to render in the toolbar. Each entry is either a shorthand string identifier or a full item definition object. */
+    items: (ToolbarItemDef | ToolbarItemShorthand)[];
+};
+/**
+ * Shorthand string identifiers that can be used in `Toolbar.items` or on a toolbar item's `toolbarItem`.
+ * Includes the provided toolbar item components and `'separator'`.
+ */
+export type ToolbarItemShorthand = ToolbarItemComponentName | 'separator' | (string & {});
+/**
+ * A component reference for a toolbar item. Either a shorthand string identifier,
+ * a component class (AG Grid / Angular / React class component), or a component
+ * function (React functional component).
+ */
+export type ToolbarItemComponent<T> = ToolbarItemShorthand | T;
+/** Params passed to a toolbar item's `action` callback when the item is activated. */
+export interface ToolbarItemActionParams<TData = any, TContext = any> extends AgGridCommon<TData, TContext> {
+    /** The toolbar item `key` identifying which item triggered the action. */
+    key: string;
+}
+/** Properties common to every toolbar item definition variant. */
+interface ToolbarItemDefBase {
+    /**
+     * Unique identifier used to look up this item via `api.getToolbarItemInstance(key)`.
+     * Optional — items without a key still render. Set a key only on items you want to
+     * access via the API.
+     */
+    key?: string;
+    /** Alignment within the toolbar. Falls back to the toolbar-level `alignment`. */
+    alignment?: 'left' | 'right';
+}
+/**
+ * Action Button shorthand — renders a default button using `label`, `icon` and `action`,
+ * without requiring a component reference. Provide at least one of `label`, `icon` or `action`.
+ */
+export interface ToolbarButtonItemDef<TData = any, TContext = any> extends ToolbarItemDefBase {
+    /** Visible text rendered next to the icon. Omit to render an icon-only button. */
+    label?: string;
+    /** Hover tooltip and `aria-label`. Falls back to `label` when omitted. */
+    tooltip?: string;
+    /** Icon displayed on the default button. */
+    icon?: IconName;
+    /** Function invoked when the default button is clicked. */
+    action?: (params: ToolbarItemActionParams<TData, TContext>) => void;
+    /** Not used for action buttons — set `toolbarItem` to use a built-in or custom component instead. */
+    toolbarItem?: never;
+    /** Not used for action buttons — set `toolbarItem` to use a built-in or custom component instead. */
+    toolbarItemParams?: never;
+}
+/** Params accepted by the `agMenuToolbarItem` built-in toolbar item. */
+export interface ToolbarMenuItemParams<TData = any, TContext = any> {
+    /** Items shown in the dropdown. Accepts `MenuItemDef` objects or built-in string names (e.g. `'copy'`, `'export'`, `'separator'`). */
+    menuItems?: (MenuItemDef<TData, TContext> | DefaultMenuItem)[];
+}
+/**
+ * Reference to a built-in toolbar item component (or `'separator'`) that does not accept params.
+ */
+export interface ToolbarBuiltInItemDef extends ToolbarItemDefBase {
+    /** A built-in toolbar item component name, or `'separator'`. */
+    toolbarItem: Exclude<ToolbarItemComponentName, 'agMenuToolbarItem'> | 'separator';
+    /** Built-in items (other than `agMenuToolbarItem`) do not accept params. */
+    toolbarItemParams?: never;
+    /** Not used for built-in items — use the Action Button variant for label/icon/action. */
+    label?: never;
+    /** Not used for built-in items — use the Action Button variant for label/icon/action. */
+    icon?: never;
+    /** Not used for built-in items — use the Action Button variant for label/icon/action. */
+    action?: never;
+}
+/**
+ * Reference to the `agMenuToolbarItem` built-in toolbar item — a button that opens a dropdown
+ * menu. Configure `label`, `icon`, and `tooltip` at the top level; `toolbarItemParams` carries
+ * the menu contents.
+ */
+export interface ToolbarMenuBuiltInItemDef<TData = any, TContext = any> extends ToolbarItemDefBase {
+    /** The `agMenuToolbarItem` built-in component. */
+    toolbarItem: 'agMenuToolbarItem';
+    /** Configuration for the menu button (menu items). */
+    toolbarItemParams?: ToolbarMenuItemParams<TData, TContext>;
+    /** Visible text rendered next to the icon. Omit to render an icon-only button. */
+    label?: string;
+    /** Hover tooltip and `aria-label`. Falls back to `label`, then to the locale "Menu" text. */
+    tooltip?: string;
+    /** Icon displayed on the button. Defaults to the `menu` icon. */
+    icon?: IconName;
+    /** Not used for menu items. */
+    action?: never;
+}
+/**
+ * Reference to a user-provided custom toolbar item component.
+ * `toolbarItem` is a component class/function, or the name of a registered custom component.
+ */
+export interface ToolbarCustomItemDef<TParams = any, TCustom = any> extends ToolbarItemDefBase {
+    /** Custom component reference, or the name of a registered custom component. */
+    toolbarItem: TCustom;
+    /** Parameters forwarded to the custom component. */
+    toolbarItemParams?: TParams;
+    /** Not used for custom items — use the Action Button variant for label/icon/action. */
+    label?: never;
+    /** Not used for custom items — use the Action Button variant for label/icon/action. */
+    icon?: never;
+    /** Not used for custom items — use the Action Button variant for label/icon/action. */
+    action?: never;
+}
+/**
+ * A toolbar item definition. One of the following variants:
+ * - {@link ToolbarButtonItemDef} — action button shorthand (`label`/`icon`/`action`)
+ * - {@link ToolbarBuiltInItemDef} — reference to a built-in component or `'separator'`
+ * - {@link ToolbarMenuBuiltInItemDef} — reference to the `agMenuToolbarItem` dropdown menu button
+ * - {@link ToolbarCustomItemDef} — reference to a custom component
+ */
+export type ToolbarItemDef<TData = any, TContext = any, TParams = any, TCustom = any> = ToolbarButtonItemDef<TData, TContext> | ToolbarBuiltInItemDef | ToolbarMenuBuiltInItemDef<TData, TContext> | ToolbarCustomItemDef<TParams, TCustom>;
+/**
+ * Params delivered to a toolbar item component. Mirrors the runtime shape produced by the
+ * grid: a flat object containing the item-definition fields the grid forwards, merged with
+ * `AgGridCommon`. The `toolbarItem` reference itself is intentionally not forwarded — the
+ * component already knows what it is.
+ */
+export interface IToolbarItemParams<TData = any, TContext = any, TParams = any> extends AgGridCommon<TData, TContext> {
+    /**
+     * Identifier for the item. Mirrors the `key` set on the item definition, or an
+     * auto-generated key when none was provided. Used internally; only items with an
+     * explicit key on the definition are reachable via `api.getToolbarItemInstance(key)`.
+     */
+    key: string;
+    /** Explicit alignment, when set on the item definition. */
+    alignment?: 'left' | 'right';
+    /** Custom params forwarded from the item definition's `toolbarItemParams`. */
+    toolbarItemParams?: TParams;
+    /** Label, when set on the item definition (action-button shorthand or `agMenuToolbarItem`). */
+    label?: string;
+    /** Tooltip / aria-label, when set on the item definition. */
+    tooltip?: string;
+    /** Icon name, when set on the item definition. */
+    icon?: IconName;
+    /** Action callback, when using the action-button shorthand. */
+    action?: (params: ToolbarItemActionParams<TData, TContext>) => void;
+}
+/**
+ * Interface that custom toolbar item components may implement to receive lifecycle callbacks from the grid.
+ * Implement `refresh` to update in-place when the `toolbar` option changes, avoiding a full destroy/recreate cycle.
+ */
+export interface IToolbarItem<TData = any, TContext = any> {
+    /**
+     * Called when the `toolbar` grid option updates.
+     * Return `true` if the component updates itself with the new params.
+     * Return `false` (or omit) to have the grid destroy and recreate the component.
+     */
+    refresh?(params: IToolbarItemParams<TData, TContext>): boolean;
+}
+/**
+ * Full interface for toolbar item components: combines `IToolbarItem` (optional `refresh` callback)
+ * with the standard AG Grid component lifecycle (`IComponent`).
+ * Custom toolbar components that are class-based should implement this interface.
+ */
+export interface IToolbarItemComp<TData = any, TContext = any> extends IToolbarItem<TData, TContext>, IComponent<IToolbarItemParams<TData, TContext>> {
+}
+/** @internal AG_GRID_INTERNAL - Not for public use. Can change / be removed at any time. */
+export interface IToolbarService {
+    setToolbar(toolbar: IToolbarComp): void;
+    clearToolbar(toolbar: IToolbarComp): void;
+    getToolbarItemInstance<T = IToolbarItem>(key: string): T | undefined;
+}
+/** @internal AG_GRID_INTERNAL - Not for public use. Can change / be removed at any time. */
+export interface IToolbarComp {
+    getToolbarItemInstance<T = IToolbarItem>(key: string): T | undefined;
+}
+export {};

package/dist/types/src/interfaces/menuItem.d.ts

@@ -139,4 +139,4 @@ export interface IMenuItem extends BaseMenuItem {
 }
 export interface IMenuItemComp<TData = any, TContext = any> extends IComponent<IMenuItemParams<TData, TContext>>, IMenuItem {
 }
-export type DefaultMenuItem = 'pinSubMenu' | 'pinLeft' | 'pinRight' | 'pinRowSubMenu' | 'pinTop' | 'pinBottom' | 'unpinRow' | 'clearPinned' | 'valueAggSubMenu' | 'autoSizeThis' | 'autoSizeAll' | 'rowGroup' | 'rowUnGroup' | 'resetColumns' | 'expandAll' | 'contractAll' | 'copy' | 'copyWithHeaders' | 'copyWithGroupHeaders' | 'cut' | 'paste' | 'export' | 'csvExport' | 'excelExport' | 'separator' | 'pivotChart' | 'chartRange' | 'columnFilter' | 'columnChooser' | 'sortAscending' | 'sortDescending' | 'sortAbsoluteAscending' | 'sortAbsoluteDescending' | 'sortUnSort';
+export type DefaultMenuItem = 'pinSubMenu' | 'pinLeft' | 'pinRight' | 'pinRowSubMenu' | 'pinTop' | 'pinBottom' | 'unpinRow' | 'clearPinned' | 'valueAggSubMenu' | 'autoSizeThis' | 'autoSizeAll' | 'rowGroup' | 'rowUnGroup' | 'resetColumns' | 'expandAll' | 'contractAll' | 'copy' | 'copyWithHeaders' | 'copyWithGroupHeaders' | 'cut' | 'paste' | 'note' | 'export' | 'csvExport' | 'excelExport' | 'separator' | 'pivotChart' | 'chartRange' | 'columnFilter' | 'columnChooser' | 'sortAscending' | 'sortDescending' | 'sortAbsoluteAscending' | 'sortAbsoluteDescending' | 'sortUnSort';

package/dist/types/src/interfaces/notes.d.ts

@@ -0,0 +1,147 @@
+import type { Bean } from '../context/bean';
+import type { AgColumn } from '../entities/agColumn';
+import type { ColKey } from '../entities/colDef';
+import type { CellCtrl } from '../rendering/cell/cellCtrl';
+import type { RowCtrl } from '../rendering/row/rowCtrl';
+import type { Column } from './iColumn';
+import type { AgGridCommon } from './iCommon';
+import type { IRowNode } from './iRowNode';
+export interface Note<TMetadata = any> {
+    /** Text content of the note. */
+    text: string;
+    /** Set to `true` to make this note readonly. */
+    readOnly?: boolean;
+    /** Optional author of the note. */
+    author?: string;
+    /** Optional creation timestamp. */
+    createdAt?: string;
+    /** Optional updated timestamp. */
+    updatedAt?: string;
+    /** Optional application metadata to be associated with this note. */
+    metadata?: TMetadata;
+}
+export interface NoteParams {
+    /** Column that the note is for. */
+    column: ColKey;
+    /** Row that the note is for. */
+    rowNode: IRowNode;
+    /** If using fullWidthRows the location is `cell` for normal cells. */
+    location?: 'cell';
+}
+export interface FullWidthRowNoteParams {
+    /** Full width row */
+    rowNode: IRowNode;
+    /** Location is `fullWidthRow` for full width row notes. */
+    location: 'fullWidthRow';
+    /** If `embedFullWidthRows=true` identifies the pinned section the note has been applied to. */
+    pinned?: 'left' | 'right';
+}
+export type GetNoteParams = NoteParams | FullWidthRowNoteParams;
+export type SetNoteParams<TMetadata = any> = GetNoteParams & {
+    /** Note to be saved. */
+    note: Note<TMetadata> | undefined;
+};
+export interface NotesDataSourceNoteParams {
+    /** Column for the note. */
+    column: Column;
+    /** Row for the note. */
+    rowNode: IRowNode;
+    /** Location of the note. */
+    location?: 'cell';
+}
+export interface NotesDataSourceFullWidthRowNoteParams {
+    /** Row for the note. */
+    rowNode: IRowNode;
+    /** Location of the note. */
+    location: 'fullWidthRow';
+    /** If `embedFullWidthRows=true` identifies the pinned section the note has been applied to. */
+    pinned?: 'left' | 'right';
+}
+export type NotesDataSourceGetNoteParams = NotesDataSourceNoteParams;
+export interface NotesDataSourceSetNoteParams<TMetadata = any> extends NotesDataSourceNoteParams {
+    /** Note to be saved. */
+    note: Note<TMetadata> | undefined;
+}
+export type FullWidthNotesDataSourceGetNoteParams = NotesDataSourceNoteParams | NotesDataSourceFullWidthRowNoteParams;
+export type FullWidthNotesDataSourceSetNoteParams<TMetadata = any> = NotesDataSourceSetNoteParams<TMetadata> | (NotesDataSourceFullWidthRowNoteParams & {
+    /** Note to be saved. */
+    note: Note<TMetadata> | undefined;
+});
+export interface NotesDataSourceParams extends AgGridCommon<any, any> {
+}
+interface BaseNotesDataSource {
+    /** Initialise the data source so that the user can take a reference to the gridApi if needed. */
+    init?(params: NotesDataSourceParams): void;
+    /** Called by the grid when the data source is being disposed. */
+    destroy?(): void;
+}
+/**
+ * Control where notes are stored/retrieved from.
+ * An implementation can store note state separately from the row data, or persist it remotely.
+ */
+export interface NotesDataSource<TMetadata = any> extends BaseNotesDataSource {
+    /** Return the note for the given cell. */
+    getNote(params: NotesDataSourceGetNoteParams): Note<TMetadata> | undefined;
+    /** Set or clear the note for the given cell. */
+    setNote(params: NotesDataSourceSetNoteParams<TMetadata>): void;
+}
+/**
+ * Control where notes are stored/retrieved from for both cells and full width rows.
+ */
+export interface FullWidthNotesDataSource<TMetadata = any> extends BaseNotesDataSource {
+    /** Enables full width row notes for this datasource. */
+    supportsFullWidthRows: true;
+    /** Return the note for the given cell or full width row. */
+    getNote(params: FullWidthNotesDataSourceGetNoteParams): Note<TMetadata> | undefined;
+    /** Set or clear the note for the given cell or full width row. */
+    setNote(params: FullWidthNotesDataSourceSetNoteParams<TMetadata>): void;
+}
+export interface RefreshNotesParams {
+    /** Only refresh the provided rowNodes. If `undefined` refresh all rows. */
+    rowNodes?: IRowNode[];
+    /** Only refresh the provided columns. If `undefined` refresh all columns. */
+    columns?: (string | Column)[];
+}
+/** @internal AG_GRID_INTERNAL - Not for public use. Can change / be removed at any time. */
+export interface INoteAccess {
+    params: GetNoteParams;
+    rowNode: IRowNode;
+    column: AgColumn;
+    note: Note | undefined;
+    isReadOnly: boolean;
+    isSuppressed: boolean;
+    canView: boolean;
+    canCreate: boolean;
+    canEdit: boolean;
+    canDelete: boolean;
+}
+/** @internal AG_GRID_INTERNAL - Not for public use. Can change / be removed at any time. */
+export interface INotesFeature {
+    refresh(): void;
+    show(params?: {
+        focusEditor?: boolean;
+        pinned?: 'left' | 'right';
+    }): void;
+    hide(save?: boolean): void;
+    destroy(): void;
+}
+/** @internal AG_GRID_INTERNAL - Not for public use. Can change / be removed at any time. */
+export interface INotesDataService extends Bean {
+    hasDataSource(): boolean;
+    supportsFullWidthRows(): boolean;
+    getNote(params: GetNoteParams): Note | undefined;
+    setNote(params: SetNoteParams): void;
+}
+/** @internal AG_GRID_INTERNAL - Not for public use. Can change / be removed at any time. */
+export interface INotesService extends Bean {
+    hasDataSource(): boolean;
+    onDataSourceChanged(): void;
+    createNotesFeature(ctrl: CellCtrl): INotesFeature | undefined;
+    createFullWidthNotesFeature(ctrl: RowCtrl): INotesFeature | undefined;
+    getNoteAccess(params: GetNoteParams): INoteAccess | undefined;
+    getNote(params: GetNoteParams): Note | undefined;
+    showNote(params: GetNoteParams, focusEditor?: boolean): boolean;
+    setNote(params: SetNoteParams): void;
+    refreshNotes(params?: RefreshNotesParams): void;
+}
+export {};