@xh/hoist 73.0.0-SNAPSHOT.1745976013413 → 73.0.0-SNAPSHOT.1746050068813

package/cmp/form/FormModel.ts

@@ -37,9 +37,7 @@ import {SubformsFieldConfig, SubformsFieldModel} from './field/SubformsFieldMode
 import {isLocalDate, LocalDate} from '@xh/hoist/utils/datetime';
 
 export interface FormConfig {
-    /**
-     * FieldModels, or configurations to create them, for all data fields managed by this FormModel.
-     */
+    /** FieldModels, or configs to create them, for all data fields managed by the model. */
     fields?: Array<BaseFieldModel | BaseFieldConfig | SubformsFieldConfig | SubformsFieldModel>;
 
     /** Map of initial values for fields in this model. */
@@ -62,28 +60,33 @@ export interface FormPersistOptions extends PersistOptions {
     excludeFields?: string[];
 }
 
+export interface FormValidateOptions {
+    /** True to trigger display of validation errors (if any) by bound `FormField`s after validation is complete. */
+    display?: boolean;
+}
+
 /**
- * FormModel is the main entry point for Form specification. This Model's `fields` collection holds
- * multiple FieldModel instances, which in turn hold the state of user edited data and the
- * validation rules around editing that data.
+ * FormModel is the main entry point for Form specification. This Model's `fields` object references
+ * multiple {@link FieldModel} instances, keyed by name, which in turn hold the state of user-
+ * edited data and the validation rules around editing that data.
  *
  * A complete representation of all fields and data within a Form can be produced via this model's
- * `getData()` method, making it easy to harvest all values for e.g. submission to a server.
+ * {@link getData} method, making it easy to harvest all values for e.g. submission to a server.
  *
- * Individual field values are also available as observables via this model's `values` proxy. An
- * application model can setup a reaction to track changes to any value and execute app-specific
+ * Individual field values are also available as observables via this model's {@link values} proxy.
+ * An application model can setup a reaction to track changes to any value and execute app-specific
  * logic such as disabling one field based on the state of another, or setting up cascading options.
  *
  * This Model provides an overall validation state, determined by the current validation state of
  * its fields as per their configured rules and constraints.
  *
- * FormModels can be nested via SubformsFieldModels, a specialized type of FieldModel that itself
- * manages a collection of child FormModels. This allows use cases where Forms support editing of
+ * FormModels can be nested via {@link SubformsFieldModel}s, a specialized type of FieldModel that
+ * itself manages a collection of child FormModels. This enables forms to support editing of
  * dynamic collections of complex objects with their own internal validation rules (e.g. a FormModel
  * representing a market order might have multiple nested FormModels to represent execution splits,
  * where each split has its own internal fields for broker, quantity, and time).
  *
- * @see FieldModel for details on state and validation maintained at the individual field level.
+ * See {@link FieldModel} for details on state/validation maintained at the individual field level.
  */
 export class FormModel extends HoistModel {
     /** Container object for FieldModel instances, keyed by field name.*/
@@ -200,7 +203,6 @@ export class FormModel extends HoistModel {
 
     /**
      * Set the value of one or more fields on this form.
-     *
      * @param values - map of field name to value.
      */
     @action
@@ -220,9 +222,7 @@ export class FormModel extends HoistModel {
     //-----------------------------------
     /**
      * The Field that is currently focused on this form.
-     *
-     * @see FieldModel.focus() for important information on this method
-     * and its limitations.
+     * See {@link FieldModel.focus} for important information on this method and its limitations.
      */
     @computed
     get focusedField(): BaseFieldModel {
@@ -231,9 +231,7 @@ export class FormModel extends HoistModel {
 
     /**
      * Focus a field on this form.
-     *
-     * @see FieldModel.focus() for important information on this method
-     * and its limitations.
+     * See {@link FieldModel.focus} for important information on this method and its limitations.
      */
     focusField(name: string) {
         this.getField(name)?.focus();
@@ -266,21 +264,15 @@ export class FormModel extends HoistModel {
         return flatMap(this.fields, s => s.allErrors);
     }
 
-    /**
-     * Recompute all validations and return true if the form is valid.
-     *
-     * @param opts - set 'display' to true to trigger the display of
-     *  validation errors (if any) by bound FormField components after validation
-     *  is complete.
-     */
-    async validateAsync(opts?: {display?: boolean}): Promise<boolean> {
+    /** Recompute all validations and return true if the form is valid. */
+    async validateAsync(opts?: FormValidateOptions): Promise<boolean> {
         const {display = true} = opts ?? {},
             promises = map(this.fields, m => m.validateAsync({display}));
         await Promise.all(promises);
         return this.isValid;
     }
 
-    /** Trigger the display of validation errors (if any) by bound FormField components. */
+    /** Trigger the display of validation errors (if any) by bound `FormField`s. */
     displayValidation() {
         forOwn(this.fields, m => m.displayValidation());
     }

package/cmp/form/field/SubformsFieldModel.ts

@@ -15,36 +15,47 @@ import {BaseFieldModel, BaseFieldConfig} from './BaseFieldModel';
 import {FormConfig} from '../FormModel';
 
 export interface SubformsFieldConfig extends BaseFieldConfig {
-    /** Config for FormModel representing a subform. */
+    /**
+     * Config for a {@link FormModel} to be auto-created to manage and validate the data for each
+     *
+     */
     subforms: FormConfig;
 
     /**
-     * Initial value of this field.  If a function, will be
-     * executed dynamically when form is initialized to provide value.
+     * Initial value of this field. If a function, will be executed dynamically when form is
+     * initialized to provide value.
      */
     initialValue?: any[];
 }
 
+export interface SubformAddOptions {
+    /** Initial values for the new object/subform. */
+    initialValues?: PlainObject;
+    /** Index within the collection where the new subform should be inserted. */
+    index?: number;
+}
+
 /**
- * A data field in a form whose value is a collection of FormModels (subforms).
+ * A data field in a form whose value is a collection of nested objects - all of the same shape, but
+ * with arbitrary internal complexity. A dedicated {@link FormModel} is auto-created to manage and
+ * validate each object independently.
  *
- * 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 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.
+ * all existing form contents to new values. Call {@link add} or {@link remove} on one of these
+ * fields to adjust the contents of its collection while preserving existing 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.
+ * 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 class SubformsFieldModel extends BaseFieldModel {
-    // (Sub)FormModels created by this model, tracked to support cleanup.
-    @managed
-    private createdModels: FormModel[] = [];
+    /** (Sub)FormModels created by this model, tracked to support cleanup. */
+    @managed private createdModels: FormModel[] = [];
+
     private formConfig: FormConfig = null;
-    private origInitialValues: any[];
+    private readonly origInitialValues: any[];
 
     constructor({subforms, initialValue = [], ...rest}: SubformsFieldConfig) {
         super(rest);
@@ -161,14 +172,9 @@ export class SubformsFieldModel extends BaseFieldModel {
     //-----------------------------
     // Collection management
     //-----------------------------
-    /**
-     * 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 a new object (subform) to this field's collection. */
     @action
-    add(opts: {initialValues?: PlainObject; index?: number} = {}) {
+    add(opts: SubformAddOptions = {}) {
         const {initialValues = {}, index = this.value.length} = opts,
             newSubforms = this.parseValue([initialValues]),
             newValue = clone(this.value);

package/cmp/grid/columns/DatesTimes.ts

@@ -4,7 +4,7 @@
  *
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
-import {ColumnSpec} from '@xh/hoist/cmp/grid';
+import {ColumnSpec, ExcelFormat} from '@xh/hoist/cmp/grid';
 import {
     compactDateRenderer,
     dateRenderer,
@@ -12,7 +12,6 @@ import {
     dateTimeSecRenderer,
     timeRenderer
 } from '@xh/hoist/format';
-import {ExcelFormat} from '../enums/ExcelFormat';
 
 const defaults: ColumnSpec = {align: 'right'};
 

package/cmp/grid/impl/GridHScrollbar.ts

@@ -7,10 +7,9 @@
 import {GridLocalModel, GridModel} from '@xh/hoist/cmp/grid';
 import {div} from '@xh/hoist/cmp/layout';
 import {hoistCmp, HoistModel, HoistProps, useLocalModel} from '@xh/hoist/core';
-import {makeObservable} from '@xh/hoist/mobx';
+import {action, makeObservable, observable} from '@xh/hoist/mobx';
 import {observeResize} from '@xh/hoist/utils/js';
 import {sumBy} from 'lodash';
-import {action, observable} from 'mobx';
 import {createRef, RefObject} from 'react';
 
 /**

package/core/HoistBase.ts

@@ -4,15 +4,21 @@
  *
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
-import {runInAction} from 'mobx';
-import {XH, PersistenceProvider, PersistOptions, DebounceSpec, Some, PersistableState} from './';
 import {
-    throwIf,
+    action,
+    autorun as mobxAutorun,
+    comparer,
+    reaction as mobxReaction,
+    runInAction,
+    when as mobxWhen
+} from '@xh/hoist/mobx';
+import {
     getOrCreate,
-    logInfo,
     logDebug,
     logError,
+    logInfo,
     logWarn,
+    throwIf,
     withDebug,
     withInfo
 } from '@xh/hoist/utils/js';
@@ -25,15 +31,9 @@ import {
     isString,
     upperFirst
 } from 'lodash';
-import {
-    action,
-    comparer,
-    autorun as mobxAutorun,
-    reaction as mobxReaction,
-    when as mobxWhen
-} from '@xh/hoist/mobx';
 import {IAutorunOptions, IReactionOptions} from 'mobx/dist/api/autorun';
-import {IReactionDisposer, IEqualsComparer} from 'mobx/dist/internal';
+import {IEqualsComparer, IReactionDisposer} from 'mobx/dist/internal';
+import {DebounceSpec, PersistableState, PersistenceProvider, PersistOptions, Some, XH} from './';
 
 export interface HoistBaseClass {
     new (...args: any[]): HoistBase;

package/data/cube/CubeField.ts

@@ -28,23 +28,8 @@ export interface CubeFieldSpec extends FieldSpec {
     /** True to allow this field to be used for grouping.*/
     isDimension?: boolean;
 
-    /**
-     * Instance of a Hoist Cube Aggregator (from the aggregate package), or string alias for the
-     * same (e.g. 'MAX').
-     */
-    aggregator?:
-        | Aggregator
-        | 'AVG'
-        | 'AVG_STRICT'
-        | 'CHILD_COUNT'
-        | 'LEAF_COUNT'
-        | 'MAX'
-        | 'MIN'
-        | 'NULL'
-        | 'SINGLE'
-        | 'SUM'
-        | 'SUM_STRICT'
-        | 'UNIQUE';
+    /** Instance of a Hoist Cube {@link Aggregator} or string token alias for one. */
+    aggregator?: Aggregator | AggregatorToken;
 
     /** Function to determine if aggregation should be performed at a given level of a query result. */
     canAggregateFn?: CanAggregateFn;
@@ -60,6 +45,20 @@ export interface CubeFieldSpec extends FieldSpec {
     parentDimension?: string;
 }
 
+/** Convenient (and serializable) alias for one of Hoist's Cube {@link Aggregator} classes. */
+export type AggregatorToken =
+    | 'AVG'
+    | 'AVG_STRICT'
+    | 'CHILD_COUNT'
+    | 'LEAF_COUNT'
+    | 'MAX'
+    | 'MIN'
+    | 'NULL'
+    | 'SINGLE'
+    | 'SUM'
+    | 'SUM_STRICT'
+    | 'UNIQUE';
+
 /**
  * @param dimension - dimension of aggregation
  * @param value - value of record on dimension
@@ -114,7 +113,7 @@ export class CubeField extends Field {
     //------------------------
     // Implementation
     //------------------------
-    private parseAggregator(val: any): Aggregator {
+    private parseAggregator(val: Aggregator | AggregatorToken): Aggregator {
         if (isString(val)) {
             switch (val) {
                 case 'AVG':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xh/hoist",
-  "version": "73.0.0-SNAPSHOT.1745976013413",
+  "version": "73.0.0-SNAPSHOT.1746050068813",
   "description": "Hoist add-on for building and deploying React Applications.",
   "repository": "github:xh/hoist-react",
   "homepage": "https://xh.io",

package/svc/TrackService.ts

@@ -119,6 +119,8 @@ export class TrackService extends HoistService {
             msg: stripTags(options.message),
             clientUsername: XH.getUsername(),
             appVersion: XH.getEnv('clientVersion'),
+            loadId: XH.loadId,
+            tabId: XH.tabId,
             url: window.location.href,
             timestamp: Date.now()
         };