From 50d724eb6ac6ee0b4933f4812e8b3c2057632f12 Mon Sep 17 00:00:00 2001
From: Divlo <contact@divlo.fr>
Date: Fri, 26 Aug 2022 23:05:38 +0200
Subject: [PATCH] fix(types): improve documentation

---
 README.md               |  8 ++++----
 src/components/Form.tsx |  4 ++++
 src/hooks/useForm.ts    | 25 ++++++++++++++++++++-----
 3 files changed, 28 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index e8c6749..a8cfd9b 100644
--- a/README.md
+++ b/README.md
@@ -24,7 +24,7 @@
 
 There is also a [React Hooks](https://reactjs.org/docs/hooks-intro.html) to be used in combination with the `<Form />` component to validate the data with [Ajv JSON schema validator](https://ajv.js.org/), see [advanced usage](#%EF%B8%8F-advanced-usage).
 
-Demo: [https://react-component-form.vercel.app/](https://react-component-form.vercel.app/).
+Example demo: [https://react-component-form.vercel.app/](https://react-component-form.vercel.app/).
 
 ## 💾 Install
 
@@ -60,8 +60,8 @@ Basically you have access to the same props of the HTML `form` tag in React, but
 
 Instead to get the `event` param you get `formData` and `formElement` parameters:
 
-- `formData`: It's an object where the keys are the name of your inputs and the current value. Behind the scene, it uses the [FormData](https://developer.mozilla.org/docs/Web/API/FormData) constructor.
-- `formElement`: It's the actual HTML form element in the DOM so for example you can access the `.reset()` method on a [HTMLFormElement](https://developer.mozilla.org/docs/Web/API/HTMLFormElement).
+- `formData`: Object where the keys are the name of your inputs and the current value. Behind the scene, it uses the [FormData](https://developer.mozilla.org/docs/Web/API/FormData) constructor.
+- `formElement`: The HTML form element in the DOM so for example you can access the `.reset()` method on a [HTMLFormElement](https://developer.mozilla.org/docs/Web/API/HTMLFormElement).
 
 ## ⚙️ Advanced Usage
 
@@ -122,7 +122,7 @@ export const Example = () => {
 
 #### Returns
 
-- `handleUseForm(onSubmit)`: Function to be used with the `onSubmit` prop of the `<Form />` component.
+- `handleUseForm(onSubmit)`: Function to be used with the `onSubmit` or `onChange` prop of the `<Form />` component.
 - `fetchState = 'idle'`: The current state of the form (`'error' | 'success' | 'idle' | 'loading'`).
 - `setFetchState`: Function to update the `fetchState`.
 - `message`: Global message of the form (not specific to a property).
diff --git a/src/components/Form.tsx b/src/components/Form.tsx
index 5ae4e36..b864fcf 100644
--- a/src/components/Form.tsx
+++ b/src/components/Form.tsx
@@ -4,6 +4,10 @@ export interface FormDataObject {
   [key: string]: FormDataEntryValue
 }
 
+/**
+ * @param formData Object where the keys are the name of your inputs and the current value.
+ * @param formElement The HTML form element in the DOM.
+ */
 export type HandleForm = (
   formData: FormDataObject,
   formElement: HTMLFormElement
diff --git a/src/hooks/useForm.ts b/src/hooks/useForm.ts
index 0c184a2..a508ef4 100644
--- a/src/hooks/useForm.ts
+++ b/src/hooks/useForm.ts
@@ -16,10 +16,17 @@ export type ErrorsObject<K extends Schema> = {
   [key in keyof Partial<K>]: Error[] | undefined
 }
 
+export type HandleUseFormCallbackResult<K extends Schema> = Message<K> | null
+
+/**
+ * @param formData Object where the keys are the name of your inputs and the current value.
+ * @param formElement The HTML form element in the DOM.
+ * @returns The return can be either `null` or an object with a global message of type `'error' | 'success'`.
+ */
 export type HandleUseFormCallback<K extends Schema> = (
   formData: Static<TObject<K>>,
   formElement: HTMLFormElement
-) => Promise<Message<K> | null> | Message<K> | null
+) => Promise<HandleUseFormCallbackResult<K>> | HandleUseFormCallbackResult<K>
 
 export type HandleUseForm<K extends Schema> = (
   callback?: HandleUseFormCallback<K>
@@ -40,8 +47,14 @@ export interface PropertiesMessage<K extends Schema> {
 export type Message<K extends Schema> = GlobalMessage | PropertiesMessage<K>
 
 export interface UseFormResult<K extends Schema> {
+  /**
+   * Function to be used with the `onSubmit` or `onChange` prop of the `<Form />` component.
+   */
   handleUseForm: HandleUseForm<K>
 
+  /**
+   * The current state of the form.
+   */
   readonly fetchState: FetchState
   setFetchState: React.Dispatch<React.SetStateAction<FetchState>>
 
@@ -52,11 +65,13 @@ export interface UseFormResult<K extends Schema> {
   setMessage: React.Dispatch<React.SetStateAction<string | undefined>>
 
   /**
-   * Errors for each property.
+   * Object of errors:
+   *  - Key: correspond to a property in the JSON Schema.
+   *  - Value: array of {@link ErrorObject}.
    *
-   * The array will always have at least one element (never empty) in case of errors.
+   *    The array will always have at least one element (never empty) in case of errors.
    *
-   * `undefined` means no errors.
+   *    If the value is `undefined`, it means there are no errors for this property.
    */
   readonly errors: ErrorsObject<K>
 }
@@ -110,7 +125,7 @@ export const useForm = <K extends Schema>(
             formElement
           )
           if (message != null) {
-            const { value = undefined, type, properties } = message
+            const { value, type, properties } = message
             setMessage(value)
             setFetchState(type)
             if (type === 'error') {