1.3.0 - types and comments refactoring

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-hive/honey-form",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "The TS library to build the fully customized forms using React framework",
   "keywords": [
     "react",
@@ -31,15 +31,15 @@
     "!dist/**/jest*"
   ],
   "peerDependencies": {
-    "react": "18.3.1",
-    "react-dom": "18.3.1",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0",
     "@mdx-js/react": "3.0.1"
   },
   "devDependencies": {
     "@testing-library/react": "16.0.1",
     "@types/jest": "29.5.13",
-    "@types/react": "18.3.6",
-    "@types/react-dom": "18.3.0",
+    "@types/react": ">=18.0.0",
+    "@types/react-dom": ">=18.0.0",
     "@types/mdx": "2.0.13",
     "@typescript-eslint/eslint-plugin": "7.18.0",
     "@typescript-eslint/parser": "7.18.0",

src/helpers.ts

@@ -55,7 +55,7 @@ export const getHoneyFormUniqueId = () => {
 /**
  * Maps over each field configuration and invokes the provided callback to create form fields.
  *
- * @template Form - Type representing the entire form.
+ * @template Form - The type representing the structure of the entire form.
  * @template FormContext - The type representing the context associated with the form.
  *
  * @param {HoneyFormFieldsConfigs<Form, FormContext>} fieldsConfigs - Object containing field configurations.
@@ -83,7 +83,7 @@ export const mapFieldsConfigs = <Form extends HoneyFormBaseForm, FormContext>(
 /**
  * Maps server errors to a new format using a callback for each field with server errors.
  *
- * @template Form - Type representing the entire form.
+ * @template Form - The type representing the structure of the entire form.
  *
  * @param {HoneyFormServerErrors<Form>} serverErrors - The server errors associated with form fields.
  * @param {(erredFieldName: keyof Form, fieldErrors: HoneyFormFieldErrorMessage[]) => HoneyFormFieldError[]} callback
@@ -107,7 +107,7 @@ export const mapServerErrors = <Form extends HoneyFormBaseForm>(
 /**
  * Iterates over each form field and invokes the provided callback.
  *
- * @template Form - Type representing the entire form.
+ * @template Form - The type representing the structure of the entire form.
  * @template FormContext - The type representing the context associated with the form.
  *
  * @param {HoneyFormFields<Form, FormContext>} formFields - An object containing the form fields.
@@ -129,7 +129,7 @@ export const forEachFormField = <Form extends HoneyFormBaseForm, FormContext>(
 /**
  * Iterates over each form field error and invokes the provided callback.
  *
- * @template Form - Type representing the entire form.
+ * @template Form - The type representing the structure of the entire form.
  *
  * @param {HoneyFormErrors<Form>} formErrors - An object containing form field errors.
  * @param {(fieldName: keyof Form, fieldErrors: HoneyFormFieldError[]) => void} callback - A callback function
@@ -194,7 +194,7 @@ export const getFormValues = <Form extends HoneyFormBaseForm, FormContext>(
 /**
  * Checks if the given form field configuration is interactive.
  *
- * @template Form - Type representing the entire form.
+ * @template Form - The type representing the structure of the entire form.
  * @template FieldName - The name of the field within the form.
  * @template FormContext - The type representing the context associated with the form.
  *
@@ -217,7 +217,7 @@ export const checkIfFieldIsInteractive = <
 /**
  * Checks if a given form field is of passive type, such as checkbox, radio, or file.
  *
- * @template Form - Type representing the entire form.
+ * @template Form - The type representing the structure of the entire form.
  * @template FieldName - The name of the field within the form.
  * @template FormContext - The type representing the context associated with the form.
  *
@@ -237,7 +237,7 @@ export const checkIfFieldIsPassive = <
 /**
  * Checks if a given form field is of object type.
  *
- * @template Form - Type representing the entire form.
+ * @template Form - The type representing the structure of the entire form.
  * @template FieldName - The name of the field within the form.
  * @template FormContext - The type representing the context associated with the form.
  *
@@ -257,7 +257,7 @@ export const checkIfFieldIsObject = <
 /**
  * Checks if a given form field is nested forms.
  *
- * @template Form - Type representing the entire form.
+ * @template Form - The type representing the structure of the entire form.
  * @template FieldName - The name of the field within the form.
  * @template FormContext - The type representing the context associated with the form.
  *
@@ -279,7 +279,7 @@ export const checkIfFieldIsNestedForms = <
  *
  * @template ParentForm - Type representing the parent form.
  * @template ParentFieldName - The field name type for the parent form that will contain the array of child forms.
- * @template Form - Type representing the entire form.
+ * @template Form - The type representing the structure of the entire form.
  * @template FieldName - The name of the field within the form.
  * @template FormContext - The type representing the context associated with the form.
  */
@@ -314,7 +314,7 @@ type CheckIsSkipFieldOptions<
  *
  * @template ParentForm - Type representing the parent form.
  * @template ParentFieldName - The field name type for the parent form that will contain the array of child forms.
- * @template Form - Type representing the entire form.
+ * @template Form - The type representing the structure of the entire form.
  * @template FieldName - The name of the field within the form.
  * @template FormContext - The type representing the context associated with the form.
  *
@@ -341,7 +341,7 @@ export const checkIsSkipField = <
 /**
  * Schedules the validation for a specific form field.
  *
- * @template Form - Type representing the entire form.
+ * @template Form - The type representing the structure of the entire form.
  * @template FieldName - The name of the field to validate.
  *
  * @param {HoneyFormField<Form, FieldName>} formField - The form field for which validation is to be scheduled.
@@ -360,7 +360,7 @@ export const scheduleFieldValidation = <
  *
  * @template ParentForm - Type representing the parent form.
  * @template ParentFieldName - The field name type for the parent form that will contain the array of child forms.
- * @template Form - Type representing the entire form.
+ * @template Form - The type representing the structure of the entire form.
  * @template FormContext - The type representing the context associated with the form.
  *
  * @param {HoneyFormParentField<ParentForm, ParentFieldName>} parentField - The parent form field where the child form is associated.
@@ -421,7 +421,7 @@ export const getSubmitFormValues = <
 /**
  * Retrieves form errors for each form field.
  *
- * @template Form - Type representing the entire form.
+ * @template Form - The type representing the structure of the entire form.
  * @template FormContext - The type representing the context associated with the form.
  *
  * @param {HoneyFormFields<Form, FormContext>} formFields - The form fields to extract errors from.
@@ -513,7 +513,7 @@ export const unregisterChildForm = <
 /**
  * Runs validation on child forms associated with a given form field.
  *
- * @template Form - Type representing the entire form.
+ * @template Form - The type representing the structure of the entire form.
  * @template FieldName - The name of the field within the form.
  * @template FormContext - The type representing the context associated with the form.
  *
@@ -615,7 +615,7 @@ const serializeForm = <Form extends HoneyFormBaseForm>(
 /**
  * Deserializes raw form data into a form object.
  *
- * @template Form - Type representing the entire form.
+ * @template Form - The type representing the structure of the entire form.
  *
  * @param {string} rawFormData - The raw form data as a string.
  * @param {HoneyFormFieldDeserializer<Form>} formFieldDeserializer - The deserializer function for the form fields.
@@ -642,7 +642,7 @@ const deserializeForm = <Form extends HoneyFormBaseForm>(
 /**
  * Serializes form data and stores it in the query string under the specified form name.
  *
- * @template Form - Type representing the entire form.
+ * @template Form - The type representing the structure of the entire form.
  * @template FormContext - The type representing the context associated with the form.
  *
  * @param {BaseHoneyFormFieldsConfigs<Form, FormContext>} fieldsConfigs - Configuration object for the form fields, including serializer functions.
@@ -672,7 +672,7 @@ export const serializeFormToQueryString = <Form extends HoneyFormBaseForm, FormC
 /**
  * Deserializes a form from a query string.
  *
- * @template Form - Type representing the entire form.
+ * @template Form - The type representing the structure of the entire form.
  * @template FormContext - The type representing the context associated with the form.
  *
  * @param {BaseHoneyFormFieldsConfigs<Form, FormContext>} fieldsConfigs - Configuration object for the form fields, including deserializer functions.

src/hooks/use-base-honey-form.ts

@@ -11,7 +11,7 @@ import type {
   HoneyFormState,
   HoneyFormFieldPushValue,
   HoneyFormFieldRemoveValue,
-  HoneyFormFieldSetInternalValue,
+  HoneyFormFieldSetValueInternal,
   HoneyFormFieldAddErrors,
   HoneyFormFieldFinishAsyncValidation,
   HoneyFormValidateField,
@@ -122,9 +122,8 @@ export const useBaseHoneyForm = <
   /**
    * Handles form field changes with optional debouncing.
    *
-   * This function is designed to manage updates to form fields, incorporating an optional debounce mechanism
-   * to limit the frequency of form updates. The debounce functionality is particularly useful when dealing
-   * with inputs that trigger changes frequently, like text fields.
+   * This function is designed to manage updates to form fields, incorporating an optional debounced mechanism
+   * to limit the frequency of form updates.
    *
    * @param initiatorFieldName - The name of the field that triggered the change. This is used to determine
    *                             the appropriate delay time if a custom delay setting (`changeDelay`) is provided for that field.
@@ -186,7 +185,7 @@ export const useBaseHoneyForm = <
   };
 
   /**
-   * @template Form - Type representing the entire form.
+   * @template Form - The type representing the structure of the entire form.
    */
   const setFormValues = useCallback<HoneyFormSetFormValues<Form>>(
     (
@@ -252,7 +251,7 @@ export const useBaseHoneyForm = <
   );
 
   /**
-   * @template Form - Type representing the entire form.
+   * @template Form - The type representing the structure of the entire form.
    */
   const setFormErrors = useCallback<HoneyFormSetFormErrors<Form>>(formErrors => {
     // eslint-disable-next-line @typescript-eslint/no-use-before-define
@@ -281,7 +280,7 @@ export const useBaseHoneyForm = <
   }, []);
 
   /**
-   * @template Form - Type representing the entire form.
+   * @template Form - The type representing the structure of the entire form.
    */
   const finishFieldAsyncValidation: HoneyFormFieldFinishAsyncValidation<Form> = fieldName => {
     // eslint-disable-next-line @typescript-eslint/no-use-before-define
@@ -299,9 +298,9 @@ export const useBaseHoneyForm = <
   /**
    * Set the value of a form field and update the form state accordingly.
    *
-   * @template Form - Type representing the entire form.
+   * @template Form - The type representing the structure of the entire form.
    */
-  const setFieldValue: HoneyFormFieldSetInternalValue<Form> = (
+  const setFieldValue: HoneyFormFieldSetValueInternal<Form> = (
     fieldName,
     fieldValue,
     { isValidate = true, isDirty = true, isFormat = true, isPushValue = false } = {},
@@ -376,7 +375,7 @@ export const useBaseHoneyForm = <
   };
 
   /**
-   * @template Form - Type representing the entire form.
+   * @template Form - The type representing the structure of the entire form.
    */
   const clearFieldErrors: HoneyFormFieldClearErrors<Form> = fieldName => {
     // eslint-disable-next-line @typescript-eslint/no-use-before-define
@@ -392,7 +391,7 @@ export const useBaseHoneyForm = <
   };
 
   /**
-   * @template Form - Type representing the entire form.
+   * @template Form - The type representing the structure of the entire form.
    */
   const pushFieldValue: HoneyFormFieldPushValue<Form> = (fieldName, value) => {
     // @ts-expect-error
@@ -402,7 +401,7 @@ export const useBaseHoneyForm = <
   /**
    * Removes a value from a specific form field that holds an array of values.
    *
-   * @template Form - Type representing the entire form.
+   * @template Form - The type representing the structure of the entire form.
    */
   const removeFieldValue: HoneyFormFieldRemoveValue<Form> = (fieldName, formIndex) => {
     const formFields = formFieldsRef.current;
@@ -517,7 +516,7 @@ export const useBaseHoneyForm = <
    * This function clears the default value of the specified field and removes it
    * from the form fields. The form's internal state and references are updated accordingly.
    *
-   * @template Form - Type representing the entire form.
+   * @template Form - The type representing the structure of the entire form.
    *
    * @param {keyof Form} fieldName - The name of the field to be removed from the form.
    */

src/types/api.types.ts

@@ -1,11 +1,8 @@
 import type {
   HoneyFormAddFormField,
-  HoneyFormBaseForm,
   HoneyFormClearErrors,
   HoneyFormDefaultValues,
   HoneyFormErrors,
-  HoneyFormFieldAddError,
-  HoneyFormFieldAddErrors,
   HoneyFormFields,
   HoneyFormRemoveFormField,
   HoneyFormReset,
@@ -14,8 +11,9 @@ import type {
   HoneyFormSetFormValues,
   HoneyFormSubmit,
   HoneyFormValidate,
-  HoneyFormValues,
 } from './types';
+import type { HoneyFormFieldAddError, HoneyFormFieldAddErrors } from './field.types';
+import type { HoneyFormBaseForm, HoneyFormValues } from './common.types';
 
 export type HoneyFormApi<Form extends HoneyFormBaseForm, FormContext = undefined> = {
   /**
@@ -165,7 +163,7 @@ export type HoneyFormApi<Form extends HoneyFormBaseForm, FormContext = undefined
 /**
  * Represents an API for managing multiple form instances.
  *
- * @template Form - Type representing the entire form.
+ * @template Form - The type representing the structure of the entire form.
  * @template FormContext - The type representing the context associated with the form.
  */
 export type MultiHoneyFormsApi<Form extends HoneyFormBaseForm, FormContext = undefined> = {

src/types/common.types.ts

@@ -0,0 +1,31 @@
+export type HoneyFormFieldName = string;
+
+export type HoneyFormId = string;
+
+/**
+ * Defines the structure of a basic form where each field is identified by a name and holds a value.
+ *
+ * This type is a generic representation of a form where field names are strings, and field values
+ * can be of any type. It serves as a base type for defining more specific forms with defined field types.
+ */
+export type HoneyFormBaseForm = Record<HoneyFormFieldName, unknown>;
+
+/**
+ * Represents a child form that inherits the structure of a basic form.
+ *
+ * This type is used to define forms that are nested within a parent form. It is essentially the same
+ * as `HoneyFormBaseForm`, indicating that child forms follow the same structure as the base form.
+ */
+export type ChildHoneyFormBaseForm = HoneyFormBaseForm;
+
+/**
+ * Defines the possible values for each field in a form, allowing for fields to be `undefined`.
+ *
+ * The type maps each field name to either its value or `undefined`. This is useful when a field's value
+ * may not be set or initialized, allowing for flexibility in handling default values or optional fields.
+ *
+ * @template Form - The type representing the structure of the entire form.
+ */
+export type HoneyFormValues<Form extends HoneyFormBaseForm> = {
+  [FieldName in keyof Form]: Form[FieldName] | undefined;
+};