Merge branch 'main' into third-party-adapters

docs/framework/react/reference/useForm.md

@@ -6,15 +6,12 @@ title: useForm
 ### `useForm`
 
 ```tsx
-export function useForm<TData>(
-  opts?: FormOptions<TData> & { listen?: (state: FormState<TData>) => any },
-): FormApi<TData>
+export function useForm<TData>(opts?: FormOptions<TData>): FormApi<TData>
 ```
+A custom react hook that returns an instance of the `FormApi<TData>` class.
+This API encapsulates all the necessary functionalities related to the form. It allows you to manage form state, handle submissions, and interact with form fields
 
-A custom hook that returns an instance of the `FormApi<TData>` class.
 
-- `opts`
-  - Optional form options and a `listen` function to be called with the form state.
 
 ### `FormProps`
 
@@ -23,12 +20,56 @@ An object type representing the form component props.
 - Inherits from `React.HTMLProps<HTMLFormElement>`.
 - `children: React.ReactNode`
   - The form's child elements.
-- `noFormElement?: boolean`
-  - If true, the form component will not render an HTML form element.
 
-### `FormComponent`
+```tsx
+  onSubmit: (e: FormSubmitEvent) => void
+```
+  - `onSubmit` function of type `FormSubmitEvent = React.FormEvent<HTMLFormElement>`
+
+```tsx
+  disabled: boolean
+```
+  - `disabled` boolean to disable form
+
+
+
+### Return value of `UseForm` is  `FormApi<TFormData>`
+
+- The `FormApi` contains the following properties
+
+```tsx
+Provider: (props: { children: any }) => any
+```
+- React provider use to wrap your components
+- Reference React [ContextProvider]("https://react.dev/reference/react/createContext#provider")
+
 
-A type representing a form component.
 
-- `(props: FormProps) => any`
-  - A function that takes `FormProps` as an argument and returns a form component.
+```tsx
+   Field: FieldComponent<TFormData, TFormData>getFormProps: () => FormProps
+```
+- A React component to render form fields. With this, you can render and manage individual form fields.
+
+```tsx
+   useField: UseField<TFormData>
+```
+- A custom React hook that provides functionalities related to individual form fields. It gives you access to field values, errors, and allows you to set or update field values.
+
+
+```tsx
+   useStore: <TSelected = NoInfer<FormState<TFormData>>>(
+      selector?: (state: NoInfer<FormState<TFormData>>) => TSelected,
+    ) => TSelected
+```
+- a `useStore` hook that connects to the internal store of the form. It can be used to access the form's current state or any other related state information. You can optionally pass in a selector function to cherry-pick specific parts of the state
+
+
+```tsx
+   Subscribe: <TSelected = NoInfer<FormState<TFormData>>>(props: {
+      selector?: (state: NoInfer<FormState<TFormData>>) => TSelected
+      children:
+        | ((state: NoInfer<TSelected>) => React.ReactNode)
+        | React.ReactNode
+    }) => any
+```
+- a `Subscribe` function that allows you to listen and react to changes in the form's state. It's especially useful when you need to execute side effects or render specific components in response to state updates.

docs/reference/formApi.md

@@ -5,7 +5,7 @@ title: Form API
 
 ### Creating a new FormApi Instance
 
-> Some of these docs may be inaccurate due to an API shift in `0.11.0`. If you're interested in helping us fix these issues, please [join our Discord](https://tlinz.com/discord) and reach out in the `#form` channel.
+
 
 Normally, you will not need to create a new `FormApi` instance directly. Instead, you will use a framework hook/function like `useForm` or `createForm` to create a new instance for you that utilizes your frameworks reactivity model. However, if you need to create a new instance manually, you can do so by calling the `new FormApi` constructor.
 
@@ -20,60 +20,91 @@ An object representing the options for a form.
 - ```tsx
     defaultValues?: TData
   ```
-  - The default values for the form fields.
+  - Set initial values for you form.
 - ```tsx
     defaultState?: Partial<FormState<TData>>
   ```
   - The default state for the form.
+
+- ```tsx
+    asyncDebounceMs?: number
+  ```
+  -  Optional time in milliseconds if you want to introduce a delay before firing off an async action.
+
+- ```tsx
+      onMount?: (values: TData, formApi: FormApi<TData>) => ValidationError
+  ```
+  -  Optional function that fires as soon as the component mounts.
+- ```tsx
+    onMountAsync?: ( values: TData, formApi: FormApi<TData>) => ValidationError | Promise<ValidationError>
+  ```
+  -  Optional async function that fires when the component mounts
 - ```tsx
-    onSubmit?: (values: TData, formApi: FormApi<TData>) => Promise<any>
+    onMountAsyncDebounceMs?: number
   ```
-  - A function to be called when the form is submitted and valid.
+  - The default time in milliseconds that if set to a number larger than 0, will debounce the async validation event by this length of time in milliseconds.
+
 - ```tsx
-    onInvalidSubmit?: (values: TData, formApi: FormApi<TData>) => void
+     onChange?: (values: TData, formApi: FormApi<TData>) => ValidationError
   ```
-  - A function to be called when the form is submitted but invalid.
+  -  Optional function that checks the validity of your data whenever a value changes
+
 - ```tsx
-    validate?: (values: TData, formApi: FormApi<TData>) => Promise<any>
+    onChangeAsync?: (values: TData, formApi: FormApi<TData>) => ValidationError | Promise<ValidationError>
   ```
-  - A function for custom validation logic for the form.
+  -  Optional onChange  asynchronous counterpart to onChange. Useful for more complex validation logic that might involve server requests.
+
 - ```tsx
-    defaultValidatePristine?: boolean
+    onChangeAsyncDebounceMs?: number
   ```
-  - A boolean flag to enable or disable validation for pristine fields.
+  - The default time in milliseconds that if set to a number larger than 0, will debounce the async validation event by this length of time in milliseconds.
+
 - ```tsx
-    defaultValidateOn?: ValidationCause
+    onBlur?: (values: TData, formApi: FormApi<TData>) => ValidationError
   ```
-  - The default minimum cause for a field to be synchronously validated
+  -  Optional  function that validates the form data when a field loses focus, returns a `ValidationError`
+
 - ```tsx
-    defaultValidateAsyncOn?: ValidationCause
+    onBlurAsync?:  (values: TData,formApi: FormApi<TData>) => ValidationError | Promise<ValidationError>
   ```
-  - The default minimum cause for a field to be asynchronously validated
+  -  Optional onBlur asynchronous validation method for when a field loses focus return a `ValidationError`  or a promise of `Promise<ValidationError>`
+
 - ```tsx
-    defaultValidateAsyncDebounceMs?: number
+    onBlurAsyncDebounceMs?: number
   ```
   - The default time in milliseconds that if set to a number larger than 0, will debounce the async validation event by this length of time in milliseconds.
 
+- ```tsx
+      onSubmit?: (values: TData, formApi: FormApi<TData>) => any | Promise<any>
+  ```
+  - A function to be called when the form is submitted, what should happen once the user submits a valid form  returns `any` or a promise `Promise<any>`
+
+- ```tsx
+    onSubmitInvalid?: (values: TData, formApi: FormApi<TData>) => void
+  ```
+  - Specify an action for scenarios where the user tries to submit an invalid form.
+
+
 ### `FormApi<TFormData>`
 
 A class representing the Form API. It handles the logic and interactions with the form state.
 
 #### Properties
 
 - ```tsx
-  options: FormOptions<TFormData>
+  options: FormOptions<TFormData> = {}
   ```
   - The options for the form.
 - ```tsx
   store: Store<FormState<TFormData>>
   ```
-  - The internal store for the form state.
+  - An internal mechanism that keeps track of the form's state.
 - ```tsx
   state: FormState<TFormData>
   ```
   - The current state of the form.
 - ```tsx
-  fieldInfo: Record<DeepKeys<TFormData>, FieldInfo<TFormData>>
+  fieldInfo: Record<DeepKeys<TFormData>, FieldInfo<TFormData>> ={} as any
   ```
   - A record of field information for each field in the form.
 - ```tsx
@@ -103,12 +134,9 @@ A class representing the Form API. It handles the logic and interactions with th
   validateAllFields()
   ```
   - Validates all fields in the form.
+
 - ```tsx
-  validateForm()
-  ```
-  - Validates the form itself.
-- ```tsx
-    handleSubmit(e: FormEvent & { __handled?: boolean })
+    handleSubmit(e: FormSubmitEvent)
   ```
   - Handles the form submission event, performs validation, and calls the appropriate onSubmit or onInvalidSubmit callbacks.
 - ```tsx
@@ -221,22 +249,9 @@ An object representing the field information for a specific field within the for
   instances: Record<string, FieldApi<any, TFormData>>
   ```
   - A record of field instances with unique identifiers as keys.
-- ```tsx
-    validationCount?: number
-  ```
-  - A counter for tracking the number of validations performed on the field.
-- ```tsx
-    validationPromise?: Promise<ValidationError>
-  ```
-  - A promise representing the current validation state of the field.
-- ```tsx
-    validationResolve?: (error: ValidationError) => void
-  ```
-  - A function to resolve the validation promise with a possible validation error.
-- ```tsx
-    validationReject?: (error: unknown) => void
-  ```
-  - A function to reject the validation promise with an error.
+  - Check below for `ValidationMeta`
+
+
 
 ### `ValidationMeta`
 
@@ -246,6 +261,11 @@ An object representing the validation metadata for a field.
     validationCount?: number
   ```
   - A counter for tracking the number of validations performed on the field.
+
+- ```tsx
+    validationAsyncCount?: number
+  ```
+  - A counter for tracking the number of validations performed on the field async.
 - ```tsx
     validationPromise?: Promise<ValidationError>
   ```