feat(Form): handle @error event (#718)

Co-authored-by: Albert <albert@Alberts-MacBook-Pro.local>
Co-authored-by: Romain Hamel <romain@boilr.io>
Co-authored-by: Benjamin Canac <canacb1@gmail.com>

docs/components/content/examples/FormExampleBasic.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import type { FormError, FormSubmitEvent } from '@nuxt/ui/dist/runtime/types'
+import type { FormError, FormSubmitEvent } from '#ui/types'
 
 const state = reactive({
   email: undefined,
@@ -13,18 +13,14 @@ const validate = (state: any): FormError[] => {
   return errors
 }
 
-async function submit (event: FormSubmitEvent<any>) {
+async function onSubmit (event: FormSubmitEvent<any>) {
   // Do something with data
   console.log(event.data)
 }
 </script>
 
 <template>
-  <UForm
-    :validate="validate"
-    :state="state"
-    @submit="submit"
-  >
+  <UForm :validate="validate" :state="state" @submit="onSubmit">
     <UFormGroup label="Email" name="email">
       <UInput v-model="state.email" />
     </UFormGroup>

docs/components/content/examples/FormExampleElements.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { z } from 'zod'
-import type { FormSubmitEvent } from '@nuxt/ui/dist/runtime/types'
+import type { FormSubmitEvent } from '#ui/types'
 
 const options = [
   { label: 'Option 1', value: 'option-1' },
@@ -45,19 +45,14 @@ type Schema = z.infer<typeof schema>
 
 const form = ref()
 
-async function submit (event: FormSubmitEvent<Schema>) {
+async function onSubmit (event: FormSubmitEvent<Schema>) {
   // Do something with event.data
   console.log(event.data)
 }
 </script>
 
 <template>
-  <UForm
-    ref="form"
-    :schema="schema"
-    :state="state"
-    @submit="submit"
-  >
+  <UForm ref="form" :schema="schema" :state="state" @submit="onSubmit">
     <UFormGroup name="input" label="Input">
       <UInput v-model="state.input" />
     </UFormGroup>

docs/components/content/examples/FormExampleJoi.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import Joi from 'joi'
-import type { FormSubmitEvent } from '@nuxt/ui/dist/runtime/types'
+import type { FormSubmitEvent } from '#ui/types'
 
 const schema = Joi.object({
   email: Joi.string().required(),
@@ -14,18 +14,14 @@ const state = reactive({
   password: undefined
 })
 
-async function submit (event: FormSubmitEvent<any>) {
+async function onSubmit (event: FormSubmitEvent<any>) {
   // Do something with event.data
   console.log(event.data)
 }
 </script>
 
 <template>
-  <UForm
-    :schema="schema"
-    :state="state"
-    @submit="submit"
-  >
+  <UForm :schema="schema" :state="state" @submit="onSubmit">
     <UFormGroup label="Email" name="email">
       <UInput v-model="state.email" />
     </UFormGroup>

docs/components/content/examples/FormExampleOnError.vue

@@ -0,0 +1,42 @@
+<script setup lang="ts">
+import type { FormError, FormErrorEvent, FormSubmitEvent } from '#ui/types'
+
+const state = reactive({
+  email: undefined,
+  password: undefined
+})
+
+const validate = (state: any): FormError[] => {
+  const errors = []
+  if (!state.email) errors.push({ path: 'email', message: 'Required' })
+  if (!state.password) errors.push({ path: 'password', message: 'Required' })
+  return errors
+}
+
+async function onSubmit (event: FormSubmitEvent<any>) {
+  // Do something with data
+  console.log(event.data)
+}
+
+async function onError (event: FormErrorEvent) {
+  const element = document.getElementById(event.errors[0].id)
+  element?.focus()
+  element?.scrollIntoView({ behavior: 'smooth', block: 'center' })
+}
+</script>
+
+<template>
+  <UForm :validate="validate" :state="state" @submit="onSubmit" @error="onError">
+    <UFormGroup label="Email" name="email">
+      <UInput v-model="state.email" />
+    </UFormGroup>
+
+    <UFormGroup label="Password" name="password">
+      <UInput v-model="state.password" type="password" />
+    </UFormGroup>
+
+    <UButton type="submit">
+      Submit
+    </UButton>
+  </UForm>
+</template>

docs/components/content/examples/FormExampleValibot.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { string, objectAsync, email, minLength, Input } from 'valibot'
-import type { FormSubmitEvent } from '@nuxt/ui/dist/runtime/types'
+import type { FormSubmitEvent } from '#ui/types'
 
 const schema = objectAsync({
   email: string([email('Invalid email')]),
@@ -14,18 +14,14 @@ const state = reactive({
   password: undefined
 })
 
-async function submit (event: FormSubmitEvent<Schema>) {
+async function onSubmit (event: FormSubmitEvent<Schema>) {
   // Do something with event.data
   console.log(event.data)
 }
 </script>
 
 <template>
-  <UForm
-    :schema="schema"
-    :state="state"
-    @submit="submit"
-  >
+  <UForm :schema="schema" :state="state" @submit="onSubmit">
     <UFormGroup label="Email" name="email">
       <UInput v-model="state.email" />
     </UFormGroup>

docs/components/content/examples/FormExampleYup.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { object, string, InferType } from 'yup'
-import type { FormSubmitEvent } from '@nuxt/ui/dist/runtime/types'
+import type { FormSubmitEvent } from '#ui/types'
 
 const schema = object({
   email: string().email('Invalid email').required('Required'),
@@ -16,18 +16,14 @@ const state = reactive({
   password: undefined
 })
 
-async function submit (event: FormSubmitEvent<Schema>) {
+async function onSubmit (event: FormSubmitEvent<Schema>) {
   // Do something with event.data
   console.log(event.data)
 }
 </script>
 
 <template>
-  <UForm
-    :schema="schema"
-    :state="state"
-    @submit="submit"
-  >
+  <UForm :schema="schema" :state="state" @submit="onSubmit">
     <UFormGroup label="Email" name="email">
       <UInput v-model="state.email" />
     </UFormGroup>

docs/components/content/examples/FormExampleZod.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { z } from 'zod'
-import type { FormSubmitEvent } from '@nuxt/ui/dist/runtime/types'
+import type { FormSubmitEvent } from '#ui/types'
 
 const schema = z.object({
   email: z.string().email('Invalid email'),
@@ -14,18 +14,14 @@ const state = reactive({
   password: undefined
 })
 
-async function submit (event: FormSubmitEvent<Schema>) {
+async function onSubmit (event: FormSubmitEvent<Schema>) {
   // Do something with data
   console.log(event.data)
 }
 </script>
 
 <template>
-  <UForm
-    :schema="schema"
-    :state="state"
-    @submit="submit"
-  >
+  <UForm :schema="schema" :state="state" @submit="onSubmit">
     <UFormGroup label="Email" name="email">
       <UInput v-model="state.email" />
     </UFormGroup>

docs/content/1.getting-started/5.examples.md

@@ -130,6 +130,7 @@ Our theming system provides a lot of flexibility to customize the components.
 Here is some examples of what you can do with the [CommandPalette](/navigation/command-palette).
 
 #### Algolia
+
 ::component-example
 ---
 padding: false

docs/content/3.forms/10.form.md

@@ -35,7 +35,6 @@ You can provide a schema from [Yup](#yup), [Zod](#zod) or [Joi](#joi), [Valibot]
 
 :component-example{component="form-example-joi" :componentProps='{"class": "space-y-4 w-60"}'}
 
-
 ### Valibot
 
 :component-example{component="form-example-valibot" :componentProps='{"class": "space-y-4 w-60"}'}
@@ -87,7 +86,7 @@ You can manually set errors after form submission if required. To do this, simpl
 
 ```vue
 <script setup lang="ts">
-import type { FormError, FormSubmitEvent } from '@nuxt/ui/dist/runtime/types'
+import type { FormError, FormSubmitEvent } from '#ui/types'
 
 const state = reactive({
   email: undefined,
@@ -96,7 +95,7 @@ const state = reactive({
 
 const form = ref()
 
-async function submit (event: FormSubmitEvent<any>) {
+async function onSubmit (event: FormSubmitEvent<any>) {
   form.value.clear()
   try {
     const response = await $fetch('...')
@@ -112,7 +111,7 @@ async function submit (event: FormSubmitEvent<any>) {
 </script>
 
 <template>
-  <UForm ref="form" :state="state" @submit="submit">
+  <UForm ref="form" :state="state" @submit="onSubmit">
     <UFormGroup label="Email" name="email">
       <UInput v-model="state.email" />
     </UFormGroup>
@@ -138,6 +137,18 @@ The Form component automatically triggers validation upon `submit`, `input`, `bl
 Take a look at the component!
 ::
 
+## Error event :u-badge{label="New" class="align-middle ml-2 !rounded-full" variant="subtle"}
+
+You can listen to the `@error` event to handle errors. This event is triggered when the form is validated and contains an array of `FormError` objects with the following fields:
+
+- `id` - the identifier of the form element.
+- `path` - the path to the form element matching the `name`.
+- `message` - the error message to display.
+
+Here is an example of how to focus the first form element with an error:
+
+:component-example{component="form-example-on-error" :componentProps='{"class": "space-y-4 w-60"}'}
+
 ## Props
 
 :component-props

src/runtime/components/forms/Form.vue

@@ -11,9 +11,17 @@ import type { ZodSchema } from 'zod'
 import type { ValidationError as JoiError, Schema as JoiSchema } from 'joi'
 import type { ObjectSchema as YupObjectSchema, ValidationError as YupError } from 'yup'
 import type { ObjectSchemaAsync as ValibotObjectSchema } from 'valibot'
-import type { FormError, FormEvent, FormEventType, FormSubmitEvent, Form } from '../../types/form'
+import type { FormError, FormEvent, FormEventType, FormSubmitEvent, FormErrorEvent, Form } from '../../types/form'
 import { uid } from '../../utils/uid'
 
+class FormException extends Error {
+  constructor (message: string) {
+    super(message)
+    this.message = message
+    Object.setPrototypeOf(this, FormException.prototype)
+  }
+}
+
 export default defineComponent({
   props: {
     schema: {
@@ -39,7 +47,7 @@ export default defineComponent({
       default: () => ['blur', 'input', 'change', 'submit']
     }
   },
-  emits: ['submit'],
+  emits: ['submit', 'error'],
   setup (props, { expose, emit }) {
     const bus = useEventBus<FormEvent>(`form-${uid()}`)
 
@@ -52,6 +60,8 @@ export default defineComponent({
     const errors = ref<FormError[]>([])
     provide('form-errors', errors)
     provide('form-events', bus)
+    const inputs = ref({})
+    provide('form-inputs', inputs)
 
     async function getErrors (): Promise<FormError[]> {
       let errs = await props.validate(props.state)
@@ -87,7 +97,7 @@ export default defineComponent({
       }
 
       if (!opts.silent && errors.value.length > 0) {
-        throw new Error(
+        throw new FormException(
           `Form validation failed: ${JSON.stringify(errors.value, null, 2)}`
         )
       }
@@ -95,12 +105,29 @@ export default defineComponent({
     }
 
     async function onSubmit (event: SubmitEvent) {
-      if (props.validateOn?.includes('submit')) {
-        await validate()
+      try {
+        if (props.validateOn?.includes('submit')) {
+          await validate()
+        }
+        const submitEvent: FormSubmitEvent<any> = {
+          ...event,
+          data: props.state
+        }
+        emit('submit', submitEvent)
+      } catch (error) {
+        if (!(error instanceof FormException)) {
+          throw error
+        }
+
+        const errorEvent: FormErrorEvent = {
+          ...event,
+          errors: errors.value.map((err) => ({
+            ...err,
+            id: inputs.value[err.path]
+          }))
+        }
+        emit('error', errorEvent)
       }
-      const submitEvent = event as FormSubmitEvent<any>
-      submitEvent.data = props.state
-      emit('submit', event)
     }
 
     expose({

src/runtime/composables/useFormGroup.ts

@@ -1,22 +1,32 @@
-import { inject, ref, computed } from 'vue'
+import { inject, ref, computed, onMounted } from 'vue'
 import { type UseEventBusReturn, useDebounceFn } from '@vueuse/core'
 import type { FormEvent, FormEventType, InjectedFormGroupValue } from '../types/form'
 
 type InputProps = {
   id?: string
-  size?: string
+  size?: string | number | symbol
   color?: string
   name?: string
 }
 
 export const useFormGroup = (inputProps?: InputProps, config?: any) => {
     const formBus = inject<UseEventBusReturn<FormEvent, string> | undefined>('form-events', undefined)
-    const formGroup = inject<InjectedFormGroupValue>('form-group', undefined)
+    const formGroup = inject<InjectedFormGroupValue | undefined>('form-group', undefined)
+    const formInputs = inject<any>('form-inputs', undefined)
 
-    if (formGroup) {
-      // Updates for="..." attribute on label if inputProps.id is provided
-      formGroup.inputId.value = inputProps?.id ?? formGroup?.inputId.value
-    }
+    const inputId = ref(inputProps?.id)
+
+    onMounted(() => {
+      inputId.value = inputProps?.id ?? formGroup?.inputId.value
+      if (formGroup) {
+        // Updates for="..." attribute on label if inputProps.id is provided
+        formGroup.inputId.value = inputId.value
+
+        if (formInputs) {
+          formInputs.value[formGroup.name.value] = inputId
+        }
+      }
+    })
 
     const blurred = ref(false)
 
@@ -42,7 +52,7 @@ export const useFormGroup = (inputProps?: InputProps, config?: any) => {
     }, 300)
 
     return {
-      inputId: computed(() => inputProps.id ?? formGroup?.inputId.value),
+      inputId,
       name: computed(() => inputProps?.name ?? formGroup?.name.value),
       size: computed(() => inputProps?.size ?? formGroup?.size.value ?? config?.default?.size),
       color: computed(() => formGroup?.error?.value ? 'red' : inputProps?.color),

src/runtime/types/form.d.ts

@@ -1,10 +1,16 @@
-export interface FormError {
-  path: string
+import { Ref } from 'vue'
+
+export interface FormError<T extends string = string> {
+  path: T
   message: string
 }
 
+export interface FormErrorWithId extends FormError {
+  id: string
+}
+
 export interface Form<T> {
-  validate(path?: string, opts: { silent?: boolean }): Promise<T>
+  validate(path?: string, opts?: { silent?: boolean }): Promise<T>
   clear(path?: string): void
   errors: Ref<FormError[]>
   setErrors(errs: FormError[], path?: string): void
@@ -12,17 +18,18 @@ export interface Form<T> {
 }
 
 export type FormSubmitEvent<T> = SubmitEvent & { data: T }
+export type FormErrorEvent = SubmitEvent & { errors: FormErrorWithId[] }
 
 export type FormEventType = 'blur' | 'input' | 'change' | 'submit'
 
 export interface FormEvent {
   type: FormEventType
-  path: string
+  path?: string
 }
 
 export interface InjectedFormGroupValue {
-  inputId: Ref<string>
+  inputId: Ref<string | undefined>
   name: Ref<string>
-  size: Ref<string>
+  size: Ref<string | number | symbol>
   error: Ref<string | boolean>
 }