Personalise highlights (#14834)

* Add visibility hidden to the highlights container

* Hide highlights and unhide them if a user doesnt have a highlights history

* inline css for now

* Add logs for testing

* Store article ID in history on click

* Articles moving but container is at the end

* Update local storage key

* Auto scroll back to start on layout event

* Check if contain the same urls before continuing

* Update naming

* UseEffect instead of LayoutEffect

* Improve naming

* Track views on cards and demote unengaged cards

* Fix return type

* Introduce `personalHighlights` module to manage highlight card ordering based on user engagement

* Add helper to get ordered cards from stored history

* Add helper methods to track clicks and views in order history

* Add functions to demote cards and  to track and store final card engagement

* Update view tracker to store the first two cards viewed

* Simplify api and add logging for testing

* Logging and use visbility state instead of beforeUnload as it is better supported

* Track views on show rather than on leave so that it doesn't interfeer with click tracking

* Track views straight away

* working

* Refactor naming and add comments

* Make trackCardClick optional so we only provide it on highlights

* Add test suite for personalisedHighlights

* Tidy up

* Add AB Test set boiler plate which will be used in conjunction with guardian/frontend#28327

# Conflicts:
#	dotcom-rendering/src/experiments/ab-tests.ts

* Add client side test mechanism into scrollable highlights

* Prefer /* */ comments over // for VSCode integration

* Prefer event handler style naming convention in personaliseHighlights so that it does semantically overlap with telemetry

* Set ordered trails so that visibility is set only once in the useLayoutEffect

* Update comments to improve readability

* Fix linting

* Fire a view event only if the container has been personalised

* Lower max view count to 2 view as requested by editorial

* Simplify flash solution by only applying scroll-snap styles once the highlights are visible.

* Store a card identifier rather than the whole card to ensure editorial card updates are visible to users with stored history. (#14835)

* Refactor test setup in Highlights test (#14836)

* Store a card identifier rather than the whole card to ensure editorial card updates are visible to users with stored history.

* Refactor ab test attribution so that we can apply personalisation behaviour only if a user is in a test variant

* Move visibility setting inside useeffect

* Remove control from the list of potential ab variants as this is covered by  'not-in-test'

* Prefer undefined rather than 'undetermined' as this is representative of what is returned from SWR under the hood of the useAB hook

* Set visibility when the user is not in the test

Author: abeddow91

dotcom-rendering/src/components/Card/components/CardLink.tsx

@@ -21,16 +21,19 @@ type Props = {
 	headlineText: string;
 	dataLinkName?: string;
 	isExternalLink: boolean;
+	trackCardClick?: () => void;
 };
 
 const InternalLink = ({
 	linkTo,
 	headlineText,
 	dataLinkName,
+	trackCardClick,
 }: {
 	linkTo: string;
 	headlineText: string;
 	dataLinkName?: string;
+	trackCardClick?: () => void;
 }) => {
 	return (
 		// eslint-disable-next-line jsx-a11y/anchor-has-content -- we have an aria-label attribute describing the content
@@ -39,6 +42,7 @@ const InternalLink = ({
 			css={fauxLinkStyles}
 			data-link-name={dataLinkName}
 			aria-label={headlineText}
+			onClick={trackCardClick}
 		/>
 	);
 };
@@ -47,10 +51,12 @@ const ExternalLink = ({
 	linkTo,
 	headlineText,
 	dataLinkName,
+	trackCardClick,
 }: {
 	linkTo: string;
 	headlineText: string;
 	dataLinkName?: string;
+	trackCardClick?: () => void;
 }) => {
 	return (
 		// eslint-disable-next-line jsx-a11y/anchor-has-content -- we have an aria-label attribute describing the content
@@ -61,6 +67,7 @@ const ExternalLink = ({
 			aria-label={headlineText + ' (opens in new tab)'}
 			target="_blank"
 			rel="noreferrer"
+			onClick={trackCardClick}
 		/>
 	);
 };
@@ -70,6 +77,7 @@ export const CardLink = ({
 	headlineText,
 	dataLinkName = 'article', //this makes sense if the link is to an article, but should this say something like "external" if it's an external link? are there any other uses/alternatives?
 	isExternalLink,
+	trackCardClick,
 }: Props) => {
 	return (
 		<>
@@ -78,13 +86,15 @@ export const CardLink = ({
 					linkTo={linkTo}
 					headlineText={headlineText}
 					dataLinkName={dataLinkName}
+					trackCardClick={trackCardClick}
 				/>
 			)}
 			{!isExternalLink && (
 				<InternalLink
 					linkTo={linkTo}
 					headlineText={headlineText}
 					dataLinkName={dataLinkName}
+					trackCardClick={trackCardClick}
 				/>
 			)}
 		</>

dotcom-rendering/src/components/DecideContainer.tsx

@@ -233,7 +233,7 @@ export const DecideContainer = ({
 			return <NavList trails={trails} showImage={true} />;
 		case 'scrollable/highlights':
 			return (
-				<Island priority="feature" defer={{ until: 'visible' }}>
+				<Island priority="critical">
 					<ScrollableHighlights trails={trails} frontId={frontId} />
 				</Island>
 			);

dotcom-rendering/src/components/Masthead/HighlightsCard.tsx

@@ -32,6 +32,7 @@ export type HighlightsCardProps = {
 	byline?: string;
 	isExternalLink: boolean;
 	starRating?: Rating;
+	trackCardClick: () => void;
 };
 
 const container = css`
@@ -133,6 +134,7 @@ export const HighlightsCard = ({
 	byline,
 	isExternalLink,
 	starRating,
+	trackCardClick,
 }: HighlightsCardProps) => {
 	const isMediaCard = isMedia(format);
 
@@ -144,6 +146,7 @@ export const HighlightsCard = ({
 					headlineText={headlineText}
 					dataLinkName={dataLinkName}
 					isExternalLink={isExternalLink}
+					trackCardClick={trackCardClick}
 				/>
 
 				<div css={content}>

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

@@ -1,4 +1,5 @@
 import { css } from '@emotion/react';
+import type { ABTestAPI as ABTestAPIType } from '@guardian/ab-core';
 import { from, space } from '@guardian/source/foundations';
 import {
 	Button,
@@ -7,8 +8,16 @@ import {
 	SvgChevronRightSingle,
 } from '@guardian/source/react-components';
 import { useEffect, useRef, useState } from 'react';
+import { submitComponentEvent } from '../client/ophan/ophan';
 import { getZIndex } from '../lib/getZIndex';
 import { ophanComponentId } from '../lib/ophan-helpers';
+import {
+	clearHighlightsState,
+	getOrderedHighlights,
+	onHighlightEvent,
+	resetHighlightsState,
+} from '../lib/personaliseHighlights';
+import { useAB } from '../lib/useAB';
 import { palette } from '../palette';
 import type { DCRFrontCard } from '../types/front';
 import { HighlightsCard } from './Masthead/HighlightsCard';
@@ -41,8 +50,7 @@ const carouselStyles = css`
 	grid-auto-flow: column;
 	overflow-x: auto;
 	overflow-y: hidden;
-	scroll-snap-type: x mandatory;
-	scroll-behavior: smooth;
+	scroll-behavior: auto;
 	overscroll-behavior-x: contain;
 	overscroll-behavior-y: auto;
 
@@ -78,6 +86,10 @@ const carouselStyles = css`
 	position: relative;
 `;
 
+const scrollSnapStyles = css`
+	scroll-snap-type: x mandatory;
+`;
+
 const itemStyles = css`
 	scroll-snap-align: start;
 	grid-area: span 1;
@@ -207,12 +219,55 @@ const getOphanInfo = (frontId?: string) => {
 	};
 };
 
+const isEqual = (
+	historicalHighlights: DCRFrontCard[],
+	currentHighlights: DCRFrontCard[],
+) => {
+	const c = currentHighlights.map((v) => v.url);
+	const h = historicalHighlights.map((v) => v.url);
+	return c.every((v) => {
+		return h.includes(v);
+	});
+};
 export const ScrollableHighlights = ({ trails, frontId }: Props) => {
 	const carouselRef = useRef<HTMLOListElement | null>(null);
 	const carouselLength = trails.length;
 	const imageLoading = 'eager';
 	const [showPreviousButton, setShowPreviousButton] = useState(false);
 	const [showNextButton, setShowNextButton] = useState(true);
+	const [shouldShowHighlights, setShouldShowHighlights] = useState(false);
+	const [orderedTrails, setOrderedTrails] = useState<DCRFrontCard[]>(trails);
+
+	const ABTestAPI = useAB()?.api;
+
+	type Attr =
+		| 'click-tracking'
+		| 'view-tracking'
+		| 'click-and-view-tracking'
+		| 'not-in-test'
+		| undefined;
+
+	const getUserABAttr = (api?: ABTestAPIType): Attr => {
+		if (!api) return undefined;
+
+		if (api.isUserInVariant('PersonalisedHighlights', 'click-tracking')) {
+			return 'click-tracking';
+		}
+		if (api.isUserInVariant('PersonalisedHighlights', 'view-tracking')) {
+			return 'view-tracking';
+		}
+		if (
+			api.isUserInVariant(
+				'PersonalisedHighlights',
+				'click-and-view-tracking',
+			)
+		) {
+			return 'click-and-view-tracking';
+		}
+		return 'not-in-test';
+	};
+
+	const abTestPersonalisedHighlightAttr = getUserABAttr(ABTestAPI);
 
 	const scrollTo = (direction: 'left' | 'right') => {
 		if (!carouselRef.current) return;
@@ -247,6 +302,15 @@ export const ScrollableHighlights = ({ trails, frontId }: Props) => {
 		setShowNextButton(scrollLeft < maxScrollLeft);
 	};
 
+	useEffect(() => {
+		if (
+			abTestPersonalisedHighlightAttr === 'view-tracking' ||
+			abTestPersonalisedHighlightAttr === 'click-and-view-tracking'
+		) {
+			onHighlightEvent('VIEW');
+		}
+	}, [abTestPersonalisedHighlightAttr]);
+
 	useEffect(() => {
 		const carouselElement = carouselRef.current;
 		if (!carouselElement) return;
@@ -264,11 +328,57 @@ export const ScrollableHighlights = ({ trails, frontId }: Props) => {
 		};
 	}, []);
 
+	useEffect(() => {
+		if (abTestPersonalisedHighlightAttr === undefined) {
+			return;
+		}
+
+		if (abTestPersonalisedHighlightAttr === 'not-in-test') {
+			clearHighlightsState();
+			setOrderedTrails(trails);
+			setShouldShowHighlights(true);
+			return;
+		}
+
+		const personalisedHighlights = getOrderedHighlights(trails);
+		if (
+			personalisedHighlights.length === 0 ||
+			personalisedHighlights.length !== trails.length ||
+			!isEqual(personalisedHighlights, trails)
+		) {
+			/* Reset to editorial order */
+			resetHighlightsState(trails);
+			setOrderedTrails(trails);
+			setShouldShowHighlights(true);
+			return;
+		}
+		/* Otherwise, use personalised order from local storage */
+		setOrderedTrails(personalisedHighlights);
+		setShouldShowHighlights(true);
+		/* Fire a view event only if the container has been personalised */
+		void submitComponentEvent(
+			{
+				component: {
+					componentType: 'CONTAINER',
+					id: `reordered-highlights-container`,
+				},
+				action: 'VIEW',
+			},
+			'Web',
+		);
+	}, [trails, abTestPersonalisedHighlightAttr]);
+
 	const { ophanComponentLink, ophanComponentName, ophanFrontName } =
 		getOphanInfo(frontId);
 
 	return (
-		<div css={containerStyles} data-link-name={ophanFrontName}>
+		<div
+			css={[
+				containerStyles,
+				{ visibility: shouldShowHighlights ? 'visible' : 'hidden' },
+			]}
+			data-link-name={ophanFrontName}
+		>
 			<ol
 				data-link-name={ophanComponentLink}
 				data-component={ophanComponentName}
@@ -277,10 +387,16 @@ export const ScrollableHighlights = ({ trails, frontId }: Props) => {
 				css={[
 					carouselStyles,
 					generateCarouselColumnStyles(carouselLength),
+					/*
+					 * Enable scroll-snap only when visible to prevent browser scroll anchoring.
+					 * When items reorder, browsers try to keep previously visible items in view,
+					 * causing unwanted scrolling. Enabling snap after reordering forces position 0.
+					 // */
+					shouldShowHighlights && scrollSnapStyles,
 				]}
 				data-heatphan-type="carousel"
 			>
-				{trails.map((trail) => {
+				{orderedTrails.map((trail) => {
 					return (
 						<li
 							key={trail.url}
@@ -300,6 +416,16 @@ export const ScrollableHighlights = ({ trails, frontId }: Props) => {
 								showQuotedHeadline={trail.showQuotedHeadline}
 								mainMedia={trail.mainMedia}
 								starRating={trail.starRating}
+								trackCardClick={() => {
+									if (
+										abTestPersonalisedHighlightAttr ===
+											'click-tracking' ||
+										abTestPersonalisedHighlightAttr ===
+											'click-and-view-tracking'
+									) {
+										onHighlightEvent('CLICK', trail);
+									}
+								}}
 							/>
 						</li>
 					);

dotcom-rendering/src/experiments/ab-tests.ts

@@ -2,6 +2,7 @@ import type { ABTest } from '@guardian/ab-core';
 import { abTestTest } from './tests/ab-test-test';
 import { auxiaSignInGate } from './tests/auxia-sign-in-gate';
 import { noAuxiaSignInGate } from './tests/no-auxia-sign-in-gate';
+import { personalisedHighlights } from './tests/personalised-highlights';
 import { signInGateMainControl } from './tests/sign-in-gate-main-control';
 import { signInGateMainVariant } from './tests/sign-in-gate-main-variant';
 import { userBenefitsApi } from './tests/user-benefits-api';
@@ -14,5 +15,6 @@ export const tests: ABTest[] = [
 	signInGateMainControl,
 	userBenefitsApi,
 	auxiaSignInGate,
+	personalisedHighlights,
 	noAuxiaSignInGate,
 ];

dotcom-rendering/src/experiments/tests/personalised-highlights.ts

@@ -0,0 +1,43 @@
+import type { ABTest } from '@guardian/ab-core';
+
+export const personalisedHighlights: ABTest = {
+	id: 'PersonalisedHighlights',
+	start: '2025-10-29',
+	expiry: '2025-12-04',
+	author: 'Anna Beddow',
+	description:
+		'Allow user behaviour to personalise the ordering of cards in the highlights container.',
+	audience: 0,
+	audienceOffset: 0,
+	successMeasure: '',
+	audienceCriteria: '',
+	idealOutcome: '',
+	showForSensitive: true,
+	canRun: () => true,
+	variants: [
+		{
+			id: 'control',
+			test: (): void => {
+				/* no-op */
+			},
+		},
+		{
+			id: 'click-tracking',
+			test: (): void => {
+				/* no-op */
+			},
+		},
+		{
+			id: 'view-tracking',
+			test: (): void => {
+				/* no-op */
+			},
+		},
+		{
+			id: 'click-and-view-tracking',
+			test: (): void => {
+				/* no-op */
+			},
+		},
+	],
+};