feat: allow override form values with defaults

CHANGELOG.md

@@ -16,6 +16,10 @@ should change the heading of the (upcoming) version to include a major version b
 
 -->
 
+## @rjsf/util
+
+- Allow form value overrides with defaults [#4625](https://github.com/rjsf-team/react-jsonschema-form/pull/4625
+
 # 6.0.0-beta.8
 
 ## @rjsf/util

packages/docs/docs/api-reference/form-props.md

@@ -269,6 +269,9 @@ NOTE: If there is a default for a field and the `formData` is unspecified, the d
 | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
 | `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                                          |
+| `useDefault`                    | Always use the default value instead of form data                                                                                         |
+
+|
 
 ## experimental_customMergeAllOf
 

packages/docs/docs/api-reference/utility-functions.md

@@ -661,7 +661,7 @@ Merges the `defaults` object of type `T` into the `formData` of type `T`
 When merging defaults and form data, we want to merge in this specific way:
 
 - objects are deeply merged
-- arrays are merged in such a way that:
+- arrays are either replaced (when `defaultSupercedes` is true) or merged in such a way that:
   - when the array is set in form data, only array entries set in form data are deeply merged; additional entries from the defaults are ignored unless `mergeExtraArrayDefaults` is true, in which case the extras are appended onto the end of the form data
   - when the array is not set in form data, the default is copied over
 - scalars are overwritten/set by form data
@@ -672,6 +672,7 @@ When merging defaults and form data, we want to merge in this specific way:
 - [formData]: T | undefined - The form data into which the defaults will be merged
 - [mergeExtraArrayDefaults=false]: boolean - If true, any additional default array entries are appended onto the formData
 - [defaultSupercedesUndefined=false]: boolean - If true, an explicit undefined value will be overwritten by the default value
+- [defaultSupercedes=false]: boolean - If true, a value will be overwritten by the default value
 
 #### Returns
 

packages/playground/src/components/Header.tsx

@@ -201,6 +201,11 @@ const liveSettingsSelectSchema: RJSFSchema = {
               title: 'Use default for undefined field value',
               enum: ['useDefaultIfFormDataUndefined'],
             },
+            {
+              type: 'string',
+              title: 'Always use default for field value',
+              enum: ['useDefault'],
+            },
           ],
         },
       },

packages/utils/src/mergeDefaultsWithFormData.ts

@@ -20,7 +20,7 @@ import isNil from 'lodash/isNil';
  * @param [formData] - The form data into which the defaults will be merged
  * @param [mergeExtraArrayDefaults=false] - If true, any additional default array entries are appended onto the formData
  * @param [defaultSupercedesUndefined=false] - If true, an explicit undefined value will be overwritten by the default value
- * @param [overrideFormDataWithDefaults=false] - If true, the default value will overwrite the form data value. If the value
+ * @param [overrideFormDataWithDefaultsStrategy='noop'] - If not 'noop', the default value will overwrite the form data value. Values can be either replaced or merged, if the value
  *        doesn't exist in the default, we take it from formData and in the case where the value is set to undefined in formData.
  *       This is useful when we have already merged formData with defaults and want to add an additional field from formData
  *       that does not exist in defaults.
@@ -31,14 +31,14 @@ export default function mergeDefaultsWithFormData<T = any>(
   formData?: T,
   mergeExtraArrayDefaults = false,
   defaultSupercedesUndefined = false,
-  overrideFormDataWithDefaults = false,
+  overrideFormDataWithDefaultsStrategy: 'noop' | 'replace' | 'merge' = 'noop',
 ): T | undefined {
   if (Array.isArray(formData)) {
     const defaultsArray = Array.isArray(defaults) ? defaults : [];
 
-    // If overrideFormDataWithDefaults is true, we want to override the formData with the defaults
-    const overrideArray = overrideFormDataWithDefaults ? defaultsArray : formData;
-    const overrideOppositeArray = overrideFormDataWithDefaults ? formData : defaultsArray;
+    // If overrideFormDataWithDefaultsStrategy is not noop, we want to override the formData with the defaults
+    const overrideArray = overrideFormDataWithDefaultsStrategy !== 'noop' ? defaultsArray : formData;
+    const overrideOppositeArray = overrideFormDataWithDefaultsStrategy !== 'noop' ? formData : defaultsArray;
 
     const mapped = overrideArray.map((value, idx) => {
       // We want to explicitly make sure that the value is NOT undefined since null, 0 and empty space are valid values
@@ -48,33 +48,43 @@ export default function mergeDefaultsWithFormData<T = any>(
           formData[idx],
           mergeExtraArrayDefaults,
           defaultSupercedesUndefined,
-          overrideFormDataWithDefaults,
+          overrideFormDataWithDefaultsStrategy,
         );
       }
       return value;
     });
 
     // Merge any extra defaults when mergeExtraArrayDefaults is true
-    // Or when overrideFormDataWithDefaults is true and the default array is shorter than the formData array
-    if ((mergeExtraArrayDefaults || overrideFormDataWithDefaults) && mapped.length < overrideOppositeArray.length) {
+    // Or when overrideFormDataWithDefaults is not noop and the default array is shorter than the formData array
+    if (
+      (mergeExtraArrayDefaults || overrideFormDataWithDefaultsStrategy === 'merge') &&
+      mapped.length < overrideOppositeArray.length
+    ) {
       mapped.push(...overrideOppositeArray.slice(mapped.length));
     }
     return mapped as unknown as T;
   }
   if (isObject(formData)) {
+    const iterationSource = overrideFormDataWithDefaultsStrategy === 'replace' ? (defaults ?? {}) : formData;
     const acc: { [key in keyof T]: any } = Object.assign({}, defaults); // Prevent mutation of source object.
-    return Object.keys(formData as GenericObjectType).reduce((acc, key) => {
+    return Object.keys(iterationSource as GenericObjectType).reduce((acc, key) => {
       const keyValue = get(formData, key);
       const keyExistsInDefaults = isObject(defaults) && key in (defaults as GenericObjectType);
       const keyExistsInFormData = key in (formData as GenericObjectType);
+      // overrideFormDataWithDefaultsStrategy can be 'merge' only when the key value exists in defaults
+      // Or if the key value doesn't exist in formData
+      const keyOverrideDefaultStrategy =
+        overrideFormDataWithDefaultsStrategy === 'replace'
+          ? 'replace'
+          : keyExistsInDefaults || !keyExistsInFormData
+            ? overrideFormDataWithDefaultsStrategy
+            : 'noop';
       acc[key as keyof T] = mergeDefaultsWithFormData<T>(
         defaults ? get(defaults, key) : {},
         keyValue,
         mergeExtraArrayDefaults,
         defaultSupercedesUndefined,
-        // overrideFormDataWithDefaults can be true only when the key value exists in defaults
-        // Or if the key value doesn't exist in formData
-        overrideFormDataWithDefaults && (keyExistsInDefaults || !keyExistsInFormData),
+        keyOverrideDefaultStrategy,
       );
       return acc;
     }, acc);
@@ -89,10 +99,10 @@ export default function mergeDefaultsWithFormData<T = any>(
   if (
     (defaultSupercedesUndefined &&
       ((!isNil(defaults) && isNil(formData)) || (typeof formData === 'number' && isNaN(formData)))) ||
-    (overrideFormDataWithDefaults && !isNil(formData))
+    (overrideFormDataWithDefaultsStrategy === 'merge' && !isNil(formData))
   ) {
     return defaults;
   }
 
-  return formData;
+  return overrideFormDataWithDefaultsStrategy === 'replace' ? defaults : formData;
 }

packages/utils/src/schema/getDefaultFormState.ts

@@ -363,6 +363,7 @@ export function computeDefaults<T = any, S extends StrictRJSFSchema = RJSFSchema
         matchingFormData as T,
         mergeExtraDefaults,
         true,
+        experimental_defaultFormStateBehavior?.mergeDefaultsIntoFormData === 'useDefault' ? 'replace' : 'noop',
       ) as T;
     }
   }
@@ -732,7 +733,7 @@ export default function getDefaultFormState<
       formData,
       true, // set to true to add any additional default array entries.
       defaultSupercedesUndefined,
-      true, // set to true to override formData with defaults if they exist.
+      'merge', // set to 'merge' to override formData with defaults if they exist.
     );
     return result;
   }

packages/utils/src/types.ts

@@ -98,8 +98,9 @@ export type Experimental_DefaultFormStateBehavior = {
    *        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
+   * - `useDefault`: - Always use the default value
    */
-  mergeDefaultsIntoFormData?: 'useFormDataIfPresent' | 'useDefaultIfFormDataUndefined';
+  mergeDefaultsIntoFormData?: 'useFormDataIfPresent' | 'useDefaultIfFormDataUndefined' | 'useDefault';
   /** Optional enumerated flag controlling how const values are merged into the form data as defaults when dealing with
    * undefined values, defaulting to `always`. The defaulting behavior for this flag will always be controlled by the
    * `emptyObjectField` flag value. For instance, if `populateRequiredDefaults` is set and the const value is not

packages/utils/test/mergeDefaultsWithFormData.test.ts

@@ -141,13 +141,13 @@ describe('mergeDefaultsWithFormData()', () => {
     expect(mergeDefaultsWithFormData(obj1, obj2)?.a).toBeInstanceOf(File);
   });
 
-  describe('test with overrideFormDataWithDefaults set to true', () => {
+  describe('test with overrideFormDataWithDefaults set to `merge`', () => {
     it('should return data in formData when no defaults', () => {
-      expect(mergeDefaultsWithFormData(undefined, [2], undefined, undefined, true)).toEqual([2]);
+      expect(mergeDefaultsWithFormData(undefined, [2], undefined, undefined, 'merge')).toEqual([2]);
     });
 
     it('should return formData when formData is undefined', () => {
-      expect(mergeDefaultsWithFormData({}, undefined, undefined, undefined, true)).toEqual(undefined);
+      expect(mergeDefaultsWithFormData({}, undefined, undefined, undefined, 'merge')).toEqual(undefined);
     });
 
     it('should deeply merge and return formData when formData is undefined and defaultSupercedesUndefined false', () => {
@@ -170,7 +170,7 @@ describe('mergeDefaultsWithFormData()', () => {
           },
           undefined,
           undefined,
-          true,
+          'merge',
         ),
       ).toEqual({
         arrayWithDefaults: [null],
@@ -183,42 +183,42 @@ describe('mergeDefaultsWithFormData()', () => {
     });
 
     it('should return default when formData is undefined and defaultSupercedesUndefined true', () => {
-      expect(mergeDefaultsWithFormData({}, undefined, undefined, true, true)).toEqual({});
+      expect(mergeDefaultsWithFormData({}, undefined, undefined, true, 'merge')).toEqual({});
     });
 
     it('should return default when formData is null and defaultSupercedesUndefined true', () => {
-      expect(mergeDefaultsWithFormData({}, null, undefined, true, true)).toEqual({});
+      expect(mergeDefaultsWithFormData({}, null, undefined, true, 'merge')).toEqual({});
     });
 
     it('should merge two one-level deep objects', () => {
-      expect(mergeDefaultsWithFormData({ a: 1 }, { b: 2 }, undefined, undefined, true)).toEqual({
+      expect(mergeDefaultsWithFormData({ a: 1 }, { b: 2 }, undefined, undefined, 'merge')).toEqual({
         a: 1,
         b: 2,
       });
     });
 
     it('should override the first object with the values from the second', () => {
-      expect(mergeDefaultsWithFormData({ a: 1 }, { a: 2 }, undefined, undefined, true)).toEqual({ a: 1 });
+      expect(mergeDefaultsWithFormData({ a: 1 }, { a: 2 }, undefined, undefined, 'merge')).toEqual({ a: 1 });
     });
 
     it('should override non-existing values of the first object with the values from the second', () => {
       expect(
-        mergeDefaultsWithFormData({ a: { b: undefined } }, { a: { b: { c: 1 } } }, undefined, undefined, true),
+        mergeDefaultsWithFormData({ a: { b: undefined } }, { a: { b: { c: 1 } } }, undefined, undefined, 'merge'),
       ).toEqual({
         a: { b: { c: 1 } },
       });
     });
 
     it('should merge arrays using entries from second', () => {
-      expect(mergeDefaultsWithFormData([1, 2, 3], [4, 5], undefined, undefined, true)).toEqual([1, 2, 3]);
+      expect(mergeDefaultsWithFormData([1, 2, 3], [4, 5], undefined, undefined, 'merge')).toEqual([1, 2, 3]);
     });
 
     it('should merge arrays using entries from second and extra from the first', () => {
-      expect(mergeDefaultsWithFormData([1, 2], [4, 5, 6], undefined, undefined, true)).toEqual([1, 2, 6]);
+      expect(mergeDefaultsWithFormData([1, 2], [4, 5, 6], undefined, undefined, 'merge')).toEqual([1, 2, 6]);
     });
 
     it('should deeply merge arrays with overlapping entries', () => {
-      expect(mergeDefaultsWithFormData([{ a: 1 }], [{ b: 2 }, { c: 3 }], undefined, undefined, true)).toEqual([
+      expect(mergeDefaultsWithFormData([{ a: 1 }], [{ b: 2 }, { c: 3 }], undefined, undefined, 'merge')).toEqual([
         { a: 1, b: 2 },
         { c: 3 },
       ]);
@@ -256,7 +256,7 @@ describe('mergeDefaultsWithFormData()', () => {
         },
         c: 2,
       };
-      expect(mergeDefaultsWithFormData<any>(obj1, obj2, undefined, undefined, true)).toEqual(expected);
+      expect(mergeDefaultsWithFormData<any>(obj1, obj2, undefined, undefined, 'merge')).toEqual(expected);
     });
 
     it('should recursively merge deeply nested objects, including extra array data', () => {
@@ -293,7 +293,7 @@ describe('mergeDefaultsWithFormData()', () => {
         c: 2,
         d: 4,
       };
-      expect(mergeDefaultsWithFormData<any>(obj1, obj2, undefined, undefined, true)).toEqual(expected);
+      expect(mergeDefaultsWithFormData<any>(obj1, obj2, undefined, undefined, 'merge')).toEqual(expected);
     });
 
     it('should recursively merge File objects', () => {
@@ -307,4 +307,94 @@ describe('mergeDefaultsWithFormData()', () => {
       expect(mergeDefaultsWithFormData(obj1, obj2)?.a).toBeInstanceOf(File);
     });
   });
+
+  describe('test with overrideFormDataWithDefaults set to `replace`', () => {
+    it('should return empty array even when no defaults', () => {
+      expect(mergeDefaultsWithFormData(undefined, [2], undefined, undefined, 'replace')).toEqual([]);
+    });
+
+    it('should return default when formData is undefined', () => {
+      expect(mergeDefaultsWithFormData({}, undefined, undefined, undefined, 'replace')).toEqual({});
+    });
+
+    it('should return default when formData is undefined and defaultSupercedesUndefined true', () => {
+      expect(mergeDefaultsWithFormData({}, undefined, undefined, true, 'replace')).toEqual({});
+    });
+
+    it('should return default when formData is null and defaultSupercedesUndefined true', () => {
+      expect(mergeDefaultsWithFormData({}, null, undefined, true, 'replace')).toEqual({});
+    });
+
+    it('should not merge two one-level deep objects', () => {
+      expect(mergeDefaultsWithFormData({ a: 1 }, { b: 2 }, undefined, undefined, 'replace')).toEqual({
+        a: 1,
+      });
+    });
+
+    it('should not override the first object with the values from the second', () => {
+      expect(mergeDefaultsWithFormData({ a: 1 }, { a: 2 }, undefined, undefined, 'replace')).toEqual({ a: 1 });
+    });
+
+    it('should not return undefined from defaults', () => {
+      expect(
+        mergeDefaultsWithFormData({ a: { b: undefined } }, { a: { b: { c: 1 } } }, undefined, undefined, 'replace'),
+      ).toEqual({
+        a: { b: {} },
+      });
+    });
+
+    it('should not merge arrays using entries from second', () => {
+      expect(mergeDefaultsWithFormData([1, 2, 3], [4, 5], undefined, undefined, 'replace')).toEqual([1, 2, 3]);
+    });
+
+    it('should not deeply merge arrays with overlapping entries', () => {
+      expect(mergeDefaultsWithFormData([{ a: 1 }], [{ b: 2 }, { c: 3 }], undefined, undefined, 'replace')).toEqual([
+        { a: 1 },
+      ]);
+    });
+
+    it('should replace objects', () => {
+      const obj1 = {
+        a: 1,
+        b: {
+          c: 3,
+          d: [1, 2, 3],
+          e: { f: { g: 1 } },
+          h: [{ i: 1 }, { i: 2 }],
+        },
+        c: 2,
+      };
+      const obj2 = {
+        a: 1,
+        b: {
+          d: [3],
+          e: { f: { h: 2 } },
+          g: 1,
+          h: [{ i: 3 }, { i: 4 }, { i: 5 }],
+        },
+        c: 3,
+        d: 4,
+      };
+      expect(mergeDefaultsWithFormData<any>(obj1, obj2, undefined, undefined, 'replace')).toEqual({
+        a: 1,
+        b: {
+          c: 3,
+          d: [1, 2, 3],
+          e: { f: { g: 1 } },
+          h: [{ i: 1 }, { i: 2 }],
+        },
+        c: 2,
+      });
+    });
+
+    it('should replace arrays', () => {
+      expect(mergeDefaultsWithFormData([1, 2], [4, 5, 6], undefined, undefined, 'replace')).toEqual([1, 2]);
+    });
+
+    it('should replace objects', () => {
+      expect(mergeDefaultsWithFormData({ a: { b: 1 } }, { a: { b: 2 } }, undefined, undefined, 'replace')).toEqual({
+        a: { b: 1 },
+      });
+    });
+  });
 });