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

package/dist/index.d.ts

@@ -242,11 +242,11 @@ interface FieldProps<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends
     /** The tree of unique ids for every child field */
     idSchema: IdSchema<T>;
     /** The data for this field */
-    formData: T;
+    formData?: T;
     /** The tree of errors for this field and its children */
     errorSchema?: ErrorSchema<T>;
     /** The field change event handler; called with the updated form data and an optional `ErrorSchema` */
-    onChange: (newFormData: T, es?: ErrorSchema<T>, id?: string) => any;
+    onChange: (newFormData: T | undefined, es?: ErrorSchema<T>, id?: string) => any;
     /** The input blur event handler; call it with the field id and value */
     onBlur: (id: string, value: any) => void;
     /** The input focus event handler; call it with the field id and value */
@@ -319,7 +319,7 @@ type FieldTemplateProps<T = any, S extends StrictRJSFSchema = RJSFSchema, F exte
     /** The `formContext` object that was passed to `Form` */
     formContext?: F;
     /** The formData for this field */
-    formData: T;
+    formData?: T;
     /** The value change event handler; Can be called with a new value to change the value for this field */
     onChange: FieldProps["onChange"];
     /** The key change event handler; Called when the key associated with a field is changed for an additionalProperty */
@@ -450,7 +450,7 @@ type ArrayFieldTemplateProps<T = any, S extends StrictRJSFSchema = RJSFSchema, F
     /** The `formContext` object that was passed to Form */
     formContext?: F;
     /** The formData for this array */
-    formData: T;
+    formData?: T;
     /** An array of strings listing all generated error messages from encountered errors for this widget */
     rawErrors?: string[];
     /** The `registry` object */
@@ -494,7 +494,7 @@ type ObjectFieldTemplateProps<T = any, S extends StrictRJSFSchema = RJSFSchema,
     /** An object containing the id for this object & ids for its properties */
     idSchema: IdSchema<T>;
     /** The form data for the object */
-    formData: T;
+    formData?: T;
     /** The `formContext` object that was passed to Form */
     formContext?: F;
     /** The `registry` object */
@@ -678,7 +678,7 @@ type UiSchema<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormCo
 /** A `CustomValidator` function takes in a `formData`, `errors` and `uiSchema` objects and returns the given `errors`
  * object back, while potentially adding additional messages to the `errors`
  */
-type CustomValidator<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any> = (formData: T, errors: FormValidation<T>, uiSchema?: UiSchema<T, S, F>) => FormValidation<T>;
+type CustomValidator<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any> = (formData: T | undefined, errors: FormValidation<T>, uiSchema?: UiSchema<T, S, F>) => FormValidation<T>;
 /** An `ErrorTransformer` function will take in a list of `errors` & a `uiSchema` and potentially return a
  * transformation of those errors in what ever way it deems necessary
  */
@@ -720,7 +720,7 @@ interface ValidatorType<T = any, S extends StrictRJSFSchema = RJSFSchema, F exte
      * @param formData - The form data to validate
      * @param rootSchema - The root schema used to provide $ref resolutions
      */
-    isValid(schema: S, formData: T, rootSchema: S): boolean;
+    isValid(schema: S, formData: T | undefined, rootSchema: S): boolean;
     /** Runs the pure validation of the `schema` and `formData` without any of the RJSF functionality. Provided for use
      * by the playground. Returns the `errors` from the validation
      *
@@ -771,13 +771,35 @@ interface SchemaUtilsType<T = any, S extends StrictRJSFSchema = RJSFSchema, F ex
      * @returns - True if the label should be displayed or false if it should not
      */
     getDisplayLabel(schema: S, uiSchema?: UiSchema<T, S, F>): boolean;
+    /** 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
+     */
+    getClosestMatchingOption(formData: T | undefined, options: S[], selectedOption?: number): number;
+    /** 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
+     */
+    getFirstMatchingOption(formData: T | undefined, options: S[]): number;
     /** 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
      */
-    getMatchingOption(formData: T, options: S[]): number;
+    getMatchingOption(formData: T | undefined, options: S[]): number;
     /** Checks to see if the `schema` and `uiSchema` combination represents an array of files
      *
      * @param schema - The schema for which check for array of files flag is desired
@@ -816,6 +838,18 @@ interface SchemaUtilsType<T = any, S extends StrictRJSFSchema = RJSFSchema, F ex
      * @returns - The schema having its conditions, additional properties, references and dependencies resolved
      */
     retrieveSchema(schema: S, formData?: T): S;
+    /** 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`.
+     *
+     * @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 of the fields uniquely associated with the old schema set
+     *      to `undefined`. Will return `undefined` if the new schema is not an object containing properties.
+     */
+    sanitizeDataForNewSchema(newSchema?: S, oldSchema?: S, data?: any): T;
     /** Generates an `IdSchema` object for the `schema`, recursively
      *
      * @param schema - The schema for which the display label flag is desired
@@ -1157,11 +1191,11 @@ declare function localToUTC(dateString: string): string | undefined;
  *   - 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
+ * @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
  */
-declare function mergeDefaultsWithFormData<T = any>(defaults: T, formData: T): T;
+declare function mergeDefaultsWithFormData<T = any>(defaults?: T, formData?: T): T | undefined;
 
 /** Recursively merge deeply nested objects.
  *
@@ -1341,13 +1375,48 @@ declare function getDefaultFormState<T = any, S extends StrictRJSFSchema = RJSFS
  */
 declare function getDisplayLabel<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any>(validator: ValidatorType<T, S, F>, schema: S, uiSchema?: UiSchema<T, S, F>, rootSchema?: S): boolean;
 
+/** 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
+ */
+declare function getClosestMatchingOption<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any>(validator: ValidatorType<T, S, F>, rootSchema: S, formData: T | undefined, options: S[], selectedOption?: number): number;
+
+/** 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
+ */
+declare function getFirstMatchingOption<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any>(validator: ValidatorType<T, S, F>, formData: T | undefined, options: S[], rootSchema: S): number;
+
 /** 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
  */
 declare function getMatchingOption<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any>(validator: ValidatorType<T, S, F>, formData: T | undefined, options: S[], rootSchema: S): number;
 
@@ -1403,6 +1472,55 @@ declare function mergeValidationData<T = any, S extends StrictRJSFSchema = RJSFS
  */
 declare function retrieveSchema<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any>(validator: ValidatorType<T, S, F>, schema: S, rootSchema?: S, rawFormData?: T): S;
 
+/** 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.
+ */
+declare function sanitizeDataForNewSchema<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any>(validator: ValidatorType<T, S, F>, rootSchema: S, newSchema?: S, oldSchema?: S, data?: any): T;
+
 /** Generates an `IdSchema` object for the `schema`, recursively
  *
  * @param validator - An implementation of the `ValidatorType` interface that will be used when necessary
@@ -1427,4 +1545,4 @@ declare function toIdSchema<T = any, S extends StrictRJSFSchema = RJSFSchema, F
  */
 declare function toPathSchema<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any>(validator: ValidatorType<T, S, F>, schema: S, name?: string, rootSchema?: S, formData?: T): PathSchema<T>;
 
-export { ADDITIONAL_PROPERTIES_KEY, ADDITIONAL_PROPERTY_FLAG, ALL_OF_KEY, ANY_OF_KEY, ArrayFieldDescriptionProps, ArrayFieldTemplateItemType, ArrayFieldTemplateProps, ArrayFieldTitleProps, CONST_KEY, CustomValidator, DEFAULT_KEY, DEFINITIONS_KEY, DEPENDENCIES_KEY, DateObject, DescriptionFieldProps, ENUM_KEY, ERRORS_KEY, EnumOptionsType, ErrorListProps, ErrorSchema, ErrorSchemaBuilder, ErrorTransformer, Field, FieldError, FieldErrorProps, FieldErrors, FieldHelpProps, FieldId, FieldPath, FieldProps, FieldTemplateProps, FieldValidation, FormContextType, FormValidation, GenericObjectType, ID_KEY, ITEMS_KEY, IconButtonProps, IdSchema, InputPropsType, NAME_KEY, ONE_OF_KEY, ObjectFieldTemplatePropertyType, ObjectFieldTemplateProps, PROPERTIES_KEY, PathSchema, REF_KEY, REQUIRED_KEY, RJSFSchema, RJSFValidationError, RJSF_ADDITONAL_PROPERTIES_FLAG, RangeSpecType, Registry, RegistryFieldsType, RegistryWidgetsType, SUBMIT_BTN_OPTIONS_KEY, SchemaUtilsType, StrictRJSFSchema, SubmitButtonProps, TemplatesType, TitleFieldProps, UIOptionsType, UISchemaSubmitButtonOptions, UI_FIELD_KEY, UI_OPTIONS_KEY, UI_WIDGET_KEY, UiSchema, UnsupportedFieldProps, ValidationData, ValidatorType, Widget, WidgetProps, WrapIfAdditionalTemplateProps, allowAdditionalItems, ariaDescribedByIds, asNumber, canExpand, createSchemaUtils, dataURItoBlob, deepEquals, descriptionId, enumOptionsDeselectValue, enumOptionsSelectValue, errorId, examplesId, findSchemaDefinition, getDefaultFormState, getDisplayLabel, getInputProps, getMatchingOption, getSchemaType, getSubmitButtonOptions, getTemplate, getUiOptions, getWidget, guessType, hasWidget, helpId, isConstant, isCustomWidget, isFilesArray, isFixedItems, isMultiSelect, isObject, isSelect, localToUTC, mergeDefaultsWithFormData, mergeObjects, mergeSchemas, mergeValidationData, optionId, optionsList, orderProperties, pad, parseDateString, processSelectValue, rangeSpec, retrieveSchema, schemaRequiresTrueValue, shouldRender, titleId, toConstant, toDateString, toIdSchema, toPathSchema, utcToLocal };
+export { ADDITIONAL_PROPERTIES_KEY, ADDITIONAL_PROPERTY_FLAG, ALL_OF_KEY, ANY_OF_KEY, ArrayFieldDescriptionProps, ArrayFieldTemplateItemType, ArrayFieldTemplateProps, ArrayFieldTitleProps, CONST_KEY, CustomValidator, DEFAULT_KEY, DEFINITIONS_KEY, DEPENDENCIES_KEY, DateObject, DescriptionFieldProps, ENUM_KEY, ERRORS_KEY, EnumOptionsType, ErrorListProps, ErrorSchema, ErrorSchemaBuilder, ErrorTransformer, Field, FieldError, FieldErrorProps, FieldErrors, FieldHelpProps, FieldId, FieldPath, FieldProps, FieldTemplateProps, FieldValidation, FormContextType, FormValidation, GenericObjectType, ID_KEY, ITEMS_KEY, IconButtonProps, IdSchema, InputPropsType, NAME_KEY, ONE_OF_KEY, ObjectFieldTemplatePropertyType, ObjectFieldTemplateProps, PROPERTIES_KEY, PathSchema, REF_KEY, REQUIRED_KEY, RJSFSchema, RJSFValidationError, RJSF_ADDITONAL_PROPERTIES_FLAG, RangeSpecType, Registry, RegistryFieldsType, RegistryWidgetsType, SUBMIT_BTN_OPTIONS_KEY, SchemaUtilsType, StrictRJSFSchema, SubmitButtonProps, TemplatesType, TitleFieldProps, UIOptionsType, UISchemaSubmitButtonOptions, UI_FIELD_KEY, UI_OPTIONS_KEY, UI_WIDGET_KEY, UiSchema, UnsupportedFieldProps, ValidationData, ValidatorType, Widget, WidgetProps, WrapIfAdditionalTemplateProps, allowAdditionalItems, ariaDescribedByIds, asNumber, canExpand, createSchemaUtils, dataURItoBlob, deepEquals, descriptionId, enumOptionsDeselectValue, enumOptionsSelectValue, errorId, examplesId, findSchemaDefinition, getClosestMatchingOption, getDefaultFormState, getDisplayLabel, getFirstMatchingOption, getInputProps, getMatchingOption, getSchemaType, getSubmitButtonOptions, getTemplate, getUiOptions, getWidget, guessType, hasWidget, helpId, isConstant, isCustomWidget, isFilesArray, isFixedItems, isMultiSelect, isObject, isSelect, localToUTC, mergeDefaultsWithFormData, mergeObjects, mergeSchemas, mergeValidationData, optionId, optionsList, orderProperties, pad, parseDateString, processSelectValue, rangeSpec, retrieveSchema, sanitizeDataForNewSchema, schemaRequiresTrueValue, shouldRender, titleId, toConstant, toDateString, toIdSchema, toPathSchema, utcToLocal };