@thorprovider/blocks 0.1.2 → 1.0.0

package/src/blocks/e-commerce/product-overview/product-overview.tsx

@@ -0,0 +1,1186 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import { Camera, Check, Heart, Info, MessageSquare, Minus, Package, Plus, Share2, ShoppingCart, Star, Truck } from 'lucide-react'
+import type { Image, Money, ProductOption, SelectedOption } from '@thorprovider/types'
+import { Button } from '../../../ui/button'
+import { Card, CardContent } from '../../../ui/card'
+import { Separator } from '../../../ui/separator'
+import { cn } from '../../../lib/utils'
+import { PRODUCT_IMAGE_FALLBACK } from '../../../lib/contracts'
+import { formatMoney, isAvailableMoney } from '../../../lib/money'
+import { ReactionToggle } from '../../shared/reaction-toggle'
+import { Carousel, CarouselContent, CarouselItem, type CarouselApi } from '../../../ui/carousel'
+import { ProductOverviewGallery } from './product-overview-gallery'
+import { ProductOverviewLightboxTab } from './product-overview-lightbox-tab'
+import { ProductOverviewReviewsTab, type ProductOverviewReview } from './product-overview-reviews-tab'
+import {
+  ProductOverviewTabs,
+  ProductOverviewTabsContentFade,
+  ProductOverviewTabsIndicator,
+  ProductOverviewTabsList,
+  ProductOverviewTabsTrigger,
+} from './product-overview-tabs'
+
+/**
+ * Canonical product-detail projection.
+ *
+ * The block consumes the canonical `@thorprovider/types` shapes (`Money`,
+ * `ProductOption`, `SelectedOption`, `Image`) so adapter output maps without a
+ * second, drifting product type. The only deviation is `price`: the canon marks
+ * it required, but a missing/unresolved backend price is a real, distinct state
+ * that must disable purchase — so the projection allows `price` to be absent
+ * and the block treats absence as "unavailable", never as zero.
+ */
+export interface ProductDetailVariant {
+  id: string
+  title: string
+  sku?: string
+  availableForSale: boolean
+  selectedOptions: SelectedOption[]
+  /** Canonical Money; omit/null when the backend has no resolved price. */
+  price?: Money | null
+  compareAtPrice?: Money
+  image?: Image
+}
+
+export interface ProductDetailProduct {
+  id: string
+  handle?: string
+  title: string
+  description?: string
+  vendor?: string
+  options: ProductOption[]
+  variants: ProductDetailVariant[]
+  images: Image[]
+  featuredImage?: Image
+}
+
+export interface ProductOverviewRating {
+  value: number
+  count: number
+}
+
+/**
+ * The bounded presentation surface. `standard` is the straightforward detail
+ * layout, `gallery` is image-forward, and `rich` adds tabbed overview/specs/
+ * reviews/gallery. The value changes structure, never the data contract.
+ */
+export type ProductOverviewPresentation = 'standard' | 'gallery' | 'rich'
+
+export interface ProductOverviewProps {
+  product: ProductDetailProduct
+  /** Bounded presentation option; defaults to `standard`. */
+  presentation?: ProductOverviewPresentation
+  /** Controlled selection: the backend variant id, or null/undefined when nothing is explicitly selected. */
+  selectedVariantId?: string | null
+  onSelectVariant?: (variantId: string) => void
+  /** Controlled quantity for the add-to-cart action; defaults to 1 when omitted. */
+  quantity?: number
+  onQuantityChange?: (quantity: number) => void
+  /** Add-to-cart identity is the selected backend variant id, with the requested quantity. */
+  onAddToCart?: (variantId: string, quantity: number) => void
+  isWishlisted?: boolean
+  onToggleWishlist?: (variantId: string, isWishlisted: boolean) => void
+  /** Optional share action (used by the `rich` presentation). */
+  onShare?: () => void
+  /** Rendered only when the backend supplies it. */
+  rating?: ProductOverviewRating
+  /** Rendered only when the backend supplies it. */
+  deliveryEstimate?: string
+  /** Rendered only when the backend supplies it. */
+  shipping?: Money
+  formatPrice?: (money: Money) => string
+  /** `rich`-only optional data. Omitted sections render no chrome. */
+  specifications?: Record<string, string>
+  /** `rich`-only optional data. Omitted sections render no chrome. */
+  features?: string[]
+  /** `rich`-only optional data. Omitted sections render no chrome. */
+  reviews?: ProductOverviewReview[]
+  sizesLabel?: string
+  variantLabel?: string
+  reviewsLabel?: string
+  addToCartLabel?: string
+  outOfStockLabel?: string
+  unavailablePriceLabel?: string
+  selectVariantLabel?: string
+  quantityLabel?: string
+  deliveryEstimateLabel?: string
+  shippingLabel?: string
+  removeFromWishlistLabel?: string
+  addToWishlistLabel?: string
+  imageFallback?: string
+  /** `gallery`/`rich` labels. */
+  badgeLabel?: string
+  availabilityLabel?: string
+  skuLabel?: string
+  overviewLabel?: string
+  specsLabel?: string
+  featuresLabel?: string
+  specificationsLabel?: string
+  galleryLabel?: string
+  photosLabel?: string
+  saveLabel?: string
+  savedLabel?: string
+  shareLabel?: string
+  basedOnReviewsLabel?: string
+  foundHelpfulLabel?: string
+  ofCounterLabel?: string
+  freeDeliveryLabel?: string
+}
+
+export function variantLabelOf(variant: ProductDetailVariant): string {
+  if (variant.title.trim() !== '') return variant.title
+  return variant.selectedOptions.map(option => option.value).join(' / ')
+}
+
+/**
+ * The add-to-cart payload contract: the explicitly selected backend variant id
+ * and a positive quantity (defaults to 1). Returns `null` when no variant has
+ * been selected — the block never substitutes the first variant.
+ */
+export function resolveAddToCartPayload(
+  variant: ProductDetailVariant | null,
+  quantity: number | undefined,
+): { variantId: string; quantity: number } | null {
+  if (!variant) return null
+  return {
+    variantId: variant.id,
+    quantity: typeof quantity === 'number' && quantity > 0 ? quantity : 1,
+  }
+}
+
+export function galleryImages(product: ProductDetailProduct, fallback: string): string[] {
+  const images = product.images
+    .map(image => image.url)
+    .filter((url): url is string => typeof url === 'string' && url.trim() !== '')
+  if (images.length > 0) return images
+  const featured = product.featuredImage?.url
+  if (typeof featured === 'string' && featured.trim() !== '') return [featured]
+  return [fallback]
+}
+
+interface ResolvedSelection {
+  selectedVariant: ProductDetailVariant | null
+  selectedPrice: Money | null | undefined
+  selectedCompareAt: Money | undefined
+  priceAvailable: boolean
+  compareAtAvailable: boolean
+  canPurchase: boolean
+  quantityValue: number
+  addPayload: { variantId: string; quantity: number } | null
+}
+
+export default function ProductOverview({
+  product,
+  presentation = 'standard',
+  selectedVariantId,
+  onSelectVariant,
+  quantity,
+  onQuantityChange,
+  onAddToCart,
+  isWishlisted = false,
+  onToggleWishlist,
+  onShare,
+  rating,
+  deliveryEstimate,
+  shipping,
+  formatPrice,
+  specifications,
+  features,
+  reviews,
+  sizesLabel = 'Variantes',
+  variantLabel = 'Variante',
+  reviewsLabel = 'Reseñas',
+  addToCartLabel = 'Agregar al carrito',
+  outOfStockLabel = 'Agotado',
+  unavailablePriceLabel = 'Precio no disponible',
+  selectVariantLabel = 'Selecciona una variante',
+  quantityLabel = 'Cantidad',
+  deliveryEstimateLabel = 'Entrega estimada',
+  shippingLabel = 'Envío',
+  removeFromWishlistLabel = 'Quitar de favoritos',
+  addToWishlistLabel = 'Agregar a favoritos',
+  imageFallback = PRODUCT_IMAGE_FALLBACK,
+  badgeLabel,
+  availabilityLabel = 'Disponible',
+  skuLabel = 'SKU',
+  overviewLabel = 'Resumen',
+  specsLabel = 'Especificaciones',
+  featuresLabel = 'Características clave',
+  specificationsLabel = 'Especificaciones técnicas',
+  galleryLabel = 'Galería',
+  photosLabel = 'fotos',
+  saveLabel = 'Guardar',
+  savedLabel = 'Guardado',
+  shareLabel = 'Compartir',
+  basedOnReviewsLabel = 'Basado en {count} reseñas',
+  foundHelpfulLabel = '{count} personas encontraron esto útil',
+  ofCounterLabel = '{current} de {total}',
+  freeDeliveryLabel,
+}: ProductOverviewProps) {
+  const [selectedImage, setSelectedImage] = useState(0)
+  const [carouselApi, setCarouselApi] = useState<CarouselApi>()
+
+  useEffect(() => {
+    if (!carouselApi) return
+    carouselApi.scrollTo(selectedImage)
+    const handleSelect = () => setSelectedImage(carouselApi.selectedScrollSnap())
+    carouselApi.on('select', handleSelect)
+    return () => {
+      carouselApi.off('select', handleSelect)
+    }
+  }, [carouselApi, selectedImage])
+
+  const selectedVariant =
+    selectedVariantId != null
+      ? product.variants.find(variant => variant.id === selectedVariantId) ?? null
+      : null
+
+  const selectedPrice = selectedVariant?.price
+  const selectedCompareAt = selectedVariant?.compareAtPrice
+  const priceAvailable = isAvailableMoney(selectedPrice)
+  const compareAtAvailable = isAvailableMoney(selectedCompareAt)
+  const canPurchase = Boolean(selectedVariant?.availableForSale) && priceAvailable
+  const quantityValue = quantity ?? 1
+  const addPayload = resolveAddToCartPayload(selectedVariant, quantityValue)
+
+  const images = galleryImages(product, imageFallback)
+  const hasRealImages = images[0] !== imageFallback || product.featuredImage != null
+  const activeImage = images[Math.min(selectedImage, images.length - 1)]
+
+  const selection: ResolvedSelection = {
+    selectedVariant,
+    selectedPrice,
+    selectedCompareAt,
+    priceAvailable,
+    compareAtAvailable,
+    canPurchase,
+    quantityValue,
+    addPayload,
+  }
+
+  const handleAddToCart = () => {
+    if (onAddToCart && addPayload) onAddToCart(addPayload.variantId, addPayload.quantity)
+  }
+  const handleToggleWishlist = () => {
+    if (!selectedVariant || !onToggleWishlist) return
+    onToggleWishlist(selectedVariant.id, !isWishlisted)
+  }
+
+  if (presentation === 'gallery') {
+    return (
+      <GalleryPresentation
+        product={product}
+        selection={selection}
+        images={images}
+        activeImage={activeImage}
+        selectedImage={selectedImage}
+        onSelectImage={setSelectedImage}
+        setCarouselApi={setCarouselApi}
+        onSelectVariant={onSelectVariant}
+        onQuantityChange={onQuantityChange}
+        onAddToCart={handleAddToCart}
+        isWishlisted={isWishlisted}
+        onToggleWishlist={onToggleWishlist ? handleToggleWishlist : undefined}
+        rating={rating}
+        formatPrice={formatPrice}
+        labels={{
+          reviewsLabel,
+          addToCartLabel,
+          outOfStockLabel,
+          unavailablePriceLabel,
+          selectVariantLabel,
+          quantityLabel,
+          removeFromWishlistLabel,
+          addToWishlistLabel,
+          freeDeliveryLabel,
+        }}
+      />
+    )
+  }
+
+  if (presentation === 'rich') {
+    return (
+      <RichPresentation
+        product={product}
+        selection={selection}
+        images={images}
+        selectedImage={selectedImage}
+        onSelectImage={setSelectedImage}
+        onSelectVariant={onSelectVariant}
+        onQuantityChange={onQuantityChange}
+        onAddToCart={handleAddToCart}
+        isWishlisted={isWishlisted}
+        onToggleWishlist={onToggleWishlist ? handleToggleWishlist : undefined}
+        onShare={onShare}
+        rating={rating}
+        formatPrice={formatPrice}
+        specifications={specifications}
+        features={features}
+        reviews={reviews}
+        labels={{
+          reviewsLabel,
+          addToCartLabel,
+          outOfStockLabel,
+          unavailablePriceLabel,
+          selectVariantLabel,
+          quantityLabel,
+          removeFromWishlistLabel,
+          addToWishlistLabel,
+          badgeLabel,
+          availabilityLabel,
+          skuLabel,
+          overviewLabel,
+          specsLabel,
+          featuresLabel,
+          specificationsLabel,
+          galleryLabel,
+          photosLabel,
+          saveLabel,
+          savedLabel,
+          shareLabel,
+          basedOnReviewsLabel,
+          foundHelpfulLabel,
+          ofCounterLabel,
+        }}
+      />
+    )
+  }
+
+  return (
+    <StandardPresentation
+      product={product}
+      selection={selection}
+      images={images}
+      activeImage={activeImage}
+      selectedImage={selectedImage}
+      onSelectImage={setSelectedImage}
+      onSelectVariant={onSelectVariant}
+      onQuantityChange={onQuantityChange}
+      onAddToCart={handleAddToCart}
+      isWishlisted={isWishlisted}
+      onToggleWishlist={onToggleWishlist ? handleToggleWishlist : undefined}
+      rating={rating}
+      deliveryEstimate={deliveryEstimate}
+      shipping={shipping}
+      formatPrice={formatPrice}
+      hasRealImages={hasRealImages}
+      labels={{
+        sizesLabel,
+        variantLabel,
+        reviewsLabel,
+        addToCartLabel,
+        outOfStockLabel,
+        unavailablePriceLabel,
+        selectVariantLabel,
+        quantityLabel,
+        deliveryEstimateLabel,
+        shippingLabel,
+        removeFromWishlistLabel,
+        addToWishlistLabel,
+      }}
+    />
+  )
+}
+
+interface SharedLabels {
+  reviewsLabel: string
+  addToCartLabel: string
+  outOfStockLabel: string
+  unavailablePriceLabel: string
+  selectVariantLabel: string
+  quantityLabel: string
+  removeFromWishlistLabel: string
+  addToWishlistLabel: string
+}
+
+function VariantSelector({
+  product,
+  selectedVariantId,
+  onSelectVariant,
+  sizesLabel,
+  variantLabel,
+  outOfStockLabel,
+}: {
+  product: ProductDetailProduct
+  selectedVariantId?: string | null
+  onSelectVariant?: (variantId: string) => void
+  sizesLabel: string
+  variantLabel: string
+  outOfStockLabel: string
+}) {
+  if (product.variants.length === 0) return null
+  return (
+    <div className='flex flex-col gap-2'>
+      <h3 className='font-bold'>{sizesLabel}</h3>
+      <div className='flex flex-wrap gap-3'>
+        {product.variants.map(variant => {
+          const isSelected = variant.id === selectedVariantId
+          return (
+            <Button
+              key={variant.id}
+              variant={isSelected ? 'default' : 'outline'}
+              onClick={onSelectVariant ? () => onSelectVariant(variant.id) : undefined}
+              disabled={!variant.availableForSale}
+              aria-pressed={isSelected}
+              className='h-9 cursor-pointer rounded-full px-4'
+            >
+              {variantLabelOf(variant)}
+              {!variant.availableForSale ? (
+                <span className='text-muted-foreground ms-2 text-xs font-normal'>{outOfStockLabel}</span>
+              ) : null}
+            </Button>
+          )
+        })}
+      </div>
+      {variantLabel ? (
+        <span className='sr-only'>{variantLabel}</span>
+      ) : null}
+    </div>
+  )
+}
+
+function QuantityStepper({
+  quantityValue,
+  quantityLabel,
+  onQuantityChange,
+}: {
+  quantityValue: number
+  quantityLabel: string
+  onQuantityChange: (quantity: number) => void
+}) {
+  return (
+    <div className='flex flex-col gap-2'>
+      <h3 className='font-bold'>{quantityLabel}</h3>
+      <div className='border-border flex w-fit items-center rounded-md border'>
+        <Button
+          type='button'
+          variant='ghost'
+          size='icon'
+          className='size-9 rounded-r-none'
+          aria-label={`${quantityLabel} -1`}
+          onClick={() => onQuantityChange(Math.max(1, quantityValue - 1))}
+          disabled={quantityValue <= 1}
+        >
+          <Minus />
+        </Button>
+        <span className='w-10 text-center text-sm tabular-nums'>{quantityValue}</span>
+        <Button
+          type='button'
+          variant='ghost'
+          size='icon'
+          className='size-9 rounded-l-none'
+          aria-label={`${quantityLabel} +1`}
+          onClick={() => onQuantityChange(quantityValue + 1)}
+        >
+          <Plus />
+        </Button>
+      </div>
+    </div>
+  )
+}
+
+function WishlistButton({
+  isWishlisted,
+  disabled,
+  onToggleWishlist,
+  removeFromWishlistLabel,
+  addToWishlistLabel,
+  className,
+}: {
+  isWishlisted: boolean
+  disabled: boolean
+  onToggleWishlist?: () => void
+  removeFromWishlistLabel: string
+  addToWishlistLabel: string
+  className?: string
+}) {
+  // Purpose-gated: no wishlist handler means no wishlist affordance. A visible
+  // button that does nothing is a dead control, so it is not rendered at all.
+  if (!onToggleWishlist) return null
+  return (
+    <Button
+      variant='outline'
+      size='icon'
+      className={cn('cursor-pointer', className)}
+      disabled={disabled}
+      onClick={onToggleWishlist}
+      aria-pressed={isWishlisted}
+      aria-label={isWishlisted ? removeFromWishlistLabel : addToWishlistLabel}
+    >
+      <ReactionToggle
+        active={isWishlisted}
+        icon={Heart}
+        iconClassName='size-5'
+        activeColorClassName='text-primary'
+      />
+    </Button>
+  )
+}
+
+function StandardPresentation({
+  product,
+  selection,
+  images,
+  activeImage,
+  selectedImage,
+  onSelectImage,
+  onSelectVariant,
+  onQuantityChange,
+  onAddToCart,
+  isWishlisted,
+  onToggleWishlist,
+  rating,
+  deliveryEstimate,
+  shipping,
+  formatPrice,
+  hasRealImages,
+  labels,
+}: {
+  product: ProductDetailProduct
+  selection: ResolvedSelection
+  images: string[]
+  activeImage: string
+  selectedImage: number
+  onSelectImage: (index: number) => void
+  onSelectVariant?: (variantId: string) => void
+  onQuantityChange?: (quantity: number) => void
+  onAddToCart: () => void
+  isWishlisted: boolean
+  onToggleWishlist?: () => void
+  rating?: ProductOverviewRating
+  deliveryEstimate?: string
+  shipping?: Money
+  formatPrice?: (money: Money) => string
+  hasRealImages: boolean
+  labels: SharedLabels & {
+    sizesLabel: string
+    variantLabel: string
+    deliveryEstimateLabel: string
+    shippingLabel: string
+  }
+}) {
+  const { selectedVariant, selectedPrice, selectedCompareAt, priceAvailable, compareAtAvailable, canPurchase, quantityValue } =
+    selection
+
+  return (
+    <div>
+      <section className='@container mx-auto w-full max-w-7xl px-4 sm:px-6 lg:px-8'>
+        <div className='grid grid-cols-1 gap-6 py-4 lg:grid-cols-2 lg:gap-8 lg:py-6 xl:grid-cols-3 xl:gap-12 xl:py-12'>
+          <div className='flex flex-col justify-between gap-6 lg:gap-8'>
+            <div className='flex flex-col gap-2 lg:gap-4'>
+              {product.vendor ? (
+                <span className='text-sm font-semibold tracking-wide uppercase'>{product.vendor}</span>
+              ) : null}
+              <h2 className='text-xl font-bold tracking-tight text-balance lg:text-3xl'>{product.title}</h2>
+              {product.description ? (
+                <p className='text-muted-foreground text-balance'>{product.description}</p>
+              ) : null}
+
+              {selectedVariant ? (
+                priceAvailable ? (
+                  <p className='text-2xl font-bold tracking-tight'>
+                    {formatMoney(selectedPrice, formatPrice)}
+                    {compareAtAvailable ? (
+                      <span className='text-muted-foreground ms-2 text-base font-normal line-through'>
+                        {formatMoney(selectedCompareAt, formatPrice)}
+                      </span>
+                    ) : null}
+                  </p>
+                ) : (
+                  <p className='text-muted-foreground text-sm'>{labels.unavailablePriceLabel}</p>
+                )
+              ) : (
+                <p className='text-muted-foreground text-sm'>{labels.selectVariantLabel}</p>
+              )}
+            </div>
+
+            {hasRealImages ? (
+              <div className='flex flex-wrap gap-4'>
+                {images.map((url, index) => (
+                  <button
+                    key={`${product.id}:image:${index}`}
+                    type='button'
+                    onClick={() => onSelectImage(index)}
+                    aria-label={`${product.title} ${index + 1}`}
+                    aria-pressed={selectedImage === index}
+                    className={cn(
+                      'ring-offset-background size-16 cursor-pointer overflow-hidden rounded-sm ring-offset-2 transition-all lg:size-18',
+                      selectedImage === index && 'ring-foreground ring-2',
+                    )}
+                  >
+                    <img src={url || undefined} alt='' className='size-full object-cover' />
+                  </button>
+                ))}
+              </div>
+            ) : null}
+          </div>
+
+          <div className='row-span-2 row-start-1 lg:col-start-2'>
+            <div className='bg-muted aspect-square w-full overflow-hidden rounded-lg'>
+              <img src={activeImage || undefined} alt={product.title} className='h-90 w-full object-cover' />
+            </div>
+          </div>
+
+          <div className='flex flex-col gap-6 lg:gap-10'>
+            <VariantSelector
+              product={product}
+              selectedVariantId={selectedVariant?.id}
+              onSelectVariant={onSelectVariant}
+              sizesLabel={labels.sizesLabel}
+              variantLabel={labels.variantLabel}
+              outOfStockLabel={labels.outOfStockLabel}
+            />
+
+            {selectedVariant && selectedVariant.selectedOptions.length > 0 ? (
+              <p className='text-muted-foreground text-sm'>
+                {selectedVariant.selectedOptions
+                  .map((option: SelectedOption) => `${option.name}: ${option.value}`)
+                  .join(' · ')}
+              </p>
+            ) : null}
+
+            {rating ? (
+              <div className='flex flex-col gap-2'>
+                <h3 className='font-bold'>{labels.reviewsLabel}</h3>
+                <div className='flex items-center gap-2'>
+                  <div className='flex gap-1' aria-hidden='true'>
+                    {[0, 1, 2, 3, 4].map(index => (
+                      <Star
+                        key={index}
+                        className='text-foreground size-5'
+                        fill={index < rating.value ? 'currentColor' : 'none'}
+                      />
+                    ))}
+                  </div>
+                  <span className='text-muted-foreground text-sm tabular-nums'>
+                    {`${rating.value} (${rating.count})`}
+                  </span>
+                </div>
+              </div>
+            ) : null}
+
+            {onQuantityChange ? (
+              <QuantityStepper
+                quantityValue={quantityValue}
+                quantityLabel={labels.quantityLabel}
+                onQuantityChange={onQuantityChange}
+              />
+            ) : null}
+
+            {deliveryEstimate || shipping ? (
+              <dl className='text-muted-foreground flex flex-col gap-1 text-sm'>
+                {deliveryEstimate ? (
+                  <div className='flex gap-2'>
+                    <dt>{labels.deliveryEstimateLabel}</dt>
+                    <dd className='text-foreground'>{deliveryEstimate}</dd>
+                  </div>
+                ) : null}
+                {isAvailableMoney(shipping) ? (
+                  <div className='flex gap-2'>
+                    <dt>{labels.shippingLabel}</dt>
+                    <dd className='text-foreground'>{formatMoney(shipping, formatPrice)}</dd>
+                  </div>
+                ) : null}
+              </dl>
+            ) : null}
+
+            <div className='flex gap-4'>
+              <Button
+                className='h-10 flex-1 cursor-pointer rounded-full px-8'
+                size='lg'
+                disabled={!canPurchase}
+                onClick={onAddToCart}
+              >
+                {labels.addToCartLabel}
+              </Button>
+              <WishlistButton
+                isWishlisted={isWishlisted}
+                disabled={!selectedVariant}
+                onToggleWishlist={onToggleWishlist}
+                removeFromWishlistLabel={labels.removeFromWishlistLabel}
+                addToWishlistLabel={labels.addToWishlistLabel}
+                className='size-9 rounded-full'
+              />
+            </div>
+          </div>
+        </div>
+      </section>
+    </div>
+  )
+}
+
+function GalleryPresentation({
+  product,
+  selection,
+  images,
+  activeImage,
+  selectedImage,
+  onSelectImage,
+  setCarouselApi,
+  onSelectVariant,
+  onQuantityChange,
+  onAddToCart,
+  isWishlisted,
+  onToggleWishlist,
+  rating,
+  formatPrice,
+  labels,
+}: {
+  product: ProductDetailProduct
+  selection: ResolvedSelection
+  images: string[]
+  activeImage: string
+  selectedImage: number
+  onSelectImage: (index: number) => void
+  setCarouselApi: (api: CarouselApi | undefined) => void
+  onSelectVariant?: (variantId: string) => void
+  onQuantityChange?: (quantity: number) => void
+  onAddToCart: () => void
+  isWishlisted: boolean
+  onToggleWishlist?: () => void
+  rating?: ProductOverviewRating
+  formatPrice?: (money: Money) => string
+  labels: SharedLabels & { freeDeliveryLabel?: string }
+}) {
+  const { selectedVariant, selectedPrice, selectedCompareAt, priceAvailable, compareAtAvailable, canPurchase, quantityValue } =
+    selection
+
+  return (
+    <section className='mx-auto w-full max-w-7xl px-4 sm:px-6 lg:px-8'>
+      <div className='grid grid-cols-1 gap-8 py-4 md:py-6 lg:grid-cols-2 lg:py-12'>
+        <div className='flex flex-col gap-4'>
+          <Carousel setApi={setCarouselApi} className='w-full'>
+            <CarouselContent>
+              {images.map((url, index) => (
+                <CarouselItem key={`${product.id}:carousel:${index}`}>
+                  <div className='bg-muted flex h-130 w-full items-center justify-center overflow-hidden rounded-lg'>
+                    <img src={url || undefined} alt={`${product.title} ${index + 1}`} className='h-full w-full object-cover' />
+                  </div>
+                </CarouselItem>
+              ))}
+            </CarouselContent>
+          </Carousel>
+
+          <div className='flex flex-wrap gap-4'>
+            {images.map((url, index) => (
+              <button
+                type='button'
+                key={`${product.id}:thumb:${index}`}
+                onClick={() => onSelectImage(index)}
+                aria-label={`Mostrar imagen ${index + 1} de ${product.title}`}
+                aria-pressed={selectedImage === index}
+                className='aspect-square size-16 cursor-pointer'
+              >
+                <img
+                  src={url || undefined}
+                  alt={`${product.title} ${index + 1}`}
+                  className={cn(
+                    'size-full cursor-pointer rounded-md object-cover ring-offset-2 transition-all',
+                    selectedImage === index ? 'ring-foreground ring-2' : '',
+                  )}
+                />
+              </button>
+            ))}
+          </div>
+        </div>
+
+        <div className='flex flex-col gap-6'>
+          <header className='flex flex-col gap-4'>
+            <div className='flex items-center'>
+              <Button variant='ghost' size='icon' className='bg-primary size-6 scale-75 cursor-pointer rounded-full'>
+                <Check className='text-primary-foreground size-4' />
+              </Button>
+              {product.vendor ? <span className='ms-2 font-medium'>{product.vendor}</span> : null}
+              {selectedVariant?.sku ? (
+                <span className='text-muted-foreground ms-auto'>{selectedVariant.sku}</span>
+              ) : null}
+            </div>
+            <h1 className='text-xl font-bold text-balance xl:text-3xl'>{product.title}</h1>
+
+            {rating ? (
+              <div className='flex items-center gap-2'>
+                <div className='flex'>
+                  {[0, 1, 2, 3, 4].map(i => (
+                    <Star
+                      key={i}
+                      className={cn(
+                        'size-5',
+                        i < rating.value ? 'fill-foreground text-foreground' : 'text-muted-foreground',
+                      )}
+                    />
+                  ))}
+                </div>
+                <span className='text-muted-foreground text-sm'>
+                  {rating.count} {labels.reviewsLabel}
+                </span>
+              </div>
+            ) : null}
+          </header>
+
+          {selectedVariant ? (
+            priceAvailable ? (
+              <p className='text-4xl font-bold'>
+                {formatMoney(selectedPrice, formatPrice)}
+                {compareAtAvailable ? (
+                  <span className='text-muted-foreground ms-2 text-xl font-normal line-through'>
+                    {formatMoney(selectedCompareAt, formatPrice)}
+                  </span>
+                ) : null}
+              </p>
+            ) : (
+              <p className='text-muted-foreground text-sm'>{labels.unavailablePriceLabel}</p>
+            )
+          ) : (
+            <p className='text-muted-foreground text-sm'>{labels.selectVariantLabel}</p>
+          )}
+
+          <VariantSelector
+            product={product}
+            selectedVariantId={selectedVariant?.id}
+            onSelectVariant={onSelectVariant}
+            sizesLabel={labels.selectVariantLabel}
+            variantLabel=''
+            outOfStockLabel={labels.outOfStockLabel}
+          />
+
+          {onQuantityChange ? (
+            <QuantityStepper
+              quantityValue={quantityValue}
+              quantityLabel={labels.quantityLabel}
+              onQuantityChange={onQuantityChange}
+            />
+          ) : null}
+
+          <div className='flex gap-4'>
+            <Button className='h-12 flex-1 cursor-pointer rounded-md' size='lg' disabled={!canPurchase} onClick={onAddToCart}>
+              <ShoppingCart />
+              {labels.addToCartLabel}
+            </Button>
+            <WishlistButton
+              isWishlisted={isWishlisted}
+              disabled={!selectedVariant}
+              onToggleWishlist={onToggleWishlist}
+              removeFromWishlistLabel={labels.removeFromWishlistLabel}
+              addToWishlistLabel={labels.addToWishlistLabel}
+              className='border-input size-12 rounded-md'
+            />
+          </div>
+
+          {labels.freeDeliveryLabel ? (
+            <div className='text-muted-foreground flex items-center justify-center gap-2 text-sm'>
+              <Truck className='size-4' />
+              <span>{labels.freeDeliveryLabel}</span>
+            </div>
+          ) : null}
+        </div>
+      </div>
+    </section>
+  )
+}
+
+function RichPresentation({
+  product,
+  selection,
+  images,
+  selectedImage,
+  onSelectImage,
+  onSelectVariant,
+  onQuantityChange,
+  onAddToCart,
+  isWishlisted,
+  onToggleWishlist,
+  onShare,
+  rating,
+  formatPrice,
+  specifications,
+  features,
+  reviews,
+  labels,
+}: {
+  product: ProductDetailProduct
+  selection: ResolvedSelection
+  images: string[]
+  selectedImage: number
+  onSelectImage: (index: number) => void
+  onSelectVariant?: (variantId: string) => void
+  onQuantityChange?: (quantity: number) => void
+  onAddToCart: () => void
+  isWishlisted: boolean
+  onToggleWishlist?: () => void
+  onShare?: () => void
+  rating?: ProductOverviewRating
+  formatPrice?: (money: Money) => string
+  specifications?: Record<string, string>
+  features?: string[]
+  reviews?: ProductOverviewReview[]
+  labels: SharedLabels & {
+    badgeLabel?: string
+    availabilityLabel: string
+    skuLabel: string
+    overviewLabel: string
+    specsLabel: string
+    featuresLabel: string
+    specificationsLabel: string
+    galleryLabel: string
+    photosLabel: string
+    saveLabel: string
+    savedLabel: string
+    shareLabel: string
+    basedOnReviewsLabel: string
+    foundHelpfulLabel: string
+    ofCounterLabel: string
+  }
+}) {
+  const { selectedVariant, selectedPrice, selectedCompareAt, priceAvailable, compareAtAvailable, canPurchase, quantityValue } =
+    selection
+
+  const featureList = features && features.length > 0 ? features : undefined
+  const specEntries = specifications ? Object.entries(specifications) : []
+  const hasSpecs = specEntries.length > 0
+  const hasReviews = Boolean(reviews && reviews.length > 0)
+  const hasGallery = images.length > 1
+  const hasTabs = Boolean(featureList) || hasSpecs || hasReviews || hasGallery
+  const reviewCount = reviews?.length ?? 0
+
+  // The initial tab is computed once and frozen: Base UI's uncontrolled Tabs warns if
+  // `defaultValue` changes after mount, and this expression tracks the data-derived tab set
+  // (which changes when optional props like `specifications` appear or disappear).
+  const [defaultTab] = useState(() =>
+    featureList ? 'overview' : hasSpecs ? 'specs' : hasReviews ? 'reviews' : 'gallery',
+  )
+
+  return (
+    <section className='py-12'>
+      <div className='mx-auto w-full max-w-7xl px-4 sm:px-6 lg:px-8'>
+        <div className='grid gap-12 lg:grid-cols-2'>
+          <ProductOverviewGallery
+            images={images}
+            title={product.title}
+            badgeLabel={labels.badgeLabel}
+            selectedImage={selectedImage}
+            onSelectImage={onSelectImage}
+            photosLabel={labels.photosLabel}
+          />
+
+          <div className='flex flex-col gap-8'>
+            <div>
+              <h1 className='text-3xl leading-tight font-bold text-balance'>{product.title}</h1>
+              <div className='mt-4 flex flex-wrap items-center gap-4'>
+                {rating ? (
+                  <div className='flex items-center gap-2'>
+                    <div className='flex'>
+                      {[0, 1, 2, 3, 4].map(i => (
+                        <Star
+                          key={i}
+                          className={cn(
+                            'size-4',
+                            i < rating.value ? 'fill-foreground text-foreground' : 'text-muted-foreground',
+                          )}
+                        />
+                      ))}
+                    </div>
+                    <span className='text-sm font-medium'>{rating.value}</span>
+                  </div>
+                ) : null}
+                {hasReviews ? (
+                  <span className='text-muted-foreground text-sm'>
+                    {reviewCount} {labels.reviewsLabel.toLowerCase()}
+                  </span>
+                ) : null}
+                {selectedVariant?.sku ? (
+                  <>
+                    <Separator orientation='vertical' className='h-4' />
+                    <span className='text-muted-foreground text-sm'>
+                      {labels.skuLabel}: {selectedVariant.sku}
+                    </span>
+                  </>
+                ) : null}
+              </div>
+            </div>
+
+            {selectedVariant ? (
+              priceAvailable ? (
+                <div className='flex items-baseline gap-3'>
+                  <span className='text-4xl font-bold'>{formatMoney(selectedPrice, formatPrice)}</span>
+                  {compareAtAvailable ? (
+                    <span className='text-muted-foreground text-xl line-through'>
+                      {formatMoney(selectedCompareAt, formatPrice)}
+                    </span>
+                  ) : null}
+                </div>
+              ) : (
+                <p className='text-muted-foreground text-sm'>{labels.unavailablePriceLabel}</p>
+              )
+            ) : (
+              <p className='text-muted-foreground text-sm'>{labels.selectVariantLabel}</p>
+            )}
+
+            {selectedVariant?.availableForSale ? (
+              <div className='bg-success/10 inline-flex w-fit items-center gap-2 rounded-full px-3 py-1.5'>
+                <div className='bg-success size-2 rounded-full' />
+                <span className='text-success text-sm font-medium'>{labels.availabilityLabel}</span>
+              </div>
+            ) : null}
+
+            {product.description ? <p className='text-muted-foreground leading-relaxed'>{product.description}</p> : null}
+
+            <VariantSelector
+              product={product}
+              selectedVariantId={selectedVariant?.id}
+              onSelectVariant={onSelectVariant}
+              sizesLabel={labels.selectVariantLabel}
+              variantLabel=''
+              outOfStockLabel={labels.outOfStockLabel}
+            />
+
+            {onQuantityChange ? (
+              <QuantityStepper
+                quantityValue={quantityValue}
+                quantityLabel={labels.quantityLabel}
+                onQuantityChange={onQuantityChange}
+              />
+            ) : null}
+
+            <div className='flex flex-col gap-4'>
+              <Button size='lg' className='h-12 w-full cursor-pointer gap-2' disabled={!canPurchase} onClick={onAddToCart}>
+                <ShoppingCart />
+                {labels.addToCartLabel}
+              </Button>
+              <div className='flex gap-3'>
+                <WishlistButton
+                  isWishlisted={isWishlisted}
+                  disabled={!selectedVariant}
+                  onToggleWishlist={onToggleWishlist}
+                  removeFromWishlistLabel={labels.removeFromWishlistLabel}
+                  addToWishlistLabel={labels.addToWishlistLabel}
+                  className='h-12 flex-1 gap-2 rounded-md'
+                />
+                {onShare ? (
+                  <Button
+                    variant='outline'
+                    size='lg'
+                    className='h-12 flex-1 cursor-pointer gap-2'
+                    onClick={onShare}
+                  >
+                    <Share2 />
+                    {labels.shareLabel}
+                  </Button>
+                ) : null}
+              </div>
+            </div>
+          </div>
+        </div>
+
+        {hasTabs ? (
+          <div className='mt-16'>
+            <ProductOverviewTabs defaultValue={defaultTab} className='w-full'>
+              <ProductOverviewTabsList className='bg-muted/50 relative grid !h-12 w-full grid-cols-4 rounded-xl p-1'>
+                <ProductOverviewTabsIndicator />
+                {featureList ? (
+                  <ProductOverviewTabsTrigger
+                    value='overview'
+                    className='z-10 h-10 gap-2 text-sm font-medium data-active:bg-transparent data-active:shadow-none dark:data-active:bg-transparent'
+                  >
+                    <Info className='size-4 shrink-0' />
+                    <span className='hidden sm:inline'>{labels.overviewLabel}</span>
+                  </ProductOverviewTabsTrigger>
+                ) : null}
+                {hasSpecs ? (
+                  <ProductOverviewTabsTrigger
+                    value='specs'
+                    className='z-10 h-10 gap-2 text-sm font-medium data-active:bg-transparent data-active:shadow-none dark:data-active:bg-transparent'
+                  >
+                    <Package className='size-4 shrink-0' />
+                    <span className='hidden sm:inline'>{labels.specsLabel}</span>
+                  </ProductOverviewTabsTrigger>
+                ) : null}
+                {hasReviews ? (
+                  <ProductOverviewTabsTrigger
+                    value='reviews'
+                    className='z-10 h-10 gap-2 text-sm font-medium data-active:bg-transparent data-active:shadow-none dark:data-active:bg-transparent'
+                  >
+                    <MessageSquare className='size-4 shrink-0' />
+                    <span className='hidden sm:inline'>
+                      {labels.reviewsLabel} ({reviewCount})
+                    </span>
+                  </ProductOverviewTabsTrigger>
+                ) : null}
+                {hasGallery ? (
+                  <ProductOverviewTabsTrigger
+                    value='gallery'
+                    className='z-10 h-10 gap-2 text-sm font-medium data-active:bg-transparent data-active:shadow-none dark:data-active:bg-transparent'
+                  >
+                    <Camera className='size-4 shrink-0' />
+                    <span className='hidden sm:inline'>{labels.galleryLabel}</span>
+                  </ProductOverviewTabsTrigger>
+                ) : null}
+              </ProductOverviewTabsList>
+              {featureList ? (
+                <ProductOverviewTabsContentFade value='overview' className='mt-8'>
+                  <Card className='border shadow-none'>
+                    <CardContent className='p-8 py-0'>
+                      <h3 className='mb-6 text-xl font-semibold text-balance'>{labels.featuresLabel}</h3>
+                      <div className='grid gap-4 sm:grid-cols-2'>
+                        {featureList.map(feature => (
+                          <div key={feature} className='group flex items-center gap-3'>
+                            <div className='bg-primary/20 size-2 rounded-full transition-colors' />
+                            <span className='text-sm'>{feature}</span>
+                          </div>
+                        ))}
+                      </div>
+                    </CardContent>
+                  </Card>
+                </ProductOverviewTabsContentFade>
+              ) : null}
+              {hasSpecs ? (
+                <ProductOverviewTabsContentFade value='specs' className='mt-8'>
+                  <Card className='border shadow-none'>
+                    <CardContent className='p-8 py-0'>
+                      <h3 className='mb-6 text-xl font-semibold text-balance'>{labels.specificationsLabel}</h3>
+                      <div className='flex flex-col gap-4'>
+                        {specEntries.map(([key, value]) => (
+                          <div
+                            key={key}
+                            className='border-muted grid grid-cols-1 gap-2 border-b py-3 last:border-b-0 md:grid-cols-3 md:gap-4'
+                          >
+                            <span className='text-muted-foreground text-sm font-medium'>{key}</span>
+                            <span className='col-span-1 text-sm md:col-span-2'>{value}</span>
+                          </div>
+                        ))}
+                      </div>
+                    </CardContent>
+                  </Card>
+                </ProductOverviewTabsContentFade>
+              ) : null}
+              {hasReviews && reviews ? (
+                <ProductOverviewTabsContentFade value='reviews' className='mt-8'>
+                  <ProductOverviewReviewsTab
+                    rating={rating?.value ?? 0}
+                    reviews={reviews}
+                    basedOnReviewsLabel={labels.basedOnReviewsLabel}
+                    foundHelpfulLabel={labels.foundHelpfulLabel}
+                  />
+                </ProductOverviewTabsContentFade>
+              ) : null}
+              {hasGallery ? (
+                <ProductOverviewTabsContentFade value='gallery' className='mt-8'>
+                  <ProductOverviewLightboxTab
+                    images={images}
+                    title={product.title}
+                    galleryLabel={labels.galleryLabel}
+                    ofCounterLabel={labels.ofCounterLabel}
+                  />
+                </ProductOverviewTabsContentFade>
+              ) : null}
+            </ProductOverviewTabs>
+          </div>
+        ) : null}
+      </div>
+    </section>
+  )
+}
+
+export type { ProductOverviewReview }
+export { ProductOverviewGallery, ProductOverviewLightboxTab, ProductOverviewReviewsTab }