@jekrch/react-viewport-lightbox 0.2.0 → 0.3.1

package/dist/index.d.cts

@@ -50,6 +50,12 @@ interface ViewerContext<TData = unknown> {
     index: number;
     item: ViewerItem<TData>;
     total: number;
+    /**
+     * True once the exit animation has started (after a close was requested,
+     * before `onClose` fires and the viewer unmounts). Lets overlay content fade
+     * out in step with the closing chrome instead of vanishing on unmount.
+     */
+    closing: boolean;
     hasPrev: boolean;
     hasNext: boolean;
     goPrev: () => void;
@@ -90,6 +96,14 @@ interface ImageViewerProps<TData = unknown> {
     onNavigate?: (direction: "prev" | "next") => void;
     /** Called AFTER the exit animation completes. */
     onClose: () => void;
+    /**
+     * Called when the user presses Escape, before the viewer closes. Return
+     * `true` to mark the key handled and veto the default close — e.g. to dismiss
+     * a consumer overlay (drawer/graph) first, closing the viewer only on a
+     * second press. Return `false`/`undefined` to fall through to the default
+     * close.
+     */
+    onEscape?: () => boolean;
     /**
      * Enables a shared-element "zoom from thumbnail" open/close transition. Given
      * the active index, return the on-screen rect of the source element (e.g. the
@@ -109,6 +123,20 @@ interface ImageViewerProps<TData = unknown> {
     zoomToCursor?: boolean;
     /** Show the `index / total` counter. Default `true`. */
     showCounter?: boolean;
+    /**
+     * Show the built-in zoom in/out/reset buttons in the top bar. Independent of
+     * `zoom` (which governs the gesture behavior): set this `false` to keep
+     * zoom/pan gestures while a consumer overlay (e.g. an open graph/drawer that
+     * covers the image) temporarily owns the chrome. Default `true`.
+     */
+    showZoomControls?: boolean;
+    /**
+     * Suppress built-in arrow-key navigation (and the swipe commit) without
+     * tearing the viewer down. Useful while an overlay that has its own
+     * left/right handling is open. Does not hide the on-screen nav buttons.
+     * Default `false`.
+     */
+    disableNavigation?: boolean;
     /** Wrap around at the ends. Default `false`. */
     loop?: boolean;
     /**
@@ -129,6 +157,35 @@ interface ImageViewerProps<TData = unknown> {
     renderNavStart?: (ctx: ViewerContext<TData>) => ReactNode;
     /** Pinned to the RIGHT edge of the nav row; mirror of `renderNavStart`. */
     renderNavEnd?: (ctx: ViewerContext<TData>) => ReactNode;
+    /**
+     * Where the `renderNavStart` / `renderNavEnd` slots sit relative to the
+     * prev/counter/next group:
+     * - `"edge"` (default): pinned to the left/right edges of the nav row (max
+     *   42rem), keeping the nav group optically centered regardless of slot width.
+     * - `"inline"`: placed directly flanking the nav group as one centered
+     *   cluster, so a details/info toggle hugs the arrows.
+     */
+    navSlotPlacement?: "edge" | "inline";
+    /**
+     * Size of the prev/next nav arrows (the bottom nav controls). A number is
+     * treated as pixels; a string is used verbatim (e.g. `"1.5rem"`). Sets the
+     * `--rvl-nav-height` custom property, so it can equally be themed in CSS.
+     * Defaults to `2.375rem` (38px) to match the comic-snaps viewer.
+     */
+    navHeight?: number | string;
+    /**
+     * Gap between the bottom nav controls and the viewport's bottom edge. A number
+     * is treated as pixels; a string is used verbatim (e.g. `"2rem"`). Sets the
+     * `--rvl-nav-inset` custom property and is floored by the device safe-area
+     * inset. Defaults to `1.3rem`.
+     */
+    navInset?: number | string;
+    /**
+     * Counter font size. By default the counter scales with `navHeight` (≈0.29×);
+     * set this to override that ratio with a fixed size. A number is treated as
+     * pixels; a string is used verbatim. Sets `--rvl-counter-font-size`.
+     */
+    counterFontSize?: number | string;
     /** Content below the nav row. */
     renderFooter?: (ctx: ViewerContext<TData>) => ReactNode;
     /** Drawers/graphs layered over the image. */
@@ -144,7 +201,7 @@ interface ImageViewerProps<TData = unknown> {
  * `onIndexChange`; mount it when open and it runs its own enter/exit animation,
  * calling `onClose` after the exit completes.
  */
-declare function ImageViewer<TData = unknown>({ items, index, onIndexChange, onNavigate, onClose, getOriginRect, zoom, zoomToCursor, showCounter, loop, closeOnBackdropClick, renderHeader, renderHeaderActions, renderNavStart, renderNavEnd, renderFooter, renderOverlay, classNames, icons, ariaLabel, }: ImageViewerProps<TData>): react.JSX.Element | null;
+declare function ImageViewer<TData = unknown>({ items, index, onIndexChange, onNavigate, onClose, onEscape, getOriginRect, zoom, zoomToCursor, showCounter, showZoomControls, disableNavigation, loop, closeOnBackdropClick, renderHeader, renderHeaderActions, renderNavStart, renderNavEnd, navSlotPlacement, navHeight, navInset, counterFontSize, renderFooter, renderOverlay, classNames, icons, ariaLabel, }: ImageViewerProps<TData>): react.JSX.Element | null;
 
 interface NavButtonProps {
     direction: "prev" | "next";

package/dist/index.d.ts

@@ -50,6 +50,12 @@ interface ViewerContext<TData = unknown> {
     index: number;
     item: ViewerItem<TData>;
     total: number;
+    /**
+     * True once the exit animation has started (after a close was requested,
+     * before `onClose` fires and the viewer unmounts). Lets overlay content fade
+     * out in step with the closing chrome instead of vanishing on unmount.
+     */
+    closing: boolean;
     hasPrev: boolean;
     hasNext: boolean;
     goPrev: () => void;
@@ -90,6 +96,14 @@ interface ImageViewerProps<TData = unknown> {
     onNavigate?: (direction: "prev" | "next") => void;
     /** Called AFTER the exit animation completes. */
     onClose: () => void;
+    /**
+     * Called when the user presses Escape, before the viewer closes. Return
+     * `true` to mark the key handled and veto the default close — e.g. to dismiss
+     * a consumer overlay (drawer/graph) first, closing the viewer only on a
+     * second press. Return `false`/`undefined` to fall through to the default
+     * close.
+     */
+    onEscape?: () => boolean;
     /**
      * Enables a shared-element "zoom from thumbnail" open/close transition. Given
      * the active index, return the on-screen rect of the source element (e.g. the
@@ -109,6 +123,20 @@ interface ImageViewerProps<TData = unknown> {
     zoomToCursor?: boolean;
     /** Show the `index / total` counter. Default `true`. */
     showCounter?: boolean;
+    /**
+     * Show the built-in zoom in/out/reset buttons in the top bar. Independent of
+     * `zoom` (which governs the gesture behavior): set this `false` to keep
+     * zoom/pan gestures while a consumer overlay (e.g. an open graph/drawer that
+     * covers the image) temporarily owns the chrome. Default `true`.
+     */
+    showZoomControls?: boolean;
+    /**
+     * Suppress built-in arrow-key navigation (and the swipe commit) without
+     * tearing the viewer down. Useful while an overlay that has its own
+     * left/right handling is open. Does not hide the on-screen nav buttons.
+     * Default `false`.
+     */
+    disableNavigation?: boolean;
     /** Wrap around at the ends. Default `false`. */
     loop?: boolean;
     /**
@@ -129,6 +157,35 @@ interface ImageViewerProps<TData = unknown> {
     renderNavStart?: (ctx: ViewerContext<TData>) => ReactNode;
     /** Pinned to the RIGHT edge of the nav row; mirror of `renderNavStart`. */
     renderNavEnd?: (ctx: ViewerContext<TData>) => ReactNode;
+    /**
+     * Where the `renderNavStart` / `renderNavEnd` slots sit relative to the
+     * prev/counter/next group:
+     * - `"edge"` (default): pinned to the left/right edges of the nav row (max
+     *   42rem), keeping the nav group optically centered regardless of slot width.
+     * - `"inline"`: placed directly flanking the nav group as one centered
+     *   cluster, so a details/info toggle hugs the arrows.
+     */
+    navSlotPlacement?: "edge" | "inline";
+    /**
+     * Size of the prev/next nav arrows (the bottom nav controls). A number is
+     * treated as pixels; a string is used verbatim (e.g. `"1.5rem"`). Sets the
+     * `--rvl-nav-height` custom property, so it can equally be themed in CSS.
+     * Defaults to `2.375rem` (38px) to match the comic-snaps viewer.
+     */
+    navHeight?: number | string;
+    /**
+     * Gap between the bottom nav controls and the viewport's bottom edge. A number
+     * is treated as pixels; a string is used verbatim (e.g. `"2rem"`). Sets the
+     * `--rvl-nav-inset` custom property and is floored by the device safe-area
+     * inset. Defaults to `1.3rem`.
+     */
+    navInset?: number | string;
+    /**
+     * Counter font size. By default the counter scales with `navHeight` (≈0.29×);
+     * set this to override that ratio with a fixed size. A number is treated as
+     * pixels; a string is used verbatim. Sets `--rvl-counter-font-size`.
+     */
+    counterFontSize?: number | string;
     /** Content below the nav row. */
     renderFooter?: (ctx: ViewerContext<TData>) => ReactNode;
     /** Drawers/graphs layered over the image. */
@@ -144,7 +201,7 @@ interface ImageViewerProps<TData = unknown> {
  * `onIndexChange`; mount it when open and it runs its own enter/exit animation,
  * calling `onClose` after the exit completes.
  */
-declare function ImageViewer<TData = unknown>({ items, index, onIndexChange, onNavigate, onClose, getOriginRect, zoom, zoomToCursor, showCounter, loop, closeOnBackdropClick, renderHeader, renderHeaderActions, renderNavStart, renderNavEnd, renderFooter, renderOverlay, classNames, icons, ariaLabel, }: ImageViewerProps<TData>): react.JSX.Element | null;
+declare function ImageViewer<TData = unknown>({ items, index, onIndexChange, onNavigate, onClose, onEscape, getOriginRect, zoom, zoomToCursor, showCounter, showZoomControls, disableNavigation, loop, closeOnBackdropClick, renderHeader, renderHeaderActions, renderNavStart, renderNavEnd, navSlotPlacement, navHeight, navInset, counterFontSize, renderFooter, renderOverlay, classNames, icons, ariaLabel, }: ImageViewerProps<TData>): react.JSX.Element | null;
 
 interface NavButtonProps {
     direction: "prev" | "next";

package/dist/index.js

@@ -590,16 +590,29 @@ function useBarMeasure(topBarRef, bottomBarRef, measureKey) {
 var lockCount = 0;
 var previousOverflow = "";
 var previousPaddingRight = "";
+var previousPosition = "";
+var previousTop = "";
+var previousWidth = "";
+var lockedScrollY = 0;
 function useBodyScrollLock(isLocked) {
   useEffect(() => {
     if (!isLocked) return;
     if (typeof document === "undefined") return;
     if (lockCount === 0) {
       const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;
+      const rootGutter = window.getComputedStyle(document.documentElement).scrollbarGutter;
+      const reservesGutter = typeof rootGutter === "string" && rootGutter.includes("stable");
+      lockedScrollY = window.scrollY;
       previousOverflow = document.body.style.overflow;
       previousPaddingRight = document.body.style.paddingRight;
+      previousPosition = document.body.style.position;
+      previousTop = document.body.style.top;
+      previousWidth = document.body.style.width;
       document.body.style.overflow = "hidden";
-      if (scrollbarWidth > 0) {
+      document.body.style.position = "fixed";
+      document.body.style.top = `-${lockedScrollY}px`;
+      document.body.style.width = "100%";
+      if (scrollbarWidth > 0 && !reservesGutter) {
         const currentPaddingRight = parseFloat(window.getComputedStyle(document.body).paddingRight) || 0;
         document.body.style.paddingRight = `${currentPaddingRight + scrollbarWidth}px`;
       }
@@ -610,6 +623,10 @@ function useBodyScrollLock(isLocked) {
       if (lockCount === 0) {
         document.body.style.overflow = previousOverflow;
         document.body.style.paddingRight = previousPaddingRight;
+        document.body.style.position = previousPosition;
+        document.body.style.top = previousTop;
+        document.body.style.width = previousWidth;
+        window.scrollTo(0, lockedScrollY);
       }
     };
   }, [isLocked]);
@@ -722,6 +739,7 @@ function NavButton({ direction, enabled, onClick, icon, className }) {
 }
 var ANIM_MS = 250;
 var IMG_PADDING = 44;
+var GHOST_CLICK_MS = 700;
 var ZOOM_EASE = "cubic-bezier(0.22, 1, 0.36, 1)";
 function prefersReducedMotion() {
   if (typeof window === "undefined" || !window.matchMedia) return false;
@@ -747,16 +765,23 @@ function ImageViewer({
   onIndexChange,
   onNavigate,
   onClose,
+  onEscape,
   getOriginRect,
   zoom = true,
   zoomToCursor = true,
   showCounter = true,
+  showZoomControls = true,
+  disableNavigation = false,
   loop = false,
   closeOnBackdropClick = false,
   renderHeader,
   renderHeaderActions,
   renderNavStart,
   renderNavEnd,
+  navSlotPlacement = "edge",
+  navHeight,
+  navInset,
+  counterFontSize,
   renderFooter,
   renderOverlay,
   classNames,
@@ -768,6 +793,11 @@ function ImageViewer({
   const [collapsing, setCollapsing] = useState(false);
   const [isTouchDevice, setIsTouchDevice] = useState(false);
   const [contentShift, setContentShiftState] = useState({ transform: null, animate: true });
+  const openedAtRef = useRef(Date.now());
+  const isGhostMouseEvent = useCallback(
+    () => Date.now() - openedAtRef.current < GHOST_CLICK_MS,
+    []
+  );
   const containerRef = useRef(null);
   const imgWrapperRef = useRef(null);
   const topBarRef = useRef(null);
@@ -801,7 +831,15 @@ function ImageViewer({
   const { slideTrackRef, slideActive, slideAnimating, swipeOffset, commitSlide } = slide;
   const gestures = useGestureHandler(zoomPan, slide, hasPrev, hasNext, zoom, zoomToCursor);
   useEffect(() => {
-    setIsTouchDevice("ontouchstart" in window || navigator.maxTouchPoints > 0);
+    if (typeof window === "undefined" || !window.matchMedia) {
+      setIsTouchDevice("ontouchstart" in window || navigator.maxTouchPoints > 0);
+      return;
+    }
+    const mq = window.matchMedia("(hover: none) and (pointer: coarse)");
+    const update = () => setIsTouchDevice(mq.matches);
+    update();
+    mq.addEventListener("change", update);
+    return () => mq.removeEventListener("change", update);
   }, []);
   useEffect(() => {
     const onResize = () => setViewportWidth(window.innerWidth);
@@ -907,6 +945,33 @@ function ImageViewer({
     }
     setTimeout(onClose, reduce ? 0 : ANIM_MS);
   }, [onClose, getOriginRect, index, isZoomed, imgRef, imgWrapperRef]);
+  const handleBackdropTouchEnd = useCallback(
+    (e) => {
+      if (e.target !== e.currentTarget) return;
+      e.preventDefault();
+      handleClose();
+    },
+    [handleClose]
+  );
+  const handleDoubleClickGuarded = useCallback(
+    (e) => {
+      if (isGhostMouseEvent()) return;
+      handleDoubleClick(e);
+    },
+    [handleDoubleClick, isGhostMouseEvent]
+  );
+  const handleBackdropClick = useCallback(() => {
+    if (isGhostMouseEvent()) return;
+    handleClose();
+  }, [handleClose, isGhostMouseEvent]);
+  const handleStageClick = useCallback(
+    (e) => {
+      if (e.target !== e.currentTarget) return;
+      if (isGhostMouseEvent()) return;
+      handleClose();
+    },
+    [handleClose, isGhostMouseEvent]
+  );
   const navigate = useCallback(
     (dir) => {
       if (dir === "prev") {
@@ -920,16 +985,17 @@ function ImageViewer({
   useEffect(() => {
     const handler = (e) => {
       if (e.key === "Escape") {
+        if (onEscape?.()) return;
         handleClose();
         return;
       }
-      if (displayScale > 1) return;
+      if (disableNavigation || displayScale > 1) return;
       if (e.key === "ArrowLeft" && hasPrev) navigate("prev");
       if (e.key === "ArrowRight" && hasNext) navigate("next");
     };
     window.addEventListener("keydown", handler);
     return () => window.removeEventListener("keydown", handler);
-  }, [handleClose, hasPrev, hasNext, displayScale, navigate]);
+  }, [handleClose, hasPrev, hasNext, displayScale, navigate, onEscape, disableNavigation]);
   const setContentShift = useCallback((transform, animate = true) => {
     setContentShiftState({ transform, animate });
   }, []);
@@ -938,6 +1004,7 @@ function ImageViewer({
     index,
     item,
     total: items.length,
+    closing,
     hasPrev,
     hasNext,
     goPrev: () => navigate("prev"),
@@ -970,6 +1037,12 @@ function ImageViewer({
   const reservedH = bottomBarH + IMG_PADDING * 2;
   const imgMaxHeight = `calc(100vh - ${reservedH}px)`;
   const imgStyle = { maxHeight: imgMaxHeight };
+  const dim = (v) => typeof v === "number" ? `${v}px` : v;
+  const rootStyle = {
+    ...navHeight != null && { "--rvl-nav-height": dim(navHeight) },
+    ...navInset != null && { "--rvl-nav-inset": dim(navInset) },
+    ...counterFontSize != null && { "--rvl-counter-font-size": dim(counterFontSize) }
+  };
   if (gateEntry && !fullLoaded) imgStyle.opacity = 0;
   const totalDigits = String(items.length).length;
   const counterMinWidth = `${totalDigits * 2 * 0.6 + 1.5}em`;
@@ -979,7 +1052,7 @@ function ImageViewer({
   const nextItem = nextIndex >= 0 ? items[nextIndex] : null;
   const showAdjacent = slideActive || slideAnimating || swipeOffset !== 0;
   const adjacentOpacity = Math.min(1, Math.abs(swipeOffset) / (viewportWidth * 0.8 || 1));
-  const showZoomControls = zoom && !isTouchDevice;
+  const showZoomCtrls = zoom && !isTouchDevice && showZoomControls && !contentShift.transform;
   const headerActions = renderHeaderActions?.(ctx);
   const navStart = renderNavStart?.(ctx);
   const navEnd = renderNavEnd?.(ctx);
@@ -994,12 +1067,14 @@ function ImageViewer({
       "aria-modal": "true",
       "aria-label": ariaLabel ?? item.alt ?? "Image viewer",
       tabIndex: -1,
+      style: rootStyle,
       children: [
         /* @__PURE__ */ jsx(
           "div",
           {
             className: cx("rvl-backdrop", cn("backdrop")),
-            onClick: closeOnBackdropClick ? handleClose : void 0,
+            onClick: closeOnBackdropClick ? handleBackdropClick : void 0,
+            onTouchEnd: closeOnBackdropClick ? handleBackdropTouchEnd : void 0,
             "aria-hidden": "true"
           }
         ),
@@ -1007,7 +1082,7 @@ function ImageViewer({
           /* @__PURE__ */ jsx("div", { className: cx("rvl-header", cn("topBar")), children: renderHeader?.(ctx) }),
           /* @__PURE__ */ jsxs("div", { className: "rvl-header-actions", children: [
             headerActions,
-            showZoomControls && isZoomed && /* @__PURE__ */ jsxs(
+            showZoomCtrls && isZoomed && /* @__PURE__ */ jsxs(
               "button",
               {
                 type: "button",
@@ -1024,7 +1099,7 @@ function ImageViewer({
                 ]
               }
             ),
-            showZoomControls && /* @__PURE__ */ jsx(
+            showZoomCtrls && /* @__PURE__ */ jsx(
               "button",
               {
                 type: "button",
@@ -1038,7 +1113,7 @@ function ImageViewer({
                 children: mergedIcons.zoomIn
               }
             ),
-            showZoomControls && /* @__PURE__ */ jsx(
+            showZoomCtrls && /* @__PURE__ */ jsx(
               "button",
               {
                 type: "button",
@@ -1072,9 +1147,8 @@ function ImageViewer({
           "div",
           {
             className: "rvl-stage",
-            onClick: closeOnBackdropClick ? (e) => {
-              if (e.target === e.currentTarget) handleClose();
-            } : void 0,
+            onClick: closeOnBackdropClick ? handleStageClick : void 0,
+            onTouchEnd: closeOnBackdropClick ? handleBackdropTouchEnd : void 0,
             style: {
               transform: contentShift.transform ?? "translateY(0)",
               // animate=false snaps with no transition (overrides the CSS transition)
@@ -1117,7 +1191,7 @@ function ImageViewer({
                       ref: imgWrapperRef,
                       className: "rvl-img-wrapper",
                       onClick: (e) => e.stopPropagation(),
-                      onDoubleClick: handleDoubleClick,
+                      onDoubleClick: handleDoubleClickGuarded,
                       onPointerDown: gestures.handlePointerDown,
                       onPointerMove: gestures.handlePointerMove,
                       onPointerUp: gestures.handlePointerUp,
@@ -1164,7 +1238,7 @@ function ImageViewer({
           }
         ),
         /* @__PURE__ */ jsxs("div", { ref: bottomBarRef, className: cx("rvl-bar", "rvl-bottom-bar", cn("bottomBar")), children: [
-          showNavRow && /* @__PURE__ */ jsx("div", { className: "rvl-nav-row", children: /* @__PURE__ */ jsxs("div", { className: "rvl-nav-inner", children: [
+          showNavRow && /* @__PURE__ */ jsx("div", { className: "rvl-nav-row", children: /* @__PURE__ */ jsxs("div", { className: cx("rvl-nav-inner", navSlotPlacement === "inline" && "rvl-nav-inline"), children: [
             navStart != null && /* @__PURE__ */ jsx("div", { className: cx("rvl-nav-start", cn("navStart")), children: navStart }),
             hasNavGroup && /* @__PURE__ */ jsxs("div", { className: "rvl-nav-group", children: [
               /* @__PURE__ */ jsx(