feat: rename mouseScroll to mouseWheel and enhance wheel options in Carousel configuration

Author: ismail9k

docs/config.md

@@ -18,8 +18,7 @@
 | `itemsToShow`              | `number`  \| 'auto'                         | 1                                | Number of slides visible simultaneously. Use 'auto' for variable width slides.                         |
 | `modelValue`               | `number`                                    | 0                                | Controls the active slide index. Can be used with v-model for two-way binding.                         |
 | `mouseDrag`                | `boolean` \| `DragConfig`                   | true                             | Enables/disables mouse drag navigation. See [Drag Options](#drag-options) for configuration details.   |
-| `mouseScroll`              | `boolean`                                   | false                            | Enables/disables mouse wheel scrolling for carousel navigation.                                        |
-| `mouseScrollThreshold`     | `number`                                    | 10                               | Controls the sensitivity threshold for mouse scrolling. Higher values require more scrolling.          |
+| `mouseWheel`               | `boolean` \| `WheelConfig`                   | false                            | Enables/disables mouse wheel scrolling for carousel navigation. See [Wheel Options](#wheel-options) for configuration details. |
 | `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" />                 |
 | `slideEffect`              | 'slide', 'fade'                             | 'slide'                          | Determines the transition effect between slides.                                                       |
@@ -55,6 +54,42 @@ Both `mouseDrag` and `touchDrag` properties accept either a boolean value or a `
 </template>
 ```
 
+## Wheel Options
+
+The `mouseWheel` property accepts either a boolean value or a `WheelConfig` object with the following properties:
+
+| Property    | Type     | Default | Description                                                                                |
+|-------------|----------|---------|--------------------------------------------------------------------------------------------|
+| `threshold` | `number` | 10      | Controls the wheel movement threshold required to trigger a slide transition. Higher values require more scrolling to trigger a slide change. |
+
+### Example
+
+```vue
+<template>
+  <Carousel 
+    :mouseWheel="{ threshold: 20 }"
+  >
+    <!-- Slides -->
+  </Carousel>
+</template>
+```
+
+## I18n
+
+Available keys:
+
+| Key                   | Defaults                               | Description                                                                |
+| --------------------- | -------------------------------------- | -------------------------------------------------------------------------- |
+| `ariaGallery`         | "Gallery"                              | Used as the aria-label for the main carousel element, indicating purpose.  |
+| `ariaNavigateToSlide` | "Navigate to slide {slideNumber}"      | Sets title and aria-label for pagination buttons to select a slide.        |
+| `ariaNextSlide`       | "Navigate to next slide"               | Sets title and aria-label for the "Next" navigation button.                |
+| `ariaPreviousSlide`   | "Navigate to previous slide"           | Sets title and aria-label for the "Previous" navigation button.            |
+| `iconArrowDown`       | "Arrow pointing downwards"             | Sets title and aria-label for the downward-pointing arrow SVG icon.        |
+| `iconArrowLeft`       | "Arrow pointing to the left"           | Sets title and aria-label for the left-pointing arrow SVG icon.            |
+| `iconArrowRight`      | "Arrow pointing to the right"          | Sets title and aria-label for the right-pointing arrow SVG icon.           |
+| `iconArrowUp`         | "Arrow pointing upwards"               | Sets title and aria-label for the upward-pointing arrow SVG icon.          |
+| `itemXofY`            | "Item {currentSlide} of {slidesCount}" | Provides screen readers with the current slide's position in the sequence. |
+
 ## Slots
 
 ### Slides/Default
@@ -141,3 +176,16 @@ Available keys:
 | `iconArrowRight`      | "Arrow pointing to the right"          | Sets title and aria-label for the right-pointing arrow SVG icon.           |
 | `iconArrowUp`         | "Arrow pointing upwards"               | Sets title and aria-label for the upward-pointing arrow SVG icon.          |
 | `itemXofY`            | "Item {currentSlide} of {slidesCount}" | Provides screen readers with the current slide's position in the sequence. |
+
+### Example
+
+```vue
+<template>
+  <Carousel 
+    :mouseDrag="{ threshold: 0.5 }" 
+    :touchDrag="{ threshold: 0.7 }"
+  >
+    <!-- Slides -->
+  </Carousel>
+</template>
+```

src/components/Carousel/Carousel.ts

@@ -861,7 +861,7 @@ export const Carousel = defineComponent({
           style: { transform: trackTransform.value },
           onMousedownCapture: config.mouseDrag ? handleDragStart : null,
           onTouchstartPassiveCapture: config.touchDrag ? handleDragStart : null,
-          onWheel: config.mouseScroll ? handleScroll : null,
+          onWheel: config.mouseWheel ? handleScroll : null,
         },
         output
       )

src/components/Carousel/carouselProps.ts

@@ -18,6 +18,7 @@ import type {
   SlideEffect,
   SnapAlign,
   DragConfig,
+  WheelConfig,
 } from '@/shared'
 
 export const carouselProps = {
@@ -109,9 +110,9 @@ export const carouselProps = {
     type: [Boolean, Object] as PropType<boolean | DragConfig>,
   },
   // toggle mouse wheel scrolling
-  mouseScroll: {
-    default: DEFAULT_CONFIG.mouseScroll,
-    type: Boolean,
+  mouseWheel: {
+    default: DEFAULT_CONFIG.mouseWheel,
+    type: [Boolean, Object] as PropType<boolean | WheelConfig>,
   },
   // control mouse scroll threshold
   mouseScrollThreshold: {

src/composables/useWheel.ts

@@ -29,7 +29,7 @@ export function useWheel(options: UseWheelOptions) {
   })
 
   const handleScroll = throttle((event: Event): void => {
-    if (!config.mouseScroll || sliding.value) {
+    if (!config.mouseWheel || sliding.value) {
       return
     }
 
@@ -39,7 +39,8 @@ export function useWheel(options: UseWheelOptions) {
     const wheelEvent = event as WheelEvent
 
     // Add sensitivity threshold to prevent small movements from triggering navigation
-    const threshold = config.mouseScrollThreshold as number // Default to 30 if undefined
+    const threshold =
+      typeof config.mouseWheel === 'object' ? (config.mouseWheel.threshold ?? 10) : 10
 
     // Determine scroll direction
     const deltaY = Math.abs(wheelEvent.deltaY) > threshold ? wheelEvent.deltaY : 0

src/shared/constants.ts

@@ -59,7 +59,7 @@ export const DEFAULT_CONFIG: CarouselConfig = {
   itemsToShow: 1,
   modelValue: 0,
   mouseDrag: true,
-  mouseScroll: false,
+  mouseWheel: false,
   mouseScrollThreshold: 10,
   pauseAutoplayOnHover: false,
   preventExcessiveDragging: false,

src/shared/types.ts

@@ -31,6 +31,9 @@ export type SnapAlign = (typeof SNAP_ALIGN_OPTIONS)[number]
 export type DragConfig = {
   threshold?: number
 }
+export type WheelConfig = {
+  threshold?: number
+}
 
 export type CarouselConfig = {
   autoplay?: number
@@ -47,7 +50,7 @@ export type CarouselConfig = {
   itemsToShow: number | 'auto'
   modelValue?: number
   mouseDrag?: boolean | DragConfig
-  mouseScroll?: boolean
+  mouseWheel?: boolean | WheelConfig
   mouseScrollThreshold?: number
   pauseAutoplayOnHover?: boolean
   preventExcessiveDragging: boolean