Refactor of all animation-related components and mobile navigation to use a central store for eventing instead of an ad hoc events systems. Implements pause / resume when the mobile splash screen opens, maintains state and checks prefers-reduced motion to pause animations when the user does not want them.

Author: webstackdev

eslint.config.ts

@@ -1,3 +1,4 @@
+/* eslint-disable */
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import eslint from '@eslint/js'
@@ -13,6 +14,7 @@ import noHtmlElementAssertionsRule from './test/eslint/no-html-element-assertion
 import noQuerySelectorOutsideSelectorsRule from './test/eslint/no-query-selector-outside-selectors-rule'
 
 const level = 'error'
+const astroParser = (astroPlugin as unknown as { parser: typeof tsPlugin.parser }).parser
 const tsconfigRootDir = path.dirname(fileURLToPath(import.meta.url))
 
 const errorDefinitionIgnores = [
@@ -239,6 +241,7 @@ export default [
   {
     files: [
       'integrations/**/*',
+      'src/integrations/**/*',
       'scripts/**/*.ts',
       'src/components/**/server/**/*',
       'src/layouts/**/server/**/*',
@@ -272,6 +275,16 @@ export default [
       'no-restricted-syntax': createRestrictedSyntaxRule({ allowTestError: true }),
     },
   },
+  {
+    files: [
+      'src/integrations/**/*.spec.ts',
+      'src/integrations/**/__tests__/**/*.ts',
+    ],
+    ignores: errorDefinitionIgnores,
+    rules: {
+      'no-restricted-syntax': createRestrictedSyntaxRule({ allowTestError: true }),
+    },
+  },
   /**
    * =================================================================================================
    *
@@ -304,7 +317,7 @@ export default [
       'src/pages/**/*.astro',
     ],
     languageOptions: {
-      parser: astroPlugin.parser,
+      parser: astroParser,
       parserOptions: {
         parser: tsPlugin.parser,
         project: './tsconfig.json',
@@ -667,6 +680,8 @@ export default [
   },
   {
     files: [
+      /** Test case for the utility is an exception to the restricted paths rule */
+      'src/components/scripts/utils/__tests__/siteUrlClient.spec.ts',
       /** Environment file in src/pages/api is an exception to the restricted paths rule */
       'src/pages/api/_environment/environmentApi.ts',
       'src/pages/api/_logger/index.ts',

src/components/Animations/Computers/client/__tests__/index.spec.ts

@@ -50,12 +50,14 @@ const getComputersModule = () => {
 
 const addScriptBreadcrumbMock = vi.hoisted(() => vi.fn())
 const handleScriptErrorMock = vi.hoisted(() => vi.fn())
-const onAnimationEventMock = vi.hoisted(() => vi.fn())
-
-const lifecycleEvents = vi.hoisted(() => ({
-  OVERLAY_OPENED: 'overlay-opened',
-  OVERLAY_CLOSED: 'overlay-closed',
-}))
+const createAnimationControllerMock = vi.hoisted(() =>
+  vi.fn(() => ({
+    requestPlay: vi.fn(),
+    requestPause: vi.fn(),
+    clearUserPreference: vi.fn(),
+    destroy: vi.fn(),
+  }))
+)
 
 vi.mock('@components/scripts/errors', () => ({
   addScriptBreadcrumb: addScriptBreadcrumbMock,
@@ -65,9 +67,8 @@ vi.mock('@components/scripts/errors/handler', () => ({
   handleScriptError: handleScriptErrorMock,
 }))
 
-vi.mock('@components/scripts/events', () => ({
-  AnimationLifecycleEvent: lifecycleEvents,
-  onAnimationEvent: onAnimationEventMock,
+vi.mock('@components/scripts/store', () => ({
+  createAnimationController: createAnimationControllerMock,
 }))
 
 vi.mock('gsap', () => ({
@@ -141,8 +142,6 @@ describe('ComputersAnimation web component module', () => {
 
 describe('ComputersAnimationElement', () => {
   it('initializes the GSAP timeline when hero markup exists', async () => {
-    const { overlayOpenedCleanup, overlayClosedCleanup } = mockOverlayLifecycle()
-
     await renderComputersAnimation(async ({ element }) => {
       element.initialize()
 
@@ -152,22 +151,25 @@ describe('ComputersAnimationElement', () => {
         '.monitorBottom',
         expect.objectContaining({ transformOrigin: '50% 100%' }),
       )
-      expect(onAnimationEventMock).toHaveBeenNthCalledWith(1, lifecycleEvents.OVERLAY_OPENED, expect.any(Function))
-      expect(onAnimationEventMock).toHaveBeenNthCalledWith(2, lifecycleEvents.OVERLAY_CLOSED, expect.any(Function))
+      expect(createAnimationControllerMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          animationId: 'computers-animation',
+          debugLabel: 'ComputersAnimationElement',
+          onPause: expect.any(Function),
+          onPlay: expect.any(Function),
+        }),
+      )
       expect(getBreadcrumbOperations()).toEqual(expect.arrayContaining(['initialize', 'startAnimation']))
-      expect(overlayOpenedCleanup).not.toHaveBeenCalled()
-      expect(overlayClosedCleanup).not.toHaveBeenCalled()
     })
   })
 
-  it('pauses and resumes when overlay lifecycle events fire', async () => {
-    mockOverlayLifecycle()
-
+  it('pauses and resumes when lifecycle controller callbacks run', async () => {
     await renderComputersAnimation(async ({ element }) => {
       element.initialize()
 
-      const pauseHandler = onAnimationEventMock.mock.calls[0]?.[1] as (() => void) | undefined
-      const resumeHandler = onAnimationEventMock.mock.calls[1]?.[1] as (() => void) | undefined
+      const controllerArgs = createAnimationControllerMock.mock.calls[0]?.[0]
+      const pauseHandler = controllerArgs?.onPause
+      const resumeHandler = controllerArgs?.onPlay
 
       pauseHandler?.()
       resumeHandler?.()
@@ -179,14 +181,12 @@ describe('ComputersAnimationElement', () => {
   })
 
   it('tears down resources on disconnect', async () => {
-    const { overlayOpenedCleanup, overlayClosedCleanup } = mockOverlayLifecycle()
-
     await renderComputersAnimation(async ({ element }) => {
       element.initialize()
       element.disconnectedCallback()
 
-      expect(overlayOpenedCleanup).toHaveBeenCalled()
-      expect(overlayClosedCleanup).toHaveBeenCalled()
+      const controllerHandle = getLastControllerHandle()
+      expect(controllerHandle?.destroy).toHaveBeenCalled()
       expect(timelineMock.kill).toHaveBeenCalled()
       expect(getBreadcrumbOperations()).toContain('teardown')
     })
@@ -274,13 +274,6 @@ const renderComputersAnimation = async (
   })
 }
 
-const mockOverlayLifecycle = () => {
-  const overlayOpenedCleanup = vi.fn()
-  const overlayClosedCleanup = vi.fn()
-  onAnimationEventMock.mockReturnValueOnce(overlayOpenedCleanup).mockReturnValueOnce(overlayClosedCleanup)
-  return { overlayOpenedCleanup, overlayClosedCleanup }
-}
-
 const getBreadcrumbOperations = (): string[] => {
   return addScriptBreadcrumbMock.mock.calls
     .map(([context]) => context?.operation)
@@ -323,3 +316,8 @@ function createTimelineMock() {
 }
 
 const generateUniqueTagName = (): string => `computers-animation-${Math.random().toString(36).slice(2)}`
+
+const getLastControllerHandle = () =>
+  createAnimationControllerMock.mock.results.at(-1)?.value as
+    | ReturnType<typeof createAnimationControllerMock>
+    | undefined

src/components/Animations/Computers/client/index.ts

@@ -2,7 +2,10 @@ import { LitElement } from 'lit'
 import { gsap } from 'gsap'
 import { addScriptBreadcrumb } from '@components/scripts/errors'
 import { handleScriptError } from '@components/scripts/errors/handler'
-import { AnimationLifecycleEvent, onAnimationEvent } from '@components/scripts/events'
+import {
+  createAnimationController,
+  type AnimationControllerHandle,
+} from '@components/scripts/store'
 import { defineCustomElement } from '@components/scripts/utils'
 import type { WebComponentModule } from '@components/scripts/@types/webComponentModule'
 
@@ -36,9 +39,8 @@ const Anticipate = {
 
 export class ComputersAnimationElement extends LitElement {
   private timeline: Timeline | null = null
-  private overlayOpenedCleanup: (() => void) | undefined
-  private overlayClosedCleanup: (() => void) | undefined
   private initialized = false
+  private animationController: AnimationControllerHandle | undefined
   private readonly domReadyHandler = () => {
     document.removeEventListener('DOMContentLoaded', this.domReadyHandler)
     this.initialize()
@@ -76,11 +78,15 @@ export class ComputersAnimationElement extends LitElement {
 
     try {
       this.startAnimation()
-      this.overlayOpenedCleanup = onAnimationEvent(AnimationLifecycleEvent.OVERLAY_OPENED, () => {
-        this.pause()
-      })
-      this.overlayClosedCleanup = onAnimationEvent(AnimationLifecycleEvent.OVERLAY_CLOSED, () => {
-        this.resume()
+      this.animationController = createAnimationController({
+        animationId: 'computers-animation',
+        debugLabel: SCRIPT_NAME,
+        onPause: () => {
+          this.pause()
+        },
+        onPlay: () => {
+          this.resume()
+        },
       })
       this.initialized = true
     } catch (error) {
@@ -117,10 +123,8 @@ export class ComputersAnimationElement extends LitElement {
     addScriptBreadcrumb(context)
 
     try {
-      this.overlayOpenedCleanup?.()
-      this.overlayClosedCleanup?.()
-      this.overlayOpenedCleanup = undefined
-      this.overlayClosedCleanup = undefined
+      this.animationController?.destroy()
+      this.animationController = undefined
 
       if (this.timeline) {
         this.timeline.kill()

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

@@ -9,6 +9,17 @@ 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(),
+}))
+
+vi.mock('@components/scripts/store', () => ({
+  createAnimationController: createAnimationControllerMock,
+}))
+
 type CarouselComponentModule = WebComponentModule<CarouselElement>
 type ConcreteCarouselProps = Required<CarouselProps<'articles'>>
 
@@ -79,6 +90,7 @@ const renderCarousel = async (
 describe('Carousel component (server output)', () => {
   beforeEach(() => {
     vi.clearAllMocks()
+    createAnimationControllerMock.mockClear()
   })
 
   it('renders the provided title and respects the requested limit', async () => {
@@ -130,4 +142,10 @@ describe('Carousel component (server output)', () => {
       expect(new Set(cardTitles)).toEqual(new Set(['Article Four', 'Article Three', 'Article One']))
     }, { variant: 'random', limit: 3 })
   })
+
+  it('registers an animation lifecycle controller', async () => {
+    await renderCarousel(() => {
+      expect(createAnimationControllerMock).toHaveBeenCalled()
+    })
+  })
 })

src/components/Carousel/client/index.ts

@@ -4,6 +4,10 @@ import { addButtonEventListeners } from '@components/scripts/elementListeners'
 import { addScriptBreadcrumb, ClientScriptError } from '@components/scripts/errors'
 import { handleScriptError } from '@components/scripts/errors/handler'
 import { defineCustomElement } from '@components/scripts/utils'
+import {
+  createAnimationController,
+  type AnimationControllerHandle,
+} from '@components/scripts/store'
 import type { WebComponentModule } from '@components/scripts/@types/webComponentModule'
 
 const SCRIPT_NAME = 'CarouselElement'
@@ -32,15 +36,22 @@ export class CarouselElement extends HTMLElement {
   private prevBtn: HTMLButtonElement | null = null
   private nextBtn: HTMLButtonElement | null = null
   private initialized = false
+  private animationController: AnimationControllerHandle | undefined
+  private readonly animationInstanceId: string
   private readonly domReadyHandler = () => {
     document.removeEventListener('DOMContentLoaded', this.domReadyHandler)
     this.initialize()
   }
   private readonly autoplayPlayHandler = () => this.setAutoplayState('playing')
   private readonly autoplayStopHandler = () => this.setAutoplayState('paused')
 
-  private static readonly instances = new Set<CarouselElement>()
-  private static visibilityHandler: (() => void) | undefined
+  private static instanceCounter = 0
+
+  constructor() {
+    super()
+    CarouselElement.instanceCounter += 1
+    this.animationInstanceId = `carousel-${CarouselElement.instanceCounter}`
+  }
 
   connectedCallback(): void {
     if (typeof document === 'undefined') return
@@ -49,7 +60,6 @@ export class CarouselElement extends HTMLElement {
     addScriptBreadcrumb(context)
 
     try {
-      CarouselElement.registerInstance(this)
       if (document.readyState === 'loading') {
         document.addEventListener('DOMContentLoaded', this.domReadyHandler, { once: true })
         return
@@ -64,7 +74,6 @@ export class CarouselElement extends HTMLElement {
     if (typeof document === 'undefined') return
     document.removeEventListener('DOMContentLoaded', this.domReadyHandler)
     this.teardown()
-    CarouselElement.unregisterInstance(this)
   }
 
   private initialize(): void {
@@ -101,6 +110,7 @@ export class CarouselElement extends HTMLElement {
 
       this.initialized = true
       this.setAttribute('data-carousel-ready', 'true')
+      this.registerAnimationLifecycle()
     } catch (error) {
       this.teardown()
       handleScriptError(error, context)
@@ -126,6 +136,8 @@ export class CarouselElement extends HTMLElement {
     this.initialized = false
     this.removeAttribute('data-carousel-ready')
     this.removeAttribute('data-carousel-autoplay')
+    this.animationController?.destroy()
+    this.animationController = undefined
 
     if (this.dotsContainer) {
       this.dotsContainer.innerHTML = ''
@@ -257,39 +269,19 @@ export class CarouselElement extends HTMLElement {
     this.setAttribute('data-carousel-autoplay', state)
   }
 
-  private static registerInstance(instance: CarouselElement): void {
-    CarouselElement.instances.add(instance)
-    CarouselElement.ensureVisibilityHandler()
-  }
-
-  private static unregisterInstance(instance: CarouselElement): void {
-    CarouselElement.instances.delete(instance)
-    if (CarouselElement.instances.size === 0) {
-      CarouselElement.cleanupVisibilityHandler()
-    }
-  }
-
-  private static ensureVisibilityHandler(): void {
-    if (typeof document === 'undefined') return
-    if (CarouselElement.visibilityHandler) return
-
-    CarouselElement.visibilityHandler = () => {
-      if (document.hidden) {
-        CarouselElement.instances.forEach(instance => instance.pause())
-      } else {
-        CarouselElement.instances.forEach(instance => instance.resume())
-      }
-    }
-
-    document.addEventListener('visibilitychange', CarouselElement.visibilityHandler)
-  }
-
-  private static cleanupVisibilityHandler(): void {
-    if (typeof document === 'undefined') return
-    if (!CarouselElement.visibilityHandler) return
-
-    document.removeEventListener('visibilitychange', CarouselElement.visibilityHandler)
-    CarouselElement.visibilityHandler = undefined
+  private registerAnimationLifecycle(): void {
+    if (this.animationController) return
+    this.animationController = createAnimationController({
+      animationId: 'carousel',
+      instanceId: this.animationInstanceId,
+      debugLabel: SCRIPT_NAME,
+      onPlay: () => {
+        this.resume()
+      },
+      onPause: () => {
+        this.pause()
+      },
+    })
   }
 }