feat(Tabs): control selected index (#490)

docs/components/content/examples/TabsExampleChange.vue

@@ -0,0 +1,22 @@
+<script setup>
+const items = [{
+  label: 'Tab1',
+  content: 'This is the content shown for Tab1'
+}, {
+  label: 'Tab2',
+  content: 'And, this is the content for Tab2'
+}, {
+  label: 'Tab3',
+  content: 'Finally, this is the content for Tab3'
+}]
+
+function onChange (index) {
+  const item = items[index]
+
+  alert(`${item.label} was clicked!`)
+}
+</script>
+
+<template>
+  <UTabs :items="items" @change="onChange" />
+</template>

docs/components/content/examples/TabsExampleVModel.vue

@@ -0,0 +1,34 @@
+<script setup>
+const items = [{
+  label: 'Tab1',
+  content: 'This is the content shown for Tab1'
+}, {
+  label: 'Tab2',
+  content: 'And, this is the content for Tab2'
+}, {
+  label: 'Tab3',
+  content: 'Finally, this is the content for Tab3'
+}]
+
+const route = useRoute()
+const router = useRouter()
+
+const selected = computed({
+  get () {
+    const index = items.findIndex((item) => item.label === route.query.tab)
+    if (index === -1) {
+      return 0
+    }
+
+    return index
+  },
+  set (value) {
+    // Hash is specified here to prevent the page from scrolling to the top
+    router.replace({ query: { tab: items[value].label }, hash: '#control-the-selected-index' })
+  }
+})
+</script>
+
+<template>
+  <UTabs v-model="selected" :items="items" />
+</template>

docs/content/5.navigation/4.tabs.md

@@ -83,6 +83,78 @@ const items = [...]
 ```
 ::
 
+::callout{icon="i-heroicons-exclamation-triangle"}
+  This will have no effect if you are using a `v-model` to control the selected index.
+::
+
+### Listen to changes :u-badge{label="Edge" class="ml-2 align-text-bottom !rounded-full" variant="subtle"}
+
+You can listen to changes by using the `@change` event. The event will emit the index of the selected item.
+
+::component-example
+#default
+:tabs-example-change{class="w-full"}
+
+#code
+```vue
+<script setup>
+const items = [...]
+
+function onChange (index) {
+  const item = items[index]
+
+  alert(`${item.label} was clicked!`)
+}
+</script>
+
+<template>
+  <UTabs :items="items" @change="onChange" />
+</template>
+```
+::
+
+### Control the selected index :u-badge{label="Edge" class="ml-2 align-text-bottom !rounded-full" variant="subtle"}
+
+Use a `v-model` to control the selected index.
+
+::component-example
+#default
+:tabs-example-v-model{class="w-full"}
+
+#code
+```vue
+<script setup>
+const items = [...]
+
+const route = useRoute()
+const router = useRouter()
+
+const selected = computed({
+  get () {
+    const index = items.findIndex((item) => item.label === route.query.tab)
+    if (index === -1) {
+      return 0
+    }
+
+    return index
+  },
+  set (value) {
+    // Hash is specified here to prevent the page from scrolling to the top
+    router.replace({ query: { tab: items[value].label }, hash: '#control-the-selected-index' })
+  }
+})
+</script>
+
+<template>
+  <UTabs v-model="selected" :items="items" />
+</template>
+```
+::
+
+::callout{icon="i-heroicons-information-circle"}
+In this example, we are binding tabs to the route query. Refresh the page to see the selected tab change.
+::
+
 ## Slots
 
 You can use slots to customize the buttons and items content of the Accordion.