Payment method promotions adjustments

client/components/spotlight/__tests__/index.test.tsx

@@ -114,7 +114,7 @@ describe( 'Spotlight Component', () => {
 		expect( screen.getByTestId( 'custom-image' ) ).toBeInTheDocument();
 	} );
 
-	it( 'calls onPrimaryClick and onDismiss when primary button is clicked', () => {
+	it( 'calls onPrimaryClick and onDismiss when primary button is clicked', async () => {
 		const onPrimaryClick = jest.fn();
 		const onDismiss = jest.fn();
 
@@ -127,10 +127,17 @@ describe( 'Spotlight Component', () => {
 		);
 
 		const primaryButton = screen.getByText( 'Activate' );
-		userEvent.click( primaryButton );
+		await userEvent.click( primaryButton );
 
 		expect( onPrimaryClick ).toHaveBeenCalledTimes( 1 );
-		// onDismiss is called after animation timeout
+
+		// onDismiss is called after animation timeout (300ms)
+		await waitFor(
+			() => {
+				expect( onDismiss ).toHaveBeenCalledTimes( 1 );
+			},
+			{ timeout: 500 }
+		);
 	} );
 
 	it( 'calls onSecondaryClick when secondary button is clicked', () => {

client/components/spotlight/index.tsx

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import React, { useEffect, useState } from 'react';
+import React, { useCallback, useEffect, useRef, useState } from 'react';
 import {
 	Card,
 	CardBody,
@@ -40,6 +40,11 @@ const Spotlight: React.FC< SpotlightProps > = ( {
 } ) => {
 	const [ isVisible, setIsVisible ] = useState( false );
 	const [ isAnimatingIn, setIsAnimatingIn ] = useState( false );
+	const closeTimeoutRef = useRef< ReturnType< typeof setTimeout > | null >(
+		null
+	);
+	const dialogRef = useRef< HTMLDivElement >( null );
+	const previouslyFocusedElementRef = useRef< HTMLElement | null >( null );
 
 	useEffect( () => {
 		if ( showImmediately ) {
@@ -62,6 +67,15 @@ const Spotlight: React.FC< SpotlightProps > = ( {
 		return () => clearTimeout( timer );
 	}, [ showImmediately ] );
 
+	// Cleanup close timeout on unmount
+	useEffect( () => {
+		return () => {
+			if ( closeTimeoutRef.current ) {
+				clearTimeout( closeTimeoutRef.current );
+			}
+		};
+	}, [] );
+
 	// Call onView when spotlight becomes visible
 	useEffect( () => {
 		if ( isAnimatingIn && onView ) {
@@ -70,14 +84,72 @@ const Spotlight: React.FC< SpotlightProps > = ( {
 		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, [ isAnimatingIn ] );
 
-	const handleClose = () => {
+	const handleClose = useCallback( () => {
 		setIsAnimatingIn( false );
 		// Wait for animation to complete before hiding
-		setTimeout( () => {
+		closeTimeoutRef.current = setTimeout( () => {
 			setIsVisible( false );
 			onDismiss();
 		}, 300 );
-	};
+	}, [ onDismiss ] );
+
+	// Focus management: save previous focus, focus dialog, handle Escape, trap focus, restore on close
+	useEffect( () => {
+		if ( ! isVisible || ! dialogRef.current ) {
+			return;
+		}
+
+		const dialog = dialogRef.current;
+		const ownerDocument = dialog.ownerDocument;
+
+		// Save the currently focused element to restore later
+		previouslyFocusedElementRef.current = ownerDocument.activeElement as HTMLElement;
+
+		// Focus the dialog
+		dialog.focus();
+
+		const handleKeyDown = ( event: KeyboardEvent ) => {
+			if ( event.key === 'Escape' ) {
+				event.preventDefault();
+				handleClose();
+				return;
+			}
+
+			// Focus trapping
+			if ( event.key === 'Tab' ) {
+				const focusableElements = dialog.querySelectorAll<
+					HTMLElement
+				>(
+					'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+				);
+				const firstElement = focusableElements[ 0 ];
+				const lastElement =
+					focusableElements[ focusableElements.length - 1 ];
+				const activeElement = ownerDocument.activeElement;
+
+				if ( event.shiftKey && activeElement === firstElement ) {
+					// Shift + Tab: if on first element, wrap to last
+					event.preventDefault();
+					lastElement?.focus();
+				} else if (
+					! event.shiftKey &&
+					activeElement === lastElement
+				) {
+					// Tab: if on last element, wrap to first
+					event.preventDefault();
+					firstElement?.focus();
+				}
+			}
+		};
+
+		ownerDocument.addEventListener( 'keydown', handleKeyDown );
+
+		return () => {
+			ownerDocument.removeEventListener( 'keydown', handleKeyDown );
+			// Restore focus to previously focused element
+			previouslyFocusedElementRef.current?.focus();
+		};
+	}, [ isVisible, handleClose ] );
 
 	const handlePrimaryClick = () => {
 		onPrimaryClick();
@@ -94,7 +166,14 @@ const Spotlight: React.FC< SpotlightProps > = ( {
 				isAnimatingIn ? 'wcpay-spotlight--visible' : ''
 			}` }
 		>
-			<div className="wcpay-spotlight__container">
+			<div
+				ref={ dialogRef }
+				role="dialog"
+				aria-modal="true"
+				aria-labelledby="spotlight-heading"
+				tabIndex={ -1 }
+				className="wcpay-spotlight__container"
+			>
 				<Card
 					className={ `wcpay-spotlight__card ${
 						image ? 'has-image' : ''
@@ -147,7 +226,10 @@ const Spotlight: React.FC< SpotlightProps > = ( {
 								<Chip message={ badge } type="primary" />
 							</div>
 						) }
-						<h2 className="wcpay-spotlight__heading">
+						<h2
+							id="spotlight-heading"
+							className="wcpay-spotlight__heading"
+						>
 							{ heading }
 						</h2>
 						<div className="wcpay-spotlight__description">

client/components/spotlight/style.scss

@@ -25,6 +25,10 @@
 			margin: 0;
 		}
 	}
+
+	@media ( prefers-reduced-motion: reduce ) {
+		transition: none;
+	}
 }
 
 .wcpay-spotlight__container {

client/components/spotlight/types.ts

@@ -1,5 +1,10 @@
 /** @format */
 
+/**
+ * External dependencies
+ */
+import type { ReactNode } from 'react';
+
 /**
  * Props for the Spotlight component.
  */
@@ -17,17 +22,17 @@ export interface SpotlightProps {
 	/**
 	 * Description content (can be a string or React component).
 	 */
-	description: React.ReactNode;
+	description: ReactNode;
 
 	/**
 	 * Optional disclaimer content shown at the bottom (can be a string or React component).
 	 */
-	disclaimer?: React.ReactNode;
+	disclaimer?: ReactNode;
 
 	/**
 	 * Image element or URL to display in the spotlight.
 	 */
-	image?: React.ReactNode | string;
+	image?: ReactNode | string;
 
 	/**
 	 * Primary button label.

client/data/promotions/actions.ts

@@ -19,6 +19,30 @@ import {
 import { ApiError } from '../../types/errors';
 import { NAMESPACE } from '../constants';
 
+/**
+ * Type guard to check if an error is an ApiError.
+ */
+function isApiError( error: unknown ): error is ApiError {
+	return (
+		typeof error === 'object' &&
+		error !== null &&
+		'code' in error &&
+		typeof ( error as ApiError ).code === 'string'
+	);
+}
+
+/**
+ * Normalizes an unknown error to an ApiError.
+ */
+function normalizeError( error: unknown ): ApiError {
+	if ( isApiError( error ) ) {
+		return error;
+	}
+	return {
+		code: 'unknown_error',
+	};
+}
+
 export function updatePromotions(
 	data: PromotionsData
 ): UpdatePromotionsAction {
@@ -47,7 +71,7 @@ export function* activatePromotion(
 	identifier: string,
 	acceptTerms = true
 ): unknown {
-	const path = `${ NAMESPACE }/payment-method-promotions/${ identifier }/activate`;
+	const path = `${ NAMESPACE }/pm-promotions/${ identifier }/activate`;
 
 	try {
 		yield apiFetch( {
@@ -78,7 +102,11 @@ export function* activatePromotion(
 				'woocommerce-payments'
 			)
 		);
-		yield updateErrorForPromotions( e as ApiError );
+		yield controls.dispatch(
+			'wc/payments',
+			'updateErrorForPromotions',
+			normalizeError( e )
+		);
 	}
 }
 
@@ -92,7 +120,7 @@ export function* dismissPromotion(
 	identifier: string,
 	variationId: string
 ): unknown {
-	const path = `${ NAMESPACE }/payment-method-promotions/${ identifier }/dismiss`;
+	const path = `${ NAMESPACE }/pm-promotions/${ identifier }/dismiss`;
 
 	try {
 		yield apiFetch( {
@@ -123,6 +151,10 @@ export function* dismissPromotion(
 				'woocommerce-payments'
 			)
 		);
-		yield updateErrorForPromotions( e as ApiError );
+		yield controls.dispatch(
+			'wc/payments',
+			'updateErrorForPromotions',
+			normalizeError( e )
+		);
 	}
 }

client/data/promotions/resolvers.ts

@@ -11,19 +11,84 @@ import { __ } from '@wordpress/i18n';
  * Internal dependencies
  */
 import { NAMESPACE } from '../constants';
-import { updatePromotions, updateErrorForPromotions } from './actions';
-import { PromotionsData } from './types';
+import { Promotion, PromotionVariation, PromotionsData } from './types';
 import { ApiError } from '../../types/errors';
 
+/**
+ * Type guard to check if an object is a valid PromotionVariation.
+ */
+function isPromotionVariation( value: unknown ): value is PromotionVariation {
+	if ( typeof value !== 'object' || value === null ) {
+		return false;
+	}
+	const obj = value as Record< string, unknown >;
+	return (
+		typeof obj.id === 'string' &&
+		typeof obj.type === 'string' &&
+		typeof obj.heading === 'string' &&
+		typeof obj.description === 'string' &&
+		typeof obj.cta_label === 'string' &&
+		typeof obj.cta_url === 'string'
+	);
+}
+
+/**
+ * Type guard to check if an object is a valid Promotion.
+ */
+function isPromotion( value: unknown ): value is Promotion {
+	if ( typeof value !== 'object' || value === null ) {
+		return false;
+	}
+	const obj = value as Record< string, unknown >;
+	return (
+		typeof obj.promo_id === 'string' &&
+		typeof obj.discount_rate === 'string' &&
+		typeof obj.duration_days === 'number' &&
+		Array.isArray( obj.variations ) &&
+		obj.variations.every( isPromotionVariation )
+	);
+}
+
+/**
+ * Type guard to check if a value is valid PromotionsData.
+ */
+function isPromotionsData( value: unknown ): value is PromotionsData {
+	return Array.isArray( value ) && value.every( isPromotion );
+}
+
+/**
+ * Type guard to check if an error is an ApiError.
+ */
+function isApiError( error: unknown ): error is ApiError {
+	return typeof error === 'object' && error !== null && 'code' in error;
+}
+
+/**
+ * Normalizes an unknown error to an ApiError.
+ */
+function normalizeError( error: unknown ): ApiError {
+	if ( isApiError( error ) ) {
+		return error;
+	}
+	return {
+		code: 'unknown_error',
+	};
+}
+
 /**
  * Retrieve promotions data.
  */
 export function* getPromotions(): unknown {
-	const path = `${ NAMESPACE }/payment-method-promotions`;
+	const path = `${ NAMESPACE }/pm-promotions`;
 
 	try {
 		const result = yield apiFetch( { path } );
-		yield updatePromotions( result as PromotionsData );
+
+		if ( ! isPromotionsData( result ) ) {
+			throw new Error( 'Invalid promotions data received from API' );
+		}
+
+		yield controls.dispatch( 'wc/payments', 'updatePromotions', result );
 	} catch ( e ) {
 		yield controls.dispatch(
 			'core/notices',
@@ -33,6 +98,10 @@ export function* getPromotions(): unknown {
 				'woocommerce-payments'
 			)
 		);
-		yield updateErrorForPromotions( e as ApiError );
+		yield controls.dispatch(
+			'wc/payments',
+			'updateErrorForPromotions',
+			normalizeError( e )
+		);
 	}
 }