Get relative coords (software-mansion#2400)

This pr introduces the getRelativeCoords function which enables to convert absolute coordinates to coordinates relative to the given view.

docs/docs/api/miscellaneous/getRelativeCoords.md

@@ -0,0 +1,49 @@
+---
+id: getRelativeCoords
+title: getRelativeCoords
+sidebar_label: getRelativeCoords
+---
+
+Determines the location on the screen, relative to the given view. It might be useful, when there are only absolute coordinates available and you need coordinates relative to the parent.
+
+### Arguments
+
+#### animatedRef
+
+The product of [`useAnimatedRef`](../hooks/useAnimatedRef) is a Reanimated's extension of a standard React's ref(delivers view tag on the UI thread). This ref should be passed as a prop to view relative to which we want to know coordinates.
+
+#### x
+
+Absolute `x` coordinate.
+
+#### y
+
+Absolute `y` coordinate
+
+### Returns
+
+Object which contains relative coordinates
+
+- `x`
+- `y`
+
+### Example
+
+```js
+const Comp = () => {
+  const aref = useAnimatedRef();
+  // ...
+
+  const gestureHandler = useAnimatedGestureHandler({
+    onEnd: (event) => {
+      getRelativeCoords(aref, event.absoluteX, event.absoluteY)
+    },
+  });
+
+  return <View ref={aref}>
+    <PanGestureHandler onGestureEvent={gestureHandler}>
+      <Animated.View style={[styles.box]} />
+    </PanGestureHandler>
+  </View>;
+};
+```

docs/sidebars.js

@@ -59,6 +59,7 @@ module.exports = {
             'api/miscellaneous/runOnJS',
             'api/miscellaneous/runOnUI',
             'api/miscellaneous/interpolate',
+            'api/miscellaneous/getRelativeCoords',
           ],
         },
       ],

react-native-reanimated.d.ts

@@ -649,6 +649,15 @@ declare module 'react-native-reanimated' {
     pageY: number;
   };
 
+  export function getRelativeCoords(
+    ref: RefObject<Component>,
+    x: number,
+    y: number
+  ): {
+    x: number;
+    y: number;
+  };
+
   export function scrollTo(
     ref: RefObject<ReactNativeScrollView | ScrollView>,
     x: number,

src/reanimated2/index.ts

@@ -7,3 +7,4 @@ export * from './NativeMethods';
 export * from './Colors';
 export * from './PropAdapters';
 export * from './layoutReanimation';
+export * from './utils';

src/reanimated2/utils.ts

@@ -0,0 +1,21 @@
+import { Component } from 'react';
+import { measure } from '.';
+import { RefObjectFunction } from './hook/useAnimatedRef';
+
+export interface ComponentCoords {
+  x: number;
+  y: number;
+}
+
+export function getRelativeCoords(
+  parentRef: RefObjectFunction<Component>,
+  x: number,
+  y: number
+): ComponentCoords {
+  'worklet';
+  const parentCoords = measure(parentRef);
+  return {
+    x: x - parentCoords.x,
+    y: y - parentCoords.y,
+  };
+}