@xh/hoist 59.3.1 → 59.4.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 59.4.0 - 2023-11-28
+
+### 💥 Breaking Changes
+
+* The constructors for `ColumnGroup` no long accept arbitrary rest (e.g `...rest`)
+arguments for applying app-specific data to the object. Instead, use the new `appData` property.
+
+### ⚙️ Technical
+
+* Enhanced `LogUtils` to support logging objects (and any other non-string values). Also
+  added new exports for `logWarn()` and `logError()` with the same standardized formatting.
+* Added standardized `LogUtils` methods to `HoistBase`, for use within Hoist models and services.
+
+### 🐞 Bug Fixes
+
+* `ZoneGrid` will no longer render labels or delimiters for empty values.
+
+### ⚙️ Typescript API Adjustments
+
+* Updated type for `ReactionSpec.equals` to include already-supported string shorthands.
+
+## 59.3.2 - 2023-11-21
+
+### 🐞 Bug Fixes
+
+* `ZoneGrid` will more gracefully handle state that has become out of sync with its mapper
+  requirements.
+
 ## 59.3.1 - 2023-11-10
 
 ### 🐞 Bug Fixes
@@ -49,9 +77,9 @@
 * Improved core `HoistComponent` performance by preventing unnecessary re-renderings triggered by
   spurious model lookup changes.
 * New flag `GridModel.experimental.enableFullWidthScroll` enables scrollbars to span pinned columns.
-  * Early test release behind the flag, expected to made the default behavior in next release.
+    * Early test release behind the flag, expected to made the default behavior in next release.
 * Renamed `XH.getActiveModels()` to `XH.getModels()` for clarity / consistency.
-  * API change, but not expected to impact applications.
+    * API change, but not expected to impact applications.
 * Added `XH.getModel()` convenience method to return the first matching model.
 
 ## 59.2.0 - 2023-10-16

package/admin/differ/DifferModel.ts

@@ -6,18 +6,16 @@
  */
 
 import {GridModel} from '@xh/hoist/cmp/grid';
+import {div, hbox, p} from '@xh/hoist/cmp/layout';
 import {HoistModel, LoadSpec, managed, XH} from '@xh/hoist/core';
+import {RecordActionSpec} from '@xh/hoist/data';
 import {actionCol} from '@xh/hoist/desktop/cmp/grid';
-import {div, p} from '@xh/hoist/cmp/layout';
 import {Icon} from '@xh/hoist/icon';
-import {bindable, makeObservable, observable, action} from '@xh/hoist/mobx';
+import {action, bindable, makeObservable, observable} from '@xh/hoist/mobx';
 import {pluralize} from '@xh/hoist/utils/js';
-import {hbox} from '@xh/hoist/cmp/layout';
-import {cloneDeep, isEqual, isString, isNil, omit, remove, trimEnd} from 'lodash';
+import {cloneDeep, isEqual, isNil, isString, omit, remove, trimEnd} from 'lodash';
 import {hspacer} from '../../cmp/layout';
-
 import {DifferDetailModel} from './DifferDetailModel';
-import {RecordActionSpec} from '@xh/hoist/data';
 
 /**
  * @internal
@@ -378,7 +376,7 @@ export class DifferModel extends HoistModel {
             content = await window.navigator.clipboard.readText();
             content = JSON.parse(content);
         } catch (e) {
-            console.warn('Error reading config from clipboard', e);
+            this.logWarn('Error reading config from clipboard', e);
         }
 
         this.clipboardContent = content;

package/appcontainer/AppContainerModel.ts

@@ -114,8 +114,8 @@ export class AppContainerModel extends HoistModel {
     }
 
     /**
-     * Called when application container first mounted in order to trigger initial
-     * authentication and initialization of framework and application.
+     * Called when {@link AppContainer} first mounted.
+     * Triggers initial authentication and initialization of Hoist and application.
      */
     async initAsync() {
         // Avoid multiple calls, which can occur if AppContainer remounted.
@@ -196,14 +196,12 @@ export class AppContainerModel extends HoistModel {
                 numbro['BigNumber'].clone();
             }
 
-            // Confirm hoist-core version after environment service loaded
-            const hcVersion = XH.environmentService.get('hoistCoreVersion');
-            if (!checkMinVersion(hcVersion, MIN_HOIST_CORE_VERSION)) {
-                throw XH.exception(`
-                    This version of Hoist React requires the server to run Hoist Core
-                    v${MIN_HOIST_CORE_VERSION} or greater. Version ${hcVersion} detected.
-                `);
-            }
+            // Confirm hoist-core version after environment service loaded.
+            const hcVersion = XH.getEnv('hoistCoreVersion');
+            throwIf(
+                !checkMinVersion(hcVersion, MIN_HOIST_CORE_VERSION),
+                `This version of Hoist React requires the server to run Hoist Core ≥ v${MIN_HOIST_CORE_VERSION}. Version ${hcVersion} detected.`
+            );
 
             await installServicesAsync([
                 AlertBannerService,

package/appcontainer/AppStateModel.ts

@@ -7,7 +7,7 @@
 import {AppState, AppSuspendData, HoistModel, XH} from '@xh/hoist/core';
 import {action, makeObservable, observable, reaction} from '@xh/hoist/mobx';
 import {Timer} from '@xh/hoist/utils/async';
-import {getClientDeviceInfo, logDebug} from '@xh/hoist/utils/js';
+import {getClientDeviceInfo} from '@xh/hoist/utils/js';
 import {isBoolean, isString} from 'lodash';
 
 /**
@@ -34,7 +34,7 @@ export class AppStateModel extends HoistModel {
     @action
     setAppState(nextState: AppState) {
         if (this.state !== nextState) {
-            logDebug(`AppState change: ${this.state} → ${nextState}`, this);
+            this.logDebug(`AppState change: ${this.state} → ${nextState}`);
         }
         this.state = nextState;
     }
@@ -87,6 +87,7 @@ export class AppStateModel extends HoistModel {
                                 appVersion: XH.appVersion,
                                 appBuild: XH.appBuild,
                                 locationHref: window.location.href,
+                                wasDiscarded: window.document['wasDiscarded'],
                                 ...getClientDeviceInfo()
                             },
                             logData: ['appVersion', 'appBuild'],

package/appcontainer/PageStateModel.ts

@@ -6,7 +6,6 @@
  */
 import {HoistModel, PageState} from '@xh/hoist/core';
 import {action, makeObservable, observable} from '@xh/hoist/mobx';
-import {logDebug} from '@xh/hoist/utils/js';
 
 /**
  * Implementation of PageState maintenance.
@@ -35,7 +34,7 @@ export class PageStateModel extends HoistModel {
     private setState(nextState: PageState) {
         if (this.state == 'terminated' || this.state == nextState) return;
 
-        logDebug(`PageState change: ${this.state} → ${nextState}`, this);
+        this.logDebug(`PageState change: ${this.state} → ${nextState}`);
         this.state = nextState;
     }
 

package/appcontainer/SizingModeModel.ts

@@ -40,7 +40,7 @@ export class SizingModeModel extends HoistModel {
                 platform = this.getPlatform();
 
             if (!isPlainObject(pref)) {
-                console.warn(
+                this.logWarn(
                     `Required pref 'xhSizingMode' must be type JSON - update via Admin Console.`
                 );
                 return;
@@ -48,7 +48,7 @@ export class SizingModeModel extends HoistModel {
 
             XH.setPref('xhSizingMode', {...pref, [platform]: sizingMode});
         } else {
-            console.warn(`Missing required JSON pref 'xhSizingMode' - add via Admin Console.`);
+            this.logWarn(`Missing required JSON pref 'xhSizingMode' - add via Admin Console.`);
         }
     }
 

package/cmp/ag-grid/AgGrid.ts

@@ -18,6 +18,7 @@ import {
     XH
 } from '@xh/hoist/core';
 import {AgGridReact, GridOptions} from '@xh/hoist/kit/ag-grid';
+import {logError} from '@xh/hoist/utils/js';
 import {splitLayoutProps} from '@xh/hoist/utils/react';
 import classNames from 'classnames';
 import {isNil} from 'lodash';
@@ -60,9 +61,9 @@ export const [AgGrid, agGrid] = hoistCmp.withFactory<AgGridProps>({
 
     render({model, className, testId, ...props}, ref) {
         if (!AgGridReact) {
-            console.error(
-                'ag-Grid has not been imported in to this application. Please import and ' +
-                    'register modules in Bootstrap.js. See the XH Toolbox app for an example.'
+            logError(
+                'AG Grid not imported/licensed by this app - import and register modules in Bootstrap.ts. See the XH Toolbox app for an example.',
+                AgGrid
             );
             return placeholder('ag-Grid library not available.');
         }

package/cmp/ag-grid/AgGridModel.ts

@@ -5,6 +5,7 @@
  * Copyright © 2023 Extremely Heavy Industries Inc.
  */
 import {HoistModel, PlainObject, SizingMode, Some} from '@xh/hoist/core';
+import type {ColumnApi, GridApi, IRowNode, SortDirection} from '@xh/hoist/kit/ag-grid';
 import {action, bindable, computed, makeObservable, observable} from '@xh/hoist/mobx';
 import {throwIf} from '@xh/hoist/utils/js';
 import {
@@ -23,8 +24,6 @@ import {
 } from 'lodash';
 import {GridSorter, GridSorterLike} from '../grid/GridSorter';
 
-import type {ColumnApi, GridApi, SortDirection} from '@xh/hoist/kit/ag-grid';
-
 export interface AgGridModelConfig {
     sizingMode?: SizingMode;
 
@@ -177,7 +176,7 @@ export class AgGridModel extends HoistModel {
                 try {
                     return this[`get${startCase(type)}State`]();
                 } catch (err) {
-                    console.warn(`Encountered errors retrieving ${type} state:`, err);
+                    this.logWarn(`Encountered errors retrieving ${type} state`, err);
                     errors[type] = err.toString();
                 }
             };
@@ -358,7 +357,7 @@ export class AgGridModel extends HoistModel {
                     col.setSort(state.sort);
                     col.setSortIndex(state.sortIndex);
                 } else {
-                    console.warn(
+                    this.logWarn(
                         'Could not find a secondary column to associate with the pivot column path',
                         state.colId
                     );
@@ -554,7 +553,7 @@ export class AgGridModel extends HoistModel {
      * @returns the first row in the grid, after sorting and filtering, which
      *  has data associated with it (i.e. not a group or other synthetic row).
      */
-    getFirstSelectableRowNode(): PlainObject {
+    getFirstSelectableRowNode(): IRowNode {
         this.throwIfNotReady();
 
         let ret = null;
@@ -595,7 +594,7 @@ export class AgGridModel extends HoistModel {
     /**
      * @returns row data pinned to the bottom of the grid
      */
-    getPinnedBottomRowData() {
+    getPinnedBottomRowData(): PlainObject[] {
         this.throwIfNotReady();
         return this.getPinnedRowData('Bottom');
     }
@@ -605,7 +604,7 @@ export class AgGridModel extends HoistModel {
     //------------------------
     @action
     handleGridReady({api, columnApi}) {
-        console.debug(`AgGridModel ${this.xhId} initializing`);
+        this.logDebug(`Initializing`, this.xhId);
         throwIf(
             this.agApi && this.agApi != api,
             'Attempted to mount a grid on a GridModel that is already in use. ' +
@@ -617,12 +616,12 @@ export class AgGridModel extends HoistModel {
 
     @action
     handleGridUnmount() {
-        console.debug(`AgGridModel ${this.xhId} un-initializing`);
+        this.logDebug(`Un-initializing`, this.xhId);
         this.agApi = null;
         this.agColumnApi = null;
     }
 
-    private getPinnedRowData(side) {
+    private getPinnedRowData(side: string): PlainObject[] {
         const {agApi} = this,
             count = agApi[`getPinned${side}RowCount`](),
             ret = [];

package/cmp/chart/Chart.ts

@@ -22,6 +22,7 @@ import {useContextMenu} from '@xh/hoist/dynamics/desktop';
 import {Icon} from '@xh/hoist/icon';
 import {Highcharts} from '@xh/hoist/kit/highcharts';
 import {runInAction} from '@xh/hoist/mobx';
+import {logError} from '@xh/hoist/utils/js';
 import {
     createObservableRef,
     getLayoutProps,
@@ -61,9 +62,9 @@ export const [Chart, chart] = hoistCmp.withFactory<ChartProps>({
 
     render({model, className, aspectRatio, testId, ...props}, ref) {
         if (!Highcharts) {
-            console.error(
-                'Highcharts has not been imported in to this application. Please import and ' +
-                    'register in Bootstrap.js. See the XH Toolbox app for an example.'
+            logError(
+                'Highcharts not imported by this app - import and register modules in Bootstrap.ts. See the XH Toolbox app for an example.',
+                Chart
             );
             return placeholder('Highcharts library not available.');
         }

package/cmp/dataview/DataViewModel.ts

@@ -4,7 +4,7 @@
  *
  * Copyright © 2023 Extremely Heavy Industries Inc.
  */
-import {RowClickedEvent, RowDoubleClickedEvent} from '@ag-grid-community/core';
+import {RowClickedEvent, RowDoubleClickedEvent, RowHeightParams} from '@ag-grid-community/core';
 import {
     ColumnRenderer,
     ColumnSpec,
@@ -127,7 +127,7 @@ export interface DataViewConfig {
 export type ItemHeightFn = (params: {
     record: StoreRecord;
     dataViewModel: DataViewModel;
-    agParams: PlainObject;
+    agParams: RowHeightParams;
 }) => number;
 
 /**

package/cmp/filter/FilterChooserModel.ts

@@ -199,7 +199,7 @@ export class FilterChooserModel extends HoistModel {
                     run: state => this.provider.write(state)
                 });
             } catch (e) {
-                console.error(e);
+                this.logError(e);
                 XH.safeDestroy(this.provider);
                 this.provider = null;
             }
@@ -251,7 +251,7 @@ export class FilterChooserModel extends HoistModel {
             }
 
             // 2) Main path - set internal value.
-            console.debug('Setting FilterChooser value:', value);
+            this.logDebug('Setting value', value);
             this.value = value;
 
             // 3) Set props on select input needed to display
@@ -292,7 +292,7 @@ export class FilterChooserModel extends HoistModel {
                 })
                 .linkTo(this.filterTask);
         } catch (e) {
-            console.error('Failed to set value on FilterChooserModel', e);
+            this.logError('Failed to set value', e);
             this.value = null;
             this.selectOptions = null;
             this.selectValue = null;
@@ -490,7 +490,7 @@ export class FilterChooserModel extends HoistModel {
         if (f === null) return true;
         if (f instanceof FieldFilter) {
             if (!this.getFieldSpec(f.field)) {
-                console.error(`Invalid Filter for FilterChooser: ${f.field}`);
+                this.logError(`Invalid FieldFilter - no fieldSpec configured for ${f.field}.`);
                 return false;
             }
             return true;
@@ -500,7 +500,7 @@ export class FilterChooserModel extends HoistModel {
             return f.filters.every(it => this.validateFilter(it));
         }
 
-        console.error('Invalid filter for FilterChooser', f);
+        this.logError('Invalid Filter - unhandled type', f);
         return false;
     }
 

package/cmp/grid/Grid.ts

@@ -41,7 +41,7 @@ import type {
 } from '@xh/hoist/kit/ag-grid';
 import {computed, observer} from '@xh/hoist/mobx';
 import {wait} from '@xh/hoist/promise';
-import {consumeEvent, isDisplayed, logDebug, logWithDebug} from '@xh/hoist/utils/js';
+import {consumeEvent, isDisplayed, logWithDebug} from '@xh/hoist/utils/js';
 import {createObservableRef, getLayoutProps} from '@xh/hoist/utils/react';
 import classNames from 'classnames';
 import {debounce, isEmpty, isEqual, isNil, max, maxBy, merge} from 'lodash';
@@ -634,7 +634,7 @@ export class GridLocalModel extends HoistModel {
         let transaction = null;
         if (prevCount !== 0) {
             transaction = this.genTransaction(newRs, prevRs);
-            logDebug(this.transactionLogStr(transaction), this);
+            this.logDebug(this.transactionLogStr(transaction));
 
             if (!this.transactionIsEmpty(transaction)) {
                 agApi.applyTransaction(transaction);

package/cmp/grid/GridContextMenu.ts

@@ -4,9 +4,9 @@
  *
  * Copyright © 2023 Extremely Heavy Industries Inc.
  */
-import {PlainObject} from '@xh/hoist/core';
 import {GridModel} from '@xh/hoist/cmp/grid';
 import {RecordActionLike} from '@xh/hoist/data';
+import {GetContextMenuItemsParams} from '@xh/hoist/kit/ag-grid';
 
 /**
  * If a String, value can be '-' for a separator, or a token supported by ag-Grid
@@ -46,4 +46,4 @@ export type GridContextMenuToken =
  */
 export type GridContextMenuSpec =
     | GridContextMenuItemLike[]
-    | ((agParams: PlainObject, gridModel: GridModel) => GridContextMenuItemLike[]);
+    | ((agParams: GetContextMenuItemsParams, gridModel: GridModel) => GridContextMenuItemLike[]);

package/cmp/grid/GridModel.ts

@@ -56,14 +56,7 @@ import {action, bindable, makeObservable, observable, when} from '@xh/hoist/mobx
 import {wait, waitFor} from '@xh/hoist/promise';
 import {ExportOptions} from '@xh/hoist/svc/GridExportService';
 import {SECONDS} from '@xh/hoist/utils/datetime';
-import {
-    deepFreeze,
-    logWithDebug,
-    throwIf,
-    warnIf,
-    withDebug,
-    withDefault
-} from '@xh/hoist/utils/js';
+import {deepFreeze, logWithDebug, throwIf, warnIf, withDefault} from '@xh/hoist/utils/js';
 import equal from 'fast-deep-equal';
 import {
     castArray,
@@ -818,7 +811,7 @@ export class GridModel extends HoistModel {
 
         const indexCount = indices.length;
         if (indexCount !== records.length) {
-            console.warn('Grid row nodes not found for all provided records.');
+            this.logWarn('Grid row nodes not found for all provided records.');
         }
 
         if (indexCount === 1) {
@@ -978,7 +971,7 @@ export class GridModel extends HoistModel {
 
         const invalidColIds = colIds.filter(it => !this.findColumn(this.columns, it));
         if (invalidColIds.length) {
-            console.warn(
+            this.logWarn(
                 'Unknown colId specified in groupBy - grid will not be grouped.',
                 invalidColIds
             );
@@ -1025,7 +1018,7 @@ export class GridModel extends HoistModel {
             it => !it.colId?.startsWith('ag-Grid') && !this.findColumn(this.columns, it.colId)
         );
         if (invalidSorters.length) {
-            console.warn('GridSorter colId not found in grid columns', invalidSorters);
+            this.logWarn('GridSorter colId not found in grid columns', invalidSorters);
             return;
         }
 
@@ -1360,10 +1353,9 @@ export class GridModel extends HoistModel {
 
         const rowIndex = agApi.getRowNode(recToEdit?.agId)?.rowIndex;
         if (isNil(rowIndex) || rowIndex < 0) {
-            console.warn(
-                'Unable to start editing - ' + record
-                    ? 'specified record not found'
-                    : 'no records found'
+            this.logWarn(
+                'Unable to start editing',
+                record ? 'specified record not found' : 'no records found'
             );
             return;
         }
@@ -1381,11 +1373,11 @@ export class GridModel extends HoistModel {
         }
 
         if (!colToEdit) {
-            console.warn(
-                'Unable to start editing - ' +
-                    (colId
-                        ? `column with colId ${colId} not found, or not editable`
-                        : 'no editable columns found')
+            this.logWarn(
+                'Unable to start editing',
+                colId
+                    ? `column with colId ${colId} not found, or not editable`
+                    : 'no editable columns found'
             );
             return;
         }
@@ -1438,7 +1430,7 @@ export class GridModel extends HoistModel {
         try {
             await when(() => this.isReady, {timeout});
         } catch (ignored) {
-            withDebug(`Grid failed to enter ready state after waiting ${timeout}ms`, null, this);
+            this.logDebug(`Grid failed to enter ready state after waiting ${timeout}ms`);
         }
         await wait();
 

package/cmp/grid/Types.ts

@@ -5,8 +5,9 @@
  * Copyright © 2023 Extremely Heavy Industries Inc.
  */
 
+import {IRowNode} from '@xh/hoist/kit/ag-grid';
 import {GridFilterFieldSpecConfig} from '@xh/hoist/cmp/grid/filter/GridFilterFieldSpec';
-import {HSide, PersistOptions, PlainObject, SizingMode, Some} from '@xh/hoist/core';
+import {HSide, PersistOptions, SizingMode, Some} from '@xh/hoist/core';
 import {Store, StoreRecord, View} from '@xh/hoist/data';
 import {ReactElement, ReactNode} from 'react';
 import {Column} from './columns/Column';
@@ -54,8 +55,8 @@ export type GridGroupSortFn = (
     groupField: string,
     metadata: {
         gridModel: GridModel;
-        nodeA: PlainObject;
-        nodeB: PlainObject;
+        nodeA: IRowNode;
+        nodeB: IRowNode;
     }
 ) => number;
 
@@ -167,8 +168,8 @@ export type ColumnComparator<T = any> = (
     params: {
         recordA: StoreRecord;
         recordB: StoreRecord;
-        agNodeA: PlainObject;
-        agNodeB: PlainObject;
+        agNodeA: IRowNode;
+        agNodeB: IRowNode;
         column: Column;
         gridModel: GridModel;
         defaultComparator: (a: T, b: T) => number;

package/cmp/grid/columns/Column.ts

@@ -14,7 +14,7 @@ import {
     RecordActionSpec,
     StoreRecord
 } from '@xh/hoist/data';
-import {apiRemoved, throwIf, warnIf, withDefault} from '@xh/hoist/utils/js';
+import {apiRemoved, logDebug, logWarn, throwIf, warnIf, withDefault} from '@xh/hoist/utils/js';
 import classNames from 'classnames';
 import {
     castArray,
@@ -932,12 +932,12 @@ export class Column {
                     sortCfg = find(gridModel.sortBy, {colId}),
                     sortDir = sortCfg?.sort || 'asc',
                     abs = sortCfg?.abs || false,
-                    recordA = agNodeA?.data,
-                    recordB = agNodeB?.data,
+                    recordA = agNodeA?.data as StoreRecord,
+                    recordB = agNodeB?.data as StoreRecord,
                     params = {
                         recordA,
                         recordB,
-                        column: this,
+                        column: this as Column,
                         gridModel,
                         defaultComparator: this.defaultComparator,
                         agNodeA,
@@ -962,7 +962,7 @@ export class Column {
         if (editor) {
             ret.cellEditor = forwardRef((agParams: PlainObject, ref) => {
                 const props = {
-                    record: agParams.data,
+                    record: agParams.data as StoreRecord,
                     gridModel,
                     column: this,
                     agParams,
@@ -1056,23 +1056,23 @@ export class Column {
 
     private parseFilterable(filterable) {
         if (!filterable) return false;
+        const {colId} = this;
 
         if (XH.isMobileApp) {
-            console.warn(`'filterable' is not supported on mobile and will be ignored.`);
+            logDebug(
+                `Column ${colId} specs 'filterable' but not supported on mobile - will be ignored.`,
+                this
+            );
             return false;
         }
 
         if (!this.field) {
-            console.warn(
-                `Column '${this.colId}' is not a Store field. 'filterable' will be ignored.`
-            );
+            logWarn(`Column ${colId} is not a Store field. 'filterable' will be ignored.`, this);
             return false;
         }
 
         if (this.field === 'cubeLabel') {
-            console.warn(
-                `Column '${this.colId}' is a cube label column. 'filterable' will be ignored.`
-            );
+            logWarn(`Column ${colId} is a cube label column. 'filterable' will be ignored.`, this);
             return false;
         }
 

package/cmp/grid/columns/ColumnGroup.ts

@@ -4,17 +4,17 @@
  *
  * Copyright © 2023 Extremely Heavy Industries Inc.
  */
-import {HAlign, PlainObject, Some, Thunkable} from '@xh/hoist/core';
+import {HAlign, PlainObject, Some, Thunkable, XH} from '@xh/hoist/core';
 import {genDisplayName} from '@xh/hoist/data';
+
+import type {ColGroupDef} from '@xh/hoist/kit/ag-grid';
 import {throwIf, withDefault} from '@xh/hoist/utils/js';
-import {clone, isEmpty, isFunction, isString} from 'lodash';
+import {clone, isEmpty, isFunction, isString, keysIn} from 'lodash';
 import {ReactNode} from 'react';
 import {GridModel} from '../GridModel';
 import {ColumnHeaderClassFn, ColumnHeaderNameFn} from '../Types';
 import {Column, ColumnSpec, getAgHeaderClassFn} from './Column';
 
-import type {ColGroupDef} from '@xh/hoist/kit/ag-grid';
-
 export interface ColumnGroupSpec {
     /** Column or ColumnGroup configs for children of this group.*/
     children: Array<ColumnGroupSpec | ColumnSpec>;
@@ -39,6 +39,8 @@ export interface ColumnGroupSpec {
 
     /** True to skip this column when adding to grid. */
     omit?: Thunkable<boolean>;
+
+    appData?: PlainObject;
 }
 
 /**
@@ -62,6 +64,8 @@ export class ColumnGroup {
      */
     agOptions?: PlainObject;
 
+    appData: PlainObject;
+
     /**
      * Not for application use. ColumnGroups are created internally by Hoist.
      *
@@ -83,6 +87,7 @@ export class ColumnGroup {
             headerAlign,
             agOptions,
             borders,
+            appData,
             ...rest
         } = config;
 
@@ -92,8 +97,6 @@ export class ColumnGroup {
             'Must specify groupId or a string headerName for a ColumnGroup'
         );
 
-        Object.assign(this, rest);
-
         this.groupId = withDefault(groupId, headerName) as string;
         this.headerName = withDefault(headerName, genDisplayName(this.groupId));
         this.headerClass = headerClass;
@@ -102,6 +105,14 @@ export class ColumnGroup {
         this.children = children;
         this.gridModel = gridModel;
         this.agOptions = agOptions ? clone(agOptions) : {};
+        this.appData = appData ? clone(appData) : {};
+
+        if (!isEmpty(rest)) {
+            const keys = keysIn(rest);
+            throw XH.exception(
+                `Column group '${this.groupId}' configured with unsupported key(s) '${keys}'. Custom config data must be nested within the 'appData' property.`
+            );
+        }
     }
 
     getAgSpec(): ColGroupDef {