@arroyavecommerce/theme-kinetic 0.2.0

package/src/catalog/gallery.test.tsx

@@ -0,0 +1,201 @@
+import { readFileSync } from "node:fs"
+import { fileURLToPath } from "node:url"
+import { describe, expect, it } from "vitest"
+import { renderToStaticMarkup } from "react-dom/server"
+import { GaleriaProducto } from "./gallery"
+import { mockCtx, fixtureDetalle } from "../test/mock-ctx"
+
+const codigoFuente = readFileSync(fileURLToPath(new URL("./gallery.tsx", import.meta.url)), "utf-8")
+
+/**
+ * Regresion 4d-ii (ver plp.test.tsx): un contenedor `hidden` (sin `md:` que lo
+ * re-muestre) deja su contenido en `display:none` en mobile. Camina el HTML
+ * balanceando aperturas/cierres de `<div>`/`<aside>` y devuelve `true` si el
+ * indice `objetivo` cae DENTRO de un elemento cuya clase contiene el token
+ * exacto "hidden".
+ */
+function estaAnidadoEnOculto(html: string, objetivo: number): boolean {
+  const tagRe = /<(div|aside)\b[^>]*?(\/)?>|<\/(div|aside)>/g
+  const pila: { oculto: boolean; inicio: number }[] = []
+  let match: RegExpExecArray | null
+  while ((match = tagRe.exec(html))) {
+    const esCierre = match[0].startsWith("</")
+    if (esCierre) {
+      const marco = pila.pop()
+      if (marco?.oculto && objetivo > marco.inicio && objetivo < match.index) {
+        return true
+      }
+      continue
+    }
+    const esAutoCerrado = match[2] === "/"
+    const claseMatch = match[0].match(/\bclass="([^"]*)"/)
+    const esOculto = claseMatch ? claseMatch[1].split(/\s+/).includes("hidden") : false
+    if (!esAutoCerrado) {
+      pila.push({ oculto: esOculto, inicio: match.index })
+    }
+  }
+  return false
+}
+
+function tagsImg(html: string): string[] {
+  return html.match(/<img[^>]*>/g) ?? []
+}
+
+describe("GaleriaProducto variante grid", () => {
+  it("renderiza las imagenes (via ctx.componentes.Imagen) con su alt", () => {
+    const detalle = fixtureDetalle()
+    const html = renderToStaticMarkup(
+      <GaleriaProducto imagenes={detalle.producto.imagenes} ctx={mockCtx()} variante="grid" />,
+    )
+
+    for (const img of detalle.producto.imagenes) {
+      expect(html).toContain(`alt="${img.alt}"`)
+    }
+  })
+
+  it("la primera imagen (LCP) lleva prioridad; las demas no", () => {
+    const detalle = fixtureDetalle()
+    const html = renderToStaticMarkup(
+      <GaleriaProducto imagenes={detalle.producto.imagenes} ctx={mockCtx()} variante="grid" />,
+    )
+    const tags = tagsImg(html)
+    const [primera, ...resto] = detalle.producto.imagenes
+
+    const tagsPrimera = tags.filter((t) => t.includes(`src="${primera.url}"`))
+    expect(tagsPrimera.length).toBeGreaterThan(0)
+    for (const t of tagsPrimera) expect(t).toContain('data-prioridad="true"')
+
+    for (const img of resto) {
+      const tagsOtra = tags.filter((t) => t.includes(`src="${img.url}"`))
+      for (const t of tagsOtra) expect(t).not.toContain("data-prioridad")
+    }
+  })
+
+  it("layout desktop 2x2 (hidden md:grid)", () => {
+    const detalle = fixtureDetalle()
+    const html = renderToStaticMarkup(
+      <GaleriaProducto imagenes={detalle.producto.imagenes} ctx={mockCtx()} variante="grid" />,
+    )
+    expect(html).toContain("hidden md:grid")
+  })
+})
+
+describe("GaleriaProducto variante carrusel", () => {
+  it("renderiza imagen principal + thumbnails (hidden md:...)", () => {
+    const detalle = fixtureDetalle()
+    const html = renderToStaticMarkup(
+      <GaleriaProducto imagenes={detalle.producto.imagenes} ctx={mockCtx()} variante="carrusel" />,
+    )
+    expect(html).toMatch(/hidden md:/)
+    for (const img of detalle.producto.imagenes) {
+      expect(html).toContain(`alt="${img.alt}"`)
+    }
+  })
+
+  it('renderiza el contador "1 / N"', () => {
+    const detalle = fixtureDetalle()
+    const html = renderToStaticMarkup(
+      <GaleriaProducto imagenes={detalle.producto.imagenes} ctx={mockCtx()} variante="carrusel" />,
+    )
+    expect(html).toContain(`1 / ${detalle.producto.imagenes.length}`)
+  })
+})
+
+describe("GaleriaProducto: galeria mobile swipe (md:hidden) siempre presente", () => {
+  it.each(["grid", "carrusel"] as const)(
+    'variante:"%s": la galeria mobile swipe renderiza TODAS las imagenes con dots',
+    (variante) => {
+      const detalle = fixtureDetalle()
+      const html = renderToStaticMarkup(
+        <GaleriaProducto imagenes={detalle.producto.imagenes} ctx={mockCtx()} variante={variante} />,
+      )
+      expect(html).toContain("md:hidden")
+
+      const dots = html.match(/data-dot/g) ?? []
+      expect(dots).toHaveLength(detalle.producto.imagenes.length)
+    },
+  )
+
+  it("mostrarFavoritos:false no renderiza el boton de favoritos en la galeria mobile", () => {
+    const detalle = fixtureDetalle()
+    const html = renderToStaticMarkup(
+      <GaleriaProducto
+        imagenes={detalle.producto.imagenes}
+        ctx={mockCtx()}
+        variante="grid"
+        mostrarFavoritos={false}
+      />,
+    )
+    expect(html).not.toContain("♡")
+    expect(html).not.toContain("♥")
+  })
+
+  it("mostrarFavoritos:true renderiza el boton de favoritos en la galeria mobile", () => {
+    const detalle = fixtureDetalle()
+    const html = renderToStaticMarkup(
+      <GaleriaProducto
+        imagenes={detalle.producto.imagenes}
+        ctx={mockCtx()}
+        variante="grid"
+        mostrarFavoritos={true}
+      />,
+    )
+    expect(html).toContain("♡")
+  })
+})
+
+describe("regresion 4d-ii: el contenido de la galeria (data-dot, imagenes mobile) no queda bajo un hidden incondicional", () => {
+  it.each(["grid", "carrusel"] as const)('variante:"%s": verifica TODOS los data-dot mobile', (variante) => {
+    const detalle = fixtureDetalle()
+    const html = renderToStaticMarkup(
+      <GaleriaProducto imagenes={detalle.producto.imagenes} ctx={mockCtx()} variante={variante} />,
+    )
+
+    // Verifica que data-galeria no esté bajo hidden incondicional
+    const idxGaleria = html.indexOf("data-galeria")
+    expect(idxGaleria).toBeGreaterThan(-1)
+    expect(estaAnidadoEnOculto(html, idxGaleria)).toBe(false)
+
+    // Encuentra TODOS los data-dot en el HTML (galeria mobile swipe)
+    const dotRegex = /data-dot/g
+    const dotMatches = Array.from(html.matchAll(dotRegex))
+    expect(dotMatches.length).toBe(detalle.producto.imagenes.length)
+
+    // Verifica que NINGUNO de los data-dot esté anidado en un hidden incondicional
+    for (const match of dotMatches) {
+      const idxDot = match.index ?? -1
+      expect(idxDot).toBeGreaterThan(-1)
+      expect(estaAnidadoEnOculto(html, idxDot)).toBe(false)
+    }
+  })
+})
+
+describe("zoom / lightbox: disparadores sobre las imagenes", () => {
+  it.each(["grid", "carrusel"] as const)(
+    'variante:"%s": expone botones "Ampliar imagen" (data-zoom) para abrir el lightbox',
+    (variante) => {
+      const detalle = fixtureDetalle()
+      const html = renderToStaticMarkup(
+        <GaleriaProducto imagenes={detalle.producto.imagenes} ctx={mockCtx()} variante={variante} />,
+      )
+      expect(html).toContain("data-zoom")
+      expect(html).toMatch(/aria-label="Ampliar imagen:/)
+    },
+  )
+
+  it("el lightbox NO se renderiza hasta que se abre (cerrado por defecto)", () => {
+    const detalle = fixtureDetalle()
+    const html = renderToStaticMarkup(
+      <GaleriaProducto imagenes={detalle.producto.imagenes} ctx={mockCtx()} variante="grid" />,
+    )
+    expect(html).not.toContain("data-lightbox")
+    expect(html).not.toContain('aria-label="Imagen ampliada"')
+  })
+})
+
+describe("guard de estandar (cero <img>/<a> directos)", () => {
+  it("no emite <img> ni <a> directos: todo pasa por ctx.componentes", () => {
+    expect(codigoFuente).not.toMatch(/<img[\s>]/)
+    expect(codigoFuente).not.toMatch(/<a[\s>]/)
+  })
+})

package/src/catalog/gallery.tsx

@@ -0,0 +1,212 @@
+"use client"
+
+import { useState } from "react"
+import type { RenderContext } from "../context"
+import { Lightbox } from "./lightbox"
+
+export type ImagenGaleria = { url: string; alt: string }
+export type GaleriaVariante = "grid" | "carrusel"
+
+/** Callback que abre el lightbox en la imagen `indice`. */
+type AbrirZoom = (indice: number) => void
+
+/**
+ * Botón-overlay transparente que cubre una imagen (`absolute inset-0`) para
+ * abrir el zoom/lightbox al hacer click. `z-[1]` para quedar sobre la imagen
+ * pero debajo del chrome (nav ‹ ›, badges, favoritos) que va en `z-10`.
+ */
+function DisparadorZoom({ indice, alt, onAbrir }: { indice: number; alt: string; onAbrir?: AbrirZoom }) {
+  if (!onAbrir) return null
+  return (
+    <button
+      type="button"
+      data-zoom
+      onClick={() => onAbrir(indice)}
+      aria-label={`Ampliar imagen: ${alt}`}
+      className="absolute inset-0 z-[1] h-full w-full cursor-zoom-in bg-transparent p-0"
+    />
+  )
+}
+
+/** Galeria desktop en grilla 2x2 (mockup PDP grid l.35-40). CLS 0: aspect-ratio reservado. */
+function GaleriaGrid({ imagenes, ctx, onAbrirZoom }: { imagenes: ImagenGaleria[]; ctx: RenderContext; onAbrirZoom?: AbrirZoom }) {
+  const { Imagen } = ctx.componentes
+  return (
+    <div className="hidden md:grid md:grid-cols-2 md:gap-3">
+      {imagenes.map((img, i) => (
+        <div
+          key={img.url}
+          className="relative overflow-hidden"
+          style={{ aspectRatio: "1 / 1", background: "var(--cms-superficie)", borderRadius: "var(--cms-radio)" }}
+        >
+          <Imagen src={img.url} alt={img.alt} className="h-full w-full object-cover" prioridad={i === 0} />
+          <DisparadorZoom indice={i} alt={img.alt} onAbrir={onAbrirZoom} />
+        </div>
+      ))}
+    </div>
+  )
+}
+
+/** Galeria desktop tipo carrusel: imagen principal + thumbnails verticales (mockup PDP carrusel l.99-110). */
+function GaleriaCarrusel({ imagenes, ctx, onAbrirZoom }: { imagenes: ImagenGaleria[]; ctx: RenderContext; onAbrirZoom?: AbrirZoom }) {
+  const { Imagen } = ctx.componentes
+  const [activo, setActivo] = useState(0)
+  const total = imagenes.length
+  const actual = imagenes[activo]
+
+  return (
+    <div className="hidden md:grid md:grid-cols-[76px_1fr] md:gap-5 md:items-start">
+      <div className="flex flex-col gap-2.5">
+        {imagenes.map((img, i) => (
+          <button
+            key={img.url}
+            type="button"
+            onClick={() => setActivo(i)}
+            aria-label={`Ver imagen ${i + 1}`}
+            aria-pressed={i === activo}
+            className="relative overflow-hidden p-0"
+            style={{
+              aspectRatio: "1 / 1",
+              borderRadius: "var(--cms-radio)",
+              outline: i === activo ? "2px solid var(--cms-texto)" : "none",
+              outlineOffset: "2px",
+              border: "none",
+              background: "transparent",
+              opacity: i === activo ? 1 : 0.6,
+            }}
+          >
+            <Imagen src={img.url} alt={img.alt} className="h-full w-full object-cover" />
+          </button>
+        ))}
+      </div>
+      <div
+        className="relative overflow-hidden"
+        style={{ aspectRatio: "1200 / 1500", background: "var(--cms-superficie)", borderRadius: "var(--cms-radio)" }}
+      >
+        <Imagen src={actual.url} alt={actual.alt} className="h-full w-full object-cover" prioridad={activo === 0} />
+        <DisparadorZoom indice={activo} alt={actual.alt} onAbrir={onAbrirZoom} />
+        <button
+          type="button"
+          onClick={() => setActivo((a) => (a - 1 + total) % total)}
+          aria-label="Imagen anterior"
+          className="absolute left-3.5 top-1/2 z-10 flex h-9 w-9 -translate-y-1/2 items-center justify-center rounded-full"
+          style={{ background: "var(--cms-superficie)", border: "var(--cms-grosor-borde) solid var(--cms-borde)" }}
+        >
+          ‹
+        </button>
+        <button
+          type="button"
+          onClick={() => setActivo((a) => (a + 1) % total)}
+          aria-label="Imagen siguiente"
+          className="absolute right-3.5 top-1/2 z-10 flex h-9 w-9 -translate-y-1/2 items-center justify-center rounded-full"
+          style={{ background: "var(--cms-superficie)", border: "var(--cms-grosor-borde) solid var(--cms-borde)" }}
+        >
+          ›
+        </button>
+        <span
+          className="absolute bottom-3 left-1/2 z-10 -translate-x-1/2 rounded-full px-2.5 py-1 text-[10px] font-medium"
+          style={{
+            background: "var(--cms-superficie)",
+            border: "var(--cms-grosor-borde) solid var(--cms-borde)",
+            fontFamily: "var(--cms-fuente-mono)",
+          }}
+        >
+          {activo + 1} / {total}
+        </span>
+      </div>
+    </div>
+  )
+}
+
+/** Galeria mobile swipe edge-to-edge con dots + favoritos opcional (mockup PDP mobile l.191-194). */
+function GaleriaSwipeMobil({
+  imagenes,
+  ctx,
+  mostrarFavoritos = false,
+  onAbrirZoom,
+}: {
+  imagenes: ImagenGaleria[]
+  ctx: RenderContext
+  mostrarFavoritos?: boolean
+  onAbrirZoom?: AbrirZoom
+}) {
+  const { Imagen } = ctx.componentes
+  const [favorito, setFavorito] = useState(false)
+
+  return (
+    <div className="relative md:hidden">
+      <div className="flex snap-x snap-mandatory overflow-x-auto" style={{ scrollbarWidth: "none" }}>
+        {imagenes.map((img, i) => (
+          <div
+            key={img.url}
+            className="relative w-full flex-none snap-center overflow-hidden"
+            style={{ aspectRatio: "1 / 1.25", background: "var(--cms-superficie)" }}
+          >
+            <Imagen src={img.url} alt={img.alt} className="h-full w-full object-cover" prioridad={i === 0} />
+            <DisparadorZoom indice={i} alt={img.alt} onAbrir={onAbrirZoom} />
+          </div>
+        ))}
+      </div>
+      <div className="absolute inset-x-0 bottom-2.5 flex items-center justify-center gap-1.5" aria-hidden="true">
+        {imagenes.map((img, i) => (
+          <span
+            key={img.url}
+            data-dot
+            className="h-1.5 w-1.5 rounded-full"
+            style={{ background: "var(--cms-texto)", opacity: i === 0 ? 1 : 0.3 }}
+          />
+        ))}
+      </div>
+      {mostrarFavoritos ? (
+        <button
+          type="button"
+          onClick={() => setFavorito((v) => !v)}
+          aria-pressed={favorito}
+          aria-label="favoritos"
+          className="absolute right-3 top-3 z-10 flex h-9 w-9 items-center justify-center rounded-full text-[16px]"
+          style={{ background: "var(--cms-superficie)", border: "var(--cms-grosor-borde) solid var(--cms-borde)" }}
+        >
+          {favorito ? "♥" : "♡"}
+        </button>
+      ) : null}
+    </div>
+  )
+}
+
+const DESKTOP_POR_VARIANTE: Record<GaleriaVariante, typeof GaleriaGrid> = {
+  grid: GaleriaGrid,
+  carrusel: GaleriaCarrusel,
+}
+
+/**
+ * Galeria del PDP: despacha por `variante` en desktop (`hidden md:...`) y
+ * SIEMPRE renderiza la galeria mobile swipe (`md:hidden`) — lección 4d-ii: el
+ * contenido (las imagenes) nunca queda anidado en un `hidden` incondicional,
+ * solo el chrome desktop/mobile-only usa `hidden`/`md:hidden` para dispatchear
+ * entre las dos presentaciones, que coexisten SIEMPRE en el DOM.
+ */
+export function GaleriaProducto({
+  imagenes,
+  ctx,
+  variante,
+  mostrarFavoritos = false,
+}: {
+  imagenes: ImagenGaleria[]
+  ctx: RenderContext
+  variante: GaleriaVariante
+  mostrarFavoritos?: boolean
+}) {
+  const Desktop = DESKTOP_POR_VARIANTE[variante] ?? GaleriaGrid
+  // `null` = lightbox cerrado; un número = índice de la imagen ampliada.
+  const [zoom, setZoom] = useState<number | null>(null)
+
+  return (
+    <div data-galeria className="flex flex-col">
+      <Desktop imagenes={imagenes} ctx={ctx} onAbrirZoom={setZoom} />
+      <GaleriaSwipeMobil imagenes={imagenes} ctx={ctx} mostrarFavoritos={mostrarFavoritos} onAbrirZoom={setZoom} />
+      {zoom !== null ? (
+        <Lightbox imagenes={imagenes} ctx={ctx} indiceInicial={zoom} onCerrar={() => setZoom(null)} />
+      ) : null}
+    </div>
+  )
+}

package/src/catalog/lightbox.test.tsx

@@ -0,0 +1,95 @@
+import { readFileSync } from "node:fs"
+import { fileURLToPath } from "node:url"
+import { describe, expect, it } from "vitest"
+import { renderToStaticMarkup } from "react-dom/server"
+import { Lightbox, siguienteIndice, anteriorIndice } from "./lightbox"
+import { mockCtx, fixtureDetalle } from "../test/mock-ctx"
+
+const codigoFuente = readFileSync(fileURLToPath(new URL("./lightbox.tsx", import.meta.url)), "utf-8")
+
+describe("siguienteIndice / anteriorIndice (wrap-around)", () => {
+  it("siguienteIndice avanza y da la vuelta al final", () => {
+    expect(siguienteIndice(0, 4)).toBe(1)
+    expect(siguienteIndice(3, 4)).toBe(0)
+  })
+
+  it("anteriorIndice retrocede y da la vuelta al inicio", () => {
+    expect(anteriorIndice(1, 4)).toBe(0)
+    expect(anteriorIndice(0, 4)).toBe(3)
+  })
+
+  it("total 0 no revienta (devuelve 0)", () => {
+    expect(siguienteIndice(0, 0)).toBe(0)
+    expect(anteriorIndice(0, 0)).toBe(0)
+  })
+})
+
+describe("Lightbox markup + aria", () => {
+  it("renderiza un dialog modal con aria-label y la imagen del indice inicial", () => {
+    const detalle = fixtureDetalle()
+    const html = renderToStaticMarkup(
+      <Lightbox imagenes={detalle.producto.imagenes} ctx={mockCtx()} indiceInicial={1} onCerrar={() => {}} />,
+    )
+
+    expect(html).toContain('role="dialog"')
+    expect(html).toContain('aria-modal="true"')
+    expect(html).toContain('aria-label="Imagen ampliada"')
+    expect(html).toContain("data-lightbox")
+    // El índice inicial (1) determina la imagen mostrada.
+    expect(html).toContain(`src="${detalle.producto.imagenes[1].url}"`)
+    expect(html).toContain(`alt="${detalle.producto.imagenes[1].alt}"`)
+  })
+
+  it("expone el boton de cierre (aria-label Cerrar) para cerrar con click", () => {
+    const detalle = fixtureDetalle()
+    const html = renderToStaticMarkup(
+      <Lightbox imagenes={detalle.producto.imagenes} ctx={mockCtx()} indiceInicial={0} onCerrar={() => {}} />,
+    )
+    expect(html).toContain('aria-label="Cerrar"')
+  })
+
+  it("con varias imagenes muestra navegacion ‹ › y contador N / total", () => {
+    const detalle = fixtureDetalle()
+    const total = detalle.producto.imagenes.length
+    const html = renderToStaticMarkup(
+      <Lightbox imagenes={detalle.producto.imagenes} ctx={mockCtx()} indiceInicial={0} onCerrar={() => {}} />,
+    )
+    expect(html).toContain('aria-label="Imagen anterior"')
+    expect(html).toContain('aria-label="Imagen siguiente"')
+    expect(html).toContain("data-lightbox-contador")
+    expect(html).toContain(`1 / ${total}`)
+  })
+
+  it("con una sola imagen NO muestra navegacion ni contador", () => {
+    const detalle = fixtureDetalle()
+    const html = renderToStaticMarkup(
+      <Lightbox imagenes={[detalle.producto.imagenes[0]]} ctx={mockCtx()} indiceInicial={0} onCerrar={() => {}} />,
+    )
+    expect(html).not.toContain('aria-label="Imagen anterior"')
+    expect(html).not.toContain('aria-label="Imagen siguiente"')
+    expect(html).not.toContain("data-lightbox-contador")
+  })
+
+  it("indiceInicial fuera de rango degrada a null (no revienta)", () => {
+    const detalle = fixtureDetalle()
+    const html = renderToStaticMarkup(
+      <Lightbox imagenes={detalle.producto.imagenes} ctx={mockCtx()} indiceInicial={99} onCerrar={() => {}} />,
+    )
+    expect(html).toBe("")
+  })
+
+  it("respeta prefers-reduced-motion (motion-reduce:transition-none)", () => {
+    const detalle = fixtureDetalle()
+    const html = renderToStaticMarkup(
+      <Lightbox imagenes={detalle.producto.imagenes} ctx={mockCtx()} indiceInicial={0} onCerrar={() => {}} />,
+    )
+    expect(html).toContain("motion-reduce:transition-none")
+  })
+})
+
+describe("guard de estandar (cero <img>/<a> directos)", () => {
+  it("no emite <img> ni <a> directos: todo pasa por ctx.componentes", () => {
+    expect(codigoFuente).not.toMatch(/<img[\s>]/)
+    expect(codigoFuente).not.toMatch(/<a[\s>]/)
+  })
+})

package/src/catalog/lightbox.tsx

@@ -0,0 +1,184 @@
+"use client"
+
+import { useCallback, useEffect, useRef, useState } from "react"
+import type { RenderContext } from "../context"
+import type { ImagenGaleria } from "./gallery"
+
+/** Índice de la imagen siguiente (con wrap-around). Puro para poder testearlo sin DOM. */
+export function siguienteIndice(actual: number, total: number): number {
+  return total > 0 ? (actual + 1) % total : 0
+}
+
+/** Índice de la imagen anterior (con wrap-around). Puro para poder testearlo sin DOM. */
+export function anteriorIndice(actual: number, total: number): number {
+  return total > 0 ? (actual - 1 + total) % total : 0
+}
+
+/**
+ * Lightbox / zoom a pantalla completa de la galería PDP. Aislado en su propio
+ * módulo `"use client"` (lección "use client": los hooks van SOLO en archivos
+ * client dedicados, nunca en módulos que exporten tipos/constantes consumidos
+ * por el servidor). `gallery.tsx` lo importa y lo monta bajo demanda.
+ *
+ * - Overlay `fixed inset-0` con scrim oscuro semitransparente.
+ * - Navegación ‹ › entre imágenes (wrap-around) + teclas ← →.
+ * - Cierra con Esc o click en el scrim.
+ * - Foco atrapado dentro del diálogo (Tab/Shift+Tab ciclan entre los botones);
+ *   el foco entra al botón "Cerrar" al abrir.
+ * - Respeta `prefers-reduced-motion` (sin transición cuando el usuario la reduce).
+ */
+export function Lightbox({
+  imagenes,
+  ctx,
+  indiceInicial,
+  onCerrar,
+}: {
+  imagenes: ImagenGaleria[]
+  ctx: RenderContext
+  indiceInicial: number
+  onCerrar: () => void
+}) {
+  const { Imagen } = ctx.componentes
+  const total = imagenes.length
+  const [activo, setActivo] = useState(indiceInicial)
+  const dialogRef = useRef<HTMLDivElement>(null)
+  const cerrarRef = useRef<HTMLButtonElement>(null)
+
+  const irAnterior = useCallback(() => setActivo((a) => anteriorIndice(a, total)), [total])
+  const irSiguiente = useCallback(() => setActivo((a) => siguienteIndice(a, total)), [total])
+
+  // Foco inicial en "Cerrar" al montar.
+  useEffect(() => {
+    cerrarRef.current?.focus()
+  }, [])
+
+  // Teclado: Esc cierra, ← → navegan, Tab queda atrapado dentro del diálogo.
+  useEffect(() => {
+    function onKey(e: KeyboardEvent) {
+      if (e.key === "Escape") {
+        onCerrar()
+        return
+      }
+      if (e.key === "ArrowLeft") {
+        irAnterior()
+        return
+      }
+      if (e.key === "ArrowRight") {
+        irSiguiente()
+        return
+      }
+      if (e.key === "Tab") {
+        const focusables = dialogRef.current?.querySelectorAll<HTMLElement>("button")
+        if (!focusables || focusables.length === 0) return
+        const primero = focusables[0]
+        const ultimo = focusables[focusables.length - 1]
+        const activoEl = document.activeElement
+        if (e.shiftKey && activoEl === primero) {
+          e.preventDefault()
+          ultimo.focus()
+        } else if (!e.shiftKey && activoEl === ultimo) {
+          e.preventDefault()
+          primero.focus()
+        }
+      }
+    }
+    document.addEventListener("keydown", onKey)
+    return () => document.removeEventListener("keydown", onKey)
+  }, [onCerrar, irAnterior, irSiguiente])
+
+  const actual = imagenes[activo]
+  if (!actual) return null
+
+  return (
+    <div
+      ref={dialogRef}
+      role="dialog"
+      aria-modal="true"
+      aria-label="Imagen ampliada"
+      data-lightbox
+      className="fixed inset-0 z-[60] flex items-center justify-center p-6 md:p-10"
+      style={{ background: "var(--cms-scrim, rgba(0,0,0,.86))" }}
+      onClick={onCerrar}
+    >
+      <button
+        ref={cerrarRef}
+        type="button"
+        onClick={onCerrar}
+        aria-label="Cerrar"
+        className="absolute right-4 top-4 z-10 flex h-10 w-10 items-center justify-center rounded-full text-[18px] leading-none"
+        style={{
+          background: "var(--cms-superficie, #fff)",
+          color: "var(--cms-texto, #111)",
+          border: "var(--cms-grosor-borde, 1px) solid var(--cms-borde, #e5e5e5)",
+        }}
+      >
+        ×
+      </button>
+
+      {total > 1 ? (
+        <button
+          type="button"
+          onClick={(e) => {
+            e.stopPropagation()
+            irAnterior()
+          }}
+          aria-label="Imagen anterior"
+          className="absolute left-4 top-1/2 z-10 flex h-11 w-11 -translate-y-1/2 items-center justify-center rounded-full text-[20px] leading-none"
+          style={{
+            background: "var(--cms-superficie, #fff)",
+            color: "var(--cms-texto, #111)",
+            border: "var(--cms-grosor-borde, 1px) solid var(--cms-borde, #e5e5e5)",
+          }}
+        >
+          ‹
+        </button>
+      ) : null}
+
+      <div
+        className="relative flex max-h-full max-w-full items-center justify-center overflow-hidden"
+        style={{ borderRadius: "var(--cms-radio, 0)" }}
+        onClick={(e) => e.stopPropagation()}
+      >
+        <Imagen
+          src={actual.url}
+          alt={actual.alt}
+          className="max-h-[86vh] max-w-[90vw] object-contain transition-opacity duration-200 motion-reduce:transition-none"
+        />
+      </div>
+
+      {total > 1 ? (
+        <button
+          type="button"
+          onClick={(e) => {
+            e.stopPropagation()
+            irSiguiente()
+          }}
+          aria-label="Imagen siguiente"
+          className="absolute right-4 top-1/2 z-10 flex h-11 w-11 -translate-y-1/2 items-center justify-center rounded-full text-[20px] leading-none"
+          style={{
+            background: "var(--cms-superficie, #fff)",
+            color: "var(--cms-texto, #111)",
+            border: "var(--cms-grosor-borde, 1px) solid var(--cms-borde, #e5e5e5)",
+          }}
+        >
+          ›
+        </button>
+      ) : null}
+
+      {total > 1 ? (
+        <span
+          data-lightbox-contador
+          className="absolute bottom-5 left-1/2 -translate-x-1/2 rounded-full px-3 py-1 text-[11px] font-medium"
+          style={{
+            background: "var(--cms-superficie, #fff)",
+            color: "var(--cms-texto, #111)",
+            border: "var(--cms-grosor-borde, 1px) solid var(--cms-borde, #e5e5e5)",
+            fontFamily: "var(--cms-fuente-mono, monospace)",
+          }}
+        >
+          {activo + 1} / {total}
+        </span>
+      ) : null}
+    </div>
+  )
+}