Add navigation buttons to the product carousel

Author: oliverabrahams

dotcom-rendering/src/components/CarouselNavigationButtons.tsx

@@ -105,6 +105,7 @@ export const CarouselNavigationButtons = ({
 				aria-label="previous"
 				value="previous"
 				data-link-name={dataLinkNamePreviousButton}
+				data-testid="carousel-back-button"
 			/>
 
 			<Button
@@ -119,6 +120,7 @@ export const CarouselNavigationButtons = ({
 				aria-label="next"
 				value="next"
 				data-link-name={dataLinkNameNextButton}
+				data-testid="carousel-forward-button"
 			/>
 		</div>,
 		portalNode,

dotcom-rendering/src/components/ScrollableProduct.importable.tsx

@@ -2,11 +2,23 @@ import type { SerializedStyles } from '@emotion/react';
 import { css } from '@emotion/react';
 import type { Breakpoint } from '@guardian/source/foundations';
 import { from, space } from '@guardian/source/foundations';
-import { useRef } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import type { ArticleFormat } from '../lib/articleFormat';
+import { nestedOphanComponents } from '../lib/ophan-helpers';
 import { palette } from '../palette';
 import type { ProductBlockElement } from '../types/content';
+import { CarouselNavigationButtons } from './CarouselNavigationButtons';
 import { ProductCarouselCard } from './ProductCarouselCard';
+import { Subheading } from './Subheading';
+
+const carouselHeader = css`
+	padding-bottom: 10px;
+	padding-top: ${space[6]}px;
+	border-bottom: 1px solid ${palette('--card-border-supporting')};
+	margin-bottom: 10px;
+	display: flex;
+	justify-content: space-between;
+`;
 
 export type FixedSlideWidth = {
 	defaultWidth: number;
@@ -21,6 +33,9 @@ type Props = {
 const baseContainerStyles = css`
 	position: relative;
 `;
+const navigationStyles = css`
+	padding-bottom: ${space[1]}px;
+`;
 
 const subgridStyles = css`
 	scroll-snap-align: start;
@@ -41,7 +56,7 @@ const leftBorderStyles = css`
 		bottom: 0;
 		left: -10px;
 		width: 1px;
-		background-color: ${palette('--card-border-top')};
+		background-color: ${palette('--card-border-supporting')};
 		transform: translateX(-50%);
 	}
 `;
@@ -93,6 +108,9 @@ const generateFixedWidthColumStyles = ({
 
 export const ScrollableProduct = ({ products, format }: Props) => {
 	const carouselRef = useRef<HTMLOListElement | null>(null);
+	const [previousButtonEnabled, setPreviousButtonEnabled] = useState(false);
+	const [nextButtonEnabled, setNextButtonEnabled] = useState(true);
+
 	const carouselLength = products.length;
 	const fixedSlideWidth: FixedSlideWidth = {
 		defaultWidth: 240,
@@ -122,6 +140,44 @@ export const ScrollableProduct = ({ products, format }: Props) => {
 		});
 	};
 
+	/**
+	 * Throttle scroll events to optimise performance. As we're only using this
+	 * to toggle button state as the carousel is scrolled we don't need to
+	 * handle every event. This function ensures the callback is only called
+	 * once every 200ms, no matter how many scroll events are fired.
+	 */
+	const throttleEvent = (callback: () => void) => {
+		let isThrottled: boolean = false;
+		return function () {
+			if (!isThrottled) {
+				callback();
+				isThrottled = true;
+				setTimeout(() => (isThrottled = false), 200);
+			}
+		};
+	};
+
+	/**
+	 * Updates state of navigation buttons based on carousel's scroll position.
+	 *
+	 * This function checks the current scroll position of the carousel and sets
+	 * the styles of the previous and next buttons accordingly. The button state
+	 * is toggled when the midpoint of the first or last card has been scrolled
+	 * in or out of view.
+	 */
+	const updateButtonVisibilityOnScroll = () => {
+		const carouselElement = carouselRef.current;
+		if (!carouselElement) return;
+
+		const scrollLeft = carouselElement.scrollLeft;
+		const maxScrollLeft =
+			carouselElement.scrollWidth - carouselElement.clientWidth;
+		const cardWidth = carouselElement.querySelector('li')?.offsetWidth ?? 0;
+
+		setPreviousButtonEnabled(scrollLeft > cardWidth / 2);
+		setNextButtonEnabled(scrollLeft < maxScrollLeft - cardWidth / 2);
+	};
+
 	/**
 	 * Scrolls the carousel to a certain position when a card gains focus.
 	 *
@@ -176,26 +232,75 @@ export const ScrollableProduct = ({ products, format }: Props) => {
 		}
 	};
 
+	useEffect(() => {
+		const carouselElement = carouselRef.current;
+		if (!carouselElement) return;
+
+		carouselElement.addEventListener(
+			'scroll',
+			throttleEvent(updateButtonVisibilityOnScroll),
+		);
+
+		return () => {
+			carouselElement.removeEventListener(
+				'scroll',
+				throttleEvent(updateButtonVisibilityOnScroll),
+			);
+		};
+	}, []);
+
 	return (
-		<div css={[baseContainerStyles]}>
-			<ol
-				ref={carouselRef}
-				css={carouselStyles}
-				data-heatphan-type="carousel"
-				onFocus={scrollToCardOnFocus}
-			>
-				{products.map((product: ProductBlockElement) => (
-					<li
-						key={product.productCtas[0]?.url ?? product.elementId}
-						css={[subgridStyles, leftBorderStyles]}
-					>
-						<ProductCarouselCard
-							product={product}
-							format={format}
-						/>
-					</li>
-				))}
-			</ol>
-		</div>
+		<>
+			<div css={carouselHeader}>
+				<Subheading
+					format={format}
+					id={'at-a-glance'}
+					topPadding={false}
+				>
+					At a glance
+				</Subheading>
+				<div
+					css={navigationStyles}
+					id={'at-a-glance-carousel-navigation'}
+				></div>
+			</div>
+			<div css={[baseContainerStyles]}>
+				<ol
+					ref={carouselRef}
+					css={carouselStyles}
+					data-heatphan-type="carousel"
+					onFocus={scrollToCardOnFocus}
+				>
+					{products.map((product: ProductBlockElement) => (
+						<li
+							key={
+								product.productCtas[0]?.url ?? product.elementId
+							}
+							css={[subgridStyles, leftBorderStyles]}
+						>
+							<ProductCarouselCard
+								product={product}
+								format={format}
+							/>
+						</li>
+					))}
+				</ol>
+				<CarouselNavigationButtons
+					previousButtonEnabled={previousButtonEnabled}
+					nextButtonEnabled={nextButtonEnabled}
+					onClickPreviousButton={() => scrollTo('left')}
+					onClickNextButton={() => scrollTo('right')}
+					sectionId={'at-a-glance'}
+					dataLinkNamePreviousButton={nestedOphanComponents(
+						'carousel',
+						'previous-button',
+					)}
+					dataLinkNameNextButton={nestedOphanComponents(
+						'carousel',
+						'next-button',
+					)}
+				/>
+			</div>
+		</>
 	);
 };

dotcom-rendering/src/components/ScrollableProducts.stories.tsx

@@ -15,19 +15,39 @@ const meta = {
 				breakpoints.tablet,
 				breakpoints.wide,
 			],
+			// Because this component uses react.createPortal
+			// we delay to give the portals time to hydrate
+			delay: 500,
 		},
 	},
 	args: {
 		products: [
-			{ ...exampleProduct, h2Id: 'product' },
 			{
 				...exampleProduct,
+				primaryHeadingHtml: '<em>Product 0</em>',
+				h2Id: 'product',
+			},
+			{
+				...exampleProduct,
+				primaryHeadingHtml: '<em>Product 1</em>',
 				h2Id: 'product-1',
 				productName: 'Lorem ipsum dolor sit amet',
 			},
-			{ ...exampleProduct, h2Id: 'product-2' },
-			{ ...exampleProduct, h2Id: 'product-3' },
-			{ ...exampleProduct, h2Id: 'product-4' },
+			{
+				...exampleProduct,
+				primaryHeadingHtml: '<em>Product 2</em>',
+				h2Id: 'product-2',
+			},
+			{
+				...exampleProduct,
+				primaryHeadingHtml: '<em>Product 3</em>',
+				h2Id: 'product-3',
+			},
+			{
+				...exampleProduct,
+				primaryHeadingHtml: '<em>Product 4</em>',
+				h2Id: 'product-4',
+			},
 		],
 		format: {
 			design: ArticleDesign.Review,
@@ -78,3 +98,20 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const With5Cards = {} satisfies Story;
+
+export const ClickForwardArrow = {
+	play: async ({ canvas, userEvent }) => {
+		await userEvent.click(canvas.getByTestId('carousel-forward-button'));
+	},
+} satisfies Story;
+
+export const ClickForwardTwiceAndBackOnce = {
+	play: async ({ canvas, userEvent }) => {
+		const user = userEvent.setup({
+			delay: 500, // delay between each interaction
+		});
+		await user.click(canvas.getByTestId('carousel-forward-button'));
+		await user.click(canvas.getByTestId('carousel-forward-button'));
+		await user.click(canvas.getByTestId('carousel-back-button'));
+	},
+} satisfies Story;