Pre release 4.0.0

docs/docs/.vitepress/config.mts

@@ -14,7 +14,7 @@ export default defineConfig({
     nav: [
       { text: 'Home', link: '/' },
       {
-        text: '3.1.0',
+        text: '4.0.0',
         items: [
           {
             text: 'Releases',
@@ -46,12 +46,12 @@ export default defineConfig({
         text: 'Utilities',
         collapsed: true,
         items: [
+          { text: 'fitContainer', link: '/utilities/fitContainer' },
           { text: 'useImageResolution', link: '/utilities/useimageresolution' },
           {
             text: 'useTransformationState',
             link: '/utilities/usetransformationstate',
           },
-          { text: 'getAspectRatioSize', link: '/utilities/getAspectRatioSize' },
         ],
       },
       {

docs/docs/components/gallery.md

@@ -14,7 +14,8 @@ A practical gallery component which mimics Telegram's gallery behavior, among it
 - **Tap to Item:** Tap on the edges of an item to go to the previous or next item.
 - **Custom Scroll Transition**: Customize scroll behavior with your own transitions.
 
-The next video footage is taken from the [Example app](https://github.com/Glazzes/react-native-zoom-toolkit/tree/main/example).
+The next video footage is taken from the [Example app](https://github.com/Glazzes/react-native-zoom-toolkit/tree/main/example)
+while using a custom transition.
 
 <div style="width: 100%; display: flex; justify-content: center; align-items: center">
   <video src="../assets/gallery.mp4" controls />
@@ -165,6 +166,14 @@ Used to extract a unique key for a given item at the specified index.
 
 Maximum number of items to be rendered at once.
 
+### gap
+
+| Type     | Default |
+| -------- | ------- |
+| `number` | `0`     |
+
+Blank space between items.
+
 ### initialIndex
 
 | Type     | Default |
@@ -468,11 +477,12 @@ Jump to the item at the given index.
 
 ### GalleryTransitionState
 
-| Property      | Type                 | Description                                           |
-| ------------- | -------------------- | ----------------------------------------------------- |
-| `index`       | `number`             | Index of an item rendered in the gallery.             |
-| `activeIndex` | `number`             | Index of the currently displayed item on the gallery. |
-| `vertical`    | `boolean`            | Whether the gallery is in vertical mode or not.       |
-| `isScrolling` | `boolean`            | Whether the gallery is actively being scrolled.       |
-| `scroll`      | `number`             | Current scroll value.                                 |
-| `gallerySize` | `SizeVector<number>` | Width and height of the gallery.                      |
+| Property      | Type                     | Description                                           |
+| ------------- | ------------------------ | ----------------------------------------------------- |
+| `index`       | `number`                 | Index of an item rendered in the gallery.             |
+| `activeIndex` | `number`                 | Index of the currently displayed item on the gallery. |
+| `gap`         | `number`                 | Blank space between items.                            |
+| `direction`   | `vertical \| horizontal` | Direction of the gallery.                             |
+| `isScrolling` | `boolean`                | Whether the gallery is actively being scrolled.       |
+| `scroll`      | `number`                 | Current scroll value.                                 |
+| `gallerySize` | `SizeVector<number>`     | Width and height of the gallery.                      |

docs/docs/components/resumablezoom.md

@@ -31,37 +31,32 @@ This component is best utilized when at least one of the two dimensions of the w
 
 ```jsx
 import React from 'react';
-import { Image, View, useWindowDimensions } from 'react-native';
+import { Image, useWindowDimensions } from 'react-native';
 import {
+  fitContainer,
   ResumableZoom,
-  getAspectRatioSize,
   useImageResolution,
 } from 'react-native-zoom-toolkit';
 
 const uri =
   'https://assets-global.website-files.com/63634f4a7b868a399577cf37/64665685a870fadf4bb171c2_labrador%20americano.jpg';
 
 const App = () => {
-  const { width } = useWindowDimensions();
-
-  // Gets the resolution of your image
+  const { width, height } = useWindowDimensions();
   const { isFetching, resolution } = useImageResolution({ uri });
   if (isFetching || resolution === undefined) {
     return null;
   }
 
-  // An utility function to get the size without compromising the aspect ratio
-  const imageSize = getAspectRatioSize({
-    aspectRatio: resolution.width / resolution.height,
-    width: width,
+  const size = fitContainer(resolution.width / resolution.height, {
+    width,
+    height,
   });
 
   return (
-    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
-      <ResumableZoom maxScale={resolution}>
-        <Image source={{ uri }} style={imageSize} resizeMethod={'scale'} />
-      </ResumableZoom>
-    </View>
+    <ResumableZoom maxScale={resolution}>
+      <Image source={{ uri }} style={{ ...size }} resizeMethod={'scale'} />
+    </ResumableZoom>
   );
 };
 
@@ -320,12 +315,19 @@ Programmatically zoom in or out to a xy position within the child component.
 | multiplier | `number`                      | Value to multiply the current scale for, values greater than one zoom in and values less than one zoom out.                                                                                                                      |
 | xy         | `Vector<number> \| undefined` | Position of the point to zoom in or out starting from the top left corner of your component, leaving this value as undefined will be infered as zooming in or out from the center of the child component's current visible area. |
 
+### getVisibleRect
+
+Get the coordinates of the current visible rectangle within ResumableZoom's frame.
+
+- type definition: `() => Rect`
+- return type: `{x: number, y: number, width: number, height: number}`
+
 ### requestState
 
 Request internal transformation values of this component at the moment of the calling.
 
 - type definition: `() => CommonZoomState<number>`
-- return type: [CommonZoomState](#commonzoomstate)
+- return type: [CommonZoomState\<number\>](#commonzoomstate)
 
 ### assignState
 

docs/docs/components/snapbackzoom.md

@@ -1,5 +1,5 @@
 ---
-title: Snapback Zoom
+title: SnapbackZoom
 description: An ideal zoom component for preview handling
 outline: deep
 ---
@@ -161,6 +161,28 @@ if you need to mirror the current state of the gesture to some other component,
 
 Callback triggered once the snap back animation has finished.
 
+### scrollRef
+
+| Type                                       | Default     |
+| ------------------------------------------ | ----------- |
+| `React.RefObject<React.ComponentType<{}>>` | `undefined` |
+
+Improve gesture detection when SnapbackZoom is rendered within a vertical ScrollView, see the following example.
+
+```tsx
+const scrollViewRef = useRef<ScrollView>(null);
+
+<ScrollView ref={scrollViewRef}>
+  {images.map((uri) => {
+    return (
+      <SnapbackZoom scrollRef={scrollViewRef}>
+        <Image source={{ uri }} style={styles.image} />
+      </SnapbackZoom>
+    );
+  })}
+</ScrollView>;
+```
+
 ## About resizeConfig Property
 
 Before you start reading, for a visual reference watch the video above and pay attention to the parrot image.

docs/docs/installation.md

@@ -5,46 +5,25 @@ outline: deep
 
 # Installation
 
-Install `react-native-zoom-toolkit` in your project
-
-::: code-group
-
-```sh [npm]
-npm install react-native-zoom-toolkit
-```
-
-```sh [yarn]
-yarn add react-native-zoom-toolkit
-```
-
-:::
-
-### Dependencies
-
 This library relies on both Reanimated and Gesture Handler making part of your project, if you do not have them installed already please refer to [Reanimated](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/) and [Gesture Handler](https://docs.swmansion.com/react-native-gesture-handler/docs/fundamentals/installation) installation guides.
 
-::: tip Recommended Versions
-
-- Recommended versions for react-native-gesture-handler are `2.16.0` and above, previous versions should work
-  well but it's not guaranteed.
-  :::
+| React Native Version | React Native Zoom Toolkit Version | Gesture Handler version |
+| -------------------- | --------------------------------- | ----------------------- |
+| `<= 0.76`            | `3.x.x`                           | 2.16.0 and beyond.      |
+| `>= 0.76`            | `4.x.x`                           | 2.19.0 and beyond.      |
 
 ::: code-group
 
 ```sh [npm]
-npm install react-native-gesture-handler react-native-reanimated
+npm install react-native-zoom-toolkit react-native-gesture-handler react-native-reanimated
 ```
 
 ```sh [yarn]
-yarn add react-native-gesture-handler react-native-reanimated
+yarn add react-native-zoom-toolkit react-native-gesture-handler react-native-reanimated
 ```
 
 ```sh [expo]
-npx expo install react-native-gesture-handler react-native-reanimated
+npx expo install react-native-zoom-toolkit react-native-gesture-handler react-native-reanimated
 ```
 
 :::
-
-### Additional Setup
-
-No additional setup is required.

docs/docs/utilities/fitContainer.md

@@ -0,0 +1,28 @@
+---
+title: fitContainer
+description: Get width and height of an element to fit a container
+outline: deep
+---
+
+# fitContainer
+
+Get the width and height for an element based on its aspect ratio and the container to fit in a such a way the
+aspect ratio of the element is not compromised.
+
+## Type Definition
+
+| Name        | Type                 | Description                         |
+| ----------- | -------------------- | ----------------------------------- |
+| aspectRatio | `number`             | Aspect ratio of the element to fit. |
+| container   | `SizeVector<number>` | Width and height of the container.  |
+
+## How to use
+
+```js
+const container = useWindowDimensions();
+const resolution = { width: 1920, height: 1080 };
+const size = fitContainer(resolution.width / resolution.height, {
+  width: container.width,
+  height: container.height,
+});
+```

docs/docs/utilities/useimageresolution.md

@@ -5,45 +5,39 @@ outline: deep
 ---
 
 # useImageResolution hook
-Get the resolution of a bundle or network image.
+
+Get the resolution of a network, bundle or base64 image.
 
 ### How to use
+
 ```jsx
 import { useImageResolution } from 'react-native-zoom-toolkit';
 
-// Get resolution of a bundle image
+// Network image
+const { isFetching, resolution, error } = useImageResolution({
+  uri: 'url to some network image',
+  headers: {
+    Authorization: 'some bearer token',
+  },
+});
+
+// Bundle image
 const { isFetching, resolution, error } = useImageResolution(
   require('path to your bundle image asset')
 );
 
-// Get resolution of a network image
+// Base64 image
 const { isFetching, resolution, error } = useImageResolution({
-  uri: 'url to some network image',
-  headers: {
-    'Authorization': 'some bearer token',
-  }
-})
-
+  uri: 'your base64 string',
+});
 ```
-- parameter information
-
-| Property | Type |Description |
-|----------|------|------------|
-| `source`    | `Source \| number` | An url pointing to a network image and headers or a require statement to a bundle image asset. |
-
-- returns [FetchImageResolutionResult](#fetchimageresolutionresult)
 
 ## Type Definitions
-### Source
-| Property | Type |Description |
-|----------|------|------------|
-| `uri`    | `string` | An url pointing to a network image. |
-| `headers`    | `Record<string, string> \| undefined` | Optional headers, in case you are accesing network protected images. |
 
 ### FetchImageResolutionResult
 
-| Property | Type |Description |
-|----------|------|------------|
-| `isFetching`    | `boolean` | Whether the hook is fetching or not. |
-| `resolution`    | `SizeVector \| undefined` | Width and height of the image. |
-| `error` | `Error \| undefined` | An error in case the image fetching fails. |
+| Property     | Type                      | Description                                |
+| ------------ | ------------------------- | ------------------------------------------ |
+| `isFetching` | `boolean`                 | Whether the hook is fetching or not.       |
+| `resolution` | `SizeVector \| undefined` | Width and height of the image.             |
+| `error`      | `Error \| undefined`      | An error in case the image fetching fails. |

example/app.json

@@ -4,6 +4,7 @@
     "slug": "example",
     "scheme": "example",
     "version": "1.0.0",
+    "newArchEnabled": true,
     "orientation": "default",
     "icon": "./assets/icon.png",
     "userInterfaceStyle": "light",
@@ -28,6 +29,6 @@
       "favicon": "./assets/favicon.png",
       "bundler": "metro"
     },
-    "plugins": ["expo-router"]
+    "plugins": ["expo-router", "expo-video"]
   }
 }

example/app/_layout.tsx

@@ -1,12 +1,13 @@
 import React from 'react';
+import { StyleSheet } from 'react-native';
+
 import { Drawer } from 'expo-router/drawer';
 import { GestureHandlerRootView } from 'react-native-gesture-handler';
 import * as Orientation from 'expo-screen-orientation';
 
 Orientation.lockAsync(Orientation.OrientationLock.PORTRAIT_UP);
 
 import { default as CustomDrawer } from '../src/navigation/Drawer';
-import { StyleSheet } from 'react-native';
 
 const _layout = () => {
   return (

example/app/snapback.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { SnapbackZoomExample } from '../src/snapback';
+import SnapbackZoomExample from '../src/snapback';
 
 const snapback = () => {
   return <SnapbackZoomExample />;