Required Label (wildcard) (#155)

This PR aims to:
- unify the label required function
- provide support for arrays and nested objects for the requiredFields

Author: Michele-Masciave

CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- support into `requiredFields` property of `Form` component, for nested objects and arrays.
+- `form` helper functions
+
+### Fixed
+
+- Required field label on `FormGroupLayoutLabel`, `ColorPicker`, `TelephoneNumberInput`, `TypeaheadTextField` (hence `StaticTypeaheadInput` and `AsyncTypeaheadInput`) in order to display \* also on nested and array fields.
+
+  1. `requiredFields` can still accept a `FieldPath<T>[]`
+  2. In order to be complaint with `FieldPath` react-hook-form type (`object.${number}.property`) array properties provide a wildcard:
+
+  ```tsx
+  requiredFields = [
+    `object`,
+    `object.nestedObjects`,
+    `objects.*.property`,
+    `object.nestedObject.property`,
+    `object.nestedObjects.*.property`,
+  ];
+  ```
+
+  is going to consider as required:
+
+  ```tsx
+    name="object"
+    name="object.nestedObjects.0", "object.nestedObjects.1", etc.
+    name="objects.0.property", name="objects.1.property", etc.
+    name="object.nestedObject.property"
+    name="object.nestedObjects.0.property", name="object.nestedObjects.1.property", etc.
+  ```
+
 ## [3.13.1] - 2025-11-13
 
 ### Fixed

cypress/cypress/component/FormGroupLayout/FormGroupLayout.cy.tsx

@@ -77,6 +77,54 @@ it("testing existing * on nested object", () => {
   cy.get(`label[for=${fakePerson.city.address.street}]`).should("have.text", `${fakePerson.city.address.street} *`);
 });
 
+it("testing existing * on arrays", () => {
+  const fakePerson = {
+    city: {
+      address: {
+        streetsAsString: [faker.random.alpha(10), faker.random.alpha(10), faker.random.alpha(10)],
+        streetsAsObject: [
+          { name: faker.random.alpha(10), date: new Date() },
+          { name: faker.random.alpha(10), date: new Date() },
+          { name: faker.random.alpha(10), date: new Date() },
+        ],
+      },
+    },
+  };
+
+  const schema = yup.object().shape({
+    city: yup.object().shape({
+      address: yup.object().shape({
+        streetsAsString: yup.array().of(yup.string().required()),
+        streetsAsObject: yup.array().of(
+          yup.object().shape({
+            name: yup.string().required(),
+            date: yup.date(),
+          }),
+        ),
+      }),
+    }),
+  });
+
+  mount(
+    <Form<typeof fakePerson>
+      onSubmit={() => {
+        // Nothing to do
+      }}
+      defaultValues={fakePerson}
+      resolver={yupResolver(schema)}
+      requiredFields={["city.address.streetsAsString", "city.address.streetsAsObject.*.name", "city.address.streetsAsObject.*.date"]}
+    >
+      <Input<typeof fakePerson> name="city.address.streetsAsObject.0.name" label="Street as object" />
+      <Input<typeof fakePerson> name="city.address.streetsAsString.0" label="Street as string" />
+      <DatePickerInput<typeof fakePerson> name="city.address.streetsAsObject.0.date" label="Date as object" />
+    </Form>,
+  );
+
+  cy.get(`label[for="city.address.streetsAsObject.0.name"`).should("have.text", "Street as object *");
+  cy.get(`label[for="city.address.streetsAsString.0"`).should("have.text", "Street as string *");
+  cy.get(`label[for="city.address.streetsAsObject.0.date"`).should("have.text", "Date as object *");
+});
+
 const ValidationForm = (props: { hideValidationMessage?: boolean; hideValidationMessages?: boolean }) => {
   const { hideValidationMessage, hideValidationMessages } = props;
   const schema = yup.object().shape({

src/index.ts

@@ -6,10 +6,12 @@ export * from "./lib/TelephoneNumberInput";
 export * from "./lib/AsyncTypeaheadInput";
 export * from "./lib/types/Typeahead";
 export * from "./lib/types/LabelValueOption";
+export * from "./lib/types/Form";
 export * from "./lib/DatePickerInput";
 export * from "./lib/ColorPickerInput";
 export * from "./lib/RatingInput";
 export * from "./lib/helpers/dateUtils";
+export * from "./lib/helpers/form";
 export * from "./lib/helpers/mui";
 export * from "./lib/helpers/typeahead";
 export * from "./lib/hooks/useDebounceHook";

src/lib/Form.tsx

@@ -1,8 +1,9 @@
 import { ReactNode } from "react";
-import { DeepPartial, FieldPath, FieldValues, Resolver, SubmitHandler, useForm, UseFormReturn } from "react-hook-form";
+import { DeepPartial, FieldValues, Resolver, SubmitHandler, useForm, UseFormReturn } from "react-hook-form";
 import { jsonIsoDateReviver } from "./helpers/dateUtils";
 import { FormContext, FormContextProps } from "./context/FormContext";
 import { AutoSubmitConfig, useAutoSubmit } from "./hooks/useAutoSubmit";
+import { RequiredFieldPath } from "./types/Form";
 
 export interface FormMethods<T extends FieldValues> extends UseFormReturn<T, unknown>, FormContextProps<T> {}
 
@@ -23,9 +24,9 @@ interface FormProps<T extends FieldValues> {
   defaultValues?: DeepPartial<T>;
 
   /**
-   * passed fieldnames will be marked with "*"
+   * passed field names will be marked with "*"
    */
-  requiredFields?: FieldPath<T>[];
+  requiredFields?: RequiredFieldPath<T>[];
 
   /**
    * disable all fields inside the form making it readonly

src/lib/FormGroupLayoutLabel.tsx

@@ -2,6 +2,7 @@ import { CSSProperties, ReactNode } from "react";
 import { useFormContext } from "./context/FormContext";
 import { FieldPath, FieldValues } from "react-hook-form";
 import { Label, UncontrolledTooltip } from "reactstrap";
+import { getRequiredLabel } from "./helpers/form";
 
 interface FormGroupLayoutLabelProps<T extends FieldValues> {
   label: ReactNode;
@@ -24,9 +25,7 @@ const FormGroupLayoutLabel = <T extends FieldValues>(props: FormGroupLayoutLabel
     return null;
   }
 
-  const fieldIsRequired = typeof label === "string" && requiredFields.includes(fieldName);
-  const finalLabel = fieldIsRequired ? `${String(label)} *` : label;
-
+  const finalLabel = getRequiredLabel<T>(label, fieldName, requiredFields);
   const switchLayout = layout === "switch";
   const checkboxLayout = layout === "checkbox";
 

src/lib/components/ColorPicker/ColorPicker.tsx

@@ -11,6 +11,7 @@ import { useMemo } from "react";
 import { TinyColor } from "@ctrl/tinycolor";
 import Popover from "@mui/material/Popover";
 import Colorful from "@uiw/react-color-colorful"; // must be imported as default, otherwise it will provide a runtime error in nextjs
+import { getRequiredLabel } from "../../helpers/form";
 
 const getColorByFormat = <T extends FieldValues>(color: TinyColor, format: ColorPickerInputProps<T>["format"]) => {
   switch (format) {
@@ -49,7 +50,7 @@ const ColorPicker = <T extends FieldValues>(props: ColorPickerInputProps<T>) =>
     requiredFields,
     formState: { errors },
     hideValidationMessages,
-  } = useFormContext();
+  } = useFormContext<T>();
   const focusHandler = useMarkOnFocusHandler(markAllOnFocus);
   const {
     field: { ref, ...field },
@@ -69,8 +70,7 @@ const ColorPicker = <T extends FieldValues>(props: ColorPickerInputProps<T>) =>
   const hideErrorMessage = useMemo(() => hideValidationMessages || hideValidationMessage, [hideValidationMessages, hideValidationMessage]);
   const hasError = useMemo(() => !!fieldError, [fieldError]);
   const errorMessage = useMemo(() => String(fieldError?.message), [fieldError]);
-  const fieldIsRequired = label && typeof label === "string" && requiredFields.includes(name);
-  const finalLabel = useMemo(() => (fieldIsRequired ? `${String(label)} *` : label), [fieldIsRequired, label]);
+  const finalLabel = useMemo(() => getRequiredLabel<T>(label, name, requiredFields), [label, name, requiredFields]);
 
   return (
     <PopupState variant="popover" popupId={`popover-${name}`}>

src/lib/components/TelephoneNumberInput/TelephoneNumberInputInternal.tsx

@@ -7,7 +7,7 @@ import { useFormContext } from "../../context/FormContext";
 import { useEffect, useMemo, useRef, useState } from "react";
 import Popover from "@mui/material/Popover";
 import { TelephoneNumberInputProps } from "../../TelephoneNumberInput";
-
+import { getRequiredLabel } from "../../helpers/form";
 import { Country, extractCountryCodeFromTelephoneNumber, extractNationalNumberFromTelephoneNumber } from "../../helpers/telephoneNumber";
 import { TelephoneNumberInputAdornment } from "./TelephoneNumberInputAdornment";
 import { isNullOrWhitespace } from "@neolution-ch/javascript-utils";
@@ -58,8 +58,7 @@ const TelephoneNumberInputInternal = <T extends FieldValues>(props: TelephoneNum
   const hideErrorMessage = useMemo(() => hideValidationMessages || hideValidationMessage, [hideValidationMessages, hideValidationMessage]);
   const hasError = useMemo(() => !!fieldError, [fieldError]);
   const errorMessage = useMemo(() => String(fieldError?.message), [fieldError]);
-  const fieldIsRequired = label && typeof label === "string" && requiredFields.includes(name);
-  const finalLabel = useMemo(() => (fieldIsRequired ? `${String(label)} *` : label), [fieldIsRequired, label]);
+  const finalLabel = useMemo(() => getRequiredLabel<T>(label, name, requiredFields), [label, name, requiredFields]);
 
   // we need to control the country in the case the value inside the form is undefined
   const [country, setCountry] = useState<Country>(extractCountryCodeFromTelephoneNumber(field.value as string | undefined, defaultCountry));

src/lib/components/Typeahead/TypeaheadTextField.tsx

@@ -9,6 +9,7 @@ import { CommonTypeaheadProps } from "../../types/Typeahead";
 import { FieldError, FieldValues, get } from "react-hook-form";
 import { MergedAddonProps } from "../../types/CommonInputProps";
 import { useFormContext } from "../../context/FormContext";
+import { getRequiredLabel } from "../../helpers/form";
 
 interface TypeaheadTextFieldProps<T extends FieldValues, TRenderAddon>
   extends Omit<CommonTypeaheadProps<T>, "id" | "disabled" | "onChange">,
@@ -47,15 +48,13 @@ const TypeaheadTextField = <T extends FieldValues, TRenderAddon = unknown>(props
     formState: { errors },
     requiredFields,
     hideValidationMessages,
-  } = useFormContext();
+  } = useFormContext<T>();
 
   const fieldError = get(errors, name) as FieldError | undefined;
   const hasError = useMemo(() => !!fieldError, [fieldError]);
   const errorMessage = useMemo(() => String(fieldError?.message), [fieldError]);
   const hideErrorMessage = useMemo(() => hideValidationMessages || hideValidationMessage, [hideValidationMessages, hideValidationMessage]);
-
-  const fieldIsRequired = label && typeof label === "string" && requiredFields.includes(name);
-  const finalLabel = useMemo(() => (fieldIsRequired ? `${String(label)} *` : label), [fieldIsRequired, label]);
+  const finalLabel = useMemo(() => getRequiredLabel<T>(label, name, requiredFields), [label, name, requiredFields]);
 
   const startAdornment = useMemo(
     () =>

src/lib/context/FormContext.tsx

@@ -1,8 +1,9 @@
 import { createContext, useContext } from "react";
-import { FieldPath, FieldValues, UseFormReturn } from "react-hook-form";
+import { FieldValues, UseFormReturn } from "react-hook-form";
+import { RequiredFieldPath } from "../types/Form";
 
 export interface FormContextProps<T extends FieldValues> extends UseFormReturn<T, unknown> {
-  requiredFields: FieldPath<T>[];
+  requiredFields: RequiredFieldPath<T>[];
   disabled: boolean;
   hideValidationMessages: boolean;
   disableAriaAutocomplete: boolean;

src/lib/helpers/form.ts

@@ -0,0 +1,25 @@
+import { ReactNode } from "react";
+import { FieldPath, FieldValues } from "react-hook-form";
+import { RequiredFieldPath } from "../types/Form";
+
+const matchesWildcard = (rule: string, pathParts: string[]) => {
+  const ruleParts = rule.split(".");
+  // remove trailing index placeholder in case of primitive arrays
+  if (pathParts.length - ruleParts.length === 1 && pathParts.at(-1) === "*") {
+    pathParts = pathParts.slice(0, -1);
+  }
+  return ruleParts.length === pathParts.length && pathParts.every((p, i) => ruleParts[i] === p);
+};
+
+const isRequiredField = <T extends FieldValues>(fieldPath: string, requiredFields?: RequiredFieldPath<T>[]) => {
+  const normalizedPathParts = fieldPath.split(".").map((x) => (Number.isNaN(Number(x)) ? x : "*"));
+  return !!requiredFields?.some((rule) => rule === fieldPath || matchesWildcard(rule, normalizedPathParts));
+};
+
+const getRequiredLabel = <T extends FieldValues>(
+  label: ReactNode,
+  fieldPath: FieldPath<T>,
+  requiredFields?: RequiredFieldPath<T>[],
+): ReactNode => (typeof label === "string" ? (isRequiredField(fieldPath, requiredFields) ? `${String(label)} *` : label) : label);
+
+export { getRequiredLabel, isRequiredField };