feat(Carousel): expose methods to allow autoplay

Resolves #1300

docs/components/content/examples/CarouselExampleAutoplay.vue

@@ -0,0 +1,37 @@
+<script setup lang="ts">
+const items = [
+  'https://picsum.photos/1920/1080?random=1',
+  'https://picsum.photos/1920/1080?random=2',
+  'https://picsum.photos/1920/1080?random=3',
+  'https://picsum.photos/1920/1080?random=4',
+  'https://picsum.photos/1920/1080?random=5',
+  'https://picsum.photos/1920/1080?random=6'
+]
+
+const carouselRef = ref()
+
+onMounted(() => {
+  setInterval(() => {
+    if (!carouselRef.value) return
+
+    if (carouselRef.value.page === carouselRef.value.pages) {
+      return carouselRef.value.select(0)
+    }
+
+    carouselRef.value.next()
+  }, 3000)
+})
+</script>
+
+<template>
+  <UCarousel
+    ref="carouselRef"
+    v-slot="{ item }"
+    :items="items"
+    :ui="{ item: 'basis-full' }"
+    class="rounded-lg overflow-hidden"
+    indicators
+  >
+    <img :src="item" class="w-full" draggable="false">
+  </UCarousel>
+</template>

docs/content/2.components/carousel.md

@@ -100,6 +100,12 @@ The number of indicators will be automatically generated based on the number of
 
 :component-example{component="carousel-example-indicators-size"}
 
+## Autoplay
+
+You can easily implement an autoplay behavior using the exposed [API](#api) through a template ref.
+
+:component-example{component="carousel-example-autoplay"}
+
 ## Slots
 
 ### `default`
@@ -120,7 +126,7 @@ You can customize the position of the buttons through `ui.arrows.wrapper`.
 
 ### `indicator`
 
-With the `indicators` prop enabled, use the `#indicator` slot to set the content of the indicators. You will have access to the `active`, `index` properties and `on-click` method in the slot scope.
+With the `indicators` prop enabled, use the `#indicator` slot to set the content of the indicators. You will have access to the `active`, `page` properties and `on-click` method in the slot scope.
 
 :component-example{component="carousel-example-slots-indicator"}
 
@@ -132,6 +138,28 @@ You can customize the position of the buttons through `ui.indicators.wrapper`.
 
 :component-props
 
+## API
+
+When accessing the component via a template ref, you can use the following:
+
+::field-group
+  ::field{name="page" type="number"}
+    The current page.
+  ::
+  ::field{name="pages" type="number"}
+    The total number of pages.
+  ::
+  ::field{name="select (page)"}
+    Go to a specific page.
+  ::
+  ::field{name="next ()"}
+    Go to the next page.
+  ::
+  ::field{name="prev ()"}
+    Go to the previous page.
+  ::
+::
+
 ## Config
 
 :component-preset