fix: harden embla initialization filters

Author: sunmorgn

docs/API.md

@@ -26,7 +26,7 @@ addFilter(
 );
 ```
 
-Both filters receive the carousel context object as the third argument. `rtcamp.carouselKit.emblaPlugins` also receives the filtered options on `options`.
+Both filter callbacks receive the filtered value as their first argument and the filter context object as their second argument. `rtcamp.carouselKit.emblaPlugins` also receives the filtered options on the `options` property of this object.
 
 rtCarousel also exposes an action after Embla has initialized so integrations can call Embla methods or subscribe to Embla events:
 

src/blocks/carousel/__tests__/view.test.ts

@@ -863,6 +863,92 @@ describe( 'Carousel View Module', () => {
 					delete ( window as HooksWindow ).wp;
 				}
 			} );
+
+			it( 'should keep original Embla options when the options filter returns undefined', () => {
+				const mockContext = createMockContext( {
+					options: { duration: 25 },
+				} );
+				const { wrapper, viewport } = createMockCarouselDOM();
+				const mockEmbla = createMockEmblaInstance();
+				const originalIntersectionObserver = window.IntersectionObserver;
+				const applyFilters = jest.fn( ( hookName, value ) => {
+					if ( hookName === 'rtcamp.carouselKit.emblaOptions' ) {
+						return undefined;
+					}
+					return value;
+				} );
+
+				mockVisibleViewport( viewport );
+
+				( window as HooksWindow ).wp = {
+					hooks: {
+						applyFilters,
+					},
+				};
+				( getContext as jest.Mock ).mockReturnValue( mockContext );
+				( getElement as jest.Mock ).mockReturnValue( { ref: wrapper } );
+				( EmblaCarousel as unknown as jest.Mock ).mockReturnValue( mockEmbla );
+				delete ( window as Window & { IntersectionObserver?: typeof IntersectionObserver } ).IntersectionObserver;
+
+				try {
+					storeConfig.callbacks.initCarousel();
+
+					expect( EmblaCarousel ).toHaveBeenCalledWith(
+						viewport,
+						expect.objectContaining( { duration: 25 } ),
+						[],
+					);
+				} finally {
+					( window as Window & { IntersectionObserver?: typeof IntersectionObserver } ).IntersectionObserver =
+						originalIntersectionObserver;
+					delete ( window as HooksWindow ).wp;
+				}
+			} );
+
+			it( 'should keep original Embla plugins when the plugins filter returns a non-array value', () => {
+				const mockContext = createMockContext( {
+					autoplay: {
+						delay: 3000,
+						stopOnInteraction: true,
+						stopOnMouseEnter: false,
+					},
+				} );
+				const { wrapper, viewport } = createMockCarouselDOM();
+				const mockEmbla = createMockEmblaInstance();
+				const originalIntersectionObserver = window.IntersectionObserver;
+				const applyFilters = jest.fn( ( hookName, value ) => {
+					if ( hookName === 'rtcamp.carouselKit.emblaPlugins' ) {
+						return 'not-an-array';
+					}
+					return value;
+				} );
+
+				mockVisibleViewport( viewport );
+
+				( window as HooksWindow ).wp = {
+					hooks: {
+						applyFilters,
+					},
+				};
+				( getContext as jest.Mock ).mockReturnValue( mockContext );
+				( getElement as jest.Mock ).mockReturnValue( { ref: wrapper } );
+				( EmblaCarousel as unknown as jest.Mock ).mockReturnValue( mockEmbla );
+				delete ( window as Window & { IntersectionObserver?: typeof IntersectionObserver } ).IntersectionObserver;
+
+				try {
+					storeConfig.callbacks.initCarousel();
+
+					expect( EmblaCarousel ).toHaveBeenCalledWith(
+						viewport,
+						expect.any( Object ),
+						[ expect.objectContaining( { name: 'autoplay' } ) ],
+					);
+				} finally {
+					( window as Window & { IntersectionObserver?: typeof IntersectionObserver } ).IntersectionObserver =
+						originalIntersectionObserver;
+					delete ( window as HooksWindow ).wp;
+				}
+			} );
 		} );
 	} );
 } );

src/blocks/carousel/view.ts

@@ -56,7 +56,8 @@ const applyEmblaFilter = <T>(
 		return value;
 	}
 
-	return applyFilters( hookName, value, filterContext ) as T;
+	const result = applyFilters( hookName, value, filterContext );
+	return result !== null && result !== undefined ? ( result as T ) : value;
 };
 
 const doEmblaAction = (
@@ -339,8 +340,11 @@ store( 'rt-carousel/carousel', {
 						plugins,
 						{ ...filterContext, options: filteredOptions },
 					);
+					const safePlugins = Array.isArray( filteredPlugins )
+						? filteredPlugins
+						: plugins;
 
-					const embla = EmblaCarousel( viewport, filteredOptions, filteredPlugins );
+					const embla = EmblaCarousel( viewport, filteredOptions, safePlugins );
 
 					emblaInstances.set( viewport, embla );
 					viewport[ EMBLA_KEY ] = embla;
@@ -384,7 +388,7 @@ store( 'rt-carousel/carousel', {
 						{
 							...filterContext,
 							options: filteredOptions,
-							plugins: filteredPlugins,
+							plugins: safePlugins,
 						},
 					);