// @design-system: domain/HeroCarousel
/**
* HeroCarousel - auto-playing full-width featured carousel for desktop hero areas.
*
* Features:
* - Auto-advances every `interval` ms (default 4000).
* - Pauses when the browser tab is hidden (visibility API).
* - `prefers-reduced-motion`: no auto-advance, no CSS transition.
* - WCAG 2.2.2: pause/play button always visible (not hover-only).
* - RTL-aware slide transform (inverted direction for Hebrew).
* - Two modes: `deals` (shows PriceDisplay + CountdownTimer overlay) /
* `gallery` (shows vendor/deal name only).
*
* @example
*
*/
'use client';
import { useCallback, useEffect, useRef, useState } from 'react';
import { usePrefersReducedMotion } from '@/lib/hooks/useHydrated';
import { cn } from '@/lib/cn';
import { Image } from '@/components/ui/primitives/Image';
import { PriceDisplay } from '../PriceDisplay';
import { CountdownTimer } from '../CountdownTimer';
import { useT } from '@/lib/i18n/react';
import { useLocale } from '@/lib/i18n/react';
import { dirForLocale } from '@/lib/i18n';
import type { DealCardDeal } from '../DealCard';
export interface HeroCarouselSlide {
id: string;
/** Deal data - required in 'deals' mode, optional in 'gallery' mode. */
deal?: DealCardDeal;
/** Absolute image URL. */
imageSrc: string;
/** Descriptive alt text for the slide image. */
imageAlt: string;
/** Optional overlay label (used in gallery mode). */
label?: string;
/** Focal point for object-position. Default 0.5 each. */
focalX?: number;
focalY?: number;
}
export interface HeroCarouselProps {
slides: HeroCarouselSlide[];
/**
* - `deals`: shows PriceDisplay + CountdownTimer overlay on each slide.
* - `gallery`: shows a simple label overlay (e.g. vendor/business name).
* @default 'deals'
*/
mode?: 'deals' | 'gallery';
/** Auto-advance interval in ms. Set to Infinity to disable. @default 4000 */
interval?: number;
/** Called when a slide is activated (click or Enter). */
onSelectDeal?: (id: string) => void;
className?: string;
}
export function HeroCarousel({
slides,
mode = 'deals',
interval = 4000,
onSelectDeal,
className,
}: HeroCarouselProps) {
const t = useT('hero_carousel');
const { locale } = useLocale();
const isRTL = dirForLocale(locale) === 'rtl';
const [activeIndex, setActiveIndex] = useState(0);
const [isPaused, setIsPaused] = useState(false);
const intervalRef = useRef | null>(null);
// Detect prefers-reduced-motion
const prefersReducedMotion = usePrefersReducedMotion();
const goToSlide = useCallback(
(index: number) => {
setActiveIndex(((index % slides.length) + slides.length) % slides.length);
},
[slides.length],
);
const goNext = useCallback(() => {
goToSlide(activeIndex + 1);
}, [activeIndex, goToSlide]);
const goPrev = useCallback(() => {
goToSlide(activeIndex - 1);
}, [activeIndex, goToSlide]);
const handleKeyDown = useCallback(
(e: React.KeyboardEvent) => {
switch (e.key) {
case 'ArrowRight':
e.preventDefault();
if (isRTL) {
goPrev();
} else {
goNext();
}
break;
case 'ArrowLeft':
e.preventDefault();
if (isRTL) {
goNext();
} else {
goPrev();
}
break;
case 'Home':
e.preventDefault();
goToSlide(0);
break;
case 'End':
e.preventDefault();
goToSlide(slides.length - 1);
break;
}
},
[isRTL, goNext, goPrev, goToSlide, slides.length],
);
// Auto-play
useEffect(() => {
if (slides.length <= 1 || isPaused || prefersReducedMotion || interval === Infinity) return;
const startAutoPlay = () => {
intervalRef.current = setInterval(goNext, interval);
};
const stopAutoPlay = () => {
if (intervalRef.current) {
clearInterval(intervalRef.current);
intervalRef.current = null;
}
};
const handleVisibilityChange = () => {
if (document.visibilityState === 'hidden') {
stopAutoPlay();
} else {
stopAutoPlay();
startAutoPlay();
}
};
startAutoPlay();
document.addEventListener('visibilitychange', handleVisibilityChange);
return () => {
stopAutoPlay();
document.removeEventListener('visibilitychange', handleVisibilityChange);
};
}, [goNext, interval, isPaused, prefersReducedMotion, slides.length]);
if (slides.length === 0) return null;
const translateX = isRTL ? `calc(${activeIndex} * 100%)` : `calc(-${activeIndex} * 100%)`;
return (
{/* Keyboard-navigable carousel container. tabIndex required by ARIA APG carousel pattern;
jsx-a11y doesn't model this keyboard-focusable region exemption. */}