@xh/hoist 57.0.0 → 57.0.1

package/build/types/cmp/form/field/BaseFieldModel.d.ts

@@ -0,0 +1,156 @@
+/// <reference types="react" />
+import { HoistModel } from '@xh/hoist/core';
+import { Rule, RuleLike, ValidationState } from '@xh/hoist/data';
+import { FormModel } from '../FormModel';
+export interface BaseFieldConfig {
+    /** Unique name for this field within its parent FormModel. */
+    name: string;
+    /** User-facing name for labels and validation messages. */
+    displayName?: string;
+    /**
+     * Initial value of this field.  If a function, will be executed dynamically when form is
+     * initialized to provide value.
+     */
+    initialValue?: any;
+    /** True to disable the input control for this field.*/
+    disabled?: boolean;
+    /** True to render a read-only value (vs. an input control). */
+    readonly?: boolean;
+    /** Rules, rule configs, or validation functions to apply to this field. */
+    rules?: RuleLike[];
+}
+/**
+ * Abstract Base class for FieldModels.
+ *
+ * @see FieldModel
+ * @see SubformsFieldModel
+ */
+export declare abstract class BaseFieldModel extends HoistModel {
+    get isFieldModel(): boolean;
+    initialValue: any;
+    value: any;
+    name: string;
+    displayName: string;
+    rules: Rule[];
+    /**
+     * True to trigger the display of any validation error messages by this
+     * model's bound FormField component. False to hide any such messages - even if the value
+     * is not in fact valid. This is often preferable when the user has yet to interact with
+     * this field since init/reset and eagerly showing validation errors would be confusing.
+     */
+    validationDisplayed: boolean;
+    /**
+     * The input Component bound to this field.
+     *
+     * This is an observable property that provides access to the "ref" or "imperativeHandle"
+     * of the bound component.
+     *
+     * This getter is provided to applications as an 'escape hatch' when they need
+     * imperative access to the underlying rendering of this FieldModel.
+     * Applications should not typically need to use this property.
+     *
+     * Note that there is no requirement that any input is bound to this FieldModel, or that there
+     * is only a single such input.  In the case of multiple bound inputs, no guarantee is
+     * provided regarding which one will be returned.
+     */
+    get boundInput(): any;
+    private _disabled;
+    private _readonly;
+    private _formModel;
+    private origInitialValue;
+    boundInputRef: import("react").RefObject<unknown> & ((instance: unknown) => void);
+    private _errors;
+    private validationTask;
+    private validationRunId;
+    constructor({ name, displayName, initialValue, disabled, readonly, rules }: BaseFieldConfig);
+    /** Parent FormModel - set via FormModel ctor/addField(). */
+    get formModel(): FormModel;
+    set formModel(formModel: FormModel);
+    /**
+     * Current data/value stored within this field.
+     *
+     * For standard, single-field FieldModels, returns the current value stored in the field.
+     * Overridden by SubformsFieldModels, which return the data for each sub-form in an array.
+     */
+    getData(): any;
+    get disabled(): boolean;
+    setDisabled(disabled: boolean): void;
+    get readonly(): boolean;
+    setReadonly(readonly: boolean): void;
+    setValue(v: any): void;
+    /** All validation errors for this field. */
+    get errors(): string[];
+    /** All validation errors for this field and its sub-forms. */
+    get allErrors(): string[];
+    /**
+     * Set the initial value of the field, reset to that value, and reset validation state.
+     *
+     * @param value - if undefined, field will be reset to initial value specified
+     *      when field was constructed.
+     */
+    init(value: any): void;
+    /** Reset to the initial value and reset validation state. */
+    reset(): void;
+    /** True if value has been changed since last reset/init. */
+    get isDirty(): boolean;
+    /**
+     * Is the bound input associated with this field focused?
+     *
+     * Note that there is no requirement that any input is bound to this FieldModel, or that there
+     * is only a single such input.  In the case of multiple bound inputs, no guarantee is provided
+     * regarding which one is consulted by this getter.
+     */
+    get hasFocus(): boolean;
+    /**
+     * Focus the bound input associated with this field.
+     *
+     * Note that there is no requirement that any input is bound to this FieldModel, or that there
+     * is only a single such input.  In the case of multiple bound inputs, no guarantee is
+     * provided regarding which one will be focused.
+     */
+    focus(): void;
+    /**
+     * Blur the bound input associated with this field.
+     */
+    blur(): void;
+    /**
+     * Trigger the display of any validation messages by the bound FormField component. Called
+     * when validation is requested on the parent FormModel, when the field is dirtied, or when a
+     * HoistInput bound to the field is blurred.
+     *
+     * @param includeSubforms - true to include all subforms of this field.
+     */
+    displayValidation(includeSubforms?: boolean): void;
+    /** Validation state of the field. */
+    get validationState(): ValidationState;
+    /** True if this field is confirmed to be Valid. */
+    get isValid(): boolean;
+    /** True if this field is confirmed to be NotValid. */
+    get isNotValid(): boolean;
+    /**
+     * True if validation of this field is currently pending, in which case
+     * the current state is out of date and should be considered provisional.
+     */
+    get isValidationPending(): boolean;
+    /**
+     * True if this field requires a non-nullish (null or undefined) value,
+     * i.e. if there is an active rule with the 'required' constraint.
+     */
+    get isRequired(): boolean;
+    /**
+     * Recompute all validations and return true if the field is valid.
+     *
+     * @param display - true to trigger the display of validation errors (if any)
+     *      by the bound FormField component after validation is complete.
+     */
+    validateAsync(opts?: {
+        display?: boolean;
+    }): Promise<boolean>;
+    getDataOrProxy(): any;
+    private processRuleSpecs;
+    private computeValidationAsync;
+    private evaluateAsync;
+    private evaluateRuleAsync;
+    private ruleIsActive;
+    protected deriveValidationState(): ValidationState;
+}

package/build/types/cmp/form/field/FieldModel.d.ts

@@ -0,0 +1,11 @@
+import { BaseFieldModel } from './BaseFieldModel';
+/**
+ * Model for a data field within a Form. Specifies the field's name, user-facing label, validation
+ * rules, and other properties. Holds the field's value as initialized by a parent FormModel or
+ * updated by a user interacting with a bound FormField component.
+ *
+ * These models are typically created by passing configuration objects to the constructor of FormModel.
+ * The parent Form/FormModel and the FormField component work together to bind to this model by name.
+ */
+export declare class FieldModel extends BaseFieldModel {
+}

package/build/types/cmp/form/field/SubformsFieldModel.d.ts

@@ -0,0 +1,65 @@
+import { PlainObject } from '@xh/hoist/core';
+import { ValidationState } from '@xh/hoist/data';
+import { FormModel } from '../FormModel';
+import { BaseFieldModel, BaseFieldConfig } from './BaseFieldModel';
+import { FormConfig } from '../FormModel';
+export interface SubformsFieldConfig extends BaseFieldConfig {
+    /** Config for FormModel representing a subform. */
+    subforms: FormConfig;
+    /**
+     * Initial value of this field.  If a function, will be
+     * executed dynamically when form is initialized to provide value.
+     */
+    initialValue?: any[];
+}
+/**
+ * A data field in a form whose value is a collection of FormModels (subforms).
+ *
+ * Applications should initialize this field with an array of objects.  These values will be
+ * loaded into an array of managed FormModels which will form the value of this field.
+ *
+ * Applications should *not* modify the value property directly, unless they wish to reinitialize
+ * all existing form contents to new values.  Use the methods add() or remove() to
+ * adjust the contents of the collection while preserving existing form state.
+ *
+ * Validation rules for the entire collection may be specified as for any field, but
+ * validations on the subforms will also bubble up to this field, affecting its overall
+ * validation state.
+ */
+export declare class SubformsFieldModel extends BaseFieldModel {
+    private createdModels;
+    private formConfig;
+    private origInitialValues;
+    constructor({ subforms, initialValue, ...rest }: SubformsFieldConfig);
+    get hasFocus(): boolean;
+    focus(): void;
+    blur(): void;
+    getDataOrProxy(): any;
+    getData(): any[];
+    init(value: any): void;
+    setValue(v: any): void;
+    get formModel(): FormModel;
+    set formModel(formModel: FormModel);
+    get allErrors(): string[];
+    reset(): void;
+    displayValidation(includeSubforms?: boolean): void;
+    get isValidationPending(): boolean;
+    get isDirty(): boolean;
+    validateAsync(opts?: {
+        display?: boolean;
+    }): Promise<boolean>;
+    protected deriveValidationState(): ValidationState;
+    /**
+     * Add a new record (subform) to this field.
+     *
+     * @param initialValues - object containing initial values for new record.
+     * @param index - index in collection where subform should be inserted.
+     */
+    add(opts?: {
+        initialValues?: PlainObject;
+        index?: number;
+    }): void;
+    remove(formModel: FormModel): void;
+    private parseValue;
+    private cleanupModels;
+}

package/build/types/cmp/form/index.d.ts

@@ -0,0 +1,6 @@
+export * from './Form';
+export * from './FormModel';
+export * from './field/BaseFieldModel';
+export * from './field/FieldModel';
+export * from './field/SubformsFieldModel';
+export * from './BaseFormFieldProps';

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

@@ -0,0 +1,39 @@
+/// <reference types="react" />
+import { HoistProps, LayoutProps } from '@xh/hoist/core';
+import './Grid.scss';
+import { GridModel } from './GridModel';
+import type { GridOptions, GridReadyEvent } from '@xh/hoist/kit/ag-grid';
+export interface GridProps extends HoistProps<GridModel>, LayoutProps {
+    /**
+     * Options for ag-Grid's API.
+     *
+     * This constitutes an 'escape hatch' for applications that need to get to the underlying
+     * ag-Grid API. It should be used with care. Settings made here might be overwritten and/or
+     * interfere with the implementation of this component and its use of the ag-Grid API.
+     *
+     * Note that changes to these options after the component's initial render will be ignored.
+     */
+    agOptions?: GridOptions;
+    /**
+     * Callback when the grid has initialized. The component will call this with the ag-Grid
+     * event after running its internal handler to associate the ag-Grid APIs with its model.
+     */
+    onGridReady?: (e: GridReadyEvent) => void;
+}
+/**
+ * The primary rich data grid component within the Hoist toolkit.
+ * It is a highly managed wrapper around ag-Grid and is the main display component for GridModel.
+ *
+ * Applications should typically configure and interact with Grids via a GridModel, which provides
+ * support for specifying the Grid's data Store, Column definitions, sorting and grouping state,
+ * selection API, and more.
+ *
+ * For advanced ag-Grid use-cases that are not well supported by this component, note that the
+ * {@link AgGrid} Hoist component provides much thinner and less opinionated wrapper around ag-Grid
+ * while still retaining consistent styling and some additional conveniences. However a number of
+ * core Hoist integrations and features will *not* be available with that thinner wrapper.
+ *
+ * @see {@link https://www.ag-grid.com/javascript-grid-reference-overview/|ag-Grid Docs}
+ * @see GridModel
+ */
+export declare const Grid: import("react").FC<GridProps>, grid: import("@xh/hoist/core").ElementFactory<GridProps>;

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

@@ -0,0 +1,44 @@
+import { Some } from '@xh/hoist/core';
+import { Column } from './columns';
+import { GridAutosizeMode } from './enums/GridAutosizeMode';
+export interface GridAutosizeOptions {
+    /** Mode governing when resize occurs. Defaults to GridAutosizeMode.ON_SIZING_MODE_CHANGE.*/
+    mode?: GridAutosizeMode;
+    /**
+     * Additional pixels to add to the size of each column beyond its absolute minimum.
+     * May be used to adjust the spacing in the grid. Columns that wish to
+     * override this value may specify `Column.autosizeBufferPx`. Default is 5.
+     */
+    bufferPx?: number;
+    /**
+     *  True to show mask over the grid during the autosize operation. Default is true.
+     */
+    showMask?: boolean;
+    /**
+     * True to limit operation to rendered rows only. Default is false.
+     * Set to true for grids that contain many rows and columns, for which full autosizing
+     * of all data would be too slow.
+     */
+    renderedRowsOnly?: boolean;
+    /**
+     *  True to autosize all rows, even when hidden due to a collapsed ancestor row.
+     *  Only has an effect when renderedRowsOnly is false. Default is false.
+     *  Note that setting this to true can have performance impacts for large tree grids with many cells.
+     */
+    includeCollapsedChildren?: boolean;
+    /**
+     * Columns ids to autosize, or a function for testing if the given column should be
+     * autosized. Typically used when calling autosizeAsync() manually. To generally exclude
+     * a column from autosizing, see the autosizable option on columns.
+     */
+    columns?: Some<string> | ((c: Column) => boolean);
+    /**
+     * How to fill remaining space after the columns have been autosized. Valid
+     * options are ['all', 'left', 'right', 'none']. Default is 'none'. Note this
+     * option is an advanced option that should be used with care - setting it will mean that all
+     * available horizontal space will be allocated. If the grid is subsequently compressed in
+     * width, or content added to it, horizontal scrolling of the columns may result that may
+     * require an additional autosize.
+     */
+    fillMode?: string;
+}

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

@@ -0,0 +1,28 @@
+import { PlainObject } from '@xh/hoist/core';
+import { GridModel } from '@xh/hoist/cmp/grid';
+import { RecordActionLike } from '@xh/hoist/data';
+/**
+ * If a String, value can be '-' for a separator, or a token supported by ag-Grid
+ * for its native menu items, or a Hoist specific token.
+ * {@link https://www.ag-grid.com/javascript-grid-context-menu/#built-in-menu-items}
+ */
+export type GridContextMenuItemLike = RecordActionLike | GridContextMenuToken | string;
+/**
+ * Hoist tokens, all of which require a GridModel:
+ *          `autosizeColumns` - autosize columns to fit their contents.
+ *          `copyCell` - copy cell value to clipboard.
+ *          `colChooser` - display column chooser for a grid.
+ *          `expandCollapseAll` - expand/collapse all parent rows on grouped or tree grid.
+ *          `export` - export grid data to excel via Hoist's server-side export capabilities.
+ *          `exportExcel` - alias for `export`.
+ *          `exportCsv` - export to CSV via Hoist's server-side export capabilities.
+ *          `exportLocal` - export to Excel via ag-Grid's built-in client side export.
+ *          'filter' - Sub menu to filter grid. Requires grid filtering.
+ *          `restoreDefaults` - restore column, sorting, and grouping configs and clear any
+ *              persistent grid state. See {@link GridModel.restoreDefaults}
+ */
+export type GridContextMenuToken = 'autosizeColumns' | 'copyCell' | 'colChooser' | 'expandCollapseAll' | 'export' | 'exportExcel' | 'exportCsv' | 'exportLocal' | 'filter' | 'restoreDefaults';
+/**
+ * Specification for a GridContextMenu.  Either a list of items, or a function to produce one.
+ */
+export type GridContextMenuSpec = GridContextMenuItemLike[] | ((agParams: PlainObject, gridModel: GridModel) => GridContextMenuItemLike[]);