From bc81d45b2b2cd3aa44c438c3642e2775d5bf22d7 Mon Sep 17 00:00:00 2001
From: Benjamin Canac <canacb1@gmail.com>
Date: Mon, 12 Jun 2023 14:34:12 +0200
Subject: [PATCH] docs: improve forms usage with examples

---
 .../content/examples/CheckboxExample.vue      |  7 ++++
 .../content/examples/InputExample.vue         |  7 ++++
 .../content/examples/RadioExample.vue         | 23 ++++++++++++
 .../content/examples/SelectExample.vue        |  9 +++++
 .../content/examples/TextareaExample.vue      |  7 ++++
 .../content/examples/ToggleExample.vue        |  7 ++++
 docs/content/3.forms/1.input.md               | 21 ++++++++---
 docs/content/3.forms/2.textarea.md            | 21 ++++++++---
 docs/content/3.forms/3.select.md              | 31 +++++++++-------
 docs/content/3.forms/4.select-menu.md         |  2 --
 docs/content/3.forms/5.checkbox.md            | 21 ++++++++---
 docs/content/3.forms/6.radio.md               | 35 ++++++++++++++++---
 docs/content/3.forms/7.toggle.md              | 17 ++++++++-
 13 files changed, 172 insertions(+), 36 deletions(-)
 create mode 100644 docs/components/content/examples/CheckboxExample.vue
 create mode 100644 docs/components/content/examples/InputExample.vue
 create mode 100644 docs/components/content/examples/RadioExample.vue
 create mode 100644 docs/components/content/examples/SelectExample.vue
 create mode 100644 docs/components/content/examples/TextareaExample.vue
 create mode 100644 docs/components/content/examples/ToggleExample.vue

diff --git a/docs/components/content/examples/CheckboxExample.vue b/docs/components/content/examples/CheckboxExample.vue
new file mode 100644
index 00000000..d34d412c
--- /dev/null
+++ b/docs/components/content/examples/CheckboxExample.vue
@@ -0,0 +1,7 @@
+<script setup>
+const selected = ref(false)
+</script>
+
+<template>
+  <UCheckbox v-model="selected" name="notifications" label="Notifications" />
+</template>
diff --git a/docs/components/content/examples/InputExample.vue b/docs/components/content/examples/InputExample.vue
new file mode 100644
index 00000000..50dc64a4
--- /dev/null
+++ b/docs/components/content/examples/InputExample.vue
@@ -0,0 +1,7 @@
+<script setup>
+const value = ref('')
+</script>
+
+<template>
+  <UInput v-model="value" />
+</template>
diff --git a/docs/components/content/examples/RadioExample.vue b/docs/components/content/examples/RadioExample.vue
new file mode 100644
index 00000000..157026f5
--- /dev/null
+++ b/docs/components/content/examples/RadioExample.vue
@@ -0,0 +1,23 @@
+<script setup>
+const methods = [{
+  name: 'email',
+  value: 'email',
+  label: 'Email'
+}, {
+  name: 'sms',
+  value: 'sms',
+  label: 'Phone (SMS)'
+}, {
+  name: 'push',
+  value: 'push',
+  label: 'Push notification'
+}]
+
+const selected = ref('sms')
+</script>
+
+<template>
+  <div class="space-y-1">
+    <URadio v-for="method of methods" :key="method.name" v-model="selected" v-bind="method" />
+  </div>
+</template>
diff --git a/docs/components/content/examples/SelectExample.vue b/docs/components/content/examples/SelectExample.vue
new file mode 100644
index 00000000..47c3abe2
--- /dev/null
+++ b/docs/components/content/examples/SelectExample.vue
@@ -0,0 +1,9 @@
+<script setup>
+const countries = ['United States', 'Canada', 'Mexico']
+
+const country = ref(countries[0])
+</script>
+
+<template>
+  <USelect v-model="country" :options="countries" />
+</template>
diff --git a/docs/components/content/examples/TextareaExample.vue b/docs/components/content/examples/TextareaExample.vue
new file mode 100644
index 00000000..9aa4a05f
--- /dev/null
+++ b/docs/components/content/examples/TextareaExample.vue
@@ -0,0 +1,7 @@
+<script setup>
+const value = ref('')
+</script>
+
+<template>
+  <UTextarea v-model="value" />
+</template>
diff --git a/docs/components/content/examples/ToggleExample.vue b/docs/components/content/examples/ToggleExample.vue
new file mode 100644
index 00000000..a23f8044
--- /dev/null
+++ b/docs/components/content/examples/ToggleExample.vue
@@ -0,0 +1,7 @@
+<script setup>
+const selected = ref(false)
+</script>
+
+<template>
+  <UToggle v-model="selected" />
+</template>
diff --git a/docs/content/3.forms/1.input.md b/docs/content/3.forms/1.input.md
index 4615aa0f..c25f08d8 100644
--- a/docs/content/3.forms/1.input.md
+++ b/docs/content/3.forms/1.input.md
@@ -5,11 +5,22 @@ description: Display an input field.
 
 ## Usage
 
-::component-card
----
-baseProps:
-  name: 'input'
----
+Use a `v-model` to make the Input reactive.
+
+::component-example
+#default
+:input-example
+
+#code
+```vue
+<script setup>
+const value = ref('')
+</script>
+
+<template>
+  <UInput v-model="value" />
+</template>
+```
 ::
 
 ### Style
diff --git a/docs/content/3.forms/2.textarea.md b/docs/content/3.forms/2.textarea.md
index df8a68cf..2f876643 100644
--- a/docs/content/3.forms/2.textarea.md
+++ b/docs/content/3.forms/2.textarea.md
@@ -5,11 +5,22 @@ description: Display a textarea field.
 
 ## Usage
 
-::component-card
----
-baseProps:
-  name: 'textarea'
----
+Use a `v-model` to make the Textarea reactive.
+
+::component-example
+#default
+:textarea-example
+
+#code
+```vue
+<script setup>
+const value = ref('')
+</script>
+
+<template>
+  <UTextarea v-model="value" />
+</template>
+```
 ::
 
 ### Style
diff --git a/docs/content/3.forms/3.select.md b/docs/content/3.forms/3.select.md
index 7a08a509..f5d7eda1 100644
--- a/docs/content/3.forms/3.select.md
+++ b/docs/content/3.forms/3.select.md
@@ -7,19 +7,24 @@ description: Display a select field.
 
 The Select component is a wrapper around the native `<select>` HTML element. For more advanced use cases like searching or multiple selection, consider using the [SelectMenu](/forms/select-menu) component.
 
-::component-card
----
-baseProps:
-  name: 'select'
-  modelValue: 'United States'
-props:
-  options:
-    - 'United States'
-    - 'Canada'
-    - 'Mexico'
-excludedProps:
-  - options
----
+Use a `v-model` to make the Select reactive alongside the `options` prop to pass an array of strings or objects.
+
+::component-example
+#default
+:select-example
+
+#code
+```vue
+<script setup>
+const countries = ['United States', 'Canada', 'Mexico']
+
+const country = ref(countries[0])
+</script>
+
+<template>
+  <USelect v-model="country" :options="countries" />
+</template>
+```
 ::
 
 ### Style
diff --git a/docs/content/3.forms/4.select-menu.md b/docs/content/3.forms/4.select-menu.md
index 7d6fe165..b5c519e2 100644
--- a/docs/content/3.forms/4.select-menu.md
+++ b/docs/content/3.forms/4.select-menu.md
@@ -10,8 +10,6 @@ headlessui:
 
 The SelectMenu component renders by default a [Select](/forms/select) component and is based on the `ui.select` preset. You can use most of the Select props to configure the display if you don't want to override the default slot such as [color](/forms/select#style), [variant](/forms/select#style), [size](/forms/select#size), [placeholder](/forms/select#placeholder), [icon](/forms/select#icon), [disabled](/forms/select#disabled), etc.
 
-### Options
-
 Like the Select component, you can use the `options` prop to pass an array of strings or objects.
 
 ::component-example
diff --git a/docs/content/3.forms/5.checkbox.md b/docs/content/3.forms/5.checkbox.md
index 55870530..9c1c634f 100644
--- a/docs/content/3.forms/5.checkbox.md
+++ b/docs/content/3.forms/5.checkbox.md
@@ -5,11 +5,22 @@ description: Display a checkbox field.
 
 ## Usage
 
-::component-card
----
-baseProps:
-  name: 'checkbox'
----
+Use a `v-model` to make the Checkbox reactive.
+
+::component-example
+#default
+:checkbox-example
+
+#code
+```vue
+<script setup>
+const selected = ref(false)
+</script>
+
+<template>
+  <UCheckbox v-model="selected" name="notifications" label="Notifications" />
+</template>
+```
 ::
 
 ### Label
diff --git a/docs/content/3.forms/6.radio.md b/docs/content/3.forms/6.radio.md
index 8e94532b..3ef937d0 100644
--- a/docs/content/3.forms/6.radio.md
+++ b/docs/content/3.forms/6.radio.md
@@ -5,11 +5,36 @@ description: Display a radio field.
 
 ## Usage
 
-::component-card
----
-baseProps:
-  name: 'radio'
----
+Use a `v-model` to make the Radio reactive.
+
+::component-example
+#default
+:radio-example
+
+#code
+```vue
+<script setup>
+const methods = [{
+  name: 'email',
+  value: 'email',
+  label: 'Email'
+}, {
+  name: 'sms',
+  value: 'sms',
+  label: 'Phone (SMS)'
+}, {
+  name: 'push',
+  value: 'push',
+  label: 'Push notification'
+}]
+
+const selected = ref('sms')
+</script>
+
+<template>
+  <URadio v-for="method of methods" :key="method.name" v-model="selected" v-bind="method" />
+</template>
+```
 ::
 
 ### Label
diff --git a/docs/content/3.forms/7.toggle.md b/docs/content/3.forms/7.toggle.md
index 3331be38..8ede6d55 100644
--- a/docs/content/3.forms/7.toggle.md
+++ b/docs/content/3.forms/7.toggle.md
@@ -8,7 +8,22 @@ headlessui:
 
 ## Usage
 
-::component-card
+Use a `v-model` to make the Toggle reactive.
+
+::component-example
+#default
+:toggle-example
+
+#code
+```vue
+<script setup>
+const selected = ref(false)
+</script>
+
+<template>
+  <UToggle v-model="selected" />
+</template>
+```
 ::
 
 ### Icon