Fix race condition in pause() / resume() system for Embla autoplay plugin

Author: webstackdev

src/components/Carousel/client/__tests__/index.spec.ts

@@ -8,12 +8,38 @@ import type { WebComponentModule } from '@components/scripts/@types/webComponent
 import { executeRender } from '@test/unit/helpers/litRuntime'
 import sampleCollection from '@components/Carousel/client/__fixtures__/collection.fixture'
 
-const createAnimationControllerMock = vi.fn(() => ({
-  requestPlay: vi.fn(),
-  requestPause: vi.fn(),
-  clearUserPreference: vi.fn(),
-  destroy: vi.fn(),
-}))
+const createAnimationControllerMock = vi.fn((config?: { onPlay?: () => void }) => {
+  config?.onPlay?.()
+  return {
+    requestPlay: vi.fn(),
+    requestPause: vi.fn(),
+    clearUserPreference: vi.fn(),
+    destroy: vi.fn(),
+  }
+})
+
+type AutoplayPluginInstance = {
+  play: ReturnType<typeof vi.fn>
+  stop: ReturnType<typeof vi.fn>
+}
+
+const autoplayPluginInstances: AutoplayPluginInstance[] = []
+
+const createAutoplayPluginMock = vi.fn(() => {
+  const instance: AutoplayPluginInstance = {
+    play: vi.fn(),
+    stop: vi.fn(),
+  }
+  autoplayPluginInstances.push(instance)
+  return instance
+})
+
+let mockScrollSnaps = [0, 1, 2]
+
+const setMockScrollSnaps = (snapCount: number) => {
+  const count = Math.max(1, snapCount)
+  mockScrollSnaps = Array.from({ length: count }, (_, index) => index)
+}
 
 vi.mock('@components/scripts/store', () => ({
   createAnimationController: createAnimationControllerMock,
@@ -35,7 +61,7 @@ vi.mock('embla-carousel', () => {
     on: vi.fn(() => createEmbla.mock.results.at(-1)?.value ?? {}),
     off: vi.fn(() => createEmbla.mock.results.at(-1)?.value ?? {}),
     destroy: vi.fn(),
-    scrollSnapList: vi.fn(() => [0, 1, 2]),
+    scrollSnapList: vi.fn(() => mockScrollSnaps),
     selectedScrollSnap: vi.fn(() => 0),
     scrollTo: vi.fn(),
   }))
@@ -47,10 +73,7 @@ vi.mock('embla-carousel', () => {
 
 vi.mock('embla-carousel-autoplay', () => ({
   __esModule: true,
-  default: vi.fn(() => ({
-    play: vi.fn(),
-    stop: vi.fn(),
-  })),
+  default: createAutoplayPluginMock,
 }))
 
 const defaultCarouselProps: ConcreteCarouselProps = {
@@ -90,6 +113,9 @@ describe('Carousel component (server output)', () => {
   beforeEach(() => {
     vi.clearAllMocks()
     createAnimationControllerMock.mockClear()
+    autoplayPluginInstances.length = 0
+    createAutoplayPluginMock.mockClear()
+    setMockScrollSnaps(3)
   })
 
   it('renders the provided title and respects the requested limit', async () => {
@@ -145,6 +171,30 @@ describe('Carousel component (server output)', () => {
   it('registers an animation lifecycle controller', async () => {
     await renderCarousel(() => {
       expect(createAnimationControllerMock).toHaveBeenCalled()
-    })
+    }, { currentSlug: 'article-four' })
+  })
+
+  it('defers autoplay activation until Embla is ready', async () => {
+    vi.useFakeTimers()
+    try {
+      await renderCarousel(async () => {
+        const pluginInstance = autoplayPluginInstances.at(-1)
+        expect(pluginInstance).toBeDefined()
+        expect(pluginInstance?.play).not.toHaveBeenCalled()
+        await vi.runAllTimersAsync()
+        expect(pluginInstance?.play).toHaveBeenCalled()
+      }, { currentSlug: 'article-four' })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('skips autoplay wiring when Embla reports a single snap', async () => {
+    setMockScrollSnaps(1)
+    await renderCarousel(({ root }) => {
+      expect(createAnimationControllerMock).not.toHaveBeenCalled()
+      expect(root.getAttribute('data-carousel-autoplay')).toBe('paused')
+      expect(autoplayPluginInstances.at(-1)?.play).not.toHaveBeenCalled()
+    }, { currentSlug: 'article-four' })
   })
 })

src/components/Carousel/client/index.ts

@@ -7,6 +7,7 @@ import { defineCustomElement } from '@components/scripts/utils'
 import {
   createAnimationController,
   type AnimationControllerHandle,
+  type AnimationPlayState,
 } from '@components/scripts/store'
 import type { WebComponentModule } from '@components/scripts/@types/webComponentModule'
 
@@ -23,6 +24,7 @@ const AUTOPLAY_OPTIONS = {
   delay: 4000,
   stopOnInteraction: true,
   stopOnMouseEnter: true,
+  playOnInit: false,
 }
 
 type DebugEmblaElement = HTMLElement & { __emblaApi__?: EmblaCarouselType }
@@ -37,6 +39,11 @@ export class CarouselElement extends HTMLElement {
   private nextBtn: HTMLButtonElement | null = null
   private initialized = false
   private animationController: AnimationControllerHandle | undefined
+  private pendingAutoplayState: AnimationPlayState | null = null
+  private hasAutoplaySupport = false
+  private autoplayReady = false
+  private autoplayReadyScheduled = false
+  private autoplayReadyTimer: ReturnType<typeof setTimeout> | null = null
   private readonly animationInstanceId: string
   private readonly domReadyHandler = () => {
     document.removeEventListener('DOMContentLoaded', this.domReadyHandler)
@@ -93,24 +100,37 @@ export class CarouselElement extends HTMLElement {
         throw new ClientScriptError('CarouselElement: Missing required DOM parts for initialization.')
       }
 
-      this.autoplayPlugin = Autoplay({ ...AUTOPLAY_OPTIONS })
-      this.emblaApi = EmblaCarousel(this.viewport, EMBLA_OPTIONS, [this.autoplayPlugin])
+      const slideCount = this.querySelectorAll('[data-carousel-slide]').length
+      const requestedAutoplay = slideCount > 1 ? Autoplay({ ...AUTOPLAY_OPTIONS }) : null
+      this.autoplayReady = false
+      this.autoplayReadyScheduled = false
+      const plugins = requestedAutoplay ? [requestedAutoplay] : []
+      this.emblaApi = EmblaCarousel(this.viewport, EMBLA_OPTIONS, plugins)
       this.emblaRoot.__emblaApi__ = this.emblaApi
+      const emblaSnapCount = this.emblaApi.scrollSnapList().length
+      const supportsAutoplay = slideCount > 1 && emblaSnapCount > 1
+      this.hasAutoplaySupport = supportsAutoplay
+      this.autoplayPlugin = supportsAutoplay ? requestedAutoplay : null
       this.setAutoplayState('paused')
 
-      const emblaWithEvents = this.emblaApi as EmblaCarouselType & {
-        on: (_event: string, _handler: () => void) => EmblaCarouselType
-      }
+      if (this.autoplayPlugin) {
+        const emblaWithEvents = this.emblaApi as EmblaCarouselType & {
+          on: (_event: string, _handler: () => void) => EmblaCarouselType
+        }
 
-      emblaWithEvents.on('autoplay:play', this.autoplayPlayHandler)
-      emblaWithEvents.on('autoplay:stop', this.autoplayStopHandler)
+        emblaWithEvents.on('autoplay:play', this.autoplayPlayHandler)
+        emblaWithEvents.on('autoplay:stop', this.autoplayStopHandler)
+      }
 
       this.setupNavigationButtons()
       this.setupDotsNavigation()
 
       this.initialized = true
       this.setAttribute('data-carousel-ready', 'true')
-      this.registerAnimationLifecycle()
+      if (this.hasAutoplaySupport) {
+        this.registerAnimationLifecycle()
+        this.scheduleAutoplayReady()
+      }
     } catch (error) {
       this.teardown()
       handleScriptError(error, context)
@@ -123,8 +143,10 @@ export class CarouselElement extends HTMLElement {
         off: (_event: string, _handler: () => void) => EmblaCarouselType
       }
 
-      emblaWithEvents.off('autoplay:play', this.autoplayPlayHandler)
-      emblaWithEvents.off('autoplay:stop', this.autoplayStopHandler)
+      if (this.autoplayPlugin) {
+        emblaWithEvents.off('autoplay:play', this.autoplayPlayHandler)
+        emblaWithEvents.off('autoplay:stop', this.autoplayStopHandler)
+      }
       this.emblaApi.destroy()
     }
     if (this.emblaRoot && '__emblaApi__' in this.emblaRoot) {
@@ -138,6 +160,14 @@ export class CarouselElement extends HTMLElement {
     this.removeAttribute('data-carousel-autoplay')
     this.animationController?.destroy()
     this.animationController = undefined
+    this.pendingAutoplayState = null
+    this.hasAutoplaySupport = false
+    if (this.autoplayReadyTimer) {
+      clearTimeout(this.autoplayReadyTimer)
+      this.autoplayReadyTimer = null
+    }
+    this.autoplayReadyScheduled = false
+    this.autoplayReady = false
 
     if (this.dotsContainer) {
       this.dotsContainer.innerHTML = ''
@@ -249,17 +279,15 @@ export class CarouselElement extends HTMLElement {
 
   pause(): void {
     try {
-      this.autoplayPlugin?.stop()
-      this.setAutoplayState('paused')
+      this.updateAutoplayState('paused')
     } catch (error) {
       handleScriptError(error, { scriptName: SCRIPT_NAME, operation: 'pause' })
     }
   }
 
   resume(): void {
     try {
-      this.autoplayPlugin?.play()
-      this.setAutoplayState('playing')
+      this.updateAutoplayState('playing')
     } catch (error) {
       handleScriptError(error, { scriptName: SCRIPT_NAME, operation: 'resume' })
     }
@@ -269,8 +297,42 @@ export class CarouselElement extends HTMLElement {
     this.setAttribute('data-carousel-autoplay', state)
   }
 
+  private updateAutoplayState(state: AnimationPlayState): void {
+    if (!this.hasAutoplaySupport || !this.autoplayPlugin || !this.emblaApi || !this.initialized || !this.autoplayReady) {
+      if (this.hasAutoplaySupport) {
+        this.pendingAutoplayState = state
+        this.setAutoplayState(state)
+      } else {
+        this.pendingAutoplayState = null
+        this.setAutoplayState('paused')
+      }
+      return
+    }
+
+    this.pendingAutoplayState = null
+    if (state === 'playing') {
+      this.autoplayPlugin.play()
+    } else {
+      this.autoplayPlugin.stop()
+    }
+    this.setAutoplayState(state)
+  }
+
+  private flushPendingAutoplayState(): void {
+    if (!this.pendingAutoplayState || !this.autoplayReady || !this.autoplayPlugin) return
+
+    const pendingState = this.pendingAutoplayState
+    this.pendingAutoplayState = null
+
+    try {
+      this.updateAutoplayState(pendingState)
+    } catch (error) {
+      handleScriptError(error, { scriptName: SCRIPT_NAME, operation: 'flushAutoplay' })
+    }
+  }
+
   private registerAnimationLifecycle(): void {
-    if (this.animationController) return
+    if (this.animationController || !this.hasAutoplaySupport) return
     this.animationController = createAnimationController({
       animationId: 'carousel',
       instanceId: this.animationInstanceId,
@@ -283,6 +345,26 @@ export class CarouselElement extends HTMLElement {
       },
     })
   }
+
+  private scheduleAutoplayReady(): void {
+    if (this.autoplayReadyScheduled || !this.autoplayPlugin) return
+    this.autoplayReadyScheduled = true
+
+    const markReady = () => {
+      this.autoplayReadyScheduled = false
+      this.autoplayReadyTimer = null
+      if (!this.initialized || !this.autoplayPlugin) return
+      this.autoplayReady = true
+      this.flushPendingAutoplayState()
+    }
+
+    if (typeof window === 'undefined') {
+      markReady()
+      return
+    }
+
+    this.autoplayReadyTimer = window.setTimeout(markReady, 0)
+  }
 }
 
 declare global {

src/components/Testimonials/client/__tests__/index.spec.ts

@@ -8,12 +8,31 @@ import type { WebComponentModule } from '@components/scripts/@types/webComponent
 import { executeRender } from '@test/unit/helpers/litRuntime'
 import testimonialsCollection from '@components/Testimonials/client/__fixtures__/collection.fixture'
 
-const createAnimationControllerMock = vi.fn(() => ({
-  requestPlay: vi.fn(),
-  requestPause: vi.fn(),
-  clearUserPreference: vi.fn(),
-  destroy: vi.fn(),
-}))
+const createAnimationControllerMock = vi.fn((config?: { onPlay?: () => void }) => {
+  config?.onPlay?.()
+  return {
+    requestPlay: vi.fn(),
+    requestPause: vi.fn(),
+    clearUserPreference: vi.fn(),
+    destroy: vi.fn(),
+  }
+})
+
+type AutoplayPluginInstance = {
+  play: ReturnType<typeof vi.fn>
+  stop: ReturnType<typeof vi.fn>
+}
+
+const autoplayPluginInstances: AutoplayPluginInstance[] = []
+
+const createAutoplayPluginMock = vi.fn(() => {
+  const instance: AutoplayPluginInstance = {
+    play: vi.fn(),
+    stop: vi.fn(),
+  }
+  autoplayPluginInstances.push(instance)
+  return instance
+})
 
 vi.mock('@components/scripts/store', () => ({
   createAnimationController: createAnimationControllerMock,
@@ -53,10 +72,7 @@ vi.mock('embla-carousel', () => {
 
 vi.mock('embla-carousel-autoplay', () => ({
   __esModule: true,
-  default: vi.fn(() => ({
-    play: vi.fn(),
-    stop: vi.fn(),
-  })),
+  default: createAutoplayPluginMock,
 }))
 
 const defaultProps: TestimonialsProps = {
@@ -89,6 +105,8 @@ describe('Testimonials component', () => {
   beforeEach(() => {
     vi.clearAllMocks()
     createAnimationControllerMock.mockClear()
+    autoplayPluginInstances.length = 0
+    createAutoplayPluginMock.mockClear()
   })
 
   it('renders the supplied title and respects the limit', async () => {
@@ -113,7 +131,7 @@ describe('Testimonials component', () => {
       const dots = root.querySelectorAll('.embla__dot')
 
       expect(root.getAttribute('data-carousel-ready')).toBe('true')
-      expect(root.getAttribute('data-carousel-autoplay')).toBe('paused')
+      expect(root.getAttribute('data-carousel-autoplay')).toBe('playing')
       expect(dots.length).toBeGreaterThan(0)
     })
   })
@@ -123,4 +141,18 @@ describe('Testimonials component', () => {
       expect(createAnimationControllerMock).toHaveBeenCalled()
     })
   })
+
+  it('defers autoplay activation until Embla is ready', async () => {
+    vi.useFakeTimers()
+    try {
+      await renderTestimonials(async () => {
+        const pluginInstance = autoplayPluginInstances.at(-1)
+        expect(pluginInstance?.play).not.toHaveBeenCalled()
+        await vi.runAllTimersAsync()
+        expect(pluginInstance?.play).toHaveBeenCalled()
+      })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
 })