@thorprovider/blocks 0.1.3 → 1.0.0

package/src/blocks/e-commerce/storefront-hero/storefront-hero.tsx

@@ -0,0 +1,1283 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import { motion, useReducedMotion } from 'motion/react'
+import { ArrowRight, MapPin, Search, ShoppingBag, Star } from 'lucide-react'
+import type { ComponentProps, ReactNode } from 'react'
+
+import { Badge } from '../../../ui/badge'
+import { Button } from '../../../ui/button'
+import { Card, CardContent } from '../../../ui/card'
+import { Carousel, CarouselContent, CarouselItem, type CarouselApi } from '../../../ui/carousel'
+import { Input } from '../../../ui/input'
+import { cn } from '../../../lib/utils'
+import type { CTA } from '../../../lib/types'
+
+/**
+ * Display contract for products featured in the hero. Every popularity,
+ * review, or availability field is host-supplied evidence: omitted fields
+ * render nothing (honest omission) instead of fabricated defaults.
+ */
+export interface FeaturedProduct {
+  id: string
+  name: string
+  /** Current selling price. */
+  price: number
+  /** Real compare-at price. Discount treatments render only from a real `originalPrice > price` pair. */
+  originalPrice?: number
+  /** Image URL or path; omitted entirely when absent or blank (never an empty `src`). */
+  image?: string
+  /** Accessible image description (falls back to `name`). */
+  imageAlt?: string
+  /** Host-supplied brand label; the row renders only when supplied. */
+  brand?: string
+  /** Host-supplied swatch colors; the row renders only when supplied. */
+  colors?: string[]
+  /** Host-supplied rating (0–5); rendered only when supplied. */
+  rating?: number
+  /** Host-supplied review count; rendered only when supplied. */
+  reviewCount?: number
+  /** Host-supplied availability. Absence makes no stock claim; an explicit `false` disables purchase. */
+  inStock?: boolean
+  /** Host-supplied "new" flag; the badge renders only when true. */
+  isNew?: boolean
+  /** Host-supplied badge label for showcase slides (e.g. a category); rendered only when supplied. */
+  tag?: string
+}
+
+export interface HeroImage {
+  src: string
+  alt: string
+}
+
+export interface HeroDepartment {
+  id: string
+  name: string
+  /** Image URL; omitted entirely when absent or blank. */
+  image?: string
+  /** Accessible image description (falls back to `name`). */
+  imageAlt?: string
+  /** Host-supplied count label; rendered only when supplied. */
+  count?: string
+  /** Link destination; renders the chip as a link when present. */
+  href?: string
+}
+
+export interface HeroFeaturedDeal {
+  id: string
+  name: string
+  /** Host-supplied supporting description; rendered only when supplied. */
+  description?: string
+  /** Image URL; omitted entirely when absent or blank. */
+  image?: string
+  /** Accessible image description (falls back to `name`). */
+  imageAlt?: string
+  price: number
+  /** Real compare-at price; rendered struck-through only when greater than `price`. */
+  originalPrice?: number
+  /** Optional call to action shown on the card. */
+  cta?: CTA
+}
+
+export interface HeroStoreLocator {
+  title: string
+  description: string
+  ctaLabel: string
+  /** Link destination for the locator button; falls back to `onLocateStores`. */
+  ctaHref?: string
+}
+
+export interface HeroDeal {
+  id: string
+  /** Deal name shown in the deals bar badge, e.g. a campaign name. */
+  title: string
+  /** Host-supplied discount label (from a real compare-at price); rendered only when supplied. */
+  discount?: string
+  /** Host-supplied countdown text; rendered only when supplied — the block never invents one. */
+  endTime?: string
+}
+
+export interface HeroCategory {
+  id: string
+  name: string
+  /** Image URL; omitted entirely when absent or blank. */
+  image?: string
+  /** Accessible image description (falls back to `name`). */
+  imageAlt?: string
+  /** Host-supplied count label; rendered only when supplied. */
+  count?: string
+  /** Link destination; renders the card arrow as a link when present. */
+  href?: string
+}
+
+/**
+ * The bounded presentation surface, reusing the registry's archetype intent
+ * vocabulary: `compact` (text-forward hero + product grid), `showcase`
+ * (search affordance + rotating product carousel), `editorial` (department
+ * navigation + optional deals/locator), `promotional` (deals bar + category
+ * grid). The value changes structure, never the data contract.
+ */
+export type StorefrontHeroPresentation = 'compact' | 'showcase' | 'editorial' | 'promotional'
+
+export interface StorefrontHeroProps {
+  title: string
+  description: string
+  /** Bounded presentation option; defaults to `compact`. */
+  presentation?: StorefrontHeroPresentation
+  /** ISO 4217 code used to format prices via `Intl.NumberFormat`; never hardcoded. */
+  currency?: string
+  /** Featured products. An empty list renders the hero text-forward with no empty grid chrome. */
+  products: FeaturedProduct[]
+  badge?: string
+  titleAccent?: string
+  primaryCta?: CTA
+  secondaryCta?: CTA
+  /**
+   * Optional editorial image. Rendered as a native `<img>` when `src` is a
+   * non-empty string; omitted entirely when absent or blank (never an empty
+   * `src`).
+   */
+  heroImage?: HeroImage
+  /** `showcase` only. The search input renders only when a handler is supplied. */
+  onSearch?: (query: string) => void
+  /** `editorial` only: department navigation grid. */
+  departments?: HeroDepartment[]
+  /** `editorial` only: featured deal cards. */
+  featuredDeals?: HeroFeaturedDeal[]
+  /** `editorial` only: store locator strip. */
+  storeLocator?: HeroStoreLocator
+  /** `editorial` only: shipping banner text under the CTAs. */
+  shippingInfo?: string
+  /** `promotional` only: rotating deals bar. */
+  deals?: HeroDeal[]
+  /** `promotional` only: category card grid. */
+  categories?: HeroCategory[]
+  /** Milliseconds between rotations (showcase carousel and promotional deals bar; default 3000). */
+  rotationInterval?: number
+  onAddToCart?: (product: FeaturedProduct) => void
+  onBuyNow?: (product: FeaturedProduct) => void
+  onSelectColor?: (product: FeaturedProduct, index: number, color: string) => void
+  onDepartmentClick?: (department: HeroDepartment) => void
+  onShopNow?: (item: HeroFeaturedDeal | HeroDeal) => void
+  onLocateStores?: () => void
+  onCategoryClick?: (category: HeroCategory) => void
+  /** Detail/purchase affordance on product cards and showcase slides. */
+  addToCartLabel?: string
+  buyNowLabel?: string
+  newLabel?: string
+  outOfStockLabel?: string
+  colorsLabel?: string
+  /** Suffix appended to the computed discount percentage (default `% OFF`). */
+  discountSuffixLabel?: string
+  /** `showcase` labels. */
+  searchPlaceholder?: string
+  searchLabel?: string
+  /** `showcase` copy under each slide's product name. */
+  featuredDescription?: string
+  /** `editorial`/`promotional` labels. */
+  shopNowLabel?: string
+  endsInLabel?: string
+  productsLabel?: string
+  viewLabel?: string
+}
+
+function hasRealDiscount(item: Pick<FeaturedProduct, 'price' | 'originalPrice'>): boolean {
+  return (
+    typeof item.originalPrice === 'number' &&
+    Number.isFinite(item.originalPrice) &&
+    item.originalPrice > item.price &&
+    item.price >= 0
+  )
+}
+
+function discountPercent(price: number, originalPrice: number): number {
+  return Math.round(((originalPrice - price) / originalPrice) * 100)
+}
+
+function formatAmount(amount: number, currency?: string): string {
+  if (currency) {
+    return new Intl.NumberFormat(undefined, { style: 'currency', currency }).format(amount)
+  }
+  return new Intl.NumberFormat(undefined, { maximumFractionDigits: 2 }).format(amount)
+}
+
+function CtaButton({
+  cta,
+  variant,
+  className = 'group relative cursor-pointer overflow-hidden px-8 py-6 text-base font-medium',
+  children,
+}: {
+  cta: CTA
+  variant?: ComponentProps<typeof Button>['variant']
+  className?: string
+  children: ReactNode
+}) {
+  if (cta.href) {
+    return (
+      <Button variant={variant} size='lg' className={className} asChild>
+        <a href={cta.href}>{children}</a>
+      </Button>
+    )
+  }
+
+  return (
+    <Button variant={variant} size='lg' className={className}>
+      {children}
+    </Button>
+  )
+}
+
+function HeroHeading({
+  title,
+  titleAccent,
+  badge,
+}: {
+  title: string
+  titleAccent?: string
+  badge?: string
+}) {
+  return (
+    <>
+      {badge && (
+        <div className='border-primary/20 bg-primary/5 text-primary inline-flex items-center rounded-full border px-4 py-1.5 text-sm font-medium backdrop-blur-sm'>
+          {badge}
+        </div>
+      )}
+      <h1 className='text-foreground mt-8 text-4xl font-bold tracking-tight sm:text-5xl md:text-7xl'>
+        {title}{' '}
+        {titleAccent && (
+          <span className='from-primary to-primary/70 bg-gradient-to-r bg-clip-text text-transparent'>
+            {titleAccent}
+          </span>
+        )}
+      </h1>
+    </>
+  )
+}
+
+function EditorialHeading({
+  title,
+  titleAccent,
+  badge,
+}: {
+  title: string
+  titleAccent?: string
+  badge?: string
+}) {
+  return (
+    <>
+      {badge && (
+        <div className='border-primary/20 bg-primary/5 text-primary inline-flex items-center justify-center rounded-md border px-4 py-1.5 text-sm'>
+          {badge}
+        </div>
+      )}
+      <h1 className='mt-6 text-4xl font-bold tracking-tight text-balance sm:text-5xl md:text-6xl'>
+        {title} {titleAccent && <span className='text-primary'>{titleAccent}</span>}
+      </h1>
+    </>
+  )
+}
+
+interface HeroLabels {
+  addToCartLabel: string
+  buyNowLabel: string
+  newLabel: string
+  outOfStockLabel: string
+  colorsLabel: string
+  discountSuffixLabel: string
+  searchPlaceholder: string
+  searchLabel: string
+  featuredDescription?: string
+  shopNowLabel: string
+  endsInLabel: string
+  productsLabel: string
+  viewLabel: string
+}
+
+function CompactProductCard({
+  product,
+  currency,
+  labels,
+  onAddToCart,
+  onBuyNow,
+  onSelectColor,
+  hasCustomBuyNowLabel,
+}: {
+  product: FeaturedProduct
+  currency?: string
+  labels: HeroLabels
+  onAddToCart?: (product: FeaturedProduct) => void
+  onBuyNow?: (product: FeaturedProduct) => void
+  onSelectColor?: (product: FeaturedProduct, index: number, color: string) => void
+  hasCustomBuyNowLabel: boolean
+}) {
+  const outOfStock = product.inStock === false
+  const onSale = hasRealDiscount(product)
+  // A host-supplied custom action label is a purchase affordance and requires
+  // its handler; the block's default label is a detail affordance that may
+  // render without one. Never infer this from the label's language.
+  const showBuyNow = Boolean(onBuyNow) || !hasCustomBuyNowLabel
+
+  return (
+    <div className='bg-card relative h-full overflow-hidden rounded-lg border shadow-sm transition-shadow hover:shadow-md'>
+      <div className='absolute top-4 left-4 z-10 flex flex-col gap-2'>
+        {product.isNew && (
+          <Badge variant='secondary' className='rounded-full'>{labels.newLabel}</Badge>
+        )}
+        {onSale && (
+          <Badge variant='destructive' className='rounded-full'>
+            {discountPercent(product.price, product.originalPrice as number)}
+            {labels.discountSuffixLabel}
+          </Badge>
+        )}
+      </div>
+
+      <div className='relative aspect-square overflow-hidden'>
+        {product.image && product.image.trim().length > 0 ? (
+          <img
+            src={product.image}
+            alt={product.imageAlt ?? product.name}
+            className='size-full object-cover'
+            loading='lazy'
+          />
+        ) : null}
+        {outOfStock && (
+          <div className='absolute inset-0 flex items-center justify-center bg-black/50'>
+            <span className='rounded bg-white/90 px-3 py-1 text-sm font-medium'>{labels.outOfStockLabel}</span>
+          </div>
+        )}
+      </div>
+
+      <div className='p-4'>
+        {product.brand && product.brand.trim().length > 0 && (
+          <div className='text-muted-foreground mb-1 text-sm font-medium'>{product.brand}</div>
+        )}
+        <h3 className='mb-2 font-medium'>{product.name}</h3>
+
+        <div className='mb-3'>
+          <span className='text-lg font-bold'>{formatAmount(product.price, currency)}</span>
+          {onSale && (
+            <span className='text-muted-foreground ms-2 text-sm line-through'>
+              {formatAmount(product.originalPrice as number, currency)}
+            </span>
+          )}
+        </div>
+
+        {product.colors && product.colors.length > 0 && (
+          <div className='mb-4 flex items-center'>
+            <span className='text-muted-foreground me-2 text-sm'>{labels.colorsLabel}</span>
+            <div className='flex gap-1'>
+              {product.colors.map((color, i) => (
+                <button
+                  key={i}
+                  className='size-5 rounded-full border'
+                  style={{ backgroundColor: color }}
+                  aria-label={`Opción de color ${i + 1}`}
+                  onClick={onSelectColor ? () => onSelectColor(product, i, color) : undefined}
+                />
+              ))}
+            </div>
+          </div>
+        )}
+
+        {typeof product.rating === 'number' && (
+          <div className='mb-4 flex items-center'>
+            <div className='flex'>
+              {[...Array(5)].map((_, i) => (
+                <Star
+                  key={i}
+                  className={`size-4 ${i < Math.floor(product.rating ?? 0) ? 'fill-foreground text-foreground' : 'text-muted-foreground'}`}
+                />
+              ))}
+            </div>
+            {typeof product.reviewCount === 'number' && (
+              <span className='text-muted-foreground ms-2 text-sm'>({product.reviewCount.toLocaleString()})</span>
+            )}
+          </div>
+        )}
+
+        <div className='flex flex-col gap-2'>
+          {onAddToCart && (
+            <Button
+              variant='outline'
+              className='h-9 cursor-pointer px-4 py-2'
+              disabled={outOfStock}
+              onClick={() => onAddToCart(product)}
+            >
+              <ShoppingBag />
+              {labels.addToCartLabel}
+            </Button>
+          )}
+          {showBuyNow && (
+            <Button
+              className='h-9 cursor-pointer px-4 py-2'
+              disabled={outOfStock}
+              onClick={onBuyNow ? () => onBuyNow(product) : undefined}
+            >
+              {labels.buyNowLabel}
+            </Button>
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+function CompactPresentation({
+  title,
+  description,
+  products,
+  badge,
+  titleAccent,
+  primaryCta,
+  secondaryCta,
+  heroImage,
+  currency,
+  labels,
+  onAddToCart,
+  onBuyNow,
+  onSelectColor,
+  hasCustomBuyNowLabel,
+}: {
+  title: string
+  description: string
+  products: FeaturedProduct[]
+  badge?: string
+  titleAccent?: string
+  primaryCta?: CTA
+  secondaryCta?: CTA
+  heroImage?: HeroImage
+  currency?: string
+  labels: HeroLabels
+  onAddToCart?: (product: FeaturedProduct) => void
+  onBuyNow?: (product: FeaturedProduct) => void
+  onSelectColor?: (product: FeaturedProduct, index: number, color: string) => void
+  hasCustomBuyNowLabel: boolean
+}) {
+  const reduceMotion = useReducedMotion()
+
+  return (
+    <div className='from-primary/5 to-background relative overflow-hidden bg-gradient-to-br'>
+      <div className='relative z-10 mx-auto w-full max-w-7xl flex flex-col items-center justify-between gap-12 px-4 sm:px-6 lg:px-8 py-16 lg:py-20 xl:flex-row xl:items-start'>
+        <motion.div
+          initial={reduceMotion ? false : { opacity: 0, y: 24 }}
+          animate={{ opacity: 1, y: 0 }}
+          transition={{ duration: 0.5, ease: 'easeOut' }}
+          className='mx-auto max-w-xl text-center lg:mx-0 xl:text-left'
+        >
+          <HeroHeading title={title} titleAccent={titleAccent} badge={badge} />
+          <p className='text-muted-foreground mt-8 text-lg'>{description}</p>
+          {(primaryCta || secondaryCta) && (
+            <div className='mt-10 flex flex-col gap-4 sm:flex-row sm:justify-center xl:justify-start'>
+              {primaryCta && (
+                <CtaButton cta={primaryCta}>
+                  <span className='relative z-10 flex items-center gap-2'>
+                    {primaryCta.label}
+                    <ArrowRight className='transition-transform group-hover:translate-x-1' />
+                  </span>
+                  <span className='bg-primary/5 absolute inset-0 -z-0 opacity-0 transition-opacity group-hover:opacity-100'></span>
+                </CtaButton>
+              )}
+              {secondaryCta && (
+                <CtaButton cta={secondaryCta} variant='outline'>
+                  <span className='relative z-10 flex items-center gap-2'>
+                    <ShoppingBag />
+                    {secondaryCta.label}
+                  </span>
+                </CtaButton>
+              )}
+            </div>
+          )}
+          {heroImage && heroImage.src.trim().length > 0 ? (
+            <img
+              src={heroImage.src}
+              alt={heroImage.alt}
+              className='mt-10 aspect-video w-full rounded-lg object-cover'
+            />
+          ) : null}
+        </motion.div>
+
+        {products.length > 0 && (
+          <div className='w-full max-w-2xl lg:mt-0'>
+            <div className='grid gap-6 sm:grid-cols-2'>
+              {products.map((product, index) => (
+                <motion.div
+                  key={product.id}
+                  initial={reduceMotion ? false : { opacity: 0, y: 24 }}
+                  whileInView={{ opacity: 1, y: 0 }}
+                  viewport={{ once: true, margin: '-40px' }}
+                  transition={{
+                    duration: 0.45,
+                    delay: reduceMotion ? 0 : index * 0.1,
+                    ease: 'easeOut',
+                  }}
+                >
+                  <CompactProductCard
+                    product={product}
+                    currency={currency}
+                    labels={labels}
+                    onAddToCart={onAddToCart}
+                    onBuyNow={onBuyNow}
+                    onSelectColor={onSelectColor}
+                    hasCustomBuyNowLabel={hasCustomBuyNowLabel}
+                  />
+                </motion.div>
+              ))}
+            </div>
+          </div>
+        )}
+      </div>
+
+      <div className='bg-primary/10 absolute -top-32 -right-32 size-96 rounded-full blur-3xl' />
+      <div className='bg-secondary/30 absolute -bottom-32 -left-32 size-96 rounded-full blur-3xl' />
+    </div>
+  )
+}
+
+function ShowcaseSlide({
+  product,
+  currency,
+  labels,
+  onBuyNow,
+}: {
+  product: FeaturedProduct
+  currency?: string
+  labels: HeroLabels
+  onBuyNow?: (product: FeaturedProduct) => void
+}) {
+  const outOfStock = product.inStock === false
+
+  return (
+    <Card className='relative size-full overflow-hidden border-1 py-4'>
+      <CardContent className='px-4'>
+        <div className='relative size-full overflow-hidden rounded-md'>
+          {product.image && product.image.trim().length > 0 ? (
+            <img
+              src={product.image}
+              alt={product.imageAlt ?? product.name}
+              className='h-[500px] w-full object-cover'
+              loading='lazy'
+            />
+          ) : null}
+        </div>
+        <div className='from-background/90 via-background/30 absolute inset-0 bg-linear-to-t to-transparent' />
+
+        <div className='text-background-foreground absolute inset-0 flex flex-col justify-end p-8'>
+          <div className='relative z-10 flex max-w-md flex-col gap-4'>
+            {product.tag && (
+              <Badge className='w-fit rounded-full px-2.5 py-0.5 font-semibold'>{product.tag}</Badge>
+            )}
+            <h2 className='text-4xl font-bold'>{product.name}</h2>
+            {labels.featuredDescription && (
+              <p className='text-background-foreground/80 text-lg'>{labels.featuredDescription}</p>
+            )}
+            <span className='text-3xl font-bold'>{formatAmount(product.price, currency)}</span>
+            <div className='flex items-center gap-4 pt-2'>
+              {onBuyNow && (
+                <Button
+                  size='lg'
+                  className='h-10 cursor-pointer rounded-full px-8'
+                  disabled={outOfStock}
+                  onClick={() => onBuyNow(product)}
+                >
+                  {labels.buyNowLabel}
+                </Button>
+              )}
+              {typeof product.rating === 'number' && (
+                <div className='text-foreground flex items-center gap-1'>
+                  <Star className='fill-foreground size-5' />
+                  <span className='font-medium'>{product.rating}</span>
+                  {typeof product.reviewCount === 'number' && (
+                    <span className='text-foreground/80'>({product.reviewCount})</span>
+                  )}
+                </div>
+              )}
+            </div>
+          </div>
+        </div>
+      </CardContent>
+    </Card>
+  )
+}
+
+function ShowcasePresentation({
+  title,
+  description,
+  products,
+  badge,
+  primaryCta,
+  secondaryCta,
+  currency,
+  labels,
+  onSearch,
+  onBuyNow,
+  rotationInterval,
+}: {
+  title: string
+  description: string
+  products: FeaturedProduct[]
+  badge?: string
+  primaryCta?: CTA
+  secondaryCta?: CTA
+  currency?: string
+  labels: HeroLabels
+  onSearch?: (query: string) => void
+  onBuyNow?: (product: FeaturedProduct) => void
+  rotationInterval: number
+}) {
+  const reduceMotion = useReducedMotion()
+  const [searchQuery, setSearchQuery] = useState('')
+  const [api, setApi] = useState<CarouselApi>()
+  const [currentSlide, setCurrentSlide] = useState(0)
+
+  useEffect(() => {
+    if (!api || products.length <= 1 || reduceMotion) return
+
+    const interval = setInterval(() => {
+      const nextSlide = (currentSlide + 1) % products.length
+      api.scrollTo(nextSlide)
+      setCurrentSlide(nextSlide)
+    }, rotationInterval)
+
+    return () => clearInterval(interval)
+  }, [api, currentSlide, products.length, reduceMotion, rotationInterval])
+
+  const handleSearch = () => {
+    if (onSearch) onSearch(searchQuery)
+  }
+
+  return (
+    <section className='from-background to-accent/20 relative bg-linear-to-b'>
+      <div className='relative mx-auto w-full max-w-7xl px-4 py-16 sm:px-6 lg:px-8 lg:py-20'>
+        <div className='grid grid-cols-1 items-center gap-12 lg:grid-cols-2'>
+          <header className='flex flex-col gap-8'>
+            {badge && (
+              <Badge variant='outline' className='flex h-auto w-fit items-center rounded-full px-4 py-2 font-semibold'>
+                {badge}
+              </Badge>
+            )}
+
+            <h1 className='text-5xl leading-tight font-bold text-balance md:text-6xl lg:text-7xl'>{title}</h1>
+
+            <p className='text-muted-foreground max-w-lg text-xl text-balance'>{description}</p>
+
+            {onSearch && (
+              <div className='relative max-w-md'>
+                <Input
+                  type='search'
+                  placeholder={labels.searchPlaceholder}
+                  value={searchQuery}
+                  onChange={e => setSearchQuery(e.target.value)}
+                  onKeyDown={e => {
+                    if (e.key === 'Enter') handleSearch()
+                  }}
+                  className='h-14 rounded-full pe-4 pl-12 text-lg'
+                  aria-label={labels.searchPlaceholder}
+                />
+                <Search className='text-muted-foreground absolute top-1/2 start-4 size-5 -translate-y-1/2' />
+                <Button
+                  size='lg'
+                  className='absolute top-1/2 end-2 h-10 -translate-y-1/2 cursor-pointer rounded-full px-6'
+                  onClick={handleSearch}
+                >
+                  {labels.searchLabel}
+                </Button>
+              </div>
+            )}
+
+            {(primaryCta || secondaryCta) && (
+              <div className='flex items-center gap-4'>
+                {primaryCta && (
+                  <CtaButton cta={primaryCta} className='h-10 cursor-pointer rounded-full px-4'>
+                    <span className='flex items-center gap-2'>
+                      {primaryCta.label}
+                      <ArrowRight />
+                    </span>
+                  </CtaButton>
+                )}
+                {secondaryCta && (
+                  <CtaButton cta={secondaryCta} variant='outline' className='h-10 cursor-pointer rounded-full px-4'>
+                    <span className='flex items-center gap-2'>
+                      <ShoppingBag />
+                      {secondaryCta.label}
+                    </span>
+                  </CtaButton>
+                )}
+              </div>
+            )}
+          </header>
+
+          {products.length > 0 && (
+            <div className='flex flex-col gap-4'>
+              <div className='relative h-[500px] w-full border-0'>
+                <Carousel
+                  className='group size-full'
+                  setApi={setApi}
+                  opts={{
+                    align: 'start',
+                    loop: true,
+                    duration: 20,
+                    skipSnaps: true,
+                  }}
+                >
+                  <CarouselContent className='h-full'>
+                    {products.map(product => (
+                      <CarouselItem key={product.id} className='h-full'>
+                        <ShowcaseSlide product={product} currency={currency} labels={labels} onBuyNow={onBuyNow} />
+                      </CarouselItem>
+                    ))}
+                  </CarouselContent>
+                </Carousel>
+              </div>
+
+              <div className='relative mt-8 flex justify-center gap-3'>
+                {products.map((product, index) => (
+                  <button
+                    key={product.id}
+                    type='button'
+                    onClick={() => {
+                      api?.scrollTo(index)
+                      setCurrentSlide(index)
+                    }}
+                    className={cn(
+                      'relative size-3 rounded-full transition-all',
+                      currentSlide === index ? 'bg-primary' : 'bg-foreground/20 hover:bg-foreground/40'
+                    )}
+                    aria-label={`Ir a la diapositiva ${index + 1}`}
+                    aria-current={currentSlide === index ? 'step' : undefined}
+                  />
+                ))}
+              </div>
+            </div>
+          )}
+        </div>
+      </div>
+    </section>
+  )
+}
+
+function EditorialPresentation({
+  title,
+  description,
+  badge,
+  titleAccent,
+  primaryCta,
+  secondaryCta,
+  shippingInfo,
+  departments,
+  featuredDeals,
+  storeLocator,
+  currency,
+  labels,
+  onDepartmentClick,
+  onShopNow,
+  onLocateStores,
+}: {
+  title: string
+  description: string
+  badge?: string
+  titleAccent?: string
+  primaryCta?: CTA
+  secondaryCta?: CTA
+  shippingInfo?: string
+  departments: HeroDepartment[]
+  featuredDeals: HeroFeaturedDeal[]
+  storeLocator?: HeroStoreLocator
+  currency?: string
+  labels: HeroLabels
+  onDepartmentClick?: (department: HeroDepartment) => void
+  onShopNow?: (item: HeroFeaturedDeal | HeroDeal) => void
+  onLocateStores?: () => void
+}) {
+  const departmentChipClasses = cn(
+    'flex flex-col items-center gap-4 rounded-lg p-2 text-center outline-none',
+    'transition-opacity hover:opacity-90 focus-visible:ring-2 focus-visible:ring-ring',
+  )
+
+  return (
+    <div className='bg-background relative overflow-hidden'>
+      <div className='relative z-10'>
+        <div className='mx-auto w-full max-w-7xl px-4 py-16 sm:px-6 lg:px-8 lg:py-20'>
+          <div className='mx-auto max-w-4xl text-center'>
+            <EditorialHeading title={title} titleAccent={titleAccent} badge={badge} />
+
+            <p className='text-muted-foreground mx-auto mt-6 max-w-2xl text-lg'>{description}</p>
+
+            {(primaryCta || secondaryCta) && (
+              <div className='mt-8 flex flex-wrap justify-center gap-4'>
+                {primaryCta && (
+                  <CtaButton cta={primaryCta} className='group h-10 cursor-pointer px-4 text-base'>
+                    {primaryCta.label}
+                    <ArrowRight className='transition-transform group-hover:translate-x-1' />
+                  </CtaButton>
+                )}
+                {secondaryCta && (
+                  <CtaButton cta={secondaryCta} variant='outline' className='group h-10 cursor-pointer px-4 text-base'>
+                    {secondaryCta.label}
+                  </CtaButton>
+                )}
+              </div>
+            )}
+
+            {shippingInfo && (
+              <div className='mt-6'>
+                <div className='bg-background/80 text-muted-foreground inline-flex items-center gap-2 rounded-full px-4 py-1.5 text-sm backdrop-blur-sm'>
+                  <MapPin className='text-primary size-4' aria-hidden='true' />
+                  <span>{shippingInfo}</span>
+                </div>
+              </div>
+            )}
+
+            {departments.length > 0 && (
+              <div className='mt-12 grid grid-cols-3 gap-8'>
+                {departments.map(department => {
+                  const chip = (
+                    <>
+                      {department.image && department.image.trim().length > 0 ? (
+                        <img
+                          src={department.image}
+                          alt={department.imageAlt ?? department.name}
+                          className='bg-card border-border size-16 rounded-full border object-cover'
+                          loading='lazy'
+                        />
+                      ) : null}
+                      <div>
+                        <div className='text-lg font-medium'>{department.name}</div>
+                        {department.count && (
+                          <div className='text-muted-foreground mt-1 text-sm'>{department.count}</div>
+                        )}
+                      </div>
+                    </>
+                  )
+
+                  if (department.href) {
+                    return (
+                      <a
+                        key={department.id}
+                        href={department.href}
+                        className={cn(departmentChipClasses, 'cursor-pointer')}
+                      >
+                        {chip}
+                      </a>
+                    )
+                  }
+
+                  return (
+                    <button
+                      key={department.id}
+                      type='button'
+                      onClick={onDepartmentClick ? () => onDepartmentClick(department) : undefined}
+                      className={cn(departmentChipClasses, 'cursor-pointer')}
+                    >
+                      {chip}
+                    </button>
+                  )
+                })}
+              </div>
+            )}
+
+            {featuredDeals.length > 0 && (
+              <div className='mt-16 grid gap-6 sm:grid-cols-2'>
+                {featuredDeals.map(deal => {
+                  const onSale = hasRealDiscount(deal)
+
+                  return (
+                    <Card key={deal.id} className='mx-auto h-full w-full overflow-hidden border-0 py-0 shadow-lg'>
+                      <CardContent className='p-0'>
+                        <div className='relative aspect-[3/2] overflow-hidden'>
+                          {deal.image && deal.image.trim().length > 0 ? (
+                            <img
+                              src={deal.image}
+                              alt={deal.imageAlt ?? deal.name}
+                              className='size-full object-cover object-center transition-transform duration-700 hover:scale-105'
+                              loading='lazy'
+                            />
+                          ) : null}
+                          <div className='from-background/90 via-background/30 absolute inset-0 bg-gradient-to-t to-transparent' />
+                          <div className='absolute inset-0 flex items-end p-8'>
+                            <div className='w-full'>
+                              <div className='bg-background/80 flex flex-col items-center justify-between gap-6 rounded-lg p-6 backdrop-blur-sm sm:flex-row sm:gap-8'>
+                                <div className='text-center sm:text-left'>
+                                  <h3 className='text-2xl font-bold tracking-tight sm:text-3xl'>{deal.name}</h3>
+                                  {deal.description && (
+                                    <p className='text-muted-foreground mt-1'>{deal.description}</p>
+                                  )}
+                                  <div className='mt-2 flex items-baseline justify-center gap-2 sm:justify-start'>
+                                    <span className='text-lg font-bold'>{formatAmount(deal.price, currency)}</span>
+                                    {onSale && (
+                                      <span className='text-muted-foreground text-sm line-through'>
+                                        {formatAmount(deal.originalPrice as number, currency)}
+                                      </span>
+                                    )}
+                                  </div>
+                                </div>
+                                {(deal.cta?.href || onShopNow) && (
+                                  <div className='flex-shrink-0'>
+                                    {deal.cta?.href ? (
+                                      <Button size='lg' className='group h-10 cursor-pointer px-4' asChild>
+                                        <a href={deal.cta.href}>
+                                          {deal.cta.label}
+                                          <ArrowRight className='transition-transform group-hover:translate-x-1' />
+                                        </a>
+                                      </Button>
+                                    ) : (
+                                      <Button
+                                        size='lg'
+                                        className='group h-10 cursor-pointer px-4'
+                                        onClick={() => onShopNow?.(deal)}
+                                      >
+                                        {deal.cta?.label ?? labels.shopNowLabel}
+                                        <ArrowRight className='transition-transform group-hover:translate-x-1' />
+                                      </Button>
+                                    )}
+                                  </div>
+                                )}
+                              </div>
+                            </div>
+                          </div>
+                        </div>
+                      </CardContent>
+                    </Card>
+                  )
+                })}
+              </div>
+            )}
+
+            {storeLocator && (
+              <div className='border-border/50 bg-background/50 mt-8 rounded-lg border p-6 backdrop-blur-sm'>
+                <div className='flex flex-col items-center gap-6 sm:flex-row sm:justify-between'>
+                  <div className='flex items-center gap-4'>
+                    <div className='bg-primary/10 text-primary flex size-12 items-center justify-center rounded-full'>
+                      <MapPin className='size-6' aria-hidden='true' />
+                    </div>
+                    <div className='text-start'>
+                      <h4 className='text-lg font-medium'>{storeLocator.title}</h4>
+                      <p className='text-muted-foreground'>{storeLocator.description}</p>
+                    </div>
+                  </div>
+                  {(storeLocator.ctaHref || onLocateStores) && (
+                    <div>
+                      {storeLocator.ctaHref ? (
+                        <Button variant='outline' className='h-9 cursor-pointer px-4 py-2 whitespace-nowrap' asChild>
+                          <a href={storeLocator.ctaHref}>{storeLocator.ctaLabel}</a>
+                        </Button>
+                      ) : (
+                        <Button
+                          variant='outline'
+                          className='h-9 cursor-pointer px-4 py-2 whitespace-nowrap'
+                          onClick={onLocateStores}
+                        >
+                          {storeLocator.ctaLabel}
+                        </Button>
+                      )}
+                    </div>
+                  )}
+                </div>
+              </div>
+            )}
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+function PromotionalPresentation({
+  title,
+  description,
+  badge,
+  titleAccent,
+  deals,
+  categories,
+  rotationInterval,
+  labels,
+  onShopNow,
+  onCategoryClick,
+}: {
+  title: string
+  description: string
+  badge?: string
+  titleAccent?: string
+  deals: HeroDeal[]
+  categories: HeroCategory[]
+  rotationInterval: number
+  labels: HeroLabels
+  onShopNow?: (item: HeroFeaturedDeal | HeroDeal) => void
+  onCategoryClick?: (category: HeroCategory) => void
+}) {
+  const reduceMotion = useReducedMotion()
+  const [currentDeal, setCurrentDeal] = useState(0)
+
+  useEffect(() => {
+    if (deals.length <= 1 || reduceMotion) return
+
+    const interval = setInterval(() => {
+      setCurrentDeal(prev => (prev + 1) % deals.length)
+    }, rotationInterval)
+
+    return () => clearInterval(interval)
+  }, [deals.length, reduceMotion, rotationInterval])
+
+  const deal = deals[currentDeal]
+
+  return (
+    <div className='relative'>
+      {deal && (
+        <header className='bg-primary text-primary-foreground sticky top-0 z-50 shadow-md'>
+          <div className='mx-auto w-full max-w-7xl px-4 py-2 sm:px-6 lg:px-8'>
+            <div className='flex items-center justify-center'>
+              <div className='flex w-full max-w-3xl items-center justify-center gap-4'>
+                <div className='flex items-center gap-2'>
+                  <Badge
+                    variant='secondary'
+                    className='bg-primary-foreground text-primary px-2.5 py-0.5 font-semibold'
+                  >
+                    {deal.title}
+                  </Badge>
+                  {deal.discount && <span className='font-semibold'>{deal.discount}</span>}
+                </div>
+                {deal.endTime && (
+                  <span className='hidden sm:inline'>
+                    {labels.endsInLabel} {deal.endTime}
+                  </span>
+                )}
+                {onShopNow && (
+                  <Button
+                    variant='link'
+                    size='sm'
+                    className='text-primary-foreground hover:text-primary-foreground/80 ml-auto h-8 cursor-pointer px-3 text-xs'
+                    onClick={() => onShopNow(deal)}
+                  >
+                    {labels.shopNowLabel} <ArrowRight />
+                  </Button>
+                )}
+              </div>
+            </div>
+          </div>
+        </header>
+      )}
+
+      <main className='mx-auto w-full max-w-7xl px-4 py-8 sm:px-6 lg:px-8'>
+        <div className='mb-12 text-center'>
+          {badge && (
+            <div className='relative inline-block'>
+              <Badge
+                variant='outline'
+                className='mb-4 flex h-auto items-center rounded-full px-3.5 py-1.5 text-sm font-normal'
+              >
+                {badge}
+              </Badge>
+            </div>
+          )}
+          <h1 className='text-4xl font-bold tracking-tight text-balance sm:text-5xl md:text-6xl'>
+            {title}
+            {titleAccent && (
+              <>
+                <br />
+                {titleAccent}
+              </>
+            )}
+          </h1>
+          <p className='text-muted-foreground mx-auto mt-4 max-w-2xl text-lg'>{description}</p>
+        </div>
+
+        {categories.length > 0 && (
+          <div className='grid gap-4 sm:grid-cols-2 lg:grid-cols-4'>
+            {categories.map(category => (
+              <Card key={category.id} className='group relative overflow-hidden py-0 transition-all duration-500'>
+                {category.image && category.image.trim().length > 0 ? (
+                  <img
+                    src={category.image}
+                    alt={category.imageAlt ?? category.name}
+                    className='aspect-4/5 size-full object-cover grayscale transition-all duration-500 hover:grayscale-0'
+                    width={400}
+                    height={500}
+                    loading='lazy'
+                  />
+                ) : (
+                  <div className='bg-muted aspect-4/5 size-full' />
+                )}
+                <CardContent className='absolute inset-x-0 bottom-0 p-4'>
+                  <div className='mt-1 flex items-center justify-between'>
+                    <div>
+                      <h2 className='text-background dark:text-foreground text-lg font-medium'>{category.name}</h2>
+                      {category.count && (
+                        <span className='text-background/80 dark:text-foreground/80 text-sm'>
+                          {category.count} {labels.productsLabel}
+                        </span>
+                      )}
+                    </div>
+                    {category.href ? (
+                      <Button
+                        variant='secondary'
+                        size='icon'
+                        className='h-9 w-9 cursor-pointer rounded-full backdrop-blur-xs'
+                        aria-label={`${labels.viewLabel} ${category.name}`}
+                        asChild
+                      >
+                        <a href={category.href}>
+                          <ArrowRight />
+                        </a>
+                      </Button>
+                    ) : onCategoryClick ? (
+                      <Button
+                        variant='secondary'
+                        size='icon'
+                        className='h-9 w-9 cursor-pointer rounded-full backdrop-blur-xs'
+                        aria-label={`${labels.viewLabel} ${category.name}`}
+                        onClick={() => onCategoryClick(category)}
+                      >
+                        <ArrowRight />
+                      </Button>
+                    ) : null}
+                  </div>
+                </CardContent>
+              </Card>
+            ))}
+          </div>
+        )}
+      </main>
+    </div>
+  )
+}
+
+export function StorefrontHero({
+  title,
+  description,
+  presentation = 'compact',
+  currency,
+  products,
+  badge,
+  titleAccent,
+  primaryCta,
+  secondaryCta,
+  heroImage,
+  onSearch,
+  departments = [],
+  featuredDeals = [],
+  storeLocator,
+  shippingInfo,
+  deals = [],
+  categories = [],
+  rotationInterval = 3000,
+  onAddToCart,
+  onBuyNow,
+  onSelectColor,
+  onDepartmentClick,
+  onShopNow,
+  onLocateStores,
+  onCategoryClick,
+  addToCartLabel = 'Agregar al carrito',
+  buyNowLabel,
+  newLabel = 'Nuevo',
+  outOfStockLabel = 'Agotado',
+  colorsLabel = 'Colores:',
+  discountSuffixLabel = '% OFF',
+  searchPlaceholder = 'Buscar productos...',
+  searchLabel = 'Buscar',
+  featuredDescription,
+  shopNowLabel = 'Comprar ahora',
+  endsInLabel = 'Termina en',
+  productsLabel = 'productos',
+  viewLabel = 'Ver',
+}: StorefrontHeroProps) {
+  // Presence-based, never label-language based: a host-supplied custom action
+  // label is a purchase affordance that must be handler-gated, while the
+  // block's own default label is a non-purchase detail affordance that may
+  // render without a handler (preserving the accepted default detail).
+  const resolvedBuyNowLabel = buyNowLabel ?? 'Ver producto'
+  const hasCustomBuyNowLabel = buyNowLabel !== undefined
+  const labels: HeroLabels = {
+    addToCartLabel,
+    buyNowLabel: resolvedBuyNowLabel,
+    newLabel,
+    outOfStockLabel,
+    colorsLabel,
+    discountSuffixLabel,
+    searchPlaceholder,
+    searchLabel,
+    featuredDescription,
+    shopNowLabel,
+    endsInLabel,
+    productsLabel,
+    viewLabel,
+  }
+
+  if (presentation === 'showcase') {
+    return (
+      <ShowcasePresentation
+        title={title}
+        description={description}
+        products={products}
+        badge={badge}
+        primaryCta={primaryCta}
+        secondaryCta={secondaryCta}
+        currency={currency}
+        labels={labels}
+        onSearch={onSearch}
+        onBuyNow={onBuyNow}
+        rotationInterval={rotationInterval}
+      />
+    )
+  }
+
+  if (presentation === 'editorial') {
+    return (
+      <EditorialPresentation
+        title={title}
+        description={description}
+        badge={badge}
+        titleAccent={titleAccent}
+        primaryCta={primaryCta}
+        secondaryCta={secondaryCta}
+        shippingInfo={shippingInfo}
+        departments={departments}
+        featuredDeals={featuredDeals}
+        storeLocator={storeLocator}
+        currency={currency}
+        labels={labels}
+        onDepartmentClick={onDepartmentClick}
+        onShopNow={onShopNow}
+        onLocateStores={onLocateStores}
+      />
+    )
+  }
+
+  if (presentation === 'promotional') {
+    return (
+      <PromotionalPresentation
+        title={title}
+        description={description}
+        badge={badge}
+        titleAccent={titleAccent}
+        deals={deals}
+        categories={categories}
+        rotationInterval={rotationInterval}
+        labels={labels}
+        onShopNow={onShopNow}
+        onCategoryClick={onCategoryClick}
+      />
+    )
+  }
+
+  return (
+    <CompactPresentation
+      title={title}
+      description={description}
+      products={products}
+      badge={badge}
+      titleAccent={titleAccent}
+      primaryCta={primaryCta}
+      secondaryCta={secondaryCta}
+      heroImage={heroImage}
+      currency={currency}
+      labels={labels}
+      onAddToCart={onAddToCart}
+      onBuyNow={onBuyNow}
+      onSelectColor={onSelectColor}
+      hasCustomBuyNowLabel={hasCustomBuyNowLabel}
+    />
+  )
+}
+
+export default StorefrontHero