@xh/hoist 57.0.0 → 57.0.2

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

@@ -0,0 +1,358 @@
+import { HoistService, AppSpec, AppState, ExceptionHandlerOptions, ExceptionHandler, TrackOptions, SizingMode, HoistServiceClass, Theme, PlainObject, HoistException } from './';
+import { Store } from '@xh/hoist/data';
+import { AlertBannerService, AutoRefreshService, ChangelogService, ConfigService, EnvironmentService, FetchService, GridAutosizeService, GridExportService, IdentityService, IdleService, InspectorService, JsonBlobService, LocalStorageService, PrefService, TrackService, WebSocketService, FetchOptions } from '@xh/hoist/svc';
+import { AppContainerModel } from '../appcontainer/AppContainerModel';
+import { ToastModel } from '../appcontainer/ToastModel';
+import { BannerModel } from '../appcontainer/BannerModel';
+import '../styles/XH.scss';
+import { ModelSelector, HoistModel, RefreshContextModel } from './model';
+import { HoistAppModel, RouterModel, BannerSpec, ToastSpec, MessageSpec, HoistUser, TaskObserver } from './';
+/**
+ * Top-level Singleton model for Hoist. This is the main entry point for the API.
+ *
+ * Provides access to the built-in Hoist services, metadata about the application and environment,
+ * and convenience aliases to the most common framework operations. It also maintains key observable
+ * application state regarding dialogs, loading, and exceptions.
+ *
+ * Available via import as `XH` - also installed as `window.XH` for troubleshooting purposes.
+ */
+export declare class XHApi {
+    private _initCalled;
+    private _lastActivityMs;
+    private _uaParser;
+    constructor();
+    /** short internal code for the application. */
+    appCode: string;
+    /** user-facing display name for the app. See also `XH.clientAppName`. */
+    appName: string;
+    /** semVer or Snapshot version of the client build. */
+    appVersion: string;
+    /**
+     * optional identifier for the client build (e.g. a git commit hash or a
+     * build ID from a CI system). Varies depending on how builds are configured.
+     */
+    appBuild: string;
+    /** root URL context/path - prepended to all relative fetch requests. */
+    baseUrl: string;
+    /** true if app is running in a local development environment. */
+    isDevelopmentMode: boolean;
+    alertBannerService: AlertBannerService;
+    autoRefreshService: AutoRefreshService;
+    changelogService: ChangelogService;
+    configService: ConfigService;
+    environmentService: EnvironmentService;
+    fetchService: FetchService;
+    gridAutosizeService: GridAutosizeService;
+    gridExportService: GridExportService;
+    identityService: IdentityService;
+    idleService: IdleService;
+    inspectorService: InspectorService;
+    jsonBlobService: JsonBlobService;
+    localStorageService: LocalStorageService;
+    prefService: PrefService;
+    trackService: TrackService;
+    webSocketService: WebSocketService;
+    /** Get a reference to a singleton service by camel case name.*/
+    getService(name: string): HoistService;
+    /** Get a reference to a singleton service by full class. */
+    getService<T extends HoistService>(cls: HoistServiceClass<T>): T;
+    fetch(opts: FetchOptions): Promise<import("./").FetchResponse>;
+    fetchJson(opts: FetchOptions): Promise<any>;
+    /**
+     * Primary convenience alias for reading soft configuration values.
+     * @param key - identifier of the config to return.
+     * @param defaultVal - value to return if there is no client-side config with this key.
+     * @returns the soft-configured value.
+     */
+    getConf(key: string, defaultVal?: any): any;
+    /**
+     * Primary convenience alias for reading user preference values.
+     * @param key - identifier of the pref to return.
+     * @param defaultVal - value to return if there is no pref with this key.
+     * @returns the user's preference, or the data-driven default if pref not yet set by user.
+     */
+    getPref(key: string, defaultVal?: any): any;
+    /**
+     * Primary convenience alias for setting user preference values.
+     * @param key - identifier of the pref to set.
+     * @param val - the new value to persist for the current user.
+     */
+    setPref(key: string, val: any): void;
+    track(opts: string | TrackOptions): void;
+    getEnv(key: string): any;
+    getUser(): HoistUser;
+    getUsername(): string;
+    get isMobileApp(): boolean;
+    get clientAppCode(): string;
+    get clientAppName(): string;
+    get isPhone(): boolean;
+    get isTablet(): boolean;
+    get isDesktop(): boolean;
+    appContainerModel: AppContainerModel;
+    routerModel: RouterModel;
+    suspendData: any;
+    accessDeniedMessage: string;
+    exceptionHandler: ExceptionHandler;
+    /** current lifecycle state of the application. */
+    appState: AppState;
+    /** milliseconds timestamp at moment user activity / interaction was last detected. */
+    get lastActivityMs(): number;
+    /** true if application initialized and running (observable). */
+    get appIsRunning(): boolean;
+    /** The currently authenticated user. */
+    authUsername: string;
+    /** Root level application model. */
+    appModel: HoistAppModel;
+    /** Specifications for this application, provided in call to `XH.renderApp()`. */
+    appSpec: AppSpec;
+    /** Main entry point. Initialize and render application code. */
+    renderApp<T extends HoistAppModel>(appSpec: AppSpec<T>): void;
+    /**
+     * Install HoistServices on XH.
+     *
+     * @param serviceClasses - Classes extending HoistService
+     *
+     * This method will create, initialize, and install the services classes listed on XH.
+     * All services will be initialized concurrently. To guarantee execution order of service
+     * initialization, make multiple calls to this method with await.
+     *
+     * Applications must choose a unique name of the form xxxService to avoid naming collisions.
+     * If naming collisions are detected, an error will be thrown.
+     */
+    installServicesAsync(...serviceClasses: HoistServiceClass[]): Promise<void>;
+    /**
+     * Transition the application state.
+     * @internal
+     */
+    setAppState(appState: AppState): void;
+    /**
+     * Trigger a full reload of the current application.
+     *
+     * This method will reload the entire application document in the browser.
+     * To simply trigger a refresh of the loadable content within the application,
+     * see {@link XH.refreshAppAsync} instead.
+     */
+    reloadApp(): void;
+    /**
+     * Refresh the current application.
+     *
+     * This method will do an "in-place" refresh of the loadable content as defined by the app.
+     * It is a short-cut to `XH.refreshContextModel.refreshAsync()`.
+     *
+     * To trigger a full reload of the application document in the browser (including code)
+     * see {@link XH.reloadApp} instead.
+     */
+    refreshAppAsync(): Promise<void>;
+    /**
+     * Tracks globally loading promises.
+     * Apps should link any async operations that should mask the entire viewport to this model.
+     */
+    get appLoadModel(): TaskObserver;
+    /**
+     * The global RefreshContextModel for this application.
+     */
+    get refreshContextModel(): RefreshContextModel;
+    /** Toggle the theme between light and dark variants. */
+    toggleTheme(): void;
+    /**
+     * Sets the theme directly (useful for custom app option controls).
+     */
+    setTheme(value: Theme, persist?: boolean): void;
+    /** Is the app currently rendering in dark theme? */
+    get darkTheme(): boolean;
+    setSizingMode(sizingMode: SizingMode): void;
+    get sizingMode(): SizingMode;
+    /** Current viewport width / height. (observable) */
+    get viewportSize(): {
+        width: number;
+        height: number;
+    };
+    /** Is the viewport in portrait orientation? (observable) */
+    get isPortrait(): boolean;
+    /** Is the viewport in landscape orientation? (observable) */
+    get isLandscape(): boolean;
+    /**
+     * Underlying Router5 Router object implementing the routing state.
+     * Applications should use this property to directly access the Router5 API.
+     */
+    get router(): import("router5").Router;
+    /**
+     * The current routing state as an observable property.
+     * @see RoutingManager.currentState
+     */
+    get routerState(): import("router5").State;
+    /** Route the app - shortcut to this.router.navigate. */
+    navigate(...args: any[]): import("router5/types/types/base").CancelFn;
+    /** Add a routeName to the current route, preserving params */
+    appendRoute(routeName: string, newParams?: PlainObject): import("router5/types/types/base").CancelFn;
+    /** Remove last routeName from the current route, preserving params */
+    popRoute(): import("router5/types/types/base").CancelFn;
+    /**
+     * Show a modal message dialog.
+     *
+     * Note that this method will autofocus the confirm button by default. To focus the cancel
+     * button instead (e.g. for confirming risky operations), applications should specify a
+     * `cancelProps` argument of the following form `cancelProps: {..., autoFocus: true}`.
+     *
+     * @returns true if user confirms, false if user cancels. If an input is provided, the
+     * Promise will resolve to the input value if user confirms.
+     */
+    message<T = unknown>(config: MessageSpec): Promise<T | boolean>;
+    /**
+     * Show a modal 'alert' dialog with message and default 'OK' button.
+     * @returns true when user acknowledges alert.
+     */
+    alert(config: MessageSpec): Promise<boolean>;
+    /**
+     * Show a modal 'confirm' dialog with message and default 'OK'/'Cancel' buttons.
+     * @returns true if user confirms, false if user cancels.
+     */
+    confirm(config: MessageSpec): Promise<boolean>;
+    /**
+     * Show a modal 'prompt' dialog with a default TextInput, message and 'OK'/'Cancel' buttons.
+     *
+     * The default TextInput comes with props set for:
+     *   1. autoFocus = true
+     *   2. selectOnFocus = true (desktop only)
+     *   3. onKeyDown handler to confirm on <enter> (same as clicking 'OK') (desktop only)
+     * Applications may also provide a custom HoistInput, in which all props must be set.
+     *
+     * @returns value of input if user confirms, false if user cancels.
+     */
+    prompt<T = unknown>(config: MessageSpec): Promise<T | false>;
+    /**
+     * Show a non-modal "toast" notification that appears and then automatically dismisses.
+     * @returns model representing the toast. May be used for programmatic dismissal.
+     */
+    toast(config: ToastSpec | string): ToastModel;
+    /**
+     * Show a toast with default intent and icon indicating success.
+     */
+    successToast(config: ToastSpec | string): ToastModel;
+    /**
+     * Show a toast with default intent and icon indicating a warning.
+     */
+    warningToast(config: ToastSpec | string): ToastModel;
+    /**
+     * Show a toast with intent and icon indicating a serious issue.
+     */
+    dangerToast(config: ToastSpec | string): ToastModel;
+    /**
+     * Show a Banner across the top of the viewport. Banners are unique by their
+     * category prop - showing a new banner with an existing category will replace it.
+     */
+    showBanner(spec: BannerSpec | string): BannerModel;
+    /**
+     * Hide banner by category name.
+     */
+    hideBanner(category?: string): void;
+    /**
+     * Handle an exception. This method is an alias for {@link ExceptionHandler.handleException}.
+     *
+     * This method may be called by applications in order to provide logging, reporting, and
+     * display of exceptions. It is typically called directly in catch() blocks.
+     *
+     * See also Promise.catchDefault(). That method will delegate its arguments to this method
+     * and provides a more convenient interface for catching exceptions in Promise chains.
+     *
+     * @param exception - thrown object, will be coerced into a HoistException by Exception.create().
+     * @param options - provides further control over how the exception is shown and/or logged.
+     */
+    handleException(exception: unknown, options?: ExceptionHandlerOptions): void;
+    /**
+     * Show an exception. This method is an alias for {@link ExceptionHandler.showException}.
+     *
+     * Intended to be used for the deferred / user-initiated showing of exceptions that have
+     * already been appropriately logged. Applications should typically prefer `handleException`.
+     *
+     * @param exception - thrown object, will be coerced into a HoistException by Exception.create().
+     * @param options - provides further control over how the exception is shown and/or logged.
+     */
+    showException(exception: unknown, options?: ExceptionHandlerOptions): void;
+    /**
+     * Create a new exception - See {@link Exception}.
+     *
+     * @param src - If a native JS Error, it will be enhanced into a HoistException and returned.
+     *      If a plain object, all properties will be set on a new HoistException.
+     *      Other inputs will be treated as the `message` of a new HoistException.
+     */
+    exception(src: unknown): HoistException;
+    /** Show "about this app" dialog, powered by {@link EnvironmentService}. */
+    showAboutDialog(): void;
+    /** Show a "release notes" dialog, powered by {@link ChangelogService}. */
+    showChangelog(): void;
+    /**
+     * Show a dialog to elicit feedback from the user.
+     * @param message - optional message to preset within the feedback dialog.
+     */
+    showFeedbackDialog({ message }?: {
+        message?: string;
+    }): void;
+    /** Show the impersonation bar to allow switching users. */
+    showImpersonationBar(): void;
+    /** Show a dialog to allow the user to view and set app options. */
+    showOptionsDialog(): void;
+    /**
+     * Return a collection of Models currently 'active' in this application.
+     *
+     * This will include all models that have not had `destroy()`
+     * called on them.  Models will be returned in creation order.
+     */
+    getActiveModels(selector?: ModelSelector): HoistModel[];
+    /** All services registered with this application. */
+    getServices(): HoistService[];
+    /** All Stores registered with this application. */
+    getStores(): Store[];
+    /**
+     * Resets user preferences and any persistent local application state, then reloads the app.
+     */
+    restoreDefaultsAsync(): Promise<void>;
+    /**
+     * Helper method to destroy resources safely (e.g. child HoistModels). Will quietly skip args
+     * that are null / undefined or that do not implement destroy().
+     *
+     * @param args - objects to be destroyed. If any argument is an array,
+     *      each element in the array will be destroyed (this is *not* done recursively);.
+     */
+    safeDestroy(...args: (any | any[])[]): void;
+    /**
+     * Generate an ID string, unique within this run of the client application and suitable
+     * for local-to-client uses such as auto-generated store record identifiers.
+     *
+     * Deliberately *not* intended to be globally unique, suitable for reuse, or to appear as such.
+     */
+    genId(): string;
+    /**
+     * Called when application container first mounted in order to trigger initial
+     * authentication and initialization of framework and application.
+     * @internal
+     */
+    initAsync(): Promise<void>;
+    /**
+     * Complete initialization. Called after the client has confirmed that the user is generally
+     * authenticated and known to the server (regardless of application roles at this point).
+     * @internal
+     */
+    completeInitAsync(): Promise<void>;
+    /**
+     * Suspend all app activity and display, including timers and web sockets.
+     *
+     * Suspension is a terminal state, requiring user to reload the app.
+     * Used for idling, forced version upgrades, and ad-hoc killing of problematic clients.
+     * @internal
+     */
+    suspendApp(suspendData: any): void;
+    private checkAccess;
+    private setDocTitle;
+    private getAuthStatusFromServerAsync;
+    private startRouter;
+    private startOptionsDialog;
+    private get acm();
+    private bindInitSequenceToAppLoadModel;
+    private trackLoad;
+    private createActivityListeners;
+    private get uaParser();
+    private parseAppSpec;
+}
+/** app-wide singleton instance. */
+export declare const XH: XHApi;

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

@@ -0,0 +1,55 @@
+import { ReactNode, ReactElement, ForwardedRef, Key } from 'react';
+import { PlainObject, Some, Thunkable } from './types/Types';
+/**
+ * Alternative format for specifying React Elements in render functions. This type is designed to
+ * provide a well-formatted, declarative, native javascript approach to configuring Elements and
+ * their children. It serves as an alternative to JSX and is especially useful for code-heavy
+ * element trees. (For element trees with a significant amount of hypertext, JSX could be a better
+ * choice.)
+ *
+ * The core enhancement to this format over jsx is it expects child elements and props to be
+ * specified in a single bundle, with children placed within an `item` or `items` key. This allows
+ * developers to write declarative, multi-level element trees in a concise yet highly-readable
+ * style.  An additional feature is the minor-but-useful support for an `omit` property, which
+ * allows element subtrees to be declaratively excluded from rendering if a given condition is met.
+ * This avoids the need for the common, but clunky React practice of wrapping elements in ternary
+ * statements to accomplish conditional rendering.
+ *
+ * @see {@link createElement} - That function is a thin-wrapper over `React.createChildren` that
+ * consumes this format.
+ *
+ * Finally, note that if a React Component has its own props of `item`, `items`, or `omit`, the
+ * props may be specified in this object with a `$` prefix (e.g. `$item`) to avoid conflicting
+ * with this API.  The '$' will be stripped from the prop name before passing it along to the
+ * underlying component.
+ */
+export type ElementSpec<P extends PlainObject> = P & {
+    /** Child Element(s). Equivalent provided as Rest Arguments to React.createElement.*/
+    items?: Some<ReactNode>;
+    /**  Equivalent to `items`, offered for code clarity when only one child is needed. */
+    item?: Some<ReactNode>;
+    /** True to exclude the Element. */
+    omit?: Thunkable<boolean>;
+    /** React Ref for this component. */
+    ref?: ForwardedRef<any>;
+    /** React key for this component. */
+    key?: Key;
+    $items?: any;
+    $item?: any;
+    $omit?: any;
+};
+export type ElementFactory<P = any> = ((...args: ReactNode[]) => ReactElement<P, any>) & ((arg: ElementSpec<P>) => ReactElement<P, any>);
+/**
+ * Create a React Element from a Component type and an ElementSpec.
+ *
+ * This function is a thin-wrapper over `React.createChildren` that
+ * consumes the ElementSpec format.
+ *
+ * @param type - React Component or string representing an HTML element.
+ * @param spec - element spec.
+ */
+export declare function createElement<P = any>(type: any, spec: ElementSpec<P>): ReactElement<P, any>;
+/**
+ *  Create a factory function that can create a ReactElement from an ElementSpec.
+ */
+export declare function elementFactory<P = any>(type: any): ElementFactory<P>;

package/build/types/core/enums/RefreshMode.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Options for how content should be refreshed via their built-in RefreshContextModel when they
+ * receive a refresh request while inactive/hidden or are (re)activated by their parent container.
+ * Used by {@link TabContainerModel} and {@link DashContainerModel}.
+ */
+export declare const RefreshMode: Readonly<{
+    /** Always refresh a tab when requested, even if it is inactive (hidden). */
+    ALWAYS: "always";
+    /** Note a refresh request for an inactive tab and run refresh if/when tab is next activated. */
+    ON_SHOW_LAZY: "onShowLazy";
+    /** Always refresh when tab is activated, regardless of whether or not refresh was requested. */
+    ON_SHOW_ALWAYS: "onShowAlways";
+    /** Ignore refresh requests entirely when tab is inactive. Do not auto-refresh when reactivated. */
+    SKIP_HIDDEN: "skipHidden";
+}>;
+export type RefreshMode = (typeof RefreshMode)[keyof typeof RefreshMode];

package/build/types/core/enums/RenderMode.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Options for how contents should be rendered by their parent container.
+ * Used by {@link TabContainerModel}, {@link DashContainerModel}, and {@link PanelModel}.
+ */
+export declare const RenderMode: Readonly<{
+    /** Always render contents when the parent container is rendered, even if inactive. */
+    ALWAYS: "always";
+    /** Render contents lazily or "just in time" - only if/when the content is first activated. */
+    LAZY: "lazy";
+    /** Render lazily, and actively unmount the contents if/when de-activated. */
+    UNMOUNT_ON_HIDE: "unmountOnHide";
+}>;
+export type RenderMode = (typeof RenderMode)[keyof typeof RenderMode];

package/build/types/core/enums/SizingMode.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Standardized sizes used by Grid - affects padding, row heights, font sizes, etc.
+ */
+export declare const SizingMode: Readonly<{
+    TINY: "tiny";
+    COMPACT: "compact";
+    STANDARD: "standard";
+    LARGE: "large";
+}>;
+export type SizingMode = (typeof SizingMode)[keyof typeof SizingMode];

package/build/types/core/exception/Exception.d.ts

@@ -0,0 +1,63 @@
+import { FetchOptions } from '@xh/hoist/svc';
+import { FetchResponse } from '../';
+import { FetchException, HoistException, TimeoutException, TimeoutExceptionConfig } from './Types';
+/**
+ * Standardized Exception/Error objects.
+ *
+ * The main entry point for this class is the create() method.
+ * Applications can use this method to create various generic runtime exceptions.
+ * @see ExceptionHandler.handleException
+ */
+export declare class Exception {
+    /**
+     * Create and return a HoistException
+     *
+     * See {@link XH.exception} - an alias for this factory off of `XH`.
+     *
+     * @param src - If a native JS Error, it will be enhanced into a HoistException and returned.
+     *      If a plain object, all properties will be set on a new HoistException.
+     *      Other inputs will be treated as the `message` of a new HoistException.
+     */
+    static create(src: unknown): HoistException;
+    /**
+     * Create an Error for when an operation (e.g. a Promise) times out.
+     */
+    static timeout(config: TimeoutExceptionConfig): TimeoutException;
+    /**
+     * Create an Error to throw when a fetch call returns a !ok response.
+     * @param fetchOptions - original options passed to FetchService.
+     * @param fetchResponse - return value of native fetch, as enhanced by FetchService.
+     */
+    static fetchError(fetchOptions: FetchOptions, fetchResponse: FetchResponse): FetchException;
+    /**
+     * Create an Error to throw when a fetchJson call encounters a SyntaxError.
+     * @param fetchOptions - original options passed to FetchService.
+     * @param cause - object thrown by native {@link response.json}.
+     */
+    static fetchJsonParseError(fetchOptions: FetchOptions, cause: any): FetchException;
+    /**
+     * Create an Error to throw when a fetch call is aborted.
+     * @param fetchOptions - original options passed to FetchService.
+     * @param cause - object thrown by native fetch
+     */
+    static fetchAborted(fetchOptions: FetchOptions, cause: any): FetchException;
+    /**
+     * Create an Error to throw when a fetch call times out.
+     * @param fetchOptions - original options the app passed when calling FetchService.
+     * @param cause - underlying timeout exception
+     * @param message - optional custom message
+     *
+     * @returns an exception that is both a TimeoutException, and a FetchException, with the
+     *      underlying TimeoutException as its cause.
+     */
+    static fetchTimeout(fetchOptions: FetchOptions, cause: TimeoutException, message: string): FetchException & TimeoutException;
+    /**
+     * Create an Error for when the server called by fetch does not respond
+     * @param fetchOptions - original options the app passed to FetchService.fetch
+     * @param cause - object thrown by native fetch
+     */
+    static serverUnavailable(fetchOptions: FetchOptions, cause: any): FetchException;
+    private static createFetchException;
+    private static createInternal;
+}
+export declare function isHoistException(src: unknown): src is HoistException;

package/build/types/core/exception/ExceptionHandler.d.ts

@@ -0,0 +1,121 @@
+import { HoistException } from '../';
+export interface ExceptionHandlerOptions {
+    /** Text (ideally user-friendly) describing the error. */
+    message?: string;
+    /** Title for an alert dialog, if shown. */
+    title?: string;
+    /**
+     * Configure modal alert and logging to indicate that this is an unexpected error. Default
+     * true for most exceptions, false for those marked as `isRoutine`.
+     */
+    showAsError?: boolean;
+    /**
+     * Send the exception to the server to be stored for review in the Hoist Admin Console?
+     * Default true when `showAsError` is true, excepting 'isAutoRefresh' fetch exceptions.
+     */
+    logOnServer?: boolean;
+    /**
+     * Display an alert dialog to the user.
+     * Default true, excepting 'isAutoRefresh' and 'isFetchAborted' exceptions.
+     */
+    showAlert?: boolean;
+    /**
+     * If `showAlert`, which type of alert to display. Defaults to ExceptionHandler.ALERT_TYPE.
+     */
+    alertType?: 'dialog' | 'toast';
+    /**
+     * Force user to fully refresh the app in order to dismiss - default false, excepting
+     * session-related exceptions.
+     */
+    requireReload?: boolean;
+    /**
+     * A list of parameters that should be hidden from the exception log and alert.
+     */
+    hideParams?: string[];
+}
+export interface ExceptionHandlerLoggingOptions {
+    /** Exception to be logged. */
+    exception: HoistException;
+    /** True if the user was shown a modal alert. */
+    userAlerted: boolean;
+    /**
+     * Optional user-provided message detailing what they did to trigger the error, or any other
+     * details the user chooses to provide.
+     */
+    userMessage?: string;
+}
+/**
+ * Provides Centralized Exception Handling for Hoist Application.
+ * Manages the logging and display of exceptions.
+ */
+export declare class ExceptionHandler {
+    #private;
+    /**
+     * Property paths within error details JSON to replace with '******'
+     */
+    static REDACT_PATHS: string[];
+    /**
+     * Default type of alert to use to display exceptions with `showAlert`.
+     */
+    static ALERT_TYPE: 'dialog' | 'toast';
+    /**
+     * Default props provided to toast, when alert type is 'toast'
+     */
+    static TOAST_PROPS: object;
+    constructor();
+    /**
+     * Called by Hoist internally to handle exceptions, with built-in support for parsing certain
+     * Hoist-specific exception options, displaying an appropriate error dialog to users, and
+     * logging back to the server for stateful error tracking in the Admin Console.
+     *
+     * Typical application entry points to this method are the {@link XH.handleException} alias and
+     * {@link Promise.catchDefault}.
+     *
+     * This handler provides the most value with HoistExceptions created by {@link Exception.create}.
+     * Hoist automatically creates such exceptions in most instances, most notably in FetchService,
+     * which generates de-serialized versions of server exceptions. See {@link XH.exception} for a
+     * convenient way to create these enhanced exceptions in application code.
+     *
+     * This handler will respect an `isRoutine` flag set on HoistExceptions that can be thrown in
+     * the course of "normal" app operation and do not represent unexpected errors. When true, this
+     * handler will apply defaults that avoid overly alarming the user and skip server-side logging.
+     *
+     * @param exception - thrown object, will be coerced into a HoistException by Exception.create().
+     * @param options - provides further control over how the exception is shown and/or logged.
+     */
+    handleException(exception: unknown, options?: ExceptionHandlerOptions): void;
+    /**
+     * Show an exception in an error dialog, without logging the error to the server or console.
+     * Intended to be used for the deferred / user-initiated showing of exceptions that have
+     * already been appropriately logged. Applications should typically prefer `handleException`.
+     *
+     * @param exception - thrown object, will be coerced into a HoistException by Exception.create().
+     * @param options - provides further control over how the exception is shown and/or logged.
+     */
+    showException(exception: unknown, options?: ExceptionHandlerOptions): void;
+    /**
+     * Create a server-side exception entry. Client metadata will be set automatically.
+     *
+     * This method will swallow any exceptions thrown in the course of its own execution, failing
+     * silently to avoid masking or compounding the actual exception to be handled.
+     *
+     * Note the App version is POSTed to ensure we capture the version of the client the user is
+     * actually running when the exception was generated.
+     *
+     * @returns true if message was successfully sent to server.
+     */
+    logOnServerAsync(options: ExceptionHandlerLoggingOptions): Promise<boolean>;
+    /**
+     * Serialize an error object safely for submission to server, or user display.
+     * This method will avoid circular references and will trim the depth of the object.
+     */
+    stringifyErrorSafely(exception: HoistException): string;
+    private parseArgs;
+    private hideParams;
+    private logException;
+    private parseOptions;
+    private sessionMismatch;
+    private sessionExpired;
+    private cleanStack;
+    private cloneAndTrim;
+}