@rjsf/utils 5.0.0-beta.16 → 5.0.0-beta.18

package/dist/utils.umd.development.js

@@ -1,8 +1,8 @@
 (function (global, factory) {
-  typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('lodash-es/isEqualWith'), require('lodash-es/get'), require('lodash-es/isEmpty'), require('jsonpointer'), require('lodash-es/omit'), require('lodash-es/set'), require('json-schema-merge-allof'), require('lodash-es/union'), require('lodash-es/cloneDeep'), require('react'), require('react-is')) :
-  typeof define === 'function' && define.amd ? define(['exports', 'lodash-es/isEqualWith', 'lodash-es/get', 'lodash-es/isEmpty', 'jsonpointer', 'lodash-es/omit', 'lodash-es/set', 'json-schema-merge-allof', 'lodash-es/union', 'lodash-es/cloneDeep', 'react', 'react-is'], factory) :
-  (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["@rjsf/utils"] = {}, global.isEqualWith, global.get, global.isEmpty, global.jsonpointer, global.omit, global.set, global.mergeAllOf, global.union, global.cloneDeep, global.React, global.ReactIs));
-})(this, (function (exports, isEqualWith, get, isEmpty, jsonpointer, omit, set, mergeAllOf, union, cloneDeep, React, ReactIs) { 'use strict';
+  typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('lodash-es/isEqualWith'), require('lodash-es/get'), require('lodash-es/isEmpty'), require('jsonpointer'), require('lodash-es/omit'), require('lodash-es/has'), require('lodash-es/isObject'), require('lodash-es/isString'), require('lodash-es/reduce'), require('lodash-es/times'), require('lodash-es/set'), require('json-schema-merge-allof'), require('lodash-es/union'), require('lodash-es/cloneDeep'), require('react'), require('react-is')) :
+  typeof define === 'function' && define.amd ? define(['exports', 'lodash-es/isEqualWith', 'lodash-es/get', 'lodash-es/isEmpty', 'jsonpointer', 'lodash-es/omit', 'lodash-es/has', 'lodash-es/isObject', 'lodash-es/isString', 'lodash-es/reduce', 'lodash-es/times', 'lodash-es/set', 'json-schema-merge-allof', 'lodash-es/union', 'lodash-es/cloneDeep', 'react', 'react-is'], factory) :
+  (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["@rjsf/utils"] = {}, global.isEqualWith, global.get, global.isEmpty, global.jsonpointer, global.omit, global.has, global.isObject$1, global.isString, global.reduce, global.times, global.set, global.mergeAllOf, global.union, global.cloneDeep, global.React, global.ReactIs));
+})(this, (function (exports, isEqualWith, get, isEmpty, jsonpointer, omit, has, isObject$1, isString, reduce, times, set, mergeAllOf, union, cloneDeep, React, ReactIs) { 'use strict';
 
   function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
 
@@ -11,6 +11,11 @@
   var isEmpty__default = /*#__PURE__*/_interopDefaultLegacy(isEmpty);
   var jsonpointer__default = /*#__PURE__*/_interopDefaultLegacy(jsonpointer);
   var omit__default = /*#__PURE__*/_interopDefaultLegacy(omit);
+  var has__default = /*#__PURE__*/_interopDefaultLegacy(has);
+  var isObject__default = /*#__PURE__*/_interopDefaultLegacy(isObject$1);
+  var isString__default = /*#__PURE__*/_interopDefaultLegacy(isString);
+  var reduce__default = /*#__PURE__*/_interopDefaultLegacy(reduce);
+  var times__default = /*#__PURE__*/_interopDefaultLegacy(times);
   var set__default = /*#__PURE__*/_interopDefaultLegacy(set);
   var mergeAllOf__default = /*#__PURE__*/_interopDefaultLegacy(mergeAllOf);
   var union__default = /*#__PURE__*/_interopDefaultLegacy(union);
@@ -89,7 +94,7 @@
       descriptor.enumerable = descriptor.enumerable || false;
       descriptor.configurable = true;
       if ("value" in descriptor) descriptor.writable = true;
-      Object.defineProperty(target, descriptor.key, descriptor);
+      Object.defineProperty(target, _toPropertyKey(descriptor.key), descriptor);
     }
   }
   function _createClass(Constructor, protoProps, staticProps) {
@@ -129,6 +134,20 @@
     }
     return target;
   }
+  function _toPrimitive(input, hint) {
+    if (typeof input !== "object" || input === null) return input;
+    var prim = input[Symbol.toPrimitive];
+    if (prim !== undefined) {
+      var res = prim.call(input, hint || "default");
+      if (typeof res !== "object") return res;
+      throw new TypeError("@@toPrimitive must return a primitive value.");
+    }
+    return (hint === "string" ? String : Number)(input);
+  }
+  function _toPropertyKey(arg) {
+    var key = _toPrimitive(arg, "string");
+    return typeof key === "symbol" ? key : String(key);
+  }
 
   /** Below are the list of all the keys into various elements of a RJSFSchema or UiSchema that are used by the various
    * utility functions. In addition to those keys, there are the special `ADDITIONAL_PROPERTY_FLAG` and
@@ -283,12 +302,14 @@
   }
 
   /** Given the `formData` and list of `options`, attempts to find the index of the option that best matches the data.
+   * Deprecated, use `getFirstMatchingOption()` instead.
    *
    * @param validator - An implementation of the `ValidatorType` interface that will be used when necessary
    * @param formData - The current formData, if any, used to figure out a match
    * @param options - The list of options to find a matching options from
    * @param rootSchema - The root schema, used to primarily to look up `$ref`s
    * @returns - The index of the matched option or 0 if none is available
+   * @deprecated
    */
   function getMatchingOption(validator, formData, options, rootSchema) {
     // For performance, skip validating subschemas if formData is undefined. We just
@@ -344,6 +365,19 @@
     return 0;
   }
 
+  /** Given the `formData` and list of `options`, attempts to find the index of the first option that matches the data.
+   * Always returns the first option if there is nothing that matches.
+   *
+   * @param validator - An implementation of the `ValidatorType` interface that will be used when necessary
+   * @param formData - The current formData, if any, used to figure out a match
+   * @param options - The list of options to find a matching options from
+   * @param rootSchema - The root schema, used to primarily to look up `$ref`s
+   * @returns - The index of the first matched option or 0 if none is available
+   */
+  function getFirstMatchingOption(validator, formData, options, rootSchema) {
+    return getMatchingOption(validator, formData, options, rootSchema);
+  }
+
   /** Given a specific `value` attempts to guess the type of a schema element. In the case where we have to implicitly
    *  create a schema, it is useful to know what type to use based on the data we are defining.
    *
@@ -395,6 +429,12 @@
     if (!type && (schema.properties || schema.additionalProperties)) {
       return "object";
     }
+    if (!type && Array.isArray(schema.oneOf) && schema.oneOf.length) {
+      return getSchemaType(schema.oneOf[0]);
+    }
+    if (!type && Array.isArray(schema.anyOf) && schema.anyOf.length) {
+      return getSchemaType(schema.anyOf[0]);
+    }
     if (Array.isArray(type) && type.length === 2 && type.includes("null")) {
       type = type.find(function (type) {
         return type !== "null";
@@ -403,99 +443,6 @@
     return type;
   }
 
-  /** Detects whether the given `schema` contains fixed items. This is the case when `schema.items` is a non-empty array
-   * that only contains objects.
-   *
-   * @param schema - The schema in which to check for fixed items
-   * @returns - True if there are fixed items in the schema, false otherwise
-   */
-  function isFixedItems(schema) {
-    return Array.isArray(schema.items) && schema.items.length > 0 && schema.items.every(function (item) {
-      return isObject(item);
-    });
-  }
-
-  /** 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:
-   *   - 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
-   *   - when the array is not set in form data, the default is copied over
-   * - scalars are overwritten/set by form data
-   *
-   * @param defaults - The defaults to merge
-   * @param formData - The form data into which the defaults will be merged
-   * @returns - The resulting merged form data with defaults
-   */
-  function mergeDefaultsWithFormData(defaults, formData) {
-    if (Array.isArray(formData)) {
-      var defaultsArray = Array.isArray(defaults) ? defaults : [];
-      var mapped = formData.map(function (value, idx) {
-        if (defaultsArray[idx]) {
-          return mergeDefaultsWithFormData(defaultsArray[idx], value);
-        }
-        return value;
-      });
-      return mapped;
-    }
-    if (isObject(formData)) {
-      var acc = Object.assign({}, defaults); // Prevent mutation of source object.
-      return Object.keys(formData).reduce(function (acc, key) {
-        acc[key] = mergeDefaultsWithFormData(defaults ? get__default["default"](defaults, key) : {}, get__default["default"](formData, key));
-        return acc;
-      }, acc);
-    }
-    return formData;
-  }
-
-  /** Recursively merge deeply nested objects.
-   *
-   * @param obj1 - The first object to merge
-   * @param obj2 - The second object to merge
-   * @param [concatArrays=false] - Optional flag that, when true, will cause arrays to be concatenated. Use
-   *          "preventDuplicates" to merge arrays in a manner that prevents any duplicate entries from being merged.
-   *          NOTE: Uses shallow comparison for the duplicate checking.
-   * @returns - A new object that is the merge of the two given objects
-   */
-  function mergeObjects(obj1, obj2, concatArrays) {
-    if (concatArrays === void 0) {
-      concatArrays = false;
-    }
-    return Object.keys(obj2).reduce(function (acc, key) {
-      var left = obj1 ? obj1[key] : {},
-        right = obj2[key];
-      if (obj1 && key in obj1 && isObject(right)) {
-        acc[key] = mergeObjects(left, right, concatArrays);
-      } else if (concatArrays && Array.isArray(left) && Array.isArray(right)) {
-        var toMerge = right;
-        if (concatArrays === "preventDuplicates") {
-          toMerge = right.reduce(function (result, value) {
-            if (!left.includes(value)) {
-              result.push(value);
-            }
-            return result;
-          }, []);
-        }
-        acc[key] = left.concat(toMerge);
-      } else {
-        acc[key] = right;
-      }
-      return acc;
-    }, Object.assign({}, obj1)); // Prevent mutation of source object.
-  }
-
-  /** This function checks if the given `schema` matches a single constant value. This happens when either the schema has
-   * an `enum` array with a single value or there is a `const` defined.
-   *
-   * @param schema - The schema for a field
-   * @returns - True if the `schema` has a single constant value, false otherwise
-   */
-  function isConstant(schema) {
-    return Array.isArray(schema["enum"]) && schema["enum"].length === 1 || CONST_KEY in schema;
-  }
-
   /** Recursively merge deeply nested schemas. The difference between `mergeSchemas` and `mergeObjects` is that
    * `mergeSchemas` only concats arrays for values under the 'required' keyword, and when it does, it doesn't include
    * duplicate values.
@@ -532,7 +479,7 @@
    * @param validator - An implementation of the `ValidatorType<T, S>` interface that is used to detect valid schema conditions
    * @param schema - The schema for which resolving a condition is desired
    * @param rootSchema - The root schema that will be forwarded to all the APIs
-   * @param formData - The current formData to assist retrieving a schema
+   * @param [formData] - The current formData to assist retrieving a schema
    * @returns - A schema with the appropriate condition resolved
    */
   function resolveCondition(validator, schema, rootSchema, formData) {
@@ -620,6 +567,10 @@
           }, rootSchema, formData);
         } else if ("type" in schema.additionalProperties) {
           additionalProperties = _extends({}, schema.additionalProperties);
+        } else if (ANY_OF_KEY in schema.additionalProperties || ONE_OF_KEY in schema.additionalProperties) {
+          additionalProperties = _extends({
+            type: "object"
+          }, schema.additionalProperties);
         } else {
           additionalProperties = {
             type: guessType(get__default["default"](formData, [key]))
@@ -691,9 +642,9 @@
       remainingSchema = _objectWithoutPropertiesLoose(schema, _excluded4);
     var resolvedSchema = remainingSchema;
     if (Array.isArray(resolvedSchema.oneOf)) {
-      resolvedSchema = resolvedSchema.oneOf[getMatchingOption(validator, formData, resolvedSchema.oneOf, rootSchema)];
+      resolvedSchema = resolvedSchema.oneOf[getFirstMatchingOption(validator, formData, resolvedSchema.oneOf, rootSchema)];
     } else if (Array.isArray(resolvedSchema.anyOf)) {
-      resolvedSchema = resolvedSchema.anyOf[getMatchingOption(validator, formData, resolvedSchema.anyOf, rootSchema)];
+      resolvedSchema = resolvedSchema.anyOf[getFirstMatchingOption(validator, formData, resolvedSchema.anyOf, rootSchema)];
     }
     return processDependencies(validator, dependencies, resolvedSchema, rootSchema, formData);
   }
@@ -814,6 +765,242 @@
     return mergeSchemas(schema, retrieveSchema(validator, dependentSchema, rootSchema, formData));
   }
 
+  /** A junk option used to determine when the getFirstMatchingOption call really matches an option rather than returning
+   * the first item
+   */
+  var JUNK_OPTION = {
+    type: "object",
+    properties: {
+      __not_really_there__: {
+        type: "number"
+      }
+    }
+  };
+  /** Recursive function that calculates the score of a `formData` against the given `schema`. The computation is fairly
+   * simple. Initially the total score is 0. When `schema.properties` object exists, then all the `key/value` pairs within
+   * the object are processed as follows after obtaining the formValue from `formData` using the `key`:
+   * - If the `value` contains a `$ref`, `calculateIndexScore()` is called recursively with the formValue and the new
+   *   schema that is the result of the ref in the schema being resolved and that sub-schema's resulting score is added to
+   *   the total.
+   * - If the `value` contains a `oneOf` and there is a formValue, then score based on the index returned from calling
+   *   `getClosestMatchingOption()` of that oneOf.
+   * - If the type of the `value` is 'object', `calculateIndexScore()` is called recursively with the formValue and the
+   *   `value` itself as the sub-schema, and the score is added to the total.
+   * - If the type of the `value` matches the guessed-type of the `formValue`, the score is incremented by 1, UNLESS the
+   *   value has a `default` or `const`. In those case, if the `default` or `const` and the `formValue` match, the score
+   *   is incremented by another 1 otherwise it is decremented by 1.
+   *
+   * @param validator - An implementation of the `ValidatorType` interface that will be used when necessary
+   * @param rootSchema - The root JSON schema of the entire form
+   * @param schema - The schema for which the score is being calculated
+   * @param formData - The form data associated with the schema, used to calculate the score
+   * @returns - The score a schema against the formData
+   */
+  function calculateIndexScore(validator, rootSchema, schema, formData) {
+    if (formData === void 0) {
+      formData = {};
+    }
+    var totalScore = 0;
+    if (schema) {
+      if (isObject__default["default"](schema.properties)) {
+        totalScore += reduce__default["default"](schema.properties, function (score, value, key) {
+          var formValue = get__default["default"](formData, key);
+          if (typeof value === "boolean") {
+            return score;
+          }
+          if (has__default["default"](value, REF_KEY)) {
+            var newSchema = retrieveSchema(validator, value, rootSchema, formValue);
+            return score + calculateIndexScore(validator, rootSchema, newSchema, formValue || {});
+          }
+          if (has__default["default"](value, ONE_OF_KEY) && formValue) {
+            return score + getClosestMatchingOption(validator, rootSchema, formValue, get__default["default"](value, ONE_OF_KEY));
+          }
+          if (value.type === "object") {
+            return score + calculateIndexScore(validator, rootSchema, value, formValue || {});
+          }
+          if (value.type === guessType(formValue)) {
+            // If the types match, then we bump the score by one
+            var newScore = score + 1;
+            if (value["default"]) {
+              // If the schema contains a readonly default value score the value that matches the default higher and
+              // any non-matching value lower
+              newScore += formValue === value["default"] ? 1 : -1;
+            } else if (value["const"]) {
+              // If the schema contains a const value score the value that matches the default higher and
+              // any non-matching value lower
+              newScore += formValue === value["const"] ? 1 : -1;
+            }
+            // TODO eventually, deal with enums/arrays
+            return newScore;
+          }
+          return score;
+        }, 0);
+      } else if (isString__default["default"](schema.type) && schema.type === guessType(formData)) {
+        totalScore += 1;
+      }
+    }
+    return totalScore;
+  }
+  /** Determines which of the given `options` provided most closely matches the `formData`. Using
+   * `getFirstMatchingOption()` to match two schemas that differ only by the readOnly, default or const value of a field
+   * based on the `formData` and returns 0 when there is no match. Rather than passing in all the `options` at once to
+   * this utility, instead an array of valid option indexes is created by iterating over the list of options, call
+   * `getFirstMatchingOptions` with a list of one junk option and one good option, seeing if the good option is considered
+   * matched.
+   *
+   * Once the list of valid indexes is created, if there is only one valid index, just return it. Otherwise, if there are
+   * no valid indexes, then fill the valid indexes array with the indexes of all the options. Next, the index of the
+   * option with the highest score is determined by iterating over the list of valid options, calling
+   * `calculateIndexScore()` on each, comparing it against the current best score, and returning the index of the one that
+   * eventually has the best score.
+   *
+   * @param validator - An implementation of the `ValidatorType` interface that will be used when necessary
+   * @param rootSchema - The root JSON schema of the entire form
+   * @param formData - The form data associated with the schema
+   * @param options - The list of options that can be selected from
+   * @param [selectedOption=-1] - The index of the currently selected option, defaulted to -1 if not specified
+   * @returns - The index of the option that is the closest match to the `formData` or the `selectedOption` if no match
+   */
+  function getClosestMatchingOption(validator, rootSchema, formData, options, selectedOption) {
+    if (selectedOption === void 0) {
+      selectedOption = -1;
+    }
+    // Reduce the array of options down to a list of the indexes that are considered matching options
+    var allValidIndexes = options.reduce(function (validList, option, index) {
+      var testOptions = [JUNK_OPTION, option];
+      var match = getFirstMatchingOption(validator, formData, testOptions, rootSchema);
+      // The match is the real option, so add its index to list of valid indexes
+      if (match === 1) {
+        validList.push(index);
+      }
+      return validList;
+    }, []);
+    // There is only one valid index, so return it!
+    if (allValidIndexes.length === 1) {
+      return allValidIndexes[0];
+    }
+    if (!allValidIndexes.length) {
+      // No indexes were valid, so we'll score all the options, add all the indexes
+      times__default["default"](options.length, function (i) {
+        return allValidIndexes.push(i);
+      });
+    }
+    // Score all the options in the list of valid indexes and return the index with the best score
+    var _allValidIndexes$redu = allValidIndexes.reduce(function (scoreData, index) {
+        var bestScore = scoreData.bestScore;
+        var option = options[index];
+        if (has__default["default"](option, REF_KEY)) {
+          option = retrieveSchema(validator, option, rootSchema, formData);
+        }
+        var score = calculateIndexScore(validator, rootSchema, option, formData);
+        if (score > bestScore) {
+          return {
+            bestIndex: index,
+            bestScore: score
+          };
+        }
+        return scoreData;
+      }, {
+        bestIndex: selectedOption,
+        bestScore: 0
+      }),
+      bestIndex = _allValidIndexes$redu.bestIndex;
+    return bestIndex;
+  }
+
+  /** Detects whether the given `schema` contains fixed items. This is the case when `schema.items` is a non-empty array
+   * that only contains objects.
+   *
+   * @param schema - The schema in which to check for fixed items
+   * @returns - True if there are fixed items in the schema, false otherwise
+   */
+  function isFixedItems(schema) {
+    return Array.isArray(schema.items) && schema.items.length > 0 && schema.items.every(function (item) {
+      return isObject(item);
+    });
+  }
+
+  /** 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:
+   *   - 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
+   *   - when the array is not set in form data, the default is copied over
+   * - scalars are overwritten/set by form data
+   *
+   * @param [defaults] - The defaults to merge
+   * @param [formData] - The form data into which the defaults will be merged
+   * @returns - The resulting merged form data with defaults
+   */
+  function mergeDefaultsWithFormData(defaults, formData) {
+    if (Array.isArray(formData)) {
+      var defaultsArray = Array.isArray(defaults) ? defaults : [];
+      var mapped = formData.map(function (value, idx) {
+        if (defaultsArray[idx]) {
+          return mergeDefaultsWithFormData(defaultsArray[idx], value);
+        }
+        return value;
+      });
+      return mapped;
+    }
+    if (isObject(formData)) {
+      var acc = Object.assign({}, defaults); // Prevent mutation of source object.
+      return Object.keys(formData).reduce(function (acc, key) {
+        acc[key] = mergeDefaultsWithFormData(defaults ? get__default["default"](defaults, key) : {}, get__default["default"](formData, key));
+        return acc;
+      }, acc);
+    }
+    return formData;
+  }
+
+  /** Recursively merge deeply nested objects.
+   *
+   * @param obj1 - The first object to merge
+   * @param obj2 - The second object to merge
+   * @param [concatArrays=false] - Optional flag that, when true, will cause arrays to be concatenated. Use
+   *          "preventDuplicates" to merge arrays in a manner that prevents any duplicate entries from being merged.
+   *          NOTE: Uses shallow comparison for the duplicate checking.
+   * @returns - A new object that is the merge of the two given objects
+   */
+  function mergeObjects(obj1, obj2, concatArrays) {
+    if (concatArrays === void 0) {
+      concatArrays = false;
+    }
+    return Object.keys(obj2).reduce(function (acc, key) {
+      var left = obj1 ? obj1[key] : {},
+        right = obj2[key];
+      if (obj1 && key in obj1 && isObject(right)) {
+        acc[key] = mergeObjects(left, right, concatArrays);
+      } else if (concatArrays && Array.isArray(left) && Array.isArray(right)) {
+        var toMerge = right;
+        if (concatArrays === "preventDuplicates") {
+          toMerge = right.reduce(function (result, value) {
+            if (!left.includes(value)) {
+              result.push(value);
+            }
+            return result;
+          }, []);
+        }
+        acc[key] = left.concat(toMerge);
+      } else {
+        acc[key] = right;
+      }
+      return acc;
+    }, Object.assign({}, obj1)); // Prevent mutation of source object.
+  }
+
+  /** This function checks if the given `schema` matches a single constant value. This happens when either the schema has
+   * an `enum` array with a single value or there is a `const` defined.
+   *
+   * @param schema - The schema for a field
+   * @returns - True if the `schema` has a single constant value, false otherwise
+   */
+  function isConstant(schema) {
+    return Array.isArray(schema["enum"]) && schema["enum"].length === 1 || CONST_KEY in schema;
+  }
+
   /** Checks to see if the `schema` combination represents a select
    *
    * @param validator - An implementation of the `ValidatorType` interface that will be used when necessary
@@ -939,9 +1126,9 @@
         return computeDefaults(validator, itemSchema, Array.isArray(parentDefaults) ? parentDefaults[idx] : undefined, rootSchema, formData, includeUndefinedValues);
       });
     } else if (ONE_OF_KEY in schema) {
-      schema = schema.oneOf[getMatchingOption(validator, isEmpty__default["default"](formData) ? undefined : formData, schema.oneOf, rootSchema)];
+      schema = schema.oneOf[getClosestMatchingOption(validator, rootSchema, isEmpty__default["default"](formData) ? undefined : formData, schema.oneOf, 0)];
     } else if (ANY_OF_KEY in schema) {
-      schema = schema.anyOf[getMatchingOption(validator, isEmpty__default["default"](formData) ? undefined : formData, schema.anyOf, rootSchema)];
+      schema = schema.anyOf[getClosestMatchingOption(validator, rootSchema, isEmpty__default["default"](formData) ? undefined : formData, schema.anyOf, 0)];
     }
     // Not defaults defined for this node, fallback to generic typed ones.
     if (typeof defaults === "undefined") {
@@ -1133,6 +1320,169 @@
     };
   }
 
+  var NO_VALUE = /*#__PURE__*/Symbol("no Value");
+  /** Sanitize the `data` associated with the `oldSchema` so it is considered appropriate for the `newSchema`. If the new
+   * schema does not contain any properties, then `undefined` is returned to clear all the form data. Due to the nature
+   * of schemas, this sanitization happens recursively for nested objects of data. Also, any properties in the old schema
+   * that are non-existent in the new schema are set to `undefined`. The data sanitization process has the following flow:
+   *
+   * - If the new schema is an object that contains a `properties` object then:
+   *   - Create a `removeOldSchemaData` object, setting each key in the `oldSchema.properties` having `data` to undefined
+   *   - Create an empty `nestedData` object for use in the key filtering below:
+   *   - Iterate over each key in the `newSchema.properties` as follows:
+   *     - Get the `formValue` of the key from the `data`
+   *     - Get the `oldKeySchema` and `newKeyedSchema` for the key, defaulting to `{}` when it doesn't exist
+   *     - Retrieve the schema for any refs within each `oldKeySchema` and/or `newKeySchema`
+   *     - Get the types of the old and new keyed schemas and if the old doesn't exist or the old & new are the same then:
+   *       - If `removeOldSchemaData` has an entry for the key, delete it since the new schema has the same property
+   *       - If type of the key in the new schema is `object`:
+   *         - Store the value from the recursive `sanitizeDataForNewSchema` call in `nestedData[key]`
+   *       - Otherwise, check for default or const values:
+   *         - Get the old and new `default` values from the schema and check:
+   *           - If the new `default` value does not match the form value:
+   *             - If the old `default` value DOES match the form value, then:
+   *               - Replace `removeOldSchemaData[key]` with the new `default`
+   *               - Otherwise, if the new schema is `readOnly` then replace `removeOldSchemaData[key]` with undefined
+   *         - Get the old and new `const` values from the schema and check:
+   *           - If the new `const` value does not match the form value:
+   *           - If the old `const` value DOES match the form value, then:
+   *             - Replace `removeOldSchemaData[key]` with the new `const`
+   *             - Otherwise, replace `removeOldSchemaData[key]` with undefined
+   *   - Once all keys have been processed, return an object built as follows:
+   *     - `{ ...removeOldSchemaData, ...nestedData, ...pick(data, keysToKeep) }`
+   * - If the new and old schema types are array and the `data` is an array then:
+   *   - If the type of the old and new schema `items` are a non-array objects:
+   *     - Retrieve the schema for any refs within each `oldKeySchema.items` and/or `newKeySchema.items`
+   *     - If the `type`s of both items are the same (or the old does not have a type):
+   *       - If the type is "object", then:
+   *         - For each element in the `data` recursively sanitize the data, stopping at `maxItems` if specified
+   *       - Otherwise, just return the `data` removing any values after `maxItems` if it is set
+   *   - If the type of the old and new schema `items` are booleans of the same value, return `data` as is
+   * - Otherwise return `undefined`
+   *
+   * @param validator - An implementation of the `ValidatorType` interface that will be used when necessary
+   * @param rootSchema - The root JSON schema of the entire form
+   * @param [newSchema] - The new schema for which the data is being sanitized
+   * @param [oldSchema] - The old schema from which the data originated
+   * @param [data={}] - The form data associated with the schema, defaulting to an empty object when undefined
+   * @returns - The new form data, with all the fields uniquely associated with the old schema set
+   *      to `undefined`. Will return `undefined` if the new schema is not an object containing properties.
+   */
+  function sanitizeDataForNewSchema(validator, rootSchema, newSchema, oldSchema, data) {
+    if (data === void 0) {
+      data = {};
+    }
+    // By default, we will clear the form data
+    var newFormData;
+    // If the new schema is of type object and that object contains a list of properties
+    if (has__default["default"](newSchema, PROPERTIES_KEY)) {
+      // Create an object containing root-level keys in the old schema, setting each key to undefined to remove the data
+      var removeOldSchemaData = {};
+      if (has__default["default"](oldSchema, PROPERTIES_KEY)) {
+        var properties = get__default["default"](oldSchema, PROPERTIES_KEY, {});
+        Object.keys(properties).forEach(function (key) {
+          if (has__default["default"](data, key)) {
+            removeOldSchemaData[key] = undefined;
+          }
+        });
+      }
+      var keys = Object.keys(get__default["default"](newSchema, PROPERTIES_KEY, {}));
+      // Create a place to store nested data that will be a side-effect of the filter
+      var nestedData = {};
+      keys.forEach(function (key) {
+        var formValue = get__default["default"](data, key);
+        var oldKeyedSchema = get__default["default"](oldSchema, [PROPERTIES_KEY, key], {});
+        var newKeyedSchema = get__default["default"](newSchema, [PROPERTIES_KEY, key], {});
+        // Resolve the refs if they exist
+        if (has__default["default"](oldKeyedSchema, REF_KEY)) {
+          oldKeyedSchema = retrieveSchema(validator, oldKeyedSchema, rootSchema, formValue);
+        }
+        if (has__default["default"](newKeyedSchema, REF_KEY)) {
+          newKeyedSchema = retrieveSchema(validator, newKeyedSchema, rootSchema, formValue);
+        }
+        // Now get types and see if they are the same
+        var oldSchemaTypeForKey = get__default["default"](oldKeyedSchema, "type");
+        var newSchemaTypeForKey = get__default["default"](newKeyedSchema, "type");
+        // Check if the old option has the same key with the same type
+        if (!oldSchemaTypeForKey || oldSchemaTypeForKey === newSchemaTypeForKey) {
+          if (has__default["default"](removeOldSchemaData, key)) {
+            // SIDE-EFFECT: remove the undefined value for a key that has the same type between the old and new schemas
+            delete removeOldSchemaData[key];
+          }
+          // If it is an object, we'll recurse and store the resulting sanitized data for the key
+          if (newSchemaTypeForKey === "object" || newSchemaTypeForKey === "array" && Array.isArray(formValue)) {
+            // SIDE-EFFECT: process the new schema type of object recursively to save iterations
+            var itemData = sanitizeDataForNewSchema(validator, rootSchema, newKeyedSchema, oldKeyedSchema, formValue);
+            if (itemData !== undefined || newSchemaTypeForKey === "array") {
+              // only put undefined values for the array type and not the object type
+              nestedData[key] = itemData;
+            }
+          } else {
+            // Ok, the non-object types match, let's make sure that a default or a const of a different value is replaced
+            // with the new default or const. This allows the case where two schemas differ that only by the default/const
+            // value to be properly selected
+            var newOptionDefault = get__default["default"](newKeyedSchema, "default", NO_VALUE);
+            var oldOptionDefault = get__default["default"](oldKeyedSchema, "default", NO_VALUE);
+            if (newOptionDefault !== NO_VALUE && newOptionDefault !== formValue) {
+              if (oldOptionDefault === formValue) {
+                // If the old default matches the formValue, we'll update the new value to match the new default
+                removeOldSchemaData[key] = newOptionDefault;
+              } else if (get__default["default"](newKeyedSchema, "readOnly") === true) {
+                // If the new schema has the default set to read-only, treat it like a const and remove the value
+                removeOldSchemaData[key] = undefined;
+              }
+            }
+            var newOptionConst = get__default["default"](newKeyedSchema, "const", NO_VALUE);
+            var oldOptionConst = get__default["default"](oldKeyedSchema, "const", NO_VALUE);
+            if (newOptionConst !== NO_VALUE && newOptionConst !== formValue) {
+              // Since this is a const, if the old value matches, replace the value with the new const otherwise clear it
+              removeOldSchemaData[key] = oldOptionConst === formValue ? newOptionConst : undefined;
+            }
+          }
+        }
+      });
+      newFormData = _extends({}, data, removeOldSchemaData, nestedData);
+      // First apply removing the old schema data, then apply the nested data, then apply the old data keys to keep
+    } else if (get__default["default"](oldSchema, "type") === "array" && get__default["default"](newSchema, "type") === "array" && Array.isArray(data)) {
+      var oldSchemaItems = get__default["default"](oldSchema, "items");
+      var newSchemaItems = get__default["default"](newSchema, "items");
+      // If any of the array types `items` are arrays (remember arrays are objects) then we'll just drop the data
+      // Eventually, we may want to deal with when either of the `items` are arrays since those tuple validations
+      if (typeof oldSchemaItems === "object" && typeof newSchemaItems === "object" && !Array.isArray(oldSchemaItems) && !Array.isArray(newSchemaItems)) {
+        if (has__default["default"](oldSchemaItems, REF_KEY)) {
+          oldSchemaItems = retrieveSchema(validator, oldSchemaItems, rootSchema, data);
+        }
+        if (has__default["default"](newSchemaItems, REF_KEY)) {
+          newSchemaItems = retrieveSchema(validator, newSchemaItems, rootSchema, data);
+        }
+        // Now get types and see if they are the same
+        var oldSchemaType = get__default["default"](oldSchemaItems, "type");
+        var newSchemaType = get__default["default"](newSchemaItems, "type");
+        // Check if the old option has the same key with the same type
+        if (!oldSchemaType || oldSchemaType === newSchemaType) {
+          var maxItems = get__default["default"](newSchema, "maxItems", -1);
+          if (newSchemaType === "object") {
+            newFormData = data.reduce(function (newValue, aValue) {
+              var itemValue = sanitizeDataForNewSchema(validator, rootSchema, newSchemaItems, oldSchemaItems, aValue);
+              if (itemValue !== undefined && (maxItems < 0 || newValue.length < maxItems)) {
+                newValue.push(itemValue);
+              }
+              return newValue;
+            }, []);
+          } else {
+            newFormData = maxItems > 0 && data.length > maxItems ? data.slice(0, maxItems) : data;
+          }
+        }
+      } else if (typeof oldSchemaItems === "boolean" && typeof newSchemaItems === "boolean" && oldSchemaItems === newSchemaItems) {
+        // If they are both booleans and have the same value just return the data as is otherwise fall-thru to undefined
+        newFormData = data;
+      }
+      // Also probably want to deal with `prefixItems` as tuples with the latest 2020 draft
+    }
+
+    return newFormData;
+  }
+
   /** Generates an `IdSchema` object for the `schema`, recursively
    *
    * @param validator - An implementation of the `ValidatorType` interface that will be used when necessary
@@ -1278,11 +1628,37 @@
     _proto.getDisplayLabel = function getDisplayLabel$1(schema, uiSchema) {
       return getDisplayLabel(this.validator, schema, uiSchema, this.rootSchema);
     }
+    /** Determines which of the given `options` provided most closely matches the `formData`.
+     * Returns the index of the option that is valid and is the closest match, or 0 if there is no match.
+     *
+     * The closest match is determined using the number of matching properties, and more heavily favors options with
+     * matching readOnly, default, or const values.
+     *
+     * @param formData - The form data associated with the schema
+     * @param options - The list of options that can be selected from
+     * @param [selectedOption] - The index of the currently selected option, defaulted to -1 if not specified
+     * @returns - The index of the option that is the closest match to the `formData` or the `selectedOption` if no match
+     */;
+    _proto.getClosestMatchingOption = function getClosestMatchingOption$1(formData, options, selectedOption) {
+      return getClosestMatchingOption(this.validator, this.rootSchema, formData, options, selectedOption);
+    }
+    /** Given the `formData` and list of `options`, attempts to find the index of the first option that matches the data.
+     * Always returns the first option if there is nothing that matches.
+     *
+     * @param formData - The current formData, if any, used to figure out a match
+     * @param options - The list of options to find a matching options from
+     * @returns - The firstindex of the matched option or 0 if none is available
+     */;
+    _proto.getFirstMatchingOption = function getFirstMatchingOption$1(formData, options) {
+      return getFirstMatchingOption(this.validator, formData, options, this.rootSchema);
+    }
     /** Given the `formData` and list of `options`, attempts to find the index of the option that best matches the data.
+     * Deprecated, use `getFirstMatchingOption()` instead.
      *
      * @param formData - The current formData, if any, onto which to provide any missing defaults
      * @param options - The list of options to find a matching options from
      * @returns - The index of the matched option or 0 if none is available
+     * @deprecated
      */;
     _proto.getMatchingOption = function getMatchingOption$1(formData, options) {
       return getMatchingOption(this.validator, formData, options, this.rootSchema);
@@ -1335,6 +1711,20 @@
     _proto.retrieveSchema = function retrieveSchema$1(schema, rawFormData) {
       return retrieveSchema(this.validator, schema, this.rootSchema, rawFormData);
     }
+    /** Sanitize the `data` associated with the `oldSchema` so it is considered appropriate for the `newSchema`. If the
+     * new schema does not contain any properties, then `undefined` is returned to clear all the form data. Due to the
+     * nature of schemas, this sanitization happens recursively for nested objects of data. Also, any properties in the
+     * old schemas that are non-existent in the new schema are set to `undefined`.
+     *
+     * @param [newSchema] - The new schema for which the data is being sanitized
+     * @param [oldSchema] - The old schema from which the data originated
+     * @param [data={}] - The form data associated with the schema, defaulting to an empty object when undefined
+     * @returns - The new form data, with all the fields uniquely associated with the old schema set
+     *      to `undefined`. Will return `undefined` if the new schema is not an object containing properties.
+     */;
+    _proto.sanitizeDataForNewSchema = function sanitizeDataForNewSchema$1(newSchema, oldSchema, data) {
+      return sanitizeDataForNewSchema(this.validator, this.rootSchema, newSchema, oldSchema, data);
+    }
     /** Generates an `IdSchema` object for the `schema`, recursively
      *
      * @param schema - The schema for which the display label flag is desired
@@ -1418,6 +1808,43 @@
     };
   }
 
+  /** Removes the `value` from the currently `selected` list of values
+   *
+   * @param value - The value to be removed from the selected list
+   * @param selected - The current list of selected values
+   * @returns - The updated `selected` list with the `value` removed from it
+   */
+  function enumOptionsDeselectValue(value, selected) {
+    return selected.filter(function (v) {
+      return v !== value;
+    });
+  }
+
+  /** Add the `value` to the list of `selected` values in the proper order as defined by `allEnumOptions`
+   *
+   * @param value - The value that should be selected
+   * @param selected - The current list of selected values
+   * @param allEnumOptions - The list of all the known enumOptions
+   * @returns - The updated list of selected enum values with `value` added to it in the proper location
+   */
+  function enumOptionsSelectValue(value, selected, allEnumOptions) {
+    if (allEnumOptions === void 0) {
+      allEnumOptions = [];
+    }
+    var all = allEnumOptions.map(function (_ref) {
+      var value = _ref.value;
+      return value;
+    });
+    var at = all.indexOf(value);
+    // If location of the value is not in the list of all enum values, just put it at the end
+    var updated = at === -1 ? selected.concat(value) : selected.slice(0, at).concat(value, selected.slice(at));
+    // As inserting values at predefined index positions doesn't work with empty
+    // arrays, we need to reorder the updated selection to match the initial order
+    return updated.sort(function (a, b) {
+      return Number(all.indexOf(a) > all.indexOf(b));
+    });
+  }
+
   /** The `ErrorSchemaBuilder<T>` is used to build an `ErrorSchema<T>` since the definition of the `ErrorSchema` type is
    * designed for reading information rather than writing it. Use this class to add, replace or clear errors in an error
    * schema by using either dotted path or an array of path names. Once you are done building the `ErrorSchema`, you can
@@ -1777,6 +2204,80 @@
     }
   }
 
+  /** Generates a consistent `id` pattern for a given `id` and a `suffix`
+   *
+   * @param id - Either simple string id or an IdSchema from which to extract it
+   * @param suffix - The suffix to append to the id
+   */
+  function idGenerator(id, suffix) {
+    var theId = isString__default["default"](id) ? id : id[ID_KEY];
+    return theId + "__" + suffix;
+  }
+  /** Return a consistent `id` for the field description element
+   *
+   * @param id - Either simple string id or an IdSchema from which to extract it
+   * @returns - The consistent id for the field description element from the given `id`
+   */
+  function descriptionId(id) {
+    return idGenerator(id, "description");
+  }
+  /** Return a consistent `id` for the field error element
+   *
+   * @param id - Either simple string id or an IdSchema from which to extract it
+   * @returns - The consistent id for the field error element from the given `id`
+   */
+  function errorId(id) {
+    return idGenerator(id, "error");
+  }
+  /** Return a consistent `id` for the field examples element
+   *
+   * @param id - Either simple string id or an IdSchema from which to extract it
+   * @returns - The consistent id for the field examples element from the given `id`
+   */
+  function examplesId(id) {
+    return idGenerator(id, "examples");
+  }
+  /** Return a consistent `id` for the field help element
+   *
+   * @param id - Either simple string id or an IdSchema from which to extract it
+   * @returns - The consistent id for the field help element from the given `id`
+   */
+  function helpId(id) {
+    return idGenerator(id, "help");
+  }
+  /** Return a consistent `id` for the field title element
+   *
+   * @param id - Either simple string id or an IdSchema from which to extract it
+   * @returns - The consistent id for the field title element from the given `id`
+   */
+  function titleId(id) {
+    return idGenerator(id, "title");
+  }
+  /** Return a list of element ids that contain additional information about the field that can be used to as the aria
+   * description of the field. This is correctly omitting `titleId` which would be "labeling" rather than "describing" the
+   * element.
+   *
+   * @param id - Either simple string id or an IdSchema from which to extract it
+   * @param [includeExamples=false] - Optional flag, if true, will add the `examplesId` into the list
+   * @returns - The string containing the list of ids for use in an `aria-describedBy` attribute
+   */
+  function ariaDescribedByIds(id, includeExamples) {
+    if (includeExamples === void 0) {
+      includeExamples = false;
+    }
+    var examples = includeExamples ? " " + examplesId(id) : "";
+    return errorId(id) + " " + descriptionId(id) + " " + helpId(id) + examples;
+  }
+  /** Return a consistent `id` for the `option`s of a `Radio` or `Checkboxes` widget
+   *
+   * @param id - The id of the parent component for the option
+   * @param option - The option for which the id is desired
+   * @returns - An id for the option based on the parent `id`
+   */
+  function optionId(id, option) {
+    return id + "-" + option.value;
+  }
+
   /** Converts a local Date string into a UTC date string
    *
    * @param dateString - The string representation of a date as accepted by the `Date()` constructor
@@ -2102,14 +2603,22 @@
   exports.UI_OPTIONS_KEY = UI_OPTIONS_KEY;
   exports.UI_WIDGET_KEY = UI_WIDGET_KEY;
   exports.allowAdditionalItems = allowAdditionalItems;
+  exports.ariaDescribedByIds = ariaDescribedByIds;
   exports.asNumber = asNumber;
   exports.canExpand = canExpand;
   exports.createSchemaUtils = createSchemaUtils;
   exports.dataURItoBlob = dataURItoBlob;
   exports.deepEquals = deepEquals;
+  exports.descriptionId = descriptionId;
+  exports.enumOptionsDeselectValue = enumOptionsDeselectValue;
+  exports.enumOptionsSelectValue = enumOptionsSelectValue;
+  exports.errorId = errorId;
+  exports.examplesId = examplesId;
   exports.findSchemaDefinition = findSchemaDefinition;
+  exports.getClosestMatchingOption = getClosestMatchingOption;
   exports.getDefaultFormState = getDefaultFormState;
   exports.getDisplayLabel = getDisplayLabel;
+  exports.getFirstMatchingOption = getFirstMatchingOption;
   exports.getInputProps = getInputProps;
   exports.getMatchingOption = getMatchingOption;
   exports.getSchemaType = getSchemaType;
@@ -2119,6 +2628,7 @@
   exports.getWidget = getWidget;
   exports.guessType = guessType;
   exports.hasWidget = hasWidget;
+  exports.helpId = helpId;
   exports.isConstant = isConstant;
   exports.isCustomWidget = isCustomWidget;
   exports.isFilesArray = isFilesArray;
@@ -2131,6 +2641,7 @@
   exports.mergeObjects = mergeObjects;
   exports.mergeSchemas = mergeSchemas;
   exports.mergeValidationData = mergeValidationData;
+  exports.optionId = optionId;
   exports.optionsList = optionsList;
   exports.orderProperties = orderProperties;
   exports.pad = pad;
@@ -2138,8 +2649,10 @@
   exports.processSelectValue = processSelectValue;
   exports.rangeSpec = rangeSpec;
   exports.retrieveSchema = retrieveSchema;
+  exports.sanitizeDataForNewSchema = sanitizeDataForNewSchema;
   exports.schemaRequiresTrueValue = schemaRequiresTrueValue;
   exports.shouldRender = shouldRender;
+  exports.titleId = titleId;
   exports.toConstant = toConstant;
   exports.toDateString = toDateString;
   exports.toIdSchema = toIdSchema;