@12-apps/ui 1.0.0 → 1.3.1

package/src/components/data-display/Lightbox/Lightbox.hooks.ts

@@ -0,0 +1,259 @@
+import type React from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import {
+  DEFAULT_AUTOPLAY_INTERVAL_MS,
+  MAX_ZOOM,
+  MIN_SWIPE_DISTANCE,
+  MIN_ZOOM,
+  WHEEL_ZOOM_FACTOR,
+  ZOOM_STEP,
+} from './Lightbox.constants';
+import type { LightboxItem, LightboxProps } from './Lightbox.types';
+
+const clampZoom = (zoom: number): number => Math.max(MIN_ZOOM, Math.min(MAX_ZOOM, zoom));
+
+// Items with no explicit type are images.
+const isImageItem = (item?: LightboxItem): item is LightboxItem =>
+  Boolean(item && (item.type === 'image' || !item.type));
+
+// Images are fetched once and remembered, so stepping back to one is instant.
+export const usePreloader = () => {
+  const [preloadedImages, setPreloadedImages] = useState<Set<string>>(new Set());
+
+  return useCallback(
+    (src: string) => {
+      if (preloadedImages.has(src)) return;
+
+      const img = new window.Image();
+      img.onload = () => setPreloadedImages((prev) => new Set([...prev, src]));
+      img.src = src;
+    },
+    [preloadedImages],
+  );
+};
+
+export interface ZoomState {
+  zoomLevel: number;
+  panOffset: { x: number; y: number };
+  setZoomLevel: React.Dispatch<React.SetStateAction<number>>;
+  resetZoom: () => void;
+  zoomIn: () => void;
+  zoomOut: () => void;
+}
+
+export const useZoomState = (): ZoomState => {
+  const [zoomLevel, setZoomLevel] = useState(1);
+  const [panOffset, setPanOffset] = useState({ x: 0, y: 0 });
+
+  const resetZoom = useCallback(() => {
+    setZoomLevel(1);
+    setPanOffset({ x: 0, y: 0 });
+  }, []);
+
+  const zoomIn = useCallback(() => setZoomLevel((prev) => Math.min(MAX_ZOOM, prev * ZOOM_STEP)), []);
+  const zoomOut = useCallback(
+    () => setZoomLevel((prev) => Math.max(MIN_ZOOM, prev / ZOOM_STEP)),
+    [],
+  );
+
+  return { zoomLevel, panOffset, setZoomLevel, resetZoom, zoomIn, zoomOut };
+};
+
+export const useWheelZoom = ({
+  enabled,
+  setZoomLevel,
+}: {
+  enabled: boolean;
+  setZoomLevel: React.Dispatch<React.SetStateAction<number>>;
+}) =>
+  useCallback(
+    (event: React.WheelEvent) => {
+      if (!enabled) return;
+
+      event.preventDefault();
+      // Scrolling up (negative deltaY) zooms in.
+      setZoomLevel((prev) => clampZoom(prev + event.deltaY * -WHEEL_ZOOM_FACTOR));
+    },
+    [enabled, setZoomLevel],
+  );
+
+export const useNavigation = ({
+  items,
+  loop,
+  startIndex,
+  resetZoom,
+  preloadImage,
+}: {
+  items: LightboxItem[];
+  loop: boolean;
+  startIndex: number;
+  resetZoom: () => void;
+  preloadImage: (src: string) => void;
+}) => {
+  const [currentIndex, setCurrentIndex] = useState(
+    Math.max(0, Math.min(startIndex, items.length - 1)),
+  );
+
+  const goToIndex = useCallback(
+    (index: number) => {
+      if (items.length === 0) return;
+
+      // Looping wraps both ways; otherwise the index sticks at the ends.
+      const newIndex = loop
+        ? ((index % items.length) + items.length) % items.length
+        : Math.max(0, Math.min(index, items.length - 1));
+
+      setCurrentIndex(newIndex);
+      resetZoom();
+
+      // Fetch the neighbours so a step in either direction shows immediately.
+      [items[newIndex - 1], items[newIndex + 1]]
+        .filter(isImageItem)
+        .forEach((item) => preloadImage(item.src));
+    },
+    [items, loop, resetZoom, preloadImage],
+  );
+
+  const next = useCallback(() => {
+    if (currentIndex < items.length - 1 || loop) goToIndex(currentIndex + 1);
+  }, [currentIndex, items.length, loop, goToIndex]);
+
+  const prev = useCallback(() => {
+    if (currentIndex > 0 || loop) goToIndex(currentIndex - 1);
+  }, [currentIndex, loop, goToIndex]);
+
+  return { currentIndex, goToIndex, next, prev };
+};
+
+export const useAutoplay = ({
+  isOpen,
+  autoplay,
+  itemCount,
+  currentIndex,
+  next,
+}: {
+  isOpen: boolean;
+  autoplay: LightboxProps['autoplay'];
+  itemCount: number;
+  currentIndex: number;
+  next: () => void;
+}) => {
+  const [isAutoPlaying, setIsAutoPlaying] = useState(false);
+  const timerRef = useRef<number | undefined>(undefined);
+
+  useEffect(() => {
+    if (!isAutoPlaying || !autoplay || itemCount <= 1) return;
+
+    const interval =
+      typeof autoplay === 'object'
+        ? autoplay.interval || DEFAULT_AUTOPLAY_INTERVAL_MS
+        : DEFAULT_AUTOPLAY_INTERVAL_MS;
+
+    timerRef.current = window.setTimeout(next, interval);
+
+    return () => window.clearTimeout(timerRef.current);
+  }, [isAutoPlaying, autoplay, currentIndex, next, itemCount]);
+
+  // Opening a gallery with more than one item starts the slideshow.
+  useEffect(() => {
+    setIsAutoPlaying(Boolean(isOpen && autoplay && itemCount > 1));
+  }, [isOpen, autoplay, itemCount]);
+
+  const stopAutoplay = useCallback(() => {
+    setIsAutoPlaying(false);
+    window.clearTimeout(timerRef.current);
+  }, []);
+
+  return { isAutoPlaying, setIsAutoPlaying, stopAutoplay };
+};
+
+export const useLightboxKeyboard = ({
+  isOpen,
+  showControls,
+  autoplay,
+  close,
+  prev,
+  next,
+  setIsAutoPlaying,
+}: {
+  isOpen: boolean;
+  showControls: boolean;
+  autoplay: LightboxProps['autoplay'];
+  close: () => void;
+  prev: () => void;
+  next: () => void;
+  setIsAutoPlaying: React.Dispatch<React.SetStateAction<boolean>>;
+}) => {
+  useEffect(() => {
+    if (!isOpen) return;
+
+    const arrows: Record<string, () => void> = { ArrowLeft: prev, ArrowRight: next };
+
+    const handleKeyDown = (event: { key: string; preventDefault: () => void }) => {
+      if (event.key === 'Escape') {
+        close();
+        return;
+      }
+
+      const arrow = arrows[event.key];
+      if (arrow && showControls) {
+        event.preventDefault();
+        arrow();
+        return;
+      }
+
+      if (event.key === ' ') {
+        event.preventDefault();
+        if (autoplay) setIsAutoPlaying((playing) => !playing);
+      }
+    };
+
+    document.addEventListener('keydown', handleKeyDown);
+    return () => document.removeEventListener('keydown', handleKeyDown);
+  }, [isOpen, showControls, close, prev, next, autoplay, setIsAutoPlaying]);
+};
+
+// Horizontal swipes step through the gallery; a downward swipe dismisses it.
+export const useSwipe = ({
+  prev,
+  next,
+  close,
+}: {
+  prev: () => void;
+  next: () => void;
+  close: () => void;
+}) => {
+  const touchStartRef = useRef<{ x: number; y: number } | null>(null);
+
+  const handleTouchStart = useCallback((event: React.TouchEvent) => {
+    const touch = event.touches.length === 1 ? event.touches[0] : undefined;
+    if (touch) touchStartRef.current = { x: touch.clientX, y: touch.clientY };
+  }, []);
+
+  const handleTouchEnd = useCallback(
+    (event: React.TouchEvent) => {
+      const start = touchStartRef.current;
+      const touch = event.changedTouches[0];
+      touchStartRef.current = null;
+      if (!start || !touch) return;
+
+      const deltaX = touch.clientX - start.x;
+      const deltaY = touch.clientY - start.y;
+
+      // Whichever axis moved further decides what the gesture meant.
+      if (Math.abs(deltaX) > Math.abs(deltaY)) {
+        if (Math.abs(deltaX) > MIN_SWIPE_DISTANCE) {
+          if (deltaX > 0) prev();
+          else next();
+        }
+        return;
+      }
+
+      if (deltaY > MIN_SWIPE_DISTANCE) close();
+    },
+    [prev, next, close],
+  );
+
+  return { handleTouchStart, handleTouchEnd };
+};

package/src/components/data-display/Lightbox/Lightbox.test.stories.tsx

@@ -488,11 +488,14 @@ export const EdgeCases: Story = {
         expect(lightbox).toBeInTheDocument();
       });
 
-      // Should not show navigation controls for empty gallery
-      const nextButton = document.querySelector('[aria-label="Next item"]');
-      const prevButton = document.querySelector('[aria-label="Previous item"]');
-      expect(nextButton).not.toBeInTheDocument();
-      expect(prevButton).not.toBeInTheDocument();
+      // The close button always renders, so waiting for it first means the
+      // absence checks below describe what an empty gallery omits, rather than
+      // passing because nothing had rendered yet.
+      await waitFor(() => {
+        expect(document.querySelector('[aria-label="Close lightbox"]')).toBeInTheDocument();
+        expect(document.querySelector('[aria-label="Next item"]')).not.toBeInTheDocument();
+        expect(document.querySelector('[aria-label="Previous item"]')).not.toBeInTheDocument();
+      });
     });
   },
 };
@@ -514,59 +517,49 @@ export const SingleImageGallery: Story = {
     });
 
     await step('Should not show navigation controls for single image', async () => {
-      const nextButton = document.querySelector('[aria-label="Next item"]');
-      const prevButton = document.querySelector('[aria-label="Previous item"]');
-
-      expect(nextButton).not.toBeInTheDocument();
-      expect(prevButton).not.toBeInTheDocument();
+      // The close button proves the overlay rendered, so the absences here are
+      // about what a one-item gallery omits rather than about timing.
+      await waitFor(() => {
+        expect(document.querySelector('[aria-label="Close lightbox"]')).toBeInTheDocument();
+        expect(document.querySelector('[aria-label="Next item"]')).not.toBeInTheDocument();
+        expect(document.querySelector('[aria-label="Previous item"]')).not.toBeInTheDocument();
+      });
     });
 
     await step('Should show correct counter for single image', async () => {
-      const counter = document.querySelector('[aria-live="polite"]');
-      expect(counter).not.toBeInTheDocument(); // No counter for single image
+      await waitFor(() => {
+        // No counter for single image
+        expect(document.querySelector('[aria-live="polite"]')).not.toBeInTheDocument();
+      });
     });
   },
 };
 
-// 11. Performance Tests
+// 11. Open and navigate.
+// The two steps below used to bracket their waitFor calls with Date.now() and
+// assert 2s/500ms budgets. Those measured the machine rather than the component,
+// and could not fail independently of the waitFor timeout that already bounds
+// each wait.
 export const Performance: Story = {
   render: () => <LightboxTestWrapper />,
   play: async ({ canvasElement, step }) => {
     const canvas = within(canvasElement);
 
-    await step('Should open lightbox quickly', async () => {
-      const startTime = Date.now();
-
+    await step('Should open lightbox', async () => {
       const openButton = canvas.getByTestId('open-lightbox');
       await userEvent.click(openButton);
 
       await waitFor(() => {
-        const lightbox = document.querySelector('[role="dialog"]');
-        expect(lightbox).toBeInTheDocument();
-
-        const endTime = Date.now();
-        const openTime = endTime - startTime;
-
-        // Should open within reasonable time (2 seconds)
-        expect(openTime).toBeLessThan(2000);
+        expect(document.querySelector('[role="dialog"]')).toBeInTheDocument();
       });
     });
 
-    await step('Should navigate between images smoothly', async () => {
-      const startTime = Date.now();
-
+    await step('Should navigate between images', async () => {
       const nextButton = document.querySelector('[aria-label="Next item"]');
       await userEvent.click(nextButton!);
 
       await waitFor(() => {
-        const image = document.querySelector('img[alt="Test Image 2"]');
-        expect(image).toBeInTheDocument();
-
-        const endTime = Date.now();
-        const navigateTime = endTime - startTime;
-
-        // Navigation should be fast (500ms)
-        expect(navigateTime).toBeLessThan(500);
+        expect(document.querySelector('img[alt="Test Image 2"]')).toBeInTheDocument();
       });
     });
   },