[core, form] Add mergeFormDataAndSchemaDefaults method to Merger

Author: x0k

.changeset/violet-wombats-cross.md

@@ -0,0 +1,5 @@
+---
+"@sjsf/form": minor
+---
+
+Add `mergeFormDataAndSchemaDefaults` method to `Merger`

packages/form/package.json

@@ -86,6 +86,10 @@
     "./legacy-omit-extra-data": {
       "types": "./dist/legacy-omit-extra-data.d.ts",
       "default": "./dist/legacy-omit-extra-data.js"
+    },
+    "./get-default-form-state": {
+      "types": "./dist/get-default-form-state.d.ts",
+      "default": "./dist/get-default-form-state.js"
     }
   }
 }

packages/form/src/core/default-merger.ts

@@ -1,12 +1,32 @@
 import mergeAllOf, { type Options } from "json-schema-merge-allof";
 
 import type { Merger } from "./merger.js";
-import type { Schema } from "./schema.js";
+import type { Schema, SchemaValue } from "./schema.js";
+import type { Validator } from "./validator.js";
+import { getDefaultFormState2 } from "./default-state.js";
 
-export const defaultMerger: Merger = {
-  mergeAllOf(schema) {
+export class DefaultMerger implements Merger {
+  constructor(
+    protected readonly validator: Validator,
+    protected readonly rootSchema: Schema
+  ) {}
+
+  mergeAllOf(schema: Schema): Schema {
     return mergeAllOf(schema, {
       deep: false,
     } as Options) as Schema;
-  },
-};
+  }
+
+  mergeFormDataAndSchemaDefaults(
+    formData: SchemaValue | undefined,
+    schema: Schema
+  ): SchemaValue | undefined {
+    return getDefaultFormState2(
+      this.validator,
+      this,
+      schema,
+      formData,
+      this.rootSchema
+    );
+  }
+}

packages/form/src/core/default-state.test.ts

@@ -22,12 +22,15 @@ import { RECURSIVE_REF, RECURSIVE_REF_ALLOF } from "./fixtures/test-data.js";
 import type { Validator } from "./validator.js";
 import type { Schema } from "./schema.js";
 import { makeTestValidator } from "./test-validator.js";
-import { defaultMerger } from './default-merger.js';
+import { DefaultMerger } from './default-merger.js';
+import type { Merger } from './merger.js';
 
 let testValidator: Validator;
+let defaultMerger: Merger
 
 beforeEach(() => {
   testValidator = makeTestValidator();
+  defaultMerger = new DefaultMerger(testValidator, {});
 });
 
 describe("getDefaultFormState2()", () => {
@@ -2952,6 +2955,39 @@ describe("getDefaultFormState2()", () => {
       );
     });
   });
+  describe('object with defaults and undefined in formData, testing mergeDefaultsIntoFormData', () => {
+    let schema: Schema;
+    let defaultedFormData: any;
+    beforeAll(() => {
+      schema = {
+        type: 'object',
+        properties: {
+          field: {
+            type: 'string',
+            default: 'foo',
+          },
+        },
+        required: ['field'],
+      };
+      defaultedFormData = { field: 'foo' };
+    });
+    it('returns field value of default when formData is empty', () => {
+      const formData = {};
+      expect(getDefaultFormState2(testValidator, defaultMerger, schema, formData)).toEqual(defaultedFormData);
+    });
+    it('returns field value of undefined when formData has undefined for field', () => {
+      const formData = { field: undefined };
+      expect(getDefaultFormState2(testValidator, defaultMerger, schema, formData)).toEqual(formData);
+    });
+    it('returns field value of default when formData has undefined for field and `useDefaultIfFormDataUndefined`', () => {
+      const formData = { field: undefined };
+      expect(
+        getDefaultFormState2(testValidator, defaultMerger, schema, formData, undefined, undefined, {
+          mergeDefaultsIntoFormData: 'useDefaultIfFormDataUndefined',
+        })
+      ).toEqual(defaultedFormData);
+    });
+  });
   it("should return undefined defaults for a required array property with minItems", () => {
     const schema: Schema = {
       type: "object",

packages/form/src/core/default-state.ts

@@ -25,7 +25,7 @@ import {
 import { getSimpleSchemaType } from "./type.js";
 import { isMultiSelect2 } from "./is-select.js";
 import { getClosestMatchingOption2 } from "./matching.js";
-import { defaultMerger } from './default-merger.js';
+import { DefaultMerger } from './default-merger.js';
 import type { Merger } from './merger.js';
 
 export function getDefaultValueForType(type: SchemaType) {
@@ -59,7 +59,7 @@ export function getDefaultFormState(
   rootSchema?: Schema,
   includeUndefinedValues: boolean | "excludeObjectChildren" = false,
   experimental_defaultFormStateBehavior?: Experimental_DefaultFormStateBehavior,
-  merger: Merger = defaultMerger
+  merger: Merger = new DefaultMerger(validator, rootSchema ?? theSchema)
 ): SchemaValue | undefined {
   return getDefaultFormState2(
     validator,
@@ -100,7 +100,8 @@ export function getDefaultFormState2(
     return mergeDefaultsWithFormData(
       defaults,
       formData,
-      experimental_defaultFormStateBehavior?.arrayMinItems?.mergeExtraDefaults
+      experimental_defaultFormStateBehavior?.arrayMinItems?.mergeExtraDefaults,
+      experimental_defaultFormStateBehavior?.mergeDefaultsIntoFormData === "useDefaultIfFormDataUndefined"
     );
   }
   return formData;
@@ -159,6 +160,15 @@ type Experimental_DefaultFormStateBehavior = {
    * Optional flag to compute the default form state using allOf and if/then/else schemas. Defaults to `skipDefaults'.
    */
   allOf?: "populateDefaults" | "skipDefaults";
+  /** Optional enumerated flag controlling how the defaults are merged into the form data when dealing with undefined
+   * values, defaulting to `useFormDataIfPresent`.
+   * NOTE: If there is a default for a field and the `formData` is unspecified, the default ALWAYS merges.
+   * - `useFormDataIfPresent`: Legacy behavior - Do not merge defaults if there is a value for a field in `formData`,
+   *        even if that value is explicitly set to `undefined`
+   * - `useDefaultIfFormDataUndefined`: - If the value of a field within the `formData` is `undefined`, then use the
+   *        default value instead
+   */
+  mergeDefaultsIntoFormData?: 'useFormDataIfPresent' | 'useDefaultIfFormDataUndefined';
 };
 
 interface ComputeDefaultsProps {
@@ -178,7 +188,7 @@ export function computeDefaults<T extends SchemaValue>(
   validator: Validator,
   rawSchema: Schema,
   computeDefaultsProps?: ComputeDefaultsProps,
-  merger: Merger = defaultMerger
+  merger: Merger = new DefaultMerger(validator, rawSchema)
 ): SchemaValue | undefined {
   return computeDefaults2<T>(
     validator,

packages/form/src/core/is-file-schema.ts

@@ -2,7 +2,7 @@
 // Licensed under the Apache License, Version 2.0.
 // Modifications made by Roman Krasilnikov.
 
-import { defaultMerger } from './default-merger.js';
+import { DefaultMerger } from './default-merger.js';
 import type { Merger } from './merger.js';
 import { retrieveSchema2 } from "./resolve.js";
 import { DATA_URL_FORMAT, isNormalArrayItems, type Schema } from "./schema.js";
@@ -19,7 +19,7 @@ export function isFilesArray(
   validator: Validator,
   schema: Schema,
   rootSchema?: Schema,
-  merger: Merger = defaultMerger
+  merger: Merger = new DefaultMerger(validator, rootSchema ?? schema)
 ) {
   return isFilesArray2(validator, merger, schema, rootSchema);
 }

packages/form/src/core/is-select.test.ts

@@ -8,12 +8,15 @@ import type { Schema } from "./schema.js";
 import type { Validator } from "./validator.js";
 import { isMultiSelect2, isSelect2 } from "./is-select.js";
 import { makeTestValidator } from "./test-validator.js";
-import { defaultMerger } from './default-merger.js';
+import { DefaultMerger } from './default-merger.js';
+import type { Merger } from './merger.js';
 
 let testValidator: Validator;
+let defaultMerger: Merger
 
 beforeEach(() => {
   testValidator = makeTestValidator();
+  defaultMerger = new DefaultMerger(testValidator, {});
 });
 
 describe("isSelect2()", () => {

packages/form/src/core/is-select.ts

@@ -7,7 +7,7 @@ import type { Validator } from "./validator.js";
 import { retrieveSchema2 } from "./resolve.js";
 import { isSchemaOfConstantValue } from "./constant-schema.js";
 import type { Merger } from "./merger.js";
-import { defaultMerger } from "./default-merger.js";
+import { DefaultMerger } from "./default-merger.js";
 
 /**
  * @deprecated use `isSelect2`
@@ -16,7 +16,7 @@ export function isSelect(
   validator: Validator,
   theSchema: Schema,
   rootSchema: Schema,
-  merger: Merger = defaultMerger
+  merger: Merger = new DefaultMerger(validator, rootSchema)
 ) {
   return isSelect2(validator, merger, theSchema, rootSchema);
 }
@@ -48,7 +48,7 @@ export function isMultiSelect(
   validator: Validator,
   schema: Schema,
   rootSchema: Schema,
-  merger: Merger = defaultMerger
+  merger: Merger = new DefaultMerger(validator, rootSchema)
 ) {
   return isMultiSelect2(validator, merger, schema, rootSchema);
 }

packages/form/src/core/matching.test.ts

@@ -17,15 +17,18 @@ import { calculateIndexScore2, getClosestMatchingOption2 } from "./matching.js";
 import { beforeEach, describe, expect, it } from "vitest";
 import type { Validator } from "./validator.js";
 import { makeTestValidator } from "./test-validator.js";
-import { defaultMerger } from "./default-merger.js";
+import { DefaultMerger } from "./default-merger.js";
+import type { Merger } from './merger.js';
 
 const firstOption = oneOfSchema.definitions!.first_option_def as Schema;
 const secondOption = oneOfSchema.definitions!.second_option_def as Schema;
 
 let testValidator: Validator;
+let defaultMerger: Merger
 
 beforeEach(() => {
   testValidator = makeTestValidator();
+  defaultMerger = new DefaultMerger(testValidator, oneOfSchema);
 });
 
 describe("calculateIndexScore", () => {

packages/form/src/core/matching.ts

@@ -2,7 +2,7 @@
 // Licensed under the Apache License, Version 2.0.
 // Modifications made by Roman Krasilnikov.
 
-import { defaultMerger } from './default-merger.js';
+import { DefaultMerger } from './default-merger.js';
 import {
   getDiscriminatorFieldFromSchema,
   getOptionMatchingSimpleDiscriminator,
@@ -130,7 +130,7 @@ export function calculateIndexScore(
   rootSchema: Schema,
   schema?: Schema,
   formData?: SchemaValue,
-  merger: Merger = defaultMerger
+  merger: Merger = new DefaultMerger(validator, rootSchema)
 ): number {
   return calculateIndexScore2(validator, merger, rootSchema, schema, formData);
 }
@@ -232,7 +232,7 @@ export function getClosestMatchingOption(
   options: Schema[],
   selectedOption = -1,
   discriminatorField?: string,
-  merger: Merger = defaultMerger
+  merger: Merger = new DefaultMerger(validator, rootSchema)
 ): number {
   return getClosestMatchingOption2(
     validator,