@adaptabletools/adaptable 22.0.0-canary.0 → 22.0.0-canary.10

package/src/agGrid/AdaptableAgGrid.js

@@ -6,6 +6,7 @@ import { PrimaryKeyDocsLink } from '../Utilities/Constants/DocumentationLinkCons
 import StringExtensions from '../Utilities/Extensions/StringExtensions';
 import Emitter from '../Utilities/Emitter';
 import { applyDefaultAdaptableOptions } from '../AdaptableOptions/DefaultAdaptableOptions';
+import { resolveContainerElement } from '../Utilities/resolveContainerElement';
 import { AgGridAdapter } from './AgGridAdapter';
 import * as GeneralConstants from '../Utilities/Constants/GeneralConstants';
 import { AG_GRID_GRAND_TOTAL_ROW_ID, AG_GRID_GROUPED_COLUMN, AUTOGENERATED_PK_COLUMN, ERROR_LAYOUT, GROUP_PATH_SEPARATOR, HALF_SECOND, QUARTER_SECOND, } from '../Utilities/Constants/GeneralConstants';
@@ -155,38 +156,79 @@ LocalEventService_Prototype.dispatchEvent = function (event) {
 const adaptableInstances = {};
 const publishTimestamp = Number(ADAPTABLE_PUBLISH_TIMESTAMP);
 export class AdaptableAgGrid {
+    logger;
+    _id;
+    lifecycleState;
+    variant;
+    emitter;
+    /**
+     * Runtime flags
+     */
+    hasAutogeneratedPrimaryKey;
+    hasAdaptableToolPanel;
+    initWithLazyData;
+    _rawAdaptableOptions;
+    adaptableOptions;
+    _isDetailGrid;
+    _isDetailGridForIndex;
+    agGridOptionsService;
+    agGridAdapter;
+    agGridColumnAdapter;
+    agGridMenuAdapter;
+    agGridExportAdapter;
+    agGridThemeAdapter;
+    agGridModulesAdapter;
+    DANGER_USE_GETTER_adaptableContainerElement;
+    DANGER_USE_GETTER_agGridContainerElement;
+    api;
+    adaptableStore;
+    adaptableModules;
+    DataService;
+    CalculatedColumnExpressionService;
+    ModuleService;
+    ValidationService;
+    QueryLanguageService;
+    AlertService;
+    TeamSharingService;
+    MetamodelService;
+    RowFormService;
+    Fdc3Service;
+    AnnotationsService;
+    FlashingCellService;
+    LicenseService;
+    ChartingService;
+    ThemeService;
+    rowListeners;
+    throttleFilterOnDataChange;
+    debouncedSetSelectedRows;
+    debouncedSetSelectedCells;
+    agGridListenerKeydown;
+    agGridListenerMouseEnter;
+    agGridListenerMouseLeave;
+    listenerGlobalSetRowSelection;
+    listenerGlobalChartingChanges;
+    listenerCellEditingStarted;
+    listenerFirstDataRendered;
+    listenerPivotChanged;
+    listenerCellSelectionChanged;
+    listenerSortChanged;
+    listenerColumnGroupOpened;
+    layoutManager;
+    columnMinMaxValuesCache = {};
+    renderReactRoot = (node, container) => defaultRenderReactRoot(node, container);
+    unmountReactRoot;
+    unmountLoadingScreen;
+    /**
+     * Temporary, these are MIGRATION technical debts, and should be removed as soon as possible
+     */
+    adaptableStatusPanelKeys = [];
+    adaptableStatusPanelDefs = [];
+    hasAdaptableStatusBar;
+    // see #no_additional_react_root
+    _PRIVATE_adaptableJSXElement;
+    _prevLayout;
+    __prevLayoutForRefresh;
     constructor(config) {
-        this.columnMinMaxValuesCache = {};
-        this.renderReactRoot = (node, container) => defaultRenderReactRoot(node, container);
-        /**
-         * Temporary, these are MIGRATION technical debts, and should be removed as soon as possible
-         */
-        this.adaptableStatusPanelKeys = [];
-        // only for our private / internal events used within Adaptable
-        // public events are emitted through the EventApi
-        this._emit = (eventName, data) => {
-            if (this.emitter) {
-                return this.emitter.emit(eventName, data);
-            }
-        };
-        this._emitSync = (eventName, data) => {
-            if (this.emitter) {
-                return this.emitter.emitSync(eventName, data);
-            }
-        };
-        this._on = (eventName, callback) => {
-            if (!this.emitter) {
-                return () => { };
-            }
-            return this.emitter.on(eventName, callback);
-        };
-        this._onIncludeFired = (eventName, callback) => {
-            if (!this.emitter) {
-                return () => { };
-            }
-            return this.emitter.onIncludeFired(eventName, callback);
-        };
-        this.__updateColumnModelAndRefreshGrid_already_called = false;
         this.lifecycleState = 'initial';
         this.emitter = new Emitter();
         this.agGridOptionsService = new AgGridOptionsService(this);
@@ -222,6 +264,30 @@ export class AdaptableAgGrid {
     get isDestroyed() {
         return this.lifecycleState === 'preDestroyed';
     }
+    // only for our private / internal events used within Adaptable
+    // public events are emitted through the EventApi
+    _emit = (eventName, data) => {
+        if (this.emitter) {
+            return this.emitter.emit(eventName, data);
+        }
+    };
+    _emitSync = (eventName, data) => {
+        if (this.emitter) {
+            return this.emitter.emitSync(eventName, data);
+        }
+    };
+    _on = (eventName, callback) => {
+        if (!this.emitter) {
+            return () => { };
+        }
+        return this.emitter.on(eventName, callback);
+    };
+    _onIncludeFired = (eventName, callback) => {
+        if (!this.emitter) {
+            return () => { };
+        }
+        return this.emitter.onIncludeFired(eventName, callback);
+    };
     /**
      * Internal initializer for Adaptable, directly called by the React and Angular Adaptable wrappers
      * @private
@@ -296,7 +362,7 @@ export class AdaptableAgGrid {
         this.adaptableOptions = this.normalizeAdaptableOptions(this.adaptableOptions);
         const { showLoadingScreen, loadingScreenDelay, loadingScreenText, loadingScreenTitle } = this.adaptableOptions.userInterfaceOptions.loadingScreenOptions;
         if (showLoadingScreen) {
-            this.logger.info(`Show Loading Screen`);
+            this.logger.info('Showing loading screen');
             // it's important to use ensureLoadingScreenPortalElement
             // and not ensurePortalElement, because multiple adaptable instances share the same portal element
             // so when displaying the second one, the react root associated to the portal element
@@ -312,7 +378,7 @@ export class AdaptableAgGrid {
                 }), portalElement);
             }
             else {
-                this.logger.consoleError(`Adaptable failed to show the loading screen!`);
+                this.logger.consoleError('Failed to create loading screen portal element.');
             }
         }
         this.forPlugins((plugin) => plugin.afterInitOptions(this, this.adaptableOptions));
@@ -371,7 +437,7 @@ export class AdaptableAgGrid {
         // see #map_dateString_to_date
         this.agGridAdapter.patchColDefs(columnDefs, (colDef) => {
             if (colDef.cellDataType === 'dateString') {
-                this.logger.consoleError(`AG Grid: Column '${colDef.colId}' specifies cellDataType='dateString' which is no longer supported. It has been automatically replaced with cellDataType='date'. Please update your column definition.`);
+                this.logger.consoleError(`Column "${colDef.colId}" uses cellDataType="dateString" which is no longer supported. It has been replaced with cellDataType="date". Please update your column definition.`);
                 colDef.cellDataType = 'date';
             }
         });
@@ -402,8 +468,8 @@ export class AdaptableAgGrid {
         const agGridApi = await this.initializeAgGrid(gridOptions, config.modules, config.renderAgGridFrameworkComponent);
         if (agGridApi === false) {
             this.midwayDestroy();
-            this.logger.consoleError(`Adaptable failed to initialize AG Grid!`);
-            return Promise.reject('Adaptable failed to initialize AG Grid!');
+            this.logger.consoleError('Failed to initialize AG Grid.');
+            return Promise.reject('Failed to initialize AG Grid.');
         }
         this.layoutManager = new LayoutManager({
             gridApi: agGridApi,
@@ -428,7 +494,7 @@ export class AdaptableAgGrid {
         this.layoutManager.onColumnDefsChanged(() => {
             this.updateColumnModelAndRefreshGrid();
         });
-        this.logger.info(`Hide Loading Screen`);
+        this.logger.info('Hiding loading screen');
         this.unmountLoadingScreen?.();
         perfInitAgGrid.end();
         initAgGridMarker.end();
@@ -439,7 +505,7 @@ export class AdaptableAgGrid {
         this.lifecycleState = 'agGridReady';
         this.api.entitlementApi.internalApi.setModulesAgGridDepsInfos();
         this.ModuleService.logMissingAgGridDepsInfos();
-        this.logger.info(`Registered AG Grid modules (incl. dependent modules): `, this.agGridModulesAdapter.getAgGridRegisteredModuleNames().sort());
+        this.logger.info('Registered AG Grid modules (including dependents):', this.agGridModulesAdapter.getAgGridRegisteredModuleNames().sort());
         /**
          * At this point AG Grid is initialized!
          */
@@ -529,10 +595,7 @@ export class AdaptableAgGrid {
         const layoutState = state.Layout;
         // ensure that at least one Layout has been provided
         if (!layoutState || !layoutState.Layouts?.length) {
-            this.logger
-                .consoleError(`You have not defined any Layout in your InitialState.Layout.Layouts[] state!
-
-You need to define at least one Layout!`);
+            this.logger.consoleError('No Layouts defined in InitialState.Layout.Layouts[]. At least one Layout is required.');
         }
         // ensure CurrentLayout is valid
         if (!layoutState.CurrentLayout ||
@@ -654,11 +717,8 @@ You need to define at least one Layout!`);
         // FIXME AFL FILTER why is this needed???
         this.refreshSelectedCellsState();
         this.refreshSelectedRowsState();
-        // FIXME AFL: this is temporary, will be replaced with v22's new autoCol filtering
-        const currentPivotLayoutHasAutoCols = this.api.layoutApi.isCurrentLayoutPivot() &&
-            !!this.api.layoutApi.getCurrentRowGroupsColumnIds()?.length;
         // agGridApi.setFilterModel() already triggered onFilterChanged(), so we skip it if updateColumnFilterModel is TRUE
-        if (!filteringApplied || currentPivotLayoutHasAutoCols) {
+        if (!filteringApplied) {
             agGridApi.onFilterChanged();
             filteringApplied = true;
         }
@@ -698,21 +758,90 @@ You need to define at least one Layout!`);
     hideQuickFilter() {
         this.agGridAdapter.getAgGridApi().setGridOption('floatingFiltersHeight', 0);
     }
+    showAdaptableToolPanel() {
+        if (!this.hasAdaptableToolPanel) {
+            // don't re-add the ToolPanel if it's hidden by entitlement
+            if (this.api.entitlementApi.isModuleHiddenEntitlement('ToolPanel')) {
+                return;
+            }
+            const currentSideBar = this.agGridAdapter.getGridOption('sideBar');
+            if (currentSideBar?.toolPanels) {
+                const updatedSideBar = {
+                    ...currentSideBar,
+                    toolPanels: [...currentSideBar.toolPanels, this.buildAdaptableToolPanelDef()],
+                };
+                this.agGridAdapter.setGridOption('sideBar', updatedSideBar);
+                this.hasAdaptableToolPanel = true;
+            }
+        }
+    }
+    hideAdaptableToolPanel() {
+        if (this.hasAdaptableToolPanel) {
+            // close the tool panel if it's currently open
+            this.api.toolPanelApi.closeAdapTableToolPanel();
+            const currentSideBar = this.agGridAdapter.getGridOption('sideBar');
+            if (currentSideBar?.toolPanels) {
+                const updatedSideBar = {
+                    ...currentSideBar,
+                    toolPanels: currentSideBar.toolPanels.filter((toolPanelDef) => {
+                        if (typeof toolPanelDef === 'string') {
+                            return toolPanelDef !== GeneralConstants.ADAPTABLE_TOOLPANEL_ID;
+                        }
+                        return toolPanelDef.id !== GeneralConstants.ADAPTABLE_TOOLPANEL_ID;
+                    }),
+                };
+                this.agGridAdapter.setGridOption('sideBar', updatedSideBar);
+            }
+            this.hasAdaptableToolPanel = false;
+        }
+    }
+    buildAdaptableToolPanelDef() {
+        return {
+            id: GeneralConstants.ADAPTABLE_TOOLPANEL_ID,
+            toolPanel: GeneralConstants.ADAPTABLE_TOOLPANEL_COMPONENT,
+            labelDefault: GeneralConstants.ADAPTABLE,
+            labelKey: 'adaptable',
+            iconKey: 'menu',
+            width: UIHelper.getAdaptableToolPanelWidth(),
+            minWidth: UIHelper.getAdaptableToolPanelWidth(),
+        };
+    }
+    showAdaptableStatusBar() {
+        if (!this.hasAdaptableStatusBar && this.adaptableStatusPanelDefs.length > 0) {
+            const currentStatusBar = this.agGridAdapter.getGridOption('statusBar');
+            if (currentStatusBar) {
+                // filter out any Adaptable panels that may already exist to avoid duplicates
+                const existingNonAdaptablePanels = (currentStatusBar.statusPanels ?? []).filter((panel) => !this.adaptableStatusPanelKeys.includes(panel.key));
+                const updatedStatusBar = {
+                    ...currentStatusBar,
+                    statusPanels: [...existingNonAdaptablePanels, ...this.adaptableStatusPanelDefs],
+                };
+                this.agGridAdapter.setGridOption('statusBar', updatedStatusBar);
+                this.hasAdaptableStatusBar = true;
+            }
+        }
+    }
+    hideAdaptableStatusBar() {
+        if (this.hasAdaptableStatusBar) {
+            const currentStatusBar = this.agGridAdapter.getGridOption('statusBar');
+            if (currentStatusBar?.statusPanels) {
+                const updatedStatusBar = {
+                    ...currentStatusBar,
+                    statusPanels: currentStatusBar.statusPanels.filter((panel) => !this.adaptableStatusPanelKeys.includes(panel.key)),
+                };
+                this.agGridAdapter.setGridOption('statusBar', updatedStatusBar);
+            }
+            this.hasAdaptableStatusBar = false;
+        }
+    }
     normalizeAdaptableOptions(adaptableOptions) {
         if (this.hasAutogeneratedPrimaryKey) {
-            this.logger
-                .warn(`Autogenerated primary key (adaptableOptions.autogeneratedPrimaryKey = TRUE) should be used only as a last resort,
-      when no unique column is available, as it limits some Adaptable functionalities!
-
-      For more details see: ${PrimaryKeyDocsLink}`);
+            this.logger.warn(`Autogenerated primary key is enabled (adaptableOptions.autogeneratedPrimaryKey = true). This should be a last resort as it limits some Adaptable features. See: ${PrimaryKeyDocsLink}`);
             this.adaptableOptions.primaryKey = AUTOGENERATED_PK_COLUMN;
             return this.adaptableOptions;
         }
         if (StringExtensions.IsNullOrEmpty(adaptableOptions.primaryKey)) {
-            this.logger.consoleError(`AdaptableOptions.primaryKey is required and cannot be empty or null!
-      As a fallback, you can set adaptableOptions.autogeneratedPrimaryKey = TRUE
-
-      For more details see: ${PrimaryKeyDocsLink}`);
+            this.logger.consoleError(`adaptableOptions.primaryKey is required and must not be empty. As a fallback, set adaptableOptions.autogeneratedPrimaryKey = true. See: ${PrimaryKeyDocsLink}`);
         }
         return adaptableOptions;
     }
@@ -744,7 +873,7 @@ You need to define at least one Layout!`);
          */
         this.agGridOptionsService.setGridOptionsProperty(gridOptions, 'defaultColDef', (original_defaultColDef) => {
             if (original_defaultColDef?.headerValueGetter) {
-                this.logger.warn(`defaultColDef.headerValueGetter and overrides the Adaptable custom header mechanism! We recommend using a ColumnOptions.columnHeader instead!`);
+                this.logger.warn('defaultColDef.headerValueGetter overrides the Adaptable header mechanism. Consider using ColumnOptions.columnHeader instead.');
                 return original_defaultColDef;
             }
             // #customize_header
@@ -761,7 +890,7 @@ You need to define at least one Layout!`);
          */
         this.agGridOptionsService.setGridOptionsProperty(gridOptions, 'defaultColGroupDef', (original_defaultColGroupDef) => {
             if (original_defaultColGroupDef?.headerValueGetter) {
-                this.logger.warn(`defaultColGroupDef.headerValueGetter and overrides the Adaptable custom header mechanism! We recommend using a ColumnOptions.tableColumnHeader instead!`);
+                this.logger.warn('defaultColGroupDef.headerValueGetter overrides the Adaptable header mechanism. Consider using ColumnOptions.tableColumnHeader instead.');
                 return original_defaultColGroupDef;
             }
             const defaultColGroupDef = { ...original_defaultColGroupDef };
@@ -781,11 +910,11 @@ You need to define at least one Layout!`);
             }
             if (original_autoGroupColumnDef?.filter === false) {
                 // if user disables filter on autoGroupColumnDef, we respect that
-                this.logger.info(`autoGroupColumnDef.filter is disabled as per user configuration.`);
+                this.logger.info('autoGroupColumnDef.filter is disabled via user configuration.');
                 return original_autoGroupColumnDef;
             }
             if (typeof original_autoGroupColumnDef?.filter === 'object') {
-                this.logger.warn(`autoGroupColumnDef.filter is set and overrides the Adaptable custom filter mechanism! We recommend using a ColumnOptions.columnHeader instead!`);
+                this.logger.consoleWarn('autoGroupColumnDef.filter overrides the Adaptable filtering mechanism for the Group Column. Adaptable-managed filters will not apply to this column. Contact support for alternatives.');
                 return original_autoGroupColumnDef;
             }
             const autoGroupColumnDef = { ...original_autoGroupColumnDef };
@@ -793,7 +922,7 @@ You need to define at least one Layout!`);
             // !! DO NOT REMOVE THIS !!
             // see https://github.com/ag-grid/ag-grid/blob/6f43ff257c2e285068eb425b655e58d6eeb89816/packages/ag-grid-enterprise/src/rowHierarchy/autoColService.ts#L225
             autoGroupColumnDef.filterValueGetter = (params) => {
-                this.logger.error('autoGroupColumnDef.filterValueGetter was called unexpectedly; this is not an expected execution path!', params);
+                this.logger.consoleWarn('Unexpected invocation of autoGroupColumnDef.filterValueGetter. This is not expected under normal operation. Please contact support.', params);
                 return '';
             };
             // !! it is important that we always return the same component / handler instances
@@ -1107,16 +1236,7 @@ You need to define at least one Layout!`);
                     return original_sideBar;
                 }
                 const isAdaptableToolPanelHidden = this.api.entitlementApi.isModuleHiddenEntitlement('ToolPanel');
-                const adaptableToolPanelDef = {
-                    id: GeneralConstants.ADAPTABLE_TOOLPANEL_ID,
-                    toolPanel: GeneralConstants.ADAPTABLE_TOOLPANEL_COMPONENT,
-                    labelDefault: GeneralConstants.ADAPTABLE,
-                    labelKey: 'adaptable',
-                    iconKey: 'menu',
-                    width: UIHelper.getAdaptableToolPanelWidth(),
-                    minWidth: UIHelper.getAdaptableToolPanelWidth(),
-                    // maxWidth = undefined,
-                };
+                const adaptableToolPanelDef = this.buildAdaptableToolPanelDef();
                 const mapToolPanelDefs = (toolPanelDefs = []) => {
                     // if it's an alias for the adaptable tool panel, map it to a ToolPanelDef, otherwise return it as it is
                     return toolPanelDefs.map((toolPanelDef) => toolPanelDef === GeneralConstants.ADAPTABLE_TOOLPANEL_ID
@@ -1191,19 +1311,29 @@ You need to define at least one Layout!`);
             this.agGridOptionsService.setGridOptionsProperty(gridOptions, 'statusBar', (original_statusBar) => {
                 const statusPanels = (original_statusBar?.statusPanels ?? [])?.map((statusPanel) => {
                     if (statusPanel.statusPanel === ADAPTABLE_STATUS_PANEL) {
+                        if (!statusPanel.key) {
+                            this.logger.consoleWarn('AdaptableStatusPanel is missing a "key" property. This panel will not be managed by HideAdaptableUI. Please provide a unique key.');
+                            return statusPanel;
+                        }
                         this.adaptableStatusPanelKeys.push(statusPanel.key);
                         const context = {
                             Key: statusPanel.key,
                         };
-                        return {
+                        const adaptablePanelDef = {
                             ...statusPanel,
                             statusPanel: createAgStatusPanelComponent(AdaptableStatusBar, this, context),
                         };
+                        this.adaptableStatusPanelDefs.push(adaptablePanelDef);
+                        return adaptablePanelDef;
                     }
                     return statusPanel;
                 });
                 return { ...original_statusBar, statusPanels };
             });
+            this.hasAdaptableStatusBar = this.adaptableStatusPanelKeys.length > 0;
+        }
+        else {
+            this.hasAdaptableStatusBar = false;
         }
         /**
          * `getRowStyle`
@@ -1363,15 +1493,14 @@ You need to define at least one Layout!`);
             const rowData = agGridApi.getGridOption('rowData');
             this.initWithLazyData = rowData == undefined || rowData.length === 0;
             if (this.initWithLazyData) {
-                this.logger.info('initWithLazyData = TRUE');
+                this.logger.info('Initializing with lazy data (no initial rowData).');
             }
             if (!this.getAgGridContainerElement()) {
                 // initialize the agGridContainerElement from the AgGrid instance
                 const gridRoot = this.agGridAdapter.getAgGridRootElement();
                 const gridContainer = gridRoot?.closest('[class*="ag-theme"]');
                 if (!gridContainer) {
-                    this.logger.consoleError(`No AG Grid container could be derived from the Adaptable framework wrapper.
-            Please contact AdapTable Support and in the meantime provide a valid container element in 'ContainerOptions.agGridContainer'!`);
+                    this.logger.consoleError('Failed to derive AG Grid container from the framework wrapper. Please provide a valid container element via ContainerOptions.agGridContainer.');
                 }
                 this.DANGER_USE_GETTER_agGridContainerElement = gridContainer;
             }
@@ -1379,7 +1508,7 @@ You need to define at least one Layout!`);
         }
         const agGridContainer = this.getAgGridContainerElement();
         if (!agGridContainer) {
-            this.logger.consoleError('No AG Grid container element found in the DOM. Please provide a valid container element in `ContainerOptions.agGridContainer`');
+            this.logger.consoleError('AG Grid container element not found in the DOM. Please provide a valid element via ContainerOptions.agGridContainer.');
             return Promise.resolve(false);
         }
         let gridParams;
@@ -1392,21 +1521,22 @@ You need to define at least one Layout!`);
     useRowNodeLookUp() {
         return this.agGridAdapter.getAgGridApi().getGridOption('getRowId') != undefined;
     }
+    buildInitContainerContext() {
+        return {
+            adaptableId: this.adaptableOptions?.adaptableId ?? '',
+            adaptableStateKey: this.adaptableOptions?.adaptableStateKey ?? '',
+            adaptableContext: this.adaptableOptions?.adaptableContext,
+        };
+    }
     getAgGridContainerElement() {
         if (!this.DANGER_USE_GETTER_agGridContainerElement) {
-            this.DANGER_USE_GETTER_agGridContainerElement =
-                typeof this.adaptableOptions?.containerOptions?.agGridContainer === 'string'
-                    ? document.getElementById(this.adaptableOptions?.containerOptions?.agGridContainer)
-                    : this.adaptableOptions?.containerOptions?.agGridContainer;
+            this.DANGER_USE_GETTER_agGridContainerElement = resolveContainerElement(this.adaptableOptions?.containerOptions?.agGridContainer, this.buildInitContainerContext());
         }
         return this.DANGER_USE_GETTER_agGridContainerElement;
     }
     getAdaptableContainerElement() {
         if (!this.DANGER_USE_GETTER_adaptableContainerElement) {
-            this.DANGER_USE_GETTER_adaptableContainerElement =
-                typeof this.adaptableOptions?.containerOptions?.adaptableContainer === 'string'
-                    ? document.getElementById(this.adaptableOptions?.containerOptions?.adaptableContainer)
-                    : this.adaptableOptions?.containerOptions?.adaptableContainer;
+            this.DANGER_USE_GETTER_adaptableContainerElement = resolveContainerElement(this.adaptableOptions?.containerOptions?.adaptableContainer, this.buildInitContainerContext());
         }
         return this.DANGER_USE_GETTER_adaptableContainerElement;
     }
@@ -1794,7 +1924,7 @@ You need to define at least one Layout!`);
             // if no primary key column then lets check the first row to see if its a data item
             const primaryKeyDataItem = this.getFirstRowNode()?.data[primaryKey];
             if (!primaryKeyDataItem) {
-                errorMessage = `The Primary Key '${this.adaptableOptions.primaryKey}' does not exist.  This will affect many functions in AdapTable.`;
+                errorMessage = `Primary key column "${this.adaptableOptions.primaryKey}" not found. This will affect many Adaptable features.`;
                 if (this.adaptableOptions.alertOptions.showMissingPrimaryKeyAlert) {
                     // show an alert if that is the option
                     this.api.alertApi.showAlertError('No Primary Key', errorMessage);
@@ -1851,12 +1981,12 @@ You need to define at least one Layout!`);
     checkShouldClearExistingFiltersOrSearches() {
         // if they have selected to clear Filters on startup then do it
         if (this.adaptableOptions.filterOptions.clearFiltersOnStartUp) {
-            this.logger.warn('Clearing any saved Filters as "clearFiltersOnStartUp" is true');
+            this.logger.warn('Clearing saved filters (clearFiltersOnStartUp is enabled).');
             this.api.filterApi.clearAllFilters();
         }
         // if they have selected to clear searches on startup then do it
         if (this.adaptableOptions.quickSearchOptions.clearQuickSearchOnStartUp) {
-            this.logger.warn('Clearing any saved Searches as "clearQuickSearchOnStartUp" is true');
+            this.logger.warn('Clearing saved Quick Search (clearQuickSearchOnStartUp is enabled).');
             this.api.quickSearchApi.clearQuickSearch();
         }
     }
@@ -2069,6 +2199,7 @@ You need to define at least one Layout!`);
         }
         return rawValue;
     }
+    __updateColumnModelAndRefreshGrid_already_called = false;
     updateColumnModelAndRefreshGrid() {
         if (this.__updateColumnModelAndRefreshGrid_already_called) {
             return;
@@ -2084,7 +2215,7 @@ You need to define at least one Layout!`);
         }
     }
     _updateColumnModelAndRefreshGridNow() {
-        this.logger.info(`Updating Column Model and Refreshing Grid.`);
+        this.logger.info('Updating column model and refreshing grid.');
         this.deriveAdaptableColumnStateFromAgGrid();
         this.agGridColumnAdapter.setupColumns();
         this.redrawBody();
@@ -2110,7 +2241,7 @@ You need to define at least one Layout!`);
             this.agGridAdapter.getAgGridApi().redrawRows(redrawRowsParams);
         }
         catch (ex) {
-            this.logger.consoleError('AG Grid redrawRows was unable to find some row nodes. Tried to redraw row nodes: ', rowNodes, ex);
+            this.logger.consoleError('AG Grid redrawRows failed to locate some row nodes.', rowNodes, ex);
         }
     }
     redrawRow(rowNode) {
@@ -2404,6 +2535,69 @@ You need to define at least one Layout!`);
             });
         }
     }
+    async manageGridRows(dataRowConfig, dataUpdateConfig = {}) {
+        const result = {
+            addedRows: [],
+            updatedRows: [],
+            removedRows: [],
+        };
+        if (!dataRowConfig) {
+            return result;
+        }
+        if (!dataRowConfig.addRows || !dataRowConfig.updateRows || !dataRowConfig.deleteRows) {
+            return result;
+        }
+        const addDataRows = dataRowConfig.addRows;
+        const updateDataRows = dataRowConfig.updateRows;
+        const removeDataRows = dataRowConfig.deleteRows;
+        if (this.hasAutogeneratedPrimaryKey) {
+            this.addSyntheticPrimaryKeyIfMissing(addDataRows);
+        }
+        if (dataUpdateConfig.runAsync) {
+            return new Promise((resolve) => {
+                this.applyAgGridTransactionAsync({
+                    update: updateDataRows,
+                    add: addDataRows,
+                    remove: removeDataRows,
+                    addIndex: dataUpdateConfig.addIndex,
+                }, (transaction) => {
+                    if (typeof dataUpdateConfig.callback === 'function') {
+                        dataUpdateConfig.callback(transaction);
+                    }
+                    if (transaction?.add) {
+                        this.updateRowGroupsAndColumnGroupsExpandedState();
+                    }
+                    resolve({
+                        addedRows: transaction?.add,
+                        updatedRows: transaction?.update,
+                        removedRows: transaction?.remove,
+                    });
+                });
+                if (dataUpdateConfig.flushAsync) {
+                    this.agGridAdapter.getAgGridApi().flushAsyncTransactions();
+                }
+            });
+        }
+        else {
+            const transaction = this.applyAgGridTransaction({
+                update: updateDataRows,
+                add: addDataRows,
+                remove: removeDataRows,
+                addIndex: dataUpdateConfig.addIndex,
+            });
+            if (transaction?.add) {
+                this.updateRowGroupsAndColumnGroupsExpandedState();
+            }
+            if (dataUpdateConfig.flushAsync) {
+                this.agGridAdapter.getAgGridApi().flushAsyncTransactions();
+            }
+            return Promise.resolve({
+                addedRows: transaction?.add,
+                updatedRows: transaction?.update,
+                removedRows: transaction?.remove,
+            });
+        }
+    }
     deleteRows(dataRows, dataUpdateConfig) {
         dataUpdateConfig = dataUpdateConfig || {};
         if (dataUpdateConfig.runAsync) {
@@ -2460,14 +2654,14 @@ You need to define at least one Layout!`);
     }
     autoSizeColumns(columnIds) {
         if (!this.agGridModulesAdapter.isAgGridModuleRegistered('ColumnAutoSizeModule')) {
-            this.logger.consoleError(`Could not auto-size columns [${columnIds}] - missing required AG Grid module 'ColumnAutoSizeModule'`);
+            this.logger.consoleError(`Auto-sizing columns [${columnIds}] requires the AG Grid "ColumnAutoSizeModule". Please register this module.`);
             return;
         }
         this.layoutManager.autoSizeColumns(columnIds);
     }
     autoSizeAllColumns() {
         if (!this.agGridModulesAdapter.isAgGridModuleRegistered('ColumnAutoSizeModule')) {
-            this.logger.consoleError(`Could not auto-size all columns - missing required AG Grid module 'ColumnAutoSizeModule'`);
+            this.logger.consoleError('Auto-sizing all columns requires the AG Grid "ColumnAutoSizeModule". Please register this module.');
             return;
         }
         const agGridApi = this.agGridAdapter.getAgGridApi();
@@ -2625,7 +2819,7 @@ You need to define at least one Layout!`);
                 customInFilterValuesResult = await customInFilterValues(customInFilterValuesContext);
             }
             catch (error) {
-                this.logger.consoleError(`Failed to fetch custom filter values`, column, error);
+                this.logger.consoleError('Failed to retrieve custom filter values.', column, error);
             }
             return customInFilterValuesResult;
         }
@@ -2665,7 +2859,7 @@ You need to define at least one Layout!`);
                     customDistinctValues = await customEditColumnValues(customEditValuesContext);
                 }
                 catch (error) {
-                    this.logger.consoleError(`Failed to fetch custom edit values`, column, error);
+                    this.logger.consoleError('Failed to retrieve custom edit values.', column, error);
                 }
                 return customDistinctValues ?? [];
             }
@@ -3120,7 +3314,7 @@ You need to define at least one Layout!`);
         if (this.getAgGridRowModelType() !== 'clientSide') {
             // only in client-side row model can we loop through filtered&sorted rows
             // see https://www.ag-grid.com/javascript-data-grid/accessing-data/#iterating-rows
-            this.logger.warn('`forAllVisibleRowNodesDo()` is only supported in client-side row model. `forAllRowNodesDo` will be used instead.');
+            this.logger.warn('forAllVisibleRowNodesDo() is only supported with client-side row model. Falling back to forAllRowNodesDo().');
             return this.forAllRowNodesDo(func, config);
         }
         this.agGridAdapter.getAgGridApi().forEachNodeAfterFilterAndSort((rowNode, rowIndex) => {
@@ -3172,14 +3366,14 @@ You need to define at least one Layout!`);
     }
     selectNode(rowNode, clearSelection) {
         if (!rowNode) {
-            this.logger.error('No node to select');
+            this.logger.error('Cannot select: row node is null.');
             return;
         }
         rowNode.setSelected(true, clearSelection);
     }
     deSelectNode(rowNode, clearSelection) {
         if (!rowNode) {
-            this.logger.error('No node to deselect');
+            this.logger.error('Cannot deselect: row node is null.');
             return;
         }
         rowNode.setSelected(false, clearSelection);
@@ -3267,7 +3461,7 @@ You need to define at least one Layout!`);
     }
     showChart(chartDefinition, container) {
         if (!this.isReady) {
-            this.logger.consoleError('Adaptable must be instantiated before calling showChart');
+            this.logger.consoleError('Cannot call showChart before Adaptable is fully initialized.');
             return null;
         }
         /**
@@ -3288,7 +3482,7 @@ You need to define at least one Layout!`);
     }
     updateChart(chart) {
         if (!chart.Model) {
-            this.logger.consoleError(`Chart definition must have a Model property to be updated: ${chart.Name}`);
+            this.logger.consoleError(`Cannot update chart "${chart.Name}": the chart definition is missing the required Model property.`);
             return;
         }
         const upgradableProperties = {
@@ -3300,12 +3494,21 @@ You need to define at least one Layout!`);
             suppressChartRanges: Boolean(chart.Model.suppressChartRanges),
             aggFunc: chart.Model.aggFunc,
         };
+        // Skip the AG Grid API call if the upgradable properties haven't changed
+        // to avoid unnecessary chartOptionsChanged events (see #ag_grid_update_chart_loop)
+        const currentModel = this.getChartModels().find((model) => model.chartId === chart.Model.chartId);
+        if (currentModel &&
+            Boolean(currentModel.unlinkChart) === upgradableProperties.unlinkChart &&
+            Boolean(currentModel.suppressChartRanges) === upgradableProperties.suppressChartRanges &&
+            currentModel.aggFunc === upgradableProperties.aggFunc) {
+            return;
+        }
         // see also #ag_grid_update_chart_loop
         this.agGridAdapter.getAgGridApi().updateChart(upgradableProperties);
     }
     getChartModels() {
         if (!this.isReady) {
-            this.logger.consoleError('Adaptable must be instantiated before calling getChartModels');
+            this.logger.consoleError('Cannot call getChartModels before Adaptable is fully initialized.');
             return [];
         }
         return this.agGridAdapter.getAgGridApi().getChartModels();
@@ -3339,7 +3542,7 @@ You need to define at least one Layout!`);
     }
     setAgGridQuickSearch(searchText) {
         if (!this.agGridModulesAdapter.isAgGridModuleRegistered('QuickFilterModule')) {
-            this.logger.consoleError(`Can NOT set Quick Search text - missing required AG Grid module 'QuickFilterModule'`);
+            this.logger.consoleError('Quick Search requires the AG Grid "QuickFilterModule". Please register this module to enable Quick Search.');
             return;
         }
         this.agGridAdapter.setGridOption('quickFilterText', searchText);
@@ -3349,7 +3552,7 @@ You need to define at least one Layout!`);
     }
     setAgGridFindSearchValue(searchText) {
         if (!this.agGridModulesAdapter.isAgGridModuleRegistered('FindModule')) {
-            this.logger.consoleError(`Can NOT set Find Search text - missing required AG Grid module 'FindModule'`);
+            this.logger.consoleError('Find Search requires the AG Grid "FindModule". Please register this module to enable Find Search.');
             return;
         }
         this.agGridAdapter.setGridOption('findSearchValue', searchText);
@@ -3878,7 +4081,7 @@ You need to define at least one Layout!`);
         cellDataChangedInfos.forEach((cellDataChangedInfo) => {
             // if a Cell Data Change is undone, log to the Console
             if (cellDataChangedInfo.trigger === 'undo') {
-                this.logger.info(`Undo data change: PK(${cellDataChangedInfo.primaryKeyValue}) Col(${cellDataChangedInfo.column}) RevertedValue(${cellDataChangedInfo.oldValue}) OriginalValue(${cellDataChangedInfo.newValue})`);
+                this.logger.info(`Data change reverted: column="${cellDataChangedInfo.column}", primaryKey="${cellDataChangedInfo.primaryKeyValue}", from=${cellDataChangedInfo.newValue} to=${cellDataChangedInfo.oldValue}`);
             }
             // For Changes except Aggregations, reset cell selection if required
             if (cellDataChangedInfo.trigger === 'edit' ||
@@ -4083,7 +4286,7 @@ You need to define at least one Layout!`);
         this.api.layoutApi.createOrUpdateLayout(layout);
     }
     refreshAdaptableAfterLayoutChange(layout) {
-        this.logger.info('refreshAdaptableAfterLayoutChange()');
+        this.logger.info('Refreshing Adaptable after layout change.');
         const prevLayoutForRefresh = this.__prevLayoutForRefresh || this.api.layoutApi.getCurrentLayout();
         // see #on-regroup-expect-group-column-to-be-recomputed-and-setup-properly
         const rowGroupsChanged = this.isRowGroupDifferentInLayout(prevLayoutForRefresh, layout);
@@ -4129,7 +4332,7 @@ You need to define at least one Layout!`);
                 .forEach((colType) => {
                 const newValidCellDataType = mapOldTypeToDataType(colType);
                 if (newValidCellDataType) {
-                    this.logger.consoleWarn(`Column ${columnDefinition.colId ?? columnDefinition.field} has a type of ${colType} which is no longer in use${newValidCellDataType !== 'unknown' ? `. Please use 'colDef.cellDataType' instead: ${newValidCellDataType}` : ''}`);
+                    this.logger.consoleWarn(`Column "${columnDefinition.colId ?? columnDefinition.field}" uses deprecated type "${colType}"${newValidCellDataType !== 'unknown' ? `. Use colDef.cellDataType="${newValidCellDataType}" instead.` : '. This type is no longer supported.'}`);
                 }
             });
         });