#416 - Add watchDrag option

packages/embla-carousel-class-names/src/components/ClassNames.ts

@@ -35,7 +35,7 @@ function ClassNames(userOptions: ClassNamesOptionsType = {}): ClassNamesType {
 
     root = carousel.rootNode()
     slides = carousel.slideNodes()
-    const isDraggable = carousel.internalEngine().options.draggable
+    const isDraggable = !!carousel.internalEngine().options.watchDrag
 
     if (isDraggable) {
       addClass(root, options.draggable)

packages/embla-carousel-docs/src/content/pages/api/options.mdx

@@ -231,15 +231,6 @@ Set scroll duration when triggered by any of the API methods. Higher numbers ena
 
 ---
 
-### draggable
-
-Type: <BrandPrimaryText>`boolean`</BrandPrimaryText>  
-Default: <BrandSecondaryText>`true`</BrandSecondaryText>
-
-Enables for scrolling the carousel with mouse and touch interactions.
-
----
-
 ### inViewThreshold
 
 Type: <BrandPrimaryText>`number`</BrandPrimaryText>  
@@ -310,12 +301,28 @@ Set the initial scroll snap to the given number. First snap index starts at `0`.
 
 ---
 
+### watchDrag
+
+Type: <BrandPrimaryText>`boolean | (event: MouseEvent | TouchEvent, emblaApi: EmblaCarouselType) => boolean | void`</BrandPrimaryText>  
+Default: <BrandSecondaryText>`true`</BrandSecondaryText>
+
+Enables for scrolling the carousel with mouse and touch interactions. Set this to `false` to disable drag events or pass a custom callback to add your own drag logic.
+
+<Admonition type="note">
+  **Note:** When passing a custom callback it will run **before** the default
+  Embla drag behaviour. Return `true` in your callback if you want Embla to run
+  its default drag behaviour after your callback, or return `false` if you want
+  to disable it.
+</Admonition>
+
+---
+
 ### watchResize
 
 Type: <BrandPrimaryText>`boolean | (entries: ResizeObserverEntry[], emblaApi: EmblaCarouselType) => boolean | void`</BrandPrimaryText>  
 Default: <BrandSecondaryText>`true`</BrandSecondaryText>
 
-Embla automatically watches the [container](/api/methods/#containernode/) and [slides](/api/methods/#slidenodes/) for size changes and runs [reInit](/api/methods/#reinit/) when any size has changed. Set this to `false` to disable this behaviour or pass a custom callback to write your own resize logic.
+Embla automatically watches the [container](/api/methods/#containernode/) and [slides](/api/methods/#slidenodes/) for size changes and runs [reInit](/api/methods/#reinit/) when any size has changed. Set this to `false` to disable this behaviour or pass a custom callback to add your own resize logic.
 
 <Admonition type="note">
   **Note:** When passing a custom callback it will run **before** the default
@@ -331,7 +338,7 @@ Embla automatically watches the [container](/api/methods/#containernode/) and [s
 Type: <BrandPrimaryText>`boolean | (mutations: MutationRecord[], emblaApi: EmblaCarouselType) => boolean | void`</BrandPrimaryText>  
 Default: <BrandSecondaryText>`true`</BrandSecondaryText>
 
-Embla automatically watches the [container](/api/methods/#containernode/) for **added** and/or **removed** slides and runs [reInit](/api/methods/#reinit/) if needed. Set this to `false` to disable this behaviour or pass a custom callback to write your own resize logic.
+Embla automatically watches the [container](/api/methods/#containernode/) for **added** and/or **removed** slides and runs [reInit](/api/methods/#reinit/) if needed. Set this to `false` to disable this behaviour or pass a custom callback to add your own slides changed logic.
 
 <Admonition type="note">
   **Note:** When passing a custom callback it will run **before** the default

packages/embla-carousel-docs/src/content/pages/guides/previous-and-next-buttons.md

@@ -14,7 +14,7 @@ This guide will show you **how** to **add previous and next buttons** using the
 
 ## Button placement
 
-Assuming your carousel is [draggable](/api/options/#draggable), it's important to note that the **root node** will **respond to pointer events**. The root node is the one that is passed to the `EmblaCarousel` initializer. In the following example, it has the class name `embla`:
+Assuming your carousel is [draggable](/api/options/#watchdrag), it's important to note that the **root node** will **respond to pointer events**. The root node is the one that is passed to the `EmblaCarousel` initializer. In the following example, it has the class name `embla`:
 
 ```html
 <div class="embla">

packages/embla-carousel/src/components/DragHandler.ts

@@ -1,3 +1,4 @@
+import { EmblaCarouselType } from './EmblaCarousel'
 import { AnimationType } from './Animation'
 import { CounterType } from './Counter'
 import { DirectionType } from './Direction'
@@ -9,12 +10,19 @@ import { ScrollBodyType } from './ScrollBody'
 import { ScrollTargetType } from './ScrollTarget'
 import { ScrollToType } from './ScrollTo'
 import { Vector1D, Vector1DType } from './Vector1d'
-import { deltaAbs, factorAbs, mathAbs, mathSign } from './utils'
+import { deltaAbs, factorAbs, isBoolean, mathAbs, mathSign } from './utils'
 import { PercentOfViewType } from './PercentOfView'
 import { Limit } from './Limit'
 
+type DragHandlerCallbackType = (
+  evt: PointerEventType,
+  emblaApi: EmblaCarouselType,
+) => boolean | void
+
+export type DragHandlerOptionType = boolean | DragHandlerCallbackType
+
 export type DragHandlerType = {
-  init: () => void
+  init: (emblaApi: EmblaCarouselType, watchDrag: DragHandlerOptionType) => void
   destroy: () => void
   pointerDown: () => boolean
 }
@@ -55,14 +63,23 @@ export function DragHandler(
   let preventClick = false
   let isMouse = false
 
-  function init(): void {
+  function init(
+    emblaApi: EmblaCarouselType,
+    watchDrag: DragHandlerOptionType,
+  ): void {
+    if (!watchDrag) return
+
+    function downIfAllowed(evt: PointerEventType): void {
+      if (isBoolean(watchDrag) || watchDrag(evt, emblaApi)) down(evt)
+    }
+
     const node = rootNode
     initEvents
       .add(node, 'dragstart', (evt) => evt.preventDefault(), nonPassiveEvent)
       .add(node, 'touchmove', () => undefined, nonPassiveEvent)
       .add(node, 'touchend', () => undefined)
-      .add(node, 'touchstart', down)
-      .add(node, 'mousedown', down)
+      .add(node, 'touchstart', downIfAllowed)
+      .add(node, 'mousedown', downIfAllowed)
       .add(node, 'touchcancel', up)
       .add(node, 'contextmenu', up)
       .add(node, 'click', click, true)

packages/embla-carousel/src/components/EmblaCarousel.ts

@@ -103,8 +103,8 @@ function EmblaCarousel(
       }
       engine.slideLooper.loop()
     }
-    if (options.draggable && container.offsetParent && slides.length) {
-      engine.dragHandler.init()
+    if (container.offsetParent && slides.length) {
+      engine.dragHandler.init(self, options.watchDrag)
     }
   }
 

packages/embla-carousel/src/components/Options.ts

@@ -3,6 +3,7 @@ import { AxisOptionType } from './Axis'
 import { SlidesToScrollOptionType } from './SlidesToScroll'
 import { DirectionOptionType } from './Direction'
 import { ScrollContainOptionType } from './ScrollContain'
+import { DragHandlerOptionType } from './DragHandler'
 import { ResizeHandlerOptionType } from './ResizeHandler'
 import { SlidesHandlerOptionType } from './SlidesHandler'
 
@@ -26,12 +27,12 @@ export type OptionsType = CreateOptionsType<{
   direction: DirectionOptionType
   slidesToScroll: SlidesToScrollOptionType
   dragFree: boolean
-  draggable: boolean
   inViewThreshold: number
   loop: boolean
   skipSnaps: boolean
   duration: number
   startIndex: number
+  watchDrag: DragHandlerOptionType
   watchResize: ResizeHandlerOptionType
   watchSlides: SlidesHandlerOptionType
 }>
@@ -46,13 +47,13 @@ export const defaultOptions: OptionsType = {
   slidesToScroll: 1,
   breakpoints: {},
   dragFree: false,
-  draggable: true,
   inViewThreshold: 0,
   loop: false,
   skipSnaps: false,
   duration: 25,
   startIndex: 0,
   active: true,
+  watchDrag: true,
   watchResize: true,
   watchSlides: true,
 }

packages/embla-carousel/src/components/ResizeHandler.ts

@@ -42,7 +42,7 @@ export function ResizeHandler(
     containerSize = readSize(container)
     slideSizes = slides.map(readSize)
 
-    const defaultCallback = (entries: ResizeObserverEntry[]): void => {
+    function defaultCallback(entries: ResizeObserverEntry[]): void {
       for (const entry of entries) {
         const isContainer = entry.target === container
         const slideIndex = slides.indexOf(<HTMLElement>entry.target)

packages/embla-carousel/src/components/SlidesHandler.ts

@@ -26,7 +26,7 @@ export function SlidesHandler(container: HTMLElement): SlidesHandlerType {
   ): void {
     if (!watchSlides) return
 
-    const defaultCallback = (mutations: MutationRecord[]): void => {
+    function defaultCallback(mutations: MutationRecord[]): void {
       for (const mutation of mutations) {
         if (mutation.type === 'childList') {
           emblaApi.reInit()