Merge pull request #66 from Glazzes/dev

Before release 3.1.0

docs/docs/.vitepress/config.mts

@@ -14,7 +14,7 @@ export default defineConfig({
     nav: [
       { text: 'Home', link: '/' },
       {
-        text: '3.0.0',
+        text: '3.1.0',
         items: [
           {
             text: 'Releases',

docs/docs/components/cropzoom.md

@@ -66,7 +66,10 @@ const App = () => {
       resolution={resolution}
       OverlayComponent={renderOverlay}
     >
-      <Image source={{uri: iamgeUrl }} style={{ width: '100%', height: '100%' }} />
+      <Image
+        source={{uri: iamgeUrl }}
+        style={{ width: '100%', height: '100%' }}
+      />
     </CropZoom>
   );
 }
@@ -152,12 +155,6 @@ defined by `minScale` and `maxScale` properties, possible values are:
 | --------- | ------- | -------- |
 | `boolean` | `true`  | `No`     |
 
-::: warning Beware iOS users
-This feature is disabled by default for iOS users when a version of React Native Gesture Handler prior to `2.16.0` is installed, installing a version greater than equals `2.16.0` will set the value of this property to `true` by default.
-
-For more information see this [Gesture Handler's issue](https://github.com/software-mansion/react-native-gesture-handler/issues/2833) and [this issue](https://github.com/Glazzes/react-native-zoom-toolkit/issues/10).
-:::
-
 Lets the user pan the component around as they pinch as well as providing a more accurate pinch gesture calculation
 to user interaction. Panning as you pinch will not trigger any pan gesture related callbacks.
 
@@ -217,8 +214,8 @@ values to some other component as it updates, see [CropZoomState](#cropzoomstate
 | ------------ | ----------- | -------- |
 | `() => void` | `undefined` | `No`     |
 
-Callback triggered when a pan or pinch gesture ends, if an animation started at the end of one
-of the gestures this callback's execution will be delayed until the animation has finished.
+Callback triggered when a pan, pinch or double tap gesture ends, if an animation started at the end of one
+of the gestures the execution of this callback will be delayed until such animation finishes.
 
 ## Methods
 

docs/docs/components/gallery.md

@@ -190,8 +190,8 @@ Modifies the orientation of the component to vertical mode.
 Maximum scale value allowed by the pinch gesture for all elements, expects values bigger than or equals one.
 
 You can also pass an array as big as the `data` property array containing the resolution of your images/videos,
-for instance `[{width: 1920, height: 1080}, {width: 1000, height: 1000}]`; maxScale is infered in such a way
-it's a value just before your content starts to pixelate.
+for instance `[{width: 1920, height: 1080}, {width: 1000, height: 1000}]`; maxScale will be infered for each
+element in such a way it's a value just before your content starts to pixelate.
 
 ### zoomEnabled
 
@@ -207,12 +207,26 @@ Enables or disables both pinch and double tap gestures.
 | --------- | ------- |
 | `boolean` | `true`  |
 
-::: tip Condition
+Allow the user to go to the next or previous item by tapping the horizontal edges of the gallery, this property
+only works in horizontal mode.
 
-- This property only works in horizontal mode.
+### allowOverflow
+
+| Type      | Default |
+| --------- | ------- |
+| `boolean` | `false` |
+
+::: tip Tip
+This property's usage is intended for creating a carousel with zoomable previews, if that's your goal do
+the following:
+
+- Set this property to true.
+- Set `pinchCenetingMode` property to sync.
+- Set `scaleMode` property to bounce.
+- Set `maxScale` property to 1.
   :::
 
-Allow the user to go to the next or previous item by tapping the horizontal edges of the gallery.
+Allow the items of gallery to overflow the container during a pinch gesture.
 
 ### scaleMode
 
@@ -221,24 +235,18 @@ Allow the user to go to the next or previous item by tapping the horizontal edge
 | `'clamp' \| 'bounce'` | `'bounce'` |
 
 Determine how your component must behave when the pinch gesture's scale value exceeds boundaries
-defined by `minScale` and `maxScale` properties, possible values are:
+defined by the minimum scale (1) and `maxScale` property, possible values are:
 
 - `clamp` keeps the scale whithin the already mentioned scale boundaries.
 - `bounce` lets the user scale above and below the scale boundary values, at the end of the pinch gesture
-  the scale value animates back to `minScale` or `maxScale` respectively.
+  the scale value animates back to 1 or `maxScale` respectively.
 
 ### allowPinchPanning
 
 | Type      | Default |
 | --------- | ------- |
 | `boolean` | `true`  |
 
-::: warning Beware iOS users
-This feature is disabled by default for iOS users when a version of React Native Gesture Handler prior to `2.16.0` is installed, installing a version greater than equals `2.16.0` will set the value of this property to `true` by default.
-
-For more information see this [Gesture Handler's issue](https://github.com/software-mansion/react-native-gesture-handler/issues/2833) and [this issue](https://github.com/Glazzes/react-native-zoom-toolkit/issues/10).
-:::
-
 Lets the user drag the current item around as they pinch, it also provides a more accurate pinch gesture calculation to user interaction.
 
 ### pinchCenteringMode
@@ -248,7 +256,7 @@ Lets the user drag the current item around as they pinch, it also provides a mor
 | `'clamp' \| 'sync'` | `'clamp'` |
 
 ::: tip Tip
-This property is meant to be used when `allowPinchPanning` property is set to `true`.
+This property does nothing unless `allowPinchPanning` property is set to `true`.
 :::
 
 Determine the behavior used by the pinch gesture relative to the boundaries of its enclosing component,
@@ -281,7 +289,7 @@ Callback triggered when the user taps the current item once, provides additional
 | ------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------- |
 | `(translateY: number, released: boolean) => void` | `undefined` | see [worklets](https://docs.swmansion.com/react-native-reanimated/docs/2.x/fundamentals/worklets/) |
 
-::: tip Conditions
+::: tip Trigger Conditions
 
 - Gallery must be on horizontal mode
 - The current item must be at a scale of one.
@@ -356,7 +364,7 @@ values to some other component as it updates, see [CommonZoomState](#commonzooms
 | `() => void` | `undefined` |
 
 Callback triggered when a pan, pinch or double tap gesture ends, if an animation started at the end of one
-of the gestures this callback's execution will be delayed until the animation has finished.
+of the gestures the execution of this callback will be delayed until such animation finishes.
 
 ### onZoomBegin
 
@@ -380,12 +388,13 @@ Callback triggered when component returns back to its original state (scale valu
 | ---------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------- |
 | `(state: GalleryTransitionState) => ViewStyle` | `undefined` | see [worklets](https://docs.swmansion.com/react-native-reanimated/docs/2.x/fundamentals/worklets/) |
 
-Worklet callback used to modify the scroll animation used by the gallery, keep in mind the following when building a custom transition, see [GalleryTransitionState](#gallerytransitionstate).
+Worklet callback used to modify the scroll animation used by the gallery, keep in mind the following when
+building a custom transition:
 
 - All elements are absolute positioned one on top of another.
-- Use translateX and translateY style properties to position the items to your particular needs.
+- Use `translateX` and `translateY` style properties to position the items to your particular needs.
 
-The base behaviour would look this:
+The base scroll behaviour looks like this:
 
 ```js
 const baseAnimation = (state) => {
@@ -423,16 +432,16 @@ Reset all transformations to their initial state.
 - type definition: `(animate?: boolean) => void`
 - parameter information
 
-| Name      | Type                   | Default | Description                                |
-| --------- | ---------------------- | ------- | ------------------------------------------ |
-| `animate` | `boolean \| undefined` | `true`  | Whether to animate the transition or not . |
+| Name      | Type                   | Description                                                   |
+| --------- | ---------------------- | ------------------------------------------------------------- |
+| `animate` | `boolean \| undefined` | Whether to animate the transition or not, defaults to `true`. |
 
 ### requestState
 
 Request internal transformation values of the current item at the moment of the calling
 
-- type definition: `() => ResumableZoomState`;
-- return type: [ResumableZoomState](#resumablezoomstate).
+- type definition: `() => CommonZoomState<number>`;
+- return type: [CommonZoomState](#commonzoomstate).
 
 ### setIndex
 
@@ -464,6 +473,6 @@ Jump to the item at the given index.
 | `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 being scrolled or not.         |
-| `scroll`      | `number`             | How much the gallery has been scrolled.               |
+| `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

@@ -24,11 +24,10 @@ The next video footage is taken from the [Example app](https://github.com/Glazze
 
 Its usage is pretty straight forward, just wrap a component of your choice with it, the following example is a full screen image detail component.
 
-::: tip Remember
+::: tip Tip
 
-- This component uses `flex: 1` style therefore it will attempt to take all available space.
-- This component is best utilized when at least one of the two dimensions of the wrapped component is bigger than equals the space it's occupying in the screen, for instance if it's a full screen image detail screen, your image should be as wide or as tall as the size of your screen.
-  :::
+This component is best utilized when at least one of the two dimensions of the wrapped component is bigger than equals the space it's occupying in the screen, for instance if it's a full screen image detail screen, your image should be as wide or as tall as the size of your screen.
+:::
 
 ```jsx
 import React from 'react';
@@ -73,6 +72,15 @@ export default App;
 
 All properties for this component are optional.
 
+### style
+
+| Type        | Default       |
+| ----------- | ------------- |
+| `ViewStyle` | `{ flex: 1 }` |
+
+Styles used by the container enclosing your component. The following styles are enforced by the library and
+can not be modified: `{ justifyContent: 'center', alignItems: 'center' }`.
+
 ### extendGestures
 
 | Type      | Default |
@@ -136,12 +144,6 @@ defined by `minScale` and `maxScale` properties, possible values are:
 | --------- | ------- |
 | `boolean` | `true`  |
 
-::: warning Beware iOS users
-This feature is disabled by default for iOS users when a version of React Native Gesture Handler prior to `2.16.0` is installed, installing a version greater than equals `2.16.0` will set the value of this property to `true` by default.
-
-For more information see this [Gesture Handler's issue](https://github.com/software-mansion/react-native-gesture-handler/issues/2833) and [this issue](https://github.com/Glazzes/react-native-zoom-toolkit/issues/10).
-:::
-
 Lets the user pan the component around as they pinch as well as providing a more accurate pinch gesture calculation
 to user interaction. Panning as you pinch will not trigger any pan gesture related callbacks.
 
@@ -274,7 +276,7 @@ values to some other component as it updates, see [CommonZoomState](#commonzooms
 | `() => void` | `undefined` |
 
 Callback triggered when a pan, pinch or double tap gesture ends, if an animation started at the end of one
-of the gestures this callback's execution will be delayed until the animation has finished.
+of the gestures the execution of this callback will be delayed until such animation finishes.
 
 ## Methods
 
@@ -290,7 +292,9 @@ import {
 const ref = useRef<ResumableZoomType>(null);
 ref.current?.reset(false);
 
-<ResumableZoom ref={ref}>// some component here</ResumableZoom>;
+<ResumableZoom ref={ref}>
+  <SomeComponent />
+</ResumableZoom>;
 ```
 
 ### reset

docs/docs/components/snapbackzoom.md

@@ -8,13 +8,15 @@ outline: deep
 
 An ideal component for preview handling, as its name suggests it returns to its original position after the pinch gesture ends, you can see this feature being implemented in Telegram's messages containing images and/or videos or Instragram's posts.
 
-::: warning Beware iOS users
-This component will be subject to some level of stuttering, unless you install a version of React Native Gesture Handler greater than equals `2.16.0`.
+The next video footage is a complex use case, this one is taken from the [Example app](https://github.com/Glazzes/react-native-zoom-toolkit/tree/main/example).
 
-For more information see this [Gesture Handler's issue](https://github.com/software-mansion/react-native-gesture-handler/issues/2833) and [this issue](https://github.com/Glazzes/react-native-zoom-toolkit/issues/10).
-:::
+::: warning What this component is not
+
+This component turns its child component into a zoomable one, that's all, this component nor any component has the
+ability to bypass zIndex and overflow style's restrictions, it's ability to go over other elements relies
+completely on you and how you structured your layout to handle such use case.
 
-The next video footage represents a complex use case, this one is taken from the [Example app](https://github.com/Glazzes/react-native-zoom-toolkit/tree/main/example)
+:::
 
 <div style="width: 100%; display: flex; justify-content: center; align-items: center">
   <video src="../assets/snapbackzoom.mp4" controls />
@@ -24,24 +26,25 @@ The next video footage represents a complex use case, this one is taken from the
 
 Its usage is pretty straight forward, just wrap a component of your choice with it.
 
-::: tip Child Componenet Guidelines
+::: tip Child Component Guidelines
 SnapbackZoom's child component must be measurable, therefore avoid the following:
 
 - Do not use relative size units like `{width: '100%'}`, use absolute values instead, for instance
   `{width: 200, height: 200}`.
 - Do not use `{position: 'absolute'}` style, wrap SnapbackZoom in an absolute positioned view if you need to.
-:::
+  :::
 
 ```jsx
 import { SnapbackZoom } from "react-native-zoom-toolkit"
 
 // Simple use case
 <SnapbackZoom>
-  <Image // <= This could be an Expo image or a Video
+  <Image
     source={{ uri: IMAGE }}
     style={{ width: 200, height: 200 }}
-    resizeMethod={"scale"} // <= Very important for images in Android do not forget it
-    resizeMode={"cover"}/>
+    resizeMethod={"scale"}
+    resizeMode={"cover"}
+  />
 </SnapbackZoom>
 
 // Complex use case
@@ -56,12 +59,14 @@ import { SnapbackZoom } from "react-native-zoom-toolkit"
     'worklet';
      console.log(e);
   }}
-  onGestureEnd={() => console.log('animation finished!')}>
-    <Image // <= This could be an Expo image or a Video
+  onGestureEnd={() => console.log('animation finished!')}
+>
+    <Image
       source={{ uri: IMAGE }}
       style={{ width: 200, height: 200 }}
-      resizeMethod={"scale"} // <= Very important for images in Android do not forget it
-      resizeMode={"cover"}/>
+      resizeMethod={"scale"}
+      resizeMode={"cover"}
+    />
 </SnapbackZoom>
 ```
 

docs/docs/guides/downscale.md

@@ -11,7 +11,7 @@ current zoom scale, something like a map marker for instance, so let's take a lo
 ## How to
 
 All elements within a zoom component will be scaled equally, so what you need is to perform the inverse process
-in such a way the zoom scale from the parent component is cancelled out by our downscale process, let's set up
+in such a way the zoom scale from the parent component is "cancelled out" by our downscale process, let's set up
 our custom downscale component.
 
 ```tsx{9,15}
@@ -105,6 +105,9 @@ const { onUpdate, state } = useTransformationState('resumable');
 
 :::
 
+In case you're not trying to mirror the current zoom component's state, I'd always recommend going with the
+manual approach.
+
 This is pretty much it, you can expand this basic setup to your particular requirements.
 
 ## Why isn't this a built-in feature?

docs/docs/guides/skia.md

@@ -87,7 +87,7 @@ const App = () => {
             Center of transformation must match the center of
             the image, by default the tranformation center is
             located at the top left corner of the image, x and y
-            properties to be exact.
+            properties to be precise.
           */}
           origin={vec(centerX, centerY)}
         />
@@ -158,7 +158,7 @@ const App = () => {
           extendGestures={true}
           onUpdate={onUpdate}
         >
-          {/* Nested child is the same as the Skia image */}
+          {/* Nested child is the same size as the Skia image */}
           <View style={{ width: imageSize.width, height: imageSize.height }} />
         </ResumableZoom>
       </View>

docs/docs/installation.md

@@ -4,6 +4,7 @@ outline: deep
 ---
 
 # Installation
+
 Install `react-native-zoom-toolkit` in your project
 
 ::: code-group
@@ -19,13 +20,14 @@ yarn add react-native-zoom-toolkit
 :::
 
 ### Dependencies
-This library relies on both Reanimated and Gesture Handler being 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.
 
-::: warning Beware iOS users
-Dragging the components around as you pinch is disabled by default for iOS users unless you install a version of Gesture Handler greater than equals `2.16.0`.
+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.
 
-For more information see this [Gesture Handler's issue](https://github.com/software-mansion/react-native-gesture-handler/issues/2833) and [this issue](https://github.com/Glazzes/react-native-zoom-toolkit/issues/10).
-:::
+::: 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.
+  :::
 
 ::: code-group
 
@@ -44,4 +46,5 @@ npx expo install react-native-gesture-handler react-native-reanimated
 :::
 
 ### Additional Setup
+
 No additional setup is required.