feat: allow default value overrides form data

Author: Lonli-Lokli

CHANGELOG.md

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

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

@@ -269,7 +269,7 @@ 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                                                                                         |
+| `useDefaultAlways`              | Always use the default value instead of form data                                                                                         |
 
 |
 

packages/playground/src/components/Header.tsx

@@ -204,7 +204,7 @@ const liveSettingsSelectSchema: RJSFSchema = {
             {
               type: 'string',
               title: 'Always use default for field value',
-              enum: ['useDefault'],
+              enum: ['useDefaultAlways'],
             },
           ],
         },

packages/utils/src/mergeDefaultsWithFormData.ts

@@ -1,7 +1,7 @@
 import get from 'lodash/get';
 
 import isObject from './isObject';
-import { GenericObjectType } from '../src';
+import { GenericObjectType, OverrideFormDataStrategy } from '../src';
 import isNil from 'lodash/isNil';
 
 /** Merges the `defaults` object of type `T` into the `formData` of type `T`
@@ -20,25 +20,24 @@ 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 [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.
+ * @param [overrideFormDataWithDefaultsStrategy=OverrideFormDataStrategy.noop] - Strategy for merging defaults and form data
  * @returns - The resulting merged form data with defaults
  */
 export default function mergeDefaultsWithFormData<T = any>(
   defaults?: T,
   formData?: T,
   mergeExtraArrayDefaults = false,
   defaultSupercedesUndefined = false,
-  overrideFormDataWithDefaultsStrategy: 'noop' | 'replace' | 'merge' = 'noop',
+  overrideFormDataWithDefaultsStrategy: OverrideFormDataStrategy = OverrideFormDataStrategy.noop,
 ): T | undefined {
   if (Array.isArray(formData)) {
     const defaultsArray = Array.isArray(defaults) ? defaults : [];
 
     // 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 overrideArray =
+      overrideFormDataWithDefaultsStrategy !== OverrideFormDataStrategy.noop ? defaultsArray : formData;
+    const overrideOppositeArray =
+      overrideFormDataWithDefaultsStrategy !== OverrideFormDataStrategy.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
@@ -55,17 +54,18 @@ export default function mergeDefaultsWithFormData<T = any>(
     });
 
     // Merge any extra defaults when mergeExtraArrayDefaults is true
-    // Or when overrideFormDataWithDefaults is not noop and the default array is shorter than the formData array
+    // Or when overrideFormDataWithDefaults is 'merge' and the default array is shorter than the formData array
     if (
-      (mergeExtraArrayDefaults || overrideFormDataWithDefaultsStrategy === 'merge') &&
+      (mergeExtraArrayDefaults || overrideFormDataWithDefaultsStrategy === OverrideFormDataStrategy.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 iterationSource =
+      overrideFormDataWithDefaultsStrategy === OverrideFormDataStrategy.replace ? (defaults ?? {}) : formData;
     const acc: { [key in keyof T]: any } = Object.assign({}, defaults); // Prevent mutation of source object.
     return Object.keys(iterationSource as GenericObjectType).reduce((acc, key) => {
       const keyValue = get(formData, key);
@@ -74,11 +74,11 @@ export default function mergeDefaultsWithFormData<T = any>(
       // 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'
+        overrideFormDataWithDefaultsStrategy === OverrideFormDataStrategy.replace
+          ? OverrideFormDataStrategy.replace
           : keyExistsInDefaults || !keyExistsInFormData
             ? overrideFormDataWithDefaultsStrategy
-            : 'noop';
+            : OverrideFormDataStrategy.noop;
       acc[key as keyof T] = mergeDefaultsWithFormData<T>(
         defaults ? get(defaults, key) : {},
         keyValue,
@@ -99,10 +99,10 @@ export default function mergeDefaultsWithFormData<T = any>(
   if (
     (defaultSupercedesUndefined &&
       ((!isNil(defaults) && isNil(formData)) || (typeof formData === 'number' && isNaN(formData)))) ||
-    (overrideFormDataWithDefaultsStrategy === 'merge' && !isNil(formData))
+    (overrideFormDataWithDefaultsStrategy === OverrideFormDataStrategy.merge && !isNil(formData))
   ) {
     return defaults;
   }
 
-  return overrideFormDataWithDefaultsStrategy === 'replace' ? defaults : formData;
+  return overrideFormDataWithDefaultsStrategy === OverrideFormDataStrategy.replace ? defaults : formData;
 }

packages/utils/src/schema/getDefaultFormState.ts

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

packages/utils/src/types.ts

@@ -98,9 +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
+   * - `useDefaultAlways`: - Always use the default value
    */
-  mergeDefaultsIntoFormData?: 'useFormDataIfPresent' | 'useDefaultIfFormDataUndefined' | 'useDefault';
+  mergeDefaultsIntoFormData?: 'useFormDataIfPresent' | 'useDefaultIfFormDataUndefined' | 'useDefaultAlways';
   /** 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
@@ -1266,3 +1266,14 @@ export interface SchemaUtilsType<T = any, S extends StrictRJSFSchema = RJSFSchem
    */
   toPathSchema(schema: S, name?: string, formData?: T): PathSchema<T>;
 }
+
+/** Strategy for merging defaults with existing form data */
+export enum OverrideFormDataStrategy {
+  /** No merge or override applied */
+  noop,
+  /** 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 */
+  merge,
+  /** Replace form data with defined default */
+  replace,
+}

packages/utils/test/schema/getDefaultFormStateTest.ts

@@ -1341,9 +1341,9 @@ export default function getDefaultFormStateTest(testValidator: TestValidatorType
           });
         });
 
-        describe('mergeDefaultsIntoFormData set to "useDefault"', () => {
+        describe('mergeDefaultsIntoFormData set to "useDefaultAlways"', () => {
           const experimental_defaultFormStateBehavior: Experimental_DefaultFormStateBehavior = {
-            mergeDefaultsIntoFormData: 'useDefault',
+            mergeDefaultsIntoFormData: 'useDefaultAlways',
           };
 
           test('getDefaultFormState', () => {