feat(carousel): improve Auto Scroll UX and enforce compatible transition settings

src/blocks/carousel/__tests__/edit.test.tsx

@@ -257,6 +257,7 @@ describe( 'Carousel Edit setup flow', () => {
 		expect( selectLabels ).not.toContain( 'Contain Scroll' );
 		expect( toggleLabels ).not.toContain( 'Free Drag' );
 		expect( toggleLabels ).not.toContain( 'Scroll Auto' );
+		expect( toggleLabels ).not.toContain( 'Enable Auto Scroll' );
 		expect( ( RangeControl as unknown as jest.Mock ).mock.calls.some(
 			( [ props ] ) => props.label === 'Slides to Scroll',
 		) ).toBe( false );
@@ -282,6 +283,7 @@ describe( 'Carousel Edit setup flow', () => {
 		expect( selectLabels ).toContain( 'Contain Scroll' );
 		expect( toggleLabels ).toContain( 'Free Drag' );
 		expect( toggleLabels ).toContain( 'Scroll Auto' );
+		expect( toggleLabels ).toContain( 'Enable Auto Scroll' );
 	} );
 
 	it( 'calls setAttributes with the selected transition', () => {
@@ -300,6 +302,6 @@ describe( 'Carousel Edit setup flow', () => {
 
 		transitionCall[ 0 ].onChange( 'fade' );
 
-		expect( setAttributes ).toHaveBeenCalledWith( { transition: 'fade' } );
+		expect( setAttributes ).toHaveBeenCalledWith( { transition: 'fade', autoScroll: false } );
 	} );
 } );

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

@@ -16,6 +16,7 @@ import { store, getContext, getElement } from '@wordpress/interactivity';
 
 import EmblaCarousel, { type EmblaCarouselType } from 'embla-carousel';
 import Fade from 'embla-carousel-fade';
+import AutoScroll from 'embla-carousel-auto-scroll';
 
 // Symbol key used by the view.ts for Embla instances
 const EMBLA_KEY = Symbol.for( 'rt-carousel.carousel' );
@@ -913,6 +914,57 @@ describe( 'Carousel View Module', () => {
 						originalIntersectionObserver;
 				}
 			} );
+
+			it( 'does not include the AutoScroll plugin when transition is fade', () => {
+				const mockContext = createMockContext( {
+					transition: 'fade',
+					autoScroll: {
+						speed: 2,
+						direction: 'forward',
+						startDelay: 1000,
+						stopOnInteraction: true,
+						stopOnMouseEnter: false,
+					},
+				} );
+				const { wrapper, viewport } = createMockCarouselDOM();
+				const originalIntersectionObserver = window.IntersectionObserver;
+
+				viewport.getBoundingClientRect = jest.fn( () => ( {
+					width: 100,
+					height: 0,
+					top: 0,
+					right: 0,
+					bottom: 0,
+					left: 0,
+					x: 0,
+					y: 0,
+					toJSON: () => ( {} ),
+				} ) );
+
+				( getContext as jest.Mock ).mockReturnValue( mockContext );
+				( getElement as jest.Mock ).mockReturnValue( { ref: wrapper } );
+				( EmblaCarousel as unknown as jest.Mock ).mockReturnValue(
+					createMockEmblaInstance( {
+						scrollProgress: jest.fn( () => 0 ),
+						slideNodes: jest.fn( () => [] ),
+					} ),
+				);
+				delete ( window as Window & { IntersectionObserver?: typeof IntersectionObserver } ).IntersectionObserver;
+
+				try {
+					storeConfig.callbacks.initCarousel();
+
+					const lastCall = ( EmblaCarousel as unknown as jest.Mock ).mock.calls.at( -1 );
+					expect( lastCall?.[ 2 ] ).toContainEqual( ( Fade as unknown as jest.Mock ).mock.results.at( -1 )?.value );
+					const autoScrollMockResult = ( AutoScroll as unknown as jest.Mock ).mock.results.at( -1 )?.value;
+					if ( autoScrollMockResult ) {
+						expect( lastCall?.[ 2 ] ).not.toContainEqual( autoScrollMockResult );
+					}
+				} finally {
+					( window as Window & { IntersectionObserver?: typeof IntersectionObserver } ).IntersectionObserver =
+						originalIntersectionObserver;
+				}
+			} );
 		} );
 	} );
 } );

src/blocks/carousel/edit.tsx

@@ -326,9 +326,16 @@ export default function Edit( {
 							{ label: __( 'Slide', 'rt-carousel' ), value: 'slide' },
 							{ label: __( 'Fade', 'rt-carousel' ), value: 'fade' },
 						] }
-						onChange={ ( value ) =>
-							setAttributes( { transition: value as CarouselAttributes[ 'transition' ] } )
-						}
+						onChange={ ( value ) => {
+							const nextTransition = value as CarouselAttributes[ 'transition' ];
+							const nextAttributes: Partial< CarouselAttributes > = {
+								transition: nextTransition,
+							};
+							if ( nextTransition === 'fade' ) {
+								nextAttributes.autoScroll = false;
+							}
+							setAttributes( nextAttributes );
+						} }
 						help={ __(
 							'Choose how slides transition: sliding horizontally or cross-fading.',
 							'rt-carousel',
@@ -496,71 +503,73 @@ export default function Edit( {
 						</>
 					) }
 				</PanelBody>
-				<PanelBody
-					title={ __( 'Auto Scroll', 'rt-carousel' ) }
-					initialOpen={ false }
-				>
-					<ToggleControl
-						label={ __( 'Enable Auto Scroll', 'rt-carousel' ) }
-						checked={ autoScroll }
-						onChange={ ( value ) => setAttributes( {
-							autoScroll: value,
-							autoplay: value ? false : autoplay,
-							loop: ( value && autoScrollDirection === 'backward' ) ? true : loop,
-						} ) }
-					/>
-					{ autoScroll && ( <>
-						<RangeControl
-							label={ __( 'Speed', 'rt-carousel' ) }
-							value={ autoScrollSpeed }
-							onChange={ ( value ) =>
-								setAttributes( { autoScrollSpeed: value ?? 2 } )
-							}
-							min={ 1 }
-							max={ 10 }
-						/>
-						<SelectControl
-							label={ __( 'Direction', 'rt-carousel' ) }
-							value={ autoScrollDirection }
-							options={ [
-								{ label: __( 'Forward', 'rt-carousel' ), value: 'forward' },
-								{ label: __( 'Backward', 'rt-carousel' ), value: 'backward' },
-							] }
-							onChange={ ( value ) =>
-								setAttributes( {
-									autoScrollDirection: value as CarouselAttributes['autoScrollDirection'],
-									loop: value === 'backward' ? true : loop,
-								} )
-							}
-						/>
-						<RangeControl
-							label={ __( 'Start Delay (ms)', 'rt-carousel' ) }
-							value={ autoScrollStartDelay }
-							onChange={ ( value ) =>
-								setAttributes( { autoScrollStartDelay: value ?? 1000 } )
-							}
-							min={ 0 }
-							max={ 10000 }
-							step={ 100 }
-						/>
-						<ToggleControl
-							label={ __( 'Stop on Interaction', 'rt-carousel' ) }
-							checked={ autoScrollStopOnInteraction }
-							onChange={ ( value ) =>
-								setAttributes( { autoScrollStopOnInteraction: value } )
-							}
-							help={ __( 'Stop auto scroll when user interacts with carousel.', 'rt-carousel' ) }
-						/>
+				{ transition !== 'fade' && (
+					<PanelBody
+						title={ __( 'Auto Scroll', 'rt-carousel' ) }
+						initialOpen={ false }
+					>
 						<ToggleControl
-							label={ __( 'Stop on Mouse Enter', 'rt-carousel' ) }
-							checked={ autoScrollStopOnMouseEnter }
-							onChange={ ( value ) =>
-								setAttributes( { autoScrollStopOnMouseEnter: value } )
-							}
-							help={ __( 'Stop auto scroll when mouse hovers over carousel.', 'rt-carousel' ) }
+							label={ __( 'Enable Auto Scroll', 'rt-carousel' ) }
+							checked={ autoScroll }
+							onChange={ ( value ) => setAttributes( {
+								autoScroll: value,
+								autoplay: value ? false : autoplay,
+								loop: ( value && autoScrollDirection === 'backward' ) ? true : loop,
+							} ) }
 						/>
-					</> ) }
-				</PanelBody>
+						{ autoScroll && ( <>
+							<RangeControl
+								label={ __( 'Speed', 'rt-carousel' ) }
+								value={ autoScrollSpeed }
+								onChange={ ( value ) =>
+									setAttributes( { autoScrollSpeed: value ?? 2 } )
+								}
+								min={ 1 }
+								max={ 10 }
+							/>
+							<SelectControl
+								label={ __( 'Direction', 'rt-carousel' ) }
+								value={ autoScrollDirection }
+								options={ [
+									{ label: __( 'Forward', 'rt-carousel' ), value: 'forward' },
+									{ label: __( 'Backward', 'rt-carousel' ), value: 'backward' },
+								] }
+								onChange={ ( value ) =>
+									setAttributes( {
+										autoScrollDirection: value as CarouselAttributes['autoScrollDirection'],
+										loop: value === 'backward' ? true : loop,
+									} )
+								}
+							/>
+							<RangeControl
+								label={ __( 'Start Delay (ms)', 'rt-carousel' ) }
+								value={ autoScrollStartDelay }
+								onChange={ ( value ) =>
+									setAttributes( { autoScrollStartDelay: value ?? 1000 } )
+								}
+								min={ 0 }
+								max={ 10000 }
+								step={ 100 }
+							/>
+							<ToggleControl
+								label={ __( 'Stop on Interaction', 'rt-carousel' ) }
+								checked={ autoScrollStopOnInteraction }
+								onChange={ ( value ) =>
+									setAttributes( { autoScrollStopOnInteraction: value } )
+								}
+								help={ __( 'Stop auto scroll when user interacts with carousel.', 'rt-carousel' ) }
+							/>
+							<ToggleControl
+								label={ __( 'Stop on Mouse Enter', 'rt-carousel' ) }
+								checked={ autoScrollStopOnMouseEnter }
+								onChange={ ( value ) =>
+									setAttributes( { autoScrollStopOnMouseEnter: value } )
+								}
+								help={ __( 'Stop auto scroll when mouse hovers over carousel.', 'rt-carousel' ) }
+							/>
+						</> ) }
+					</PanelBody>
+				) }
 			</InspectorControls>
 			<InspectorAdvancedControls>
 				<TextControl

src/blocks/carousel/save.tsx

@@ -72,7 +72,7 @@ export default function Save( {
 			'Slide {{currentSlide}} of {{totalSlides}}',
 			'rt-carousel',
 		),
-		autoScroll: autoScroll ? {
+		autoScroll: ( transition !== 'fade' && autoScroll ) ? {
 			speed: autoScrollSpeed,
 			direction: autoScrollDirection,
 			startDelay: autoScrollStartDelay,

src/blocks/carousel/view.ts

@@ -320,7 +320,7 @@ store( 'rt-carousel/carousel', {
 						plugins.push( Autoplay( context.autoplay as AutoplayOptionsType ) );
 					}
 
-					if ( context.autoScroll ) {
+					if ( context.autoScroll && context.transition !== 'fade' ) {
 						plugins.push( AutoScroll( context.autoScroll as AutoScrollOptionsType ) );
 					}
 

tests/js/setup.ts

@@ -61,6 +61,22 @@ jest.mock( 'embla-carousel-fade', () => ( {
 	} ) ),
 } ) );
 
+/**
+ * Mock embla-carousel-auto-scroll module.
+ */
+jest.mock( 'embla-carousel-auto-scroll', () => ( {
+	__esModule: true,
+	default: jest.fn( () => ( {
+		name: 'autoScroll',
+		options: {},
+		init: jest.fn(),
+		destroy: jest.fn(),
+		play: jest.fn(),
+		stop: jest.fn(),
+		isPlaying: jest.fn( () => false ),
+	} ) ),
+} ) );
+
 /**
  * Mock WordPress block editor components.
  */