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

package/CHANGELOG.md

@@ -10,6 +10,8 @@ Requires `hoist-core >= 30.0` with new APIs to support the consolidated Admin Co
 
 * Added a new "Clients" Admin Console tab- a consolidated view of all websocket-connected clients
   across all instances in the cluster.
+* Updated `FormModel` to support `persistWith` for storing and recalling its values, including
+  developer options to persist all or a provided subset of fields.
 
 ### 🐞 Bug Fixes
 

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

@@ -1,4 +1,4 @@
-import { HoistModel, PlainObject } from '@xh/hoist/core';
+import { HoistModel, PersistOptions, PlainObject } from '@xh/hoist/core';
 import { ValidationState } from '@xh/hoist/data';
 import { BaseFieldConfig, BaseFieldModel } from './field/BaseFieldModel';
 import { SubformsFieldConfig, SubformsFieldModel } from './field/SubformsFieldModel';
@@ -9,11 +9,19 @@ export interface FormConfig {
     fields?: Array<BaseFieldModel | BaseFieldConfig | SubformsFieldConfig | SubformsFieldModel>;
     /** Map of initial values for fields in this model. */
     initialValues?: PlainObject;
+    /** Options governing persistence of the form state. */
+    persistWith?: FormPersistOptions;
     disabled?: boolean;
     readonly?: boolean;
     /** @internal */
     xhImpl?: boolean;
 }
+export interface FormPersistOptions extends PersistOptions {
+    /** If persisting only a subset of all fields, provide an array of field names. */
+    includeFields?: string[];
+    /** If excluding a subset of all fields, provide an array of field names. */
+    excludeFields?: string[];
+}
 /**
  * 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
@@ -57,7 +65,7 @@ export declare class FormModel extends HoistModel {
      * See {@link getData} instead if you need to get or react to the values of *any/all* fields.
      */
     get values(): PlainObject;
-    constructor({ fields, initialValues, disabled, readonly, xhImpl }?: FormConfig);
+    constructor({ fields, initialValues, disabled, persistWith, readonly, xhImpl }?: FormConfig);
     getField(fieldName: string): BaseFieldModel;
     /**
      * Snapshot of current field values, keyed by field name.
@@ -127,4 +135,7 @@ export declare class FormModel extends HoistModel {
     /** Trigger the display of validation errors (if any) by bound FormField components. */
     displayValidation(): void;
     private createValuesProxy;
+    private initPersist;
+    private serialize;
+    private deserialize;
 }

package/cmp/form/FormModel.ts

@@ -4,14 +4,37 @@
  *
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
-import {HoistModel, managed, PlainObject} from '@xh/hoist/core';
+import {
+    HoistModel,
+    managed,
+    PersistableState,
+    PersistenceProvider,
+    PersistOptions,
+    PlainObject
+} from '@xh/hoist/core';
 import {ValidationState} from '@xh/hoist/data';
 import {action, bindable, computed, makeObservable, observable} from '@xh/hoist/mobx';
 import {throwIf} from '@xh/hoist/utils/js';
-import {flatMap, forEach, forOwn, map, mapValues, pickBy, some, values} from 'lodash';
+import {
+    flatMap,
+    forEach,
+    forOwn,
+    isArray,
+    isDate,
+    isObject,
+    isString,
+    map,
+    mapValues,
+    pick,
+    pickBy,
+    some,
+    values,
+    without
+} from 'lodash';
 import {BaseFieldConfig, BaseFieldModel} from './field/BaseFieldModel';
 import {FieldModel} from './field/FieldModel';
 import {SubformsFieldConfig, SubformsFieldModel} from './field/SubformsFieldModel';
+import {isLocalDate, LocalDate} from '@xh/hoist/utils/datetime';
 
 export interface FormConfig {
     /**
@@ -22,6 +45,9 @@ export interface FormConfig {
     /** Map of initial values for fields in this model. */
     initialValues?: PlainObject;
 
+    /** Options governing persistence of the form state. */
+    persistWith?: FormPersistOptions;
+
     disabled?: boolean;
     readonly?: boolean;
 
@@ -29,6 +55,13 @@ export interface FormConfig {
     xhImpl?: boolean;
 }
 
+export interface FormPersistOptions extends PersistOptions {
+    /** If persisting only a subset of all fields, provide an array of field names. */
+    includeFields?: string[];
+    /** If excluding a subset of all fields, provide an array of field names. */
+    excludeFields?: string[];
+}
+
 /**
  * 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
@@ -87,6 +120,7 @@ export class FormModel extends HoistModel {
         fields = [],
         initialValues = {},
         disabled = false,
+        persistWith = null,
         readonly = false,
         xhImpl = false
     }: FormConfig = {}) {
@@ -97,6 +131,7 @@ export class FormModel extends HoistModel {
         this.disabled = disabled;
         this.readonly = readonly;
         const models = {};
+
         fields.forEach((f: any) => {
             const model =
                     f instanceof BaseFieldModel
@@ -111,6 +146,7 @@ export class FormModel extends HoistModel {
         this.fields = models;
 
         this.init(initialValues);
+        if (persistWith) this.initPersist(persistWith);
 
         // Set the owning formModel *last* after all fields in place with data.
         // This (currently) kicks off the validation and other reactivity.
@@ -274,4 +310,50 @@ export class FormModel extends HoistModel {
             }
         );
     }
+
+    private initPersist({
+        includeFields = null,
+        excludeFields = null,
+        path = 'formValues',
+        ...rootPersistWith
+    }: FormPersistOptions) {
+        const allFields = Object.keys(this.fields);
+        const fieldNamesToPersist = excludeFields
+            ? without(allFields, ...excludeFields)
+            : (includeFields ?? allFields);
+
+        PersistenceProvider.create({
+            persistOptions: {
+                path,
+                ...rootPersistWith
+            },
+            target: {
+                getPersistableState: () =>
+                    new PersistableState(this.serialize(pick(this.getData(), fieldNamesToPersist))),
+                setPersistableState: ({value: formValues}) =>
+                    this.setValues(this.deserialize(pick(formValues, fieldNamesToPersist)))
+            },
+            owner: this
+        });
+    }
+
+    private serialize = (formValue: unknown) => {
+        if (isArray(formValue)) return formValue.map(this.serialize);
+        if (isDate(formValue)) return {_xhType: 'date', value: formValue.toJSON()};
+        if (isLocalDate(formValue)) return {_xhType: 'localDate', value: formValue.toJSON()};
+        if (isObject(formValue)) return mapValues(formValue, this.serialize);
+        return formValue;
+    };
+
+    private deserialize = (formValue: unknown) => {
+        if (isArray(formValue)) return formValue.map(this.deserialize);
+        if (isObject(formValue)) {
+            if ('_xhType' in formValue && 'value' in formValue && isString(formValue.value)) {
+                if (formValue._xhType === 'date') return new Date(formValue.value);
+                if (formValue._xhType === 'localDate') return LocalDate.get(formValue.value);
+            }
+            return mapValues(formValue, this.deserialize);
+        }
+        return formValue;
+    };
 }

package/package.json

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