@jekrch/react-viewport-lightbox 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -19,8 +19,19 @@ interface ViewerItem<TData = unknown> {
     /** Arbitrary per-slide payload, surfaced as `ctx.item.data` in render slots. */
     data?: TData;
 }
+/**
+ * A rectangle in viewport coordinates. Structurally compatible with the
+ * `DOMRect` returned by `element.getBoundingClientRect()`, so you can pass one
+ * straight through.
+ */
+interface ViewerRect {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
 /** Named, themeable regions of the viewer that accept a `className` override. */
-type ViewerSlot = "root" | "backdrop" | "topBar" | "bottomBar" | "image" | "button" | "counter" | "navButton" | "navStart" | "navEnd" | "overlay";
+type ViewerSlot = "root" | "backdrop" | "topBar" | "bottomBar" | "image" | "button" | "counter" | "navButton" | "navStart" | "navEnd" | "overlay" | "spinner";
 /** Overridable control icons. Each is a React node rendered inside its button. */
 interface ViewerIcons {
     close: ReactNode;
@@ -39,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;
@@ -79,12 +96,55 @@ 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
+     * gallery thumbnail) — typically `el.getBoundingClientRect()`. The active
+     * image expands from that rect on open and collapses back into it on close.
+     * Return `null` for an index with no on-screen source (or omit the prop
+     * entirely) to fall back to the default fade. Honors reduced-motion.
+     */
+    getOriginRect?: (index: number) => ViewerRect | null;
     /** Enable zoom/pan (wheel, pinch, double-tap). Default `true`. */
     zoom?: boolean;
+    /**
+     * Anchor wheel- and pinch-zoom on the pointer: scrolling zooms toward the
+     * cursor and a pinch zooms toward the gesture midpoint. Set `false` to zoom
+     * about the viewport center instead. Default `true`.
+     */
+    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;
+    /**
+     * Close the viewer when the empty area around the image (the backdrop) is
+     * clicked. Clicks on the image, the bars, and the control buttons are
+     * unaffected. Default `false`.
+     */
+    closeOnBackdropClick?: boolean;
     /** Top-left title area. */
     renderHeader?: (ctx: ViewerContext<TData>) => ReactNode;
     /** Extra top-right buttons, rendered before the close button. */
@@ -97,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. */
@@ -112,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, zoom, showCounter, loop, 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";
@@ -172,7 +261,12 @@ interface ImageZoomPanState {
  */
 declare function useImageZoomPan(imgWrapperRef: RefObject<HTMLDivElement | null>, currentIndex: number, 
 /** When false, wheel-zoom and double-click-zoom are disabled. Default true. */
-enabled?: boolean): ImageZoomPanState;
+enabled?: boolean, 
+/**
+ * When true (default), wheel-zoom anchors on the cursor. When false, it zooms
+ * about the viewport center.
+ */
+zoomToCursor?: boolean): ImageZoomPanState;
 
 interface SlideNavigationState {
     slideTrackRef: React.RefObject<HTMLDivElement | null>;
@@ -195,7 +289,9 @@ interface SlideNavigationState {
  * preloaded/decoded before navigation commits so the swipe lands on a painted
  * frame.
  */
-declare function useSlideNavigation(items: ViewerItem[], currentIndex: number, onNavigate: (index: number) => void, onSlideStart?: (direction: "prev" | "next") => void): SlideNavigationState;
+declare function useSlideNavigation(items: ViewerItem[], currentIndex: number, onNavigate: (index: number) => void, onSlideStart?: (direction: "prev" | "next") => void, 
+/** When true, navigation wraps around the ends instead of stopping. */
+loop?: boolean): SlideNavigationState;
 
 interface GestureHandlers {
     handlePointerDown: (e: React.PointerEvent) => void;
@@ -215,7 +311,12 @@ interface GestureHandlers {
  */
 declare function useGestureHandler(zoomPan: ImageZoomPanState, slide: SlideNavigationState, hasPrev: boolean, hasNext: boolean, 
 /** When false, pinch-zoom and double-tap-zoom are disabled. Default true. */
-zoomEnabled?: boolean): GestureHandlers;
+zoomEnabled?: boolean, 
+/**
+ * When true (default), pinch-zoom anchors on the gesture midpoint. When
+ * false, it zooms about the viewport center.
+ */
+zoomToCursor?: boolean): GestureHandlers;
 
 /**
  * Measures the height of the top and bottom bars so the image area
@@ -274,4 +375,4 @@ declare function resolveSlideDirection({ offset, elapsedMs, viewportWidth, hasPr
  */
 declare function useFocusTrap(containerRef: RefObject<HTMLElement | null>, active: boolean): void;
 
-export { ChevronLeftIcon, ChevronRightIcon, CloseIcon, type Dims, type ImageTransform, ImageViewer, type ImageViewerProps, type ImageZoomPanState, MAX_SCALE, MIN_SCALE, NavButton, type ResolveSlideArgs, type SlideAction, type SlideNavigationState, type ViewerContext, type ViewerIcons, type ViewerItem, type ViewerSlot, ZoomInIcon, ZoomOutIcon, clampTranslate, defaultIcons, resolveSlideDirection, useBarMeasure, useBodyScrollLock, useFocusTrap, useGestureHandler, useImageZoomPan, useSlideNavigation };
+export { ChevronLeftIcon, ChevronRightIcon, CloseIcon, type Dims, type ImageTransform, ImageViewer, type ImageViewerProps, type ImageZoomPanState, MAX_SCALE, MIN_SCALE, NavButton, type ResolveSlideArgs, type SlideAction, type SlideNavigationState, type ViewerContext, type ViewerIcons, type ViewerItem, type ViewerRect, type ViewerSlot, ZoomInIcon, ZoomOutIcon, clampTranslate, defaultIcons, resolveSlideDirection, useBarMeasure, useBodyScrollLock, useFocusTrap, useGestureHandler, useImageZoomPan, useSlideNavigation };

package/dist/index.d.ts

@@ -19,8 +19,19 @@ interface ViewerItem<TData = unknown> {
     /** Arbitrary per-slide payload, surfaced as `ctx.item.data` in render slots. */
     data?: TData;
 }
+/**
+ * A rectangle in viewport coordinates. Structurally compatible with the
+ * `DOMRect` returned by `element.getBoundingClientRect()`, so you can pass one
+ * straight through.
+ */
+interface ViewerRect {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
 /** Named, themeable regions of the viewer that accept a `className` override. */
-type ViewerSlot = "root" | "backdrop" | "topBar" | "bottomBar" | "image" | "button" | "counter" | "navButton" | "navStart" | "navEnd" | "overlay";
+type ViewerSlot = "root" | "backdrop" | "topBar" | "bottomBar" | "image" | "button" | "counter" | "navButton" | "navStart" | "navEnd" | "overlay" | "spinner";
 /** Overridable control icons. Each is a React node rendered inside its button. */
 interface ViewerIcons {
     close: ReactNode;
@@ -39,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;
@@ -79,12 +96,55 @@ 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
+     * gallery thumbnail) — typically `el.getBoundingClientRect()`. The active
+     * image expands from that rect on open and collapses back into it on close.
+     * Return `null` for an index with no on-screen source (or omit the prop
+     * entirely) to fall back to the default fade. Honors reduced-motion.
+     */
+    getOriginRect?: (index: number) => ViewerRect | null;
     /** Enable zoom/pan (wheel, pinch, double-tap). Default `true`. */
     zoom?: boolean;
+    /**
+     * Anchor wheel- and pinch-zoom on the pointer: scrolling zooms toward the
+     * cursor and a pinch zooms toward the gesture midpoint. Set `false` to zoom
+     * about the viewport center instead. Default `true`.
+     */
+    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;
+    /**
+     * Close the viewer when the empty area around the image (the backdrop) is
+     * clicked. Clicks on the image, the bars, and the control buttons are
+     * unaffected. Default `false`.
+     */
+    closeOnBackdropClick?: boolean;
     /** Top-left title area. */
     renderHeader?: (ctx: ViewerContext<TData>) => ReactNode;
     /** Extra top-right buttons, rendered before the close button. */
@@ -97,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. */
@@ -112,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, zoom, showCounter, loop, 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";
@@ -172,7 +261,12 @@ interface ImageZoomPanState {
  */
 declare function useImageZoomPan(imgWrapperRef: RefObject<HTMLDivElement | null>, currentIndex: number, 
 /** When false, wheel-zoom and double-click-zoom are disabled. Default true. */
-enabled?: boolean): ImageZoomPanState;
+enabled?: boolean, 
+/**
+ * When true (default), wheel-zoom anchors on the cursor. When false, it zooms
+ * about the viewport center.
+ */
+zoomToCursor?: boolean): ImageZoomPanState;
 
 interface SlideNavigationState {
     slideTrackRef: React.RefObject<HTMLDivElement | null>;
@@ -195,7 +289,9 @@ interface SlideNavigationState {
  * preloaded/decoded before navigation commits so the swipe lands on a painted
  * frame.
  */
-declare function useSlideNavigation(items: ViewerItem[], currentIndex: number, onNavigate: (index: number) => void, onSlideStart?: (direction: "prev" | "next") => void): SlideNavigationState;
+declare function useSlideNavigation(items: ViewerItem[], currentIndex: number, onNavigate: (index: number) => void, onSlideStart?: (direction: "prev" | "next") => void, 
+/** When true, navigation wraps around the ends instead of stopping. */
+loop?: boolean): SlideNavigationState;
 
 interface GestureHandlers {
     handlePointerDown: (e: React.PointerEvent) => void;
@@ -215,7 +311,12 @@ interface GestureHandlers {
  */
 declare function useGestureHandler(zoomPan: ImageZoomPanState, slide: SlideNavigationState, hasPrev: boolean, hasNext: boolean, 
 /** When false, pinch-zoom and double-tap-zoom are disabled. Default true. */
-zoomEnabled?: boolean): GestureHandlers;
+zoomEnabled?: boolean, 
+/**
+ * When true (default), pinch-zoom anchors on the gesture midpoint. When
+ * false, it zooms about the viewport center.
+ */
+zoomToCursor?: boolean): GestureHandlers;
 
 /**
  * Measures the height of the top and bottom bars so the image area
@@ -274,4 +375,4 @@ declare function resolveSlideDirection({ offset, elapsedMs, viewportWidth, hasPr
  */
 declare function useFocusTrap(containerRef: RefObject<HTMLElement | null>, active: boolean): void;
 
-export { ChevronLeftIcon, ChevronRightIcon, CloseIcon, type Dims, type ImageTransform, ImageViewer, type ImageViewerProps, type ImageZoomPanState, MAX_SCALE, MIN_SCALE, NavButton, type ResolveSlideArgs, type SlideAction, type SlideNavigationState, type ViewerContext, type ViewerIcons, type ViewerItem, type ViewerSlot, ZoomInIcon, ZoomOutIcon, clampTranslate, defaultIcons, resolveSlideDirection, useBarMeasure, useBodyScrollLock, useFocusTrap, useGestureHandler, useImageZoomPan, useSlideNavigation };
+export { ChevronLeftIcon, ChevronRightIcon, CloseIcon, type Dims, type ImageTransform, ImageViewer, type ImageViewerProps, type ImageZoomPanState, MAX_SCALE, MIN_SCALE, NavButton, type ResolveSlideArgs, type SlideAction, type SlideNavigationState, type ViewerContext, type ViewerIcons, type ViewerItem, type ViewerRect, type ViewerSlot, ZoomInIcon, ZoomOutIcon, clampTranslate, defaultIcons, resolveSlideDirection, useBarMeasure, useBodyScrollLock, useFocusTrap, useGestureHandler, useImageZoomPan, useSlideNavigation };