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

package/core/persist/LocalStorageProvider.ts

@@ -5,20 +5,21 @@
  * Copyright © 2024 Extremely Heavy Industries Inc.
  */
 
-import {PersistenceProvider, PersistOptions} from './';
+import {XH} from '@xh/hoist/core';
 import {throwIf} from '@xh/hoist/utils/js';
-import {XH} from '../';
+import {PersistenceProvider, PersistenceProviderConfig} from './';
 
 /**
  * PersistenceProvider that stores state within the Browser's LocalStorage.
  */
-export class LocalStorageProvider extends PersistenceProvider {
-    key: string;
+export class LocalStorageProvider<S> extends PersistenceProvider<S> {
+    readonly key: string;
 
-    constructor({localStorageKey: key, ...rest}: PersistOptions) {
-        throwIf(!key, `LocalStorageProvider requires a 'localStorageKey'.`);
-        super(rest);
-        this.key = key;
+    constructor(cfg: PersistenceProviderConfig<S>) {
+        super(cfg);
+        const {localStorageKey} = cfg.persistOptions;
+        throwIf(!localStorageKey, `LocalStorageProvider requires a 'localStorageKey'.`);
+        this.key = localStorageKey;
     }
 
     //----------------
@@ -31,8 +32,4 @@ export class LocalStorageProvider extends PersistenceProvider {
     override writeRaw(data) {
         XH.localStorageService.set(this.key, data);
     }
-
-    override clearRaw() {
-        XH.localStorageService.remove(this.key);
-    }
 }

package/core/persist/PersistOptions.ts

@@ -6,10 +6,9 @@
  */
 
 import {DebounceSpec} from '../';
+import type {DashViewModel} from '@xh/hoist/desktop/cmp/dash'; // Import type only
+import type {ViewManagerModel} from '@xh/hoist/core/persist/viewmanager'; // Import type only
 
-/**
- * Options governing persistence.
- */
 export interface PersistOptions {
     /** Dot delimited path to store state. */
     path?: string;
@@ -30,7 +29,10 @@ export interface PersistOptions {
     localStorageKey?: string;
 
     /** DashViewModel used to read / write view state. */
-    dashViewModel?: object;
+    dashViewModel?: DashViewModel;
+
+    /** ViewManagerModel used to read / write view state. */
+    viewManagerModel?: ViewManagerModel;
 
     /**
      *  Function returning blob of data to be used for reading state.

package/core/persist/Persistable.ts

@@ -0,0 +1,23 @@
+import {isEqual} from 'lodash';
+
+/**
+ * Interface for objects that can be bound to a {@link PersistenceProvider}.
+ * @typeParam S - must be serializable to JSON and PersistableState<S> must be observable
+ */
+export interface Persistable<S> {
+    getPersistableState(): PersistableState<S>;
+    setPersistableState(state: PersistableState<S>): void;
+}
+
+/** Wrapper for a serializable Persistable state object. */
+export class PersistableState<S> {
+    value: S;
+
+    constructor(value: S) {
+        this.value = value;
+    }
+
+    equals(other: PersistableState<S>): boolean {
+        return isEqual(this.value, other.value);
+    }
+}

package/core/persist/PersistenceProvider.ts

@@ -5,24 +5,39 @@
  * Copyright © 2024 Extremely Heavy Industries Inc.
  */
 
-import {DebounceSpec, XH} from '../';
-import {
-    LocalStorageProvider,
-    PrefProvider,
-    DashViewProvider,
-    CustomProvider,
-    PersistOptions
-} from './';
+import {logDebug, logError, throwIf} from '@xh/hoist/utils/js';
 import {
     cloneDeep,
-    isUndefined,
+    debounce as lodashDebounce,
     get,
-    set,
-    unset,
+    isEmpty,
     isNumber,
-    debounce as lodashDebounce
+    isUndefined,
+    set,
+    toPath
 } from 'lodash';
-import {throwIf} from '@xh/hoist/utils/js';
+import {IReactionDisposer, reaction} from 'mobx';
+import {DebounceSpec, HoistBase, Persistable, PersistableState, XH} from '../';
+import {
+    CustomProvider,
+    DashViewProvider,
+    LocalStorageProvider,
+    PersistOptions,
+    PrefProvider,
+    ViewManagerProvider
+} from './';
+
+export type PersistenceProviderConfig<S> =
+    | {
+          persistOptions: PersistOptions;
+          target: Persistable<S>;
+          owner: HoistBase;
+      }
+    | {
+          persistOptions: PersistOptions;
+          target: Persistable<S> & HoistBase;
+          owner?: HoistBase;
+      };
 
 /**
  * Abstract superclass for adaptor objects used by models and components to (re)store state to and
@@ -32,51 +47,130 @@ import {throwIf} from '@xh/hoist/utils/js';
  * Implementations should take care to incorporate any writes immediately into the readable state.
  *
  * Hoist-provided implementations include:
- *   - {@link PrefProvider} - stores state in a predefined Hoist application Preference.
- *   - {@link LocalStorageProvider} - stores state in browser local storage under a configured key.
- *   - {@link DashViewProvider} - stores state with other Dashboard-specific state via a `DashViewModel`.
+ *   - {@link PrefProvider} - persists to a predefined Hoist JSON Preference.
+ *   - {@link LocalStorageProvider} - persists to browser local storage under a configured key.
+ *   - {@link DashViewProvider} - persists to a bound `DashViewModel` to save state for components
+ *     used within a dashboard widget. For this to be useful, the parent {@link DashModel} must
+ *     itself be persisted via a different provider - it acts as a collector of the widget-level
+ *     state managed by its DashViewModels and this provider.
+ *   - {@link ViewManagerProvider} - persists to saved views managed by {@link ViewManagerModel}.
  *   - {@link CustomProvider} - API for app and components to provide their own storage mechanism.
  */
-export class PersistenceProvider {
-    get isPersistenceProvider(): boolean {
-        return true;
-    }
+export abstract class PersistenceProvider<S> {
+    readonly path: string;
+    readonly debounce: DebounceSpec;
+    readonly owner: HoistBase;
 
-    path: string;
-    debounce: DebounceSpec;
+    protected target: Persistable<S>;
+    protected defaultState: PersistableState<S>;
+
+    private disposer: IReactionDisposer;
 
     /**
      * Construct an instance of this class.
+     *
+     * Will fail gently, returning `null` and logging an error if the provider could not be created
+     * due to an unparseable config or failure on initial read.
+     *
+     * Note: Targets should initialize their default persistable state *before* creating a
+     * `PersistenceProvider` and defer creating reactions to persistable state until *after*. This
+     * allows the provider to capture the default state and then apply any persisted state to the
+     * target without thrashing.
      */
-    static create({type, ...rest}: PersistOptions): PersistenceProvider {
-        if (!type) {
-            if (rest.prefKey) type = 'pref';
-            if (rest.localStorageKey) type = 'localStorage';
-            if (rest.dashViewModel) type = 'dashView';
-            if (rest.getData || rest.setData) type = 'custom';
-        }
+    static create<S>(cfg: PersistenceProviderConfig<S>): PersistenceProvider<S> {
+        cfg = {
+            owner: cfg.target instanceof HoistBase ? cfg.target : cfg.owner,
+            ...cfg
+        };
+        const {target, persistOptions} = cfg;
+
+        let {type, ...rest} = persistOptions,
+            ret: PersistenceProvider<S>;
 
-        switch (type) {
-            case 'pref':
-                return new PrefProvider(rest);
-            case 'localStorage':
-                return new LocalStorageProvider(rest);
-            case `dashView`:
-                return new DashViewProvider(rest);
-            case 'custom':
-                return new CustomProvider(rest);
-            default:
-                throw XH.exception(`Unknown Persistence Provider for type: ${type}`);
+        try {
+            if (!type) {
+                if (rest.prefKey) type = 'pref';
+                if (rest.localStorageKey) type = 'localStorage';
+                if (rest.dashViewModel) type = 'dashView';
+                if (rest.viewManagerModel) type = 'viewManager';
+                if (rest.getData || rest.setData) type = 'custom';
+            }
+
+            switch (type) {
+                case 'pref':
+                    ret = new PrefProvider(cfg);
+                    break;
+                case 'localStorage':
+                    ret = new LocalStorageProvider(cfg);
+                    break;
+                case `dashView`:
+                    ret = new DashViewProvider(cfg);
+                    break;
+                case `viewManager`:
+                    ret = new ViewManagerProvider(cfg);
+                    break;
+                case 'custom':
+                    ret = new CustomProvider(cfg);
+                    break;
+                default:
+                    throw XH.exception(`Unknown Persistence Provider for type: ${type}`);
+            }
+
+            ret.bindToTarget(target);
+            return ret;
+        } catch (e) {
+            logError(e, cfg.owner);
+            ret?.destroy();
+            return null;
         }
     }
 
-    /**
-     * Called by implementations only. See create.
-     */
-    protected constructor({path, debounce = 250}: PersistOptions) {
-        throwIf(isUndefined(path), 'Path not specified in PersistenceProvider.');
+    /** Read persisted state at this provider's path. */
+    read(): PersistableState<S> {
+        const state = get(this.readRaw(), this.path);
+        logDebug(['Reading state', state], this.owner);
+        return !isUndefined(state) ? new PersistableState(state) : null;
+    }
+
+    /** Persist JSON-serializable state to this provider's path. */
+    write(state: S) {
+        logDebug(['Writing state', state], this.owner);
+        this.writeInternal(state);
+    }
+
+    /** Clear any persisted data at a path. Also clears any parent objects that become empty. */
+    clear() {
+        logDebug('Clearing state', this.owner);
+        const obj = cloneDeep(this.readRaw()),
+            path = toPath(this.path);
+        do {
+            const property = path.pop(),
+                parent = isEmpty(path) ? obj : get(obj, path);
+            if (parent) delete parent[property];
+            if (!isEmpty(parent)) break;
+        } while (!isEmpty(path));
+        this.writeRaw(obj);
+    }
+
+    destroy() {
+        this.disposer?.();
+    }
+
+    //----------------
+    // Protected API
+    //----------------
+    /** Called by implementations only. Use the {@link create} factory instead. */
+    protected constructor(cfg: PersistenceProviderConfig<S>) {
+        const {owner, persistOptions} = cfg;
+        this.owner = owner;
+
+        const {path, debounce = 250} = persistOptions;
+        throwIf(!path, 'Path not specified in PersistenceProvider.');
+
         this.path = path;
         this.debounce = debounce;
+        this.owner.markManaged(this);
+
         if (debounce) {
             this.writeInternal = isNumber(debounce)
                 ? lodashDebounce(this.writeInternal, debounce)
@@ -84,49 +178,35 @@ export class PersistenceProvider {
         }
     }
 
-    /**
-     * Read data at a path
-     */
-    read(): any {
-        return get(this.readRaw(), this.path);
-    }
+    /** Called by factory method to bind this provider to its target. */
+    protected bindToTarget(target: Persistable<S>) {
+        this.target = target;
+        this.defaultState = target.getPersistableState();
 
-    /**
-     * Save data at a path
-     * @param data  - data to be written to the path, must be serializable to JSON.
-     */
-    write(data: any) {
-        this.writeInternal(data);
-    }
+        const state = this.read();
+        if (state) target.setPersistableState(state);
 
-    /**
-     * Clear any state saved by this object at a path
-     */
-    clear(path: string = this.path) {
-        const obj = cloneDeep(this.readRaw());
-        unset(obj, this.path);
-        this.writeRaw(obj);
+        // Direct use of MobX reaction to avoid circular dependency with HoistBase
+        this.disposer = reaction(
+            () => this.target.getPersistableState(),
+            state => {
+                if (state.equals(this.defaultState)) {
+                    this.clear();
+                } else {
+                    this.write(state.value);
+                }
+            }
+        );
     }
 
-    /**
-     * Clear *all* state held by this object.
-     */
-    clearAll() {
-        this.clearRaw();
-    }
-
-    //----------------
-    // Implementation
-    //----------------
-    protected writeInternal(data: object) {
+    protected writeInternal(data: S) {
         const obj = cloneDeep(this.readRaw());
         set(obj, this.path, data);
         this.writeRaw(obj);
     }
 
-    protected writeRaw(obj: object) {}
-    protected readRaw(): object {
+    protected writeRaw(obj: Record<typeof this.path, S>) {}
+    protected readRaw(): Record<typeof this.path, S> {
         return null;
     }
-    protected clearRaw() {}
 }

package/core/persist/PrefProvider.ts

@@ -5,20 +5,21 @@
  * Copyright © 2024 Extremely Heavy Industries Inc.
  */
 
-import {XH} from '../';
-import {PersistenceProvider, PersistOptions} from './';
+import {PersistenceProviderConfig, XH} from '../';
+import {PersistenceProvider} from './';
 import {throwIf} from '@xh/hoist/utils/js';
 
 /**
  * PersistenceProvider that stores state within the Hoist Preferences system.
  */
-export class PrefProvider extends PersistenceProvider {
-    key: string;
+export class PrefProvider<S> extends PersistenceProvider<S> {
+    readonly key: string;
 
-    constructor({prefKey: key, ...rest}: PersistOptions) {
-        throwIf(!key, `PrefProvider requires a 'prefKey'.`);
-        super(rest);
-        this.key = key;
+    constructor(cfg: PersistenceProviderConfig<S>) {
+        super(cfg);
+        const {prefKey} = cfg.persistOptions;
+        throwIf(!prefKey, `PrefProvider requires a 'prefKey'.`);
+        this.key = prefKey;
     }
 
     //----------------
@@ -31,8 +32,4 @@ export class PrefProvider extends PersistenceProvider {
     override writeRaw(data) {
         XH.prefService.set(this.key, data);
     }
-
-    override clearRaw() {
-        XH.prefService.unset(this.key);
-    }
 }

package/core/persist/index.ts

@@ -1,6 +1,8 @@
+export * from './Persistable';
 export * from './PersistOptions';
 export * from './PersistenceProvider';
 export * from './LocalStorageProvider';
 export * from './DashViewProvider';
 export * from './PrefProvider';
 export * from './CustomProvider';
+export * from './viewmanager/ViewManagerProvider';

package/core/persist/viewmanager/Types.ts

@@ -0,0 +1,51 @@
+import {PlainObject} from '@xh/hoist/core';
+
+/**
+ * Interface for a bundle of {@link PersistableState} managed by {@link ViewManagerModel}.
+ * Views are persisted to / loaded from the server as {@link JsonBlob}s.
+ */
+export interface View<T extends PlainObject = PlainObject> {
+    /** Either null for private views or special token "*" for globally shared views. */
+    acl: '*' | null;
+    dateCreated: number;
+    description: string;
+    /** Calculated display group - either "Shared [entityName]" or "My [entityName]". */
+    group: string;
+    /**
+     * True if user has tagged this view as a favorite. Note that a user's list of favorite views is
+     * persisted via `ViewManagerModel.persistWith` and *not* stored in the blob itself.
+     */
+    isFavorite: boolean;
+    /** True if this view has been shared (acl == "*") and is visible to all users. */
+    isShared: boolean;
+    lastUpdated: number;
+    lastUpdatedBy: string;
+    /** User-supplied descriptive name. */
+    name: string;
+    /** Original creator of the view, and the only user with access to it if not shared. */
+    owner: string;
+    token: string;
+    /** App-defined type discriminator, as per {@link ViewManagerConfig.viewType}. */
+    type: string;
+    value: T;
+}
+
+/**
+ * Abstract representation of ViewManager views available for selection, potentially grouped into
+ * hierarchical folders. Lightweight, user-driven organization into "folders" is supported by
+ * inserting a "\" in the name of any view.
+ */
+export type ViewTree = {
+    text: string;
+    selected: boolean;
+} & (
+    | {
+          type: 'folder';
+          items: ViewTree[];
+      }
+    | {
+          type: 'view';
+          token: string;
+          description: string;
+      }
+);