Allow cinemagraph option for looping video

domlander · domlander · commit 98989b6fae9a · 2025-11-13T09:46:38.000Z
diff --git a/dotcom-rendering/src/components/Card/Card.tsx b/dotcom-rendering/src/components/Card/Card.tsx
@@ -896,6 +896,10 @@ export const Card = ({
 					<MediaWrapper
 						mediaSize={mediaSize}
 						mediaType={media.type}
+						isCinemagraph={
+							media.mainMedia?.type === 'SelfHostedVideo' &&
+							media.mainMedia.videoStyle === 'Cinemagraph'
+						}
 						mediaPositionOnDesktop={mediaPositionOnDesktop}
 						mediaPositionOnMobile={mediaPositionOnMobile}
 						hideMediaOverlay={media.type === 'slideshow'}
@@ -952,6 +956,12 @@ export const Card = ({
 									uniqueId={uniqueId}
 									height={media.mainMedia.height}
 									width={media.mainMedia.width}
+									isCinemagraph={
+										media.mainMedia?.type ===
+											'SelfHostedVideo' &&
+										media.mainMedia.videoStyle ===
+											'Cinemagraph'
+									}
 									posterImage={media.mainMedia.image ?? ''}
 									fallbackImage={media.mainMedia.image ?? ''}
 									fallbackImageSize={mediaSize}
diff --git a/dotcom-rendering/src/components/Card/components/MediaWrapper.tsx b/dotcom-rendering/src/components/Card/components/MediaWrapper.tsx
@@ -1,6 +1,7 @@
 import type { SerializedStyles } from '@emotion/react';
 import { css } from '@emotion/react';
 import { between, from, space, until } from '@guardian/source/foundations';
+import { getZIndex } from '../../../lib/getZIndex';
 import type { CardMediaType } from '../../../types/layout';
 
 const mediaFixedSize = {
@@ -29,6 +30,7 @@ type Props = {
 	children: React.ReactNode;
 	mediaSize: MediaSizeType;
 	mediaType?: CardMediaType;
+	isCinemagraph?: boolean;
 	mediaPositionOnDesktop: MediaPositionType;
 	mediaPositionOnMobile: MediaPositionType;
 	/**
@@ -48,6 +50,9 @@ const mediaOverlayContainerStyles = css`
 	left: 0;
 	width: 100%;
 	height: 100%;
+	z-index: ${getZIndex('mediaOverlay')};
+	cursor: pointer;
+	pointer-events: none;
 `;
 
 /**
@@ -201,6 +206,7 @@ export const MediaWrapper = ({
 	children,
 	mediaSize,
 	mediaType,
+	isCinemagraph,
 	mediaPositionOnDesktop,
 	mediaPositionOnMobile,
 	hideMediaOverlay,
@@ -267,8 +273,10 @@ export const MediaWrapper = ({
 		>
 			<>
 				{children}
-				{/* This image overlay is styled when the CardLink is hovered */}
-				{(mediaType === 'picture' || mediaType === 'slideshow') &&
+				{/* This overlay is styled when the CardLink is hovered */}
+				{(mediaType === 'picture' ||
+					mediaType === 'slideshow' ||
+					(mediaType === 'loop-video' && isCinemagraph)) &&
 					!hideMediaOverlay && (
 						<div
 							css={[
diff --git a/dotcom-rendering/src/components/LoopVideo.importable.tsx b/dotcom-rendering/src/components/LoopVideo.importable.tsx
@@ -33,6 +33,10 @@ const videoContainerStyles = css`
 	position: relative;
 `;
 
+const cinemagraphContainerStyles = css`
+	pointer-events: none;
+`;
+
 /**
  * Dispatches a custom play audio event so that other videos listening
  * for this event will be muted.
@@ -116,6 +120,11 @@ type Props = {
 	uniqueId: string;
 	height: number;
 	width: number;
+	/**
+	 * All controls on the video are hidden: the video looks like a GIF.
+	 * This includes but may not be limited to: audio icon, play/pause icon, subtitles, progress bar.
+	 */
+	isCinemagraph: boolean;
 	posterImage: string;
 	fallbackImage: CardPictureProps['mainImage'];
 	fallbackImageSize: CardPictureProps['imageSize'];
@@ -133,6 +142,7 @@ export const LoopVideo = ({
 	uniqueId,
 	height,
 	width,
+	isCinemagraph,
 	posterImage,
 	fallbackImage,
 	fallbackImageSize,
@@ -642,8 +652,13 @@ export const LoopVideo = ({
 	return (
 		<figure
 			ref={setNode}
-			css={videoContainerStyles}
-			className="loop-video-container"
+			css={[
+				videoContainerStyles,
+				isCinemagraph && cinemagraphContainerStyles,
+			]}
+			className={`loop-video-container ${
+				isCinemagraph ? 'cinemagraph' : ''
+			}`}
 			data-component="gu-video-loop"
 		>
 			<LoopVideoPlayer
@@ -663,17 +678,20 @@ export const LoopVideo = ({
 				handleLoadedMetadata={handleLoadedMetadata}
 				handleLoadedData={handleLoadedData}
 				handleCanPlay={handleCanPlay}
-				handlePlayPauseClick={handlePlayPauseClick}
-				handleAudioClick={handleAudioClick}
-				handleKeyDown={handleKeyDown}
-				handlePause={handlePause}
+				handlePlayPauseClick={
+					!isCinemagraph ? handlePlayPauseClick : undefined
+				}
+				handleAudioClick={!isCinemagraph ? handleAudioClick : undefined}
+				handleKeyDown={!isCinemagraph ? handleKeyDown : undefined}
+				handlePause={!isCinemagraph ? handlePause : undefined}
 				onError={onError}
-				AudioIcon={hasAudio ? AudioIcon : null}
+				AudioIcon={hasAudio && !isCinemagraph ? AudioIcon : null}
 				preloadPartialData={preloadPartialData}
-				showPlayIcon={showPlayIcon}
-				subtitleSource={subtitleSource}
-				subtitleSize={subtitleSize}
+				showPlayIcon={!isCinemagraph ? showPlayIcon : false}
+				subtitleSize={!isCinemagraph ? subtitleSize : undefined}
+				subtitleSource={!isCinemagraph ? subtitleSource : undefined}
 				activeCue={activeCue}
+				isCinemagraph={isCinemagraph}
 			/>
 		</figure>
 	);
diff --git a/dotcom-rendering/src/components/LoopVideo.stories.tsx b/dotcom-rendering/src/components/LoopVideo.stories.tsx
@@ -71,6 +71,14 @@ export const Without5to4Ratio: Story = {
 	},
 };
 
+export const WithCinemagraph: Story = {
+	name: 'With cinemagraph',
+	args: {
+		...Default.args,
+		isCinemagraph: true,
+	},
+};
+
 export const PausePlay: Story = {
 	...Default,
 	name: 'Pause and play interaction',
diff --git a/dotcom-rendering/src/components/LoopVideoPlayer.tsx b/dotcom-rendering/src/components/LoopVideoPlayer.tsx
@@ -22,11 +22,7 @@ import { SubtitleOverlay } from './SubtitleOverlay';
 
 export type SubtitleSize = 'small' | 'medium' | 'large';
 
-const videoStyles = (
-	width: number,
-	height: number,
-	subtitleSize: SubtitleSize,
-) => css`
+const videoStyles = (width: number, height: number) => css`
 	position: relative;
 	display: block;
 	height: auto;
@@ -35,7 +31,9 @@ const videoStyles = (
 	/* Prevents CLS by letting the browser know the space the video will take up. */
 	aspect-ratio: ${width} / ${height};
 	object-fit: cover;
+`;
 
+const subtitleStyles = (subtitleSize: SubtitleSize | undefined) => css`
 	::cue {
 		/* Hide the cue by default as we prefer custom overlay */
 		visibility: hidden;
@@ -112,19 +110,21 @@ type Props = {
 	handleLoadedMetadata: (event: SyntheticEvent) => void;
 	handleLoadedData: (event: SyntheticEvent) => void;
 	handleCanPlay: (event: SyntheticEvent) => void;
-	handlePlayPauseClick: (event: SyntheticEvent) => void;
-	handleAudioClick: (event: SyntheticEvent) => void;
-	handleKeyDown: (event: React.KeyboardEvent<HTMLVideoElement>) => void;
-	handlePause: (event: SyntheticEvent) => void;
+	handlePlayPauseClick?: (event: SyntheticEvent) => void;
+	handleAudioClick?: (event: SyntheticEvent) => void;
+	handleKeyDown?: (event: React.KeyboardEvent<HTMLVideoElement>) => void;
+	handlePause?: (event: SyntheticEvent) => void;
 	onError: (event: SyntheticEvent<HTMLVideoElement>) => void;
 	AudioIcon: ((iconProps: IconProps) => JSX.Element) | null;
 	posterImage?: string;
 	preloadPartialData: boolean;
 	showPlayIcon: boolean;
 	subtitleSource?: string;
-	subtitleSize: SubtitleSize;
+	subtitleSize?: SubtitleSize;
 	/* used in custom subtitle overlays */
 	activeCue?: ActiveCue | null;
+	/* Cinemagraphs do not display subtitles or video controls */
+	isCinemagraph: boolean;
 };
 
 /**
@@ -165,16 +165,26 @@ export const LoopVideoPlayer = forwardRef(
 			subtitleSource,
 			subtitleSize,
 			activeCue,
+			isCinemagraph,
 		}: Props,
 		ref: React.ForwardedRef<HTMLVideoElement>,
 	) => {
 		const loopVideoId = `loop-video-${uniqueId}`;
+		const showSubtitles =
+			!!subtitleSource &&
+			!!subtitleSize &&
+			!!activeCue?.text &&
+			!isCinemagraph;
+
 		return (
 			<>
 				{/* eslint-disable-next-line jsx-a11y/media-has-caption -- Captions will be considered later. */}
 				<video
 					id={loopVideoId}
-					css={videoStyles(width, height, subtitleSize)}
+					css={[
+						videoStyles(width, height),
+						showSubtitles && subtitleStyles(subtitleSize),
+					]}
 					crossOrigin="anonymous"
 					ref={ref}
 					tabIndex={0}
@@ -228,61 +238,65 @@ export const LoopVideoPlayer = forwardRef(
 					)}
 					{FallbackImageComponent}
 				</video>
-				{!!activeCue?.text && (
+				{showSubtitles && (
 					<SubtitleOverlay
 						text={activeCue.text}
 						subtitleSize={subtitleSize}
 					/>
 				)}
-				{ref && 'current' in ref && ref.current && isPlayable && (
-					<>
-						{/* Play icon */}
-						{showPlayIcon && (
-							<button
-								type="button"
-								onClick={handlePlayPauseClick}
-								css={playIconStyles}
-								data-link-name={`gu-video-loop-play-${atomId}`}
-								data-testid="play-icon"
-							>
-								<PlayIcon iconWidth="narrow" />
-							</button>
-						)}
-						{/* Progress bar */}
-						<LoopVideoProgressBar
-							videoId={loopVideoId}
-							currentTime={currentTime}
-							duration={ref.current.duration}
-						/>
-						{/* Audio icon */}
-						{AudioIcon && (
-							<button
-								type="button"
-								onClick={handleAudioClick}
-								css={audioButtonStyles}
-								data-link-name={`gu-video-loop-${
-									isMuted ? 'unmute' : 'mute'
-								}-${atomId}`}
-							>
-								<div
-									css={audioIconContainerStyles}
-									data-testid={`${
+				{ref &&
+					'current' in ref &&
+					ref.current &&
+					isPlayable &&
+					!isCinemagraph && (
+						<>
+							{/* Play icon */}
+							{showPlayIcon && (
+								<button
+									type="button"
+									onClick={handlePlayPauseClick}
+									css={playIconStyles}
+									data-link-name={`gu-video-loop-play-${atomId}`}
+									data-testid="play-icon"
+								>
+									<PlayIcon iconWidth="narrow" />
+								</button>
+							)}
+							{/* Progress bar */}
+							<LoopVideoProgressBar
+								videoId={loopVideoId}
+								currentTime={currentTime}
+								duration={ref.current.duration}
+							/>
+							{/* Audio icon */}
+							{AudioIcon && (
+								<button
+									type="button"
+									onClick={handleAudioClick}
+									css={audioButtonStyles}
+									data-link-name={`gu-video-loop-${
 										isMuted ? 'unmute' : 'mute'
-									}-icon`}
+									}-${atomId}`}
 								>
-									<AudioIcon
-										size="xsmall"
-										theme={{
-											fill: palette(
-												'--loop-video-audio-icon',
-											),
-										}}
-									/>
-								</div>
-							</button>
-						)}
-					</>
-				)}
+									<div
+										css={audioIconContainerStyles}
+										data-testid={`${
+											isMuted ? 'unmute' : 'mute'
+										}-icon`}
+									>
+										<AudioIcon
+											size="xsmall"
+											theme={{
+												fill: palette(
+													'--loop-video-audio-icon',
+												),
+											}}
+										/>
+									</div>
+								</button>
+							)}
+						</>
+					)}
 			</>
 		);
 	},
diff --git a/dotcom-rendering/src/frontend/schemas/feFront.json b/dotcom-rendering/src/frontend/schemas/feFront.json
@@ -3239,6 +3239,14 @@
                 },
                 "activeVersion": {
                     "type": "number"
+                },
+                "videoPlayerFormat": {
+                    "enum": [
+                        "Cinemagraph",
+                        "Default",
+                        "Loop"
+                    ],
+                    "type": "string"
                 }
             },
             "required": [
diff --git a/dotcom-rendering/src/frontend/schemas/feTagPage.json b/dotcom-rendering/src/frontend/schemas/feTagPage.json
@@ -1412,6 +1412,14 @@
                 },
                 "activeVersion": {
                     "type": "number"
+                },
+                "videoPlayerFormat": {
+                    "enum": [
+                        "Cinemagraph",
+                        "Default",
+                        "Loop"
+                    ],
+                    "type": "string"
                 }
             },
             "required": [
diff --git a/dotcom-rendering/src/lib/getZIndex.ts b/dotcom-rendering/src/lib/getZIndex.ts
@@ -86,6 +86,9 @@ const indices = [
 	'bodyArea',
 	'rightColumnArea',
 
+	// Media overlay
+	'mediaOverlay',
+
 	// Loop video container
 	'loop-video-progress-bar-foreground',
 	'loop-video-progress-bar-background',
diff --git a/dotcom-rendering/src/model/enhanceCards.ts b/dotcom-rendering/src/model/enhanceCards.ts
