feat: enlarge gallery images in a Lightbox with prev/next navigation (#390)

* feat: add base Lightbox overlay shell

Add a fullscreen overlay with a close button as the foundation for
the gallery image enlargement view. Image rendering is added next.

* feat: render selected image and credit in Lightbox

Display the enlarged image with its alt text and optional credit
inside the overlay added previously.

* feat: wire gallery image click to open Lightbox

Add lightboxImage state to HeritageDetailLayout and connect
HeritageGallery's onSelectImage to it, rendering the Lightbox so
clicking a gallery thumbnail enlarges the image.

* feat: close Lightbox on Escape key or outside click

Improve usability by letting users dismiss the enlarged image via
keyboard or by clicking the overlay backdrop, not just the close
button.

* refactor: move Lightbox out of shared/uis into heritage-detail

Lightbox is only used for enlarging gallery images on the heritage
detail page, so it doesn't belong in the generic shared UI primitives
directory.

* feat: add prev/next navigation to Lightbox

Switch HeritageGallery's onSelectImage to pass the clicked image's
index instead of its data, and have Lightbox track the current index
within the full image list. This lets users navigate to the next or
previous photo with on-screen arrows (or Left/Right arrow keys)
without closing the Lightbox.

Author: zigzagdev

client/src/app/features/top/components/heritage-detail/HeritageDetailLayout.tsx

@@ -6,6 +6,7 @@ import { HeritageHero } from "./HeritageHero";
 import { HeritageOverViewSection } from "./HeritageOverviewSection";
 import { HeritageSidebar } from "./HeritageSidebar";
 import { HeritageGallery } from "./HeritageGallery";
+import { Lightbox } from "./Lightbox.tsx";
 import { DetailHeritageMap } from "@features/top/components/heritage-detail/DetailHeritageMap.tsx";
 import { textType } from "@shared/styles/typography";
 import { useSetBreadcrumbLabel } from "@features/breadcrumbs/BreadCrumbHooks.ts";
@@ -97,6 +98,7 @@ function KeyExamInfo({ item }: { item: WorldHeritageDetailVm }) {
 export function HeritageDetailLayout({ item }: { item: WorldHeritageDetailVm }) {
   const [search, setSearch] = useState<SearchValues>(DEFAULT_SEARCH);
   const [isSearchOpen, setIsSearchOpen] = useState(false);
+  const [lightboxIndex, setLightboxIndex] = useState<number | null>(null);
   const setLabel = useSetBreadcrumbLabel();
   const navigate = useNavigate();
   const text = useText();
@@ -189,7 +191,7 @@ export function HeritageDetailLayout({ item }: { item: WorldHeritageDetailVm })
           {/* Left: Overview → Gallery */}
           <div className="space-y-8" id="content">
             <HeritageOverViewSection item={item} />
-            <HeritageGallery images={item.images} />
+            <HeritageGallery images={item.images} onSelectImage={setLightboxIndex} />
           </div>
 
           {/* Right: Sidebar (PC only) */}
@@ -198,6 +200,13 @@ export function HeritageDetailLayout({ item }: { item: WorldHeritageDetailVm })
           </div>
         </div>
       </main>
+
+      <Lightbox
+        images={item.images}
+        index={lightboxIndex}
+        onClose={() => setLightboxIndex(null)}
+        onNavigate={setLightboxIndex}
+      />
     </div>
   );
 }

client/src/app/features/top/components/heritage-detail/HeritageGallery.tsx

@@ -10,7 +10,7 @@ export function HeritageGallery({
   images: WorldHeritageImageVm[];
   previewCount?: number;
   onOpenGallery?: () => void;
-  onSelectImage?: (img: Pick<WorldHeritageImageVm, "id" | "url" | "alt" | "credit">) => void;
+  onSelectImage?: (index: number) => void;
 }) {
   if (!images?.length) return null;
 
@@ -44,13 +44,11 @@ export function HeritageGallery({
       </div>
 
       <div className="mt-5 grid grid-cols-2 gap-3 sm:grid-cols-3">
-        {preview.map((img) => (
+        {preview.map((img, index) => (
           <button
             key={img.id}
             type="button"
-            onClick={() =>
-              onSelectImage?.({ id: img.id, url: img.url, alt: img.alt, credit: img.credit })
-            }
+            onClick={() => onSelectImage?.(index)}
             className="group text-left"
             aria-label={img.alt ? `Open photo: ${img.alt}` : "Open photo"}
             title={img.alt ?? "Open photo"}

client/src/app/features/top/components/heritage-detail/Lightbox.tsx

@@ -0,0 +1,95 @@
+import { useEffect } from "react";
+import CloseIcon from "@mui/icons-material/Close";
+import NavigateBeforeIcon from "@mui/icons-material/NavigateBefore";
+import NavigateNextIcon from "@mui/icons-material/NavigateNext";
+import IconButton from "@shared/uis/Icon-Button.tsx";
+import type { WorldHeritageImageVm } from "../../../../../domain/types.ts";
+
+type LightboxImage = Pick<WorldHeritageImageVm, "id" | "url" | "alt" | "credit">;
+
+export function Lightbox({
+  images,
+  index,
+  onClose,
+  onNavigate,
+}: {
+  images: LightboxImage[];
+  index: number | null;
+  onClose: () => void;
+  onNavigate: (index: number) => void;
+}) {
+  const image = index !== null ? images[index] : null;
+  const hasPrev = index !== null && index > 0;
+  const hasNext = index !== null && index < images.length - 1;
+
+  useEffect(() => {
+    if (!image) return;
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Escape") onClose();
+      if (e.key === "ArrowLeft" && hasPrev) onNavigate(index! - 1);
+      if (e.key === "ArrowRight" && hasNext) onNavigate(index! + 1);
+    };
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [image, index, hasPrev, hasNext, onClose, onNavigate]);
+
+  if (!image) return null;
+
+  return (
+    <div
+      role="dialog"
+      aria-modal="true"
+      onClick={onClose}
+      className="fixed inset-0 z-50 flex items-center justify-center bg-black/80 p-4"
+    >
+      <IconButton
+        onClick={onClose}
+        aria-label="Close"
+        className="!absolute !right-4 !top-4 !text-white"
+      >
+        <CloseIcon />
+      </IconButton>
+
+      {hasPrev && (
+        <IconButton
+          onClick={(e) => {
+            e.stopPropagation();
+            onNavigate(index! - 1);
+          }}
+          aria-label="Previous photo"
+          className="!absolute !left-4 !top-1/2 !-translate-y-1/2 !text-white"
+        >
+          <NavigateBeforeIcon />
+        </IconButton>
+      )}
+
+      {hasNext && (
+        <IconButton
+          onClick={(e) => {
+            e.stopPropagation();
+            onNavigate(index! + 1);
+          }}
+          aria-label="Next photo"
+          className="!absolute !right-4 !top-1/2 !-translate-y-1/2 !text-white"
+        >
+          <NavigateNextIcon />
+        </IconButton>
+      )}
+
+      <figure className="max-h-full max-w-full" onClick={(e) => e.stopPropagation()}>
+        <img
+          src={image.url}
+          alt={image.alt ?? ""}
+          referrerPolicy="no-referrer"
+          className="max-h-[85vh] max-w-full rounded-lg object-contain"
+        />
+        {image.credit && (
+          <figcaption className="mt-2 text-center text-sm text-zinc-300">
+            © {image.credit}
+          </figcaption>
+        )}
+      </figure>
+    </div>
+  );
+}