Implement feature-flagged support for ignoring of optional array fields with minItems set (rjsf-team#3604)

Author: RPiAwesomeness

CHANGELOG.md

@@ -26,6 +26,8 @@ should change the heading of the (upcoming) version to include a major version b
 
 - Updated the `MultiSchemaField` to use the new `getDiscriminatorFieldFromSchema()` API
 
+- Added new `experimental_defaultFormStateBehavior` prop to `Form` to specify alternate behavior when dealing with the rendering of array fields where `minItems` is set but field is not `required` (fixes [3363](https://github.com/rjsf-team/react-jsonschema-form/issues/3363)) ([3604](https://github.com/rjsf-team/react-jsonschema-form/pull/3604))
+
 ## @rjsf/fluent-ui
 
 - Added support for `additionalProperties` to fluent-ui theme, fixing [#2777](https://github.com/rjsf-team/react-jsonschema-form/issues/2777).
@@ -36,10 +38,12 @@ should change the heading of the (upcoming) version to include a major version b
   - Updated `getDefaultFormState()` and `toPathSchema()` to use `getDiscriminatorFieldFromSchema()` to provide a discriminator field to `getClosestMatchingOption()` calls.
 - Refactored the `retrieveSchema()` internal API functions to support implementing an internal `schemaParser()` API for use in precompiling schemas, in support of [#3543](https://github.com/rjsf-team/react-jsonschema-form/issues/3543)
 - Fixed `toPathSchema()` to handle `properties` in an object along with `anyOf`/`oneOf`, fixing [#3628](https://github.com/rjsf-team/react-jsonschema-form/issues/3628) and [#1628](https://github.com/rjsf-team/react-jsonschema-form/issues/1628)
+- Refactored optional parameters for `computeDefaults()` into destructured props object to reduce clutter when only specifying later of the optional argument ([3604](https://github.com/rjsf-team/react-jsonschema-form/pull/3604))
 
 ## Dev / docs / playground
 
 - Added documentation to `custom-templates` describing how to extend the `BaseInputTemplate`
+- Added **minItems behavior for array field** live setting ([3604](https://github.com/rjsf-team/react-jsonschema-form/pull/3604))
 
 # 5.6.2
 

packages/core/src/components/Form.tsx

@@ -32,6 +32,7 @@ import {
   ValidationData,
   validationDataMerge,
   ValidatorType,
+  Experimental_DefaultFormStateBehavior,
 } from '@rjsf/utils';
 import _get from 'lodash/get';
 import _isEmpty from 'lodash/isEmpty';
@@ -181,6 +182,9 @@ export interface FormProps<T = any, S extends StrictRJSFSchema = RJSFSchema, F e
    * to put the second parameter before the first in its translation.
    */
   translateString?: Registry['translateString'];
+  /** Optional configuration object with flags, if provided, allows users to override default form state behavior
+   * Currently only affecting minItems on array fields */
+  experimental_defaultFormStateBehavior?: Experimental_DefaultFormStateBehavior;
   // Private
   /**
    * _internalFormWrapper is currently used by the semantic-ui theme to provide a custom wrapper around `<Form />`
@@ -305,9 +309,16 @@ export default class Form<
     const liveValidate = 'liveValidate' in props ? props.liveValidate : this.props.liveValidate;
     const mustValidate = edit && !props.noValidate && liveValidate;
     const rootSchema = schema;
+    const experimental_defaultFormStateBehavior =
+      'experimental_defaultFormStateBehavior' in props
+        ? props.experimental_defaultFormStateBehavior
+        : this.props.experimental_defaultFormStateBehavior;
     let schemaUtils: SchemaUtilsType<T, S, F> = state.schemaUtils;
-    if (!schemaUtils || schemaUtils.doesSchemaUtilsDiffer(props.validator, rootSchema)) {
-      schemaUtils = createSchemaUtils<T, S, F>(props.validator, rootSchema);
+    if (
+      !schemaUtils ||
+      schemaUtils.doesSchemaUtilsDiffer(props.validator, rootSchema, experimental_defaultFormStateBehavior)
+    ) {
+      schemaUtils = createSchemaUtils<T, S, F>(props.validator, rootSchema, experimental_defaultFormStateBehavior);
     }
     const formData: T = schemaUtils.getDefaultFormState(schema, inputFormData) as T;
     const retrievedSchema = schemaUtils.retrieveSchema(schema, formData);

packages/core/test/Form.test.jsx

@@ -1398,6 +1398,49 @@ describeRepeated('Form common', (createFormComponent) => {
     });
   });
 
+  describe('Default form state behavior flag', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        albums: {
+          type: 'array',
+          items: { type: 'string' },
+          title: 'Album Titles',
+          minItems: 3,
+        },
+      },
+    };
+    it('Errors when minItems is set, field is required, and minimum number of items are not present with IgnoreMinItemsUnlessRequired flag set', () => {
+      const { node, onError } = createFormComponent({
+        schema: { ...schema, required: ['albums'] },
+        formData: {
+          albums: ['Until We Have Faces'],
+        },
+        experimental_defaultFormStateBehavior: { arrayMinItems: 'requiredOnly' },
+      });
+      submitForm(node);
+      sinon.assert.calledWithMatch(onError.lastCall, [
+        {
+          message: 'must NOT have fewer than 3 items',
+          name: 'minItems',
+          params: { limit: 3 },
+          property: '.albums',
+          schemaPath: '#/properties/albums/minItems',
+          stack: "'Album Titles' must NOT have fewer than 3 items",
+        },
+      ]);
+    });
+    it('Submits when minItems is set, field is not required, and no items are present with IgnoreMinItemsUnlessRequired flag set', () => {
+      const { node, onSubmit } = createFormComponent({
+        schema,
+        formData: {},
+        experimental_defaultFormStateBehavior: { arrayMinItems: 'requiredOnly' },
+      });
+      submitForm(node);
+      sinon.assert.calledWithMatch(onSubmit.lastCall, { formData: {} });
+    });
+  });
+
   describe('Schema and external formData updates', () => {
     let comp;
     let onChangeProp;

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

@@ -59,6 +59,41 @@ Formerly the `validate` prop.
 The `customValidate` prop requires a function that specifies custom validation rules for the form.
 See [Validation](../usage/validation.md) for more information.
 
+## experimental_defaultFormStateBehavior
+
+Experimental features to specify different form state behavior. Currently, this only affects the handling of optional array fields where `minItems` is set.
+
+The following sub-sections represent the different keys in this object, with the tables explaining the values and their meanings.
+
+### `arrayMinItems`
+
+| Flag Value     | Description                                                                                                                        |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `populate`     | Legacy behavior - populate minItems entries with default values initially and include empty array when no values have been defined |
+| `requiredOnly` | Ignore `minItems` on a field when calculating defaults unless the field is required                                                |
+
+```tsx
+import { RJSFSchema } from '@rjsf/utils';
+import validator from '@rjsf/validator-ajv8';
+
+const schema: RJSFSchema = {
+  type: 'array',
+  items: { type: 'string' },
+  minItems: 3,
+};
+
+render(
+  <Form
+    schema={schema}
+    validator={validator}
+    experimental_defaultFormStateBehavior={{
+      arrayMinItems: 'requiredOnly',
+    }}
+  />,
+  document.getElementById('app')
+);
+```
+
 ## disabled
 
 It's possible to disable the whole form by setting the `disabled` prop. The `disabled` prop is then forwarded down to each field of the form.

packages/playground/src/components/Header.tsx

@@ -65,6 +65,37 @@ const liveSettingsSchema: RJSFSchema = {
       title: 'Show Error List',
       enum: [false, 'top', 'bottom'],
     },
+    experimental_defaultFormStateBehavior: {
+      title: 'Default Form State Behavior (Experimental)',
+      type: 'object',
+      properties: {
+        arrayMinItems: {
+          type: 'string',
+          title: 'minItems behavior for array field',
+          default: 'populate',
+          oneOf: [
+            {
+              type: 'string',
+              title: 'Populate remaining minItems with default values (legacy behavior)',
+              enum: ['populate'],
+            },
+            {
+              type: 'string',
+              title: 'Ignore minItems unless field is required',
+              enum: ['requiredOnly'],
+            },
+          ],
+        },
+      },
+    },
+  },
+};
+
+const liveSettingsUiSchema: UiSchema = {
+  experimental_defaultFormStateBehavior: {
+    'ui:options': {
+      label: false,
+    },
   },
 };
 
@@ -175,6 +206,7 @@ export default function Header({
             formData={liveSettings}
             validator={localValidator}
             onChange={handleSetLiveSettings}
+            uiSchema={liveSettingsUiSchema}
           >
             <div />
           </Form>

packages/playground/src/components/Playground.tsx

@@ -44,6 +44,7 @@ export default function Playground({ themes, validators }: PlaygroundProps) {
     readonly: false,
     omitExtraData: false,
     liveOmit: false,
+    experimental_defaultFormStateBehavior: { arrayMinItems: 'populate' },
   });
   const [FormComponent, setFormComponent] = useState<ComponentType<FormProps>>(withTheme({}));
   const [ArrayFieldTemplate, setArrayFieldTemplate] = useState<ComponentType<ArrayFieldTemplateProps>>();
@@ -82,6 +83,7 @@ export default function Playground({ themes, validators }: PlaygroundProps) {
       setObjectFieldTemplate(ObjectFieldTemplate);
       setLiveSettings(liveSettings);
       setShowForm(true);
+      setLiveSettings(liveSettings);
     },
     [theme, onThemeSelected, themes]
   );

packages/utils/src/createSchemaUtils.ts

@@ -1,6 +1,7 @@
 import deepEquals from './deepEquals';
 import {
   ErrorSchema,
+  Experimental_DefaultFormStateBehavior,
   FormContextType,
   GlobalUISchemaOptions,
   IdSchema,
@@ -29,24 +30,31 @@ import {
 } from './schema';
 
 /** The `SchemaUtils` class provides a wrapper around the publicly exported APIs in the `utils/schema` directory such
- * that one does not have to explicitly pass the `validator` or `rootSchema` to each method. Since both the `validator`
- * and `rootSchema` generally does not change across a `Form`, this allows for providing a simplified set of APIs to the
+ * that one does not have to explicitly pass the `validator`, `rootSchema`, or `experimental_defaultFormStateBehavior` to each method.
+ * Since these generally do not change across a `Form`, this allows for providing a simplified set of APIs to the
  * `@rjsf/core` components and the various themes as well. This class implements the `SchemaUtilsType` interface.
  */
 class SchemaUtils<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any>
   implements SchemaUtilsType<T, S, F>
 {
   rootSchema: S;
   validator: ValidatorType<T, S, F>;
+  experimental_defaultFormStateBehavior: Experimental_DefaultFormStateBehavior;
 
   /** Constructs the `SchemaUtils` instance with the given `validator` and `rootSchema` stored as instance variables
    *
    * @param validator - An implementation of the `ValidatorType` interface that will be forwarded to all the APIs
    * @param rootSchema - The root schema that will be forwarded to all the APIs
+   * @param experimental_defaultFormStateBehavior - Configuration flags to allow users to override default form state behavior
    */
-  constructor(validator: ValidatorType<T, S, F>, rootSchema: S) {
+  constructor(
+    validator: ValidatorType<T, S, F>,
+    rootSchema: S,
+    experimental_defaultFormStateBehavior: Experimental_DefaultFormStateBehavior
+  ) {
     this.rootSchema = rootSchema;
     this.validator = validator;
+    this.experimental_defaultFormStateBehavior = experimental_defaultFormStateBehavior;
   }
 
   /** Returns the `ValidatorType` in the `SchemaUtilsType`
@@ -63,13 +71,22 @@ class SchemaUtils<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends Fo
    *
    * @param validator - An implementation of the `ValidatorType` interface that will be compared against the current one
    * @param rootSchema - The root schema that will be compared against the current one
+   * @param [experimental_defaultFormStateBehavior] Optional configuration object, if provided, allows users to override default form state behavior
    * @returns - True if the `SchemaUtilsType` differs from the given `validator` or `rootSchema`
    */
-  doesSchemaUtilsDiffer(validator: ValidatorType<T, S, F>, rootSchema: S): boolean {
+  doesSchemaUtilsDiffer(
+    validator: ValidatorType<T, S, F>,
+    rootSchema: S,
+    experimental_defaultFormStateBehavior = {}
+  ): boolean {
     if (!validator || !rootSchema) {
       return false;
     }
-    return this.validator !== validator || !deepEquals(this.rootSchema, rootSchema);
+    return (
+      this.validator !== validator ||
+      !deepEquals(this.rootSchema, rootSchema) ||
+      !deepEquals(this.experimental_defaultFormStateBehavior, experimental_defaultFormStateBehavior)
+    );
   }
 
   /** Returns the superset of `formData` that includes the given set updated to include any missing fields that have
@@ -87,7 +104,14 @@ class SchemaUtils<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends Fo
     formData?: T,
     includeUndefinedValues: boolean | 'excludeObjectChildren' = false
   ): T | T[] | undefined {
-    return getDefaultFormState<T, S, F>(this.validator, schema, formData, this.rootSchema, includeUndefinedValues);
+    return getDefaultFormState<T, S, F>(
+      this.validator,
+      schema,
+      formData,
+      this.rootSchema,
+      includeUndefinedValues,
+      this.experimental_defaultFormStateBehavior
+    );
   }
 
   /** Determines whether the combination of `schema` and `uiSchema` properties indicates that the label for the `schema`
@@ -258,12 +282,17 @@ class SchemaUtils<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends Fo
  *
  * @param validator - an implementation of the `ValidatorType` interface that will be forwarded to all the APIs
  * @param rootSchema - The root schema that will be forwarded to all the APIs
+ * @param [experimental_defaultFormStateBehavior] Optional configuration object, if provided, allows users to override default form state behavior
  * @returns - An implementation of a `SchemaUtilsType` interface
  */
 export default function createSchemaUtils<
   T = any,
   S extends StrictRJSFSchema = RJSFSchema,
   F extends FormContextType = any
->(validator: ValidatorType<T, S, F>, rootSchema: S): SchemaUtilsType<T, S, F> {
-  return new SchemaUtils<T, S, F>(validator, rootSchema);
+>(
+  validator: ValidatorType<T, S, F>,
+  rootSchema: S,
+  experimental_defaultFormStateBehavior = {}
+): SchemaUtilsType<T, S, F> {
+  return new SchemaUtils<T, S, F>(validator, rootSchema, experimental_defaultFormStateBehavior);
 }