@rjsf/utils 6.0.0-beta.20 → 6.0.0-beta.22

package/src/types.ts

@@ -2,6 +2,7 @@ import type {
   ButtonHTMLAttributes,
   ChangeEvent,
   ComponentType,
+  FocusEvent,
   HTMLAttributes,
   ReactElement,
   ReactNode,
@@ -35,6 +36,9 @@ export type FormContextType = GenericObjectType;
  */
 export type TestIdShape = Record<string, string>;
 
+/** Function to generate HTML name attributes from path segments */
+export type NameGeneratorFunction = (path: FieldPathList, idPrefix: string, isMultiValue?: boolean) => string;
+
 /** Experimental feature that specifies the Array `minItems` default form state behavior
  */
 export type Experimental_ArrayMinItems = {
@@ -175,6 +179,8 @@ export type FieldPathId = {
   $id: string;
   /** The path for a field */
   path: FieldPathList;
+  /** The optional HTML name attribute for a field, generated by nameGenerator if provided */
+  name?: string;
 };
 
 /** Type describing a name used for a field in the `PathSchema` */
@@ -327,9 +333,9 @@ export type TemplatesType<T = any, S extends StrictRJSFSchema = RJSFSchema, F ex
   /** The template to use while rendering the description for an array field */
   ArrayFieldDescriptionTemplate: ComponentType<ArrayFieldDescriptionProps<T, S, F>>;
   /** The template to use while rendering the buttons for an item in an array field */
-  ArrayFieldItemButtonsTemplate: ComponentType<ArrayFieldItemButtonsTemplateType<T, S, F>>;
+  ArrayFieldItemButtonsTemplate: ComponentType<ArrayFieldItemButtonsTemplateProps<T, S, F>>;
   /** The template to use while rendering an item in an array field */
-  ArrayFieldItemTemplate: ComponentType<ArrayFieldItemTemplateType<T, S, F>>;
+  ArrayFieldItemTemplate: ComponentType<ArrayFieldItemTemplateProps<T, S, F>>;
   /** The template to use while rendering the title for an array field */
   ArrayFieldTitleTemplate: ComponentType<ArrayFieldTitleProps<T, S, F>>;
   /** The template to use while rendering the standard html input */
@@ -350,6 +356,8 @@ export type TemplatesType<T = any, S extends StrictRJSFSchema = RJSFSchema, F ex
   MultiSchemaFieldTemplate: ComponentType<MultiSchemaFieldTemplateProps<T, S, F>>;
   /** The template to use while rendering an object */
   ObjectFieldTemplate: ComponentType<ObjectFieldTemplateProps<T, S, F>>;
+  /** The template to use while rendering the Optional Data field controls */
+  OptionalDataControlsTemplate: ComponentType<OptionalDataControlsTemplateProps<T, S, F>>;
   /** The template to use for rendering the title of a field */
   TitleFieldTemplate: ComponentType<TitleFieldProps<T, S, F>>;
   /** The template to use for rendering information about an unsupported field type in the schema */
@@ -398,6 +406,10 @@ export type GlobalUISchemaOptions = GenericObjectType & {
   /** Enables the displaying of description text that contains markdown
    */
   enableMarkdownInDescription?: boolean;
+  /** Enables the rendering of the Optional Data Field UI for specific types of schemas, either `object`, `array` or
+   * both. To disable the Optional Data Field UI for a specific field, provide an empty array within the UI schema.
+   */
+  enableOptionalDataFieldForType?: ('object' | 'array')[];
 };
 
 /** The set of options from the `Form` that will be available on the `Registry` for use in everywhere the `registry` is
@@ -414,6 +426,11 @@ export type GlobalFormOptions = {
   readonly idSeparator: string;
   /** The component update strategy used by the Form and its fields for performance optimization */
   readonly experimental_componentUpdateStrategy?: 'customDeep' | 'shallow' | 'always';
+  /** Optional function to generate custom HTML name attributes for form elements. Receives the field path segments
+   * and element type (object or array), and returns a custom name string. This allows backends like PHP/Rails
+   * (`root[tasks][0][title]`) or Django (`root__tasks-0__title`) to receive form data in their expected format.
+   */
+  readonly nameGenerator?: NameGeneratorFunction;
 };
 
 /** The object containing the registered core, theme and custom fields and widgets as well as the root schema, form
@@ -541,10 +558,15 @@ export type FieldTemplateProps<
   formData?: T;
   /** The value change event handler; Can be called with a new value to change the value for this field */
   onChange: FieldProps<T, S, F>['onChange'];
-  /** The key change event handler; Called when the key associated with a field is changed for an additionalProperty */
-  onKeyChange: (value: string) => () => void;
-  /** The property drop/removal event handler; Called when a field is removed in an additionalProperty context */
-  onDropPropertyClick: (value: string) => () => void;
+  /** Callback used to handle the changing of an additional property key's name with the new value
+   */
+  onKeyRename: (newKey: string) => void;
+  /** Callback used to handle the changing of an additional property key's name when the input is blurred. The event's
+   * target's value will be used as the new value. Its a wrapper callback around `onKeyRename`
+   */
+  onKeyRenameBlur: (event: FocusEvent<HTMLInputElement>) => void;
+  /** Callback used to handle the removal of the additionalProperty */
+  onRemoveProperty: () => void;
 };
 
 /** The properties that are passed to the `UnsupportedFieldTemplate` implementation */
@@ -571,6 +593,8 @@ export type TitleFieldProps<
   title: string;
   /** A boolean value stating if the field is required */
   required?: boolean;
+  /** Add optional data control */
+  optionalDataControl?: ReactNode;
 };
 
 /** The properties that are passed to a `DescriptionFieldTemplate` implementation */
@@ -595,6 +619,8 @@ export type ArrayFieldTitleProps<
   title?: string;
   /** The FieldPathId of the field in the hierarchy */
   fieldPathId: FieldPathId;
+  /** Add optional data control */
+  optionalDataControl?: ReactNode;
 };
 
 /** The properties that are passed to a `ArrayFieldDescriptionTemplate` implementation */
@@ -610,7 +636,7 @@ export type ArrayFieldDescriptionProps<
 };
 
 /** The properties of the buttons to render for each element in the ArrayFieldTemplateProps.items array */
-export type ArrayFieldItemButtonsTemplateType<
+export type ArrayFieldItemButtonsTemplateProps<
   T = any,
   S extends StrictRJSFSchema = RJSFSchema,
   F extends FormContextType = any,
@@ -637,20 +663,22 @@ export type ArrayFieldItemButtonsTemplateType<
   index: number;
   /** A number stating the total number `items` in the array */
   totalItems: number;
-  /** Returns a function that adds a new item at `index` */
-  onAddIndexClick: (index: number) => (event?: any) => void;
-  /** Returns a function that copies the item at `index` into the position at `index + 1` */
-  onCopyIndexClick: (index: number) => (event?: any) => void;
-  /** Returns a function that removes the item at `index` */
-  onDropIndexClick: (index: number) => (event?: any) => void;
-  /** Returns a function that swaps the items at `index` with `newIndex` */
-  onReorderClick: (index: number, newIndex: number) => (event?: any) => void;
+  /** Callback function that adds a new item below this item */
+  onAddItem: (event?: any) => void;
+  /** Callback function that copies this item below itself */
+  onCopyItem: (event?: any) => void;
+  /** Callback function that moves the item up one spot in the list */
+  onMoveUpItem: (event?: any) => void;
+  /** Callback function that moves the item down one spot in the list */
+  onMoveDownItem: (event?: any) => void;
+  /** Callback function that removes the item from the list */
+  onRemoveItem: (event?: any) => void;
   /** A boolean value stating if the array item is read-only */
   readonly?: boolean;
 };
 
-/** The properties of each element in the ArrayFieldTemplateProps.items array */
-export type ArrayFieldItemTemplateType<
+/** The properties used to render the ArrayFieldItemTemplate */
+export type ArrayFieldItemTemplateProps<
   T = any,
   S extends StrictRJSFSchema = RJSFSchema,
   F extends FormContextType = any,
@@ -658,7 +686,7 @@ export type ArrayFieldItemTemplateType<
   /** The html for the item's content */
   children: ReactNode;
   /** The props to pass to the `ArrayFieldItemButtonTemplate` */
-  buttonsProps: ArrayFieldItemButtonsTemplateType<T, S, F>;
+  buttonsProps: ArrayFieldItemButtonsTemplateProps<T, S, F>;
   /** The className string */
   className: string;
   /** A boolean value stating if the array item is disabled */
@@ -672,36 +700,25 @@ export type ArrayFieldItemTemplateType<
   /** A boolean value stating if the array item is read-only */
   readonly?: boolean;
   /** A stable, unique key for the array item */
-  key: string;
+  itemKey: string;
+  /** The UI schema of the array item's parent array field used for
+   * customization in some themes
+   */
+  parentUiSchema?: UiSchema<T, S, F>;
 };
 
-/**
- * @deprecated - Use `ArrayFieldItemTemplateType` instead
- */
-export type ArrayFieldTemplateItemType<
-  T = any,
-  S extends StrictRJSFSchema = RJSFSchema,
-  F extends FormContextType = any,
-> = ArrayFieldItemTemplateType<T, S, F>;
-
-/** The properties that are passed to an `ArrayFieldTemplate` implementation */
-export type ArrayFieldTemplateProps<
+/** The common properties of the two container templates: `ArrayFieldTemplateProps` and `ObjectFieldTemplateProps` */
+export type ContainerFieldTemplateProps<
   T = any,
   S extends StrictRJSFSchema = RJSFSchema,
   F extends FormContextType = any,
 > = RJSFBaseProps<T, S, F> & {
-  /** A boolean value stating whether new elements can be added to the array */
-  canAdd?: boolean;
   /** The className string */
   className?: string;
   /** A boolean value stating if the array is disabled */
   disabled?: boolean;
   /** The FieldPathId of the field in the hierarchy */
   fieldPathId: FieldPathId;
-  /** An array of objects representing the items in the array */
-  items: ArrayFieldItemTemplateType<T, S, F>[];
-  /** A function that adds a new item to the array */
-  onAddClick: (event?: any) => void;
   /** A boolean value stating if the array is read-only */
   readonly?: boolean;
   /** A boolean value stating if the array is required */
@@ -712,8 +729,24 @@ export type ArrayFieldTemplateProps<
   title: string;
   /** The formData for this array */
   formData?: T;
-  /** The tree of errors for this field and its children */
+  /** The optional validation errors in the form of an `ErrorSchema` */
   errorSchema?: ErrorSchema<T>;
+  /** The optional data control node to render within the ObjectFieldTemplate that controls */
+  optionalDataControl?: ReactNode;
+};
+
+/** The properties that are passed to an `ArrayFieldTemplate` implementation */
+export type ArrayFieldTemplateProps<
+  T = any,
+  S extends StrictRJSFSchema = RJSFSchema,
+  F extends FormContextType = any,
+> = ContainerFieldTemplateProps<T, S, F> & {
+  /** A boolean value stating whether new elements can be added to the array */
+  canAdd?: boolean;
+  /** An array of React elements representing the items in the array */
+  items: ReactElement[];
+  /** A function that adds a new item to the end of the array */
+  onAddClick: (event?: any) => void;
   /** An array of strings listing all generated error messages from encountered errors for this widget */
   rawErrors?: string[];
 };
@@ -737,17 +770,15 @@ export type ObjectFieldTemplateProps<
   T = any,
   S extends StrictRJSFSchema = RJSFSchema,
   F extends FormContextType = any,
-> = RJSFBaseProps<T, S, F> & {
-  /** A string value containing the title for the object */
-  title: string;
+> = ContainerFieldTemplateProps<T, S, F> & {
   /** A string value containing the description for the object */
   description?: string | ReactElement;
-  /** A boolean value stating if the object is disabled */
-  disabled?: boolean;
   /** An array of objects representing the properties in the object */
   properties: ObjectFieldTemplatePropertyType[];
-  /** Returns a function that adds a new property to the object (to be used with additionalProperties) */
-  onAddClick: (schema: S) => () => void;
+  /** Callback to use in order to add an new additionalProperty to the object field  (to be used with
+   * additionalProperties and patternProperties)
+   */
+  onAddProperty: () => void;
   /** A boolean value stating if the object is read-only */
   readonly?: boolean;
   /** A boolean value stating if the object is required */
@@ -762,6 +793,22 @@ export type ObjectFieldTemplateProps<
   formData?: T;
 };
 
+/** The properties that are passed to a OptionalDataControlsTemplate implementation */
+export type OptionalDataControlsTemplateProps<
+  T = any,
+  S extends StrictRJSFSchema = RJSFSchema,
+  F extends FormContextType = any,
+> = RJSFBaseProps<T, S, F> & {
+  /** The generated id for this Optional Data Control instance */
+  id: string;
+  /** The label to use for the Optional Data Control */
+  label: string;
+  /** Optional callback to call when clicking on the Optional Data Control to add data */
+  onRemoveClick?: () => void;
+  /** Optional callback to call when clicking on the Optional Data Control to remove data */
+  onAddClick?: () => void;
+};
+
 /** The properties that are passed to a WrapIfAdditionalTemplate implementation */
 export type WrapIfAdditionalTemplateProps<
   T = any,
@@ -783,8 +830,9 @@ export type WrapIfAdditionalTemplateProps<
     | 'disabled'
     | 'schema'
     | 'uiSchema'
-    | 'onKeyChange'
-    | 'onDropPropertyClick'
+    | 'onKeyRename'
+    | 'onKeyRenameBlur'
+    | 'onRemoveProperty'
     | 'registry'
   >;
 
@@ -850,6 +898,8 @@ export interface WidgetProps<T = any, S extends StrictRJSFSchema = RJSFSchema, F
   multiple?: boolean;
   /** An array of strings listing all generated error messages from encountered errors for this widget */
   rawErrors?: string[];
+  /** The optional custom HTML name attribute generated by the nameGenerator function, if provided */
+  htmlName?: string;
 }
 
 /** The definition of a React-based Widget component */
@@ -1194,12 +1244,14 @@ export interface SchemaUtilsType<T = any, S extends StrictRJSFSchema = RJSFSchem
    * @param [includeUndefinedValues=false] - Optional flag, if true, cause undefined values to be added as defaults.
    *          If "excludeObjectChildren", cause undefined values for this object and pass `includeUndefinedValues` as
    *          false when computing defaults for any nested object properties.
+   * @param initialDefaultsGenerated - Indicates whether or not initial defaults have been generated
    * @returns - The resulting `formData` with all the defaults provided
    */
   getDefaultFormState(
     schema: S,
     formData?: T,
     includeUndefinedValues?: boolean | 'excludeObjectChildren',
+    initialDefaultsGenerated?: boolean,
   ): T | T[] | undefined;
   /** Determines whether the combination of `schema` and `uiSchema` properties indicates that the label for the `schema`
    * should be displayed in a UI.
@@ -1275,9 +1327,10 @@ export interface SchemaUtilsType<T = any, S extends StrictRJSFSchema = RJSFSchem
    *
    * @param schema - The schema for which retrieving a schema is desired
    * @param [formData] - The current formData, if any, to assist retrieving a schema
+   * @param [resolveAnyOfOrOneOfRefs] - Optional flag indicating whether to resolved refs in anyOf/oneOf lists
    * @returns - The schema having its conditions, additional properties, references and dependencies resolved
    */
-  retrieveSchema(schema: S, formData?: T): S;
+  retrieveSchema(schema: S, formData?: T, resolveAnyOfOrOneOfRefs?: boolean): 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

package/src/useDeepCompareMemo.ts

@@ -0,0 +1,17 @@
+import { useRef } from 'react';
+import isEqual from 'lodash/isEqual';
+
+/** Hook that stores and returns a `T` value. If `newValue` is the same as the stored one, then the stored one is
+ * returned to avoid having a component rerender due it being a different object. Otherwise, the `newValue` is stored
+ * and returned.
+ *
+ * @param newValue - The potential new `T` value
+ * @returns - The latest stored `T` value
+ */
+export default function useDeepCompareMemo<T = unknown>(newValue: T): T {
+  const valueRef = useRef<T>(newValue);
+  if (!isEqual(newValue, valueRef.current)) {
+    valueRef.current = newValue;
+  }
+  return valueRef.current;
+}

package/src/validationDataMerge.ts

@@ -11,11 +11,13 @@ import { ErrorSchema, ValidationData } from './types';
  *
  * @param validationData - The current `ValidationData` into which to merge the additional errors
  * @param [additionalErrorSchema] - The optional additional set of errors in an `ErrorSchema`
+ * @param [preventDuplicates=false] - Optional flag, if true, will call `mergeObjects()` with `preventDuplicates`
  * @returns - The `validationData` with the additional errors from `additionalErrorSchema` merged into it, if provided.
  */
 export default function validationDataMerge<T = any>(
   validationData: ValidationData<T>,
   additionalErrorSchema?: ErrorSchema<T>,
+  preventDuplicates = false,
 ): ValidationData<T> {
   if (!additionalErrorSchema) {
     return validationData;
@@ -24,7 +26,11 @@ export default function validationDataMerge<T = any>(
   let errors = toErrorList(additionalErrorSchema);
   let errorSchema = additionalErrorSchema;
   if (!isEmpty(oldErrorSchema)) {
-    errorSchema = mergeObjects(oldErrorSchema, additionalErrorSchema, true) as ErrorSchema<T>;
+    errorSchema = mergeObjects(
+      oldErrorSchema,
+      additionalErrorSchema,
+      preventDuplicates ? 'preventDuplicates' : true,
+    ) as ErrorSchema<T>;
     errors = [...oldErrors].concat(errors);
   }
   return { errorSchema, errors };