docs(form): update (#2167)

Co-authored-by: Benjamin Canac <canacb1@gmail.com>

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

@@ -0,0 +1,37 @@
+<script setup lang="ts">
+import type { FormError, FormSubmitEvent } from '#ui/types'
+
+const state = reactive({
+  email: undefined,
+  password: undefined
+})
+
+const validate = (state: any): FormError[] => {
+  const errors = []
+  if (!state.email) errors.push({ name: 'email', message: 'Required' })
+  if (!state.password) errors.push({ name: 'password', message: 'Required' })
+  return errors
+}
+
+const toast = useToast()
+async function onSubmit(event: FormSubmitEvent<any>) {
+  toast.add({ title: 'Success', description: 'The form has been submitted.', color: 'green' })
+  console.log(event.data)
+}
+</script>
+
+<template>
+  <UForm :validate="validate" :state="state" class="space-y-4" @submit="onSubmit">
+    <UFormField label="Email" name="email">
+      <UInput v-model="state.email" />
+    </UFormField>
+
+    <UFormField label="Password" name="password">
+      <UInput v-model="state.password" type="password" />
+    </UFormField>
+
+    <UButton type="submit">
+      Submit
+    </UButton>
+  </UForm>
+</template>

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

@@ -0,0 +1,115 @@
+<script setup lang="ts">
+import { z } from 'zod'
+import type { FormSubmitEvent, Form } from '@nuxt/ui'
+
+const schema = z.object({
+  input: z.string().min(10),
+  inputMenu: z.any().refine(option => option?.value === 'option-2', {
+    message: 'Select Option 2'
+  }),
+  inputMenuMultiple: z.any().refine(values => !!values?.find((option: any) => option.value === 'option-2'), {
+    message: 'Include Option 2'
+  }),
+  textarea: z.string().min(10),
+  select: z.string().refine(value => value === 'option-2', {
+    message: 'Select Option 2'
+  }),
+  selectMenu: z.any().refine(option => option?.value === 'option-2', {
+    message: 'Select Option 2'
+  }),
+  selectMenuMultiple: z.any().refine(values => !!values?.find((option: any) => option.value === 'option-2'), {
+    message: 'Include Option 2'
+  }),
+  switch: z.boolean().refine(value => value === true, {
+    message: 'Toggle me'
+  }),
+  checkbox: z.boolean().refine(value => value === true, {
+    message: 'Check me'
+  }),
+  radioGroup: z.string().refine(value => value === 'option-2', {
+    message: 'Select Option 2'
+  }),
+  slider: z.number().max(20, { message: 'Must be less than 20' })
+})
+
+type Schema = z.output<typeof schema>
+
+const state = reactive<Partial<Schema>>({})
+const form = ref<Form<Schema>>()
+
+const items = [
+  { label: 'Option 1', value: 'option-1' },
+  { label: 'Option 2', value: 'option-2' },
+  { label: 'Option 3', value: 'option-3' }
+]
+
+const toast = useToast()
+async function onSubmit(event: FormSubmitEvent<any>) {
+  toast.add({ title: 'Success', description: 'The form has been submitted.', color: 'green' })
+  console.log(event.data)
+}
+</script>
+
+<template>
+  <UForm ref="form" :state="state" :schema="schema" @submit="onSubmit">
+    <div class="grid grid-cols-3 gap-4">
+      <UFormField label="Input" name="input">
+        <UInput v-model="state.input" placeholder="john@lennon.com" class="w-40" />
+      </UFormField>
+
+      <div class="flex flex-col gap-4">
+        <UFormField name="switch">
+          <USwitch v-model="state.switch" label="Switch me" />
+        </UFormField>
+
+        <UFormField name="checkbox">
+          <UCheckbox v-model="state.checkbox" label="Check me" />
+        </UFormField>
+      </div>
+
+      <UFormField name="slider" label="Slider">
+        <USlider v-model="state.slider" />
+      </UFormField>
+
+      <UFormField name="select" label="Select">
+        <USelect v-model="state.select" :items="items" />
+      </UFormField>
+
+      <UFormField name="selectMenu" label="Select Menu">
+        <USelectMenu v-model="state.selectMenu" :items="items" />
+      </UFormField>
+
+      <UFormField name="selectMenuMultiple" label="Select Menu (Multiple)">
+        <USelectMenu v-model="state.selectMenuMultiple" multiple :items="items" />
+      </UFormField>
+
+      <UFormField name="inputMenu" label="Input Menu">
+        <UInputMenu v-model="state.inputMenu" :items="items" />
+      </UFormField>
+
+      <UFormField name="inputMenuMultiple" label="Input Menu (Multiple)">
+        <UInputMenu v-model="state.inputMenuMultiple" multiple :items="items" />
+      </UFormField>
+
+      <span />
+
+      <UFormField label="Textarea" name="textarea">
+        <UTextarea v-model="state.textarea" />
+      </UFormField>
+
+      <UFormField name="radioGroup">
+        <URadioGroup v-model="state.radioGroup" legend="Radio group" :items="items" />
+      </UFormField>
+    </div>
+
+    <div class="flex gap-2 mt-8">
+      <UButton color="gray" type="submit" :disabled="form?.disabled">
+        Submit
+      </UButton>
+
+      <UButton color="gray" variant="outline" :disabled="form?.disabled" @click="form?.clear()">
+        Clear
+      </UButton>
+    </div>
+  </UForm>
+</template>

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

@@ -0,0 +1,38 @@
+<script setup lang="ts">
+import Joi from 'joi'
+import type { FormSubmitEvent } from '#ui/types'
+
+const schema = Joi.object({
+  email: Joi.string().required(),
+  password: Joi.string()
+    .min(8)
+    .required()
+})
+
+const state = reactive({
+  email: undefined,
+  password: undefined
+})
+
+const toast = useToast()
+async function onSubmit(event: FormSubmitEvent<any>) {
+  toast.add({ title: 'Success', description: 'The form has been submitted.', color: 'green' })
+  console.log(event.data)
+}
+</script>
+
+<template>
+  <UForm :schema="schema" :state="state" class="space-y-4" @submit="onSubmit">
+    <UFormField label="Email" name="email">
+      <UInput v-model="state.email" />
+    </UFormField>
+
+    <UFormField label="Password" name="password">
+      <UInput v-model="state.password" type="password" />
+    </UFormField>
+
+    <UButton type="submit">
+      Submit
+    </UButton>
+  </UForm>
+</template>

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

@@ -0,0 +1,54 @@
+<script setup lang="ts">
+import { z } from 'zod'
+import type { FormSubmitEvent } from '@nuxt/ui'
+
+const schema = z.object({
+  name: z.string().min(2),
+  news: z.boolean()
+})
+
+type Schema = z.output<typeof schema>
+
+const nestedSchema = z.object({
+  email: z.string().email()
+})
+
+type NestedSchema = z.output<typeof nestedSchema>
+
+const state = reactive<Partial<Schema & NestedSchema>>({ })
+
+const toast = useToast()
+async function onSubmit(event: FormSubmitEvent<any>) {
+  toast.add({ title: 'Success', description: 'The form has been submitted.', color: 'green' })
+  console.log(event.data)
+}
+</script>
+
+<template>
+  <UForm
+    :state="state"
+    :schema="schema"
+    class="gap-4 flex flex-col w-60"
+    @submit="(event) => onSubmit(event)"
+  >
+    <UFormField label="Name" name="name">
+      <UInput v-model="state.name" placeholder="John Lennon" />
+    </UFormField>
+
+    <div>
+      <UCheckbox v-model="state.news" name="news" label="Register to our newsletter" />
+    </div>
+
+    <UForm v-if="state.news" :state="state" :schema="nestedSchema">
+      <UFormField label="Email" name="email">
+        <UInput v-model="state.email" placeholder="john@lennon.com" />
+      </UFormField>
+    </UForm>
+
+    <div>
+      <UButton type="submit">
+        Submit
+      </UButton>
+    </div>
+  </UForm>
+</template>

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

@@ -0,0 +1,79 @@
+<script setup lang="ts">
+import { z } from 'zod'
+import type { FormSubmitEvent } from '@nuxt/ui'
+
+const schema = z.object({
+  customer: z.string().min(2)
+})
+
+type Schema = z.output<typeof schema>
+
+const itemSchema = z.object({
+  description: z.string().min(1),
+  price: z.number().min(0)
+})
+
+type ItemSchema = z.output<typeof itemSchema>
+
+const state = reactive<Partial<Schema & { items: Partial<ItemSchema>[] }>>({
+  items: [{}]
+})
+
+function addItem() {
+  if (!state.items) {
+    state.items = []
+  }
+  state.items.push({})
+}
+
+function removeItem() {
+  if (state.items) {
+    state.items.pop()
+  }
+}
+const formItemRef = ref()
+
+const toast = useToast()
+async function onSubmit(event: FormSubmitEvent<any>) {
+  toast.add({ title: 'Success', description: 'The form has been submitted.', color: 'green' })
+  console.log(event.data)
+}
+</script>
+
+<template>
+  <UForm
+    ref="formItemRef"
+    :state="state"
+    :schema="schema"
+    class="gap-4 flex flex-col w-60"
+    @submit="onSubmit"
+  >
+    <UFormField label="Customer" name="customer">
+      <UInput v-model="state.customer" placeholder="Wonka Industries" />
+    </UFormField>
+
+    <UForm v-for="item, count in state.items" :key="count" :state="item" :schema="itemSchema" class="flex gap-2">
+      <UFormField :label="!count ? 'Description' : undefined" name="description">
+        <UInput v-model="item.description" />
+      </UFormField>
+      <UFormField :label="!count ? 'Price' : undefined" name="price" class="w-20">
+        <UInput v-model="item.price" type="number" />
+      </UFormField>
+    </UForm>
+
+    <div class="flex gap-2">
+      <UButton color="gray" variant="subtle" size="sm" @click="addItem()">
+        Add Item
+      </UButton>
+
+      <UButton color="gray" variant="ghost" size="sm" @click="removeItem()">
+        Remove Item
+      </UButton>
+    </div>
+    <div>
+      <UButton type="submit">
+        Submit
+      </UButton>
+    </div>
+  </UForm>
+</template>

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

@@ -0,0 +1,43 @@
+<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({ name: 'email', message: 'Required' })
+  if (!state.password) errors.push({ name: 'password', message: 'Required' })
+  return errors
+}
+
+const toast = useToast()
+async function onSubmit(event: FormSubmitEvent<any>) {
+  toast.add({ title: 'Success', description: 'The form has been submitted.', color: 'green' })
+  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" class="space-y-4" @submit="onSubmit" @error="onError">
+    <UFormField label="Email" name="email">
+      <UInput v-model="state.email" />
+    </UFormField>
+
+    <UFormField label="Password" name="password">
+      <UInput v-model="state.password" type="password" />
+    </UFormField>
+
+    <UButton type="submit">
+      Submit
+    </UButton>
+  </UForm>
+</template>

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

@@ -0,0 +1,38 @@
+<script setup lang="ts">
+import * as v from 'valibot'
+import type { FormSubmitEvent } from '#ui/types'
+
+const schema = v.object({
+  email: v.pipe(v.string(), v.email('Invalid email')),
+  password: v.pipe(v.string(), v.minLength(8, 'Must be at least 8 characters'))
+})
+
+type Schema = v.InferOutput<typeof schema>
+
+const state = reactive({
+  email: '',
+  password: ''
+})
+
+const toast = useToast()
+async function onSubmit(event: FormSubmitEvent<Schema>) {
+  toast.add({ title: 'Success', description: 'The form has been submitted.', color: 'green' })
+  console.log(event.data)
+}
+</script>
+
+<template>
+  <UForm :schema="v.safeParser(schema)" :state="state" class="space-y-4" @submit="onSubmit">
+    <UFormField label="Email" name="email">
+      <UInput v-model="state.email" />
+    </UFormField>
+
+    <UFormField label="Password" name="password">
+      <UInput v-model="state.password" type="password" />
+    </UFormField>
+
+    <UButton type="submit">
+      Submit
+    </UButton>
+  </UForm>
+</template>

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

@@ -0,0 +1,40 @@
+<script setup lang="ts">
+import { object, string, type InferType } from 'yup'
+import type { FormSubmitEvent } from '#ui/types'
+
+const schema = object({
+  email: string().email('Invalid email').required('Required'),
+  password: string()
+    .min(8, 'Must be at least 8 characters')
+    .required('Required')
+})
+
+type Schema = InferType<typeof schema>
+
+const state = reactive({
+  email: undefined,
+  password: undefined
+})
+
+const toast = useToast()
+async function onSubmit(event: FormSubmitEvent<Schema>) {
+  toast.add({ title: 'Success', description: 'The form has been submitted.', color: 'green' })
+  console.log(event.data)
+}
+</script>
+
+<template>
+  <UForm :schema="schema" :state="state" class="space-y-4" @submit="onSubmit">
+    <UFormField label="Email" name="email">
+      <UInput v-model="state.email" />
+    </UFormField>
+
+    <UFormField label="Password" name="password">
+      <UInput v-model="state.password" type="password" />
+    </UFormField>
+
+    <UButton type="submit">
+      Submit
+    </UButton>
+  </UForm>
+</template>

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

@@ -0,0 +1,38 @@
+<script setup lang="ts">
+import { z } from 'zod'
+import type { FormSubmitEvent } from '#ui/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 = reactive({
+  email: undefined,
+  password: undefined
+})
+
+const toast = useToast()
+async function onSubmit(event: FormSubmitEvent<Schema>) {
+  toast.add({ title: 'Success', description: 'The form has been submitted.', color: 'green' })
+  console.log(event.data)
+}
+</script>
+
+<template>
+  <UForm :schema="schema" :state="state" class="space-y-4" @submit="onSubmit">
+    <UFormField label="Email" name="email">
+      <UInput v-model="state.email" />
+    </UFormField>
+
+    <UFormField label="Password" name="password">
+      <UInput v-model="state.password" type="password" />
+    </UFormField>
+
+    <UButton type="submit">
+      Submit
+    </UButton>
+  </UForm>
+</template>