fix(types): improve documentation

This commit is contained in:
Divlo 2022-08-26 23:05:38 +02:00
parent c979bab553
commit 50d724eb6a
No known key found for this signature in database
GPG Key ID: 8F9478F220CE65E9
3 changed files with 28 additions and 9 deletions

View File

@ -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).

View File

@ -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

View File

@ -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') {