docs: improve documentation

Adds JSDoc to zoomable component's types as well as for the utilities.
Improves documentaion redability for CropZoom and ResumableZoom components.
Bumps documentation version to 1.0.1
Warns NPM website watchers about its markdown render poor capabilities at README.md file.
Modifies deploy documentation workflow from being triggered on push at main branch in favor of a manual execution.

.github/workflows/docs.yaml

@@ -1,9 +1,5 @@
 name: Deploy documentation to Github Pages
 on:
-  push:
-    branches:
-      - main
-
   workflow_dispatch:
 
 permissions:

README.md

@@ -1,3 +1,6 @@
+>[!Note]
+> Are you watching from NPM website? NPM's markdown renderer is pretty bad, better watch it on [github](https://github.com/Glazzes/react-native-zoom-toolkit).
+
 <div>
   <h1 align="center">React Native Zoom Toolkit</h1>
 </div>
@@ -6,7 +9,7 @@
   <h4 align="center">A set of utilities and components for common pinch to zoom feature requirements</h4>
 </div>
 
-| &nbsp;SnapbackZoom&nbsp; | ResumableZoom | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;CropZoom&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; |
+| SnapbackZoom | ResumableZoom | CropZoom |
 |--------------|---------------|----------|
 |<video src="https://github.com/Glazzes/react-native-zoomable/assets/52082794/19f73880-96ee-4eb4-b68f-53191faf4027" width="100%" controls> | <video src="https://github.com/Glazzes/react-native-zoom-toolkit/assets/52082794/f07a8916-e115-4af5-ae6d-932fa86a5e53" width="100%" controls> | <video src="https://github.com/Glazzes/react-native-zoomable/assets/52082794/7253f7d5-42b0-4426-92ca-5b6772e10b5e" width="100%" controls> |
 
@@ -26,7 +29,7 @@ The idea behind this library is to provide a set of components and utilities for
 - **SnapBackZoom:** Zoom in and snap back, this component automatically snaps back to its original position once the gesture ends, making it ideal for previews.
 - **ResumableZoom**: Pick up where you left last time! This component remembers your previous interactions with it, just the same way it works in your Android/IOS OS integrated gallery application, making it ideal for detail screens and gallery screens.
 - **CropZoom:** An ideal, practical and unopinionated component for image and video cropping needs.
-- **Mirror:**: Mirror the current pinch gesture transformations to any other component you want.
+- **Mirror:** Mirror the current pinch gesture transformations to any other component you want.
 - **Expo Go Compatible**: This library has been written in typescript only with supported modules by the expo go app.
 
 ## Documentation

docs/docs/.vitepress/config.mts

@@ -12,7 +12,7 @@ export default defineConfig({
     // https://vitepress.dev/reference/default-theme-config
     nav: [
       { text: 'Home', link: '/' },
-      {text: '1.0.0', items: [
+      {text: '1.0.1', items: [
         {text: 'Releases', link: 'https://github.com/Glazzes/react-native-zoom-toolkit/releases'},
         {text: 'Contributing', link: 'https://github.com/Glazzes/react-native-zoom-toolkit/blob/main/CONTRIBUTING.md'},
       ]}

docs/docs/components/cropzoom.md

@@ -13,7 +13,7 @@ An ideal, practical and unopinionated component for image and video cropping nee
 - **Fixed size:** Enforce all resulting crops to be of a fixed size, ideal for profile pictures.
 
 This component comes with a handy algorithm to perform cropping operations for you, however you will need the help a of deidicated library for this task.
-- see [Use Crop Zoom with Expo Image Manipulator](../guides/cropzoomexpo)
+- see [Use Crop Zoom with Expo Image Manipulator](../guides/cropzoomexpo) guide.
 
 The next video footage is taken from the [Example app](https://github.com/Glazzes/react-native-zoom-toolkit/tree/main/example).
 
@@ -30,6 +30,7 @@ Its usage is pretty straight forward, just wrap a component of your choice with
 
 ::: tip Remember
 - This component uses `flex: 1` style property therefore it will attempt to take all available space, its minimum dimensions are the values provided to `cropSize` property.
+- The crop area is centered using `justifyContent` and `alignItems` center.
 - This component calculates the dimensions needed to meet the `resolution` property's aspect ratio, therefore your images and videos must use `{ flex: 1 }` style property so they cover the gesture detection area properly.
 :::
 
@@ -87,7 +88,7 @@ For an overlay mode example, see Example App's [CropZoom Skia Example](https://g
 |------|---------|----------|-----------------|
 | `CropMode` | `CropMode.MANAGED` | `No`   | see [CropMode](#cropmode-enum) |
 
-Selects which mode to use.
+Select which one of the two available modes to use.
 
 ### cropSize
 | Type | Required |
@@ -101,14 +102,14 @@ Size of the cropping area.
 |------|----------|
 | `{ width: number; height: number; }` | `Yes`    |
 
-Resolution of your image/video or how big whatever you are trying to crop really is.
+Resolution of your image, video or how big whatever you are trying to crop really is.
 
 ### debug
 | Type | Default | Required |
 |------|---------|----------|
 | `boolean` | `false` | `No`    |
 
-Highlights the cropping area with a red-ish color as well as the gesture detection area with a light green color, this property is meant to be used when `mode` property is set to `CropMode.OVERLAY` so you can align your underlying component with it properly.
+Highlights the cropping area with a red-ish color as well as the gesture detection area with a light green color, use it to align your `OverlayComponent` with the crop area properly.
 
 ::: tip Note
 In case you're color blind and/or have any trouble differentiating colors, please consider opening an issue suggesting a suitable pair of colors.
@@ -133,14 +134,14 @@ Maximum scale value allowed by the pinch gesture, negative values instruct the c
 |------|---------|----------|-----------------|
 | `PanMode` | `PanMode.FREE` | `No`    | see [PanMode](#panmode-enum) |
 
-Which one of the three available pan modes to use.
+Select which one of the three available pan modes to use.
 
 ### scaleMode
 | Type | Default | Required | Additional Info |
 |------|---------|----------|-----------------|
 | `ScaleMode` | `ScaleMode.BOUNCE` | `No`    | see [ScaleMode](#scalemode-enum) |
 
-Which one of the two available scale modes to use.
+Select which one of the two available scale modes to use.
 
 ### panWithPinch
 | Type | Default | Required |
@@ -154,7 +155,7 @@ Lets the user drag the component around as they pinch, it also provides a more a
 |------|---------|-----------------|
 | `function` | `undefined` | see [tap gesture event data](https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/tap-gesture#event-data) |
 
-Callback triggered when a tap is made, receives a tap gesture event as its only argument.
+Callback triggered when the user taps the wrapped component once, receives a tap gesture event as its only argument.
 
 ### onPanStart
 | Type | Default | Additional Info |
@@ -189,9 +190,7 @@ Callback triggered as soon as the user lift their fingers off the screen after p
 |------|---------|----------|----------------|
 | `worklet function` | `undefined` | `No`    | see [worklets](https://docs.swmansion.com/react-native-reanimated/docs/2.x/fundamentals/worklets/) |
 
-Callback triggered as the user interacts with the component, it also means interacting through its [methods](#methods), receives an object of type [CropZoomState](#cropzoomstate) as its only argument.
-
-Ideal if you need to mirror the internal state of the component to some other component as it updates.
+Worklet callback triggered as the user interacts with the component, it also means interacting through its [methods](#methods), receives an object of type [CropZoomState](#cropzoomstate) as its only argument, ideal if you need to mirror the internal state of the component to some other component as it updates.
 
 
 ### OverlayComponent
@@ -201,7 +200,9 @@ Ideal if you need to mirror the internal state of the component to some other co
 
 A function that returns a React Component, such component will sit between your desired component to crop and the gesture detector, for instance you can pass an svg component with a "hole" in it.
 
-Previous condition: `mode` property is set to `CropMode.MANAGED` (default value).
+::: tip Condition
+`mode` property must be set to `CropMode.MANAGED` (default value).
+:::
 
 
 ## Methods
@@ -218,7 +219,8 @@ ref.current?.crop(200);
 ```
 
 ### crop
-Map all the transformations applied to your component into a simple and ready to use object specifying the context necessary for a crop operation, such object must be used along with a library capable of cropping images and/or videos, for instance [Expo Image Manipulator](https://docs.expo.dev/versions/latest/sdk/imagemanipulator/).
+Map all the transformations applied to your component into a simple and ready to use object specifying the context necessary for a crop operation, such object must be used along with a library capable of cropping images and/or videos, for instance Expo Image Manipulator, see [Use Crop Zoom with Expo Image Manipulator](../guides/cropzoomexpo) guide.
+
 - Arguments
 
 | Name | Type | Default | Description |
@@ -228,7 +230,7 @@ Map all the transformations applied to your component into a simple and ready to
 - Returns [CropContextResult](#cropcontextresult)
 
 ::: warning Beware
-All crops resulting from this method may be subject to one pixel margin of error, this is an intentional behavior in order to prevent some image cropping libraries from crashing your app.
+If you called this method with the `fixedWidth` argument, resulting crops may be subject to one pixel margin of error, this is an intentional behavior in order to prevent some image cropping libraries from crashing your app.
 :::
 
 ### rotate

docs/docs/components/resumablezoom.md

@@ -86,21 +86,21 @@ Minimum scale value allowed by the pinch gesture, expects values greater than or
 
 Maximum scale value allowed by the pinch gesture, expects values bigger than or equals one.
 
-Alternatively you can pass a resolution object, for instance an HD image resolution `{ width: 1920, height: 1080 }`; this will instruct the component to calculate `maxScale` in such a way it's a value just before images and videos start getting pixelated.
+Alternatively you can pass the resolution of your image/video, for instance `{ width: 1920, height: 1080 }`; this will instruct the component to calculate `maxScale`  in such a way it's a value just before images and videos start getting pixelated.
 
 ### panMode
 | Type | Default | Additional Info |
 |------|---------|-----------------|
 | `PanMode` | `PanMode.CLAMP` | see [PanMode](#panmode-enum) |
 
-Which one of the three available pan modes to use.
+Select which one of the three available pan modes to use.
 
 ### scaleMode
 | Type | Default | Additional Info |
 |------|---------|-----------------|
 | `ScaleMode` | `ScaleMode.BOUNCE` | see [ScaleMode](#scalemode-enum) |
 
-Which one of the two available scale modes to use.
+Select which one of the two available scale modes to use.
 
 ### decay
 | Type | Default | Additional Info |
@@ -142,28 +142,28 @@ Lets the user drag the component around as they pinch, it also provides a more a
 |------|---------|-----------------|
 | `function` | `undefined` | see [tap gesture event data](https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/tap-gesture#event-data) |
 
-Callback triggered when a tap is made, receives a tap gesture event as its only argument.
+Callback triggered when the user taps the wrapped component once, receives a tap gesture event as its only argument.
 
 ### onSwipeRight
 | Type | Default |
 |------|---------|
 | `function` | `undefined` |
 
-Callback triggered when a swipe to the right gesture has occurred.
+Callback triggered when the user swipes to the right.
 
 ::: tip Condition
-This callback is only triggered when your component is at its minimum scale and `panMode` property is set to `PanMode.CLAMP`
+This callback is only triggered when your component is at its minimum scale and `panMode` property is set to `PanMode.CLAMP` (default value).
 :::
 
 ### onSwipeLeft
 | Type | Default |
 |------|---------|
 | `function` | `undefined` |
 
-Callback triggered when a swipe to the left gesture has occurred.
+Callback triggered when the user swipes to the left.
 
 ::: tip Condition
-This callback is only triggered when your component is at its minimum scale and `panMode` property is set to `PanMode.CLAMP`
+This callback is only triggered when your component is at its minimum scale and `panMode` property is set to `PanMode.CLAMP` (default value).
 :::
 
 ### onPanStart
@@ -199,7 +199,7 @@ Callback triggered as soon as the user lifts their fingers off the screen after
 |------|---------|----------------|
 | `worklet function` | `undefined` | see [worklets](https://docs.swmansion.com/react-native-reanimated/docs/2.x/fundamentals/worklets/) |
 
-Callback triggered as the user interacts with the component, it also means interacting through its [methods](#methods), receives an object of type [ResumableZoomState](#resumablezoomstate) as its only argument.
+Worklet callback triggered as the user interacts with the component, it also means interacting through its [methods](#methods), receives an object of type [ResumableZoomState](#resumablezoomstate) as its only argument.
 
 Ideal if you need to mirror the internal state of the component to some other component as it updates.
 
@@ -208,10 +208,12 @@ Ideal if you need to mirror the internal state of the component to some other co
 |------|---------|----------------|
 | `worklet function` | `undefined` | see [worklets](https://docs.swmansion.com/react-native-reanimated/docs/2.x/fundamentals/worklets/) |
 
-Callback triggered when the component has been panned beyond the boundaries defined by its enclosing container, ideal property to mimic scroll behavior.
+Worklet callback triggered when the component has been panned beyond the boundaries defined by its enclosing container, receives as an argument how much the component has been panned beyond its enclosing container boundaries, positive values from the right and negative values from the left.
+
+Ideal to mimic scroll behavior.
 
 ::: tip Condition
-This callback is only triggered when the `panMode` property is set to `PanMode.CLAMP`.
+This callback is only triggered when the `panMode` property is set to `PanMode.CLAMP` (default value).
 :::
 
 ## Methods

docs/docs/components/snapbackzoom.md

@@ -93,14 +93,14 @@ Enables or disable gestures, when gestures are disabled your component can detec
 |------|---------|-----------------|
 | `function` | `undefined` | see [tap gesture event data](https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/tap-gesture#event-data) |
 
-Callback triggered when a single tap is made, receives a tap gesture event as its only argument.
+Callback triggered when the user taps the wrapped component once, receives a tap gesture event as its only argument.
 
 ### onDoubleTap
 | Type | Default | Additional Info |
 |------|---------|-----------------|
 | `function` | `undefined` | see [tap gesture event data](https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/tap-gesture#event-data) |
 
-Callback triggered when a double tap is made, receives a tap gesture event as its only argument.
+Callback triggered when the user taps the wrapped component twice, receives a tap gesture event as its only argument.
 
 ### onPinchStart
 | Type | Default | Additional Info |
@@ -121,8 +121,7 @@ Callback triggered as soon as the user lifts their fingers off the screen after
 |------|---------|-----------------|
 | `worklet function` | `undefined` | see [worklets](https://docs.swmansion.com/react-native-reanimated/docs/2.x/fundamentals/worklets/) |
 
-Callback triggered from the moment pinch gesture starts until the snap back animation finishes, 
-receives an object of type [SnapbackZoomState](#snapbackzoomstate) as its only argument.
+Worklet callback triggered from the moment pinch gesture starts until the snap back animation finishes, receives an object of type [SnapbackZoomState](#snapbackzoomstate) as its only argument.
 
 Ideal if you need to mirror the current state of the gesture to some other component.
 
@@ -169,7 +168,7 @@ At a scale of one your image is a tile of 200x200 pixel size, in other words a s
 | `width` | `number` | Inital width measurement of your component |
 | `height` | `number` | Inital height measurement of your component |
 | `resizedWidth` | `number \| undefined` | Current width measurement of your component, if `resizeConfig` property is `undefined`, this value will be `undefined` too |
-| `resizedWidth` | `number \| undefined` | Current height measurement of your component, if `resizeConfig` property is `undefined`, this value will be `undefined` too |
+| `resizedHeight` | `number \| undefined` | Current height measurement of your component, if `resizeConfig` property is `undefined`, this value will be `undefined` too |
 | `translateX` | `number` | Current translateX transformation value |
 | `translateY` | `number` | Current translateY transformation value |
 | `scale` | `number` | Current scale transformation value |

example/src/cropzoom/commons/CropModal.tsx

@@ -8,6 +8,9 @@ type CropModalProps = {
   setCrop: (uri: string | undefined) => void;
 };
 
+/*
+ * Just a modal that displays the crop result image.
+ */
 const CropModal: React.FC<CropModalProps> = ({ uri, setCrop }) => {
   const resetCrop = () => {
     setCrop(undefined);

example/src/cropzoom/commons/CropOverlay.tsx

@@ -7,6 +7,10 @@ type CropOverlayProps = {
   cropSize: number;
 };
 
+/*
+ * Draws an SVG as big as the space cropzoom is ocuppying in the screen, this
+ * one also draws a "hole" in it as big as the crop size.
+ */
 const CropOverlay: React.FC<CropOverlayProps> = ({ cropSize }) => {
   const { width, height } = useWindowDimensions();
 

example/src/cropzoom/skia-example/EffectPreview.tsx

@@ -22,6 +22,10 @@ type EffectPreviewProps = {
   matrix: number[];
 };
 
+/*
+ * Renders a preview image with the color matrix applied to it.
+ * On tap updates the color matrix of the full size image.
+ */
 const EffectPreview: React.FC<EffectPreviewProps> = ({
   index,
   activeIndex,

example/src/resumable/gallery/ListImage.tsx

@@ -13,8 +13,8 @@ import {
   type ResumableZoomType,
 } from 'react-native-zoom-toolkit';
 
-import { SCROLL_SIZE, TIMING_CONFIG, images } from './constants';
-import { snapPoint, subscribeToIndexChangeEvent } from './utils';
+import { SCROLL_SIZE, TIMING_CONFIG, images } from './utils/constants';
+import { snapPoint, subscribeToIndexChangeEvent } from './utils/utils';
 import type { PanGestureEvent } from '../../../../src/commons/types';
 
 type ListImageProps = {
@@ -77,7 +77,7 @@ const ListImage: React.FC<ListImageProps> = ({
     });
   };
 
-  // if no swipe gesture has been detected  determine whether to scroll to next or previous item.
+  // if no swipe gesture has been detected  determine whether to scroll to the next or previous item.
   // scrollOffset is updated at the end of every animation so next time we start "scrolling" again
   // it will start where we left.
   const onPanEnd = (e: PanGestureEvent) => {

example/src/resumable/gallery/ResumableGalleryExample.tsx

@@ -17,9 +17,9 @@ import { StatusBar, setStatusBarHidden } from 'expo-status-bar';
 import ListImage from './ListImage';
 import Appbar from '../basic/Appbar';
 
-import { images } from './constants';
+import { images } from './utils/constants';
 import Constants from 'expo-constants';
-import ScrollPreview from './ScrollPreview';
+import ScrollPreview from './scroll/ScrollPreview';
 
 const barHeight = Constants.statusBarHeight;
 

example/src/resumable/gallery/PreviewImage.tsx → example/src/resumable/gallery/scroll/PreviewImage.tsx

@@ -1,15 +1,19 @@
 import React from 'react';
 import { Pressable, StyleSheet } from 'react-native';
 import { Image } from 'expo-image';
-import { PREVIEW_SIZE } from './constants';
-import { theme } from '../../constants';
+import { PREVIEW_SIZE } from '../utils/constants';
+import { theme } from '../../../constants';
 
 type PreviewImageProps = {
   uri: string;
   index: number;
   scrollTo: (index: number) => void;
 };
 
+/*
+ * Small image preview drawn at the bottom of the screen.
+ * On tapped scroll the position of its bigger counterpart.
+ */
 const PreviewImage: React.FC<PreviewImageProps> = ({
   uri,
   index,