chore: clean up and docs

Author: harry-whorlow

docs/framework/react/guides/listeners.md

@@ -89,3 +89,34 @@ We enable an easy method for debouncing your listeners by adding a `onChangeDebo
   )}
 </form.Field>
 ```
+
+### form listeners
+
+At a higher level, listeners are also available at the form level, allowing you access to the `onMount` and `onSubmit` events, and having `onChange` and `onBlur` propagated to all the form's children.
+
+`onMount` and `onSubmit` listeners have to following props:
+
+- formApi
+
+`onChange` and `onBlur` listeners have access to formApi, as well as:
+
+- fieldName
+- fieldApi
+
+```tsx
+const form = useForm({
+  listeners: {
+    onMount: ({ formApi }) => {
+      // custom logging service
+      loggingService('mount', formApi.state.values)
+    },
+
+    onChange: ({ formApi }) => {
+      // autosave logic
+      if (formApi.state.isValid) {
+        formApi.handleSubmit()
+      }
+    },
+  },
+})
+```

packages/form-core/src/FieldApi.ts

@@ -1645,6 +1645,11 @@ export class FieldApi<
 
   private triggerOnBlurListener() {
     const debounceMs = this.options.listeners?.onBlurDebounceMs
+    this.form.options.listeners?.onBlur?.({
+      fieldName: this.name,
+      formApi: this.form,
+      fieldApi: this,
+    })
 
     if (debounceMs && debounceMs > 0) {
       if (this.timeoutIds.listeners.blur) {
@@ -1656,30 +1661,24 @@ export class FieldApi<
           value: this.state.value,
           fieldApi: this,
         })
-
-        this.form.options.listeners?.onBlur?.({
-          fieldName: this.name,
-          formApi: this.form,
-          fieldApi: this,
-        })
       }, debounceMs)
     } else {
       this.options.listeners?.onBlur?.({
         value: this.state.value,
         fieldApi: this,
       })
-
-      this.form.options.listeners?.onBlur?.({
-        fieldName: this.name,
-        formApi: this.form,
-        fieldApi: this,
-      })
     }
   }
 
   private triggerOnChangeListener() {
     const debounceMs = this.options.listeners?.onChangeDebounceMs
 
+    this.form.options.listeners?.onChange?.({
+      fieldName: this.name as never,
+      formApi: this.form,
+      fieldApi: this,
+    })
+
     if (debounceMs && debounceMs > 0) {
       if (this.timeoutIds.listeners.change) {
         clearTimeout(this.timeoutIds.listeners.change)
@@ -1690,24 +1689,12 @@ export class FieldApi<
           value: this.state.value,
           fieldApi: this,
         })
-
-        this.form.options.listeners?.onChange?.({
-          fieldName: this.name as never,
-          formApi: this.form,
-          fieldApi: this,
-        })
       }, debounceMs)
     } else {
       this.options.listeners?.onChange?.({
         value: this.state.value,
         fieldApi: this,
       })
-
-      this.form.options.listeners?.onChange?.({
-        fieldName: this.name as never,
-        formApi: this.form,
-        fieldApi: this,
-      })
     }
   }
 }