@jekrch/react-viewport-lightbox 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,277 @@
+import * as react from 'react';
+import { ReactNode, SVGProps, RefObject } from 'react';
+
+/**
+ * A single image in the viewer. Neutral replacement for app-specific item
+ * types (e.g. `Panel` / `Organism`).
+ *
+ * `TData` is an optional per-slide payload (caption, credit, links, anything).
+ * It travels with the item and is surfaced as `ctx.item.data` in every render
+ * slot, so details stay paired with their image without a parallel lookup.
+ */
+interface ViewerItem<TData = unknown> {
+    id: string;
+    /** FINAL url — the consumer resolves any base path before passing it in. */
+    src: string;
+    alt?: string;
+    /** Optional thumbnail url; falls back to `src`. */
+    thumbnail?: string;
+    /** Arbitrary per-slide payload, surfaced as `ctx.item.data` in render slots. */
+    data?: TData;
+}
+/** Named, themeable regions of the viewer that accept a `className` override. */
+type ViewerSlot = "root" | "backdrop" | "topBar" | "bottomBar" | "image" | "button" | "counter" | "navButton" | "navStart" | "navEnd" | "overlay";
+/** Overridable control icons. Each is a React node rendered inside its button. */
+interface ViewerIcons {
+    close: ReactNode;
+    zoomIn: ReactNode;
+    zoomOut: ReactNode;
+    prev: ReactNode;
+    next: ReactNode;
+}
+/**
+ * Context object handed to every render slot. Exposes navigation, zoom, and
+ * layout-measurement state so slot content (info drawers, graphs, custom
+ * headers) can coordinate with the viewer.
+ */
+interface ViewerContext<TData = unknown> {
+    items: ViewerItem<TData>[];
+    index: number;
+    item: ViewerItem<TData>;
+    total: number;
+    hasPrev: boolean;
+    hasNext: boolean;
+    goPrev: () => void;
+    goNext: () => void;
+    goTo: (index: number) => void;
+    close: () => void;
+    isZoomed: boolean;
+    displayScale: number;
+    zoomIn: () => void;
+    zoomOut: () => void;
+    resetZoom: () => void;
+    isTouchDevice: boolean;
+    /**
+     * Measured bar heights so overlays (info drawers) can size themselves
+     * between the bars.
+     */
+    topBarHeight: number;
+    bottomBarHeight: number;
+    /**
+     * Lets an overlay push the image track up/down (drawer-open behavior).
+     * Pass a CSS transform string, or `null` to reset. `animate` defaults to
+     * `true`; pass `false` to apply the shift instantly with no transition — e.g.
+     * to snap the image back to center on navigation so it slides in horizontally
+     * instead of dropping down.
+     */
+    setContentShift: (transform: string | null, animate?: boolean) => void;
+}
+interface ImageViewerProps<TData = unknown> {
+    items: ViewerItem<TData>[];
+    /** Controlled index of the active item. */
+    index: number;
+    onIndexChange: (index: number) => void;
+    /**
+     * Fired when a slide STARTS (button, key, or swipe), before the animation and
+     * the resulting `onIndexChange`. Lets overlays (e.g. an info drawer) animate
+     * out in sync with the image. `direction` is the swipe direction.
+     */
+    onNavigate?: (direction: "prev" | "next") => void;
+    /** Called AFTER the exit animation completes. */
+    onClose: () => void;
+    /** Enable zoom/pan (wheel, pinch, double-tap). Default `true`. */
+    zoom?: boolean;
+    /** Show the `index / total` counter. Default `true`. */
+    showCounter?: boolean;
+    /** Wrap around at the ends. Default `false`. */
+    loop?: boolean;
+    /** Top-left title area. */
+    renderHeader?: (ctx: ViewerContext<TData>) => ReactNode;
+    /** Extra top-right buttons, rendered before the close button. */
+    renderHeaderActions?: (ctx: ViewerContext<TData>) => ReactNode;
+    /**
+     * Pinned to the LEFT edge of the nav row, vertically centered alongside the
+     * prev/counter/next group (which stays optically centered). Ideal for an
+     * info/details toggle that should not cost an extra row of vertical space.
+     */
+    renderNavStart?: (ctx: ViewerContext<TData>) => ReactNode;
+    /** Pinned to the RIGHT edge of the nav row; mirror of `renderNavStart`. */
+    renderNavEnd?: (ctx: ViewerContext<TData>) => ReactNode;
+    /** Content below the nav row. */
+    renderFooter?: (ctx: ViewerContext<TData>) => ReactNode;
+    /** Drawers/graphs layered over the image. */
+    renderOverlay?: (ctx: ViewerContext<TData>) => ReactNode;
+    classNames?: Partial<Record<ViewerSlot, string>>;
+    icons?: Partial<ViewerIcons>;
+    ariaLabel?: string;
+}
+
+/**
+ * Batteries-included fullscreen image viewer: zoom, pan, pinch, and swipe
+ * navigation with themeable chrome and render slots. Controlled via `index` /
+ * `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;
+
+interface NavButtonProps {
+    direction: "prev" | "next";
+    enabled: boolean;
+    onClick: () => void;
+    icon: ReactNode;
+    className?: string;
+}
+declare function NavButton({ direction, enabled, onClick, icon, className }: NavButtonProps): react.JSX.Element;
+
+declare function CloseIcon(props: SVGProps<SVGSVGElement>): react.JSX.Element;
+declare function ZoomInIcon(props: SVGProps<SVGSVGElement>): react.JSX.Element;
+declare function ZoomOutIcon(props: SVGProps<SVGSVGElement>): react.JSX.Element;
+declare function ChevronLeftIcon(props: SVGProps<SVGSVGElement>): react.JSX.Element;
+declare function ChevronRightIcon(props: SVGProps<SVGSVGElement>): react.JSX.Element;
+/** The full default icon set, merged with any consumer overrides. */
+declare const defaultIcons: ViewerIcons;
+
+declare const MIN_SCALE = 1;
+declare const MAX_SCALE = 5;
+interface ImageTransform {
+    scale: number;
+    x: number;
+    y: number;
+}
+interface ImageZoomPanState {
+    imgRef: RefObject<HTMLImageElement | null>;
+    displayScale: number;
+    isZoomed: boolean;
+    transformRef: React.MutableRefObject<ImageTransform>;
+    /** Base (unscaled) image dimensions for clamp calculations */
+    baseDimsRef: React.MutableRefObject<{
+        width: number;
+        height: number;
+    }>;
+    resetTransform: () => void;
+    setTransform: (t: ImageTransform, animate?: boolean) => void;
+    applyTransform: (t: ImageTransform, animate?: boolean) => void;
+    clampTranslate: (x: number, y: number, scale: number) => {
+        x: number;
+        y: number;
+    };
+    measureBaseDims: () => void;
+    handleDoubleClick: (e: React.MouseEvent) => void;
+}
+/**
+ * Manages zoom/pan state for an image viewer.
+ *
+ * Applies scale + translate transforms to the **wrapper** element rather
+ * than the image itself. This avoids an iOS Safari compositing bug where
+ * CSS scale() on an element clips its painted output to the element's
+ * original layout bounds.
+ *
+ * When zoomed, the wrapper is positioned absolute inset-0 (full viewport),
+ * so its layout bounds already match the viewport and scaling it won't clip.
+ * The image stays at its natural constrained size, centered via flexbox.
+ */
+declare function useImageZoomPan(imgWrapperRef: RefObject<HTMLDivElement | null>, currentIndex: number, 
+/** When false, wheel-zoom and double-click-zoom are disabled. Default true. */
+enabled?: boolean): ImageZoomPanState;
+
+interface SlideNavigationState {
+    slideTrackRef: React.RefObject<HTMLDivElement | null>;
+    slideActive: boolean;
+    slideAnimating: boolean;
+    swipeOffset: number;
+    swipeOffsetRef: React.MutableRefObject<number>;
+    commitLockRef: React.MutableRefObject<boolean>;
+    applySlideOffset: (offset: number, animate?: boolean) => void;
+    commitSlide: (direction: "prev" | "next") => void;
+    snapBack: () => void;
+    resolveSlide: (gestureStartTime: number) => void;
+    setSlideActive: React.Dispatch<React.SetStateAction<boolean>>;
+}
+/**
+ * Manages the three-slot slide carousel: swipe offset tracking, animated
+ * commit/snap-back, and DOM resets on navigation.
+ *
+ * `items[i].src` is treated as a final, ready-to-load url — the next image is
+ * 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;
+
+interface GestureHandlers {
+    handlePointerDown: (e: React.PointerEvent) => void;
+    handlePointerMove: (e: React.PointerEvent) => void;
+    handlePointerUp: (e: React.PointerEvent) => void;
+    handleTouchStart: (e: React.TouchEvent) => void;
+    handleTouchMove: (e: React.TouchEvent) => void;
+    handleTouchEnd: (e: React.TouchEvent) => void;
+}
+/**
+ * Coordinates zoom/pan and slide gestures, routing pointer and touch events
+ * to the appropriate behavior based on current zoom state.
+ *
+ * When zoomed (scale > 1): pointer/touch drags are pans.
+ * When unzoomed (scale === 1): pointer/touch drags are slide-to-navigate.
+ * Two-finger touch is always a pinch-zoom.
+ */
+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;
+
+/**
+ * Measures the height of the top and bottom bars so the image area
+ * can be constrained to fit between them.
+ */
+declare function useBarMeasure(topBarRef: RefObject<HTMLDivElement | null>, bottomBarRef: RefObject<HTMLDivElement | null>, 
+/** Re-measure whenever this key changes (e.g. currentIndex) */
+measureKey: unknown): {
+    topBarH: number;
+    bottomBarH: number;
+};
+
+declare function useBodyScrollLock(isLocked: boolean): void;
+
+/**
+ * Pure geometry/threshold helpers shared by the interaction hooks. Kept free of
+ * React and DOM globals so they can be unit-tested in isolation.
+ */
+interface Dims {
+    width: number;
+    height: number;
+}
+/**
+ * Clamp a pan translation so the scaled image edge can't move past the
+ * viewport edge. Returns `{ x: 0, y: 0 }` when not zoomed or when base
+ * dimensions are unknown.
+ */
+declare function clampTranslate(x: number, y: number, scale: number, baseDims: Dims, viewport: Dims): {
+    x: number;
+    y: number;
+};
+type SlideAction = "prev" | "next" | "snap";
+interface ResolveSlideArgs {
+    /** Current horizontal swipe offset in px (positive = dragged right). */
+    offset: number;
+    /** Elapsed time of the gesture in ms (used for fling velocity). */
+    elapsedMs: number;
+    viewportWidth: number;
+    hasPrev: boolean;
+    hasNext: boolean;
+    /** Fraction of viewport width past which a drag commits. Default 0.25. */
+    distanceThreshold?: number;
+    /** px/ms past which a fast fling commits regardless of distance. Default 0.4. */
+    velocityThreshold?: number;
+}
+/**
+ * Decide whether a released swipe should navigate `prev`/`next` or `snap` back,
+ * based on distance and fling velocity.
+ */
+declare function resolveSlideDirection({ offset, elapsedMs, viewportWidth, hasPrev, hasNext, distanceThreshold, velocityThreshold, }: ResolveSlideArgs): SlideAction;
+
+/**
+ * Traps Tab focus within `containerRef` while `active`, and restores focus to
+ * the previously-focused element on deactivate/unmount. SSR-safe (effect only
+ * runs in the browser).
+ */
+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 };