Merge pull request #487 from Tofandel/feat/carousel-ref

ismail9k · web-flow · commit b64f27a6f9a8 · 2025-03-06T10:22:37.000+03:00
Allow carousel ref to be passed to Pagination and Navigation
diff --git a/docs/api/data.md b/docs/api/data.md
@@ -13,20 +13,26 @@ import { ref } from 'vue';
 const myCarousel = ref(null);
 
 // Data can be accessed under data property
-if (myCarousel.data.currentSlide === 10) {
+if (myCarousel.currentSlide === 10) {
   // Do your magic here
 }
 ....
 ```
 
-## Available Data
+## Available Exposed data
 
-| Data           | Description                        |
-| -------------- | ---------------------------------- |
-| `config`       | the current carousel configuration |
-| `currentSlide` | current slide index                |
-| `maxSlide`     | maximum slide index                |
-| `middleSlide`  | middle slide index                 |
-| `minSlide`     | minimum slide index                |
-| `slideSize`    | single slide width or height       |
-| `slidesCount`  | slides total count                 |
+| Data           | Description                                                                                       |
+|----------------|---------------------------------------------------------------------------------------------------|
+| `currentSlide` | current slide index                                                                               |
+| `activeSlide`  | current slide index even while dragging                                                           |
+| `isSliding`    | if the slider is dragging                                                                         |
+| `isVertical`   | if the slider is vertical                                                                         |
+| `nav`          | An object of navigation methods                                                                   |
+| `config`       | the current carousel configuration                                                                |
+| `maxSlide`     | maximum slide index                                                                               |
+| `minSlide`     | minimum slide index                                                                               |
+| `slideSize`    | single slide width or height                                                                      |
+| `slidesCount`  | slides total count                                                                                |
+| `slides`       | an array of Slides component                                                                      |
+| `viewport`     | the viewport element                                                                              |
+| `visibleRange` | an object with {min, max} properties min being the lowest visible slide index and max the highest |
diff --git a/docs/config.md b/docs/config.md
@@ -3,7 +3,7 @@
 ## Available Props
 
 | Prop                       | Type                                        | Default                          | Description                                                                                            |
-| -------------------------- | ------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------ |
+|----------------------------|---------------------------------------------|----------------------------------|--------------------------------------------------------------------------------------------------------|
 | `autoplay`                 | `number`                                    | 0                                | Time interval (in milliseconds) between auto-advancing slides. Set to 0 to disable autoplay.           |
 | `breakpointMode`           | 'viewport', 'carousel'                      | 'viewport'                       | Defines whether breakpoints are calculated based on viewport width or carousel container width.        |
 | `breakpoints`              | `object`                                    | null                             | Responsive breakpoint configurations. Each breakpoint can override any carousel prop.                  |
@@ -15,6 +15,7 @@
 | `ignoreAnimations`         | `boolean` \| `string` \| `array`            | false                            | Specifies which CSS animations should be excluded from slide size calculations. <Badge text="0.10.0"/> |
 | `itemsToScroll`            | `number`                                    | 1                                | Number of slides to move when navigating. Useful for creating slide groups.                            |
 | `itemsToShow`              | `number`  \| 'auto'                         | 1                                | Number of slides visible simultaneously. Use 'auto' for variable width slides.                         |
+| `clamp`                    | `boolean`                                   | false                            | If true will clamp itemsToShow to the number of available slides                                       |
 | `modelValue`               | `number`                                    | 0                                | Controls the active slide index. Can be used with v-model for two-way binding.                         |
 | `mouseDrag`                | `boolean`                                   | true                             | Enables/disables mouse drag navigation.                                                                |
 | `pauseAutoplayOnHover`     | `boolean`                                   | false                            | When true, autoplay pauses while the mouse cursor is over the carousel.                                |
@@ -24,7 +25,7 @@
 | `transition`               | `number`                                    | 300                              | Duration of the slide transition animation in milliseconds.                                            |
 | `wrapAround`               | `boolean`                                   | false                            | When true, creates an infinite loop effect by connecting the last slide to the first.                  |
 
-> **itemsToShow**: Controls the number of visible slides. Values between 1 and the total slide count are valid. Values outside this range are automatically clamped. Using 'auto' allows slides to determine their own width based on content.
+> **itemsToShow**: Controls the number of visible slides. Values higher than 1 and decimals are valid. Using 'auto' allows slides to determine their own width based on content.
 
 > **Direction Settings**: For vertical orientations ('ttb'/'top-to-bottom', 'btt'/'bottom-to-top'), the carousel requires a fixed height setting. Direction can be specified using either short ('ltr', 'rtl', 'ttb', 'btt') or verbose ('left-to-right', 'right-to-left', 'top-to-bottom', 'bottom-to-top') formats.
 
@@ -88,6 +89,19 @@ Used to add display carousel addons components.
 </template>
 ```
 
+#### Using addons outside of the carousel
+
+```vue {7,8,9}
+<template>
+  <Carousel ref="carousel">
+    <Slide v-for="slide in slides" :key="slide">
+      <div class="carousel__item">{{ slide }}</div>
+    </Slide>
+  </Carousel>
+  <Navigation :carousel="carousel" v-if="carousel && carousel.slidesCount > 1" />
+</template>
+```
+
 ### I18n
 
 Available keys:
diff --git a/eslint.config.js b/eslint.config.js
@@ -21,7 +21,7 @@ export default tseslint.config(
       },
     },
     rules: {
-      'no-console': 'off',
+      'no-console': ["error", { allow: ["warn", "error"] }],
       '@typescript-eslint/no-unused-vars': 'error',
       '@typescript-eslint/no-empty-function': 'off',
       '@typescript-eslint/no-non-null-assertion': 'off',
diff --git a/rollup.config.js b/rollup.config.js
@@ -65,8 +65,9 @@ export default [
   {
     input: 'src/index.ts',
     output: [{ file: 'dist/carousel.d.ts', format: 'es' }],
-    external: [/\.css$/],
+    external: ['vue', /\.css$/],
     plugins: [
+      typescript(),
       dts({
         rollupTypes: true,
         pathsToAliases: true,
diff --git a/src/components/Carousel/Carousel.ts b/src/components/Carousel/Carousel.ts
@@ -12,7 +12,7 @@ import {
   SetupContext,
   shallowReactive,
   watch,
-  watchEffect,
+  watchEffect, toRefs,
 } from 'vue'
 
 import { ARIA as ARIAComponent } from '@/components/ARIA'
@@ -141,6 +141,15 @@ export const Carousel = defineComponent({
       })
 
       Object.assign(config, fallbackConfig.value, newConfig)
+
+      // Validate itemsToShow
+      if (!isAuto.value) {
+        config.itemsToShow = getNumberInRange({
+          val: Number(config.itemsToShow),
+          max: props.clamp ? slidesCount.value : Infinity,
+          min: 1,
+        });
+      }
     }
 
     const handleResize = throttle(() => {
@@ -209,15 +218,6 @@ export const Carousel = defineComponent({
           min: minSlideIndex.value,
         })
       }
-
-      // Validate itemsToShow
-      if (!isAuto.value) {
-        config.itemsToShow = getNumberInRange({
-          val: Number(config.itemsToShow),
-          max: slidesCount.value,
-          min: 1,
-        })
-      }
     }
 
     const ignoreAnimations = computed<false | string[]>(() => {
@@ -852,17 +852,17 @@ export const Carousel = defineComponent({
       slidesCount,
     })
 
-    expose<CarouselExposed>({
+    expose<CarouselExposed>(reactive({
       data,
-      nav,
       next,
       prev,
       restartCarousel,
       slideTo,
       updateBreakpointsConfig,
       updateSlideSize,
       updateSlidesData,
-    })
+      ...toRefs(provided),
+    }))
 
     return () => {
       const slotSlides = slots.default || slots.slides
diff --git a/src/components/Carousel/Carousel.types.ts b/src/components/Carousel/Carousel.types.ts
@@ -29,9 +29,8 @@ export type CarouselData = {
 }
 
 export type CarouselExposed = CarouselMethods & {
-  data: Reactive<CarouselData>
-  nav: CarouselNav
-}
+  data: Reactive<CarouselData> // TODO deprecate and remove
+} & InjectedCarousel
 
 export type CarouselMethods = CarouselNav & {
   restartCarousel: () => void
diff --git a/src/components/Carousel/carouselProps.ts b/src/components/Carousel/carouselProps.ts
@@ -96,7 +96,7 @@ export const carouselProps = {
     validator(value: boolean, props: { wrapAround?: boolean }) {
       if (value && props.wrapAround) {
         console.warn(
-          `[vue3-carousel warn]: "preventExcessiveDragging" cannot be used with wrapAround. The setting will be ignored.`
+          `[vue3-carousel]: "preventExcessiveDragging" cannot be used with wrapAround. The setting will be ignored.`
         )
       }
 
@@ -139,7 +139,7 @@ export const carouselProps = {
         (!props.height || props.height === 'auto')
       ) {
         console.warn(
-          `[vue3-carousel warn]: The dir "${value}" is not supported with height "auto".`
+          `[vue3-carousel]: The dir "${value}" is not supported with height "auto".`
         )
       }
       return true
@@ -150,4 +150,7 @@ export const carouselProps = {
     default: DEFAULT_CONFIG.wrapAround,
     type: Boolean,
   },
+  clamp: {
+    type: Boolean,
+  }
 }
diff --git a/src/components/Navigation/Navigation.ts b/src/components/Navigation/Navigation.ts
@@ -1,4 +1,4 @@
-import { computed, defineComponent, h, inject } from 'vue'
+import { computed, defineComponent, h, inject, PropType } from 'vue'
 
 import { injectCarousel, NormalizedDir } from '@/shared'
 
@@ -9,11 +9,13 @@ import { NavigationProps } from './Navigation.types'
 export const Navigation = defineComponent<NavigationProps>({
   name: 'CarouselNavigation',
   inheritAttrs: false,
+  props: {
+    carousel: {
+      type: Object as PropType<NavigationProps['carousel']>,
+    },
+  },
   setup(props, { slots, attrs }) {
-    const carousel = inject(injectCarousel)
-    if (!carousel) {
-      return () => '' // Don't render, let vue warn about the missing provide
-    }
+    let carousel = inject(injectCarousel, null)!
     const { next: slotNext, prev: slotPrev } = slots
 
     const getPrevIcon = () => {
@@ -45,6 +47,13 @@ export const Navigation = defineComponent<NavigationProps>({
     )
 
     return () => {
+      if (props.carousel) {
+        carousel = props.carousel;
+      }
+      if (!carousel) {
+        console.warn('[vue3-carousel]: A carousel component must be provided for the navigation component to display')
+        return '';
+      }
       const { i18n } = carousel.config
       const prevButton = h(
         'button',
diff --git a/src/components/Navigation/Navigation.types.ts b/src/components/Navigation/Navigation.types.ts
@@ -1 +1,5 @@
-export type NavigationProps = Record<never, never> // No props for now
+import { Carousel, CarouselExposed } from '@/components/Carousel'
+
+export type NavigationProps = {
+  carousel?: InstanceType<typeof Carousel> & CarouselExposed
+}
diff --git a/src/components/Pagination/Pagination.ts b/src/components/Pagination/Pagination.ts
@@ -1,4 +1,4 @@
-import { computed, defineComponent, h, inject, VNode } from 'vue'
+import { computed, defineComponent, h, inject, PropType, VNode } from 'vue'
 
 import { injectCarousel } from '@/shared'
 import { getSnapAlignOffset, i18nFormatter, mapNumberToRange } from '@/utils'
@@ -14,13 +14,12 @@ export const Pagination = defineComponent<PaginationProps>({
     paginateByItemsToShow: {
       type: Boolean,
     },
+    carousel: {
+      type: Object as PropType<PaginationProps['carousel']>,
+    }
   },
   setup(props) {
-    const carousel = inject(injectCarousel)
-
-    if (!carousel) {
-      return () => '' // Don't render, let vue warn about the missing provide
-    }
+    let carousel = inject(injectCarousel, null)!
 
     const itemsToShow = computed(() => carousel.config.itemsToShow as number)
     const offset = computed(() =>
@@ -53,6 +52,13 @@ export const Pagination = defineComponent<PaginationProps>({
       ) === slide
 
     return () => {
+      if (props.carousel) {
+        carousel = props.carousel;
+      }
+      if (!carousel) {
+        console.warn('[vue3-carousel]: A carousel component must be provided for the pagination component to display')
+        return '';
+      }
       const children: Array<VNode> = []
 
       for (
diff --git a/src/components/Pagination/Pagination.types.ts b/src/components/Pagination/Pagination.types.ts
@@ -1,4 +1,7 @@
+import { Carousel, CarouselExposed } from '@/components/Carousel'
+
 export type PaginationProps = {
   disableOnClick?: boolean
   paginateByItemsToShow?: boolean
+  carousel?: InstanceType<typeof Carousel> & CarouselExposed
 }
diff --git a/src/components/Slide/Slide.ts b/src/components/Slide/Slide.ts
@@ -35,10 +35,6 @@ export const Slide = defineComponent({
       type: Boolean,
       default: false,
     },
-    position: {
-      type: String,
-      default: undefined,
-    },
   },
   setup(props: DeepReadonly<SlideProps>, { attrs, slots, expose }: SetupContext) {
     const carousel = inject(injectCarousel)
diff --git a/src/components/Slide/Slide.types.ts b/src/components/Slide/Slide.types.ts
@@ -2,5 +2,4 @@ export type SlideProps = {
   id?: string
   index: number
   isClone?: boolean
-  position?: 'before' | 'after'
 }
diff --git a/src/shared/types.ts b/src/shared/types.ts
@@ -49,6 +49,7 @@ export type CarouselConfig = {
   touchDrag?: boolean
   transition?: number
   wrapAround?: boolean
+  clamp?: boolean
 }
 
 export type VueClass = string | Record<string, boolean> | VueClass[]
diff --git a/src/utils/createCloneSlides.ts b/src/utils/createCloneSlides.ts
@@ -21,7 +21,6 @@ export function createCloneSlides({ slides, position, toShow }: CreateCloneSlide
     const props = {
       index,
       isClone: true,
-      position,
       id: undefined, // Make sure we don't duplicate the id which would be invalid html
       key: `clone-${position}-${i}`,
     }
diff --git a/src/utils/getSnapAlignOffset.spec.ts b/src/utils/getSnapAlignOffset.spec.ts
@@ -1,5 +1,7 @@
 import { describe, expect, test } from 'vitest'
 
+import { SnapAlign } from '@/shared'
+
 import { getSnapAlignOffset } from './getSnapAlignOffset'
 
 describe('getSnapAlignOffset', () => {
@@ -17,7 +19,7 @@ describe('getSnapAlignOffset', () => {
     test('should return 0 for invalid alignment', () => {
       expect(
         getSnapAlignOffset({
-          align: 'invalid' as any,
+          align: 'invalid' as unknown as SnapAlign,
           slideSize: 200,
           viewportSize: 800,
         })
diff --git a/tests/components/RefCarousel.vue b/tests/components/RefCarousel.vue
@@ -0,0 +1,28 @@
+<script setup lang="ts">
+import {
+  Carousel,
+  Slide,
+  Navigation as CarouselNavigation,
+  Pagination as CarouselPagination,
+} from '@/index'
+
+import {ref} from 'vue';
+
+const vModel = defineModel<number>({ default: 0 })
+const slideNum = 5;
+const carousel = ref();
+</script>
+
+<template>
+  <Carousel
+    v-model="vModel"
+    ref="carousel"
+  >
+    <Slide v-for="slide in slideNum" :key="slide">
+      {{ slide }}
+      <input type="text" />
+    </Slide>
+  </Carousel>
+  <CarouselNavigation v-if="carousel" :carousel="carousel" />
+  <CarouselPagination v-if="carousel" :carousel="carousel" />
+</template>
diff --git a/tests/integration/navigation.spec.ts b/tests/integration/navigation.spec.ts
@@ -9,6 +9,8 @@ import {
   Navigation,
 } from '@/index'
 
+import RefCarousel from '../components/RefCarousel.vue'
+
 describe('Navigation.ts', () => {
   const consoleMock = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
 
@@ -98,4 +100,12 @@ describe('Navigation.ts', () => {
     expect(wrapper.find('.carousel__prev').text()).toBe('icon-1')
     expect(wrapper.find('.carousel__next').text()).toBe('icon-2')
   })
+
+  it('renders with a carousel ref', async () => {
+    const wrapper = await mount(RefCarousel, {})
+
+    expect(consoleMock).not.toHaveBeenCalled()
+    expect(wrapper.find('.carousel__prev').attributes()).to.contain({'disabled': ''})
+    expect(wrapper.find('.carousel__next').attributes()).to.contain({'type': 'button'})
+  })
 })
diff --git a/tests/integration/pagination.spec.ts b/tests/integration/pagination.spec.ts

Original file line number	Diff line number	Diff line change
`@@ -96,7 +96,7 @@ export const carouselProps = {`
`96`	`96`	`validator(value: boolean, props: { wrapAround?: boolean }) {`
`97`	`97`	`if (value && props.wrapAround) {`
`98`	`98`	`console.warn(`
`99`		- `[vue3-carousel warn]: "preventExcessiveDragging" cannot be used with wrapAround. The setting will be ignored.`
	`99`	+ `[vue3-carousel]: "preventExcessiveDragging" cannot be used with wrapAround. The setting will be ignored.`
`100`	`100`	`)`
`101`	`101`	`}`
`102`	`102`
`@@ -139,7 +139,7 @@ export const carouselProps = {`
`139`	`139`	`(!props.height \|\| props.height === 'auto')`
`140`	`140`	`) {`
`141`	`141`	`console.warn(`
`142`		- `[vue3-carousel warn]: The dir "${value}" is not supported with height "auto".`
	`142`	+ `[vue3-carousel]: The dir "${value}" is not supported with height "auto".`
`143`	`143`	`)`
`144`	`144`	`}`
`145`	`145`	`return true`
`@@ -150,4 +150,7 @@ export const carouselProps = {`
`150`	`150`	`default: DEFAULT_CONFIG.wrapAround,`
`151`	`151`	`type: Boolean,`
`152`	`152`	`},`
	`153`	`+ clamp: {`
	`154`	`+ type: Boolean,`
	`155`	`+ }`
`153`	`156`	`}`