Add a11y announcements for carousel slide changes (#125)

* Add screen reader slide announcements for carousel navigation

* Prevent stale carousel slide announcements

Author: deepakpra

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

@@ -336,7 +336,9 @@ describe( 'Carousel View Module', () => {
 
 				setEmblaOnViewport( viewport, mockEmbla );
 
-				const mockContext = createMockContext();
+				const mockContext = createMockContext( {
+					selectedIndex: 1,
+				} );
 				( mockContext as CarouselContext & { snap?: { index: number } } ).snap = {
 					index: 0,
 				};
@@ -694,6 +696,67 @@ describe( 'Carousel View Module', () => {
 
 				consoleErrorSpy.mockRestore();
 			} );
+
+			it( 'should update announcement after a manual slide change', () => {
+				const mockContext = createMockContext( {
+					announcementPattern: 'Slide {{currentSlide}} of {{totalSlides}}',
+					selectedIndex: -1,
+				} );
+				const { wrapper, viewport } = createMockCarouselDOM();
+				const listeners: {
+					select?: () => void;
+				} = {};
+				const selectedScrollSnap = jest
+					.fn()
+					.mockReturnValueOnce( 0 )
+					.mockReturnValueOnce( 1 );
+				const mockEmbla = createMockEmblaInstance( {
+					selectedScrollSnap,
+					scrollSnapList: jest.fn( () => [ 0, 1, 2, 3, 4 ] ),
+					slideNodes: jest.fn( () =>
+						Array.from( { length: 5 }, () => document.createElement( 'div' ) ),
+					),
+					scrollProgress: jest.fn( () => 0.25 ),
+				} );
+				const originalIntersectionObserver = window.IntersectionObserver;
+
+				mockEmbla.on = jest.fn( ( eventName: string, callback: () => void ) => {
+					if ( eventName === 'select' ) {
+						listeners.select = callback;
+					}
+					return mockEmbla;
+				} );
+
+				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( mockEmbla );
+				delete ( window as Window & { IntersectionObserver?: typeof IntersectionObserver } ).IntersectionObserver;
+
+				try {
+					storeConfig.callbacks.initCarousel();
+
+					mockContext.shouldAnnounce = true;
+					listeners.select?.();
+
+					expect( mockContext.announcement ).toBe( 'Slide 2 of 5' );
+					expect( mockContext.shouldAnnounce ).toBe( false );
+				} finally {
+					( window as Window & { IntersectionObserver?: typeof IntersectionObserver } ).IntersectionObserver =
+						originalIntersectionObserver;
+				}
+			} );
 		} );
 	} );
 } );

src/blocks/carousel/save.tsx

@@ -52,6 +52,13 @@ export default function Save( {
 		slideCount: 0,
 		/* translators: %d: slide number */
 		ariaLabelPattern: __( 'Go to slide %d', 'rt-carousel' ),
+		announcement: '',
+		shouldAnnounce: false,
+		/* translators: {{currentSlide}}: current slide number, {{totalSlides}}: total slide count. */
+		announcementPattern: __(
+			'Slide {{currentSlide}} of {{totalSlides}}',
+			'rt-carousel',
+		),
 	};
 
 	const blockProps = useBlockProps.save( {
@@ -71,7 +78,26 @@ export default function Save( {
 		} as React.CSSProperties,
 	} );
 
-	const innerBlocksProps = useInnerBlocksProps.save( blockProps );
+	const innerBlocksProps = useInnerBlocksProps.save( blockProps ) as ReturnType<
+		typeof useInnerBlocksProps.save
+	> & {
+		children: React.ReactNode;
+	};
+	const { children, ...wrapperProps } = innerBlocksProps;
+	const announcementLiveRegion = (
+		<span
+			className="screen-reader-text"
+			role="status"
+			aria-live="polite"
+			aria-atomic="true"
+			data-wp-text="context.announcement"
+		/>
+	);
 
-	return <div { ...innerBlocksProps } />;
+	return (
+		<div { ...wrapperProps }>
+			{ children }
+			{ announcementLiveRegion }
+		</div>
+	);
 }

src/blocks/carousel/types.ts

@@ -57,6 +57,9 @@ export type CarouselContext = {
 	canScrollNext: boolean;
 	scrollProgress: number;
 	ariaLabelPattern: string;
+	announcement?: string;
+	announcementPattern?: string;
+	shouldAnnounce?: boolean;
 	ref?: HTMLElement | null;
 	slideCount: number;
 	initialized?: boolean;

src/blocks/carousel/view.ts

@@ -56,6 +56,42 @@ const getProgress = (): number => {
 	return Math.max( 0, Math.min( 1, scrollProgress || 0 ) );
 };
 
+const getSlideAnnouncement = (
+	context: CarouselContext,
+	selectedIndex: number,
+	slideCount: number,
+): string => {
+	if ( ! slideCount || slideCount <= 1 || ! context.announcementPattern ) {
+		return '';
+	}
+	return context.announcementPattern
+		.replace( '{{currentSlide}}', ( selectedIndex + 1 ).toString() )
+		.replace( '{{totalSlides}}', slideCount.toString() );
+};
+
+const updateSlideAnnouncement = (
+	context: CarouselContext,
+	previousSelectedIndex: number,
+): void => {
+	if ( ! context.shouldAnnounce ) {
+		return;
+	}
+
+	if ( context.selectedIndex !== previousSelectedIndex ) {
+		context.announcement = getSlideAnnouncement(
+			context,
+			context.selectedIndex,
+			context.slideCount,
+		);
+	}
+
+	context.shouldAnnounce = false;
+};
+
+const markForAnnouncement = (): void => {
+	getContext<CarouselContext>().shouldAnnounce = true;
+};
+
 store( 'rt-carousel/carousel', {
 	state: {
 		get canScrollPrev() {
@@ -72,6 +108,9 @@ store( 'rt-carousel/carousel', {
 			const element = getElementRef( getElement() );
 			const embla = getEmblaFromElement( element );
 			if ( embla ) {
+				if ( embla.canScrollPrev() ) {
+					markForAnnouncement();
+				}
 				embla.scrollPrev();
 			} else {
 				// eslint-disable-next-line no-console
@@ -82,6 +121,9 @@ store( 'rt-carousel/carousel', {
 			const element = getElementRef( getElement() );
 			const embla = getEmblaFromElement( element );
 			if ( embla ) {
+				if ( embla.canScrollNext() ) {
+					markForAnnouncement();
+				}
 				embla.scrollNext();
 			} else {
 				// eslint-disable-next-line no-console
@@ -98,6 +140,9 @@ store( 'rt-carousel/carousel', {
 				const element = getElementRef( getElement() );
 				const embla = getEmblaFromElement( element );
 				if ( embla ) {
+					if ( snap.index !== context.selectedIndex ) {
+						markForAnnouncement();
+					}
 					embla.scrollTo( snap.index );
 				}
 			}
@@ -237,6 +282,7 @@ store( 'rt-carousel/carousel', {
 					viewport[ EMBLA_KEY ] = embla;
 
 					const updateState = () => {
+						const previousSelectedIndex = context.selectedIndex;
 						const scrollSnapList = embla.scrollSnapList();
 						context.initialized = true;
 						context.canScrollPrev = embla.canScrollPrev();
@@ -249,6 +295,7 @@ store( 'rt-carousel/carousel', {
 						}
 						context.scrollProgress = embla.scrollProgress();
 						context.slideCount = embla.slideNodes().length;
+						updateSlideAnnouncement( context, previousSelectedIndex );
 					};
 
 					embla.on( 'select', updateState );