feat(Form): automatically focus the first field with an error upon submission failure

docs/app/components/content/examples/form/FormExampleOnError.vue

@@ -22,10 +22,9 @@ async function onSubmit(event: FormSubmitEvent<Schema>) {
 }
 
 async function onError(event: FormErrorEvent) {
-  if (event?.errors?.[0]?.id) {
-    const element = document.getElementById(event.errors[0].id)
-    element?.focus()
-    element?.scrollIntoView({ behavior: 'smooth', block: 'center' })
+  const error = event.errors[0]
+  if (error) {
+    toast.add({ title: 'Error', description: `Please check the form ${error.name}.`, color: 'error' })
   }
 }
 </script>

docs/content/docs/2.components/form.md

@@ -158,7 +158,11 @@ You can listen to the `@error` event to handle errors. This event is triggered w
 - `name` - the `name` of the `FormField`
 - `message` - the error message to display.
 
-Here's an example that focuses the first input element with an error after the form is submitted:
+::tip
+By default, the form automatically focuses the first field with an error when submission fails through the `focus-on-error` prop. You can disable this by passing `:focus-on-error="false"`.
+::
+
+Here's an example of using the `@error` event to add custom behavior, such as displaying a toast notification when validation fails:
 
 ::component-example
 ---

src/runtime/components/Form.vue

@@ -60,6 +60,11 @@ export type FormProps<S extends FormSchema, T extends boolean = true, N extends
    * @defaultValue `true`
    */
   loadingAuto?: boolean
+  /**
+   * When `true`, the form automatically focuses the first field with an error on failed submission.
+   * @defaultValue `true`
+   */
+  focusOnError?: boolean
   class?: any
   ui?: { base?: any }
   onSubmit?: ((event: FormSubmitEvent<FormData<S, T>>) => void | Promise<void>) | (() => void | Promise<void>)
@@ -82,7 +87,7 @@ import { useAppConfig } from '#imports'
 import { formOptionsInjectionKey, formInputsInjectionKey, formBusInjectionKey, formLoadingInjectionKey, formErrorsInjectionKey, formStateInjectionKey } from '../composables/useFormField'
 import { tv } from '../utils/tv'
 import { useComponentProps } from '../composables/useComponentProps'
-import { validateSchema, getAtPath, setAtPath } from '../utils/form'
+import { validateSchema, getAtPath, setAtPath, scrollToErrorEl } from '../utils/form'
 import { FormValidationException } from '../types/form'
 
 type I = InferInput<S>
@@ -93,6 +98,7 @@ const _props = withDefaults(defineProps<FormProps<S, T, N>>(), {
     return ['input', 'blur', 'change'] as FormInputEvents[]
   },
   validateOnInputDelay: 300,
+  focusOnError: true,
   transform: () => true as T,
   loadingAuto: true
 })
@@ -280,6 +286,10 @@ async function onSubmitWrapper(payload: Event) {
       throw error
     }
 
+    if (props.focusOnError) {
+      scrollToErrorEl(error.errors)
+    }
+
     const errorEvent: FormErrorEvent = {
       ...event,
       errors: error.errors

src/runtime/utils/form.ts

@@ -1,6 +1,6 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec'
 import type { Struct } from 'superstruct'
-import type { FormSchema, ValidateReturnSchema } from '../types/form'
+import type { FormErrorWithId, FormSchema, ValidateReturnSchema } from '../types/form'
 
 export function isSuperStructSchema(schema: any): schema is Struct<any, any> {
   return (
@@ -114,3 +114,17 @@ export function setAtPath<T extends object>(
 
   return data
 }
+
+let timeOut: NodeJS.Timeout | null = null
+export function scrollToErrorEl(errors: FormErrorWithId[]) {
+  const error = errors[0]
+  if (error) {
+    const el = document.getElementById(error.id!)
+    if (el) {
+      if (timeOut) clearTimeout(timeOut)
+      timeOut = setTimeout(() => {
+        el.focus()
+      }, 0)
+    }
+  }
+}

test/components/Form.spec.ts

@@ -275,6 +275,24 @@ describe('Form', () => {
       expect(passwordField.text()).toBe('Invalid input: expected string, received undefined')
     })
 
+    it('focuses on first error element on submit error', async () => {
+      const emailInputMock = { focus: vi.fn() }
+      const passwordInputMock = { focus: vi.fn() }
+      const getElementByIdSpy = vi.spyOn(document, 'getElementById').mockImplementation((id) => {
+        if (id === 'email') return emailInputMock as any
+        if (id === 'password') return passwordInputMock as any
+        return null
+      })
+
+      await form.submit()
+      await new Promise(resolve => setTimeout(resolve, 0))
+
+      expect(emailInputMock.focus).toHaveBeenCalledTimes(1)
+      expect(passwordInputMock.focus).toHaveBeenCalledTimes(0)
+
+      getElementByIdSpy.mockRestore()
+    })
+
     it('validate on submit works', async () => {
       state.email = 'bob@dylan.com'
       state.password = 'strongpassword'