Fix 391 & 2099 with new initialFormData prop and setFieldValue() on Form (#4815)

* Fix 391 with new initialFormData prop on Form
Fixes #391 by adding support for the `initialFormData` prop on `Form`
- Updated `@rjsf/core` as follows:
  - Updated `FormProps` to add the new `initialFormData` prop
  - Updated `Form` so that is behaves as a "controlled" form when `formData` is passed and uncontrolled when `initialFormData` is passed
  - Also fixed an issue where live validation was called on the initial form render, causing errors to show immediately, partially fixing #512
  - Updated the tests for `Form`, `ArrayField`, `ObjectField` and `StringField` to deal with the change to not live validating on initial render
  - Added new tests for `Form` that verify the fixes around controlled vs uncontrolled form related to the `initialFormData` and how it affects `reset()`
- Updated `form-props.md` and `v6x upgrade guide.md` to document the new `initialFormData` prop and the other potentially breaking `Form` fix
- Updated the `CHANGELOG.md` accordingly

* Apply suggestions from code review

* - Improved documentation

* - Fixed blank lines

* Update packages/docs/docs/migration-guides/v6.x upgrade guide.md

* - Updated `CHANGELOG.md` for other merged PR

* - Added `setFieldValue()` implementation on `Form`

* - Made `setFieldValue()` pass in the id of the field to `onChange()`

* Update packages/core/test/ArrayField.test.jsx

Co-authored-by: Nick Grosenbacher <nickgrosenbacher@gmail.com>

---------

Co-authored-by: Nick Grosenbacher <nickgrosenbacher@gmail.com>

Author: heath-freenome

CHANGELOG.md

@@ -21,10 +21,19 @@ should change the heading of the (upcoming) version to include a major version b
 
 - Updated `FormProps` to add new `onChange`/`onBlur` values for the `liveValidate` and `liveOmit` props, deprecating the `boolean` aspect of them
 - Updated `Form` to support the new feature to do `onBlur` handling of `liveValidate` and `liveOmit`
+- Updated `FormProps` to add the new `initialFormData` prop
+- Updated `Form` so that is behaves as a "controlled" form when `formData` is passed and uncontrolled when `initialFormData` is passed, fixing [#391](https://github.com/rjsf-team/react-jsonschema-form/issues/391)
+  - Also fixed an issue where live validation was called on the initial form render, causing errors to show immediately, partially fixing [#512](https://github.com/rjsf-team/react-jsonschema-form/issues/512)
+- Updated `Form` to add a new programmatic function, `setFieldValue(fieldPath: string | FieldPathList, newValue?: T): void`, fixing [#2099](https://github.com/rjsf-team/react-jsonschema-form/issues/2099)
+
+## @rjsf/mantine
+
+- Updated `FieldHelpTemplate` to avoid issue when `help` `and `fieldPathId` are undefined
 
 ## Dev / docs / playground
+
 - Updated the playground to switch `liveValidate` and `liveOmit` from checkboxes to radio buttons for the new options
-- Updated `form-props.md` and `v6x upgrade guide.md` to document the new feature and deprecation
+- Updated `internals.md`, `form-props.md` and `v6x upgrade guide.md` to document the new features, potential breaking changes and deprecations
 
 # 6.0.0-beta.22
 
@@ -127,6 +136,7 @@ should change the heading of the (upcoming) version to include a major version b
 - BREAKING CHANGE: Renamed `ArrayFieldItemButtonsTemplateType` to `ArrayFieldItemButtonsTemplateProps` and updated it to replace the `onAddIndexClick()`, `onCopyIndexClick()`, `onDropIndexClick()` and `onReorderClick()` callback-generator props with the `onAddItem()`, `onCopyItem()`, `onMoveUpItem()`, `onMoveDownItem()` and `onRemoveItem()` callback props
 
 ## Dev / docs / playground
+
 - Updated the `formTests.tsx` snapshots to add an `anyOf` of all arrays with different item types and removed the disabling of the optional data controls feature for the optional object with oneOfs
   - Updated the snapshots in all of the themes accordingly
 - Updated the playground to make the same changes as `formTests.tsx` in the `optionalDataControls.ts` sample, moving the `experimental_defaultFormStateBehavior` inside of a `liveSettings` block

packages/core/src/components/Form.tsx

@@ -54,6 +54,9 @@ import _toPath from 'lodash/toPath';
 
 import getDefaultRegistry from '../getDefaultRegistry';
 
+/** Internal only symbol used by the `reset()` function to indicate that a reset operation is happening */
+const IS_RESET = Symbol('reset');
+
 /** The properties that are passed to the `Form` */
 export interface FormProps<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any> {
   /** The JSON schema object for the form */
@@ -64,8 +67,14 @@ export interface FormProps<T = any, S extends StrictRJSFSchema = RJSFSchema, F e
   children?: ReactNode;
   /** The uiSchema for the form */
   uiSchema?: UiSchema<T, S, F>;
-  /** The data for the form, used to prefill a form with existing data */
+  /** The data for the form, used to load a "controlled" form with its current data. If you want an "uncontrolled" form
+   * with initial data, then use `initialFormData` instead.
+   */
   formData?: T;
+  /** The initial data for the form, used to fill an "uncontrolled" form with existing data on the initial render and
+   * when `reset()` is called programmatically.
+   */
+  initialFormData?: T;
   // Form presentation and behavior modifiers
   /** You can provide a `formContext` object to the form, which is passed down to all fields and widgets. Useful for
    * implementing context aware fields and widgets.
@@ -361,9 +370,11 @@ export default class Form<
       throw new Error('A validator is required for Form functionality to work');
     }
 
-    this.state = this.getStateFromProps(props, props.formData);
-    if (this.props.onChange && !deepEquals(this.state.formData, this.props.formData)) {
-      this.props.onChange(toIChangeEvent(this.state));
+    const { formData: propsFormData, initialFormData, onChange } = props;
+    const formData = propsFormData ?? initialFormData;
+    this.state = this.getStateFromProps(props, formData, undefined, undefined, undefined, true);
+    if (onChange && !deepEquals(this.state.formData, formData)) {
+      onChange(toIChangeEvent(this.state));
     }
     this.formElement = createRef();
   }
@@ -440,7 +451,6 @@ export default class Form<
   ) {
     if (snapshot.shouldUpdate) {
       const { nextState } = snapshot;
-
       if (
         !deepEquals(nextState.formData, this.props.formData) &&
         !deepEquals(nextState.formData, prevState.formData) &&
@@ -476,6 +486,7 @@ export default class Form<
     const schema = 'schema' in props ? props.schema : this.props.schema;
     const validator = 'validator' in props ? props.validator : this.props.validator;
     const uiSchema: UiSchema<T, S, F> = ('uiSchema' in props ? props.uiSchema! : this.props.uiSchema!) || {};
+    const isUncontrolled = props.formData === undefined && this.props.formData === undefined;
     const edit = typeof inputFormData !== 'undefined';
     const liveValidate = 'liveValidate' in props ? props.liveValidate : this.props.liveValidate;
     const mustValidate = edit && !props.noValidate && liveValidate;
@@ -506,9 +517,17 @@ export default class Form<
     }
 
     const rootSchema = schemaUtils.getRootSchema();
+
+    // Compute the formData for getDefaultFormState() function based on the inputFormData, isUncontrolled and state
+    let defaultsFormData = inputFormData;
+    if (inputFormData === IS_RESET) {
+      defaultsFormData = undefined;
+    } else if (inputFormData === undefined && isUncontrolled) {
+      defaultsFormData = state.formData;
+    }
     const formData: T = schemaUtils.getDefaultFormState(
       rootSchema,
-      inputFormData,
+      defaultsFormData,
       false,
       state.initialDefaultsGenerated,
     ) as T;
@@ -799,6 +818,20 @@ export default class Form<
     return this.getUsedFormData(formData, fieldNames);
   };
 
+  /** Allows a user to set a value for the provided `fieldPath`, which must be either a dotted path to the field OR a
+   * `FieldPathList`. To set the root element, used either `''` or `[]` for the path. Passing undefined will clear the
+   * value in the field.
+   *
+   * @param fieldPath - Either a dotted path to the field or the `FieldPathList` to the field
+   * @param [newValue] - The new value for the field
+   */
+  setFieldValue = (fieldPath: string | FieldPathList, newValue?: T) => {
+    const { registry } = this.state;
+    const path = Array.isArray(fieldPath) ? fieldPath : fieldPath.split('.');
+    const fieldPathId = toFieldPathId('', registry.globalFormOptions, path);
+    this.onChange(newValue, path, undefined, fieldPathId[ID_KEY]);
+  };
+
   /** Pushes the given change information into the `pendingChanges` array and then calls `processPendingChanges()` if
    * the array only contains a single pending change.
    *
@@ -941,8 +974,16 @@ export default class Form<
    *
    */
   reset = () => {
-    const { onChange } = this.props;
-    const newState = this.getStateFromProps(this.props, undefined);
+    // Cast the IS_RESET symbol to T to avoid type issues, we use this symbol to detect reset mode
+    const { formData: propsFormData, initialFormData = IS_RESET as T, onChange } = this.props;
+    const newState = this.getStateFromProps(
+      this.props,
+      propsFormData ?? initialFormData,
+      undefined,
+      undefined,
+      undefined,
+      true,
+    );
     const newFormData = newState.formData;
     const state = {
       formData: newFormData,

packages/core/test/ArrayField.test.jsx

@@ -380,6 +380,9 @@ describe('ArrayField', () => {
         liveValidate: true,
       });
 
+      // trigger the errors by submitting the form
+      submitForm(node);
+
       const matches = node.querySelectorAll('#custom');
       expect(matches).to.have.length.of(1);
       expect(matches[0].textContent).to.eql('must NOT have fewer than 2 items');
@@ -1302,6 +1305,8 @@ describe('ArrayField', () => {
           formData: ['foo', 'foo'],
           liveValidate: true,
         });
+        // trigger the errors by submitting the form since initial render no longer shows them
+        submitForm(node);
 
         const matches = node.querySelectorAll('#custom');
         expect(matches).to.have.length.of(1);
@@ -1452,6 +1457,9 @@ describe('ArrayField', () => {
           liveValidate: true,
         });
 
+        // trigger the errors by submitting the form since initial render no longer shows them
+        submitForm(node);
+
         const matches = node.querySelectorAll('#custom');
         expect(matches).to.have.length.of(1);
         expect(matches[0].textContent).to.eql('must NOT have fewer than 3 items');
@@ -1660,6 +1668,9 @@ describe('ArrayField', () => {
         liveValidate: true,
       });
 
+      // trigger the errors by submitting the form since initial render no longer shows them
+      submitForm(node);
+
       const matches = node.querySelectorAll('#custom');
       expect(matches).to.have.length.of(1);
       expect(matches[0].textContent).to.eql('must NOT have fewer than 5 items');
@@ -1733,6 +1744,9 @@ describe('ArrayField', () => {
         liveValidate: true,
       });
 
+      // trigger the errors by submitting the form since initial render no longer shows them
+      submitForm(node);
+
       const matches = node.querySelectorAll('#custom-error');
       expect(matches).to.have.length.of(2);
       expect(matches[0].textContent).to.eql('must NOT have fewer than 3 items');
@@ -3136,18 +3150,17 @@ describe('ArrayField', () => {
     it('Check that when formData changes, the form should re-validate', () => {
       const { node, rerender } = createFormComponent({
         schema,
-        formData: [
-          {
-            text: null,
-          },
-        ],
+        formData: [{}],
         liveValidate: true,
       });
 
+      // trigger the errors by submitting the form since initial render no longer shows them
+      submitForm(node);
+
       const errorMessages = node.querySelectorAll('#root_0_text__error');
       expect(errorMessages).to.have.length(1);
       const errorMessageContent = node.querySelector('#root_0_text__error .text-danger').textContent;
-      expect(errorMessageContent).to.contain('must be string');
+      expect(errorMessageContent).to.contain("must have required property 'text'");
 
       rerender({ schema, formData: [{ text: 'test' }], liveValidate: true });