arthur/ui
1
0
Fork 0
mirror of https://github.com/ArthurDanjou/ui.git synced 2026-01-21 15:31:46 +01:00
Code Issues Packages Projects Releases Wiki Activity

feat(Form): improve form control and input validation trigger (#487)

Browse Source 
Co-authored-by: Benjamin Canac <canacb1@gmail.com>
This commit is contained in:
Romain Hamel
2023-08-12 16:48:53 +02:00
committed by Benjamin Canac
parent 60bb74675c
commit 6d7973f6e1
23 changed files with 529 additions and 381 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/components/content/ComponentCard.vue
View File

@@ -164,9 +164,7 @@ const code = computed(() => {
continue
}
const prop = meta?.meta?.props?.find((prop: any) => prop.name === key)
code += ` ${(prop?.type === 'boolean' && value !== true) || typeof value === 'object' ? ':' : ''}${key === 'modelValue' ? 'value' : useKebabCase(key)}${prop?.type === 'boolean' && !!value && key !== 'modelValue' ? '' : `="${typeof value === 'object' ? renderObject(value) : value}"`}`
code += ` ${(typeof value === 'boolean' && value !== true) || typeof value === 'object' ? ':' : ''}${key === 'modelValue' ? 'value' : useKebabCase(key)}${typeof value === 'boolean' && !!value && key !== 'modelValue' ? '' : `="${typeof value === 'object' ? renderObject(value) : value}"`}`
}
if (props.slots) {

13
docs/components/content/examples/FormExampleBasic.vue
View File

@@ -1,6 +1,6 @@
<script setup lang="ts">
import { ref } from 'vue'
import type { FormError } from '@nuxthq/ui/dist/runtime/types'
import type { FormError, FormSubmitEvent } from '@nuxthq/ui/dist/runtime/types'
const state = ref({
email: undefined,
@@ -14,20 +14,17 @@ const validate = (state: any): FormError[] => {
return errors
}
const form = ref()
async function submit () {
await form.value!.validate()
// Do something with state.value
async function submit (event: FormSubmitEvent<any>) {
// Do something with data
console.log(event.data)
}
</script>
<template>
<UForm
ref="form"
:validate="validate"
:state="state"
@submit.prevent="submit"
@submit="submit"
>
<UFormGroup label="Email" name="email">
<UInput v-model="state.email" />

16
docs/components/content/examples/FormExampleElements.vue
View File

@@ -1,7 +1,7 @@
<script setup lang="ts">
import { ref } from 'vue'
import { z } from 'zod'
import type { Form } from '@nuxthq/ui/dist/runtime/types'
import type { FormSubmitEvent } from '@nuxthq/ui/dist/runtime/types'
const options = [
{ label: 'Option 1', value: 'option-1' },
@@ -44,11 +44,11 @@ const schema = z.object({
type Schema = z.infer<typeof schema>
const form = ref<Form<Schema>>()
const form = ref()
async function submit () {
await form.value!.validate()
// Do something with state.value
async function submit (event: FormSubmitEvent<Schema>) {
// Do something with event.data
console.log(event.data)
}
</script>
@@ -57,7 +57,7 @@ async function submit () {
ref="form"
:schema="schema"
:state="state"
@submit.prevent="submit"
@submit="submit"
>
<UFormGroup name="input" label="Input">
<UInput v-model="state.input" />
@@ -96,5 +96,9 @@ async function submit () {
<UButton type="submit">
Submit
</UButton>
<UButton variant="outline" class="ml-2" @click="form.clear()">
Clear
</UButton>
</UForm>
</template>

28
docs/components/content/examples/FormExampleJoi.vue
View File

@@ -1,40 +1,38 @@
<script setup lang="ts">
import { ref } from 'vue'
import Joi from 'joi'
import type { FormSubmitEvent } from '@nuxthq/ui/dist/runtime/types'
const schema = Joi.object({
emailJoi: Joi.string().required(),
passwordJoi: Joi.string()
email: Joi.string().required(),
password: Joi.string()
.min(8)
.required()
})
const state = ref({
emailJoi: undefined,
passwordJoi: undefined
email: undefined,
password: undefined
})
const form = ref()
async function submit () {
await form.value!.validate()
// Do something with state.value
async function submit (event: FormSubmitEvent<any>) {
// Do something with event.data
console.log(event.data)
}
</script>
<template>
<UForm
ref="form"
:schema="schema"
:state="state"
@submit.prevent="submit"
@submit="submit"
>
<UFormGroup label="Email" name="emailJoi">
<UInput v-model="state.emailJoi" />
<UFormGroup label="Email" name="email">
<UInput v-model="state.email" />
</UFormGroup>
<UFormGroup label="Password" name="passwordJoi">
<UInput v-model="state.passwordJoi" type="password" />
<UFormGroup label="Password" name="password">
<UInput v-model="state.password" type="password" />
</UFormGroup>
<UButton type="submit">

29
docs/components/content/examples/FormExampleYup.vue
View File

@@ -1,11 +1,11 @@
<script setup lang="ts">
import { ref } from 'vue'
import { object, string, InferType } from 'yup'
import type { Form } from '@nuxthq/ui/dist/runtime/types'
import type { FormSubmitEvent } from '@nuxthq/ui/dist/runtime/types'
const schema = object({
emailYup: string().email('Invalid email').required('Required'),
passwordYup: string()
email: string().email('Invalid email').required('Required'),
password: string()
.min(8, 'Must be at least 8 characters')
.required('Required')
})
@@ -13,31 +13,28 @@ const schema = object({
type Schema = InferType<typeof schema>
const state = ref({
emailYup: undefined,
passwordYup: undefined
email: undefined,
password: undefined
})
const form = ref<Form<Schema>>()
async function submit () {
await form.value!.validate()
// Do something with state.value
async function submit (event: FormSubmitEvent<Schema>) {
// Do something with event.data
console.log(event.data)
}
</script>
<template>
<UForm
ref="form"
:schema="schema"
:state="state"
@submit.prevent="submit"
@submit="submit"
>
<UFormGroup label="Email" name="emailYup">
<UInput v-model="state.emailYup" />
<UFormGroup label="Email" name="email">
<UInput v-model="state.email" />
</UFormGroup>
<UFormGroup label="Password" name="passwordYup">
<UInput v-model="state.passwordYup" type="password" />
<UFormGroup label="Password" name="password">
<UInput v-model="state.password" type="password" />
</UFormGroup>
<UButton type="submit">

29
docs/components/content/examples/FormExampleZod.vue
View File

@@ -1,41 +1,38 @@
<script setup lang="ts">
import { ref } from 'vue'
import { z } from 'zod'
import type { Form } from '@nuxthq/ui/dist/runtime/types'
import type { FormSubmitEvent } from '@nuxthq/ui/dist/runtime/types'
const schema = z.object({
emailZod: z.string().email('Invalid email'),
passwordZod: z.string().min(8, 'Must be at least 8 characters')
email: z.string().email('Invalid email'),
password: z.string().min(8, 'Must be at least 8 characters')
})
type Schema = z.output<typeof schema>
const state = ref({
emailZod: undefined,
passwordZod: undefined
email: undefined,
password: undefined
})
const form = ref<Form<Schema>>()
async function submit () {
await form.value!.validate()
// Do something with state.value
async function submit (event: FormSubmitEvent<Schema>) {
// Do something with data
console.log(event.data)
}
</script>
<template>
<UForm
ref="form"
:schema="schema"
:state="state"
@submit.prevent="submit"
@submit="submit"
>
<UFormGroup label="Email" name="emailZod">
<UInput v-model="state.emailZod" />
<UFormGroup label="Email" name="email">
<UInput v-model="state.email" />
</UFormGroup>
<UFormGroup label="Password" name="passwordZod">
<UInput v-model="state.passwordZod" type="password" />
<UFormGroup label="Password" name="password">
<UInput v-model="state.password" type="password" />
</UFormGroup>
<UButton type="submit">

9
docs/components/content/examples/FormGroupErrorExample.vue Normal file
View File

@@ -0,0 +1,9 @@
<template>
<UFormGroup v-slot="{ error }" label="Email" :error="!email && 'You must enter an email'" help="This is a nice email!">
<UInput v-model="email" type="email" placeholder="Enter email" :trailing-icon="error && 'i-heroicons-exclamation-triangle-20-solid'" />
</UFormGroup>
</template>
<script setup lang="ts">
const email = ref('')
</script>

177
docs/content/3.forms/10.form.md
View File

@@ -26,7 +26,8 @@ The Form component requires the `validate` and `state` props for form validation
#code
```vue
<script setup lang="ts">
import type { FormError } from '@nuxthq/ui/dist/runtime/types'
import { ref } from 'vue'
import type { FormError, FormSubmitEvent } from '@nuxthq/ui/dist/runtime/types'
const state = ref({
email: undefined,
@@ -40,20 +41,17 @@ const validate = (state: any): FormError[] => {
return errors
}
const form = ref()
async function submit () {
await form.value!.validate()
// Do something with state.value
async function submit (event: FormSubmitEvent<any>) {
// Do something with data
console.log(event.data)
}
</script>
<template>
<UForm
ref="form"
:validate="validate"
:state="state"
@submit.prevent="submit"
@submit="submit"
>
<UFormGroup label="Email" name="email">
<UInput v-model="state.email" />
@@ -84,7 +82,9 @@ You can provide a schema from [Yup](#yup), [Zod](#zod) or [Joi](#joi) through th
#code
```vue
<script setup lang="ts">
import { ref } from 'vue'
import { object, string, InferType } from 'yup'
import type { FormSubmitEvent } from '@nuxthq/ui/dist/runtime/types'
const schema = object({
email: string().email('Invalid email').required('Required'),
@@ -93,25 +93,24 @@ const schema = object({
.required('Required')
})
type Schema = InferType<typeof schema>
const state = ref({
email: undefined,
password: undefined
})
const form = ref()
async function submit () {
await form.value!.validate()
// Do something with state.value
async function submit (event: FormSubmitEvent<Schema>) {
// Do something with event.data
console.log(event.data)
}
</script>
<template>
<UForm
ref="form"
:schema="schema"
:state="state"
@submit.prevent="submit"
@submit="submit"
>
<UFormGroup label="Email" name="email">
<UInput v-model="state.email" />
@@ -138,32 +137,33 @@ async function submit () {
#code
```vue
<script setup lang="ts">
import { ref } from 'vue'
import { z } from 'zod'
import type { FormSubmitEvent } from '@nuxthq/ui/dist/runtime/types'
const schema = z.object({
email: z.string().email('Invalid email'),
password: z.string().min(8, 'Must be at least 8 characters')
})
type Schema = z.output<typeof schema>
const state = ref({
email: undefined,
password: undefined
})
const form = ref()
async function submit () {
await form.value!.validate()
// Do something with state.value
async function submit (event: FormSubmitEvent<Schema>) {
// Do something with data
console.log(event.data)
}
</script>
<template>
<UForm
ref="form"
:schema="schema"
:state="state"
@submit.prevent="submit"
@submit="submit"
>
<UFormGroup label="Email" name="email">
<UInput v-model="state.email" />
@@ -190,8 +190,9 @@ async function submit () {
#code
```vue
<script setup lang="ts">
import { ref } from 'vue'
import Joi from 'joi'
import type { Schema } from 'joi'
import type { FormSubmitEvent } from '@nuxthq/ui/dist/runtime/types'
const schema = Joi.object({
email: Joi.string().required(),
@@ -205,18 +206,17 @@ const state = ref({
password: undefined
})
async function submit () {
await form.value!.validate()
// Do something with state.value
async function submit (event: FormSubmitEvent<any>) {
// Do something with event.data
console.log(event.data)
}
</script>
<template>
<UForm
ref="form"
:schema="schema"
:state="state"
@submit.prevent="submit"
@submit="submit"
>
<UFormGroup label="Email" name="email">
<UInput v-model="state.email" />
@@ -234,38 +234,6 @@ async function submit () {
```
::
## Type Inference
You can utilize Zod and Yup's type inference feature to automatically infer the types of your schema and form data. This allows for strong type checking and better code validation, reducing the likelihood of errors.
```vue
<script setup lang="ts">
import type { Form } from '@nuxthq/ui/dist/runtime/types'
// [...]
const schema = z.object({
email: z.string().email('Invalid email'),
password: z.string().min(8, 'Must be at least 8 characters')
})
const state = ref<Partial<Schema>>({
email: undefined,
password: undefined
})
type Schema = z.output<typeof schema>
// For Yup, use:
// type Schema = InferType<typeof schema>
const form = ref<Form<Schema>>()
async function submit() {
const data = await form.value!.validate()
// Do something with data
}
</script>
// [...]
```
## Other libraries
For other validation libraries, you can define your own component with custom validation logic.
@@ -274,30 +242,30 @@ Here is an example with [Vuelidate](https://github.com/vuelidate/vuelidate):
```vue
<script setup lang="ts">
import useVuelidate from '@vuelidate/core';
import useVuelidate from '@vuelidate/core'
const props = defineProps({
rules: { type: Object, required: true },
model: { type: Object, required: true },
});
model: { type: Object, required: true }
})
const form = ref();
const v = useVuelidate(props.rules, props.model);
const v = useVuelidate(props.rules, props.model)
async function validateWithVuelidate() {
v.value.$touch();
await v.value.$validate();
v.value.$touch()
await v.value.$validate()
return v.value.$errors.map((error) => ({
message: error.$message,
path: error.$propertyPath,
}));
}))
}
defineExpose({
validate: async () => {
await form.value.validate();
},
});
await form.value.validate()
}
})
</script>
<template>
@@ -307,9 +275,56 @@ defineExpose({
</template>
```
## Backend validation
You can manually set errors after form submission if required. To do this, simply use the `form.setErrors` function to set the errors as needed.
```vue
<script setup lang="ts">
import type { FormError, FormSubmitEvent } from '@nuxthq/ui/dist/runtime/types'
const state = ref({
email: undefined,
password: undefined
})
const form = ref()
async function submit (event: FormSubmitEvent<any>) {
form.value.clear()
const response = await fetch('...')
if (!response.status === 422) {
const errors = await response.json()
form.value.setErrors(errors.map((err) => {
// Map validation errors to { path: string, message: string }
}))
} else {
// ...
}
}
</script>
<template>
<UForm ref="form" :state="state" @submit="submit">
<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>
```
## Input events
The Form component automatically triggers validation upon input `blur` or `change` events. This ensures that any errors are displayed as soon as the user interacts with the form elements.
The Form component automatically triggers validation upon `submit`, `input`, `blur` or `change` events. This ensures that any errors are displayed as soon as the user interacts with the form elements. You can control when validation happens this using the `validate-on` prop.
::component-example
#default
@@ -319,3 +334,23 @@ The Form component automatically triggers validation upon input `blur` or `chang
## Props
:component-props
## API
::field-group
::field{name="validate (path?: string, opts: { silent?: boolean })" type="Promise<T>"}
Triggers form validation. Will raise any errors unless `opts.silent` is set to true.
::
::field{name="clear (path?: string)" type="void"}
Clears form errors associated with a specific path. If no path is provided, clears all form errors.
::
::field{name="getErrors (path?: string)" type="FormError[]"}
Retrieves form errors associated with a specific path. If no path is provided, returns all form errors.
::
::field{name="setErrors (errors: FormError[], path?: string)" type="void"}
Sets form errors for a given path. If no path is provided, overrides all errors.
::
::field{name="errors" type="Ref<FormError[]>"}
A reference to the array containing validation errors. Use this to access or manipulate the error information.
::
::

43
docs/content/3.forms/9.form-group.md
View File

@@ -111,27 +111,54 @@ Use the `error` prop to display an error message below the form element.
When used together with the `help` prop, the `error` prop will take precedence.
::component-example
#default
:form-group-error-example
#code
```vue
<template>
<UFormGroup v-slot="{ error }" label="Email" :error="!email && 'You must enter an email'" help="This is a nice email!">
<UInput v-model="email" type="email" placeholder="Enter email" :trailing-icon="error && 'i-heroicons-exclamation-triangle-20-solid'" />
</UFormGroup>
</template>
<script setup lang="ts">
const email = ref('')
</script>
```
::
::callout{icon="i-heroicons-light-bulb"}
The `error` prop will automatically set the `color` prop of the form element to `red`.
::
You can also use the `error` prop as a boolean to mark the form element as invalid.
::component-card
---
baseProps:
name: 'group-error'
props:
label: 'Email'
help: 'We will never share your email with anyone else.'
error: "Not a valid email address."
error: true
ui:
error: 'hidden'
excludedProps:
- ui
- error
- label
code: >-
<UInput placeholder="you@example.com" trailing-icon="i-heroicons-exclamation-triangle-20-solid" />
<UInput placeholder="you@example.com" />
---
#default
:u-input{model-value="benjamincanac" placeholder="you@example.com" trailing-icon="i-heroicons-exclamation-triangle-20-solid"}
:u-input{model-value="benjamincanac" placeholder="you@example.com"}
::
You can also use the `error` prop as a boolean to mark the form element as invalid.
::callout{icon="i-heroicons-light-bulb"}
The `error` prop will automatically set the `color` prop of the form element to `red`.
::callout{icon="i-heroicons-light-bulb" to="/forms/form"}
Learn more about form validation in the `Form` component.
::
### Size :u-badge{label="New" class="ml-2 align-text-bottom !rounded-full" variant="subtle"}