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

package/src/shallowEquals.ts

@@ -0,0 +1,41 @@
+/** Implements a shallow equals comparison that uses Object.is() for comparing values.
+ * This function compares objects by checking if all keys and their values are equal using Object.is().
+ *
+ * @param a - The first element to compare
+ * @param b - The second element to compare
+ * @returns - True if the `a` and `b` are shallow equal, false otherwise
+ */
+export default function shallowEquals(a: any, b: any): boolean {
+  // If they're the same reference, they're equal
+  if (Object.is(a, b)) {
+    return true;
+  }
+
+  // If either is null or undefined, they're not equal (since we know they're not the same reference)
+  if (a == null || b == null) {
+    return false;
+  }
+
+  // If they're not objects, they're not equal (since Object.is already checked)
+  if (typeof a !== 'object' || typeof b !== 'object') {
+    return false;
+  }
+
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+
+  // Different number of keys means not equal
+  if (keysA.length !== keysB.length) {
+    return false;
+  }
+
+  // Check if all keys and values are equal
+  for (let i = 0; i < keysA.length; i++) {
+    const key = keysA[i];
+    if (!Object.prototype.hasOwnProperty.call(b, key) || !Object.is(a[key], b[key])) {
+      return false;
+    }
+  }
+
+  return true;
+}

package/src/shouldRender.ts

@@ -1,16 +1,41 @@
 import React from 'react';
 
 import deepEquals from './deepEquals';
+import shallowEquals from './shallowEquals';
+
+/** The supported component update strategies */
+export type ComponentUpdateStrategy = 'customDeep' | 'shallow' | 'always';
 
 /** Determines whether the given `component` should be rerendered by comparing its current set of props and state
- * against the next set. If either of those two sets are not the same, then the component should be rerendered.
+ * against the next set. The comparison strategy can be controlled via the `updateStrategy` parameter.
  *
  * @param component - A React component being checked
  * @param nextProps - The next set of props against which to check
  * @param nextState - The next set of state against which to check
+ * @param updateStrategy - The strategy to use for comparison:
+ *   - 'customDeep': Uses RJSF's custom deep equality checks (default)
+ *   - 'shallow': Uses shallow comparison of props and state
+ *   - 'always': Always returns true (React's default behavior)
  * @returns - True if the component should be re-rendered, false otherwise
  */
-export default function shouldRender(component: React.Component, nextProps: any, nextState: any) {
+export default function shouldRender(
+  component: React.Component,
+  nextProps: any,
+  nextState: any,
+  updateStrategy: ComponentUpdateStrategy = 'customDeep',
+) {
+  if (updateStrategy === 'always') {
+    // Use React's default behavior: always update if state or props change (no shouldComponentUpdate optimization)
+    return true;
+  }
+
+  if (updateStrategy === 'shallow') {
+    // Use shallow comparison for props and state
+    const { props, state } = component;
+    return !shallowEquals(props, nextProps) || !shallowEquals(state, nextState);
+  }
+
+  // Use custom deep equality checks (default 'customDeep' strategy)
   const { props, state } = component;
   return !deepEquals(props, nextProps) || !deepEquals(state, nextState);
 }

package/src/toFieldPathId.ts

@@ -0,0 +1,24 @@
+import { ID_KEY } from './constants';
+import { FieldPathId, FieldPathList, GlobalFormOptions } from './types';
+
+/** Constructs the `FieldPathId` for `fieldPath`. If `parentPathId` is provided, the `fieldPath` is appended to the end
+ * of the parent path. Then the `ID_KEY` of the resulting `FieldPathId` is constructed from the `idPrefix` and
+ * `idSeparator` contained within the `globalFormOptions`. If `fieldPath` is passed as an empty string, it will simply
+ * generate the path from the `parentPath` (if provided) and the `idPrefix` and `idSeparator`
+ *
+ * @param fieldPath - The property name or array index of the current field element
+ * @param globalFormOptions - The `GlobalFormOptions` used to get the `idPrefix` and `idSeparator`
+ * @param [parentPath] - The optional `FieldPathId` or `FieldPathList` of the parent element for this field element
+ * @returns - The `FieldPathId` for the given `fieldPath` and the optional `parentPathId`
+ */
+export default function toFieldPathId(
+  fieldPath: string | number,
+  globalFormOptions: GlobalFormOptions,
+  parentPath?: FieldPathId | FieldPathList,
+): FieldPathId {
+  const basePath = Array.isArray(parentPath) ? parentPath : parentPath?.path;
+  const childPath = fieldPath === '' ? [] : [fieldPath];
+  const path = basePath ? basePath.concat(...childPath) : childPath;
+  const id = [globalFormOptions.idPrefix, ...path].join(globalFormOptions.idSeparator);
+  return { path, [ID_KEY]: id };
+}

package/src/types.ts

@@ -158,20 +158,25 @@ export type InputPropsType = Omit<RangeSpecType, 'step'> & {
   accept?: HTMLInputElement['accept'];
 };
 
-/** Type describing an id used for a field in the `IdSchema` */
-export type FieldId = {
+/** The list of path elements that represents where in the schema a field is located. When the item in the field list is
+ * a string, then it represents the name of the property within an object. When it is a number, then it represents the
+ * index within an array.
+ *
+ * For example:
+ * `[]` represents the root object of the schema
+ * `['foo', 'bar']` represents the `bar` element contained within the `foo` element of the schema
+ * `['baz', 1]` represents the second element in the list `baz` of the schema
+ */
+export type FieldPathList = (string | number)[];
+
+/** Type describing an id and path used for a field */
+export type FieldPathId = {
   /** The id for a field */
   $id: string;
+  /** The path for a field */
+  path: FieldPathList;
 };
 
-/** Type describing a recursive structure of `FieldId`s for an object with a non-empty set of keys */
-export type IdSchema<T = any> = T extends GenericObjectType
-  ? FieldId & {
-      /** The set of ids for fields in the recursive object structure */
-      [key in keyof T]?: IdSchema<T[key]>;
-    }
-  : FieldId;
-
 /** Type describing a name used for a field in the `PathSchema` */
 export type FieldPath = {
   /** The name of a field */
@@ -212,6 +217,8 @@ export type RJSFValidationError = {
   schemaPath?: string;
   /** Full error name, for example ".name is a required property" */
   stack: string;
+  /** The title property for the failing field*/
+  title?: string;
 };
 
 /** The type that describes an error in a field */
@@ -261,8 +268,6 @@ export type ErrorListProps<
   errorSchema: ErrorSchema<T>;
   /** An array of the errors */
   errors: RJSFValidationError[];
-  /** The `formContext` object that was passed to `Form` */
-  formContext?: F;
 };
 
 /** The properties that are passed to an `FieldErrorTemplate` implementation */
@@ -275,8 +280,8 @@ export type FieldErrorProps<
   errorSchema?: ErrorSchema<T>;
   /** An array of the errors */
   errors?: Array<string | ReactElement>;
-  /** The tree of unique ids for every child field */
-  idSchema: IdSchema<T>;
+  /** The FieldPathId of the field in the hierarchy */
+  fieldPathId: FieldPathId;
 };
 
 /** The properties that are passed to an `FieldHelpTemplate` implementation */
@@ -287,8 +292,8 @@ export type FieldHelpProps<
 > = RJSFBaseProps<T, S, F> & {
   /** The help information to be rendered */
   help?: string | ReactElement;
-  /** The tree of unique ids for every child field */
-  idSchema: IdSchema<T>;
+  /** The FieldPathId of the field in the hierarchy */
+  fieldPathId: FieldPathId;
   /** Flag indicating whether there are errors associated with this field */
   hasErrors?: boolean;
 };
@@ -341,6 +346,8 @@ export type TemplatesType<T = any, S extends StrictRJSFSchema = RJSFSchema, F ex
   FieldTemplate: ComponentType<FieldTemplateProps<T, S, F>>;
   /** The template to use to render a Grid element */
   GridTemplate: ComponentType<GridTemplateProps>;
+  /** The template to use while rendering a multi-schema field (i.e. anyOf, oneOf) */
+  MultiSchemaFieldTemplate: ComponentType<MultiSchemaFieldTemplateProps<T, S, F>>;
   /** The template to use while rendering an object */
   ObjectFieldTemplate: ComponentType<ObjectFieldTemplateProps<T, S, F>>;
   /** The template to use for rendering the title of a field */
@@ -370,9 +377,10 @@ export type TemplatesType<T = any, S extends StrictRJSFSchema = RJSFSchema, F ex
 };
 
 /** The set of UiSchema options that can be set globally and used as fallbacks at an individual template, field or
- * widget level when no field-level value of the option is provided.
+ * widget level when no field-level value of the option is provided. Extends GenericObjectType to support allowing users
+ * to provide any value they need for their customizations.
  */
-export type GlobalUISchemaOptions = {
+export type GlobalUISchemaOptions = GenericObjectType & {
   /** Flag, if set to `false`, new items cannot be added to array fields, unless overridden (defaults to true) */
   addable?: boolean;
   /** Flag, if set to `true`, array items can be copied (defaults to false) */
@@ -392,6 +400,22 @@ export type GlobalUISchemaOptions = {
   enableMarkdownInDescription?: boolean;
 };
 
+/** The set of options from the `Form` that will be available on the `Registry` for use in everywhere the `registry` is
+ * available.
+ */
+export type GlobalFormOptions = {
+  /** To avoid collisions with existing ids in the DOM, it is possible to change the prefix used for ids;
+   * Default is `root`. This prop is passed to the `toFilePathId()` function within the RJSF field implementations.
+   */
+  readonly idPrefix: string;
+  /** To avoid using a path separator that is present in field names, it is possible to change the separator used for
+   * ids; Default is `_`. This prop is passed to the `toFilePathId()` function within the RJSF field implementations.
+   */
+  readonly idSeparator: string;
+  /** The component update strategy used by the Form and its fields for performance optimization */
+  readonly experimental_componentUpdateStrategy?: 'customDeep' | 'shallow' | 'always';
+};
+
 /** The object containing the registered core, theme and custom fields and widgets as well as the root schema, form
  * context, schema utils and templates.
  */
@@ -400,7 +424,7 @@ export interface Registry<T = any, S extends StrictRJSFSchema = RJSFSchema, F ex
    * registered fields
    */
   fields: RegistryFieldsType<T, S, F>;
-  /** The set of templates used by the `Form`. Includes templates from `core`, theme-specific fields and any custom
+  /** The set of templates used by the `Form`. Includes templates from `core`, theme-specific templates and any custom
    * registered templates
    */
   templates: TemplatesType<T, S, F>;
@@ -418,29 +442,31 @@ export interface Registry<T = any, S extends StrictRJSFSchema = RJSFSchema, F ex
   schemaUtils: SchemaUtilsType<T, S>;
   /** The string translation function to use when displaying any of the RJSF strings in templates, fields or widgets */
   translateString: (stringKey: TranslatableString, params?: string[]) => string;
+  /** The global Form Options that are available for all templates, fields and widgets to access */
+  readonly globalFormOptions: GlobalFormOptions;
   /** The optional global UI Options that are available for all templates, fields and widgets to access */
   globalUiOptions?: GlobalUISchemaOptions;
 }
 
-/** The properties that are passed to a Field implementation */
+/** The properties that are passed to a `Field` implementation */
 export interface FieldProps<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any>
   extends GenericObjectType,
     RJSFBaseProps<T, S, F>,
     Pick<HTMLAttributes<HTMLElement>, Exclude<keyof HTMLAttributes<HTMLElement>, 'onBlur' | 'onFocus' | 'onChange'>> {
-  /** The tree of unique ids for every child field */
-  idSchema: IdSchema<T>;
+  /** The FieldPathId of the field in the hierarchy */
+  fieldPathId: FieldPathId;
   /** The data for this field */
   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 | undefined, es?: ErrorSchema<T>, id?: string) => any;
+  /** The field change event handler; called with the updated field value, the change path for the value
+   * (defaults to an empty array), an optional ErrorSchema and the optional id of the field being changed
+   */
+  onChange: (newValue: T | undefined, path: FieldPathList, es?: ErrorSchema<T>, id?: string) => void;
   /** 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 */
   onFocus: (id: string, value: any) => void;
-  /** The `formContext` object that you passed to `Form` */
-  formContext?: F;
   /** A boolean value stating if the field should autofocus */
   autofocus?: boolean;
   /** A boolean value stating if the field is disabled */
@@ -453,14 +479,6 @@ export interface FieldProps<T = any, S extends StrictRJSFSchema = RJSFSchema, F
   required?: boolean;
   /** The unique name of the field, usually derived from the name of the property in the JSONSchema */
   name: string;
-  /** To avoid collisions with existing ids in the DOM, it is possible to change the prefix used for ids;
-   * Default is `root`
-   */
-  idPrefix?: string;
-  /** To avoid using a path separator that is present in field names, it is possible to change the separator used for
-   * ids (Default is `_`)
-   */
-  idSeparator?: string;
   /** An array of strings listing all generated error messages from encountered errors for this field */
   rawErrors?: string[];
 }
@@ -468,9 +486,12 @@ export interface FieldProps<T = any, S extends StrictRJSFSchema = RJSFSchema, F
 /** The definition of a React-based Field component */
 export type Field<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any> = ComponentType<
   FieldProps<T, S, F>
->;
+> & {
+  /** The optional TEST_IDS block that some fields contain, exported for testing purposes */
+  TEST_IDS?: TestIdShape;
+};
 
-/** The properties that are passed to a FieldTemplate implementation */
+/** The properties that are passed to a `FieldTemplate` implementation */
 export type FieldTemplateProps<
   T = any,
   S extends StrictRJSFSchema = RJSFSchema,
@@ -516,8 +537,6 @@ export type FieldTemplateProps<
    * you don't want to clutter the UI
    */
   displayLabel?: boolean;
-  /** The `formContext` object that was passed to `Form` */
-  formContext?: F;
   /** The formData for this field */
   formData?: T;
   /** The value change event handler; Can be called with a new value to change the value for this field */
@@ -534,8 +553,8 @@ export type UnsupportedFieldProps<
   S extends StrictRJSFSchema = RJSFSchema,
   F extends FormContextType = any,
 > = RJSFBaseProps<T, S, F> & {
-  /** The tree of unique ids for every child field */
-  idSchema?: IdSchema<T>;
+  /** The FieldPathId of the field in the hierarchy */
+  fieldPathId: FieldPathId;
   /** The reason why the schema field has an unsupported type */
   reason: string;
 };
@@ -574,8 +593,8 @@ export type ArrayFieldTitleProps<
 > = Omit<TitleFieldProps<T, S, F>, 'id' | 'title'> & {
   /** The title for the field being rendered */
   title?: string;
-  /** The idSchema of the field in the hierarchy */
-  idSchema: IdSchema<T>;
+  /** The FieldPathId of the field in the hierarchy */
+  fieldPathId: FieldPathId;
 };
 
 /** The properties that are passed to a `ArrayFieldDescriptionTemplate` implementation */
@@ -586,8 +605,8 @@ export type ArrayFieldDescriptionProps<
 > = Omit<DescriptionFieldProps<T, S, F>, 'id' | 'description'> & {
   /** The description of the field being rendered */
   description?: string | ReactElement;
-  /** The idSchema of the field in the hierarchy */
-  idSchema: IdSchema<T>;
+  /** An object containing the id and path for this field */
+  fieldPathId: FieldPathId;
 };
 
 /** The properties of the buttons to render for each element in the ArrayFieldTemplateProps.items array */
@@ -596,8 +615,8 @@ export type ArrayFieldItemButtonsTemplateType<
   S extends StrictRJSFSchema = RJSFSchema,
   F extends FormContextType = any,
 > = RJSFBaseProps<T, S, F> & {
-  /** The idSchema of the item for which buttons are being rendered */
-  idSchema: IdSchema<T>;
+  /** The FieldPathId of the item for which buttons are being rendered */
+  fieldPathId: FieldPathId;
   /** The className string */
   className?: string;
   /** Any optional style attributes */
@@ -665,7 +684,7 @@ export type ArrayFieldTemplateItemType<
   F extends FormContextType = any,
 > = ArrayFieldItemTemplateType<T, S, F>;
 
-/** The properties that are passed to an ArrayFieldTemplate implementation */
+/** The properties that are passed to an `ArrayFieldTemplate` implementation */
 export type ArrayFieldTemplateProps<
   T = any,
   S extends StrictRJSFSchema = RJSFSchema,
@@ -677,8 +696,8 @@ export type ArrayFieldTemplateProps<
   className?: string;
   /** A boolean value stating if the array is disabled */
   disabled?: boolean;
-  /** An object containing the id for this object & ids for its properties */
-  idSchema: IdSchema<T>;
+  /** 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 */
@@ -691,8 +710,6 @@ export type ArrayFieldTemplateProps<
   hideError?: boolean;
   /** A string value containing the title for the array */
   title: string;
-  /** The `formContext` object that was passed to Form */
-  formContext?: F;
   /** The formData for this array */
   formData?: T;
   /** The tree of errors for this field and its children */
@@ -737,14 +754,12 @@ export type ObjectFieldTemplateProps<
   required?: boolean;
   /** A boolean value stating if the field is hiding its errors */
   hideError?: boolean;
-  /** An object containing the id for this object & ids for its properties */
-  idSchema: IdSchema<T>;
+  /** The FieldPathId of the field in the hierarchy */
+  fieldPathId: FieldPathId;
   /** The optional validation errors in the form of an `ErrorSchema` */
   errorSchema?: ErrorSchema<T>;
   /** The form data for the object */
   formData?: T;
-  /** The `formContext` object that was passed to Form */
-  formContext?: F;
 };
 
 /** The properties that are passed to a WrapIfAdditionalTemplate implementation */
@@ -773,11 +788,23 @@ export type WrapIfAdditionalTemplateProps<
     | 'registry'
   >;
 
-/** The properties that are passed to a Widget implementation */
+/** The properties that are passed to a MultiSchemaFieldTemplate implementation */
+export interface MultiSchemaFieldTemplateProps<
+  T = any,
+  S extends StrictRJSFSchema = RJSFSchema,
+  F extends FormContextType = any,
+> extends RJSFBaseProps<T, S, F> {
+  /** The rendered widget used to select a schema option */
+  selector: ReactNode;
+  /** The rendered SchemaField for the selected schema option */
+  optionSchemaField: ReactNode;
+}
+
+/** The properties that are passed to a `Widget` implementation */
 export interface WidgetProps<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any>
   extends GenericObjectType,
     RJSFBaseProps<T, S, F>,
-    Pick<HTMLAttributes<HTMLElement>, Exclude<keyof HTMLAttributes<HTMLElement>, 'onBlur' | 'onFocus'>> {
+    Pick<HTMLAttributes<HTMLElement>, Exclude<keyof HTMLAttributes<HTMLElement>, 'onBlur' | 'onFocus' | 'onChange'>> {
   /** The generated id for this widget, used to provide unique `name`s and `id`s for the HTML field elements rendered by
    * widgets
    */
@@ -807,8 +834,6 @@ export interface WidgetProps<T = any, S extends StrictRJSFSchema = RJSFSchema, F
     /** The enum options list for a type that supports them */
     enumOptions?: EnumOptionsType<S>[];
   };
-  /** The `formContext` object that you passed to `Form` */
-  formContext?: F;
   /** The input blur event handler; call it with the widget id and value */
   onBlur: (id: string, value: any) => void;
   /** The value change event handler; call it with the new value every time it changes */
@@ -985,6 +1010,13 @@ export type UIOptionsType<
   [key: string]: boolean | number | string | object | any[] | null | undefined;
 };
 
+/**
+ * A utility type that extracts the element type from an array type.
+ * If the type is not an array, it returns the type itself as a safe fallback.
+ * Handles both standard arrays and readonly arrays.
+ */
+export type ArrayElement<A> = A extends readonly (infer E)[] ? E : A;
+
 /** Type describing the well-known properties of the `UiSchema` while also supporting all user defined properties,
  * starting with `ui:`.
  */
@@ -998,7 +1030,10 @@ export type UiSchema<
      * Registry for use everywhere.
      */
     'ui:globalOptions'?: GlobalUISchemaOptions;
-    /** Allows the form to generate a unique prefix for the `Form`'s root prefix  */
+    /** Allows the form to generate a unique prefix for the `Form`'s root prefix
+     *
+     * @deprecated - use `Form.idPrefix` instead, will be removed in a future major version
+     */
     'ui:rootFieldId'?: string;
     /** By default, any field that is rendered for an `anyOf`/`oneOf` schema will be wrapped inside the `AnyOfField` or
      * `OneOfField` component. This default behavior may be undesirable if your custom field already handles behavior
@@ -1010,6 +1045,13 @@ export type UiSchema<
     'ui:fieldReplacesAnyOrOneOf'?: boolean;
     /** An object that contains all the potential UI options in a single object */
     'ui:options'?: UIOptionsType<T, S, F>;
+    /** The uiSchema for items in an array. Can be an object for a uniform uiSchema across all items (current behavior),
+     * or a function that returns a dynamic uiSchema based on the item's data and index.
+     * When using a function, it receives the item data, index, and optionally the form context as parameters.
+     */
+    items?:
+      | UiSchema<ArrayElement<T>, S, F>
+      | ((itemData: ArrayElement<T>, index: number, formContext?: F) => UiSchema<ArrayElement<T>, S, F>);
   };
 
 /** A `CustomValidator` function takes in a `formData`, `errors` and `uiSchema` objects and returns the given `errors`
@@ -1096,6 +1138,11 @@ export interface FoundFieldType<S extends StrictRJSFSchema = RJSFSchema> {
  * set of APIs to the `@rjsf/core` components and the various themes as well.
  */
 export interface SchemaUtilsType<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any> {
+  /** Returns the `rootSchema` in the `SchemaUtilsType`
+   *
+   * @returns - The rootSchema
+   */
+  getRootSchema(): S;
   /** Returns the `ValidatorType` in the `SchemaUtilsType`
    *
    * @returns - The `ValidatorType`
@@ -1243,16 +1290,6 @@ export interface SchemaUtilsType<T = any, S extends StrictRJSFSchema = RJSFSchem
    *      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
-   * @param [id] - The base id for the schema
-   * @param [formData] - The current formData, if any, onto which to provide any missing defaults
-   * @param [idPrefix='root'] - The prefix to use for the id
-   * @param [idSeparator='_'] - The separator to use for the path segments in the id
-   * @returns - The `IdSchema` object for the `schema`
-   */
-  toIdSchema(schema: S, id?: string, formData?: T, idPrefix?: string, idSeparator?: string): IdSchema<T>;
   /** Generates an `PathSchema` object for the `schema`, recursively
    *
    * @param schema - The schema for which the display label flag is desired