@xh/hoist 82.0.1 → 82.0.3

package/build/types/core/impl/InstanceManager.d.ts

@@ -0,0 +1,24 @@
+import { HoistService, HoistModel } from '../';
+import { Store } from '@xh/hoist/data';
+/**
+ * Generic singleton object for cataloging global models and services.
+ * @internal
+ */
+declare class InstanceManager {
+    services: Set<HoistService>;
+    models: Set<HoistModel>;
+    stores: Set<Store>;
+    private modelsByTestId;
+    private testSupportedModels;
+    registerModel(m: HoistModel): void;
+    unregisterModel(m: HoistModel): void;
+    registerService(s: HoistService): void;
+    registerStore(s: Store): void;
+    unregisterStore(s: Store): void;
+    registerModelWithTestId(testId: string, m: HoistModel): void;
+    unregisterModelWithTestId(testId: string): void;
+    getModelByTestId(testId: string): HoistModel;
+    constructor();
+}
+export declare const instanceManager: InstanceManager;
+export {};

package/build/types/core/impl/PlatformManager.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Generic singleton object for registering Mobile and Desktop Components and ensuring that they
+ * are never cross-imported within the same client application bundle.
+ * @internal
+ */
+declare class PlatformManager {
+    private mobileAPIRegistered;
+    private desktopAPIRegistered;
+    registerDesktop(): void;
+    registerMobile(): void;
+}
+export declare const platformManager: PlatformManager;
+export {};

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

@@ -0,0 +1,22 @@
+export * from './enums/RefreshMode';
+export * from './enums/RenderMode';
+export * from './enums/SizingMode';
+export * from './types/Interfaces';
+export * from './types/Types';
+export * from './types/AppState';
+export * from './elem';
+export * from './persist/';
+export * from './TaskObserver';
+export * from './HoistBase';
+export * from './HoistBaseDecorators';
+export * from './load';
+export * from './model';
+export * from './HoistService';
+export * from './AppSpec';
+export * from './HoistProps';
+export * from './HoistComponent';
+export * from './RefreshContextView';
+export * from './HoistAppModel';
+export * from './HoistAuthModel';
+export * from './ExceptionHandler';
+export { XH, XHApi } from './XH';

package/build/types/core/load/LoadSpec.d.ts

@@ -0,0 +1,55 @@
+import { PlainObject } from '../types/Types';
+import { LoadSupport } from './';
+/**
+ * Object describing a load/refresh request in Hoist.
+ *
+ * Instances of this class are created within the public APIs provided by {@link LoadSupport}
+ * and are passed to subclass (i.e. app-level) implementations of `doLoadAsync()`.
+ *
+ * Application implementations of `doLoadAsync()` can consult this object's flags. Of particular
+ * interest are {@link isStale} and {@link isObsolete}, which implementations can read after any
+ * async calls return to determine if a newer, subsequent load has already been requested.
+ *
+ * In addition, `doLoadAsync()` implementations should typically pass along this object to any
+ * calls they make to `loadAsync()` on other objects + all calls to {@link FetchService} APIs.
+ *
+ * Note that Hoist's exception handling and activity tracking will consult the {@link isAutoRefresh}
+ * flag on specs passed to their calls to automatically adjust their behavior (e.g. not showing an
+ * exception dialog on error, not tracking background refresh activity).
+ *
+ * @see LoadSupport
+ */
+export type LoadSpecConfig = {
+    /** True if triggered by a refresh request (automatic or user-driven). */
+    isRefresh?: boolean;
+    /** True if triggered by an automatic refresh process. */
+    isAutoRefresh?: boolean;
+    /** Application specific information about the load request. */
+    meta?: PlainObject;
+};
+export declare class LoadSpec {
+    /** True if triggered by a refresh request (automatic or user-driven). */
+    isRefresh: boolean;
+    /** True if triggered by an automatic refresh process. */
+    isAutoRefresh: boolean;
+    /** Application specific information about the load request. */
+    meta: PlainObject;
+    /** Time the load started. */
+    dateCreated: Date;
+    /** Index of the associated load on this object - 0 for the first load. */
+    loadNumber: number;
+    /** Owner of this object. */
+    owner: LoadSupport;
+    /** True if a more recent request to load this object's owner has *started*. */
+    get isStale(): boolean;
+    /** True if a more recent request to load this object's owner has *successfully completed*. */
+    get isObsolete(): boolean;
+    /** Display type of refresh for troubleshooting and logging. */
+    get typeDisplay(): string;
+    get isFirstLoad(): boolean;
+    /**
+     * @internal - not for application use. LoadSpecs are constructed automatically by Hoist's
+     * {@link LoadSupport} class as part of its managed `loadAsync()` wrapper.
+     */
+    constructor(config: LoadSpecConfig, owner: LoadSupport);
+}

package/build/types/core/load/LoadSupport.d.ts

@@ -0,0 +1,36 @@
+import { HoistBase, LoadSpecConfig, PlainObject, TaskObserver } from '../';
+import { LoadSpec, Loadable } from './';
+/**
+ * Provides support for objects that participate in Hoist's loading/refresh lifecycle.
+ *
+ * This utility is used by core Hoist classes such as {@link HoistModel} and {@link HoistService}.
+ * Model and service instances will automatically create an instance of this class if they have
+ * declared a concrete implementation of `doLoadAsync()`, signalling that they wish to take
+ * advantage of the additional tracking and management provided here.
+ *
+ * Not typically created directly by applications.
+ */
+export declare class LoadSupport extends HoistBase implements Loadable {
+    lastRequested: LoadSpec;
+    lastSucceeded: LoadSpec;
+    loadObserver: TaskObserver;
+    lastLoadRequested: Date;
+    lastLoadCompleted: Date;
+    lastLoadException: any;
+    target: Loadable;
+    constructor(target: Loadable);
+    loadAsync(loadSpec?: LoadSpecConfig): Promise<void>;
+    refreshAsync(meta?: PlainObject): Promise<void>;
+    autoRefreshAsync(meta?: PlainObject): Promise<void>;
+    doLoadAsync(loadSpec: LoadSpec): Promise<void>;
+}
+/**
+ * Load a collection of objects concurrently.
+ *
+ * Note that this method uses 'allSettled' in its implementation, meaning a failure of any one call
+ * will not cause the entire batch to throw.
+ *
+ * @param objs - list of objects to be loaded
+ * @param loadSpec - optional metadata related to this request.
+ */
+export declare function loadAllAsync(objs: Loadable[], loadSpec?: LoadSpec | any): Promise<PromiseSettledResult<void>[]>;

package/build/types/core/load/Loadable.d.ts

@@ -0,0 +1,48 @@
+import { TaskObserver } from '../';
+import { LoadSpec } from './';
+/**
+ * Interface for the primary load/refresh APIs on models and services with {@link LoadSupport}.
+ */
+export interface Loadable {
+    /**
+     * For tracking the loading of this object.
+     * Note that this object will *not* track auto-refreshes.
+     */
+    loadObserver: TaskObserver;
+    /** Date when last load was initiated. */
+    lastLoadRequested: Date;
+    /** Date when last load was completed. */
+    lastLoadCompleted: Date;
+    /** Any exception that occurred during last load. */
+    lastLoadException: any;
+    /**
+     * Load the target.
+     *
+     * This method is the main public entry point for this interface and is responsible for
+     * calling the objects `doLoadAsync()` implementation.  See also `refreshAsync()` and
+     * `autoRefreshAsync()` for convenience variants of this method.
+     *
+     * @param loadSpec - a {@link LoadSpec}, or an object containing properties to create one.
+     */
+    loadAsync(loadSpec?: LoadSpec | Partial<LoadSpec>): Promise<void>;
+    /**
+     * Refresh the target.
+     * @param meta - optional metadata for the request.
+     */
+    refreshAsync(meta?: object): Promise<void>;
+    /**
+     * Auto-refresh the target.
+     * @param meta - optional metadata for the request.
+     */
+    autoRefreshAsync(meta?: object): Promise<void>;
+    /**
+     * Implement this method to load data or other state from external data sources or services.
+     * This is a template method - callers should call `loadAsync()` or `refreshAsync()` instead.
+     *
+     * @param loadSpec - metadata about the underlying request. Implementations should
+     *      take care to pass this parameter in calls to any delegates that support it, e.g.
+     *      when calling the `loadAsync()` method of other services or child models with
+     *      `loadSupport` or when making calls to {@link FetchService} APIs.
+     */
+    doLoadAsync(loadSpec: LoadSpec): Promise<void>;
+}

package/build/types/core/load/index.d.ts

@@ -0,0 +1,3 @@
+export * from './LoadSpec';
+export * from './Loadable';
+export * from './LoadSupport';

package/build/types/core/model/CreatesSpec.d.ts

@@ -0,0 +1,29 @@
+import { Thunkable } from './../types/Types';
+import { HoistModel, HoistModelClass, ModelPublishMode } from './';
+/**
+ * Returns a ModelSpec to define how a functional HoistComponent should create its primary backing
+ * HoistModel. Use this option when your component will create its own model internally, and does
+ * *not* expect one to be provided via props or context.
+ *
+ * The constructed model instance will be provided to the component via props and placed in context
+ * for access by all subcomponents.
+ *
+ * The model created will be considered to be 'owned' by the receiving component. If it implements
+ * loading it will be loaded on component mount, and it will always be destroyed on
+ * component unmount.
+ *
+ * @param spec - HoistModel Class to construct, or a function returning a concrete HoistModel instance.
+ * @param opts - additional options
+ */
+export declare function creates<T extends HoistModel>(spec: Thunkable<HoistModelClass<T>> | (() => T), opts?: CreatesOptions): CreatesSpec<T>;
+export interface CreatesOptions {
+    /** Mode for publishing this model to context. */
+    publishMode?: ModelPublishMode;
+}
+export declare class CreatesSpec<T extends HoistModel> {
+    fromContext: boolean;
+    optional: boolean;
+    publishMode: ModelPublishMode;
+    createFn: () => T;
+    constructor(spec: any, publishMode: ModelPublishMode);
+}

package/build/types/core/model/HoistModel.d.ts

@@ -0,0 +1,203 @@
+import { DefaultHoistProps, HoistBase, LoadSpecConfig, PlainObject, TaskObserver } from '../';
+import { Loadable, LoadSpec, LoadSupport } from '../load';
+import { ModelSelector } from './';
+import { Class } from 'type-fest';
+/**
+ * Base class for *stateful Hoist Models*.
+ *
+ * A `HoistModel` is the canonical Hoist unit for:
+ * - holding observable state (MobX)
+ * - implementing business logic and derived/computed values
+ * - coordinating async loading / refresh via `loadAsync()`
+ * - optionally participating in the component context hierarchy as a **linked model**
+ *
+ * PURPOSE
+ * - Provide a common lifecycle + MobX integration point for Hoist state.
+ * - Provide optional managed loading/refresh support when `doLoadAsync()` is implemented.
+ * - Provide linked-model features when a model is created via Hoist component wiring.
+ *
+ * NON-GOALS
+ * - This is not a React component.
+ * - This is not a generic DI container / service locator (use `lookupModel()` only for linked models).
+ * - This does not prescribe app-specific data fetching patterns beyond the `doLoadAsync()` template.
+ *
+ * KEY CONCEPTS (Hoist vocabulary)
+ * - **Model**: a long-lived stateful object backing UI and/or application state.
+ * - **Linked model**: a model created for (and bound to) a specific component instance.
+ * - **Load support**: managed async loading via {@link LoadSupport} + {@link LoadSpec}.
+ *
+ * LIFECYCLE / OWNERSHIP
+ * - Created by:
+ *   - Hoist component factories when configured with `model` (see {@link hoistCmp.factory}).
+ *   - The {@link creates} directive or {@link useLocalModel} hook (linked models).
+ *   - Application code (unlinked models) when used as general-purpose state holders.
+ * - Scope:
+ *   - Linked models are 1:1 with a component instance and are destroyed on unmount.
+ *   - Unlinked models are owned by application code; you are responsible for lifecycle.
+ *
+ * LINKED MODEL BEHAVIOR
+ * Linked models:
+ * - expose observable {@link componentProps} (shallow-observed per prop)
+ * - can acquire ancestor models via {@link lookupModel} / `@lookup`
+ * - receive {@link onLinked} during the *first render* of the linked component
+ * - receive {@link afterLinked} after the first render (via React effect)
+ * - are auto-loaded on mount via {@link loadAsync} (if load support is enabled)
+ * - register for subsequent refreshes via the nearest {@link RefreshContextModel}
+ * - are destroyed when their linked component is unmounted
+ *
+ * MANAGED LOADING / REFRESH
+ * - Implement {@link doLoadAsync} to opt into managed loading via {@link LoadSupport}.
+ * - When enabled, callers should use {@link loadAsync}/{@link refreshAsync}/{@link autoRefreshAsync}.
+ *   The {@link LoadSpec} instance passed to `doLoadAsync()` can be inspected to determine the
+ *   particular type of load that was triggered, as well as to determine if a newer load has already
+ *   been triggered via {@link LoadSpec.isStale} and {@link LoadSpec.isObsolete}.
+ * - Other load state/metadata is available via {@link loadModel} and timestamps/exceptions accessors.
+ *
+ * INVARIANTS / ASSUMPTIONS
+ * - `makeObservable(this)` is called by this base constructor, registering observables declared
+ *    directly on `HoistModel`.
+ * - {@link lookupModel} is only valid for linked models, and only during/after {@link onLinked}.
+ *
+ * ERROR + LOADING BEHAVIOR
+ * - If {@link doLoadAsync} is not overridden, load support is not installed and loading APIs are no-ops.
+ * - If {@link doLoadAsync} is overridden, {@link LoadSupport} is installed automatically.
+ *
+ * PERFORMANCE NOTES
+ * - {@link componentProps} uses shallow equality; only reference changes to individual props notify observers.
+ *
+ * COMMON PITFALLS
+ * - Declaring new `@observable` properties in a subclass but failing to call `makeObservable(this)`
+ *   in the subclass constructor. MobX requires each concrete class introducing observables to
+ *   register them explicitly.
+ * - Calling {@link lookupModel} before the model is linked (create via {@link creates}/{@link useLocalModel},
+ *   and call during/after {@link onLinked}).
+ * - Overriding the constructor and forgetting to call `super()`.
+ * - Mutating `@observables` outside MobX actions.
+ *
+ * CANONICAL USAGE
+ * ```ts
+ * // Linked model backing a Hoist component
+ * class MyModel extends HoistModel {
+ *   @observable.ref data: SomeData = null;
+ *
+ *   constructor() {
+ *     super();
+ *     makeObservable(this);
+ *   }
+ *
+ *   override async doLoadAsync(loadSpec: LoadSpec) {
+ *     this.data = await api.loadSomeData(loadSpec);
+ *   }
+ *
+ *   override onLinked() {
+ *     const parent = this.lookupModel(ParentModel);
+ *     // safe to use parent/componentProps here
+ *   }
+ * }
+ *
+ * // In a Hoist component factory
+ * export const myView = hoistCmp.factory<MyModel>(({model}) => {
+ *   // render using model.data, call model.loadAsync(), etc.
+ * });
+ * ```
+ *
+ * SEE ALSO
+ * - {@link HoistBase}
+ * - {@link LoadSupport}
+ * - {@link LoadSpec}
+ * - {@link creates}
+ * - {@link useLocalModel}
+ */
+export declare abstract class HoistModel extends HoistBase implements Loadable {
+    /** Type for constructing an instance of this model */
+    config: unknown;
+    static get isHoistModel(): boolean;
+    get isHoistModel(): boolean;
+    _componentProps: DefaultHoistProps | null;
+    _modelLookup: any;
+    _created: number;
+    constructor();
+    /**
+     * Provides optional support for Hoist's approach to managed loading.
+     *
+     * Applications will not typically need to access this object directly. If a subclass
+     * declares a concrete implementation of the `doLoadAsync()` template method, an instance of
+     * `LoadSupport` will automatically be created and installed to support the extensions below.
+     *
+     * See the class-level comments above for additional details.
+     */
+    loadSupport: LoadSupport;
+    get loadObserver(): TaskObserver;
+    get loadModel(): TaskObserver;
+    get lastLoadRequested(): Date;
+    get lastLoadCompleted(): Date;
+    get lastLoadException(): any;
+    refreshAsync(meta?: PlainObject): Promise<void>;
+    autoRefreshAsync(meta?: PlainObject): Promise<void>;
+    /**
+     * Template method for subclasses that want managed loading.
+     *
+     * Override this method to opt into Hoist's managed loading (i.e. installation of {@link LoadSupport}).
+     * Do not call this method directly - call {@link loadAsync}/{@link refreshAsync}/{@link autoRefreshAsync}.
+     */
+    doLoadAsync(loadSpec: LoadSpec): Promise<void>;
+    loadAsync(loadSpec?: LoadSpecConfig): Promise<void>;
+    get isLinked(): boolean;
+    /**
+     * React props on component linked to this model.
+     *
+     * Only available for linked models.
+     *
+     * Observability is based on a shallow computation for each prop (i.e. a reference
+     * change in any particular prop will trigger observers to be notified).
+     */
+    get componentProps(): DefaultHoistProps;
+    /**
+     * Called during first render of the component linked to this model.
+     *
+     * Only available for linked models.
+     *
+     * This method will be called when this model has been fully linked to the component
+     * hierarchy. Use this method for any work requiring the availability of lookup models or
+     * componentProps.  Note that this method is called *during* the initial rendering of the
+     * linked component.  See also `afterLinked` for a version of this method, that will be called
+     * after the first render is complete.
+     */
+    onLinked(): void;
+    /**
+     * Called after first render of the component linked to this model.
+     *
+     * Only available for linked models.
+     *
+     * This method is similar to `onLinked`, however it will be called after rendering has completed
+     * using the native react `useEffect` hook.
+     */
+    afterLinked(): void;
+    /**
+     * Lookup an ancestor model in the context hierarchy.
+     *
+     * Only available for linked models.
+     *
+     * @param selector - type of model to lookup.
+     * @returns model, or null if no matching model found.
+     */
+    lookupModel<T extends HoistModel>(selector: ModelSelector<T>): T | null;
+    /** @internal - called by Hoist to keep {@link componentProps} in sync for linked models. */
+    setComponentProps(newProps: DefaultHoistProps | null): void;
+    /**
+     * @internal
+     * Selector matching used by Hoist model lookup.
+     *
+     * Supported selectors include:
+     * - a HoistModel class reference
+     * - a predicate function `(model) => selector`
+     * - `true` (match any)
+     * - `'*'` (match any if `acceptWildcard` is true)
+     * - a class name string
+     */
+    matchesSelector(selector: ModelSelector, acceptWildcard?: boolean): boolean;
+    destroy(): void;
+}
+export type HoistModelClass<T extends HoistModel> = Class<T> | {
+    prototype: Pick<T, keyof T>;
+};

package/build/types/core/model/Hooks.d.ts

@@ -0,0 +1,28 @@
+import { HoistModel, HoistModelClass, ModelSelector, ModelLookup } from './';
+/**
+ * Hook to allow a component to access a HoistModel provided in context by an ancestor component.
+ * @param selector - selector to identify the model to be returned.
+ * @returns model or null if no matching model found.
+ */
+export declare function useContextModel<T extends HoistModel>(selector?: ModelSelector<T>): T;
+/**
+ * Create a new model that will be maintained for lifetime of the component and destroyed when the
+ * component is unmounted.
+ * @param spec - class of HoistModel to create, or a function returning one.
+ */
+export declare function useLocalModel<T extends HoistModel>(spec?: HoistModelClass<T> | (() => T)): T;
+/**
+ * Integrate a HoistModel owned by a component into the component's lifecycle, enabling support for
+ * both the Loading lifecycle and destruction. No-op, if model is null.
+ * @internal
+ */
+export declare function useModelLinker(model: HoistModel, modelLookup: ModelLookup, props: object): void;
+/**
+ * Default Context for useLocalModel.
+ * Set by HoistComponent during render to minimize app boilerplate required.
+ * @internal
+ */
+export declare const localModelContext: {
+    modelLookup: any;
+    props: any;
+};

package/build/types/core/model/ManagedRefreshContextModel.d.ts

@@ -0,0 +1,23 @@
+import { Loadable, LoadSpec } from '../load';
+import { RefreshContextModel } from './';
+import { RefreshMode } from '../';
+export type ManagedRefreshTarget = Loadable & {
+    isActive: boolean;
+    refreshMode: RefreshMode;
+};
+/**
+ * A refresh context model that consults a model's RefreshMode and active state to manage
+ * refreshes of its target models.
+ *
+ * The associated Loadable must have both:
+ *  a) An observable `isActive` property, that returns a boolean value.
+ *  b) A `refreshMode` property, that returns a RefreshMode enum value.
+ */
+export declare class ManagedRefreshContextModel extends RefreshContextModel {
+    xhImpl: boolean;
+    model: ManagedRefreshTarget;
+    refreshPending: boolean;
+    constructor(model: ManagedRefreshTarget);
+    doLoadAsync(loadSpec: LoadSpec): Promise<void>;
+    noteActiveChanged(isActive: boolean): void;
+}

package/build/types/core/model/ModelLookup.d.ts

@@ -0,0 +1,26 @@
+import { ModelSelector, HoistModel, ModelPublishMode } from './..';
+/**
+ * Support for making models available to components via React context.
+ *
+ * Not created directly by applications. Components specify how/if they publish/source their
+ * models from context via the `model` config option passed into the `hoistCmp()` factory.
+ * Hoist will in turn create and manage instances of this class to power those links.
+ *
+ * @internal
+ */
+export declare class ModelLookup {
+    model: HoistModel;
+    parent: ModelLookup;
+    publishMode: ModelPublishMode;
+    constructor(model: HoistModel, parent: ModelLookup, publishMode: ModelPublishMode);
+    /**
+     * Lookup a model in the context hierarchy
+     * @returns model, or null if no matching model found.
+     */
+    lookupModel(selector: ModelSelector): HoistModel;
+}
+/**
+ * Context used to publish a ModelLookup
+ */
+export declare const ModelLookupContext: import("react").Context<any>;
+export declare const modelLookupContextProvider: import("./..").ElementFactory<import("react").ProviderProps<any>>;

package/build/types/core/model/ModelSelector.d.ts

@@ -0,0 +1,27 @@
+import { HoistModel, HoistModelClass } from './';
+/**
+ * Type for use in identifying a model or set of models.  May be one of:
+ *
+ *  - class (or superclass) to match
+ *  - `"*"` to accept any Model
+ *  - boolean
+ *  - function taking a model and returning any of the above.
+ */
+export type ModelSelector<T extends HoistModel = HoistModel> = HoistModelClass<T> | string | boolean | ((model: HoistModel) => ModelSelector<T>);
+/**
+ * Ensure an object is a ModelSelector, or throw.
+ */
+export declare function ensureIsSelector(s: any): void;
+/**
+ * Format a ModelSelector for debugging purposes.
+ */
+export declare function formatSelector(selector: ModelSelector): string;
+/**
+ * Parameterized decorator to inject an instance of an ancestor model in the Model lookup
+ * hierarchy into this object.
+ *
+ * The decorated property will be filled only when the Model is linked to the Component hierarchy.
+ * Accessing properties decorated with `@lookup` should first be done in the
+ * {@link HoistModel.onLinked} or {@link HoistModel.afterLinked} handlers.
+ */
+export declare const lookup: any;

package/build/types/core/model/ModelSpec.d.ts

@@ -0,0 +1,30 @@
+import { CreatesSpec, UsesSpec, HoistModel } from './';
+/**
+ * Specification for model to be rendered by a HoistComponent.
+ * See {@link uses} and {@link creates} for standard factories that produce instances of this type.
+ * @internal
+ */
+export type ModelSpec<T extends HoistModel = HoistModel> = CreatesSpec<T> | UsesSpec<T>;
+/**
+ * Options for how a Model should be published to context.
+ */
+export declare const ModelPublishMode: Readonly<{
+    /**
+     * Model may be looked up from context using wildcard ('*') and model's top-level
+     * properties will also be searched for an appropriate model during lookup.  This is the
+     * default mode and typical mode used by application models.
+     */
+    DEFAULT: "default";
+    /**
+     *  Model may be looked up via context using an explicit selector, but NOT wildcard (*).
+     *  Model's internal properties will never be searched for matching models during lookup.
+     *  Useful for component or toolkit models that should be available for querying via context,
+     *  but are not intended to serve as default models or model providers.
+     */
+    LIMITED: "limited";
+    /**
+     * Do not publish the model to context.
+     */
+    NONE: "none";
+}>;
+export type ModelPublishMode = (typeof ModelPublishMode)[keyof typeof ModelPublishMode];

package/build/types/core/model/RefreshContextModel.d.ts

@@ -0,0 +1,45 @@
+import { HoistModel } from './';
+import { LoadSpec, Loadable } from '../load';
+/**
+ * A model to manage refreshing sections of the application, where "refreshing" refers to app-
+ * specific actions to load and display updated data. Calling `refreshAsync()` on this model will
+ * refresh all linked models underneath its corresponding component hierarchy.
+ *
+ * An instance of this class is provided by the framework as `XH.refreshContextModel` and
+ * installed at the top level of the application's component hierarchy, allowing for an "app-wide"
+ * refresh trigger via `XH.refreshAppAsync()`.
+ *
+ * Apps can create additional sub-contexts using a `RefreshContextView` paired with this model if
+ * they need to coordinate refreshes within a more targeted sections of their UI.
+ *
+ * HoistModels that enable LoadSupport are the primary targets for the refresh calls made by this
+ * class. Such models are auto-linked to the nearest RefreshContextModel when their associated
+ * component is mounted.
+ *
+ * (Note that models must be "owned" by their Component to be auto-linked in this way - meaning they
+ * must be internally created by the Component, either directly or from a config passed via props.)
+ *
+ * Note that TabContainer automatically establishes separate refresh contexts for its tabs and uses
+ * these to implement efficient refresh handling of inactive and not-yet-rendered tabs. See the
+ * `refreshMode` configs on `TabContainerModel` and `TabModel` for more information on this common
+ * use case.
+ *
+ * @see RootRefreshContextModel
+ * @see HoistModel.loadSupport
+ */
+export declare class RefreshContextModel extends HoistModel {
+    /** Targets registered for refresh. */
+    refreshTargets: Loadable[];
+    /**
+     * Register a target with this model for refreshing.
+     *
+     * Not typically called directly by applications.  Hoist will automatically register
+     * HoistModels that implement loading when their owning Component is first mounted.
+     */
+    register(target: Loadable): void;
+    /**
+     * Unregister a target from this model.
+     */
+    unregister(target: Loadable): void;
+    doLoadAsync(loadSpec: LoadSpec): Promise<void>;
+}

package/build/types/core/model/RootRefreshContextModel.d.ts

@@ -0,0 +1,14 @@
+import { LoadSpec } from '../load';
+import { RefreshContextModel } from './';
+/**
+ * Top-level refresh context model - triggers a full refresh of the app via a call to `loadAsync()`
+ * on the AppModel, followed by refreshes of any target models within the component hierarchy.
+ *
+ * An instance of this object is installed and linked by the framework as `XH.refreshContextModel`
+ * and should *not* be created or managed by application code.
+ *
+ * The `XH.refreshAppAsync()` convenience method is the recommended entry-point for apps to call.
+ */
+export declare class RootRefreshContextModel extends RefreshContextModel {
+    doLoadAsync(loadSpec: LoadSpec): Promise<void>;
+}