@xh/hoist 57.0.0 → 57.0.2

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

@@ -0,0 +1,109 @@
+import { HoistProps, DefaultHoistProps, ElementFactory } from './';
+import { ModelSpec, HoistModel } from './model';
+import { ForwardedRef, FC, ReactNode } from 'react';
+/**
+ * Type representing props passed to a HoistComponent's render function.
+ *
+ * This type removes from its base type several props that are used by HoistComponent itself and
+ * not provided to the render function.
+ */
+export type RenderPropsOf<P extends HoistProps> = P & {
+    /** Pre-processed by HoistComponent internals into a mounted model.  Never passed to render. */
+    modelConfig: never;
+    /** Pre-processed by HoistComponent internals and attached to model.  Never passed to render. */
+    modelRef: never;
+};
+/**
+ * Configuration for creating a Component.  May be specified either as a render function,
+ * or an object containing a render function and associated metadata.
+ */
+export type ComponentConfig<P extends HoistProps> = ((props: RenderPropsOf<P>, ref?: ForwardedRef<any>) => ReactNode) | {
+    /** Render function defining the component. */
+    render(props: RenderPropsOf<P>, ref?: ForwardedRef<any>): ReactNode;
+    /**
+     * Spec defining the model to be rendered by this component.
+     * Specify as false for components that don't require a primary model. Otherwise, set to the
+     * return of {@link uses} or {@link creates} - these factory functions will create a spec for
+     * either externally-provided or internally-created models. Defaults to `uses('*')`.
+     */
+    model?: ModelSpec<P['model']> | false;
+    /**
+     * Base CSS class for this component. Will be combined with any className
+     * in props, with the combined string passed into render as a prop.
+     */
+    className?: string;
+    /** Component name for debugging/inspection. */
+    displayName?: string;
+    /**
+     * True (default) to wrap component in a call to `React.memo()`.
+     * Components that are known to be unable to make effective use of memo (e.g. container
+     * components) may set this to `false`. Not typically set by application code.
+     */
+    memo?: boolean;
+    /**
+     *  True (default) to enable MobX-powered reactivity via the
+     * `observer()` HOC from mobx-react. Components that are known to dereference no observable
+     *  state may set this to `false`, but this is not typically done by application code.
+     */
+    observer?: boolean;
+};
+/**
+ * Hoist utility for defining functional components. This is the primary method for creating
+ * components for use in Hoist applications. Accepts either a render function (directly) or a
+ * configuration object to specify that function and additional options, as described below.
+ *
+ * The primary additional config option is `model`. It specifies how a backing HoistModel will be
+ * provided to / created by this component and if the component should publish its model to any
+ * subcomponents via context.
+ *
+ * By default, this utility wraps the returned component in the MobX 'observer' HOC, enabling
+ * MobX-powered reactivity and auto-re-rendering of observable properties read from models and
+ * any other sources of observable state.
+ *
+ * Forward refs {@link https://reactjs.org/docs/forwarding-refs.html} are supported by specifying a
+ * render function that accepts two arguments. In that case, the second arg will be considered a
+ * ref, and this utility will apply `React.forwardRef` as required.
+ *
+ * @param config - specification object, or a render function defining the component.
+ * @returns a functional React Component for use within Hoist apps.
+ *
+ * @see hoistCmp - a shorthand alias to this function.
+ *
+ * This function also has several related functions
+ *
+ *   - `hoistCmp.factory` - return an elementFactory for a newly defined Component.
+ *           instead of the Component itself.
+ *
+ *   - `hoistCmp.withFactory` - return a 2-element list containing both the newly
+ *          defined Component and an elementFactory for it.
+ */
+export declare function hoistCmp<M extends HoistModel>(config: ComponentConfig<DefaultHoistProps<M>>): FC<DefaultHoistProps<M>>;
+export declare function hoistCmp<P extends HoistProps>(config: ComponentConfig<P>): FC<P>;
+export declare namespace hoistCmp {
+    var factory: typeof hoistCmpFactory;
+    var withFactory: typeof hoistCmpWithFactory;
+}
+/**
+ * Alias for {@link hoistCmp}.
+ */
+export declare const hoistComponent: typeof hoistCmp;
+/**
+ * Return an element factory for a newly defined component.
+ *
+ * Most typically used by application, this provides a simple element factory.
+ */
+export declare function hoistCmpFactory<M extends HoistModel>(config: ComponentConfig<DefaultHoistProps<M>>): ElementFactory<DefaultHoistProps<M>>;
+export declare function hoistCmpFactory<P extends HoistProps>(config: ComponentConfig<P>): ElementFactory<P>;
+/**
+ * Returns a 2-element list containing both the newly defined Component and an elementFactory for it.
+ * Used by Hoist for exporting Component artifacts that support both JSX and elementFactory based development.
+ *
+ * Not typically used by applications.
+ */
+export declare function hoistCmpWithFactory<M extends HoistModel>(config: ComponentConfig<DefaultHoistProps<M>>): [FC<DefaultHoistProps<M>>, ElementFactory<DefaultHoistProps<M>>];
+export declare function hoistCmpWithFactory<P extends HoistProps>(config: ComponentConfig<P>): [FC<P>, ElementFactory<P>];
+/**
+ * Component to render certain errors caught within hoistComponent.
+ * @internal
+ */
+export declare function setCmpErrorDisplay(ef: ElementFactory): void;

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

@@ -0,0 +1,91 @@
+import { HoistModel } from '@xh/hoist/core/model';
+import { CSSProperties, HTMLAttributes, ReactNode, Ref } from 'react';
+/**
+ * Props interface for Hoist Components.
+ *
+ * This interface brings in additional properties that are added to the props
+ * collection by HoistComponent.
+ */
+export interface HoistProps<M extends HoistModel = HoistModel> {
+    /**
+     * Associated HoistModel for this Component.  Depending on the component, may be specified as
+     * an instance of a HoistModel, or a configuration object to create one, or left undefined.
+     * HoistComponent will resolve (i.e. lookup in context or create if needed) a concrete Model
+     * instance and provide it to the Render method of the component.
+     */
+    model?: M;
+    /**
+     * Used for specifying the *configuration* of a model to be created by Hoist for this component
+     * when first mounted.  Should be used only on a component that specifies the 'uses()' directive
+     * with the `createFromConfig` set as true. See the `uses()` directive for more information.
+     */
+    modelConfig?: M extends null ? never : M['config'];
+    /**
+     * Used for gaining a reference to the model of a HoistComponent.
+     */
+    modelRef?: M extends null ? never : Ref<M>;
+    /**
+     * ClassName for the component.  Includes the classname as provided in props, enhanced with
+     * any base class name provided by the component definition itself.
+     */
+    className?: string;
+    /** React children. */
+    children?: ReactNode;
+}
+/**
+ * A version of Hoist props that allows dynamic keys/properties.   This is the interface that
+ * Hoist uses for components that do not explicitly specify the type of props they expect.
+ *
+ * This behavior is useful for file or package-local components that do not require an explicit
+ * props API.
+ */
+export interface DefaultHoistProps<M extends HoistModel = HoistModel> extends HoistProps<M> {
+    [x: string]: any;
+}
+/**
+ * Props for Components that support standard Layout attributes
+ *
+ * Most component will typically separate these props out and pass them along to another component
+ * which also supports this interface.  Eventually, they should be passed to a Box class.
+ */
+export interface BoxProps extends LayoutProps, Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'contextMenu'> {
+}
+export interface StyleProps {
+    style?: CSSProperties;
+}
+export interface LayoutProps {
+    margin?: string | number;
+    marginTop?: string | number;
+    marginRight?: string | number;
+    marginBottom?: string | number;
+    marginLeft?: string | number;
+    padding?: string | number;
+    paddingTop?: string | number;
+    paddingRight?: string | number;
+    paddingBottom?: string | number;
+    paddingLeft?: string | number;
+    height?: string | number;
+    minHeight?: string | number;
+    maxHeight?: string | number;
+    width?: string | number;
+    minWidth?: string | number;
+    maxWidth?: string | number;
+    flex?: string | number;
+    flexBasis?: string | number;
+    flexDirection?: string | number;
+    flexGrow?: string | number;
+    flexShrink?: string | number;
+    flexWrap?: string | number;
+    alignItems?: string;
+    alignSelf?: string;
+    alignContent?: string;
+    justifyContent?: string;
+    overflow?: string;
+    overflowX?: string;
+    overflowY?: string;
+    textOverflow?: string;
+    top?: string | number;
+    left?: string | number;
+    position?: string;
+    display?: string;
+}

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

@@ -0,0 +1,56 @@
+import { HoistBase, LoadSupport, LoadSpec, Loadable, PlainObject } from './';
+/**
+ * Core superclass for Services in Hoist. Services are special classes used in both Hoist and
+ * application code as centralized points for managing app-wide state and loading / processing
+ * data from external APIs.
+ *
+ * Services are distinct from Models in that they are typically constructed and initialized within
+ * either `XH` (for Hoist-provided services) or within the `initAsync()` method of your primary
+ * `AppModel` - see {@link XH.installServicesAsync}. A single instance of each service is
+ * constructed and installed as a property on the `XH` singleton.
+ *
+ * (E.g. an app that defines and initializes a custom `TradeEntryService` class can access and use
+ * that instance as `XH.tradeEntryService`. This mirrors the pattern for singleton service
+ * injection used within the Grails server.)
+ *
+ * Services are most commonly used as engines within an application for loading, processing, and
+ * potentially caching data, although keep in mind their singleton nature when maintaining and
+ * updating state within your service. (E.g. if your service caches business objects and hands them
+ * out to callers, take care that those shared objects aren't modified by callers in unexpectedly
+ * shared ways.)
+ *
+ * Services extend `HoistBase` and can therefore leverage MobX-powered observables and reactions if
+ * so desired. And while components should typically source their state from backing models, they
+ * can also read and react to service state and call service APIs.
+ */
+export declare class HoistService extends HoistBase implements Loadable {
+    _created: number;
+    static get isHoistService(): boolean;
+    get isHoistService(): boolean;
+    constructor();
+    /**
+     * Called by framework or application to initialize before application startup.
+     * Throwing an exception from this method will typically block startup.
+     * Service writers should take care to stifle and manage all non-fatal exceptions.
+     */
+    initAsync(): Promise<void>;
+    /**
+     * 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.
+     */
+    loadSupport: LoadSupport;
+    get loadModel(): import("./TaskObserver").TaskObserver;
+    get lastLoadRequested(): Date;
+    get lastLoadCompleted(): Date;
+    get lastLoadException(): any;
+    refreshAsync(meta?: PlainObject): Promise<void>;
+    autoRefreshAsync(meta?: PlainObject): Promise<void>;
+    doLoadAsync(loadSpec: LoadSpec): Promise<void>;
+    loadAsync(loadSpec?: LoadSpec | Partial<LoadSpec>): Promise<void>;
+}
+export interface HoistServiceClass<T extends HoistService = HoistService> {
+    new (): T;
+}

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

@@ -0,0 +1,11 @@
+/// <reference types="react" />
+import { RefreshContextModel } from './model';
+/**
+ * Establishes an area of the application with an independent RefreshContextModel.
+ *
+ * The model established by this view will be refreshed by its parent context but may also be refreshed
+ * independently.
+ *
+ * @see RefreshContextModel
+ */
+export declare const RefreshContextView: import("react").FC<import("./HoistProps").DefaultHoistProps<RefreshContextModel>>, refreshContextView: import("./elem").ElementFactory<import("./HoistProps").DefaultHoistProps<RefreshContextModel>>;

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

@@ -0,0 +1,41 @@
+import { HoistModel } from './';
+import { Router, State } from 'router5';
+/**
+ * Top-level model for managing application routing in Hoist.
+ *
+ * This observable model uses Router5 (https://router5.js.org/) to manage the
+ * underlying routes, presenting them to the application as a set of MobX observables.
+ */
+export declare class RouterModel extends HoistModel {
+    /** Router5 state object representing the current state. */
+    currentState: State;
+    /** Underlying Router5 Router object implementing the routing state. */
+    router: Router;
+    /**
+     * Does the routing system already have a given route?
+     */
+    hasRoute(routeName: string): boolean;
+    /**
+     * Add routes to the router.
+     *
+     * @param routes - collection of router5 route spec.
+     *      This method supports an additional keyword 'omit' on each spec, in order to allow declarative
+     *      exclusion.  Otherwise these are Router5 configs to be passed directly to the Router5 API.
+     */
+    addRoutes(routes: object[]): void;
+    /**
+     * Add a routeName to the current route, preserving params
+     * @param routeName - the routeName to append
+     * @param newParams - additional params for this routeName to be merged with existing params.
+     */
+    appendRoute(routeName: string, newParams?: object): import("router5/types/types/base").CancelFn;
+    /**
+     * Remove last routeName from the current route, preserving params
+     */
+    popRoute(): import("router5/types/types/base").CancelFn;
+    constructor();
+    private setCurrentState;
+    private getRouteNames;
+    private createRouter;
+    private preprocessRoutes;
+}

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

@@ -0,0 +1,75 @@
+import { ReactNode } from 'react';
+/**
+ * Tracks the execution state of one or more asynchronous tasks.
+ *
+ * An instance of this class can be used to control masks or other UI elements that
+ * track the progression of asynchronous tasks. It can be passed directly to a Panel
+ * component via its `mask` property, providing a common and convenient
+ * method for masking a section of a user interface while an operation is pending.
+ */
+export declare class TaskObserver {
+    /**
+     * Create a new TaskObserver that will be pending if *any* linked
+     * subtasks is still pending.
+     */
+    static trackAll({ tasks, message }?: {
+        tasks?: TaskObserver[];
+        message?: string;
+    }): TaskObserver;
+    /**
+     * Create a new TaskObserver that will be pending if its *last* linked
+     * subtask is still pending.
+     *
+     * Useful for tracking repeated invocations of the same operation, such as
+     * serially reloading of data from the server.
+     */
+    static trackLast({ message }?: {
+        message?: string;
+    }): TaskObserver;
+    /**
+     * Create a TaskObserver bound to a single Promise.
+     * @see {@link Promise.linkTo} - preferred way to link an existing TaskObserver to a promise.
+     * @internal
+     */
+    static forPromise({ promise, message }: {
+        promise: any;
+        message: any;
+    }): PromiseObserver;
+    get isTaskObserver(): boolean;
+    /**
+     * Is the task considered to be executing/in-progress? Observable.
+     */
+    get isPending(): boolean;
+    /**
+     * The number of pending tasks. Observable.
+     */
+    get pendingCount(): number;
+    /**
+     * The message describing the executing task. Observable.
+     */
+    get message(): ReactNode;
+    /**
+     *  Set the message describing the executing task.
+     */
+    setMessage(msg: ReactNode): void;
+    /**
+     * Link the task to a subtask.
+     */
+    linkTo(task: TaskObserver): void;
+    /**
+     * This class is abstract and should not be instantiated directly. To get an instance of this
+     * class, use static methods trackFirst(), trackLast() or fromPromise().
+     * @internal
+     */
+    constructor();
+}
+declare class PromiseObserver extends TaskObserver {
+    private _isPending;
+    private _message;
+    get isPromiseObserver(): boolean;
+    get isPending(): boolean;
+    get pendingCount(): 1 | 0;
+    get message(): ReactNode;
+    constructor(promise: any, message: any);
+}
+export {};