@akinon/pz-theme 2.0.37-rc.0 → 2.0.38-beta.0

package/src/blocks/__tests__/product-gallery-block.test.tsx

@@ -0,0 +1,974 @@
+import fs from 'fs';
+import path from 'path';
+import React from 'react';
+import { fireEvent, render } from '@testing-library/react';
+import ProductGalleryBlock from '../product-gallery-block';
+import { ThemePageContextProvider } from '../../theme-page-context';
+
+/**
+ * jsdom ships no PointerEvent, and testing-library then falls back to a plain
+ * Event — which carries no coordinates, so every gesture assertion would pass
+ * or fail on NaN rather than on the behaviour. MouseEvent already models the
+ * coordinates; only the two pointer fields have to be added.
+ */
+if (typeof window.PointerEvent === 'undefined') {
+  class PointerEventPolyfill extends MouseEvent {
+    public pointerId: number;
+    public pointerType: string;
+
+    constructor(type: string, init: PointerEventInit = {}) {
+      super(type, init);
+      this.pointerId = init.pointerId ?? 0;
+      this.pointerType = init.pointerType ?? '';
+    }
+  }
+
+  (window as unknown as Record<string, unknown>).PointerEvent =
+    PointerEventPolyfill;
+}
+
+/**
+ * Zoom, the full-screen viewer and the fallback image are all opt-in, so the
+ * first suite here is the one that matters most: a block carrying none of the
+ * new properties must render the exact markup it rendered before they existed.
+ * The snapshots in this file were captured from the block at HEAD, BEFORE a
+ * line of the new code was written — they are a golden, not a recording of the
+ * current behaviour.
+ */
+const renderBlock = (
+  properties: Record<string, unknown>,
+  product: Record<string, unknown> | null,
+  extra: Record<string, unknown> = {}
+) =>
+  render(
+    <ThemePageContextProvider value={product ? { product } : null}>
+      <ProductGalleryBlock
+        {...({
+          block: {
+            id: 'gallery',
+            type: 'product-gallery',
+            styles: {},
+            properties,
+            order: 0,
+            hidden: false
+          },
+          placeholderId: 'p',
+          sectionId: 's',
+          isDesigner: false,
+          currentBreakpoint: 'desktop',
+          ...extra
+        } as any)}
+      />
+    </ThemePageContextProvider>
+  );
+
+const PRODUCT = {
+  pk: 1,
+  name: 'Wool Coat',
+  images: [
+    { url: 'https://cdn.example.com/a.jpg', alt: 'front' },
+    { url: 'https://cdn.example.com/b.jpg', alt: 'back' },
+    { url: 'https://cdn.example.com/c.jpg' }
+  ]
+};
+
+describe('ProductGalleryBlock — golden default render', () => {
+  it('renders the carousel exactly as it did before zoom existed', () => {
+    const { container } = renderBlock({}, PRODUCT);
+
+    expect(container.innerHTML).toMatchSnapshot();
+  });
+
+  it('renders the grid layout unchanged', () => {
+    const { container } = renderBlock({ layout: 'grid' }, PRODUCT);
+
+    expect(container.innerHTML).toMatchSnapshot();
+  });
+
+  it('renders arrows, dots and the counter unchanged', () => {
+    const { container } = renderBlock(
+      { showArrows: true, showDots: true, showCounter: true },
+      PRODUCT
+    );
+
+    expect(container.innerHTML).toMatchSnapshot();
+  });
+
+  it('renders the side-thumbnail arrangement unchanged', () => {
+    const { container } = renderBlock(
+      { thumbPosition: 'left', thumbSize: 80, thumbLimit: 2 },
+      PRODUCT
+    );
+
+    expect(container.innerHTML).toMatchSnapshot();
+  });
+
+  it('renders the single-image product unchanged', () => {
+    const { container } = renderBlock({}, { pk: 2, image: 'https://cdn.example.com/only.jpg' });
+
+    expect(container.innerHTML).toMatchSnapshot();
+  });
+
+  it('renders nothing on the storefront when the product has no photos', () => {
+    const { container } = renderBlock({}, { pk: 3 });
+
+    expect(container.innerHTML).toBe('');
+  });
+
+  it('renders the designer placeholder when the product has no photos', () => {
+    const { container } = renderBlock({}, { pk: 3 }, { isDesigner: true });
+
+    expect(container.innerHTML).toMatchSnapshot();
+  });
+
+  it('renders the designer carousel unchanged', () => {
+    const { container } = renderBlock({}, PRODUCT, { isDesigner: true });
+
+    expect(container.innerHTML).toMatchSnapshot();
+  });
+
+  it('draws no enlargement affordance of any kind by default', () => {
+    const { container } = renderBlock({}, PRODUCT);
+
+    expect(container.querySelector('[data-part="viewer-trigger"]')).toBeNull();
+    expect(container.querySelector('[data-part="zoom-image"]')).toBeNull();
+    expect(container.querySelector('[data-part="zoom-hint"]')).toBeNull();
+    expect(container.querySelector('[role="dialog"]')).toBeNull();
+  });
+});
+
+/** jsdom measures nothing, so the frame is given a size to zoom against. */
+const sizeFrame = (element: Element | null) => {
+  if (!element) throw new Error('no frame');
+  element.getBoundingClientRect = () =>
+    ({ left: 0, top: 0, width: 200, height: 400 }) as DOMRect;
+};
+
+describe('ProductGalleryBlock — pointer zoom', () => {
+  it('magnifies the region under a mouse and drops it on leave', () => {
+    const { container } = renderBlock({ enableZoom: true }, PRODUCT);
+    const frame = container.querySelector('[data-product-gallery-main]');
+    sizeFrame(frame);
+
+    fireEvent.pointerMove(frame!, {
+      pointerType: 'mouse',
+      clientX: 50,
+      clientY: 100
+    });
+
+    const layer = container.querySelector<HTMLElement>(
+      '[data-part="zoom-image"]'
+    );
+    expect(layer).not.toBeNull();
+    expect(layer?.style.transform).toBe('scale(2)');
+    expect(layer?.style.transformOrigin).toBe('25% 25%');
+    // The frame reports it so a brand can restyle it while it is magnified.
+    expect(frame?.getAttribute('data-state')).toBe('open');
+
+    fireEvent.pointerLeave(frame!);
+    expect(container.querySelector('[data-part="zoom-image"]')).toBeNull();
+  });
+
+  it('honours the authored magnification', () => {
+    const { container } = renderBlock(
+      { enableZoom: true, zoomLevel: 3.5 },
+      PRODUCT
+    );
+    const frame = container.querySelector('[data-product-gallery-main]');
+    sizeFrame(frame);
+
+    fireEvent.pointerMove(frame!, {
+      pointerType: 'mouse',
+      clientX: 100,
+      clientY: 200
+    });
+
+    expect(
+      container.querySelector<HTMLElement>('[data-part="zoom-image"]')?.style
+        .transform
+    ).toBe('scale(3.5)');
+  });
+
+  it('ignores a finger — a touch has no hover to magnify under', () => {
+    const { container } = renderBlock({ enableZoom: true }, PRODUCT);
+    const frame = container.querySelector('[data-product-gallery-main]');
+    sizeFrame(frame);
+
+    fireEvent.pointerMove(frame!, {
+      pointerType: 'touch',
+      clientX: 50,
+      clientY: 100
+    });
+
+    expect(container.querySelector('[data-part="zoom-image"]')).toBeNull();
+  });
+
+  it('never magnifies under the author pointer in the designer', () => {
+    const { container } = renderBlock({ enableZoom: true }, PRODUCT, {
+      isDesigner: true
+    });
+    const frame = container.querySelector('[data-product-gallery-main]');
+    sizeFrame(frame);
+
+    fireEvent.pointerMove(frame!, {
+      pointerType: 'mouse',
+      clientX: 50,
+      clientY: 100
+    });
+
+    expect(container.querySelector('[data-part="zoom-image"]')).toBeNull();
+  });
+
+  it('scales the asset commerce sent until a larger one is named', () => {
+    const { container } = renderBlock({ enableZoom: true }, PRODUCT);
+    const frame = container.querySelector('[data-product-gallery-main]');
+    sizeFrame(frame);
+
+    fireEvent.pointerMove(frame!, {
+      pointerType: 'mouse',
+      clientX: 50,
+      clientY: 100
+    });
+
+    expect(
+      container.querySelector('[data-part="zoom-image"]')?.getAttribute('src')
+    ).toBe('https://cdn.example.com/a.jpg');
+  });
+});
+
+const openViewer = (container: HTMLElement) => {
+  const trigger = container.querySelector<HTMLElement>(
+    '[data-part="viewer-trigger"]'
+  );
+  if (!trigger) throw new Error('no viewer trigger');
+  fireEvent.click(trigger);
+  return trigger;
+};
+
+describe('ProductGalleryBlock — full-screen viewer', () => {
+  it('opens from the photo and reaches the other photos from inside', () => {
+    const { container } = renderBlock(
+      { enableViewer: true, viewerShowThumbs: true, viewerShowCounter: true },
+      PRODUCT
+    );
+
+    openViewer(container);
+
+    const dialog = container.querySelector('[role="dialog"]');
+    expect(dialog).not.toBeNull();
+    expect(dialog?.getAttribute('aria-label')).toBe('Product images');
+    expect(
+      container.querySelector('[data-part="viewer-image"]')?.getAttribute('src')
+    ).toBe('https://cdn.example.com/a.jpg');
+    expect(
+      container.querySelector('[data-part="viewer-counter"]')?.textContent
+    ).toBe('1 / 3');
+
+    fireEvent.click(
+      container.querySelector('[data-product-gallery-viewer-arrow="next"]')!
+    );
+    expect(
+      container.querySelector('[data-part="viewer-image"]')?.getAttribute('src')
+    ).toBe('https://cdn.example.com/b.jpg');
+
+    const thumbs = container.querySelectorAll('[data-part="viewer-thumb"]');
+    expect(thumbs).toHaveLength(3);
+    fireEvent.click(thumbs[2]);
+    expect(
+      container.querySelector('[data-part="viewer-image"]')?.getAttribute('src')
+    ).toBe('https://cdn.example.com/c.jpg');
+  });
+
+  it('claims aria-modal on the storefront and never in the designer', () => {
+    const shop = renderBlock({ enableViewer: true }, PRODUCT);
+    openViewer(shop.container);
+    expect(
+      shop.container.querySelector('[role="dialog"]')?.getAttribute('aria-modal')
+    ).toBe('true');
+
+    const canvas = renderBlock({ enableViewer: true }, PRODUCT, {
+      isDesigner: true
+    });
+    openViewer(canvas.container);
+    // The trap is deliberately not armed on the canvas, so the claim would
+    // describe a dialog that does not exist.
+    expect(
+      canvas.container
+        .querySelector('[role="dialog"]')
+        ?.getAttribute('aria-modal')
+    ).toBeNull();
+  });
+
+  it('moves focus in, traps it, and hands it back to the opener', () => {
+    const { container } = renderBlock({ enableViewer: true }, PRODUCT);
+    const trigger = openViewer(container);
+
+    const close = container.querySelector<HTMLElement>(
+      '[data-part="viewer-close"]'
+    );
+    expect(document.activeElement).toBe(close);
+
+    // Focus escaping into the page behind is pulled straight back.
+    document.body.focus();
+    fireEvent.focusIn(document.body, { target: document.body });
+    expect(container.contains(document.activeElement)).toBe(true);
+
+    fireEvent.keyDown(document, { key: 'Escape' });
+    expect(container.querySelector('[role="dialog"]')).toBeNull();
+    expect(document.activeElement).toBe(trigger);
+  });
+
+  it('always keeps a pointer way out, whatever else is switched off', () => {
+    const { container } = renderBlock(
+      { enableViewer: true, viewerCloseOnEscape: false, viewerShowArrows: false },
+      PRODUCT
+    );
+    openViewer(container);
+
+    fireEvent.keyDown(document, { key: 'Escape' });
+    expect(container.querySelector('[role="dialog"]')).not.toBeNull();
+
+    const close = container.querySelector('[data-part="viewer-close"]');
+    expect(close).not.toBeNull();
+    fireEvent.click(close!);
+    expect(container.querySelector('[role="dialog"]')).toBeNull();
+  });
+
+  /**
+   * The backdrop is painted, then the dialog is laid over the whole viewport
+   * on top of it — so no tap ever reaches the backdrop. What a shopper can
+   * actually hit around the photo is the stage, and that must NOT dismiss the
+   * viewer: the first half of a double-tap-to-zoom lands there.
+   */
+  it('keeps the viewer up under the taps a shopper can actually land', () => {
+    const { container } = renderBlock({ enableViewer: true }, PRODUCT);
+    openViewer(container);
+
+    const stage = () => container.querySelector('[data-part="viewer-stage"]')!;
+
+    fireEvent.click(stage());
+    expect(container.querySelector('[role="dialog"]')).not.toBeNull();
+
+    fireEvent.doubleClick(stage());
+    expect(container.querySelector('[role="dialog"]')).not.toBeNull();
+    expect(
+      container.querySelector<HTMLElement>('[data-part="viewer-image"]')?.style
+        .transform
+    ).toBe('translate(0px, 0px) scale(3)');
+
+    fireEvent.click(container.querySelector('[data-part="viewer-close"]')!);
+    expect(container.querySelector('[role="dialog"]')).toBeNull();
+  });
+
+  it('gives the page back its own scrolling on every visit', () => {
+    // A storefront that sets its own overflow has to get THAT value back.
+    document.body.style.overflow = 'auto';
+
+    const { container, unmount } = renderBlock({ enableViewer: true }, PRODUCT);
+
+    openViewer(container);
+    expect(document.body.style.overflow).toBe('hidden');
+
+    fireEvent.click(container.querySelector('[data-part="viewer-close"]')!);
+    expect(document.body.style.overflow).toBe('auto');
+
+    // A lock leaked on the first visit leaves the page frozen from here on.
+    openViewer(container);
+    expect(document.body.style.overflow).toBe('hidden');
+
+    // Navigating away with the viewer up must not freeze what comes next.
+    unmount();
+    expect(document.body.style.overflow).toBe('auto');
+
+    document.body.style.overflow = '';
+  });
+
+  it('leaves the page alone in the designer', () => {
+    const { container } = renderBlock({ enableViewer: true }, PRODUCT, {
+      isDesigner: true
+    });
+    openViewer(container);
+
+    expect(document.body.style.overflow).toBe('');
+  });
+
+  it('opens every grid cell at the photo that was clicked', () => {
+    const { container } = renderBlock(
+      { layout: 'grid', enableViewer: true },
+      PRODUCT
+    );
+
+    const triggers = container.querySelectorAll('[data-part="viewer-trigger"]');
+    expect(triggers).toHaveLength(3);
+
+    fireEvent.click(triggers[1]);
+    expect(
+      container.querySelector('[data-part="viewer-image"]')?.getAttribute('src')
+    ).toBe('https://cdn.example.com/b.jpg');
+  });
+
+  it('swipes to the next photo and back', () => {
+    const { container } = renderBlock({ enableViewer: true }, PRODUCT);
+    openViewer(container);
+
+    const stage = container.querySelector('[data-part="viewer-stage"]')!;
+    const swipe = (from: number, to: number) => {
+      fireEvent.pointerDown(stage, { pointerId: 1, clientX: from, clientY: 40 });
+      fireEvent.pointerMove(stage, { pointerId: 1, clientX: to, clientY: 40 });
+      fireEvent.pointerUp(stage, { pointerId: 1, clientX: to, clientY: 40 });
+    };
+
+    swipe(300, 100);
+    expect(
+      container.querySelector('[data-part="viewer-image"]')?.getAttribute('src')
+    ).toBe('https://cdn.example.com/b.jpg');
+
+    swipe(100, 300);
+    expect(
+      container.querySelector('[data-part="viewer-image"]')?.getAttribute('src')
+    ).toBe('https://cdn.example.com/a.jpg');
+  });
+
+  it('does not mistake a tap or a short drag for a swipe', () => {
+    const { container } = renderBlock({ enableViewer: true }, PRODUCT);
+    openViewer(container);
+
+    const stage = container.querySelector('[data-part="viewer-stage"]')!;
+    fireEvent.pointerDown(stage, { pointerId: 1, clientX: 300, clientY: 40 });
+    fireEvent.pointerMove(stage, { pointerId: 1, clientX: 288, clientY: 40 });
+    fireEvent.pointerUp(stage, { pointerId: 1, clientX: 288, clientY: 40 });
+
+    expect(
+      container.querySelector('[data-part="viewer-image"]')?.getAttribute('src')
+    ).toBe('https://cdn.example.com/a.jpg');
+  });
+
+  it('pinches to zoom, then pans instead of swiping, and double-tap resets', () => {
+    const { container } = renderBlock({ enableViewer: true }, PRODUCT);
+    openViewer(container);
+
+    const stage = container.querySelector('[data-part="viewer-stage"]')!;
+    const image = container.querySelector<HTMLElement>(
+      '[data-part="viewer-image"]'
+    )!;
+
+    fireEvent.pointerDown(stage, { pointerId: 1, clientX: 100, clientY: 100 });
+    fireEvent.pointerDown(stage, { pointerId: 2, clientX: 140, clientY: 100 });
+    fireEvent.pointerMove(stage, { pointerId: 2, clientX: 220, clientY: 100 });
+
+    expect(image.style.transform).toBe('translate(0px, 0px) scale(3)');
+    expect(image.getAttribute('data-state')).toContain('active');
+
+    // One finger up, the other keeps dragging: that is a pan, not a swipe.
+    fireEvent.pointerUp(stage, { pointerId: 2, clientX: 220, clientY: 100 });
+    fireEvent.pointerMove(stage, { pointerId: 1, clientX: 130, clientY: 120 });
+    expect(image.style.transform).toBe('translate(30px, 20px) scale(3)');
+
+    fireEvent.pointerUp(stage, { pointerId: 1, clientX: 130, clientY: 120 });
+    expect(
+      container.querySelector('[data-part="viewer-image"]')?.getAttribute('src')
+    ).toBe('https://cdn.example.com/a.jpg');
+
+    fireEvent.doubleClick(stage);
+    expect(
+      container.querySelector<HTMLElement>('[data-part="viewer-image"]')?.style
+        .transform
+    ).toBe('translate(0px, 0px) scale(1)');
+  });
+
+  /**
+   * A finger resting on the photo while the other hand taps Close is never
+   * followed by a pointerup. If that id stays booked, every later one-finger
+   * drag is counted as the second finger of a pinch and no swipe fires again.
+   */
+  it('still swipes on later visits after a finger was down when it closed', () => {
+    const { container } = renderBlock({ enableViewer: true }, PRODUCT);
+    const stage = () => container.querySelector('[data-part="viewer-stage"]')!;
+    const shownPhoto = () =>
+      container.querySelector('[data-part="viewer-image"]')?.getAttribute('src');
+
+    openViewer(container);
+    fireEvent.pointerDown(stage(), { pointerId: 7, clientX: 120, clientY: 40 });
+    fireEvent.click(container.querySelector('[data-part="viewer-close"]')!);
+
+    const swipeLeft = (pointerId: number) => {
+      fireEvent.pointerDown(stage(), { pointerId, clientX: 300, clientY: 40 });
+      fireEvent.pointerMove(stage(), { pointerId, clientX: 100, clientY: 40 });
+      fireEvent.pointerUp(stage(), { pointerId, clientX: 100, clientY: 40 });
+    };
+
+    openViewer(container);
+    swipeLeft(8);
+    expect(shownPhoto()).toBe('https://cdn.example.com/b.jpg');
+    fireEvent.click(container.querySelector('[data-part="viewer-close"]')!);
+
+    openViewer(container);
+    swipeLeft(9);
+    expect(shownPhoto()).toBe('https://cdn.example.com/c.jpg');
+  });
+
+  /**
+   * A PDP swaps the photo list under the gallery when the shopper picks
+   * another colour, and it can do that while the viewer is up — the cell that
+   * opened it is then gone by the time it closes. Handing focus back to a
+   * detached node silently drops a keyboard shopper at the top of the
+   * document, with the gallery they were reading nowhere near the caret.
+   */
+  it('lands focus back on the gallery when the trigger it came from is gone', () => {
+    const Gallery = ({ images }: { images: unknown[] }) => (
+      <ThemePageContextProvider
+        value={{ product: { pk: 1, name: 'Wool Coat', images } }}
+      >
+        <ProductGalleryBlock
+          {...({
+            block: {
+              id: 'gallery',
+              type: 'product-gallery',
+              styles: {},
+              properties: { layout: 'grid', enableViewer: true },
+              order: 0,
+              hidden: false
+            },
+            placeholderId: 'p',
+            sectionId: 's',
+            isDesigner: false,
+            currentBreakpoint: 'desktop'
+          } as any)}
+        />
+      </ThemePageContextProvider>
+    );
+
+    const { container, rerender } = render(<Gallery images={PRODUCT.images} />);
+
+    const opener = container.querySelectorAll<HTMLElement>(
+      '[data-part="viewer-trigger"]'
+    )[2];
+    // A real click focuses the button it lands on; jsdom's does not, and
+    // without it the handover is measured from a page where nothing had focus.
+    opener.focus();
+    fireEvent.click(opener);
+
+    rerender(<Gallery images={[PRODUCT.images[0]]} />);
+    expect(opener.isConnected).toBe(false);
+
+    fireEvent.click(container.querySelector('[data-part="viewer-close"]')!);
+
+    expect(document.activeElement).toBe(
+      container.querySelector('[data-part="viewer-trigger"]')
+    );
+  });
+
+  it('resets the magnification when the photo changes', () => {
+    const { container } = renderBlock({ enableViewer: true }, PRODUCT);
+    openViewer(container);
+
+    const stage = container.querySelector('[data-part="viewer-stage"]')!;
+    fireEvent.doubleClick(stage);
+    expect(
+      container.querySelector<HTMLElement>('[data-part="viewer-image"]')?.style
+        .transform
+    ).toBe('translate(0px, 0px) scale(3)');
+
+    fireEvent.click(
+      container.querySelector('[data-product-gallery-viewer-arrow="next"]')!
+    );
+    expect(
+      container.querySelector<HTMLElement>('[data-part="viewer-image"]')?.style
+        .transform
+    ).toBe('translate(0px, 0px) scale(1)');
+  });
+});
+
+describe('ProductGalleryBlock — high-resolution source', () => {
+  it('asks the CDN for a larger rendition inside the viewer', () => {
+    const { container } = renderBlock(
+      { enableViewer: true, highResTemplate: '{url}?width=2000' },
+      PRODUCT
+    );
+    openViewer(container);
+
+    expect(
+      container.querySelector('[data-part="viewer-image"]')?.getAttribute('src')
+    ).toBe('https://cdn.example.com/a.jpg?width=2000');
+  });
+
+  it('falls back to the asset commerce sent when the larger one 404s', () => {
+    const { container } = renderBlock(
+      { enableViewer: true, highResTemplate: '{url}?width=2000' },
+      PRODUCT
+    );
+    openViewer(container);
+
+    const image = container.querySelector('[data-part="viewer-image"]')!;
+    fireEvent.error(image);
+
+    expect(
+      container.querySelector('[data-part="viewer-image"]')?.getAttribute('src')
+    ).toBe('https://cdn.example.com/a.jpg');
+  });
+
+  it('ignores a template with no binding rather than pointing every photo at one url', () => {
+    const { container } = renderBlock(
+      { enableViewer: true, highResTemplate: 'https://cdn.example.com/big.jpg' },
+      PRODUCT
+    );
+    openViewer(container);
+
+    expect(
+      container.querySelector('[data-part="viewer-image"]')?.getAttribute('src')
+    ).toBe('https://cdn.example.com/a.jpg');
+  });
+
+  it('refuses a template that resolves to a script url', () => {
+    const { container } = renderBlock(
+      { enableViewer: true, highResTemplate: 'javascript:alert(1)//{url}' },
+      PRODUCT
+    );
+    openViewer(container);
+
+    expect(
+      container.querySelector('[data-part="viewer-image"]')?.getAttribute('src')
+    ).toBe('https://cdn.example.com/a.jpg');
+  });
+});
+
+describe('ProductGalleryBlock — fallback photo', () => {
+  const FALLBACK = 'https://cdn.example.com/placeholder.png';
+
+  it('still renders nothing when no fallback is authored', () => {
+    const { container } = renderBlock({}, { pk: 9, images: [] });
+
+    expect(container.innerHTML).toBe('');
+  });
+
+  it('stands in for a product with no photos at all', () => {
+    const { container } = renderBlock(
+      { fallbackImage: FALLBACK, fallbackAlt: 'Photo coming soon' },
+      { pk: 9 }
+    );
+
+    const image = container.querySelector('[data-part="image"]');
+    expect(image?.getAttribute('src')).toBe(FALLBACK);
+    expect(image?.getAttribute('alt')).toBe('Photo coming soon');
+    expect(image?.getAttribute('data-state')).toBe('empty');
+    expect(
+      container
+        .querySelector('[data-product-gallery-main]')
+        ?.getAttribute('data-state')
+    ).toBe('empty');
+  });
+
+  it('stands in when the payload carries only empty urls', () => {
+    const { container } = renderBlock(
+      { fallbackImage: FALLBACK },
+      { pk: 9, images: [{ url: '' }, { image: '   ' }] }
+    );
+
+    expect(
+      container.querySelector('[data-part="image"]')?.getAttribute('src')
+    ).toBe(FALLBACK);
+  });
+
+  it('takes over the frame and the thumbnail when a photo fails to load', () => {
+    const { container } = renderBlock({ fallbackImage: FALLBACK }, PRODUCT);
+
+    fireEvent.error(container.querySelector('[data-part="image"]')!);
+
+    const image = container.querySelector('[data-part="image"]');
+    expect(image?.getAttribute('src')).toBe(FALLBACK);
+    expect(image?.getAttribute('data-state')).toBe('empty');
+    // The same dead url in the strip is swapped too.
+    const thumb = container.querySelector('[data-part="thumb-image"]');
+    expect(thumb?.getAttribute('src')).toBe(FALLBACK);
+    // Only the photo that failed; the others are untouched.
+    expect(
+      container.querySelectorAll('[data-part="thumb-image"]')[1].getAttribute('src')
+    ).toBe('https://cdn.example.com/b.jpg');
+  });
+
+  it('does not loop when the fallback itself fails', () => {
+    const { container } = renderBlock({ fallbackImage: FALLBACK }, { pk: 9 });
+
+    const image = container.querySelector('[data-part="image"]')!;
+    fireEvent.error(image);
+    fireEvent.error(image);
+
+    expect(
+      container.querySelector('[data-part="image"]')?.getAttribute('src')
+    ).toBe(FALLBACK);
+  });
+
+  it('refuses a script url as a fallback and keeps the old behaviour', () => {
+    const { container } = renderBlock(
+      { fallbackImage: 'java\tscript:alert(1)' },
+      { pk: 9 }
+    );
+
+    expect(container.innerHTML).toBe('');
+  });
+
+  it('refuses an svg data url, which carries markup', () => {
+    const { container } = renderBlock(
+      { fallbackImage: 'data:image/svg+xml,<svg onload="alert(1)"/>' },
+      { pk: 9 }
+    );
+
+    expect(container.innerHTML).toBe('');
+  });
+
+  /**
+   * Grid cells past the first row are lazy, so a photo the shopper never
+   * scrolled to has never been requested — the viewer is its first requester,
+   * and its failure is the first anything hears of the dead url.
+   */
+  it('takes over inside the viewer when the photo the viewer asked for is dead', () => {
+    const { container } = renderBlock(
+      {
+        layout: 'grid',
+        enableViewer: true,
+        fallbackImage: FALLBACK,
+        fallbackAlt: 'Photo coming soon'
+      },
+      PRODUCT
+    );
+
+    const triggers = container.querySelectorAll('[data-part="viewer-trigger"]');
+    fireEvent.click(triggers[2]);
+
+    const image = () => container.querySelector('[data-part="viewer-image"]');
+    expect(image()?.getAttribute('src')).toBe('https://cdn.example.com/c.jpg');
+
+    fireEvent.error(image()!);
+
+    expect(image()?.getAttribute('src')).toBe(FALLBACK);
+    expect(image()?.getAttribute('alt')).toBe('Photo coming soon');
+    expect(image()?.getAttribute('data-state')).toContain('empty');
+  });
+
+  it('drops the larger rendition first, then gives up on the url itself', () => {
+    const { container } = renderBlock(
+      {
+        enableViewer: true,
+        highResTemplate: '{url}?width=2000',
+        fallbackImage: FALLBACK
+      },
+      PRODUCT
+    );
+    openViewer(container);
+
+    const image = () => container.querySelector('[data-part="viewer-image"]');
+    expect(image()?.getAttribute('src')).toBe(
+      'https://cdn.example.com/a.jpg?width=2000'
+    );
+
+    fireEvent.error(image()!);
+    expect(image()?.getAttribute('src')).toBe('https://cdn.example.com/a.jpg');
+    expect(image()?.getAttribute('data-state') ?? '').not.toContain('empty');
+
+    // Only now is the url itself given up on — and the fallback is asked for
+    // at the same larger rendition, since the template is a CDN address rule.
+    fireEvent.error(image()!);
+    expect(image()?.getAttribute('src')).toBe(`${FALLBACK}?width=2000`);
+    expect(image()?.getAttribute('data-state')).toContain('empty');
+
+    // A fallback that will not load either has to come to rest, not loop.
+    fireEvent.error(image()!);
+    expect(image()?.getAttribute('src')).toBe(FALLBACK);
+
+    fireEvent.error(image()!);
+    expect(image()?.getAttribute('src')).toBe(FALLBACK);
+  });
+
+  it('shows the fallback inside the viewer too', () => {
+    const { container } = renderBlock(
+      { enableViewer: true, fallbackImage: FALLBACK, fallbackAlt: 'No photo' },
+      { pk: 9 }
+    );
+    openViewer(container);
+
+    const image = container.querySelector('[data-part="viewer-image"]');
+    expect(image?.getAttribute('src')).toBe(FALLBACK);
+    expect(image?.getAttribute('alt')).toBe('No photo');
+    expect(image?.getAttribute('data-state')).toContain('empty');
+  });
+});
+
+describe('ProductGalleryBlock — authored copy', () => {
+  it('draws the hint only once an enlargement is offered, and only if authored', () => {
+    expect(
+      renderBlock({ zoomHint: 'Tap to enlarge' }, PRODUCT).container.querySelector(
+        '[data-part="zoom-hint"]'
+      )
+    ).toBeNull();
+
+    expect(
+      renderBlock(
+        { enableViewer: true, zoomHint: 'Tap to enlarge' },
+        PRODUCT
+      ).container.querySelector('[data-part="zoom-hint"]')?.textContent
+    ).toBe('Tap to enlarge');
+  });
+
+  /**
+   * Magnify is a hover affordance. With the viewer off there is no enlargement
+   * a finger can reach, so a hint left standing over the photo on a phone
+   * promises something a tap cannot deliver.
+   */
+  it('hides a magnify-only hint from a pointer that cannot hover', () => {
+    const { container } = renderBlock(
+      { enableZoom: true, zoomHint: 'Hover to zoom' },
+      PRODUCT
+    );
+
+    expect(
+      container.querySelector('[data-part="zoom-hint"]')?.textContent
+    ).toBe('Hover to zoom');
+
+    const rules = Array.from(container.querySelectorAll('style'))
+      .map((node) => node.textContent ?? '')
+      .join('');
+    const gate = /@media \(hover:none\)\{([^{]+)\{display:none;\}\}/.exec(rules);
+    expect(gate).not.toBeNull();
+
+    // The selector is handed back to the DOM rather than matched as a string:
+    // a rule scoped to the wrong instance reads identically and hides nothing.
+    expect(Array.from(container.querySelectorAll(gate![1].trim()))).toEqual([
+      container.querySelector('[data-part="zoom-hint"]')
+    ]);
+  });
+
+  it('scopes that gate over every cell of the grid layout', () => {
+    const { container } = renderBlock(
+      { layout: 'grid', enableZoom: true, zoomHint: 'Hover to zoom' },
+      PRODUCT
+    );
+
+    const rules = Array.from(container.querySelectorAll('style'))
+      .map((node) => node.textContent ?? '')
+      .join('');
+    const gate = /@media \(hover:none\)\{([^{]+)\{display:none;\}\}/.exec(rules);
+
+    expect(container.querySelectorAll('[data-part="zoom-hint"]')).toHaveLength(3);
+    expect(container.querySelectorAll(gate![1].trim())).toHaveLength(3);
+  });
+
+  it('keeps the hint for every shopper once the viewer can answer a tap', () => {
+    const { container } = renderBlock(
+      { enableZoom: true, enableViewer: true, zoomHint: 'Tap to enlarge' },
+      PRODUCT
+    );
+
+    expect(
+      container.querySelector('[data-part="zoom-hint"]')?.textContent
+    ).toBe('Tap to enlarge');
+    expect(
+      Array.from(container.querySelectorAll('style'))
+        .map((node) => node.textContent ?? '')
+        .join('')
+    ).not.toContain('hover:none');
+  });
+
+  it('lets a brand word every viewer control', () => {
+    const { container } = renderBlock(
+      {
+        enableViewer: true,
+        viewerOpenLabel: '{name} fotoğrafını büyüt',
+        viewerTitle: 'Ürün fotoğrafları',
+        viewerCloseLabel: 'Kapat',
+        viewerShowCounter: true,
+        viewerCounterLabel: '{index}. / {total}',
+        viewerPrevLabel: 'Önceki',
+        viewerNextLabel: 'Sonraki'
+      },
+      PRODUCT
+    );
+
+    expect(
+      container
+        .querySelector('[data-part="viewer-trigger"]')
+        ?.getAttribute('aria-label')
+    ).toBe('Wool Coat fotoğrafını büyüt');
+
+    openViewer(container);
+
+    expect(
+      container.querySelector('[role="dialog"]')?.getAttribute('aria-label')
+    ).toBe('Ürün fotoğrafları');
+    expect(
+      container
+        .querySelector('[data-part="viewer-close"]')
+        ?.getAttribute('aria-label')
+    ).toBe('Kapat');
+    expect(
+      container.querySelector('[data-part="viewer-counter"]')?.textContent
+    ).toBe('1. / 3');
+    expect(
+      container
+        .querySelector('[data-product-gallery-viewer-arrow="prev"]')
+        ?.getAttribute('aria-label')
+    ).toBe('Önceki');
+  });
+});
+
+describe('ProductGalleryBlock — the states the image frame reports', () => {
+  it('names magnifying with a token the browser cannot raise on its own', () => {
+    const { container } = renderBlock({ enableZoom: true }, PRODUCT);
+    const frame = container.querySelector('[data-product-gallery-main]');
+    sizeFrame(frame);
+
+    fireEvent.pointerMove(frame!, {
+      pointerType: 'mouse',
+      clientX: 50,
+      clientY: 100
+    });
+
+    const states = (frame?.getAttribute('data-state') ?? '').split(' ');
+    expect(states).toContain('open');
+    // `active` also carries the browser's own `:active`, so a brand styling
+    // "while magnifying" would get it on every mousedown — magnify off too.
+    expect(states).not.toContain('active');
+  });
+
+  it('names the grid cell the shopper is on', () => {
+    const { container } = renderBlock({ layout: 'grid' }, PRODUCT);
+    const cells = container.querySelectorAll('[data-product-gallery-cell]');
+
+    expect(cells[0].getAttribute('data-state')).toContain('selected');
+    expect(cells[1].getAttribute('data-state') ?? '').not.toContain('selected');
+  });
+});
+
+/**
+ * The other half of the part contract lives in the editor: a state the
+ * renderer reports and the editor never declares is a style a designer has no
+ * way to write. The editor is a sibling checkout, so this is skipped where it
+ * is not cloned rather than failed.
+ */
+const DESCRIPTOR_PATH = path.resolve(
+  __dirname,
+  '../../../../../../pz-dynamic-widget/src/config/blocks/product-blocks.ts'
+);
+
+const declaredStatesFor = (part: string): string[] => {
+  const source = fs.readFileSync(DESCRIPTOR_PATH, 'utf8');
+  const group = new RegExp(
+    `partGroup\\('${part}',[\\s\\S]*?states:\\s*\\{([\\s\\S]*?)\\}`
+  ).exec(source);
+
+  if (!group) throw new Error(`no states declared for part "${part}"`);
+
+  return Array.from(group[1].matchAll(/([a-z][a-z-]*)\s*:/g), (m) => m[1]);
+};
+
+(fs.existsSync(DESCRIPTOR_PATH) ? describe : describe.skip)(
+  'ProductGalleryBlock — editor reach over those states',
+  () => {
+    it('declares every state the image frame reports, and no phantom one', () => {
+      expect(declaredStatesFor('main').sort()).toEqual([
+        'empty',
+        'open',
+        'selected'
+      ]);
+    });
+  }
+);