@xh/hoist 74.0.0-SNAPSHOT.1748626008777 → 74.0.0-SNAPSHOT.1748890930922

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## 74.0.0-SNAPSHOT - unreleased
 
+### 💥 Breaking Changes (upgrade difficulty: 🟢 LOW - minor change to ViewManagerModel)
+
+* Removed `ViewManagerModel.settleTime`. Now set via individual `PersistOptions.settleTime` instead.
+
+### 🎁 New Features
+* Added `ViewManagerModel.preserveUnsavedChanges` flag to opt-out of that behaviour.
+* Added `PersistOptions.settleTime` to configure time to wait for state to settle before persisting.
+* Support for gridcolumn level `onCellClicked` events.
+
+### 🐞 Bug Fixes
+* Improved `ViewManagerModel.settleTime` by delegating to individual `PersistenceProviders`.
+* Fixed bug where grid column state could become unintentionally dirty when columns were hidden.
+
 ## v73.0.1 - 2025-05-19
 
 ### 🐞 Bug Fixes

package/build/types/cmp/grid/GridModel.d.ts

@@ -120,7 +120,9 @@ export interface GridConfig {
      */
     onRowDoubleClicked?: (e: RowDoubleClickedEvent) => void;
     /**
-     * Callback when a cell is clicked.
+     * Callback when any cell on the grid is clicked - inspect the event to determine the column.
+     * Note that {@link ColumnSpec.onCellClicked} is a more targeted handler scoped to a single
+     * column, which might be more convenient when clicks on only one column are of interest.
      */
     onCellClicked?: (e: CellClickedEvent) => void;
     /**

package/build/types/cmp/grid/columns/Column.d.ts

@@ -4,6 +4,7 @@ import { FunctionComponent, ReactNode } from 'react';
 import { GridModel } from '../GridModel';
 import { ColumnCellClassFn, ColumnCellClassRuleFn, ColumnComparator, ColumnEditableFn, ColumnEditorFn, ColumnEditorProps, ColumnExcelFormatFn, ColumnExportValueFn, ColumnGetValueFn, ColumnHeaderClassFn, ColumnHeaderNameFn, ColumnRenderer, ColumnSetValueFn, ColumnSortSpec, ColumnSortValueFn, ColumnTooltipFn } from '../Types';
 import type { ColDef } from '@xh/hoist/kit/ag-grid';
+import { CellClickedEvent } from '@ag-grid-community/core';
 export interface ColumnSpec {
     /**
      * Name of data store field to display within the column, or object containing properties
@@ -248,6 +249,11 @@ export interface ColumnSpec {
      * many rows + multiple actions per row. Defaults to false;
      */
     actionsShowOnHoverOnly?: boolean;
+    /**
+     * Callback when a cell within this column clicked.
+     * See also {@link GridConfig.onCellClicked}, called when any cell within the grid is clicked.
+     */
+    onCellClicked?: (e: CellClickedEvent) => void;
     /**
      * "escape hatch" object to pass directly to Ag-Grid for desktop implementations. Note these
      * options may be used / overwritten by the framework itself, and are not all guaranteed to be
@@ -337,6 +343,7 @@ export declare class Column {
     actionsShowOnHoverOnly?: boolean;
     fieldSpec: FieldSpec;
     omit: Thunkable<boolean>;
+    onCellClicked?: (e: CellClickedEvent) => void;
     gridModel: GridModel;
     agOptions: ColDef;
     appData: PlainObject;

package/build/types/cmp/viewmanager/ViewManagerModel.d.ts

@@ -43,6 +43,11 @@ export interface ViewManagerConfig {
      * True (default) to allow users to share their views with other users.
      */
     enableSharing?: boolean;
+    /**
+     * True (default) to save pending state to SessionStorage so that it can be restored across
+     * browser refreshes. Unlike auto-save, this does not write to the database.
+     */
+    preserveUnsavedChanges?: boolean;
     /**
      * Function to determine the initial view for a user, when no view has already been persisted.
      * Will be passed a list of views available to the current user.  Implementations where
@@ -52,13 +57,6 @@ export interface ViewManagerConfig {
      * Must be set when enableDefault is false.
      */
     initialViewSpec?: (views: ViewInfo[]) => ViewInfo;
-    /**
-     * Delay (in ms) to wait after state has been set on associated components before listening for
-     * further state changes. The long default wait 1000ms is intended to avoid a false positive
-     * dirty indicator when linking to complex components such as dashboards or grids that can
-     * report immediate changes to state due to internal processing or rendering.
-     */
-    settleTime?: number;
     /**
      * True to allow the user to publish or edit the global views. Apps are expected to
      * commonly set this based on user roles - e.g. `XH.getUser().hasRole('MANAGE_GRID_VIEWS')`.
@@ -132,8 +130,8 @@ export declare class ViewManagerModel<T = PlainObject> extends HoistModel {
     readonly enableDefault: boolean;
     readonly enableGlobal: boolean;
     readonly enableSharing: boolean;
+    readonly preserveUnsavedChanges: boolean;
     readonly manageGlobal: boolean;
-    readonly settleTime: number;
     readonly initialViewSpec: (views: ViewInfo[]) => ViewInfo;
     /** Current view. Will not include uncommitted changes */
     view: View<T>;
@@ -161,16 +159,12 @@ export declare class ViewManagerModel<T = PlainObject> extends HoistModel {
     /** Unsaved changes on the current view.*/
     private pendingValue;
     /**
-     * Array of {@link ViewManagerProvider} instances bound to this model. Providers will
-     * push themselves onto this array when constructed with a reference to this model. Used to
-     * proactively push state to the target components when the model's selected `value` changes.
-     * @internal
+     * Array of {@link ViewManagerProvider} instances bound to this model. Used to proactively push
+     * state to the target components when the model's selected `value` changes.
      */
-    providers: ViewManagerProvider<any>[];
+    private providers;
     /** Data access for persisting views. */
     private dataAccess;
-    /** Last time changes were pushed to linked persistence providers */
-    private lastPushed;
     get isValueDirty(): boolean;
     get isViewSavable(): boolean;
     get isViewAutoSavable(): boolean;
@@ -207,8 +201,18 @@ export declare class ViewManagerModel<T = PlainObject> extends HoistModel {
     /** Promote a view to global visibility/ownership status. */
     makeViewGlobalAsync(view: ViewInfo): Promise<View<T>>;
     deleteViewsAsync(toDelete: ViewInfo[]): Promise<void>;
+    /**
+     * Called by {@link ViewManagerProvider} to receive state changes from this model.
+     * @internal
+     */
+    registerProvider(provider: ViewManagerProvider<any>): void;
+    /**
+     * Called by {@link ViewManagerProvider} to stop receiving state changes.
+     * @internal
+     */
+    unregisterProvider(provider: ViewManagerProvider<any>): void;
     private initAsync;
-    private pendingValueReaction;
+    private unsavedChangesReaction;
     private autoSaveReaction;
     private stateReactions;
     private loadViewAsync;

package/build/types/core/persist/PersistOptions.d.ts

@@ -11,6 +11,10 @@ export interface PersistOptions {
     path?: string;
     /** Debounce interval in ms, or a lodash debounce config. */
     debounce?: DebounceSpec;
+    /**
+     * Delay (in ms) to wait after state has been read before listening for further state changes.
+     */
+    settleTime?: number;
     /**
      * Type of PersistenceProvider to create. Specify as one of the built-in string types,
      * or a subclass of PersistenceProvider.

package/build/types/core/persist/PersistenceProvider.d.ts

@@ -26,9 +26,12 @@ export declare abstract class PersistenceProvider<S = any> {
     readonly path: string;
     readonly debounce: DebounceSpec;
     readonly owner: HoistBase;
+    readonly settleTime: number;
     protected target: Persistable<S>;
     protected defaultState: PersistableState<S>;
     private disposer;
+    private lastReadState;
+    private lastReadTime;
     /**
      * Construct an instance of this class.
      *

package/cmp/grid/GridModel.ts

@@ -255,7 +255,9 @@ export interface GridConfig {
     onRowDoubleClicked?: (e: RowDoubleClickedEvent) => void;
 
     /**
-     * Callback when a cell is clicked.
+     * Callback when any cell on the grid is clicked - inspect the event to determine the column.
+     * Note that {@link ColumnSpec.onCellClicked} is a more targeted handler scoped to a single
+     * column, which might be more convenient when clicks on only one column are of interest.
      */
     onCellClicked?: (e: CellClickedEvent) => void;
 

package/cmp/grid/columns/Column.ts

@@ -71,6 +71,7 @@ import type {
     ValueGetterParams,
     ValueSetterParams
 } from '@xh/hoist/kit/ag-grid';
+import {CellClickedEvent} from '@ag-grid-community/core';
 
 export interface ColumnSpec {
     /**
@@ -374,6 +375,12 @@ export interface ColumnSpec {
      */
     actionsShowOnHoverOnly?: boolean;
 
+    /**
+     * Callback when a cell within this column clicked.
+     * See also {@link GridConfig.onCellClicked}, called when any cell within the grid is clicked.
+     */
+    onCellClicked?: (e: CellClickedEvent) => void;
+
     /**
      * "escape hatch" object to pass directly to Ag-Grid for desktop implementations. Note these
      * options may be used / overwritten by the framework itself, and are not all guaranteed to be
@@ -479,6 +486,7 @@ export class Column {
     actionsShowOnHoverOnly?: boolean;
     fieldSpec: FieldSpec;
     omit: Thunkable<boolean>;
+    onCellClicked?: (e: CellClickedEvent) => void;
 
     gridModel: GridModel;
     agOptions: ColDef;
@@ -551,6 +559,7 @@ export class Column {
             actionsShowOnHoverOnly,
             actions,
             omit,
+            onCellClicked,
             agOptions,
             appData,
             ...rest
@@ -657,6 +666,7 @@ export class Column {
 
         this.actions = actions;
         this.actionsShowOnHoverOnly = actionsShowOnHoverOnly ?? false;
+        this.onCellClicked = onCellClicked;
 
         this.gridModel = gridModel;
         this.agOptions = agOptions ? clone(agOptions) : {};
@@ -758,7 +768,8 @@ export class Column {
                     if (event.shiftKey && event.key === 'Enter') return true;
 
                     return false;
-                }
+                },
+                onCellClicked: this.onCellClicked
             };
 
         // We will change this setter as needed to install the renderer in the proper location

package/cmp/grid/impl/InitPersist.ts

@@ -5,9 +5,9 @@
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
 import {PersistableState, PersistenceProvider} from '@xh/hoist/core';
-import {isObject} from 'lodash';
+import {isEqual, isObject} from 'lodash';
 import {GridModel} from '../GridModel';
-import {GridModelPersistOptions} from '../Types';
+import {ColumnState, GridModelPersistOptions} from '../Types';
 
 /**
  * Initialize persistence for a {@link GridModel} by applying its `persistWith` config.
@@ -33,7 +33,8 @@ export function initPersist(
                 ...persistWith
             },
             target: {
-                getPersistableState: () => new PersistableState(gridModel.persistableColumnState),
+                getPersistableState: () =>
+                    new PersistableColumnState(gridModel.persistableColumnState),
                 setPersistableState: ({value}) => gridModel.setColumnState(value)
             },
             owner: gridModel
@@ -75,3 +76,12 @@ export function initPersist(
         });
     }
 }
+
+class PersistableColumnState extends PersistableState<ColumnState[]> {
+    override equals(other: PersistableState<ColumnState[]>): boolean {
+        return isEqual(
+            this.value.filter(it => !it.hidden),
+            other.value.filter(it => !it.hidden)
+        );
+    }
+}

package/cmp/viewmanager/ViewManagerModel.ts

@@ -19,7 +19,7 @@ import type {ViewManagerProvider, ReactionSpec} from '@xh/hoist/core';
 import {genDisplayName} from '@xh/hoist/data';
 import {fmtDateTime} from '@xh/hoist/format';
 import {action, bindable, makeObservable, observable, comparer, runInAction} from '@xh/hoist/mobx';
-import {olderThan, SECONDS} from '@xh/hoist/utils/datetime';
+import {SECONDS} from '@xh/hoist/utils/datetime';
 import {executeIfFunction, pluralize, throwIf} from '@xh/hoist/utils/js';
 import {find, isEqual, isNil, isNull, isObject, isUndefined, lowerCase, uniqBy} from 'lodash';
 import {ReactNode} from 'react';
@@ -74,6 +74,12 @@ export interface ViewManagerConfig {
      */
     enableSharing?: boolean;
 
+    /**
+     * True (default) to save pending state to SessionStorage so that it can be restored across
+     * browser refreshes. Unlike auto-save, this does not write to the database.
+     */
+    preserveUnsavedChanges?: boolean;
+
     /**
      * Function to determine the initial view for a user, when no view has already been persisted.
      * Will be passed a list of views available to the current user.  Implementations where
@@ -84,14 +90,6 @@ export interface ViewManagerConfig {
      */
     initialViewSpec?: (views: ViewInfo[]) => ViewInfo;
 
-    /**
-     * Delay (in ms) to wait after state has been set on associated components before listening for
-     * further state changes. The long default wait 1000ms is intended to avoid a false positive
-     * dirty indicator when linking to complex components such as dashboards or grids that can
-     * report immediate changes to state due to internal processing or rendering.
-     */
-    settleTime?: number;
-
     /**
      * True to allow the user to publish or edit the global views. Apps are expected to
      * commonly set this based on user roles - e.g. `XH.getUser().hasRole('MANAGE_GRID_VIEWS')`.
@@ -176,8 +174,8 @@ export class ViewManagerModel<T = PlainObject> extends HoistModel {
     readonly enableDefault: boolean;
     readonly enableGlobal: boolean;
     readonly enableSharing: boolean;
+    readonly preserveUnsavedChanges: boolean;
     readonly manageGlobal: boolean;
-    readonly settleTime: number;
     readonly initialViewSpec: (views: ViewInfo[]) => ViewInfo;
 
     /** Current view. Will not include uncommitted changes */
@@ -216,19 +214,14 @@ export class ViewManagerModel<T = PlainObject> extends HoistModel {
     private pendingValue: PendingValue<T> = null;
 
     /**
-     * Array of {@link ViewManagerProvider} instances bound to this model. Providers will
-     * push themselves onto this array when constructed with a reference to this model. Used to
-     * proactively push state to the target components when the model's selected `value` changes.
-     * @internal
+     * Array of {@link ViewManagerProvider} instances bound to this model. Used to proactively push
+     * state to the target components when the model's selected `value` changes.
      */
-    providers: ViewManagerProvider<any>[] = [];
+    private providers: ViewManagerProvider<any>[] = [];
 
     /** Data access for persisting views. */
     private dataAccess: DataAccess<T>;
 
-    /** Last time changes were pushed to linked persistence providers */
-    private lastPushed: number = null;
-
     //---------------
     // Getters
     //---------------
@@ -296,7 +289,7 @@ export class ViewManagerModel<T = PlainObject> extends HoistModel {
         enableDefault = true,
         enableGlobal = true,
         enableSharing = true,
-        settleTime = 1000,
+        preserveUnsavedChanges = true,
         initialViewSpec = null
     }: ViewManagerConfig) {
         super();
@@ -317,7 +310,7 @@ export class ViewManagerModel<T = PlainObject> extends HoistModel {
         this.enableGlobal = enableGlobal;
         this.enableSharing = enableSharing;
         this.enableAutoSave = enableAutoSave;
-        this.settleTime = settleTime;
+        this.preserveUnsavedChanges = preserveUnsavedChanges;
         this.initialViewSpec = initialViewSpec;
 
         this.selectTask = TaskObserver.trackLast({
@@ -421,10 +414,7 @@ export class ViewManagerModel<T = PlainObject> extends HoistModel {
 
     @action
     setValue(value: Partial<T>) {
-        const {view, pendingValue, lastPushed, settleTime} = this;
-        if (!pendingValue && settleTime && !olderThan(lastPushed, settleTime)) {
-            return;
-        }
+        const {view, pendingValue} = this;
 
         value = this.cleanState(value);
         if (!isEqual(value, view.value)) {
@@ -500,6 +490,25 @@ export class ViewManagerModel<T = PlainObject> extends HoistModel {
         if (exception) throw exception;
     }
 
+    //------------------
+    // Internal
+    //------------------
+    /**
+     * Called by {@link ViewManagerProvider} to receive state changes from this model.
+     * @internal
+     */
+    registerProvider(provider: ViewManagerProvider<any>) {
+        this.providers.push(provider);
+    }
+
+    /**
+     * Called by {@link ViewManagerProvider} to stop receiving state changes.
+     * @internal
+     */
+    unregisterProvider(provider: ViewManagerProvider<any>) {
+        this.providers = this.providers.filter(it => it !== provider);
+    }
+
     //------------------
     // Implementation
     //------------------
@@ -515,7 +524,9 @@ export class ViewManagerModel<T = PlainObject> extends HoistModel {
                 this.views = views;
                 this.userPinned = state.userPinned;
                 this.autoSave = state.autoSave;
-                this.pendingValue = XH.sessionStorageService.get(pendingValueStorageKey);
+                if (this.preserveUnsavedChanges) {
+                    this.pendingValue = XH.sessionStorageService.get(pendingValueStorageKey);
+                }
             });
 
             // 2) Initialize/choose initial view.  Null is ok, and will yield default.
@@ -537,13 +548,13 @@ export class ViewManagerModel<T = PlainObject> extends HoistModel {
         }
 
         this.addReaction(
-            this.pendingValueReaction(),
+            this.preserveUnsavedChanges ? this.unsavedChangesReaction() : null,
             this.autoSaveReaction(),
             ...this.stateReactions(initialState)
         );
     }
 
-    private pendingValueReaction(): ReactionSpec {
+    private unsavedChangesReaction(): ReactionSpec {
         return {
             track: () => this.pendingValue,
             run: v => XH.sessionStorageService.set(this.pendingValueStorageKey, v)
@@ -588,7 +599,6 @@ export class ViewManagerModel<T = PlainObject> extends HoistModel {
             .thenAction(latest => {
                 this.setAsView(latest, pendingValue?.token == token ? pendingValue : null);
                 this.providers.forEach(it => it.pushStateToTarget());
-                this.lastPushed = Date.now();
             })
             .linkTo(this.selectTask);
     }
@@ -622,6 +632,9 @@ export class ViewManagerModel<T = PlainObject> extends HoistModel {
         if (!view.isDefault) {
             this.views = uniqBy([view.info, ...this.views], 'token');
         }
+
+        // Ensure providers have a clean reference of the current view state.
+        this.providers.forEach(it => it.read());
     }
 
     private handleException(e, opts: ExceptionHandlerOptions = {}) {

package/core/persist/PersistOptions.ts

@@ -28,6 +28,11 @@ export interface PersistOptions {
     /** Debounce interval in ms, or a lodash debounce config. */
     debounce?: DebounceSpec;
 
+    /**
+     * Delay (in ms) to wait after state has been read before listening for further state changes.
+     */
+    settleTime?: number;
+
     /**
      * Type of PersistenceProvider to create. Specify as one of the built-in string types,
      * or a subclass of PersistenceProvider.

package/core/persist/PersistenceProvider.ts

@@ -5,6 +5,7 @@
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
 
+import {olderThan} from '@xh/hoist/utils/datetime';
 import {logDebug, logError, throwIf} from '@xh/hoist/utils/js';
 import {
     cloneDeep,
@@ -59,11 +60,14 @@ export abstract class PersistenceProvider<S = any> {
     readonly path: string;
     readonly debounce: DebounceSpec;
     readonly owner: HoistBase;
+    readonly settleTime: number;
 
     protected target: Persistable<S>;
     protected defaultState: PersistableState<S>;
 
     private disposer: IReactionDisposer;
+    private lastReadState: PersistableState<S>;
+    private lastReadTime: number;
 
     /**
      * Construct an instance of this class.
@@ -126,7 +130,10 @@ export abstract class PersistenceProvider<S = any> {
     read(): PersistableState<S> {
         const state = get(this.readRaw(), this.path);
         logDebug(['Reading state', state], this.owner);
-        return !isUndefined(state) ? new PersistableState(state) : null;
+        const ret = !isUndefined(state) ? new PersistableState(state) : null;
+        this.lastReadState = ret;
+        this.lastReadTime = Date.now();
+        return ret;
     }
 
     /** Persist JSON-serializable state to this provider's path. */
@@ -161,11 +168,12 @@ export abstract class PersistenceProvider<S = any> {
         const {owner, persistOptions} = cfg;
         this.owner = owner;
 
-        const {path, debounce = 250} = persistOptions;
+        const {path, debounce = 250, settleTime} = persistOptions;
         throwIf(!path, 'Path not specified in PersistenceProvider.');
 
         this.path = path;
         this.debounce = debounce;
+        this.settleTime = settleTime;
         this.owner.markManaged(this);
 
         if (debounce) {
@@ -187,8 +195,14 @@ export abstract class PersistenceProvider<S = any> {
         this.disposer = reaction(
             () => this.target.getPersistableState(),
             state => {
-                if (state.equals(this.defaultState)) {
+                if (this.settleTime && !olderThan(this.lastReadTime, this.settleTime)) {
+                    return;
+                } else if (state.equals(this.defaultState)) {
                     this.clear();
+                } else if (this.lastReadState && state.equals(this.lastReadState)) {
+                    // If the last read state is equal to the current state, use the last read state
+                    // to avoid appearing "dirty"
+                    this.write(this.lastReadState.value);
                 } else {
                     this.write(state.value);
                 }

package/core/persist/provider/ViewManagerProvider.ts

@@ -6,7 +6,6 @@
  */
 
 import {throwIf} from '@xh/hoist/utils/js';
-import {pull} from 'lodash';
 import {PersistenceProvider, PersistenceProviderConfig} from '../PersistenceProvider';
 import type {ViewManagerModel} from '@xh/hoist/cmp/viewmanager/ViewManagerModel';
 
@@ -18,7 +17,7 @@ export class ViewManagerProvider<S> extends PersistenceProvider<S> {
         const {viewManagerModel} = cfg.persistOptions;
         throwIf(!viewManagerModel, `ViewManagerProvider requires a 'viewManagerModel'.`);
         this.viewManagerModel = viewManagerModel;
-        viewManagerModel.providers.push(this);
+        viewManagerModel.registerProvider(this);
     }
 
     pushStateToTarget() {
@@ -38,10 +37,7 @@ export class ViewManagerProvider<S> extends PersistenceProvider<S> {
     }
 
     override destroy() {
-        if (this.viewManagerModel) {
-            pull(this.viewManagerModel.providers, this);
-        }
-
+        this.viewManagerModel?.unregisterProvider(this);
         super.destroy();
     }
 }

package/desktop/cmp/dash/canvas/DashCanvasModel.ts

@@ -195,6 +195,7 @@ export class DashCanvasModel
             PersistenceProvider.create({
                 persistOptions: {
                     path: 'dashCanvas',
+                    settleTime: 1000,
                     ...persistWith
                 },
                 target: this

package/desktop/cmp/dash/container/DashContainerModel.ts

@@ -215,6 +215,7 @@ export class DashContainerModel
             PersistenceProvider.create({
                 persistOptions: {
                     path: 'dashContainer',
+                    settleTime: 1000,
                     ...persistWith
                 },
                 target: this

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xh/hoist",
-  "version": "74.0.0-SNAPSHOT.1748626008777",
+  "version": "74.0.0-SNAPSHOT.1748890930922",
   "description": "Hoist add-on for building and deploying React Applications.",
   "repository": "github:xh/hoist-react",
   "homepage": "https://xh.io",