@xh/hoist 70.0.0-SNAPSHOT.1731022145122 → 70.0.0-SNAPSHOT.1731374612473

package/cmp/grid/impl/InitPersist.ts

@@ -0,0 +1,71 @@
+/*
+ * This file belongs to Hoist, an application development toolkit
+ * developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
+ *
+ * Copyright © 2024 Extremely Heavy Industries Inc.
+ */
+import {PersistableState, PersistenceProvider} from '@xh/hoist/core';
+import {isObject} from 'lodash';
+import {GridModel} from '../GridModel';
+import {GridModelPersistOptions} from '../Types';
+
+/**
+ * Initialize persistence for a {@link GridModel} by applying its `persistWith` config.
+ * @internal
+ */
+export function initPersist(
+    gridModel: GridModel,
+    {
+        persistColumns = true,
+        persistGrouping = true,
+        persistSort = true,
+        path = 'grid',
+        ...rootPersistWith
+    }: GridModelPersistOptions
+) {
+    if (persistColumns) {
+        const persistWith = isObject(persistColumns) ? persistColumns : rootPersistWith;
+        PersistenceProvider.create({
+            persistOptions: {
+                path: `${path}.columns`,
+                ...persistWith
+            },
+            target: {
+                getPersistableState: () => new PersistableState(gridModel.persistableColumnState),
+                setPersistableState: ({value}) => gridModel.setColumnState(value)
+            },
+            owner: gridModel
+        });
+    }
+
+    if (persistSort) {
+        const persistWith = isObject(persistSort) ? persistSort : rootPersistWith;
+        PersistenceProvider.create({
+            persistOptions: {
+                path: `${path}.sortBy`,
+                ...persistWith
+            },
+            target: {
+                getPersistableState: () =>
+                    new PersistableState(gridModel.sortBy.map(it => it.toString())),
+                setPersistableState: ({value}) => gridModel.setSortBy(value)
+            },
+            owner: gridModel
+        });
+    }
+
+    if (persistGrouping) {
+        const persistWith = isObject(persistSort) ? persistSort : rootPersistWith;
+        PersistenceProvider.create({
+            persistOptions: {
+                path: `${path}.groupBy`,
+                ...persistWith
+            },
+            target: {
+                getPersistableState: () => new PersistableState(gridModel.groupBy),
+                setPersistableState: ({value}) => gridModel.setGroupBy(value)
+            },
+            owner: gridModel
+        });
+    }
+}

package/cmp/grouping/GroupingChooserModel.ts

@@ -5,19 +5,12 @@
  * Copyright © 2024 Extremely Heavy Industries Inc.
  */
 
-import {
-    HoistModel,
-    managed,
-    PersistenceProvider,
-    PersistOptions,
-    PlainObject,
-    XH
-} from '@xh/hoist/core';
+import {HoistModel, PersistableState, PersistenceProvider, PersistOptions} from '@xh/hoist/core';
 import {genDisplayName} from '@xh/hoist/data';
 import {action, computed, makeObservable, observable} from '@xh/hoist/mobx';
 import {executeIfFunction, throwIf} from '@xh/hoist/utils/js';
 import {createObservableRef} from '@xh/hoist/utils/react';
-import {cloneDeep, difference, isArray, isEmpty, isEqual, isString, keys, sortBy} from 'lodash';
+import {difference, isArray, isEmpty, isEqual, isObject, isString, keys, sortBy} from 'lodash';
 
 export interface GroupingChooserConfig {
     /**
@@ -62,11 +55,11 @@ export interface DimensionSpec {
 }
 
 export interface GroupingChooserPersistOptions extends PersistOptions {
-    /** True (default) to save value to state. */
-    persistValue?: boolean;
+    /** True (default) to include value or provide value-specific PersistOptions. */
+    persistValue?: boolean | PersistOptions;
 
-    /** True (default) to include favorites. */
-    persistFavorites?: boolean;
+    /** True (default) to include favorites or provide favorites-specific PersistOptions. */
+    persistFavorites?: boolean | PersistOptions;
 }
 
 export class GroupingChooserModel extends HoistModel {
@@ -76,9 +69,6 @@ export class GroupingChooserModel extends HoistModel {
     allowEmpty: boolean;
     maxDepth: number;
     commitOnChange: boolean;
-
-    @managed provider: PersistenceProvider = null;
-    persistValue: boolean = false;
     persistFavorites: boolean = false;
 
     // Implementation fields for Control
@@ -140,34 +130,10 @@ export class GroupingChooserModel extends HoistModel {
         throwIf(isEmpty(value) && !this.allowEmpty, 'Initial value cannot be empty.');
         throwIf(!this.validateValue(value), 'Initial value is invalid.');
 
-        // Read state from provider -- fail gently
-        if (persistWith) {
-            try {
-                this.provider = PersistenceProvider.create({
-                    path: 'groupingChooser',
-                    ...persistWith
-                });
-                this.persistValue = persistWith.persistValue ?? true;
-                this.persistFavorites = persistWith.persistFavorites ?? true;
-
-                const state = cloneDeep(this.provider.read());
-                if (this.persistValue && state?.value && this.validateValue(state?.value)) {
-                    value = state.value;
-                }
-                if (this.persistFavorites && state?.favorites) {
-                    favorites = state.favorites;
-                }
-
-                this.addReaction({
-                    track: () => this.persistState,
-                    run: state => this.provider.write(state)
-                });
-            } catch (e) {
-                this.logError(e);
-                XH.safeDestroy(this.provider);
-                this.provider = null;
-            }
-        }
+        this.setValue(value);
+        this.setFavorites(favorites);
+
+        if (persistWith) this.initPersist(persistWith);
 
         this.addReaction({
             track: () => this.pendingValue,
@@ -175,9 +141,6 @@ export class GroupingChooserModel extends HoistModel {
                 if (this.commitOnChange) this.setValue(this.pendingValue);
             }
         });
-
-        this.setValue(value);
-        this.setFavorites(favorites);
     }
 
     @action
@@ -320,19 +283,47 @@ export class GroupingChooserModel extends HoistModel {
         return this.favorites?.some(v => isEqual(v, value));
     }
 
-    //-------------------------
-    // Persistence handling
-    //-------------------------
-    get persistState() {
-        const ret: PlainObject = {};
-        if (this.persistValue) ret.value = this.value;
-        if (this.persistFavorites) ret.favorites = this.favorites;
-        return ret;
-    }
-
     //------------------------
     // Implementation
     //------------------------
+    private initPersist({
+        persistValue = true,
+        persistFavorites = true,
+        path = 'groupingChooser',
+        ...rootPersistWith
+    }: GroupingChooserPersistOptions) {
+        if (persistValue) {
+            const persistWith = isObject(persistValue) ? persistValue : rootPersistWith;
+            PersistenceProvider.create({
+                persistOptions: {
+                    path: `${path}.value`,
+                    ...persistWith
+                },
+                target: {
+                    getPersistableState: () => new PersistableState(this.value),
+                    setPersistableState: ({value}) => this.setValue(value)
+                },
+                owner: this
+            });
+        }
+
+        if (persistFavorites) {
+            const persistWith = isObject(persistFavorites) ? persistFavorites : rootPersistWith,
+                provider = PersistenceProvider.create({
+                    persistOptions: {
+                        path: `${path}.favorites`,
+                        ...persistWith
+                    },
+                    target: {
+                        getPersistableState: () => new PersistableState(this.favorites),
+                        setPersistableState: ({value}) => this.setFavorites(value)
+                    },
+                    owner: this
+                });
+            if (provider) this.persistFavorites = true;
+        }
+    }
+
     private normalizeDimensions(
         dims: Array<DimensionSpec | string>
     ): Record<string, DimensionSpec> {

package/cmp/tab/TabContainerModel.ts

@@ -7,6 +7,8 @@
 import {
     HoistModel,
     managed,
+    Persistable,
+    PersistableState,
     PersistenceProvider,
     PersistOptions,
     RefreshContextModel,
@@ -18,7 +20,7 @@ import {action, makeObservable, observable} from '@xh/hoist/mobx';
 import {wait} from '@xh/hoist/promise';
 import {isOmitted} from '@xh/hoist/utils/impl';
 import {ensureUniqueBy, throwIf} from '@xh/hoist/utils/js';
-import {difference, find, findLast, isString, isUndefined, without} from 'lodash';
+import {difference, find, findLast, isString, without} from 'lodash';
 import {ReactNode} from 'react';
 import {TabConfig, TabModel} from './TabModel';
 import {TabSwitcherProps} from './TabSwitcherProps';
@@ -85,7 +87,7 @@ export interface TabContainerConfig {
  *
  * Note: Routing is currently enabled for desktop applications only.
  */
-export class TabContainerModel extends HoistModel {
+export class TabContainerModel extends HoistModel implements Persistable<{activeTabId: string}> {
     declare config: TabContainerConfig;
 
     @managed
@@ -102,7 +104,6 @@ export class TabContainerModel extends HoistModel {
     renderMode: RenderMode;
     refreshMode: RefreshMode;
     emptyText: ReactNode;
-    provider: PersistenceProvider;
 
     @managed
     refreshContextModel: RefreshContextModel;
@@ -156,7 +157,13 @@ export class TabContainerModel extends HoistModel {
 
             this.forwardRouterToTab(this.activeTabId);
         } else if (persistWith) {
-            this.setupStateProvider(persistWith);
+            PersistenceProvider.create({
+                persistOptions: {
+                    path: 'tabContainer',
+                    ...persistWith
+                },
+                target: this
+            });
         }
 
         if (track) {
@@ -320,6 +327,17 @@ export class TabContainerModel extends HoistModel {
         if (target) this.activateTab(target);
     }
 
+    //-------------------------
+    // Persistable Interface
+    //-------------------------
+    getPersistableState(): PersistableState<{activeTabId: string}> {
+        return new PersistableState({activeTabId: this.activeTabId});
+    }
+
+    setPersistableState(state: PersistableState<{activeTabId: string}>): void {
+        this.activateTab(state.value.activeTabId);
+    }
+
     //-------------------------
     // Implementation
     //-------------------------
@@ -374,38 +392,6 @@ export class TabContainerModel extends HoistModel {
 
         return null;
     }
-
-    private setupStateProvider(persistWith) {
-        // Read state from provider -- fail gently
-        let state = null;
-
-        try {
-            this.provider = PersistenceProvider.create({path: 'tabContainer', ...persistWith});
-            state = this.provider.read() || null;
-        } catch (e) {
-            this.logError(e);
-            XH.safeDestroy(this.provider);
-            this.provider = null;
-        }
-
-        // Initialize state, or clear if state's activeTabId no longer exists
-        if (!isUndefined(state?.activeTabId)) {
-            const id = state.activeTabId;
-            if (this.findTab(id)) {
-                this.activateTab(id);
-            } else {
-                this.provider.clear();
-            }
-        }
-
-        // Attach to provider last
-        if (this.provider) {
-            this.addReaction({
-                track: () => this.activeTabId,
-                run: activeTabId => this.provider.write({activeTabId})
-            });
-        }
-    }
 }
 
 export interface AddTabOptions {

package/cmp/zoneGrid/Types.ts

@@ -38,10 +38,10 @@ export interface ZoneField {
 }
 
 export interface ZoneGridModelPersistOptions extends PersistOptions {
-    /** True to include mapping information (default true) */
-    persistMapping?: boolean;
-    /** True to include grouping information (default true) */
-    persistGrouping?: boolean;
-    /** True to include sorting information (default true) */
-    persistSort?: boolean;
+    /** True (default) to include mapping state or provide mapping-specific PersistOptions. */
+    persistMappings?: boolean | PersistOptions;
+    /** True (default) to include grouping state or provide grouping-specific PersistOptions. */
+    persistGrouping?: boolean | PersistOptions;
+    /** True (default) to include sort state or provide sort-specific PersistOptions. */
+    persistSort?: boolean | PersistOptions;
 }

package/cmp/zoneGrid/ZoneGridModel.ts

@@ -56,7 +56,7 @@ import {action, bindable, makeObservable, observable} from '@xh/hoist/mobx';
 import {executeIfFunction, throwIf, withDefault} from '@xh/hoist/utils/js';
 import {castArray, find, forOwn, isEmpty, isFinite, isPlainObject, isString} from 'lodash';
 import {ReactNode} from 'react';
-import {ZoneGridPersistenceModel} from './impl/ZoneGridPersistenceModel';
+import {initPersist} from './impl/InitPersist';
 import {ZoneMapperConfig, ZoneMapperModel} from './impl/ZoneMapperModel';
 import {Zone, ZoneGridModelPersistOptions, ZoneLimit, ZoneMapping} from './Types';
 
@@ -315,7 +315,6 @@ export class ZoneGridModel extends HoistModel {
     restoreDefaultsWarning: ReactNode;
 
     private _defaultState; // initial state provided to ctor - powers restoreDefaults().
-    @managed persistenceModel: ZoneGridPersistenceModel;
 
     constructor(config: ZoneGridConfig) {
         super();
@@ -363,9 +362,7 @@ export class ZoneGridModel extends HoistModel {
         this.setGroupBy(groupBy);
 
         this.mapperModel = this.parseMapperModel(zoneMapperModel);
-        this.persistenceModel = persistWith
-            ? new ZoneGridPersistenceModel(this, persistWith)
-            : null;
+        if (persistWith) initPersist(this, persistWith);
 
         this.addReaction({
             track: () => [this.leftColumnSpec, this.rightColumnSpec],
@@ -398,8 +395,6 @@ export class ZoneGridModel extends HoistModel {
         this.setSortBy(sortBy);
         this.setGroupBy(groupBy);
 
-        this.persistenceModel?.clear();
-
         if (this.restoreDefaultsFn) {
             await this.restoreDefaultsFn();
         }

package/cmp/zoneGrid/impl/InitPersist.ts

@@ -0,0 +1,70 @@
+/*
+ * This file belongs to Hoist, an application development toolkit
+ * developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
+ *
+ * Copyright © 2024 Extremely Heavy Industries Inc.
+ */
+import {PersistableState, PersistenceProvider} from '@xh/hoist/core';
+import {isObject} from 'lodash';
+import {ZoneGridModel} from '../ZoneGridModel';
+import {ZoneGridModelPersistOptions} from '../Types';
+
+/**
+ * Initialize persistence for a {@link ZoneGridModel} by applying its `persistWith` config.
+ * @internal
+ */
+export function initPersist(
+    zoneGridModel: ZoneGridModel,
+    {
+        persistMappings = true,
+        persistGrouping = true,
+        persistSort = true,
+        path = 'zoneGrid',
+        ...rootPersistWith
+    }: ZoneGridModelPersistOptions
+) {
+    if (persistMappings) {
+        const persistWith = isObject(persistMappings) ? persistMappings : rootPersistWith;
+        PersistenceProvider.create({
+            persistOptions: {
+                path: `${path}.mappings`,
+                ...persistWith
+            },
+            target: {
+                getPersistableState: () => new PersistableState(zoneGridModel.mappings),
+                setPersistableState: ({value}) => zoneGridModel.setMappings(value)
+            },
+            owner: zoneGridModel
+        });
+    }
+
+    if (persistGrouping) {
+        const persistWith = isObject(persistGrouping) ? persistGrouping : rootPersistWith;
+        PersistenceProvider.create({
+            persistOptions: {
+                path: `${path}.groupBy`,
+                ...persistWith
+            },
+            target: {
+                getPersistableState: () => new PersistableState(zoneGridModel.groupBy),
+                setPersistableState: ({value}) => zoneGridModel.setGroupBy(value)
+            },
+            owner: zoneGridModel
+        });
+    }
+
+    if (persistSort) {
+        const persistWith = isObject(persistSort) ? persistSort : rootPersistWith;
+        PersistenceProvider.create({
+            persistOptions: {
+                path: `${path}.sortBy`,
+                ...persistWith
+            },
+            target: {
+                getPersistableState: () => new PersistableState(zoneGridModel.sortBy?.toString()),
+                setPersistableState: ({value}) => zoneGridModel.setSortBy(value)
+            },
+            owner: zoneGridModel
+        });
+    }
+}

package/core/HoistBase.ts

@@ -4,7 +4,8 @@
  *
  * Copyright © 2024 Extremely Heavy Industries Inc.
  */
-import {XH, PersistenceProvider, PersistOptions, DebounceSpec, Some} from './';
+import {runInAction} from 'mobx';
+import {XH, PersistenceProvider, PersistOptions, DebounceSpec, Some, PersistableState} from './';
 import {
     throwIf,
     getOrCreate,
@@ -16,19 +17,16 @@ import {
     withInfo
 } from '@xh/hoist/utils/js';
 import {
-    cloneDeep,
     debounce as lodashDebounce,
     isFunction,
     isNil,
     isNumber,
     isPlainObject,
     isString,
-    isUndefined,
     upperFirst
 } from 'lodash';
 import {
     action,
-    runInAction,
     comparer,
     autorun as mobxAutorun,
     reaction as mobxReaction,
@@ -258,26 +256,20 @@ export abstract class HoistBase {
      * @param options - options governing the persistence of this object. These will be applied
      *      on top of any default persistWith options defined on the instance itself.
      */
-    markPersist(property: string, options: PersistOptions = {}) {
+    markPersist(property: keyof this & string, options: PersistOptions = {}) {
         // Read from and attach to Provider, failing gently
-        try {
-            const persistWith = {path: property, ...this.persistWith, ...options},
-                provider = this.markManaged(PersistenceProvider.create(persistWith)),
-                providerState = provider.read();
-            if (!isUndefined(providerState)) {
-                runInAction(() => (this[property] = cloneDeep(providerState)));
+        PersistenceProvider.create({
+            persistOptions: {
+                path: property,
+                ...this.persistWith,
+                ...options
+            },
+            owner: this,
+            target: {
+                getPersistableState: () => new PersistableState(this[property]),
+                setPersistableState: state => runInAction(() => (this[property] = state.value))
             }
-            this.addReaction({
-                track: () => this[property],
-                run: data => provider.write(data)
-            });
-        } catch (e) {
-            this.logError(
-                `Failed to configure Persistence for '${property}'.  Be sure to fully specify ` +
-                    `'persistWith' on this object or in the method call`,
-                e
-            );
-        }
+        });
     }
 
     /** @returns true if this instance has been destroyed. */

package/core/HoistBaseDecorators.ts

@@ -4,10 +4,8 @@
  *
  * Copyright © 2024 Extremely Heavy Industries Inc.
  */
-import {cloneDeep, isUndefined} from 'lodash';
-import {wait} from '../promise';
 import {logError, throwIf} from '../utils/js';
-import {HoistBaseClass, PersistenceProvider, PersistOptions} from './';
+import {HoistBaseClass, PersistableState, PersistenceProvider, PersistOptions} from './';
 
 /**
  * Decorator to make a property "managed". Managed properties are designed to hold objects that
@@ -74,34 +72,34 @@ function createPersistDescriptor(
         return descriptor;
     }
     const codeValue = descriptor.initializer;
+    let hasInitialized = false,
+        ret;
     const initializer = function () {
-        let providerState;
+        // Initializer can be called multiple times when stacking decorators.
+        if (hasInitialized) return ret;
 
-        // Read from and attach to Provider.
-        // Fail gently -- initialization exceptions causes stack overflows for MobX.
-        try {
-            const persistWith = {path: property, ...this.persistWith, ...options},
-                provider = this.markManaged(PersistenceProvider.create(persistWith));
-            providerState = cloneDeep(provider.read());
-            wait().then(() => {
-                this.addReaction({
-                    track: () => this[property],
-                    run: data => provider.write(data)
-                });
-            });
-        } catch (e) {
-            logError(
-                [
-                    `Failed to configure Persistence for '${property}'.  Be sure to fully specify ` +
-                        `'persistWith' on this object or annotation`,
-                    e
-                ],
-                target
-            );
-        }
+        // codeValue undefined if no initial in-code value provided, otherwise call to get initial value.
+        ret = codeValue?.call(this);
 
-        // 2) Return data from provider data *or* code, if provider not yet set or failed
-        return !isUndefined(providerState) ? providerState : codeValue?.call(this);
+        const persistOptions = {path: property, ...this.persistWith, ...options};
+        PersistenceProvider.create({
+            persistOptions,
+            owner: this,
+            target: {
+                getPersistableState: () =>
+                    new PersistableState(hasInitialized ? this[property] : ret),
+                setPersistableState: state => {
+                    if (!hasInitialized) {
+                        ret = state.value;
+                    } else {
+                        this[property] = state.value;
+                    }
+                }
+            }
+        });
+
+        hasInitialized = true;
+        return ret;
     };
     return {...descriptor, initializer};
 }

package/core/persist/CustomProvider.ts

@@ -5,7 +5,7 @@
  * Copyright © 2024 Extremely Heavy Industries Inc.
  */
 
-import {PersistenceProvider, PersistOptions} from './';
+import {PersistenceProvider, PersistenceProviderConfig} from './';
 import {throwIf} from '@xh/hoist/utils/js';
 
 /**
@@ -15,16 +15,17 @@ import {throwIf} from '@xh/hoist/utils/js';
  * This provider allows applications to use the Persistence API to populate and read state from
  * components without actually writing to any pre-defined storage.
  */
-export class CustomProvider extends PersistenceProvider {
-    getData;
-    setData;
+export class CustomProvider<S> extends PersistenceProvider<S> {
+    readonly getData;
+    readonly setData;
 
-    constructor({getData, setData, ...rest}: PersistOptions) {
+    constructor(cfg: PersistenceProviderConfig<S>) {
+        super(cfg);
+        const {getData, setData} = cfg.persistOptions;
         throwIf(
             !getData || !setData,
             `CustomProvider requires a 'getData' and a 'setData' function.`
         );
-        super(rest);
         this.getData = getData;
         this.setData = setData;
     }
@@ -39,8 +40,4 @@ export class CustomProvider extends PersistenceProvider {
     override writeRaw(data) {
         this.setData(data);
     }
-
-    override clearRaw() {
-        this.setData(null);
-    }
 }

package/core/persist/DashViewProvider.ts

@@ -5,18 +5,20 @@
  * Copyright © 2024 Extremely Heavy Industries Inc.
  */
 
-import {PersistenceProvider, PersistOptions} from './';
+import type {DashViewModel} from '@xh/hoist/desktop/cmp/dash'; // Import type only
 import {throwIf} from '@xh/hoist/utils/js';
+import {PersistenceProvider, PersistenceProviderConfig} from './';
 
 /**
  * PersistenceProvider that stores state within a DashViewModel.
  */
-export class DashViewProvider extends PersistenceProvider {
-    dashViewModel;
+export class DashViewProvider<S> extends PersistenceProvider<S> {
+    readonly dashViewModel: DashViewModel;
 
-    constructor({dashViewModel, ...rest}: PersistOptions) {
+    constructor(cfg: PersistenceProviderConfig<S>) {
+        super(cfg);
+        const {dashViewModel} = cfg.persistOptions;
         throwIf(!dashViewModel, `DashViewProvider requires a 'dashViewModel'.`);
-        super(rest);
         this.dashViewModel = dashViewModel;
     }
 
@@ -29,10 +31,6 @@ export class DashViewProvider extends PersistenceProvider {
     }
 
     override writeRaw(data) {
-        this.dashViewModel.setViewState(data);
-    }
-
-    override clearRaw() {
-        return this.dashViewModel.setViewState(null);
+        this.dashViewModel.viewState = data;
     }
 }