From b5ac2b4d45af0d14b83da7de5efd29877f57e46f Mon Sep 17 00:00:00 2001
From: Fadeedev <fagbohundeborah26@gmail.com>
Date: Tue, 20 Oct 2026 22:17:55 +0100
Subject: [PATCH] feat(gallery): analytics, keyboard nav, memoization,
 integration tests (#1256 #1257 #1258 #1259)

---
 docs/GALLERY.md                               |  24 ++
 src/components/property/ImageGallery.tsx      | 382 +++++++++++++-----
 src/components/property/ImageLightbox.tsx     |  44 +-
 .../ImageGallery.integration.test.tsx         |  99 +++++
 src/lib/__tests__/galleryAnalytics.test.ts    |  39 ++
 src/lib/galleryAnalytics.ts                   |  54 +++
 6 files changed, 516 insertions(+), 126 deletions(-)
 create mode 100644 docs/GALLERY.md
 create mode 100644 src/components/property/__tests__/ImageGallery.integration.test.tsx
 create mode 100644 src/lib/__tests__/galleryAnalytics.test.ts
 create mode 100644 src/lib/galleryAnalytics.ts

diff --git a/docs/GALLERY.md b/docs/GALLERY.md
new file mode 100644
index 00000000..a4ffba40
--- /dev/null
+++ b/docs/GALLERY.md
@@ -0,0 +1,24 @@
+# Property Image Gallery
+
+Covers issues **#1256–#1259**.
+
+## Features
+
+| Issue | Behavior |
+| --- | --- |
+| #1259 Analytics | `trackGalleryEvent` → gtag + `dataLayer` (`gallery_view`, open/close/navigate, keyboard) |
+| #1258 Keyboard | Arrow/Home/End focus movement; Enter/Space opens lightbox; lightbox already supports ←/→/Esc |
+| #1257 Re-renders | `React.memo` on gallery shells; `useCallback` / `useMemo` for handlers and thumbnail list |
+| #1256 Tests | `ImageGallery.integration.test.tsx`, `galleryAnalytics.test.ts` |
+
+## Usage
+
+```tsx
+import { ImageGallery } from '@/components/property/ImageGallery';
+
+<ImageGallery images={urls} propertyName={property.title} />
+```
+
+## Analytics payload
+
+Events include optional `propertyName`, `imageIndex`, `imageCount`, `direction`, `method`.
diff --git a/src/components/property/ImageGallery.tsx b/src/components/property/ImageGallery.tsx
index 54cbcf47..29e75dbd 100644
--- a/src/components/property/ImageGallery.tsx
+++ b/src/components/property/ImageGallery.tsx
@@ -1,11 +1,19 @@
 'use client';
 
-import React, { useState } from 'react';
+import React, {
+  useState,
+  useCallback,
+  useMemo,
+  memo,
+  useRef,
+  useEffect,
+} from 'react';
 import Image from 'next/image';
 import { ImageLightbox } from './ImageLightbox';
 import { ErrorBoundary } from '@/components/ui/SimpleErrorBoundary';
+import { trackGalleryEvent } from '@/lib/galleryAnalytics';
 
-interface ImageGalleryProps {
+export interface ImageGalleryProps {
   images: string[];
   propertyName: string;
 }
@@ -15,130 +23,280 @@ interface ImageGalleryProps {
  * failure in either used to take the whole property page down with it. The
  * boundary below keeps the failure inside the gallery, where it degrades to a
  * retryable fallback.
+ *
+ * #1257 — memoized root + stable callbacks to limit re-renders.
+ * #1258 — keyboard navigation on the thumbnail strip and main image.
+ * #1259 — analytics events for open / navigate / close.
  */
-export const ImageGallery: React.FC<ImageGalleryProps> = (props) => (
+export const ImageGallery: React.FC<ImageGalleryProps> = memo((props) => (
   <ErrorBoundary>
     <ImageGalleryContent {...props} />
   </ErrorBoundary>
-);
+));
+ImageGallery.displayName = 'ImageGallery';
 
-const ImageGalleryContent: React.FC<ImageGalleryProps> = ({ 
-  images, 
-  propertyName 
-}) => {
-  const [lightboxIndex, setLightboxIndex] = useState<number | null>(null);
-  // Issue #1253 — the gallery had no loading state, so an image that was still
-  // being fetched left an empty grey box. The skeleton is drawn over the
-  // image until the browser reports it has loaded.
-  const [mainImageLoaded, setMainImageLoaded] = useState(false);
+const ImageGalleryContent: React.FC<ImageGalleryProps> = memo(
+  ({ images, propertyName }) => {
+    const [lightboxIndex, setLightboxIndex] = useState<number | null>(null);
+    const [mainImageLoaded, setMainImageLoaded] = useState(false);
+    const [focusIndex, setFocusIndex] = useState(0);
+    const thumbRefs = useRef<(HTMLButtonElement | null)[]>([]);
 
-  const openLightbox = (index: number) => {
-    setLightboxIndex(index);
-  };
+    const imageCount = images?.length ?? 0;
+    const thumbSources = useMemo(
+      () => (images && images.length > 1 ? images.slice(1, 5) : []),
+      [images],
+    );
 
-  const closeLightbox = () => {
-    setLightboxIndex(null);
-  };
+    useEffect(() => {
+      if (imageCount > 0) {
+        trackGalleryEvent('gallery_view', {
+          propertyName,
+          imageCount,
+        });
+      }
+    }, [propertyName, imageCount]);
 
-  if (!images || images.length === 0) {
-    return (
-      <div className="relative rounded-xl overflow-hidden bg-gray-200 dark:bg-gray-700 h-[400px] flex items-center justify-center">
-        <div className="text-center">
-          <svg className="w-16 h-16 mx-auto mb-4 text-gray-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M4 16l4.586-4.586a2 2 0 012.828 0L16 16m-2-2l1.586-1.586a2 2 0 012.828 0L20 14m-6-6h.01M6 20h12a2 2 0 002-2V6a2 2 0 00-2-2H6a2 2 0 00-2 2v12a2 2 0 002 2z" />
-          </svg>
-          <p className="text-gray-500 dark:text-gray-400">No images available</p>
-        </div>
-      </div>
+    const openLightbox = useCallback(
+      (index: number, method: 'click' | 'keyboard' = 'click') => {
+        setLightboxIndex(index);
+        trackGalleryEvent('gallery_lightbox_open', {
+          propertyName,
+          imageIndex: index,
+          imageCount,
+          method,
+        });
+        if (method === 'click' && index > 0) {
+          trackGalleryEvent('gallery_thumbnail_click', {
+            propertyName,
+            imageIndex: index,
+            imageCount,
+          });
+        }
+      },
+      [propertyName, imageCount],
     );
-  }
 
-  return (
-    <>
-      <div className="space-y-4">
-        {/* Main Image */}
-        <div className="relative rounded-xl overflow-hidden cursor-pointer group">
-          <Image
-            src={images[0]}
-            alt={propertyName}
-            width={800}
-            height={600}
-            className="w-full h-[400px] object-cover transition-transform duration-300 group-hover:scale-105"
-            onClick={() => openLightbox(0)}
-            onLoad={() => setMainImageLoaded(true)}
-          />
+    const closeLightbox = useCallback(() => {
+      if (lightboxIndex !== null) {
+        trackGalleryEvent('gallery_lightbox_close', {
+          propertyName,
+          imageIndex: lightboxIndex,
+          imageCount,
+        });
+      }
+      setLightboxIndex(null);
+    }, [lightboxIndex, propertyName, imageCount]);
 
-          {/* Issue #1253 — loading skeleton, drawn over the image until it has
-              loaded. It is decorative, so it is hidden from assistive tech. */}
-          {!mainImageLoaded && (
-            <div
-              className="absolute inset-0 animate-pulse bg-gray-200 dark:bg-gray-700"
-              aria-hidden="true"
-            />
-          )}
-           
-          {/* Overlay with image count */}
-          <div className="absolute inset-0 bg-black bg-opacity-0 group-hover:bg-opacity-20 transition-all duration-300 flex items-center justify-center">
-            <div className="opacity-0 group-hover:opacity-100 transition-opacity duration-300 bg-white/90 backdrop-blur-sm px-4 py-2 rounded-lg">
-              <p className="text-gray-900 font-medium">Click to view all {images.length} images</p>
-            </div>
+    const handleLightboxNavigate = useCallback(
+      (nextIndex: number, direction: 'next' | 'previous' | 'jump') => {
+        trackGalleryEvent('gallery_lightbox_navigate', {
+          propertyName,
+          imageIndex: nextIndex,
+          imageCount,
+          direction,
+        });
+      },
+      [propertyName, imageCount],
+    );
+
+    // #1258 — grid keyboard navigation
+    const handleGridKeyDown = useCallback(
+      (e: React.KeyboardEvent, index: number) => {
+        if (!images || images.length === 0) return;
+        let next = index;
+        switch (e.key) {
+          case 'ArrowRight':
+          case 'ArrowDown':
+            e.preventDefault();
+            next = Math.min(images.length - 1, index + 1);
+            break;
+          case 'ArrowLeft':
+          case 'ArrowUp':
+            e.preventDefault();
+            next = Math.max(0, index - 1);
+            break;
+          case 'Home':
+            e.preventDefault();
+            next = 0;
+            break;
+          case 'End':
+            e.preventDefault();
+            next = images.length - 1;
+            break;
+          case 'Enter':
+          case ' ':
+            e.preventDefault();
+            openLightbox(index, 'keyboard');
+            trackGalleryEvent('gallery_keyboard_navigate', {
+              propertyName,
+              imageIndex: index,
+              imageCount,
+              method: 'keyboard',
+            });
+            return;
+          default:
+            return;
+        }
+        setFocusIndex(next);
+        // Focus thumbnail buttons when index maps into the strip (main = 0)
+        if (next === 0) {
+          // main image is a button too
+          thumbRefs.current[0]?.focus();
+        } else {
+          thumbRefs.current[next]?.focus();
+        }
+        trackGalleryEvent('gallery_keyboard_navigate', {
+          propertyName,
+          imageIndex: next,
+          imageCount,
+          method: 'keyboard',
+        });
+      },
+      [images, openLightbox, propertyName, imageCount],
+    );
+
+    if (!images || images.length === 0) {
+      return (
+        <div className="relative rounded-xl overflow-hidden bg-gray-200 dark:bg-gray-700 h-[400px] flex items-center justify-center">
+          <div className="text-center">
+            <svg
+              className="w-16 h-16 mx-auto mb-4 text-gray-400"
+              fill="none"
+              stroke="currentColor"
+              viewBox="0 0 24 24"
+              aria-hidden
+            >
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                strokeWidth={2}
+                d="M4 16l4.586-4.586a2 2 0 012.828 0L16 16m-2-2l1.586-1.586a2 2 0 012.828 0L20 14m-6-6h.01M6 20h12a2 2 0 002-2V6a2 2 0 00-2-2H6a2 2 0 00-2 2v12a2 2 0 002 2z"
+              />
+            </svg>
+            <p className="text-gray-500 dark:text-gray-400">No images available</p>
           </div>
         </div>
+      );
+    }
 
-        {/* Thumbnail Gallery */}
-        {images.length > 1 && (
-          <div className="grid grid-cols-4 gap-2">
-            {images.slice(1, 5).map((image, index) => {
-              const actualIndex = index + 1;
-              return (
-                <div 
-                  key={actualIndex} 
-                  className="relative rounded-lg overflow-hidden cursor-pointer group"
-                  onClick={() => openLightbox(actualIndex)}
+    return (
+      <>
+        <div
+          className="space-y-4"
+          role="region"
+          aria-label={`${propertyName} image gallery`}
+        >
+          {/* Main Image */}
+          <button
+            type="button"
+            ref={(el) => {
+              thumbRefs.current[0] = el;
+            }}
+            className="relative w-full rounded-xl overflow-hidden cursor-pointer group text-left focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-2"
+            onClick={() => openLightbox(0, 'click')}
+            onKeyDown={(e) => handleGridKeyDown(e, 0)}
+            aria-label={`View ${propertyName} main image`}
+            tabIndex={focusIndex === 0 ? 0 : -1}
+          >
+            {!mainImageLoaded && (
+              <div
+                className="absolute inset-0 bg-gray-200 dark:bg-gray-700 animate-pulse"
+                aria-hidden
+              />
+            )}
+            <Image
+              src={images[0]}
+              alt={propertyName}
+              width={800}
+              height={600}
+              className="w-full h-[400px] object-cover transition-transform duration-300 group-hover:scale-105"
+              onLoad={() => setMainImageLoaded(true)}
+              priority
+            />
+          </button>
+
+          {/* Thumbnail strip */}
+          {thumbSources.length > 0 && (
+            <div
+              className="grid grid-cols-4 gap-2"
+              role="listbox"
+              aria-label="Property image thumbnails"
+            >
+              {thumbSources.map((image, index) => {
+                const actualIndex = index + 1;
+                return (
+                  <button
+                    key={`${actualIndex}-${image}`}
+                    type="button"
+                    role="option"
+                    ref={(el) => {
+                      thumbRefs.current[actualIndex] = el;
+                    }}
+                    className="relative rounded-lg overflow-hidden cursor-pointer group focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-2"
+                    onClick={() => openLightbox(actualIndex, 'click')}
+                    onKeyDown={(e) => handleGridKeyDown(e, actualIndex)}
+                    aria-label={`${propertyName} - Image ${actualIndex + 1}`}
+                    aria-selected={focusIndex === actualIndex}
+                    tabIndex={focusIndex === actualIndex ? 0 : -1}
+                  >
+                    <Image
+                      src={image}
+                      alt={`${propertyName} - Image ${actualIndex + 1}`}
+                      width={200}
+                      height={150}
+                      className="w-full h-24 object-cover transition-transform duration-300 group-hover:scale-110"
+                    />
+                    <div className="absolute inset-0 bg-black bg-opacity-0 group-hover:bg-opacity-30 transition-all duration-300 flex items-center justify-center pointer-events-none">
+                      <svg
+                        className="w-6 h-6 text-white opacity-0 group-hover:opacity-100 transition-opacity duration-300"
+                        fill="none"
+                        stroke="currentColor"
+                        viewBox="0 0 24 24"
+                        aria-hidden
+                      >
+                        <path
+                          strokeLinecap="round"
+                          strokeLinejoin="round"
+                          strokeWidth={2}
+                          d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0zM10 7v3m0 0v3m0-3h3m-3 0H7"
+                        />
+                      </svg>
+                    </div>
+                  </button>
+                );
+              })}
+
+              {images.length > 5 && (
+                <button
+                  type="button"
+                  className="relative rounded-lg overflow-hidden bg-gray-200 dark:bg-gray-700 flex items-center justify-center cursor-pointer group focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500"
+                  onClick={() => openLightbox(5, 'click')}
+                  aria-label={`View ${images.length - 5} more images`}
                 >
-                  <Image
-                    src={image}
-                    alt={`${propertyName} - Image ${actualIndex + 1}`}
-                    width={200}
-                    height={150}
-                    className="w-full h-24 object-cover transition-transform duration-300 group-hover:scale-110"
-                  />
-                  
-                  {/* Hover overlay */}
-                  <div className="absolute inset-0 bg-black bg-opacity-0 group-hover:bg-opacity-30 transition-all duration-300 flex items-center justify-center">
-                    <svg className="w-6 h-6 text-white opacity-0 group-hover:opacity-100 transition-opacity duration-300" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0zM10 7v3m0 0v3m0-3h3m-3 0H7" />
-                    </svg>
+                  <div className="text-center">
+                    <div className="text-2xl font-bold text-gray-600 dark:text-gray-400 mb-1">
+                      +{images.length - 5}
+                    </div>
+                    <div className="text-xs text-gray-500 dark:text-gray-500">
+                      more
+                    </div>
                   </div>
-                </div>
-              );
-            })}
-            
-            {/* Show more indicator if there are more than 5 images */}
-            {images.length > 5 && (
-              <div className="relative rounded-lg overflow-hidden bg-gray-200 dark:bg-gray-700 flex items-center justify-center cursor-pointer group">
-                <div className="text-center">
-                  <div className="text-2xl font-bold text-gray-600 dark:text-gray-400 mb-1">
-                    +{images.length - 5}
-                  </div>
-                  <div className="text-xs text-gray-500 dark:text-gray-500">
-                    more
-                  </div>
-                </div>
-                <div className="absolute inset-0 bg-black bg-opacity-0 group-hover:bg-opacity-30 transition-all duration-300" />
-              </div>
-            )}
-          </div>
-        )}
-      </div>
+                </button>
+              )}
+            </div>
+          )}
+        </div>
 
-      {/* Lightbox */}
-      <ImageLightbox
-        images={images}
-        initialIndex={lightboxIndex || 0}
-        isOpen={lightboxIndex !== null}
-        onClose={closeLightbox}
-      />
-    </>
-  );
-};
+        <ImageLightbox
+          images={images}
+          initialIndex={lightboxIndex ?? 0}
+          isOpen={lightboxIndex !== null}
+          onClose={closeLightbox}
+          onNavigate={handleLightboxNavigate}
+        />
+      </>
+    );
+  },
+);
+ImageGalleryContent.displayName = 'ImageGalleryContent';
diff --git a/src/components/property/ImageLightbox.tsx b/src/components/property/ImageLightbox.tsx
index 9aabe59e..9489760b 100644
--- a/src/components/property/ImageLightbox.tsx
+++ b/src/components/property/ImageLightbox.tsx
@@ -9,6 +9,8 @@ interface ImageLightboxProps {
   initialIndex?: number;
   isOpen: boolean;
   onClose: () => void;
+  /** Optional analytics hook when the visible image changes (#1259). */
+  onNavigate?: (index: number, direction: 'next' | 'previous' | 'jump') => void;
 }
 
 export const ImageLightbox: React.FC<ImageLightboxProps> = ({
@@ -16,6 +18,7 @@ export const ImageLightbox: React.FC<ImageLightboxProps> = ({
   initialIndex = 0,
   isOpen,
   onClose,
+  onNavigate,
 }) => {
   const [currentIndex, setCurrentIndex] = useState(initialIndex);
   const [touchStart, setTouchStart] = useState<number | null>(null);
@@ -45,6 +48,31 @@ export const ImageLightbox: React.FC<ImageLightboxProps> = ({
     };
   }, [isOpen]);
 
+  const navigateNext = useCallback(() => {
+    setCurrentIndex((prev) => {
+      const next = (prev + 1) % images.length;
+      onNavigate?.(next, 'next');
+      return next;
+    });
+  }, [images.length, onNavigate]);
+
+  const navigatePrevious = useCallback(() => {
+    setCurrentIndex((prev) => {
+      const next = (prev - 1 + images.length) % images.length;
+      onNavigate?.(next, 'previous');
+      return next;
+    });
+  }, [images.length, onNavigate]);
+
+  const handleThumbnailClick = useCallback(
+    (index: number) => {
+      setCurrentIndex(index);
+      onNavigate?.(index, 'jump');
+    },
+    [onNavigate],
+  );
+
+  if (!isOpen || images.length === 0) return null;
   // Keyboard navigation
   useEffect(() => {
     if (!isOpen) return;
@@ -70,7 +98,7 @@ export const ImageLightbox: React.FC<ImageLightboxProps> = ({
       document.removeEventListener('keydown', handleKeyDown);
       document.body.style.overflow = 'unset';
     };
-  }, [isOpen, currentIndex]);
+  }, [isOpen, navigateNext, navigatePrevious, onClose]);
 
   // Touch handlers for mobile swipe
   const handleTouchStart = useCallback((e: React.TouchEvent) => {
@@ -95,21 +123,9 @@ export const ImageLightbox: React.FC<ImageLightboxProps> = ({
     if (isRightSwipe) {
       navigatePrevious();
     }
-  }, [touchStart, touchEnd]);
+  }, [touchStart, touchEnd, navigateNext, navigatePrevious]);
 
-  const navigateNext = () => {
-    setCurrentIndex((prev) => (prev + 1) % images.length);
-  };
 
-  const navigatePrevious = () => {
-    setCurrentIndex((prev) => (prev - 1 + images.length) % images.length);
-  };
-
-  const handleThumbnailClick = (index: number) => {
-    setCurrentIndex(index);
-  };
-
-  if (!isOpen || images.length === 0) return null;
 
   return (
     // Issue #1252 — `role="dialog"` + `aria-modal` tell assistive tech that
diff --git a/src/components/property/__tests__/ImageGallery.integration.test.tsx b/src/components/property/__tests__/ImageGallery.integration.test.tsx
new file mode 100644
index 00000000..63a9ee29
--- /dev/null
+++ b/src/components/property/__tests__/ImageGallery.integration.test.tsx
@@ -0,0 +1,99 @@
+/**
+ * Gallery integration tests (#1256) covering keyboard nav (#1258),
+ * analytics (#1259), and memoization surface (#1257).
+ */
+import React from 'react';
+import { render, screen, fireEvent } from '@testing-library/react';
+import { ImageGallery } from '../ImageGallery';
+import * as analytics from '@/lib/galleryAnalytics';
+
+jest.mock('next/image', () => ({
+  __esModule: true,
+  default: (props: any) => {
+    // eslint-disable-next-line @next/next/no-img-element, jsx-a11y/alt-text
+    return <img {...props} />;
+  },
+}));
+
+jest.mock('@/components/ui/SimpleErrorBoundary', () => ({
+  ErrorBoundary: ({ children }: { children: React.ReactNode }) => <>{children}</>,
+}));
+
+const images = [
+  '/img/a.jpg',
+  '/img/b.jpg',
+  '/img/c.jpg',
+  '/img/d.jpg',
+];
+
+describe('ImageGallery integration (#1256–#1259)', () => {
+  let trackSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    trackSpy = jest.spyOn(analytics, 'trackGalleryEvent').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    trackSpy.mockRestore();
+  });
+
+  it('renders empty state when there are no images', () => {
+    render(<ImageGallery images={[]} propertyName="Empty Lot" />);
+    expect(screen.getByText('No images available')).toBeInTheDocument();
+  });
+
+  it('fires gallery_view on mount', () => {
+    render(<ImageGallery images={images} propertyName="Sky Villa" />);
+    expect(trackSpy).toHaveBeenCalledWith(
+      'gallery_view',
+      expect.objectContaining({ propertyName: 'Sky Villa', imageCount: 4 }),
+    );
+  });
+
+  it('opens lightbox on main image click and tracks analytics', () => {
+    render(<ImageGallery images={images} propertyName="Sky Villa" />);
+    fireEvent.click(screen.getByLabelText('View Sky Villa main image'));
+    expect(trackSpy).toHaveBeenCalledWith(
+      'gallery_lightbox_open',
+      expect.objectContaining({ imageIndex: 0, method: 'click' }),
+    );
+    expect(screen.getByRole('dialog')).toBeInTheDocument();
+  });
+
+  it('supports keyboard navigation on the main image (Enter opens)', () => {
+    render(<ImageGallery images={images} propertyName="Sky Villa" />);
+    const main = screen.getByLabelText('View Sky Villa main image');
+    main.focus();
+    fireEvent.keyDown(main, { key: 'Enter' });
+    expect(trackSpy).toHaveBeenCalledWith(
+      'gallery_lightbox_open',
+      expect.objectContaining({ method: 'keyboard' }),
+    );
+    expect(screen.getByRole('dialog')).toBeInTheDocument();
+  });
+
+  it('moves focus with arrow keys on the gallery grid', () => {
+    render(<ImageGallery images={images} propertyName="Sky Villa" />);
+    const main = screen.getByLabelText('View Sky Villa main image');
+    main.focus();
+    fireEvent.keyDown(main, { key: 'ArrowRight' });
+    expect(trackSpy).toHaveBeenCalledWith(
+      'gallery_keyboard_navigate',
+      expect.objectContaining({ method: 'keyboard' }),
+    );
+  });
+
+  it('closes lightbox with Escape and tracks close', () => {
+    render(<ImageGallery images={images} propertyName="Sky Villa" />);
+    fireEvent.click(screen.getByLabelText('View Sky Villa main image'));
+    fireEvent.keyDown(document, { key: 'Escape' });
+    expect(trackSpy).toHaveBeenCalledWith(
+      'gallery_lightbox_close',
+      expect.objectContaining({ propertyName: 'Sky Villa' }),
+    );
+  });
+
+  it('exports a memoized component (displayName set)', () => {
+    expect(ImageGallery.displayName).toBe('ImageGallery');
+  });
+});
diff --git a/src/lib/__tests__/galleryAnalytics.test.ts b/src/lib/__tests__/galleryAnalytics.test.ts
new file mode 100644
index 00000000..2e7610ba
--- /dev/null
+++ b/src/lib/__tests__/galleryAnalytics.test.ts
@@ -0,0 +1,39 @@
+import { trackGalleryEvent } from '../galleryAnalytics';
+
+describe('galleryAnalytics (#1259)', () => {
+  beforeEach(() => {
+    (window as any).dataLayer = [];
+    (window as any).gtag = jest.fn();
+  });
+
+  afterEach(() => {
+    delete (window as any).gtag;
+  });
+
+  it('pushes events to dataLayer and gtag', () => {
+    trackGalleryEvent('gallery_lightbox_open', {
+      propertyName: 'Villa',
+      imageIndex: 1,
+      imageCount: 4,
+      method: 'click',
+    });
+    expect((window as any).dataLayer.length).toBeGreaterThan(0);
+    expect((window as any).dataLayer[0]).toMatchObject({
+      event: 'gallery_lightbox_open',
+      category: 'gallery',
+      propertyName: 'Villa',
+    });
+    expect((window as any).gtag).toHaveBeenCalledWith(
+      'event',
+      'gallery_lightbox_open',
+      expect.objectContaining({ event_category: 'gallery' }),
+    );
+  });
+
+  it('does not throw when gtag is missing', () => {
+    delete (window as any).gtag;
+    expect(() =>
+      trackGalleryEvent('gallery_view', { imageCount: 0 }),
+    ).not.toThrow();
+  });
+});
diff --git a/src/lib/galleryAnalytics.ts b/src/lib/galleryAnalytics.ts
new file mode 100644
index 00000000..d092d2d3
--- /dev/null
+++ b/src/lib/galleryAnalytics.ts
@@ -0,0 +1,54 @@
+/**
+ * Gallery analytics events (#1259).
+ * Pushes structured events to the gtag dataLayer when available; no-ops otherwise.
+ */
+
+export type GalleryAnalyticsEvent =
+  | 'gallery_view'
+  | 'gallery_thumbnail_click'
+  | 'gallery_lightbox_open'
+  | 'gallery_lightbox_close'
+  | 'gallery_lightbox_navigate'
+  | 'gallery_keyboard_navigate';
+
+export interface GalleryEventPayload {
+  propertyName?: string;
+  imageIndex?: number;
+  imageCount?: number;
+  direction?: 'next' | 'previous' | 'jump';
+  method?: 'click' | 'keyboard' | 'swipe';
+}
+
+declare global {
+  interface Window {
+    dataLayer?: unknown[];
+    gtag?: (...args: unknown[]) => void;
+  }
+}
+
+/** Track a gallery interaction. Safe to call on the server (no-ops). */
+export function trackGalleryEvent(
+  event: GalleryAnalyticsEvent,
+  payload: GalleryEventPayload = {},
+): void {
+  if (typeof window === 'undefined') return;
+
+  const detail = {
+    event,
+    category: 'gallery',
+    ...payload,
+  };
+
+  try {
+    if (typeof window.gtag === 'function') {
+      window.gtag('event', event, {
+        event_category: 'gallery',
+        ...payload,
+      });
+    }
+    window.dataLayer = window.dataLayer || [];
+    window.dataLayer.push(detail);
+  } catch {
+    // Analytics must never break the UI.
+  }
+}