Merge pull request #489 from tbranger/feat/threshold-option

feat: add threshold option for slide transition customization

Author: ismail9k

docs/config.md

@@ -21,6 +21,7 @@
 | `pauseAutoplayOnHover`     | `boolean`                                   | false                            | When true, autoplay pauses while the mouse cursor is over the carousel.                                |
 | `preventExcessiveDragging` | `boolean`                                   | false                            | Limits dragging behavior at carousel boundaries for better UX. <Badge text="0.13.0" />                 |
 | `snapAlign`                | 'start', 'end', 'center-odd', 'center-even' | 'center'                         | Determines how slides are aligned within the viewport.                                                 |
+| `threshold`                | `number`                                    | 0.5                              | Define a threshold for the drag distance required to trigger a slide transition.                       |
 | `touchDrag`                | `boolean`                                   | true                             | Enables/disables touch navigation on touch-enabled devices.                                            |
 | `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.                  |

playground/App.vue

@@ -46,6 +46,7 @@ const defaultConfig = {
   gap: 10,
   pauseAutoplayOnHover: true,
   useBreakpoints: false,
+  threshold: 0.5,
 }
 
 const config = reactive({ ...defaultConfig })

src/components/Carousel/Carousel.ts

@@ -422,6 +422,7 @@ export const Carousel = defineComponent({
         isReversed: isReversed.value,
         dragged,
         effectiveSlideSize: effectiveSlideSize.value,
+        threshold: config.threshold,
       })
 
       activeSlideIndex.value = config.wrapAround

src/components/Carousel/carouselProps.ts

@@ -117,6 +117,11 @@ export const carouselProps = {
       return SLIDE_EFFECTS.includes(value)
     },
   },
+  // control the threshold to trigger slide change
+  threshold: {
+    default: DEFAULT_CONFIG.threshold,
+    type: Number
+  },
   // sliding transition time in ms
   transition: {
     default: DEFAULT_CONFIG.transition,

src/shared/constants.ts

@@ -63,6 +63,7 @@ export const DEFAULT_CONFIG: CarouselConfig = {
   preventExcessiveDragging: false,
   slideEffect: SLIDE_EFFECTS[0],
   snapAlign: SNAP_ALIGN_OPTIONS[0],
+  threshold: 0.5,
   touchDrag: true,
   transition: 300,
   wrapAround: false,

src/shared/types.ts

@@ -46,6 +46,7 @@ export type CarouselConfig = {
   preventExcessiveDragging: boolean
   slideEffect: SlideEffect
   snapAlign: SnapAlign
+  threshold: number
   touchDrag?: boolean
   transition?: number
   wrapAround?: boolean

src/utils/getDraggedSlidesCount.spec.ts

@@ -9,6 +9,7 @@ describe('getDraggedSlidesCount', () => {
       isReversed: false,
       dragged: { x: 150, y: 0 },
       effectiveSlideSize: 100,
+      threshold: 0.5,
     }
     expect(getDraggedSlidesCount(params)).toBe(-2)
   })
@@ -19,6 +20,7 @@ describe('getDraggedSlidesCount', () => {
       isReversed: true,
       dragged: { x: 150, y: 0 },
       effectiveSlideSize: 100,
+      threshold: 0.5,
     }
     expect(getDraggedSlidesCount(params)).toBe(2)
   })
@@ -29,6 +31,7 @@ describe('getDraggedSlidesCount', () => {
       isReversed: true,
       dragged: { x: 0, y: 150 },
       effectiveSlideSize: 100,
+      threshold: 0.5,
     }
     expect(getDraggedSlidesCount(params)).toBe(2)
   })
@@ -39,16 +42,106 @@ describe('getDraggedSlidesCount', () => {
       isReversed: false,
       dragged: { x: 0, y: 150 },
       effectiveSlideSize: 100,
+      threshold: 0.5,
     }
     expect(getDraggedSlidesCount(params)).toBe(-2)
   })
 
+  it('should handle drag equal to the threshold', () => {
+    const params = {
+      isVertical: false,
+      isReversed: false,
+      dragged: { x: 50, y: 0 },
+      effectiveSlideSize: 100,
+      threshold: 0.5,
+    };
+    expect(getDraggedSlidesCount(params)).toBe(-1);
+  });
+
+  it('should handle reversed drag equal to the threshold', () => {
+    const params = {
+      isVertical: false,
+      isReversed: true,
+      dragged: { x: 50, y: 0 },
+      effectiveSlideSize: 100,
+      threshold: 0.5,
+    };
+    expect(getDraggedSlidesCount(params)).toBe(1);
+  });
+
+  it('should handle vertical drag equal to the threshold', () => {
+    const params = {
+      isVertical: true,
+      isReversed: false,
+      dragged: { x: 0, y: 50 },
+      effectiveSlideSize: 100,
+      threshold: 0.5,
+    };
+    expect(getDraggedSlidesCount(params)).toBe(-1);
+  });
+
+    it('should handle reversed vertical drag equal to the threshold', () => {
+    const params = {
+      isVertical: true,
+      isReversed: true,
+      dragged: { x: 0, y: 50 },
+      effectiveSlideSize: 100,
+      threshold: 0.5,
+    };
+    expect(getDraggedSlidesCount(params)).toBe(1);
+  });
+
+  it('should handle drag less than the threshold', () => {
+    const params = {
+      isVertical: false,
+      isReversed: false,
+      dragged: { x: 49, y: 0 },
+      effectiveSlideSize: 100,
+      threshold: 0.5,
+    };
+    expect(getDraggedSlidesCount(params)).toBe(0);
+  });
+
+    it('should handle reversed drag less than the threshold', () => {
+    const params = {
+      isVertical: false,
+      isReversed: true,
+      dragged: { x: 49, y: 0 },
+      effectiveSlideSize: 100,
+      threshold: 0.5,
+    };
+    expect(getDraggedSlidesCount(params)).toBe(0);
+  });
+
+  it('should handle vertical drag less than the threshold', () => {
+    const params = {
+      isVertical: true,
+      isReversed: false,
+      dragged: { x: 0, y: 49 },
+      effectiveSlideSize: 100,
+      threshold: 0.5,
+    };
+    expect(getDraggedSlidesCount(params)).toBe(0);
+  });
+
+    it('should handle reversed vertical drag less than the threshold', () => {
+    const params = {
+      isVertical: true,
+      isReversed: true,
+      dragged: { x: 0, y: 49 },
+      effectiveSlideSize: 100,
+      threshold: 0.5,
+    };
+    expect(getDraggedSlidesCount(params)).toBe(0);
+  });
+
   it('should handle zero drag', () => {
     const params = {
       isVertical: false,
       isReversed: false,
       dragged: { x: 0, y: 0 },
       effectiveSlideSize: 100,
+      threshold: 0.5,
     }
     expect(getDraggedSlidesCount(params)).toBe(0)
   })

src/utils/getDraggedSlidesCount.ts

@@ -3,6 +3,7 @@ type DragParams = {
   isReversed: boolean
   dragged: { x: number; y: number }
   effectiveSlideSize: number
+  threshold: number
 }
 
 /**
@@ -11,15 +12,23 @@ type DragParams = {
  * @returns Number of slides to move (positive or negative)
  */
 export function getDraggedSlidesCount(params: DragParams): number {
-  const { isVertical, isReversed, dragged, effectiveSlideSize } = params
+  const { isVertical, isReversed, dragged, effectiveSlideSize, threshold } = params
 
   // Get drag value based on direction
   const dragValue = isVertical ? dragged.y : dragged.x
 
   // If no drag, return +0 explicitly
   if (dragValue === 0) return 0
 
-  const slidesDragged = Math.round(dragValue / effectiveSlideSize)
+  const dragRatio = dragValue / effectiveSlideSize
+  const absRatio = Math.abs(dragRatio)
+
+  // If below the threshold, consider it no movement
+  if (absRatio < threshold) return 0
+  
+  // For drags less than a full slide, move one slide in the drag direction
+  // For drags of a full slide or more, move the corresponding number of slides
+  const slidesDragged = absRatio < 1 ? Math.sign(dragRatio) : Math.round(dragRatio)
 
   return isReversed ? slidesDragged : -slidesDragged
 }