react-native-gesture-image-viewer 1.2.2 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-gesture-image-viewer",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "🖼️ A highly customizable and easy-to-use React Native image viewer with gesture support and external controls",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -14,6 +14,7 @@
   },
   "files": [
     "lib",
+    "src",
     "android",
     "ios",
     "cpp",

package/src/GestureViewer.tsx

@@ -0,0 +1,171 @@
+import { useCallback, useEffect, useMemo } from 'react';
+import { type FlatList, Platform, type ScrollViewProps, StyleSheet, useWindowDimensions, View } from 'react-native';
+import { Gesture, GestureDetector, GestureHandlerRootView } from 'react-native-gesture-handler';
+import Animated from 'react-native-reanimated';
+import { registry } from './GestureViewerRegistry';
+import type { GestureViewerProps } from './types';
+import { useGestureViewer } from './useGestureViewer';
+import { isFlashListLike, isFlatListLike, isScrollViewLike } from './utils';
+import WebPagingFixStyle from './WebPagingFixStyle';
+
+export function GestureViewer<T = any, LC = typeof FlatList>({
+  id = 'default',
+  data,
+  renderItem: renderItemProp,
+  renderContainer,
+  ListComponent,
+  width: customWidth,
+  listProps,
+  backdropStyle: backdropStyleProps,
+  containerStyle,
+  initialIndex = 0,
+  itemSpacing = 0,
+  useSnap = false,
+  ...props
+}: GestureViewerProps<T, LC>) {
+  const Component = ListComponent as React.ComponentType<any>;
+
+  const { width: screenWidth } = useWindowDimensions();
+
+  const width = useSnap ? customWidth || screenWidth : screenWidth;
+
+  const { listRef, isZoomed, dismissGesture, zoomGesture, onMomentumScrollEnd, animatedStyle, backdropStyle } =
+    useGestureViewer({
+      id,
+      data,
+      width,
+      initialIndex,
+      itemSpacing,
+      useSnap,
+      ...props,
+    });
+
+  const renderItem = useCallback(
+    ({ item, index }: { item: T; index: number }) => {
+      return (
+        <View
+          key={typeof item === 'string' ? item : index}
+          style={[
+            {
+              width,
+              height: '100%',
+              justifyContent: 'center',
+              alignItems: 'center',
+              marginHorizontal: itemSpacing / 2,
+            },
+          ]}
+        >
+          {renderItemProp(item, index)}
+        </View>
+      );
+    },
+    [width, itemSpacing, renderItemProp],
+  );
+
+  const getItemLayout = useCallback(
+    (_: ArrayLike<T> | null | undefined, index: number) => ({
+      length: width + itemSpacing,
+      offset: (width + itemSpacing) * index,
+      index,
+    }),
+    [width, itemSpacing],
+  );
+
+  const keyExtractor = useCallback(
+    (item: T, index: number) => (typeof item === 'string' ? item : `image-${index}`),
+    [],
+  );
+
+  const gesture = useMemo(() => {
+    return Gesture.Race(dismissGesture, zoomGesture);
+  }, [zoomGesture, dismissGesture]);
+
+  useEffect(() => {
+    registry.createManager(id);
+
+    return () => registry.deleteManager(id);
+  }, [id]);
+
+  const commonProps: ScrollViewProps = useMemo(
+    () => ({
+      horizontal: true,
+      scrollEnabled: !isZoomed,
+      showsHorizontalScrollIndicator: false,
+      onMomentumScrollEnd: onMomentumScrollEnd,
+      ...(useSnap
+        ? {
+            snapToInterval: width + itemSpacing,
+            snapToAlignment: 'center',
+            decelerationRate: 'fast',
+          }
+        : {
+            pagingEnabled: true,
+          }),
+      scrollEventThrottle: 16,
+      removeClippedSubviews: true,
+    }),
+    [width, itemSpacing, isZoomed, onMomentumScrollEnd, useSnap],
+  );
+
+  const listComponent = (
+    <GestureHandlerRootView>
+      <GestureDetector gesture={gesture}>
+        <View style={[styles.container, containerStyle]}>
+          <Animated.View style={[styles.background, backdropStyleProps, backdropStyle]} />
+          <Animated.View
+            style={[styles.content, animatedStyle]}
+            {...(Platform.OS === 'web' &&
+              isFlashListLike(Component) && { dataSet: { 'flash-list-paging-enabled-fix': true } })}
+          >
+            {isScrollViewLike(Component) ? (
+              <Component ref={listRef} {...commonProps} {...listProps}>
+                {data.map((item, index) => renderItem({ item, index }))}
+              </Component>
+            ) : (
+              isFlatListLike(Component) && (
+                <Component
+                  ref={listRef}
+                  {...commonProps}
+                  data={data}
+                  renderItem={renderItem}
+                  initialScrollIndex={initialIndex}
+                  keyExtractor={keyExtractor}
+                  windowSize={3}
+                  maxToRenderPerBatch={3}
+                  getItemLayout={getItemLayout}
+                  {...(isFlashListLike(Component) && { estimatedItemSize: width + itemSpacing })}
+                  // NOTE - https://github.com/necolas/react-native-web/issues/1299
+                  {...(Platform.OS === 'web' &&
+                    isFlatListLike(Component) && { dataSet: { 'flat-list-paging-enabled-fix': true } })}
+                  {...listProps}
+                />
+              )
+            )}
+          </Animated.View>
+          <WebPagingFixStyle Component={Component} />
+        </View>
+      </GestureDetector>
+    </GestureHandlerRootView>
+  );
+
+  return renderContainer ? renderContainer(listComponent) : listComponent;
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+  content: {
+    flex: 1,
+    width: '100%',
+    height: '100%',
+  },
+  background: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    backgroundColor: 'black',
+  },
+});

package/src/GestureViewerManager.ts

@@ -0,0 +1,201 @@
+import { type SharedValue, withTiming } from 'react-native-reanimated';
+import { createBoundsConstraint } from './utils';
+
+export type GestureViewerManagerState = {
+  currentIndex: number;
+  dataLength: number;
+};
+
+class GestureViewerManager {
+  private currentIndex = 0;
+  private dataLength = 0;
+  private width = 0;
+  private height = 0;
+  private scale: SharedValue<number> | null = null;
+  private translateX: SharedValue<number> | null = null;
+  private translateY: SharedValue<number> | null = null;
+  private maxZoomScale = 2;
+  private listRef: any | null = null;
+  private enableSwipeGesture = true;
+  private listeners = new Set<(state: GestureViewerManagerState) => void>();
+
+  private notifyListeners() {
+    const state = this.getState();
+
+    this.listeners.forEach((listener) => listener(state));
+  }
+
+  subscribe(listener: (state: GestureViewerManagerState) => void) {
+    this.listeners.add(listener);
+
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  getState() {
+    return {
+      currentIndex: this.currentIndex,
+      dataLength: this.dataLength,
+    };
+  }
+
+  setWidth(width: number) {
+    this.width = width;
+  }
+
+  setHeight(height: number) {
+    this.height = height;
+  }
+
+  setListRef(ref: any) {
+    this.listRef = ref;
+  }
+
+  setDataLength(length: number) {
+    this.dataLength = length;
+  }
+
+  setEnableSwipeGesture(enabled: boolean) {
+    this.enableSwipeGesture = enabled;
+  }
+
+  setCurrentIndex(index: number) {
+    if (index !== this.currentIndex) {
+      this.currentIndex = index;
+    }
+  }
+
+  setZoomSharedValues(
+    scale: SharedValue<number>,
+    translateX: SharedValue<number>,
+    translateY: SharedValue<number>,
+    maxZoomScale: number,
+  ) {
+    this.scale = scale;
+    this.translateX = translateX;
+    this.translateY = translateY;
+    this.maxZoomScale = maxZoomScale;
+  }
+
+  notifyStateChange() {
+    this.notifyListeners();
+  }
+
+  /**
+   * @param multiplier - The multiplier to zoom in.
+   * @range 0.01 - 1
+   * @default 0.25
+   */
+  zoomIn = (multiplier = 0.25) => {
+    if (!this.scale || !this.translateX || !this.translateY || multiplier < 0.01 || multiplier > 1) {
+      return;
+    }
+
+    const nextScale = Math.min(this.scale.value * (1 + multiplier), this.maxZoomScale);
+
+    this.scale.value = withTiming(nextScale);
+
+    const { translateX, translateY } = createBoundsConstraint({
+      width: this.width,
+      height: this.height,
+    })({
+      translateX: this.translateX.value,
+      translateY: this.translateY.value,
+      scale: nextScale,
+    });
+
+    this.translateX.value = withTiming(translateX);
+    this.translateY.value = withTiming(translateY);
+  };
+
+  /**
+   * @param multiplier - The multiplier to zoom out.
+   * @range 0.01 - 1
+   * @default 0.25
+   */
+  zoomOut = (multiplier = 0.25) => {
+    if (!this.scale || !this.translateX || !this.translateY || multiplier < 0.01 || multiplier > 1) {
+      return;
+    }
+
+    const nextScale = Math.max(this.scale.value / (1 + multiplier), 1);
+
+    this.scale.value = withTiming(nextScale);
+
+    if (nextScale === 1) {
+      this.translateX.value = withTiming(0);
+      this.translateY.value = withTiming(0);
+      return;
+    }
+
+    const { translateX, translateY } = createBoundsConstraint({
+      width: this.width,
+      height: this.height,
+    })({
+      translateX: this.translateX.value,
+      translateY: this.translateY.value,
+      scale: nextScale,
+    });
+
+    this.translateX.value = withTiming(translateX);
+    this.translateY.value = withTiming(translateY);
+  };
+
+  /**
+   * @param scale - The scale to reset to.
+   * @default 1
+   */
+  resetZoom = (scale = 1) => {
+    if (!this.scale || !this.translateX || !this.translateY || scale <= 0 || scale > this.maxZoomScale) {
+      return;
+    }
+
+    this.scale.value = withTiming(scale);
+    this.translateX.value = withTiming(0);
+    this.translateY.value = withTiming(0);
+  };
+
+  goToIndex = (index: number) => {
+    if (index < 0 || index >= this.dataLength || !this.enableSwipeGesture || !this.listRef) {
+      return;
+    }
+
+    this.currentIndex = index;
+
+    if (this.listRef.scrollToIndex) {
+      this.listRef.scrollToIndex({ index, animated: true });
+    } else if (this.listRef.scrollTo) {
+      this.listRef.scrollTo({ x: index * this.width, animated: true });
+    }
+
+    this.notifyListeners();
+  };
+
+  goToPrevious = () => {
+    if (this.currentIndex > 0) {
+      this.goToIndex(this.currentIndex - 1);
+    }
+  };
+
+  goToNext = () => {
+    if (this.currentIndex < this.dataLength - 1) {
+      this.goToIndex(this.currentIndex + 1);
+    }
+  };
+
+  cleanUp() {
+    this.listeners.clear();
+    this.listRef = null;
+    this.enableSwipeGesture = true;
+    this.currentIndex = 0;
+    this.dataLength = 0;
+
+    this.maxZoomScale = 2;
+    this.scale = null;
+    this.translateX = null;
+    this.translateY = null;
+  }
+}
+
+export default GestureViewerManager;

package/src/GestureViewerRegistry.ts

@@ -0,0 +1,66 @@
+import GestureViewerManager from './GestureViewerManager';
+
+class GestureViewerRegistry {
+  private managers = new Map<string, GestureViewerManager>();
+  private subscribers = new Map<string, Set<(manager: GestureViewerManager | null) => void>>();
+
+  subscribeToManager(id: string, callback: (manager: GestureViewerManager | null) => void) {
+    if (!this.subscribers.has(id)) {
+      this.subscribers.set(id, new Set());
+    }
+
+    this.subscribers.get(id)?.add(callback);
+
+    const manager = this.managers.get(id) || null;
+
+    callback(manager);
+
+    return () => {
+      const subscribers = this.subscribers.get(id);
+
+      subscribers?.delete(callback);
+
+      if (subscribers && subscribers.size === 0) {
+        this.subscribers.delete(id);
+      }
+    };
+  }
+
+  createManager(id: string): GestureViewerManager | null {
+    if (this.managers.has(id)) {
+      return this.managers.get(id) || null;
+    }
+
+    const manager = new GestureViewerManager();
+    this.managers.set(id, manager);
+
+    this.notifySubscribers(id, manager);
+
+    return manager;
+  }
+
+  getManager(id: string): GestureViewerManager | null {
+    return this.managers.get(id) || null;
+  }
+
+  deleteManager(id: string) {
+    const manager = this.managers.get(id);
+
+    if (manager) {
+      manager.cleanUp();
+      this.managers.delete(id);
+
+      this.notifySubscribers(id, null);
+    }
+  }
+
+  notifySubscribers(id: string, manager: GestureViewerManager | null) {
+    const listeners = this.subscribers.get(id);
+
+    if (listeners) {
+      [...listeners].forEach((callback) => callback(manager));
+    }
+  }
+}
+
+export const registry = new GestureViewerRegistry();

package/src/WebPagingFixStyle.tsx

@@ -0,0 +1,24 @@
+import { Platform } from 'react-native';
+import { isFlashListLike, isFlatListLike } from './utils';
+
+type WebPagingFixStyleProps = {
+  Component: React.ComponentType<any>;
+};
+
+function WebPagingFixStyle({ Component }: WebPagingFixStyleProps) {
+  if (Platform.OS !== 'web') {
+    return null;
+  }
+
+  if (isFlashListLike(Component)) {
+    return <style>{`[data-flash-list-paging-enabled-fix] > div {height: 100%;}`}</style>;
+  }
+
+  if (isFlatListLike(Component)) {
+    return <style>{`[data-flat-list-paging-enabled-fix] > div > div > div {height: 100%;}`}</style>;
+  }
+
+  return null;
+}
+
+export default WebPagingFixStyle;

package/src/index.tsx

@@ -0,0 +1,3 @@
+export { GestureViewer } from './GestureViewer';
+export type { GestureViewerProps } from './types';
+export { useGestureViewerController } from './useGestureViewerController';

package/src/types.ts

@@ -0,0 +1,144 @@
+import type React from 'react';
+import type { FlatList as RNFlatList, ScrollView as RNScrollView, StyleProp, ViewStyle } from 'react-native';
+import type { FlatList as GHFlatList, ScrollView as GHScrollView } from 'react-native-gesture-handler';
+
+export type FlatListComponent = typeof RNFlatList | typeof GHFlatList;
+export type ScrollViewComponent = typeof RNScrollView | typeof GHScrollView;
+
+type GetComponentProps<T> = T extends React.ComponentType<infer P> ? P : never;
+
+type ConditionalListProps<LC> = LC extends FlatListComponent
+  ? React.ComponentProps<LC>
+  : LC extends ScrollViewComponent
+    ? React.ComponentProps<LC>
+    : GetComponentProps<LC>;
+
+export interface GestureViewerProps<T = any, LC = typeof RNFlatList> {
+  /**
+   * When you want to efficiently manage multiple `GestureViewer` instances, you can use the `id` prop to use multiple `GestureViewer` components.
+   * @remark `GestureViewer` automatically removes instances from memory when components are unmounted, so no manual memory management is required.
+   * @default 'default'
+   */
+  id?: string;
+  /**
+   * The data to display in the `GestureViewer`.
+   */
+  data: T[];
+  /**
+   * The index of the item to display in the `GestureViewer` when the component is mounted.
+   * @default 0
+   */
+  initialIndex?: number;
+  /**
+   * A callback function that is called when the index of the item changes.
+   */
+  onIndexChange?: (index: number) => void;
+  /**
+   * A callback function that is called when the `GestureViewer` is dismissed.
+   */
+  onDismiss?: () => void;
+  /**
+   * A callback function that is called to render the item.
+   */
+  renderItem: (item: T, index: number) => React.ReactElement;
+  /**
+   * A callback function that is called to render the container.
+   */
+  renderContainer?: (children: React.ReactElement) => React.ReactElement;
+  /**
+   * Support for any list component like `ScrollView`, `FlatList`, `FlashList` through the `ListComponent` prop.
+   */
+  ListComponent: LC;
+  /**
+   * The width of the `GestureViewer`.
+   * @remark If you don't set this prop, the width of the `GestureViewer` will be the same as the width of the screen.
+   * @default screen width
+   */
+  width?: number;
+  /**
+   * Enables snap scrolling mode.
+   *
+   * @remark
+   * **`false` (default)**: Paging mode (`pagingEnabled: true`)
+   * - Scrolls by full screen size increments
+   *
+   * **`true`**: Snap mode (`snapToInterval` auto-calculated)
+   * - `snapToInterval` is automatically calculated based on `width` and `itemSpacing` values
+   * - Use this option when you need item spacing
+   * @default false
+   *
+   */
+  useSnap?: boolean;
+  /**
+   * `dismissThreshold` controls when `onDismiss` is called by applying a threshold value during vertical gestures.
+   * @default 80
+   */
+  dismissThreshold?: number;
+  // swipeThreshold?: number;
+  // velocityThreshold?: number;
+  /**
+   * Calls `onDismiss` function when swiping down.
+   * @remark Useful for closing modals with downward swipe gestures.
+   * @default true
+   */
+  enableDismissGesture?: boolean;
+  /**
+   * Controls left/right swipe gestures.
+   * @remark When `false`, horizontal gestures are disabled.
+   * @default true
+   */
+  enableSwipeGesture?: boolean;
+  /**
+   * `resistance` controls the range of vertical movement by applying resistance during vertical gestures.
+   * @default 2
+   */
+  resistance?: number;
+  /**
+   * The props to pass to the list component.
+   * @remark The `listProps` provides **type inference based on the selected list component**, ensuring accurate autocompletion and type safety in your IDE.
+   */
+  listProps?: Partial<ConditionalListProps<LC>>;
+  /**
+   * The style of the backdrop.
+   */
+  backdropStyle?: StyleProp<ViewStyle>;
+  /**
+   * The style of the container.
+   */
+  containerStyle?: StyleProp<ViewStyle>;
+  /**
+   * By default, the background `opacity` gradually decreases from 1 to 0 during downward swipe gestures.
+   * @remark When `false`, this animation is disabled.
+   * @default true
+   */
+  animateBackdrop?: boolean;
+  /**
+   * Only works when zoom is active, allows moving item position when zoomed.
+   * @remark When `false`, gesture movement is disabled during zoom.
+   * @default true
+   */
+  enableZoomPanGesture?: boolean;
+  /**
+   * Controls two-finger pinch gestures.
+   * @remark When `false`, two-finger zoom gestures are disabled.
+   * @default true
+   */
+  enableZoomGesture?: boolean;
+  /**
+   * Controls double-tap zoom gestures.
+   * @remark When `false`, double-tap zoom gestures are disabled.
+   * @default true
+   */
+  enableDoubleTapGesture?: boolean;
+  /**
+   * The maximum zoom scale.
+   * @default 2
+   */
+  maxZoomScale?: number;
+  /**
+   * The spacing between items in pixels.
+   * @remark Only applied when `useSnap` is `true`.
+   * @default 0
+   */
+  itemSpacing?: number;
+}