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

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+## v70.0.0-SNAPSHOT
+
+### 💥 Breaking Changes (upgrade difficulty: 🟢 LOW - changes to advanced persistence APIs)
+
+* Upgraded the `PersistenceProvider` API as noted in `New Features`. Could require updates in apps
+  with advanced direct usages of this API (uncommon).
+* Updated `GridModel` persistence to omit the widths of autosized columns from its persisted state.
+  This helps to keep persisted state more stable, avoiding spurious diffs due to autosize updates.
+  Note this can result in more visible column resizing for large grids without in-code default
+  widths. Please let XH know if this is a noticeable annoyance for your app.
+* Removed the following persistence-related model classes, properties, and methods:
+    * `GridPersistenceModel` and `ZoneGridPersistenceModel`
+    * `GridModel|ZoneGridModel.persistenceModel`
+    * `GridModel.autosizeState`
+    * `Column.manuallySized`
+    * `GroupingChooserModel|FilterChooserModel.persistValue`
+    * `DashModel|GroupingChooserModel|FilterChooserModel|PanelModel|TabContainerModel.provider`
+    * `PersistenceProvider.clearRaw()`
+* Renamed `ZoneGridModelPersistOptions.persistMappings`, adding the trailing `s` for consistency.
+* Changed signature of `JsonBlobService.listAsync()` to inline `loadSpec` with all other args in a
+  single options object.
+* Changed signature of `waitFor()` to take its optional `interval` and `timeout` arguments in a
+  single options object.
+
+### 🎁 New Features
+
+* Introduced a new `ViewManager` component and backing model to support user-driven management of
+  persisted component state - e.g. saved grid views.
+    * Bundled with a desktop-only menu button based component, but designed to be extensible.
+    * Bindable to any persistable component with `persistWith: {viewManagerModel: myViewManager}`.
+    * Detects changes to any bound components and syncs them back to saved views, with support for
+      an autosave option or user-driven saving with a clear "dirty" indicator.
+    * Saves persisted state back to the server using Hoist Core `JSONBlob`s for storage.
+    * Includes a simple sharing model - if enabled for all or some users, allows those users to
+      publish saved views to everyone else in the application.
+    * Users can rename views, nest them into folders, and mark them as favorites for quick access.
+* Generally enhanced Hoist's persistence-related APIs:
+    * Added new `Persistable` interface to formalize the contract for objects that can be persisted.
+    * `PersistenceProvider` now targets a `Persistable` and is responsible for setting persisted
+      state on its bound `Persistable` when the provider is constructed and persisting state from
+      its bound `Persistable` when changes are detected.
+    * In its constructor, `PersistenceProvider` also stores the initial state of its bound
+      `Persistable` and clears its persisted state when structurally equal to the initial state.
+* Updated persistable components to support specifying distinct `PersistOptions` for individual
+  bits of persisted state. E.g. you can now configure a `GroupingChooserModel` used within a
+  dashboard widget to persist its value to that particular widget's `DashViewModel` while saving the
+  user's favorites to a global preference.
+
+### ⚙️ Typescript API Adjustments
+
+* Tightened `FilterChooserFilterLike` union type to remove the generic `Filter` type, as filter
+  chooser supports only `FieldFilter` and `CompoundFilter`.
+* Improved `HoistBase.markPersist()` signature to ensure the provided property name is a known key
+  of the model.
+* Expanded the `JsonBlob` interface to include additional properties present on all blobs.
+* Corrected `DashViewSpec.title` to be optional - it can be defaulted from the `id`.
+
 ## 69.1.0 - 2024-11-07
 
 ### 🐞 Bug Fixes

package/build/types/cmp/filter/FilterChooserModel.d.ts

@@ -1,4 +1,4 @@
-import { HoistModel, PersistenceProvider, PersistOptions, PlainObject, TaskObserver } from '@xh/hoist/core';
+import { HoistModel, PersistOptions, TaskObserver, Thunkable } from '@xh/hoist/core';
 import { CompoundFilter, FieldFilter, Filter, Store, View } from '@xh/hoist/data';
 import { CompoundFilterSpec, FieldFilterSpec, FilterLike } from '@xh/hoist/data/filter/Types';
 import { ReactNode } from 'react';
@@ -30,11 +30,11 @@ export interface FilterChooserConfig {
      * to produce the same. Note that FilterChooser currently can only edit and create a flat collection
      * of FieldFilters, to be 'AND'ed together.
      */
-    initialValue?: FilterChooserFilterLike | (() => FilterChooserFilterLike);
+    initialValue?: Thunkable<FilterChooserFilterLike>;
     /**
      * Initial favorites as an array of filter configurations, or a function to produce such an array.
      */
-    initialFavorites?: FilterChooserFilterLike[] | (() => FilterChooserFilterLike[]);
+    initialFavorites?: Thunkable<FilterChooserFilterLike[]>;
     /**
      * true to offer all field suggestions when the control is focused with an empty query,
      * to aid discoverability.
@@ -70,8 +70,6 @@ export declare class FilterChooserModel extends HoistModel {
     maxTags: number;
     maxResults: number;
     introHelpText: ReactNode;
-    provider: PersistenceProvider;
-    persistValue: boolean;
     persistFavorites: boolean;
     /** Tracks execution of filtering operation on bound object.*/
     filterTask: TaskObserver;
@@ -106,25 +104,32 @@ export declare class FilterChooserModel extends HoistModel {
     }[];
     openFavoritesMenu(): void;
     closeFavoritesMenu(): void;
-    setFavorites(favorites: Filter[]): void;
+    setFavorites(favorites: FilterChooserFilterLike[]): void;
     addFavorite(filter: FilterChooserFilter): void;
     removeFavorite(filter: FilterChooserFilter): void;
     findFavorite(filter: FilterChooserFilter): Filter;
     isFavorite(filter: FilterChooserFilter): boolean;
-    get persistState(): PlainObject;
     parseFieldSpecs(specs: Array<FilterChooserFieldSpecConfig | string>, fieldSpecDefaults: Partial<FilterChooserFieldSpecConfig>): Array<FilterChooserFieldSpec>;
     getFieldSpec(fieldName: string): FilterChooserFieldSpec;
     validateFilter(f: Filter): f is FilterChooserFilter;
     getDefaultIntroHelpText(): string;
+    private initPersist;
+    private setValueInternal;
+    /**
+     * Update the select value and bind the filter to the bound model. Runs asynchronously after
+     * selectOptions are set to ensure the component is ready to render the tags correctly.
+     */
+    private updateSelectValueAndBind;
 }
 interface FilterChooserPersistOptions extends PersistOptions {
-    /** True (default) to save value to state. */
-    persistValue?: boolean;
-    /** True (default) to include favorites. */
-    persistFavorites?: boolean;
+    /** True (default) to include value or provide value-specific PersistOptions. */
+    persistValue?: boolean | PersistOptions;
+    /** True (default) to include favorites or provide favorites-specific PersistOptions. */
+    persistFavorites?: boolean | PersistOptions;
 }
 /** A variant of {@link Filter} that excludes FunctionFilter (unsupported by FilterChooser). */
 export type FilterChooserFilter = CompoundFilter | FieldFilter;
+export type FilterChooserFilterSpec = CompoundFilterSpec | FieldFilterSpec;
 /** A variant of {@link FilterLike} that excludes FunctionFilters and FilterTestFn. */
-export type FilterChooserFilterLike = Filter | CompoundFilterSpec | FieldFilterSpec | FilterChooserFilterLike[];
+export type FilterChooserFilterLike = FilterChooserFilter | FilterChooserFilterSpec | FilterChooserFilterLike[];
 export {};

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

@@ -9,8 +9,7 @@ import { ReactNode } from 'react';
 import { GridAutosizeOptions } from './GridAutosizeOptions';
 import { GridContextMenuSpec } from './GridContextMenu';
 import { GridSorter, GridSorterLike } from './GridSorter';
-import { GridPersistenceModel } from './impl/GridPersistenceModel';
-import { AutosizeState, ColChooserConfig, ColumnState, GridModelPersistOptions, GroupRowRenderer, RowClassFn, RowClassRuleFn } from './Types';
+import { ColChooserConfig, ColumnState, GridModelPersistOptions, GroupRowRenderer, RowClassFn, RowClassRuleFn } from './Types';
 export interface GridConfig {
     /** Columns for this grid. */
     columns?: Array<ColumnSpec | ColumnGroupSpec>;
@@ -245,9 +244,9 @@ export declare class GridModel extends HoistModel {
     columns: Array<ColumnGroup | Column>;
     columnState: ColumnState[];
     expandState: any;
-    autosizeState: AutosizeState;
     sortBy: GridSorter[];
     groupBy: string[];
+    get persistableColumnState(): ColumnState[];
     showSummary: boolean | VSide;
     emptyText: ReactNode;
     treeStyle: TreeStyle;
@@ -265,7 +264,6 @@ export declare class GridModel extends HoistModel {
     isInEditingMode: boolean;
     static defaultContextMenu: string[];
     private _defaultState;
-    persistenceModel: GridPersistenceModel;
     /**
      * Is autosizing enabled on this grid?
      * To disable autosizing, set autosizeOptions.mode to GridAutosizeMode.DISABLED.
@@ -436,9 +434,7 @@ export declare class GridModel extends HoistModel {
     setExpandState(expandState: any): void;
     noteAgExpandStateChange(): void;
     noteAgSelectionStateChanged(): void;
-    setAutosizeState(autosizeState: any): void;
     noteColumnManuallySized(colId: any, width: any): void;
-    noteColumnsAutosized(colIds: any): void;
     /**
      * This method will update the current column definition if it has changed.
      * Throws an exception if any of the columns provided in colStateChanges are not
@@ -499,12 +495,12 @@ export declare class GridModel extends HoistModel {
      * columns are also ignored unless {@link GridAutosizeOptions.includeHiddenColumns} has been
      * set to true.
      *
-     * @param options - optional overrides of this model's configured {@link autosizeOptions}.
+     * @param overrideOpts - optional overrides of this model's {@link GridAutosizeOptions}.
      */
-    autosizeAsync(options?: GridAutosizeOptions): Promise<void>;
+    autosizeAsync(overrideOpts?: Omit<GridAutosizeOptions, 'mode'>): Promise<void>;
     /**
      * Begin an inline editing session.
-     * @param recOrId - StoreRecord/ID to edit. If unspecified, the first selected StoreRecord
+     * @param record - StoreRecord/ID to edit. If unspecified, the first selected StoreRecord
      *      will be used, if any, or the first overall StoreRecord in the grid.
      * @param colId - ID of column on which to start editing. If unspecified, the first
      *      editable column will be used.

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

@@ -1,6 +1,6 @@
 import { IRowNode } from '@xh/hoist/kit/ag-grid';
 import { GridFilterFieldSpecConfig } from '@xh/hoist/cmp/grid/filter/GridFilterFieldSpec';
-import { HSide, PersistOptions, SizingMode, Some } from '@xh/hoist/core';
+import { HSide, PersistOptions, Some } from '@xh/hoist/core';
 import { Store, StoreRecord, View } from '@xh/hoist/data';
 import { ReactElement, ReactNode } from 'react';
 import { Column } from './columns/Column';
@@ -16,10 +16,6 @@ export interface ColumnState {
     /** Side if pinned, null if not. */
     pinned?: HSide;
 }
-export interface AutosizeState {
-    /** Sizing mode used last time the columns were autosized. */
-    sizingMode?: SizingMode;
-}
 /**
  * Comparator for custom grid group sorting, provided to GridModel.
  * @param groupAVal - first group value to be compared.
@@ -51,20 +47,12 @@ export type RowClassFn = (record: StoreRecord) => Some<string>;
  */
 export type RowClassRuleFn = (agParams: RowClassParams) => boolean;
 export interface GridModelPersistOptions extends PersistOptions {
-    /** True to include column information (default true) */
-    persistColumns?: boolean;
-    /** True to include grouping information (default true) */
-    persistGrouping?: boolean;
-    /** True to include sorting information (default true) */
-    persistSort?: boolean;
-    /**
-     * Key to be used to identify location of legacy grid state from LocalStorage.
-     * This key will identify the pre-v35 location for grid state, and will be used
-     * as an initial source of grid state after an upgrade to v35.0.0 or greater.
-     * Defaults to the new value of 'key'.  If no legacy state is available at this
-     * location, the key is ignored.
-     */
-    legacyStateKey?: string;
+    /** True (default) to include column state or provide column-specific PersistOptions. */
+    persistColumns?: 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;
 }
 export interface GridFilterModelConfig {
     /**

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

@@ -337,7 +337,6 @@ export declare class Column {
     actions?: Array<RecordActionSpec | RecordAction>;
     actionsShowOnHoverOnly?: boolean;
     fieldSpec: FieldSpec;
-    manuallySized: boolean;
     omit: Thunkable<boolean>;
     gridModel: GridModel;
     agOptions: ColDef;

package/build/types/cmp/grid/impl/InitPersist.d.ts

@@ -0,0 +1,7 @@
+import { GridModel } from '../GridModel';
+import { GridModelPersistOptions } from '../Types';
+/**
+ * Initialize persistence for a {@link GridModel} by applying its `persistWith` config.
+ * @internal
+ */
+export declare function initPersist(gridModel: GridModel, { persistColumns, persistGrouping, persistSort, path, ...rootPersistWith }: GridModelPersistOptions): void;

package/build/types/cmp/grouping/GroupingChooserModel.d.ts

@@ -1,5 +1,5 @@
 /// <reference types="react" />
-import { HoistModel, PersistenceProvider, PersistOptions, PlainObject } from '@xh/hoist/core';
+import { HoistModel, PersistOptions } from '@xh/hoist/core';
 export interface GroupingChooserConfig {
     /**
      * Dimensions available for selection. When using GroupingChooser to create Cube queries,
@@ -34,10 +34,10 @@ export interface DimensionSpec {
     displayName?: string;
 }
 export interface GroupingChooserPersistOptions extends PersistOptions {
-    /** True (default) to save value to state. */
-    persistValue?: boolean;
-    /** True (default) to include favorites. */
-    persistFavorites?: boolean;
+    /** True (default) to include value or provide value-specific PersistOptions. */
+    persistValue?: boolean | PersistOptions;
+    /** True (default) to include favorites or provide favorites-specific PersistOptions. */
+    persistFavorites?: boolean | PersistOptions;
 }
 export declare class GroupingChooserModel extends HoistModel {
     value: string[];
@@ -45,8 +45,6 @@ export declare class GroupingChooserModel extends HoistModel {
     allowEmpty: boolean;
     maxDepth: number;
     commitOnChange: boolean;
-    provider: PersistenceProvider;
-    persistValue: boolean;
     persistFavorites: boolean;
     pendingValue: string[];
     editorIsOpen: boolean;
@@ -81,7 +79,7 @@ export declare class GroupingChooserModel extends HoistModel {
     addFavorite(value: string[]): void;
     removeFavorite(value: string[]): void;
     isFavorite(value: string[]): boolean;
-    get persistState(): PlainObject;
+    private initPersist;
     private normalizeDimensions;
     private createDimension;
     private removeUnknownDimsFromValue;

package/build/types/cmp/tab/TabContainerModel.d.ts

@@ -1,4 +1,4 @@
-import { HoistModel, PersistenceProvider, PersistOptions, RefreshContextModel, RefreshMode, RenderMode } from '@xh/hoist/core';
+import { HoistModel, Persistable, PersistableState, PersistOptions, RefreshContextModel, RefreshMode, RenderMode } from '@xh/hoist/core';
 import { ReactNode } from 'react';
 import { TabConfig, TabModel } from './TabModel';
 import { TabSwitcherProps } from './TabSwitcherProps';
@@ -54,7 +54,9 @@ export interface TabContainerConfig {
  *
  * Note: Routing is currently enabled for desktop applications only.
  */
-export declare class TabContainerModel extends HoistModel {
+export declare class TabContainerModel extends HoistModel implements Persistable<{
+    activeTabId: string;
+}> {
     config: TabContainerConfig;
     tabs: TabModel[];
     activeTabId: string;
@@ -65,7 +67,6 @@ export declare class TabContainerModel extends HoistModel {
     renderMode: RenderMode;
     refreshMode: RefreshMode;
     emptyText: ReactNode;
-    provider: PersistenceProvider;
     refreshContextModel: RefreshContextModel;
     private lastActiveTabId;
     constructor({ tabs, defaultTabId, route, switcher, track, renderMode, refreshMode, persistWith, emptyText, xhImpl }: TabContainerConfig);
@@ -103,11 +104,16 @@ export declare class TabContainerModel extends HoistModel {
      * @param cycle - true to loop back to first tab if necessary.
      */
     activateNextTab(cycle?: boolean): void;
+    getPersistableState(): PersistableState<{
+        activeTabId: string;
+    }>;
+    setPersistableState(state: PersistableState<{
+        activeTabId: string;
+    }>): void;
     private setActiveTabIdInternal;
     private syncWithRouter;
     private forwardRouterToTab;
     private calculateActiveTabId;
-    private setupStateProvider;
 }
 export interface AddTabOptions {
     /** Index in tab collection where tab is to be added. */

package/build/types/cmp/zoneGrid/Types.d.ts

@@ -26,10 +26,10 @@ export interface ZoneField {
     sortingOrder: ColumnSortSpec[];
 }
 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/build/types/cmp/zoneGrid/ZoneGridModel.d.ts

@@ -3,7 +3,6 @@ import { ColumnRenderer, ColumnSpec, GridContextMenuSpec, GridGroupSortFn, GridM
 import { Awaitable, HoistModel, LoadSpec, PlainObject, Some, VSide } from '@xh/hoist/core';
 import { RecordAction, Store, StoreConfig, StoreRecordOrId, StoreSelectionConfig, StoreSelectionModel, StoreTransaction } from '@xh/hoist/data';
 import { ReactNode } from 'react';
-import { ZoneGridPersistenceModel } from './impl/ZoneGridPersistenceModel';
 import { ZoneMapperConfig, ZoneMapperModel } from './impl/ZoneMapperModel';
 import { Zone, ZoneGridModelPersistOptions, ZoneLimit, ZoneMapping } from './Types';
 export interface ZoneGridConfig {
@@ -203,7 +202,6 @@ export declare class ZoneGridModel extends HoistModel {
     restoreDefaultsFn: () => Awaitable<void>;
     restoreDefaultsWarning: ReactNode;
     private _defaultState;
-    persistenceModel: ZoneGridPersistenceModel;
     constructor(config: ZoneGridConfig);
     /**
      * Restore the mapping, sorting, and grouping configs as specified by the application at

package/build/types/cmp/zoneGrid/impl/InitPersist.d.ts

@@ -0,0 +1,7 @@
+import { ZoneGridModel } from '../ZoneGridModel';
+import { ZoneGridModelPersistOptions } from '../Types';
+/**
+ * Initialize persistence for a {@link ZoneGridModel} by applying its `persistWith` config.
+ * @internal
+ */
+export declare function initPersist(zoneGridModel: ZoneGridModel, { persistMappings, persistGrouping, persistSort, path, ...rootPersistWith }: ZoneGridModelPersistOptions): void;

package/build/types/core/HoistBase.d.ts

@@ -134,7 +134,7 @@ export declare 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): void;
+    markPersist(property: keyof this & string, options?: PersistOptions): void;
     /** @returns true if this instance has been destroyed. */
     get isDestroyed(): boolean;
     /**

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

@@ -1,4 +1,4 @@
-import { PersistenceProvider, PersistOptions } from './';
+import { PersistenceProvider, PersistenceProviderConfig } from './';
 /**
  * A minimal Persistence provider for use by apps that wish to implement the actual persistence
  * of the backing data via custom handlers.
@@ -6,11 +6,10 @@ import { PersistenceProvider, PersistOptions } from './';
  * 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 declare class CustomProvider extends PersistenceProvider {
-    getData: any;
-    setData: any;
-    constructor({ getData, setData, ...rest }: PersistOptions);
+export declare class CustomProvider<S> extends PersistenceProvider<S> {
+    readonly getData: any;
+    readonly setData: any;
+    constructor(cfg: PersistenceProviderConfig<S>);
     readRaw(): any;
     writeRaw(data: any): void;
-    clearRaw(): void;
 }

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

@@ -1,11 +1,11 @@
-import { PersistenceProvider, PersistOptions } from './';
+import type { DashViewModel } from '@xh/hoist/desktop/cmp/dash';
+import { PersistenceProvider, PersistenceProviderConfig } from './';
 /**
  * PersistenceProvider that stores state within a DashViewModel.
  */
-export declare class DashViewProvider extends PersistenceProvider {
-    dashViewModel: any;
-    constructor({ dashViewModel, ...rest }: PersistOptions);
-    readRaw(): any;
+export declare class DashViewProvider<S> extends PersistenceProvider<S> {
+    readonly dashViewModel: DashViewModel;
+    constructor(cfg: PersistenceProviderConfig<S>);
+    readRaw(): import("..").PlainObject;
     writeRaw(data: any): void;
-    clearRaw(): any;
 }

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

@@ -1,11 +1,10 @@
-import { PersistenceProvider, PersistOptions } from './';
+import { PersistenceProvider, PersistenceProviderConfig } from './';
 /**
  * PersistenceProvider that stores state within the Browser's LocalStorage.
  */
-export declare class LocalStorageProvider extends PersistenceProvider {
-    key: string;
-    constructor({ localStorageKey: key, ...rest }: PersistOptions);
+export declare class LocalStorageProvider<S> extends PersistenceProvider<S> {
+    readonly key: string;
+    constructor(cfg: PersistenceProviderConfig<S>);
     readRaw(): any;
     writeRaw(data: any): void;
-    clearRaw(): void;
 }

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

@@ -1,7 +1,6 @@
 import { DebounceSpec } from '../';
-/**
- * Options governing persistence.
- */
+import type { DashViewModel } from '@xh/hoist/desktop/cmp/dash';
+import type { ViewManagerModel } from '@xh/hoist/core/persist/viewmanager';
 export interface PersistOptions {
     /** Dot delimited path to store state. */
     path?: string;
@@ -17,7 +16,9 @@ export interface PersistOptions {
     /** Browser local storage key used to store state. */
     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.
      *  Ignored if `prefKey`, `localStorageKey` or `dashViewModel` are provided.

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

@@ -0,0 +1,14 @@
+/**
+ * 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 declare class PersistableState<S> {
+    value: S;
+    constructor(value: S);
+    equals(other: PersistableState<S>): boolean;
+}

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

@@ -1,5 +1,14 @@
-import { DebounceSpec } from '../';
+import { DebounceSpec, HoistBase, Persistable, PersistableState } from '../';
 import { PersistOptions } 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
  * from a persistent location, typically a Hoist preference or key within browser local storage.
@@ -8,42 +17,46 @@ import { PersistOptions } from './';
  * 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 declare class PersistenceProvider {
-    get isPersistenceProvider(): boolean;
-    path: string;
-    debounce: DebounceSpec;
+export declare abstract class PersistenceProvider<S> {
+    readonly path: string;
+    readonly debounce: DebounceSpec;
+    readonly owner: HoistBase;
+    protected target: Persistable<S>;
+    protected defaultState: PersistableState<S>;
+    private disposer;
     /**
      * 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;
-    /**
-     * Called by implementations only. See create.
-     */
-    protected constructor({ path, debounce }: PersistOptions);
-    /**
-     * Read data at a path
-     */
-    read(): any;
-    /**
-     * Save data at a path
-     * @param data  - data to be written to the path, must be serializable to JSON.
-     */
-    write(data: any): void;
-    /**
-     * Clear any state saved by this object at a path
-     */
-    clear(path?: string): void;
-    /**
-     * Clear *all* state held by this object.
-     */
-    clearAll(): void;
-    protected writeInternal(data: object): void;
-    protected writeRaw(obj: object): void;
-    protected readRaw(): object;
-    protected clearRaw(): void;
+    static create<S>(cfg: PersistenceProviderConfig<S>): PersistenceProvider<S>;
+    /** Read persisted state at this provider's path. */
+    read(): PersistableState<S>;
+    /** Persist JSON-serializable state to this provider's path. */
+    write(state: S): void;
+    /** Clear any persisted data at a path. Also clears any parent objects that become empty. */
+    clear(): void;
+    destroy(): void;
+    /** Called by implementations only. Use the {@link create} factory instead. */
+    protected constructor(cfg: PersistenceProviderConfig<S>);
+    /** Called by factory method to bind this provider to its target. */
+    protected bindToTarget(target: Persistable<S>): void;
+    protected writeInternal(data: S): void;
+    protected writeRaw(obj: Record<typeof this.path, S>): void;
+    protected readRaw(): Record<typeof this.path, S>;
 }

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

@@ -1,11 +1,11 @@
-import { PersistenceProvider, PersistOptions } from './';
+import { PersistenceProviderConfig } from '../';
+import { PersistenceProvider } from './';
 /**
  * PersistenceProvider that stores state within the Hoist Preferences system.
  */
-export declare class PrefProvider extends PersistenceProvider {
-    key: string;
-    constructor({ prefKey: key, ...rest }: PersistOptions);
+export declare class PrefProvider<S> extends PersistenceProvider<S> {
+    readonly key: string;
+    constructor(cfg: PersistenceProviderConfig<S>);
     readRaw(): any;
     writeRaw(data: any): void;
-    clearRaw(): void;
 }

package/build/types/core/persist/index.d.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';