feat: add examples for carousel api handling

apps/www/__registry__/index.ts

@@ -184,6 +184,13 @@ export const Index = {
       component: () => import('../src/lib/registry/default/example/CardWithForm.vue').then(m => m.default),
       files: ['../src/lib/registry/default/example/CardWithForm.vue'],
     },
+    CarouselApi: {
+      name: 'CarouselApi',
+      type: 'components:example',
+      registryDependencies: ['carousel', 'button'],
+      component: () => import('../src/lib/registry/default/example/CarouselApi.vue').then(m => m.default),
+      files: ['../src/lib/registry/default/example/CarouselApi.vue'],
+    },
     CarouselDemo: {
       name: 'CarouselDemo',
       type: 'components:example',
@@ -1005,6 +1012,13 @@ export const Index = {
       component: () => import('../src/lib/registry/new-york/example/CardWithForm.vue').then(m => m.default),
       files: ['../src/lib/registry/new-york/example/CardWithForm.vue'],
     },
+    CarouselApi: {
+      name: 'CarouselApi',
+      type: 'components:example',
+      registryDependencies: ['carousel', 'button'],
+      component: () => import('../src/lib/registry/new-york/example/CarouselApi.vue').then(m => m.default),
+      files: ['../src/lib/registry/new-york/example/CarouselApi.vue'],
+    },
     CarouselDemo: {
       name: 'CarouselDemo',
       type: 'components:example',

apps/www/src/content/docs/components/carousel.md

@@ -172,3 +172,46 @@ You can pass options to the carousel using the `opts` prop. See the [Embla Carou
   </Carousel>
 </template>
 ```
+
+## API
+
+Use the `useCarousel` hook to get the instance of the API.
+
+<ComponentPreview name="CarouselApi" />
+
+## Events
+
+You can listen to events using the api instance from `useCarousel()`.
+
+```vue
+<script setup>
+import { nextTick, ref, watch } from 'vue'
+import { useCarousel } from '@/components/ui/carousel'
+
+const api = ref<CarouselApi>()
+
+function setApi(val: CarouselApi) {
+  api.value = val
+}
+
+const stop = watch(api, (api) => {
+  if (!api)
+    return
+
+  // Watch only once or use watchOnce() in @vueuse/core
+  nextTick(() => stop())
+
+  api.on('select', () => {
+    // Do something on select.
+  })
+})
+</script>
+
+<template>
+  <Carousel @init-api="setApi">
+    ...
+  </Carousel>
+</template>
+```
+
+See the [Embla Carousel docs](https://www.embla-carousel.com/api/events/) for more information on using events.

apps/www/src/lib/registry/default/example/CarouselApi.vue

@@ -0,0 +1,51 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { watchOnce } from '@vueuse/core'
+import type { CarouselApi } from '@/lib/registry/default/ui/carousel'
+import { Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious } from '@/lib/registry/default/ui/carousel'
+import { Card, CardContent } from '@/lib/registry/default/ui/card'
+
+const api = ref<CarouselApi>()
+const totalCount = ref(0)
+const current = ref(0)
+
+function setApi(val: CarouselApi) {
+  api.value = val
+}
+
+watchOnce(api, (api) => {
+  if (!api)
+    return
+
+  totalCount.value = api.scrollSnapList().length
+  current.value = api.selectedScrollSnap() + 1
+
+  api.on('select', () => {
+    current.value = api.selectedScrollSnap() + 1
+  })
+})
+</script>
+
+<template>
+  <div class="flex flex-col items-center space-x-2">
+    <Carousel class="w-full max-w-xs" @init-api="setApi">
+      <CarouselContent>
+        <CarouselItem v-for="(_, index) in 5" :key="index">
+          <div class="p-1">
+            <Card>
+              <CardContent class="flex aspect-square items-center justify-center p-6">
+                <span class="text-4xl font-semibold">{{ index + 1 }}</span>
+              </CardContent>
+            </Card>
+          </div>
+        </CarouselItem>
+      </CarouselContent>
+      <CarouselPrevious />
+      <CarouselNext />
+    </Carousel>
+
+    <div class="py-2 text-center text-sm text-muted-foreground">
+      Slide {{ current }} of {{ totalCount }}
+    </div>
+  </div>
+</template>

apps/www/src/lib/registry/new-york/example/CarouselApi.vue

@@ -0,0 +1,51 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { watchOnce } from '@vueuse/core'
+import type { CarouselApi } from '@/lib/registry/new-york/ui/carousel'
+import { Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious } from '@/lib/registry/new-york/ui/carousel'
+import { Card, CardContent } from '@/lib/registry/new-york/ui/card'
+
+const api = ref<CarouselApi>()
+const totalCount = ref(0)
+const current = ref(0)
+
+function setApi(val: CarouselApi) {
+  api.value = val
+}
+
+watchOnce(api, (api) => {
+  if (!api)
+    return
+
+  totalCount.value = api.scrollSnapList().length
+  current.value = api.selectedScrollSnap() + 1
+
+  api.on('select', () => {
+    current.value = api.selectedScrollSnap() + 1
+  })
+})
+</script>
+
+<template>
+  <div class="flex flex-col items-center space-x-2">
+    <Carousel class="w-full max-w-xs" @init-api="setApi">
+      <CarouselContent>
+        <CarouselItem v-for="(_, index) in 5" :key="index">
+          <div class="p-1">
+            <Card>
+              <CardContent class="flex aspect-square items-center justify-center p-6">
+                <span class="text-4xl font-semibold">{{ index + 1 }}</span>
+              </CardContent>
+            </Card>
+          </div>
+        </CarouselItem>
+      </CarouselContent>
+      <CarouselPrevious />
+      <CarouselNext />
+    </Carousel>
+
+    <div class="py-2 text-center text-sm text-muted-foreground">
+      Slide {{ current }} of {{ totalCount }}
+    </div>
+  </div>
+</template>